prol2tpd

 

NAME

prol2tpd - L2TP protocol daemon  

SYNOPSIS

prol2tpd [-f] [-D] [-d debugmask] [-p plugin-file]
[-o log-file] [-L syslog-facility] [-n]
[-u udp-port] [-c config-file] [-n]  

DESCRIPTION

prol2tpd is an L2TP daemon supporting L2TPv2 and L2TPv3. L2TPv2 is defined in RFC2661 and is a method for carrying one or more PPP sessions over a UDP tunnel. L2TPv3 is defined in RFC3931 improves on L2TPv2 by allowing different types of traffic to be carried over an IP tunnel. prol2tpd handles only the control message exchanges which are used to setup tunnels and sessions with the peer.

For general information on the features of ProL2TP refer to prol2tp(7).

The prol2tpd daemon uses Linux netlink sockets for its configuration interface. Netlink must be enabled for prol2tpd to function.  

OPTIONS

-d debugmask
Set the system-wide debug trace message mask. The mask may be specified as a decimal or hexadecimal integer or as a comma-separated list of trace categories. Trace messages are categorized as SYSTEM, API, PROTOCOL, FSM (finite state machine), DATA, FUNC (functions), XPRT (transport), AVP, SYSTEM, PPP and KERNEL. Each category of message may be enabled/disabled when L2TP is first started using this option. The setting is used as the default debug setting unless overridden by the config file. See the DEBUGGING section below.
-D
Enable extra debug features of prol2tpd. By default, messages at info level or higher are logged, unless the log_level parameter is set to debug in the config file. Using this option changes the log level to debug and enables some extra low-level debug messages that may be useful for debugging. When this option is used, the default debug state of new tunnels and sessions is enabled, unless overridden by config settings. Thus all debug messages are output by default and some messages in the output are more verbose. Consider using this option when commissioning changes as it provides a convenient way to enable all debug without adding debug options in the config file. It is not recommended to use this setting in production environments.
-f
Run in the foreground. By default, prol2tpd forks itself and runs in the background. For debugging, it is sometimes useful to run the application in the foreground.
-o log-file
Sets the log file to use for log messages. If not specified, log messages go to syslog. This setting may be overridden by the log_file option in the config file.
-L log-facility
By default, when using syslog, prol2tpd logs messages to the LOG_DAEMON syslog facility. This option may be used to log messages to one of the localN facilities instead (local0..local7) so that the logged messages can be directed via syslog configuration to a separate file or syslog server. See syslog.conf(5) for how to configure syslog.
-p plugin-file
Loads the named L2TP plugin (a shared library supporting the ProL2TP plugin interface). Plugins are installed in /usr/lib/prol2tp/. More than one plugin may be loaded by specifying multiple -p options. The plugin APIs may also be used to implement interfaces to external applications or subsystems. The plugin API is documented separately.
-u udp-port
Tells prol2tpd to listen on the specified port rather than the default L2TP port (1701).
-c config-file
Read configuration commands from the specified file rather than the default /etc/prol2tpd.conf. This option may not be available in all environments since it is an installation option. If not available, use l2tpconfig's config restore command instead.
-n
Do nothing. This option is useful to check the config file. Exits with zero status if the config file is parsed successfully, or non-zero if an error occurs. Users may run prol2tpd -n while another prol2tpd instance is running to check a config file.
$ prol2tpd -c /tmp/prol2tpd-new.conf -n
ProL2TP v1.8.0, (c) Copyright 2004-2016 Katalix Systems Ltd.
ProL2TP licensed to Katalix Systems Ltd
Using config file: /tmp/prol2tpd-new.conf
Config file OK.
 

CONFIGURATION

ProL2TP is configured using a config file. To modify configuration, the config file is modified and the daemon is sent a HUP signal to request it to reload its config. The config file syntax is covered in prol2tpd.conf(5).

The prol2tp command line utility gives operators visibility of current operational status. See prol2tp(1).  

PLUGINS

A number of plugins are distributed with ProL2TP. Additional plugins may be added using the ProL2TP SDK, if required. The standard plugins are:-

