1PPPOE(8)                    System Manager's Manual                   PPPOE(8)
2
3
4

NAME

6       pppoe - user-space PPPoE client.
7

SYNOPSIS

9       pppd pty 'pppoe [pppoe_options]' [pppd_options]
10
11       pppoe -A [pppoe_options]
12

DESCRIPTION

14       pppoe  is  a  user-space client for PPPoE (Point-to-Point Protocol over
15       Ethernet) for Linux and other UNIX systems.   pppoe  works  in  concert
16       with  the pppd PPP daemon to provide a PPP connection over Ethernet, as
17       is used by many DSL service providers.
18
19

OPTIONS

21       -I interface
22              The -I option specifies the Ethernet interface  to  use.   Under
23              Linux,  it  is  typically eth0 or eth1.  The interface should be
24              "up" before you start pppoe, but should  not  be  configured  to
25              have an IP address.
26
27
28       -T timeout
29              The  -T  option  causes  pppoe  to exit if no session traffic is
30              detected for timeout seconds.  I recommend  that  you  use  this
31              option  as  an  extra  safety measure, but if you do, you should
32              make sure that PPP generates enough traffic so the timeout  will
33              normally  not  be  triggered.  The best way to do this is to use
34              the lcp-echo-interval option to pppd.  You should set the  PPPoE
35              timeout to be about four times the LCP echo interval.
36
37
38       -D file_name
39              The  -D option causes every packet to be dumped to the specified
40              file_name.  This is intended for  debugging  only;  it  produces
41              huge amounts of output and greatly reduces performance.
42
43
44       -V     The -V option causes pppoe to print its version number and exit.
45
46
47       -A     The  -A option causes pppoe to send a PADI packet and then print
48              the names  of  access  concentrators  in  each  PADO  packet  it
49              receives.   Do not use this option in conjunction with pppd; the
50              -A option is meant to be used interactively to give  interesting
51              information about the access concentrator.
52
53
54       -S service_name
55              Specifies  the  desired  service name.  pppoe will only initiate
56              sessions with access concentrators which can provide the  speci‐
57              fied  service.   In  most  cases,  you  should  not specify this
58              option.  Use it only if you know that there are multiple  access
59              concentrators or know that you need a specific service name.
60
61
62       -C ac_name
63              Specifies the desired access concentrator name.  pppoe will only
64              initiate sessions with the specified  access  concentrator.   In
65              most  cases, you should not specify this option.  Use it only if
66              you know that there are multiple access concentrators.  If  both
67              the  -S  and  -C options are specified, they must both match for
68              pppoe to initiate a session.
69
70
71       -U     Causes pppoe to use the Host-Uniq tag in its discovery  packets.
72              This  lets  you  run multiple pppoe daemons without having their
73              discovery packets interfere with one another.  You  must  supply
74              this  option  to all pppoe daemons if you intend to run multiple
75              daemons simultaneously.
76
77
78       -s     Causes pppoe to use synchronous PPP encapsulation.  If  you  use
79              this  option,  then you must use the sync option with pppd.  You
80              are encouraged to use  this  option  if  it  works,  because  it
81              greatly  reduces  the CPU overhead of pppoe.  However, it MAY be
82              unreliable on slow machines -- there is a race condition between
83              pppd  writing  data  and pppoe reading it.  For this reason, the
84              default setting is  asynchronous.   If  you  encounter  bugs  or
85              crashes with Synchronous PPP, turn it off -- don't e-mail me for
86              support!
87
88
89       -m MSS Causes pppoe to clamp the TCP maximum segment size at the speci‐
90              fied value.  Because of PPPoE overhead, the maximum segment size
91              for PPPoE is smaller than  for  normal  Ethernet  encapsulation.
92              This could cause problems for machines on a LAN behind a gateway
93              using PPPoE.  If you have a LAN behind a gateway, and the  gate‐
94              way  connects to the Internet using PPPoE, you are strongly rec‐
95              ommended to use a -m 1412 option.  This avoids having to set the
96              MTU on all the hosts on the LAN.
97
98
99       -p file
100              Causes  pppoe  to  write  its  process-ID to the specified file.
101              This can be used to locate and kill pppoe processes.
102
103
104       -e sess:mac
105              Causes pppoe to skip the discovery phase and  move  directly  to
106              the  session  phase.   The  session is given by sess and the MAC
107              address of the peer by mac.  This mode is not meant  for  normal
108              use; it is designed only for pppoe-server(8).
109
110
111       -n     Causes  pppoe  not to open a discovery socket.  This mode is not
112              meant for normal use; it is designed only for pppoe-server(8).
113
114
115       -k     Causes pppoe to terminate an existing session by sending a  PADT
116              frame, and then exit.  You must use the -e option in conjunction
117              with this option to specify the session to kill.   This  may  be
118              useful  for  killing sessions when a buggy peer does not realize
119              the session has ended.
120
121
122       -d     Causes pppoe to perform discovery and then exit, after  printing
123              session information to standard output.  The session information
124              is printed in exactly the format  expected  by  the  -e  option.
125              This  option  lets  you initiate a PPPoE discovery, perform some
126              other work, and then start the actual PPP session.  Be  careful;
127              if  you use this option in a loop, you can create many sessions,
128              which may annoy your peer.
129
130
131       -f disc:sess
132              The -f option sets the Ethernet frame types for PPPoE  discovery
133              and session frames.  The types are specified as hexadecimal num‐
134              bers separated by a colon.   Standard  PPPoE  uses  frame  types
135              8863:8864.   You should not use this option unless you are abso‐
136              lutely sure the peer you  are  dealing  with  uses  non-standard
137              frame  types.   If  your ISP uses non-standard frame types, com‐
138              plain!
139
140
141       -h     The -h option causes pppoe to print usage information and exit.
142
143

