Menu ▾ ▴

YfiTechTelkom

Anonymous

Introduction

ISP's in South Africa usually makes use of Telkom's infrastructure to supply their clients with Internet access.
These include broadband services like DSL.
This document discus the modifications to a standard YFi Hotspot Manager system to work with Telkom to provide Internet access.
It also discuss how to comply to the regulation which were published in the Government Gazette 29141 (Notice 1112 of 2006).
This requirement stipulates that a South African ISP shall not subject local bandwidth usage to the cap.
You do not want them to get angry with you ;-).

Requirements

  • A working YFi Hotspot Manager setup on a server with a fixed IP Address.
  • Telkom's guideline document entitled ISP Information for broadband RADIUS authentication.
  • A registered realm at Telkom. This will entitle them to forward proxy RADIUS request to the YFi Hotspot Manager server running FreeRADIUS.
  • The shared secret between YFi Hotspot Manager and the Telkom RADIUS servers.

Once the above requirements are met, we can continue with the set-up.
This document will make use of fictional data. Please change to suit your implementation.

Sample Data

The following table lists the sample data which will be used in the rest of the document.
It is SAMPLE data, remember to change it for your set-up.

Item
Value

Telkom Proxy RADIUS server1
10.10.10.11

Telkom Proxy RADIUS server2
10.10.10.12

Telkom Proxy RADIUS server3
10.10.10.13

Shared Secret
greatsecret

YFi Hotspot Manager IP
20.20.20.11

Telkom NAS IP
30.30.30.11

Realm registered with Telkom
yfi-dsl.co.za

Server receiving POD requests
40.40.40.11

Port for POD requests
1234

Changes to make

The following is a list of changes to make in order to ready our system for the Telkom hook-up.

  • Add a Telkom type to the list of available NAS devices.
  • Add the yfi-dsl.co.za realm on YFi Hotspot Manager.
  • Add the Telkom Proxy RADIUS servers as NAS devices.
  • Modify the CakePHP code to be able to include POD request to Telkom.
  • Add Dictionary files specific to Telkom.
  • Modify FreeRADIUS Perl code to include POD requests to Telkom.
  • Modify FreeRADIUS Perl code to include the Degrading of services once a cap is blown. (To comply to government regulations)
  • Create a Skeleton Profile and Specific Profile containing attributes specific to Telkom.

Each item on the list will be discussed in its own sub-section.

Add to list of NAS available devices

  • We want to differentiate the list of NAS device types registered on the YFi Hotspot Manager system.

  • Since we will add devices from Telkom, we add a new type of device to the list.

  • Edit the /var/www/c2/yfi_cake/config/yfi.php file. 

    $config['nas']['device_types']  = array('other','CoovaChilli','CoovaChilli-AP','DD-Wrt','Open-Wrt','Mikrotik','Open-Wrt[Ent]','Telkom');

Add Realm

You need to register a realm with Telkom. It will typically be related to the domain name of the ISP you are in control of.
A user will then have a name like dvdwalt@‌.
When you try and authenticate a PPP session on the Telkom network, their RADIUS servers will proxy the RADIUS request to the designated servers for the specified realm.
Using our sample data, it will forward an authentication request to IP Address 20.20.20.11.
You also have to add the realm t0 the FreeRADIUS server using the YFi Hotspot Manager.

  • Select Realms & Providers -> Realm Management.
  • Click on the add action on the right (Green Plus).
  • Supply the realm detail.

Add Proxy RADIUS servers as NAS devices

The document supplied list around 13 servers which has to be added as NAS devices to YFi Hotspot Manager.
We list three in the sample data.
Ensure they are all added and take note of the following.

  • The IP address of the server.
  • The description (this is up to you)
  • The shared secret between this servers and YFi Hotspot Manager.
  • Disable Active monitoring of the NAS device. We do not want to send ping packets out to servers not under our control.

