prol2tp(7) ProL2TP Manual prol2tp(7) NAME prol2tp - ProL2TP Software Suite Overview DESCRIPTION This document describes the general features of ProL2TP, a commercial implementation of L2TP for Linux. FEATURE SUMMARY ProL2TP is an implementation of Layer Two Tunneling Protocol, Versions 2 and 3. Key features are:- * Control messages are handled by a daemon, prol2tpd. All L2TP data packets are handled by the Linux kernel or a custom data-plane. * Incoming and outgoing tunnels and sessions are supported. * Operation as both LAC (client) and LNS (server) simultaneously is supported. A single server may be a LAC for some tunnels and a LNS for others. * Supports both L2TPv2 and L2TPv3. Automatic fallback to L2TPv2 if peer does not support L2TPv3. * 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. * Multiple tunnels between the same two L2TP hosts is supported. * 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. custom data-plane, vendor AVPs, B-RAS etc etc. * 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. SECURE TUNNEL ESTABLISHMENT The L2TP protocol standards, documented in RFC2661 (L2TPv2) and RFC 3931 (L2TPv3) provide 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 (obscured). 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. L2TP LINUX KERNEL DRIVER Unless a custom dataplane is used, L2TP Linux kernel drivers must be installed in order to exchange data packets over an L2TP session. 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. Some distros package the L2TP kernel modules in optionally installed packages, e.g. linux-modules-extra (Ubuntu, Fedora), linux- image-extra (Debian). ProL2TP can also be used in systems where the data path (data plane) is handled outside the Linux kernel, e.g. Openvswitch, DPDK. A plugin API (available as an extra option) allows system integrators to implement system-specific functions when tunnels and sessions are created and deleted. If L2TP modules are installed, modern kernels will autoload the modules when first used. SELINUX If SElinux is enabled in enforcing mode, some requests made by ProL2TP might be rejected. 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, install and configure a Linux IPSec package, e.g. Strongswan. Setup IPSec policies and Security Associations such that L2TP traffic is handled by the IPSec subsystem. SYSTEMD ProL2TP is packaged to use the Linux distribution's default system init subsystem. For most Linux distros, this is systemd(1). prol2tpd is controlled as the prol2tp systemd service. Some systemd environments watch system network events and may configure dynamic network interfaces. The default prol2tp install tells systemd to not manage l2tpeth interfaces. This can be overridden by adding systemd configuration, if required. See systemd.network(5). Where systemd is not used, prol2tpd may be managed by upstart (if available) or rc init scripts. 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 which must also be run as root. The ProL2TP config file should be writable only by the root user. LIMITATIONS Although ProL2TP is a comprehensive L2TP implementation, it does have some limitations. * ProL2TP 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 may be adjusted using ulimit(3). * For PPP pseudowires, propppd creates a socket for each PPP session. The maximum number of PPP sessions may therefore also be limited by the maximum number of file descriptors that a single process may have open (MAX_FILES). This may be adjusted using ulimit(3). * If the Linux kernel dataplane is used, a virtual network device is created dynamically for each L2TP session. If there are many sessions, this may cause other subsystems which listen on network events from the kernel, e.g. udev, networkmanager, systemd-network to receive many more events than their designers expected to handle, especially if many L2TP sessions are established or torn down in quick succession. * 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. SEE ALSO The following documents are also available in the ProL2TP set:- * prol2tpd(8) describes prol2tpd, the L2TP daemon implementing the L2TP control protocol. * prol2tpd.conf(5) describes the syntax of a local configuration file which may be used to control the L2TP daemon. * prol2tp(1) describes the command line interface application which provides visibility of current status, i.e. tunnels, sessions etc. * prol2tpwatch(1) describes the command line application which watches L2TP events and outputs a line per event. This can be used to easily monitor L2TP activity or in system scripts to wait for L2TP events. * propppd(8) covers the optional PPP daemon of the ProL2TP suite. * proacd(8) covers the optional PPPoE Access Concentrator daemon of the ProL2TP suite. AUTHORS Katalix Systems Ltd. ProL2TP 2.6.0 March 2024 prol2tp(7)