openl2tpd(8) OpenL2TP Manual openl2tpd(8)NAMEopenl2tpd - L2TP protocol daemon
SYNOPSISopenl2tpd [-f] [-R] [-D] [-d debugmask] [-L log-facility] [-p plugin-
file]
[-u udp-port] [-c config-file] [-S] [-y ppp-throttle-rate]
DESCRIPTIONopenl2tpd 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 catego‐
rized as SYSTEM, API, PROTOCOL, FSM (finite state machine), DA‐
TA, FUNC (functions), XPRT (transport), AVP, AVPHIDE and AVPDA‐
TA. 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 con‐
venient shortcut to setting the trace_flags of all default pro‐
files to all-enabled. -f Run in the foreground. By default,
openl2tpd forks itself and runs in the background. For debug‐
ging, 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 implementa‐
tions 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 document‐
ed 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 avail‐
able 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 giv‐
en, 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 op‐
tion will cause openl2tpd to limit the number of active pro‐
cesses 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 sys‐
tem becomes overloaded when lots of sessions are created or
deleted simultaneously, for example when persistant tunnels re‐
cover. 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 ap‐
plication 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 oper‐
ating systems including Microsoft Windows, Sun Solaris and even embed‐
ded 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 re‐
store 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 diag‐
nosis. 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, re‐
source allocation failures, sequence number errors and so on. Each tun‐
nel 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 mes‐
sages sent and received and the number of data packets sent and re‐
ceived. 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 log‐
ging, right down to individual message categories of specific tunnel or
session instances. A modifiable trace_flags parameter is a trace mes‐
sage mask. Each tunnel and session instance has a trace_flags parame‐
ter, the initial value of which is set from a tunnel or session pro‐
file.
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 in‐
stances 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 cate‐
gories, 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 ALSOopenl2tp(7), openl2tpd(8), openl2tpd.conf(5), openl2tp_rpc(4)OpenL2TP 13 August 2007 openl2tpd(8)
