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.

ProL2TP has many parameters which might be daunting at first. In practice, few parameters need to be set to configure a working system. Some sample config files are usually installed in /usr/share/doc/prol2tp/example-configs/.  

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 a locally initiated L2TP tunnel. A tunnel is identified by a unique name and may contain tunnel parameters and one or more session blocks, one per session within the tunnel. Tunnel parameters may be derived from a named tunnel profile. A tunnel block is used only in client configurations to 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. The default values are suitable for most cases.

 

SYSTEM

debug
System debug options. This controls the generation of log messages. In ProL2TP, messages are group into categories which may be individually enabled or disabled. For example, state machine events are grouped under an fsm category, and protocol related debug is grouped under a protocol category. Options are specified as a comma-separated list of debug categories: protocol, fsm, api, transport, data, ppp, avp, func, system, kernel. Special values all and none enable or disable all options.
next_tunnel_debug
Enable or disable debug for the next created tunnel. Overrides debug settings set at create time or by the administrator. When a new tunnel is created with debug enabled via this setting, the setting is cleared. This is therefore useful to enable debug for a single tunnel instance in a busy system, to diagnose tunnel related problems.
next_session_debug
Enable or disable debug for the next created session. Overrides debug settings set at create time or by the administrator. When a new session is created with debug enabled via this setting, the setting is cleared. This is therefore useful to enable debug for a single session instance in a busy system, to diagnose session related problems.
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.
log_file
Set the output file for log messages. If not specified, log messages are sent to syslog. Messages are timestamped. Default is to use syslog.
log_buffer
Denotes a log buffer config block, enclosed by parenthesis. See the LOG BUFFER section.
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.
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.
autoname_interfaces
Controls whether prol2tpd automatically names L2TPv3 ethernet network interfaces if a name isn't otherwise specified using the session's interface_name parameter. Usually, the Linux kernel automatically names network interfaces. However, the Linux kernel limits the number of interface names using the same name prefix (in L2TP's case l2tpeth) to 32768. This parameter is therefore only useful in environments where more than that number of L2TPv3 ethernet pseudowires are used. Default=OFF.
 

LOG BUFFER

An optional log_buffer block may be used within a SYSTEM block to enable logging to an internal log buffer. The message log level and debug options may be configured independently, giving flexibility for logging different messages to the main log (syslog or file) or to the log buffer. The log buffer is viewed using the prol2tp show log command.

buffer_size
The buffer size, in bytes. If 0, the log buffer is disabled. If the size is modified, any messages already in the log buffer are lost. Default=4096.
buffer_wrap
A boolean flag, controlling whether the log buffer wraps when full, overwriting old messages. If set to false, new messages are not added to the log buffer once it fills up. Default=YES.
debug
Log buffer debug options. This controls which message categories get added to the log buffer. Options are specified as a comma separated list, as described in the debug parameter of the SYSTEM block. The default value is inherited from the SYSTEM block's debug setting.
log_level
The log level for messages logged to the log buffer. The default value is inherited from the SYSTEM block's log_level setting.
 

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

Tunnel profile parameters may also be used in Tunnel statements.

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. Default=NONE.
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.
dscp
Set 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=0 (no DSCP set).
encap_type
If the tunnel is L2TPv3, this parameter specifies the tunnel transport encapsulation type: udp or ip. For L2TPv2 tunnels, this parameter is ignored, since L2TPv2 is UDP only. Default=udp.
local_udp_port
When UDP encapsulation is being used, specifies the 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
When UDP encapsulation is being used, specifies the UDP port number to use for the tunnel. Default is to assign an ephemeral port during UDP connection establishment with the peer.
interface_name
The local network interface name to use for the tunnel, e.g. eth0. This can be used to force a specific interface to be used; the interface is usually derived by a route lookup. Default=NONE (use any).
use_tiebreaker
Enable use of a tiebreaker when setting up the tunnel. This enforces a single tunnel between the local system and the L2TP peer. It is typically used where a tunnel can be initiated by both the LAC and LNS, but may also be used to enforce only one active tunnel between two peers. Default=OFF.
framing_cap
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. Default=any.
bearer_cap
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. Default=any.
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=NONE (use local system hostname).
secret
Optional secret which is shared with tunnel peer. Must be specified when hide_avps is enabled. Default=NONE (no secret).
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. The L2TP protocol allows some L2TP Attribute Value Pairs (AVPs) contained in L2TP control protocol messages to be obscured from network sniffers. This adds some overhead with L2TP message transmit and receive. Requires a tunnel secret to be configured. Default OFF.
pseudowire_caps
For L2TPv3 tunnels, this 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. Default : derived from local Linux kernel features available.
debug
Enables or disables debug messages from the tunnel. Default=OFF.
use_udp_checksums
When UDP encapsulaion is used, specifies to 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. Default=10.
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. Default=10.
retry_timeout
Retry timeout. The delay (in seconds) before sending the first retry of unacknowledged control frames. If the peer does not respond, an exponential backoff is used for each retry, until the retry timeout reaches 8 seconds. 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 in tunnel. Default=0 (limited only by max_sessions limit in system parameters).
mtu
Default MTU for all sessions in tunnel. Usually overridden by an quivalent mtu setting in the session. Default=1460.
session_profile_name
Name of session profile which will be used for default values of the tunnel's session parameters, unless a session profile name is determined by other configuration. Default = not set.
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 = 120.
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 = 300.
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 in the tunnel 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.
interop_flags
Specifies a bitmask of flags to control non-standard behaviour for interopability with other L2TP implementations. It is specified as an integer value and used as a bitmask to enable or disable options individually. Default=0 (no options enabled).
Bit Use
0   Include PROTOCOL_VERSION AVP
      in L2TPv3 SCCRP messages.
1   Include PSEUDOWIRE_TYPE AVP
      in L2TPv3 ICRP messages.
2   Use ASSIGNED_COOKIE AVP value to
      indicate the cookie in outbound
      data packets of the session. Default
      is it indicates the expected cookie
      in received data packets.
3   If SCCRQ has been acked by peer, it
      wins the tiebreaker.
4   If a locally-created tunnel fails and
      tries to establish again, have it retain
      its original tunnel_id.
5   Ignore missing CIRCUIT_STATUS AVP in
      received L2TPv3 ICRQ/ICRP messages.
6   Send Cisco AVPs in L2TPv3
      ICRQ/ICRP/ICCN messages.
7   Set M bit in transmitted
      PROTOCOL_VERSION AVP.
8   Use Cisco format for L2TPv3
      L2SPECIFIC_SUBLAYER AVP.
9   Send ZLB messages instead of ACK messages
      in L2TPv3 authenticated tunnels.
enforce_unique_peer
Each L2TP peer identifies itself using L2TP host_name and/or router_id AVPs in its SCCRQ tunnel setup request and these values may be used to reference peer-specific settings. Setting this boolean flag ON enables extra checks when L2TP tunnel setup messages are received to check that the advertised host_name and/or router_id values are not already in use by another L2TP peer. This can be useful in some networks where operators own both the client and server sides of the L2TP network and wish to ensure that misconfigured clients cannot mistakenly share config settings of another client. Default: OFF.
 

SESSION PROFILE

Session profile parameters may also be used in SESSION statements.

ppp_profile_name
For PPP sessions, this is the name of ppp profile to use for PPP parameters. If not specified, the profile name is inherited from the tunnel or the peer profile. Default=NONE..
ethernet_profile_name
For L2TPv3 Ethernet pseudowires, this is the name of the ethernet profile to use for ethernet parameters. Default=NONE.
debug
Enables or disables debug messages from the session. Default=OFF.
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, eth or vlan, corresponding to PPP, Ethernet and VLAN pseudowires. Valid for L2TPv3 only. For vlan pseudowire types, vlan_id must also be specified. Required parameter for locally created L2TPv3 sessions. For network-created sessions, the pseudowire type is set by the remote peer requesting the session. This is a required parameter of SESSION blocks for L2TPv3 sessions. Default=NONE.
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, l2tpethN for ethernet pseudowires, or l2tpethN.M for vlan pseudowires (where M is the vlan id).
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. 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=0 (no limit)
connect_speed
Indicates transmit and receive connection speed. This option is deprecated. Use tx_connect_speed and rx_connect_speed instead.
tx_connect_speed
Indicates transmit connection speed.
rx_connect_speed
Indicates receive connection speed.
use_sequence_numbers
Says whether to enable sequence numbers in the data channel if peer supports them.
reorder_timeout
Timeout to wait for out-of-sequence packets before discarding.
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 all transmitted data packets of 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 of the specified length 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. All data packets received from the peer are expected to have the cookie value specified. Default: no peer cookie.
remote_end_id
This parameter is used to identify the session instance in L2TPv3 tunnels. Its value is indicated to the peer and is shared with the peer. Hence it is used by administrators to identify the session instance at both the local end and remote end. This value may be used to match incoming session setup requests via a session profile, and therefore a specific ppp or ethernet profile. It may also be used by the L2TPv3 session setup collision detection mechanism. The value is specified as hex digits, preceded by "hex:", e.g. hex:01234567 or a quoted string and must match the corresponding value for the session configured at the peer. Default: empty.
use_tiebreaker
Enable use of a tiebreaker when setting up the session. The tiebreaker is used when a collision in session setup messages is detected, where both L2TP peers attempt to setup a session with a given remote_end_id simultaneously. It is useful only for L2TPv3 LAC-LAC or LNS-LNS setups. Default=OFF.
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".
user_data
Specifies a string to be associated with the session. This may be useful to store environment-specific information with the session. If set, it is used as the value for the USER_DATA environment variable in the session event scripts. Default: empty.
 

PPP PROFILE

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_requests
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_config_requests
Maximum number of IPCP config-requests to transmit without successful acknowledgement before declaring a failure. Default=10.
ipcp_max_config_naks
Maximum number of IPCP config-naks to allow before starting to send config-rejects instead. Default=10.
ipcp_max_terminate_requests
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_config_requests
Maximum number of LCP config-request transmissions. Default=10.
lcp_max_config_naks
Maximum number of LCP config-requests to transmit without successful acknowledgement before declaring a failure. Default=10.
lcp_max_terminate_requests
Maximum number of LCP term-requests to send. Default=3.
lcp_retransmit_interval
LCP retransmission timeout. Default=3.
allow_ppp_compression
Allow one or more PPP compression algorithms. In most cases, PPP and IP header compression is disabled in L2TP links. This option allows compression to be enabled in environments where packet loss is unlikely and bandwidth usage is an important deployment consideration. To set specific compression options, use extra_options to add other pppd options such as deflate. If this option is OFF, all compression options are disabled by the following options: "noacccomp nopcomp nobsdcomp nodeflate nopredictor1 novj novjccomp". Default=OFF.
initiate_lcp
When used at a server, PPP usually listens silently for LCP messages from the peer. This option may be used to force the server to send LCP configure-request messages when establishing the PPP link. This parameter is ignored if used at the client side since clients always initiate LCP. Default=NO.
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, or used to locate a local IP pool defined using an ip pool block.
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..
extra_options
A quoted string of space-separated extra pppd options. This option may be useful to add pppd options which are not available in the PPP profile. If set, these arguments are included in the pppd command arguments when ProL2TP start the PPP instance. Default: NONE.
 

ETHERNET PROFILE

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
The VLAN ID to be used for VLAN pseudowires (pseudowire_type vlan). It is passed to session scripts (if used) in a VLAN_ID environment variable regardless of pseudowire type setting.
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.
mac_addr
The ethernet MAC address to be assigned to the network interface device created for the L2TPv3 ethernet session. MAC address values are specified as 6 hexadecimal bytes separated by a colon, e.g. 00:01:02:03:04:05. If not specified, the MAC address used for the interface is auto-generated.
 

IP POOL

debug
Enables or disables debug messages from the ip pool. Default=OFF.
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

A tunnel block tells prol2tpd about tunnels which it should establish with L2TP peers. If such tunnels fail, prol2tpd will periodically try to re-establish them. There is one TUNNEL block per tunnel instance. If configuring a server which does not initiate tunnels itself, it is necessary to define TUNNEL blocks in the config file.

All parameters of the tunnel profile may be used in tunnel statements and override any parameter also supplied via a tunnel profile. In addition, several parameters may only be specified in the tunnel statement. These are identified below.

As a minimum, the peer_ipaddr parameter must be specified, either via a tunnel profile or in the tunnel statement.

In addition to the parameters listed for tunnel profiles, the following parameters may also be specified in the tunnel statement.

tunnel_id
Optional tunnel id of new tunnel. Usually auto-generated. Use is discouraged. Default = autogenerate.
tunnel_profile_name
Name of tunnel profile which will be used for default values of this tunnel's parameters. Default = no profile specified.
 

SESSION

A session block tells prol2tpd about sessions which it should establish with L2TP peers. Session blocks must always be within a TUNNEL block of the parent tunnel. If such sessions fail, prol2tpd will periodically try to re-establish them while the parent tunnel is up. There is one SESSION block per session instance. If configuring a server which does not initiate sessions itself, it is necessary to define SESSION blocks in the config file.

All parameters of the session profile may be used in session statements and override any parameter also supplied via a session profile. In addition, several parameters may only be specified in the session statement. These are identified below.

For sessions in L2TPv3 tunnels, the pseudowire_type parameter must be specified, either via a session profile or in the session statement.

In addition to the parameters listed for session profiles, the following parameters may also be specified in the session statement.

session_id
Optional session id of new session. Usually auto-generated. Use is discouraged. Default = autogenerate.
session_profile_name
Name of session profile. If not specified, the profile name is inherited from the tunnel or the peer profile.
 

EXAMPLES

Some sample config files are provided with ProL2TP. They are usually installed in the system's /usr/share/doc area, in a prol2tp subdirectory.
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" {
        pseudowire_type ppp
        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

    log_level notice
    debug protocol,fsm
}

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

    # Log tunnel events. Optional.
    debug on
}

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

    # Log session events. Optional. 
    debug on
}

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

    log_level notice
    debug protocol,fsm
}

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

    # Log tunnel events. Optional.
    debug on

    # 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 on
}

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
    }
}
A symmetric L2TPv3 LAC-LAC ethernet pseudowire.

