proacd.conf(5) ProL2TP Manual proacd.conf(5)
NAME
proacd.conf - proacd configuration file
SYNOPSIS
This document describes the configuration file syntax of the ProL2TP
Access Concentration Daemon.
DESCRIPTION
The proacd.conf file contains configuration information for proacd.
Whitespace and newline characters are ignored. Comments may be
included: they start with the # character, and end at the end of the
line. Keywords are case sensitive and lowercase. The configuration
consists of one or more route definitions, and zero or more profile
definitions. Strings may be quoted where they need to include spaces.
SYSTEM CONFIGURATION
General proacd configuration is done in the system configuration block.
The system configuration block is defined using the keyword system, and
an open brace begins the content of the system configuration. This is
followed by system configuration statements, and the block ends with a
closing brace.
system { system_configuration_statements }
CONFIGURATION STATEMENTS
debug [mask]
The debug statement replicates the functionality of the -D and -d
proacd commandline options. The presence of the debug keyword, with
or without a following mask enables debug message output. The
optional mask is a comma separated list of debug modules. Valid
debug modules are route, pppoe, l2tp, radius, ppp, pppfsm, lcpfsm,
ctrl, trace, pppd, system and parser. The special mask all enables
debugging in all modules.
log_file "filename"
The log_file keyword replicates the functionality of the -o proacd
commandline option. It redirects proacd output to the file
indicated by the parameter filename, which must be enclosed in
double quotes. The full directory path to the filename must already
exist, proacd will not create directories.
ac_name "name"
The ac_name keyword sets an arbitrary string to be sent in the AC-
Name tag of PPPoE PADO discovery packets as per RFC2516. If unset
proacd will generate a default string based on the software version
number and name of the host it is running on.
ROUTE DEFINITION
Routes are defined using the keyword route, followed by a unique route
name. An open brace begins the content of the route definition, the
route source and destination definitions immediately follow, and the
definition is ended by a closing brace. A route definition must include
only one each of source and destination declarations, the order of
which is unimportant.
route "name" { source_definition destination_definition }
PROFILE DEFINITION
Profiles are used to contain a destination definition so that it may be
referred to by name. A profile is defined using the keyword profile,
followed by a unique profile name. An open brace begins the content of
the profile definition, the profile destination definition follows, and
the definition is ended by a closing brace. A profile definition must
contain exactly one destination declaration.
profile "name" { destination_definition }
SOURCE DEFINIITON
A source definition begins with the keyword source (or the abbreviation
src), followed by a protocol name (see SOURCE PROTOCOLS below). An
open brace begins the content of the source definition, followed by
protocol specific statements, and ended by a closing brace.
source protocol { statement [ ... statement ] }
DESTINATION DEFINIITON
A destination definition begins with the keyword destination (or the
abbreviation dst), followed by a protocol name (see DESTINATION
PROTOCOLS below). An open brace begins the content of the destination
definition, followed by protocol specific statements, and ended by a
closing brace.
destination protocol { statement [ ... statement ] }
SOURCE PROTOCOLS
PPPoE
A PPPoE source definition uses the protocol keyword pppoe. The
following statements are used within a PPPoE source definition to
control client's access to services:
The interface statement
Specifies the ethernet interface on which to listen for PPPoE session
requests, one and only one interface is required per PPPoE source
definition.
interface "interface_name"
The service_name statement
PPPoE client service requests include a service name, service_name
statements specify which requests will be granted. At least one
service_name statement is required in a PPPoE source definition,
multiple service_name statements are permitted.
service_name any
Indicates that service should be provided to any client requesting it,
regardless of the service name they request. When proacd responds to a
PPPoE service request as a result of this statement, the service name
that is returned to the client will match the one they requested. This
prevents clients from trying different service names in order to
establish what services the access concentrator provides.
service_name advertised "name"
Indicates that proacd should advertise to clients that service name is
provided by this access concentrator. Service will be provided to any
client which requests a service with this name.
service_name private "name"
Indicates that proacd should provide service to clients which request a
service named name. The service name will not be advertised to clients
who request a list of services this access concentrator provides.
Multiple routes may offer service on the same ethernet interface. In
this case, proacd will attempt to match the service name requested to
an advertised or private service_name statement before resorting to
providing service under a service_name any statement.
To avoid a routing conflict, only one route may offer to provide
service with the service_name any on any particular ethernet interface.
DESTINATION PROTOCOLS
L2TP
An L2TP destination definition uses the protocol keyword l2tp. The
proacd daemon will establish a new L2TP session within an L2TP tunnel
for each successfully negotiated route source connection. The
following statements are used within an L2TP destination definition to
control session and tunnel creation:
The tunnel_name statement
Specifies the name to give to the tunnel which will be established (if
it isn't already opened) as the destination for this route.
tunnel_name "name"
The tunnel_profile statement
Specifies the prol2tpd tunnel profile name which contains the
parameters of the tunnel which proacd will establish as the destination
for this route. All tunnel configuration must be done via prol2tpd
profiles.
tunnel_profile "name"
The peer_address statement
This statement sets the address (IP address or fully qualified domain
name) of the L2TP peer to which the tunnel should be established.
peer_address "address"
PPPD
A PPPD destination definition uses the protocol keyword pppd. The
proacd daemon will fork a new pppd process to handle the incoming PPPoE
session. The following statements are used within a PPPD destination
definition to configure the pppd process which is started.
The options_file statement
Specifies the path to the options file which will be passed directly
through to the new pppd instance using the pppd parameter file. All
other pppd configuration must be done via the options file.
options_file "path"
RADIUS
A RADIUS destination definition uses the protocol keyword radius. The
final destination endpoint of a RADIUS route is discovered by proacd
using the RADIUS protocol.
A RADIUS destination consists of RADIUS configuration statements and
one or more server definitions:
destination radius { [ statements ... ] server_definition [ ...
server_definition ] }
CONFIGURATION STATEMENTS
The ppp_auth_protocols statement
The ppp_auth_protocols statement is a comma-separated quoted list of
the authentication protocols to be negotiated with PPPoE clients during
LCP. This list should match the authentication protocols offered by
RADIUS servers within the enclosing RADIUS destination definition.
Supported authentication types are "pap", "chap" and "eap". If not
specified proacd defaults to offering all protocols (equivalent to
ppp_auth_protocols "pap,chap,eap")
ppp_auth_protocols "auth_protocol_list"
The proxy_auth statement
The proxy_auth statement sets a boolean flag to enable or disable proxy
authentication if supported by the destination. If enabled, PPP
authentication data is collected by proacd and sent to an L2TP peer in
additional L2TP AVPs when the L2TP session is established. If not
specified, proxy authentication is disabled.
proxy_auth "yes|no"
SERVER DEFINITION
This defines one of the group of RADIUS servers to contact for
destination endpoint parameters. The server definition begins with the
keyword server followed by the address (IP address or fully qualified
domain name) of the RADIUS server. An open brace begins the content of
the server definition, followed by further RADIUS server statements,
and is ended by a closing brace.
server "address" { statement [ ... statement ] }
The secret statement
The secret statement specifies the shared secret to use when contacting
this RADIUS server. The secret statement is mandatory.
secret "secret"
The retries statement
The retries statement sets the number of times proacd should retry an
attempt to contact a RADIUS server before giving up. If this statement
is not present, the default number of retries is 2 (i.e.: a total of 3
attempts to contact the server).
retries retries
The timeout statement
The timeout statement specifies the number of seconds that proacd
should wait for a response from a RADIUS server. If this statement is
not present, the default is to wait for 5 seconds.
timeout seconds
The port statement
The port statement sets the UDP port number to use when contacting the
RADIUS server for authentication. Valid values are numbers in the
range 1 to 65535. The default value if not specified is 1812.
port number
RADIUS SERVER CONFIGURATION
When using a RADIUS server to provide the parameters of a route
destination, certain RADIUS attributes must be returned so that proacd
can open the required destination endpoint. Depending on the RADIUS
attributes returned, proacd is able to route to either L2TP or PPPD
destinations.
L2TP ATTRIBUTES
To configure an L2TP destination, the following attributes should be
set in the RADIUS server configuration. It is possible to specify all
of the required L2TP parameters via RADIUS attributes, or to use a
combination of local configuration parameters in proacd and prol2tpd
and RADIUS attributes. For any parameters specified in both the
derived proacd/prol2tpd profile AND via a returned RADIUS attribute,
the RADIUS value will be used.
MANDATORY
Tunnel-Type
Selects the destination endpoint protocol. Set to L2TP.
OPTIONAL
Tunnel-Private-Group-ID
If Tunnel-Server-Endpoint is also specified, this attribute is
interpreted as the prol2tpd tunnel profile name to be used to
create the tunnel.
If Tunnel-Server-Endpoint is not specified, then this attribute is
interpreted as a proacd profile name, and the tunnel parameters
will be derived from that profile.
Tunnel-Assignment-ID
Sets the tunnel name. If not set, the tunnel name is taken from the
proacd profile, or Tunnel-Private-Group-ID value, else the string
"default".
Tunnel-Server-Endpoint
Sets the IP address or FQDN of the tunnel destination server. If
not set, this address is derived from the proacd profile. If no
address can be derived, the tunnel will not establish.
Tunnel-Client-Endpoint
Sets the IP address of the local interface to be used for the
tunnel. This must be an IP address of an existing public interface
of the LAC. The default is to let the system's routing tables
determine the best interface to reach the L2TP tunnel peer address.
Tunnel-Password
Sets the password (shared secret) to be used when establishing the
L2TP tunnel. If not set, the LAC will attempt to establish an
unauthenticated L2TP tunnel.
Tunnel-Client-Auth-ID
Sets the advertised name when establishing the L2TP tunnel to the
peer. This value is passed in L2TP control packets to the peer in
the L2TP HostName AVP and may be used by the peer to match
configured parameters of the requestor. If not set, the system's
hostname is used.
Tunnel-Medium-Type
Selects the tunnel medium. This attribute tells proacd how to
decode the address values given in Tunnel-Client-Endpoint and
Tunnel-Server-Endpoint attributes. Currently only IPv4 is
supported.
Katalix-Tx-Connect-Speed
Sets the transmit connect speed to use for the session. This is a
Katalix vendor specific attribute: vendor 42620, attribute type 1.
Katalix-Rx-Connect-Speed
Sets the receive connect speed to use for the session. This is a
Katalix vendor specific attribute: vendor 42620, attribute type 2.
PPPD ATTRIBUTES
To configure a PPPD destination, it is necessary to define a profile
with a PPPD destination definition (see PROFILE DEFINITION above). This
profile will be used to configure the pppd session, and is selected by
the Framed-Route attribute.
The following attributes should be set in the RADIUS server
configuration to indicate to proacd that it should terminate an
incoming session with a local pppd instance.
MANDATORY
Framed-Protocol
Selects the destination endpoint protocol. Set to PPP.
Framed-Route
Selects the proacd profile name, the destination parameters will be
derived from that profile.
OPTIONAL
Framed-IP-Address
Gives the IP address to be passed to pppd to use as the remote IP
address for the PPP session. This is passed via the pppd
commandline as ":<remote-ip-address>", the IP address to be used
for the local IP address should be configured via the pppd options
file as "<local-ip-address>:".
ACCESS CONTROL LISTS
To protect against denial of service attacks (DoS), proacd implements
access control lists. One access control definition may be included
within a source definition. Access control definitons begin with either
the allow or the deny keyword. An open brace begins the content of the
control list, followed by one or more list entries and the definition
is ended with a closing brace. Lists defined with the allow keyword
cause proacd to deny access to any clients which don't match one of the
following list entries. Lists defined with the deny keyword cause
proacd to deny access to any clients which match one of the following
list entries.
allow { list_entry [ ... list_entry ] }
deny { list_entry [ ... list_entry ] }
The syntax of the list_entry is dependent on the protocol of the route
source.
PPPoE
Access control list entries for PPPoE sources contain the ethernet MAC
addresses of the clients to allow/deny access to, for example:
allow { "12:34:56:78:9A:BC" "23:45:67:89:AB:CD" }
Access control lists can also be modified at runtime using the
proac_manage utility, see it's manpage for details.
EXAMPLES
route "public clients" {
source pppoe {
interface "eth0"
service_name any
deny {
"12:34:56:78:9A:BC"
"23:45:67:89:AB:CD"
}
}
destination l2tp {
tunnel_name "public tunnel"
tunnel_profile "public"
peer_address "192.168.1.100"
}
}
route "private clients" {
source pppoe {
interface "eth0"
service_name private "restricted"
service_name private "private"
}
destination l2tp {
tunnel_name "private tunnel"
tunnel_profile "private"
peer_address "privatel2tp.example.com"
}
}
profile "radius_pppd" {
destination pppd {
options_file "/etc/ppp/options.radius"
}
}
route "dynamic clients" {
source pppoe {
interface "eth0"
service_name private "dynamic"
}
destination radius {
ppp_auth_protocols "chap,eap"
proxy_auth on
server "radiusauth.example.com" {
secret "terces 321"
timeout 10
port 7777
}
}
}
route "management" {
source pppoe {
interface "eth1"
service_name any
}
destination pppd {
options_file "/etc/ppp/options.management"
}
}
A PPPoE client connection on eth0 which requests a service name other
than 'restricted' or 'private' will use the 'public clients' route.
proacd will open a session inside the tunnel 'public tunnel' to the
peer at 192.168.1.100 and forward all PPPoE session packets to the peer
over that session. If the tunnel 'public tunnel' does not already
exist, proacd will ask prol2tpd to create it using the prol2tpd tunnel
profile named 'public'.
A PPPoE client which requested the service name 'restricted' or
'private' will instead be forwarded down a session created by proacd on
the tunnel 'private tunnel' to the peer privatel2tp.example.com. If
the tunnel 'private tunnel' does not already exist, proacd will ask
prol2tpd to create it using the prol2tpd tunnel profile named
'private'.
A PPPoE client requesting the service name 'dynamic' will perform
initial LCP negotiation with proacd itself, which will offer CHAP or
EAP authentication. This will cause proacd to contact the RADIUS server
radiusauth.example.com on port 7777 with the PPPoE client's
authentication parameters. The RADIUS server may then accept or decline
to authenticate the user. If authenticated, it will return RADIUS
attributes sufficient to enable proacd to negotiate the endpoint for
the incoming PPPoE session. It will then open the destination endpoint
and connect the incoming PPPoE client session to it.
All PPPoE clients requesting service on 'eth1' will be terminated in a
local pppd instance, the options to be passed to this pppd instance
will be read from the file '/etc/ppp/options.management'. IP addresses
and authentication parameters are configured in this external options
file.
SEE ALSO
proacd(8), proac_info(8), proac_trace(8), proac_manage(8),
ProL2TP 2.5.2 October 2023 proacd.conf(5)