1.. SPDX-License-Identifier: GPL-2.0 2 3==== 4L2TP 5==== 6 7This document describes how to use the kernel's L2TP drivers to 8provide L2TP functionality. L2TP is a protocol that tunnels one or 9more sessions over an IP tunnel. It is commonly used for VPNs 10(L2TP/IPSec) and by ISPs to tunnel subscriber PPP sessions over an IP 11network infrastructure. With L2TPv3, it is also useful as a Layer-2 12tunneling infrastructure. 13 14Features 15======== 16 17L2TPv2 (PPP over L2TP (UDP tunnels)). 18L2TPv3 ethernet pseudowires. 19L2TPv3 PPP pseudowires. 20L2TPv3 IP encapsulation. 21Netlink sockets for L2TPv3 configuration management. 22 23History 24======= 25 26The original pppol2tp driver was introduced in 2.6.23 and provided 27L2TPv2 functionality (rfc2661). L2TPv2 is used to tunnel one or more PPP 28sessions over a UDP tunnel. 29 30L2TPv3 (rfc3931) changes the protocol to allow different frame types 31to be passed over an L2TP tunnel by moving the PPP-specific parts of 32the protocol out of the core L2TP packet headers. Each frame type is 33known as a pseudowire type. Ethernet, PPP, HDLC, Frame Relay and ATM 34pseudowires for L2TP are defined in separate RFC standards. Another 35change for L2TPv3 is that it can be carried directly over IP with no 36UDP header (UDP is optional). It is also possible to create static 37unmanaged L2TPv3 tunnels manually without a control protocol 38(userspace daemon) to manage them. 39 40To support L2TPv3, the original pppol2tp driver was split up to 41separate the L2TP and PPP functionality. Existing L2TPv2 userspace 42apps should be unaffected as the original pppol2tp sockets API is 43retained. L2TPv3, however, uses netlink to manage L2TPv3 tunnels and 44sessions. 45 46Design 47====== 48 49The L2TP protocol separates control and data frames. The L2TP kernel 50drivers handle only L2TP data frames; control frames are always 51handled by userspace. L2TP control frames carry messages between L2TP 52clients/servers and are used to setup / teardown tunnels and 53sessions. An L2TP client or server is implemented in userspace. 54 55Each L2TP tunnel is implemented using a UDP or L2TPIP socket; L2TPIP 56provides L2TPv3 IP encapsulation (no UDP) and is implemented using a 57new l2tpip socket family. The tunnel socket is typically created by 58userspace, though for unmanaged L2TPv3 tunnels, the socket can also be 59created by the kernel. Each L2TP session (pseudowire) gets a network 60interface instance. In the case of PPP, these interfaces are created 61indirectly by pppd using a pppol2tp socket. In the case of ethernet, 62the netdevice is created upon a netlink request to create an L2TPv3 63ethernet pseudowire. 64 65For PPP, the PPPoL2TP driver, net/l2tp/l2tp_ppp.c, provides a 66mechanism by which PPP frames carried through an L2TP session are 67passed through the kernel's PPP subsystem. The standard PPP daemon, 68pppd, handles all PPP interaction with the peer. PPP network 69interfaces are created for each local PPP endpoint. The kernel's PPP 70subsystem arranges for PPP control frames to be delivered to pppd, 71while data frames are forwarded as usual. 72 73For ethernet, the L2TPETH driver, net/l2tp/l2tp_eth.c, implements a 74netdevice driver, managing virtual ethernet devices, one per 75pseudowire. These interfaces can be managed using standard Linux tools 76such as "ip" and "ifconfig". If only IP frames are passed over the 77tunnel, the interface can be given an IP addresses of itself and its 78peer. If non-IP frames are to be passed over the tunnel, the interface 79can be added to a bridge using brctl. All L2TP datapath protocol 80functions are handled by the L2TP core driver. 81 82Each tunnel and session within a tunnel is assigned a unique tunnel_id 83and session_id. These ids are carried in the L2TP header of every 84control and data packet. (Actually, in L2TPv3, the tunnel_id isn't 85present in data frames - it is inferred from the IP connection on 86which the packet was received.) The L2TP driver uses the ids to lookup 87internal tunnel and/or session contexts to determine how to handle the 88packet. Zero tunnel / session ids are treated specially - zero ids are 89never assigned to tunnels or sessions in the network. In the driver, 90the tunnel context keeps a reference to the tunnel UDP or L2TPIP 91socket. The session context holds data that lets the driver interface 92to the kernel's network frame type subsystems, i.e. PPP, ethernet. 93 94Userspace Programming 95===================== 96 97For L2TPv2, there are a number of requirements on the userspace L2TP 98daemon in order to use the pppol2tp driver. 99 1001. Use a UDP socket per tunnel. 101 1022. Create a single PPPoL2TP socket per tunnel bound to a special null 103 session id. This is used only for communicating with the driver but 104 must remain open while the tunnel is active. Opening this tunnel 105 management socket causes the driver to mark the tunnel socket as an 106 L2TP UDP encapsulation socket and flags it for use by the 107 referenced tunnel id. This hooks up the UDP receive path via 108 udp_encap_rcv() in net/ipv4/udp.c. PPP data frames are never passed 109 in this special PPPoX socket. 110 1113. Create a PPPoL2TP socket per L2TP session. This is typically done 112 by starting pppd with the pppol2tp plugin and appropriate 113 arguments. A PPPoL2TP tunnel management socket (Step 2) must be 114 created before the first PPPoL2TP session socket is created. 115 116When creating PPPoL2TP sockets, the application provides information 117to the driver about the socket in a socket connect() call. Source and 118destination tunnel and session ids are provided, as well as the file 119descriptor of a UDP socket. See struct pppol2tp_addr in 120include/linux/if_pppol2tp.h. Note that zero tunnel / session ids are 121treated specially. When creating the per-tunnel PPPoL2TP management 122socket in Step 2 above, zero source and destination session ids are 123specified, which tells the driver to prepare the supplied UDP file 124descriptor for use as an L2TP tunnel socket. 125 126Userspace may control behavior of the tunnel or session using 127setsockopt and ioctl on the PPPoX socket. The following socket 128options are supported:- 129 130========= =========================================================== 131DEBUG bitmask of debug message categories. See below. 132SENDSEQ - 0 => don't send packets with sequence numbers 133 - 1 => send packets with sequence numbers 134RECVSEQ - 0 => receive packet sequence numbers are optional 135 - 1 => drop receive packets without sequence numbers 136LNSMODE - 0 => act as LAC. 137 - 1 => act as LNS. 138REORDERTO reorder timeout (in millisecs). If 0, don't try to reorder. 139========= =========================================================== 140 141Only the DEBUG option is supported by the special tunnel management 142PPPoX socket. 143 144In addition to the standard PPP ioctls, a PPPIOCGL2TPSTATS is provided 145to retrieve tunnel and session statistics from the kernel using the 146PPPoX socket of the appropriate tunnel or session. 147 148For L2TPv3, userspace must use the netlink API defined in 149include/linux/l2tp.h to manage tunnel and session contexts. The 150general procedure to create a new L2TP tunnel with one session is:- 151 1521. Open a GENL socket using L2TP_GENL_NAME for configuring the kernel 153 using netlink. 154 1552. Create a UDP or L2TPIP socket for the tunnel. 156 1573. Create a new L2TP tunnel using a L2TP_CMD_TUNNEL_CREATE 158 request. Set attributes according to desired tunnel parameters, 159 referencing the UDP or L2TPIP socket created in the previous step. 160 1614. Create a new L2TP session in the tunnel using a 162 L2TP_CMD_SESSION_CREATE request. 163 164The tunnel and all of its sessions are closed when the tunnel socket 165is closed. The netlink API may also be used to delete sessions and 166tunnels. Configuration and status info may be set or read using netlink. 167 168The L2TP driver also supports static (unmanaged) L2TPv3 tunnels. These 169are where there is no L2TP control message exchange with the peer to 170setup the tunnel; the tunnel is configured manually at each end of the 171tunnel. There is no need for an L2TP userspace application in this 172case -- the tunnel socket is created by the kernel and configured 173using parameters sent in the L2TP_CMD_TUNNEL_CREATE netlink 174request. The "ip" utility of iproute2 has commands for managing static 175L2TPv3 tunnels; do "ip l2tp help" for more information. 176 177Debugging 178========= 179 180The driver supports a flexible debug scheme where kernel trace 181messages may be optionally enabled per tunnel and per session. Care is 182needed when debugging a live system since the messages are not 183rate-limited and a busy system could be swamped. Userspace uses 184setsockopt on the PPPoX socket to set a debug mask. 185 186The following debug mask bits are available: 187 188================ ============================== 189L2TP_MSG_DEBUG verbose debug (if compiled in) 190L2TP_MSG_CONTROL userspace - kernel interface 191L2TP_MSG_SEQ sequence numbers handling 192L2TP_MSG_DATA data packets 193================ ============================== 194 195If enabled, files under a l2tp debugfs directory can be used to dump 196kernel state about L2TP tunnels and sessions. To access it, the 197debugfs filesystem must first be mounted:: 198 199 # mount -t debugfs debugfs /debug 200 201Files under the l2tp directory can then be accessed:: 202 203 # cat /debug/l2tp/tunnels 204 205The debugfs files should not be used by applications to obtain L2TP 206state information because the file format is subject to change. It is 207implemented to provide extra debug information to help diagnose 208problems.) Users should use the netlink API. 209 210/proc/net/pppol2tp is also provided for backwards compatibility with 211the original pppol2tp driver. It lists information about L2TPv2 212tunnels and sessions only. Its use is discouraged. 213 214Unmanaged L2TPv3 Tunnels 215======================== 216 217Some commercial L2TP products support unmanaged L2TPv3 ethernet 218tunnels, where there is no L2TP control protocol; tunnels are 219configured at each side manually. New commands are available in 220iproute2's ip utility to support this. 221 222To create an L2TPv3 ethernet pseudowire between local host 192.168.1.1 223and peer 192.168.1.2, using IP addresses 10.5.1.1 and 10.5.1.2 for the 224tunnel endpoints:: 225 226 # ip l2tp add tunnel tunnel_id 1 peer_tunnel_id 1 udp_sport 5000 \ 227 udp_dport 5000 encap udp local 192.168.1.1 remote 192.168.1.2 228 # ip l2tp add session tunnel_id 1 session_id 1 peer_session_id 1 229 # ip -s -d show dev l2tpeth0 230 # ip addr add 10.5.1.2/32 peer 10.5.1.1/32 dev l2tpeth0 231 # ip li set dev l2tpeth0 up 232 233Choose IP addresses to be the address of a local IP interface and that 234of the remote system. The IP addresses of the l2tpeth0 interface can be 235anything suitable. 236 237Repeat the above at the peer, with ports, tunnel/session ids and IP 238addresses reversed. The tunnel and session IDs can be any non-zero 23932-bit number, but the values must be reversed at the peer. 240 241======================== =================== 242Host 1 Host2 243======================== =================== 244udp_sport=5000 udp_sport=5001 245udp_dport=5001 udp_dport=5000 246tunnel_id=42 tunnel_id=45 247peer_tunnel_id=45 peer_tunnel_id=42 248session_id=128 session_id=5196755 249peer_session_id=5196755 peer_session_id=128 250======================== =================== 251 252When done at both ends of the tunnel, it should be possible to send 253data over the network. e.g.:: 254 255 # ping 10.5.1.1 256 257 258Sample Userspace Code 259===================== 260 2611. Create tunnel management PPPoX socket:: 262 263 kernel_fd = socket(AF_PPPOX, SOCK_DGRAM, PX_PROTO_OL2TP); 264 if (kernel_fd >= 0) { 265 struct sockaddr_pppol2tp sax; 266 struct sockaddr_in const *peer_addr; 267 268 peer_addr = l2tp_tunnel_get_peer_addr(tunnel); 269 memset(&sax, 0, sizeof(sax)); 270 sax.sa_family = AF_PPPOX; 271 sax.sa_protocol = PX_PROTO_OL2TP; 272 sax.pppol2tp.fd = udp_fd; /* fd of tunnel UDP socket */ 273 sax.pppol2tp.addr.sin_addr.s_addr = peer_addr->sin_addr.s_addr; 274 sax.pppol2tp.addr.sin_port = peer_addr->sin_port; 275 sax.pppol2tp.addr.sin_family = AF_INET; 276 sax.pppol2tp.s_tunnel = tunnel_id; 277 sax.pppol2tp.s_session = 0; /* special case: mgmt socket */ 278 sax.pppol2tp.d_tunnel = 0; 279 sax.pppol2tp.d_session = 0; /* special case: mgmt socket */ 280 281 if(connect(kernel_fd, (struct sockaddr *)&sax, sizeof(sax) ) < 0 ) { 282 perror("connect failed"); 283 result = -errno; 284 goto err; 285 } 286 } 287 2882. Create session PPPoX data socket:: 289 290 struct sockaddr_pppol2tp sax; 291 int fd; 292 293 /* Note, the target socket must be bound already, else it will not be ready */ 294 sax.sa_family = AF_PPPOX; 295 sax.sa_protocol = PX_PROTO_OL2TP; 296 sax.pppol2tp.fd = tunnel_fd; 297 sax.pppol2tp.addr.sin_addr.s_addr = addr->sin_addr.s_addr; 298 sax.pppol2tp.addr.sin_port = addr->sin_port; 299 sax.pppol2tp.addr.sin_family = AF_INET; 300 sax.pppol2tp.s_tunnel = tunnel_id; 301 sax.pppol2tp.s_session = session_id; 302 sax.pppol2tp.d_tunnel = peer_tunnel_id; 303 sax.pppol2tp.d_session = peer_session_id; 304 305 /* session_fd is the fd of the session's PPPoL2TP socket. 306 * tunnel_fd is the fd of the tunnel UDP socket. 307 */ 308 fd = connect(session_fd, (struct sockaddr *)&sax, sizeof(sax)); 309 if (fd < 0 ) { 310 return -errno; 311 } 312 return 0; 313 314Internal Implementation 315======================= 316 317The driver keeps a struct l2tp_tunnel context per L2TP tunnel and a 318struct l2tp_session context for each session. The l2tp_tunnel is 319always associated with a UDP or L2TP/IP socket and keeps a list of 320sessions in the tunnel. The l2tp_session context keeps kernel state 321about the session. It has private data which is used for data specific 322to the session type. With L2TPv2, the session always carried PPP 323traffic. With L2TPv3, the session can also carry ethernet frames 324(ethernet pseudowire) or other data types such as ATM, HDLC or Frame 325Relay. 326 327When a tunnel is first opened, the reference count on the socket is 328increased using sock_hold(). This ensures that the kernel socket 329cannot be removed while L2TP's data structures reference it. 330 331Some L2TP sessions also have a socket (PPP pseudowires) while others 332do not (ethernet pseudowires). We can't use the socket reference count 333as the reference count for session contexts. The L2TP implementation 334therefore has its own internal reference counts on the session 335contexts. 336 337To Do 338===== 339 340Add L2TP tunnel switching support. This would route tunneled traffic 341from one L2TP tunnel into another. Specified in 342http://tools.ietf.org/html/draft-ietf-l2tpext-tunnel-switching-08 343 344Add L2TPv3 VLAN pseudowire support. 345 346Add L2TPv3 IP pseudowire support. 347 348Add L2TPv3 ATM pseudowire support. 349 350Miscellaneous 351============= 352 353The L2TP drivers were developed as part of the OpenL2TP project by 354Katalix Systems Ltd. OpenL2TP is a full-featured L2TP client / server, 355designed from the ground up to have the L2TP datapath in the 356kernel. The project also implemented the pppol2tp plugin for pppd 357which allows pppd to use the kernel driver. Details can be found at 358http://www.openl2tp.org. 359