Man Linux: Main Page and Category List

NAME

       pppoe - user-space PPPoE client.

SYNOPSIS

       pppd ptypppoe [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 DSL 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 recommend  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.

       -S service_name
              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 service name.

       -C ac_name
              Specifies the desired access concentrator name.  pppoe will only
              initiate  sessions  with  the specified 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 discovery 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
              unreliable on slow machines -- there is a race condition between
              pppd writing data and pppoe reading it.  For  this  reason,  the
              default  setting  is  asynchronous.   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  gateway  using  PPPoE.   If  you  have a LAN behind a
              gateway, 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.

       -H MAC Causes pppoe to use the indicated Ethernet MAC  address  as  the
              source  address  for  sending packets.  MAC must be specified in
              the AA:BB:CC:DD:EE:FF syntax.   If  this  option  is  specified,
              pppoe puts the interface into promiscuous mode.

       -p file
              Causes  pppoe  to  write  its  process-ID to the specified 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 output.  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
              absolutely sure the peer you are dealing with uses  non-standard
              frame  types.   If  your  ISP  uses  non-standard  frame  types,
              complain!

       -h     The -h option causes pppoe to print usage information and  exit.

PPPOE BACKGROUND

       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 networks.

       PPPoE  works  by  encapsulating  PPP  frames  in  Ethernet frames.  The
       protocol has two distinct stages:  The discovery 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 (typically, 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 normal 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      The code must be easy to read and maintain.

       o      It must be fully compliant with RFC  2516,  the  proposed  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 running on a firewall machine, all machines
       behind the firewall 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@roaringpenguin.com>, with much
       inspiration from an earlier version by Luke Stras.

       The pppoe home page is http://www.roaringpenguin.com/pppoe/.

SEE ALSO

       pppd(8),      pppoe-sniff(8),      pppoe-server(8),     pppoe-relay(8),
       /usr/share/doc/pppoe/README.Debian.gz