Section 3.7. Global parameters

3.7.1. Foreground

If this parameter is set, it makes the server run in the foreground instead of as a detached daemon. No argument is required. The default behaviour is to run as a daemon. You must run in the foreground if you want to run Radiator in a console window, from inetd or restartWrapper. For more information, see file:/data/radiator-reference-manual/source/HighAvailabilityradiusd/UsingInetd_HighAvailability.dita#UsingInit_HighAvailability and file:/data/radiator-reference-manual/source/HighAvailabilityradiusd/UsingRestartWrapper_HighAvailability.dita#UsingRestartWrapper_HighAvailamility.

# Run in the foreground
Foreground

3.7.2. LogStdout

If this parameter appears, it makes all logging output appear on STDOUT as well as in the log file. No argument is required. The default behaviour is not to log to STDOUT. You must be running in Foreground mode for this to have an effect.

# Log to stdout
LogStdout

3.7.3. Trace

Sets the priority level of trace messages to be logged in the log file (and printed on stdout if LogStdout is defined). The argument is an integer from 0 to 5, with the following meanings:

0 ERR. Error conditions. Serious and unexpected failures
1 WARNING. Warning conditions. Unexpected failures
2 NOTICE. Normal but significant conditions
3 INFO. Informational messages
4 DEBUG. Debugging messages
5 EXTRA_DEBUG. Incoming raw packet dumps in hexadecimal

A trace level of 4 or more will produce all the possible tracing messages, including dumps of every RADIUS message received and sent: you probably do not want that in a production environment. The default tracing level is 0. You can change the current tracing level while Radiator is running on Unix platforms by signalling it with SIGUSR1 and SIGUSR2. For more information, see Section 4. Running radiusd.

# Show everything up to and including INFO level
Trace       3

3.7.4. LogTraceId

LogTraceId flag parameter allows logging messages related to an authentication exchange and to its subsequent accounting session with a tracing identifier. LogTraceId can be configured for global level and Log clause level. LogTraceId enables prepending a tracing ID to messages logged to STDOUT, when LogStdout is enabled, and to log file configured with

<Log
                     FILE>

and <Log SYSLOG>. For more information, see Section 3.7.2. LogStdout.

Tip

Support for using the same tracing identifier with accounting messages requires enabling parameter in the authenticating Handler clause. For more information, see Section 3.31.38. AutoClass.

Tracing ID works in conjunction with the Radiator load balancer allowing coordinated log message indexing and lookup between frontend load balancers and backend workers.

# Prepend tracing id to log messages
LogTraceId

3.7.5. LogRejectLevel

Log level for rejected authentication attempts. Can be overridden by Handler. Defaults to 3 (INFO).

3.7.6. AuthPort

Specifies which port(s) Radiator will listen on for RADIUS authentication requests. The argument may be either a numeric port number or an alphanumeric service name as specified in /etc/services/ (or its equivalent on your system). Multiple comma-separated ports may be specified. The default port is 1645. Note that the officially assigned port number for RADIUS authentication has been changed to 1812. AuthPort may contain special formatting characters. A typical use of special formatting characters is with GlobalVar and command line arguments.

# Listen for authentication requests on port 1812 as per RFC 
# 2865
AuthPort 1812

Note

Actually Radiator will also service accounting requests received on the authentication port without complaint.

Tip

You can prevent Radiator from binding to an authentication port by undefining AuthPort:

# Do not bind to an auth port:
AuthPort

Tip

You can pass any port number as a command line argument to radiusd with a configuration like this:

AuthPort %{GlobalVar:authport}

and then run radiusd with an argument to set the port number like this:

radiusd authport=1810 ...

Tip

You could listen for requests on the 2 most common RADIUS authentication port numbers with

AuthPort 1645,1812

Tip

Radiator will listen for requests on each given AuthPort (default 1645), on each IP address specified by BindAddress (default 0.0.0.0). For more information, see Section 3.5. Address binding.

3.7.7. AcctPort

