From 77b8fcd93b91f3741071210df2baccffc539f880 Mon Sep 17 00:00:00 2001 From: venaas Date: Mon, 6 Oct 2008 14:35:14 +0000 Subject: updated man pages, generated from docbook git-svn-id: https://svn.testnett.uninett.no/radsecproxy/branches/release-1.2@417 e88ac4ed-0b26-0410-9574-a7f39faa03bf --- radsecproxy.conf.5.xml | 658 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 658 insertions(+) create mode 100644 radsecproxy.conf.5.xml (limited to 'radsecproxy.conf.5.xml') diff --git a/radsecproxy.conf.5.xml b/radsecproxy.conf.5.xml new file mode 100644 index 0000000..bafd98f --- /dev/null +++ b/radsecproxy.conf.5.xml @@ -0,0 +1,658 @@ + + + + 2008-10-06 + + + + radsecproxy.conf + + 5 + radsecproxy 1.2 + + + + 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 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 3 which logs +errors, warnings and some informational messages. Note that the command line +option 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 + 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 if you specify port number. + + + + + 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. + + + + + listenTCP + + +This option is deprecated. listenTLS should be used +instead. In future versions listenTCP will be used for +RADIUS over TCP (not TLS encrypted). + + + + + listenAccountingUDP + + +This is similar to the listenUDP option, except that it is +used for specifying port and optionally the address to receive UDP Accounting +messages on. + + + + + 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). + + + + + sourceTLS + + +This can be used to specify source address and/or source port that the proxy +will use for TLS connections. Note that this option was previously called +sourceTCP. + + + + + sourceTCP + + +This option is deprecated. sourceTLS should be used +instead. In future versions sourceTCP will be used for +RADIUS over TCP (not TLS encrypted). + + + + + 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, Btls +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 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). + + +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, 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 allowed options in a client block are host, +type, secret, tls, +certificateNameCheck, +matchCertificateAttribute, rewrite, +rewriteIn, rewriteOut and +rewriteAttribute. We already discussed the +host option. The value of type must be +either udp or tls. 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. + + +For a TLS 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 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 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 the +first address is used. For TLS, the proxy will loop through the addresses until +it can connect to one of them. In the case of TLS, 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. + + +The allowed options in a server block are host, +port, type, secret, +tls, certificateNameCheck, +matchCertificateAttribute, rewrite, +rewriteIn, rewriteOut, +statusServer, retryCount and +retryInterval. + + +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, 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. + + + + 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 TLS 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. 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 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 clients to use one config, and all +TLS 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 +and CRLCheck. When doing RADIUS over TLS, 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. + + +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 + + + + -- cgit v1.1