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 /* 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 424L2TP 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 452LCP 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 482IPCP/IPv6CP PPP frames will be available for read on `ppp_if_fd`. 483 484The ppp<ifunit> interface can then be configured as usual with netlink's 485RTM_NEWLINK, RTM_NEWADDR, RTM_NEWROUTE, or ioctl's SIOCSIFMTU, SIOCSIFADDR, 486SIOCSIFDSTADDR, 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 526It can be noted that when bridging PPP channels, the PPP session is not locally 527terminated, and no local PPP interface is created. PPP frames arriving on one 528channel are directly passed to the other channel, and vice versa. 529 530The PPP channel does not need to be kept open. Only the session PPPoX data 531sockets need to be kept open. 532 533More generally, it is also possible in the same way to e.g. bridge a PPPoL2TP 534PPP channel with other types of PPP channels, such as PPPoE. 535 536See more details for the PPP side in ppp_generic.rst. 537 538Old L2TPv2-only API 539------------------- 540 541When L2TP was first added to the Linux kernel in 2.6.23, it 542implemented only L2TPv2 and did not include a netlink API. Instead, 543tunnel and session instances in the kernel were managed directly using 544only PPPoL2TP sockets. The PPPoL2TP socket is used as described in 545section "PPPoL2TP Session Socket API" but tunnel and session instances 546are automatically created on a connect() of the socket instead of 547being 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 560This API is still supported but its use is discouraged. Instead, new 561L2TPv2 applications should use netlink to first create the tunnel and 562session, then create a PPPoL2TP socket for the session. 563 564Unmanaged L2TPv3 tunnels 565------------------------ 566 567The kernel L2TP subsystem also supports static (unmanaged) L2TPv3 568tunnels. Unmanaged tunnels have no userspace tunnel socket, and 569exchange no control messages with the peer to set up the tunnel; the 570tunnel is configured manually at each end of the tunnel. All 571configuration is done using netlink. There is no need for an L2TP 572userspace application in this case -- the tunnel socket is created by 573the 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 576l2tp help`` for more information. 577 578Debugging 579--------- 580 581The L2TP subsystem offers a range of debugging interfaces through the 582debugfs filesystem. 583 584To access these interfaces, the debugfs filesystem must first be mounted:: 585 586 # mount -t debugfs debugfs /debug 587 588Files under the l2tp directory can then be accessed, providing a summary 589of the current population of tunnel and session contexts existing in the 590kernel:: 591 592 # cat /debug/l2tp/tunnels 593 594The debugfs files should not be used by applications to obtain L2TP 595state information because the file format is subject to change. It is 596implemented to provide extra debug information to help diagnose 597problems. Applications should instead use the netlink API. 598 599In addition the L2TP subsystem implements tracepoints using the standard 600kernel event tracing API. The available L2TP events can be reviewed as 601follows:: 602 603 # find /debug/tracing/events/l2tp 604 605Finally, /proc/net/pppol2tp is also provided for backwards compatibility 606with the original pppol2tp code. It lists information about L2TPv2 607tunnels and sessions only. Its use is discouraged. 608 609Internal Implementation 610======================= 611 612This section is for kernel developers and maintainers. 613 614Sockets 615------- 616 617UDP sockets are implemented by the networking core. When an L2TP 618tunnel is created using a UDP socket, the socket is set up as an 619encapsulated UDP socket by setting encap_rcv and encap_destroy 620callbacks on the UDP socket. l2tp_udp_encap_recv is called when 621packets are received on the socket. l2tp_udp_encap_destroy is called 622when userspace closes the socket. 623 624L2TPIP sockets are implemented in `net/l2tp/l2tp_ip.c`_ and 625`net/l2tp/l2tp_ip6.c`_. 626 627Tunnels 628------- 629 630The kernel keeps a struct l2tp_tunnel context per L2TP tunnel. The 631l2tp_tunnel is always associated with a UDP or L2TP/IP socket and 632keeps a list of sessions in the tunnel. When a tunnel is first 633registered with L2TP core, the reference count on the socket is 634increased. This ensures that the socket cannot be removed while L2TP's 635data structures reference it. 636 637Tunnels are identified by a unique tunnel id. The id is 16-bit for 638L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit 639value. 640 641Tunnels are kept in a per-net list, indexed by tunnel id. The 642tunnel id namespace is shared by L2TPv2 and L2TPv3. 643 644Handling tunnel socket close is perhaps the most tricky part of the 645L2TP implementation. If userspace closes a tunnel socket, the L2TP 646tunnel and all of its sessions must be closed and destroyed. Since the 647tunnel context holds a ref on the tunnel socket, the socket's 648sk_destruct won't be called until the tunnel sock_put's its 649socket. For UDP sockets, when userspace closes the tunnel socket, the 650socket's encap_destroy handler is invoked, which L2TP uses to initiate 651its tunnel close actions. For L2TPIP sockets, the socket's close 652handler initiates the same tunnel close actions. All sessions are 653first closed. Each session drops its tunnel ref. When the tunnel ref 654reaches zero, the tunnel drops its socket ref. 655 656Sessions 657-------- 658 659The kernel keeps a struct l2tp_session context for each session. Each 660session has private data which is used for data specific to the 661session type. With L2TPv2, the session always carries PPP 662traffic. With L2TPv3, the session can carry Ethernet frames (Ethernet 663pseudowire) or other data types such as PPP, ATM, HDLC or Frame 664Relay. Linux currently implements only Ethernet and PPP session types. 665 666Some L2TP session types also have a socket (PPP pseudowires) while 667others do not (Ethernet pseudowires). 668 669Like tunnels, L2TP sessions are identified by a unique 670session id. Just as with tunnel ids, the session id is 16-bit for 671L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit 672value. 673 674Sessions hold a ref on their parent tunnel to ensure that the tunnel 675stays extant while one or more sessions references it. 676 677Sessions are kept in a per-net list. L2TPv2 sessions and L2TPv3 678sessions are stored in separate lists. L2TPv2 sessions are keyed 679by a 32-bit key made up of the 16-bit tunnel ID and 16-bit 680session ID. L2TPv3 sessions are keyed by the 32-bit session ID, since 681L2TPv3 session ids are unique across all tunnels. 682 683Although the L2TPv3 RFC specifies that L2TPv3 session ids are not 684scoped by the tunnel, the Linux implementation has historically 685allowed this. Such session id collisions are supported using a per-net 686hash table keyed by sk and session ID. When looking up L2TPv3 687sessions, the list entry may link to multiple sessions with that 688session ID, in which case the session matching the given sk (tunnel) 689is used. 690 691PPP 692--- 693 694`net/l2tp/l2tp_ppp.c`_ implements the PPPoL2TP socket family. Each PPP 695session has a PPPoL2TP socket. 696 697The PPPoL2TP socket's sk_user_data references the l2tp_session. 698 699Userspace sends and receives PPP packets over L2TP using a PPPoL2TP 700socket. Only PPP control frames pass over this socket: PPP data 701packets are handled entirely by the kernel, passing between the L2TP 702session and its associated ``pppN`` netdev through the PPP channel 703interface of the kernel PPP subsystem. 704 705The L2TP PPP implementation handles the closing of a PPPoL2TP socket 706by closing its corresponding L2TP session. This is complicated because 707it must consider racing with netlink session create/destroy requests 708and pppol2tp_connect trying to reconnect with a session that is in the 709process of being closed. PPP sessions hold a ref on their associated 710socket in order that the socket remains extants while the session 711references it. 712 713Ethernet 714-------- 715 716`net/l2tp/l2tp_eth.c`_ implements L2TPv3 Ethernet pseudowires. It 717manages a netdev for each session. 718 719L2TP Ethernet sessions are created and destroyed by netlink request, 720or are destroyed when the tunnel is destroyed. Unlike PPP sessions, 721Ethernet sessions do not have an associated socket. 722 723Miscellaneous 724============= 725 726RFCs 727---- 728 729The kernel code implements the datapath features specified in the 730following RFCs: 731 732======= =============== =================================== 733RFC2661 L2TPv2 https://tools.ietf.org/html/rfc2661 734RFC3931 L2TPv3 https://tools.ietf.org/html/rfc3931 735RFC4719 L2TPv3 Ethernet https://tools.ietf.org/html/rfc4719 736======= =============== =================================== 737 738Implementations 739--------------- 740 741A number of open source applications use the L2TP kernel subsystem: 742 743============ ============================================== 744iproute2 https://github.com/shemminger/iproute2 745go-l2tp https://github.com/katalix/go-l2tp 746tunneldigger https://github.com/wlanslovenija/tunneldigger 747xl2tpd https://github.com/xelerance/xl2tpd 748============ ============================================== 749 750Limitations 751----------- 752 753The current implementation has a number of limitations: 754 755 1) Interfacing with openvswitch is not yet implemented. It may be 756 useful to map OVS Ethernet and VLAN ports into L2TPv3 tunnels. 757 758 2) VLAN pseudowires are implemented using an ``l2tpethN`` interface 759 configured with a VLAN sub-interface. Since L2TPv3 VLAN 760 pseudowires carry one and only one VLAN, it may be better to use 761 a single netdevice rather than an ``l2tpethN`` and ``l2tpethN``:M 762 pair per VLAN session. The netlink attribute 763 ``L2TP_ATTR_VLAN_ID`` was added for this, but it was never 764 implemented. 765 766Testing 767------- 768 769Unmanaged L2TPv3 Ethernet features are tested by the kernel's built-in 770selftests. See `tools/testing/selftests/net/l2tp.sh`_. 771 772Another test suite, l2tp-ktest_, covers all 773of the L2TP APIs and tunnel/session types. This may be integrated into 774the kernel's built-in L2TP selftests in the future. 775 776.. Links 777.. _Generic Netlink: generic_netlink.html 778.. _libmnl: https://www.netfilter.org/projects/libmnl 779.. _include/uapi/linux/l2tp.h: ../../../include/uapi/linux/l2tp.h 780.. _include/linux/if_pppol2tp.h: ../../../include/linux/if_pppol2tp.h 781.. _net/l2tp/l2tp_ip.c: ../../../net/l2tp/l2tp_ip.c 782.. _net/l2tp/l2tp_ip6.c: ../../../net/l2tp/l2tp_ip6.c 783.. _net/l2tp/l2tp_ppp.c: ../../../net/l2tp/l2tp_ppp.c 784.. _net/l2tp/l2tp_eth.c: ../../../net/l2tp/l2tp_eth.c 785.. _tools/testing/selftests/net/l2tp.sh: ../../../tools/testing/selftests/net/l2tp.sh 786.. _l2tp-ktest: https://github.com/katalix/l2tp-ktest 787