OpenL2TP Online Documentation.

openl2tpd

Section: OpenL2TP Manual (8)
Updated: 17 September 2006
Index Return to Main Contents

NAME

openl2tpd - L2TP protocol daemon

SYNOPSIS

openl2tpd [-f] [-R] [-d nnn] [-L log-facility] [-p plugin-file]
[-u udp-port] [-c config-file] [-S]

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 nnn: Set the system-wide trace message mask. Trace messages are categorized as SYSTEM, API, PROTOCOL, FSM (finite state machine), DATA, FUNC (functions), XPRT (transport), AVP, AVPHIDE and AVPDATA and each category of message may be enabled/disabled when L2TP is first started using this option. See the DEBUGGING section below.
-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 then 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. This 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.

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.

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.