Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Apropos / Subsearch:
optional field

PPPOE(4)                 BSD Kernel Interfaces Manual                 PPPOE(4)

     pppoe -- PPP Over Ethernet protocol network interface

     pseudo-device pppoe

     The pppoe interface encapsulates Point-to-Point Protocol (PPP) packets
     inside Ethernet frames as defined by RFC 2516.

     This is often used to connect a router via a DSL modem to an access con-
     centrator.  The pppoe interface does not by itself transmit or receive
     frames, but needs an Ethernet interface to do so.  This Ethernet inter-
     face is connected to the pppoe interface via ifconfig(8).  The Ethernet
     interface needs to be marked UP, but does not need to have an IP address.

     There are two basic modes of operation, controlled via the link1 switch.
     The default mode, link1 not being set, tries to keep the configured ses-
     sion open all the time.  If the session is disconnected, a new connection
     attempt is started immediately.  The ``dial on demand'' mode, selected by
     setting link1, only establishes a connection when data is being sent to
     the interface.

     Before a pppoe interface is usable, it needs to be configured.  The fol-
     lowing steps are necessary:

     o   Create the interface.

     o   Connect an Ethernet interface.  This interface is used for the physi-
         cal communication.  As noted above it must be marked UP, but need not
         have an IP address.

     o   Configure authentication.  The PPP session needs to identify the
         client to the peer.  For more details on the available options see

     o   If using IPv6, configure a link-local address.

     This all is typically accomplished using an /etc/hostname.pppoe0 file.  A
     typical file looks like this:

           inet6 eui64
           inet NONE \
                   pppoedev em0 authproto pap \
                   authname 'testcaller' authkey 'donttell' up
           !/sbin/route add default -ifp pppoe0
           !/sbin/route add default -ifp pppoe0 fe80::

     The physical interface must also be marked 'up':

           # echo "up" > /etc/hostname.em0

     Since this is a PPP interface, the addresses assigned to the interface
     may change during PPP negotiation.  There is no fine grained control
     available for deciding which addresses are acceptable and which are not.
     For the local side and the remote address there is exactly one choice:
     hard coded address or wildcard.  If a real address is assigned to one
     side of the connection, PPP negotiation will only agree to exactly this
     address.  If one side is wildcarded, every address suggested by the peer
     will be accepted.

     To wildcard the local address set it to; to wildcard the remote
     address set it to

     A pppoe enabled kernel will not interfere with other PPPoE implementa-
     tions running on the same machine.  Under special circumstances (details
     below) this is not desirable, so the pppoe driver can be told to kill all
     unknown PPPoE sessions received by the Ethernet interface used for a con-
     figured pppoe interface.  To do this, add the following to your kernel
     config file:


     This option is only useful if you have a static IP address assigned and
     your ISP does not use LCP echo requests to monitor the link status.
     After a crash or power failure the peer device still tries to send data
     to the no longer active session on your computer, and might refuse to
     reestablish a new connection, because there already is an open session.
     On receipt of such packets, the pppoe driver with this option set will
     send a PADT packet (request to terminate the session).  The peer will
     immediately disconnect the orphaned session and allow a new one to be

     If the kernel is compiled with option PPPOE_SERVER, there are two modes
     of connection, controlled via the link0 switch.  The default mode, link0
     not being set, is client mode.  The ``PPPoE server'' mode, selected by
     setting link0, is to wait for incoming PPPoE sessions.

     Problems can arise on machines with private IPs connecting to the Inter-
     net via a machine running both Network Address Translation (NAT) and
     pppoe.  Standard Ethernet uses a maximum transmission unit (MTU) of 1500
     bytes, whereas PPPoE mechanisms need a further 8 bytes of overhead.  This
     leaves a maximum MTU of 1492.  pppoe sets the MTU on its interface to
     1492 as a matter of course.  However, machines connecting on a private
     LAN will still have their MTUs set to 1500, causing conflict.  Using a
     packet filter, the maximum segment size (MSS) can be set (clamped) to the
     required value.  The following rule in pf.conf(5) would set the MSS to

           match on pppoe0 scrub (max-mss 1440)

     Although in theory the maximum MSS over a PPPoE interface is 1452 bytes,
     1440 appears to be a safer bet.  Note that setting the MSS this way can
     have undesirable effects, such as interfering with the OS detection fea-
     tures of pf(4).

     Alternatively in cases where the remote equipment supports RFC 4638 and
     the physical interface is configured to support jumbo frames, the MTU of
     the pppoe interface can be raised and it will attempt to negotiate an
     increased MTU.  For example, in /etc/hostname.pppoe0:

           inet NONE mtu 1500 \
                   pppoedev em0 authproto pap \
                   authname 'testcaller' authkey 'donttell' up
           !/sbin/route add default -ifp pppoe0

     The physical interface must also be configured like so:

           # echo "up mtu 1508" > /etc/hostname.em0

     With this, the previously mentioned MSS clamping rules in pf.conf(5) are
     no longer necessary.

     See pf.conf(5) for more information on MTU, MSS, and NAT.

     sppp(4), hostname.if(5), pf.conf(5), ifconfig(8)

     L. Mamakos, K. Lidl, J. Evarts, D. Carrel, D. Simone, and R. Wheeler, A
     Method for Transmitting PPP Over Ethernet (PPPoE), RFC 2516, February

     P. Arberg, D. Kourkouzelis, M. Duckett, T. Anschutz, and J. Moisand,
     Accommodating a Maximum Transit Unit/Maximum Receive Unit (MTU/MRU)
     Greater Than 1492 in the Point-to-Point Protocol over Ethernet (PPPoE),
     RFC 4638, September 2006.

     The pppoe device first appeared in OpenBSD 3.7.

     RFC 4638 negotiation is only aware of the MTU configured on the end-
     points, but not the maximum MTU supported on the path between them.  If
     the path cannot pass the larger Ethernet frames, negotiation will succeed
     but the connection will not function correctly.

     This implementation is client side only.

     It is important to specify ``netmask'' to ifconfig(8).
     If the netmask is unspecified, it will be set to 8 when is con-
     figured to the interface, and it will persist after negotiation.

     The presence of a mygate(5) file will interfere with the routing table.
     Make sure this file is either empty or does not exist.

BSD                             March 24, 2017                             BSD