prol2tpd.conf

 

NAME

prol2tpd.conf - ProL2TP configuration file  

SYNOPSIS

This document describes the configuration file syntax of ProL2TP.  

DESCRIPTION

A configuration file is used to setup prol2tpd. It is processed when prol2tpd starts up, and again if it receives a SIGHUP signal.

As well as being used to set configuration parameters, the config file is also used to create L2TP tunnel and session instances which prol2tpd initiates as a client. prol2tpd will manage such tunnels and establish them in the network with no further action by the operator. When used as a server, the config file defines parameters to be used when accepting L2TP connections with peers.  

FILE SYNTAX

Parameters are organised in blocks, delimited by braces { }. The block type and optional name precedes the open brace. Parameters are written inside the braces, as a parameter name and value pair.

block-type "name" {
  param1 value
  param2 "string-value"
}

 

BLOCK TYPES

The following block types exist in ProL2TP:
SYSTEM
Contains attributes that may be used to control the system behavior of ProL2TP, i.e. tunnel instance limits, UDP port number, debug logging options etc. There is always one instance of this object and it has no name.

system {
  params...
}
PEER PROFILE
Identifies parameters to be used when connecting with an L2TP peer. Peers are identified by name or by IP address / netmask. The peer profile specifies default tunnel, session, PPP and ethernet profile names which are to be used for the peer, unless overridden by other settings. Peer profiles are matched by IP address or peer identifier, which is provided in the L2TP tunnel setup request. They are the core mechanism used in servers to identify specific tunnel, session, ppp and ethernet profiles for incoming requests from clients.

peer profile "name" {
  params...
}
TUNNEL PROFILE
Provides a named set of L2TP tunnel parameters which may be used when creating tunnels locally (by specifying the tunnel profile name when the tunnel is created) or when tunnels are created by remote request.

tunnel profile "name" {
  params...
}
SESSION PROFILE
Provides a named set of L2TP session parameters which may be used when creating sessions locally (by specifying the session profile name when the session is created) or when sessions are created by remote request.

session profile "name" {
  params...
}
PPP PROFILE
Provides a named set of PPP parameters which are to be used when creating PPP sessions in L2TP tunnels.

ppp profile "name" {
  params...
}
ETHERNET PROFILE
Provides a named set of ethernet parameters which are to be used when creating L2TPv3 ethernet pseudowires.

ethernet profile "name" {
  params...
}
IP POOL
Defines a named IP address pool. The prol2tpd daemon assigns IP addresses from a named pool when configured to do so using the ip_pool_name parameter in ppp or ethernet profiles.

ip pool "name" {
  params...
}
TUNNEL
Contains parameters of an L2TP tunnel, such as tunnel secret, AVP hiding, L2TP hello timeout etc. A tunnel is identified by a unique name and may contain one or more session blocks, one per session within the tunnel. A tunnel block is used only in client configurations to automatically create one or more tunnels.

tunnel "name" {
  params...
}
SESSION
Contains parameters of an L2TP session within a tunnel, such as data link options and whether to use data sequence numbers. A session is scoped by a tunnel block and is identified by a tunnel-unique name.

tunnel "name" {
  params...
  session "name" {
    params...
  }
}

 

PARAMETERS

This section identifies the parameters available in each block.

 

SYSTEM

debug
System debug options. This controls the generation of log messages that are not associated with specific tunnel, session or PPP instances, such as management API requests or L2TP tunnel setup message received. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
next_tunnel_debug
Debug options to be used for the next tunnel instance created either by the local administrator or by network request. Overrides debug settings set at create time or by the administrator. When the tunnel is successfully established, the debug options for the tunnel are returned to their configured value. This is therefore useful to enable debug for a single tunnel instance in a busy system, to diagnose tunnel related problems. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
next_session_debug
Debug options to be used for the next session instance created either by the local administrator or by network request. Overrides debug settings set at create time or by the administrator. When the session is successfully established, the debug options for the session are returned to their configured value. This is therefore useful to enable debug for a single session instance in a busy system, to diagnose session related problems. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
log_level
Set the verbosity level of debug messages output by prol2tpd. Values match traditional Unix syslog levels, namely debug, info, notice, warning, error. Default is info.
max_tunnels
Maximum number of tunnels permitted. Default=0 (no limit).
max_sessions
Maximum number of sessions permitted. Default=0 (no limit).
drain_tunnels
Enable the draining of existing tunnels. This prevents new tunnels from being created but does not delete those already present. This can be used to perform a soft shutdown of a system.
deny_local_tunnel_creates
Deny the creation of new tunnels by local request.
deny_remote_tunnel_creates
Deny the creation of new tunnels by remote peers.
tunnel_rate_limit
Maximum number of tunnels that may be created by network request per 10 second sample period. This is not used for locally created tunnels (clients). This parameter may be useful to protect against denial of service attacks, where L2TP tunnel setup requests overload the system. Default=0 (no limit).
session_rate_limit
Maximum number of sessions that may be created by network request per 10 second sample period. This is not used for locally created sessions (clients). This parameter may be useful to protect against denial of service attacks, where L2TP session setup requests overload the system. Default=0 (no limit).
router_id
Required for L2TPv3 only. This is a 4-octet value which uniquely identifies the local system. It is usually derived from one of the system's active IP addresses, as specified in RFC2072, Section 8.1. It may be specified either as a number or an IP address. Default=0.
listen
Specifies a comma-separated list of IP addresses that prol2tpd will listen on. Default is any IP address.
max_tunnels_per_peer
Maximum number of tunnels from this L2TP node to each peer. A peer is identified by IP address, so this parameter allows the number of tunnels between the same IP nodes to be limited. Default=0 (no limit).
 

