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