prol2tp

 

NAME

prol2tp - General documentation  

SYNOPSIS

This document describes the general features of ProL2TP, a commercial implementation of L2TP for Linux.

ProL2TP is ideal for use in any of the following environments:-

as an L2TP VPN service for deployment on servers at the workplace, providing L2TP VPN access for home workers.
as an L2TPv2/L2TPv3 client/server in commercial Embedded Linux systems, such as home gateways or even big telecommunications switches. Support for vendor AVPs, interfacing with external software applications, and controlling a custom data plane is provided using a documented plugin API.
as an L2TP client for desktop users.
 

PROTOCOL OVERVIEW

L2TPv2 was designed by the IETF (Internet Engineering Task Force, the internet standards body) to tunnel one or more PPP sessions through an IP tunnel across an IP network. L2TPv3 adds the ability to carry different types of data frame over L2TP, such as ethernet frames, and means that L2TP can carry many different types of traffic over IP networks. L2TP utilizes two types of messages, control messages and data messages. Control messages are used in the establishment, maintenance and clearing of tunnels and sessions. Data messages are used to encapsulate data frames being carried over the tunnel. Control messages utilize a reliable control channel within L2TP to guarantee delivery. Data messages are not retransmitted when packet loss occurs.

When two L2TP peers have established a tunnel, sessions may be added to the tunnel. A tunnel may carry up to 65535 sessions. Control message exchanges are used to setup each L2TP session. When an L2TP session is in place, data packets may be passed over the (unreliable) data channel of the session. Thus data packets are encapsulated first by an L2TP header and then a packet transport such as UDP, Frame Relay, ATM, etc.


   +-------------------+
   | PPP Frames        |
   +-------------------+    +-----------------------+
   | L2TP Data Messages|    | L2TP Control Messages |
   +-------------------+    +-----------------------+
   | L2TP Data Channel |    | L2TP Control Channel  |
   | (unreliable)      |    | (reliable)            |
   +------------------------------------------------+
   |      Packet Transport (UDP, FR, ATM, etc.)     |
   +------------------------------------------------+

        Diagram reproduced from RFC2661

L2TPv3 changes the packet structure to allow packet types other than PPP to be carried. The layout of some fields in the L2TP packet are abstracted to allow for future packet technologies to be added to L2TP without rework of the L2TP protocol itself.


   +-------------------+    +-----------------------+
   | Tunneled Frame    |    | L2TP Control Message  |
   +-------------------+    +-----------------------+
   | L2TP Data Header  |    | L2TP Control Header   |
   +-------------------+    +-----------------------+
   | L2TP Data Channel |    | L2TP Control Channel  |
   | (unreliable)      |    | (reliable)            |
   +-------------------+----+-----------------------+
   | Packet-Switched Network (IP, FR, MPLS, etc.)   |
   +------------------------------------------------+

        Diagram reproduced from RFC3931

 

L2TPv2 Access Concentrator (LAC)

The LAC takes PPP sessions from ingress interfaces, which may be regular modems, ATM (PPPoA), Frame Relay (PPPoFR) or ethernet (PPPoE) interfaces and tunnels them through L2TP tunnels. The LAC might create a new tunnel on-demand for the PPP session or it might choose to use an existing L2TP tunnel if it already exists.

In the simplest case, the PPP client and LAC are located on the same host and only one PPP session is used per L2TP tunnel. Some L2TP implementations, most notably Microsoft's, have this limitation.  

L2TPv2 Network Server (LNS)

The LNS is typically the server side of an L2TP connection. It accepts requests from the network to create new tunnels or add new sessions to tunnels. The LNS may terminate the PPP sessions locally or it may forward them via egress PPP interfaces.  

L2TPv3 End-point (LCCE)

The L2TPv3 protocol defines tunnel endpoints as LCCEs. It is different terminology, but it basically means both LAC and LNS.  

FEATURE SUMMARY

