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