1.\" $NetBSD: pppoe.4,v 1.32 2006/08/04 17:08:52 wiz 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 July 4, 2006 38.Dt PPPOE 4 39.Os 40.Sh NAME 41.Nm pppoe 42.Nd PPP over Ethernet protocol network interface 43.Sh SYNOPSIS 44.Cd 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. 55The 56.Nm 57interface does not by itself transmit or receive frames, 58but needs an Ethernet interface to do so. 59This Ethernet interface is connected to the 60.Nm 61interface via 62.Xr pppoectl 8 . 63The Ethernet interface needs to be marked UP, but does not need to have an 64IP address. 65.Pp 66There are two basic modes of operation, controlled via the 67.Em link1 68switch. 69The default mode, 70.Em link1 71not being set, tries to keep the configured session open all the 72time. 73If the session is disconnected, a new connection attempt is started 74immediately. 75The 76.Dq dial on demand 77mode, selected by setting 78.Em link1 , 79only establishes a connection when data is being sent to the interface. 80.Pp 81If the kernel is compiled with options 82.Dv PPPOE_SERVER , 83there are two modes of connection, controlled via the 84.Em link0 85switch. 86The default mode, 87.Em link0 88not being set, is client mode. 89The 90.Dq PPPoE server 91mode, selected by setting 92.Em link0 , 93is to wait for incoming PPPoE session. 94.Pp 95Before a 96.Nm 97interface is usable, it needs to be configured. 98The following steps are necessary: 99.Bl -bullet 100.It 101Create the interface. 102.It 103Connect an Ethernet interface. 104This interface is used for the physical communication. 105As noted above it must be marked UP, but need not have an IP address. 106.It 107Configure authentication. 108The PPP session needs to identify the client to the peer. 109For more details on the available options see 110.Xr pppoectl 8 . 111.El 112.Pp 113This all is typically accomplished using an 114.Pa /etc/ifconfig.pppoe0 115file. 116.Ss MSS/MTU problems 117If you are using a 118.Nm 119interface, you will have an unusually low MTU for todays Internet. 120Combined with a lot of misconfigured sites (host using path MTU discovery 121behind a router blocking all ICMP traffic) this will often cause problems. 122Connections to these servers will only work if your system advertises the 123right MSS in the TCP three way handshake. 124To get the right MSS, you need to set 125.Bd -literal -offset indent 126# Obey interface MTUs when calculating MSS 127net.inet.tcp.mss_ifmtu=1 128.Ed 129.Pp 130in your 131.Pa /etc/sysctl.conf 132file. 133This causes the calculated MSS to be based on the MTU of the interface 134via which the packet is sent. 135This is always the right value if you are sure the answer to this packet 136will be received on the same interface (i.e., you only have one interface 137connected to the Internet.) 138.Pp 139Unfortunately this sysctl does not fix the MSS advertised by hosts in 140the network behind a 141.Nm 142connected router. 143To fix this you need 144.Em MSS-clamping , 145explained below. 146.Ss Setting up NAT with MSS-clamping 147Some systems behind misconfigured firewalls try to use 148Path-MTU-Discovery, while their firewall blocks all ICMP messages. 149This is an illegal, but not uncommon, setup. 150Typically you will have no chance to fix this (remote, outside of your 151control) setup. 152And sometimes you will have to use such remote systems (to download 153data from them, or to do your online banking). 154.Pp 155Without special care systems as described above will not be able 156to send larger chunks of data to a system connected via 157.Nm . 158But there is a workaround (some may call it cheating): pretend to not 159be able to handle large packets, by sending a small MSS (maximum 160segment size) option during initial TCP handshake. 161.Pp 162For connections originating from your 163.Nm 164connected machines, this is accomplished by setting the sysctl 165variable 166.Dv net.inet.tcp.mss_ifmtu 167to 1 (see above). 168For connections originating from systems behind your 169.Nm 170router, you need to set the 171.Dv mssclamp 172options in your NAT rules, like in this example of 173.Pa /etc/ipnat.conf : 174.Bd -literal -offset indent 175map pppoe0 192.168.1.0/24 -\*[Gt] 0/32 portmap tcp/udp 44000:49999 mssclamp 1440 176map pppoe0 192.168.1.0/24 -\*[Gt] 0/32 mssclamp 1440 177.Ed 178.Pp 179If you do not use NAT, you need to set up a 1:1 NAT rule, just to 180get the clamping: 181.Bd -literal -offset indent 182map pppoe0 x.x.x.x/24 -\*[Gt] 0/0 mssclamp 1440 183.Ed 184.Pp 185The above examples assume a MTU of 1492 bytes. 186If the MTU on your PPPoE connection is smaller use the MTU \- 52 bytes for 187clamping e.g. 1408 bytes for a MTU of 1460 bytes. 188.Em Note : 189The theoretically correct value for the above example would be 1452 bytes 190(it accounts for the smaller PPPoE MTU, the TCP header and the maximum of 1910x40 bytes of TCP options) but it seems to not be sufficient in some cases. 192Experiments conducted by various people have shown that clamping to the MSS 193values suggested above works best. 194.Sh EXAMPLES 195A typical 196.Pa /etc/ifconfig.pppoe0 197file looks like this: 198.Bd -literal -offset indent 199create 200! /sbin/ifconfig ne0 up 201! /sbin/pppoectl -e ne0 $int 202! /sbin/pppoectl $int myauthproto=pap myauthname=testcaller myauthsecret=donttell 203inet 0.0.0.0 0.0.0.1 netmask 0xffffffff 204#! /sbin/route add default -iface 0.0.0.1 205up 206.Ed 207The commented out call to 208.Xr route 8 209may be omitted and the route added in the ip-up script called by 210.Xr ifwatchd 8 211when the real IP address is known. 212This is easy in the 213.Dq connect always 214mode (link1 not set), but hard to accomplish in the 215.Dq dial on demand 216mode (link1 set). 217In the latter case adding an iface route is an easy workaround. 218.Pp 219The 220.Nm 221interfaces operate completely inside the kernel, without any userland 222support. 223Because of this, a special daemon is used to fire ip-up or 224down scripts to execute arbitrary code when the PPP session is established 225and addresses of the interface become available. 226To enable the usage of 227.Pa /etc/ppp/ip-up 228and 229.Pa /etc/ppp/ip-down 230for this purpose, simply add 231.Bd -literal -offset indent 232ifwatchd=YES 233.Ed 234.Pp 235to 236.Pa /etc/rc.conf . 237See 238.Xr ifwatchd 8 239for details and parameters passed to these scripts. 240.Pp 241Since this is a PPP interface, the addresses assigned to the interface 242may change during PPP negotiation. 243There is no fine grained control available 244for deciding which addresses are acceptable and which are not. 245For the local side and the 246remote address there is exactly one choice: hard coded address or wildcard. 247If a real address is assigned to one side of the connection, PPP negotiation 248will only agree to exactly this address. 249If one side is wildcarded, every address suggested by the peer will 250be accepted. 251.Pp 252To wildcard the local address set it to 0.0.0.0, to wildcard the remote 253address set it to 0.0.0.1. 254Wildcarding is not available (nor necessary) for IPv6 operation. 255.Sh OPTIONS 256A 257.Nm 258enabled kernel will not interfere with other 259.Nm PPPoE 260implementations running on the same machine. 261Under special circumstances 262(details below) this is not desirable, so the 263.Nm 264driver can be told to kill all unknown 265.Nm PPPoE 266sessions received by the Ethernet interface used for a configured 267.Nm 268interface. 269To do this, add the following to your kernel config file: 270.Pp 271.Dl options PPPOE_TERM_UNKNOWN_SESSIONS 272.Pp 273Note that this will break all userland 274.Nm PPPoE 275implementations using the same Ethernet interface! 276.Pp 277This option is only useful if you have a static IP address assigned and 278your ISP does not use LCP echo requests to monitor the link status. 279After a crash or power failure the peer device still tries to send data to 280the no longer active session on your computer, and might refuse to 281reestablish a new connection, because there already is an open session. 282On receipt of such packets, the 283.Nm 284driver with this option set will send a PADT packet (request to 285terminate the session). 286The peer will immediately disconnect 287the orphaned session and allow a new one to be established. 288.Pp 289To enable 290.Nm 291server support in the kernel, use 292.Pp 293.Dl options PPPOE_SERVER 294.Pp 295As described above, this allows 296.Nm 297interfaces to be created and configured for incoming connections by 298setting the 299.Dq Li link0 300flag with 301.Xr ifconfig 8 . 302.Sh SEE ALSO 303.Xr ifwatchd 8 , 304.Xr pppoectl 8 305.Rs 306.%R RFC 307.%N 2516 308.%T "A Method for Transmitting PPP Over Ethernet (PPPoE)" 309.%D February 1999 310.Re 311.Sh HISTORY 312The 313.Nm 314device appeared in 315.Nx 1.6 . 316.Sh DEVIATIONS FROM STANDARD 317The PPPoE standard, 318.Li RFC2516 , 319requires a maximal MTU of 1492 octets. 320This value is the maximum conservative 321value possible, based on the PPPoE header size and the minimum frame size 322Ethernet interfaces are required to support. 323.Pp 324In practice most modern Ethernet interfaces support bigger frames, and 325many PPPoE services allow the use of (slightly) larger MTUs, to avoid 326the problems described above. 327.Pp 328This implementation allows MTU values as large as possible with the actual 329MTU of the used Ethernet interface. 330.Sh BUGS 331When using the wildcard address 0.0.0.0 (as described above) 332it is important to specify the proper 333.Dq Li netmask 334to 335.Xr ifconfig 8 , 336in most setups 337.Dq Li 0xffffffff . 338If the netmask is unspecified, it will be set to 8 when 0.0.0.0 is 339configured to the interface, and it will persist after negotiation. 340