|
@@ -1,44 +1,95 @@
|
|
|
-This brief document describes how to use the kernel's PPPoL2TP driver
|
|
|
-to provide L2TP functionality. L2TP is a protocol that tunnels one or
|
|
|
-more PPP sessions over a UDP tunnel. It is commonly used for VPNs
|
|
|
+This document describes how to use the kernel's L2TP drivers to
|
|
|
+provide L2TP functionality. L2TP is a protocol that tunnels one or
|
|
|
+more sessions over an IP tunnel. It is commonly used for VPNs
|
|
|
(L2TP/IPSec) and by ISPs to tunnel subscriber PPP sessions over an IP
|
|
|
-network infrastructure.
|
|
|
+network infrastructure. With L2TPv3, it is also useful as a Layer-2
|
|
|
+tunneling infrastructure.
|
|
|
+
|
|
|
+Features
|
|
|
+========
|
|
|
+
|
|
|
+L2TPv2 (PPP over L2TP (UDP tunnels)).
|
|
|
+L2TPv3 ethernet pseudowires.
|
|
|
+L2TPv3 PPP pseudowires.
|
|
|
+L2TPv3 IP encapsulation.
|
|
|
+Netlink sockets for L2TPv3 configuration management.
|
|
|
+
|
|
|
+History
|
|
|
+=======
|
|
|
+
|
|
|
+The original pppol2tp driver was introduced in 2.6.23 and provided
|
|
|
+L2TPv2 functionality (rfc2661). L2TPv2 is used to tunnel one or more PPP
|
|
|
+sessions over a UDP tunnel.
|
|
|
+
|
|
|
+L2TPv3 (rfc3931) changes the protocol to allow different frame types
|
|
|
+to be passed over an L2TP tunnel by moving the PPP-specific parts of
|
|
|
+the protocol out of the core L2TP packet headers. Each frame type is
|
|
|
+known as a pseudowire type. Ethernet, PPP, HDLC, Frame Relay and ATM
|
|
|
+pseudowires for L2TP are defined in separate RFC standards. Another
|
|
|
+change for L2TPv3 is that it can be carried directly over IP with no
|
|
|
+UDP header (UDP is optional). It is also possible to create static
|
|
|
+unmanaged L2TPv3 tunnels manually without a control protocol
|
|
|
+(userspace daemon) to manage them.
|
|
|
+
|
|
|
+To support L2TPv3, the original pppol2tp driver was split up to
|
|
|
+separate the L2TP and PPP functionality. Existing L2TPv2 userspace
|
|
|
+apps should be unaffected as the original pppol2tp sockets API is
|
|
|
+retained. L2TPv3, however, uses netlink to manage L2TPv3 tunnels and
|
|
|
+sessions.
|
|
|
|
|
|
Design
|
|
|
======
|
|
|
|
|
|
-The PPPoL2TP driver, drivers/net/pppol2tp.c, provides a mechanism by
|
|
|
-which PPP frames carried through an L2TP session are passed through
|
|
|
-the kernel's PPP subsystem. The standard PPP daemon, pppd, handles all
|
|
|
-PPP interaction with the peer. PPP network interfaces are created for
|
|
|
-each local PPP endpoint.
|
|
|
-
|
|
|
-The L2TP protocol http://www.faqs.org/rfcs/rfc2661.html defines L2TP
|
|
|
-control and data frames. L2TP control frames carry messages between
|
|
|
-L2TP clients/servers and are used to setup / teardown tunnels and
|
|
|
-sessions. An L2TP client or server is implemented in userspace and
|
|
|
-will use a regular UDP socket per tunnel. L2TP data frames carry PPP
|
|
|
-frames, which may be PPP control or PPP data. The kernel's PPP
|
|
|
+The L2TP protocol separates control and data frames. The L2TP kernel
|
|
|
+drivers handle only L2TP data frames; control frames are always
|
|
|
+handled by userspace. L2TP control frames carry messages between L2TP
|
|
|
+clients/servers and are used to setup / teardown tunnels and
|
|
|
+sessions. An L2TP client or server is implemented in userspace.
|
|
|
+
|
|
|
+Each L2TP tunnel is implemented using a UDP or L2TPIP socket; L2TPIP
|
|
|
+provides L2TPv3 IP encapsulation (no UDP) and is implemented using a
|
|
|
+new l2tpip socket family. The tunnel socket is typically created by
|
|
|
+userspace, though for unmanaged L2TPv3 tunnels, the socket can also be
|
|
|
+created by the kernel. Each L2TP session (pseudowire) gets a network
|
|
|
+interface instance. In the case of PPP, these interfaces are created
|
|
|
+indirectly by pppd using a pppol2tp socket. In the case of ethernet,
|
|
|
+the netdevice is created upon a netlink request to create an L2TPv3
|
|
|
+ethernet pseudowire.
|
|
|
+
|
|
|
+For PPP, the PPPoL2TP driver, net/l2tp/l2tp_ppp.c, provides a
|
|
|
+mechanism by which PPP frames carried through an L2TP session are
|
|
|
+passed through the kernel's PPP subsystem. The standard PPP daemon,
|
|
|
+pppd, handles all PPP interaction with the peer. PPP network
|
|
|
+interfaces are created for each local PPP endpoint. The kernel's PPP
|
|
|
subsystem arranges for PPP control frames to be delivered to pppd,
|
|
|
while data frames are forwarded as usual.
|
|
|
|
|
|
+For ethernet, the L2TPETH driver, net/l2tp/l2tp_eth.c, implements a
|
|
|
+netdevice driver, managing virtual ethernet devices, one per
|
|
|
+pseudowire. These interfaces can be managed using standard Linux tools
|
|
|
+such as "ip" and "ifconfig". If only IP frames are passed over the
|
|
|
+tunnel, the interface can be given an IP addresses of itself and its
|
|
|
+peer. If non-IP frames are to be passed over the tunnel, the interface
|
|
|
+can be added to a bridge using brctl. All L2TP datapath protocol
|
|
|
+functions are handled by the L2TP core driver.
|
|
|
+
|
|
|
Each tunnel and session within a tunnel is assigned a unique tunnel_id
|
|
|
and session_id. These ids are carried in the L2TP header of every
|
|
|
-control and data packet. The pppol2tp driver uses them to lookup
|
|
|
-internal tunnel and/or session contexts. Zero tunnel / session ids are
|
|
|
-treated specially - zero ids are never assigned to tunnels or sessions
|
|
|
-in the network. In the driver, the tunnel context keeps a pointer to
|
|
|
-the tunnel UDP socket. The session context keeps a pointer to the
|
|
|
-PPPoL2TP socket, as well as other data that lets the driver interface
|
|
|
-to the kernel PPP subsystem.
|
|
|
-
|
|
|
-Note that the pppol2tp kernel driver handles only L2TP data frames;
|
|
|
-L2TP control frames are simply passed up to userspace in the UDP
|
|
|
-tunnel socket. The kernel handles all datapath aspects of the
|
|
|
-protocol, including data packet resequencing (if enabled).
|
|
|
-
|
|
|
-There are a number of requirements on the userspace L2TP daemon in
|
|
|
-order to use the pppol2tp driver.
|
|
|
+control and data packet. (Actually, in L2TPv3, the tunnel_id isn't
|
|
|
+present in data frames - it is inferred from the IP connection on
|
|
|
+which the packet was received.) The L2TP driver uses the ids to lookup
|
|
|
+internal tunnel and/or session contexts to determine how to handle the
|
|
|
+packet. Zero tunnel / session ids are treated specially - zero ids are
|
|
|
+never assigned to tunnels or sessions in the network. In the driver,
|
|
|
+the tunnel context keeps a reference to the tunnel UDP or L2TPIP
|
|
|
+socket. The session context holds data that lets the driver interface
|
|
|
+to the kernel's network frame type subsystems, i.e. PPP, ethernet.
|
|
|
+
|
|
|
+Userspace Programming
|
|
|
+=====================
|
|
|
+
|
|
|
+For L2TPv2, there are a number of requirements on the userspace L2TP
|
|
|
+daemon in order to use the pppol2tp driver.
|
|
|
|
|
|
1. Use a UDP socket per tunnel.
|
|
|
|
|
@@ -86,6 +137,35 @@ In addition to the standard PPP ioctls, a PPPIOCGL2TPSTATS is provided
|
|
|
to retrieve tunnel and session statistics from the kernel using the
|
|
|
PPPoX socket of the appropriate tunnel or session.
|
|
|
|
|
|
+For L2TPv3, userspace must use the netlink API defined in
|
|
|
+include/linux/l2tp.h to manage tunnel and session contexts. The
|
|
|
+general procedure to create a new L2TP tunnel with one session is:-
|
|
|
+
|
|
|
+1. Open a GENL socket using L2TP_GENL_NAME for configuring the kernel
|
|
|
+ using netlink.
|
|
|
+
|
|
|
+2. Create a UDP or L2TPIP socket for the tunnel.
|
|
|
+
|
|
|
+3. Create a new L2TP tunnel using a L2TP_CMD_TUNNEL_CREATE
|
|
|
+ request. Set attributes according to desired tunnel parameters,
|
|
|
+ referencing the UDP or L2TPIP socket created in the previous step.
|
|
|
+
|
|
|
+4. Create a new L2TP session in the tunnel using a
|
|
|
+ L2TP_CMD_SESSION_CREATE request.
|
|
|
+
|
|
|
+The tunnel and all of its sessions are closed when the tunnel socket
|
|
|
+is closed. The netlink API may also be used to delete sessions and
|
|
|
+tunnels. Configuration and status info may be set or read using netlink.
|
|
|
+
|
|
|
+The L2TP driver also supports static (unmanaged) L2TPv3 tunnels. These
|
|
|
+are where there is no L2TP control message exchange with the peer to
|
|
|
+setup the tunnel; the tunnel is configured manually at each end of the
|
|
|
+tunnel. There is no need for an L2TP userspace application in this
|
|
|
+case -- the tunnel socket is created by the kernel and configured
|
|
|
+using parameters sent in the L2TP_CMD_TUNNEL_CREATE netlink
|
|
|
+request. The "ip" utility of iproute2 has commands for managing static
|
|
|
+L2TPv3 tunnels; do "ip l2tp help" for more information.
|
|
|
+
|
|
|
Debugging
|
|
|
=========
|
|
|
|
|
@@ -102,6 +182,69 @@ PPPOL2TP_MSG_CONTROL userspace - kernel interface
|
|
|
PPPOL2TP_MSG_SEQ sequence numbers handling
|
|
|
PPPOL2TP_MSG_DATA data packets
|
|
|
|
|
|
+If enabled, files under a l2tp debugfs directory can be used to dump
|
|
|
+kernel state about L2TP tunnels and sessions. To access it, the
|
|
|
+debugfs filesystem must first be mounted.
|
|
|
+
|
|
|
+# mount -t debugfs debugfs /debug
|
|
|
+
|
|
|
+Files under the l2tp directory can then be accessed.
|
|
|
+
|
|
|
+# cat /debug/l2tp/tunnels
|
|
|
+
|
|
|
+The debugfs files should not be used by applications to obtain L2TP
|
|
|
+state information because the file format is subject to change. It is
|
|
|
+implemented to provide extra debug information to help diagnose
|
|
|
+problems.) Users should use the netlink API.
|
|
|
+
|
|
|
+/proc/net/pppol2tp is also provided for backwards compaibility with
|
|
|
+the original pppol2tp driver. It lists information about L2TPv2
|
|
|
+tunnels and sessions only. Its use is discouraged.
|
|
|
+
|
|
|
+Unmanaged L2TPv3 Tunnels
|
|
|
+========================
|
|
|
+
|
|
|
+Some commercial L2TP products support unmanaged L2TPv3 ethernet
|
|
|
+tunnels, where there is no L2TP control protocol; tunnels are
|
|
|
+configured at each side manually. New commands are available in
|
|
|
+iproute2's ip utility to support this.
|
|
|
+
|
|
|
+To create an L2TPv3 ethernet pseudowire between local host 192.168.1.1
|
|
|
+and peer 192.168.1.2, using IP addresses 10.5.1.1 and 10.5.1.2 for the
|
|
|
+tunnel endpoints:-
|
|
|
+
|
|
|
+# modprobe l2tp_eth
|
|
|
+# modprobe l2tp_netlink
|
|
|
+
|
|
|
+# ip l2tp add tunnel tunnel_id 1 peer_tunnel_id 1 udp_sport 5000 \
|
|
|
+ udp_dport 5000 encap udp local 192.168.1.1 remote 192.168.1.2
|
|
|
+# ip l2tp add session tunnel_id 1 session_id 1 peer_session_id 1
|
|
|
+# ifconfig -a
|
|
|
+# ip addr add 10.5.1.2/32 peer 10.5.1.1/32 dev l2tpeth0
|
|
|
+# ifconfig l2tpeth0 up
|
|
|
+
|
|
|
+Choose IP addresses to be the address of a local IP interface and that
|
|
|
+of the remote system. The IP addresses of the l2tpeth0 interface can be
|
|
|
+anything suitable.
|
|
|
+
|
|
|
+Repeat the above at the peer, with ports, tunnel/session ids and IP
|
|
|
+addresses reversed. The tunnel and session IDs can be any non-zero
|
|
|
+32-bit number, but the values must be reversed at the peer.
|
|
|
+
|
|
|
+Host 1 Host2
|
|
|
+udp_sport=5000 udp_sport=5001
|
|
|
+udp_dport=5001 udp_dport=5000
|
|
|
+tunnel_id=42 tunnel_id=45
|
|
|
+peer_tunnel_id=45 peer_tunnel_id=42
|
|
|
+session_id=128 session_id=5196755
|
|
|
+peer_session_id=5196755 peer_session_id=128
|
|
|
+
|
|
|
+When done at both ends of the tunnel, it should be possible to send
|
|
|
+data over the network. e.g.
|
|
|
+
|
|
|
+# ping 10.5.1.1
|
|
|
+
|
|
|
+
|
|
|
Sample Userspace Code
|
|
|
=====================
|
|
|
|
|
@@ -158,12 +301,48 @@ Sample Userspace Code
|
|
|
}
|
|
|
return 0;
|
|
|
|
|
|
+Internal Implementation
|
|
|
+=======================
|
|
|
+
|
|
|
+The driver keeps a struct l2tp_tunnel context per L2TP tunnel and a
|
|
|
+struct l2tp_session context for each session. The l2tp_tunnel is
|
|
|
+always associated with a UDP or L2TP/IP socket and keeps a list of
|
|
|
+sessions in the tunnel. The l2tp_session context keeps kernel state
|
|
|
+about the session. It has private data which is used for data specific
|
|
|
+to the session type. With L2TPv2, the session always carried PPP
|
|
|
+traffic. With L2TPv3, the session can also carry ethernet frames
|
|
|
+(ethernet pseudowire) or other data types such as ATM, HDLC or Frame
|
|
|
+Relay.
|
|
|
+
|
|
|
+When a tunnel is first opened, the reference count on the socket is
|
|
|
+increased using sock_hold(). This ensures that the kernel socket
|
|
|
+cannot be removed while L2TP's data structures reference it.
|
|
|
+
|
|
|
+Some L2TP sessions also have a socket (PPP pseudowires) while others
|
|
|
+do not (ethernet pseudowires). We can't use the socket reference count
|
|
|
+as the reference count for session contexts. The L2TP implementation
|
|
|
+therefore has its own internal reference counts on the session
|
|
|
+contexts.
|
|
|
+
|
|
|
+To Do
|
|
|
+=====
|
|
|
+
|
|
|
+Add L2TP tunnel switching support. This would route tunneled traffic
|
|
|
+from one L2TP tunnel into another. Specified in
|
|
|
+http://tools.ietf.org/html/draft-ietf-l2tpext-tunnel-switching-08
|
|
|
+
|
|
|
+Add L2TPv3 VLAN pseudowire support.
|
|
|
+
|
|
|
+Add L2TPv3 IP pseudowire support.
|
|
|
+
|
|
|
+Add L2TPv3 ATM pseudowire support.
|
|
|
+
|
|
|
Miscellaneous
|
|
|
-============
|
|
|
+=============
|
|
|
|
|
|
-The PPPoL2TP driver was developed as part of the OpenL2TP project by
|
|
|
+The L2TP drivers were developed as part of the OpenL2TP project by
|
|
|
Katalix Systems Ltd. OpenL2TP is a full-featured L2TP client / server,
|
|
|
designed from the ground up to have the L2TP datapath in the
|
|
|
kernel. The project also implemented the pppol2tp plugin for pppd
|
|
|
which allows pppd to use the kernel driver. Details can be found at
|
|
|
-http://openl2tp.sourceforge.net.
|
|
|
+http://www.openl2tp.org.
|