Specifies which port Radiator will listen on for RADIUS accounting requests. The argument may be either a numeric port number or an alphanumeric service name as specified in /etc/services (or equivalent on your system). Multiple comma-separated ports may be specified. The default port is 1646. Note that the officially assigned port number for RADIUS accounting has been changed to 1813. AcctPort may contain special formatting characters. A typical use of special formatting characters is with GlobalVar and command line arguments.

# Listen for accounting requests on port 1813 as 
# per RFC 2866
AcctPort 1813

Note

Actually Radiator will also service authentication requests received on the accounting port without complaint.

Tip

You can prevent Radiator from binding to an accounting port by undefining Acct- Port:

# Do not bind to an accounting port:
AcctPort

Tip

You could listen for requests on the 2 most common RADIUS accounting port numbers with

AcctPort 1646,1813

Tip

Radiator will listen for requests on each given AcctPort (default 1646), on each IP address specified by BindAddress (default 0.0.0.0). For more information, see Section 3.5. Address binding.

3.7.8. KeepSocketsOnReload

Note

This option was introduced in Radiator 4.13 and is currently considered experimental.

This optional flag controls whether opened RADIUS listen sockets should be left intact on a reload request. When enabled, the changes in BindAddress, AuthPort and AcctPort are ignored during reload. You may consider enabling this option when incoming RADIUS requests should be buffered during the reload instead of ICMP unreachable messages being sent back to the RADIUS clients.

3.7.9. BindAddress

This optional parameter specifies one or more IPv4 and IPv6 addresses to listen for RADIUS requests on. It is only useful if you are running Radiator on a multi-homed host (i.e. a host that has more than one network address). Defaults to 0.0.0.0 (i.e. listens on all IPv4 networks connected to the host). Multiple addresses can be separated with a comma. Radiator will listen for requests on each AuthPort and AcctPort on each BindAddress address.

Using this parameter, you can run multiple instances of Radiator on the one computer, where each Radiator listens to RADIUS requests directed to a different host address. BindAddress can include special formatting characters and multiple IPv4 and IPv6 addresses.

# Only listen on one network address
BindAddress 203.63.154.1

You can listen for requests on only some of many multi-homed addresses on this host:

BindAddress 200.10.5.4,200.10.7.3,::1

You can listen for requests directed to a particular IPv6 address:

BindAddress 2001:db8:0100:f101:0210:a4ff:fee3:9566

For more information, see Section 3.6. IPv6 support. Also see Section 3.7.10. BindV6Only for more about IPv6 wildcard address :: special handling.

3.7.10. BindV6Only

This optional parameter allows you to explicitly set the IPV6_V6ONLY option for the sockets listening to IPv6 wildcard address.

RFC 3493 “Basic Socket Interface Extensions for IPv6” specifies a boolean socket option IPV6_V6ONLY. When this option is turned off, IPv6 wildcard listen socket can receive both IPv6 and IPv4 packets. Received IPv4 packets use special IPv4-mapped address format where the IPv4 address is encoded after the 96-bit prefix 0:0:0:0:FFFF.

For example, request from IPv4 address 172.16.172.2 is mapped to IPv6 address ::ffff:172.16.172.2. In this case you may need to configure your Client clause as

<Client
                     ::ffff:172.16.172.2>

IPV6_V6ONLY socket option is by default turned on by some operating systems and off by some others.

Perl 5.16 or later or recent enough Socket.pm CPAN module is required for this parameter.

For more information about IPv6 support and address binding, see Section 3.6. IPv6 support and Section 3.7.9. BindAddress.

Note

This parameter covers only RADIUS authentication and accounting sockets up to Radiator 4.24. Starting with 4.25 it was expanded to other TCP, SCTP and UDP listen sockets Radiator creates.

3.7.11. DbDir

Specifies the directory to be used for user database files. Defaults to /usr/local/etc/raddb on Unix and Windows. For convenience, the DbDir directory name can be referred to as %D in any file name path in this configuration file.

# Look in /opt/etc/raddb for username database
DbDir /opt/etc/raddb

