1IP-L2TP(8) Linux IP-L2TP(8)
2
6 ip-l2tp - L2TPv3 static unmanaged tunnel configuration
7
9 ip [ OPTIONS ] l2tp { COMMAND | help }
10 ip l2tp add tunnel
12 remote ADDR local ADDR
13 tunnel_id ID peer_tunnel_id ID
14 [ encap { ip | udp } ]
15 [ udp_sport PORT ] [ udp_dport PORT ]
16 [ udp_csum { on | off } ]
17 [ udp6_csum_tx { on | off } ]
18 [ udp6_csum_rx { on | off } ]
19 ip l2tp add session [ name NAME ]
20 tunnel_id ID session_id ID peer_session_id ID
21 [ cookie HEXSTR ] [ peer_cookie HEXSTR ]
22 [ l2spec_type { none | default } ]
23 [ seq { none | send | recv | both } ]
24 [ offset OFFSET ] [ peer_offset OFFSET ]
25 ip l2tp del tunnel tunnel_id ID
26 ip l2tp del session tunnel_id ID session_id ID
27 ip l2tp show tunnel [ tunnel_id ID ]
28 ip l2tp show session [ tunnel_id ID.B ] [ session_id ID ]
29 NAME := STRING
30 ADDR := { IP_ADDRESS | any }
31 PORT := { NUMBER }
32 ID := { NUMBER }
33 HEXSTR := { 8 or 16 hex digits (4 / 8 bytes) }
34
36 The ip l2tp commands are used to establish static, or so-called unman‐
37 aged L2TPv3 ethernet tunnels. For unmanaged tunnels, there is no L2TP
38 control protocol so no userspace daemon is required - tunnels are manu‐
39 ally created by issuing commands at a local system and at a remote
40 peer.
41 L2TPv3 is suitable for Layer-2 tunneling. Static tunnels are useful to
43 establish network links across IP networks when the tunnels are fixed.
44 L2TPv3 tunnels can carry data of more than one session. Each session is
45 identified by a session_id and its parent tunnel's tunnel_id. A tunnel
46 must be created before a session can be created in the tunnel.
47 When creating an L2TP tunnel, the IP address of the remote peer is
49 specified, which can be either an IPv4 or IPv6 address. The local IP
50 address to be used to reach the peer must also be specified. This is
51 the address on which the local system will listen for and accept
52 received L2TP data packets from the peer.
53 L2TPv3 defines two packet encapsulation formats: UDP or IP. UDP encap‐
55 sulation is most common. IP encapsulation uses a dedicated IP protocol
56 value to carry L2TP data without the overhead of UDP. Use IP encapsula‐
57 tion only when there are no NAT devices or firewalls in the network
58 path.
59 When an L2TPv3 ethernet session is created, a virtual network interface
61 is created for the session, which must then be configured and brought
62 up, just like any other network interface. When data is passed through
63 the interface, it is carried over the L2TP tunnel to the peer. By con‐
64 figuring the system's routing tables or adding the interface to a
65 bridge, the L2TP interface is like a virtual wire (pseudowire) con‐
66 nected to the peer.
67 Establishing an unmanaged L2TPv3 ethernet pseudowire involves manually
69 creating L2TP contexts on the local system and at the peer. Parameters
70 used at each site must correspond or no data will be passed. No consis‐
71 tency checks are possible since there is no control protocol used to
72 establish unmanaged L2TP tunnels. Once the virtual network interface of
73 a given L2TP session is configured and enabled, data can be transmit‐
74 ted, even if the peer isn't yet configured. If the peer isn't config‐
75 ured, the L2TP data packets will be discarded by the peer.
76 To establish an unmanaged L2TP tunnel, use l2tp add tunnel and l2tp add
78 session commands described in this document. Then configure and enable
79 the tunnel's virtual network interface, as required.
80 Note that unmanaged tunnels carry only ethernet frames. If you need to
82 carry PPP traffic (L2TPv2) or your peer doesn't support unmanaged
83 L2TPv3 tunnels, you will need an L2TP server which implements the L2TP
84 control protocol. The L2TP control protocol allows dynamic L2TP tunnels
85 and sessions to be established and provides for detecting and acting
86 upon network failures.
87 ip l2tp add tunnel - add a new tunnel
89 tunnel_id ID
90 set the tunnel id, which is a 32-bit integer value. Uniquely
91 identifies the tunnel. The value used must match the peer_tun‐
92 nel_id value being used at the peer.
93 peer_tunnel_id ID
95 set the peer tunnel id, which is a 32-bit integer value assigned
96 to the tunnel by the peer. The value used must match the tun‐
97 nel_id value being used at the peer.
98 remote ADDR
100 set the IP address of the remote peer. May be specified as an
101 IPv4 address or an IPv6 address.
102 local ADDR
104 set the IP address of the local interface to be used for the
105 tunnel. This address must be the address of a local interface.
106 May be specified as an IPv4 address or an IPv6 address.
107 encap ENCAP
109 set the encapsulation type of the tunnel.
110 Valid values for encapsulation are: udp, ip.
111 udp_sport PORT
113 set the UDP source port to be used for the tunnel. Must be
114 present when udp encapsulation is selected. Ignored when ip
115 encapsulation is selected.
116 udp_dport PORT
118 set the UDP destination port to be used for the tunnel. Must be
119 present when udp encapsulation is selected. Ignored when ip
120 encapsulation is selected.
121 udp_csum STATE
123 (IPv4 only) control if IPv4 UDP checksums should be calculated
124 and checked for the encapsulating UDP packets, when UDP encapsu‐
125 lating is selected. Default is off.
126 Valid values are: on, off.
127 udp6_csum_tx STATE
129 (IPv6 only) control if IPv6 UDP checksums should be calculated
130 for encapsulating UDP packets, when UDP encapsulating is
131 selected. Default is on.
132 Valid values are: on, off.
133 udp6_csum_rx STATE
135 (IPv6 only) control if IPv6 UDP checksums should be checked for
136 the encapsulating UDP packets, when UDP encapsulating is
137 selected. Default is on.
138 Valid values are: on, off.
139 ip l2tp del tunnel - destroy a tunnel
141 tunnel_id ID
142 set the tunnel id of the tunnel to be deleted. All sessions
143 within the tunnel must be deleted first.
144 ip l2tp show tunnel - show information about tunnels
146 tunnel_id ID
147 set the tunnel id of the tunnel to be shown. If not specified,
148 information about all tunnels is printed.
149 ip l2tp add session - add a new session to a tunnel
151 name NAME
152 sets the session network interface name. Default is l2tpethN.
153 tunnel_id ID
155 set the tunnel id, which is a 32-bit integer value. Uniquely
156 identifies the tunnel into which the session will be created.
157 The tunnel must already exist.
158 session_id ID
160 set the session id, which is a 32-bit integer value. Uniquely
161 identifies the session being created. The value used must match
162 the peer_session_id value being used at the peer.
163 peer_session_id ID
165 set the peer session id, which is a 32-bit integer value
166 assigned to the session by the peer. The value used must match
167 the session_id value being used at the peer.
168 cookie HEXSTR
170 sets an optional cookie value to be assigned to the session.
171 This is a 4 or 8 byte value, specified as 8 or 16 hex digits,
172 e.g. 014d3636deadbeef. The value must match the peer_cookie
173 value set at the peer. The cookie value is carried in L2TP data
174 packets and is checked for expected value at the peer. Default
175 is to use no cookie.
176 peer_cookie HEXSTR
178 sets an optional peer cookie value to be assigned to the ses‐
179 sion. This is a 4 or 8 byte value, specified as 8 or 16 hex dig‐
180 its, e.g. 014d3636deadbeef. The value must match the cookie
181 value set at the peer. It tells the local system what cookie
182 value to expect to find in received L2TP packets. Default is to
183 use no cookie.
184 l2spec_type L2SPECTYPE
186 set the layer2specific header type of the session.
187 Valid values are: none, default.
188 seq SEQ
190 controls sequence numbering to prevent or detect out of order
191 packets. send puts a sequence number in the default layer2spe‐
192 cific header of each outgoing packet. recv reorder packets if
193 they are received out of order. Default is none.
194 Valid values are: none, send, recv, both.
195 offset OFFSET
197 sets the byte offset from the L2TP header where user data starts
198 in transmitted L2TP data packets. This is hardly ever used. If
199 set, the value must match the peer_offset value used at the
200 peer. Default is 0.
201 peer_offset OFFSET
203 sets the byte offset from the L2TP header where user data starts
204 in received L2TP data packets. This is hardly ever used. If set,
205 the value must match the offset value used at the peer. Default
206 is 0.
207 ip l2tp del session - destroy a session
209 tunnel_id ID
210 set the tunnel id in which the session to be deleted is located.
211 session_id ID
213 set the session id of the session to be deleted.
214 ip l2tp show session - show information about sessions
216 tunnel_id ID
217 set the tunnel id of the session(s) to be shown. If not speci‐
218 fied, information about sessions in all tunnels is printed.
219 session_id ID
221 set the session id of the session to be shown. If not specified,
222 information about all sessions is printed.
223
225 Setup L2TP tunnels and sessions
226 site-A:# ip l2tp add tunnel tunnel_id 3000 peer_tunnel_id 4000 \
227 encap udp local 1.2.3.4 remote 5.6.7.8 \
228 udp_sport 5000 udp_dport 6000
229 site-A:# ip l2tp add session tunnel_id 3000 session_id 1000 \
230 peer_session_id 2000
231 site-B:# ip l2tp add tunnel tunnel_id 4000 peer_tunnel_id 3000 \
233 encap udp local 5.6.7.8 remote 1.2.3.4 \
234 udp_sport 6000 udp_dport 5000
235 site-B:# ip l2tp add session tunnel_id 4000 session_id 2000 \
236 peer_session_id 1000
237 site-A:# ip link set l2tpeth0 up mtu 1488
239 site-B:# ip link set l2tpeth0 up mtu 1488
241 Notice that the IP addresses, UDP ports and tunnel / session ids are
243 matched and reversed at each site.
244 Configure as IP interfaces
246 The two interfaces can be configured with IP addresses if only IP data
247 is to be carried. This is perhaps the simplest configuration.
248 site-A:# ip addr add 10.42.1.1 peer 10.42.1.2 dev l2tpeth0
250 site-B:# ip addr add 10.42.1.2 peer 10.42.1.1 dev l2tpeth0
252 site-A:# ping 10.42.1.2
254 Now the link should be usable. Add static routes as needed to have data
256 sent over the new link.
257 Configure as bridged interfaces
259 To carry non-IP data, the L2TP network interface is added to a bridge
260 instead of being assigned its own IP address, using standard Linux
261 utilities. Since raw ethernet frames are then carried inside the tun‐
262 nel, the MTU of the L2TP interfaces must be set to allow space for
263 those headers.
264 site-A:# ip link set l2tpeth0 up mtu 1446
266 site-A:# ip link add br0 type bridge
267 site-A:# ip link set l2tpeth0 master br0
268 site-A:# ip link set eth0 master br0
269 site-A:# ip link set br0 up
270 If you are using VLANs, setup a bridge per VLAN and bridge each VLAN
272 over a separate L2TP session. For example, to bridge VLAN ID 5 on eth1
273 over an L2TP pseudowire:
274 site-A:# ip link set l2tpeth0 up mtu 1446
276 site-A:# ip link add brvlan5 type bridge
277 site-A:# ip link set l2tpeth0.5 master brvlan5
278 site-A:# ip link set eth1.5 master brvlan5
279 site-A:# ip link set brvlan5 up
280 Adding the L2TP interface to a bridge causes the bridge to forward
282 traffic over the L2TP pseudowire just like it forwards over any other
283 interface. The bridge learns MAC addresses of hosts attached to each
284 interface and intelligently forwards frames from one bridge port to
285 another. IP addresses are not assigned to the l2tpethN interfaces. If
286 the bridge is correctly configured at both sides of the L2TP pseu‐
287 dowire, it should be possible to reach hosts in the peer's bridged net‐
288 work.
289 When raw ethernet frames are bridged across an L2TP tunnel, large
291 frames may be fragmented and forwarded as individual IP fragments to
292 the recipient, depending on the MTU of the physical interface used by
293 the tunnel. When the ethernet frames carry protocols which are reassem‐
294 bled by the recipient, like IP, this isn't a problem. However, such
295 fragmentation can cause problems for protocols like PPPoE where the
296 recipient expects to receive ethernet frames exactly as transmitted. In
297 such cases, it is important that frames leaving the tunnel are reassem‐
298 bled back into a single frame before being forwarded on. To do so,
299 enable netfilter connection tracking (conntrack) or manually load the
300 Linux netfilter defrag modules at each tunnel endpoint.
301 site-A:# modprobe nf_defrag_ipv4
303 site-B:# modprobe nf_defrag_ipv4
305 If L2TP is being used over IPv6, use the IPv6 defrag module.
307
309 Unmanaged (static) L2TPv3 tunnels are supported by some network equip‐
310 ment equipment vendors such as Cisco.
311 In Linux, L2TP Hello messages are not supported in unmanaged tunnels.
313 Hello messages are used by L2TP clients and servers to detect link
314 failures in order to automate tearing down and reestablishing dynamic
315 tunnels. If a non-Linux peer supports Hello messages in unmanaged tun‐
316 nels, it must be turned off to interoperate with Linux.
317 Linux defaults to use the Default Layer2SpecificHeader type as defined
319 in the L2TPv3 protocol specification, RFC3931. This setting must be
320 consistent with that configured at the peer. Some vendor implementa‐
321 tions (e.g. Cisco) default to use a Layer2SpecificHeader type of None.
322
324 ip(8)
325
327 James Chapman <jchapman@katalix.com>
328iproute2 19 Apr 2012 IP-L2TP(8)