PEER PROFILE

peer_ipaddr
IP address of peer. May be specified as an IPv4 or IPv6 address.
netmask
IP netmask to be used when matching for peer_ipaddr. Not used if peer_ipaddr is not set. Default is to use the whole address when matching profiles.
tunnel_profile_name
Name of default Tunnel Profile. Default="default"
session_profile_name
Name of default Session Profile. Default="default"
ppp_profile_name
Name of default PPP Profile. Default="default"
ethernet_profile_name
Name of default Ethernet Profile. Default="default"
router_id
The router_id of an L2TPv3 peer that will match this profile. Default=0 (not set).
 

TUNNEL PROFILE

peer_ipaddr
Peer IP address. May be specified as an IPv4 or IPv6 address or as a hostname which will be resolved by prol2tpd when creating tunnels using this profile.
local_ipaddr
Source IP address. May be specified as an IPv4 or IPv6 address or as a hostname which will be resolved by prol2tpd when creating tunnels using this profile. May be used to force a tunnel to use a specific local interface. By default, the system chooses how to reach the peer by IP route table lookup.
proto_version
The protocol version of a tunnel. 2 means L2TPv2. 3 means L2TPv3. Default is 0, which means either L2TPv2 or L2TPv3 is acceptable. For clients, the value 0 causes ProL2TP to send its tunnel setup request in a form that will work with both L2TPv2 and L2TPv3 peers.
encap_type
L2TPv3 tunnel transport encapsulation type: udp or ip. Default=udp.
local_udp_port
UDP port number to use for the local side of the UDP connection. Default is to assign an ephemeral port. If using a NAT gateway which is unable to track UDP ephemeral port assignments, this parameter may be set to a fixed port (usually 1701) to have the server not use ephemeral ports.
peer_udp_port
UDP port number with which to contact peer L2TP server. Default is to assign anephemeral port.
use_tiebreaker
Enable use of a tiebreaker when setting up the tunnel. Default=ON
framing_caps
Framing capabilities: sync, async, any. These are passed to the peer when the tunnel is set up to tell the capabilities of the network beyond the L2TP tunnel.
bearer_caps
Bearer capabilities: digital, analog, any. These are passed to the peer when the tunnel is set up to tell the capabilities of the network beyond the L2TP tunnel.
host_name
Name to advertise to the peer when setting up the tunnel. This name is passed in the HOST_NAME AVP and may be used by the peer to invoke local policies. Default=local system hostname.
secret
Optional secret which is shared with tunnel peer. Must be specified when hide_avps is enabled.
auth_mode
Tunnel authentication mode:-
none - no authentication, unless secret is given
simple - check peer hostname
challenge - require tunnel secret
message_digest
Message digest algorithm. Possible values are md5, sha1, or none. Not used for L2TPv2 tunnels. If specified without auth_mode and secret, a message digest is added to all control messages as a data integrity check. If auth_mode is challenge and a secret is specified then the digest is used for L2TPv3 authentication. When used for authentication defaults to md5, otherwise defaults to none.
hide_avps
Hide AVPs. Default OFF
pseudowire_caps
Identifies the set of pseudowire types supported by the tunnel. These are specified as one or more pseudowire type numbers (defined in RFC3379). By default, prol2tpd advertises PPP and Ethernet pseudowire types. Use this option if configuring tunnels which should accept only PPP or only ethernet pseudowire types; prol2tpd will reject requests from peers to setup a pseudowire type not in this list. Not used for L2TPv2 tunnels.
pmtu_discovery
Do Path MTU Discovery. Default=OFF.
debug
Debug options. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
use_udp_checksums
Use UDP checksums in data frames. Default=ON
hello_timeout
Set timeout used for periodic L2TP Hello messages (in seconds). Hello messages are sent only if no data or control frames have been sent or received since the last Hello was sent and are therefore useful as a tunnel keepalive. Default=60.
max_retries
The maximum number of retransmits of unacknowledged control frames. Setting this too low may bring down a tunnel unecessarily if a brief network error occurs. Setting it too high delays the system responding to real network outages. Control messages are retransmitted on an exponentially increasing delay. Default=5.
rx_window_size
Receive window size. This is the maximum number of control messages that the system will queue for processing. It is the maximum number of unacknowledged messages. Must be 4 or greater.
tx_window_size
Transmit window size. This is the preferred maximum number of unacknowledged messages that the local system will send to the peer. It can be reduced if the peer's rx_window_size is smaller.
retry_timeout
Retry timeout. The delay (in seconds) before sending the first retry of unacknowledged control frames. Default=1.
idle_timeout
Idle timeout. The time (in seconds) that a tunnel will remain after its last session has been torn down. Default=0, tunnel remains forever when it has no sessions, until a local administrator or network request deletes it..
max_sessions
Maximum number of sessions allowed on tunnel. Default=0 (limited only by max_sessions limit in system parameters).
mtu
MTU for all sessions in tunnel. Default=1460.
session_profile_name
Name of session profile which will be used for default values of the tunnel's session parameters.
establish_timeout
Establish timeout. The time (in seconds) that a tunnel will wait for the peer to complete the tunnel setup message exchange. This may be useful to protect against cases where a buggy or very slow peer acknowledges control messages but does not send timely tunnel setup response messages. Default=0 (no timeout).
persist_pend_timeout
The time (in seconds) that a persisting tunnel will wait in RETRY state before trying to establish itself again. Setting a low value decreases the time taken to recover from network failures, at the expense of more frequent tunnel setup messages being sent into the network when the L2TP peer is down. Some peer implementations may get confused if this value is set too low such that the peer does not time out its state before a new tunnel setup request is sent. The value must be greater than 5. Default = 60.
always_transmit_keepalives
The L2TP protocol specification states that L2TP Hello messages should be transmitted only if no L2TP control or data frames have been received within a specified period. Thus, Hello messages are seldom transmitted. This option can be used to force Hello messages to be transmitted periodically, regardless of other activity in the tunnel. Default OFF
 

