.\" $Id: pppoe.8,v 1.6 2005/08/09 02:49:16 dfs Exp $ .\" LIC: GPL.TH PPPOE 8 "3 July 2000".UC 4.SH NAMEpppoe \- user-space PPPoE client..SH SYNOPSIS.B pppd pty 'pppoe \fR[\fIpppoe_options\fR]\fB' \fR[\fIpppd_options\fR].P.B pppoe -A \fR[\fIpppoe_options\fR].SH DESCRIPTION\fBpppoe\fR is a user-space client for PPPoE (Point-to-Point Protocolover Ethernet) for Linux and other UNIX systems.  \fBpppoe\fR works inconcert with the \fBpppd\fR PPP daemon to provide a PPP connectionover Ethernet, as is used by many DSL service providers..SH OPTIONS.TP.B \-I \fIinterface\fRThe \fB\-I\fR option specifies the Ethernet interface to use.  Under Linux,it is typically \fIeth0\fR or \fIeth1\fR.  The interface should be "up"before you start \fBpppoe\fR, but should \fInot\fR be configured to havean IP address..TP.B \-T \fItimeout\fRThe \fB\-T\fR option causes \fBpppoe\fR to exit if no session trafficis detected for \fItimeout\fR seconds.  I recommend that you use thisoption as an extra safety measure, but if you do, you should make surethat PPP generates enough traffic so the timeout will normally not betriggered.  The best way to do this is to use the\fIlcp-echo-interval\fR option to \fBpppd\fR.  You should set thePPPoE timeout to be about four times the LCP echo interval..TP.B \-D \fIfile_name\fRThe \fB\-D\fR option causes every packet to be dumped to the specified\fIfile_name\fR.  This is intended for debugging only; it produces hugeamounts of output and greatly reduces performance..TP.B \-VThe \fB\-V\fR option causes \fBpppoe\fR to print its version number andexit..TP.B \-AThe \fB\-A\fR option causes \fBpppoe\fR to send a PADI packet and then printthe names of access concentrators in each PADO packet it receives.  Do notuse this option in conjunction with \fBpppd\fR; the \fB\-A\fR option ismeant to be used interactively to give interesting information about theaccess concentrator..TP.B \-S \fIservice_name\fRSpecifies the desired service name.  \fBpppoe\fR will only initiate sessionswith access concentrators which can provide the specified service.  Inmost cases, you should \fInot\fR specify this option.  Use it only if youknow that there are multiple access concentrators or know that you need aspecific service name..TP.B \-C \fIac_name\fRSpecifies the desired access concentrator name.  \fBpppoe\fR will onlyinitiate sessions with the specified access concentrator.  Inmost cases, you should \fInot\fR specify this option.  Use it only if youknow that there are multiple access concentrators.  If both the\fB\-S\fR and \fB\-C\fR options are specified, they must \fIboth\fR matchfor \fBpppoe\fR to initiate a session..TP.B \-UCauses \fBpppoe\fR to use the Host-Uniq tag in its discovery packets.  Thislets you run multiple \fBpppoe\fR daemons without having their discoverypackets interfere with one another.  You must supply this option to\fIall\fR \fBpppoe\fR daemons if you intend to run multiple daemonssimultaneously..TP.B \-sCauses \fBpppoe\fR to use \fIsynchronous\fR PPP encapsulation.  If youuse this option, then you \fImust\fR use the \fBsync\fR option with\fBpppd\fR.  You are encouraged to use this option if it works, becauseit greatly reduces the CPU overhead of \fBpppoe\fR.  However, itMAY be unreliable on slow machines -- there is a race condition betweenpppd writing data and pppoe reading it.  For this reason, the defaultsetting is asynchronous.  If you encounter bugs or crashes with SynchronousPPP, turn it off -- don't e-mail me for support!.TP.B \-m \fIMSS\fRCauses \fBpppoe\fR to \fIclamp\fR the TCP maximum segment size at the specifiedvalue.  Because of PPPoE overhead, the maximum segment size for PPPoE issmaller than for normal Ethernet encapsulation.  This could cause problemsfor machines on a LAN behind a gateway using PPPoE.  If you have a LANbehind a gateway, and the gateway connects to the Internet using PPPoE,you are strongly recommended to use a \fB\-m 1412\fR option.  This avoidshaving to set the MTU on all the hosts on the LAN..TP.B \-p \fIfile\fRCauses \fBpppoe\fR to write its process-ID to the specified file.  Thiscan be used to locate and kill \fBpppoe\fR processes..TP.B \-e \fIsess:mac\fRCauses \fBpppoe\fR to skip the discovery phase and move directly to thesession phase.  The session is given by \fIsess\fR and the MAC address ofthe peer by \fImac\fR.  This mode is \fInot\fR meant for normal use; itis designed only for \fBpppoe-server\fR(8)..TP.B \-nCauses \fBpppoe\fR not to open a discovery socket.  This mode is\fInot\fR meant for normal use; it is designed only for\fBpppoe-server\fR(8)..TP.B \-kCauses \fBpppoe\fR to terminate an existing session by sending a PADT frame,and then exit.  You must use the \fB\-e\fR option in conjunction with thisoption to specify the session to kill.  This may be useful for killingsessions when a buggy peer does not realize the session has ended..TP.B \-dCauses \fBpppoe\fR to perform discovery and then exit, after printingsession information to standard output.  The session information is printedin exactly the format expected by the \fB\-e\fR option.  This option letsyou initiate a PPPoE discovery, perform some other work, and then startthe actual PPP session.  \fIBe careful\fR; if you use this option in a loop,you can create many sessions, which may annoy your peer..TP.B \-f disc:sessThe \fB\-f\fR option sets the Ethernet frame types for PPPoE discoveryand session frames.  The types are specified as hexadecimal numbersseparated by a colon.  Standard PPPoE uses frame types 8863:8864.\fIYou should not use this option\fR unless you are absolutely surethe peer you are dealing with uses non-standard frame types.  If yourISP uses non-standard frame types, complain!.TP.B \-hThe \fB\-h\fR option causes \fBpppoe\fR to print usage information andexit..SH PPPOE BACKGROUNDPPPoE (Point-to-Point Protocol over Ethernet) is described in RFC 2516and is a protocol which allows the session abstraction to be maintainedover bridged Ethernet networks.PPPoE works by encapsulating PPP frames in Ethernet frames.  The protocolhas two distinct stages:  The \fIdiscovery\fR and the \fIsession\fR stage.In the discovery stage, the host broadcasts a special PADI (PPPoEActive Discovery Initiation) frame to discover any \fIaccessconcentrators\fR.  The access concentrators (typically, only oneaccess concentrator) reply with PADO (PPPoE Active Discovery Offer)packets, announcing their presence and the services they offer.  Thehost picks one of the access concentrators and transmits a PADR (PPPoEActive Discovery Request) packet, asking for a session.  The accessconcentrator replies with a PADS (PPPoE Active DiscoverySession-Confirmation) packet.  The protocol then moves to the session stage.In the session stage, the host and access concentrator exchange PPP framesembedded in Ethernet frames.  The normal Ethernet MTU is 1500 bytes, butthe PPPoE overhead plus two bytes of overhead for the encapsulated PPPframe mean that the MTU of the PPP interface is at most 1492 bytes.This causes \fIall kinds of problems\fR if you are using a Linux machineas a firewall and interfaces behind the firewall have an MTU greater than1492.  In fact, to be safe, I recommend setting the MTU of machinesbehind the firewall to 1412, to allow for worst-case TCP and IP optionsin their respective headers.Normally, PPP uses the Link Control Protocol (LCP) to shut down a PPPlink.  However, the PPPoE specification allows the link to be shut downwith a special PADT (PPPoE Active Discovery Terminate) packet.  This clientrecognizes this packet and will correctly terminate if a terminate requestis received for the PPP session..SH DESIGN GOALSMy design goals for this PPPoE client were as follows, in descending orderof importance:.TP.B oIt must work..TP.B oIt must be a user-space program and not a kernel patch..TP.B oThe code must be easy to read and maintain..TP.B oIt must be fully compliant with RFC 2516, the proposed PPPoE standard..TP.B oIt must never hang up forever -- if the connection is broken, it mustdetect this and exit, allowing a wrapper script to restart the connection..TP.B oIt must be fairly efficient..PI believe I have achieved all of these goals, but (of course) am opento suggestions, patches and ideas.  See my home page,http://www.roaringpenguin.com, for contact information..SH NOTESFor best results, you must give \fBpppd\fR an mtu option of1492.  I have observed problems with excessively-large framesunless I set this option.  Also, if \fBpppoe\fR is running on a firewallmachine, all machines behind the firewall should have MTU's of 1412.If you have problems, check your system logs.  \fBpppoe\fR logs interestingthings to syslog.  You may have to turn on logging of \fIdebug\fR-levelmessages for complete diagnosis..SH AUTHORS\fBpppoe\fR was written by David F. Skoll <dfs@roaringpenguin.com>,with much inspiration from an earlier version by Luke Stras.The \fBpppoe\fR home page is \fIhttp://www.roaringpenguin.com/pppoe/\fR..SH SEE ALSOpppoe-start(8), pppoe-stop(8), pppoe-connect(8), pppd(8), pppoe.conf(5), pppoe-setup(8), pppoe-status(8), pppoe-sniff(8), pppoe-server(8), pppoe-relay(8)