Documentation/networking/l2tp.rst

   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         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
 415 Old L2TPv2-only API
 416 -------------------
 417
 418 When L2TP was first added to the Linux kernel in 2.6.23, it
 419 implemented only L2TPv2 and did not include a netlink API. Instead,
 420 tunnel and session instances in the kernel were managed directly using
 421 only PPPoL2TP sockets. The PPPoL2TP socket is used as described in
 422 section "PPPoL2TP Session Socket API" but tunnel and session instances
 423 are automatically created on a connect() of the socket instead of
 424 being 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
 437 This API is still supported but its use is discouraged. Instead, new
 438 L2TPv2 applications should use netlink to first create the tunnel and
 439 session, then create a PPPoL2TP socket for the session.
 440
 441 Unmanaged L2TPv3 tunnels
 442 ------------------------
 443
 444 The kernel L2TP subsystem also supports static (unmanaged) L2TPv3
 445 tunnels. Unmanaged tunnels have no userspace tunnel socket, and
 446 exchange no control messages with the peer to set up the tunnel; the
 447 tunnel is configured manually at each end of the tunnel. All
 448 configuration is done using netlink. There is no need for an L2TP
 449 userspace application in this case -- the tunnel socket is created by
 450 the 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
 453 l2tp help`` for more information.
 454
 455 Debugging
 456 ---------
 457
 458 The L2TP subsystem offers a range of debugging interfaces through the
 459 debugfs filesystem.
 460
 461 To access these interfaces, the debugfs filesystem must first be mounted::
 462
 463     # mount -t debugfs debugfs /debug
 464
 465 Files under the l2tp directory can then be accessed, providing a summary
 466 of the current population of tunnel and session contexts existing in the
 467 kernel::
 468
 469     # cat /debug/l2tp/tunnels
 470
 471 The debugfs files should not be used by applications to obtain L2TP
 472 state information because the file format is subject to change. It is
 473 implemented to provide extra debug information to help diagnose
 474 problems. Applications should instead use the netlink API.
 475
 476 In addition the L2TP subsystem implements tracepoints using the standard
 477 kernel event tracing API.  The available L2TP events can be reviewed as
 478 follows::
 479
 480     # find /debug/tracing/events/l2tp
 481
 482 Finally, /proc/net/pppol2tp is also provided for backwards compatibility
 483 with the original pppol2tp code. It lists information about L2TPv2
 484 tunnels and sessions only. Its use is discouraged.
 485
 486 Internal Implementation
 487 =======================
 488
 489 This section is for kernel developers and maintainers.
 490
 491 Sockets
 492 -------
 493
 494 UDP sockets are implemented by the networking core. When an L2TP
 495 tunnel is created using a UDP socket, the socket is set up as an
 496 encapsulated UDP socket by setting encap_rcv and encap_destroy
 497 callbacks on the UDP socket. l2tp_udp_encap_recv is called when
 498 packets are received on the socket. l2tp_udp_encap_destroy is called
 499 when userspace closes the socket.
 500
 501 L2TPIP sockets are implemented in `net/l2tp/l2tp_ip.c`_ and
 502 `net/l2tp/l2tp_ip6.c`_.
 503
 504 Tunnels
 505 -------
 506
 507 The kernel keeps a struct l2tp_tunnel context per L2TP tunnel. The
 508 l2tp_tunnel is always associated with a UDP or L2TP/IP socket and
 509 keeps a list of sessions in the tunnel. When a tunnel is first
 510 registered with L2TP core, the reference count on the socket is
 511 increased. This ensures that the socket cannot be removed while L2TP's
 512 data structures reference it.
 513
 514 Tunnels are identified by a unique tunnel id. The id is 16-bit for
 515 L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit
 516 value.
 517
 518 Tunnels are kept in a per-net list, indexed by tunnel id. The tunnel
 519 id namespace is shared by L2TPv2 and L2TPv3. The tunnel context can be
 520 derived from the socket's sk_user_data.
 521
 522 Handling tunnel socket close is perhaps the most tricky part of the
 523 L2TP implementation. If userspace closes a tunnel socket, the L2TP
 524 tunnel and all of its sessions must be closed and destroyed. Since the
 525 tunnel context holds a ref on the tunnel socket, the socket's
 526 sk_destruct won't be called until the tunnel sock_put's its
 527 socket. For UDP sockets, when userspace closes the tunnel socket, the
 528 socket's encap_destroy handler is invoked, which L2TP uses to initiate
 529 its tunnel close actions. For L2TPIP sockets, the socket's close
 530 handler initiates the same tunnel close actions. All sessions are
 531 first closed. Each session drops its tunnel ref. When the tunnel ref
 532 reaches zero, the tunnel puts its socket ref. When the socket is
 533 eventually destroyed, it's sk_destruct finally frees the L2TP tunnel
 534 context.
 535
 536 Sessions
 537 --------
 538
 539 The kernel keeps a struct l2tp_session context for each session.  Each
 540 session has private data which is used for data specific to the
 541 session type. With L2TPv2, the session always carries PPP
 542 traffic. With L2TPv3, the session can carry Ethernet frames (Ethernet
 543 pseudowire) or other data types such as PPP, ATM, HDLC or Frame
 544 Relay. Linux currently implements only Ethernet and PPP session types.
 545
 546 Some L2TP session types also have a socket (PPP pseudowires) while
 547 others do not (Ethernet pseudowires). We can't therefore use the
 548 socket reference count as the reference count for session
 549 contexts. The L2TP implementation therefore has its own internal
 550 reference counts on the session contexts.
 551
 552 Like tunnels, L2TP sessions are identified by a unique
 553 session id. Just as with tunnel ids, the session id is 16-bit for
 554 L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit
 555 value.
 556
 557 Sessions hold a ref on their parent tunnel to ensure that the tunnel
 558 stays extant while one or more sessions references it.
 559
 560 Sessions are kept in a per-tunnel list, indexed by session id. L2TPv3
 561 sessions are also kept in a per-net list indexed by session id,
 562 because L2TPv3 session ids are unique across all tunnels and L2TPv3
 563 data packets do not contain a tunnel id in the header. This list is
 564 therefore needed to find the session context associated with a
 565 received data packet when the tunnel context cannot be derived from
 566 the tunnel socket.
 567
 568 Although the L2TPv3 RFC specifies that L2TPv3 session ids are not
 569 scoped by the tunnel, the kernel does not police this for L2TPv3 UDP
 570 tunnels and does not add sessions of L2TPv3 UDP tunnels into the
 571 per-net session list. In the UDP receive code, we must trust that the
 572 tunnel can be identified using the tunnel socket's sk_user_data and
 573 lookup the session in the tunnel's session list instead of the per-net
 574 session list.
 575
 576 PPP
 577 ---
 578
 579 `net/l2tp/l2tp_ppp.c`_ implements the PPPoL2TP socket family. Each PPP
 580 session has a PPPoL2TP socket.
 581
 582 The PPPoL2TP socket's sk_user_data references the l2tp_session.
 583
 584 Userspace sends and receives PPP packets over L2TP using a PPPoL2TP
 585 socket. Only PPP control frames pass over this socket: PPP data
 586 packets are handled entirely by the kernel, passing between the L2TP
 587 session and its associated ``pppN`` netdev through the PPP channel
 588 interface of the kernel PPP subsystem.
 589
 590 The L2TP PPP implementation handles the closing of a PPPoL2TP socket
 591 by closing its corresponding L2TP session. This is complicated because
 592 it must consider racing with netlink session create/destroy requests
 593 and pppol2tp_connect trying to reconnect with a session that is in the
 594 process of being closed. Unlike tunnels, PPP sessions do not hold a
 595 ref on their associated socket, so code must be careful to sock_hold
 596 the socket where necessary. For all the details, see commit
 597 3d609342cc04129ff7568e19316ce3d7451a27e8.
 598
 599 Ethernet
 600 --------
 601
 602 `net/l2tp/l2tp_eth.c`_ implements L2TPv3 Ethernet pseudowires. It
 603 manages a netdev for each session.
 604
 605 L2TP Ethernet sessions are created and destroyed by netlink request,
 606 or are destroyed when the tunnel is destroyed. Unlike PPP sessions,
 607 Ethernet sessions do not have an associated socket.
 608
 609 Miscellaneous
 610 =============
 611
 612 RFCs
 613 ----
 614
 615 The kernel code implements the datapath features specified in the
 616 following RFCs:
 617
 618 ======= =============== ===================================
 619 RFC2661 L2TPv2          https://tools.ietf.org/html/rfc2661
 620 RFC3931 L2TPv3          https://tools.ietf.org/html/rfc3931
 621 RFC4719 L2TPv3 Ethernet https://tools.ietf.org/html/rfc4719
 622 ======= =============== ===================================
 623
 624 Implementations
 625 ---------------
 626
 627 A number of open source applications use the L2TP kernel subsystem:
 628
 629 ============ ==============================================
 630 iproute2     https://github.com/shemminger/iproute2
 631 go-l2tp      https://github.com/katalix/go-l2tp
 632 tunneldigger https://github.com/wlanslovenija/tunneldigger
 633 xl2tpd       https://github.com/xelerance/xl2tpd
 634 ============ ==============================================
 635
 636 Limitations
 637 -----------
 638
 639 The 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
 657 Testing
 658 -------
 659
 660 Unmanaged L2TPv3 Ethernet features are tested by the kernel's built-in
 661 selftests. See `tools/testing/selftests/net/l2tp.sh`_.
 662
 663 Another test suite, l2tp-ktest_, covers all
 664 of the L2TP APIs and tunnel/session types. This may be integrated into
 665 the 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