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

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

   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.

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

AUTHORS
       Katalix Systems, Ltd.



ProL2TP 2.4.1                     April 2023                        prol2tp(1)