Gentoo Wiki




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.


DSL Modem Requirements (Non-USB)

Warning: Most DSL modems have a PPPoE client and DHCP server built into their firmware, and are usually configured to use it by default. Typically, you must use DHCP to configure the NIC connected to the modem, then enter the modem's pre-set IP address in a browser in order to access a configuration page. You can use this web interface to simply enter your ISP username and password, and the modem will then handle the PPPoE connection. You'll have to consult the manual if you wish to do this, as each modem has its own requirements for network settings. If you chose to do that, then this document DOES NOT APPLY and if you try to configure things as shown in this How-To, your connection WILL NOT WORK. If you want to handle PPPoE yourself, which is recommended, keep reading.

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:

Linux Kernel Configuration:
-> Device Drivers
   -> Network device support

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

Linux Kernel Configuration:

[*] Network device support


Linux Kernel Configuration:

<M> PPP (point-to-point protocol) support

[ ] PPP multilink support (EXPERIMENTAL)

[ ] PPP filtering

<M> PPP support for async serial ports

< > PPP support for sync tty ports

< > PPP Deflate compression

< > PPP BSD-Compress compression

< > PPP MPPE compression (encryption) (EXPERIMENTAL)

<M> PPP over Ethernet (EXPERIMENTAL)

Note: PPPoE does not and will not use any of the compression algorithms, so enabling them, while harmless, is also pointless. As to "PPP filtering", if you need to do packet filtering in general, you want to use iptables. The option above is to allow pppd's active-filter feature to function. It is used by pppd only for deciding which packets count as link activity. It is not for firewalling. OK, that's actually not completely true: pppd also has the pass-filter option, which can be used as a limited firewall. However, pretend it is true and just use iptables.

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$"Image:CursorOFF.gif
[ 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
      Description:   Point-to-Point Protocol (PPP)
      License:       BSD GPL-2
foo ~#
emerge net-dialup/pppImage:CursorOFF.gif

Note: Don't issue the search command. It's only there to show you the package info. Just use the second command.

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


Modular Networking

Note: The current stable baselayout packages on Gentoo use what's called "Modular Networking". It is now the default method for all network configuration, and older versions of baselayout which lack support for it are no longer in portage. If you still use one of those, it is strongly recommended that you upgrade to at least baselayout version 1.12.9-r2. With one exception, this How-To does not cover obsolete methods. Also, it must be noted that baselayout versions between 1.11.11 and 1.12 use an earlier version of Modular Networking and do not work with the methods detailed here, which are based off those in the current Gentoo Handbook.


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.

Note: In this How-To, eth0 is used as the link interface for PPP. Other interfaces can certainly be used, including those of USB DSL modems. As to the latter, since USB modems can be used with other encapsulations (or none at all), and typically require additional configuration using the net-misc/br2684ctl and other packages, as well as additional kernel drivers, they are not covered here. Once properly configured for use with PPPoE, they behave much like any other interface. See the USB DSL Modems section under Resources for a few links to USB modem information.

Basic Setup

File: /etc/conf.d/net
config_eth0=( "null" )

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



    "lcp-echo-interval 15"
    "lcp-echo-failure 3"
    "mru 1492"
    "mtu 1492"

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

A bit less brief:

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 ...
Note: It can vary slightly, based on whether other networking packages are installed or not, and also depending on the value of RC_VERBOSE in /etc/conf.d/rc. The above comes from having it set to "yes".

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:  P-t-P:  Mask:
          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

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:

File: /etc/conf.d/net
config_eth0=( "" )
Note: Change the address to any given private IP, according to taste

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:

File: /etc/ppp/*ap-secrets
#      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:

File: /etc/conf.d/net

    "lcp-echo-interval 15"
    "lcp-echo-failure 3"
    "holdoff 2"
    "mru 1492"
    "mtu 1492"

The three additions have the following effects:

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

File: /etc/conf.d/net
    "asyncmap 0"
    "lcp-echo-interval 30"
    "lcp-echo-failure 5"
    "idle 300"
    "holdoff 2"
    "mru 1492"
    "mtu 1492"

What the changes do:

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

Linux Kernel Configuration:

[*] 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:

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

File: /etc/conf.d/net
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.

Warning: If you are setting PPPoE up for the first time, this method is not encouraged or recommended. It is also not recommended even if you already have an rp-pppoe-based setup. For one thing, the adsl module will eventually be removed, and all PPPoE configuration will be done with the ppp module. For another, look at it like this: with rp-pppoe by way of the adsl module, the situation is that you have the net.lo initscript, which then runs functions from the rcscript. One of those then runs /etc/ppp/pppoe-start which runs /etc/ppp/pppoe-connect which finally runs pppd. Throughout all that other files are opened by rp-pppoe for config data, and there's a bunch of redundancy all around. Stopping the connection is a similarly layered process. Then you have the all extra stuff rp-pppoe does: setting up (very) basic firewalls, and things like its link-status script. Using the ppp module is much more direct: net.lo is called with the name net.ppp0, so it then runs the pppd_start function from the rcscript, the ppp config data is read from /etc/conf.d/net, error checking is done and the type of connection determined, and it runs pppd. When it's done, the only process running is pppd itself. Using rp-pppoe, other processes will hang out in the background doing stuff you don't need. Now that the rp-pppoe plugin is a standard part of net-dialup/ppp, an extra userspace package and its associated scripts and config files is simply unecessary. Granted, it's got a nice "Just answer a few simple questions" script for configuration, but that's about its only advantage.

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

File: /etc/conf.d/net
config_eth0=( "adsl" )
Note: If your username is already set in /etc/ppp/pppoe.conf, then leave the "adsl_user_eth0" line out

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:

Note: Older versions of rp-pppoe call this adsl-setup

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:

Note: The default file is extensively commented, and contains many more options, which for brevity have been omitted.

File: /etc/ppp/pppoe.conf








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:

File: /etc/ppp/pppoe.conf

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:

File: /etc/ppp/pppoe.conf



Start on demand

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

File: /etc/ppp/pppoe.conf

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:

File: /etc/ppp/pppoe.conf

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

Note: Older versions of rp-pppoe call this adsl-start

and test with a ping: ping

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.


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 dev ppp0

An alternative command is: route

The output for that should include:

default         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 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>]
rcvd [IPCP ConfReq id=0x87 <addr>]
sent [IPCP ConfAck id=0x87 <addr>]
rcvd [IPCP ConfNak id=0x1 <addr>]
sent [IPCP ConfReq id=0x2 <addr>]
rcvd [IPCP ConfAck id=0x2 <addr>]
local  IP address
remote IP address
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:

Linux Kernel Configuration:
 -> 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.).

Linux Kernel Configuration:

[*] TCPMSS target support

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.


Official Gentoo Documentation

Other Sources


USB DSL Modems

Retrieved from ""

Last modified: Fri, 05 Sep 2008 09:40:00 +0000 Hits: 27,364