Modify CakePHP code

  • Edit the /var/www/c2/yfi_cake/controllers/components/kicker.php file and add the ability to kick users off.

  • Because the request is proxied, the NAS IP will not be defined in the NAS table, when we receive such a request we assume the user is connected through the Telkom network.

    //==========================================================================================
    }else{

    / Uncommnet this for Telkom (South Africa) implementations /
    //Assume this is a telkom entry where the $nas_ip is not defined inside the NAS table since the
    //RADIUS request is proxied for the NAS
    //Some variables to define
    $pod_server = "40.40.40.11";
    $pod_port = "1234";
    $xascend = $radacct_entry['xascendsessionsvrkey'];
    $secret = "greatsecret";
    $rc = $this->radclient;

    exec("echo \"User-Name = $username,X-Ascend-Session-Svr-Key=$xascend,NAS-IP-Address=$nas_ip,Framed-IP-Address=$framedipaddress\" | $rc -r 2 -t 2 $pod_server:$pod_port 40 $secret",$output);
    }

Dictionary files

  • We need to modify one dictionary file and add antoher.

  • Edit the following values in /usr/local/share/freeradius/dictionary.rfc2865. Change 

    ATTRIBUTE   Class                   25  octets
ATTRIBUTE   Login-LAT-Port              63  string

To 

ATTRIBUTE   Class                   25  string
ATTRIBUTE   Login-LAT-Port              63  integer

  • Create a file called /usr/local/share/freeradius/dictionary.telkom. With the following content: 

    #
#       Telkom SA RADIUS dictionary
#       
#       Used to convey Telkom Specific Information in proxied requests
#
#       EDS 20031007 eddie@saix.net
VENDOR          Telkom          1431

BEGIN-VENDOR    Telkom

#
#       Access-Type is used to describe the Access Medium used eg
#       Dial/ADSL/VSAT etc.  Used in both Access-Requests and Accounting
#
ATTRIBUTE       Telkom-Access-Type              1               string
#
#       Service-Type is used to indicate the Service used main in conjunction
#       with the SSG.  Used in both Access-Requests and Accounting
#
ATTRIBUTE       Telkom-Service-Type             2               string

# YFi Hotspot Manager trick to implement government regulation (South African)
ATTRIBUTE       Telkom-Degrade-Token            200             string

END-VENDOR      Telkom

  • Edit the /usr/local/etc/raddb/dictionary file to include the extra dictionary: 

    $INCLUDE        /usr/local/share/freeradius/dictionary.telkom

Modify FreeRADIUS Perl code to include POD

  • Edit the /usr/locat/etc/raddb/rlm_perl_modules/User.pm file add the following disconnection code: 

     my $return_data  = $self->{'sql_connector'}->one_statement_value('na_nasname',$ip);

    #__________ Telkom South Africa ___________________
    #Uncommnet this for Telkom (South Africa) implementations:
    #If this is a telkom entry where the $return_data->{'type'} is not defined inside the NAS table since the 
    #RADIUS request is proxied for the NAS
    #Thus the return will be zero!
    if(!(exists $return_data->{'type'})){

        my  $pod_server = "40.40.40.11";
        my  $pod_port   = "1234";
        my  $xascend    = $acct_detail->{'X-Ascend-Session-Svr-Key'};
        my  $secret     = "greatsecret";
        system("echo \"User-Name = $username,X-Ascend-Session-Svr-Key=$xascend,NAS-IP-Address=$ip,Framed-IP-Address=$framedipaddress\"  | $radclient -r 2 -t 2 $pod_server:$pod_port 40 $secret");
        return  #We are done here no need to do anything else!
    }

    my $type        = $return_data->{'type'};
    my $port        = $return_data->{'ports'};
    my $secret      = $return_data->{'secret'};
    my $device_flag = 0;

    #-----------------------------------------------------------------------------------------------------------------------------------------------
    #---- MAC Authentication add-on: MAC authenticated devices are authenticated to RADIUS as the Permanent user to which the Device belongs -------

Modify FreeRADIUS Perl code to include degrading of service

  • Edit the /usr/locat/etc/raddb/rlm_perl_modules/User.pm file change the following disconnection code:

FROM 

if(($return_data->{'cap'} eq 'hard')or($return_data->{'cap'} eq 'prepaid')){
   print "-> Hard Limit Specified\n";
   if($check_usage_return ne '1'){
      print "-> Hard Limit Depleted Kick User Off\n";
      $self->_kick_user_off($acct_detail);
  }
}

TO 

if(($return_data->{'cap'} eq 'hard')or($return_data->{'cap'} eq 'prepaid')){
    print "-> Hard Limit Specified\n";
    if($check_usage_return ne '1'){

        # Telkom South Africa add on
        # We need to determine if this service is ALREADY degraded -> if so we NOT degrade the serivce with a kick off
        if(($check_usage_return =~ m/Telkom-Degrade-Token/)&&($acct_detail->{'Class'} =~ m/NL1|PL1|LL1|NL2|PL2|LL2|NL3|PL3|LL3/)){

        }else{
            print "-> Hard Limit Depleted Kick User Off\n"; #Assume this is a telkom transition packet (or not Telkom packet) where the service is NOT Local yet
            $self->_kick_user_off($acct_detail);
        }
        #END Telkom South Africa add on
    }
}
  • Also make the following changes:

FROM 

if($total_available <= 0){
   return "Data Cap Depleted";
}

TO 

if($total_available <= 0){

   #Telkom South Africa add on
   my $attributes  = Attributes->new($self->{'sql_connector'});
   my $reply_hash  = $attributes->reply_attributes($username);   #Get the check hash for this user
   if (defined($reply_hash->{'Telkom-Degrade-Token'})){
       return "Telkom-Degrade-Token:".$reply_hash->{'Telkom-Degrade-Token'};
   }
   #END Telkom South Africa add on

   return "Data Cap Depleted";
}

FROM 

if($total_available <= 0){

    return "Time Cap Depleted";
}

TO 

if($total_available <= 0){

    #Telkom South Africa add on
    my $attributes  = Attributes->new($self->{'sql_connector'});
    my $reply_hash  = $attributes->reply_attributes($username);   #Get the check hash for this user
    if (defined($reply_hash->{'Telkom-Degrade-Token'})){
        return "Telkom-Degrade-Token:".$reply_hash->{'Telkom-Degrade-Token'};
    }
    #END Telkom South Africa add on

    return "Time Cap Depleted";
}
  • Edit the /usr/local/etc/raddb/rlm_perl_modules/rlm_perl.pm file. Change

FROM 

if($permanent_return != 1){

    $RAD_REPLY{'Reply-Message'} = $permanent_return;
    print "--------------------------------------------\n";
    print "--FAIL Yfi Permanent User Module -----------\n";
    print "--------------------------------------------\n";
    return 0;
}

TO 

if($permanent_return != 1){

    #Telkom South Africa add on
    if($permanent_return =~ m/Telkom-Degrade-Token/){

        my @elements = split(/:/,$permanent_return);
        #Override the original value of Configuration-Token
        $RAD_REPLY{'Configuration-Token'} = $elements[1];
        #retrun true -> we only degrade the service - we are not rejecting the request
    }else{
        $RAD_REPLY{'Reply-Message'} = $permanent_return;
        print "--------------------------------------------\n";
        print "--FAIL Yfi Permanent User Module -----------\n";
        print "--------------------------------------------\n";
        return 0;
    }
        #END Telkom South Africa add on
}

Profiles

You need to create a new set of profiles. Take note of the following guidelines.

  • The reply attribute Acct-Interim-Interval can have a minimum value of 3600 (one hour). Keep this at a minimum to minimize overshoot on a cap.
  • The reply attribute Configuration-Token will determine the service delivered to the client. Consult Telkom documentation on the available values.
  • The reply attribute Telkom-Degrade-Token is YFi Hotspot Manager specific and will specify the local-only service that a client will degrade to once the international cap is depleted.
  • The check attribute Yfi-Data (part of the Chilli dictionary) will determine the cap size.
  • Local-only connections CAN NOT degrade further once their cap is depleted.
  • International connections can degrade once their cap is depleted, provided the Telkom-Degrade-Token is specified correct.
  • International connections who's cap is depleted and do not have a Telkom-Dagrade-Token specified will be disconnected is they are of type Hard or Prepaid.

Conclusion

Using the documentation on this Wiki page should enable you to integrate your ISP into the Telkom infrastructure and be able to abide by the laws of South Africa.
You do not want them to get angry with you ;-).

Related

Wiki: Home