3.7.12. LogDir

Specifies the directory to be used to store log files. Defaults to /var/log/radius on Unix and Windows. For convenience, the LogDir directory name can be referred to as %L in any file name path in this configuration file.

# Put log files in /opt/radius instead
LogDir /opt/radius

3.7.13. LogFile

This defines the name of the log file. All logging messages are time stamped and written to this file. Each time this file is written to by Radiator, it opens, writes, and then closes the file. This means that you can safely rotate the log file at any time. The file name can include special path name characters. For more information about special characters, see Section 3.3. Special formatters. The default is %L/logfile, i.e. a file named logfile in LogDir. For more information, see Section 3.7.12. LogDir.

Here is an example of using LogFile and special characters:

# Log file goes in /var/log, with year number
LogFile /var/log/%Y-radius.log

You can disable all logging to the log file by setting LogFile to be the empty string:

# Disable logging to log file completely
LogFile

If the file name starts with a vertical bar character | then the rest of the filename is assumed to be a program to which the output is to be piped. Otherwise the output is appended to the named file.

# Pipe to my-log-prog
LogFile |/usr/local/bin/my-log-prog

Note

If LogFile is defined in your configuration file, <Log FILE> is invisibly created to handle it. For more information, see Section 3.25. <Log FILE>. You can customise the logging format, and also log microseconds by using <Log FILE> and its parameters instead of LogFile.

3.7.14. LogMicroseconds

For all configured loggers and the LogStdout logger, enables microseconds in the time stamp. LogMicroseconds requires Time::HiRes Perl module. If this module is not installed, the microseconds part in the time stamp will be all zeroes 000000. Time::HiRes is typically part of the Perl default installation or packaged separately on some systems such as Red Hat derived systems where the RPM is called perl-Time-HiRes

Tip

LogMicroseconds can also be enabled separately for specific loggers using the LogMicroseconds parameter in the respective Log clause.

3.7.15. PidFile

The name of the file where radiusd will write its process ID (PID) at start-up. Defaults to %L/radiusd.pid on Unix and Windows. The file name can include special path name characters as defined in Section 3.3. Special formatters. If the directory containing the file does not exist, it will attempt to create the directory first.

If PidFile is defined in configuration with no value, no file is written.

# So we do not conflict with another radiusd
PidFile /tmp/radiusd2.pid

3.7.16. DictionaryFile

The name of the RADIUS dictionary file. The dictionary file defines the names to be used for RADIUS attributes and their values. Its format is described in Section 9.1. Dictionary file. The file name can include special path name characters as defined in Section 3.3. Special formatters. It can also include multiple comma-separated file names. The default is %D/dictionary, i.e. a file called “dictionary” in DbDir. A dictionary file called “dictionary” that will work with most NASs and Terminal Servers is included in the Radiator distribution.

# Dictionary file is in the default installation directory
DictionaryFile /opt/radiator/radiator/dictionary

You can load the normal dictionary and locally configured dictionary with something like this:

# Need the old Ascend non-vendor-specific attributes too
DictionaryFile /opt/radiator/radiator/dictionary, %D/dictionary.local

3.7.17. ProxyUnknownAttributes

If this optional parameter is set, Radiator will forward attributes that are not present in the dictionary. Unknown attributes are not proxied by default.

3.7.18. DiameterDictionaryFile

This optional parameter specifies additional Diameter dictionary entries. The entries in DiameterDictionaryFile can replace or override any of the default entries hardwired into DiaDict.pm. Unlike DictionaryFile, only one dictionary file name can be specified. The Diameter dictionary is only used if you have a ServerDIAMETER clause in your configuration file. The file name can include special path name characters as defined in Section 3.3. Special formatters. The default is to use only the hardwired dictionary in DiaDict.pm.

DiameterDictionaryFile %D/my_private_diameter_attrs.dat

3.7.19. DictionaryReloadInterval

DictionaryReloadInterval is an optional parameter that sets an interval in seconds for checking whether the files defined by DictionaryFile have changed. If there are changes, all files are reloaded. Not enabled by default and the files are only loaded during server initialisation.