PPPOE BACKGROUND

145       PPPoE (Point-to-Point Protocol over Ethernet) is described in RFC  2516
146       and is a protocol which allows the session abstraction to be maintained
147       over bridged Ethernet networks.
148
149       PPPoE works by encapsulating PPP frames in Ethernet frames.  The proto‐
150       col has two distinct stages:  The discovery and the session stage.
151
152       In  the  discovery  stage,  the  host  broadcasts a special PADI (PPPoE
153       Active Discovery Initiation) frame to discover  any  access  concentra‐
154       tors.   The access concentrators (typically, only one access concentra‐
155       tor) reply with PADO (PPPoE Active Discovery Offer) packets, announcing
156       their  presence and the services they offer.  The host picks one of the
157       access concentrators and  transmits  a  PADR  (PPPoE  Active  Discovery
158       Request) packet, asking for a session.  The access concentrator replies
159       with a PADS (PPPoE Active Discovery Session-Confirmation) packet.   The
160       protocol then moves to the session stage.
161
162       In  the  session  stage,  the host and access concentrator exchange PPP
163       frames embedded in Ethernet frames.  The normal Ethernet  MTU  is  1500
164       bytes, but the PPPoE overhead plus two bytes of overhead for the encap‐
165       sulated PPP frame mean that the MTU of the PPP  interface  is  at  most
166       1492 bytes.  This causes all kinds of problems if you are using a Linux
167       machine as a firewall and interfaces behind the firewall  have  an  MTU
168       greater than 1492.  In fact, to be safe, I recommend setting the MTU of
169       machines behind the firewall to 1412, to allow for worst-case  TCP  and
170       IP options in their respective headers.
171
172       Normally,  PPP  uses the Link Control Protocol (LCP) to shut down a PPP
173       link.  However, the PPPoE specification allows the link to be shut down
174       with  a  special  PADT (PPPoE Active Discovery Terminate) packet.  This
175       client recognizes this packet and will correctly terminate if a  termi‐
176       nate request is received for the PPP session.
177
178

DESIGN GOALS

180       My  design  goals  for this PPPoE client were as follows, in descending
181       order of importance:
182
183
184       o      It must work.
185
186
187       o      It must be a user-space program and not a kernel patch.
188
189
190       o      The code must be easy to read and maintain.
191
192
193       o      It must be fully compliant with RFC  2516,  the  proposed  PPPoE
194              standard.
195
196
197       o      It must never hang up forever -- if the connection is broken, it
198              must detect this and exit, allowing a wrapper script to  restart
199              the connection.
200
201
202       o      It must be fairly efficient.
203
204
205       I  believe  I have achieved all of these goals, but (of course) am open
206       to suggestions, patches and ideas.  See my home page,  http://www.roar
207       ingpenguin.com, for contact information.
208
209

NOTES

211       For  best  results,  you  must give pppd an mtu option of 1492.  I have
212       observed problems with  excessively-large  frames  unless  I  set  this
213       option.   Also, if pppoe is running on a firewall machine, all machines
214       behind the firewall should have MTU's of 1412.
215
216       If you have problems, check your system logs.  pppoe  logs  interesting
217       things  to syslog.  You may have to turn on logging of debug-level mes‐
218       sages for complete diagnosis.
219
220

AUTHORS

222       pppoe was written by David F. Skoll <dfs@roaringpenguin.com>, with much
223       inspiration from an earlier version by Luke Stras.
224
225       The pppoe home page is http://www.roaringpenguin.com/pppoe/.
226
227

SEE ALSO

229       pppoe-start(8),      pppoe-stop(8),      pppoe-connect(8),     pppd(8),
230       pppoe.conf(5), pppoe-setup(8), pppoe-status(8), pppoe-sniff(8),  pppoe-
231       server(8), pppoe-relay(8)
232
233
234
235
2364th Berkeley Distribution         3 July 2000                         PPPOE(8)
Impressum