system {
    # Identifier for this L2TP peer
    router_id 1.2.3.43

    log_level notice
    debug protocol,fsm
}

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

    # Log tunnel events. Optional.
    debug on
}

session profile "one" {
    # Matches sessions with the given remote_end_id
    remote_end_id "1"

    # Force ethernet pseudowire type for L2TPv3 clients.
    pseudowire_type eth

    # Enable L2TPv3 session tiebreaker
    use_tiebreaker yes

    # Ethernet params for this session
    eth_profile_name "one"

    # Log session events. Optional. 
    debug on
}

ethernet profile "one" {
    # Configuration for the ethernet interface of the pseudowire
    bridge_name "br0"
}

tunnel "one" {
    peer_ipaddr 1.2.3.42
    use_tiebreaker yes
    session "one" {
        pseudowire_type eth
        remote_end_id "1"
        use_tiebreaker yes
        eth_profile_name "one"
    }
}

At the peer, a similar configuration can be used.


system {
    # Identifier for this L2TP peer
    router_id 1.2.3.42

    log_level notice
    debug protocol,fsm
}

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

    # Log tunnel events. Optional.
    debug on
}

session profile "one" {
    # Matches sessions with the given remote_end_id
    remote_end_id "1"

    # Force ethernet pseudowire type for L2TPv3 clients.
    pseudowire_type eth

    # Enable L2TPv3 session tiebreaker
    use_tiebreaker yes

    # Ethernet params for this session
    eth_profile_name "one"

    # Log session events. Optional. 
    debug on
}

