l2tp.rst 27 KB

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