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.4                    January 2024                   proacd.conf(5)