.\"	$NetBSD: pppoe.4,v 1.8 2002/02/06 19:17:01 wiz Exp $
.\"
.\" Copyright (c) 2001 Martin Husemann. All rights reserved.
.\"
.\" 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 AUTHOR 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 AUTHOR 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 December 10, 2001
.Dt PPPOE 4
.Os
.Sh NAME
.Nm pppoe
.Nd PPP over Ethernet protocol network interface
.Sh SYNOPSIS
.Nm 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
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.
.Sh IMPORTANT NOTE
If you are using a
.Nm
interface, you will have an unusual low MTU for todays 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 this 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
# 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.
.Sh EXAMPLES
A typical
.Pa /etc/ifconfig.pppoe0
file looks like this:
.Bd -literal
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
#! /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
ifwatchd=YES
.Ed
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 SEE ALSO
.Xr ifwatchd 8 ,
.Xr pppoectl 8
.Rs
.%R RFC
.%N 2516
.%D February 1999
.%T "A Method for Transmitting PPP Over Ethernet (PPPoE)"
.Re
.Sh HISTORY
The
.Nm
device appeared in
.Nx 1.6 .
.Sh BUGS
This implementation is client side only.