0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ====
0004 L2TP
0005 ====
0006
0007 Layer 2 Tunneling Protocol (L2TP) allows L2 frames to be tunneled over
0008 an IP network.
0009
0010 This document covers the kernel's L2TP subsystem. It documents kernel
0011 APIs for application developers who want to use the L2TP subsystem and
0012 it provides some technical details about the internal implementation
0013 which may be useful to kernel developers and maintainers.
0014
0015 Overview
0016 ========
0017
0018 The kernel's L2TP subsystem implements the datapath for L2TPv2 and
0019 L2TPv3. L2TPv2 is carried over UDP. L2TPv3 is carried over UDP or
0020 directly over IP (protocol 115).
0021
0022 The L2TP RFCs define two basic kinds of L2TP packets: control packets
0023 (the "control plane"), and data packets (the "data plane"). The kernel
0024 deals only with data packets. The more complex control packets are
0025 handled by user space.
0026
0027 An L2TP tunnel carries one or more L2TP sessions. Each tunnel is
0028 associated with a socket. Each session is associated with a virtual
0029 netdevice, e.g. ``pppN``, ``l2tpethN``, through which data frames pass
0030 to/from L2TP. Fields in the L2TP header identify the tunnel or session
0031 and whether it is a control or data packet. When tunnels and sessions
0032 are set up using the Linux kernel API, we're just setting up the L2TP
0033 data path. All aspects of the control protocol are to be handled by
0034 user space.
0035
0036 This split in responsibilities leads to a natural sequence of
0037 operations when establishing tunnels and sessions. The procedure looks
0038 like this:
0039
0040 1) Create a tunnel socket. Exchange L2TP control protocol messages
0041 with the peer over that socket in order to establish a tunnel.
0042
0043 2) Create a tunnel context in the kernel, using information
0044 obtained from the peer using the control protocol messages.
0045
0046 3) Exchange L2TP control protocol messages with the peer over the
0047 tunnel socket in order to establish a session.
0048
0049 4) Create a session context in the kernel using information
0050 obtained from the peer using the control protocol messages.
0051
0052 L2TP APIs
0053 =========
0054
0055 This section documents each userspace API of the L2TP subsystem.
0056
0057 Tunnel Sockets
0058 --------------
0059
0060 L2TPv2 always uses UDP. L2TPv3 may use UDP or IP encapsulation.
0061
0062 To create a tunnel socket for use by L2TP, the standard POSIX
0063 socket API is used.
0064
0065 For example, for a tunnel using IPv4 addresses and UDP encapsulation::
0066
0067 int sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
0068
0069 Or for a tunnel using IPv6 addresses and IP encapsulation::
0070
0071 int sockfd = socket(AF_INET6, SOCK_DGRAM, IPPROTO_L2TP);
0072
0073 UDP socket programming doesn't need to be covered here.
0074
0075 IPPROTO_L2TP is an IP protocol type implemented by the kernel's L2TP
0076 subsystem. The L2TPIP socket address is defined in struct
0077 sockaddr_l2tpip and struct sockaddr_l2tpip6 at
0078 `include/uapi/linux/l2tp.h`_. The address includes the L2TP tunnel
0079 (connection) id. To use L2TP IP encapsulation, an L2TPv3 application
0080 should bind the L2TPIP socket using the locally assigned
0081 tunnel id. When the peer's tunnel id and IP address is known, a
0082 connect must be done.
0083
0084 If the L2TP application needs to handle L2TPv3 tunnel setup requests
0085 from peers using L2TPIP, it must open a dedicated L2TPIP
0086 socket to listen for those requests and bind the socket using tunnel
0087 id 0 since tunnel setup requests are addressed to tunnel id 0.
0088
0089 An L2TP tunnel and all of its sessions are automatically closed when
0090 its tunnel socket is closed.
0091
0092 Netlink API
0093 -----------
0094
0095 L2TP applications use netlink to manage L2TP tunnel and session
0096 instances in the kernel. The L2TP netlink API is defined in
0097 `include/uapi/linux/l2tp.h`_.
0098
0099 L2TP uses `Generic Netlink`_ (GENL). Several commands are defined:
0100 Create, Delete, Modify and Get for tunnel and session
0101 instances, e.g. ``L2TP_CMD_TUNNEL_CREATE``. The API header lists the
0102 netlink attribute types that can be used with each command.
0103
0104 Tunnel and session instances are identified by a locally unique
0105 32-bit id. L2TP tunnel ids are given by ``L2TP_ATTR_CONN_ID`` and
0106 ``L2TP_ATTR_PEER_CONN_ID`` attributes and L2TP session ids are given
0107 by ``L2TP_ATTR_SESSION_ID`` and ``L2TP_ATTR_PEER_SESSION_ID``
0108 attributes. If netlink is used to manage L2TPv2 tunnel and session
0109 instances, the L2TPv2 16-bit tunnel/session id is cast to a 32-bit
0110 value in these attributes.
0111
0112 In the ``L2TP_CMD_TUNNEL_CREATE`` command, ``L2TP_ATTR_FD`` tells the
0113 kernel the tunnel socket fd being used. If not specified, the kernel
0114 creates a kernel socket for the tunnel, using IP parameters set in
0115 ``L2TP_ATTR_IP[6]_SADDR``, ``L2TP_ATTR_IP[6]_DADDR``,
0116 ``L2TP_ATTR_UDP_SPORT``, ``L2TP_ATTR_UDP_DPORT`` attributes. Kernel
0117 sockets are used to implement unmanaged L2TPv3 tunnels (iproute2's "ip
0118 l2tp" commands). If ``L2TP_ATTR_FD`` is given, it must be a socket fd
0119 that is already bound and connected. There is more information about
0120 unmanaged tunnels later in this document.
0121
0122 ``L2TP_CMD_TUNNEL_CREATE`` attributes:-
0123
0124 ================== ======== ===
0125 Attribute Required Use
0126 ================== ======== ===
0127 CONN_ID Y Sets the tunnel (connection) id.
0128 PEER_CONN_ID Y Sets the peer tunnel (connection) id.
0129 PROTO_VERSION Y Protocol version. 2 or 3.
0130 ENCAP_TYPE Y Encapsulation type: UDP or IP.
0131 FD N Tunnel socket file descriptor.
0132 UDP_CSUM N Enable IPv4 UDP checksums. Used only if FD is
0133 not set.
0134 UDP_ZERO_CSUM6_TX N Zero IPv6 UDP checksum on transmit. Used only
0135 if FD is not set.
0136 UDP_ZERO_CSUM6_RX N Zero IPv6 UDP checksum on receive. Used only if
0137 FD is not set.
0138 IP_SADDR N IPv4 source address. Used only if FD is not
0139 set.
0140 IP_DADDR N IPv4 destination address. Used only if FD is
0141 not set.
0142 UDP_SPORT N UDP source port. Used only if FD is not set.
0143 UDP_DPORT N UDP destination port. Used only if FD is not
0144 set.
0145 IP6_SADDR N IPv6 source address. Used only if FD is not
0146 set.
0147 IP6_DADDR N IPv6 destination address. Used only if FD is
0148 not set.
0149 DEBUG N Debug flags.
0150 ================== ======== ===
0151
0152 ``L2TP_CMD_TUNNEL_DESTROY`` attributes:-
0153
0154 ================== ======== ===
0155 Attribute Required Use
0156 ================== ======== ===
0157 CONN_ID Y Identifies the tunnel id to be destroyed.
0158 ================== ======== ===
0159
0160 ``L2TP_CMD_TUNNEL_MODIFY`` attributes:-
0161
0162 ================== ======== ===
0163 Attribute Required Use
0164 ================== ======== ===
0165 CONN_ID Y Identifies the tunnel id to be modified.
0166 DEBUG N Debug flags.
0167 ================== ======== ===
0168
0169 ``L2TP_CMD_TUNNEL_GET`` attributes:-
0170
0171 ================== ======== ===
0172 Attribute Required Use
0173 ================== ======== ===
0174 CONN_ID N Identifies the tunnel id to be queried.
0175 Ignored in DUMP requests.
0176 ================== ======== ===
0177
0178 ``L2TP_CMD_SESSION_CREATE`` attributes:-
0179
0180 ================== ======== ===
0181 Attribute Required Use
0182 ================== ======== ===
0183 CONN_ID Y The parent tunnel id.
0184 SESSION_ID Y Sets the session id.
0185 PEER_SESSION_ID Y Sets the parent session id.
0186 PW_TYPE Y Sets the pseudowire type.
0187 DEBUG N Debug flags.
0188 RECV_SEQ N Enable rx data sequence numbers.
0189 SEND_SEQ N Enable tx data sequence numbers.
0190 LNS_MODE N Enable LNS mode (auto-enable data sequence
0191 numbers).
0192 RECV_TIMEOUT N Timeout to wait when reordering received
0193 packets.
0194 L2SPEC_TYPE N Sets layer2-specific-sublayer type (L2TPv3
0195 only).
0196 COOKIE N Sets optional cookie (L2TPv3 only).
0197 PEER_COOKIE N Sets optional peer cookie (L2TPv3 only).
0198 IFNAME N Sets interface name (L2TPv3 only).
0199 ================== ======== ===
0200
0201 For Ethernet session types, this will create an l2tpeth virtual
0202 interface which can then be configured as required. For PPP session
0203 types, a PPPoL2TP socket must also be opened and connected, mapping it
0204 onto the new session. This is covered in "PPPoL2TP Sockets" later.
0205
0206 ``L2TP_CMD_SESSION_DESTROY`` attributes:-
0207
0208 ================== ======== ===
0209 Attribute Required Use
0210 ================== ======== ===
0211 CONN_ID Y Identifies the parent tunnel id of the session
0212 to be destroyed.
0213 SESSION_ID Y Identifies the session id to be destroyed.
0214 IFNAME N Identifies the session by interface name. If
0215 set, this overrides any CONN_ID and SESSION_ID
0216 attributes. Currently supported for L2TPv3
0217 Ethernet sessions only.
0218 ================== ======== ===
0219
0220 ``L2TP_CMD_SESSION_MODIFY`` attributes:-
0221
0222 ================== ======== ===
0223 Attribute Required Use
0224 ================== ======== ===
0225 CONN_ID Y Identifies the parent tunnel id of the session
0226 to be modified.
0227 SESSION_ID Y Identifies the session id to be modified.
0228 IFNAME N Identifies the session by interface name. If
0229 set, this overrides any CONN_ID and SESSION_ID
0230 attributes. Currently supported for L2TPv3
0231 Ethernet sessions only.
0232 DEBUG N Debug flags.
0233 RECV_SEQ N Enable rx data sequence numbers.
0234 SEND_SEQ N Enable tx data sequence numbers.
0235 LNS_MODE N Enable LNS mode (auto-enable data sequence
0236 numbers).
0237 RECV_TIMEOUT N Timeout to wait when reordering received
0238 packets.
0239 ================== ======== ===
0240
0241 ``L2TP_CMD_SESSION_GET`` attributes:-
0242
0243 ================== ======== ===
0244 Attribute Required Use
0245 ================== ======== ===
0246 CONN_ID N Identifies the tunnel id to be queried.
0247 Ignored for DUMP requests.
0248 SESSION_ID N Identifies the session id to be queried.
0249 Ignored for DUMP requests.
0250 IFNAME N Identifies the session by interface name.
0251 If set, this overrides any CONN_ID and
0252 SESSION_ID attributes. Ignored for DUMP
0253 requests. Currently supported for L2TPv3
0254 Ethernet sessions only.
0255 ================== ======== ===
0256
0257 Application developers should refer to `include/uapi/linux/l2tp.h`_ for
0258 netlink command and attribute definitions.
0259
0260 Sample userspace code using libmnl_:
0261
0262 - Open L2TP netlink socket::
0263
0264 struct nl_sock *nl_sock;
0265 int l2tp_nl_family_id;
0266
0267 nl_sock = nl_socket_alloc();
0268 genl_connect(nl_sock);
0269 genl_id = genl_ctrl_resolve(nl_sock, L2TP_GENL_NAME);
0270
0271 - Create a tunnel::
0272
0273 struct nlmsghdr *nlh;
0274 struct genlmsghdr *gnlh;
0275
0276 nlh = mnl_nlmsg_put_header(buf);
0277 nlh->nlmsg_type = genl_id; /* assigned to genl socket */
0278 nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK;
0279 nlh->nlmsg_seq = seq;
0280
0281 gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh));
0282 gnlh->cmd = L2TP_CMD_TUNNEL_CREATE;
0283 gnlh->version = L2TP_GENL_VERSION;
0284 gnlh->reserved = 0;
0285
0286 mnl_attr_put_u32(nlh, L2TP_ATTR_FD, tunl_sock_fd);
0287 mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid);
0288 mnl_attr_put_u32(nlh, L2TP_ATTR_PEER_CONN_ID, peer_tid);
0289 mnl_attr_put_u8(nlh, L2TP_ATTR_PROTO_VERSION, protocol_version);
0290 mnl_attr_put_u16(nlh, L2TP_ATTR_ENCAP_TYPE, encap);
0291
0292 - Create a session::
0293
0294 struct nlmsghdr *nlh;
0295 struct genlmsghdr *gnlh;
0296
0297 nlh = mnl_nlmsg_put_header(buf);
0298 nlh->nlmsg_type = genl_id; /* assigned to genl socket */
0299 nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK;
0300 nlh->nlmsg_seq = seq;
0301
0302 gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh));
0303 gnlh->cmd = L2TP_CMD_SESSION_CREATE;
0304 gnlh->version = L2TP_GENL_VERSION;
0305 gnlh->reserved = 0;
0306
0307 mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid);
0308 mnl_attr_put_u32(nlh, L2TP_ATTR_PEER_CONN_ID, peer_tid);
0309 mnl_attr_put_u32(nlh, L2TP_ATTR_SESSION_ID, sid);
0310 mnl_attr_put_u32(nlh, L2TP_ATTR_PEER_SESSION_ID, peer_sid);
0311 mnl_attr_put_u16(nlh, L2TP_ATTR_PW_TYPE, pwtype);
0312 /* there are other session options which can be set using netlink
0313 * attributes during session creation -- see l2tp.h
0314 */
0315
0316 - Delete a session::
0317
0318 struct nlmsghdr *nlh;
0319 struct genlmsghdr *gnlh;
0320
0321 nlh = mnl_nlmsg_put_header(buf);
0322 nlh->nlmsg_type = genl_id; /* assigned to genl socket */
0323 nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK;
0324 nlh->nlmsg_seq = seq;
0325
0326 gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh));
0327 gnlh->cmd = L2TP_CMD_SESSION_DELETE;
0328 gnlh->version = L2TP_GENL_VERSION;
0329 gnlh->reserved = 0;
0330
0331 mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid);
0332 mnl_attr_put_u32(nlh, L2TP_ATTR_SESSION_ID, sid);
0333
0334 - Delete a tunnel and all of its sessions (if any)::
0335
0336 struct nlmsghdr *nlh;
0337 struct genlmsghdr *gnlh;
0338
0339 nlh = mnl_nlmsg_put_header(buf);
0340 nlh->nlmsg_type = genl_id; /* assigned to genl socket */
0341 nlh->nlmsg_flags = NLM_F_REQUEST | NLM_F_ACK;
0342 nlh->nlmsg_seq = seq;
0343
0344 gnlh = mnl_nlmsg_put_extra_header(nlh, sizeof(*gnlh));
0345 gnlh->cmd = L2TP_CMD_TUNNEL_DELETE;
0346 gnlh->version = L2TP_GENL_VERSION;
0347 gnlh->reserved = 0;
0348
0349 mnl_attr_put_u32(nlh, L2TP_ATTR_CONN_ID, tid);
0350
0351 PPPoL2TP Session Socket API
0352 ---------------------------
0353
0354 For PPP session types, a PPPoL2TP socket must be opened and connected
0355 to the L2TP session.
0356
0357 When creating PPPoL2TP sockets, the application provides information
0358 to the kernel about the tunnel and session in a socket connect()
0359 call. Source and destination tunnel and session ids are provided, as
0360 well as the file descriptor of a UDP or L2TPIP socket. See struct
0361 pppol2tp_addr in `include/linux/if_pppol2tp.h`_. For historical reasons,
0362 there are unfortunately slightly different address structures for
0363 L2TPv2/L2TPv3 IPv4/IPv6 tunnels and userspace must use the appropriate
0364 structure that matches the tunnel socket type.
0365
0366 Userspace may control behavior of the tunnel or session using
0367 setsockopt and ioctl on the PPPoX socket. The following socket
0368 options are supported:-
0369
0370 ========= ===========================================================
0371 DEBUG bitmask of debug message categories. See below.
0372 SENDSEQ - 0 => don't send packets with sequence numbers
0373 - 1 => send packets with sequence numbers
0374 RECVSEQ - 0 => receive packet sequence numbers are optional
0375 - 1 => drop receive packets without sequence numbers
0376 LNSMODE - 0 => act as LAC.
0377 - 1 => act as LNS.
0378 REORDERTO reorder timeout (in millisecs). If 0, don't try to reorder.
0379 ========= ===========================================================
0380
0381 In addition to the standard PPP ioctls, a PPPIOCGL2TPSTATS is provided
0382 to retrieve tunnel and session statistics from the kernel using the
0383 PPPoX socket of the appropriate tunnel or session.
0384
0385 Sample userspace code:
0386
0387 - Create session PPPoX data socket::
0388
0389 struct sockaddr_pppol2tp sax;
0390 int fd;
0391
0392 /* Note, the tunnel socket must be bound already, else it
0393 * will not be ready
0394 */
0395 sax.sa_family = AF_PPPOX;
0396 sax.sa_protocol = PX_PROTO_OL2TP;
0397 sax.pppol2tp.fd = tunnel_fd;
0398 sax.pppol2tp.addr.sin_addr.s_addr = addr->sin_addr.s_addr;
0399 sax.pppol2tp.addr.sin_port = addr->sin_port;
0400 sax.pppol2tp.addr.sin_family = AF_INET;
0401 sax.pppol2tp.s_tunnel = tunnel_id;
0402 sax.pppol2tp.s_session = session_id;
0403 sax.pppol2tp.d_tunnel = peer_tunnel_id;
0404 sax.pppol2tp.d_session = peer_session_id;
0405
0406 /* session_fd is the fd of the session's PPPoL2TP socket.
0407 * tunnel_fd is the fd of the tunnel UDP / L2TPIP socket.
0408 */
0409 fd = connect(session_fd, (struct sockaddr *)&sax, sizeof(sax));
0410 if (fd < 0 ) {
0411 return -errno;
0412 }
0413 return 0;
0414
0415 Old L2TPv2-only API
0416 -------------------
0417
0418 When L2TP was first added to the Linux kernel in 2.6.23, it
0419 implemented only L2TPv2 and did not include a netlink API. Instead,
0420 tunnel and session instances in the kernel were managed directly using
0421 only PPPoL2TP sockets. The PPPoL2TP socket is used as described in
0422 section "PPPoL2TP Session Socket API" but tunnel and session instances
0423 are automatically created on a connect() of the socket instead of
0424 being created by a separate netlink request:
0425
0426 - Tunnels are managed using a tunnel management socket which is a
0427 dedicated PPPoL2TP socket, connected to (invalid) session
0428 id 0. The L2TP tunnel instance is created when the PPPoL2TP
0429 tunnel management socket is connected and is destroyed when the
0430 socket is closed.
0431
0432 - Session instances are created in the kernel when a PPPoL2TP
0433 socket is connected to a non-zero session id. Session parameters
0434 are set using setsockopt. The L2TP session instance is destroyed
0435 when the socket is closed.
0436
0437 This API is still supported but its use is discouraged. Instead, new
0438 L2TPv2 applications should use netlink to first create the tunnel and
0439 session, then create a PPPoL2TP socket for the session.
0440
0441 Unmanaged L2TPv3 tunnels
0442 ------------------------
0443
0444 The kernel L2TP subsystem also supports static (unmanaged) L2TPv3
0445 tunnels. Unmanaged tunnels have no userspace tunnel socket, and
0446 exchange no control messages with the peer to set up the tunnel; the
0447 tunnel is configured manually at each end of the tunnel. All
0448 configuration is done using netlink. There is no need for an L2TP
0449 userspace application in this case -- the tunnel socket is created by
0450 the kernel and configured using parameters sent in the
0451 ``L2TP_CMD_TUNNEL_CREATE`` netlink request. The ``ip`` utility of
0452 ``iproute2`` has commands for managing static L2TPv3 tunnels; do ``ip
0453 l2tp help`` for more information.
0454
0455 Debugging
0456 ---------
0457
0458 The L2TP subsystem offers a range of debugging interfaces through the
0459 debugfs filesystem.
0460
0461 To access these interfaces, the debugfs filesystem must first be mounted::
0462
0463 # mount -t debugfs debugfs /debug
0464
0465 Files under the l2tp directory can then be accessed, providing a summary
0466 of the current population of tunnel and session contexts existing in the
0467 kernel::
0468
0469 # cat /debug/l2tp/tunnels
0470
0471 The debugfs files should not be used by applications to obtain L2TP
0472 state information because the file format is subject to change. It is
0473 implemented to provide extra debug information to help diagnose
0474 problems. Applications should instead use the netlink API.
0475
0476 In addition the L2TP subsystem implements tracepoints using the standard
0477 kernel event tracing API. The available L2TP events can be reviewed as
0478 follows::
0479
0480 # find /debug/tracing/events/l2tp
0481
0482 Finally, /proc/net/pppol2tp is also provided for backwards compatibility
0483 with the original pppol2tp code. It lists information about L2TPv2
0484 tunnels and sessions only. Its use is discouraged.
0485
0486 Internal Implementation
0487 =======================
0488
0489 This section is for kernel developers and maintainers.
0490
0491 Sockets
0492 -------
0493
0494 UDP sockets are implemented by the networking core. When an L2TP
0495 tunnel is created using a UDP socket, the socket is set up as an
0496 encapsulated UDP socket by setting encap_rcv and encap_destroy
0497 callbacks on the UDP socket. l2tp_udp_encap_recv is called when
0498 packets are received on the socket. l2tp_udp_encap_destroy is called
0499 when userspace closes the socket.
0500
0501 L2TPIP sockets are implemented in `net/l2tp/l2tp_ip.c`_ and
0502 `net/l2tp/l2tp_ip6.c`_.
0503
0504 Tunnels
0505 -------
0506
0507 The kernel keeps a struct l2tp_tunnel context per L2TP tunnel. The
0508 l2tp_tunnel is always associated with a UDP or L2TP/IP socket and
0509 keeps a list of sessions in the tunnel. When a tunnel is first
0510 registered with L2TP core, the reference count on the socket is
0511 increased. This ensures that the socket cannot be removed while L2TP's
0512 data structures reference it.
0513
0514 Tunnels are identified by a unique tunnel id. The id is 16-bit for
0515 L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit
0516 value.
0517
0518 Tunnels are kept in a per-net list, indexed by tunnel id. The tunnel
0519 id namespace is shared by L2TPv2 and L2TPv3. The tunnel context can be
0520 derived from the socket's sk_user_data.
0521
0522 Handling tunnel socket close is perhaps the most tricky part of the
0523 L2TP implementation. If userspace closes a tunnel socket, the L2TP
0524 tunnel and all of its sessions must be closed and destroyed. Since the
0525 tunnel context holds a ref on the tunnel socket, the socket's
0526 sk_destruct won't be called until the tunnel sock_put's its
0527 socket. For UDP sockets, when userspace closes the tunnel socket, the
0528 socket's encap_destroy handler is invoked, which L2TP uses to initiate
0529 its tunnel close actions. For L2TPIP sockets, the socket's close
0530 handler initiates the same tunnel close actions. All sessions are
0531 first closed. Each session drops its tunnel ref. When the tunnel ref
0532 reaches zero, the tunnel puts its socket ref. When the socket is
0533 eventually destroyed, its sk_destruct finally frees the L2TP tunnel
0534 context.
0535
0536 Sessions
0537 --------
0538
0539 The kernel keeps a struct l2tp_session context for each session. Each
0540 session has private data which is used for data specific to the
0541 session type. With L2TPv2, the session always carries PPP
0542 traffic. With L2TPv3, the session can carry Ethernet frames (Ethernet
0543 pseudowire) or other data types such as PPP, ATM, HDLC or Frame
0544 Relay. Linux currently implements only Ethernet and PPP session types.
0545
0546 Some L2TP session types also have a socket (PPP pseudowires) while
0547 others do not (Ethernet pseudowires). We can't therefore use the
0548 socket reference count as the reference count for session
0549 contexts. The L2TP implementation therefore has its own internal
0550 reference counts on the session contexts.
0551
0552 Like tunnels, L2TP sessions are identified by a unique
0553 session id. Just as with tunnel ids, the session id is 16-bit for
0554 L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit
0555 value.
0556
0557 Sessions hold a ref on their parent tunnel to ensure that the tunnel
0558 stays extant while one or more sessions references it.
0559
0560 Sessions are kept in a per-tunnel list, indexed by session id. L2TPv3
0561 sessions are also kept in a per-net list indexed by session id,
0562 because L2TPv3 session ids are unique across all tunnels and L2TPv3
0563 data packets do not contain a tunnel id in the header. This list is
0564 therefore needed to find the session context associated with a
0565 received data packet when the tunnel context cannot be derived from
0566 the tunnel socket.
0567
0568 Although the L2TPv3 RFC specifies that L2TPv3 session ids are not
0569 scoped by the tunnel, the kernel does not police this for L2TPv3 UDP
0570 tunnels and does not add sessions of L2TPv3 UDP tunnels into the
0571 per-net session list. In the UDP receive code, we must trust that the
0572 tunnel can be identified using the tunnel socket's sk_user_data and
0573 lookup the session in the tunnel's session list instead of the per-net
0574 session list.
0575
0576 PPP
0577 ---
0578
0579 `net/l2tp/l2tp_ppp.c`_ implements the PPPoL2TP socket family. Each PPP
0580 session has a PPPoL2TP socket.
0581
0582 The PPPoL2TP socket's sk_user_data references the l2tp_session.
0583
0584 Userspace sends and receives PPP packets over L2TP using a PPPoL2TP
0585 socket. Only PPP control frames pass over this socket: PPP data
0586 packets are handled entirely by the kernel, passing between the L2TP
0587 session and its associated ``pppN`` netdev through the PPP channel
0588 interface of the kernel PPP subsystem.
0589
0590 The L2TP PPP implementation handles the closing of a PPPoL2TP socket
0591 by closing its corresponding L2TP session. This is complicated because
0592 it must consider racing with netlink session create/destroy requests
0593 and pppol2tp_connect trying to reconnect with a session that is in the
0594 process of being closed. Unlike tunnels, PPP sessions do not hold a
0595 ref on their associated socket, so code must be careful to sock_hold
0596 the socket where necessary. For all the details, see commit
0597 3d609342cc04129ff7568e19316ce3d7451a27e8.
0598
0599 Ethernet
0600 --------
0601
0602 `net/l2tp/l2tp_eth.c`_ implements L2TPv3 Ethernet pseudowires. It
0603 manages a netdev for each session.
0604
0605 L2TP Ethernet sessions are created and destroyed by netlink request,
0606 or are destroyed when the tunnel is destroyed. Unlike PPP sessions,
0607 Ethernet sessions do not have an associated socket.
0608
0609 Miscellaneous
0610 =============
0611
0612 RFCs
0613 ----
0614
0615 The kernel code implements the datapath features specified in the
0616 following RFCs:
0617
0618 ======= =============== ===================================
0619 RFC2661 L2TPv2 https://tools.ietf.org/html/rfc2661
0620 RFC3931 L2TPv3 https://tools.ietf.org/html/rfc3931
0621 RFC4719 L2TPv3 Ethernet https://tools.ietf.org/html/rfc4719
0622 ======= =============== ===================================
0623
0624 Implementations
0625 ---------------
0626
0627 A number of open source applications use the L2TP kernel subsystem:
0628
0629 ============ ==============================================
0630 iproute2 https://github.com/shemminger/iproute2
0631 go-l2tp https://github.com/katalix/go-l2tp
0632 tunneldigger https://github.com/wlanslovenija/tunneldigger
0633 xl2tpd https://github.com/xelerance/xl2tpd
0634 ============ ==============================================
0635
0636 Limitations
0637 -----------
0638
0639 The current implementation has a number of limitations:
0640
0641 1) Multiple UDP sockets with the same 5-tuple address cannot be
0642 used. The kernel's tunnel context is identified using private
0643 data associated with the socket so it is important that each
0644 socket is uniquely identified by its address.
0645
0646 2) Interfacing with openvswitch is not yet implemented. It may be
0647 useful to map OVS Ethernet and VLAN ports into L2TPv3 tunnels.
0648
0649 3) VLAN pseudowires are implemented using an ``l2tpethN`` interface
0650 configured with a VLAN sub-interface. Since L2TPv3 VLAN
0651 pseudowires carry one and only one VLAN, it may be better to use
0652 a single netdevice rather than an ``l2tpethN`` and ``l2tpethN``:M
0653 pair per VLAN session. The netlink attribute
0654 ``L2TP_ATTR_VLAN_ID`` was added for this, but it was never
0655 implemented.
0656
0657 Testing
0658 -------
0659
0660 Unmanaged L2TPv3 Ethernet features are tested by the kernel's built-in
0661 selftests. See `tools/testing/selftests/net/l2tp.sh`_.
0662
0663 Another test suite, l2tp-ktest_, covers all
0664 of the L2TP APIs and tunnel/session types. This may be integrated into
0665 the kernel's built-in L2TP selftests in the future.
0666
0667 .. Links
0668 .. _Generic Netlink: generic_netlink.html
0669 .. _libmnl: https://www.netfilter.org/projects/libmnl
0670 .. _include/uapi/linux/l2tp.h: ../../../include/uapi/linux/l2tp.h
0671 .. _include/linux/if_pppol2tp.h: ../../../include/linux/if_pppol2tp.h
0672 .. _net/l2tp/l2tp_ip.c: ../../../net/l2tp/l2tp_ip.c
0673 .. _net/l2tp/l2tp_ip6.c: ../../../net/l2tp/l2tp_ip6.c
0674 .. _net/l2tp/l2tp_ppp.c: ../../../net/l2tp/l2tp_ppp.c
0675 .. _net/l2tp/l2tp_eth.c: ../../../net/l2tp/l2tp_eth.c
0676 .. _tools/testing/selftests/net/l2tp.sh: ../../../tools/testing/selftests/net/l2tp.sh
0677 .. _l2tp-ktest: https://github.com/katalix/l2tp-ktest
