NAME

DESCRIPTION

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

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

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

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). Note that this is not required when the client name is an IP prefix. If overlapping clients are defined (see section above), they will be searched for matching MatchCertificateAttribute, but they must reference the same tls block.

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 | SubjectAltName:URI | SubjectAltName:DNS ) :/regexp/
MatchCertificateAttribute SubjectAltName:IP:address

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

DynamicLookupCommand command

StatusServer (on|off|minimal|auto)

RetryCount count

RetryInterfval interval

Rewrite rewrite

RewriteOut rewrite
RewriteIn rewrite

LoopPrevention (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 ( CN | SubjectAltName:URI | SubjectAltName:DNS ) :/regexp/
MatchCertificateAttribute SubjectAltName:IP:address
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

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