radsecproxy.conf.5.in

.TH radsecproxy.conf 5 "@RELEASEDATE@" "@PACKAGE_STRING@" ""

.SH NAME
radsecproxy.conf \- Radsec proxy configuration file

.SH DESCRIPTION
When the proxy server starts, it will first check the command line arguments,
and then read the configuration file. Normally radsecproxy will read the
configuration file \fI@SYSCONFDIR@/radsecproxy.conf\fR. The command line
\fB\-c\fR option can be used to instead read an alternate file (see
\fBradsecproxy\fR(8) for details).

If the configuration file can not be found, the proxy will exit with an error
message. Note that there is also an include facility so that any configuration
file may include other configuration files. The proxy will also exit on
configuration errors.

.SH "CONFIGURATION SYNTAX"
When the configuration file is processed, whitespace (spaces and tabs) are
generally ignored. For each line, leading and trailing whitespace are ignored.
A line is ignored if it is empty, only consists of whitespace, or if the first
non-whitespace character is a #. The configuration is generally case
insensitive, but in some cases the option values (see below) are not.

There are two types of configuration structures than can be used. The first and
simplest are lines on the format \fIoption value\fR. That is, an option name,
see below for a list of valid options, followed by whitespace (at least one
space or tab character), followed by a value. Note that if the value contains
whitespace, then it must be quoted using "" or ''. Any whitespace in front of
the option or after the value will be ignored.

The other type of structure is a block. A block spans at least two lines, and
has the format:
.RS
.nf

blocktype name {
	option value
	option value
	...
}

.fi
.RE

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 \fIoption value\fR 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:
.RS
.nf

blocktype name {
#    option value
    option "value with space"
    ...
}

.fi
.RE

Option value characters can also be written in hex for options requiring a
string type value. 
A % character followed by two hexadecimal digits will be replaced by its byte
value. Longer hex strings can be escaped with %%. In this case all following
hexadecimal digit pairs will be replace by byte values until the first non-hex
character. If a % is used without two following hexadecimal digits, the
% and the following characters are used as written. If you want to write a % and
not use this decoding, you may of course write % in hex; i.e., %25. As %00 would
terminate a string, this value is not converted in most cases, except when used
with rewrite statements or secrets.

Some options allow or require the use of regular expressions, denoted as
\fIregex\fR. The POSIX extended RE system is used, see
.BR re_format (7).

There is one special option that can be used both as a basic option and inside
all blocks. That is the option \fIInclude\fR 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.:

