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