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

FreeBSD Manual Pages


home | help
PPPOE(4)	       FreeBSD Kernel Interfaces Manual		      PPPOE(4)

     pppoe -- PPP Over Ethernet	protocol network interface

     pseudo-device pppoe

     The pppoe interface encapsulates Point-to-Point Protocol (PPP) packets
     inside Ethernet frames as defined by RFC 2516.

     This is often used	to connect a router via	a DSL modem to an access con-
     centrator.	 The pppoe interface does not by itself	transmit or receive
     frames, but needs an Ethernet interface to	do so.	This Ethernet inter-
     face is connected to the pppoe interface via ifconfig(8).	The Ethernet
     interface needs to	be marked UP, but does not need	to have	an IP address.

     There are two basic modes of operation, controlled	via the	link1 switch.
     The default mode, link1 not being set, tries to keep the configured ses-
     sion open all the time.  If the session is	disconnected, a	new connection
     attempt is	started	immediately.  The "dial	on demand" mode, selected by
     setting link1, only establishes a connection when data is being sent to
     the interface.

     Before a pppoe interface is usable, it needs to be	configured.  The fol-
     lowing steps are necessary:

     +o	 Create	the interface.

     +o	 Connect an Ethernet interface.	 This interface	is used	for the	physi-
	 cal communication.  As	noted above it must be marked UP, but need not
	 have an IP address.

     +o	 Configure authentication.  The	PPP session needs to identify the
	 client	to the peer.  For more details on the available	options	see

     +o	 If using IPv6,	configure a link-local address.

     This all is typically accomplished	using an /etc/hostname.pppoe0 file.  A
     typical file looks	like this:

	   inet	NONE \
		   pppoedev em0	authproto pap \
		   authname 'testcaller' authkey 'donttell' up
	   inet6 eui64
	   !/sbin/route	add default -ifp pppoe0
	   !/sbin/route	add -inet6 default -ifp	pppoe0 fe80::%pppoe0

     The physical interface must also be marked	`up':

	   # echo "up" > /etc/hostname.em0

     Since this	is a PPP interface, the	addresses assigned to the interface
     may change	during PPP negotiation.	 In the	above example, and serve as placeholders for dynamic address configuration.

     If	the local address is set to wildcard address, it will be
     changed to	an address suggested by	the peer.

     If	the destination	address	is set to a wildcard address in	the range from to, it will be changed to an address suggested by the
     peer, and if a default route which	uses this interface exists the gateway
     will be changed to	the suggested address as well.

     Otherwise,	PPP negotiation	will only agree	to exactly the IPv4 addresses
     which are configured on the interface.

     pppoe does	not interfere with other PPPoE implementations running on the
     same machine.  However under some circumstances (such as after a crash or
     power failure) the	peer device might initially refuse to reestablish a
     new PPPoE connection because there	is already an open session.  This
     would be indicated	by the client sending a	high number of PADI packets
     before successfully connecting.  The pppoe	driver can be told to kill all
     unknown PPPoE sessions by sending a PADT packet to	explicitly terminate
     the old session.  Add the following to the	kernel config file:


     Problems can arise	on machines with private IPs connecting	to the Inter-
     net via a machine running both Network Address Translation	(NAT) and
     pppoe.  Standard Ethernet uses a maximum transmission unit	(MTU) of 1500
     bytes, whereas PPPoE mechanisms need a further 8 bytes of overhead.  This
     leaves a maximum MTU of 1492.  pppoe sets the MTU on its interface	to
     1492 as a matter of course.  However, machines connecting on a private
     LAN will still have their MTUs set	to 1500, causing conflict.  Using a
     packet filter, the	maximum	segment	size (MSS) can be set (clamped)	to the
     required value.  The following rule in pf.conf(5) would set the MSS to

	   match on pppoe0 scrub (max-mss 1440)

     Although in theory	the maximum MSS	over a PPPoE interface is 1452 bytes,
     1440 appears to be	a safer	bet.  Note that	setting	the MSS	this way can
     have undesirable effects, such as interfering with	the OS detection fea-
     tures of pf(4).

     Alternatively in cases where the remote equipment supports	RFC 4638 and
     the physical interface is configured to support jumbo frames, the MTU of
     the pppoe interface can be	raised and it will attempt to negotiate	an in-
     creased MTU.  For example,	in /etc/hostname.pppoe0:

	   inet	NONE mtu 1500 \
		   pppoedev em0	authproto pap \
		   authname 'testcaller' authkey 'donttell' up
	   !/sbin/route	add default -ifp pppoe0

     The physical interface must also be configured like so:

	   # echo "up mtu 1508"	> /etc/hostname.em0

     With this,	the previously mentioned MSS clamping rules in pf.conf(5) are
     no	longer necessary.

     If	the MTU	is set to a value larger than 1492 and the remote endpoint
     does not support RFC 4638,	pppoe will write "No valid PPP-Max-Payload tag
     received in PADO" to the kernel message buffer and	the MTU	will remain at
     the default value.	 However, RFC 4638 negotiation only takes into account
     the MTU configured	on the endpoints, not the maximum MTU supported	on the
     path between them.	 If the	path cannot pass the larger Ethernet frames,
     negotiation will succeed but the larger frames will be dropped.  For this
     reason it is important to test the	connection with	large packets when en-
     abling a higher MTU.

     See pf.conf(5) for	more information on MTU, MSS, and NAT.

     sppp(4), hostname.if(5), pf.conf(5), ifconfig(8)

     L.	Mamakos, K. Lidl, J. Evarts, D.	Carrel,	D. Simone, and R. Wheeler, A
     Method for	Transmitting PPP Over Ethernet (PPPoE),	RFC 2516, February

     P.	Arberg,	D. Kourkouzelis, M. Duckett, T.	Anschutz, and J. Moisand,
     Accommodating a Maximum Transit Unit/Maximum Receive Unit (MTU/MRU)
     Greater Than 1492 in the Point-to-Point Protocol over Ethernet (PPPoE),
     RFC 4638, September 2006.

     The pppoe device first appeared in	OpenBSD	3.7.

     This implementation is client side	only.

     It	is important to	specify	"netmask" to ifconfig(8).  If
     the netmask is unspecified, it will be set	to 8 when is config-
     ured to the interface, and	it will	persist	after negotiation.

     The presence of a mygate(5) file will interfere with the routing table.
     Make sure this file is either empty or does not exist.

     Two pppoe interfaces configured with the same wildcard destination	ad-
     dress cannot share	a routing table.

FreeBSD	13.0			March 16, 2021			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help