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