This guide is for setting up an ADSL Internet connection using an ethernet PPPoE modem under Ubuntu 9.10 Server Edition (Karmic Koala) but previous versions of Ubuntu should be similar. Desktop versions of Ubuntu use Network Manager (nice GUI) to manage DSL connections. This guide is for configuring a connection via command line (e.g., ssh, terminal window).
Although it may be very common to use a router to connect to the Internet, at times it may be necessary to directly connect to an ADSL (frequently referred to as 'DSL') modem using PPPoE. In fact, the router used to provide internet access to the network may be running Ubuntu!!!
It is useful to know how to connect to an Internet Service Provider (ISP) using a (A)DSL modem that is configured as a "Bridge." This document lists the steps needed to establish a PPPoE network connection.
Of course, you will need to have subscribed to an ISP, and that your Internet connection is installed and functional. A "DSL" light on your modem usually shows that the line is synchronized.
You will need your username and password provided by your ISP for your DSL account. This document assumes that the computer running Ubuntu is directly connected to the (A)DSL modem via a standard network cable. If you are connecting to the modem with a usb cable, this guide is not for you.
Configuration with pppoeconf
Again, this guide is for configuring a connection via command line. You will either use the console (monitor and keyboard) provided by Ubuntu 9.10 Server Edition or over an ssh session (or telnet, shame on you!).
If you are using XOrg (a Graphical User Interface or GUI with pretty picture and menus, and colors, and such), you should be using the included Network Manager. If you are insistent upon configuring your network connection via command line, you can use a terminal. To open a terminal, use the menu bar : Applications > Accessories > Terminal.
PPPoE package installation
The PPPoE package is installed by default, but can be missing if the configuration has been changed. To check if the PPPoE package is installed, type:
dpkg -s pppoeconf
If it is installed you should see the output on the package where two lines show this:
Package: pppoeconf Status: install ok installed
If the package is not installed, insert your Ubuntu CD and in a terminal type:
sudo apt-get install pppoeconf
If the package cannot be found, you may have to add your Ubuntu CD to the list of software repositories. To add your CD, make sure it is inserted in your CD drive and in a terminal type:
sudo apt-cdrom add
If all else fails, you can download the pppoeconf package from http://packages.ubuntu.com/. Of course you will need a working Internet connection, and then to transfer the package via a CDR or USB stick for example. Double click on the package in GNOME to install it.
On the console or in your terminal session type:
A text-based menu program will guide you through the next steps, which are:
- Confirm that your Ethernet card is detected.
- Enter your username (provided by your ISP).
- Enter your password (provided by your ISP).
- If you already have a PPPoE Connection configured, you will be asked if it may be modified.
- Popular options: you are asked if you want the 'noauth' and 'defaultroute' options and to remove 'nodetach' - choose "Yes".
- Use peer DNS - choose "Yes".
- Limited MSS problem - choose "Yes".
- When you are asked if you want to connect at start up, you will probably want to say yes. (This option does not work) See the secton "Connecting on Boot"
- Finally you are asked if you want to establish the connection immediately.
Once you have finished these steps, your connection should be working.
Manual connection control
To start your ADSL connection on demand, in a terminal type:
To stop your ADSL connection, in a terminal type:
in most cases, you can just type "poff" to stop the ADSL connection and unload the module.
If your connection does not seem to work, try turning your previously configured ADSL connection on manually (see previous section). To see log, in terminal type:
Configuration by hand
This covers configuration PPPD by hand. It is a rehash of what pppoeconf did earlier, but with some subtle differences. The pppoeconf script only configures one connection called "dsl-provider" for the entire system. If you change ISPs or have multiple internet connections, you will need to re-run pppoeconf every time you wanted to use a different connection. And, as noted earlier, pppoeconf's On-Boot option does not work out of the box. By writing the config files by hand, you can have as many custom named connections as needed.
'Note' This document assumes you are familiar with a console/terminal based text editor. You should know how to edit/save text files using the editor of your choice.
The chap-secrets File
The first step is to edit the "/etc/ppp/chap-secrets" file. This file contains usernames and passwords. If my ISP assigned my username as joe.user and my password as P@$$w0rd002, I would edit/save the file to look like this.
Also at this point we can add a static IP address if you have one.
# Secrets for authentication using CHAP # client server secret IP addresses "joe.user" * "P@$$w0rd002" XXX.XXX.XXX.XXX
Next, create a Peer file that contains the settings for connecting to your ISP. This file can by named whatever you want, but might I suggest something that is easy to type. Reason being that the name of this file will be name used to bring the connection up and down. So if it were called COMCAST, you would have to type pon COMCAST and poff COMCAST. The "pppoeconf" script creates a file called dsl-provider. The Peer file is saved under the /etc/ppp/peers/ directory. Ubuntu provides a file called provider that explains some of the most common settings.
pppoeconf's default dsl-provider
Here is the dsl-provider file created by the pppoeconf script:
# Minimalistic default options file for DSL/PPPoE connections noipdefault defaultroute replacedefaultroute hide-password noauth persist plugin rp-pppoe.so eth0 user "joe.user" usepeerdns
Again, you can read about most of the commonly used options in the /etc/ppp/peers/provider file or reference the man (8) pppd page. However, I would like to point out some very important options in this file.
Any Line beginning with # is a comment
The plugin rp-pppoe.so option allows pppd to refer the interface by linux naming standards. It is a requirement for PPPoE connections.
eth0 tell pppd to build the connection on eth0. On systems with one network card, this is not a problem. If the system has two or three interfaces (like a router), you need to specify which interface is connected to the modem, be it eth1 or eth3 even. I even seen people build VPN over wireless where they had to use wl0. If this option is not specified, then PPPD will use the first ethernet interface listed in the kernel (which is usually eth0, but not always!!).
If you want all of your traffic to go over this connection, and that is usually the case, set the defaultroute and replacedefaultroute options. When the connection is made, the routing table is modified automatically to send your traffic to the ISP.
Along with ip information, most ISPs provide DNS servers to use for name resolution, to use the ISP provided servers, you should set the usepeerdns option.
Extended SBCGlobal Peer File
Here is an extended configuration file used to connect to SBCGlobal:
#/etc/ppp/peers/SBCGlobal # Load rp-ppoe.so for kernel mode interface naming compatibility (ie, ppp0, ppp1) plugin rp-pppoe.so # Which interface should be used by pppd when building the connection. eth2 #Which user/password to use from /etc/ppp/chap-secrets file. user "joe.user" #Bind this connection to ppp99 unit 99 #PPPD Options noipdefault defaultroute replacedefaultroute hide-password noauth persist
There are a few extra options here.
Here PPPD would build the connection on interface eth2.
If you are building a router that uses multiple PPP connections, sometimes it is convenient to have a specific service always come up on a specific interface. With the unit option, this peer will always connect as ppp99.
Notice the absence of usepeerdns. This is because this network has local DNS servers and therefore doesn't need the ISP-provided servers.
Dialing Peer Files
After creating these two files, you should now be able to dailup the connection using the commands listed in the Manual connection control section. If you ran pppoeconf to create the dsl-provider peer file /etc/ppp/peers/, you would dial-up with:
pon dsl-provider poff dsl-provider
Or if you want to use the custom SBCGlobal peer file:
pon SBCGlobal poff SBCGlobal
Exposing PPP Connections to the OS
Now, you could get by this far by using scripts to bring up your interfaces, or bring them up and down manually with the pon and poff commands. But there is a better way to handle the connection. Ubuntu already provides the ifup and ifdown commands for configuring your regular network connections. Well, the ifup and ifdown commands can be used to establish the PPP connections also. This makes habling the interfaces consistent with any other interface, and you are probably familiar with these commands already. This is also critical if the connection needs to be established at system boot.
Interfaces maintained the the ifup and ifdown commands are defined in the /etc/network/interfaces file. If you look at the file now, you may already see how your network connections are currently configured, be it by DHCP or static IP Address assignment
cat /etc/network/interfaces # This file describes the network interfaces available on your system # and how to activate them. For more information, see interfaces(5). # The loopback network interface auto lo iface lo inet loopback # DHCP network configuration auto eth0 iface eth0 inet dhcp
We will modify this file to include a section for the PPP connection and to change eth0 from being configured by DHCP. The pppoeconf script created following configuration file:
cat /etc/network/interfaces # This file describes the network interfaces available on your system # and how to activate them. For more information, see interfaces(5). # The loopback network interface auto lo iface lo inet loopback auto dsl-provider iface dsl-provider inet ppp pre-up /sbin/ip link set dev eth1 up # line maintained by pppoeconf provider dsl-provider auto eth0 iface eth0 inet manual
This allows the user to use ifup and ifdown to enable and disable the pppoeconf configured connection:
ifup dsl-provider ifdown dsl-provider
This template works for manually bringing the ppp0 interface up and down. You could write your own Peer files and modify the template accordingly to have the same functionality. However, this does not work as advertised at system startup/shutdown!!!
The configuration provided by pppoeconf does not actually bring the connection up at system boot. But with some modifications to the configuration file, your system should dialup the connection.
Below is the template that will bring the connect up at system boot:
auto eth0 iface eth0 inet ppp pre-up /sbin/ip link set dev eth0 up provider dsl-provider post-down /sbin/ip link set dev eth0 down
Notice that the two sections have been merged together. There is no separate stanza for dsl-provider and eth0. Only one stanza to cover them both.
Here is the stanza for the SBCGlobal peer file from earlier in the walk-through:
auto eth2 iface eth2 inet ppp pre-up /sbin/ip link set dev eth2 up provider SBCGlobal post-down /sbin/ip link set dev eth2 down
Here the stanza configures eth2 (versus eth0), and it calls the SBCGlobal peer file (versus the default dsl-provider peer file).
With this stanza, the system will be able to establish the connection using both the ifup and ifdown commands, and at system startup/shutdown. This works for 9.10 (Karmic Koala). If it does not work for you, you may try the following.
If you find that you have to run pppoeconf each time you boot, you can try two things:
Edit /etc/network/interfaces as described here, so that that 'pppoe maintained' lines are before 'auto dsl-provider':
# added by pppoeconf auto eth0 iface eth0 inet manual pre-up /sbin/ip link set dev eth0 up # line maintained by pppoeconf auto dsl-provider iface dsl-provider inet ppp provider dsl-provider
- Failing that, edit /etc/rc.local, and before the last line ("exit 0"), add:
ip link set dev eth0 up pon dsl-provider
If you are having problems with your connection, you may find valuable information in the system message logs. You may access system logs either in a terminal, or with a graphical interface.
To use the graphical log viewer, in the menu bar, go to : System > Administration > System Log. You will find the system messages in /var/log/messages.
- To use the terminal, type: