1 .. SPDX-License-Identifier: GPL-2.0
2
3 ====
4 L2TP
5 ====
6
7 Layer 2 Tunneling Protocol (L2TP) allows L2 frames to be tunneled over
8 an IP network.
9
10 This document covers the kernel's L2TP subsystem. It documents kernel
11 APIs for application developers who want to use the L2TP subsystem and
12 it provides some technical details about the internal implementation
13 which may be useful to kernel developers and maintainers.
14
15 Overview
16 ========
17
18 The kernel's L2TP subsystem implements the datapath for L2TPv2 and
19 L2TPv3. L2TPv2 is carried over UDP. L2TPv3 is carried over UDP or
20 directly over IP (protocol 115).
21
22 The L2TP RFCs define two basic kinds of L2TP packets: control packets
23 (the "control plane"), and data packets (the "data plane"). The kernel
24 deals only with data packets. The more complex control packets are
25 handled by user space.
26
27 An L2TP tunnel carries one or more L2TP sessions. Each tunnel is
28 associated with a socket. Each session is associated with a virtual
29 netdevice, e.g. ``pppN``, ``l2tpethN``, through which data frames pass
30 to/from L2TP. Fields in the L2TP header identify the tunnel or session
31 and whether it is a control or data packet. When tunnels and sessions
32 are set up using the Linux kernel API, we're just setting up the L2TP
33 data path. All aspects of the control protocol are to be handled by
34 user space.
35
36 This split in responsibilities leads to a natural sequence of
37 operations when establishing tunnels and sessions. The procedure looks
38 like this:
39
40 1) Create a tunnel socket. Exchange L2TP control protocol messages
41 with the peer over that socket in order to establish a tunnel.
42
43 2) Create a tunnel context in the kernel, using information
44 obtained from the peer using the control protocol messages.
45
46 3) Exchange L2TP control protocol messages with the peer over the
47 tunnel socket in order to establish a session.
48
49 4) Create a session context in the kernel using information
50 obtained from the peer using the control protocol messages.
51
52 L2TP APIs
53 =========
54
55 This section documents each userspace API of the L2TP subsystem.
56
57 Tunnel Sockets
58 --------------
59
60 L2TPv2 always uses UDP. L2TPv3 may use UDP or IP encapsulation.
61
62 To create a tunnel socket for use by L2TP, the standard POSIX
63 socket API is used.
64
65 For example, for a tunnel using IPv4 addresses and UDP encapsulation::
66
67 int sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
68
69 Or for a tunnel using IPv6 addresses and IP encapsulation::
70
71 int sockfd = socket(AF_INET6, SOCK_DGRAM, IPPROTO_L2TP);
72
73 UDP socket programming doesn't need to be covered here.
74
75 IPPROTO_L2TP is an IP protocol type implemented by the kernel's L2TP
76 subsystem. The L2TPIP socket address is defined in struct
77 sockaddr_l2tpip and struct sockaddr_l2tpip6 at
78 `include/uapi/linux/l2tp.h`_. The address includes the L2TP tunnel
79 (connection) id. To use L2TP IP encapsulation, an L2TPv3 application
80 should bind the L2TPIP socket using the locally assigned
81 tunnel id. When the peer's tunnel id and IP address is known, a
82 connect must be done.
83
84 If the L2TP application needs to handle L2TPv3 tunnel setup requests
85 from peers using L2TPIP, it must open a dedicated L2TPIP
86 socket to listen for those requests and bind the socket using tunnel
87 id 0 since tunnel setup requests are addressed to tunnel id 0.
88
89 An L2TP tunnel and all of its sessions are automatically closed when
90 its tunnel socket is closed.
91
92 Netlink API
93 -----------
94
95 L2TP applications use netlink to manage L2TP tunnel and session
96 instances in the kernel. The L2TP netlink API is defined in
97 `include/uapi/linux/l2tp.h`_.
98
99 L2TP uses `Generic Netlink`_ (GENL). Several commands are defined:
100 Create, Delete, Modify and Get for tunnel and session
101 instances, e.g. ``L2TP_CMD_TUNNEL_CREATE``. The API header lists the
102 netlink attribute types that can be used with each command.
103
104 Tunnel and session instances are identified by a locally unique
105 32-bit id. L2TP tunnel ids are given by ``L2TP_ATTR_CONN_ID`` and
106 ``L2TP_ATTR_PEER_CONN_ID`` attributes and L2TP session ids are given
107 by ``L2TP_ATTR_SESSION_ID`` and ``L2TP_ATTR_PEER_SESSION_ID``
108 attributes. If netlink is used to manage L2TPv2 tunnel and session
109 instances, the L2TPv2 16-bit tunnel/session id is cast to a 32-bit
110 value in these attributes.
111
112 In the ``L2TP_CMD_TUNNEL_CREATE`` command, ``L2TP_ATTR_FD`` tells the
113 kernel the tunnel socket fd being used. If not specified, the kernel
114 creates a kernel socket for the tunnel, using IP parameters set in
115 ``L2TP_ATTR_IP[6]_SADDR``, ``L2TP_ATTR_IP[6]_DADDR``,
116 ``L2TP_ATTR_UDP_SPORT``, ``L2TP_ATTR_UDP_DPORT`` attributes. Kernel
117 sockets are used to implement unmanaged L2TPv3 tunnels (iproute2's "ip
118 l2tp" commands). If ``L2TP_ATTR_FD`` is given, it must be a socket fd
119 that is already bound and connected. There is more information about
120 unmanaged tunnels later in this document.
121
122 ``L2TP_CMD_TUNNEL_CREATE`` attributes:-
123
124 ================== ======== ===
125 Attribute Required Use
126 ================== ======== ===
127 CONN_ID Y Sets the tunnel (connection) id.
128 PEER_CONN_ID Y Sets the peer tunnel (connection) id.
129 PROTO_VERSION Y Protocol version. 2 or 3.
130 ENCAP_TYPE Y Encapsulation type: UDP or IP.
131 FD N Tunnel socket file descriptor.
132 UDP_CSUM N Enable IPv4 UDP checksums. Used only if FD is
133 not set.
134 UDP_ZERO_CSUM6_TX N Zero IPv6 UDP checksum on transmit. Used only
135 if FD is not set.
136 UDP_ZERO_CSUM6_RX N Zero IPv6 UDP checksum on receive. Used only if
137 FD is not set.
138 IP_SADDR N IPv4 source address. Used only if FD is not
139 set.
140 IP_DADDR N IPv4 destination address. Used only if FD is
141 not set.
142 UDP_SPORT N UDP source port. Used only if FD is not set.
143 UDP_DPORT N UDP destination port. Used only if FD is not
144 set.
145 IP6_SADDR N IPv6 source address. Used only if FD is not
146 set.
147 IP6_DADDR N IPv6 destination address. Used only if FD is
148 not set.
149 DEBUG N Debug flags.
150 ================== ======== ===
151
152 ``L2TP_CMD_TUNNEL_DESTROY`` attributes:-
153
154 ================== ======== ===
155 Attribute Required Use
156 ================== ======== ===
157 CONN_ID Y Identifies the tunnel id to be destroyed.
158 ================== ======== ===
159
160 ``L2TP_CMD_TUNNEL_MODIFY`` attributes:-
161
162 ================== ======== ===
163 Attribute Required Use
164 ================== ======== ===
165 CONN_ID Y Identifies the tunnel id to be modified.
166 DEBUG N Debug flags.
167 ================== ======== ===
168
169 ``L2TP_CMD_TUNNEL_GET`` attributes:-
170
171 ================== ======== ===
172 Attribute Required Use
173 ================== ======== ===
174 CONN_ID N Identifies the tunnel id to be queried.
175 Ignored in DUMP requests.
176 ================== ======== ===
177
178 ``L2TP_CMD_SESSION_CREATE`` attributes:-
179
180 ================== ======== ===
181 Attribute Required Use
182 ================== ======== ===
183 CONN_ID Y The parent tunnel id.
184 SESSION_ID Y Sets the session id.
185 PEER_SESSION_ID Y Sets the parent session id.
186 PW_TYPE Y Sets the pseudowire type.
187 DEBUG N Debug flags.
188 RECV_SEQ N Enable rx data sequence numbers.
189 SEND_SEQ N Enable tx data sequence numbers.
190 LNS_MODE N Enable LNS mode (auto-enable data sequence
191 numbers).
192 RECV_TIMEOUT N Timeout to wait when reordering received
193 packets.
194 L2SPEC_TYPE N Sets layer2-specific-sublayer type (L2TPv3
195 only).
196 COOKIE N Sets optional cookie (L2TPv3 only).
197 PEER_COOKIE N Sets optional peer cookie (L2TPv3 only).
198 IFNAME N Sets interface name (L2TPv3 only).
199 ================== ======== ===
200
201 For Ethernet session types, this will create an l2tpeth virtual
202 interface which can then be configured as required. For PPP session
203 types, a PPPoL2TP socket must also be opened and connected, mapping it
204 onto the new session. This is covered in "PPPoL2TP Sockets" later.
205
206 ``L2TP_CMD_SESSION_DESTROY`` attributes:-
207
208 ================== ======== ===
209 Attribute Required Use
210 ================== ======== ===
211 CONN_ID Y Identifies the parent tunnel id of the session
212 to be destroyed.
213 SESSION_ID Y Identifies the session id to be destroyed.
214 IFNAME N Identifies the session by interface name. If
215 set, this overrides any CONN_ID and SESSION_ID
216 attributes. Currently supported for L2TPv3
217 Ethernet sessions only.
218 ================== ======== ===
219
220 ``L2TP_CMD_SESSION_MODIFY`` attributes:-
221
222 ================== ======== ===
223 Attribute Required Use
224 ================== ======== ===
225 CONN_ID Y Identifies the parent tunnel id of the session
226 to be modified.
227 SESSION_ID Y Identifies the session id to be modified.
228 IFNAME N Identifies the session by interface name. If
229 set, this overrides any CONN_ID and SESSION_ID
230 attributes. Currently supported for L2TPv3
231 Ethernet sessions only.
232 DEBUG N Debug flags.
233 RECV_SEQ N Enable rx data sequence numbers.
234 SEND_SEQ N Enable tx data sequence numbers.
235 LNS_MODE N Enable LNS mode (auto-enable data sequence
236 numbers).
237 RECV_TIMEOUT N Timeout to wait when reordering received
238 packets.
239 ================== ======== ===
240
241 ``L2TP_CMD_SESSION_GET`` attributes:-
242
243 ================== ======== ===
244 Attribute Required Use
245 ================== ======== ===
246 CONN_ID N Identifies the tunnel id to be queried.
247 Ignored for DUMP requests.
248 SESSION_ID N Identifies the session id to be queried.
249 Ignored for DUMP requests.
250 IFNAME N Identifies the session by interface name.
251 If set, this overrides any CONN_ID and
252 SESSION_ID attributes. Ignored for DUMP
253 requests. Currently supported for L2TPv3
254 Ethernet sessions only.
255 ================== ======== ===
256
257 Application developers should refer to `include/uapi/linux/l2tp.h`_ for
258 netlink command and attribute definitions.
259
260 Sample userspace code using libmnl_:
261
262 - Open L2TP netlink socket::
263
264 struct nl_sock *nl_sock;
265 int l2tp_nl_family_id;
266
267 nl_sock = nl_socket_alloc();
268 genl_connect(nl_sock);
269 genl_id = genl_ctrl_resolve(nl_sock, L2TP_GENL_NAME);
270
271 - Create a tunnel::
272
273 struct nlmsghdr *nlh;
274 struct genlmsghdr *gnlh;
275
276 nlh = mnl_nlmsg_put_header(buf);
277 nlh->nlmsg_type = genl_id; /* assigned to genl socket */
278 nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK;
279 nlh->nlmsg_seq = seq;
280
281 gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh));
282 gnlh->cmd = L2TP_CMD_TUNNEL_CREATE;
283 gnlh->version = L2TP_GENL_VERSION;
284 gnlh->reserved = 0;
285
286 mnl_attr_put_u32(nlh, L2TP_ATTR_FD, tunl_sock_fd);
287 mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid);
288 mnl_attr_put_u32(nlh, L2TP_ATTR_PEER_CONN_ID, peer_tid);
289 mnl_attr_put_u8(nlh, L2TP_ATTR_PROTO_VERSION, protocol_version);
290 mnl_attr_put_u16(nlh, L2TP_ATTR_ENCAP_TYPE, encap);
291
292 - Create a session::
293
294 struct nlmsghdr *nlh;
295 struct genlmsghdr *gnlh;
296
297 nlh = mnl_nlmsg_put_header(buf);
298 nlh->nlmsg_type = genl_id; /* assigned to genl socket */
299 nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK;
300 nlh->nlmsg_seq = seq;
301
302 gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh));
303 gnlh->cmd = L2TP_CMD_SESSION_CREATE;
304 gnlh->version = L2TP_GENL_VERSION;
305 gnlh->reserved = 0;
306
307 mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid);
308 mnl_attr_put_u32(nlh, L2TP_ATTR_PEER_CONN_ID, peer_tid);
309 mnl_attr_put_u32(nlh, L2TP_ATTR_SESSION_ID, sid);
310 mnl_attr_put_u32(nlh, L2TP_ATTR_PEER_SESSION_ID, peer_sid);
311 mnl_attr_put_u16(nlh, L2TP_ATTR_PW_TYPE, pwtype);
312 /* there are other session options which can be set using netlink
313 * attributes during session creation -- see l2tp.h
314 */
315
316 - Delete a session::
317
318 struct nlmsghdr *nlh;
319 struct genlmsghdr *gnlh;
320
321 nlh = mnl_nlmsg_put_header(buf);
322 nlh->nlmsg_type = genl_id; /* assigned to genl socket */
323 nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK;
324 nlh->nlmsg_seq = seq;
325
326 gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh));
327 gnlh->cmd = L2TP_CMD_SESSION_DELETE;
328 gnlh->version = L2TP_GENL_VERSION;
329 gnlh->reserved = 0;
330
331 mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid);
332 mnl_attr_put_u32(nlh, L2TP_ATTR_SESSION_ID, sid);
333
334 - Delete a tunnel and all of its sessions (if any)::
335
336 struct nlmsghdr *nlh;
337 struct genlmsghdr *gnlh;
338
339 nlh = mnl_nlmsg_put_header(buf);
340 nlh->nlmsg_type = genl_id; /* assigned to genl socket */
341 nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK;
342 nlh->nlmsg_seq = seq;
343
344 gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh));
345 gnlh->cmd = L2TP_CMD_TUNNEL_DELETE;
346 gnlh->version = L2TP_GENL_VERSION;
347 gnlh->reserved = 0;
348
349 mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid);
350
351 PPPoL2TP Session Socket API
352 ---------------------------
353
354 For PPP session types, a PPPoL2TP socket must be opened and connected
355 to the L2TP session.
356
357 When creating PPPoL2TP sockets, the application provides information
358 to the kernel about the tunnel and session in a socket connect()
359 call. Source and destination tunnel and session ids are provided, as
360 well as the file descriptor of a UDP or L2TPIP socket. See struct
361 pppol2tp_addr in `include/linux/if_pppol2tp.h`_. For historical reasons,
362 there are unfortunately slightly different address structures for
363 L2TPv2/L2TPv3 IPv4/IPv6 tunnels and userspace must use the appropriate
364 structure that matches the tunnel socket type.
365
366 Userspace may control behavior of the tunnel or session using
367 setsockopt and ioctl on the PPPoX socket. The following socket
368 options are supported:-
369
370 ========= ===========================================================
371 DEBUG bitmask of debug message categories. See below.
372 SENDSEQ - 0 => don't send packets with sequence numbers
373 - 1 => send packets with sequence numbers
374 RECVSEQ - 0 => receive packet sequence numbers are optional
375 - 1 => drop receive packets without sequence numbers
376 LNSMODE - 0 => act as LAC.
377 - 1 => act as LNS.
378 REORDERTO reorder timeout (in millisecs). If 0, don't try to reorder.
379 ========= ===========================================================
380
381 In addition to the standard PPP ioctls, a PPPIOCGL2TPSTATS is provided
382 to retrieve tunnel and session statistics from the kernel using the
383 PPPoX socket of the appropriate tunnel or session.
384
385 Sample userspace code:
386
387 - Create session PPPoX data socket::
388
389 /* Input: the L2TP tunnel UDP socket `tunnel_fd`, which needs to be
390 * bound already (both sockname and peername), otherwise it will not be
391 * ready.
392 */
393
394 struct sockaddr_pppol2tp sax;
395 int session_fd;
396 int ret;
397
398 session_fd = socket(AF_PPPOX, SOCK_DGRAM, PX_PROTO_OL2TP);
399 if (session_fd < 0)
400 return -errno;
401
402 sax.sa_family = AF_PPPOX;
403 sax.sa_protocol = PX_PROTO_OL2TP;
404 sax.pppol2tp.fd = tunnel_fd;
405 sax.pppol2tp.addr.sin_addr.s_addr = addr->sin_addr.s_addr;
406 sax.pppol2tp.addr.sin_port = addr->sin_port;
407 sax.pppol2tp.addr.sin_family = AF_INET;
408 sax.pppol2tp.s_tunnel = tunnel_id;
409 sax.pppol2tp.s_session = session_id;
410 sax.pppol2tp.d_tunnel = peer_tunnel_id;
411 sax.pppol2tp.d_session = peer_session_id;
412
413 /* session_fd is the fd of the session's PPPoL2TP socket.
414 * tunnel_fd is the fd of the tunnel UDP / L2TPIP socket.
415 */
416 ret = connect(session_fd, (struct sockaddr *)&sax, sizeof(sax));
417 if (ret < 0 ) {
418 close(session_fd);
419 return -errno;
420 }
421
422 return session_fd;
423
424 L2TP control packets will still be available for read on `tunnel_fd`.
425
426 - Create PPP channel::
427
428 /* Input: the session PPPoX data socket `session_fd` which was created
429 * as described above.
430 */
431
432 int ppp_chan_fd;
433 int chindx;
434 int ret;
435
436 ret = ioctl(session_fd, PPPIOCGCHAN, &chindx);
437 if (ret < 0)
438 return -errno;
439
440 ppp_chan_fd = open("/dev/ppp", O_RDWR);
441 if (ppp_chan_fd < 0)
442 return -errno;
443
444 ret = ioctl(ppp_chan_fd, PPPIOCATTCHAN, &chindx);
445 if (ret < 0) {
446 close(ppp_chan_fd);
447 return -errno;
448 }
449
450 return ppp_chan_fd;
451
452 LCP PPP frames will be available for read on `ppp_chan_fd`.
453
454 - Create PPP interface::
455
456 /* Input: the PPP channel `ppp_chan_fd` which was created as described
457 * above.
458 */
459
460 int ifunit = -1;
461 int ppp_if_fd;
462 int ret;
463
464 ppp_if_fd = open("/dev/ppp", O_RDWR);
465 if (ppp_if_fd < 0)
466 return -errno;
467
468 ret = ioctl(ppp_if_fd, PPPIOCNEWUNIT, &ifunit);
469 if (ret < 0) {
470 close(ppp_if_fd);
471 return -errno;
472 }
473
474 ret = ioctl(ppp_chan_fd, PPPIOCCONNECT, &ifunit);
475 if (ret < 0) {
476 close(ppp_if_fd);
477 return -errno;
478 }
479
480 return ppp_if_fd;
481
482 IPCP/IPv6CP PPP frames will be available for read on `ppp_if_fd`.
483
484 The ppp<ifunit> interface can then be configured as usual with netlink's
485 RTM_NEWLINK, RTM_NEWADDR, RTM_NEWROUTE, or ioctl's SIOCSIFMTU, SIOCSIFADDR,
486 SIOCSIFDSTADDR, SIOCSIFNETMASK, SIOCSIFFLAGS, or with the `ip` command.
487
488 - Bridging L2TP sessions which have PPP pseudowire types (this is also called
489 L2TP tunnel switching or L2TP multihop) is supported by bridging the PPP
490 channels of the two L2TP sessions to be bridged::
491
492 /* Input: the session PPPoX data sockets `session_fd1` and `session_fd2`
493 * which were created as described further above.
494 */
495
496 int ppp_chan_fd;
497 int chindx1;
498 int chindx2;
499 int ret;
500
501 ret = ioctl(session_fd1, PPPIOCGCHAN, &chindx1);
502 if (ret < 0)
503 return -errno;
504
505 ret = ioctl(session_fd2, PPPIOCGCHAN, &chindx2);
506 if (ret < 0)
507 return -errno;
508
509 ppp_chan_fd = open("/dev/ppp", O_RDWR);
510 if (ppp_chan_fd < 0)
511 return -errno;
512
513 ret = ioctl(ppp_chan_fd, PPPIOCATTCHAN, &chindx1);
514 if (ret < 0) {
515 close(ppp_chan_fd);
516 return -errno;
517 }
518
519 ret = ioctl(ppp_chan_fd, PPPIOCBRIDGECHAN, &chindx2);
520 close(ppp_chan_fd);
521 if (ret < 0)
522 return -errno;
523
524 return 0;
525
526 It can be noted that when bridging PPP channels, the PPP session is not locally
527 terminated, and no local PPP interface is created. PPP frames arriving on one
528 channel are directly passed to the other channel, and vice versa.
529
530 The PPP channel does not need to be kept open. Only the session PPPoX data
531 sockets need to be kept open.
532
533 More generally, it is also possible in the same way to e.g. bridge a PPPoL2TP
534 PPP channel with other types of PPP channels, such as PPPoE.
535
536 See more details for the PPP side in ppp_generic.rst.
537
538 Old L2TPv2-only API
539 -------------------
540
541 When L2TP was first added to the Linux kernel in 2.6.23, it
542 implemented only L2TPv2 and did not include a netlink API. Instead,
543 tunnel and session instances in the kernel were managed directly using
544 only PPPoL2TP sockets. The PPPoL2TP socket is used as described in
545 section "PPPoL2TP Session Socket API" but tunnel and session instances
546 are automatically created on a connect() of the socket instead of
547 being created by a separate netlink request:
548
549 - Tunnels are managed using a tunnel management socket which is a
550 dedicated PPPoL2TP socket, connected to (invalid) session
551 id 0. The L2TP tunnel instance is created when the PPPoL2TP
552 tunnel management socket is connected and is destroyed when the
553 socket is closed.
554
555 - Session instances are created in the kernel when a PPPoL2TP
556 socket is connected to a non-zero session id. Session parameters
557 are set using setsockopt. The L2TP session instance is destroyed
558 when the socket is closed.
559
560 This API is still supported but its use is discouraged. Instead, new
561 L2TPv2 applications should use netlink to first create the tunnel and
562 session, then create a PPPoL2TP socket for the session.
563
564 Unmanaged L2TPv3 tunnels
565 ------------------------
566
567 The kernel L2TP subsystem also supports static (unmanaged) L2TPv3
568 tunnels. Unmanaged tunnels have no userspace tunnel socket, and
569 exchange no control messages with the peer to set up the tunnel; the
570 tunnel is configured manually at each end of the tunnel. All
571 configuration is done using netlink. There is no need for an L2TP
572 userspace application in this case -- the tunnel socket is created by
573 the kernel and configured using parameters sent in the
574 ``L2TP_CMD_TUNNEL_CREATE`` netlink request. The ``ip`` utility of
575 ``iproute2`` has commands for managing static L2TPv3 tunnels; do ``ip
576 l2tp help`` for more information.
577
578 Debugging
579 ---------
580
581 The L2TP subsystem offers a range of debugging interfaces through the
582 debugfs filesystem.
583
584 To access these interfaces, the debugfs filesystem must first be mounted::
585
586 # mount -t debugfs debugfs /debug
587
588 Files under the l2tp directory can then be accessed, providing a summary
589 of the current population of tunnel and session contexts existing in the
590 kernel::
591
592 # cat /debug/l2tp/tunnels
593
594 The debugfs files should not be used by applications to obtain L2TP
595 state information because the file format is subject to change. It is
596 implemented to provide extra debug information to help diagnose
597 problems. Applications should instead use the netlink API.
598
599 In addition the L2TP subsystem implements tracepoints using the standard
600 kernel event tracing API. The available L2TP events can be reviewed as
601 follows::
602
603 # find /debug/tracing/events/l2tp
604
605 Finally, /proc/net/pppol2tp is also provided for backwards compatibility
606 with the original pppol2tp code. It lists information about L2TPv2
607 tunnels and sessions only. Its use is discouraged.
608
609 Internal Implementation
610 =======================
611
612 This section is for kernel developers and maintainers.
613
614 Sockets
615 -------
616
617 UDP sockets are implemented by the networking core. When an L2TP
618 tunnel is created using a UDP socket, the socket is set up as an
619 encapsulated UDP socket by setting encap_rcv and encap_destroy
620 callbacks on the UDP socket. l2tp_udp_encap_recv is called when
621 packets are received on the socket. l2tp_udp_encap_destroy is called
622 when userspace closes the socket.
623
624 L2TPIP sockets are implemented in `net/l2tp/l2tp_ip.c`_ and
625 `net/l2tp/l2tp_ip6.c`_.
626
627 Tunnels
628 -------
629
630 The kernel keeps a struct l2tp_tunnel context per L2TP tunnel. The
631 l2tp_tunnel is always associated with a UDP or L2TP/IP socket and
632 keeps a list of sessions in the tunnel. When a tunnel is first
633 registered with L2TP core, the reference count on the socket is
634 increased. This ensures that the socket cannot be removed while L2TP's
635 data structures reference it.
636
637 Tunnels are identified by a unique tunnel id. The id is 16-bit for
638 L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit
639 value.
640
641 Tunnels are kept in a per-net list, indexed by tunnel id. The tunnel
642 id namespace is shared by L2TPv2 and L2TPv3. The tunnel context can be
643 derived from the socket's sk_user_data.
644
645 Handling tunnel socket close is perhaps the most tricky part of the
646 L2TP implementation. If userspace closes a tunnel socket, the L2TP
647 tunnel and all of its sessions must be closed and destroyed. Since the
648 tunnel context holds a ref on the tunnel socket, the socket's
649 sk_destruct won't be called until the tunnel sock_put's its
650 socket. For UDP sockets, when userspace closes the tunnel socket, the
651 socket's encap_destroy handler is invoked, which L2TP uses to initiate
652 its tunnel close actions. For L2TPIP sockets, the socket's close
653 handler initiates the same tunnel close actions. All sessions are
654 first closed. Each session drops its tunnel ref. When the tunnel ref
655 reaches zero, the tunnel puts its socket ref. When the socket is
656 eventually destroyed, its sk_destruct finally frees the L2TP tunnel
657 context.
658
659 Sessions
660 --------
661
662 The kernel keeps a struct l2tp_session context for each session. Each
663 session has private data which is used for data specific to the
664 session type. With L2TPv2, the session always carries PPP
665 traffic. With L2TPv3, the session can carry Ethernet frames (Ethernet
666 pseudowire) or other data types such as PPP, ATM, HDLC or Frame
667 Relay. Linux currently implements only Ethernet and PPP session types.
668
669 Some L2TP session types also have a socket (PPP pseudowires) while
670 others do not (Ethernet pseudowires). We can't therefore use the
671 socket reference count as the reference count for session
672 contexts. The L2TP implementation therefore has its own internal
673 reference counts on the session contexts.
674
675 Like tunnels, L2TP sessions are identified by a unique
676 session id. Just as with tunnel ids, the session id is 16-bit for
677 L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit
678 value.
679
680 Sessions hold a ref on their parent tunnel to ensure that the tunnel
681 stays extant while one or more sessions references it.
682
683 Sessions are kept in a per-tunnel list, indexed by session id. L2TPv3
684 sessions are also kept in a per-net list indexed by session id,
685 because L2TPv3 session ids are unique across all tunnels and L2TPv3
686 data packets do not contain a tunnel id in the header. This list is
687 therefore needed to find the session context associated with a
688 received data packet when the tunnel context cannot be derived from
689 the tunnel socket.
690
691 Although the L2TPv3 RFC specifies that L2TPv3 session ids are not
692 scoped by the tunnel, the kernel does not police this for L2TPv3 UDP
693 tunnels and does not add sessions of L2TPv3 UDP tunnels into the
694 per-net session list. In the UDP receive code, we must trust that the
695 tunnel can be identified using the tunnel socket's sk_user_data and
696 lookup the session in the tunnel's session list instead of the per-net
697 session list.
698
699 PPP
700 ---
701
702 `net/l2tp/l2tp_ppp.c`_ implements the PPPoL2TP socket family. Each PPP
703 session has a PPPoL2TP socket.
704
705 The PPPoL2TP socket's sk_user_data references the l2tp_session.
706
707 Userspace sends and receives PPP packets over L2TP using a PPPoL2TP
708 socket. Only PPP control frames pass over this socket: PPP data
709 packets are handled entirely by the kernel, passing between the L2TP
710 session and its associated ``pppN`` netdev through the PPP channel
711 interface of the kernel PPP subsystem.
712
713 The L2TP PPP implementation handles the closing of a PPPoL2TP socket
714 by closing its corresponding L2TP session. This is complicated because
715 it must consider racing with netlink session create/destroy requests
716 and pppol2tp_connect trying to reconnect with a session that is in the
717 process of being closed. Unlike tunnels, PPP sessions do not hold a
718 ref on their associated socket, so code must be careful to sock_hold
719 the socket where necessary. For all the details, see commit
720 3d609342cc04129ff7568e19316ce3d7451a27e8.
721
722 Ethernet
723 --------
724
725 `net/l2tp/l2tp_eth.c`_ implements L2TPv3 Ethernet pseudowires. It
726 manages a netdev for each session.
727
728 L2TP Ethernet sessions are created and destroyed by netlink request,
729 or are destroyed when the tunnel is destroyed. Unlike PPP sessions,
730 Ethernet sessions do not have an associated socket.
731
732 Miscellaneous
733 =============
734
735 RFCs
736 ----
737
738 The kernel code implements the datapath features specified in the
739 following RFCs:
740
741 ======= =============== ===================================
742 RFC2661 L2TPv2 https://tools.ietf.org/html/rfc2661
743 RFC3931 L2TPv3 https://tools.ietf.org/html/rfc3931
744 RFC4719 L2TPv3 Ethernet https://tools.ietf.org/html/rfc4719
745 ======= =============== ===================================
746
747 Implementations
748 ---------------
749
750 A number of open source applications use the L2TP kernel subsystem:
751
752 ============ ==============================================
753 iproute2 https://github.com/shemminger/iproute2
754 go-l2tp https://github.com/katalix/go-l2tp
755 tunneldigger https://github.com/wlanslovenija/tunneldigger
756 xl2tpd https://github.com/xelerance/xl2tpd
757 ============ ==============================================
758
759 Limitations
760 -----------
761
762 The current implementation has a number of limitations:
763
764 1) Multiple UDP sockets with the same 5-tuple address cannot be
765 used. The kernel's tunnel context is identified using private
766 data associated with the socket so it is important that each
767 socket is uniquely identified by its address.
768
769 2) Interfacing with openvswitch is not yet implemented. It may be
770 useful to map OVS Ethernet and VLAN ports into L2TPv3 tunnels.
771
772 3) VLAN pseudowires are implemented using an ``l2tpethN`` interface
773 configured with a VLAN sub-interface. Since L2TPv3 VLAN
774 pseudowires carry one and only one VLAN, it may be better to use
775 a single netdevice rather than an ``l2tpethN`` and ``l2tpethN``:M
776 pair per VLAN session. The netlink attribute
777 ``L2TP_ATTR_VLAN_ID`` was added for this, but it was never
778 implemented.
779
780 Testing
781 -------
782
783 Unmanaged L2TPv3 Ethernet features are tested by the kernel's built-in
784 selftests. See `tools/testing/selftests/net/l2tp.sh`_.
785
786 Another test suite, l2tp-ktest_, covers all
787 of the L2TP APIs and tunnel/session types. This may be integrated into
788 the kernel's built-in L2TP selftests in the future.
789
790 .. Links
791 .. _Generic Netlink: generic_netlink.html
792 .. _libmnl: https://www.netfilter.org/projects/libmnl
793 .. _include/uapi/linux/l2tp.h: ../../../include/uapi/linux/l2tp.h
794 .. _include/linux/if_pppol2tp.h: ../../../include/linux/if_pppol2tp.h
795 .. _net/l2tp/l2tp_ip.c: ../../../net/l2tp/l2tp_ip.c
796 .. _net/l2tp/l2tp_ip6.c: ../../../net/l2tp/l2tp_ip6.c
797 .. _net/l2tp/l2tp_ppp.c: ../../../net/l2tp/l2tp_ppp.c
798 .. _net/l2tp/l2tp_eth.c: ../../../net/l2tp/l2tp_eth.c
799 .. _tools/testing/selftests/net/l2tp.sh: ../../../tools/testing/selftests/net/l2tp.sh
800 .. _l2tp-ktest: https://github.com/katalix/l2tp-ktest
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.