]>
Commit | Line | Data |
---|---|---|
6121e1fe JC |
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 | |
2227f2a5 | 18 | .BI remote " ADDR " local " ADDR " |
6121e1fe JC |
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 | .ti -8 | |
34 | .BR "ip l2tp add session" | |
35 | .RB "[ " name | |
36 | .IR NAME | |
37 | .RB " ]" | |
38 | .br | |
39 | .B tunnel_id | |
40 | .IR ID | |
41 | .B session_id | |
42 | .IR ID | |
43 | .B peer_session_id | |
44 | .IR ID | |
45 | .br | |
46 | .RB "[ " cookie | |
47 | .IR HEXSTR | |
48 | .RB " ] [ " peer_cookie | |
49 | .IR HEXSTR | |
50 | .RB " ]" | |
51 | .br | |
9c064b53 JC |
52 | .RB "[ " l2spec_type " { " none " | " default " } ]" |
53 | .br | |
8a11421a AST |
54 | .RB "[ " seq " { " none " | " send " | " recv " | " both " } ]" |
55 | .br | |
6121e1fe JC |
56 | .RB "[ " offset |
57 | .IR OFFSET | |
58 | .RB " ] [ " peer_offset | |
59 | .IR OFFSET | |
60 | .RB " ]" | |
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 | |
2227f2a5 PS |
75 | .BR "ip l2tp show tunnel" " [ " tunnel_id |
76 | .IR ID " ]" | |
6121e1fe JC |
77 | .br |
78 | .ti -8 | |
2227f2a5 PS |
79 | .BR "ip l2tp show session" " [ " tunnel_id |
80 | .IR ID .B " ] [" | |
81 | .B session_id | |
82 | .IR ID " ]" | |
6121e1fe JC |
83 | .br |
84 | .ti -8 | |
85 | .IR NAME " := " | |
86 | .IR STRING | |
87 | .ti -8 | |
2227f2a5 PS |
88 | .IR ADDR " := { " IP_ADDRESS " |" |
89 | .BR any " }" | |
6121e1fe JC |
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 | |
6274b0b7 | 107 | L2TPv3 is suitable for Layer-2 tunneling. Static tunnels are useful |
6121e1fe JC |
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 | |
6121e1fe JC |
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 | .SS ip l2tp del tunnel - destroy a tunnel | |
194 | .TP | |
195 | .BI tunnel_id " ID" | |
196 | set the tunnel id of the tunnel to be deleted. All sessions within the | |
197 | tunnel must be deleted first. | |
198 | .SS ip l2tp show tunnel - show information about tunnels | |
199 | .TP | |
200 | .BI tunnel_id " ID" | |
201 | set the tunnel id of the tunnel to be shown. If not specified, | |
202 | information about all tunnels is printed. | |
203 | .SS ip l2tp add session - add a new session to a tunnel | |
204 | .TP | |
205 | .BI name " NAME " | |
206 | sets the session network interface name. Default is l2tpethN. | |
207 | .TP | |
208 | .BI tunnel_id " ID" | |
209 | set the tunnel id, which is a 32-bit integer value. Uniquely | |
210 | identifies the tunnel into which the session will be created. The | |
211 | tunnel must already exist. | |
212 | .TP | |
213 | .BI session_id " ID" | |
214 | set the session id, which is a 32-bit integer value. Uniquely | |
215 | identifies the session being created. The value used must match the | |
216 | peer_session_id value being used at the peer. | |
217 | .TP | |
218 | .BI peer_session_id " ID" | |
219 | set the peer session id, which is a 32-bit integer value assigned to | |
220 | the session by the peer. The value used must match the session_id | |
221 | value being used at the peer. | |
222 | .TP | |
223 | .BI cookie " HEXSTR" | |
224 | sets an optional cookie value to be assigned to the session. This is a | |
225 | 4 or 8 byte value, specified as 8 or 16 hex digits, | |
226 | e.g. 014d3636deadbeef. The value must match the peer_cookie value set | |
227 | at the peer. The cookie value is carried in L2TP data packets and is | |
228 | checked for expected value at the peer. Default is to use no cookie. | |
229 | .TP | |
230 | .BI peer_cookie " HEXSTR" | |
231 | sets an optional peer cookie value to be assigned to the session. This | |
232 | is a 4 or 8 byte value, specified as 8 or 16 hex digits, | |
233 | e.g. 014d3636deadbeef. The value must match the cookie value set at | |
234 | the peer. It tells the local system what cookie value to expect to | |
235 | find in received L2TP packets. Default is to use no cookie. | |
236 | .TP | |
9c064b53 JC |
237 | .BI l2spec_type " L2SPECTYPE" |
238 | set the layer2specific header type of the session. | |
239 | .br | |
240 | Valid values are: | |
222c4dab | 241 | .BR none ", " default "." |
9c064b53 | 242 | .TP |
8a11421a AST |
243 | .BI seq " SEQ" |
244 | controls sequence numbering to prevent or detect out of order packets. | |
245 | .B send | |
246 | puts a sequence number in the default layer2specific header of each | |
247 | outgoing packet. | |
248 | .B recv | |
249 | reorder packets if they are received out of order. | |
250 | Default is | |
251 | .BR none "." | |
252 | .br | |
253 | Valid values are: | |
254 | .BR none ", " send ", " recv ", " both "." | |
255 | .TP | |
6121e1fe JC |
256 | .BI offset " OFFSET" |
257 | sets the byte offset from the L2TP header where user data starts in | |
258 | transmitted L2TP data packets. This is hardly ever used. If set, the | |
259 | value must match the peer_offset value used at the peer. Default is 0. | |
260 | .TP | |
261 | .BI peer_offset " OFFSET" | |
262 | sets the byte offset from the L2TP header where user data starts in | |
263 | received L2TP data packets. This is hardly ever used. If set, the | |
264 | value must match the offset value used at the peer. Default is 0. | |
265 | .SS ip l2tp del session - destroy a session | |
266 | .TP | |
267 | .BI tunnel_id " ID" | |
268 | set the tunnel id in which the session to be deleted is located. | |
269 | .TP | |
270 | .BI session_id " ID" | |
271 | set the session id of the session to be deleted. | |
272 | .SS ip l2tp show session - show information about sessions | |
273 | .TP | |
274 | .BI tunnel_id " ID" | |
275 | set the tunnel id of the session(s) to be shown. If not specified, | |
276 | information about sessions in all tunnels is printed. | |
277 | .TP | |
278 | .BI session_id " ID" | |
279 | set the session id of the session to be shown. If not specified, | |
280 | information about all sessions is printed. | |
281 | .SH EXAMPLES | |
282 | .PP | |
283 | .SS Setup L2TP tunnels and sessions | |
284 | .nf | |
285 | site-A:# ip l2tp add tunnel tunnel_id 3000 peer_tunnel_id 4000 \\ | |
286 | encap udp local 1.2.3.4 remote 5.6.7.8 \\ | |
287 | udp_sport 5000 udp_dport 6000 | |
288 | site-A:# ip l2tp add session tunnel_id 3000 session_id 1000 \\ | |
289 | peer_session_id 2000 | |
290 | ||
291 | site-B:# ip l2tp add tunnel tunnel_id 4000 peer_tunnel_id 3000 \\ | |
292 | encap udp local 5.6.7.8 remote 1.2.3.4 \\ | |
293 | udp_sport 6000 udp_dport 5000 | |
294 | site-B:# ip l2tp add session tunnel_id 4000 session_id 2000 \\ | |
295 | peer_session_id 1000 | |
296 | ||
297 | site-A:# ip link set l2tpeth0 up mtu 1488 | |
298 | ||
299 | site-B:# ip link set l2tpeth0 up mtu 1488 | |
300 | .fi | |
301 | .PP | |
302 | Notice that the IP addresses, UDP ports and tunnel / session ids are | |
303 | matched and reversed at each site. | |
304 | .SS Configure as IP interfaces | |
305 | The two interfaces can be configured with IP addresses if only IP data | |
306 | is to be carried. This is perhaps the simplest configuration. | |
307 | .PP | |
308 | .nf | |
309 | site-A:# ip addr add 10.42.1.1 peer 10.42.1.2 dev l2tpeth0 | |
310 | ||
311 | site-B:# ip addr add 10.42.1.2 peer 10.42.1.1 dev l2tpeth0 | |
312 | ||
313 | site-A:# ping 10.42.1.2 | |
314 | .fi | |
315 | .PP | |
316 | Now the link should be usable. Add static routes as needed to have | |
317 | data sent over the new link. | |
318 | .PP | |
319 | .SS Configure as bridged interfaces | |
320 | To carry non-IP data, the L2TP network interface is added to a bridge | |
321 | instead of being assigned its own IP address, using standard Linux | |
322 | utilities. Since raw ethernet frames are then carried inside the | |
323 | tunnel, the MTU of the L2TP interfaces must be set to allow space for | |
324 | those headers. | |
325 | .PP | |
326 | .nf | |
327 | site-A:# ip link set l2tpeth0 up mtu 1446 | |
ec72fd73 SH |
328 | site-A:# ip link add br0 type bridge |
329 | site-A:# ip link set l2tpeth0 master br0 | |
330 | site-A:# ip link set eth0 master br0 | |
6121e1fe JC |
331 | site-A:# ip link set br0 up |
332 | .fi | |
333 | .PP | |
334 | If you are using VLANs, setup a bridge per VLAN and bridge each VLAN | |
335 | over a separate L2TP session. For example, to bridge VLAN ID 5 on eth1 | |
336 | over an L2TP pseudowire: | |
337 | .PP | |
338 | .nf | |
339 | site-A:# ip link set l2tpeth0 up mtu 1446 | |
ec72fd73 SH |
340 | site-A:# ip link add brvlan5 type bridge |
341 | site-A:# ip link set l2tpeth0.5 master brvlan5 | |
342 | site-A:# ip link set eth1.5 master brvlan5 | |
6121e1fe JC |
343 | site-A:# ip link set brvlan5 up |
344 | .fi | |
345 | .PP | |
346 | Adding the L2TP interface to a bridge causes the bridge to forward | |
347 | traffic over the L2TP pseudowire just like it forwards over any other | |
348 | interface. The bridge learns MAC addresses of hosts attached to each | |
349 | interface and intelligently forwards frames from one bridge port to | |
350 | another. IP addresses are not assigned to the l2tpethN interfaces. If | |
351 | the bridge is correctly configured at both sides of the L2TP | |
352 | pseudowire, it should be possible to reach hosts in the peer's bridged | |
353 | network. | |
354 | .PP | |
355 | When raw ethernet frames are bridged across an L2TP tunnel, large | |
356 | frames may be fragmented and forwarded as individual IP fragments to | |
357 | the recipient, depending on the MTU of the physical interface used by | |
358 | the tunnel. When the ethernet frames carry protocols which are | |
359 | reassembled by the recipient, like IP, this isn't a problem. However, | |
360 | such fragmentation can cause problems for protocols like PPPoE where | |
361 | the recipient expects to receive ethernet frames exactly as | |
362 | transmitted. In such cases, it is important that frames leaving the | |
363 | tunnel are reassembled back into a single frame before being | |
364 | forwarded on. To do so, enable netfilter connection tracking | |
c9ae9bae | 365 | (conntrack) or manually load the Linux netfilter defrag modules at |
6121e1fe JC |
366 | each tunnel endpoint. |
367 | .PP | |
368 | .nf | |
c9ae9bae | 369 | site-A:# modprobe nf_defrag_ipv4 |
6121e1fe | 370 | |
c9ae9bae | 371 | site-B:# modprobe nf_defrag_ipv4 |
6121e1fe JC |
372 | .fi |
373 | .PP | |
c9ae9bae | 374 | If L2TP is being used over IPv6, use the IPv6 defrag module. |
6274b0b7 | 375 | .SH INTEROPERABILITY |
6121e1fe JC |
376 | .PP |
377 | Unmanaged (static) L2TPv3 tunnels are supported by some network | |
378 | equipment equipment vendors such as Cisco. | |
379 | .PP | |
380 | In Linux, L2TP Hello messages are not supported in unmanaged | |
381 | tunnels. Hello messages are used by L2TP clients and servers to detect | |
382 | link failures in order to automate tearing down and reestablishing | |
383 | dynamic tunnels. If a non-Linux peer supports Hello messages in | |
384 | unmanaged tunnels, it must be turned off to interoperate with Linux. | |
9c064b53 JC |
385 | .PP |
386 | Linux defaults to use the Default Layer2SpecificHeader type as defined | |
387 | in the L2TPv3 protocol specification, RFC3931. This setting must be | |
388 | consistent with that configured at the peer. Some vendor | |
389 | implementations (e.g. Cisco) default to use a Layer2SpecificHeader | |
390 | type of None. | |
6121e1fe JC |
391 | .SH SEE ALSO |
392 | .br | |
6121e1fe JC |
393 | .BR ip (8) |
394 | .SH AUTHOR | |
395 | James Chapman <jchapman@katalix.com> |