1.\" $NetBSD: pppoe.4,v 1.9 2002/04/14 11:42:56 martin Exp $ 2.\" 3.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Martin Husemann <martin@netbsd.org>. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd December 10, 2001 38.Dt PPPOE 4 39.Os 40.Sh NAME 41.Nm pppoe 42.Nd PPP over Ethernet protocol network interface 43.Sh SYNOPSIS 44.Nm pseudo-device pppoe 45.Sh DESCRIPTION 46The 47.Nm 48interface encapsulates 49.Em Point-to-Point Protocol (PPP) 50packets inside Ethernet frames as defined by 51.Li RFC2516 . 52.Pp 53This is often used to connect a router via a DSL modem to 54an access concentrator. The 55.Nm 56interface does not by itself transmit or receive frames, 57but needs an Ethernet interface to do so. This Ethernet interface 58is connected to the 59.Nm 60interface via 61.Xr pppoectl 8 . 62The Ethernet interface needs to be marked UP, but does not need to have an 63IP address. 64.Pp 65There are two basic modes of operation, controlled via the 66.Em link1 67switch. The default mode, 68.Em link1 69not being set, tries to keep the configured session open all the 70time. If the session is disconnected, a new connection attempt is started 71immediately. The 72.Dq dial on demand 73mode, selected by setting 74.Em link1 , 75only establishes a connection when data is being sent to the interface. 76.Pp 77Before a 78.Nm 79interface is usable, it needs to be configured. The following steps 80are necessary: 81.Bl -bullet 82.It 83create the interface 84.It 85connect an Ethernet interface 86This interface is used for the physical communication. As noted above it 87must be marked UP, but need not have an IP address. 88.It 89configure authentication 90The PPP session needs to identify the client to the peer. For more details 91on the available options see 92.Xr pppoectl 8 . 93.El 94.Pp 95This all is typically accomplished using an 96.Pa /etc/ifconfig.pppoe0 97file. 98.Sh IMPORTANT NOTE 99If you are using a 100.Nm 101interface, you will have an unusual low MTU for todays internet. 102Combined with a lot of misconfigured sites (host using path MTU discovery 103behind a router blocking all ICMP traffic) this will often cause problems. 104Connections to this servers will only work if your system advertises the 105right MSS in the TCP three way handshake. To get the right MSS, you need 106to set 107.Bd -literal 108# Obey interface MTUs when calculating MSS 109net.inet.tcp.mss_ifmtu=1 110.Ed 111.Pp 112in your 113.Pa /etc/sysctl.conf 114file. 115This causes the calculated MSS to be based on the MTU of the interface 116via which the packet is sent. This is always the right value if you are 117sure the answer to this packet will be received on the same interface 118(I.e. you only have one interface connected to the internet.) 119.Pp 120Unfortunately this sysctl does not fix the MSS advertised by hosts in 121the network behind a 122.Nm 123connected router. 124.Sh EXAMPLES 125A typical 126.Pa /etc/ifconfig.pppoe0 127file looks like this: 128.Bd -literal 129create 130! /sbin/ifconfig ne0 up 131! /sbin/pppoectl -e ne0 $int 132! /sbin/pppoectl $int myauthproto=pap myauthname=testcaller myauthsecret=donttell 133inet 0.0.0.0 0.0.0.1 134#! /sbin/route add default -iface 0.0.0.1 135up 136.Ed 137The commented out call to 138.Xr route 8 139may be omitted and the route added in the ip-up script called by 140.Xr ifwatchd 8 141when the real IP address is known. This is easy in the 142.Dq connect always 143mode (link1 not set), but hard to accomplish in the 144.Dq dial on demand 145mode (link1 set). In the latter case adding an iface route is an easy 146workaround. 147.Pp 148The 149.Nm 150interfaces operate completely inside the kernel, without any userland 151support. Because of this, a special daemon is used to fire ip-up or 152down scripts to execute arbitrary code when the PPP session is established 153and addresses of the interface become available. To enable the usage of 154.Pa /etc/ppp/ip-up 155and 156.Pa /etc/ppp/ip-down 157for this purpose, simply add 158.Bd -literal 159ifwatchd=YES 160.Ed 161to 162.Pa /etc/rc.conf . 163See 164.Xr ifwatchd 8 165for details and parameters passed to these scripts. 166.Pp 167Since this is a PPP interface, the addresses assigned to the interface 168may change during PPP negotiation. There is no fine grained control available 169for deciding which addresses are acceptable and which are not. For the local 170side and the 171remote address there is exactly one choice: hard coded address or wildcard. 172If a real address is assigned to one side of the connection, PPP negotiation 173will only agree to exactly this address. If one side is wildcarded, every 174address suggested by the peer will be accepted. 175.Pp 176To wildcard the local address set it to 0.0.0.0, to wildcard the remote 177address set it to 0.0.0.1. Wildcarding is not available (nor necessary) 178for IPv6 operation. 179.Sh SEE ALSO 180.Xr ifwatchd 8 , 181.Xr pppoectl 8 182.Rs 183.%R RFC 184.%N 2516 185.%D February 1999 186.%T "A Method for Transmitting PPP Over Ethernet (PPPoE)" 187.Re 188.Sh HISTORY 189The 190.Nm 191device appeared in 192.Nx 1.6 . 193.Sh BUGS 194This implementation is client side only. 195