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.


       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  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.4.1                     April 2023                    proacd.conf(5)