.\"	$NetBSD: pppoe.4,v 1.39 2017/07/03 21:30:58 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Martin Husemann <martin@NetBSD.org>.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 7, 2016
.Dt PPPOE 4
.Os
.Sh NAME
.Nm pppoe
.Nd PPP over Ethernet protocol network interface
.Sh SYNOPSIS
.Cd pseudo-device pppoe
.Sh DESCRIPTION
The
.Nm
interface encapsulates
.Em Point-to-Point Protocol (PPP)
packets inside Ethernet frames as defined by
.Li RFC2516 .
.Pp
This is often used to connect a router via a DSL modem to
an access concentrator.
The
.Nm
interface does not by itself transmit or receive frames,
but needs an Ethernet interface to do so.
This Ethernet interface is connected to the
.Nm
interface via
.Xr pppoectl 8 .
The Ethernet interface needs to be marked UP, but does not need to have an
IP address.
.Pp
There are two basic modes of operation, controlled via the
.Em link1
switch.
The default mode,
.Em link1
not being set, tries to keep the configured session open all the
time.
If the session is disconnected, a new connection attempt is started
immediately.
The
.Dq dial on demand
mode, selected by setting
.Em link1 ,
only establishes a connection when data is being sent to the interface.
.Pp
If the kernel is compiled with options
.Dv PPPOE_SERVER ,
there are two modes of connection, controlled via the
.Em link0
switch.
The default mode,
.Em link0
not being set, is client mode.
The
.Dq PPPoE server
mode, selected by setting
.Em link0 ,
is to wait for incoming PPPoE session.
.Pp
Before a
.Nm
interface is usable, it needs to be configured.
The following steps are necessary:
.Bl -bullet
.It
Create the interface.
.It
Connect an Ethernet interface.
This interface is used for the physical communication.
As noted above it must be marked UP, but need not have an IP address.
.It
Configure authentication.
The PPP session needs to identify the client to the peer.
For more details on the available options see
.Xr pppoectl 8 .
.El
.Pp
This all is typically accomplished using an
.Pa /etc/ifconfig.pppoe0
file.
.Ss MSS/MTU problems
If you are using a
.Nm
interface, you will have an unusually low MTU for today's Internet.
Combined with a lot of misconfigured sites (host using path MTU discovery
behind a router blocking all ICMP traffic) this will often cause problems.
Connections to these servers will only work if your system advertises the
right MSS in the TCP three way handshake.
To get the right MSS, you need to set
.Bd -literal -offset indent
# Obey interface MTUs when calculating MSS
net.inet.tcp.mss_ifmtu=1
.Ed
.Pp
in your
.Pa /etc/sysctl.conf
file.
This causes the calculated MSS to be based on the MTU of the interface
via which the packet is sent.
This is always the right value if you are sure the answer to this packet
will be received on the same interface (i.e., you only have one interface
connected to the Internet.)
.Pp
Unfortunately this sysctl does not fix the MSS advertised by hosts in
the network behind a
.Nm
connected router.
To fix this you need
.Em MSS-clamping ,
explained below.
.Ss Setting up NAT with MSS-clamping
Some systems behind misconfigured firewalls try to use
Path-MTU-Discovery, while their firewall blocks all ICMP messages.
This is an illegal, but not uncommon, setup.
Typically you will have no chance to fix this (remote, outside of your
control) setup.
And sometimes you will have to use such remote systems (to download
data from them, or to do your online banking).
.Pp
Without special care systems as described above will not be able
to send larger chunks of data to a system connected via
.Nm .
But there is a workaround (some may call it cheating): pretend to not
be able to handle large packets, by sending a small MSS (maximum
segment size) option during initial TCP handshake.
.Pp
For connections originating from your
.Nm
connected machines, this is accomplished by setting the sysctl
variable
.Dv net.inet.tcp.mss_ifmtu
to 1 (see above).
For connections originating from systems behind your
.Nm
router, you need to set the
.Dv mssclamp
options in your NAT rules, like in this example of
.Pa /etc/ipnat.conf :
.Bd -literal -offset indent
map pppoe0 192.168.1.0/24 -> 0/32 portmap tcp/udp 44000:49999 mssclamp 1440
map pppoe0 192.168.1.0/24 -> 0/32 mssclamp 1440
.Ed
.Pp
If you do not use NAT, you need to set up a 1:1 NAT rule, just to
get the clamping:
.Bd -literal -offset indent
map pppoe0 x.x.x.x/24 -> 0/0 mssclamp 1440
.Ed
.Pp
The above examples assume a MTU of 1492 bytes.
If the MTU on your PPPoE connection is smaller use the MTU \- 52 bytes for
clamping e.g. 1408 bytes for a MTU of 1460 bytes.
.Em Note :
The theoretically correct value for the above example would be 1452 bytes
(it accounts for the smaller PPPoE MTU, the TCP header and the maximum of
0x40 bytes of TCP options) but it seems to not be sufficient in some cases.
Experiments conducted by various people have shown that clamping to the MSS
values suggested above works best.
.Sh EXAMPLES
A typical
.Pa /etc/ifconfig.pppoe0
file looks like this:
.Bd -literal -offset indent
create
! /sbin/ifconfig ne0 up
! /sbin/pppoectl -e ne0 $int
! /sbin/pppoectl $int myauthproto=pap myauthname=testcaller myauthsecret=donttell
inet 0.0.0.0 0.0.0.1 netmask 0xffffffff
#! /sbin/route add default -iface 0.0.0.1
up
.Ed
The commented out call to
.Xr route 8
may be omitted and the route added in the ip-up script called by
.Xr ifwatchd 8
when the real IP address is known.
This is easy in the
.Dq connect always
mode (link1 not set), but hard to accomplish in the
.Dq dial on demand
mode (link1 set).
In the latter case adding an iface route is an easy workaround.
.Pp
The
.Nm
interfaces operate completely inside the kernel, without any userland
support.
Because of this, a special daemon is used to fire ip-up or
down scripts to execute arbitrary code when the PPP session is established
and addresses of the interface become available.
To enable the usage of
.Pa /etc/ppp/ip-up
and
.Pa /etc/ppp/ip-down
for this purpose, simply add
.Bd -literal -offset indent
ifwatchd=YES
.Ed
.Pp
to
.Pa /etc/rc.conf .
See
.Xr ifwatchd 8
for details and parameters passed to these scripts.
.Pp
Since this is a PPP interface, the addresses assigned to the interface
may change during PPP negotiation.
There is no fine grained control available
for deciding which addresses are acceptable and which are not.
For the local side and the
remote address there is exactly one choice: hard coded address or wildcard.
If a real address is assigned to one side of the connection, PPP negotiation
will only agree to exactly this address.
If one side is wildcarded, every address suggested by the peer will
be accepted.
.Pp
To wildcard the local address set it to 0.0.0.0, to wildcard the remote
address set it to 0.0.0.1.
Wildcarding is not available (nor necessary) for IPv6 operation.
.Sh OPTIONS
A
.Nm
enabled kernel will not interfere with other
.Nm PPPoE
implementations running on the same machine.
Under special circumstances
(details below) this is not desirable, so the
.Nm
driver can be told to kill all unknown
.Nm PPPoE
sessions received by the Ethernet interface used for a configured
.Nm
interface.
To do this, add the following to your kernel config file:
.Pp
.Dl options PPPOE_TERM_UNKNOWN_SESSIONS
.Pp
and set the value of
.Xr sysctl 7
variable
.Dv net.pppoe.term_unknown
to true.
.Pp
Note that this will break all userland
.Nm PPPoE
implementations using the same Ethernet interface!
.Pp
This option is only useful if you have a static IP address assigned and
your ISP does not use LCP echo requests to monitor the link status.
After a crash or power failure the peer device still tries to send data to
the no longer active session on your computer, and might refuse to
reestablish a new connection, because there already is an open session.
On receipt of such packets, the
.Nm
driver with this option set will send a PADT packet (request to
terminate the session).
The peer will immediately disconnect
the orphaned session and allow a new one to be established.
.Pp
To enable
.Nm
server support in the kernel, use
.Pp
.Dl options PPPOE_SERVER
.Pp
As described above, this allows
.Nm
interfaces to be created and configured for incoming connections by
setting the
.Dq Li link0
flag with
.Xr ifconfig 8 .
.Sh SEE ALSO
.Xr ifwatchd 8 ,
.Xr pppoectl 8
.Rs
.%R RFC
.%N 2516
.%T "A Method for Transmitting PPP Over Ethernet (PPPoE)"
.%D February 1999
.Re
.Rs
.%R RFC
.%N 4638
.%T "Accommodating a Maximum Transit Unit/Maximum Receive Unit (MTU/MRU) Greater Than 1492 in the Point-to-Point Protocol over Ethernet (PPPoE)"
.%D September 2006
.Re
.Sh HISTORY
The
.Nm
device appeared in
.Nx 1.6 .
.Sh DEVIATIONS FROM STANDARD
The original PPPoE standard,
.Li RFC2516 ,
requires a maximal MTU of 1492 octets.
This value is the maximum conservative
value possible, based on the PPPoE header size and the minimum frame size
Ethernet interfaces are required to support.
.Pp
In practice most modern Ethernet interfaces support bigger frames, and
many PPPoE services allow the use of (slightly) larger MTUs, to avoid
the problems described above.
.Pp
This implementation allows MTU values as large as possible with the actual
MTU of the used Ethernet interface and conforms to the enhancement to the
PPPoE standard,
.Li RFC4638 ,
to request the use of this larger MTU value with the PPPoE server.
.Sh BUGS
When using the wildcard address 0.0.0.0 (as described above)
it is important to specify the proper
.Dq Li netmask
to
.Xr ifconfig 8 ,
in most setups
.Dq Li 0xffffffff .
If the netmask is unspecified, it will be set to 8 when 0.0.0.0 is
configured to the interface, and it will persist after negotiation.