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