pppoe - user-space PPPoE client.
SYNOPSIS
pppd pty 'pppoe [pppoe_options]' [pppd_options]
pppoe -A [pppoe_options]
DESCRIPTION
pppoe is a user-space client for PPPoE (Point-to-Point
Protocol over Ethernet) for Linux and other UNIX systems.
pppoe works in concert with the pppd PPP daemon to provide
a PPP connection over Ethernet, as is used by many ADSL
service providers.
OPTIONS
-I interface
The -I option specifies the Ethernet interface to
use. Under Linux, it is typically eth0 or eth1.
The interface should be "up" before you start
pppoe, but should not be configured to have an IP
address.
-T timeout
The -T option causes pppoe to exit if no session
traffic is detected for timeout seconds. I recom
mend that you use this option as an extra safety
measure, but if you do, you should make sure that
PPP generates enough traffic so the timeout will
normally not be triggered. The best way to do this
is to use the lcp-echo-interval option to pppd.
You should set the PPPoE timeout to be about four
times the LCP echo interval.
-D file_name
The -D option causes every packet to be dumped to
the specified file_name. This is intended for
debugging only; it produces huge amounts of output
and greatly reduces performance.
-V The -V option causes pppoe to print its version
number and exit.
-A The -A option causes pppoe to send a PADI packet
and then print the names of access concentrators in
each PADO packet it receives. Do not use this
option in conjunction with pppd; the -A option is
meant to be used interactively to give interesting
information about the access concentrator.
Specifies the desired service name. pppoe will
only initiate sessions with access concentrators
which can provide the specified service. In most
cases, you should not specify this option. Use it
only if you know that there are multiple access
concentrators or know that you need a specific ser
vice name.
-C ac_name
Specifies the desired access concentrator name.
pppoe will only initiate sessions with the speci
fied access concentrator. In most cases, you
should not specify this option. Use it only if you
know that there are multiple access concentrators.
If both the -S and -C options are specified, they
must both match for pppoe to initiate a session.
-U Causes pppoe to use the Host-Uniq tag in its dis
covery packets. This lets you run multiple pppoe
daemons without having their discovery packets
interfere with one another. You must supply this
option to all pppoe daemons if you intend to run
multiple daemons simultaneously.
-s Causes pppoe to use synchronous PPP encapsulation.
If you use this option, then you must use the sync
option with pppd. You are encouraged to use this
option if it works, because it greatly reduces the
CPU overhead of pppoe. However, it MAY be unreli
able on slow machines -- there is a race condition
between pppd writing data and pppoe reading it.
For this reason, the default setting is asyn
chronous. If you encounter bugs or crashes with
Synchronous PPP, turn it off -- don't e-mail me for
support!
-m MSS Causes pppoe to clamp the TCP maximum segment size
at the specified value. Because of PPPoE overhead,
the maximum segment size for PPPoE is smaller than
for normal Ethernet encapsulation. This could
cause problems for machines on a LAN behind a gate
way using PPPoE. If you have a LAN behind a gate
way, and the gateway connects to the Internet using
PPPoE, you are strongly recommended to use a -m
1412 option. This avoids having to set the MTU on
all the hosts on the LAN.
Causes pppoe to write its process-ID to the speci
fied file. This can be used to locate and kill
pppoe processes.
-e sess:mac
Causes pppoe to skip the discovery phase and move
directly to the session phase. The session is
given by sess and the MAC address of the peer by
mac. This mode is not meant for normal use; it is
designed only for pppoe-server(8).
-n Causes pppoe not to open a discovery socket. This
mode is not meant for normal use; it is designed
only for pppoe-server(8).
-k Causes pppoe to terminate an existing session by
sending a PADT frame, and then exit. You must use
the -e option in conjunction with this option to
specify the session to kill. This may be useful
for killing sessions when a buggy peer does not
realize the session has ended.
-d Causes pppoe to perform discovery and then exit,
after printing session information to standard out
put. The session information is printed in exactly
the format expected by the -e option. This option
lets you initiate a PPPoE discovery, perform some
other work, and then start the actual PPP session.
Be careful; if you use this option in a loop, you
can create many sessions, which may annoy your
peer.
-f disc:sess
The -f option sets the Ethernet frame types for
PPPoE discovery and session frames. The types are
specified as hexadecimal numbers separated by a
colon. Standard PPPoE uses frame types 8863:8864.
You should not use this option unless you are abso
lutely sure the peer you are dealing with uses non-
standard frame types. If your ISP uses non-stan
dard frame types, complain!
-h The -h option causes pppoe to print usage informa
tion and exit.
PPPoE (Point-to-Point Protocol over Ethernet) is described
in RFC 2516 and is a protocol which allows the session
abstraction to be maintained over bridged Ethernet net
works.
PPPoE works by encapsulating PPP frames in Ethernet
frames. The protocol has two distinct stages: The dis
covery and the session stage.
In the discovery stage, the host broadcasts a special PADI
(PPPoE Active Discovery Initiation) frame to discover any
access concentrators. The access concentrators (typi
cally, only one access concentrator) reply with PADO
(PPPoE Active Discovery Offer) packets, announcing their
presence and the services they offer. The host picks one
of the access concentrators and transmits a PADR (PPPoE
Active Discovery Request) packet, asking for a session.
The access concentrator replies with a PADS (PPPoE Active
Discovery Session-Confirmation) packet. The protocol then
moves to the session stage.
In the session stage, the host and access concentrator
exchange PPP frames embedded in Ethernet frames. The nor
mal Ethernet MTU is 1500 bytes, but the PPPoE overhead
plus two bytes of overhead for the encapsulated PPP frame
mean that the MTU of the PPP interface is at most 1492
bytes. This causes all kinds of problems if you are using
a Linux machine as a firewall and interfaces behind the
firewall have an MTU greater than 1492. In fact, to be
safe, I recommend setting the MTU of machines behind the
firewall to 1412, to allow for worst-case TCP and IP
options in their respective headers.
Normally, PPP uses the Link Control Protocol (LCP) to shut
down a PPP link. However, the PPPoE specification allows
the link to be shut down with a special PADT (PPPoE Active
Discovery Terminate) packet. This client recognizes this
packet and will correctly terminate if a terminate request
is received for the PPP session.
DESIGN GOALS
My design goals for this PPPoE client were as follows, in
descending order of importance:
o It must work.
o It must be a user-space program and not a kernel
patch.
o It must be fully compliant with RFC 2516, the pro
posed PPPoE standard.
o It must never hang up forever -- if the connection
is broken, it must detect this and exit, allowing a
wrapper script to restart the connection.
o It must be fairly efficient.
I believe I have achieved all of these goals, but (of
course) am open to suggestions, patches and ideas. See my
home page, http://www.roaringpenguin.com, for contact
information.
NOTES
For best results, you must give pppd an mtu option of
1492. I have observed problems with excessively-large
frames unless I set this option. Also, if pppoe is run
ning on a firewall machine, all machines behind the fire
wall should have MTU's of 1412.
If you have problems, check your system logs. pppoe logs
interesting things to syslog. You may have to turn on
logging of debug-level messages for complete diagnosis.
AUTHORS
pppoe was written by David F. Skoll <dfs@roaringpen
guin.com>, with much inspiration from an earlier version
by Luke Stras.
The pppoe home page is http://www.roaringpen
guin.com/pppoe/.
SEE ALSO
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)
Man(1) output converted with
man2html