ppp_unix
Implements the interface to the standard UNIX pppd daemon. It is loaded by default, unless another plugin is loaded which inhibits it. The ability to load a different plugin allows prol2tpd to interface with other (possibly proprietary) PPP implementations without requiring internal changes to prol2tpd itself.
proppp
Implements the interface with ProPPP and inhibits the ppp_unix plugin. This results in all PPP sessions being handled by propppd(8) instead of UNIX pppd. ProPPP must be installed to use this plugin.
ppp_null
Provides null implementations for PPP-related actions and inhibits the ppp_unix plugin. This effectively disables PPP, which might be useful in L2TPv3 ethernet setups.
cisco_avp
Implements Cisco vendor AVPs which are required for interoperability with Cisco L2TPv3 equipment. Cisco require some Cisco-specific vendor AVPs to be present in L2TPv3 control messages. This plugin inserts them and adds receive handlers to accept them.
ipsec
When using IPSec in older Linux systems, this plugin updates Linux IPSec security database using setkey(1) to add rules for the UDP ports chosen during connection setup. In modern Linux systems, this should be handled transparently by the Linux kernel.
funnelbridge
A funnel bridge is a set of interconnected Linux bridge instances for funnelling many interfaces into a single bridge. The maximum number of interfaces supported by a single bridge is 1023, so this plugin allows more than 1023 L2TPv3 ethernet sessions to be bridged over a single trunk interface. This plugin manages the interconnected internal bridges, adding and removing dynamic L2TPv3 interfaces as required. See fbrctl(1).
bwlimit
This plugin is used to apply Linux netfilter rules to limit bandwidth of sessions when the session is configured with non-zero tx_connect_speed and/or rx_connect_speed parameters. The rules are applied by session event scripts, using environment variable values set by the plugin. The environment variables are TUNNEL_INTERFACE, PEER_TUNNEL_ID, PEER_SESSION_ID, BWL_PACKET_MARK, BWL_INGRESS, BWL_EGRESS. The sample scripts at /usr/share/doc/prol2tp/example-scripts/bw-limit/ show how they can be used.
   

USER SCRIPTS

The prol2tpd daemon can run optional, user-provided scripts or applications when certain events occur. If the script exists, it is executed whenever an L2TP session is created, deleted, changes state to up, or changes state to down. These scripts are usually shell scripts, but could be executable code files instead. Prol2tpd does not wait for the scripts to finish. The scripts are executed as root (with the real and effective user-id set to 0), so that they can do things such as update routing tables or run privileged daemons. Be careful that the contents of these scripts do not compromise your system's security. ProL2TPd runs the scripts with standard input, output and error redirected to /dev/null, and with an environment that is empty except for some environment variables that give information about the session.

The script filenames are:-

/etc/prol2tp/session-created
/etc/prol2tp/session-deleted
/etc/prol2tp/session-up
/etc/prol2tp/session-down

All scripts are passed the following arguments:-

P1
Numeric tunnel id.
P2
Numeric session id.
P3
Session type. This is either ETH or PPP.

Scripts are invoked with the following environment variables:-

