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 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:

sudo pppoeconf

A text-based menu program will guide you through the next steps, which are:

  1. Confirm that your Ethernet card is detected.
  2. Enter your username (provided by your ISP).
  3. Enter your password (provided by your ISP).
  4. If you already have a PPPoE Connection configured, you will be asked if it may be modified.
  5. Popular options: you are asked if you want the 'noauth' and 'defaultroute' options and to remove 'nodetach' - choose "Yes".
  6. Use peer DNS - choose "Yes".
  7. Limited MSS problem - choose "Yes".
  8. 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"
  9. 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:

pon dsl-provider

To stop your ADSL connection, in a terminal type:

poff dsl-provider

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

Peer Files

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

plugin eth0
user "joe.user"

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 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:

# Load for kernel mode interface naming compatibility (ie, ppp0, ppp1)

# Which interface should be used by pppd when building the connection.

#Which user/password to use from /etc/ppp/chap-secrets file.
user "joe.user"

#Bind this connection to ppp99
unit 99

#PPPD Options

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 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!!!

Boot issues

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

Error logs

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:

sudo dmesg


ADSLPPPoE (last edited 2014-04-09 18:21:52 by n-md-tanjim)