Last updated on 1 Sep 2004

This HOWTO describes how to get an ADSL link from Telkom South Africa and how to use the ADSL link in a mixed Linux/Windows environment with a Linux machine as your firewall. Note: this worked for me, but it may not work for you. By following this HOWTO, you may bring plague and famine onto your family and your penis will probably fall off. You have been warned.

With the formalities over, let's get right to the nitty gritty.

Order the Line

  • Phone Telkom to order your ADSL service on 0800 2375 00. Don't use their online ordering system, it takes them much longer to print out the order and manually read it into their ordering system. They will ask you if you want the Telkom (free) modem. If you do, it will complicate things as there will be a credit-check involved and a contract that has to be signed and faxed back so that you're tied in for two years. I chose to use my own equipment (the D-Link unit described later). Also make sure you get an account number and an order number from them when you order!
  • I chose to use Telkom as my ISP. It costs R250/month and is the cheapest of the lot (there are other alternatives out there, search for them). If you use Telkom as your ISP, they will automatically assign you a username and password. You should be able to get this information faxed to you by the end of the third week.
  • After placing your order, you wait. Telkom specifies 21 working days for the installation to be completed, but your milage will vary substantially. I suggest you give them two weeks for the entire process to kick in. During this time they will assess if your exchange is capable of ADSL and if there are spare slots on the DSLAM blade. (If there are no spare slots, your order may take months to be processed.) My order took five weeks, from the day I ordered to they day they came to install.
  • After two weeks you must start to follow up with Telkom. Phone 0800 456 786 and enquire (very politely) how far the application is - they usually ask for your order number and then they can track it on their event management system. If things are going well, don't bother them. If not, start phoning every second day to enquire how far the order is. Be sure to keep your own log of dates that you phoned, information you got and make sure you take down the name of the call-center person every time. It helps to be able to refer back to names and dates if you have to escalate the issue to a supervisor.
  • At some stage Telkom will phone you with a date for installation. Confirm the date with them and make sure they start early. Be prepared to stay at home for the entire day as they drive around between your house and the exchange and install the ADSL termination point in your home.
  • Telkom will add a microfilter to your ADSL line for your existing phones. If you don't have any existing phones, you don't need any microfilters.
  • When the installation is complete, Telkom will ask you to test the line. Hook up your D-Link DSL-300T unit to the ADSL termination point. If the ADSL line is okay and the DSLAM is responding, the ADSL light/led on the D-Link unit will come on and remain on.
  • At this point you can tell the Telkom guy thanks and sign off the installation. From here on out, you need to do the rest of the configuration yourself.
  • Ingredients

    The ingredients you need to make your ADSL line work with a Linux machine acting as a firewall for the rest of your network. These are the parts I used and I've found them to work well.

  • One Linux machine (Pentium I, 166MHz or faster, 10GB disk with at least 64MB of RAM)
  • Two NICs for the Linux machine (one for internal LAN, one for the ADSL modem)
  • One ADSL modem capable of operating in ATM bridge/PPPoE mode
  • A HUB or switch and some internal machines for your internal LAN
  • I used the D-Link DSL-300T as my ADSL modem/ATM bridge (available from PCPalace in Centurion for about R570 excl. VAT). You can also get the D-Link from various other places in SA (use Google's Froogle to search for other outlets). Try to avoid Telkom's ADSL modems and especially avoid USB modems. You want one with an ethernet port.

    The whole idea of having a pure modem (ATM bridge) is that your Linux machine gets the IP address on Telkom's ADSL network. This allows you much greater flexibility when it comes to things lile using dynamic DNS, firewalling and port-forwarding. If you're not into using Linux and you don't have any Linux experience, rather buy a ADSL Router which performs all of the above functions in one little box.

    Linux installation

    Install your favorite Linux flavour onto your Linux box (I used redHat Linux 9). I did a full install so that all the tools will be available when I need them. Download the latest version of the Linux kernel in the 2.4.x or 2.6.x series and configure the kernel for your machine. Make sure you add "PPPoE kernel support" and IPTables to your kernel configuration. Compile the kernel and reboot your machine.

    Installing pppd

    Download the latest version of PPPd (must be version 2.4.2 or later) from the Samba site. This package includes the Roaring Penguin plugin for operating pppd over ethernet (PPPoE). Untar it, configure it and build it. Copy the new pppd binary over to /usr/sbin (overwriting your old pppd binary). Also copy into /usr/lib/pppd/2.4.2/ If the directory doesn't exist, create it. Edit your /etc/ppp/pap-secrets file and add this line:
    # client        server  secret                  IP addresses
    ""     *       "yourpassword"
    Where nnnnn is your ADSL account given to you by Telkom Internet. Also, replace "yourpassword" with the one you received from Telkom. Create a script in /etc/rc.d and call it rc.pppoe. In the script, call pppd to get the link up:
    # start pppd on eth0, assuming your ADSL modem
    # is connected to eth0
    /usr/sbin/pppd plugin eth0 unit 0 linkname ADSL user \ mtu 1492 noauth persist nomultilink defaultroute
    Note that you must replace nnnnn with the number you got from Telkom Internet. Also note that pppd loads the plugin and sets the MTU to 1492. This is needed for PPPoE to function correctly since PPPoE has an 8-byte overhead and the max MTU for ethernet is 1500 bytes. You might also have to lower the MTU on your internal machines to 1492 (from 1500) if you have trouble accessing certain sites. See here how to adjust the MTU for various Windows and Linux platforms.

    Remember to configure your DNS servers in /etc/resolv.conf. I use BIND locally on the machine, so my /etc/resolv.conf points to and then I have two 'forwarders' entries in my /etc/named.conf file that points to Telkom's two main DNS servers ( and


    You must create a firewall script to protect your machine and enable masquerading on your ppp0 interface. Check out Timothy Scott Morizot's Easy Firewall Generator for IPTables. It's a web interface that asks you a few simple questions and generates an excellent firewall script that you can call from /etc/rc.d/rc.local.

    Cube E-mail comments to