| 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]> |