PPPOE(8)                OpenBSD System Manager's Manual               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 re-
             al 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.  Other-
             wise, 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 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 dis-
     abled, but not denied.  On the other hand, address and control field com-
     pression, 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 con-
     nection 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 de-
     tails.

     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 de-
             tect 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)

     L. Mamakos, et al., A Method for Transmitting PPP Over Ethernet (PPPoE),
     RFC 2516.

HISTORY
     This implementation of pppoe first appeared in OpenBSD 2.8.

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

OpenBSD 4.7                    November 17, 2007                             3
