787 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3====4L2TP5====6 7Layer 2 Tunneling Protocol (L2TP) allows L2 frames to be tunneled over8an IP network.9 10This document covers the kernel's L2TP subsystem. It documents kernel11APIs for application developers who want to use the L2TP subsystem and12it provides some technical details about the internal implementation13which may be useful to kernel developers and maintainers.14 15Overview16========17 18The kernel's L2TP subsystem implements the datapath for L2TPv2 and19L2TPv3. L2TPv2 is carried over UDP. L2TPv3 is carried over UDP or20directly over IP (protocol 115).21 22The L2TP RFCs define two basic kinds of L2TP packets: control packets23(the "control plane"), and data packets (the "data plane"). The kernel24deals only with data packets. The more complex control packets are25handled by user space.26 27An L2TP tunnel carries one or more L2TP sessions. Each tunnel is28associated with a socket. Each session is associated with a virtual29netdevice, e.g. ``pppN``, ``l2tpethN``, through which data frames pass30to/from L2TP. Fields in the L2TP header identify the tunnel or session31and whether it is a control or data packet. When tunnels and sessions32are set up using the Linux kernel API, we're just setting up the L2TP33data path. All aspects of the control protocol are to be handled by34user space.35 36This split in responsibilities leads to a natural sequence of37operations when establishing tunnels and sessions. The procedure looks38like this:39 40 1) Create a tunnel socket. Exchange L2TP control protocol messages41 with the peer over that socket in order to establish a tunnel.42 43 2) Create a tunnel context in the kernel, using information44 obtained from the peer using the control protocol messages.45 46 3) Exchange L2TP control protocol messages with the peer over the47 tunnel socket in order to establish a session.48 49 4) Create a session context in the kernel using information50 obtained from the peer using the control protocol messages.51 52L2TP APIs53=========54 55This section documents each userspace API of the L2TP subsystem.56 57Tunnel Sockets58--------------59 60L2TPv2 always uses UDP. L2TPv3 may use UDP or IP encapsulation.61 62To create a tunnel socket for use by L2TP, the standard POSIX63socket 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 L2TP76subsystem. The L2TPIP socket address is defined in struct77sockaddr_l2tpip and struct sockaddr_l2tpip6 at78`include/uapi/linux/l2tp.h`_. The address includes the L2TP tunnel79(connection) id. To use L2TP IP encapsulation, an L2TPv3 application80should bind the L2TPIP socket using the locally assigned81tunnel id. When the peer's tunnel id and IP address is known, a82connect must be done.83 84If the L2TP application needs to handle L2TPv3 tunnel setup requests85from peers using L2TPIP, it must open a dedicated L2TPIP86socket to listen for those requests and bind the socket using tunnel87id 0 since tunnel setup requests are addressed to tunnel id 0.88 89An L2TP tunnel and all of its sessions are automatically closed when90its tunnel socket is closed.91 92Netlink API93-----------94 95L2TP applications use netlink to manage L2TP tunnel and session96instances in the kernel. The L2TP netlink API is defined in97`include/uapi/linux/l2tp.h`_.98 99L2TP uses `Generic Netlink`_ (GENL). Several commands are defined:100Create, Delete, Modify and Get for tunnel and session101instances, e.g. ``L2TP_CMD_TUNNEL_CREATE``. The API header lists the102netlink attribute types that can be used with each command.103 104Tunnel and session instances are identified by a locally unique10532-bit id. L2TP tunnel ids are given by ``L2TP_ATTR_CONN_ID`` and106``L2TP_ATTR_PEER_CONN_ID`` attributes and L2TP session ids are given107by ``L2TP_ATTR_SESSION_ID`` and ``L2TP_ATTR_PEER_SESSION_ID``108attributes. If netlink is used to manage L2TPv2 tunnel and session109instances, the L2TPv2 16-bit tunnel/session id is cast to a 32-bit110value in these attributes.111 112In the ``L2TP_CMD_TUNNEL_CREATE`` command, ``L2TP_ATTR_FD`` tells the113kernel the tunnel socket fd being used. If not specified, the kernel114creates a kernel socket for the tunnel, using IP parameters set in115``L2TP_ATTR_IP[6]_SADDR``, ``L2TP_ATTR_IP[6]_DADDR``,116``L2TP_ATTR_UDP_SPORT``, ``L2TP_ATTR_UDP_DPORT`` attributes. Kernel117sockets are used to implement unmanaged L2TPv3 tunnels (iproute2's "ip118l2tp" commands). If ``L2TP_ATTR_FD`` is given, it must be a socket fd119that is already bound and connected. There is more information about120unmanaged tunnels later in this document.121 122``L2TP_CMD_TUNNEL_CREATE`` attributes:-123 124================== ======== ===125Attribute Required Use126================== ======== ===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 is133 not set.134UDP_ZERO_CSUM6_TX N Zero IPv6 UDP checksum on transmit. Used only135 if FD is not set.136UDP_ZERO_CSUM6_RX N Zero IPv6 UDP checksum on receive. Used only if137 FD is not set.138IP_SADDR N IPv4 source address. Used only if FD is not139 set.140IP_DADDR N IPv4 destination address. Used only if FD is141 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 not144 set.145IP6_SADDR N IPv6 source address. Used only if FD is not146 set.147IP6_DADDR N IPv6 destination address. Used only if FD is148 not set.149DEBUG N Debug flags.150================== ======== ===151 152``L2TP_CMD_TUNNEL_DESTROY`` attributes:-153 154================== ======== ===155Attribute Required Use156================== ======== ===157CONN_ID Y Identifies the tunnel id to be destroyed.158================== ======== ===159 160``L2TP_CMD_TUNNEL_MODIFY`` attributes:-161 162================== ======== ===163Attribute Required Use164================== ======== ===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 Use173================== ======== ===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 Use182================== ======== ===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 sequence191 numbers).192RECV_TIMEOUT N Timeout to wait when reordering received193 packets.194L2SPEC_TYPE N Sets layer2-specific-sublayer type (L2TPv3195 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 virtual202interface which can then be configured as required. For PPP session203types, a PPPoL2TP socket must also be opened and connected, mapping it204onto the new session. This is covered in "PPPoL2TP Sockets" later.205 206``L2TP_CMD_SESSION_DESTROY`` attributes:-207 208================== ======== ===209Attribute Required Use210================== ======== ===211CONN_ID Y Identifies the parent tunnel id of the session212 to be destroyed.213SESSION_ID Y Identifies the session id to be destroyed.214IFNAME N Identifies the session by interface name. If215 set, this overrides any CONN_ID and SESSION_ID216 attributes. Currently supported for L2TPv3217 Ethernet sessions only.218================== ======== ===219 220``L2TP_CMD_SESSION_MODIFY`` attributes:-221 222================== ======== ===223Attribute Required Use224================== ======== ===225CONN_ID Y Identifies the parent tunnel id of the session226 to be modified.227SESSION_ID Y Identifies the session id to be modified.228IFNAME N Identifies the session by interface name. If229 set, this overrides any CONN_ID and SESSION_ID230 attributes. Currently supported for L2TPv3231 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 sequence236 numbers).237RECV_TIMEOUT N Timeout to wait when reordering received238 packets.239================== ======== ===240 241``L2TP_CMD_SESSION_GET`` attributes:-242 243================== ======== ===244Attribute Required Use245================== ======== ===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 and252 SESSION_ID attributes. Ignored for DUMP253 requests. Currently supported for L2TPv3254 Ethernet sessions only.255================== ======== ===256 257Application developers should refer to `include/uapi/linux/l2tp.h`_ for258netlink 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 netlink313 * attributes during session creation -- see l2tp.h314 */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 API352---------------------------353 354For PPP session types, a PPPoL2TP socket must be opened and connected355to the L2TP session.356 357When creating PPPoL2TP sockets, the application provides information358to the kernel about the tunnel and session in a socket connect()359call. Source and destination tunnel and session ids are provided, as360well as the file descriptor of a UDP or L2TPIP socket. See struct361pppol2tp_addr in `include/linux/if_pppol2tp.h`_. For historical reasons,362there are unfortunately slightly different address structures for363L2TPv2/L2TPv3 IPv4/IPv6 tunnels and userspace must use the appropriate364structure that matches the tunnel socket type.365 366Userspace may control behavior of the tunnel or session using367setsockopt and ioctl on the PPPoX socket. The following socket368options are supported:-369 370========= ===========================================================371DEBUG bitmask of debug message categories. See below.372SENDSEQ - 0 => don't send packets with sequence numbers373 - 1 => send packets with sequence numbers374RECVSEQ - 0 => receive packet sequence numbers are optional375 - 1 => drop receive packets without sequence numbers376LNSMODE - 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 provided382to retrieve tunnel and session statistics from the kernel using the383PPPoX 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 be390 * bound already (both sockname and peername), otherwise it will not be391 * 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 created429 * 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 described457 * 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's485RTM_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 called489 L2TP tunnel switching or L2TP multihop) is supported by bridging the PPP490 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 locally527terminated, and no local PPP interface is created. PPP frames arriving on one528channel 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 data531sockets need to be kept open.532 533More generally, it is also possible in the same way to e.g. bridge a PPPoL2TP534PPP 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 API539-------------------540 541When L2TP was first added to the Linux kernel in 2.6.23, it542implemented only L2TPv2 and did not include a netlink API. Instead,543tunnel and session instances in the kernel were managed directly using544only PPPoL2TP sockets. The PPPoL2TP socket is used as described in545section "PPPoL2TP Session Socket API" but tunnel and session instances546are automatically created on a connect() of the socket instead of547being created by a separate netlink request:548 549 - Tunnels are managed using a tunnel management socket which is a550 dedicated PPPoL2TP socket, connected to (invalid) session551 id 0. The L2TP tunnel instance is created when the PPPoL2TP552 tunnel management socket is connected and is destroyed when the553 socket is closed.554 555 - Session instances are created in the kernel when a PPPoL2TP556 socket is connected to a non-zero session id. Session parameters557 are set using setsockopt. The L2TP session instance is destroyed558 when the socket is closed.559 560This API is still supported but its use is discouraged. Instead, new561L2TPv2 applications should use netlink to first create the tunnel and562session, then create a PPPoL2TP socket for the session.563 564Unmanaged L2TPv3 tunnels565------------------------566 567The kernel L2TP subsystem also supports static (unmanaged) L2TPv3568tunnels. Unmanaged tunnels have no userspace tunnel socket, and569exchange no control messages with the peer to set up the tunnel; the570tunnel is configured manually at each end of the tunnel. All571configuration is done using netlink. There is no need for an L2TP572userspace application in this case -- the tunnel socket is created by573the kernel and configured using parameters sent in the574``L2TP_CMD_TUNNEL_CREATE`` netlink request. The ``ip`` utility of575``iproute2`` has commands for managing static L2TPv3 tunnels; do ``ip576l2tp help`` for more information.577 578Debugging579---------580 581The L2TP subsystem offers a range of debugging interfaces through the582debugfs filesystem.583 584To access these interfaces, the debugfs filesystem must first be mounted::585 586 # mount -t debugfs debugfs /debug587 588Files under the l2tp directory can then be accessed, providing a summary589of the current population of tunnel and session contexts existing in the590kernel::591 592 # cat /debug/l2tp/tunnels593 594The debugfs files should not be used by applications to obtain L2TP595state information because the file format is subject to change. It is596implemented to provide extra debug information to help diagnose597problems. Applications should instead use the netlink API.598 599In addition the L2TP subsystem implements tracepoints using the standard600kernel event tracing API. The available L2TP events can be reviewed as601follows::602 603 # find /debug/tracing/events/l2tp604 605Finally, /proc/net/pppol2tp is also provided for backwards compatibility606with the original pppol2tp code. It lists information about L2TPv2607tunnels and sessions only. Its use is discouraged.608 609Internal Implementation610=======================611 612This section is for kernel developers and maintainers.613 614Sockets615-------616 617UDP sockets are implemented by the networking core. When an L2TP618tunnel is created using a UDP socket, the socket is set up as an619encapsulated UDP socket by setting encap_rcv and encap_destroy620callbacks on the UDP socket. l2tp_udp_encap_recv is called when621packets are received on the socket. l2tp_udp_encap_destroy is called622when userspace closes the socket.623 624L2TPIP sockets are implemented in `net/l2tp/l2tp_ip.c`_ and625`net/l2tp/l2tp_ip6.c`_.626 627Tunnels628-------629 630The kernel keeps a struct l2tp_tunnel context per L2TP tunnel. The631l2tp_tunnel is always associated with a UDP or L2TP/IP socket and632keeps a list of sessions in the tunnel. When a tunnel is first633registered with L2TP core, the reference count on the socket is634increased. This ensures that the socket cannot be removed while L2TP's635data structures reference it.636 637Tunnels are identified by a unique tunnel id. The id is 16-bit for638L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit639value.640 641Tunnels are kept in a per-net list, indexed by tunnel id. The642tunnel id namespace is shared by L2TPv2 and L2TPv3.643 644Handling tunnel socket close is perhaps the most tricky part of the645L2TP implementation. If userspace closes a tunnel socket, the L2TP646tunnel and all of its sessions must be closed and destroyed. Since the647tunnel context holds a ref on the tunnel socket, the socket's648sk_destruct won't be called until the tunnel sock_put's its649socket. For UDP sockets, when userspace closes the tunnel socket, the650socket's encap_destroy handler is invoked, which L2TP uses to initiate651its tunnel close actions. For L2TPIP sockets, the socket's close652handler initiates the same tunnel close actions. All sessions are653first closed. Each session drops its tunnel ref. When the tunnel ref654reaches zero, the tunnel drops its socket ref.655 656Sessions657--------658 659The kernel keeps a struct l2tp_session context for each session. Each660session has private data which is used for data specific to the661session type. With L2TPv2, the session always carries PPP662traffic. With L2TPv3, the session can carry Ethernet frames (Ethernet663pseudowire) or other data types such as PPP, ATM, HDLC or Frame664Relay. Linux currently implements only Ethernet and PPP session types.665 666Some L2TP session types also have a socket (PPP pseudowires) while667others do not (Ethernet pseudowires).668 669Like tunnels, L2TP sessions are identified by a unique670session id. Just as with tunnel ids, the session id is 16-bit for671L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit672value.673 674Sessions hold a ref on their parent tunnel to ensure that the tunnel675stays extant while one or more sessions references it.676 677Sessions are kept in a per-net list. L2TPv2 sessions and L2TPv3678sessions are stored in separate lists. L2TPv2 sessions are keyed679by a 32-bit key made up of the 16-bit tunnel ID and 16-bit680session ID. L2TPv3 sessions are keyed by the 32-bit session ID, since681L2TPv3 session ids are unique across all tunnels.682 683Although the L2TPv3 RFC specifies that L2TPv3 session ids are not684scoped by the tunnel, the Linux implementation has historically685allowed this. Such session id collisions are supported using a per-net686hash table keyed by sk and session ID. When looking up L2TPv3687sessions, the list entry may link to multiple sessions with that688session ID, in which case the session matching the given sk (tunnel)689is used.690 691PPP692---693 694`net/l2tp/l2tp_ppp.c`_ implements the PPPoL2TP socket family. Each PPP695session 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 PPPoL2TP700socket. Only PPP control frames pass over this socket: PPP data701packets are handled entirely by the kernel, passing between the L2TP702session and its associated ``pppN`` netdev through the PPP channel703interface of the kernel PPP subsystem.704 705The L2TP PPP implementation handles the closing of a PPPoL2TP socket706by closing its corresponding L2TP session. This is complicated because707it must consider racing with netlink session create/destroy requests708and pppol2tp_connect trying to reconnect with a session that is in the709process of being closed. PPP sessions hold a ref on their associated710socket in order that the socket remains extants while the session711references it.712 713Ethernet714--------715 716`net/l2tp/l2tp_eth.c`_ implements L2TPv3 Ethernet pseudowires. It717manages 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 723Miscellaneous724=============725 726RFCs727----728 729The kernel code implements the datapath features specified in the730following RFCs:731 732======= =============== ===================================733RFC2661 L2TPv2 https://tools.ietf.org/html/rfc2661734RFC3931 L2TPv3 https://tools.ietf.org/html/rfc3931735RFC4719 L2TPv3 Ethernet https://tools.ietf.org/html/rfc4719736======= =============== ===================================737 738Implementations739---------------740 741A number of open source applications use the L2TP kernel subsystem:742 743============ ==============================================744iproute2 https://github.com/shemminger/iproute2745go-l2tp https://github.com/katalix/go-l2tp746tunneldigger https://github.com/wlanslovenija/tunneldigger747xl2tpd https://github.com/xelerance/xl2tpd748============ ==============================================749 750Limitations751-----------752 753The current implementation has a number of limitations:754 755 1) Interfacing with openvswitch is not yet implemented. It may be756 useful to map OVS Ethernet and VLAN ports into L2TPv3 tunnels.757 758 2) VLAN pseudowires are implemented using an ``l2tpethN`` interface759 configured with a VLAN sub-interface. Since L2TPv3 VLAN760 pseudowires carry one and only one VLAN, it may be better to use761 a single netdevice rather than an ``l2tpethN`` and ``l2tpethN``:M762 pair per VLAN session. The netlink attribute763 ``L2TP_ATTR_VLAN_ID`` was added for this, but it was never764 implemented.765 766Testing767-------768 769Unmanaged L2TPv3 Ethernet features are tested by the kernel's built-in770selftests. See `tools/testing/selftests/net/l2tp.sh`_.771 772Another test suite, l2tp-ktest_, covers all773of the L2TP APIs and tunnel/session types. This may be integrated into774the kernel's built-in L2TP selftests in the future.775 776.. Links777.. _Generic Netlink: generic_netlink.html778.. _libmnl: https://www.netfilter.org/projects/libmnl779.. _include/uapi/linux/l2tp.h: ../../../include/uapi/linux/l2tp.h780.. _include/linux/if_pppol2tp.h: ../../../include/linux/if_pppol2tp.h781.. _net/l2tp/l2tp_ip.c: ../../../net/l2tp/l2tp_ip.c782.. _net/l2tp/l2tp_ip6.c: ../../../net/l2tp/l2tp_ip6.c783.. _net/l2tp/l2tp_ppp.c: ../../../net/l2tp/l2tp_ppp.c784.. _net/l2tp/l2tp_eth.c: ../../../net/l2tp/l2tp_eth.c785.. _tools/testing/selftests/net/l2tp.sh: ../../../tools/testing/selftests/net/l2tp.sh786.. _l2tp-ktest: https://github.com/katalix/l2tp-ktest787