ProL2TP is an implementation of Layer Two Tunneling Protocol, Versions 2 and 3. Key features are:-
Supports both L2TPv2 and L2TPv3. Automatic fallback to L2TPv2 if peer does not support L2TPv3.
Operation as both LAC and LNS simultanesously is supported. A single server may be a LAC for some tunnels and a LNS for others.
Incoming and outgoing tunnels and sessions are supported.
Tunnels may use either IPv4 or IPv6.
Multiple tunnels and multiple sessions in those tunnels are supported. The maximum number of tunnels and sessions is limited only by available system memory (max 65535 tunnels and 65535 sessions per tunnel for L2TPv2) or by system and user-configured limits.
All four session types are supported, i.e. LAC/LNS Incoming/Outgoing Calls.
Multiple tunnels between the same two L2TP hosts is supported.
Tunnel, session and PPP and ethernet parameters may be defined in named profiles, simplifying the management interface and allowing specific parameter values to be used for specific incoming tunnels (those created by remote request over the network).
Is able to parse and record all standard L2TPv2 and L2TPv3 AVPs defined in RFC2661 and RFC3951. It checks that all required AVPs are present in each message and generates error log messages if unexpected AVPs are seen.
Control messages are handled by a userland daemon, prol2tpd. All L2TP data packets are handled by the kernel or a custom data-plane.
Trace messages optionally logged using syslog can be enabled/disabled at system, tunnel and session levels. Thus to debug problems on a busy system, tracing can be safely enabled only for specific entities without flooding the system with messages from other uninteresting entities.
Controlled by separate command line tools and a configuration file.
Employs a plugin architecture to allow third parties to easily extend or integrate ProL2TP with other software, e.g. PPP, RADIUS, custom data-plane, vendor AVPs, B-RAS etc etc. Includes a plugin for interfacing to pppd(8) but other PPP implementations may be used if desired via a plugin.
Invokes optional, user-supplied scripts when tunnels and sessions are established and torn down. These scripts may be used to integrate with other applications in the system.
Supports automatic IP address assignment from local address pools if other address allocation mechanisms (e.g. RADIUS) are not configured.
Locally created tunnels may optionally be designated persistent, causing them to try to recreate themselves should the tunnel fail for some reason. Any locally created sessions in persistent tunnels are also automatically restored if/when the tunnel restablishes itself. This is useful if prol2tpd is used as an L2TP client.
 

PROFILES

Profiles allow a set of tunnel, session, ethernet or PPP parameters to be configured and then referred to by name. Profiles specify parameters to be used when L2TP tunnels or sessions are created by remote request over the network.

The following profile types exist:-

TUNNEL PROFILE
Provides a named set of L2TP tunnel parameters which may be used when creating tunnels locally (by specifying the tunnel profile name when the tunnel is created) or when tunnels are created by remote request.
SESSION PROFILE
Provides a named set of L2TP session parameters which may be used when creating sessions locally (by specifying the session profile name when the session is created) or when sessions are created by remote request.
ETHERNET PROFILE
For L2TPv3 ethernet and VLAN pseudowires. Provides ethernet-specific parameters which may be used when creating sessions locally (by specifying the session profile name when the session is created) or when sessions are created by remote request.
PPP PROFILE
Provides a named set of PPP parameters which are to be used when creating PPP connections in L2TP sessions.
PEER PROFILE
Identifies parameters to be used when connecting to an L2TP peer. Peers are identified by name, by IP address / netmask, or if using L2TPv3 by router_id. The peer profile specifies default tunnel, session, ethernet and PPP profile names which are to be used when communicating with the peer.

An administrator may create as many profiles as desired. The naming of profiles is scoped by profile type; it is possible to create a tunnel profile called one and a session profile called one, for example.

The profile name default is reserved; it is the name of default profiles which are used by the system when no other profile can be found.

When new L2TP tunnels, L2TP sessions, ethernet/vlan pseudowires or PPP connections are created, parameter values are derived from the named profile or from default profiles. These default profiles are automatically created by the system; their parameter values may be modified but the default profiles cannot be deleted. Default profiles thus provide a convenient way to override the default behavior of ProL2TP.

For incoming tunnel, session, ethernet and PPP setup requests, parameters are derived from tunnel, session, ethernet and PPP profiles named in the peer profile that matches the incoming peer. Thus, to configure a server to accept incoming tunnel requests from host X, using a shared password Y, the local administrator would do the following:-

create a tunnel profile and specify the tunnel password, authentication mode and any other L2TP tunnel parameters to be used for the peer.
create a peer profile, giving it the same name as the hostname of the remote peer. Specify the tunnel profile name of the tunnel profile previously created.

If multiple tunnel peers share the same password, the same tunnel profile may be used for each peer.

Note that for further flexibility, tunnel profiles allow the session profile to be named, and session profiles allow the ppp and ethernet profile to be named. Thus, when a new L2TP session is created in a tunnel, if a session profile isn't specified in the request, its session parameters are derived from the session profile called out via the tunnel profile, or via the session profile named in the peer profile if the tunnel profile did not include a session profile name. Similarly, PPP parameters are derived from the PPP profile specified in the request, or in the session profile, or in the peer profile. This feature is known as profile inheritance.  

SECURE TUNNEL ESTABLISHMENT

The L2TPv2 standard, documented in RFC2661, provides mechanisms for secure tunnel establishment.

Tunnels may optionally be protected using a shared password (secret) which must be configured at both LAC and LNS. This may be used to prevent unwanted tunnels being created; the LAC or LNS sends a challenge to the peer using the shared tunnel password and expects a valid response before allowing the new tunnel to be created.

