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  indi-
           cated  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.


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 PROTO-
       COLS below).  An open brace begins the content of the destination defi-
       nition,  followed by protocol specific statements, and ended by a clos-
       ing brace.

           destination protocol { statement [ ... statement ] }


SOURCE PROTOCOLS
   PPPoE
       A PPPoE source definition uses the protocol keyword pppoe. The  follow-
       ing  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 defi-
       nition.

           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 ser-
       vice_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 estab-
       lish 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 ser-
       vice 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  follow-
       ing  statements  are used within an L2TP destination definition to con-
       trol 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 parame-
       ters of the tunnel which proacd will establish as the  destination  for
       this  route.   All  tunnel configuration must be done via prol2tpd pro-
       files.

           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. Sup-
       ported authentication types are "pap", "chap" and "eap". If not  speci-
       fied   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 authen-
       tication data is collected by proacd and sent to an L2TP peer in  addi-
       tional  L2TP  AVPs  when the L2TP session is established. If not speci-
       fied, proxy authentication is disabled.

           proxy_auth "yes|no"

       SERVER DEFINITION

       This defines one of the group of RADIUS servers to contact for destina-
       tion  endpoint  parameters.  The server definition begins with the key-
       word 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 desti-
       nation, 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 com-
       bination 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  cre-
           ate 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 tun-
           nel. This must be an IP address of an existing public interface  of
           the  LAC.  The default is to let the system's routing tables deter-
           mine 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 unau-
           thenticated 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  config-
           ured 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 Tun-
           nel-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 configura-
       tion 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 command-
           line 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  'pri-
       vate' 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  'pri-
       vate'.

       A  PPPoE client requesting the service name 'dynamic' will perform ini-
       tial 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 authentica-
       tion  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.1.0                     August 2020                   proacd.conf(5)