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         /* 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