"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry>
<refentryinfo>
- <date>2011-04-04</date>
+ <date>2012-10-25</date>
</refentryinfo>
<refmeta>
<refentrytitle>
<application>radsecproxy.conf</application>
</refentrytitle>
<manvolnum>5</manvolnum>
- <refmiscinfo>radsecproxy 1.5-dev</refmiscinfo>
+ <refmiscinfo>radsecproxy 1.6.3-rc0</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
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
+ <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>
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>
<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
+ <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
+ the <literal>Include</literal> option. Included files may again
include other files.
</para>
</refsect1>
</para>
<variablelist>
<varlistentry>
- <term><literal>logLevel</literal></term>
+ <term><literal>PidFile</literal></term>
+ <listitem>
+ <para>
+ 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>LogLevel</literal></term>
<listitem>
<para>
This option specifies the debug level. It must be set to
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>logDestination</literal></term>
+ <term><literal>LogDestination</literal></term>
<listitem>
<para>
This specifies where the log messages should go. By
</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>listenUDP</literal></term>
+ <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>ListenUDP</literal></term>
<listitem>
<para>
Normally the proxy will listen to the standard RADIUS UDP
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>listenTCP</literal></term>
+ <term><literal>ListenTCP</literal></term>
<listitem>
<para>
- This option is similar to the <literal>listenUDP</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>.
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>listenTLS</literal></term>
+ <term><literal>ListenTLS</literal></term>
<listitem>
<para>
- This is similar to the <literal>listenUDP</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>.
+ previously called <literal>ListenTCP</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>listenDTLS</literal></term>
+ <term><literal>ListenDTLS</literal></term>
<listitem>
<para>
- This is similar to the <literal>listenUDP</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>.
</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
</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
</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
</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
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>addTTL</literal></term>
+ <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
+ 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
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>loopPrevention</literal></term>
+ <term><literal>LoopPrevention</literal></term>
<listitem>
<para>
This can be set to <literal>on</literal> or
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>include</literal></term>
+ <term><literal>IPv4Only and IPv6Only</literal></term>
+ <listitem>
+ <para>
+ 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>
<listitem>
<para>
This is not a normal configuration option; it can be
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.
+ 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
</para>
<para>
The allowed options in a client block are
- <literal>host</literal>, <literal>type</literal>,
+ <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>rewrite</literal>, <literal>rewriteIn</literal>,
- <literal>rewriteOut</literal> and
+ <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. The
- value of <literal>type</literal> must be one of
+ 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.
+ be quoted. This option is optional for TLS/DTLS and if omitted
+ will default to "radsec". (Note that using a secret other than
+ "radsec" for TLS is a violation of the standard (RFC 6614) and
+ that the proposed standard for DTLS stipulates that the secret
+ must be "radius/dtls".)
</para>
<para>
For a TLS/DTLS client you may also specify the
<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.
+
+ NOTE: All versions of radsecproxy up to and including 1.6
+ erroneously verify client certificate chains using the CA in the
+ very first matching client block regardless of which block is
+ used for the final decision. This was changed in version 1.6.1
+ so that a client block with a different <literal>tls</literal>
+ option than the first matching client block is no longer
+ considered for verification of clients.
+
</para>
<para>
For a TLS/DTLS client, the option
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
+ 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>
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.
+ 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
<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>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>.
+ <literal>retryInterval</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>,
+
+ 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>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
<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
+ 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>
the users in this domain to use one server, while other users
could be matched by another realm block and use another
server.
- </para>
+ </para>
</refsect2>
<refsect2>
<title>Realm block options</title>
<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
+ unless explicitly specified using the
<literal>rewriteOut</literal> option.
</para>
<para>
<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>
+ </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