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