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.5.4                    January 2024                       prol2tp(7)