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