Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PPPOE(8)		    System Manager's Manual		      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 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 de-
	      tected for timeout seconds.  I recommend that you	use  this  op-
	      tion  as an extra	safety measure,	but if you do, you should make
	      sure that	PPP generates enough traffic so	the timeout will  nor-
	      mally  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  re-
	      ceives.  Do not use this option in conjunction with pppd;	the -A
	      option is	meant to be used interactively to give interesting in-
	      formation	about the access concentrator.

       -S service_name
	      Specifies	 the  desired  service name.  pppoe will only initiate
	      sessions with access concentrators which can provide the	speci-
	      fied  service.   In  most	cases, you should not specify this op-
	      tion.  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.  The specific Host-Uniq  value  used  is
	      the hexadecimal representation of	the pppoe process's PID.

       -W value
	      Causes  pppoe to use the Host-Uniq tag in	its discovery packets,
	      and furthermore to set the value of  Host-Uniq  to  value.   Use
	      with caution.  Note that -W and -U are mutually-incompatible.

       -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	speci-
	      fied 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 gate-
	      way connects to the Internet using PPPoE,	you are	strongly  rec-
	      ommended to use a	-m 1412	option.	 This avoids having to set the
	      MTU on all the hosts on the LAN.

       -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 ad-
	      dress  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 num-
	      bers  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-standard  frame  types,  com-
	      plain!

       -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	proto-
       col has two distinct stages:  The discovery and the session stage.

       In the discovery	stage, the host	broadcasts a special PADI  (PPPoE  Ac-
       tive  Discovery Initiation) frame to discover any access	concentrators.
       The access concentrators	(typically, only one access concentrator)  re-
       ply  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	proto-
       col 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	encap-
       sulated	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	termi-
       nate 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.roar-
       ingpenguin.com, for contact information.

NOTES
       For best	results, you must give pppd an mtu option of 1492.  I have ob-
       served 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  mes-
       sages for complete diagnosis.

AUTHORS
       pppoe  was  written by Dianne 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
       pppoe-start(8),	 pppoe-stop(8),	  pppoe-connect(8),    pppd(8),	   pp-
       poe.conf(5),  pppoe-setup(8),  pppoe-status(8),	pppoe-sniff(8),	pppoe-
       server(8), pppoe-relay(8)

4th Berkeley Distribution	5 October 2015			      PPPOE(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PPPOE BACKGROUND | DESIGN GOALS | NOTES | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pppoe&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help