prol2tpd

 

NAME

prol2tpd - L2TP protocol daemon  

SYNOPSIS

prol2tpd [-f] [-D] [-d debugmask] [-L log-facility] [-p plugin-file]
[-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, AVPHIDE, AVPDATA 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 a per-context setting. See the DEBUGGING section below.
-D
Enable debug messages from prolt2pd. By default, debug messages are not output. Use this option to increase the verbosity of debug output.
-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. Note that when run in the foreground, any trace messages are sent to the controlling terminal rather than to syslog.
-L log-facility
By default, 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 PPP plugin (a shared library supporting the ProL2TP plugin interface). By default, the ppp_unix plugin is loaded, which makes prol2tpd use the standard UNIX pppd PPP daemon. The ability to load a different plugin allows prol2tpd to interface with other (possibly proprietary) PPP implementations without requiring internal changes to prol2tpd itself. 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.3.0, (c) Copyright 2004-2011 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).    

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.
 

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
avp_hide    avp hiding mechanism
avp_data    avp contents
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 a value for the tunnel's 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 protocol,fsm,avp

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.

If prol2tpd is started with the -d <flags> command line option, the default value used for the debug options of profiles, tunnels and sessions is that specified on the command line, unless it is overridden using a specific debug value as described above.

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 set the given debug options for the next tunnel or session instance created, until the tunnel or session is successfully established, at which point its debug settings return to the configured setting. These parameters are therefore useful to see debug about a single instance in a busy system. If the operator needs tochange 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), /usr/share/doc/prol2tp/example-scripts


 

Index

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

This document was created by man2html, using the manual pages.
Time: 14:25:48 GMT, June 03, 2013