To prevent hackers from eavesdropping on L2TP protocol packets, some protocol fields (called Attribute Value Pairs, or AVPs) in L2TP protocol messages may be hidden (encrypted). This so-called AVP hiding may be enabled when the tunnel is created. Either or both LAC and LNS may use AVP hiding in L2TP messages that it sends.

ProL2TP provides Simple and Challenge tunnel authentication modes for incoming tunnels.

SIMPLE
accepts the tunnel only if a matching peer profile can be found for the peer; a shared tunnel password is not required. Thus, by creating one or more peer profiles, an operator determines the peer host names and/or IP address ranges or L2TPv3 router_ids of permitted remote peers without needing to use passwords.
CHALLENGE
accepts the tunnel only if both SIMPLE authentication succeeds and an L2TP challenge is requested by the peer. This is the most secure mode, as it enforces the use of L2TP Challenge and Peer Profiles to identify a set of permitted remote L2TP peers.

By default, neither SIMPLE nor CHALLENGE authentication mode is enabled; L2TP requests are accepted from any remote peer.

The L2TPv3 protocol, documented in RFC3931, defines an alternative secure tunnel establishment scheme called ontrol IMessage Authentication. Unlike L2TPv2, the entire L2TPv3 message is protected by an algorithm run over the whole L2TPv3 packet, not just selected AVPs. Note that in the case of L2TPv3, Control Message Authentication must be enabled if AVP hiding is allowed.  

L2TP LINUX KERNEL DRIVER

In order to exchange data packets over an L2TP session, L2TP Linux kernel drivers must be installed. L2TPv2 drivers are available from kernel version 2.6.23 onwards. L2TPv3 drivers are available from kernel version 2.6.35 onwards. These may either be built statically into the kernel or as loadable binary modules.

ProL2TP can also be used in systems where the data path (data plane) is handled by custom hardware. A plugin API allows system integrators to implement system-specific functions when tunnels and sessions are created and deleted.  

SELINUX

If SElinux is enabled in enforcing mode, some requests made by ProL2TP might be rejected. Recent distributions include SElinux rules for ProL2TP. However, it might be necessary to add special rules in unusual setups. For example, if using non-ephemeral ports, SElinux might need to be configured for the ports being used, e.g. if using local UDP port 5000


semanage port -a -t l2tp_port_t -p udp 5000

It is recommended to run SElinux in a permissive mode after first installing ProL2TP, to capture SElinux policy warnings when using ProL2TP. Then modify SElinux settings as required.  

IPSEC

