openl2tpd

openl2tpd is a server (daemon) that implements the L2TP control protocol. When an L2TP control message arrives, openl2tpd processes it and takes actions according to its configuration. It must be run as root and is typically started automatically when the system boots. Users control openl2tpd using l2tpconfig.

openl2tpd(8)			OpenL2TP Manual			  openl2tpd(8)



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 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 plu-
	       gin 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 .

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



OpenL2TP			13 August 2007			  openl2tpd(8)