prol2tp(1)                      ProL2TP Manual                      prol2tp(1)



NAME
       prol2tp - management utility for prol2tpd

SYNOPSIS
       prol2tp [-h] [-d] [command]

       prol2tp  create  tunnel  name <tunnel_name> profile <profile_name> peer
       <peer ip> [ wait ]
       prol2tp create session  name  <session_name>  in  tunnel  <id>  profile
       <profile_name> [ wait ]
       prol2tp destroy tunnel <id> [ wait ]
       prol2tp destroy session <id> in tunnel <id> [ wait ]
       prol2tp recreate tunnel <id>
       prol2tp recreate session <id> in tunnel <id>
       prol2tp show system [ stats ]
       prol2tp show license
       prol2tp show tunnels
       prol2tp show tunnel <id> [ stats ]
       prol2tp show sessions
       prol2tp show session <id> in tunnel <id> [ stats ]
       prol2tp debug system <level>
       prol2tp debug tunnel <id> <level>
       prol2tp debug session <id> in tunnel <id> <level>
       prol2tp update license <filename>
       prol2tp reload config
       prol2tp register license [ name <name> ]
       prol2tp unregister license

DESCRIPTION
       prol2tp  is  a  command-line management utility for interactive control
       and query of the prol2tpd L2TP daemon.  It communicates with the daemon
       using an IPC socket.

       The prol2tp utility offers a range of commands, documented below, which
       control its runtime behaviour.

       prol2tp is a part of  the  ProL2TP  suite  of  programs.   For  general
       information on the features of the ProL2TP suite refer to prol2tp(7).

OPTIONS
       -h, --help
              Displays brief usage information

       -d, --debug
              Enables debug logging of IPC messages.