ProL2TP can be used with or without IPSec. To use IPSec, make sure that racoon is installed (from http://ipsec-tools.sourceforge.net) and start prol2tpd with -p ipsec.so to use the IPSec plugin. This plugin tracks L2TP tunnel setups and installs rules in the IPSec Security Policy Database (SPD). Since this plugin tracks ephemeral port usage, ProL2TP supports multiple L2TP/IPSec connections between the same IP peers. This allows configurations where there are multiple L2TP/IPSec clients behind a NAT gateway, connecting to a remote L2TP server.

To set up an L2TP/IPSec server with ProL2TP, set up IPSec for the desired IPSec policies. An example racoon configuration file is provided in the ProL2TP distribution to help get started. Add Security Policy Database (SPD) entries for the initial L2TP control connection (port 1701). When ProL2TP is used with its ipsec plugin, additional policies are added on demand for actual IP addresses and ephemeral UDP ports, as tunnels are created and deleted. The following setkey command adds an SPD to allow an L2TP server to serve L2TP/IPSec clients from any remote IP addresses.


spdadd 0.0.0.0/0[1701] 0.0.0.0/0 udp -P in ipsec
        esp/transport//require;

Then start prol2tpd with its ipsec plugin.


prol2tpd -p ipsec.so

 

SECURITY CONSIDERATIONS

The ProL2TP daemon, prol2tpd, runs as a system service, as root. It is configured by a config file and may be managed by several command line utilities.

ProL2TP defines two Unix system groups, prol2tp and prol2tpadmin to manage read-only and writable API requests. If users are to be allowed to invoke ProL2TP API requests, they should be added to one or both of these groups by the system administrator. The root user always has access privileges. Most Linux distributions provide the adduser utility, which may be used to grant user accounts with prol2tp access, e.g.


adduser fred prol2tpadmin

The ProL2TP config file should be writable only by the root user.  

INTEROPERABILITY

 

Microsoft Windows 2000 and Windows XP/Vista/7

By default, Microsoft L2TP uses IPSec for all L2TP tunnels. To disable IPSec on Microsoft systems, see

http://support.microsoft.com/default.aspx?scid=kb;en-us;q310109
Microsoft L2TP clients negotiate a PPP MTU of only 1400 bytes.
 

Cisco IOS 12.2

Cisco does not handle hidden AVPs in the SCCRQ message. As a workaround, ProL2TP turns off AVP hiding of all attributes in the SCCRQ, even if AVP hiding is enabled in the tunnel. Unlike Cisco, ProL2TP can handle hidden AVPs in the SCCRQ message.
Cisco advertises a Receive Window Size (RWS) of 512 by default which seems way too large -- RFC2661 says the default should be 10.
 

UNIMPLEMENTED FEATURES

The L2TP specifications include some features that are not currently implemented by ProL2TP. These are:-
PPP PROXY
PPP Proxy allows a LAC or LNS to shortcut PPP LCP negotiation by extracting PPP configuration messages and providing them to the peer with the L2TP session setup request. The peer passes this data to its PPP session and the two PPP sessions continue with PPP negotiation as if they were always directly connected. Although the ProL2TP API supports it, proxy PPP requires major work in the standard UNIX PPP server application pppd(8) and Linux kernel. However, ProL2TP already recognizes the PPP PROXY parameters of L2TP protocol messages and will report attributes that it receives from its peer using the current tunnel API. PPP PROXY is useful only in systems implementing some form of Broadband Remote Access Server (B-RAS).
L2TPv3 ATM, HDLC and Frame Relay pseudowire types
L2TPv3 data sequencing
Only data sequencing levels 0 ("No incoming data packets require sequencing") and 2 ("All incoming data packets require sequencing") are supported. Sequencing level 1 ("Only non-IP data packets require sequencing") is not supported.
Some L2TPv3 AVPs
The following L2TPv3 AVPs are ignored:

PREFERRED_LANGUAGE
 

LIMITATIONS

Although ProL2TP is a comprehensive L2TP implementation, it does have some limitations. These are:-
It creates one UDP or L2TP/IP socket per tunnel. The maximum number of tunnels is therefore limited by the maximum number of file descriptors that a single process may have open (MAX_FILES). This is typically 1024 but may be adjusted using ulimit(3).
For L2TPv2 and L2TPv3 PPP pseudowires, it creates one PPPoL2TP socket per session. If pppd(8) is used for PPP, these file descriptors are opened by the pppd process, so don't add to the file descriptors used by prol2tpd. However, if all PPP sessions are controlled by a single PPP process using a third party PPP implementation, the maximum session count is again limited by MAX_FILES.
If pppd(8) is used to provide PPP, one pppd process is spawned for each session. Although in virtual memory systems, the text segment (code) is shared between all instances of pppd, each process has its own data and heap. The heap alone can consume 1M of memory which can pose real problems to systems without swap space such as embedded systems.
Two local virtual interfaces are created for each VLAN pseudowire. This is how the standard Linux kernel implements VLANs. A master interface, usually named l2tpethN, contains a number of VLAN sub-interfaces named l2tpethN.M, where M is the VLAN ID. For VLAN pseudowires, there can be only one VLAN, so the requirement for two virtual interfaces per pseudowire instance is sub-optimal. Both interfaces must be up for data to pass. For L2TP VLAN pseudowires, the master interface must not be configured, since doing so may result in untagged ethernet frames being transmitted over the VLAN pseudowire.
 

REPORTING BUGS

Please report bugs to support@prol2tp.com.  

SEE ALSO

The following documents are also available in the ProL2TP set:-
prol2tpd(8)
describes how to invoke prol2tpd which is the L2TP daemon.
prol2tp(1)
describes the command line interface application which provides read-only visibility of current status, i.e. tunnels, sessions etc.
prol2tpd.conf(5)
describes the syntax of a local configuration file which may be used to control the L2TP daemon.
prol2tpctl(1)
describes a command line utility used to create or delete L2TP tunnels and sessions. It is intended for use in system scripts to create new tunnels and sessions upon network events, such as network interface configuration changes.


 

Index

NAME
SYNOPSIS
PROTOCOL OVERVIEW
L2TPv2 Access Concentrator (LAC)
L2TPv2 Network Server (LNS)
L2TPv3 End-point (LCCE)
FEATURE SUMMARY
PROFILES
SECURE TUNNEL ESTABLISHMENT
L2TP LINUX KERNEL DRIVER
SELINUX
IPSEC
SECURITY CONSIDERATIONS
INTEROPERABILITY
Microsoft Windows 2000 and Windows XP/Vista/7
Cisco IOS 12.2
UNIMPLEMENTED FEATURES
LIMITATIONS
REPORTING BUGS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 07:40:26 GMT, October 17, 2016