Provided by: radsecproxy_1.3.1-1_i386 bug

NAME

       radsecproxy.conf - Radsec proxy configuration file

DESCRIPTION

       When  the  proxy  server  starts,  it will first check the command line
       arguments, and then read the configuration file.  Normally  radsecproxy
       will  read  the  configuration  file /etc/radsecproxy.conf. The command
       line -c option can be used to  instead  read  an  alternate  file  (see
       radsecproxy(1) for details).

       If the configuration file can not be found, the proxy will exit with an
       error message. Note that there is also an include facility so that  any
       configuration  file  may  include  other configuration files. The proxy
       will also exit on configuration errors.

CONFIGURATION SYNTAX

       When the configuration file is processed, whitespace (spaces and  tabs)
       are  generally  ignored. For each line, leading and trailing whitespace
       are ignored.  A line is ignored  if  it  is  empty,  only  consists  of
       whitespace,  or  if  the  first  non-whitespace  character  is a #. The
       configuration is generally case insensitive,  but  in  some  cases  the
       option values (see below) are not.

       There  are  two types of configuration structures than can be used. The
       first and simplest are lines of the format option value.  That  is,  an
       option  name,  see  below  for  a  list  of  valid options, followed by
       whitespace (at least one space or tab character), followed by a  value.
       Note  that  if  the  value  contains whitespace, then it must be quoted
       using "" or ’’. Any whitespace in front of  the  option  or  after  the
       value will be ignored.

       The  other  type  of  structure  is a block. A block spans at least two
       lines, and has the format:

              blocktype name {
                  option value
                  option value
                  ...
              }

       That is, some blocktype, see below for a list of  the  different  block
       types,  and  then  enclosed  in braces you have zero or more lines that
       each have the previously described option value format. Different block
       types have different rules for which options can be specified, they are
       listed below. The rules regarding white space, comments and quotes  are
       as above. Hence you may do things like:

              blocktype name {
              #    option value
                  option "value with space"
                  ...
              }

       Option  value  characters  can  also be written in hex. This is done by
       writing the character % followed by two hexadecimal digits. If a  %  is
       used  without two following hexadecimal digits, the % and the following
       characters are used as written. If you want to write a %  and  not  use
       this decoding, you may of course write % in hex; i.e., %25.

       There is one special option that can be used both as a basic option and
       inside all blocks. That is the option include where the value specifies
       files  to  be  included.  The value can be a single file, or it can use
       normal shell globbing to specify multiple files, e.g.:
              include /etc/radsecproxy.conf.d/*.conf

       The files are sorted alphabetically. Included files  are  read  in  the
       order  they  are  specified,  when reaching the end of a file, the next
       file is read. When reaching the end of  the  last  included  file,  the
       proxy  returns  to  read  the  next  line following the include option.
       Included files may again include other files.

BASIC OPTIONS

       The following basic options may be specified in the configuration file.
       Note  that  blocktypes  and  options inside blocks are discussed later.
       Note that none of these options are required, and indeed in many  cases
       they  are  not needed.  Note that you should specify each at most once.
       The behaviour with multiple occurences is undefined.

       logLevel
              This option specifies the debug level. It must be set to 1, 2, 3
              or  4,  where 1 logs only serious errors, and 4 logs everything.
              The  default  is  2  which  logs  errors,  warnings  and  a  few
              informational  messages.  Note  that  the command line option -d
              overrides this.

       logDestination
              This specifies where the log messages should go. By default  the
              messages  go  to  syslog  with  facility  LOG_DAEMON. Using this
              option you can specify  another  syslog  facility,  or  you  may
              specify  that  logging should be to a particular file, not using
              syslog. The value must be either a file or syslog URL. The  file
              URL  is the standard one, specifying a local file that should be
              used. For syslog, you must use the syntax:  x-syslog:///FACILITY
              where  FACILITY  must  be one of LOG_DAEMON, LOG_MAIL, LOG_USER,
              LOG_LOCAL0,  LOG_LOCAL1,  LOG_LOCAL2,  LOG_LOCAL3,   LOG_LOCAL4,
              LOG_LOCAL5,  LOG_LOCAL6 or LOG_LOCAL7. You may omit the facility
              from the URL to specify logging to  the  default  facility,  but
              this   is  not  very  useful  since  this  is  the  default  log
              destination. Note that this option is ignored if -f is specified
              on the command line.

       listenUDP
              Normally  the  proxy will listen to the standard RADIUS UDP port
              1812 if configured to handle UDP clients.  On  most  systems  it
              will do this for all of the system’s IP addresses (both IPv4 and
              IPv6). On some systems however, it may respond to only  IPv4  or
              only  IPv6.  To specify an alternate port you may use a value of
              the form *:port where port is any valid port number. If you also
              want   to   specify   a   specific   address  you  can  do  e.g.
              192.168.1.1:1812 or [2001:db8::1]:1812. The port may be  omitted
              if  you  want  the  default  one (like in these examples). These
              examples are equivalent to  192.168.1.1  and  2001:db8::1.  Note
              that you must use brackets around the IPv6 address.  This option
              may be specified multiple times to listen to multiple  addresses
              and/or ports.

       listenTCP
              This  option  is similar to the listenUDP option, except that it
              is used for receiving connections from TCP clients. The  default
              port number is 1812.

       listenTLS
              This  is similar to the listenUDP option, except that it is used
              for receiving connections from TLS  clients.  The  default  port
              number  is  2083.  Note  that  this option was previously called
              listenTCP.

       listenDTLS
              This is similar to the listenUDP option, except that it is  used
              for  receiving  connections  from DTLS clients. The default port
              number is 2083.

       sourceUDP
              This can be used to specify source address  and/or  source  port
              that  the  proxy  will use for sending UDP client messages (e.g.
              Access Request).

       sourceTCP
              This can be used to specify source address  and/or  source  port
              that the proxy will use for TCP connections.

       sourceTLS
              This  can  be  used to specify source address and/or source port
              that the proxy will use for TLS connections.

       sourceDTLS
              This can be used to specify source address  and/or  source  port
              that the proxy will use for DTLS connections.

       TTLAttribute
              This  can  be  used  to  change  the default TTL attribute. Only
              change this if you know what you are doing. The syntax is either
              a  numerical  value denoting the TTL attribute, or two numerical
              values separated by column specifying a vendor  attribute,  i.e.
              vendorid:attribute.

       addTTL If  a  TTL  attribute  is  present, the proxy will decrement the
              value and discard the message if zero. Normally the  proxy  does
              nothing  if  no  TTL attribute is present. If you use the addTTL
              option with a value 1-255, the  proxy  will  when  forwarding  a
              message with no TTL attribute, add one with the specified value.
              Note that this option can also be specified for a client/server.
              It  will then override this setting when forwarding a message to
              that client/server.

       loopPrevention
              This can be set to on or off with off being  the  default.  When
              this  is enabled, a request will never be sent to a server named
              the same as the client it was received from. I.e., the names  of
              the  client  block and the server block are compared.  Note that
              this only gives limited protection against loops.

       include
              This is not a normal configuration option; it can  be  specified
              multiple  times.   It  can  both  be  used as a basic option and
              inside blocks. For the full description, see  the  configuration
              syntax section above.

BLOCKS

       There are five types of blocks, they are client, server, realm, tls and
       rewrite. At least one instance of each of client and realm is required.
       This is necessary for the proxy to do anything useful, and it will exit
       if not. The tls block is required if at least one  TLS/DTLS  client  or
       server  is  configured. Note that there can be multiple blocks for each
       type.  For each type, the block names should be unique.  The  behaviour
       with  multiple  occurences  of the same name for the same block type is
       undefined. Also note that some block  option  values  may  reference  a
       block by name, in which case the block name must be previously defined.
       Hence the order of the blocks may be significant.

CLIENT BLOCK

       The client block is used to configure a client. That is, tell the proxy
       about a client, and what parameters should be used for that client. The
       name of the client block must (with one exception, see below) be either
       the  IP  address  (IPv4  or  IPv6) of the client, an IP prefix (IPv4 or
       IPv6) of the form IpAddress/PrefixLength, or a domain name (FQDN). Note
       that literal IPv6 addresses must be enclosed in brackets.

       If  a  domain name is specified, then this will be resolved immediately
       to all the addresses associated with the name, and the proxy  will  not
       care about any possible DNS changes that might occur later. Hence there
       is no dependency on DNS after startup.

       When some client later sends a request to the  proxy,  the  proxy  will
       look  at the IP address the request comes from, and then go through all
       the addresses of each of the configured clients (in the order they  are
       defined), to determine which (if any) of the clients this is.

       In  the case of TLS/DTLS, the name of the client must match the FQDN or
       IP address in the client certificate. Note that this  is  not  required
       when the client name is an IP prefix.

       Alternatively  one  may  use  the host option inside a client block. In
       that case, the value of the host option is used  as  above,  while  the
       name  of  the  block  is  only  used  as  a  descriptive  name  for the
       administrator. The host option may be used multiple times, and can be a
       mix of addresses, FQDNs and prefixes.

       The  allowed  options  in  a  client block are host, type, secret, tls,
       certificateNameCheck,   matchCertificateAttribute,   duplicateInterval,
       addTTL,   rewrite,  rewriteIn,  rewriteOut  and  rewriteAttribute.   We
       already discussed the host option. The value of type  must  be  one  of
       udp,  tcp,  tls  or  dtls. The value of secret is the shared RADIUS key
       used with this client. If the secret  contains  whitespace,  the  value
       must be quoted. This option is optional for TLS/DTLS.

       For  a TLS/DTLS client you may also specify the tls option.  The option
       value must be the name of a  previously  defined  TLS  block.  If  this
       option is not specified, the TLS block with the name defaultClient will
       be used if defined. If not defined, it will try to use  the  TLS  block
       named  default.  If the specified TLS block name does not exist, or the
       option is not specified and none of the defaults exist, the proxy  will
       exit with an error.

       For  a  TLS/DTLS  client, the option certificateNameCheck can be set to
       off, to disable the default behaviour of matching CN or  SubjectAltName
       against the specified hostname or IP address.

       Additional  validation  of certificate attributes can be done by use of
       the matchCertificateAttribute option. Currently one can  only  do  some
       matching  of  CN and SubjectAltName. For regexp matching on CN, one can
       use the value CN:/regexp/. For SubjectAltName one can  only  do  regexp
       matching  of the URI, this is specified as SubjectAltName:URI:/regexp/.
       Note that currently this option can only be specified once in a  client
       block.

       The  duplicateInterval  option  can  be  used  to  specify for how many
       seconds duplicate checking should be done. If a proxy  receives  a  new
       request  within  a few seconds of a previous one, it may be treated the
       same if from the same client, with  the  same  authenticator  etc.  The
       proxy  will  then ignore the new request (if it is still processing the
       previous one), or returned a copy of the previous reply.

       The addTTL option is similar to the addTTL option  used  in  the  basic
       config.  See  that for details. Any value configured here overrides the
       basic one when sending messages to this client.

       The rewrite option is deprecated. Use rewriteIn instead.

       The rewriteIn option can be used to  refer  to  a  rewrite  block  that
       specifies  certain  rewrite  operations  that  should  be  performed on
       incoming messages from the client. The rewriting is done  before  other
       processing.   For  details, see the rewrite block text below. Similarly
       to tls discussed above, if this option is not used, there is a fallback
       to  using  the  rewrite  block named defaultClient if it exists; and if
       not, a fallback to a block named default.

       The rewriteOut option is used in the same way as rewriteIn, except that
       it  specifies  rewrite  operations that should be performed on outgoing
       messages to the client. The rewriting is done after  other  processing.
       Also, there is no rewrite fallback if this option is not used.

       The rewriteAttribute option currently makes it possible to specify that
       the User-Name attribute in a client request shall be rewritten  in  the
       request  sent  by the proxy. The User-Name attribute is written back to
       the original value if a matching response is later  sent  back  to  the
       client.     The     value     must     be    of    the    form    User-
       Name:/regexpmatch/replacement/. Example usage:
              rewriteAttribute User-Name:/^(.*)@local$/$1@example.com/

SERVER BLOCK

       The server block is used to configure a server. That is, tell the proxy
       about  a  server, and what parameters should be used when communicating
       with that server.   The  name  of  the  server  block  must  (with  one
       exception,  see  below)  be either the IP address (IPv4 or IPv6) of the
       server, or a domain name (FQDN). If a domain name  is  specified,  then
       this  will be resolved immediately to all the addresses associated with
       the name, and the proxy will not care about any  possible  DNS  changes
       that  might  occur  later.  Hence  there  is no dependency on DNS after
       startup. If the domain name resolves to multiple  addresses,  then  for
       UDP/DTLS  the  first  address is used. For TCP/TLS, the proxy will loop
       through the addresses until it can connect to one of them. In the  case
       of  TLS/DTLS,  the name of the server must match the FQDN or IP address
       in the server certificate.

       Alternatively one may use the host option inside  a  server  block.  In
       that  case,  the  value  of the host option is used as above, while the
       name of  the  block  is  only  used  as  a  descriptive  name  for  the
       administrator.  Note  that multiple host options may be used. This will
       then be treated as multiple names/addresses for the same  server.  When
       initiating  a  TCP/TLS  connection,  all  addresses of all names may be
       attempted, but there is no failover between the different host  values.
       For failover one must use separate server blocks.

       Note  that the name of the block, or values of host options may include
       a port number (separated with a column). This  port  number  will  then
       override  the  default  port or a port option in the server block. Also
       note that literal IPv6 addresses must be enclosed in brackets.

       The allowed options in a server block are  host,  port,  type,  secret,
       tls,  certificateNameCheck, matchCertificateAttribute, addTTL, rewrite,
       rewriteIn,  rewriteOut,  statusServer,  retryCount,  retryInterval  and
       dynamicLookupCommand.

       We  already  discussed  the  host option. The port option allows you to
       specify which port number the server uses. The usage of  type,  secret,
       tls,  certificateNameCheck, matchCertificateAttribute, addTTL, rewrite,
       rewriteIn and rewriteOut are just as specified  for  the  client  block
       above,  except  that  defaultServer  (and  not  defaultClient)  is  the
       fallback for the tls, rewrite and rewriteIn options.

       statusServer can be  specified  to  enable  the  use  of  status-server
       messages  for  this  server.  The  value  must be either on or off. The
       default when not specified, is off. If  statusserver  is  enabled,  the
       proxy  will  during idle periods send regular status-server messages to
       the server to verify that it is alive. This should only be  enabled  if
       the server supports it.

       The  options  retryCount  and  retryInterval can be used to specify how
       many times the proxy should retry sending a request  and  how  long  it
       should  wait  between  each  retry.  The  defaults are 2 retries and an
       interval of 5s.

       The option dynamicLookupCommand can be used to specify a  command  that
       should  be executed to dynamically configure and use a server.  The use
       of this feature will be documented separately/later.

REALM BLOCK

       When the proxy receives an Access-Request it needs  to  figure  out  to
       which  server  it  should  be forwarded. This is done by looking at the
       Username attribute in the request, and matching that against the  names
       of  the  defined realm blocks.  The proxy will match against the blocks
       in the order they are specified, using the first match if  any.  If  no
       realm  matches,  the  proxy  will simply ignore the request. Each realm
       block specifies what the server should do when  a  match  is  found.  A
       realm  block  may  contain  none,  one  or multiple server options, and
       similarly accountingServer options. There  are  also  replyMessage  and
       accountingResponse options. We will discuss these later.

   REALM BLOCK NAMES AND MATCHING
       In  the  general  case  the  proxy  will  look  for a @ in the username
       attribute, and try to do an exact case insensitive match  between  what
       comes  after  the  @  and  the name of the realm block. So if you get a
       request with the attribute value anonymous@example.com, the proxy  will
       go through the realm names in the order they are specified, looking for
       a realm block named example.com.

       There are two exceptions to this, one is the realm name *  which  means
       match everything. Hence if you have a realm block named *, then it will
       always match. This should then be the last realm block  defined,  since
       any blocks after this would never be checked. This is useful for having
       a default.

       The other exception is regular expression matching. If the  realm  name
       starts  with  a /, the name is treated as an regular expression. A case
       insensitive regexp match will then be done using  this  regexp  on  the
       value  of the entire Username attribute. Optionally you may also have a
       trailing / after the regexp. So as an  example,  if  you  want  to  use
       regexp  matching  the  domain  example.com you could have a realm block
       named  /@example\\.com$.   Optinally   this   can   also   be   written
       /@example\\.com$/.  If you want to match all domains under the .com top
       domain, you could do /@.*\\.com$. Note that since the matching is  done
       on   the   entire   attribute  value,  you  can  also  use  rules  like
       /^[a-k].*@example\\.com$/ to get some of the users in  this  domain  to
       use  one  server,  while  other users could be matched by another realm
       block and use another server.

   REALM BLOCK OPTIONS
       A realm block may contain none, one  or  multiple  server  options.  If
       defined,  the  values  of  the  server  options  must  be  the names of
       previously defined server blocks. Normally requests will  be  forwarded
       to  the  first  server  option  defined.  If  there are multiple server
       options, the proxy will do fail-over and use the second server  if  the
       first is down. If the two first are down, it will try the third etc. If
       say the first server comes back up, it will go back to using that  one.
       Currently  detection of servers being up or down is based on the use of
       StatusServer (if enabled), and that TCP/TLS/DTLS connections are up.

       A realm block may also contain none, one or  multiple  accountingServer
       options. This is used exactly like the server option, except that it is
       used for specifying where to send  matching  accounting  requests.  The
       values  must  be  the  names  of previously defined server blocks. When
       multiple accounting servers are defined, there is a failover  mechanism
       similar to the one for the server option.

       If  there  is  no  server  option,  the  proxy  will if replyMessage is
       specified, reply back to the client with an Access Reject message.  The
       message  contains  a replyMessage attribute with the value as specified
       by the replyMessage option. Note that this is different from having  no
       match since then the request is simply ignored. You may wonder why this
       is useful. One example is if you handle say all domains under say  .bv.
       Then  you  may  have  several  realm  blocks  matching the domains that
       exists, while for other domains under .bv you want to send a reject. At
       the same time you might want to send all other requests to some default
       server. After the realms for the subdomains, you would  then  have  two
       realm  definitions.  One  with  the  name  /@.*\\.bv$  with no servers,
       followed by one with the name * with the default server  defined.  This
       may also be useful for blocking particular usernames.

       If  there  is  no  accountingServer  option, the proxy will normally do
       nothing, ignoring accounting  requests.  There  is  however  an  option
       called  accountingResponse.  If  this  is set to on, the proxy will log
       some of the accounting  information  and  send  an  Accounting-Response
       back. This is useful if you do not care much about accounting, but want
       to stop clients from retransmitting  accounting  requests.  By  default
       this option is set to off.

TLS BLOCK

       The TLS block specifies TLS configuration options and you need at least
       one of these  if  you  have  clients  or  servers  using  TLS/DTLS.  As
       discussed  in  the  client  and  server block descriptions, a client or
       server block may reference a particular TLS block by  name.  There  are
       also  however  the  special  TLS block names default, defaultClient and
       defaultServer which are used as defaults if the client or server  block
       does  not  reference  a  TLS  block. Also note that a TLS block must be
       defined before the client or server block that would  use  it.  If  you
       want  the  same TLS configuration for all TLS/DTLS clients and servers,
       you need just a single tls block named  default,  and  the  client  and
       servers  need  not refer to it. If you want all TLS/DTLS clients to use
       one config, and all TLS/DTLS servers to use another, then you would  be
       fine   only   defining   two   TLS   blocks   named  defaultClient  and
       defaultServer. If you want different clients (or different servers)  to
       have  different  TLS  parameters, then you may need to create other TLS
       blocks with other names, and reference those from the client or  server
       definitions.  Note that you could also have say a client block refer to
       a default, even defaultServer if you really want to.

       The   available    TLS    block    options    are    CACertificateFile,
       CACertificatePath,         certificateFile,         certificateKeyFile,
       certificateKeyPassword,  cacheExpiry,  CRLCheck  and  policyOID.   When
       doing  RADIUS  over  TLS/DTLS,  both  the client and the server present
       certificates, and they are both verified by the peer.  Hence  you  must
       always  specify certificateFile and certificateKeyFile options, as well
       as certificateKeyPassword if  a  password  is  needed  to  decrypt  the
       private key. Note that CACertificateFile may be a certificate chain. In
       order to verify certificates, or send a  chain  of  certificates  to  a
       peer,   you   also   always   need   to  specify  CACertificateFile  or
       CACertificatePath.  Note that you may specify both, in which  case  the
       certificates  in  CACertificateFile  are checked first. By default CRLs
       are not checked. This can be changed by setting CRLCheck to on. One can
       require  peer  certificates to adhere to certain policies by specifying
       one or multiple policyOIDs using one or multiple policyOID options.

       CA certificates and CRLs are normally cached permanently. That is, once
       a  CA or CRL has been read, the proxy will never attempt to re-read it.
       CRLs may change relatively often and the proxy  should  ideally  always
       use  the  latest  CRLs.  Rather  than restarting the proxy, there is an
       option cacheExpiry that specifies how  many  seconds  the  CA  and  CRL
       information  should  be  cached. Reasonable values might be say 3600 (1
       hour) or 86400 (24 hours), depending on how frequently CRLs are updated
       and how critical it is to be up to date. This option may be set to zero
       to disable caching.

REWRITE BLOCK

       The rewrite block specifies rules that may rewrite RADIUS messages.  It
       can be used to add, remove and modify specific attributes from messages
       received from and sent to clients and  servers.  As  discussed  in  the
       client  and  server  block  descriptions,  a client or server block may
       reference a particular rewrite block by name. There  are  however  also
       the   special   rewrite   block   names   default,   defaultClient  and
       defaultServer which are used as defaults if the client or server  block
       does  not  reference  a  block.  Also note that a rewrite block must be
       defined before the client or server block that would  use  it.  If  you
       want the same rewrite rules for input from all clients and servers, you
       need just a single rewrite block named  default,  and  the  client  and
       servers  need  not  refer  to  it.  If  you want all clients to use one
       config, and all servers to use another, then you  would  be  fine  only
       defining two rewrite blocks named defaultClient and defaultServer. Note
       that these defaults are only used for rewrite on input. No rewriting is
       done  on output unless explicitly specifed using the rewriteOut option.

       The available rewrite block options are addAttribute,  removeAttribute,
       removeVendorAttribute  and  modifyAttribute.  They can all be specified
       none, one or multiple times.

       addAttribute is used to add attributes to a message. The  option  value
       must  be  of  the  form  attribute:value where attribute is a numerical
       value specifying the attribute.

       The removeAttribute option is used to specify an attribute that  should
       be removed from received messages. The option value must be a numerical
       value  specifying  which  attribute  is  to  be  removed.    Similarly,
       removeVendorAttribute  is used to specify a vendor attribute that is to
       be removed. The value  can  be  a  numerical  value  for  removing  all
       attributes  from  a  given  vendor, or of the form vendor:subattribute,
       where vendor and subattribute are  numerical  values,  for  removing  a
       specific subattribute for a specific vendor.

       modifyAttribute  is  used  to  specify  modification of attributes. The
       value must be of  the  form  attribute:/regexpmatch/replacement/  where
       attribute is a numerical attribute type, regexpmatch is regexp matching
       rule and replacement specifies how  to  replace  the  matching  regexp.
       Example usage:
              modifyAttribute 1:/^(.*)@local$/$1@example.com/

SEE ALSO

       radsecproxy(1),             RadSec            internet            draft
       〈http://tools.ietf.org/html/draft-ietf-radext-radsec