Documentation/networking/l2tp.txt

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