TUNNEL_NAME
The tunnel name, if any, provided by the administrator. Tunnels created by network request (e.g. at an L2TP server) usually do not have names.
SESSION_NAME
The session name, if any, provided by the administrator. Sessions created by network request (e.g. at an L2TP server) usually do not have names.
INTERFACE_NAME
The interface name. If the script needs to configure the interface, it should use this variable to get the interface name.
MTU
The MTU of the L2TP session. If the script needs to configure the interface, it should use this variable to derive the MTU of the interface. Note that the MTU value is the MTU of packets in the L2TP session. The actual MTU of a network interface using the session may be smaller. For example, ethernet interface MTU does not include the thernet header.
LOCAL_IP
The assigned local IP address of the interface, if any. If the script needs to configure the interface, it should use this variable to set the interface IP address.
PEER_IP
The assigned peer IP address of the interface, if any. If the script needs to configure the interface, it should use this variable to set the interface peer IP address.
NETMASK
The assigned netmask of the interface, if any. If the script needs to configure the interface, it should use this variable to set the interface netmask.
BRIDGE
The bridge name, if any. If set, this interface is to be configured in the named bridge rather than configured with IP parameters. The bridge must already exist.
SESSION_PROFILE_NAME
The profile name used to create the session, if any.
PPP_PROFILE_NAME
The PPP profile name associated with the session, if any. This is present for PPP pseudowires only.
ETH_PROFILE_NAME
The ethernet profile name associated with the session, if any. This is present for L2TPv3 ethernet pseudowires only.
REMOTE_END_ID, REMOTE_END_ID_BIN
The configured remote_end_id value, an arbitrary array of bytes which is exchanged with the peer when L2TPv3 sessions are established. If the value contains a printable string, it is returned in the REMOTE_END_ID variable, otherwise it is returned as a hex string in REMOTE_END_ID_BIN. These variables are present for L2TPv3 pseudowires only.
PEER_REMOTE_END_ID, PEER_REMOTE_END_ID_BIN
If an L2TPv3 peer sends a REMOTE_END_ID value in its session setup requests, the value is reported in these environment variables. If the value contains a printable string, it is returned in the PEER_REMOTE_END_ID variable, otherwise it is returned as a hex string in PEER_REMOTE_END_ID_BIN.
USER_DATA
The user data associated with the session. This may be set in the session's config file block or via its session profile. This allows user scripts to make use of the user data.
 

DEBUGGING

Many problems can be debugged without enabling debug logging. prol2tpd maintains numerous counters that can help with problem diagnosis. At the system level, the total number of good/bad L2TP control messages received of each message type are counted, as are the total number of illegal messages received, the number of vendor-specific AVPs received, tunnel authentication failures, session setup failures, resource allocation failures, sequence number errors and so on. Each tunnel keeps detailed status about the low-level L2TP transport such as next sequence number to be sent, sequence number expected next from peer, number of ZLB messages sent and received, number of HELLO messages sent and received and the number of data packets sent and received. Thus the first stage of problem diagnosis should always be to examine system status and statistics.

General status and statistics available will often point to where the problem lies, but it may also be necessary to obtain trace from the system. ProL2TP allows very fine levels of control over system logging, right down to individual message categories of specific tunnel or session instances. A modifiable debug parameter is a trace message mask. Each tunnel and session instance has a debug parameter, the initial value of which is set from a tunnel or session profile.

Type        Description
protocol    l2tp control protocol messages
fsm         state machine events and state changes
api         management interface
avp         l2tp message attributes
func        low level operations
xprt        transport
data        protocol data
system      internal system functions
ppp         PPP operations
kernel      messages from the kernel's l2tp subsystem

To debug a locally created tunnel creation, for example, specify the debug parameter in the tunnel parameters.

To debug incoming tunnels or sessions, identify or create a tunnel or session profile that will be used for the incoming request, then modify the tunnel or session profile's debug parameter.

The debug parameter is specified as a comma-separated list of trace options from the above list, e.g.

        debug yes

Note that changing a profile's parameter value affects only new instances created using that profile; instances already created continue to use the parameter value that existed at the time of creation.

In a busy server system, debug should be enabled with care to avoid too many messages being logged. To help server administrators diagnose tunnel or session setup problems on an otherwise fully functionaing system, the next_tunnel_debug and next_session_debug parameters are available. These can be used to enable debug for the next tunnel or session instance created. These parameters are therefore useful to see debug about a single instance in a busy system. If the operator needs to change debug settings of a specific profile or tunnel or session instance, the debug setting may be modified like any other parameter, by editting the config file. Also, where enabled, the prol2tp debug command set can be used to control debug options.  

REPORTING BUGS

Please report bugs to support@prol2tp.com.  

SEE ALSO


prol2tp(1), prol2tp(7), prol2tpd(8), prol2tpd.conf(5), prol2tpwatch(1), propppd(8), fbrctl(1), /usr/share/doc/prol2tp/example-scripts


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CONFIGURATION
PLUGINS
USER SCRIPTS
DEBUGGING
REPORTING BUGS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 07:40:26 GMT, October 17, 2016