PPPoE

Introduction

PPP, the point-to-point protocol, is used to send networking traffic through a variety of direct connections: serial cable, standard telephone line, et cetera. It is based on the notion of a circuit, much like a telephone call, one reason it is so well suited to making dial-up connections to ISP modem pools. PPPoE is an extension to this which allows you to send PPP frames inside Ethernet frames, which don't have any concept of 'circuits', and thereby have a dial-up-style connection where no actual dialing is involved and no "real" circuit exists. It is mainly used by ISPs with DSL service, and used mainly because it makes their life easier.

Prerequisites

DSL Modem Requirements (Non-USB)

As warned, your modem is likely set to use its PPPoE client. This is undesirable for a few different reasons. For one, if you're lucky, then the modem won't require you to open the web interface every time you wish to go online. If you're unlucky, it will require that, and it will also make you enter the username and password every time. Besides that, you probably can't disconnect without using the web interface, unless you bring down the interface of the NIC plugged into the modem. Typically, the modem has a timeout set after which it brings down the connection, which may or may not be configurable. In addition, all the DNS and routing information will be handled by the modem, and that may not be configurable either. Some modems will pass along all the DHCP settings from the ISP to the interface on your system, which you may not want; others will behave like a particularly limited router, requiring you to use the modem as your DHCP and DNS server, and as the default route (gateway). Sometimes, they'll let you statically configure the interface connected to the modem, but you still must direct all traffic through the modem IP. What it amounts to is a lack of control over your connection, or at least the need to deal with the modem's own particular configuration methods, which will almost always require you to use a web browser to change anything.

So, what to do? Well, in figurative terms, we're going to tell the modem to mind its own business and just sit there passing packets back and forth. Thanks, but no thanks. In more accurate terms, we're going to make it behave like an Ethernet-to-ATM bridge, and only an Ethernet-to-ATM bridge. This is where the manual comes in, because once again, different modems have different interfaces and don't always use the same terms. Some will call this "PPP is on the Computer", some will have an option similar to "RFC 1483 Bridging", others will call it "Bridging Mode", still others will call it "RFC 2684 Bridging", et cetera. Whatever it's called, turn it on.

Is it on? If yes, then now we can get on with it. If no, then you've been stuck with a crippled modem. Curse the gods, and either live with it and use the recommended settings from the manual, or replace the modem. If you're really lucky, this is just a case of the modem coming as part of a DSL package, and your ISP thinks it's clever by disabling 'extra' features with a modified copy of the firmware. Unfortunately for them, they can't really disable the firmware update features, because if it turns out something was wrong with it, they'd have to physically replace all the DSL modems they've sent out, instead of just telling users to update the firmware themselves. What that means is you can probably track down a copy of the real, complete firmware from the modem manufacturer, update, then do what you want with it. Which is only appropriate, since under the service agreement, you probably own the modem outright even if it was provided free of charge.

Required Software

PPPoE support in Linux is a two-piece puzzle. The first piece is in the kernel:

Kernel Configuration

In menuconfig, navigate to this menu:

-> Device Drivers
   -> Network device support

Now, enable the following options; you can build these into the kernel instead of using modules, if you want:

and:

Speaking of said daemon, this brings us to the second piece:

Installing PPP

If you haven't already done so, then you need to emerge net-dialup/ppp:

foo ~# emerge --search "%@net-dialup/ppp$"

Searching... [ Results for search key : net-dialup/ppp$ ] [ Applications found : 1 ] * net-dialup/ppp Latest version available: 2.4.4-r9 Latest version installed: [ Not Installed ] Size of files: 750 kB Homepage: http://www.samba.org/ppp Description: Point-to-Point Protocol (PPP) License: BSD GPL-2

foo ~# emerge net-dialup/ppp

That's it. The system can now make use of PPPoE.

Configuration

Modular Networking

/etc/conf.d/net

All network configuration should be kept in /etc/conf.d/net, so open that in your editor of choice. We'll start with a basic configuration, but don't worry: variations will be covered; this configuration, however, will likely be sufficient for most people, and is good for initial testing.

Basic Setup

config_eth0=( "null" )

config_ppp0=( "ppp" )
link_ppp0="eth0"
plugins_ppp0=( "pppoe" )

username_ppp0='your-ISP-username-here'
password_ppp0='your-ISP-password-here'

pppd_ppp0=(

    "noauth"
    "defaultroute"
    "usepeerdns"
    "default-asyncmap"
    "ipcp-accept-remote"
    "ipcp-accept-local"
    "lcp-echo-interval 15"
    "lcp-echo-failure 3"
    "mru 1492"
    "mtu 1492"
    "debug"
)

