"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry>
<refentryinfo>
- <date>2008-10-06</date>
+ <date>2009-03-12</date>
</refentryinfo>
<refmeta>
<refentrytitle>
<application>radsecproxy.conf</application>
</refentrytitle>
<manvolnum>5</manvolnum>
- <refmiscinfo>radsecproxy devel 2008-10-06</refmiscinfo>
+ <refmiscinfo>radsecproxy devel 2009-03-12</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
</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
+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
<term><literal>logLevel</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
+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>
<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
+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 if you specify port number.
+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>listenAccountingUDP</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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
<term><literal>sourceUDP</literal></term>
<listitem>
<para>
</listitem>
</varlistentry>
<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>.
+ </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>loopPrevention</literal></term>
<listitem>
<para>
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>
<title>Blocks</title>
<para>
There are five types of blocks, they are <literal>client</literal>,
-<literal>server</literal>, <literal>realm</literal>, <literal>Btls</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
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).
+(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
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.
+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>rewrite</literal>,
-<literal>rewriteIn</literal>, <literal>rewriteOut</literal> and
-<literal>rewriteAttribute</literal>. We already discussed the
+<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
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>
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:
+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>
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.
+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>rewrite</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>.
+<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>rewrite</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>)
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>
The available TLS block options are <literal>CACertificateFile</literal>,
<literal>CACertificatePath</literal>, <literal>certificateFile</literal>,
<literal>certificateKeyFile</literal>,
-<literal>certificateKeyPassword</literal>, <literal>cacheExpiry</literal>
-and <literal>CRLCheck</literal>. When doing RADIUS over TLS/DTLS, both the
+<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
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>.
+<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
using the <literal>rewriteOut</literal> option.
</para>
<para>
-The available rewrite block options are <literal>addAttribute</literal>,
+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 of the form <literal>attribute:value</literal> where
-attribute is a numerical value specifying the attribute.
+<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
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
+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 of the form
+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>