NAME

radsecproxy.conf - Radsec proxy configuration file

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 /etc/radsecproxy.conf. The command line -c option can be used to instead read an alternate file (see radsecproxy(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.

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 option value. 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:

blocktype name {
	option value
	option value
	...
}

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 option value 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:

blocktype name {
#    option value


    option "value with space"


    ...
}

Option value characters can also be written in hex for options requiring a string type value. This is done by writing the character % followed by two hexadecimal digits. 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 regex. The POSIX extended RE system is used, see 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 Include 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.:

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

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.

PidFile file

LogLevel 1-5

LogDestination (file|syslog)

LogThreadId (on|off)

LogFullUsername (on|off)

LogMAC opt

LogKey key

FTicksReporting fticks

FTicksMAC opt

FTicksKey key

FTicksSyslogFacility syslog

FTicksPrefix prefix

ListenUDP (address|*)[:port]
ListenTCP (address|*)[:port]
ListenTLS (address|*)[:port]
ListenDTLS (address|*)[:port]

SourceUDP (address|*)[:port]
SourceTCP (address|*)[:port]
SourceTLS (address|*)[:port]
SourceDTLS (address|*)[:port]

TTLAttribute (attr|vendor:attr)

AddTTL 1-255

LoopPrevention (on|off)

IPv4Only (on|off)
IPv6Only (on|off)

Include file

BLOCKS

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

CLIENT BLOCK

client (name|fqdn|(address[/length])) {
	...
}

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 IPv4Only and IPv6Only 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 (CN or SubectAltName:DNS or SubjectAltName:IP respectively) and any MatchCertificateAttribute to be positively identified. Note that no FQDN/IP is checked when using an IP prefix. 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:

Host (fqdn|(address[/length]))

IPv4Only (on|off)
IPv6Only (on|off)

Type type

Secret secret

TLS tls

CertificateNameCheck (on|off)

MatchCertificateAttribute CN:/regexp/
MatchCertificateAttribute SubjectAltName:DNS:/regexp/
MatchCertificateAttribute SubjectAltName:URI:/regexp/
MatchCertificateAttribute SubjectAltName:IP:address
MatchCertificateAttribute SubjectAltName:rID:oid
MatchCertificateAttribute SubjectAltName:otherName:oid:/regexp/

DuplicateInterval seconds

AddTTL 1-255

TCPKeepalive (on|off)

FticksVISCOUNTRY cc

FticksVISINST institution

Rewrite rewrite

RewriteIn rewrite
RewriteOut rewrite

RewriteAttribute User-Name:/regex/replace/

SERVER BLOCK

server (name|((fqdn|address)[:port])) {
	...
}

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 IPv4Only and IPv6Only 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 fqdn or address 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.

The allowed options in a server block are:

Host (fqdn|address)[:port]

Port port

Source (address|*)[:port]

DynamicLookupCommand command

StatusServer (on|off|minimal|auto)

RetryCount count

RetryInterfval interval

Rewrite rewrite

RewriteOut rewrite
RewriteIn rewrite

LoopPrevention (on|off)

BlockingStartup (on|off)

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 CLIENT BLOCK section.

IPv4Only (on|off)
IPv6Only (on|off)
Type type
Secret secret
TLS tls
CertificateNameCheck (on|off)
MatchCertificateAttribute ...
AddTTL 1-255
TCPKeepalive (on|off)

REALM BLOCK

realm (*|realm|/regex/) {
	...
}

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:

Server server
AccountingServer server

AccountingResponse (on|off)

ReplyMessage message

TLS BLOCK

tls name {
	...
}

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 default, defaultClient and defaultServer 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 default, 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 defaultClient and defaultServer. 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:

CACertificateFile file

CACertificatePath path

CertificateFile file

CertificateKeyFile file

CertificateKeyPassword password

PolicyOID oid

CRLCheck (on|off)

CacheExpiry seconds

CipherList ciphers

CipherSuites ciphersuites

TlsVersion ( version | minversion:maxversion )
DtlsVersion ( version | minversion:maxversion )

DhFile file

REWRITE BLOCK

rewrite name {
	...
}

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 default, defaultClient and defaultServer 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 default, 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 defaultClient and defaultServer. Note that these defaults are only used for rewrite on input. No rewriting is done on output unless explicitly specified using the RewriteOut option.

The rewrite actions are performed in this sequence:

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

AddAttribute attribute:value

AddVendorAttribute vendor:subattribute:value

SupplementAttribute attribute:value

SupplementVendorAttribute vendor:subattribute:value

ModifyAttribute attribute:/regex/replace/

ModifyVendorAttribute vendor:subattribute:/regex/replace/

RemoveAttribute attribute

RemoveVendorAttribute vendor[:subattribute]

WhitelistMode (on|off)

WhitelistAttribute attribute

WhitelistVendorAttribute vendor[:subattribute]

SEE ALSO

radsecproxy(8)