man/man8/ip-l2tp.8

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