SESSION PROFILE

session_profile_name
Name of session profile
ppp_profile_name
For PPP sessions, this is the name of ppp profile to use for PPP parameters.
ethernet_profile_name
For L2TPv3 Ethernet pseudowires, this is the name of the ethernet profile to use for ethernet parameters.
debug
Debug options. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
sequencing_required
Marks the tunnel that the use of sequence numbers in the data channel is mandatory. If the peer does not request sequence numbers, the tunnel setup request will be rehected. Default=NO.
use_sequence_numbers
Enable sequence numbers in the data channel if peer supports them. Default=NO.
reorder_timeout
Timeout to wait for out-of-sequence packets before discarding.
session_type
Session type: LAC Incoming (LAIC), LAC Outgoing (LAOC), LNS Incoming (LNIC), LNS Outgoing (LNOC). Default=derived from tunnel type.
pseudowire_type
Indicates the type of data to be carried in an L2TPv3 pseudowire. Valid values are ppp or eth, corresponding to PPP and Ethernet pseudowires. Valid for L2TPv3 only. Required parameter for locally created L2TPv3 sessions. For network-created sessions, the pseudowire type is set by the remote peer requesting the session.
priv_group_id
Private group ID, used to separate this session into a named administrative group. Default=NONE.
interface_name
interface name of session interface. If this is specified in the session profile, the session profile cannot be used to define parameters for more than one session, since sessions must have unique interface names. Default pppN for PPP pseudowires, or l2tpethN for ethernet pseudowires.
user_name
PPP user name. Valid for L2TPv2 or L2TPv3 PPP pseudowires only. Default=NONE.
user_password
PPP user password. Valid for L2TPv2 or L2TPv3 PPP pseudowires only. Default=NONE.
framing_type
Framing type: sync, async or any. Default=any
bearer_type
Bearer type: digital, analog, any. Default=any
establish_timeout
Establish timeout. The time (in seconds) that a session will wait for the peer to complete the session setup message exchange. This may be useful to protect against cases where a buggy or very slow peer acknowledges control messages but does not send timely session setup response messages. Default=0 (no timeout).
persist_pend_timeout
The time (in seconds) that a session in a persisting tunnel will wait in RETRY state before trying to establish itself again. Default=60.
minimum_bps
Minimum bits/sec acceptable. Default=0
maximum_bps
Maximum bits/sec required. Default=no limit
connect_speed
Specified as speed[:txspeed], indicates connection speeds.
cookie
For L2TPv3, each session carries an optional 4 or 8 byte cookie value in the packet header. This parameter specifies the cookie value to use for the session. The value is specified as hex digits, preceded by "hex:", e.g. hex:01234567. The number of hex digits must correspond to a 4 or 8 byte value. Default: no cookie.
cookie_len
If this parameter is set to 4 or 8 and a specific cookie value is not provided using the cookie parameter, a random cookie value is generated when setting up the session. Default=0.
peer_cookie
Specifies the peer cookie value which will be used to match incoming session setup requests to this profile. This is useful in servers because it allows specific incoming sessions to be matched to a specific session profile, and therefore a specific ppp or ethernet profile. The value is specified as hex digits, preceded by "hex:", e.g. hex:01234567. The number of hex digits must correspond to a 4 or 8 byte value. Default: no peer cookie.
remote_end_id
Specifies the data to be transmitted in the Remote End Id AVP for L2TPv3 sessions. This value may be used to match incoming session setup requests to this profile. This is useful in servers because it allows specific incoming sessions to be matched to a specific session profile, and therefore a specific ppp or ethernet profile. The value is specified as hex digits, preceded by "hex:", e.g. hex:01234567. Default: empty.
l2spec_type
Specifies the L2TPv3 Layer2-Specific Sublayer Type to be used for the session. Valid for L2TPv3 pseudowires only. This defines the format of a field in the L2TPv3 header of data packets. Valid values are "none" (no L2-Specific Sublayer present) or "default" (default L2-Specific Sublayer present). If using data sequence numbers, the Default L2-Specific Sublayer must be used. Default: "default".
 