So, what does all that pppd_ppp0 stuff mean? In brief:

• noauth - Don't ask your ISP to authenticate itself to you. Because it won't.
• defaultroute - pppd will automatically add a default route (i.e. your ISP's gateway)
• usepeerdns - will get and use up to two DNS server addresses from your ISP.
• default-asyncmap - escape all control characters
• ipcp-accept-remote - Accept whatever the ISP tells you its IP address is
• ipcp-accept-local - Accept whatever the ISP thinks your IP address is
• lcp-echo-interval 15 - request that the ISP send an LCP-ECHO packet every 15 seconds
• lcp-echo-failure 3 - consider the link dead if 3 consecutive requests go unanswered (more on this later)
• debug - print connection info to the system logs

A bit less brief:

• mtu 1492 and mru 1492 - The MTU is the "Maximum transmission unit", and refers to the largest allowed packet size on a given network layer. For Ethernet, that is always 1500 bytes. PPPoE, however, has a little overhead involved: 2 bytes are used by PPP, and an additional 6 are used by the PPPoE header itself. So, 1500 - (6 + 2) = 1492. Setting the MTU to this value reduces fragmentation, and can avoid problems with mis-configured firewalls. MRU, as you might guess, is the "Maximum Receive Unit". This is a PPP-specific setting, and the PPPoE standard requires that it be no more than 1492. It will most likely be negotiated to that value while connecting anyway, but setting it explicitly is just an extra little bit of insurance.

Now, before getting into alternate configurations, test this one out and see if it works. First, we need to create the net.ppp0 service: ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0

Next, we start it: /etc/init.d/net.ppp0 start

You should see output that is similar to this:

* Starting ppp0
*   Loading networking modules for ppp0
*   modules: apipa arping bridge ccwgroup macchanger macnet rename iwconfig essidnet iptunnel iproute2 pppd system ip6to4
*     iproute2 provides interface
*     pppd provides ppp
*   Bringing up ppp0
*     ppp
*       Running pppd ...
*       Backgrounding ...

Now check that the interface has been configured: ifconfig ppp0

The output should look like this, but with real IP addresses:

ppp0      Link encap:Point-to-Point Protocol
          inet addr: xxx.xxx.xxx.xxx  P-t-P: xxx.xxx.xxx.xxx  Mask:255.255.255.255
          UP POINTOPOINT RUNNING NOARP MULTICAST  MTU:1492  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:3
          RX bytes: 0 (0 b)  TX bytes:0 (0 b)

Now, let's see if it actually works: ping www.google.com

If you get a response, it works. It also means DNS is properly configured.

Alternate Setup: Assign a static IP address to eth0

While you can do this "just because", it's useful when you have a small private LAN and other machines connect to the Gentoo box, which is connected to the DSL modem. I.e., sharing a single Internet connection. The ways to do sharing are varied, and won't be covered here. In this case, you don't need to alter the configuration of ppp0. All that needs to change is eth0:

config_eth0=( "192.168.0.2/24" )

Alternate Setup: Password kept in /etc/ppp/*ap-secrets

For this, leave out the "password_ppp0=" line in /etc/conf.d/net, and, if you have not yet done so, edit /etc/ppp/pap-secrets and/or /etc/ppp/chap-secrets. Both files use the same format:

#      client                   server          secret               IP addresses
your-ISP-username-here            *       your-ISP-password-here

Alternate Setup: No automatic assignment of DNS servers

If you use some specific DNS service, run a local DNS proxy server for caching, or would just prefer a static DNS configuration, remove the line "usepeerdns" from /etc/conf.d/net. Now set your nameserver addresses in /etc/resolv.conf, or perform whatever configuration is required with the proxy or service you use.

Alternate Setup: Pseudo-Always-On Connection

Remember this setting: "lcp-echo-failure 3"?

Normally, what would happen is that ppp would disconnect and quit once that limit was reached. However, there's a simple way to have it keep initiating new connections with your ISP, so that in effect your connection to the Internet never goes down (or not for very long, anyway. Also, your IP address will change every time you connect, unless you've been assigned a Static IP. Usually, that means paying extra). This is nice if your ISP forcibly disconnects you after some arbitrary period, or the DSL modem loses sync momentarily, or there's just some random error and the link dies. To do this, use the following for "pppd_ppp0=" in /etc/conf.d/net:

pppd_ppp0=(

    "noauth"
    "defaultroute"
    "usepeerdns"
    "default-asyncmap"
    "ipcp-accept-remote"
    "ipcp-accept-local"
    "lcp-echo-interval 15"
    "lcp-echo-failure 3"
    "persist"
    "holdoff 2"
    "mru 1492"
    "mtu 1492"
    "debug"
    "lock"
)

The three additions have the following effects:

• persist - pppd will not exit, but attempt to re-open a connection
• holdoff 2 - wait 2 seconds between each attempt
• lock - create a lock file, on the off-chance something else should try to grab the device

You can adjust the holdoff interval if 2 seconds is too short a time for your ISP. In addition, if you want, you can have pppd give up and quit after a certain number of reconnection attempts. Normally, it will just keep trying until it succeeds. So to change that, add this option:

"maxfail N"

where N is some positive integer (N = 0 is the same as the default behavior defined by the baselayout scripts: keep trying forever).

Alternate Setup: Bring ppp0 up on demand

If your DSL access is metered, or you don't feel comfortable leaving the system connected more or less permanently, but you don't want to deal with having to start a connection manually every time, then use the following "pppd_ppp0=":

pppd_ppp0=(
    "noauth"
    "defaultroute"
    "asyncmap 0"
    "ipcp-accept-remote"
    "ipcp-accept-local"
    "lcp-echo-interval 30"
    "lcp-echo-failure 5"
    "noipdefault"
    "demand"
    "persist"
    "idle 300"
    "holdoff 2"
    "debug"
    "mru 1492"
    "mtu 1492"
    "lock"
)

What the changes do:

• demand - pppd will initiate a connection when it detects traffic on the link interface: eth0
• noipdefault - Don't try to figure out the IP address of the system from the hostname. Just let the ISP decide what it is. They will anyway.
• idle 300 - Bring down the link after 300 seconds (5 minutes) of inactivity. Adjust to suit your preference.
• holdoff 2 - As with an "Always-On" configuration: wait 2 seconds between connection attempts
• lock - Also as with an "Always-On configuration: create a lock file, on the off-chance something else should try to grab the device

It needs to be noted that the demand option was not intended for use with dynamic-addressing, and cannot be guaranteed to work. However, in all probability, it will work just fine.

That said, there is another aspect of an on-demand link that needs consideration: which sorts of traffic count as activity. If the interface used for the link is also used for other purposes, the link will never be considered idle, and thus, never deactivate. The solution to this is the "active-filter" option for pppd. In order to make use of it, you'll need to modify the kernel configuration given at the top of this document by enabling "PPP filtering":

You must also emerge net-dialup/ppp with the activefilter USE flag enabled. Now you can add this to the options in "pppd_ppp0=" in /etc/conf.d/net:

"active-filter 'filter-expression'"

where the expression takes the form of those used by the tcpdump utility. These can get quite complicated, depending on what sort of traffic you're interested in filtering, how other parts of your network are configured, in which direction the traffic is moving, and so forth. As such, they're really outside the scope of this document, and you should consult the pppd and tcpdump man pages for more information on how to construct one. Links to both are in the Resources section of this document, or just read your local copies.

Alternate Setup: DSL modem assigns an address via DHCP

This is almost certainly unnecessary, and you can and should just ignore the fact that the modem offers to do this. You're under no obligation to use the offered address, and it will not interfere with your ability to connect if you do not. If for some reason you still want to use this feature, you will want to configure eth0 as follows:

config_eth0=( "dhcp" )
dhcp_eth0="release nodns nontp nonis nogateway nosendhost"

Otherwise, the DSL modem will set itself as both DNS server and the default route, which probably won't work. On the other hand, it might work, and may be required. The modem may also do other things, like pass along DHCP settings from your ISP. This inconsistency among modems is why you should just not bother. There's really no point in using DHCP for a single interface, especially when eth0 doesn't even need an IP address at all in order to work with PPPoE. If you still insist on it, and the above doesn't work, then remove the "dhcp_eth0" line. If that doesn't work, then consult the modem's manual for its particular notion of a 'correct' network configuration. Lastly, it could very well be that DHCP just won't work right if you've disabled the modem's PPPoE client, which if you've gotten to this point, you have (or at least you should have).

Alternate Setup: PPPoE with the DHCPC plugin and /etc/conf.d/net

Currently, the baselayout scripts do not have any direct support for ppp's DHCPC plugin. It is not clear that it can even be used in conjunction with the PPPoE plugin, and documentation is very sparse. For now, it is recommended that you try to use one of the other configurations.

Alternate Setup: /etc/conf.d/net with net-dialup/rp-pppoe (adsl module)

If you have an existing PPPoE setup using the net-dialup/rp-pppoe package, you can use it with the "Modular Networking" method.

Well, you've been warned, so here's how to set it up:

config_eth0=( "adsl" )
adsl_user_eth0="your-ISP-username-here"

You must separately configure rp-pppoe for the above to work. For that, see the next section. The only difference will be how you start the connection.

With the adsl module, you run this command: /etc/init.d/net.eth0 start

Old method: RP-PPPoE without Modular Networking

Well, first things first. You need the net-dialup/rp-pppoe package: emerge rp-pppoe

Now we can configure it. There are two ways to do this:

• Run the package's configuration script: pppoe-setup

• Manually edit /etc/ppp/pppoe.conf

With the first method, you will be prompted to enter various bits of information, such as your username, whether to automatically assign DNS addresses, et cetera. For the second method, open /etc/ppp/pppoe.conf in an editor, and locate these variables:

ETH=eth0

USER=your-ISP-username-here

DEMAND=no

DNSTYPE=SERVER

PEERDNS=yes

DNS1=
DNS2=

DEFAULTROUTE=yes

LINUX_PLUGIN=

If these defaults are acceptable, then simply enter your username. You'll need to put your password into /etc/ppp/chap-secrets and/or /etc/ppp/pap-secrets. See Alternate Setup: Password kept in /etc/ppp/*ap-secrets above. It's recommended that you make the following change, though:

LINUX_PLUGIN=rp-pppoe.so

This will use the kernel-mode pppoe driver, which is less CPU-intensive than the default userspace implementation used by rp-pppoe. Other configuration options are detailed below.

Specify DNS servers

To set your DNS servers manually, make these changes:

DNSTYPE=SPECIFY

PEERDNS=no

DNS1=your-first-DNS-server-here
DNS2=your-second-DNS-server-here

Start on demand

To bring the link up on demand, make this change:

DEMAND=300

This will bring down the link after 300 seconds of inactivity, i.e. 5 minutes. Adjust to suit your preference.

Don't reconnect when link is lost

If instead you want the connection to stay down in the event of a disconnect, find and uncomment this line:

# RETRY_ON_FAILURE=no

Now, to start the connection, run: pppoe-start

and test with a ping: ping www.google.com

Using PPPoE with Verizon FIOS

Verizon FIOS is a residential fiber-to-the-premises service available in some parts of the United States. Verizon offers both a cheaper service with dynamic addressing, and a more-expensive service with static IP addresses. The cheaper service uses PPPoE, the more expensive service is a direct ethernet connection.

(I have read that the cheaper service is moving to DHCP at least on some areas, this was not the case for me.)

The Basic Install in this HOWTO works for Verizon FIOS. Simply remove the cat-5 where it connects to the D-Link box, and plug it into your NIC. Use the same username and password for PPP as you have set up for your Verizon email.

Troubleshooting

I'm connected, everything is configured correctly (no, it really is), but it doesn't work right (or at all)

Sometimes, this just happens. Some miscommunication between you and your ISP, or just some glitch on the ISP's end, leaves you with an unusually laggy or non-functioning link. If you're taking advantage of the "persist" option try this: killall -HUP pppd

This will send SIGHUP (Hang Up) to pppd, causing it to lose the link and reconnect. If you aren't using "persist", or SIGHUP doesn't do it, issue this command: /etc/init.d/net.ppp0 restart

I'm connected, but the test ping is timing out

Make sure the default route is correct: ip route

You should see a final line like this:

default via xxx.xxx.xxx.xxx dev ppp0

An alternative command is: route

The output for that should include:

default         xxx.xxx.xxx.xxx   0.0.0.0         UG    0      0        0 ppp0

If you do not see the expected output, check /etc/conf.d/net to make sure you didn't forget the "defaultroute" line for ppp and that you haven't set a default route with another interface. If you're unable to ping and you got a bunch of usage output for pppd when you started the service, check your spelling.

This can also be another version of the first scenario

The ppp0 interface isn't there when I run ifconfig

Well, give it a few seconds, then check again. Sometimes, the ISP is a little slow to respond. If it still hasn't shown up, then it's time to check the system logs. Aren't you glad you used the "debug" option now? Assuming you send all output to /var/log/messages (adjust for your local logging configuration), issue this command: grep pppd /var/log/messages

The output for a successful connection looks like this (minus the date and timestamp):

Plugin rp-pppoe.so loaded.
RP-PPPoE plugin version 3.3 compiled against pppd 2.4.4
pppd 2.4.4 started by root, uid 0
PADS: Service-Name: ''
PPP session is SomeInteger
using channel SomeInteger
Using interface ppp0
Connect: ppp0 <--> eth0
sent [LCP ConfReq id=0x1 <mru 1492> <magic SomeHexInteger>]
rcvd [LCP ConfReq id=0x20 <mru 1492> <auth pap> <magic SomeHexInteger>]
sent [LCP ConfAck id=0x20 <mru 1492> <auth pap> <magic SomeHexInteger>]
rcvd [LCP ConfAck id=0x1 <mru 1492> <magic SomeHexInteger>]
sent [LCP EchoReq id=0x0 magic=SomeHexInteger]
sent [PAP AuthReq id=0x1 user="your-ISP-username-here" password=<hidden>]
rcvd [PAP AuthAck id=0x1 ""]
PAP authentication succeeded
peer from calling number XX:XX:XX:XX:XX:XX authorized
sent [IPCP ConfReq id=0x1 <addr xxx.xxx.xxx.xxx>]
rcvd [IPCP ConfReq id=0x87 <addr xxx.xxx.xxx.xxx>]
sent [IPCP ConfAck id=0x87 <addr xxx.xxx.xxx.xxx>]
rcvd [IPCP ConfNak id=0x1 <addr xxx.xxx.xxx.xxx>]
sent [IPCP ConfReq id=0x2 <addr xxx.xxx.xxx.xxx>]
rcvd [IPCP ConfAck id=0x2 <addr xxx.xxx.xxx.xxx>]
local  IP address xxx.xxx.xxx.xxx
remote IP address xxx.xxx.xxx.xxx
Script /etc/ppp/ip-up started (pid SomeInteger)
Script /etc/ppp/ip-up finished (pid SomeInteger), status = 0x1

If you don't see that, you'll have error messages instead. Check /etc/conf.d/net and/or /etc/ppp/*ap-secrets, since you may have mis-typed your username and/or password. If you see a message that "Account Status does not equal 'Enabled'" or something similar, call your ISP and find out what their problem is. If you do see the above, and it's still not working, then this is probably yet another variation on the first scenario. This is also likely the case if you see messages such as:

Timeout waiting for PADO packets

That can also result from problems on the ISP end of things, so just keep trying, and call them if it doesn't resolve itself within a reasonable period of time. A third possibility is a problem with either the Ethernet NIC or the DSL modem. Google is your friend.

I'm sharing the DSL connection, and the other computers can't access some (or any) web sites (or anything at all for that matter)

You'll want to set the MTU for those machines to 1492 as well, and if you're using iptables (which you should be), you'll want to add another rule. First, check that you have the necessary kernel options compiled.

In menuconfig for kernel 2.6, navigate to:

 -> Networking
   -> Networking Options
     -> Network Packet Filtering Framework (Netfilter)
       -> IP: Netfilter configuration
         ->IP tables support

Now, enable the following options. If you're building IP tables support as modules, you will need to load the ipt_TCPMSS module (after suitable compiling, etc.).

Then, add the new iptables rule:

iptables -A FORWARD -p tcp -m tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu

It could also be that you haven't correctly set up forwarding and routing, or that you haven't configured the default route on the client machines properly, amongst other things outside the scope of this document.

Name resolution is slow

So, you're using a static DNS setup, or caching proxy, et cetera. Make sure the addresses in /etc/resolv.conf or those used in the configuration file for the proxy (or whatever you use) are correct.

Resources

Official Gentoo Documentation

• Network Configuration Guide
• Home Router Guide: Section on PPPoE
• Kernel Configuration Guide
• Initscripts Guide

Other Sources

General

• PPP Homepage
• RP-PPPoE Homepage
• pppd(8) man page
• tcpdump(8) man page
• Linux PPP HOWTO
• DSL HOWTO for Linux (includes information on USB modems)

USB DSL Modems

• Speedtouch 330 ADSL USB Modem Alternative HOWTO (from the Gentoo Forums)
• ATM on Linux HOWTO (rather outdated)
• Linux kernel driver for SpeedTouch USB modems
• Conexant AccessRunner ADSL USB modems with Linux
• br2684ctl(1) man page
• HARDWARE Install a modem that uses the eagle-usb software
• HOWTO Speedtouch modem