1This brief document describes how to use the kernel's PPPoL2TP driver
   2to provide L2TP functionality. L2TP is a protocol that tunnels one or
   3more PPP sessions over a UDP tunnel. It is commonly used for VPNs
   4(L2TP/IPSec) and by ISPs to tunnel subscriber PPP sessions over an IP
   5network infrastructure.
  10The PPPoL2TP driver, drivers/net/pppol2tp.c, provides a mechanism by
  11which PPP frames carried through an L2TP session are passed through
  12the kernel's PPP subsystem. The standard PPP daemon, pppd, handles all
  13PPP interaction with the peer. PPP network interfaces are created for
  14each local PPP endpoint.
  16The L2TP protocol defines L2TP
  17control and data frames. L2TP control frames carry messages between
  18L2TP clients/servers and are used to setup / teardown tunnels and
  19sessions. An L2TP client or server is implemented in userspace and
  20will use a regular UDP socket per tunnel. L2TP data frames carry PPP
  21frames, which may be PPP control or PPP data. The kernel's PPP
  22subsystem arranges for PPP control frames to be delivered to pppd,
  23while data frames are forwarded as usual.
  25Each tunnel and session within a tunnel is assigned a unique tunnel_id
  26and session_id. These ids are carried in the L2TP header of every
  27control and data packet. The pppol2tp driver uses them to lookup
  28internal tunnel and/or session contexts. Zero tunnel / session ids are
  29treated specially - zero ids are never assigned to tunnels or sessions
  30in the network. In the driver, the tunnel context keeps a pointer to
  31the tunnel UDP socket. The session context keeps a pointer to the
  32PPPoL2TP socket, as well as other data that lets the driver interface
  33to the kernel PPP subsystem.
  35Note that the pppol2tp kernel driver handles only L2TP data frames;
  36L2TP control frames are simply passed up to userspace in the UDP
  37tunnel socket. The kernel handles all datapath aspects of the
  38protocol, including data packet resequencing (if enabled).
  40There are a number of requirements on the userspace L2TP daemon in
  41order to use the pppol2tp driver.
  431. Use a UDP socket per tunnel.
  452. Create a single PPPoL2TP socket per tunnel bound to a special null
  46   session id. This is used only for communicating with the driver but
  47   must remain open while the tunnel is active. Opening this tunnel
  48   management socket causes the driver to mark the tunnel socket as an
  49   L2TP UDP encapsulation socket and flags it for use by the
  50   referenced tunnel id. This hooks up the UDP receive path via
  51   udp_encap_rcv() in net/ipv4/udp.c. PPP data frames are never passed
  52   in this special PPPoX socket.
  543. Create a PPPoL2TP socket per L2TP session. This is typically done
  55   by starting pppd with the pppol2tp plugin and appropriate
  56   arguments. A PPPoL2TP tunnel management socket (Step 2) must be
  57   created before the first PPPoL2TP session socket is created.
  59When creating PPPoL2TP sockets, the application provides information
  60to the driver about the socket in a socket connect() call. Source and
  61destination tunnel and session ids are provided, as well as the file
  62descriptor of a UDP socket. See struct pppol2tp_addr in
  63include/linux/if_ppp.h. Note that zero tunnel / session ids are
  64treated specially. When creating the per-tunnel PPPoL2TP management
  65socket in Step 2 above, zero source and destination session ids are
  66specified, which tells the driver to prepare the supplied UDP file
  67descriptor for use as an L2TP tunnel socket.
  69Userspace may control behavior of the tunnel or session using
  70setsockopt and ioctl on the PPPoX socket. The following socket
  71options are supported:-
  73DEBUG     - bitmask of debug message categories. See below.
  74SENDSEQ   - 0 => don't send packets with sequence numbers
  75            1 => send packets with sequence numbers
  76RECVSEQ   - 0 => receive packet sequence numbers are optional
  77            1 => drop receive packets without sequence numbers
  78LNSMODE   - 0 => act as LAC.
  79            1 => act as LNS.
  80REORDERTO - reorder timeout (in millisecs). If 0, don't try to reorder.
  82Only the DEBUG option is supported by the special tunnel management
  83PPPoX socket.
  85In addition to the standard PPP ioctls, a PPPIOCGL2TPSTATS is provided
  86to retrieve tunnel and session statistics from the kernel using the
  87PPPoX socket of the appropriate tunnel or session.
  92The driver supports a flexible debug scheme where kernel trace
  93messages may be optionally enabled per tunnel and per session. Care is
  94needed when debugging a live system since the messages are not
  95rate-limited and a busy system could be swamped. Userspace uses
  96setsockopt on the PPPoX socket to set a debug mask.
  98The following debug mask bits are available:
 100PPPOL2TP_MSG_DEBUG    verbose debug (if compiled in)
 101PPPOL2TP_MSG_CONTROL  userspace - kernel interface
 102PPPOL2TP_MSG_SEQ      sequence numbers handling
 103PPPOL2TP_MSG_DATA     data packets
 105Sample Userspace Code
 1081. Create tunnel management PPPoX socket
 110        kernel_fd = socket(AF_PPPOX, SOCK_DGRAM, PX_PROTO_OL2TP);
 111        if (kernel_fd >= 0) {
 112                struct sockaddr_pppol2tp sax;
 113                struct sockaddr_in const *peer_addr;
 115                peer_addr = l2tp_tunnel_get_peer_addr(tunnel);
 116                memset(&sax, 0, sizeof(sax));
 117                sax.sa_family = AF_PPPOX;
 118                sax.sa_protocol = PX_PROTO_OL2TP;
 119                sax.pppol2tp.fd = udp_fd;       /* fd of tunnel UDP socket */
 120                sax.pppol2tp.addr.sin_addr.s_addr = peer_addr->sin_addr.s_addr;
 121                sax.pppol2tp.addr.sin_port = peer_addr->sin_port;
 122                sax.pppol2tp.addr.sin_family = AF_INET;
 123                sax.pppol2tp.s_tunnel = tunnel_id;
 124                sax.pppol2tp.s_session = 0;     /* special case: mgmt socket */
 125                sax.pppol2tp.d_tunnel = 0;
 126                sax.pppol2tp.d_session = 0;     /* special case: mgmt socket */
 128                if(connect(kernel_fd, (struct sockaddr *)&sax, sizeof(sax) ) < 0 ) {
 129                        perror("connect failed");
 130                        result = -errno;
 131                        goto err;
 132                }
 133        }
 1352. Create session PPPoX data socket
 137        struct sockaddr_pppol2tp sax;
 138        int fd;
 140        /* Note, the target socket must be bound already, else it will not be ready */
 141        sax.sa_family = AF_PPPOX;
 142        sax.sa_protocol = PX_PROTO_OL2TP;
 143        sax.pppol2tp.fd = tunnel_fd;
 144        sax.pppol2tp.addr.sin_addr.s_addr = addr->sin_addr.s_addr;
 145        sax.pppol2tp.addr.sin_port = addr->sin_port;
 146        sax.pppol2tp.addr.sin_family = AF_INET;
 147        sax.pppol2tp.s_tunnel  = tunnel_id;
 148        sax.pppol2tp.s_session = session_id;
 149        sax.pppol2tp.d_tunnel  = peer_tunnel_id;
 150        sax.pppol2tp.d_session = peer_session_id;
 152        /* session_fd is the fd of the session's PPPoL2TP socket.
 153         * tunnel_fd is the fd of the tunnel UDP socket.
 154         */
 155        fd = connect(session_fd, (struct sockaddr *)&sax, sizeof(sax));
 156        if (fd < 0 )    {
 157                return -errno;
 158        }
 159        return 0;
 164The PPPoL2TP driver was developed as part of the OpenL2TP project by
 165Katalix Systems Ltd. OpenL2TP is a full-featured L2TP client / server,
 166designed from the ground up to have the L2TP datapath in the
 167kernel. The project also implemented the pppol2tp plugin for pppd
 168which allows pppd to use the kernel driver. Details can be found at
 170 kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.