1.. SPDX-License-Identifier: GPL-2.0
2
3====
4L2TP
5====
6
7Layer 2 Tunneling Protocol (L2TP) allows L2 frames to be tunneled over
8an IP network.
9
10This document covers the kernel's L2TP subsystem. It documents kernel
11APIs for application developers who want to use the L2TP subsystem and
12it provides some technical details about the internal implementation
13which may be useful to kernel developers and maintainers.
14
15Overview
16========
17
18The kernel's L2TP subsystem implements the datapath for L2TPv2 and
19L2TPv3. L2TPv2 is carried over UDP. L2TPv3 is carried over UDP or
20directly over IP (protocol 115).
21
22The L2TP RFCs define two basic kinds of L2TP packets: control packets
23(the "control plane"), and data packets (the "data plane"). The kernel
24deals only with data packets. The more complex control packets are
25handled by user space.
26
27An L2TP tunnel carries one or more L2TP sessions. Each tunnel is
28associated with a socket. Each session is associated with a virtual
29netdevice, e.g. ``pppN``, ``l2tpethN``, through which data frames pass
30to/from L2TP. Fields in the L2TP header identify the tunnel or session
31and whether it is a control or data packet. When tunnels and sessions
32are set up using the Linux kernel API, we're just setting up the L2TP
33data path. All aspects of the control protocol are to be handled by
34user space.
35
36This split in responsibilities leads to a natural sequence of
37operations when establishing tunnels and sessions. The procedure looks
38like 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
52L2TP APIs
53=========
54
55This section documents each userspace API of the L2TP subsystem.
56
57Tunnel Sockets
58--------------
59
60L2TPv2 always uses UDP. L2TPv3 may use UDP or IP encapsulation.
61
62To create a tunnel socket for use by L2TP, the standard POSIX
63socket API is used.
64
65For example, for a tunnel using IPv4 addresses and UDP encapsulation::
66
67    int sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
68
69Or for a tunnel using IPv6 addresses and IP encapsulation::
70
71    int sockfd = socket(AF_INET6, SOCK_DGRAM, IPPROTO_L2TP);
72
73UDP socket programming doesn't need to be covered here.
74
75IPPROTO_L2TP is an IP protocol type implemented by the kernel's L2TP
76subsystem. The L2TPIP socket address is defined in struct
77sockaddr_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
80should bind the L2TPIP socket using the locally assigned
81tunnel id. When the peer's tunnel id and IP address is known, a
82connect must be done.
83
84If the L2TP application needs to handle L2TPv3 tunnel setup requests
85from peers using L2TPIP, it must open a dedicated L2TPIP
86socket to listen for those requests and bind the socket using tunnel
87id 0 since tunnel setup requests are addressed to tunnel id 0.
88
89An L2TP tunnel and all of its sessions are automatically closed when
90its tunnel socket is closed.
91
92Netlink API
93-----------
94
95L2TP applications use netlink to manage L2TP tunnel and session
96instances in the kernel. The L2TP netlink API is defined in
97`include/uapi/linux/l2tp.h`_.
98
99L2TP uses `Generic Netlink`_ (GENL). Several commands are defined:
100Create, Delete, Modify and Get for tunnel and session
101instances, e.g. ``L2TP_CMD_TUNNEL_CREATE``. The API header lists the
102netlink attribute types that can be used with each command.
103
104Tunnel and session instances are identified by a locally unique
10532-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
107by ``L2TP_ATTR_SESSION_ID`` and ``L2TP_ATTR_PEER_SESSION_ID``
108attributes. If netlink is used to manage L2TPv2 tunnel and session
109instances, the L2TPv2 16-bit tunnel/session id is cast to a 32-bit
110value in these attributes.
111
112In the ``L2TP_CMD_TUNNEL_CREATE`` command, ``L2TP_ATTR_FD`` tells the
113kernel the tunnel socket fd being used. If not specified, the kernel
114creates 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
117sockets are used to implement unmanaged L2TPv3 tunnels (iproute2's "ip
118l2tp" commands). If ``L2TP_ATTR_FD`` is given, it must be a socket fd
119that is already bound and connected. There is more information about
120unmanaged tunnels later in this document.
121
122``L2TP_CMD_TUNNEL_CREATE`` attributes:-
123
124================== ======== ===
125Attribute          Required Use
126================== ======== ===
127CONN_ID            Y        Sets the tunnel (connection) id.
128PEER_CONN_ID       Y        Sets the peer tunnel (connection) id.
129PROTO_VERSION      Y        Protocol version. 2 or 3.
130ENCAP_TYPE         Y        Encapsulation type: UDP or IP.
131FD                 N        Tunnel socket file descriptor.
132UDP_CSUM           N        Enable IPv4 UDP checksums. Used only if FD is
133                            not set.
134UDP_ZERO_CSUM6_TX  N        Zero IPv6 UDP checksum on transmit. Used only
135                            if FD is not set.
136UDP_ZERO_CSUM6_RX  N        Zero IPv6 UDP checksum on receive. Used only if
137                            FD is not set.
138IP_SADDR           N        IPv4 source address. Used only if FD is not
139                            set.
140IP_DADDR           N        IPv4 destination address. Used only if FD is
141                            not set.
142UDP_SPORT          N        UDP source port. Used only if FD is not set.
143UDP_DPORT          N        UDP destination port. Used only if FD is not
144                            set.
145IP6_SADDR          N        IPv6 source address. Used only if FD is not
146                            set.
147IP6_DADDR          N        IPv6 destination address. Used only if FD is
148                            not set.
149DEBUG              N        Debug flags.
150================== ======== ===
151
152``L2TP_CMD_TUNNEL_DESTROY`` attributes:-
153
154================== ======== ===
155Attribute          Required Use
156================== ======== ===
157CONN_ID            Y        Identifies the tunnel id to be destroyed.
158================== ======== ===
159
160``L2TP_CMD_TUNNEL_MODIFY`` attributes:-
161
162================== ======== ===
163Attribute          Required Use
164================== ======== ===
165CONN_ID            Y        Identifies the tunnel id to be modified.
166DEBUG              N        Debug flags.
167================== ======== ===
168
169``L2TP_CMD_TUNNEL_GET`` attributes:-
170
171================== ======== ===
172Attribute          Required Use
173================== ======== ===
174CONN_ID            N        Identifies the tunnel id to be queried.
175                            Ignored in DUMP requests.
176================== ======== ===
177
178``L2TP_CMD_SESSION_CREATE`` attributes:-
179
180================== ======== ===
181Attribute          Required Use
182================== ======== ===
183CONN_ID            Y        The parent tunnel id.
184SESSION_ID         Y        Sets the session id.
185PEER_SESSION_ID    Y        Sets the parent session id.
186PW_TYPE            Y        Sets the pseudowire type.
187DEBUG              N        Debug flags.
188RECV_SEQ           N        Enable rx data sequence numbers.
189SEND_SEQ           N        Enable tx data sequence numbers.
190LNS_MODE           N        Enable LNS mode (auto-enable data sequence
191                            numbers).
192RECV_TIMEOUT       N        Timeout to wait when reordering received
193                            packets.
194L2SPEC_TYPE        N        Sets layer2-specific-sublayer type (L2TPv3
195                            only).
196COOKIE             N        Sets optional cookie (L2TPv3 only).
197PEER_COOKIE        N        Sets optional peer cookie (L2TPv3 only).
198IFNAME             N        Sets interface name (L2TPv3 only).
199================== ======== ===
200
201For Ethernet session types, this will create an l2tpeth virtual
202interface which can then be configured as required. For PPP session
203types, a PPPoL2TP socket must also be opened and connected, mapping it
204onto the new session. This is covered in "PPPoL2TP Sockets" later.
205
206``L2TP_CMD_SESSION_DESTROY`` attributes:-
207
208================== ======== ===
209Attribute          Required Use
210================== ======== ===
211CONN_ID            Y        Identifies the parent tunnel id of the session
212                            to be destroyed.
213SESSION_ID         Y        Identifies the session id to be destroyed.
214IFNAME             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================== ======== ===
223Attribute          Required Use
224================== ======== ===
225CONN_ID            Y        Identifies the parent tunnel id of the session
226                            to be modified.
227SESSION_ID         Y        Identifies the session id to be modified.
228IFNAME             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.
232DEBUG              N        Debug flags.
233RECV_SEQ           N        Enable rx data sequence numbers.
234SEND_SEQ           N        Enable tx data sequence numbers.
235LNS_MODE           N        Enable LNS mode (auto-enable data sequence
236                            numbers).
237RECV_TIMEOUT       N        Timeout to wait when reordering received
238                            packets.
239================== ======== ===
240
241``L2TP_CMD_SESSION_GET`` attributes:-
242
243================== ======== ===
244Attribute          Required Use
245================== ======== ===
246CONN_ID            N        Identifies the tunnel id to be queried.
247                            Ignored for DUMP requests.
248SESSION_ID         N        Identifies the session id to be queried.
249                            Ignored for DUMP requests.
250IFNAME             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
257Application developers should refer to `include/uapi/linux/l2tp.h`_ for
258netlink command and attribute definitions.
259
260Sample 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
351PPPoL2TP Session Socket API
352---------------------------
353
354For PPP session types, a PPPoL2TP socket must be opened and connected
355to the L2TP session.
356
357When creating PPPoL2TP sockets, the application provides information
358to the kernel about the tunnel and session in a socket connect()
359call. Source and destination tunnel and session ids are provided, as
360well as the file descriptor of a UDP or L2TPIP socket. See struct
361pppol2tp_addr in `include/linux/if_pppol2tp.h`_. For historical reasons,
362there are unfortunately slightly different address structures for
363L2TPv2/L2TPv3 IPv4/IPv6 tunnels and userspace must use the appropriate
364structure that matches the tunnel socket type.
365
366Userspace may control behavior of the tunnel or session using
367setsockopt and ioctl on the PPPoX socket. The following socket
368options are supported:-
369
370=========   ===========================================================
371DEBUG       bitmask of debug message categories. See below.
372SENDSEQ     - 0 => don't send packets with sequence numbers
373            - 1 => send packets with sequence numbers
374RECVSEQ     - 0 => receive packet sequence numbers are optional
375            - 1 => drop receive packets without sequence numbers
376LNSMODE     - 0 => act as LAC.
377            - 1 => act as LNS.
378REORDERTO   reorder timeout (in millisecs). If 0, don't try to reorder.
379=========   ===========================================================
380
381In addition to the standard PPP ioctls, a PPPIOCGL2TPSTATS is provided
382to retrieve tunnel and session statistics from the kernel using the
383PPPoX socket of the appropriate tunnel or session.
384
385Sample userspace code:
386
387  - Create session PPPoX data socket::
388
389        struct sockaddr_pppol2tp sax;
390        int fd;
391
392        /* Note, the tunnel socket must be bound already, else it
393         * will not be ready
394         */
395        sax.sa_family = AF_PPPOX;
396        sax.sa_protocol = PX_PROTO_OL2TP;
397        sax.pppol2tp.fd = tunnel_fd;
398        sax.pppol2tp.addr.sin_addr.s_addr = addr->sin_addr.s_addr;
399        sax.pppol2tp.addr.sin_port = addr->sin_port;
400        sax.pppol2tp.addr.sin_family = AF_INET;
401        sax.pppol2tp.s_tunnel  = tunnel_id;
402        sax.pppol2tp.s_session = session_id;
403        sax.pppol2tp.d_tunnel  = peer_tunnel_id;
404        sax.pppol2tp.d_session = peer_session_id;
405
406        /* session_fd is the fd of the session's PPPoL2TP socket.
407         * tunnel_fd is the fd of the tunnel UDP / L2TPIP socket.
408         */
409        fd = connect(session_fd, (struct sockaddr *)&sax, sizeof(sax));
410        if (fd < 0 ) {
411                return -errno;
412        }
413        return 0;
414
415Old L2TPv2-only API
416-------------------
417
418When L2TP was first added to the Linux kernel in 2.6.23, it
419implemented only L2TPv2 and did not include a netlink API. Instead,
420tunnel and session instances in the kernel were managed directly using
421only PPPoL2TP sockets. The PPPoL2TP socket is used as described in
422section "PPPoL2TP Session Socket API" but tunnel and session instances
423are automatically created on a connect() of the socket instead of
424being created by a separate netlink request:
425
426    - Tunnels are managed using a tunnel management socket which is a
427      dedicated PPPoL2TP socket, connected to (invalid) session
428      id 0. The L2TP tunnel instance is created when the PPPoL2TP
429      tunnel management socket is connected and is destroyed when the
430      socket is closed.
431
432    - Session instances are created in the kernel when a PPPoL2TP
433      socket is connected to a non-zero session id. Session parameters
434      are set using setsockopt. The L2TP session instance is destroyed
435      when the socket is closed.
436
437This API is still supported but its use is discouraged. Instead, new
438L2TPv2 applications should use netlink to first create the tunnel and
439session, then create a PPPoL2TP socket for the session.
440
441Unmanaged L2TPv3 tunnels
442------------------------
443
444The kernel L2TP subsystem also supports static (unmanaged) L2TPv3
445tunnels. Unmanaged tunnels have no userspace tunnel socket, and
446exchange no control messages with the peer to set up the tunnel; the
447tunnel is configured manually at each end of the tunnel. All
448configuration is done using netlink. There is no need for an L2TP
449userspace application in this case -- the tunnel socket is created by
450the kernel and configured using parameters sent in the
451``L2TP_CMD_TUNNEL_CREATE`` netlink request. The ``ip`` utility of
452``iproute2`` has commands for managing static L2TPv3 tunnels; do ``ip
453l2tp help`` for more information.
454
455Debugging
456---------
457
458The L2TP subsystem offers a range of debugging interfaces through the
459debugfs filesystem.
460
461To access these interfaces, the debugfs filesystem must first be mounted::
462
463    # mount -t debugfs debugfs /debug
464
465Files under the l2tp directory can then be accessed, providing a summary
466of the current population of tunnel and session contexts existing in the
467kernel::
468
469    # cat /debug/l2tp/tunnels
470
471The debugfs files should not be used by applications to obtain L2TP
472state information because the file format is subject to change. It is
473implemented to provide extra debug information to help diagnose
474problems. Applications should instead use the netlink API.
475
476In addition the L2TP subsystem implements tracepoints using the standard
477kernel event tracing API.  The available L2TP events can be reviewed as
478follows::
479
480    # find /debug/tracing/events/l2tp
481
482Finally, /proc/net/pppol2tp is also provided for backwards compatibility
483with the original pppol2tp code. It lists information about L2TPv2
484tunnels and sessions only. Its use is discouraged.
485
486Internal Implementation
487=======================
488
489This section is for kernel developers and maintainers.
490
491Sockets
492-------
493
494UDP sockets are implemented by the networking core. When an L2TP
495tunnel is created using a UDP socket, the socket is set up as an
496encapsulated UDP socket by setting encap_rcv and encap_destroy
497callbacks on the UDP socket. l2tp_udp_encap_recv is called when
498packets are received on the socket. l2tp_udp_encap_destroy is called
499when userspace closes the socket.
500
501L2TPIP sockets are implemented in `net/l2tp/l2tp_ip.c`_ and
502`net/l2tp/l2tp_ip6.c`_.
503
504Tunnels
505-------
506
507The kernel keeps a struct l2tp_tunnel context per L2TP tunnel. The
508l2tp_tunnel is always associated with a UDP or L2TP/IP socket and
509keeps a list of sessions in the tunnel. When a tunnel is first
510registered with L2TP core, the reference count on the socket is
511increased. This ensures that the socket cannot be removed while L2TP's
512data structures reference it.
513
514Tunnels are identified by a unique tunnel id. The id is 16-bit for
515L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit
516value.
517
518Tunnels are kept in a per-net list, indexed by tunnel id. The tunnel
519id namespace is shared by L2TPv2 and L2TPv3. The tunnel context can be
520derived from the socket's sk_user_data.
521
522Handling tunnel socket close is perhaps the most tricky part of the
523L2TP implementation. If userspace closes a tunnel socket, the L2TP
524tunnel and all of its sessions must be closed and destroyed. Since the
525tunnel context holds a ref on the tunnel socket, the socket's
526sk_destruct won't be called until the tunnel sock_put's its
527socket. For UDP sockets, when userspace closes the tunnel socket, the
528socket's encap_destroy handler is invoked, which L2TP uses to initiate
529its tunnel close actions. For L2TPIP sockets, the socket's close
530handler initiates the same tunnel close actions. All sessions are
531first closed. Each session drops its tunnel ref. When the tunnel ref
532reaches zero, the tunnel puts its socket ref. When the socket is
533eventually destroyed, its sk_destruct finally frees the L2TP tunnel
534context.
535
536Sessions
537--------
538
539The kernel keeps a struct l2tp_session context for each session.  Each
540session has private data which is used for data specific to the
541session type. With L2TPv2, the session always carries PPP
542traffic. With L2TPv3, the session can carry Ethernet frames (Ethernet
543pseudowire) or other data types such as PPP, ATM, HDLC or Frame
544Relay. Linux currently implements only Ethernet and PPP session types.
545
546Some L2TP session types also have a socket (PPP pseudowires) while
547others do not (Ethernet pseudowires). We can't therefore use the
548socket reference count as the reference count for session
549contexts. The L2TP implementation therefore has its own internal
550reference counts on the session contexts.
551
552Like tunnels, L2TP sessions are identified by a unique
553session id. Just as with tunnel ids, the session id is 16-bit for
554L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit
555value.
556
557Sessions hold a ref on their parent tunnel to ensure that the tunnel
558stays extant while one or more sessions references it.
559
560Sessions are kept in a per-tunnel list, indexed by session id. L2TPv3
561sessions are also kept in a per-net list indexed by session id,
562because L2TPv3 session ids are unique across all tunnels and L2TPv3
563data packets do not contain a tunnel id in the header. This list is
564therefore needed to find the session context associated with a
565received data packet when the tunnel context cannot be derived from
566the tunnel socket.
567
568Although the L2TPv3 RFC specifies that L2TPv3 session ids are not
569scoped by the tunnel, the kernel does not police this for L2TPv3 UDP
570tunnels and does not add sessions of L2TPv3 UDP tunnels into the
571per-net session list. In the UDP receive code, we must trust that the
572tunnel can be identified using the tunnel socket's sk_user_data and
573lookup the session in the tunnel's session list instead of the per-net
574session list.
575
576PPP
577---
578
579`net/l2tp/l2tp_ppp.c`_ implements the PPPoL2TP socket family. Each PPP
580session has a PPPoL2TP socket.
581
582The PPPoL2TP socket's sk_user_data references the l2tp_session.
583
584Userspace sends and receives PPP packets over L2TP using a PPPoL2TP
585socket. Only PPP control frames pass over this socket: PPP data
586packets are handled entirely by the kernel, passing between the L2TP
587session and its associated ``pppN`` netdev through the PPP channel
588interface of the kernel PPP subsystem.
589
590The L2TP PPP implementation handles the closing of a PPPoL2TP socket
591by closing its corresponding L2TP session. This is complicated because
592it must consider racing with netlink session create/destroy requests
593and pppol2tp_connect trying to reconnect with a session that is in the
594process of being closed. Unlike tunnels, PPP sessions do not hold a
595ref on their associated socket, so code must be careful to sock_hold
596the socket where necessary. For all the details, see commit
5973d609342cc04129ff7568e19316ce3d7451a27e8.
598
599Ethernet
600--------
601
602`net/l2tp/l2tp_eth.c`_ implements L2TPv3 Ethernet pseudowires. It
603manages a netdev for each session.
604
605L2TP Ethernet sessions are created and destroyed by netlink request,
606or are destroyed when the tunnel is destroyed. Unlike PPP sessions,
607Ethernet sessions do not have an associated socket.
608
609Miscellaneous
610=============
611
612RFCs
613----
614
615The kernel code implements the datapath features specified in the
616following RFCs:
617
618======= =============== ===================================
619RFC2661 L2TPv2          https://tools.ietf.org/html/rfc2661
620RFC3931 L2TPv3          https://tools.ietf.org/html/rfc3931
621RFC4719 L2TPv3 Ethernet https://tools.ietf.org/html/rfc4719
622======= =============== ===================================
623
624Implementations
625---------------
626
627A number of open source applications use the L2TP kernel subsystem:
628
629============ ==============================================
630iproute2     https://github.com/shemminger/iproute2
631go-l2tp      https://github.com/katalix/go-l2tp
632tunneldigger https://github.com/wlanslovenija/tunneldigger
633xl2tpd       https://github.com/xelerance/xl2tpd
634============ ==============================================
635
636Limitations
637-----------
638
639The current implementation has a number of limitations:
640
641  1) Multiple UDP sockets with the same 5-tuple address cannot be
642     used. The kernel's tunnel context is identified using private
643     data associated with the socket so it is important that each
644     socket is uniquely identified by its address.
645
646  2) Interfacing with openvswitch is not yet implemented. It may be
647     useful to map OVS Ethernet and VLAN ports into L2TPv3 tunnels.
648
649  3) VLAN pseudowires are implemented using an ``l2tpethN`` interface
650     configured with a VLAN sub-interface. Since L2TPv3 VLAN
651     pseudowires carry one and only one VLAN, it may be better to use
652     a single netdevice rather than an ``l2tpethN`` and ``l2tpethN``:M
653     pair per VLAN session. The netlink attribute
654     ``L2TP_ATTR_VLAN_ID`` was added for this, but it was never
655     implemented.
656
657Testing
658-------
659
660Unmanaged L2TPv3 Ethernet features are tested by the kernel's built-in
661selftests. See `tools/testing/selftests/net/l2tp.sh`_.
662
663Another test suite, l2tp-ktest_, covers all
664of the L2TP APIs and tunnel/session types. This may be integrated into
665the kernel's built-in L2TP selftests in the future.
666
667.. Links
668.. _Generic Netlink: generic_netlink.html
669.. _libmnl: https://www.netfilter.org/projects/libmnl
670.. _include/uapi/linux/l2tp.h: ../../../include/uapi/linux/l2tp.h
671.. _include/linux/if_pppol2tp.h: ../../../include/linux/if_pppol2tp.h
672.. _net/l2tp/l2tp_ip.c: ../../../net/l2tp/l2tp_ip.c
673.. _net/l2tp/l2tp_ip6.c: ../../../net/l2tp/l2tp_ip6.c
674.. _net/l2tp/l2tp_ppp.c: ../../../net/l2tp/l2tp_ppp.c
675.. _net/l2tp/l2tp_eth.c: ../../../net/l2tp/l2tp_eth.c
676.. _tools/testing/selftests/net/l2tp.sh: ../../../tools/testing/selftests/net/l2tp.sh
677.. _l2tp-ktest: https://github.com/katalix/l2tp-ktest
678