# Check every 30 minutes for dictionary changes
DictionaryReloadInterval 1800

3.7.20. Syslog

This parameter is now obsolete, and is replaced by the <Log SYSLOG> clause. For more information, see Section 3.26. <Log SYSLOG>.

3.7.21. LicenseFile

The name of the file from which radiusd reads its license configuration parameters. There is no default. The file name can include special path name characters as defined in Section 3.3. Special formatters. If the file does not exist, or Radiator is fully licensed, LicenseFile and its contents are ignored.

License configuration parameters are not needed with fully licensed Radiator. Only certain evaluation or locked configurations need these parameters, as instructed by Radiator sales.

# Read custom parameters for this evaluation license
LicenseFile %D/license.conf

3.7.22. SnmpgetProg

Specifies the full path name to the snmpget program. This optional parameter is only used if you are using Simultaneous-Use with a NasType of Livingston or any other NAS type that uses SNMP (see table in Section 3.14.35. NasType) in one of your Client clauses. Defaults to /usr/bin/snmpget.

Tip

You should use the snmpget from Net-SNMP

. Do not use the snmpget from CMU: its style of output is not understood by Radiator.

SnmpgetProg /usr/local/bin/snmpget

3.7.23. SnmpwalkProg

Specifies the full path name to the snmpwalk program. This optional parameter is only used if you are using Simultaneous-Use with a NasType of Ascend, CiscoVPDN or TigrisOld in one of your Client clauses. Defaults to /usr/bin/snmpwalk.

Tip

You should use the snmpwalk from Net-SNMP

. Do not use the snmpwalk from CMU: its style of output is not understood by Radiator.

SnmpwalkProg /usr/local/bin/snmpwalk

3.7.24. FingerProg

Specifies the full path name to an external finger program. This optional parameter is only used if you are using Simultaneous-Use with a NasType of Portslave, Ascend, Shiva, Computone or any other NAS type that uses finger (see table in Section 3.14.35. NasType) in any of your Client clauses. Defaults to using the standard Perl Net::Finger client that does not require an external program.

FingerProg /usr/local/bin/finger

3.7.25. PmwhoProg

Specifies the full path name to the pmwho program. This optional parameter is only used if you are using Simultaneous-Use with a NasType of TotalControl or any other NAS type that uses pmwho (see table in Section 3.14.35. NasType) in one of your Client clauses. Defaults to /usr/local/sbin/pmwho.

PmwhoProg /usr/local/bin/pmwho

3.7.26. LivingstonMIB

This optional parameter specifies the name of the Livingston SNMP MIB. It is only used if you are using Simultaneous-Use with a NasType of Livingston in one of your Client clauses. Defaults to .iso.org.dod.internet.private.enterprises.307

This parameter is deprecated and will not be supported in the future.

3.7.27. LivingstonOffs

Specifies the global default value of where the last S port is before the one or two ports specified in LivingstonHole are skipped (usually 22 for US, 29 for Europe). This optional parameter is only used if you are using Simultaneous-Use with a NasType of Livingston in one of your Client clauses. Defaults to 29.This value can be overridden on a per-Client basis by using LivingstonHole in a Client clause. For more information, see Section 3.14.43. LivingstonOffs.

3.7.28. LivingstonHole

Specifies the global default value of the size of the hole in the port list (usually 1 for US, 2 for Europe) that occurs at LivingstonOffs. This optional parameter is only used if you are using Simultaneous-Use with a NasType of Livingston in one of your Client clauses. Defaults to 2. This value can be overridden on a per-Client basis by using LivingstonHole in a Client clause. For more information, see Section 3.14.44. LivingstonHole.

3.7.29. RewriteUsername

This is an optional parameter. It enables you to alter the username in authentication and accounting requests. For more details and examples, see Section 8. Rewriting user names.

3.7.30. SocketQueueLength

