PPPOE(8)

NAME
pppoe - PPP Over Ethernet translator

SYNOPSIS
pppoe [-sv] [-i interface] [-n service] [-p system]

DESCRIPTION
The pppoe program can, with the help of ppp(8), act as a server or client for running PPP Over Ethernet.

The options are as follows:

-i interface
    Specify the interface that pppoe is to use, which should be a real Ethernet interface (not a virtual device like tun(4)). If this option is not specified, pppoe will use the first Ethernet interface that is up and running.

-n service
    Use service as the service name when negotiating with the server. By default, the client will ask for any service, and expect the server to respond with the same.

-p system
    This argument is passed, uninterpreted, to ppp(8). It can be used to specify the configuration data to be used for PPP Over Ethernet connections. This option is only used in server mode.

-s  If this option is specified, pppoe will run as a server. Otherwise, pppoe runs as a client.

-v  For each use of the flag, the verbosity of pppoe increases.

CLIENT SETUP
Configuring the client involves setting up the configuration file for ppp(8). The following statements must be included in the file for the specified system (or ``default'' if no system is specified):

    set device "!/usr/sbin/pppoe"
    set mtu max 1492
    set mru max 1492
    set speed sync
    disable acfcomp protocomp
    deny acfcomp

The set device line tells ppp to use the pppoe program for input and output instead of using a serial port or other network connection. The mtu and mru must be set to 1492 to leave room in the outgoing Ethernet packet for the pppoe headers. The set speed sync line tells ppp to use synchronous encoding for the packets sent between it and pppoe. According to RFC 2516, protocol compression, protocomp, is not recommended, so it is disabled, but not denied. On the other hand, address and control field compression, acfcomp, must be disabled and denied.

Additionally, the authentication mechanism for the connection must be specified as well as any other parameters.

EXAMPLE CONFIGURATION
Given a machine with one Ethernet interface, xl0, the first thing that must be done is to bring the interface up:

    # ifconfig xl0 up

This can be done automatically during boot with a /etc/hostname.xl0 file, see hostname.if(5) for details.

Next, a /etc/ppp/ppp.conf file must be created. Below is a minimal PPPoE style configuration, see ppp(8) for more options.

    default:
       set log Phase Chat LCP IPCP CCP tun command
    pppoe:
       set device "!/usr/sbin/pppoe -i xl0"
       set mtu max 1492
       set mru max 1492
       set speed sync
       disable acfcomp protocomp
       deny acfcomp
       set authname "myUsername"
       set authkey "myPassword"

The default section sets up some helpful information to log while getting started, and the pppoe section sets the required fields for a PPPoE connection as well as the username and password to use to authenticate to the service provider.

Once the /etc/ppp/ppp.conf file is set up, it is just a matter of setting ppp(8) into action:

    # ppp pppoe
    Working in interactive mode
    Using interface: tun0
    ppp ON deepthought> dial
    Ppp ON deepthought>
    PPp ON deepthought>
    PPP ON deepthought>

The userland ppp(8) daemon has many options for configuration, like adding default routes, network address translation, automatically using remote DNS servers, automatic dialing, etc. Please see ppp(8) for details.

Several ppp(8) options are particularly helpful when used with pppoe.

enable lqr / accept lqr
    Enable and accept link quality requests, which can be used to detect whether the link has gone down.

enable mssfixup
    Allow ppp(8) to adjust the maximum segment size on outgoing SYN packets.

SEE ALSO
pppoe(4), tun(4), hostname.if(5), ifconfig(8), ppp(8)

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

HISTORY
This implementation of pppoe first appeared in OpenBSD 2.8.

AUTHORS
-nosplit The pppoe program was written by Jason L. Wright <jason@thought.net> of Network Security Technologies, Inc. <http://www.netsec.net>.

BUGS
This software runs completely in user mode. As such it will have much more overhead than a kernel implementation.

The service is not currently used by the server code.