NAME

openl2tpd - L2TP protocol daemon

SYNOPSIS

openl2tpd [-f] [-R] [-D] [-d debugmask] [-L log-facility] [-p plugin-file]
[-u udp-port] [-c config-file] [-S] [-y ppp-throttle-rate]

DESCRIPTION

openl2tpd implements the control message protocols of L2TP version 2 as specified in RFC2661. It is required to setup, maintain and teardown L2TP tunnels and sessions.

For general information on the features of OpenL2TP refer to openl2tp(7).

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 and AVPDATA. Each category of message may be enabled/disabled when L2TP is first started using this option. See the DEBUGGING section below.

-D

Enable debug messages from all created tunnels and sessions. By default, new tunnels and sessions do not cause trace messages to be output unless the tunnel or session trace_flags parameter is set, perhaps via their profile. This flag sets the default profiles' trace_flags to all-enabled. It is provided as a convenient shortcut to setting the trace_flags of all default profiles to all-enabled. -f Run in the foreground. By default, openl2tpd 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, openl2tpd 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 OpenL2TP plugin interface). By default, the ppp_unix plugin is loaded, which makes openl2tpd use the standard UNIX pppd PPP daemon. The ability to load a different plugin allows openl2tpd to interface with other (possibly proprietary) PPP implementations without requiring internal changes to openl2tpd itself. Plugins are installed in /usr/lib/openl2tp/. More than one plugin may be loaded by specifying multiple -p options.

-R

Enables remote management. openl2tpd is controlled using Sun RPC requests. Sun RPC requests may be sent over a network so a control application implementing the OpenL2TP RPC API documented in openl2tp_rpc(4) may control openl2tpd remotely. In most environments, remote configuration isn't useful so is disabled by default. However, in closed cluster or chassis systems where several instances of openl2tpd may be running on different CPUs, the ability to control openl2tpd over a network using RPC is extremely useful.

-u udp-port

Tells openl2tpd 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/openl2tpd.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.

-S

Enable openl2tpd system status files. When this option is given, openl2tpd writes status information to files under /var/run/openl2tpd for each profile, peer, tunnel and session. These may be read using any standard file access mechanism to examine status of openl2tpd. This option may not be available in all environments since it is an installation option. If not available, use l2tpconfig commands instead.

-y ppp-throttle-rate

When starting or stopping ppp processes per session, this option will cause openl2tpd to limit the number of active processes to the specified value. PPP processes are deemed active when they are trying to connect to their peer or when they are being shut down. Note that this parameter does not limit the total number of pppd processes - it only limits the number of those processes that are created or deleted simultaneously by openl2tpd. Use this option when starting openl2tpd if the system becomes overloaded when lots of sessions are created or deleted simultaneously, for example when persistant tunnels recover. Most users are unlikely to need this option.

CONFIGURATION

Configuration is typically done using an application supporting OpenL2TP's RPC interface documented in openl2tp_rpc(4). One such application is l2tpconfig(1) which is bundled with OpenL2TP and which provides an intuitive command line interface.

Since OpenL2TP uses Sun RPC which is available in most commercial operating systems including Microsoft Windows, Sun Solaris and even embedded RTOS such as WindRiver's VxWorks, custom management applications may be developed to control openl2tpd.

Where RPC is not available, the system administrator may install OpenL2TP with local config file support. If this feature is enabled, the config file is read at startup and when openl2tpd receives a SIGHUP signal. Most environments will use the l2tpconfig utility's config restore command to load a previously saved configuration..

DEBUGGING

Many problems can be debugged without enabling debug logging. openl2tpd 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. OpenL2TP allows very fine levels of control over system logging, right down to individual message categories of specific tunnel or session instances. A modifiable trace_flags parameter is a trace message mask. Each tunnel and session instance has a trace_flags parameter, the initial value of which is set from a tunnel or session profile.

trace_flags is defined as a 32-bit bitmask, where bits are defined as follows:-

Type        Bitmask       Description
PROTOCOL    1             L2TP control protocol messages
FSM         2             State Machine events and state changes
API         4             Management interface
AVP         8             L2TP message attributes
AVP_HIDE    16            AVP hiding mechanism
AVP_DATA    32            AVP contents
FUNC        64            Low level operations
XPRT        128           Transport
DATA        256           Protocol data
SYSTEM      512           Internal system functions
PPP         1024          PPP operations

To debug a locally created tunnel creation, for example, create the tunnel as usual, but also specify a value for the tunnel's trace_flags parameter.

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 trace_flags parameter in the same way as described above.

The trace_flags parameter may be specified as an decimal/hexadecimal integer value or as a comma-separated list of trace options from the above list, e.g.

	trace_flags=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 openl2tpd is started with the -D command line flag, all tunnels and sessions are created with trace_flags set to trace all message categories, unless trace_flags is overridden using a specific trace_flags value as described above..

REPORTING BUGS

Please report bugs to <openl2tp-bugs@lists.sourceforge.net>.

SEE ALSO

openl2tp(7), openl2tpd(8), openl2tpd.conf(5), openl2tp_rpc(4)