"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry>
<refentryinfo>
- <date>2008-11-05</date>
+ <date>2012-04-27</date>
</refentryinfo>
<refmeta>
<refentrytitle>
<application>radsecproxy.conf</application>
</refentrytitle>
<manvolnum>5</manvolnum>
- <refmiscinfo>radsecproxy devel 2008-11-05</refmiscinfo>
+ <refmiscinfo>radsecproxy 1.6</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>/usr/local/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 of 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 /usr/local/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>
+ <term><literal>PidFile</literal></term>
<listitem>
<para>
-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 <option>-d</option> overrides this.
+ The PidFile option specifies the name of a file to which
+ the process id (PID) will be written. This is overridden
+ by the <option>-i</option> command line option. There is
+ no default value for the PidFile option.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>logDestination</literal></term>
+ <term><literal>LogLevel</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 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>
<varlistentry>
- <term><literal>listenUDP</literal></term>
+ <term><literal>LogDestination</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 of 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 if you specify port number.
-This option may be specified multiple times to listen to multiple addresses
-and/or ports.
+ 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>
+
+ <varlistentry>
+ <term><literal>FTicksReporting</literal></term>
+ <listitem>
+ <para>
+ The FTicksReporting option is used to enable F-Ticks
+ logging and can be set to <literal>None</literal>,
+ <literal>Basic</literal> or <literal>Full</literal>. Its
+ default value is <literal>None</literal>. If
+ FTicksReporting is set to anything other than
+ <literal>None</literal>, note that the default value for
+ FTicksMAC is <literal>VendorKeyHashed</literal> which
+ needs FTicksKey to be set.
+ </para>
+ <para>
+ See <literal>radsecproxy.conf-example</literal> for
+ details. Note that radsecproxy has to be configured with
+ F-Ticks support (<literal>--enable-fticks</literal>) for
+ this option to have any effect.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>FTicksMAC</literal></term>
+ <listitem>
+ <para>
+ The FTicksMAC option can be used to control if and how
+ Calling-Station-Id (the users Ethernet MAC address) is
+ being logged. It can be set to one of
+ <literal>Static</literal>, <literal>Original</literal>,
+ <literal>VendorHashed</literal>,
+ <literal>VendorKeyHashed</literal>,
+ <literal>FullyHashed</literal> or
+ <literal>FullyKeyHashed</literal>.
+ </para>
+ <para>
+ The default value for FTicksMAC is
+ <literal>VendorKeyHashed</literal>. This means that
+ FTicksKey has to be set.
+ <para>
+ Before chosing any of <literal>Original</literal>,
+ <literal>FullyHashed</literal> or
+ <literal>VendorHashed</literal>, consider the implications
+ for user privacy when MAC addresses are collected. How
+ will the logs be stored, transferred and accessed?
+ </para>
+ </para>
+ <para>
+ See <literal>radsecproxy.conf-example</literal> for
+ details. Note that radsecproxy has to be configured with
+ F-Ticks support (<literal>--enable-fticks</literal>) for
+ this option to have any effect.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>FTicksKey</literal></term>
+ <listitem>
+ <para>
+ The FTicksKey option is used to specify the key to use
+ when producing HMAC's as an effect of specifying
+ VendorKeyHashed or FullyKeyHashed for the FTicksMAC
+ option.
+ </para>
+ <para>
+ Note that radsecproxy has to be configured with F-Ticks
+ support (<literal>--enable-fticks</literal>) for this
+ option to have any effect.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>FTicksSyslogFacility</literal></term>
+ <listitem>
+ <para>
+ The FTicksSyslogFacility option is used to specify a
+ dedicated syslog facility for F-Ticks messages. This
+ allows for easier filtering of F-Ticks messages. If no
+ FTicksSyslogFacility option is given, F-Ticks messages are
+ written to what the LogDestination option specifies.
+ </para>
+ <para>
+ F-Ticks messages are always logged using the log level
+ LOG_DEBUG. Note that specifying a file in
+ FTicksSyslogFacility (using the file:/// prefix) is
+ not supported.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
- <term><literal>listenTCP</literal></term>
+ <term><literal>ListenUDP</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>.
+ 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>
<varlistentry>
- <term><literal>listenTLS</literal></term>
+ <term><literal>ListenTCP</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 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>
<varlistentry>
- <term><literal>listenDTLS</literal></term>
+ <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 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 TLS clients. The default port number is
+ <literal>2083</literal>. Note that this option was
+ previously called <literal>ListenTCP</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>listenAccountingUDP</literal></term>
+ <term><literal>ListenDTLS</literal></term>
<listitem>
<para>
-This is similar to the <literal>listenUDP</literal> option, except that it is
-used for specifying port and optionally the address to receive UDP Accounting
-messages on.
+ 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>
<varlistentry>
- <term><literal>sourceUDP</literal></term>
+ <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>
<varlistentry>
- <term><literal>sourceTCP</literal></term>
+ <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>
<varlistentry>
- <term><literal>sourceTLS</literal></term>
+ <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>
<varlistentry>
- <term><literal>sourceDTLS</literal></term>
+ <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>
<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>
+ <varlistentry>
+ <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.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>addTTL</literal></term>
+ <term><literal>LoopPrevention</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.
+ 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>
<varlistentry>
- <term><literal>loopPrevention</literal></term>
+ <term><literal>IPv4Only and IPv6Only</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.
+ These can be set to <literal>on</literal> or
+ <literal>off</literal> with <literal>off</literal> being
+ the default. At most one of <literal>IPv4Only</literal>
+ and <literal>IPv6Only</literal> can be enabled. Enabling
+ <literal>IPv4Only</literal> or <literal>IPv6Only</literal>
+ makes radsecproxy resolve DNS names to the corresponding
+ address family only, and not the other. This is done for
+ both clients and servers. Note that this can be
+ overridden in <literal>client</literal> and
+ <literal>server</literal> blocks, see below.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>include</literal></term>
+ <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>
<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) of the form
-IpAddress/PrefixLength, or a domain name (FQDN).
- </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.
- </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 of 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). The way an
+ FQDN is resolved into an IP address may be influenced by the use
+ of the <literal>IPv4Only</literal> and
+ <literal>IPv6Only</literal> options. 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>IPv4Only</literal>,
+ <literal>IPv6Only</literal>, <literal>type</literal>,
+ <literal>secret</literal>, <literal>tls</literal>,
+ <literal>certificateNameCheck</literal>,
+ <literal>matchCertificateAttribute</literal>,
+ <literal>duplicateInterval</literal>, <literal>AddTTL</literal>,
+ <literal>fticksVISCOUNTRY</literal>,
+ <literal>fticksVISINST</literal>, <literal>rewrite</literal>,
+ <literal>rewriteIn</literal>, <literal>rewriteOut</literal>, and
+ <literal>rewriteAttribute</literal>.
+
+ We already discussed the <literal>host</literal> option. To
+ specify how radsecproxy should resolve a <literal>host</literal>
+ given as a DNS name, the <literal>IPv4Only</literal> or the
+ <literal>IPv6Only</literal> can be set to <literal>on</literal>.
+ At most one of these options can be enabled. Enabling
+ <literal>IPv4Only</literal> or <literal>IPv6Only</literal> here
+ overrides any basic settings set at the top level.
+
+ 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 and if omitted
+ will default to "mysecret". Note that the default value of
+ <literal>secret</literal> will change in an upcoming release.
+ </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>fticksVISCOUNTRY</literal> option configures
+ clients eligible to F-Ticks logging as defined by the
+ <literal>FTicksReporting</literal> basic option.
+ </para>
+ <para>
+ The <literal>fticksVISINST</literal> option overwrites
+ the default <literal>VISINST</literal> value taken from the client
+ block name.
+ </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>
<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.
- </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> and <literal>dynamicLookupCommand</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.
+ 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. The way an FQDN is resolved into an IP
+ address may be influenced by the use of the
+ <literal>IPv4Only</literal> and <literal>IPv6Only</literal>
+ options. 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>IPv4Only</literal>, <literal>IPv6Only</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>dynamicLookupCommand</literal> and
+ <literal>retryInterval</literal> and
+ <literal>LoopPrevention</literal>.
+ </para>
+ <para>
+
+ We already discussed the <literal>host</literal> option. To
+ specify how radsecproxy should resolve a <literal>host</literal>
+ given as a DNS name, the <literal>IPv4Only</literal> or the
+ <literal>IPv6Only</literal> can be set to <literal>on</literal>.
+ At most one of these options can be enabled. Enabling
+ <literal>IPv4Only</literal> or <literal>IPv6Only</literal> here
+ overrides any basic settings set at the top level.
+
+ 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 a server. The executable file should be given with
+ full path and will be invoked with the name of the realm as its
+ first and only argument. It should either print a valid
+ <literal>server</literal> option on stdout and exit with a code
+ of 0 or print nothing and exit with a non-zero exit code. An
+ example of a shell script resolving the DNS NAPTR records for
+ the realm and then the SRV records for each NAPTR matching
+ 'x-eduroam:radius.tls' is provided in
+ <literal>tools/naptr-eduroam.sh</literal>. This option was
+ added in radsecproxy-1.3 but tends to crash radsecproxy versions
+ earlier than 1.6.
+ </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.
- </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.
+ </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>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 of the form <literal>attribute:value</literal> where
-attribute is a numerical value specifying the attribute.
- </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 of 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 of 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>
<title>See Also</title>
<para>
<citerefentry>
- <refentrytitle>radsecproxy</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry>,
- <ulink url="http://tools.ietf.org/html/draft-ietf-radext-radsec">
- <citetitle>RadSec internet draft</citetitle>
- </ulink>
+ <refentrytitle>radsecproxy</refentrytitle><manvolnum>1</manvolnum>
+ </citerefentry>,
+ <ulink url="http://tools.ietf.org/html/draft-ietf-radext-radsec">
+ <citetitle>RadSec internet draft</citetitle>
+ </ulink>
</para>
</refsect1>
</refentry>
projects / radsecproxy.git / blobdiff