ethernet profile "one" {
    # Configuration for the ethernet interface of the pseudowire
    bridge_name "br0"
}

tunnel "one" {
    peer_ipaddr 1.2.3.43
    use_tiebreaker yes
    session "one" {
        pseudowire_type eth
        remote_end_id "1"
        use_tiebreaker yes
        eth_profile_name "one"
    }
}
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
    }
}
L2TPv3 ethernet pseudowire from a cisco router.

# Start prol2tpd with "-p cisco_avp.so" to enable cisco vendor AVP
# support.
#
system {
        deny_local_tunnel_creates yes
}

tunnel profile "default" {
        proto_version 3
        encap_type ip
        mtu 1500
        # Enable non-standard protocol workarounds for cisco
        interop_flags 3
}

session profile "default" {
        pseudowire_type eth
}

ethernet profile "default" {
        # Bridge br0 must already exist
        bridge_name "br0"
        mtu 1500
}
Enable the internal log buffer.


system {
    # The main system log goes to syslog by default, or a file if
    # log_file is set below
    log_file /path/to/log/file
    debug all
    log_level warning

    # The log buffer is an optional debug tool for capturing
    # certain log messages in memory separate to the main log. It
    # can be configured independently of the system log.
    log_buffer {
        debug all
        log_level debug
        buffer_size 10000
        buffer_wrap yes
    } 
}

# More config settings here
 

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
LOG BUFFER
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: 13:51:04 GMT, May 25, 2018