


PPPOE(8)						 PPPOE(8)


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



			   3 July 2000				1





PPPOE(8)						 PPPOE(8)


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






			   3 July 2000				2





PPPOE(8)						 PPPOE(8)


       -p file
	      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.






			   3 July 2000				3





PPPOE(8)						 PPPOE(8)


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





			   3 July 2000				4





PPPOE(8)						 PPPOE(8)


       o      The code must be easy to read and maintain.


       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)











			   3 July 2000				5