This optional parameter allows you to alter the lengths of the radius socket queues from their default Operating System specific value. You may wish to set the queue lengths to be longer than the default if your Radiator server is handling very large numbers of requests, and is near its performance limits. You should never need to set them to shorter than the default. SocketQueueLength affects the length of both the authentication and the accounting socket queues. SocketQueueLength has no effect on Windows.

Tip

You may need special privileges, or you may need to change your Operating System configuration to permit longer queue lengths than the default. Consult your operating system manuals for details on how to do this.

# Make a long queue length
SocketQueueLength 1000000

3.7.31. DefineFormattedGlobalVar

Defines a value for a global variable that can be accessed anywhere special formatting characters are permitted. The syntax is:

DefineFormattedGlobalVar variablename value

This example defines the global variable called variablename to be the string value. The value can be accessed where special formatting characters are permitted with %{GlobalVar:variablename}.

Within value, special formatting characters are permitted, so you can have one global variable that depends on another global variable.

In the following example, the log file will be called ./detail-server1:

DefineFormattedGlobalVar servername server1
LogFile ./detail-%{GlobalVar:servername}

3.7.32. DefineGlobalVar

Similar to DefineFormattedGlobalVar, except that special formatting characters in value are not honoured.

3.7.33. StartupHook

This optional parameter allows you to define a Perl function that will be called during server startup and restarts. Only one argument is passed to the hook: $_[0] will be set to undef during startup and 1 for a restart (usually due to a SIGHUP).

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your hook code will be reported to the log file at start-up time. Runtime errors in your hook will also be reported to the log file when your hook executes. Multiline hooks (i.e. with trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should not use trailing comments in your hook.

StartupHook can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change or set up environment variables, umasks etc.

# Set up a umask to use for the life of this process
StartupHook sub { umask(0222);}

3.7.34. ShutdownHook

This optional parameter allows you to define a Perl function that will be called just before exiting after receiving a SIGTERM. No arguments are passed.

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your hook code will be reported to the log file at start-up time. Runtime errors in your hook will also be reported to the log file when your hook executes. Multiline hooks (i.e. with trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should not use trailing comments in your hook.

ShutdownHook can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change or set up environment variables, umasks etc.

# Delete a lock file
ShutdownHook sub { unlink '/tmp/xyzzy.lck';}

3.7.35. DelayedShutdownTime

DelayedShutdownTime instructs radiusd to delay restart or termination for the configured time. When the configured time has passed, restart or termination is done when there are no more requests to serve from the sockets.

The delay has two phases:

Wait for the configured amount of seconds before the requested restart or termination action is started.
Serve the remaining requests from the incoming sockets.

This allows radiusd to process any queued requests before restart or termination.

For more information, see Section 3.7.36. DelayedShutdownHook.

# When shutdown is triggered, wait for Radius clients to stop sending
DelayedShutdownTime 5

3.7.36. DelayedShutdownHook

DelayedShutdownHook is called immediately when radiusd is signalled to restart or terminate, and DelayedShutdownTime has been set. This hook can, for example, signal upstream proxies about the impending shutdown.

For more information, see Section 3.7.35. DelayedShutdownTime. DelayedShutdownHook is passed the following argument:

String variable that defines the action. Either restart or termination

# Tell NASes to stop sending traffic to us
DelayedShutdownHook file:"%D/delayed-shutdown-hook.pl"

3.7.37. PreClientHook

This optional parameter allows you to define a Perl function that will be called during packet processing. PreClientHook is called for each request before it passed to a Client clause. A reference to the current request is passed as the only argument.

CAUTION

At the time this hook is run, integer attributes have not yet been unpacked and decoded, and encrypted attributes have not yet been decrypted. If you need unpacked, decrypted versions of these attributes, consider using a per-client ClientHook instead.

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your hook code will be reported to the log file at start-up time. Runtime errors in your hook will also be reported to the log file when your hook executes. Multiline hooks (i.e. with trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should not use trailing comments in your hook.

PreClientHook can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change the contents of the current request or many other things. The current request has its {Client} member set to a pointer to the Client clause handling the request.

# Fake a new attribute into the request
PreClientHook sub { ${$_[0]}->add_attr('test-attr', \
      'test-value');}

3.7.38. ClientHook

This hook will be called for each request after the request has been decoded but before any other per-Client processing is done. A reference to the current request is passed as the first argument and the Client object as the second argument.

3.7.39. HandlerFindHook

Specifies an optional Perl hook that can be used to avoid linear Handler lookup when there are multiple Handlers. This is advantageous for configurations, such as proxying based on realm, where maximum packet throughput is required. The hook is expected to return the Handler to use or nothing. If nothing is returned, lookup continues as defined by Section 3.31. <Handler attribute=value,attribute=value, ....>.

The hook is passed the following arguments

$_[0] A reference to the current RADIUS request
$_[1] Current username without realm part
$_[2] Realm part of the username, if any

HandlerFindHook is not set by default. See goodies/handler-find-hook.cfg for a configuration sample.

3.7.40. USR1Hook

This optional parameter allows you to define a Perl function that will be called when a SIGUSR1 signal is received by Radiator. On Unix, SIGUSR1 normally increases the logging level by 1. If you define a USR1Hook, your hook will be called instead.

3.7.41. USR2Hook

This optional parameter allows you to define a Perl function that will be called when a SIGUSR2 signal is received by Radiator. On Unix, SIGUSR2 normally decreases the logging level by 1. If you define a USR2Hook, your hook will be called instead.

3.7.42. WINCHHook

This optional parameter allows you to define a Perl function that will be called when a SIGWINCH signal is received by Radiator.

3.7.43. MainLoopHook

This optional parameter allows you to define a Perl function that will be called once per second from within the main dispatch loop.

3.7.44. UsernameCharset

This optional parameter checks that every user name consists only of the characters in the specified character set. This can be useful to reject requests that have user names that cannot be valid. The value of the parameter is a Perl character set specification. See your Perl reference manual for details about how to construct Perl character set specifications. Note that the some special characters must be escaped with a backslash. This parameter is not set by default and no character set check is done.

UsernameCharset is available as a global and Handler level parameter. The character set checks are done for both User-Name attribute and EAP identity.

When a request is processed by a Handler, User-Name attribute must pass both global and per Handler UsernameCharset checks. When an EAP-Response/Identity message is handled by an AuthBy, the EAP identity must pass both global and per Handler UsernameCharset checks. The Handler is the last Handler that processed the request before it was passed to the AuthBy.

This example permits only alphanumeric, period, underscore, the @-sign, and dash. Note that a dash at the end of character class needs not to be escaped with a backslash:

UsernameCharset a-zA-Z0-9._@-

3.7.45. User

On Unix, this optional parameter sets both the effective and real user ID (UID) that radiusd runs as, provided radiusd starts as a suitably privileged user, such as root. The value can be a valid Unix user name or an integer UID.

3.7.46. Group

On Unix, this optional parameter sets both the effective and real group ID (GID) and supplementary groups that radiusd runs as, provided radiusd starts as a suitably privileged user, such as root. The value can be a comma-separated list of valid Unix group names or integer GIDs. The first group is set as the effective group ID.

If any of the group names fail to resolve, the call to change the groups is not done.

3.7.47. MaxChildren

Specifies the maximum number of Fork children permitted at any one time. Any attempt by an AuthBy to Fork (if so configured) will fail and the RADIUS request will be ignored if there are already that many Forked children in existence. Defaults to 0, meaning no limit.

3.7.48. SnmpNASErrorTimeout

This optional parameter specifies for how long (in seconds) SNMP simultaneous use checks will be blocked after an SNMP error during communications with a given NAS. Defaults to 60 seconds.

3.7.49. ForkClosesFDs

This optional parameter tells Radiator to forcibly close all the child processes files descriptors after a fork() on Unix. This is only necessary in very unusual circumstances where child processes interfere with the parents connections to an SQL database.

3.7.50. ResponseTimeThreshold

ResponseTimeThreshold tells Radiator to log a warning when the processing time exceeds configured millisecond threshold. The warning contains the request's User-Name and information about the Client, Handler, and the AuthBy that processes the request.

# Log if request handling takes more than 0.1 seconds
ResponseTimeThreshold 100

3.7.51. GlobalMessageLog

This optional parameter defines the Identifier of global MessageLog clause to log all Radius, Diameter, and TACACS+ protocol requests. This parameter is not set by default and no message logging is done.

You can specify multiple GlobalMessageLog parameters, typically one for each protocol. The general format is:

GlobalMessageLog protocol, identifier[, extras
                     ...]

protocol defines the protocol. The possible values are:
- radius
- radsec
- diameter
- tacacsplus
identifier is the Identifier or the MessageLog clause that does the logging.
extras is currently unused.

For more information about MessageLog clauses, see Section 3.130. <MessageLog xxxxxx>.

Here is an example of using GlobalMessageLog:

# Log all RADIUS and Diameter messages with separage MessageLog clauses
GlobalMessageLog radius,messagelograd
GlobalMessageLog diameter,messagelogdia

Note

In Radiator 4.20 or later, radius protocol does not include the messages sent and received over RadSec. To log these messages, define the protocol as radsec.

3.7.52. FarmSize

This optional parameter allows you to specify how many server instances to create in a server farm. A server farm can improve performance in some cases on Unix platforms that support fork system call.

A server farm is a set of identical Radiator servers, all monitoring the same RADIUS sockets. Incoming RADIUS requests are distributed among the child servers in the server farm. The main server acts as a supervisor, and restarts children that die or are terminated. Defaults to not set, which means no server farm, and only a single instance of Radiator is run. When FarmSize is configured, a shared duplicate cache is also strongly recommended. For more information, see DupCache.

Tip

To log server farm instance, see special formatting parameter %O and configuration parameter LogFarmInstance.

CAUTION

This parameter, and the use of server farms is not compatible with many EAP protocols, such as EAP-TLS, EAP-TTLS, PEAP etc. This is because such protocols rely in authentication state being held within each server process, and it is necessary for all the requests for such protocols to go to the same Radiator instance.

3.7.53. LogFarmInstance

LogFarmInstance flag parameter allows logging server farm instance number of a worker. LogFarmInstance can be configured for global level and Log clause level. LogFarmInstance enables prepending server farm instance number to the messages logged to STDOUT, when LogStdout is enabled, and to log file configured with <Log FILE> and

<Log
                     SYSLOG>

. For more information, see Section 3.7.2. LogStdout.

Tip

This parameter is typically enabled when FarmSize parameter is set. When FarmSize is set, the farm supervisor logs with instance number 0. When FarmSize is not set, instance number is always 0.

# Enable server farm and prepend farm instance number to log messages
FarmSize 5
LogFarmInstance

3.7.54. FarmChildHook

Perl hook that is run in each child when FarmSize is used. The hook is run when the child is started or restarted.

3.7.55. DupCache

This optional parameter defines if duplicate cache is implemented locally within the process, shared between processes with mmapped memory or if a Gossip cluster will provide a global shared cache for detecting duplicate requests. When FarmSize is configured, using a shared duplicate cache is strongly recommended. Defaults to local.

For more about Gossip, see Section 3.133. <GossipRedis> and the configuration sample goodies/farmsize.cfg.

Possible values are:

local: Local to each process. The duplicate cache is not shared
shared: Shared between processes on the same server. Requires Cache::FastMmap Perl module.
global: Shared between processes using the Gossip framework

# See DupCacheFile for the shared file location
DupCache shared

3.7.56. DupCacheFile

DupCacheFile sets the shared memory based cache file name. Special characters are allowed. %0 is replaced by -pid-timestamp-random where the actual values are generated dynamically. Perl module Cache-FastMmap is required.

Defaults to /tmp/radiator-dupcache-sharefile%0 or C:\radiator-dupcache-sharefile%0 on Windows.

CAUTION

DupCacheFile should be readable only by Radiator process. It contains the sent RADIUS reply messages which may include sensitive information.

# For example: /var/run/radiator/hashbalance-dupcache-38479-1473082581-9264
DupCacheFile /var/run/radiator/hashbalance-dupcache%0

3.7.57. EAP_UseState

EAP_UseState, currently set to off by default, enables or disables the use of State attribute with EAP for the whole server.

If your configuration uses <AuthBy EAPBALANCE>, consider switching to another AuthBy, such as <AuthBy HASHALANCE>, to avoid adding a second State in the proxied requests.

Here is an example of using EAP_UseState:

# Use State attribute for identifying all EAP authentication conversations
EAP_UseState

3.7.58. Identifier

This allows you to assign a symbolic name to a radiusd server instance, similar to Identifier for an AuthBy, Handler, and any other clause. This allows hooks, logging, Gossip framework, and other code to use a name that uniquely identifies a radiusd instance. The global Instance parameter does not have a value by default. Special formatting characters are supported.

# Set identifier based on the hostname and server farm instance number
Identifier Radiator-%h-%O

Note

A 32 hex character long hash is calculated from the formatted Identifier for possible later use. This fixed length value can be accessed from hooks and other custom code.

3.7.59. DisableMTUDiscovery

If this optional parameter is set, it disables MTU discovery on platforms that support that behaviour (currently Linux only). This can be used to prevent discarding of certain large RADIUS packet fragments on supporting operating systems.

3.7.60. PacketDumpOmitAttributes

This optional parameter specifies a comma separated list of RADIUS attribute names which will be omitted from RADIUS packet dumps in logs.

PacketDumpOmitAttributes EAP-Message,User-Password

3.7.61. StatusServer

Normally, when a Status-Server request is received, Radiator replies with some statistics including the total number of requests handled, the current request rate and so on. You can control Status-Server response by setting StatusServer to one of the following values:

off
Status-Server requests are ignored.
minimal
Reply without any attributes.
default
Reply with statistics.

3.7.62. DisabledRuntimeChecks

Radiator tries to check for commonly required but missing modules, some known security vulnerabilities and possible other runtime parameters when it starts up. Any Hooks may also call the runtime check module functions, as required by the Hook authors. Special formatting characters are supported.

Any checks that do not pass are logged but no other action is taken.

The currently recognised built-in checks are:

CVE-2014-0160 - the OpenSSL vulnerability commonly called Heartbleed
Digest::MD4 - MD4 is required by MSCHAP and MSCHAP-v2 and their derivatives

The optional DisabledRuntimeChecks parameter allows you to define the checks that should not be run.

Check for CVE-2014-0160 is done by trying to load Net::SSLeay and using the functions it provides to check for vulnerable OpenSSL versions. Many vendors have patched their OpenSSL for CVE-2014-0160 without changing the OpenSSL version number. For this reason the check may report your OpenSSL as vulnerable. The Net::SSLeay functions for reporting OpenSSL version are only present in recent Net::SSLeay versions. For this reason Radiator may log a message about version check not being able to determine OpenSSL version.

Digest::MD4 is required by MSCHAP, MSCHAP-V2 and their derivatives such as EAP-MSHCHAP-V2. We recommend having Radiator Radius::UtilXS or Digest::MD4 installed unless you are sure you will never need to support these authentication protocols. See Section 2.1.9. Radiator Radius::UtilXS and Section 2.1.5. MD4 digest for MSCHAP and MSCHAPv2 for more information.

# Our OpenSSL is patched but still reports vulnerable version
DisabledRuntimeChecks CVE-2014-0160

3.7.63. PBKDF2_MinRounds

This is an integer that defines the minimum number of rounds PBKDF2 algorithm. If the stored user password uses less rounds than this parameter specifies, the password check fails. The default value is 100.

3.7.64. PBKDF2_MaxRounds

This is an integer that defines the maximum number of rounds PBKDF2 algorithm. If the stored user password uses more rounds than this parameter specifies, the password check fails. The default value is 200000.