diff options
Diffstat (limited to 'radsecproxy.conf.5.xml')
| -rw-r--r-- | radsecproxy.conf.5.xml | 1148 |
1 files changed, 625 insertions, 523 deletions
diff --git a/radsecproxy.conf.5.xml b/radsecproxy.conf.5.xml index 4024bde..406f2bf 100644 --- a/radsecproxy.conf.5.xml +++ b/radsecproxy.conf.5.xml @@ -2,136 +2,138 @@ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> <refentry> <refentryinfo> - <date>2009-03-12</date> + <date>2011-04-04</date> </refentryinfo> <refmeta> <refentrytitle> <application>radsecproxy.conf</application> </refentrytitle> <manvolnum>5</manvolnum> - <refmiscinfo>radsecproxy devel 2009-03-12</refmiscinfo> + <refmiscinfo>radsecproxy 1.5-dev</refmiscinfo> </refmeta> <refnamediv> <refname> <application>radsecproxy.conf</application> </refname> - <refpurpose> -Radsec proxy configuration file - </refpurpose> + <refpurpose>Radsec proxy configuration file</refpurpose> </refnamediv> <refsect1> <title>Description</title> <para> -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 <filename>/etc/radsecproxy.conf</filename>. The command -line <option>-c</option> option can be used to instead read an alternate -file (see + 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 + <filename>/etc/radsecproxy.conf</filename>. The command line + <option>-c</option> option can be used to instead read an + alternate file (see <citerefentry> - <refentrytitle>radsecproxy</refentrytitle> - <manvolnum>1</manvolnum> + <refentrytitle>radsecproxy</refentrytitle><manvolnum>1</manvolnum> </citerefentry> -for details). + for details). </para> <para> - 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. + 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. </para> </refsect1> <refsect1> <title>Configuration Syntax</title> <para> -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 <literal>#</literal>. The configuration is -generally case insensitive, but in some cases the option values (see below) -are not. - </para> - <para> -There are two types of configuration structures than can be used. The first -and simplest are lines on the format <emphasis>option value</emphasis>. 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 -<literal>""</literal> or <literal>''</literal>. Any whitespace -in front of the option or after the value will be ignored. - </para> - <para> -The other type of structure is a block. A block spans at least two lines, and -has the format: - <blockquote> -<literallayout> + 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 <literal>#</literal>. The configuration is generally case + insensitive, but in some cases the option values (see below) are + not. + </para> + <para> + There are two types of configuration structures than can be + used. The first and simplest are lines on the format + <emphasis>option value</emphasis>. 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 <literal>""</literal> or <literal>''</literal>. Any + whitespace in front of the option or after the value will be + ignored. + </para> + <para> + The other type of structure is a block. A block spans at least + two lines, and has the format: + <blockquote><literallayout> blocktype name { option value option value ... } -</literallayout> - </blockquote> -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 <emphasis>option value</emphasis> 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: - <blockquote> - <para> -<literallayout> + </literallayout></blockquote> + 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 <emphasis>option + value</emphasis> 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: + <blockquote><literallayout> blocktype name { # option value option "value with space" ... } -</literallayout> - </para> - </blockquote> + </literallayout></blockquote> </para> <para> -Option value characters can also be written in hex. This is done by writing the -character <literal>%</literal> followed by two hexadecimal digits. If a -<literal>%</literal> is used without two following hexadecimal digits, the -<literal>%</literal> and the following characters are used as written. If you -want to write a <literal>%</literal> and not use this decoding, you may of -course write <literal>%</literal> in hex; i.e., <literal>%25</literal>. + Option value characters can also be written in hex. This is done + by writing the character <literal>%</literal> followed by two + hexadecimal digits. If a <literal>%</literal> is used without + two following hexadecimal digits, the <literal>%</literal> and + the following characters are used as written. If you want to + write a <literal>%</literal> and not use this decoding, you may + of course write <literal>%</literal> in hex; i.e., + <literal>%25</literal>. </para> <para> -There is one special option that can be used both as a basic option and inside -all blocks. That is the option <literal>include</literal> 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.: + There is one special option that can be used both as a basic + option and inside all blocks. That is the option + <literal>include</literal> 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.: <blockquote> <para> -include /etc/radsecproxy.conf.d/*.conf + include /etc/radsecproxy.conf.d/*.conf </para> </blockquote> -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 <literal>include</literal> option. Included files may again -include other files. + 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 <literal>include</literal> option. Included files may again + include other files. </para> </refsect1> <refsect1> <title>Basic Options</title> <para> -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. + 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. </para> <variablelist> <varlistentry> <term><literal>logLevel</literal></term> <listitem> <para> -This option specifies the debug level. It must be set to 1, 2, 3, 4 or 5, where -1 logs only serious errors, and 5 logs everything. The default is 2 which logs -errors, warnings and a few informational messages. Note that the command line -option <option>-d</option> overrides this. + This option specifies the debug level. It must be set to + 1, 2, 3, 4 or 5, where 1 logs only serious errors, and 5 + logs everything. The default is 2 which logs errors, + warnings and a few informational messages. Note that the + command line option <option>-d</option> overrides this. </para> </listitem> </varlistentry> @@ -139,22 +141,30 @@ option <option>-d</option> overrides this. <term><literal>logDestination</literal></term> <listitem> <para> -This specifies where the log messages should go. By default the messages go to -syslog with facility <literal>LOG_DAEMON</literal>. 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: -<literal>x-syslog:///FACILITY</literal> where <literal>FACILITY</literal> must -be one of <literal>LOG_DAEMON</literal>, <literal>LOG_MAIL</literal>, -<literal>LOG_USER</literal>, <literal>LOG_LOCAL0</literal>, -<literal>LOG_LOCAL1</literal>, <literal>LOG_LOCAL2</literal>, -<literal>LOG_LOCAL3</literal>, <literal>LOG_LOCAL4</literal>, -<literal>LOG_LOCAL5</literal>, <literal>LOG_LOCAL6</literal> or -<literal>LOG_LOCAL7</literal>. 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 -<option>-f</option> is specified on the command line. + This specifies where the log messages should go. By + default the messages go to syslog with facility + <literal>LOG_DAEMON</literal>. 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: + <literal>x-syslog:///FACILITY</literal> where + <literal>FACILITY</literal> must be one of + <literal>LOG_DAEMON</literal>, + <literal>LOG_MAIL</literal>, <literal>LOG_USER</literal>, + <literal>LOG_LOCAL0</literal>, + <literal>LOG_LOCAL1</literal>, + <literal>LOG_LOCAL2</literal>, + <literal>LOG_LOCAL3</literal>, + <literal>LOG_LOCAL4</literal>, + <literal>LOG_LOCAL5</literal>, + <literal>LOG_LOCAL6</literal> or + <literal>LOG_LOCAL7</literal>. 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 + <option>-f</option> is specified on the command line. </para> </listitem> </varlistentry> @@ -162,19 +172,24 @@ this is the default log destination. Note that this option is ignored if <term><literal>listenUDP</literal></term> <listitem> <para> -Normally the proxy will listen to the standard RADIUS UDP port -<literal>1812</literal> 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 on the form <literal>*:port</literal> where -port is any valid port number. If you also want to specify a specific address -you can do e.g. <literal>192.168.1.1:1812</literal> or -<literal>[2001:db8::1]:1812</literal>. The port may be omitted if you want the -default one (like in these examples). These examples are equivalent to -<literal>192.168.1.1</literal> and <literal>2001:db8::1</literal>. 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. + Normally the proxy will listen to the standard RADIUS UDP + port <literal>1812</literal> 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 on + the form <literal>*:port</literal> where port is any valid + port number. If you also want to specify a specific + address you can do + e.g. <literal>192.168.1.1:1812</literal> or + <literal>[2001:db8::1]:1812</literal>. The port may be + omitted if you want the default one (like in these + examples). These examples are equivalent to + <literal>192.168.1.1</literal> and + <literal>2001:db8::1</literal>. 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. </para> </listitem> </varlistentry> @@ -182,9 +197,10 @@ and/or ports. <term><literal>listenTCP</literal></term> <listitem> <para> -This option is similar to the <literal>listenUDP</literal> option, except -that it is used for receiving connections from TCP clients. The default port -number is <literal>1812</literal>. + This option is similar to the <literal>listenUDP</literal> + option, except that it is used for receiving connections + from TCP clients. The default port number is + <literal>1812</literal>. </para> </listitem> </varlistentry> @@ -192,10 +208,11 @@ number is <literal>1812</literal>. <term><literal>listenTLS</literal></term> <listitem> <para> -This is similar to the <literal>listenUDP</literal> option, except that it is -used for receiving connections from TLS clients. The default port number is -<literal>2083</literal>. Note that this option was previously called -<literal>listenTCP</literal>. + This is similar to the <literal>listenUDP</literal> + option, except that it is used for receiving connections + from TLS clients. The default port number is + <literal>2083</literal>. Note that this option was + previously called <literal>listenTCP</literal>. </para> </listitem> </varlistentry> @@ -203,9 +220,10 @@ used for receiving connections from TLS clients. The default port number is <term><literal>listenDTLS</literal></term> <listitem> <para> -This is similar to the <literal>listenUDP</literal> option, except that it is -used for receiving connections from DTLS clients. The default port number is -<literal>2083</literal>. + This is similar to the <literal>listenUDP</literal> + option, except that it is used for receiving connections + from DTLS clients. The default port number is + <literal>2083</literal>. </para> </listitem> </varlistentry> @@ -213,8 +231,9 @@ used for receiving connections from DTLS clients. The default port number is <term><literal>sourceUDP</literal></term> <listitem> <para> -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). + 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). </para> </listitem> </varlistentry> @@ -222,8 +241,8 @@ will use for sending UDP client messages (e.g. Access Request). <term><literal>sourceTCP</literal></term> <listitem> <para> -This can be used to specify source address and/or source port that the proxy -will use for TCP connections. + This can be used to specify source address and/or source + port that the proxy will use for TCP connections. </para> </listitem> </varlistentry> @@ -231,8 +250,8 @@ will use for TCP connections. <term><literal>sourceTLS</literal></term> <listitem> <para> -This can be used to specify source address and/or source port that the proxy -will use for TLS connections. + This can be used to specify source address and/or source + port that the proxy will use for TLS connections. </para> </listitem> </varlistentry> @@ -240,8 +259,8 @@ will use for TLS connections. <term><literal>sourceDTLS</literal></term> <listitem> <para> -This can be used to specify source address and/or source port that the proxy -will use for DTLS connections. + This can be used to specify source address and/or source + port that the proxy will use for DTLS connections. </para> </listitem> </varlistentry> @@ -249,10 +268,12 @@ will use for DTLS connections. <term><literal>TTLAttribute</literal></term> <listitem> <para> -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. <literal>vendorid:attribute</literal>. + 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. <literal>vendorid:attribute</literal>. </para> </listitem> </varlistentry> @@ -260,13 +281,15 @@ specifying a vendor attribute, i.e. <literal>vendorid:attribute</literal>. <term><literal>addTTL</literal></term> <listitem> <para> -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. + 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. </para> </listitem> </varlistentry> @@ -274,13 +297,15 @@ a message to that client/server. <term><literal>loopPrevention</literal></term> <listitem> <para> -This can be set to <literal>on</literal> or <literal>off</literal> with -<literal>off</literal> 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. -It can be used as a basic option and inside server blocks where it overrides -the basic setting. + This can be set to <literal>on</literal> or + <literal>off</literal> with <literal>off</literal> 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. It can be used as a + basic option and inside server blocks where it overrides + the basic setting. </para> </listitem> </varlistentry> @@ -288,9 +313,10 @@ the basic setting. <term><literal>include</literal></term> <listitem> <para> -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. + 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. </para> </listitem> </varlistentry> @@ -299,137 +325,158 @@ description, see the configuration syntax section above. <refsect1> <title>Blocks</title> <para> -There are five types of blocks, they are <literal>client</literal>, -<literal>server</literal>, <literal>realm</literal>, <literal>tls</literal> -and <literal>rewrite</literal>. At least one instance of each of -<literal>client</literal> and <literal>realm</literal> is required. This is -necessary for the proxy to do anything useful, and it will exit if not. The -<literal>tls</literal> 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. + There are five types of blocks, they are + <literal>client</literal>, <literal>server</literal>, + <literal>realm</literal>, <literal>tls</literal> and + <literal>rewrite</literal>. At least one instance of each of + <literal>client</literal> and <literal>realm</literal> is + required. This is necessary for the proxy to do anything useful, + and it will exit if not. The <literal>tls</literal> 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. </para> </refsect1> <refsect1> <title>Client Block</title> <para> -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) on the form -IpAddress/PrefixLength, or a domain name (FQDN). Note that literal IPv6 -addresses must be enclosed in brackets. - </para> - <para> -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. - </para> - <para> -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. - </para> - <para> -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. - </para> - <para> -Alternatively one may use the <literal>host</literal> option inside a client -block. In that case, the value of the <literal>host</literal> 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. - </para> - <para> -The allowed options in a client block are <literal>host</literal>, -<literal>type</literal>, <literal>secret</literal>, <literal>tls</literal>, -<literal>certificateNameCheck</literal>, -<literal>matchCertificateAttribute</literal>, -<literal>duplicateInterval</literal>, <literal>addTTL</literal>, -<literal>rewrite</literal>, <literal>rewriteIn</literal>, -<literal>rewriteOut</literal> and <literal>rewriteAttribute</literal>. -We already discussed the -<literal>host</literal> option. The value of <literal>type</literal> must be -one of <literal>udp</literal>, <literal>tcp</literal>, <literal>tls</literal> -or <literal>dtls</literal>. The value of <literal>secret</literal> 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. - </para> - <para> -For a TLS/DTLS client you may also specify the <literal>tls</literal> 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 -<literal>defaultClient</literal> will be used if defined. If not defined, it -will try to use the TLS block named <literal>default</literal>. 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. - </para> - <para> -For a TLS/DTLS client, the option <literal>certificateNameCheck</literal> -can be set -to <literal>off</literal>, to disable the default behaviour of matching CN or -SubjectAltName against the specified hostname or IP address. - </para> - <para> -Additional validation of certificate attributes can be done by use of the -<literal>matchCertificateAttribute</literal> option. Currently one can only do -some matching of CN and SubjectAltName. For regexp matching on CN, one can use -the value <literal>CN:/regexp/</literal>. For SubjectAltName one can only do -regexp matching of the URI, this is specified as -<literal>SubjectAltName:URI:/regexp/</literal>. Note that currently this option -can only be specified once in a client block. - </para> - <para> -The <literal>duplicateInterval</literal> 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. - </para> - <para> -The <literal>addTTL</literal> option is similar to the -<literal>addTTL</literal> option used in the basic config. See that for -details. Any value configured here overrides the basic one when sending -messages to this client. - </para> - <para> -The <literal>rewrite</literal> option is deprecated. Use -<literal>rewriteIn</literal> instead. - </para> - <para> -The <literal>rewriteIn</literal> 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 -<literal>tls</literal> discussed above, if this option is not used, there is a -fallback to using the <literal>rewrite</literal> block named -<literal>defaultClient</literal> if it exists; and if not, a fallback to a -block named <literal>default</literal>. - </para> - <para> -The <literal>rewriteOut</literal> option is used in the same way as -<literal>rewriteIn</literal>, 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. - </para> - <para> -The <literal>rewriteAttribute</literal> 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 on the form User-Name:/regexpmatch/replacement/. Example usage: + 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) on the form + IpAddress/PrefixLength, or a domain name (FQDN). Note that + literal IPv6 addresses must be enclosed in brackets. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + Alternatively one may use the <literal>host</literal> option + inside a client block. In that case, the value of the + <literal>host</literal> 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. + </para> + <para> + The allowed options in a client block are + <literal>host</literal>, <literal>type</literal>, + <literal>secret</literal>, <literal>tls</literal>, + <literal>certificateNameCheck</literal>, + <literal>matchCertificateAttribute</literal>, + <literal>duplicateInterval</literal>, <literal>addTTL</literal>, + <literal>rewrite</literal>, <literal>rewriteIn</literal>, + <literal>rewriteOut</literal> and + <literal>rewriteAttribute</literal>. + + We already discussed the <literal>host</literal> option. The + value of <literal>type</literal> must be one of + <literal>udp</literal>, <literal>tcp</literal>, + <literal>tls</literal> or <literal>dtls</literal>. The value of + <literal>secret</literal> 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. + </para> + <para> + For a TLS/DTLS client you may also specify the + <literal>tls</literal> 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 + <literal>defaultClient</literal> will be used if defined. If not + defined, it will try to use the TLS block named + <literal>default</literal>. 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. + </para> + <para> + For a TLS/DTLS client, the option + <literal>certificateNameCheck</literal> can be set to + <literal>off</literal>, to disable the default behaviour of + matching CN or SubjectAltName against the specified hostname or + IP address. + </para> + <para> + Additional validation of certificate attributes can be done by + use of the <literal>matchCertificateAttribute</literal> + option. Currently one can only do some matching of CN and + SubjectAltName. For regexp matching on CN, one can use the value + <literal>CN:/regexp/</literal>. For SubjectAltName one can only + do regexp matching of the URI, this is specified as + <literal>SubjectAltName:URI:/regexp/</literal>. Note that + currently this option can only be specified once in a client + block. + </para> + <para> + The <literal>duplicateInterval</literal> 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. + </para> + <para> + The <literal>addTTL</literal> option is similar to the + <literal>addTTL</literal> option used in the basic config. See + that for details. Any value configured here overrides the basic + one when sending messages to this client. + </para> + <para> + The <literal>rewrite</literal> option is deprecated. Use + <literal>rewriteIn</literal> instead. + </para> + <para> + The <literal>rewriteIn</literal> 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 <literal>tls</literal> + discussed above, if this option is not used, there is a fallback + to using the <literal>rewrite</literal> block named + <literal>defaultClient</literal> if it exists; and if not, a + fallback to a block named <literal>default</literal>. + </para> + <para> + The <literal>rewriteOut</literal> option is used in the same way + as <literal>rewriteIn</literal>, 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. + </para> + <para> + The <literal>rewriteAttribute</literal> 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 on the form User-Name:/regexpmatch/replacement/. Example + usage: <blockquote> <para> -rewriteAttribute User-Name:/^(.*)@local$/\1@example.com/ + rewriteAttribute User-Name:/^(.*)@local$/\1@example.com/ </para> </blockquote> </para> @@ -437,295 +484,351 @@ rewriteAttribute User-Name:/^(.*)@local$/\1@example.com/ <refsect1> <title>Server Block</title> <para> -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. - </para> - <para> -Alternatively one may use the <literal>host</literal> option inside a server -block. In that case, the value of the <literal>host</literal> 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. - </para> - <para> -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. - </para> - <para> -The allowed options in a server block are <literal>host</literal>, -<literal>port</literal>, <literal>type</literal>, <literal>secret</literal>, -<literal>tls</literal>, <literal>certificateNameCheck</literal>, -<literal>matchCertificateAttribute</literal>, <literal>addTTL</literal>, -<literal>rewrite</literal>, -<literal>rewriteIn</literal>, <literal>rewriteOut</literal>, -<literal>statusServer</literal>, <literal>retryCount</literal>, -<literal>retryInterval</literal>, <literal>dynamicLookupCommand</literal> -and <literal>loopPrevention</literal>. - </para> - <para> -We already discussed the <literal>host</literal> option. The -<literal>port</literal> option allows you to specify which port number the -server uses. The usage of <literal>type</literal>, <literal>secret</literal>, -<literal>tls</literal>, <literal>certificateNameCheck</literal>, -<literal>matchCertificateAttribute</literal>, <literal>addTTL</literal>, -<literal>rewrite</literal>, -<literal>rewriteIn</literal> and <literal>rewriteOut</literal> are just as -specified for the <literal>client block</literal> above, except that -<literal>defaultServer</literal> (and not <literal>defaultClient</literal>) -is the fallback for the <literal>tls</literal>, <literal>rewrite</literal> -and <literal>rewriteIn</literal> options. - </para> - <para> -<literal>statusServer</literal> can be specified to enable the use of -status-server messages for this server. The value must be either -<literal>on</literal> or <literal>off</literal>. The default when not -specified, is <literal>off</literal>. 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. - </para> - <para> -The options <literal>retryCount</literal> and -<literal>retryInterval</literal> 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. - </para> - <para> -The option <literal>dynamicLookupCommand</literal> 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. - </para> - <para> -Using the <literal>loopPrevention</literal> option here overrides any -basic setting of this option. See section <literal>BASIC -OPTIONS</literal> for details on this option. + 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. + </para> + <para> + Alternatively one may use the <literal>host</literal> option + inside a server block. In that case, the value of the + <literal>host</literal> 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. + </para> + <para> + 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. + </para> + <para> + The allowed options in a server block are + <literal>host</literal>, <literal>port</literal>, + <literal>type</literal>, <literal>secret</literal>, + <literal>tls</literal>, <literal>certificateNameCheck</literal>, + <literal>matchCertificateAttribute</literal>, + <literal>addTTL</literal>, <literal>rewrite</literal>, + <literal>rewriteIn</literal>, <literal>rewriteOut</literal>, + <literal>statusServer</literal>, <literal>retryCount</literal>, + <literal>retryInterval</literal>, + <literal>dynamicLookupCommand</literal> and + <literal>loopPrevention</literal>. + </para> + <para> + We already discussed the <literal>host</literal> option. The + <literal>port</literal> option allows you to specify which port + number the server uses. The usage of <literal>type</literal>, + <literal>secret</literal>, <literal>tls</literal>, + <literal>certificateNameCheck</literal>, + <literal>matchCertificateAttribute</literal>, + <literal>addTTL</literal>, <literal>rewrite</literal>, + <literal>rewriteIn</literal> and <literal>rewriteOut</literal> + are just as specified for the <literal>client block</literal> + above, except that <literal>defaultServer</literal> (and not + <literal>defaultClient</literal>) is the fallback for the + <literal>tls</literal>, <literal>rewrite</literal> and + <literal>rewriteIn</literal> options. + </para> + <para> + <literal>statusServer</literal> can be specified to enable the + use of status-server messages for this server. The value must be + either <literal>on</literal> or <literal>off</literal>. The + default when not specified, is <literal>off</literal>. 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. + </para> + <para> + The options <literal>retryCount</literal> and + <literal>retryInterval</literal> 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. + </para> + <para> + The option <literal>dynamicLookupCommand</literal> 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. + </para> + <para> + Using the <literal>loopPrevention</literal> option here + overrides any basic setting of this option. See section + <literal>BASIC OPTIONS</literal> for details on this option. </para> </refsect1> <refsect1> <title>Realm Block</title> <para> -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 <literal>server</literal> -options, and similarly <literal>accountingServer</literal> options. There are -also <literal>replyMessage</literal> and <literal>accountingResponse</literal> -options. We will discuss these later. + 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 <literal>server</literal> options, + and similarly <literal>accountingServer</literal> options. There + are also <literal>replyMessage</literal> and + <literal>accountingResponse</literal> options. We will discuss + these later. </para> <refsect2> <title>Realm block names and matching</title> <para> -In the general case the proxy will look for a <literal>@</literal> in the -username attribute, and try to do an exact case insensitive match between what -comes after the <literal>@</literal> and the name of the realm block. So if you -get a request with the attribute value <literal>anonymous@example.com</literal>, -the proxy will go through the realm names in the order they are specified, -looking for a realm block named <literal>example.com</literal>. + In the general case the proxy will look for a + <literal>@</literal> in the username attribute, and try to do + an exact case insensitive match between what comes after the + <literal>@</literal> and the name of the realm block. So if + you get a request with the attribute value + <literal>anonymous@example.com</literal>, the proxy will go + through the realm names in the order they are specified, + looking for a realm block named + <literal>example.com</literal>. </para> <para> -There are two exceptions to this, one is the realm name <literal>*</literal> -which means match everything. Hence if you have a realm block named -<literal>*</literal>, 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. + There are two exceptions to this, one is the realm name + <literal>*</literal> which means match everything. Hence if + you have a realm block named <literal>*</literal>, 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. </para> <para> -The other exception is regular expression matching. If the realm name starts -with a <literal>/</literal>, 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 -<literal>/</literal> after the regexp. So as an example, if you want to use -regexp matching the domain <literal>example.com</literal> you could have a -realm block named <literal>/@example\\.com$</literal>. Optinally this can also -be written <literal>/@example\\.com$/</literal>. If you want to match all -domains under the <literal>.com</literal> top domain, you could do -<literal>/@.*\\.com$</literal>. Note that since the matching is done on the -entire attribute value, you can also use rules like -<literal>/^[a-k].*@example\\.com$/</literal> 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. + The other exception is regular expression matching. If the + realm name starts with a <literal>/</literal>, 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 <literal>/</literal> after the regexp. So as an + example, if you want to use regexp matching the domain + <literal>example.com</literal> you could have a realm block + named <literal>/@example\\.com$</literal>. Optinally this can + also be written <literal>/@example\\.com$/</literal>. If you + want to match all domains under the <literal>.com</literal> + top domain, you could do <literal>/@.*\\.com$</literal>. Note + that since the matching is done on the entire attribute value, + you can also use rules like + <literal>/^[a-k].*@example\\.com$/</literal> 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. </para> </refsect2> <refsect2> <title>Realm block options</title> <para> -A realm block may contain none, one or multiple <literal>server</literal> -options. If defined, the values of the <literal>server</literal> 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 contain none, one or multiple + <literal>server</literal> options. If defined, the values of + the <literal>server</literal> 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. </para> <para> -A realm block may also contain none, one or multiple -<literal>accountingServer</literal> options. This is used exactly like the -<literal>server</literal> 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 -<literal>server</literal> option. + A realm block may also contain none, one or multiple + <literal>accountingServer</literal> options. This is used + exactly like the <literal>server</literal> 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 + <literal>server</literal> option. </para> <para> -If there is no <literal>server</literal> option, the proxy will if -<literal>replyMessage</literal> 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 <literal>replyMessage</literal> 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 <literal>.bv</literal>. Then you may have several realm -blocks matching the domains that exists, while for other domains under -<literal>.bv</literal> 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 -<literal>/@.*\\.bv$</literal> with no servers, followed by one with the name -<literal>*</literal> with the default server defined. This may also be useful -for blocking particular usernames. + If there is no <literal>server</literal> option, the proxy + will if <literal>replyMessage</literal> 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 <literal>replyMessage</literal> 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 + <literal>.bv</literal>. Then you may have several realm blocks + matching the domains that exists, while for other domains + under <literal>.bv</literal> 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 + <literal>/@.*\\.bv$</literal> with no servers, followed by one + with the name <literal>*</literal> with the default server + defined. This may also be useful for blocking particular + usernames. </para> <para> -If there is no <literal>accountingServer</literal> option, the proxy will -normally do nothing, ignoring accounting requests. There is however an option -called <literal>accountingResponse</literal>. If this is set to -<literal>on</literal>, 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 <literal>off</literal>. + If there is no <literal>accountingServer</literal> option, the + proxy will normally do nothing, ignoring accounting + requests. There is however an option called + <literal>accountingResponse</literal>. If this is set to + <literal>on</literal>, 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 + <literal>off</literal>. </para> </refsect2> </refsect1> <refsect1> <title>TLS Block</title> <para> -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 <literal>default</literal>, <literal>defaultClient</literal> and -<literal>defaultServer</literal> 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 <literal>default</literal>, 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 <literal>defaultClient</literal> and -<literal>defaultServer</literal>. 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 <literal>defaultServer</literal> if you really want to. - </para> - <para> -The available TLS block options are <literal>CACertificateFile</literal>, -<literal>CACertificatePath</literal>, <literal>certificateFile</literal>, -<literal>certificateKeyFile</literal>, -<literal>certificateKeyPassword</literal>, <literal>cacheExpiry</literal>, -<literal>CRLCheck</literal> and <literal>policyOID</literal>. -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 <literal>certificateFile</literal> -and <literal>certificateKeyFile</literal> options, as well as -<literal>certificateKeyPassword</literal> if a password is needed to decrypt -the private key. Note that <literal>CACertificateFile</literal> 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 -<literal>CACertificateFile</literal> or <literal>CACertificatePath</literal>. -Note that you may specify both, in which case the certificates in -<literal>CACertificateFile</literal> are checked first. By default CRLs are -not checked. This can be changed by setting <literal>CRLCheck</literal> to -<literal>on</literal>. One can require peer certificates to adhere to certain -policies by specifying one or multiple policyOIDs using one or multiple -<literal>policyOID</literal> options. - </para> - <para> -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 -<literal>cacheExpiry</literal> 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. + 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 <literal>default</literal>, + <literal>defaultClient</literal> and + <literal>defaultServer</literal> 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 <literal>default</literal>, 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 <literal>defaultClient</literal> and + <literal>defaultServer</literal>. 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 + <literal>defaultServer</literal> if you really want to. + </para> + <para> + The available TLS block options are + <literal>CACertificateFile</literal>, + <literal>CACertificatePath</literal>, + <literal>certificateFile</literal>, + <literal>certificateKeyFile</literal>, + <literal>certificateKeyPassword</literal>, + <literal>cacheExpiry</literal>, <literal>CRLCheck</literal> and + <literal>policyOID</literal>. 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 + <literal>certificateFile</literal> and + <literal>certificateKeyFile</literal> options, as well as + <literal>certificateKeyPassword</literal> if a password is + needed to decrypt the private key. Note that + <literal>CACertificateFile</literal> 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 + <literal>CACertificateFile</literal> or + <literal>CACertificatePath</literal>. Note that you may specify + both, in which case the certificates in + <literal>CACertificateFile</literal> are checked first. By + default CRLs are not checked. This can be changed by setting + <literal>CRLCheck</literal> to <literal>on</literal>. One can + require peer certificates to adhere to certain policies by + specifying one or multiple policyOIDs using one or multiple + <literal>policyOID</literal> options. + </para> + <para> + 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 + <literal>cacheExpiry</literal> 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. </para> </refsect1> <refsect1> <title>Rewrite Block</title> <para> -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 -<literal>default</literal>, <literal>defaultClient</literal> and -<literal>defaultServer</literal> 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 <literal>default</literal>, 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 <literal>defaultClient</literal> and -<literal>defaultServer</literal>. Note that these defaults are only used for -rewrite on input. No rewriting is done on output unless explicitly specifed -using the <literal>rewriteOut</literal> option. - </para> - <para> -The available rewrite block options -are <literal>addAttribute</literal>, <literal>addVendorAttribute</literal>, -<literal>removeAttribute</literal>, <literal>removeVendorAttribute</literal> -and <literal>modifyAttribute</literal>. They can all be specified none, one -or multiple times. - </para> - <para> -<literal>addAttribute</literal> is used to add attributes to a -message. The option value must be on the -form <literal>attribute:value</literal> where attribute is a numerical -value specifying the attribute. Simliarly, -the <literal>addVendorAttribute</literal> is used to specify a vendor -attribute to be added. The option value must be on the -form <literal>vendor:subattribute:value</literal>, where vendor and -subattribute are numerical values. - </para> - <para> -The <literal>removeAttribute</literal> 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, <literal>removeVendorAttribute</literal> 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 on the form -<literal>vendor:subattribute</literal>, where vendor and subattribute are -numerical values, for removing a specific subattribute for a specific -vendor. - </para> - <para> -<literal>modifyAttribute</literal> is used to specify modification of -attributes. The value must be on the form -<literal>attribute:/regexpmatch/replacement/</literal> where attribute is -a numerical attribute type, regexpmatch is regexp matching rule and -replacement specifies how to replace the matching regexp. Example usage: + 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 <literal>default</literal>, + <literal>defaultClient</literal> and + <literal>defaultServer</literal> 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 <literal>default</literal>, 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 + <literal>defaultClient</literal> and + <literal>defaultServer</literal>. Note that these defaults are + only used for rewrite on input. No rewriting is done on output + unless explicitly specifed using the + <literal>rewriteOut</literal> option. + </para> + <para> + The available rewrite block options are + <literal>addAttribute</literal>, + <literal>addVendorAttribute</literal>, + <literal>removeAttribute</literal>, + <literal>removeVendorAttribute</literal> and + <literal>modifyAttribute</literal>. They can all be specified + none, one or multiple times. + </para> + <para> + <literal>addAttribute</literal> is used to add attributes to a + message. The option value must be on the form + <literal>attribute:value</literal> where attribute is a + numerical value specifying the attribute. Simliarly, the + <literal>addVendorAttribute</literal> is used to specify a + vendor attribute to be added. The option value must be on the + form <literal>vendor:subattribute:value</literal>, where vendor + and subattribute are numerical values. + </para> + <para> + The <literal>removeAttribute</literal> 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, + <literal>removeVendorAttribute</literal> 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 on the form <literal>vendor:subattribute</literal>, where + vendor and subattribute are numerical values, for removing a + specific subattribute for a specific vendor. + </para> + <para> + <literal>modifyAttribute</literal> is used to specify + modification of attributes. The value must be on the form + <literal>attribute:/regexpmatch/replacement/</literal> where + attribute is a numerical attribute type, regexpmatch is regexp + matching rule and replacement specifies how to replace the + matching regexp. Example usage: <blockquote> <para> -modifyAttribute 1:/^(.*)@local$/\1@example.com/ + modifyAttribute 1:/^(.*)@local$/\1@example.com/ </para> </blockquote> </para> @@ -734,8 +837,7 @@ modifyAttribute 1:/^(.*)@local$/\1@example.com/ <title>See Also</title> <para> <citerefentry> - <refentrytitle>radsecproxy</refentrytitle> - <manvolnum>1</manvolnum> + <refentrytitle>radsecproxy</refentrytitle><manvolnum>1</manvolnum> </citerefentry>, <ulink url="http://tools.ietf.org/html/draft-ietf-radext-radsec"> <citetitle>RadSec internet draft</citetitle> |