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