L2TP — The Linux Kernel documentation
The Linux Kernel 7.4.0-rc3 Quick search Contents Working with the development community Development process Submitting patches Code of conduct Maintainer handbook All development-process docs Internal API manuals Core API Driver APIs Subsystems Core subsystems Human interfaces Networking interfaces Networking NetLabel InfiniBand MHI Storage interfaces Other subsystems Locking Development tools and processes Licensing rules Writing documentation Development tools Testing guide Hacking guide Tracing Fault injection Livepatching Rust User-oriented documentation Administration Build system Reporting issues Userspace tools Userspace API Firmware-related documentation Firmware Firmware and Devicetree Architecture-specific documentation CPU architectures Other documentation Unsorted documentation Translations Translations This Page Show Source 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: Create a tunnel socket.
Exchange L2TP control protocol messages with the peer over that socket in order to establish a tunnel. Create a tunnel context in the kernel, using information obtained from the peer using the control protocol messages. Exchange L2TP control protocol messages with the peer over the tunnel socket in order to establish a session. 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
The rest of this page is on the live site.