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