James Chapman | 6121e1f | 2012-05-01 15:25:23 +0100 | [diff] [blame^] | 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:# brctl addbr br0 |
| 315 | site-A:# brctl addif br0 l2tpeth0 |
| 316 | site-A:# brctl addif br0 eth0 |
| 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:# brctl addbr brvlan5 |
| 327 | site-A:# brctl addif brvlan5 l2tpeth0.5 |
| 328 | site-A:# brctl addif brvlan5 eth1.5 |
| 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 brctl (8) |
| 374 | .BR ip (8) |
| 375 | .SH AUTHOR |
| 376 | James Chapman <jchapman@katalix.com> |