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

PPPOE BACKGROUND

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

DESIGN GOALS

197       My design goals for this PPPoE client were as  follows,  in  descending
198       order of importance:
199
200
201       o      It must work.
202
203
204       o      It must be a user-space program and not a kernel patch.
205
206
207       o      The code must be easy to read and maintain.
208
209
210       o      It  must  be  fully  compliant with RFC 2516, the proposed PPPoE
211              standard.
212
213
214       o      It must never hang up forever -- if the connection is broken, it
215              must  detect this and exit, allowing a wrapper script to restart
216              the connection.
217
218
219       o      It must be fairly efficient.
220
221
222       I believe I have achieved all of these goals, but (of course)  am  open
223       to  suggestions, patches and ideas.  See my home page, http://www.roar
224       ingpenguin.com, for contact information.
225
226

NOTES

228       For best results, you must give pppd an mtu option  of  1492.   I  have
229       observed  problems  with  excessively-large  frames  unless  I set this
230       option.  Also, if pppoe is running on a firewall machine, all  machines
231       behind the firewall should have MTU's of 1412.
232
233       If  you  have problems, check your system logs.  pppoe logs interesting
234       things to syslog.  You may have to turn on logging of debug-level  mes‐
235       sages for complete diagnosis.
236
237

AUTHORS

239       pppoe  was  written by Dianne Skoll <dfs@roaringpenguin.com>, with much
240       inspiration from an earlier version by Luke Stras.
241
242       The pppoe home page is http://www.roaringpenguin.com/pppoe/.
243
244

SEE ALSO

246       pppoe-start(8),     pppoe-stop(8),      pppoe-connect(8),      pppd(8),
247       pppoe.conf(5),  pppoe-setup(8), pppoe-status(8), pppoe-sniff(8), pppoe-
248       server(8), pppoe-relay(8)
249
250
251
252
2534th Berkeley Distribution       5 October 2015                        PPPOE(8)
Impressum