| 1 | |
| 2 |
|
| 3 | ====
|
| 4 | L2TP
|
| 5 | ====
|
| 6 |
|
| 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
|
| 16 | ========
|
| 17 |
|
| 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.
|
| 356 |
|
| 357 | When creating PPPoL2TP sockets, the application provides information
|
| 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.
|
| 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 |
|
| 370 | ========= ===========================================================
|
| 371 | DEBUG bitmask of debug message categories. See below.
|
| 372 | SENDSEQ - 0 => don't send packets with sequence numbers
|
| 373 | - 1 => send packets with sequence numbers
|
| 374 | RECVSEQ - 0 => receive packet sequence numbers are optional
|
| 375 | - 1 => drop receive packets without sequence numbers
|
| 376 | LNSMODE - 0 => act as LAC.
|
| 377 | - 1 => act as LNS.
|
| 378 | REORDERTO reorder timeout (in millisecs). If 0, don't try to reorder.
|
| 379 | ========= ===========================================================
|
| 380 |
|
| 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 |
|
| 385 | Sample userspace code:
|
| 386 |
|
| 387 | - Create session PPPoX data socket::
|
| 388 |
|
| 389 | /* Input: the L2TP tunnel UDP socket `tunnel_fd`, which needs to be
|
| 390 | * bound already (both sockname and peername), otherwise it will not be
|
| 391 | * ready.
|
| 392 | */
|
| 393 |
|
| 394 | struct sockaddr_pppol2tp sax;
|
| 395 | int session_fd;
|
| 396 | int ret;
|
| 397 |
|
| 398 | session_fd = socket(AF_PPPOX, SOCK_DGRAM, PX_PROTO_OL2TP);
|
| 399 | if (session_fd < 0)
|
| 400 | return -errno;
|
| 401 |
|
| 402 | sax.sa_family = AF_PPPOX;
|
| 403 | sax.sa_protocol = PX_PROTO_OL2TP;
|
| 404 | sax.pppol2tp.fd = tunnel_fd;
|
| 405 | sax.pppol2tp.addr.sin_addr.s_addr = addr->sin_addr.s_addr;
|
| 406 | sax.pppol2tp.addr.sin_port = addr->sin_port;
|
| 407 | sax.pppol2tp.addr.sin_family = AF_INET;
|
| 408 | sax.pppol2tp.s_tunnel = tunnel_id;
|
| 409 | sax.pppol2tp.s_session = session_id;
|
| 410 | sax.pppol2tp.d_tunnel = peer_tunnel_id;
|
| 411 | sax.pppol2tp.d_session = peer_session_id;
|
| 412 |
|
| 413 | /* session_fd is the fd of the session's PPPoL2TP socket.
|
| 414 | * tunnel_fd is the fd of the tunnel UDP / L2TPIP socket.
|
| 415 | */
|
| 416 | ret = connect(session_fd, (struct sockaddr *)&sax, sizeof(sax));
|
| 417 | if (ret < 0 ) {
|
| 418 | close(session_fd);
|
| 419 | return -errno;
|
| 420 | }
|
| 421 |
|
| 422 | return session_fd;
|
| 423 |
|
| 424 | L2TP control packets will still be available for read on `tunnel_fd`.
|
| 425 |
|
| 426 | - Create PPP channel::
|
| 427 |
|
| 428 | /* Input: the session PPPoX data socket `session_fd` which was created
|
| 429 | * as described above.
|
| 430 | */
|
| 431 |
|
| 432 | int ppp_chan_fd;
|
| 433 | int chindx;
|
| 434 | int ret;
|
| 435 |
|
| 436 | ret = ioctl(session_fd, PPPIOCGCHAN, &chindx);
|
| 437 | if (ret < 0)
|
| 438 | return -errno;
|
| 439 |
|
| 440 | ppp_chan_fd = open("/dev/ppp", O_RDWR);
|
| 441 | if (ppp_chan_fd < 0)
|
| 442 | return -errno;
|
| 443 |
|
| 444 | ret = ioctl(ppp_chan_fd, PPPIOCATTCHAN, &chindx);
|
| 445 | if (ret < 0) {
|
| 446 | close(ppp_chan_fd);
|
| 447 | return -errno;
|
| 448 | }
|
| 449 |
|
| 450 | return ppp_chan_fd;
|
| 451 |
|
| 452 | LCP PPP frames will be available for read on `ppp_chan_fd`.
|
| 453 |
|
| 454 | - Create PPP interface::
|
| 455 |
|
| 456 | /* Input: the PPP channel `ppp_chan_fd` which was created as described
|
| 457 | * above.
|
| 458 | */
|
| 459 |
|
| 460 | int ifunit = -1;
|
| 461 | int ppp_if_fd;
|
| 462 | int ret;
|
| 463 |
|
| 464 | ppp_if_fd = open("/dev/ppp", O_RDWR);
|
| 465 | if (ppp_if_fd < 0)
|
| 466 | return -errno;
|
| 467 |
|
| 468 | ret = ioctl(ppp_if_fd, PPPIOCNEWUNIT, &ifunit);
|
| 469 | if (ret < 0) {
|
| 470 | close(ppp_if_fd);
|
| 471 | return -errno;
|
| 472 | }
|
| 473 |
|
| 474 | ret = ioctl(ppp_chan_fd, PPPIOCCONNECT, &ifunit);
|
| 475 | if (ret < 0) {
|
| 476 | close(ppp_if_fd);
|
| 477 | return -errno;
|
| 478 | }
|
| 479 |
|
| 480 | return ppp_if_fd;
|
| 481 |
|
| 482 | IPCP/IPv6CP PPP frames will be available for read on `ppp_if_fd`.
|
| 483 |
|
| 484 | The ppp<ifunit> interface can then be configured as usual with netlink's
|
| 485 | RTM_NEWLINK, RTM_NEWADDR, RTM_NEWROUTE, or ioctl's SIOCSIFMTU, SIOCSIFADDR,
|
| 486 | SIOCSIFDSTADDR, SIOCSIFNETMASK, SIOCSIFFLAGS, or with the `ip` command.
|
| 487 |
|
| 488 | - Bridging L2TP sessions which have PPP pseudowire types (this is also called
|
| 489 | L2TP tunnel switching or L2TP multihop) is supported by bridging the PPP
|
| 490 | channels of the two L2TP sessions to be bridged::
|
| 491 |
|
| 492 | /* Input: the session PPPoX data sockets `session_fd1` and `session_fd2`
|
| 493 | * which were created as described further above.
|
| 494 | */
|
| 495 |
|
| 496 | int ppp_chan_fd;
|
| 497 | int chindx1;
|
| 498 | int chindx2;
|
| 499 | int ret;
|
| 500 |
|
| 501 | ret = ioctl(session_fd1, PPPIOCGCHAN, &chindx1);
|
| 502 | if (ret < 0)
|
| 503 | return -errno;
|
| 504 |
|
| 505 | ret = ioctl(session_fd2, PPPIOCGCHAN, &chindx2);
|
| 506 | if (ret < 0)
|
| 507 | return -errno;
|
| 508 |
|
| 509 | ppp_chan_fd = open("/dev/ppp", O_RDWR);
|
| 510 | if (ppp_chan_fd < 0)
|
| 511 | return -errno;
|
| 512 |
|
| 513 | ret = ioctl(ppp_chan_fd, PPPIOCATTCHAN, &chindx1);
|
| 514 | if (ret < 0) {
|
| 515 | close(ppp_chan_fd);
|
| 516 | return -errno;
|
| 517 | }
|
| 518 |
|
| 519 | ret = ioctl(ppp_chan_fd, PPPIOCBRIDGECHAN, &chindx2);
|
| 520 | close(ppp_chan_fd);
|
| 521 | if (ret < 0)
|
| 522 | return -errno;
|
| 523 |
|
| 524 | return 0;
|
| 525 |
|
| 526 | It can be noted that when bridging PPP channels, the PPP session is not locally
|
| 527 | terminated, and no local PPP interface is created. PPP frames arriving on one
|
| 528 | channel are directly passed to the other channel, and vice versa.
|
| 529 |
|
| 530 | The PPP channel does not need to be kept open. Only the session PPPoX data
|
| 531 | sockets need to be kept open.
|
| 532 |
|
| 533 | More generally, it is also possible in the same way to e.g. bridge a PPPoL2TP
|
| 534 | PPP channel with other types of PPP channels, such as PPPoE.
|
| 535 |
|
| 536 | See more details for the PPP side in ppp_generic.rst.
|
| 537 |
|
| 538 | Old L2TPv2-only API
|
| 539 | -------------------
|
| 540 |
|
| 541 | When L2TP was first added to the Linux kernel in 2.6.23, it
|
| 542 | implemented only L2TPv2 and did not include a netlink API. Instead,
|
| 543 | tunnel and session instances in the kernel were managed directly using
|
| 544 | only PPPoL2TP sockets. The PPPoL2TP socket is used as described in
|
| 545 | section "PPPoL2TP Session Socket API" but tunnel and session instances
|
| 546 | are automatically created on a connect() of the socket instead of
|
| 547 | being created by a separate netlink request:
|
| 548 |
|
| 549 | - Tunnels are managed using a tunnel management socket which is a
|
| 550 | dedicated PPPoL2TP socket, connected to (invalid) session
|
| 551 | id 0. The L2TP tunnel instance is created when the PPPoL2TP
|
| 552 | tunnel management socket is connected and is destroyed when the
|
| 553 | socket is closed.
|
| 554 |
|
| 555 | - Session instances are created in the kernel when a PPPoL2TP
|
| 556 | socket is connected to a non-zero session id. Session parameters
|
| 557 | are set using setsockopt. The L2TP session instance is destroyed
|
| 558 | when the socket is closed.
|
| 559 |
|
| 560 | This API is still supported but its use is discouraged. Instead, new
|
| 561 | L2TPv2 applications should use netlink to first create the tunnel and
|
| 562 | session, then create a PPPoL2TP socket for the session.
|
| 563 |
|
| 564 | Unmanaged L2TPv3 tunnels
|
| 565 | ------------------------
|
| 566 |
|
| 567 | The kernel L2TP subsystem also supports static (unmanaged) L2TPv3
|
| 568 | tunnels. Unmanaged tunnels have no userspace tunnel socket, and
|
| 569 | exchange no control messages with the peer to set up the tunnel; the
|
| 570 | tunnel is configured manually at each end of the tunnel. All
|
| 571 | configuration is done using netlink. There is no need for an L2TP
|
| 572 | userspace application in this case -- the tunnel socket is created by
|
| 573 | the kernel and configured using parameters sent in the
|
| 574 | ``L2TP_CMD_TUNNEL_CREATE`` netlink request. The ``ip`` utility of
|
| 575 | ``iproute2`` has commands for managing static L2TPv3 tunnels; do ``ip
|
| 576 | l2tp help`` for more information.
|
| 577 |
|
| 578 | Debugging
|
| 579 | ---------
|
| 580 |
|
| 581 | The L2TP subsystem offers a range of debugging interfaces through the
|
| 582 | debugfs filesystem.
|
| 583 |
|
| 584 | To access these interfaces, the debugfs filesystem must first be mounted::
|
| 585 |
|
| 586 | # mount -t debugfs debugfs /debug
|
| 587 |
|
| 588 | Files under the l2tp directory can then be accessed, providing a summary
|
| 589 | of the current population of tunnel and session contexts existing in the
|
| 590 | kernel::
|
| 591 |
|
| 592 | # cat /debug/l2tp/tunnels
|
| 593 |
|
| 594 | The debugfs files should not be used by applications to obtain L2TP
|
| 595 | state information because the file format is subject to change. It is
|
| 596 | implemented to provide extra debug information to help diagnose
|
| 597 | problems. Applications should instead use the netlink API.
|
| 598 |
|
| 599 | In addition the L2TP subsystem implements tracepoints using the standard
|
| 600 | kernel event tracing API. The available L2TP events can be reviewed as
|
| 601 | follows::
|
| 602 |
|
| 603 | # find /debug/tracing/events/l2tp
|
| 604 |
|
| 605 | Finally, /proc/net/pppol2tp is also provided for backwards compatibility
|
| 606 | with the original pppol2tp code. It lists information about L2TPv2
|
| 607 | tunnels and sessions only. Its use is discouraged.
|
| 608 |
|
| 609 | Internal Implementation
|
| 610 | =======================
|
| 611 |
|
| 612 | This section is for kernel developers and maintainers.
|
| 613 |
|
| 614 | Sockets
|
| 615 | -------
|
| 616 |
|
| 617 | UDP sockets are implemented by the networking core. When an L2TP
|
| 618 | tunnel is created using a UDP socket, the socket is set up as an
|
| 619 | encapsulated UDP socket by setting encap_rcv and encap_destroy
|
| 620 | callbacks on the UDP socket. l2tp_udp_encap_recv is called when
|
| 621 | packets are received on the socket. l2tp_udp_encap_destroy is called
|
| 622 | when userspace closes the socket.
|
| 623 |
|
| 624 | L2TPIP sockets are implemented in `net/l2tp/l2tp_ip.c`_ and
|
| 625 | `net/l2tp/l2tp_ip6.c`_.
|
| 626 |
|
| 627 | Tunnels
|
| 628 | -------
|
| 629 |
|
| 630 | The kernel keeps a struct l2tp_tunnel context per L2TP tunnel. The
|
| 631 | l2tp_tunnel is always associated with a UDP or L2TP/IP socket and
|
| 632 | keeps a list of sessions in the tunnel. When a tunnel is first
|
| 633 | registered with L2TP core, the reference count on the socket is
|
| 634 | increased. This ensures that the socket cannot be removed while L2TP's
|
| 635 | data structures reference it.
|
| 636 |
|
| 637 | Tunnels are identified by a unique tunnel id. The id is 16-bit for
|
| 638 | L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit
|
| 639 | value.
|
| 640 |
|
| 641 | Tunnels are kept in a per-net list, indexed by tunnel id. The
|
| 642 | tunnel id namespace is shared by L2TPv2 and L2TPv3.
|
| 643 |
|
| 644 | Handling tunnel socket close is perhaps the most tricky part of the
|
| 645 | L2TP implementation. If userspace closes a tunnel socket, the L2TP
|
| 646 | tunnel and all of its sessions must be closed and destroyed. Since the
|
| 647 | tunnel context holds a ref on the tunnel socket, the socket's
|
| 648 | sk_destruct won't be called until the tunnel sock_put's its
|
| 649 | socket. For UDP sockets, when userspace closes the tunnel socket, the
|
| 650 | socket's encap_destroy handler is invoked, which L2TP uses to initiate
|
| 651 | its tunnel close actions. For L2TPIP sockets, the socket's close
|
| 652 | handler initiates the same tunnel close actions. All sessions are
|
| 653 | first closed. Each session drops its tunnel ref. When the tunnel ref
|
| 654 | reaches zero, the tunnel drops its socket ref.
|
| 655 |
|
| 656 | Sessions
|
| 657 | --------
|
| 658 |
|
| 659 | The kernel keeps a struct l2tp_session context for each session. Each
|
| 660 | session has private data which is used for data specific to the
|
| 661 | session type. With L2TPv2, the session always carries PPP
|
| 662 | traffic. With L2TPv3, the session can carry Ethernet frames (Ethernet
|
| 663 | pseudowire) or other data types such as PPP, ATM, HDLC or Frame
|
| 664 | Relay. Linux currently implements only Ethernet and PPP session types.
|
| 665 |
|
| 666 | Some L2TP session types also have a socket (PPP pseudowires) while
|
| 667 | others do not (Ethernet pseudowires).
|
| 668 |
|
| 669 | Like tunnels, L2TP sessions are identified by a unique
|
| 670 | session id. Just as with tunnel ids, the session id is 16-bit for
|
| 671 | L2TPv2 and 32-bit for L2TPv3. Internally, the id is stored as a 32-bit
|
| 672 | value.
|
| 673 |
|
| 674 | Sessions hold a ref on their parent tunnel to ensure that the tunnel
|
| 675 | stays extant while one or more sessions references it.
|
| 676 |
|
| 677 | Sessions are kept in a per-net list. L2TPv2 sessions and L2TPv3
|
| 678 | sessions are stored in separate lists. L2TPv2 sessions are keyed
|
| 679 | by a 32-bit key made up of the 16-bit tunnel ID and 16-bit
|
| 680 | session ID. L2TPv3 sessions are keyed by the 32-bit session ID, since
|
| 681 | L2TPv3 session ids are unique across all tunnels.
|
| 682 |
|
| 683 | Although the L2TPv3 RFC specifies that L2TPv3 session ids are not
|
| 684 | scoped by the tunnel, the Linux implementation has historically
|
| 685 | allowed this. Such session id collisions are supported using a per-net
|
| 686 | hash table keyed by sk and session ID. When looking up L2TPv3
|
| 687 | sessions, the list entry may link to multiple sessions with that
|
| 688 | session ID, in which case the session matching the given sk (tunnel)
|
| 689 | is used.
|
| 690 |
|
| 691 | PPP
|
| 692 | ---
|
| 693 |
|
| 694 | `net/l2tp/l2tp_ppp.c`_ implements the PPPoL2TP socket family. Each PPP
|
| 695 | session has a PPPoL2TP socket.
|
| 696 |
|
| 697 | The PPPoL2TP socket's sk_user_data references the l2tp_session.
|
| 698 |
|
| 699 | Userspace sends and receives PPP packets over L2TP using a PPPoL2TP
|
| 700 | socket. Only PPP control frames pass over this socket: PPP data
|
| 701 | packets are handled entirely by the kernel, passing between the L2TP
|
| 702 | session and its associated ``pppN`` netdev through the PPP channel
|
| 703 | interface of the kernel PPP subsystem.
|
| 704 |
|
| 705 | The L2TP PPP implementation handles the closing of a PPPoL2TP socket
|
| 706 | by closing its corresponding L2TP session. This is complicated because
|
| 707 | it must consider racing with netlink session create/destroy requests
|
| 708 | and pppol2tp_connect trying to reconnect with a session that is in the
|
| 709 | process of being closed. PPP sessions hold a ref on their associated
|
| 710 | socket in order that the socket remains extants while the session
|
| 711 | references it.
|
| 712 |
|
| 713 | Ethernet
|
| 714 | --------
|
| 715 |
|
| 716 | `net/l2tp/l2tp_eth.c`_ implements L2TPv3 Ethernet pseudowires. It
|
| 717 | manages a netdev for each session.
|
| 718 |
|
| 719 | L2TP Ethernet sessions are created and destroyed by netlink request,
|
| 720 | or are destroyed when the tunnel is destroyed. Unlike PPP sessions,
|
| 721 | Ethernet sessions do not have an associated socket.
|
| 722 |
|
| 723 | Miscellaneous
|
| 724 | =============
|
| 725 |
|
| 726 | RFCs
|
| 727 | ----
|
| 728 |
|
| 729 | The kernel code implements the datapath features specified in the
|
| 730 | following RFCs:
|
| 731 |
|
| 732 | ======= =============== ===================================
|
| 733 | RFC2661 L2TPv2 https://tools.ietf.org/html/rfc2661
|
| 734 | RFC3931 L2TPv3 https://tools.ietf.org/html/rfc3931
|
| 735 | RFC4719 L2TPv3 Ethernet https://tools.ietf.org/html/rfc4719
|
| 736 | ======= =============== ===================================
|
| 737 |
|
| 738 | Implementations
|
| 739 | ---------------
|
| 740 |
|
| 741 | A number of open source applications use the L2TP kernel subsystem:
|
| 742 |
|
| 743 | ============ ==============================================
|
| 744 | iproute2 https://github.com/shemminger/iproute2
|
| 745 | go-l2tp https://github.com/katalix/go-l2tp
|
| 746 | tunneldigger https://github.com/wlanslovenija/tunneldigger
|
| 747 | xl2tpd https://github.com/xelerance/xl2tpd
|
| 748 | ============ ==============================================
|
| 749 |
|
| 750 | Limitations
|
| 751 | -----------
|
| 752 |
|
| 753 | The current implementation has a number of limitations:
|
| 754 |
|
| 755 | 1) Interfacing with openvswitch is not yet implemented. It may be
|
| 756 | useful to map OVS Ethernet and VLAN ports into L2TPv3 tunnels.
|
| 757 |
|
| 758 | 2) VLAN pseudowires are implemented using an ``l2tpethN`` interface
|
| 759 | configured with a VLAN sub-interface. Since L2TPv3 VLAN
|
| 760 | pseudowires carry one and only one VLAN, it may be better to use
|
| 761 | a single netdevice rather than an ``l2tpethN`` and ``l2tpethN``:M
|
| 762 | pair per VLAN session. The netlink attribute
|
| 763 | ``L2TP_ATTR_VLAN_ID`` was added for this, but it was never
|
| 764 | implemented.
|
| 765 |
|
| 766 | Testing
|
| 767 | -------
|
| 768 |
|
| 769 | Unmanaged L2TPv3 Ethernet features are tested by the kernel's built-in
|
| 770 | selftests. See `tools/testing/selftests/net/l2tp.sh`_.
|
| 771 |
|
| 772 | Another test suite, l2tp-ktest_, covers all
|
| 773 | of the L2TP APIs and tunnel/session types. This may be integrated into
|
| 774 | the kernel's built-in L2TP selftests in the future.
|
| 775 |
|
| 776 | |
| 777 | .. _Generic Netlink: generic_netlink.html
|
| 778 | .. _libmnl: https://www.netfilter.org/projects/libmnl
|
| 779 | |
| 780 | |
| 781 | |
| 782 | |
| 783 | |
| 784 | |
| 785 | |
| 786 | |