PPP PROFILE

debug
Debug options. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
asyncmap
Async character map. Valid only if PPP is async mode.
mtu
Maximum Transmit Unit (MTU) or maximum packet size transmitted.
mru
Maximum Receive Unit (MRU) or maximum packet size passed when received.
sync_mode
Allow PPP sync/async operation.
auth_peer
Require PPP authentication. Refuse connection if peer does not want to authenticate. Default=YES for network-created sessions (e.g. servers), and NO for locally created sessions (e.g. clients).
auth_pap
Allow PPP PAP authentication. Default=YES. Deprecated. Use auth_refuse_pap instead.
auth_chap
Allow PPP CHAP authentication. Default=YES. Deprecated. Use auth_refuse_chap instead.
auth_mschapv1
Allow PPP MSCHAP authentication. Default=YES. Deprecated. Use auth_refuse_mschapv1 instead.
auth_mschapv2
Allow PPP MSCHAPV2 authentication. Default=YES. Deprecated. Use auth_refuse_mschapv2 instead.
auth_eap
Allow PPP EAP authentication. Default=YES. Deprecated. Use auth_refuse_eap instead.
auth_refuse_pap
Refuse PPP PAP authentication. Default=NO
auth_refuse_chap
Refuse PPP CHAP authentication. Default=NO
auth_refuse_mschapv1
Refuse PPP MSCHAP authentication. Default=NO
auth_refuse_mschapv2
Refuse PPP MSCHAPV2 authentication. Default=NO
auth_refuse_eap
Refuse PPP EAP authentication. Default=NO
auth_require_pap
Require PPP PAP authentication. Default=NO
auth_require_chap
Require PPP CHAP authentication. Default=NO
auth_require_mschapv1
Require PPP MSCHAP authentication. Default=NO
auth_require_mschapv2
Require PPP MSCHAPV2 authentication. Default=NO
auth_require_eap
Require PPP EAP authentication. Default=YES
auth_none
Allow unauthenticated PPP users. Default=NO for network-created sessions, and YES for locally created sessions.
chap_interval
Rechallenge the peer every chap_interval seconds. Default=0 (don't rechallenge).
chap_max_challenge
Maximum number of CHAP challenges to transmit without successful acknowledgment before declaring a failure. Default=10.
chap_restart
Retransmission timeout for CHAP challenges. Default=3.
pap_max_auth_reqs
Maximum number of PAP authenticate-request transmissions. Default=10.
pap_restart_interval
Retransmission timeout for PAP requests. Default=3.
pap_timeout
Maximum time to wait for peer to authenticate itself. Default=0 (no limit).
idle_timeout
Disconnect session if idle for more than N seconds. Default=0 (no limit).
ipcp_max_cfg_reqs
Maximum number of IPCP config-requests to transmit without successful acknowledgement before declaring a failure. Default=10.
ipcp_max_cfg_naks
Maximum number of IPCP config-naks to allow before starting to send config-rejects instead. Default=10.
ipcp_max_term_reqs
Maximum number of IPCP term-requests to send. Default=3.
ipcp_retransmit_interval
IPCP retransmission timeout. Default=3.
lcp_echo_failure_count
Number of LCP echo failures to accept before assuming peer is down. Default=5.
lcp_echo_interval
Send LCP echo-request to peer every N seconds. Default=0 (don't send).
lcp_max_cfg_reqs
Maximum number of LCP config-request transmissions. Default=10.
lcp_max_cfg_naks
Maximum number of LCP config-requests to transmit without successful acknowledgement before declaring a failure. Default=10.
lcp_max_term_reqs
Maximum number of LCP term-requests to send. Default=3.
lcp_retransmit_interval
LCP retransmission timeout. Default=3.
max_connect_time
Maximum connect time (in seconds) that the PPP session may stay in use.Default=0 (no limit)
local_ipaddr
The IP address to assign to the local end of the PPP link. If not set, an address may be obtained by PPP, or from a local IP address pool.
peer_ipaddr
The IP address to assign to the remote end of the PPP link. If not set, an address may be obtained by PPP, or from a local IP address pool.
dns_addr_1
Primary DNS address to use over the PPP link.
dns_addr_2
Secondary DNS address to use over the PPP link.
wins_addr_1
Primary WINS address to use over the PPP link.
wins_addr_2
Secondary WINS address to use over the PPP link.
ip_pool_name
The name of an IP pool from which to allocate local and remote IP addresses if not otherwise assigned. This value may be passed to RADIUS if RADIUS is configured. ProL2TP does not provide IP pool functionality itself.
use_radius
Says whether PPP should use RADIUS to authenticate the user and obtain user parameters for the connection. RADIUS is the preferred method to derive values for IP addresses, DNS etc rather than using fixed values in PPP profiles.
radius_hint
An arbitrary string that is passed to PPP when RADIUS is enabled. The PPP implementation may use this string in any way. The bundled ppp_unix plugin for use with pppd applies this value to pppd's radius-config-file parameter.
default_route
Says whether the PPP interface should be configured as the host's default route. Useful for use at a LAC which expects to use the L2TP tunnel as its path to the global internet.
multilink
Enable PPP multilink. Default=off.
local_name
The name to use for the local side for authentication with the peer, unless overridden by user_name.
remote_name
The name to assume for the remote peer for authentication purposes, unless overridden by a PPP username via PPP protocol exchange..
 

ETHERNET PROFILE

debug
Debug options. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
local_ipaddr
The IP address to assign to the ethernet interface when the session comes up. May be specified as an IPv4 or IPv6 address or as a hostname which will be resolved by prol2tpd when creating tunnels using this profile.
peer_ipaddr
If the peer IP address of the session is known, it can be set here. This causes the interface to be configured with the peer's IP address and ARP is disabled. May be specified as an IPv4 or IPv6 address or as a hostname which will be resolved by prol2tpd when creating tunnels using this profile.
netmask
The netmask (specified in IPv4 or IPv6 notation) with which to configure the ethernet interface when the session comes up.
bridge_name
Instead of assigning IP addresses to the ethernet interface, it can be added to a named bridge instance if this parameter is set. Use this to bridge ethernet frames over L2TP. The bridge must already exist.
vlan_id
Not yet implemented.
mtu
The MTU of the ethernet interface. By default, the MTU is derived from the MTU of the L2TP session, which is itself derived from the tunnel.
 

IP POOL

debug
Debug options. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
ip_range
A range of IP addresses assigned to the pool. The range is defined as the first and last IP address (inclusive). Multiple first/last address pairs may be specified.
 

TUNNEL

peer_ipaddr
Peer IP address. May be specified as an IPv4 or IPv6 address or as a hostname which will be resolved by prol2tpd when creating the tunnel.
config_id
Optional configuration id, used to uniquify a tunnel when there is more the one tunnel between the same two IP addresses
tunnel_id
Optional tunnel id of new tunnel. Usually auto-generated. Use is discouraged.
tunnel_profile_name
Name of tunnel profile which will be used for default values of this tunnel's parameters.
local_ipaddr
Source IP address. May be specified as an IPv4 or IPv6 address or as a hostname which will be resolved by prol2tpd when creating the tunnel.
proto_version
The protocol version of a tunnel. 2 means L2TPv2. 3 means L2TPv3. Default is 0, which means either L2TPv2 or L2TPv3 is acceptable. For clients, the value 0 causes ProL2TP to send its tunnel setup request in a form that will work with both L2TPv2 and L2TPv3 peers. For servers, the value 0 causes ProL2TP to respond with L2TPv2 or L2TPv3, depending on the received request.
local_udp_port
UDP port number to use for the local side of the UDP connection. Default is to assign an ephemeral port. If using a NAT gateway which is unable to track UDP ephemeral port assignments, this parameter may be set to a fixed port (usually 1701) to have the server not use ephemeral ports.
peer_udp_port
UDP port number with which to contact peer L2TP server. Default=1701
mode
Indicates whether the local tunnel is a LAC or LNS.
use_tiebreaker
Enable use of a tiebreaker when setting up the tunnel. Default=ON
allow_ppp_proxy
Allow PPP proxy
framing_caps
Framing capabilities: sync, async, any. These are passed to the peer when the tunnel is set up to tell the capabilities of the network beyond the L2TP tunnel.
bearer_caps
Bearer capabilities: digital, analog, any. These are passed to the peer when the tunnel is set up to tell the capabilities of the network beyond the L2TP tunnel.
host_name
Name to advertise to peer when setting up the tunnel. This name is passed in the HOST_NAME AVP and may be used by the peer to invoke local policies. Default=local system hostname.
secret
Optional secret which is shared with tunnel peer. Must be specified when hide_avps is enabled.
auth_mode
Tunnel authentication mode:-
none - no authentication, unless secret is given
simple - check peer hostname
challenge - require tunnel secret
message_digest
Message digest algorithm. Possible values are md5, sha1, or none. Not used for L2TPv2 tunnels. If specified without auth_mode and secret, a message digest is added to all control messages as a data integrity check. If auth_mode is challenge and a secret is specified then the digest is used for L2TPv3 authentication. When used for authentication defaults to md5, otherwise defaults to NONE.
hide_avps
Hide AVPs. Default OFF
pseudowire_caps
Identifies the set of pseudowire types supported by the tunnel. These are specified as one or more pseudowire type numbers (defined in RFC3379). By default, prol2tpd advertises PPP and Ethernet pseudowire types. Not used for L2TPv2 tunnels.
pmtu_discovery
Do Path MTU Discovery. Default=OFF.
debug
Debug options. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
max_retries
The maximum number of retransmits of unacknowledged control frames. Setting this too low may bring down a tunnel unecessarily if a brief network error occurs. Setting it too high delays the system responding to real network outages. Control messages are retransmitted on an exponentially increasing delay. Default=5.
rx_window_size
Receive window size. This is the maximum number of control messages that the system will queue for processing. It is the maximum number of unacknowledged messages. Must be 4 or greater.
tx_window_size
Transmit window size. This is the preferred maximum number of unacknowledged messages that the local system will send to the peer. It can be reduced if the peer's
mtu
MTU for all sessions in tunnel. Default=1460.
peer_profile_name
Name of peer profile which will be used for default values of the tunnel's parameters.
session_profile_name
Name of session profile which will be used for default values of the tunnel's session parameters. debug Debug options. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
use_udp_checksums
Use UDP checksums in data frames. Default=ON
persist
Marks the tunnel as persistent. Persistent tunnels attempt to restore themselves if the tunnel fails for some reason. Any locally created sessions in persistent tunnels are also restored if/when the tunnel reestablishes. The period at which a down persistent tunnel will attempt to reestablish is set by the persist_pend_timeout in the tunnel settings.
persist_pend_timeout
The time (in seconds) that a persisting tunnel will wait in RETRY state before trying to establish itself again. Setting a low value decreases the time taken to recover from network failures, at the expense of more frequent tunnel setup messages being sent into the network when the L2TP peer is down. Some peer implementations may get confused if this value is set too low such that the peer does not time out its state before a new tunnel setup request is sent. The value must be greater than 5. Default = 60.
hello_timeout
Set timeout used for periodic L2TP Hello messages (in seconds). Hello messages are sent only if no data or control frames have been sent or received since the last Hello was sent. Default=60.
retry_timeout
Retry timeout. The delay (in seconds) before sending the first retry of unacknowledged control frames. Default=1.
idle_timeout
Idle timeout. The time (in seconds) that a tunnel will remain after its last session has been torn down. Default=0, tunnel remains forever when it has no sessions, until a local administrator or network request deletes it..
max_sessions
Maximum number of sessions allowed on tunnel. Default=0 (limited only by max_sessions limit in system parameters).
mtu
MTU for all sessions in tunnel. Default=1460.
peer_profile_name
Name of peer profile which will be used for default values of the tunnel's parameters.
session_profile_name
Name of session profile which will be used for default values of the tunnel's session parameters.
ppp_profile_name
Name of ppp profile which will be used for default values of the tunnel's session PPP parameters.
establish_timeout
Establish timeout. The time (in seconds) that a tunnel will wait for the peer to complete the tunnel setup message exchange. This may be useful to protect against cases where a buggy or very slow peer acknowledges control messages but does not send timely tunnel setup response messages. Default=0 (no timeout).
always_transmit_keepalives
The L2TP protocol specification states that L2TP Hello messages should be transmitted only if no L2TP control or data frames have been received within a specified period. Thus, Hello messages are seldom transmitted. This option can be used to force Hello messages to be transmitted periodically, regardless of other activity in the tunnel. Default OFF
 

SESSION

session_profile_name
Name of session profile. If not specified, the profile name is inherited from the tunnel or the peer profile.
ppp_profile_name
Name of ppp profile to use for PPP parameters. If not specified, the profile name is inherited from the tunnel or the peer profile.
ethernet_profile_name
For L2TPv3 Ethernet pseudowires, this is the name of the ethernet profile to use for ethernet parameters.
debug
Debug options. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
sequencing_required
Says whether the use of sequence numbers in the data channel is mandatory. If set, the receipt of data packets without sequence numbers causes the session to be torn down.
use_sequence_numbers
Says to enable sequence numbers in the data channel if peer supports them.
no_ppp
Says to not start PPP on the L2TP session.
reorder_timeout
Timeout to wait for out-of-sequence packets before discarding. Data packet out-of-sequence reordering is not currently implemented.
session_type
Session type: LAC Incoming (LAIC), LAC Outgoing (LAOC), LNS Incoming (LNIC), LNS Outgoing (LNOC). Default=derived from tunnel type.
pseudowire_type
Indicates the type of data to be carried in an L2TPv3 pseudowire. Valid values are ppp or eth, corresponding to PPP and Ethernet pseudowires. Valid for L2TPv3 only. Required parameter for locally created L2TPv3 sessions. For network-created sessions, the pseudowire type is set by the remote peer requesting the session.
priv_group_id
Private group ID, used to separate this session into a named administrative group
interface_name
interface name of session interface. Default pppN for PPP pseudowires, or l2tpethN for ethernet pseudowires. Must be unique for each session instance.
user_name
PPP user name
user_password
PPP user password
framing_type
Framing type: sync, async or any. Default=any. These are passed to the peer when the session is set up to tell the capabilities of the network beyond the L2TP tunnel.
bearer_type
Bearer type: digital, analog, any. Default=any. These are passed to the peer when the session is set up to tell the capabilities of the network beyond the L2TP tunnel.
minimum_bps
Minimum bits/sec acceptable. Default=0 (don't care)
maximum_bps
Maximum bits/sec required. Default=9 (no limit)
connect_speed
Indicates transmit and receive connection speeds.
session_id
Session ID of session. Default=system chooses random ID. Use is discouraged.
debug
Debug options. Specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp_data, avp_info, avp_hide, func, system, kernel. Special values all and none enable or disable all options. Default=none.
sequencing_required
Says whether the use of sequence numbers in the data channel is mandatory. If set, the receipt of data packets without sequence numbers causes the session to be torn down.
use_sequence_numbers
Says whether to enable sequence numbers in the data channel if peer supports them.
no_ppp
Says to not start PPP on the L2TP session.
reorder_timeout
Timeout to wait for out-of-sequence packets before discarding. Out-of-sequence packet reordering is not currently supported.
establish_timeout
Establish timeout. The time (in seconds) that a session will wait for the peer to complete the session setup message exchange. This may be useful to protect against cases where a buggy or very slow peer acknowledges control messages but does not send timely session setup response messages. Default=0 (no timeout).
persist_pend_timeout
The time (in seconds) that a session in a persisting tunnel will wait in RETRY state before trying to establish itself again. Default=60.
cookie
For L2TPv3, each session carries an optional 4 or 8 byte cookie value in the packet header. This parameter specifies the cookie value to use for the session. The value is specified as hex digits, preceded by "hex:", e.g. hex:01234567. The number of hex digits must correspond to a 4 or 8 byte value.
cookie_len
If this parameter is set to 4 or 8 and a specific cookie value is not provided using the cookie parameter, a random cookie value is generated when setting up the session.
remote_end_id
Specifies the data to be transmitted in the Remote End Id AVP for L2TPv3 sessions. This value may be used to match incoming session setup requests. This is useful in servers because it allows specific incoming sessions to be matched to a specific session profile, and therefore a specific ppp or ethernet profile. The value is specified as hex digits, preceded by "hex:", e.g. hex:01234567. Default: empty.
l2spec_type
Specifies the L2TPv3 Layer2-Specific Sublayer Type to be used for sessions. Valid for L2TPv3 pseudowires only. This defines the format of a field in the L2TPv3 header of data packets. Valid values are "none" (no L2-Specific Sublayer present) or "default" (default L2-Specific Sublayer present). If using data sequence numbers, the Default L2-Specific Sublayer must be used. Default: "default".
 

EXAMPLES

A simple L2TP client.

system {
    # Don't let this system be used as a LNS
    deny_remote_tunnel_creates yes
}

tunnel "one" {
    peer_ipaddr 1.2.3.4

    session "one" {
        user_name "me"
        user_password "mypass"
    }
}
A simple L2TP server using RADIUS.

system {
    # Don't let this system be used as a LAC
    deny_local_tunnel_creates yes

    # Optional list of IP addresses that we listen on
    # Default is to listen on all interfaces.
    listen 1.2.3.4,10.11.12.13
}

ppp profile "default" {
    # Use RADIUS to authenticate all PPP users
    use_radius yes

    # Enable PAP and CHAP only, since that is all RADIUS supports
    auth_mschap no
    auth_mschapv2 no
    auth_eap no
}
A simple L2TP server using non-ephemeral UDP ports.

system {
    # Don't let this system be used as a LAC
    deny_local_tunnel_creates yes

    # Optional list of IP addresses that we listen on
    # Default is to listen on all interfaces.
    listen 1.2.3.4,10.11.12.13
}

# To use a non-ephemeral port for tunnels created by network request,
# configure local_udp_port to be the desired port (usually 1701). This
# forces prol2tpd to use that port for the local UDP port, instead of
# assigning an unused port for the tunnel. Using a fixed port can be
# useful if a NAT gateway is in the path, when the NAT gateway does
# not track UDP ephemeral ports.

tunnel profile "default" {
       local_udp_port 1701
}
An L2TP server using static addresses for VPN clients.

system {
    # Don't let this system be used as a LAC
    deny_local_tunnel_creates yes

    # Optional list of IP addresses that we listen on.
    # Default is to listen on all interfaces.
    listen 1.2.3.4,10.11.12.13
}

tunnel profile "default" {
    # Only one session per tunnel (VPN)
    max_sessions 1
}

peer profile "one" {
     # This client connects from the 80.81.82/24 net
     peer_ipaddr 80.81.82.0
     netmask 255.255.0.0
     ppp_profile_name "one"
}

peer profile "two" {
     # This client connects using a static public IP 40.41.42.43
     peer_ipaddr 40.41.42.43
     ppp_profile_name "two"
}

peer profile "road-warrior-3.katalix.com" {
     # This client has a name "road-warrior-3.katalix.com". For
     # incoming tunnel setup requests, prol2tpd looks for a peer
     # profile with a name that matches the client's name. This
     # is useful when the client does not use a fixed IP address.
     # Few L2TP clients support configurable names and it can be
     # difficult to find out what name a client is using.
     # If using the ProL2TP client, use the host_name parameter
     # when creating the tunnel.
     ppp_profile_name "three"
}

# Use fixed PPP addresses for each peer's connection
ppp profile "one" {
     local_ipaddr 10.1.1.1
     peer_ipaddr 10.1.1.2
}

ppp profile "two" {
     local_ipaddr 10.1.1.1
     peer_ipaddr 10.1.1.3
}

ppp profile "three" {
     local_ipaddr 10.1.1.1
     peer_ipaddr 10.1.1.4

     # Enable LCP echo because this client's network is unreliable
     lcp_echo_interval 10
}
A simple L2TPv3 server for an ethernet pseudowire.

system {
    # Don't let this system be used as a LAC
    deny_local_tunnel_creates yes

    # Optional list of IP addresses that we listen on
    # Default is to listen on all interfaces.
    listen 1.2.3.4,10.11.12.13
}

tunnel profile "default" {
    # Use L2TPv3.
    proto_version 3

    # Log tunnel events. Optional.
    debug protocol,fsm
}

session profile "default" {
    # Force ethernet pseudowire type for L2TPv3 clients.
    pseudowire_type eth

    # Log session events. Optional. 
    debug protocol,fsm
}

ethernet profile "default" {
    # Configuration for the ethernet interface of the pseudowire
    local_ipaddr 10.5.1.1
    peer_ipaddr 10.5.1.2
}

A simple L2TPv3 client for an ethernet pseudowire.

system {
    # Don't let this system be used as a LNS
    deny_remote_tunnel_creates yes
}

tunnel profile "default" {
    # Use L2TPv3.
    proto_version 3

    # Optional IP encapsulation. UDP is the default.
    # encap_type ip
}

session profile "default" {
    # Force ethernet pseudowire type for L2TPv3 clients.
    pseudowire_type eth

    # Use a 4-byte L2TPv3 cookie. Optional.
    cookie_len 4
}

ethernet profile "default" {
    # Configuration for the ethernet interface of the pseudowire
    local_ipaddr 10.5.1.2
    peer_ipaddr 10.5.1.1
}

tunnel "one" {
    peer_ipaddr 1.2.3.4

    session "one" {
        use_sequence_numbers no
    }
}
A more complex L2TPv3 server, serving several ethernet pseudowires.

system {
    # Don't let this system be used as a LAC
    deny_local_tunnel_creates yes

    # Optional list of IP addresses that we listen on
    # Default is to listen on all interfaces.
    listen 1.2.3.4,10.11.12.13
}

tunnel profile "default" {
    # Use L2TPv3.
    proto_version 3

    # Log tunnel events. Optional.
    debug protocol,fsm

    # Authenticate tunnels
    auth_mode challenge
    message_digest md5
    secret "my_password"
}

session profile "default" {
    # Force ethernet pseudowire type for L2TPv3 clients.
    pseudowire_type eth

    # Log session events. Optional. 
    debug protocol,fsm
}

ethernet profile "default" {
    # Allow space for IP, UDP and L2TP headers
    # 1500-20-8-12=1460
    mtu 1460
}

session profile "one" {
    # Use a fixed cookie value for this session
    cookie hex:1122334455667788

    # Match this profile only with requests using this cookie
    peer_cookie hex:aa55bb6612345678

    pseudowire_type eth
    ethernet_profile_name "one"
}

ethernet profile "one" {
    # Configuration for the ethernet interface of the pseudowire
    local_ipaddr 10.5.1.1
    peer_ipaddr 10.5.1.2

    # Allow space for IP, UDP and L2TP headers (including optional cookie)
    # 1500-20-8-20=1452
    mtu 1452
}

session profile "two" {
    # Use a fixed cookie value for this session
    cookie hex:2233445566778899

    # Match this profile only with requests using this cookie
    peer_cookie hex:12345678abcdef01

    pseudowire_type eth
    ethernet_profile_name "two"
}

ethernet profile "two" {
    # Configuration for the ethernet interface of the pseudowire
    local_ipaddr 10.5.1.3
    peer_ipaddr 10.5.1.4

    # Allow space for IP, UDP and L2TP headers (including optional cookie)
    # 1500-20-8-20=1452
    mtu 1452
}

If the client uses ProL2TP, it would be configured to connect to the
above server as follows:-

system {
    # Don't let this system be used as a LNS
    deny_remote_tunnel_creates yes
}

ethernet profile "one" {
    # Configuration for the ethernet interface of the pseudowire
    local_ipaddr 10.5.1.2
    peer_ipaddr 10.5.1.1
}

tunnel "one" {
    peer_ipaddr 1.2.3.4

    # Use L2TPv3.
    proto_version 3

    # L2TPv3 tunnel authentication
    auth_mode challenge
    secret "my_password"
    message_digest md5

    session "one" {
        use_sequence_numbers no
        pseudowire_type eth
        ethernet_profile_name "one"
        cookie hex:aa55bb6612345678
    }
}
 

SEE ALSO


prol2tp(1), prol2tpctl(1), prol2tp(7), prol2tpd(8), /usr/share/doc/prol2tp/example-configs


 

Index

NAME
SYNOPSIS
DESCRIPTION
FILE SYNTAX
BLOCK TYPES
PARAMETERS
SYSTEM
PEER PROFILE
TUNNEL PROFILE
SESSION PROFILE
PPP PROFILE
ETHERNET PROFILE
IP POOL
TUNNEL
SESSION
EXAMPLES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 14:25:48 GMT, June 03, 2013