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