manual/rp-pppoe/original/man8/pppoe.8

   1 .\" $Id: pppoe.8,v 1.4 2002/04/09 17:28:38 dfs Exp $
   2 .\" LIC: GPL
   3 .TH PPPOE 8 "3 July 2000"
   4 .UC 4
   5 .SH NAME
   6 pppoe \- user-space PPPoE client.
   7 .SH SYNOPSIS
   8 .B pppd pty 'pppoe \fR[\fIpppoe_options\fR]\fB' \fR[\fIpppd_options\fR]
   9 .P
  10 .B pppoe -A \fR[\fIpppoe_options\fR]
  11 .SH DESCRIPTION
  12 \fBpppoe\fR is a user-space client for PPPoE (Point-to-Point Protocol
  13 over Ethernet) for Linux and other UNIX systems.  \fBpppoe\fR works in
  14 concert with the \fBpppd\fR PPP daemon to provide a PPP connection
  15 over Ethernet, as is used by many ADSL service providers.
  16
  17 .SH OPTIONS
  18 .TP
  19 .B \-I \fIinterface\fR
  20 The \fB\-I\fR option specifies the Ethernet interface to use.  Under Linux,
  21 it is typically \fIeth0\fR or \fIeth1\fR.  The interface should be "up"
  22 before you start \fBpppoe\fR, but should \fInot\fR be configured to have
  23 an IP address.
  24
  25 .TP
  26 .B \-T \fItimeout\fR
  27 The \fB\-T\fR option causes \fBpppoe\fR to exit if no session traffic
  28 is detected for \fItimeout\fR seconds.  I recommend that you use this
  29 option as an extra safety measure, but if you do, you should make sure
  30 that PPP generates enough traffic so the timeout will normally not be
  31 triggered.  The best way to do this is to use the
  32 \fIlcp-echo-interval\fR option to \fBpppd\fR.  You should set the
  33 PPPoE timeout to be about four times the LCP echo interval.
  34
  35 .TP
  36 .B \-D \fIfile_name\fR
  37 The \fB\-D\fR option causes every packet to be dumped to the specified
  38 \fIfile_name\fR.  This is intended for debugging only; it produces huge
  39 amounts of output and greatly reduces performance.
  40
  41 .TP
  42 .B \-V
  43 The \fB\-V\fR option causes \fBpppoe\fR to print its version number and
  44 exit.
  45
  46 .TP
  47 .B \-A
  48 The \fB\-A\fR option causes \fBpppoe\fR to send a PADI packet and then print
  49 the names of access concentrators in each PADO packet it receives.  Do not
  50 use this option in conjunction with \fBpppd\fR; the \fB\-A\fR option is
  51 meant to be used interactively to give interesting information about the
  52 access concentrator.
  53
  54 .TP
  55 .B \-S \fIservice_name\fR
  56 Specifies the desired service name.  \fBpppoe\fR will only initiate sessions
  57 with access concentrators which can provide the specified service.  In
  58 most cases, you should \fInot\fR specify this option.  Use it only if you
  59 know that there are multiple access concentrators or know that you need a
  60 specific service name.
  61
  62 .TP
  63 .B \-C \fIac_name\fR
  64 Specifies the desired access concentrator name.  \fBpppoe\fR will only
  65 initiate sessions with the specified access concentrator.  In
  66 most cases, you should \fInot\fR specify this option.  Use it only if you
  67 know that there are multiple access concentrators.  If both the
  68 \fB\-S\fR and \fB\-C\fR options are specified, they must \fIboth\fR match
  69 for \fBpppoe\fR to initiate a session.
  70
  71 .TP
  72 .B \-U
  73 Causes \fBpppoe\fR to use the Host-Uniq tag in its discovery packets.  This
  74 lets you run multiple \fBpppoe\fR daemons without having their discovery
  75 packets interfere with one another.  You must supply this option to
  76 \fIall\fR \fBpppoe\fR daemons if you intend to run multiple daemons
  77 simultaneously.
  78
  79 .TP
  80 .B \-s
  81 Causes \fBpppoe\fR to use \fIsynchronous\fR PPP encapsulation.  If you
  82 use this option, then you \fImust\fR use the \fBsync\fR option with
  83 \fBpppd\fR.  You are encouraged to use this option if it works, because
  84 it greatly reduces the CPU overhead of \fBpppoe\fR.  However, it
  85 MAY be unreliable on slow machines -- there is a race condition between
  86 pppd writing data and pppoe reading it.  For this reason, the default
  87 setting is asynchronous.  If you encounter bugs or crashes with Synchronous
  88 PPP, turn it off -- don't e-mail me for support!
  89
  90 .TP
  91 .B \-m \fIMSS\fR
  92 Causes \fBpppoe\fR to \fIclamp\fR the TCP maximum segment size at the specified
  93 value.  Because of PPPoE overhead, the maximum segment size for PPPoE is
  94 smaller than for normal Ethernet encapsulation.  This could cause problems
  95 for machines on a LAN behind a gateway using PPPoE.  If you have a LAN
  96 behind a gateway, and the gateway connects to the Internet using PPPoE,
  97 you are strongly recommended to use a \fB\-m 1412\fR option.  This avoids
  98 having to set the MTU on all the hosts on the LAN.
  99
 100 .TP
 101 .B \-p \fIfile\fR
 102 Causes \fBpppoe\fR to write its process-ID to the specified file.  This
 103 can be used to locate and kill \fBpppoe\fR processes.
 104
 105 .TP
 106 .B \-e \fIsess:mac\fR
 107 Causes \fBpppoe\fR to skip the discovery phase and move directly to the
 108 session phase.  The session is given by \fIsess\fR and the MAC address of
 109 the peer by \fImac\fR.  This mode is \fInot\fR meant for normal use; it
 110 is designed only for \fBpppoe-server\fR(8).
 111
 112 .TP
 113 .B \-n
 114 Causes \fBpppoe\fR not to open a discovery socket.  This mode is
 115 \fInot\fR meant for normal use; it is designed only for
 116 \fBpppoe-server\fR(8).
 117
 118 .TP
 119 .B \-k
 120 Causes \fBpppoe\fR to terminate an existing session by sending a PADT frame,
 121 and then exit.  You must use the \fB\-e\fR option in conjunction with this
 122 option to specify the session to kill.  This may be useful for killing
 123 sessions when a buggy peer does not realize the session has ended.
 124
 125 .TP
 126 .B \-d
 127 Causes \fBpppoe\fR to perform discovery and then exit, after printing
 128 session information to standard output.  The session information is printed
 129 in exactly the format expected by the \fB\-e\fR option.  This option lets
 130 you initiate a PPPoE discovery, perform some other work, and then start
 131 the actual PPP session.  \fIBe careful\fR; if you use this option in a loop,
 132 you can create many sessions, which may annoy your peer.
 133
 134 .TP
 135 .B \-f disc:sess
 136 The \fB\-f\fR option sets the Ethernet frame types for PPPoE discovery
 137 and session frames.  The types are specified as hexadecimal numbers
 138 separated by a colon.  Standard PPPoE uses frame types 8863:8864.
 139 \fIYou should not use this option\fR unless you are absolutely sure
 140 the peer you are dealing with uses non-standard frame types.  If your
 141 ISP uses non-standard frame types, complain!
 142
 143 .TP
 144 .B \-h
 145 The \fB\-h\fR option causes \fBpppoe\fR to print usage information and
 146 exit.
 147
 148 .SH PPPOE BACKGROUND
 149
 150 PPPoE (Point-to-Point Protocol over Ethernet) is described in RFC 2516
 151 and is a protocol which allows the session abstraction to be maintained
 152 over bridged Ethernet networks.
 153
 154 PPPoE works by encapsulating PPP frames in Ethernet frames.  The protocol
 155 has two distinct stages:  The \fIdiscovery\fR and the \fIsession\fR stage.
 156
 157 In the discovery stage, the host broadcasts a special PADI (PPPoE
 158 Active Discovery Initiation) frame to discover any \fIaccess
 159 concentrators\fR.  The access concentrators (typically, only one
 160 access concentrator) reply with PADO (PPPoE Active Discovery Offer)
 161 packets, announcing their presence and the services they offer.  The
 162 host picks one of the access concentrators and transmits a PADR (PPPoE
 163 Active Discovery Request) packet, asking for a session.  The access
 164 concentrator replies with a PADS (PPPoE Active Discovery
 165 Session-Confirmation) packet.  The protocol then moves to the session stage.
 166
 167 In the session stage, the host and access concentrator exchange PPP frames
 168 embedded in Ethernet frames.  The normal Ethernet MTU is 1500 bytes, but
 169 the PPPoE overhead plus two bytes of overhead for the encapsulated PPP
 170 frame mean that the MTU of the PPP interface is at most 1492 bytes.
 171 This causes \fIall kinds of problems\fR if you are using a Linux machine
 172 as a firewall and interfaces behind the firewall have an MTU greater than
 173 1492.  In fact, to be safe, I recommend setting the MTU of machines
 174 behind the firewall to 1412, to allow for worst-case TCP and IP options
 175 in their respective headers.
 176
 177 Normally, PPP uses the Link Control Protocol (LCP) to shut down a PPP
 178 link.  However, the PPPoE specification allows the link to be shut down
 179 with a special PADT (PPPoE Active Discovery Terminate) packet.  This client
 180 recognizes this packet and will correctly terminate if a terminate request
 181 is received for the PPP session.
 182
 183 .SH DESIGN GOALS
 184
 185 My design goals for this PPPoE client were as follows, in descending order
 186 of importance:
 187
 188 .TP
 189 .B o
 190 It must work.
 191
 192 .TP
 193 .B o
 194 It must be a user-space program and not a kernel patch.
 195
 196 .TP
 197 .B o
 198 The code must be easy to read and maintain.
 199
 200 .TP
 201 .B o
 202 It must be fully compliant with RFC 2516, the proposed PPPoE standard.
 203
 204 .TP
 205 .B o
 206 It must never hang up forever -- if the connection is broken, it must
 207 detect this and exit, allowing a wrapper script to restart the connection.
 208
 209 .TP
 210 .B o
 211 It must be fairly efficient.
 212
 213 .P
 214 I believe I have achieved all of these goals, but (of course) am open
 215 to suggestions, patches and ideas.  See my home page,
 216 http://www.roaringpenguin.com, for contact information.
 217
 218 .SH NOTES
 219
 220 For best results, you must give \fBpppd\fR an mtu option of
 221 1492.  I have observed problems with excessively-large frames
 222 unless I set this option.  Also, if \fBpppoe\fR is running on a firewall
 223 machine, all machines behind the firewall should have MTU's of 1412.
 224
 225 If you have problems, check your system logs.  \fBpppoe\fR logs interesting
 226 things to syslog.  You may have to turn on logging of \fIdebug\fR-level
 227 messages for complete diagnosis.
 228
 229 .SH AUTHORS
 230 \fBpppoe\fR was written by David F. Skoll <dfs@roaringpenguin.com>,
 231 with much inspiration from an earlier version by Luke Stras.
 232
 233 The \fBpppoe\fR home page is \fIhttp://www.roaringpenguin.com/pppoe/\fR.
 234
 235 .SH SEE ALSO
 236 adsl-start(8), adsl-stop(8), adsl-connect(8), pppd(8), pppoe.conf(5), adsl-setup(8), adsl-status(8), pppoe-sniff(8), pppoe-server(8), pppoe-relay(8)
 237