prol2tpd.conf(5) ProL2TP Manual prol2tpd.conf(5)
NAME
prol2tpd.conf - prol2tpd configuration file
SYNOPSIS
This document describes the configuration file syntax of prol2tpd.
DESCRIPTION
prol2tpd is configured using a configuration file which is parsed
during initial start up, and again on receipt of a SIGHUP signal.
The configuration file provides configuration parameters for tunnels
and sessions. It can be used to define tunnel and session instances
for prol2tpd to initiate as a client. It can also be used to define
mappings to allow prol2tpd to associate incoming network requests with
configuration when running as a server.
FILE SYNTAX
Configuration parameters are organised into named blocks which are
delimited by braces { }:
block-type "name" {
param1 value
param2 value
}
Parameters are identified within the block by a field name, and call
out one or more values. Each parameter is delimited by a newline.
Parameter values may be one of a range of types. Some parameters
accept more than one value type, or even lists of values. The basic
value types are as follows:
* boolean: either `true' or `false'
* number: an unsigned integer
* string: a free-form string
* ip: an IPv4 or IPv6 address. IP addresses may include a port as per
RFC 3986, for example 10.5.0.1:9000,
[2001:db8:1f70::999:de8:7648:6e8]:9000. IP addresses may also be
specified as a string, in which case prol2tpd will resolve them to an
IP using DNS lookup.
* mac: a MAC address written as a colon-delimited set of hex bytes,
e.g. 11:22:ef:01:a3:b9
* hex: an arbitrary hexadecimal buffer prefixed with `hex:'
The hash character # is used to comment lines in the configuration.
Anything following the # character is ignored by prol2tpd.
BLOCK TYPES AND PARAMETERS
The prol2tpd syntax supports the following block types:
* system: system-wide configuration
* peer profile: maps tunnel creation requests from peers to tunnel
configuration to use for connections when acting as a server
* tunnel profile:
* defines tunnel configuration for use with a peer profile when
acting as a server
* provides an inheritance mechanism for sharing common configuration
between tunnel instances created by prol2tpd
* session profile:
* maps session creation requests from peers to session configuration
when acting as a server
* provides an inheritance mechanism for sharing common configuration
between session instances created by prol2tpd
* pseudowire profile: defines pseudowire parameters to be used
* tunnel: defines a tunnel instance for prol2tpd to create as a client
* session: defines a session instance for prol2tpd to create as a
client
SYSTEM
system {
# Configuration parameters
}
The system block configures system-wide parameters. There is at most
one instance of this block, and naming it is therefore optional.
The system block accepts the following parameters:
log_level [error|warning|notice|info|debug]
Specifies the system-wide logging level for prol2tpd. It
controls the verbosity of prol2tpd's logging. The system
log_level parameter is inherited by all tunnel and session
instances, unless they override the setting with their own
configuration. Default value: notice.
max_tunnels
Specifies the maximum number of tunnels that prol2tpd will allow
to concurrently exist. Default value: 0 (unlimited).
max_sessions
Specifies the maximum number of sessions that prol2tpd will
allow to concurrently exist. Default value: 0 (unlimited).
hostname
Specifies the string that prol2tpd will use for the system
hostname as advertised to peers in the Host Name AVP. If unset
prol2tpd will derive a value from the running system using
gethostname(2). Individual tunnel instances may override the
system-wide hostname setting.
router_id
Specifies the 32-bit value that prol2tpd will use for the system
router ID as advertised to peers in the L2TPv3 Router ID AVP.
If unset prol2tpd will derive a value from the running system
using the first valid public IPv4 address. Systems with no IPv4
address using L2TPv3 should set this configuration parameter
explicitly.
listen Specifies one or more addresses for prol2tpd to listen on for
connection requests from peers. If a given address doesn't
specify a port, prol2tpd will listen on the default L2TP port as
defined by getservbyname(3). If no listen addresses are set,
prol2tpd does not listen for incoming tunnel setup requests so
works only as an L2TP client.
PEER PROFILE
peer profile "hostname" {
# Configuration parameters
}
The peer profile block defines tunnel configuration to use for an
incoming tunnel create request from a peer. If no peer profiles are
defined, incoming tunnel setup requests will be rejected.
The peer profile block accepts the following parameters:
peer_ipaddr
Specifies the peer IP address, which is used when mapping a
create request to tunnel configuration. If not set, the peer
profile may only be matched by the hostname or router id
parameters from the peer's tunnel setup request.
netmask
Specifies the peer IP address netmask, which is used when
mapping a create request to a tunnel configuration. The netmask
defines the mask of bits in the IP address that prol2tpd should
consider when comparing IP addresses.
router_id
Specifies the peer router ID (as per the RFC 3931 Router ID
AVP), which is used when mapping a create request to tunnel
configuration.
tunnel_profile_name
Specifies the tunnel configuration to use for tunnel create
requests matching this peer profile.
TUNNEL PROFILE
tunnel profile "name" {
# Configuration parameters
}
The tunnel profile block defines a named set of tunnel configuration
which can be referenced when creating tunnel instances, and when
handling incoming tunnel creation requests from a peer. Multiple
tunnel profiles may be used in the configuration file. Each tunnel
profile block must have a unique name.
The tunnel profile block accepts the following parameters:
local_ipaddr
Specifies the local IP address for the tunnel instance to bind
to during initialisation. By default the tunnel will bind
automatically when connecting to the peer: the local_ipaddr
setting allows this to be overridden if necessary. The IP
address may be specified as an IPv4 or IPv6 address and port; or
as a string to be resolved using DNS lookup.
proto_version [0|2|3]
Specifies the L2TP protocol version to be used for the tunnel: 2
for L2TPv2 as per RFC 2661, 3 for L2TPv3 as per RFC 3931, or 0
for L2TPv3 in fallback mode as per RFC 3931 sectino 4.7.3.
Default value: 0.
dscp Specifies the Differentiated Services field in the IPv4/IPv6
packet header of all packets associated with the tunnel. The
parameter value is an integer which is written into the DSCP+ECN
field of IPv4 headers or TCLASS field of IPv6 headers. The
integer value must be a valid for the protocol or the tunnel
will fail to establish. Default value: 0 (no DSCP set).
encap_type [udp|ip]
Specifies the tunnel transport encapsulation type for L2TPv3
tunnels as per RFC 3931 section 4.1 (UDP or IP). For L2TPv2
tunnels this parameter is ignored since L2TPv2 is UDP only.
Default value: udp.
use_tiebreaker
Enable use of a tiebreaker when setting up a tunnel as per RFC
2661 section 4.4.3 (Tie Breaker AVP), to enforce the
establishment of one tunnel between two peers. It is typically
used to resolve races where a tunnel may be initiated by both
the LAC and LNS. Default value: false.
framing_cap [sync|async|any]
Specifies the value to use in the Framing Capabilities AVP in
order to advertise the capabilities of the network beyond the
L2TP tunnel. Default value: any.
bearer_cap [digital|analog|any]
Specifies the value to use in the Bearer Capabilities AVP in
order to advertise the capabilities of the network beyond the
L2TP tunnel. Default value: any.
host_name
Specifies the value to use in the Host Name AVP when
establishing the tunnel. By default prol2tpd will use the value
from the system configuration block, or derive a value from the
running system if no host name is specified in the
configuration.
secret Shared secret for use in tunnel authentication as per RFC 2661
section 5.1.1 and RFC 3931 section 4.3; and for AVP hiding as
per RFC 2661 section 4.3 and RFC 3931 5.3. When AVP hiding is
enabled for a tunnel this parameter must be set. Default value
none (no shared secret).
auth_mode [none|challenge|authenticated]
Specifies the tunnel authentication mode. The L2TPv2 and L2TPv3
protocols specify two similar authentication mechanisms:
* challenge: enables use of Challenge and Challenge Response
AVPs as per RFC 2661 section 5.1.1
* authenticated: enables Control Message Authentication as per
RFC 3931 section 4.3 (Control Message Authentication Nonce and
Message Digest AVPs).
Default value: none (no authentication).
message_digest [none|md5|sha1]
Specifies the digest calculation algorithm to use for L2TPv3
tunnels: this controls the generation of the Message Digest AVP.
If this parameter is specified without auth_mode and secret, a
message digest is added to control messages as an additional
data integrity check. If auth_mode and secret are set, then the
message digest is used as an authentication mechanism. Default
value md5 if auth_mode and secret are set, none otherwise.
hide_avps
Enable AVP hiding as per RFC 2661 section 4.3 and RFC 3931
section 5.3. If this parameter is enabled, the tunnel must have
a shared secret set using the secret parameter. Default value:
false.
disable_hidden_avp_padding
If AVP hiding is enabled, this parameter may be used to disable
padding of the hidden values. RFC 2661 and 3931 allow for
hidden AVP values to be padded in order to obscure the length of
the original value. By default prol2tpd does so for improved
security, but not all L2TP peers support padded values. This
parameter may be used to disable padding for interoperability
with such peers. Default value: false.
pseudowire_caps
For L2TPv3, this parameter specifies the set of pseudowire types
to include in the Pseudowire Capabilities List AVP. This is
specified as a list of numbers as per RFC 3931 section 10.6.
This parameter is ignored for L2TPv2 tunnels since L2TPv2 only
supports PPP pseudowires. By default prol2tpd derives the
supported pseudowire types automatically at runtime based on the
installed plugins.
log_level [error|warning|notice|info|debug]
Specifies the log level to use for the tunnel instance. It
controls the verbosity of the tunnel's logging, overriding the
value set in the system configuration block.
use_udp_checksums
Enable UDP checksum use for data frames when UDP encapsulation
is used in a tunnel. Default value: false.
hello_timeout
Specify timeout in seconds to use for periodic keepalive (hello)
control messages as per RFC 2661 section 5.5 and RFC 3931
section 4.4. If set to 0, transmission of keepalive messages is
disabled. Default value: 60 seconds.
max_retries
Specifies the maximum number of times the tunnel transport
should retransmit an unacknowledged control packet before giving
up and flagging the transport as being down. Default value: 5.
rx_window_size
Specifies the value to offer to the peer in the Receive Window
Size AVP as per RFC 2661 section 4.4.3 and RFC 3931 section
3931. This controls how many control packets the peer may send
before it must wait for an acknowledgment. Default value: 10.
tx_window_size
Specifies the number of control packets the tunnel may send to
the peer before it must wait for an acknowledgment. The value
specified here may be overridden by the peer during tunnel
establishment. Default value: 10.
retry_timeout
Specifies the timeout in seconds to use before sending the first
retry of an unacknowledged control packet. Subsequent retries
use an exponential backoff. Default value: 1 second.
idle_timeout
Specifies the timeout in seconds for the tunnel to remain
established after its last session has been torn down. Set to 0
to allow the tunnel to persist forever with no sessions.
Default value: 0 seconds.
stopccn_retransmit_period
Specifies the timeout in seconds for the tunnel to wait for
STOPCCN retransmit during shutdown as per RFC 2661 section 5.7
and RFC 3931 section 3.3.2. If set to 0, the tunnel will
default to using a 31s timeout as per the RFC recommendation.
Default value: 0 (wait for 31s).
mtu Specifies the default MTU value to use for all sessions in the
tunnel: individual sessions may override the tunnel value. May
be specified either as a number value, or as the special string
`kernel' which is used to allow the data plane to decide on the
MTU based on packet header overhead calculation. Default value:
kernel (allow the dataplane to calculate the MTU).
session_profile_name
For incoming session creation requests from the peer, this
specifies the session profile to use for configuration. For
L2TPv3 tunnels, session profiles may also be matched by
remote_end_id. A match by remote_end_id overrides
session_profile_name. If session_profile_name is not set and a
session profile cannot be matched by remote_end_id, the tunnel
will not allow the incoming session request. For outgoing
session creation requests, this setting sets the session profile
to use for the session's parameters.
establish_timeout
Specifies the timeout in seconds that the tunnel will wait for
the peer to complete the tunnel setup message exchange. This
protects against cases where a buggy or slow peer acknowledges
control packets but does not complete the tunnel setup exchange
in a timely manner. Default value: 120 seconds.
disable_session_tiebreaker
Set to disable the L2TPv3 tie breaker algorithm as referenced in
RFC 3931 section 5.4.4 (Remote End ID). Per the RFC, if two
sessions using the same remote end ID try to establish, only one
can win, and the winner is chosen using the Session Tie Breaker
AVP. For interoperability with peers not fully supporting the
RFC, this parameter skips the detection of remote end ID clashes
during session establishment in the tunnel. Default value:
false (session remote end ID clashes are detected and prevented
as per the RFC).
avp_extensions
Specifies the AVP extensions to enable in the tunnel, as a
space-separated list of extension names (e.g. l2tp_avp_cisco.so
l2tp_avp_add_protover.so). See the EXTENSIONS section below for
more details. By default no AVP extensions are used.
SESSION PROFILE
session profile "name" {
# Configuration parameters
}
The session profile block defines a named set of session configuration
which can be referenced when creating session instances, and when
handling incoming session creation requests from a peer. Multiple
session profiles may be used in the configuration file. Each session
profile block must have a unique name.
The session profile block accepts the following parameters:
pseudowire_profile_name
Specifies the pseudowire profile to use for the session. The
pseudowire profile defines configuration for the pseudowire,
which varies by pseudowire type.
log_level [error|warning|notice|info|debug]
Specifies the log level to use for the session instance. It
controls the verbosity of the session's logging, overriding the
value set in the system configuration block.
use_sequence_numbers
Enable use of sequence numbers in data packets if the peer
supports them. Note that L2TP sequence numbers are used only to
detect and optionally reorder packets that are delivered out of
sequence. Sequence numbers do not provide a reliable delivery
mechanism. Default value: false.
reorder_timeout
Specifies the timeout in milliseconds to wait for out-of-
sequence data packets before discarding them. If set to 0, do
not reorder out-of-sequence packets and instead discard them.
This parameter is ignored if use_sequence_numbers is not set.
Default value: 0 (discard out-of-sequence packets).
priv_group_id
Specifies the value to be sent in the Private Group ID AVP, used
to separate the session into a named administrative group.
interface_name
Specifies the name to be used for the session network interface.
By default sessions are automatically assigned unique interface
names.
framing_type [sync|async|any]
Specifies the framing type use in the Framing Type AVP in order
to advertise the capabilities of the network beyond the L2TP
session. Default value: any.
bearer_type [digital|analog|any]
Specifies the bearer type use in the Bearer Type AVP in order to
advertise the capabilities of the network beyond the L2TP
session. Default value: any.
tx_connect_speed
Specifies the value to use in the TX Connect Speed AVP
indicating the speed in bits per second. Default value: 0.
rx_connect_speed
Specifies the value to use in the RX Connect Speed AVP
indicating the speed in bits per second. Default value: 0.
establish_timeout
Specifies the timeout in seconds that the session will wait for
the peer to complete the session setup message exchange. This
protects against cases where a buggy or slow peer acknowledges
control packets but does not complete the session setup exchange
in a timely manner. If set to 0 no timeout is set. Default
value: 0.
cookie_len [0|4|8]
Specifies the length of cookie to send in the L2TPv3 Assigned
Cookie AVP, which is randomly generated and may be of 4 or 8
bytes in length. If set to 0, the session cookie is disabled
and the Assigned Cookie AVP is not included in control packets.
Default value: 0 (AVP disabled).
remote_end_id
Specifies the value to send in the L2TPv3 Remote End ID AVP.
The value may be specified as a string or a hex buffer
(e.g. hex:12e6b0a1).
use_tiebreaker
Enable use of a tiebreaker when setting up an L2TPv3 session as
per RFC 3931 section 5.4.4 (L2TPv2 does not specify session
tiebreakers). Default value: true.
l2spec_type
Specifies the value to send in the L2TPv3 L2-Specific Sublayer
AVP. The value may be specified as:
* "none" (or integer value 0): there is no L2-Specific sublayer
present.
* "default" (or integer value 1): the default L2-Specific
sublayer is used.
* "donotcare": prol2tpd will set the L2-Specific sublayer to
whatever the peer sends.
Default value: donotcare (use whatever the peer specifies) for
network requests; default for local instances.
physical_channel_id
Specifies the value to send in the Physical Channel ID AVP,
which encodes a vendor-specific channel number used for a call;
intended for logging purposes only. The ID is a numeric value.
If it is set to 0 the AVP is not included in control packets.
Default value: 0 (AVP disabled).
user_data
Arbitrary string which is included in some prol2tpd session-
related IPC events, and which is passed to the prol2tpd session
scripts for integration purposes.
PSEUDOWIRE PROFILE
pseudowire profile "name" {
# Configuration parameters
}
The pseudowire profile block defines a named set of pseudowire-specific
configuration which forms part of the session configuration. The
pseudowire profile contents are defined differently depending on the
pseudowire type (PPP, Ethernet, or VLAN). The type is specified using
the pseudowire_type parameter:
pseudowire_type [ppp|eth|vlan|ip]
Specifies the pseudowire type. This parameter must be set.
The following common parameters are accepted for for all pseudowire
types:
local_ipaddr
Specifies the local IP address to assign to the pseudowire
network interface.
peer_ipaddr
Specifies the peer IP address to assign to the pseudowire
network interface.
mtu Specifies the MTU to use for the pseudowire network interface.
If unset, prol2tpd defaults to the value specified in the
session configuration.
The following parameters apply to PPP pseudowires:
user_name
Specifies the user name to use for connection authentication.
user_password
Specifies the user password to use for connection
authentication.
extra_options
Specifies an arbitrary string of options to pass to propppd when
initialising the pseudowire. These options are parsed by
propppd in the same way that command line arguments to
propppctl(1) would be.
The following parameters apply to Ethernet pseudowires:
bridge_name
Specifies the name of a bridge interface to add the network
interface to. The handling of creating the bridge interface (if
required) and adding the interface to the bridge is deferred to
the prol2tpd session scripts and isn't directly implemented by
prol2tpd itself.
mac_addr
Specifies the MAC address to use for the pseudowire network
interface.
The following parameters apply to VLAN pseudowires:
vlan_id
Specifies the VLAN ID to apply to the session as per IEEE
802.1Q.
TUNNEL
tunnel "name" {
# Configuration parameters
}
The tunnel block defines a tunnel instance for prol2tpd to create.
Tunnel instances named in the configuration file are persistent: if
they fail for any reason prol2tpd will recreate them.
The tunnel block accepts all the configuration parameters defined for
the tunnel profile block, and additionally accepts the following
parameters:
tunnel_profile_name
Specifies a tunnel profile to inherit from. The tunnel instance
may optionally override any parameter specified in the named
profile.
peer_ipaddr
Specifies the IP address of the tunnel peer.
SESSION
session "name" {
# Configuration parameters
}
The session block defines a session instance for prol2tpd to create.
It must be contained within a parent tunnel block. Session instances
named in the configuration file are persistent: if they fail prol2tpd
will recreate them when their parent tunnel is recreated.
The session block accepts all the configuration parameters defined for
the session profile block, and additionally accepts the following
parameters:
session_profile_name
Specifies a session profile to inherit from. The session
instance may optionally override any parameter specified in the
named profile.
CONFIGURATION LOOKUP
When handling incoming L2TP tunnel and session setup requests, prol2tpd
uses parameters in the L2TP requests to lookup configuration to use for
the new tunnel or session. The mechanism uses L2TP parameters
contained in received L2TP control messages to find locally configured
peer, tunnel, session and pseusowire profiles.
TUNNEL
If an L2TP SCCRQ message is received, it indicates that a peer wants to
open a tunnel with the local system. The SCCRQ is matched to a peer
profile. If a peer profile cannot be found, the SCCRQ is rejected.
Thus prol2tpd will accept tunnel setup requests only from allowed
peers.
One or more parameters of the SCCRQ are used to lookup the peer
profile:
* router_id AVP in the SCCRQ (L2TPv3 only)
* hostname AVP in the SCCRQ
* source IP address of the SCCRQ
A router_id AVP is matched by the router_id parameter of the peer
profile.
A hostname is matched by the peer profile name.
IP addresses are matched by peer_ipaddr and netmask parameters of peer
profiles. These two parameters in combination can match a single IP
address or a range of IP addresses. A peer_ipaddr 0.0.0.0 or :: will
match any IPv4 or IPv6 address respectively.
Lookups are always done in the order router_id, hostname, peer IP
address and the lookup completes on first match. For example, if an
SCCRQ has router_id=42 and hostname=`bob', a peer profile with
router_id=42 set will be matched in preference to another peer profile
named `bob'
The peer profile defines a tunnel profile and prol2tpd uses
configuration defined in that tunnel profile for the new tunnel
instance.
SESSION
Once a tunnel is established, a peer may request that a session is
estabished by sending an L2TP ICRQ message. Parameters for the session
are set in session and pseudowire profiles.
For L2TPv2 tunnels, all sessions created by an ICRQ from the peer will
use the session profile called out by the tunnel profile.
For L2TPv3 tunnels, the ICRQ contains a remote_end_id AVP which can be
used to lookup a session profile. If a session profile is defined with
a matching remote_end_id value, it is used in preference to the tunnel
profile's session_profile_name. remote_end_id values must be unique
for each session. Configuration of remote_end_id is set at each peer
and is used as an identifier for the session such that each peer
configures its side of the session pseudowire interface independently.
The session profile references a pseudowire profile to use for the
session by its pseudowire_profile_name parameter.
EXTENSIONS
The L2TP protocol RFCs set rules about what an implementation must do
if it receives an unrecognised message or AVP and ProL2TP is fully
compliant with these rules. However, some L2TP implementations have
quirks or bugs that require prol2tpd to modify its protocol message
handling to work with those implementations. This is done using a
number of AVP extensions (implemented as shared libraries) which may be
enabled per tunnel using the avp_extensions parameter in the tunnel.
ProL2TP is distributed with a number of AVP extensions:
l2tp_avp_add_circuitstatus.so
Some L2TPv3 messages must contain a CircuitStatus AVP but some
L2TP implementations don't include one. This extension tells
prol2tpd to add this AVP into the received message on behalf of
the sender such that the message passes internal message
verification checks.
l2tp_avp_add_protover.so
Insert a ProtocolVersion AVP into transmitted L2TPv3 SCCRQ
messages. Some L2TPv3 implementations require this. This
extension is only needed if a peer is not compliant with
RFC3931.
l2tp_avp_add_pwtype.so
Insert a PseudowireType AVP in transmitted L2TPv3 ICRP messages.
Some L2TPv3 implementations require this. This extension is
only needed if a peer is not compliant with RFC3931.
l2tp_avp_cisco.so
Include Cisco vendor AVPs in L2TPv3 messages and handle them in
received messages. This is required to connect with most Cisco
L2TPv3 systems since Cisco define their L2TPv3 extensions such
that connections to a peer are refused if the peer doesn't look
like a Cisco.
l2tp_avp_prefer_zlb.so
Convert outbound L2TPv3 ACK messages into ZLBs. This extension
is only needed if an L2TPv3 peer is not compliant with RFC3931
and does not support the L2TPv3 ACK message.
l2tp_avp_protover_mandatory.so
Some implementations incorrectly require that the
ProtocolVersion AVP is marked mandatory by having the M bit set.
This extension tells prol2tpd to set the M bit in this AVP when
it is included in transmitted messages.
l2tp_avp_unhide_sccrq.so
If AVP hiding is enabled, prol2tpd will hide some AVPs in its
transmitted SCCRQ messages by default. Some L2TP
implementations cannot handle this, including some Cisco. Use
this extension to force that all AVPs in SCCRQ messages are
transmitted unhidden.
l2tp_avp_no_random_vector_in_ack.so
By default prol2tpd includes the Random Vector AVP in L2TPv3
Explicit Ack messages if AVP hiding is enabled. Some L2TP
implementations do not support this. This extension removes the
Random Vector AVP from ACK messages on transmit for
interoperability with such implementations.
AUTHORS
Katalix Systems, Ltd.
ProL2TP 2.6.4 October 2024 prol2tpd.conf(5)