.RS
include @SYSCONFDIR@/radsecproxy.conf.d/*.conf
.RE

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 \fIInclude\fR option. Included files may again include other
files.

.SH "BASIC OPTIONS"
The following basic options may be specified in the configuration file. Note
that blocktypes and options inside blocks are discussed later. Note that none of
these options are required, and indeed in many cases they are not needed. Note
that you should specify each at most once. The behaviour with multiple
occurrences is undefined.

.BI "PidFile " file
.RS
The PidFile option specifies the name of a \fIfile\fR to which the process id
(PID) will be written. This is overridden by the \fB\-i\fR command line option.
There is no default value for the PidFile option.
.RE

.BR "LogLevel " "1-5"
.RS
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 \fB\-d\fR overrides this.
.RE

.BI "LogDestination (" file | syslog )
.RS
This specifies where the log messages should go. By default the messages go to
syslog with facility \fBLOG_DAEMON\fR. 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 path like \fBfile:/path/to/your/logfile.log\fR 
or a syslog URL using the syntax:
.BR "x\-syslog:FACILITY" " where " FACILITY " must be one of "
.BR LOG_DAEMON ,
.BR LOG_MAIL ,
.BR LOG_USER ,
.BR LOG_LOCAL0 ,
.BR LOG_LOCAL1 ,
.BR LOG_LOCAL2 ,
.BR LOG_LOCAL3 ,
.BR LOG_LOCAL4 ,
.BR LOG_LOCAL5 ,
.BR LOG_LOCAL6 or
.BR LOG_LOCAL7 .
You may omit the facility from the URL to specify logging to the default
facility, but this is not very useful since this is the default log
destination. Note that this option is ignored if \fB\-f\fR is specified on the
command line.
.RE

.BR "LogThreadId (" on | off )
.RS
This can be set to on to include the thread-id in the log messages (useful for
debugging).
.RE


.BR "LogFullUsername (" on | off )
.RS
This can be set to off to only log the realm in Access-Accept/Reject log
messages (for privacy).
.RE

.BI "LogMAC " opt
.RS
The LogMAC 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
.BR Static ,
.BR Original ,
.BR VendorHashed ,
.BR VendorKeyHashed ,
.BR FullyHashed
or
.BR FullyKeyHashed .
The default value for LogMAC is \fBOriginal\fR.

See \fIradsecproxy.conf\-example\fR for details.
.RE

.BI "LogKey " key
.RS
The LogKey option is used to specify the \fIkey\fR to use when producing HMAC's as an
effect of specifying \fBVendorKeyHashed\fR or \fBFullyKeyHashed\fR for the
LogMAC option.
.RE

.BI "FTicksReporting " fticks
.RS
The FTicksReporting option is used to enable F-Ticks logging and can be set to
.BR None ,
.BR Basic
or
.BR Full.
Its default value is \fBNone\fR. If FTicksReporting is set to anything other
than \fBNone\fR, note that the default value for \fBFTicksMAC\fR needs
\fBFTicksKey\fR to be set. 
.br
For F-Ticks records to be generated, at least the \fBFticksVISCOUNTRY\fR
option has to be set on the originating client.

See \fIradsecproxy.conf\-example\fR for details.
.RE

.BI "FTicksMAC " opt
.RS
The FTicksMAC option has the same function as LogMAC for FTicks. The default for
FTicksMAC is \fBVendorKeyHashed\fR which needs \fBFTicksKey\fR to be set.

Before choosing any of
.BR Original ,
.BR FullyHashed
or
.BR VendorHashed ,
consider the implications for user privacy when MAC addresses are collected. How
will the logs be stored, transferred and accessed?
.RE

.BI "FTicksKey " key
.RS
The FTicksKey option has the same function as LogKey for Fticks.
.RE

.BI "FTicksSyslogFacility " syslog
.RS
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 \fBLogDestination\fR option specifies.

F-Ticks messages are always logged using the log level \fBLOG_DEBUG\fR. Note
that specifying a file in FTicksSyslogFacility (using the file: prefix) is
not supported.
.RE

.BI "FTicksPrefix " prefix
.RS
The FTicksPrefix option is used to set the \fIprefix\fR printed in F-Ticks
messages. This allows for use of F-Ticks messages in non-eduroam environments.
If no FTicksPrefix option is given, it defaults to the prefix used for eduroam
(\fIF\-TICKS/eduroam/1.0\fR).

.RE

.BI "ListenUDP (" address | \fR* )[\fR: port ]
.br
.BI "ListenTCP (" address | \fR* )[\fR: port ]
.br
.BI "ListenTLS (" address | \fR* )[\fR: port ]
.br
.BI "ListenDTLS (" address | \fR* )[\fR: port ]
.RS
Listen for the address and port for the respective protocol.
Normally the proxy will listen to the standard ports if configured to handle
clients with the respective protocol. The default ports are 1812 for \fBUDP\fR
and \fBTCP\fR and 2083 for \fBTLS\fR and \fBDTLS\fR. 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 *:\fIport\fR where \fIport\fR is any valid port
number. If you also want to specify a specific \fIaddress\fR you can do e.g.
192.168.1.1:1812 or [2001:db8::1]:1812. The port may be omitted if you want the
default one. Note that you must use brackets around the IPv6 address. These
options may be specified multiple times to listen to multiple addresses and/or
ports for each protocol.
.RE

.BI "SourceUDP (" address | \fR* )[\fR: port ]
.br
.BI "SourceTCP (" address | \fR* )[\fR: port ]
.br
.BI "SourceTLS (" address | \fR* )[\fR: port ]
.br
.BI "SourceDTLS (" address | \fR* )[\fR: port ]
.RS
This can be used to specify source address and/or source port that the proxy
will use for connecting to clients to send messages (e.g. Access Request). The
same syntax as for \fBListen...\fR applies.
.RE

.BI "TTLAttribute (" attr | vendor : attr )
.RS
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.
.RE

.BR "AddTTL " "1-255"
.RS
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 which will
override this setting when forwarding a message to that client/server.
.RE

.BR "LoopPrevention (" on | off )
.RS
When this is enabled (on), 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.
.RE

.BR "IPv4Only (" on | off )
.br
.BR "IPv6Only (" on | off )
.RS
Enabling IPv4Only or IPv6Only (on) makes radsecproxy resolve DNS names to the
corresponding address family only, and not the other. This is done for both
clients and servers. At most one of IPv4Only and IPv6Only can be enabled.
Note that this can be overridden in client and server blocks, see below.
.RE

.BR "SNI (" on | off )
.RS
Server Name Indication (SNI) is an extension to the TLS protocol.  It allows a
client to indicate which hostname it is trying to connect to at the start of
the TLS handshake. Enabling this will use the extension for all TLS and DTLS
servers which specify a hostname (not IP address). This can be overridden in 
server blocks, see below.
.RE

.BR "VerifyEAP (" on | off )
.RS
A radius proxy is mostly agnostic to the contents of the attributes within a 
radius message and forwards them as-is. However wrong EAP attributes can lead to
bad user experience. Thus radsecproxy checks the content length of the contained
EAP message and denies the access-request if it doesn't match the attribute
length. In case malformatted EAP attributes are inentional, this behaviour can
be disabled (default on).
.RE

.BR "RequireMessageAuthenticator (" on | off )
.RS
Require that all Access-* packets on UDP and TCP transport be signed with a Message-Authenticator.
.br
Enable this option if all clients and servers are known to always use Message-Authenticator to 
increase security. This setting can be overriden per client and per server (default off). 
.RE

.BR "ProtocolError (" on | off)
.RS
Send Protocol-Error responses if requests can't be forwarded, allowing clients to clean 
up their state early and not having to wait for a timeout.
.br
This setting can be overridden per client (default on).
.RE

.BI "Include " file
.RS
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.
.RE

.SH BLOCKS
There are five types of blocks, they are
.BR client ,
.BR server ,
.BR realm ,
.BR tls
and
.BR rewrite .
At least one instance of each of \fBclient\fR and \fBrealm\fR is required for
the proxy to do anything useful, and it will exit if none are configured. The
\fBtls\fR 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 occurrences 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.

.SH "CLIENT BLOCK"
.nf
.BI "client (" name | fqdn |( address [/ length ])) "\fR {"
	...
}
.fi
.PP
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 \fIaddress\fR
(IPv4 or IPv6) of the client, an IP prefix (IPv4 or IPv6) on the form
IpAddress/PrefixLength, or a domain name (\fIFQDN\fR). The way an FQDN is
resolved into an IP address may be influenced by the use of the \fBIPv4Only\fR
and \fBIPv6Only\fR options. Note that literal IPv6 addresses must be enclosed in
brackets.

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. However, if the name can not be resolved, startup will fail.

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. When using the IpAddress/PrefixLength form,
this might mask clients defined later, which then will never be matched.

In the case of TLS/DTLS, the name of the client must match the FQDN or IP
address in the client certificate (SubectAltName:DNS or SubjectAltName:IP
respectively) and any \fBMatchCertificateAttribute\fR to be positively identified. 
Note that when using an IP prefix, the SubjectAltName:IP must match the origin IP
address.
If overlapping clients are defined (see section above), they will be searched for 
positive identification, but only among clients referencing the same tls block
(selected by the first matching IP address or prefix).

The allowed options in a client block are:

.BI "Host (" fqdn |( address [/ length ]))
.RS
Alternatively of specifying the FQDN or address in the block name,  the
\fBhost\fR option may be used. In that case, the value of the \fBhost\fR option
is used as described 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.
.RE

.BR "IPv4Only (" on | off )
.br
.BR "IPv6Only (" on | off )
.RS
Enabling IPv4Only or IPv6Only (on) makes radsecproxy resolve DNS names to the
corresponding address family only, and not the other. At most one of IPv4Only
and IPv6Only can be enabled. Note that this will override the global option for
this client.
.RE

.BI "Type " type
.RS
Specify the \fItype\fR (protocol) of the client. Available options are
.BR UDP ,
.BR TCP ,
.BR TLS
and
.BR DTLS .
.br
While TLS and DTLS are secure, enctrypted transports, UDP and TCP are not.
Radius uses the shared secret only to encrypt certain critical attributes,
but most of the Radius data is sent in clear. Protection against manipulation is
only provided if the client uses the Message-Authenticator attribute.
.br
Therefore UDP and TCP should only be used in secured networks or when an underying
secure transport such as IPSEC or MACSEC is used. UDP and TCP SHOULD NOT be used
across the internet.
.RE

.BI "Secret " secret
.RS
Use \fIsecret\fR as the shared RADIUS key 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 "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".)
.RE

.BI "TLS " tls
.RS
For a TLS/DTLS client you may also specify the \fBtls\fR 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 \fBdefaultClient\fR or \fBdefault\fR will
be used if defined (in that order). 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.
.RE

.BI "ServerName " servername
.RS
Use \fIservername\fR for the certificate name check instead of \fBhost\fR or the
client block name (e.g. if \fBhost\fR uses static IP address).
.RE

.BR "CertificateNameCheck (" on | off )
.RS
For a TLS/DTLS client, disable the default behaviour of matching 
SubjectAltName against the specified hostname or IP address.
.RE

.BR "CertificateCNCheck (" on | off )
.RS
For a TLS/DTLS client, enable the legacy behavior of mathing the hostname
against the common name. This setting has no effect if \fB CertificateNameCheck\fR 
is off. Default off.
.RE

\fBMatchCertificateAttribute \fRCN:/\fIregexp\fR/
.br
\fBMatchCertificateAttribute \fRSubjectAltName:DNS:/\fIregexp\fR/
.br
\fBMatchCertificateAttribute \fRSubjectAltName:URI:/\fIregexp\fR/
.br
\fBMatchCertificateAttribute \fRSubjectAltName:IP:\fIaddress\fR
.br
\fBMatchCertificateAttribute \fRSubjectAltName:rID:\fIoid\fR
.br
\fBMatchCertificateAttribute \fRSubjectAltName:otherName:\fIoid\fR:/\fIregexp\fR/
.RS
Perform additional validation of certificate attributes. Currently matching
of CN and SubjectAltName types URI, DNS, IP, rID, and otherName is supported. If specified
multiple times, all terms must match for the certificate to be considered valid.
.RE

.BI "PSKkey " key
.RS
For TLS, use TLS-PSK (pre shared key) instead of certificate based authentication.
If specified, \fBPSKidentity\fR must also be provided.
The \fIkey\fR must be at least 16 bytes long. To provide the \fIkey\fR in hex, use 
the %% escaping (see CONFIGURATION SYNTAX).

In addition to the psk, peers must also agree on the key derivation hash function.
For this, the server simply uses the hash function of the negotiated cipher as this
negotiation must yield a compatible cipher anyway.
To ensure unambiguous cipher and hash selection, only use ciphers with the same
hash function in the \fBCipherSuites\fR of the \fBtls\fR block. If no \fBtls\fR 
block is specified, a default config with SHA256 is used.

Note: only TLS1.3 PSK is supported and only for TLS, not DTLS (pending OpenSSL DTLS1.3 support).
.RE

.BI "PSKidentity " identity
.RS
The TLS-PSK \fIidentity\fR to identify the client. When omitted, the \fBclient \fIname\fR is
used as the identity.
When using TLS-PSK, all clients are identified by their PSK identity, however it
is highly recommended to limit the allowed source address(es) using the
\fBHost \fIaddress\fR option.
.RE

.BI "DuplicateInterval " seconds
.RS
Specify for how many \fIseconds\fR 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.
.RE

.BI "IdleTimeout " seconds
.RS
After \fIseconds\fR without any traffic, connections from this client are closed. Default 600s.
.RE

.BR "AddTTL " 1-255
.RS
The AddTTL option has the same meaning as the option used in the basic config.
See the \fBBASIC OPTIONS\fR section for details. Any value configured here
overrides the basic one when sending messages to this client.
.RE

.BR "TCPKeepalive (" on | off )
.RS
Enable TCP keepalive (default is off). If
keepalives are not answered within 30s the connection is considered
lost.
.RE

.BI "FticksVISCOUNTRY " cc
.RS
Sets this client to be eligible to F-Ticks logging as defined by the
\fBFTicksReporting\fR basic option, and specifies the country to be reported.
The country should be specified by the two-letter country code.
.RE

.BI "FticksVISINST " institution
.RS
Set the institution to report in F-Ticks logging. If this option is omitted, the
name of the client block is used.
.RE

.BI "Rewrite " rewrite
.RS
This option is deprecated. Use \fBrewriteIn\fR instead.
.RE

.BI "RewriteIn " rewrite
.br
.BI "RewriteOut " rewrite
.RS
Apply the operations in the specified \fIrewrite\fR block on incoming (request)
or outgoing (response) messages from this client. Rewriting incoming messages is
done before, outgoing after other processing. If the \fBRewriteIn\fR is not
configured, the rewrite blocks \fBdefaultClient\fR or \fBdefault\fR will be
applied if defined. No default blocks are applied for \fBRewriteOut\fR.
.RE

.BI "RewriteAttribute User-Name:/" regex / replace /
.RS
Rewrite the User-Name attribute in a client request for the request forwarded 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. Example usage:

RewriteAttribute User-Name:/^(.*)@local$/\e1@example.com/
.RE

.BR "RequireMessageAuthenticator (" on | off )
.RS
Require all Access-Requests be signed with a Message-Authenticator.
.br
This should be enabled if the client is a proxy, or a NAS known to use Message-Authenticator
(e.g. all EAP based NAS like Wifi).
.br
This setting is ignored when using TLS/DTLS transport.
.RE

.BR "RequireMessageAuthenticatorProxy (" on | off)
.RS
Require all Access-Requests containing a Proxy-State attribute to be signed with a Message-Authenticaor.
.br
This should always be enabled if the client is a NAS.
.br
This setting is ignored when using TLS/DLTS transport or when \fB RequireMessageAuthenticator\fR is
enabled.
.RE

.BR "ProtocolError (" on | off)
.RS
Send Protocol-Error responses if requests can't be forwarded, allowing clients to clean 
up their state early and not having to wait for a timeout (default on).
.RE

.SH "SERVER BLOCK"
.nf
.BI "server (" name |(( fqdn | address )[\fR: port ])) "\fR {"
	...
}
.fi
.PP
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 \fBIPv4Only\fR and
\fBIPv6Only\fR options.

In the case of TLS/DTLS, the name of the server must match the FQDN or IP
address in the server certificate.

Note that the \fIfqdn\fR or \fIaddress\fR may include a \fIport\fR 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.

The allowed options in a server block are:

.BI "Host (" fqdn | address )[\fR: port ]
.RS
Alternatively of specifying the FQDN or address in the block name the \fBhost\fR
option may be used. In that case, the value of the \fBhost\fR option is used as
described 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 use separate server
blocks.
.RE

.BI "Port " port
.RS
Specify the \fIport\fR (UDP/TCP) to connect to. If omitted, UDP and TCP will
default to 1812 while TLS and DTLS will default to 2083.
.RE

.BI "Source (" address | \fR* )[\fR: port ]
.RS
Specify the source address and/or port to use for this server. See \fBSource...\fR 
options above.
.RE

.BI "DynamicLookupCommand " command
.RS
Execute the \fIcommand\fR to dynamically configure a server for a realm given by 
the username field in an Access-Request. 
The command can take two special forms, naptr:\fIservice\fR or srv:\fIprefix\fR,
or point to a script or executable.

The \fBnaptr:\fR and \fBsrv:\fR forms execute the corresponding DNS queries, either searching 
for \fIservice\fR in NAPTR records (followed by SRV query), or querying for 
\fIprefix\fB.realm\fR SRV records. Finally a server block will be constructed for 
the dynamic realm taking this server block as a template and overriding the \fBhost\fR 
entries with the content of the SRV records.

Otherwise, the \fIcommand\fR should be an executable file or script, given with 
full path, that will be invoked with the name of the realm as its first and only argument. 
It should either print a valid \fBserver {...}\fR block containing at least one \fBhost\fR 
statement on stdout and exit with a code of 0, or print nothing and exit with a non-zero 
exit code. If the command exited with 0 and provided a valid server config, it will be combined
with the statements in this server block, with the values returned by the command
taking preference.

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 \fItools/naptr\-eduroam.sh\fR.
This is equivalent to configuring 'naptr:x-eduroam:radius.tls' directly.
.RE

.BI "ServerName " servername
.RS
Use \fIservername\fR for the certificate name check instead of \fBhost\fR or the
server block name (e.g. if \fBhost\fR uses static IP address). Additionally, this 
name is used for SNI (if enabled), unless \fBSNIservername\fR is set.
.RE

.BR "SNI (" on | off )
.RS
Override gobal SNI setting (see above). This is implicitly enabled if \fBSNIservername\fR
is set.
.RE

.BI "SNIservername " sni
.RS
Explicitly set the \fIsni\fR to request from the server, in case the server is specified
by IP address or to override the hostname. Implicitly enables \fBSNI\fR for this server.
.RE

.BI "PSKkey " key
.br
.BI "PSKidentity " identity 
.RS
The meaning of these options are very similar as for the client block, with minor differences.
.br
- The \fIidentity\fR must always be provided and cannot be derived from the \fBserver \fIname\fR.
.br
- For the key derivation hash function, the hash function of the first cipher in the \fBCipherSuites\fR
of the referenced \fBtls\fR block is used.
.RE

.BR "StatusServer (" on | off | minimal | auto )
.RS
Enable the use of status-server messages for this server (default \fBoff\fR).  If
statusserver is enabled (\fBon\fR), the proxy will send regular status-server
messages to the server to verify that it is alive. Status tracking of the server
will solely depend on status-server message and ignore lost requests. This
should only be enabled if the server supports it. With the option \fBminimal\fR
status-server messages are only sent when regular requests have been lost and no
other replies have been received.

The option \fBauto\fR tries to detect whether the other server supports
status-server. If so, status-server messages are enabled in \fBminimal\fR mode.
.RE

.BI "RetryCount " count
.RS
Set how many times the proxy should retry sending a request to the server. Default is 2 retries for
UDP and DTLS. For TCP and TLS it is always 0.
.br
Retries from radius clients are ignored and radsecproxy performs its own retry handling 
since the requiremets differ when switching transport protocols.
.RE

.BI "RetryInterval " interval
.RS
Set the interval between each retry. Default is 5s.
.RE

.BI "IdleTimeout " seconds
.RS
After \fIseconds\fR without any traffic (except status-server), connections to this server
are closed.
.br
Default 600s for dynamically discovered servers, never (0) for static servers.
.RE

.BI "Rewrite " rewrite
.RS
This option is deprecated. Use \fBrewriteIn\fR instead.
.RE

.BI "RewriteOut " rewrite
.br
.BI "RewriteIn " rewrite
.RS
Apply the operations in the specified \fIrewrite\fR block on outgoing (request)
or incoming (response) messages to/from this server. Rewriting outgoing messages is
done after, incoming before other processing. If the \fBRewriteIn\fR is not
configured, the rewrite blocks \fBdefaultServer\fR or \fBdefault\fR will be
applied if defined. No default blocks are applied for \fBRewriteOut\fR.
.RE

.BR "LoopPrevention (" on | off)
.RS
This overrides the global \fBLoopPrevention\fR option for this server.
See section
\fBBASIC OPTIONS\fR for details on this option.
.RE

.BR "BlockingStartup (" on | off)
.RS
Start the dynamic server in blocking mode (default off), treating it as if it was already 
connected and enqueue requests to this server. Queued requests will be sent out when the 
connection is established. If however the dynamic lookup or the connection fails, the queued
requests will be lost.
(This is only considered for dynamic lookup servers. Ie when DynamicLookupCommand is specified)
Warning: when the dynamic lookup and connection process is slow, this wil block the 
respective realm for that time.
.RE

.BI "DTLSForceMTU " mtu
.RS
Some non-Linux platforms are unable to query the MTU of a connection, causing DTLS to limit
itself to 256 bytes and thus failing to connect. Manually set \fImtu\fR to a large enough value
so the initial DTLS client-hello fits without fragmentation. 
.RE

.BR "RequireMessageAuthenticator (" on | off )
.RS
Require all responses to Access-Requests be signed with a Message-Authenticator.
.br
This should always be be enabled unless the server is known to only support legacy RADIUS/UDP behavior.
.br
This setting is ignored when using TLS/DTLS transport.
.RE

The meaning and syntax of the following options are exactly the same as for the client
block. The details are not repeated here. Please refer to the definitions in the \fBCLIENT BLOCK\fR section.

.BR "IPv4Only (" on | off )
.br
.BR "IPv6Only (" on | off )
.br
.BI "Type " type
.br
.BI "Secret " secret
.br
.BI "TLS " tls
.br
.BR "CertificateNameCheck (" on | off )
.br
\fBMatchCertificateAttribute \fR...
.br
.BR "AddTTL " 1-255
.br
.BR "TCPKeepalive (" on | off )


.SH "REALM BLOCK"
.nf
.BI "realm (" \fR* | realm |\fR/ regex\fR/ ) "\fR {"
	...
}
.fi
.PP
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.

The allowed options in a realm block are:

.BI "Server " server
.br
.BI "AccountingServer " server
.RS
Specify the \fIserver\fR to which requests for this realm should be forwarded.
\fIserver\fR references a previously defined \fBserver\fR block (see the
\fBSERVER BLOCK\fR section). Each \fBserver\fR and \fBaccountingServer\fR can be
specified multiple times, or omitted completely. If no \fBserver\fR is
configured, the proxy will deny all Access-Requests for this realm. If no
\fBaccountingServer\fR is configured, the proxy will silently ignore all
Accounting-Requests for this realm. See the \fBSERVER SELECTION\fR section below
for details.
.RE

.BR "AccountingResponse (" on | off )
.RS
Enable sending Accounting-Response instead of ignoring Accounting-Requests when
no \fBaccoutingServer\fR are configured.
.RE

.BR "AccountingLog (" on | off )
.RS
When responding to Accounting-Requests (\fBAccountingResponse on\fR), log the 
accounting data.
.RE

.BI "ReplyMessage " message
.RS
Specify a message to be sent back to the client if a Access-Request is denied
because no \fBserver\fR are configured.
.RE

.SS "REALM BLOCK NAMES AND MATCHING"
In the general case the proxy will look for a \fB@\fR in the username attribute,
and try to do an exact, case insensitive match between what comes after the @
and the name of the realm block. So if you get a request with the attribute
value anonymous@example.com, the proxy will go through the realm names in the
order they are specified, looking for a realm block named example.com.

There are two exceptions to this, one is the realm name \fB*\fR which means
match everything. Hence if you have a realm block named *, then it will always
match. This should then be the last realm block defined, since any blocks after
this would never be checked. This is useful for having a default.

The other exception is regular expression matching. If the realm name starts
with a \fB/\fR, the name is treated as an regular expression. A case insensitive
regexp match will then be done using this regexp on the value of the entire
Username attribute. Optionally you may also have a trailing / after the regexp.
So as an example, if you want to use regexp matching the domain example.com you
could have a realm block named /@example\e.com$/. If you want to match all
domains under the \.com top domain, you could do /@.*\e.com$/. Note that since
the matching is done on the entire attribute value, you can also use rules like
/^[a\-k].*@example\e.com$/ to get some of the users in this domain to use one
server, while other users could be matched by another realm block and use
another server.

.SS "SERVER SELECTION"

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 the first server comes back up, it will go back to using that one.
Detection of servers being up or down is based on the use of StatusServer (if
enabled), and that TCP/TLS/DTLS connections are up. Otherwise unanswered
requests are used to detect unresponsive servers. AccountingServers are treated
the same, but independently of the other servers.

If there is no \fBServer\fR option (or all dynamic lookups have failed),
the proxy will if \fBReplyMessage\fR 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
\fBReplyMessage\fR option. Note that this is different from having no match
since then the request is simply ignored.  This can be used to catch all
undefined sub-domains or even all undefined realms by configuring either a regex
match like /@.*\e.example\e.com/ or the realm \fB*\fR with no server option.
Another use-case is to block a specific pattern in the username or realm part
using  a regex.

If there is no \fBAccountingServer\fR option, the proxy will normally do
nothing, ignoring accounting requests. If instead \fBAccountingResponse\fR is
set to on, the proxy will log some of the accounting information and send an
Accounting-Response back. This stops clients from retransmitting
Accounting-Request messages when a realm has no accountingServer configured.

.SH "TLS BLOCK"
.nf
.BI "tls " name "\fR {"
	...
}
.fi
.PP
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
\fBdefault\fR, \fBdefaultClient\fR and \fBdefaultServer\fR 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 \fBdefault\fR, 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 \fBdefaultClient\fR and \fBdefaultServer\fR. 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.

As both clients and servers need to present and verify a certificate, both a
certificate as well as a CA to verify the peers certificate  must be configured.

The allowed options in a tls block are:

.BI "CACertificateFile " file
.RS
The CA certificate file used to verify the peers certificate. The \fIfile\fR can
include multiple certificates as well as CRLs.
.RE

.BI "CACertificatePath " path
.RS
The path to search for CA or intermediate certificates and CRLs. All files must 
have hashed symbolic links to be found. See
.BR openssl-rehash (1).
.RE

.BI "CertificateFile " file
.RS
The server certificate this proxy will use. The file may also contain a
certificate chain. Any missing certificates to complete the chain will be searched
for in the \fBCACertificateFile\fR and \fBCACertificatePath\fR.
.RE

.BI "CertificateKeyFile " file
.RS
The private-key file for the server certificate specified in
\fBCACertificateFile\fR.
.RE

.BI "CertificateKeyPassword " password
.RS
The password to decrypt the private-key.
.RE

.BI "PolicyOID " oid
.RS
Require the peers certificate to adhere to the policy specified by \fIoid\fR.
When specified multiple times at least one policy must be valid in the peer
certificate.
.RE

.BR "CRLCheck (" on | off )
.RS
Enable checking peer certificate against the CRL (default off). Note if enabled, all
CAs in this context MUST provide a CRL, otherwise they are considered untrusted.
.br
Note that radsecproxy does not fetch the CRLs itself. This has to be done 
separately, e.g. with 
.BR fetch-crl (8)
.RE

.BI "CacheExpiry " seconds
.RS
Specify how many \fIseconds\fR the CA and CRL information should be cached. By
default, the CA and CRL are loaded at startup and cached indefinetely. After the
configured time, the CA and CRL are re-read. Alternatively, reloading the CA and CRL
can be triggered by sending a SIGHUP to the radsecproxy process. This option may
be set to zero to disable caching, but be warned: this might have a huge performance
impact.
.br
Any negative value will disable the cache expiry.
.RE

.BI "CipherList " ciphers
.RS
Specify the list of accepted \fIciphers\fR. See 
.BR openssl-ciphers (1).
.RE

.BI "CipherSuites " ciphersuites
.RS
Specify the \fIciphersuites\fR to be used for TLS1.3. See 
.BR openssl-ciphers (1).
.br
Note this requires OpenSSL 1.1.1
.RE

.BR "TlsVersion " (
.IR version " | " minversion : maxversion " )"
.br
.BR "DtlsVersion " (
.IR version " | " minversion : maxversion " )"
.RS
Specify the TLS/DTLS protocol \fIversion\fR to be used.
.br
Specify the range of allowed protocol versions between \fIminversion\fR and 
\fImaxversion\fR (inclusive). If either is left out, any version up to, or 
starting from this version is allowed. E.g. "TLS1_2:" will allow TLSv1.2 or later.
If omitted, use the system defaults set in openssl.conf
.br
Currently supported values are
.BR SSL3 , TLS1 , TLS1_1 , TLS1_2 , TLS1_3
for TLS and
.BR DTLS1 , DTLS1_2
for DTLS.
.RE

.BI "DhFile " file
.RS
DH parameter \fIfile\fR to use. See \fBopenssl-dhparam\fR(1)
.br
Note: starting with OpenSSL 3.0, use of custom DH parameters is discouraged.

.SH "REWRITE BLOCK"
.nf
.BI "rewrite " name "\fR {"
	...
}
.fi
.PP
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 \fBdefault\fR,
\fBdefaultClient\fR and \fBdefaultServer\fR 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 \fBdefault\fR, 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
\fBdefaultClient\fR and \fBdefaultServer\fR. Note that these defaults are only
used for rewrite on input. No rewriting is done on output unless explicitly
specified using the \fBRewriteOut\fR option.

The rewrite actions are performed in this sequence:
.RS
1. RemoveAttribute (or WhitelistAttribute)
.br
2. ModifyAttribute
.br
3. SupplementAttribute
.br
4. AddAttribute
.RE

All options can be specified multiple times. The allowed options in a rewrite
block are:

.BI "AddAttribute " attribute \fR: value
.RS
Add an \fIattribute\fR to the radius message and set it to \fIvalue\fR. The
\fIattribute\fR must be specified using the numerical attribute id. The
\fIvalue\fR can either be numerical, a string, or a hex value. If the value
starts with a number, it is interpreted as a 32bit unsigned integer.  Use the '
character at the start of the value to force string interpretation. When using
hex value, it is recommended to also lead with ' to avoid unintended numeric
interpretation. See the \fBCONFIGURATION SYNTAX\fR section for further details.
.RE

.BI "AddVendorAttribute " vendor \fR: subattribute \fR: value
.RS
Add a vendor attribute to the radius message, specified by \fIvendor\fR and
\fIsubattribute\fR. Both \fIvendor\fR and \fIsubattribute\fR must be specified
as numerical values. The format of \fIvalue\fR is the same as for \fBaddAttribute\fR above.
.RE

.BI "SupplementAttribute " attribute \fR: value
.RS
Add an \fIattribute\fR to the radius message and set it to \fIvalue\fR, only if
the  attribute is not yet present on the message.  The format of \fIvalue\fR is
the same as for \fBaddAttribute\fR above.
.RE

.BI "SupplementVendorAttribute " vendor \fR: subattribute \fR: value
.RS
Add a vendor attribute to the radius message only if the \fIsubattribute\fR of
this \fIvendor\fR is not yet present on the message. The format of is the same
as for \fBaddVendorAttribute\fR above.
.RE

.BI "ModifyAttribute " attribute \fR:/ regex \fR/ replace \fR/
.RS
Modify the given \fIattribute\fR using the \fIregex\fR \fIreplace\fR pattern. As
above, \fIattribute\fR must be specified by a numerical value. Example usage:

modifyAttribute 1:/^(.*)@local$/\e1@example.com/
.RE

.BI "ModifyVendorAttribute " vendor \fR: subattribute \fR:/ regex \fR/ replace \fR/
.RS
Modify the given \fIsubattribute\fR of given \fIvendor\fR using the \fIregex\fR
\fIreplace\fR pattern.  Other than the added vendor, the same syntax as for
\fBModifyAttribute\fR applies.
.RE

.BI "RemoveAttribute " attribute
.RS
Remove all attributes with the given id.
.RE

.BI "RemoveVendorAttribute " vendor [\fR: subattribute ]
.RS
Remove all vendor attributes that match the given \fIvendor\fR and
\fIsubattribute\fR. If the \fIsubattribute\fR is omitted, all attributes with
the given vendor id are removed.
.RE

.BR "WhitelistMode (" on | off )
.RS
Enable whitelist mode. All attributes except those configured with
\fBWhitelistAttribute\fR or \fBWhitelistVendorAttribute\fR will be removed.
While whitelist mode is active, \fBRemoveAttribute\fR and
\fBRemoveVendorAttribute\fR statements are ignored.
.RE

.BI "WhitelistAttribute " attribute
.RS
Do not remove attributes with the given id when \fBWhitelistMode\fR is on.
Ignored otherwise.
.RE

.BI "WhitelistVendorAttribute " vendor [\fR: subattribute ]
.RS
Do not remove vendor attributes that match the given \fIvendor\fR and
\fIsubattribute\fR when \fBWhitelistMode\fR is on. Ignored otherwise.

If the \fIsubattribute\fR is omitted, the complete vendor attribute is
whitelisted. Otherwise only the specified subattribute is kept but all other
subattributes are removed.
.RE

.SH "SEE ALSO"
\fBradsecproxy\fR(8)