Documentation/networking/l2tp.rst

27 An L2TP tunnel carries one or more L2TP sessions. Each tunnel is
30 to/from L2TP. Fields in the L2TP header identify the tunnel or session
40     1) Create a tunnel socket. Exchange L2TP control protocol messages
41        with the peer over that socket in order to establish a tunnel.
43     2) Create a tunnel context in the kernel, using information
47        tunnel socket in order to establish a session.
57 Tunnel Sockets
62 To create a tunnel socket for use by L2TP, the standard POSIX
65 For example, for a tunnel using IPv4 addresses and UDP encapsulation::
69 Or for a tunnel using IPv6 addresses and IP encapsulation::
78 `include/uapi/linux/l2tp.h`_. The address includes the L2TP tunnel
81 tunnel id. When the peer's tunnel id and IP address is known, a
84 If the L2TP application needs to handle L2TPv3 tunnel setup requests
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.
89 An L2TP tunnel and all of its sessions are automatically closed when
90 its tunnel socket is closed.
95 L2TP applications use netlink to manage L2TP tunnel and session
100 Create, Delete, Modify and Get for tunnel and session
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
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
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
127 CONN_ID            Y        Sets the tunnel (connection) id.
128 PEER_CONN_ID       Y        Sets the peer tunnel (connection) id.
131 FD                 N        Tunnel socket file descriptor.
157 CONN_ID            Y        Identifies the tunnel id to be destroyed.
165 CONN_ID            Y        Identifies the tunnel id to be modified.
174 CONN_ID            N        Identifies the tunnel id to be queried.
183 CONN_ID            Y        The parent tunnel id.
211 CONN_ID            Y        Identifies the parent tunnel id of the session
225 CONN_ID            Y        Identifies the parent tunnel id of the session
246 CONN_ID            N        Identifies the tunnel id to be queried.
271   - Create a tunnel::
334   - Delete a tunnel and all of its sessions (if any)::
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
364 structure that matches the tunnel socket type.
366 Userspace may control behavior of the tunnel or session using
382 to retrieve tunnel and session statistics from the kernel using the
383 PPPoX socket of the appropriate tunnel or session.
389         /* Input: the L2TP tunnel UDP socket `tunnel_fd`, which needs to be
414          * tunnel_fd is the fd of the tunnel UDP / L2TPIP socket.
489     L2TP tunnel switching or L2TP multihop) is supported by bridging the PPP
543 tunnel and session instances in the kernel were managed directly using
545 section "PPPoL2TP Session Socket API" but tunnel and session instances
549     - Tunnels are managed using a tunnel management socket which is a
551       id 0. The L2TP tunnel instance is created when the PPPoL2TP
552       tunnel management socket is connected and is destroyed when the
561 L2TPv2 applications should use netlink to first create the tunnel and
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
572 userspace application in this case -- the tunnel socket is created by
589 of the current population of tunnel and session contexts existing in the
618 tunnel is created using a UDP socket, the socket is set up as an
630 The kernel keeps a struct l2tp_tunnel context per L2TP tunnel. The
632 keeps a list of sessions in the tunnel. When a tunnel is first
637 Tunnels are identified by a unique tunnel id. The id is 16-bit for
641 Tunnels are kept in a per-net list, indexed by tunnel id. The
642 tunnel id namespace is shared by L2TPv2 and L2TPv3.
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
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.
670 session id. Just as with tunnel ids, the session id is 16-bit for
674 Sessions hold a ref on their parent tunnel to ensure that the tunnel
679 by a 32-bit key made up of the 16-bit tunnel ID and 16-bit
684 scoped by the tunnel, the Linux implementation has historically
688 session ID, in which case the session matching the given sk (tunnel)
720 or are destroyed when the tunnel is destroyed. Unlike PPP sessions,
773 of the L2TP APIs and tunnel/session types. This may be integrated into