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
prol2tp checkin 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. When
using a Cloud license, this command displays information about
the license server state.
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.
checkin license
When using a Cloud license with limit sharing enabled, request
prol2tpd checks in with the ProL2TP license server. This
command may be helpful for debugging connectivity issues between
prol2tpd and the ProL2TP license server. This command may also
trigger a recalculation of the sharing of tunnel and session
limits between the prol2tpd instances registered against the
Cloud license, which may be helpful for managing client
migration from one prol2tpd instance to another.
reload config
Reread the prol2tpd configuration file. Equivalent of sending
prol2tpd a SIGHUP signal.
AUTHORS
Katalix Systems, Ltd.
ProL2TP 2.6.4 October 2024 prol2tp(1)