Debian Codegraph @

upstream/debian-unstable/man8/ip-l2tp.8

raw
1 .TH IP\-L2TP 8 "19 Apr 2012" "iproute2" "Linux"
2 .SH "NAME"
3 ip-l2tp - L2TPv3 static unmanaged tunnel configuration
4 .SH "SYNOPSIS"
5 .sp
6 .ad l
7 .in +8
8 .ti -8
9 .B ip
10 .RI "[ " OPTIONS " ]"
11 .B l2tp
12 .RI " { " COMMAND " | "
13 .BR help " }"
14 .sp
15 .ti -8
16 .BR "ip l2tp add tunnel"
17 .br
18 .BI remote " ADDR " local " ADDR "
19 .br
20 .B tunnel_id
21 .IR ID
22 .B peer_tunnel_id
23 .IR ID
24 .br
25 .RB "[ " encap " { " ip " | " udp " } ]"
26 .br
27 .RB "[ " udp_sport
28 .IR PORT
29 .RB " ] [ " udp_dport
30 .IR PORT
31 .RB " ]"
32 .br
33 .RB "[ " udp_csum " { " on " | " off " } ]"
34 .br
35 .RB "[ " udp6_csum_tx " { " on " | " off " } ]"
36 .br
37 .RB "[ " udp6_csum_rx " { " on " | " off " } ]"
38 .br
39 .ti -8
40 .BR "ip l2tp add session"
41 .RB "[ " name
42 .IR NAME
43 .RB " ]"
44 .br
45 .B tunnel_id
46 .IR ID
47 .B session_id
48 .IR ID
49 .B peer_session_id
50 .IR ID
51 .br
52 .RB "[ " cookie
53 .IR HEXSTR
54 .RB " ] [ " peer_cookie
55 .IR HEXSTR
56 .RB " ]"
57 .br
58 .RB "[ " l2spec_type " { " none " | " default " } ]"
59 .br
60 .RB "[ " seq " { " none " | " send " | " recv " | " both " } ]"
61 .br
62 .ti -8
63 .BR "ip l2tp del tunnel"
64 .B tunnel_id
65 .IR ID
66 .br
67 .ti -8
68 .BR "ip l2tp del session"
69 .B tunnel_id
70 .IR ID
71 .B session_id
72 .IR ID
73 .br
74 .ti -8
75 .BR "ip l2tp show tunnel" " [ " tunnel_id
76 .IR ID " ]"
77 .br
78 .ti -8
79 .BR "ip l2tp show session" " [ " tunnel_id
80 .IR ID .B " ] ["
81 .B session_id
82 .IR ID " ]"
83 .br
84 .ti -8
85 .IR NAME " := "
86 .IR STRING
87 .ti -8
88 .IR ADDR " := { " IP_ADDRESS " |"
89 .BR any " }"
90 .ti -8
91 .IR PORT " := { " NUMBER " }"
92 .ti -8
93 .IR ID " := { " NUMBER " }"
94 .ti -8
95 .ti -8
96 .IR HEXSTR " := { 8 or 16 hex digits (4 / 8 bytes) }"
97 .SH DESCRIPTION
98 The
99 .B ip l2tp
100 commands are used to establish static, or so-called
101 .I unmanaged
102 L2TPv3 ethernet tunnels. For unmanaged tunnels, there is no L2TP
103 control protocol so no userspace daemon is required - tunnels are
104 manually created by issuing commands at a local system and at a remote
105 peer.
106 .PP
107 L2TPv3 is suitable for Layer-2 tunneling. Static tunnels are useful
108 to establish network links across IP networks when the tunnels are
109 fixed. L2TPv3 tunnels can carry data of more than one session. Each
110 session is identified by a session_id and its parent tunnel's
111 tunnel_id. A tunnel must be created before a session can be created in
112 the tunnel.
113 .PP
114 When creating an L2TP tunnel, the IP address of the remote peer is
115 specified, which can be either an IPv4 or IPv6 address. The local IP
116 address to be used to reach the peer must also be specified. This is
117 the address on which the local system will listen for and accept
118 received L2TP data packets from the peer.
119 .PP
120 L2TPv3 defines two packet encapsulation formats: UDP or IP. UDP
121 encapsulation is most common. IP encapsulation uses a dedicated IP
122 protocol value to carry L2TP data without the overhead of UDP. Use IP
123 encapsulation only when there are no NAT devices or firewalls in the
124 network path.
125 .PP
126 When an L2TPv3 ethernet session is created, a virtual network
127 interface is created for the session, which must then be configured
128 and brought up, just like any other network interface. When data is
129 passed through the interface, it is carried over the L2TP tunnel to
130 the peer. By configuring the system's routing tables or adding the
131 interface to a bridge, the L2TP interface is like a virtual wire
132 (pseudowire) connected to the peer.
133 .PP
134 Establishing an unmanaged L2TPv3 ethernet pseudowire involves manually
135 creating L2TP contexts on the local system and at the peer. Parameters
136 used at each site must correspond or no data will be passed. No
137 consistency checks are possible since there is no control protocol
138 used to establish unmanaged L2TP tunnels. Once the virtual network
139 interface of a given L2TP session is configured and enabled, data can
140 be transmitted, even if the peer isn't yet configured. If the peer
141 isn't configured, the L2TP data packets will be discarded by
142 the peer.
143 .PP
144 To establish an unmanaged L2TP tunnel, use
145 .B l2tp add tunnel
146 and
147 .B l2tp add session
148 commands described in this document. Then configure and enable the
149 tunnel's virtual network interface, as required.
150 .PP
151 Note that unmanaged tunnels carry only ethernet frames. If you need to
152 carry PPP traffic (L2TPv2) or your peer doesn't support unmanaged
153 L2TPv3 tunnels, you will need an L2TP server which implements the L2TP
154 control protocol. The L2TP control protocol allows dynamic L2TP
155 tunnels and sessions to be established and provides for detecting and
156 acting upon network failures.
157 .SS ip l2tp add tunnel - add a new tunnel
158 .TP
159 .BI tunnel_id " ID"
160 set the tunnel id, which is a 32-bit integer value. Uniquely
161 identifies the tunnel. The value used must match the peer_tunnel_id
162 value being used at the peer.
163 .TP
164 .BI peer_tunnel_id " ID"
165 set the peer tunnel id, which is a 32-bit integer value assigned to
166 the tunnel by the peer. The value used must match the tunnel_id value
167 being used at the peer.
168 .TP
169 .BI remote " ADDR"
170 set the IP address of the remote peer. May be specified as an IPv4
171 address or an IPv6 address.
172 .TP
173 .BI local " ADDR"
174 set the IP address of the local interface to be used for the
175 tunnel. This address must be the address of a local interface. May be
176 specified as an IPv4 address or an IPv6 address.
177 .TP
178 .BI encap " ENCAP"
179 set the encapsulation type of the tunnel.
180 .br
181 Valid values for encapsulation are:
182 .BR udp ", " ip "."
183 .TP
184 .BI udp_sport " PORT"
185 set the UDP source port to be used for the tunnel. Must be present
186 when udp encapsulation is selected. Ignored when ip encapsulation is
187 selected.
188 .TP
189 .BI udp_dport " PORT"
190 set the UDP destination port to be used for the tunnel. Must be
191 present when udp encapsulation is selected. Ignored when ip
192 encapsulation is selected.
193 .TP
194 .BI udp_csum " STATE"
195 (IPv4 only) control if IPv4 UDP checksums should be calculated and checked for the
196 encapsulating UDP packets, when UDP encapsulating is selected.
197 Default is
198 .BR off "."
199 .br
200 Valid values are:
201 .BR on ", " off "."
202 .TP
203 .BI udp6_csum_tx " STATE"
204 (IPv6 only) control if IPv6 UDP checksums should be calculated for encapsulating
205 UDP packets, when UDP encapsulating is selected.
206 Default is
207 .BR on "."
208 .br
209 Valid values are:
210 .BR on ", " off "."
211 .TP
212 .BI udp6_csum_rx " STATE"
213 (IPv6 only) control if IPv6 UDP checksums should be checked for the encapsulating
214 UDP packets, when UDP encapsulating is selected.
215 Default is
216 .BR on "."
217 .br
218 Valid values are:
219 .BR on ", " off "."
220 .SS ip l2tp del tunnel - destroy a tunnel
221 .TP
222 .BI tunnel_id " ID"
223 set the tunnel id of the tunnel to be deleted. All sessions within the
224 tunnel must be deleted first.
225 .SS ip l2tp show tunnel - show information about tunnels
226 .TP
227 .BI tunnel_id " ID"
228 set the tunnel id of the tunnel to be shown. If not specified,
229 information about all tunnels is printed.
230 .SS ip l2tp add session - add a new session to a tunnel
231 .TP
232 .BI name " NAME "
233 sets the session network interface name. Default is l2tpethN.
234 .TP
235 .BI tunnel_id " ID"
236 set the tunnel id, which is a 32-bit integer value. Uniquely
237 identifies the tunnel into which the session will be created. The
238 tunnel must already exist.
239 .TP
240 .BI session_id " ID"
241 set the session id, which is a 32-bit integer value. Uniquely
242 identifies the session being created. The value used must match the
243 peer_session_id value being used at the peer.
244 .TP
245 .BI peer_session_id " ID"
246 set the peer session id, which is a 32-bit integer value assigned to
247 the session by the peer. The value used must match the session_id
248 value being used at the peer.
249 .TP
250 .BI cookie " HEXSTR"
251 sets an optional cookie value to be assigned to the session. This is a
252 4 or 8 byte value, specified as 8 or 16 hex digits,
253 e.g. 014d3636deadbeef. The value must match the peer_cookie value set
254 at the peer. The cookie value is carried in L2TP data packets and is
255 checked for expected value at the peer. Default is to use no cookie.
256 .TP
257 .BI peer_cookie " HEXSTR"
258 sets an optional peer cookie value to be assigned to the session. This
259 is a 4 or 8 byte value, specified as 8 or 16 hex digits,
260 e.g. 014d3636deadbeef. The value must match the cookie value set at
261 the peer. It tells the local system what cookie value to expect to
262 find in received L2TP packets. Default is to use no cookie.
263 .TP
264 .BI l2spec_type " L2SPECTYPE"
265 set the layer2specific header type of the session.
266 .br
267 Valid values are:
268 .BR none ", " default "."
269 .TP
270 .BI seq " SEQ"
271 controls sequence numbering to prevent or detect out of order packets.
272 .B send
273 puts a sequence number in the default layer2specific header of each
274 outgoing packet.
275 .B recv
276 reorder packets if they are received out of order.
277 Default is
278 .BR none "."
279 .br
280 Valid values are:
281 .BR none ", " send ", " recv ", " both "."
282 .SS ip l2tp del session - destroy a session
283 .TP
284 .BI tunnel_id " ID"
285 set the tunnel id in which the session to be deleted is located.
286 .TP
287 .BI session_id " ID"
288 set the session id of the session to be deleted.
289 .SS ip l2tp show session - show information about sessions
290 .TP
291 .BI tunnel_id " ID"
292 set the tunnel id of the session(s) to be shown. If not specified,
293 information about sessions in all tunnels is printed.
294 .TP
295 .BI session_id " ID"
296 set the session id of the session to be shown. If not specified,
297 information about all sessions is printed.
298 .SH EXAMPLES
299 .PP
300 .SS Setup L2TP tunnels and sessions
301 .nf
302 site-A:# ip l2tp add tunnel tunnel_id 3000 peer_tunnel_id 4000 \\
303 encap udp local 1.2.3.4 remote 5.6.7.8 \\
304 udp_sport 5000 udp_dport 6000
305 site-A:# ip l2tp add session tunnel_id 3000 session_id 1000 \\
306 peer_session_id 2000
307
308 site-B:# ip l2tp add tunnel tunnel_id 4000 peer_tunnel_id 3000 \\
309 encap udp local 5.6.7.8 remote 1.2.3.4 \\
310 udp_sport 6000 udp_dport 5000
311 site-B:# ip l2tp add session tunnel_id 4000 session_id 2000 \\
312 peer_session_id 1000
313
314 site-A:# ip link set l2tpeth0 up mtu 1488
315
316 site-B:# ip link set l2tpeth0 up mtu 1488
317 .fi
318 .PP
319 Notice that the IP addresses, UDP ports and tunnel / session ids are
320 matched and reversed at each site.
321 .SS Configure as IP interfaces
322 The two interfaces can be configured with IP addresses if only IP data
323 is to be carried. This is perhaps the simplest configuration.
324 .PP
325 .nf
326 site-A:# ip addr add 10.42.1.1 peer 10.42.1.2 dev l2tpeth0
327
328 site-B:# ip addr add 10.42.1.2 peer 10.42.1.1 dev l2tpeth0
329
330 site-A:# ping 10.42.1.2
331 .fi
332 .PP
333 Now the link should be usable. Add static routes as needed to have
334 data sent over the new link.
335 .PP
336 .SS Configure as bridged interfaces
337 To carry non-IP data, the L2TP network interface is added to a bridge
338 instead of being assigned its own IP address, using standard Linux
339 utilities. Since raw ethernet frames are then carried inside the
340 tunnel, the MTU of the L2TP interfaces must be set to allow space for
341 those headers.
342 .PP
343 .nf
344 site-A:# ip link set l2tpeth0 up mtu 1446
345 site-A:# ip link add br0 type bridge
346 site-A:# ip link set l2tpeth0 master br0
347 site-A:# ip link set eth0 master br0
348 site-A:# ip link set br0 up
349 .fi
350 .PP
351 If you are using VLANs, setup a bridge per VLAN and bridge each VLAN
352 over a separate L2TP session. For example, to bridge VLAN ID 5 on eth1
353 over an L2TP pseudowire:
354 .PP
355 .nf
356 site-A:# ip link set l2tpeth0 up mtu 1446
357 site-A:# ip link add brvlan5 type bridge
358 site-A:# ip link set l2tpeth0.5 master brvlan5
359 site-A:# ip link set eth1.5 master brvlan5
360 site-A:# ip link set brvlan5 up
361 .fi
362 .PP
363 Adding the L2TP interface to a bridge causes the bridge to forward
364 traffic over the L2TP pseudowire just like it forwards over any other
365 interface. The bridge learns MAC addresses of hosts attached to each
366 interface and intelligently forwards frames from one bridge port to
367 another. IP addresses are not assigned to the l2tpethN interfaces. If
368 the bridge is correctly configured at both sides of the L2TP
369 pseudowire, it should be possible to reach hosts in the peer's bridged
370 network.
371 .PP
372 When raw ethernet frames are bridged across an L2TP tunnel, large
373 frames may be fragmented and forwarded as individual IP fragments to
374 the recipient, depending on the MTU of the physical interface used by
375 the tunnel. When the ethernet frames carry protocols which are
376 reassembled by the recipient, like IP, this isn't a problem. However,
377 such fragmentation can cause problems for protocols like PPPoE where
378 the recipient expects to receive ethernet frames exactly as
379 transmitted. In such cases, it is important that frames leaving the
380 tunnel are reassembled back into a single frame before being
381 forwarded on. To do so, enable netfilter connection tracking
382 (conntrack) or manually load the Linux netfilter defrag modules at
383 each tunnel endpoint.
384 .PP
385 .nf
386 site-A:# modprobe nf_defrag_ipv4
387
388 site-B:# modprobe nf_defrag_ipv4
389 .fi
390 .PP
391 If L2TP is being used over IPv6, use the IPv6 defrag module.
392 .SH INTEROPERABILITY
393 .PP
394 Unmanaged (static) L2TPv3 tunnels are supported by some network
395 equipment vendors such as Cisco.
396 .PP
397 In Linux, L2TP Hello messages are not supported in unmanaged
398 tunnels. Hello messages are used by L2TP clients and servers to detect
399 link failures in order to automate tearing down and reestablishing
400 dynamic tunnels. If a non-Linux peer supports Hello messages in
401 unmanaged tunnels, it must be turned off to interoperate with Linux.
402 .PP
403 Linux defaults to use the Default Layer2SpecificHeader type as defined
404 in the L2TPv3 protocol specification, RFC3931. This setting must be
405 consistent with that configured at the peer. Some vendor
406 implementations (e.g. Cisco) default to use a Layer2SpecificHeader
407 type of None.
408 .SH SEE ALSO
409 .br
410 .BR ip (8)
411 .SH AUTHOR
412 James Chapman <[email protected]>