COMMANDS
       prol2tp offers the following commands:

       * create: create tunnel and session instances

       * destroy: destroy tunnel and session instances

       * recreate: tear down and recreate tunnel and session instances

       * show: query daemon state

       * debug: control daemon log levels

       * miscellaneous: reload config, update license, register and unregister
         license

   IDENTIFYING TUNNEL AND SESSION INSTANCES
       Tunnel and session instances can be identified in a number of different
       ways, which are controlled by keywords in the prol2tp command.

       * Identification by administrative name.

         This  method  applies  to  locally-created instances, which must have
         administrative names assigned to them on creation.

         Keyword: name, e.g. tunnel name tunnel_42.

       * Identification by L2TP ID (tunnel ID, or session ID).

         This method applies to any  tunnel  or  session  instance,  including
         those  created  by network request which will not have administrative
         names assigned them.

         Keyword: id, e.g. tunnel id 279127.

   CREATE COMMANDS
       create tunnel name <tunnel_name> profile <profile_name> peer <peer  ip>
       [ wait ]
              Create a new tunnel instance.

              * tunnel_name  is  the administrative name to be assigned to the
                new instance.  Administrative names must be unique,  so  there
                must be no existing tunnel of this name.

              * profile_name  is  the name of the tunnel configuration profile
                to use for the new instance.   This  must  be  a  pre-existing
                profile in the prol2tpd configuration file.

              * peer ip is the IP address of the peer for the tunnel.

              * wait  is an optional keyword: if specified, prol2tp will block
                on the tunnel either being created in the network, or  failing
                due  to  e.g. transport  timeout  or  the peer being down.  By
                default prol2tp returns as soon as prol2tpd has  responded  to
                the  tunnel create request, while the tunnel setup is still in
                progress.

       create   session   name   <session_name>   in   tunnel   <id>   profile
       <profile_name> [ wait ]
              Create a new session instance.

              * session_name  is the administrative name to be assigned to the
                new instance.  Session administrative  names  must  be  unique
                within the parent tunnel.

              * id  identifies  the parent tunnel of the new session instance,
                using either the L2TP tunnel ID, or the administrative name.

              * profile_name refers to the session  configuration  profile  to
                use  for the new instance.  The must be a pre-existing profile
                in the prol2tpd configuration file.

              * wait is an optional keyword: if specified, prol2tp will  block
                on the session either being created in the network, or failing
                due to e.g. transport timeout or  the  peer  being  down.   By
                default  prol2tp  returns as soon as prol2tpd has responded to
                the session create request, while the session setup  is  still
                in progress.

       The create commands can be useful to create L2TP instances dynamically,
       perhaps on a system event, where having the  instance  defined  in  the
       config file prol2tpd.conf isn't convenient.

   DESTROY COMMANDS
       destroy tunnel <id> [ wait ]
              Destroy an existing tunnel instance.

              * id  identifies  the  tunnel  to destroy, using either the L2TP
                tunnel ID, or the administrative name.

              * wait is an optional keyword: if specified, prol2tp will  block
                on  the  tunnel  being torn down and removed from the network.
                By default prol2tp returns as soon as prol2tpd  has  responded
                to the tunnel destroy request.

       destroy session <session id> in tunnel <tunnel id> [ wait ]
              Destroy an existing session instance.

              * session id identifies the session to destroy, using either the
                L2TP session ID, or the administrative name.

              * tunnel id identifies the session's parent tunnel, using either
                the L2TP tunnel ID, or the administrative name.

              * wait  is an optional keyword: if specified, prol2tp will block
                on the session being torn down and removed from  the  network.
                By  default  prol2tp returns as soon as prol2tpd has responded
                to the session destroy request.

       Destroy commands can only  destroy  instances  created  by  the  create
       command.  It is not possible to destroy instances defined in the config
       file prol2tpd.conf.

   RECREATE COMMANDS
       recreate tunnel <tunnel id>
              Tear down and recreate an existing tunnel instance.

              * tunnel id identifies the tunnel to recreate, using either  the
                L2TP tunnel ID, or the administrative name.

       recreate session <session id> in tunnel <tunnel id>
              Tear down and recreate an existing session instance.

              * session  id  identifies  the session to recreate, using either
                the L2TP session ID, or the administrative name.

              * tunnel id identifies the session's parent tunnel, using either
                the L2TP tunnel ID, or the administrative name.

       The  recreate command offers a convenient way to recreate misconfigured
       tunnels and sessions.  It only  applies  to  locally-created  instances
       (i.e. those  from  the  config file or created by IPC request): this is
       because prol2tpd has no way to recreate an instance created by a peer.

   SHOW COMMANDS
       show system [ stats ]
              Display information about  the  system.   The  optional  keyword
              stats displays system statistics.

       show license
              Display   information   about   the  currently  loaded  license,
              including enabled features and tunnel/session limits.

       show tunnels
              Display a list of tunnel instances with a brief one-line summary
              of tunnel status.

       show tunnel <id> [ stats ]
              Display detailed information about a single tunnel instance.  If
              the optional keyword  stats  is  included  the  output  includes
              control and data plane statistics.

       show sessions
              Display  a  list  of  session  instances  with  a brief one-line
              summary of session status.

       show session <id> in tunnel <id> [ stats ]
              Display detailed information about a  single  session  instance.
              If  the  optional  keyword stats is included the output includes
              data plane statistics.

   DEBUG COMMANDS
       debug system <level>
              Modify log level for prol2tpd core.  This  controls  the  daemon
              logging  level,  and  will  be inherited by tunnels and sessions
              created from that point forward, so long  as  the  configuration
              file doesn't call out a log level.

              Valid  levels  are:  crit,  emerg, error, warning, notice, info,
              debug; corresponding to syslog(3) logging levels.

       debug tunnel <id> <level>
              Modify log level for a specific tunnel instance.  This  controls
              the tunnel's logging level.

              Valid  levels  are:  crit,  emerg, error, warning, notice, info,
              debug; corresponding to syslog(3) logging levels.

       debug session <id> in tunnel <id> <level>
              Modify log level for a specific session instance.  This controls
              the session's logging level.

              Valid  levels  are:  crit,  emerg, error, warning, notice, info,
              debug; corresponding to syslog(3) logging levels.

   MISCELLANEOUS COMMANDS
       update license <filename>
              Update the prol2tpd license file.  This is intended for in-field
              license  upgrades,  allowing  the  running  daemon to be updated
              without taking down the existing tunnel and  session  instances.
              Upon  successful  completion  the  license  will  be  written to
              persistent storage under the default license file path such that
              prol2tpd will load the new license when it next starts up.

       register license [ name <name> ]
              Register  a Cloud license with the ProL2TP license server, which
              is necessary prior  to  running  prol2tpd.   The  optional  name
              parameter  overrides  the  default  name  (hostname)  which  the
              license server stores  to  allow  management  of  Cloud  license
              instances.

       unregister license
              Unregister  a Cloud license by contacting the server to indicate
              that this instance is being decommissioned.

       reload config
              Reread the prol2tpd configuration file.  Equivalent  of  sending
              prol2tpd a SIGHUP signal.

AUTHORS
       Katalix Systems, Ltd.



ProL2TP 2.5.4                    January 2024                       prol2tp(1)