U buntu.

com

Official Documentation
Page History

C ommunity

Support

P artners

Community Help Wiki Contribute

Login to edit

Search

ADSLPPPoE
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).

Introduction
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.

Contents
1. Introduction
2. Configuration with pppoeconf
1. PPPoE package installation
2. pppoeconf
3. Manual connection control
4. Problems
5. Configuration by hand
1. The chap-secrets File
2. Peer Files
1. pppoeconf's default dsl-provider
2. Extended SBCGlobal Peer File
3. Dialing Peer Files
6. Exposing PPP Connections to the OS
1. Boot issues
2. Error logs

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.

pppoeconf
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).
converted by W eb2PDFConvert.com

2.
3.
4.
5.
6.
7.
8.

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"
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.

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

plog

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"

XXX.XXX.XXX.XXX

"P@$$w0rd002"

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

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.
converted by W eb2PDFConvert.com

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 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
converted by W eb2PDFConvert.com

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:
1. 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
1. 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.
converted by W eb2PDFConvert.com

system logs either in a terminal, or with a graphical interface.

1. 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.
2. To use the terminal, type:

sudo dmesg
CategoryNetworking
ADS LPPPoE (last edited 2014-04-09 18:21:52 by n-md-tanjim)

The material on this wiki is available under a free license, see Copyright / License for details
You can contribute to this wiki, see Wiki Guide for details

converted by W eb2PDFConvert.com