L2TP.CONF(5)

NAME
l2tp.conf - L2TP configuration file

DESCRIPTION
l2tpd is a user-space L2TP daemon. L2TP is the Layer Two Tunneling Protocol described in RFC 2661. It allows you to tunnel PPP sessions over a network or transport protocol (in this case, UDP.) The file /usr/pkg/etc/l2tp.conf is the configuration file for the daemon. Each line in the file takes one of the following forms:

o # comment
    A line beginning with a pound sign is ignored.

o global
    The keyword global marks the start of the global configuration section.

o section sec_name
    The keyword section marks the start of configuration options for a particular section. The section peer is built-in and allows you to specify options relating to a particular L2TP peer. Other sections may be present, depending on which handlers have been dynamically-loaded.

o option value
    All other lines contain two space-separated words: An option name and a corresponding value. If the value contains spaces, it should be surrounded by double-quotes. Double-quotes within the value may be escaped with a backslash, as in C.

The GLOBAL Section
The global section, introduced by the global keyword, defines options applicable to the entire daemon. The available options are:

o listen-port
    The UDP port on which the daemon listens. By default, the standard UDP port 1701 is used.

o load-handler handler_name
    Causes the daemon to dynamically-load a module which extends its functionality. The available modules are sync-pppd.so, an interface to the Linux pppd daemon, and cmd.so, a simple command-processor for controlling the daemon. These handlers will be described in later sections.

The PEER Section
The peer section, introduced by the section peer line, has the following options. Note that each set of peer options must be preceded by its own section peer line.

o peer addr
    Specifies the IP address of the peer. It may be an actual IP address in dotted-quad notation, or a host name.

o secret shared_secret
    Specifies the shared secret to use for tunnel authentication with the peer. If you omit this option, tunnel authentication is not performed.

o port port
    Specifies the UDP port for contacting the peer. If the peer contacts us first, we use whichever port the peer used.

o lac-handler module_name
    Specifies the name of the module which implements LAC functionality. In most cases, this should be sync-pppd. If you omit this option, then the daemon will not act as a LAC for the peer.

o lns-handler module_name
    Specifies the name of the module which implements LNS functionality. In most cases, this should be sync-pppd. If you omit this option, then the daemon will not act as a LNS for the peer.

o hide-avps bool
    If bool is 0, we will not hide any AVP's. If it is 1, we will hide all the AVP's for which hiding is permitted. If there is no shared secret, no AVP's are hidden.

o retain-tunnel bool
    If bool is 0, then the tunnel will be torn down when the last session terminates. If it is 1, the tunnel will be maintained even if there are no sessions.

o strict-ip-check bool
    By default, the l2tp code will discard datagrams for a given tunnel if the source address does not match the specified peer's IP address. If you set strict-ip-check to 0, then the l2tp code will accept datagrams for a tunnel regardless of the source IP address.

The SYNC-PPPD Section
NOTE: The sync-pppd handler only works on Linux. You must have pppd version 2.4.1 or later, and your kernel must have these modules loaded (or compiled in): ppp_synctty, ppp_generic, slhc and n_hdlc. This section is available only if you have used load-handler sync-pppd.so in the global section. Options available are:

o lns-pppd-opts options
    Options to supply to pppd when we are acting as an LNS.

o lac-pppd-opts options
    Options to supply to pppd when we are acting as an LAC.

o set-ppp-if-name boolR
    If this is set to 1, then each PPP interface is named with the process-ID of the pppd process. For example, if pppd has process-ID 3211, then the corresponding interface is called ppp3211. If you set this to 0 (the default), then the kernel picks the interface name starting at ppp0.

o pppd-path path
    Sets the path to the pppd program. If this option is not supplied, the default path of /usr/sbin/pppd is used.

Note that the sync-pppd module does not directly support maintaining a pool of IP addresses for IP address assignment. We recommend that you assign IP addresses using a RADIUS server and the latest PPP implementation from CVS.

Even if you do not supply any options to sync-pppd, you must have a section sync-pppd line to activate the handler.

The CMD Section
This section is available only if you have used load-handler cmd.so in the global section. The only option available is:

o socket-path pathname
    Specifies the path name of the UNIX-domain socket for controlling the daemon. Defaults to /var/run/l2tpctrl.

Even if you do not supply any options to cmd, you must have a section cmd line to activate the handler.

CONTROLLING THE DAEMON
If you load the cmd.so handler, you can control the daemon with a special program called l2tp-control. Here are the available commands:

o l2tp-control "exit"
    Causes the daemon to terminate all sessions and tunnels, and exit.

o l2tp-control "start-session peer"
    Causes the daemon to start a session with the specified peer. The tunnel ID and session ID are printed if the session is successfully started.

o l2tp-control "stop-session tunnel_id session_id"
    Terminates the specified session.

o l2tp-control "dump-sessions"
    Dumps a list of sessions to standard-output.

AUTHORS
l2tpd was written by David F. Skoll <dfs@roaringpenguin.com>.