4.1 Run-Time Configuration Options — ‘raddb/config’

At startup radiusd obtains its configuration values from three places. The basic configuration is kept in the executable module itself. These values are overridden by those obtained from ‘raddb/config’ file. Finally, the options obtained from the command line override the first two sets of options.

When re-reading of the configuration is initiated either by SIGHUP signal or by SNMP channel any changes in the config file take precedence over command line arguments, since ‘raddb/config’ is the only way to change configuration of the running program.

This chapter discusses the ‘raddb/config’ file in detail.

The ‘raddb/config’ consists of statements and comments. Statements end with a semicolon. Many statements contain a block of sub-statements which also terminate with a semicolon.

Comments can be written in shell, C, or C++ constructs, i.e. any of the following represent a valid comment:

# A shell comment
/* A C-style
 * multi-line comment
 */
// A C++-style comment

These are the basic statements:

4.1.1 option block

Syntax:

option {
 source-ip number ; 
 max-requests number ; 
 radiusd-user string ; 
 exec-program-user string ; 
 username-chars string ; 
 log-dir string ; 
 acct-dir string ; 
 resolve bool ; 
 max-processes number ; 
 process-idle-timeout number ; 
 master-read-timeout number ; 
 master-write-timeout number ; 
} ;

Usage

The option block defines the global options to be used by radiusd.

Boolean statements

resolve

Determines whether radius should resolve the IP addresses for diagnostic output. Specifying resolve no speeds up the server and reduces the network traffic.

Numeric statements

source-ip

Sets the source IP address. When this statement is not present, the IP address of the first available network interface on the machine will be used as source.

max-requests

Sets the maximum number of the requests in queue.

max-processes

Sets the maximum number of child processes. The default value is 16. If you plan to raise this value, make sure you have enough file descriptors available, as each child occupies four descriptors for its input/output channels.

process-idle-timeout

Sets the maximum idle time for child processes. A child terminates if it does not receive any requests from the main process within this number of seconds. By default, this parameter is 3600 seconds (one hour).

master-read-timeout

master-write-timeout

These two values set the timeout values for the interprocess input/output operations in the main server process. More specifically, master-read-timeout sets the maximum number of seconds the main process will wait for the answer from the subprocess, and master-write-timeout sets the maximum number of seconds the main process will wait for the subprocess's comunication channel to become ready for input. By default, no timeouts are imposed.

String statements

radiusd-user

Instructs radiusd to drop root privileges and to switch to the real user and group IDs of the given user after becoming daemon. Notice the following implications of this statement:

1. All configuration files must be readable for this user.
2. Authentication type System (see section System Authentication Type) requires root privileges, so it cannot be used with radiusd-user. Any ‘raddb/users’ profiles using this authentication type will be discarded.
3. Authentication type PAM (see section PAM Authentication Type) may require root provileges. It is reported to always require root privileges on some systems (notably on Solaris).
4. exec-program-user statement (see below) is ignored when used with radiusd-user.

exec-program-user

Sets the privileges for the programs executed as a result of Exec-Program and Exec-Program-Wait. The real user and group ids will be retrieved from the ‘/etc/passwd’ entry for the given user.

username-chars

Determines characters that are valid within a username. The alphanumeric characters are always allowed in a username, it is not necessary to specify them in this statement. By default the following characters are allowed in a username: ‘.-_!@#$%^&\/"’. The username-chars statement overrides this default, thus setting:

username-chars ":"

will restrict the set of allowed characters to the alphanumeric characters and colon. If you wish to expand the default character set, you will have to explicitly specify it in the username-chars argument, as shown in the example below:

username-chars ".-_!@#$%^&\\/\":"

(Notice the use of escape character ‘\’).

log-dir

Specifies the logging directory.

acct-dir

Specifies the accounting directory.

4.1.2 logging block

Syntax:

logging {
 prefix-hook string ; 
 suffix-hook string ; 
 category category_spec {
 channel channel_name ; 
 print-auth bool ; 
 print-pass bool ; 
 print-failed-pass bool ; 
 level debug_level ; 
 } ; 
 channel channel_name {
 file string ;
 syslog facility . priority [tag] ;
 print-pid bool ; 
 print-category bool ; 
 print-cons bool ; 
 print-level bool ; 
 print-priority bool ; 
 print-tid bool; 
 print-milliseconds bool; 
 prefix-hook string ; 
 suffix-hook string ; 
 }; 
} ;

Usage

The logging statement describes the course followed by radiusd's logging information.

The parts of this statement are discussed below.

4.1.2.1 Logging hooks

Most diagnostic messages displayed by radiusd describe some events that occured while processig a certain incoming request. By default they contain only a short summary of the event. Logging hooks are means of controlling actual amount of information displayed in such messages. They allow you to add to the message being displayed any relevant information from the incoming request that caused the message to appear.

A hook is a special Rewrite function that takes three arguments and returns a string. There are two kinds of logging hooks: prefix and suffix. Return value from the prefix hook function will be displayed before the actual log message, that of the suffix hook function will be displayed after the message.

Furthermore, there may be global and channel-specific hooks. Global hooks apply to all categories, unless overridden by category-specific hooks. Global prefix hook is enabled by prefix-hook statement appearing in the logging block. Global suffix hook is enabled by suffix-hook statement. Both statements take as their argument the name of corresponding Rewrite function.

For detailed information about writing logging hooks, See section Logging Hook Functions.

4.1.2.2 category statement

Each line of logging information generated by radiusd has an associated category. The logging statement allows each category of output to be controlled independently of the others. The logging category is defined by category name and a severity. category name determines what part of radiusd daemon is allowed to send its logging information to this channel. It can be any of main, auth, acct, proxy, snmp. priority determines the minimum priority of the messages displayed by this channel. The priorities in ascending order are: debug, info, notice, warn, err, crit, alert, emerg.

The full category specification, denoted by the category_spec in the above section, can take any of the following three forms:

category_name

Print the messages of given category.

priority

Print messages of all categories, abridged by given priority. If the priority is prefixed with ‘=’, only messages with given priority will be displayed. If it is prefixed with ‘!’, the messages with priority other than the specified will be displayed. Otherwise, the messages with priorities equal to or greater than the specified will be displayed.

category_name . priority

Print the messages of given category, abridged by given priority. The priority may be prefixed with either ‘=’ or ‘!’ as described above. The dot (‘.’) separates the priority from the category name, it may be surrounded by any amount of whitespace.

Additional category options valid for auth category are:

print-auth

Log individual authentications.

print-pass

Include passwords for successful authentications. It is very insecure, since all users' passwords will be echoed in the logfile. This option is provided only for debugging purposes.

print-failed-pass

Include passwords for failed authentications.

4.1.2.3 channel statement

Channels represent methods for recording logging information. Each channel has a unique name, and any categories which specify that name in a channel statement will use that channel.

radiusd can write logging information to files or send it to syslog. The file statement sends the channel's output to the named file (see section Naming Conventions). The syslog statement sends the channel's output to syslog with the specified facility and severity. Its optional last argument allows to alter default syslog tag.

Channel options modify the data flowing through the channel:

print-pid

Add the process ID of the process generating the logging information.

print-cons

Also send the logging information to the system console.

print-category

Add the category name to the logging information.

print-priority

print-level

Add the priority name to the logging information.

print-milliseconds

Print timestamp with milliseconds.

prefix-hook

Declares the name of Rewrite function used as logging prefix hook for that channel (see section Logging hooks). This overrides any global prefix hook.

suffix-hook

Declares the name of Rewrite function used as logging suffix hook for that channel (see section Logging hooks). This overrides any global suffix hook.

4.1.2.4 Example of the logging statement

logging {
 channel default {
 file "radius.log";
 print-category yes;
 print-priority yes;
 };
 channel info {
 file "radius.info";
 print-pid yes;
 print-cons yes;
 print-priority yes;
 };
 channel notice {
 syslog auth.notice;
 };
 category auth {
 print-auth yes;
 print-failed-pass yes;
 };
 category notice {
 channel notice;
 };
 category info {
 channel info;
 };
 category debug {
 channel info;
 level radiusd=1,files;
 };
 category *.!debug {
 channel default;
 };
};

4.1.3 auth statement

Syntax:

auth {
 listen ( addr-list | no ); 
 forward addr-list; 
 port number ; 
 max-requests number ; 
 time-to-live number ; 
 request-cleanup-delay number ; 
 detail bool ; 
 strip-names bool ; 
 checkrad-assume-logged bool ; 
 password-expire-warning number ; 
 compare-atribute-flag character ; 
 trace-rules bool ; 
 reject-malformed-names bool ; 
} ;

Usage:

The auth statement configures the parameters of the authentication service.

listen statement

This statement determines on which addresses radiusd will listen for incoming authentication requests. Its argument is a comma-separated list of items in the form ip:port-number. ip can be either an IP address in familiar “dotted-quad” notation or a hostname. :port-number part may be omitted, in which case the default authentication port is assumed.

If the listen statement is omitted, radiusd will accept incoming requests from any interface on the machine.

The special value no disables listening for authentication requests.

The following example configures radius to listen for the incoming requests on the default authentication port on the address 10.10.10.1 and on port 1645 on address 10.10.11.2.

listen 10.10.10.1, 10.10.11.2:1645;

forward statement

This statement enables forwarding of the requests to the given set of servers. Forwarding is an experimental feature of GNU Radius, it differs from proxying in that the requests are sent to the remote server (or servers) and processed locally. The remote server is not expected to reply.

This mode is intended primarily for debugging purposes. It could also be useful in some very complex and unusual configurations.

Numeric statements

port

Sets the number of which UDP port to listen on for the authentication requests.

max-requests

Sets the maximum number of authentication requests in the queue. Any surplus requests will be discarded.

time-to-live

Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue.

request-cleanup-delay

Sets the request cleanup delay in seconds, i.e. determines how long will the completed authentication request reside in the queue.

password-expire-warning

Sets the time interval for password expiration warning. If user's password expires within given number of seconds, radiusd will send a warning along with authentication-acknowledge response. Default is 0.

Boolean statements

detail

When set to true, radiusd will produce the detailed log of each received packet in the file ‘radacct/nasname/detail.auth’. The format of such log files is identical to the format of detailed accounting files (see section Detailed Request Accounting).

strip-names

Determines whether radiusd should strip any prefixes/suffixes off the username before logging.

checkrad-assume-logged

See section mlc statement, for the description of this setting. It is accepted in auth for compatibility with previous versions of GNU Radius.

trace-rules

Enables tracing of the configuration rules that were matched during processing of each received authentication request. See section Rule Tracing, for detailed information about this mode.

reject-malformed-names

Enables sending access-reject replies for the access-accept requests that contain an invalid value in User-Name attribute. By default such requests are discarded without answering. See the description of username-chars (see section Option statement).

Character statement

compare-attribute-flag

The argument to this statement is a character from ‘1’ through ‘9’. This statement modifies the request comparison method for authentication requests. See section Extended Comparison, for a detailed description of its usage.

4.1.4 acct statement

Syntax:

acct {
 listen ( addr-list | no ); 
 forward addr-list ; 
 port number ; 
 detail bool; 
 system bool;
 max-requests number ; 
 time-to-live number ; 
 request-cleanup-delay number ; 
 compare-atribute-flag character ; 
 trace-rules bool ; 
} ;

Usage:

The acct statement configures the parameters of the accounting service.

listen statement

This statement determines on which addresses radiusd will listen for incoming accounting requests. Its argument is a comma-separated list of items in the form ip:port-number. ip can be either an IP address in familiar “dotted-quad” notation or a hostname. :port-number part may be omitted, in which case the default accounting port is assumed.

If the listen statement is omitted, radiusd will accept incoming requests from any interface on the machine.

The special value no disables listening for accounting requests.

The following example configures radius to listen for the incoming requests on the default accounting port on the address 10.10.10.1 and on port 1646 on address 10.10.11.2.

listen 10.10.10.1, 10.10.11.2:1646;

forward statement

This statement enables forwarding of the requests to the given set of servers. Forwarding is an experimental feature of GNU Radius, it differs from proxying in that the requests are sent to the remote server (or servers) and processed locally. The remote server is not expected to reply.

This mode is intended primarily for debugging purposes. It could also be useful in some very complex and unusual configurations.

Numeric statements

port

Sets the number of which port to listen for the authentication requests.

max-requests

Sets the maximum number of accounting requests in the queue. Any surplus requests will be discarded.

time-to-live

Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue.

request-cleanup-delay

Sets the request cleanup delay in seconds, i.e. determines how long will the completed account request reside in the queue.

Boolean statements

detail

When set to no, disables detailed accounting (see section Detailed Request Accounting).

system

When set to no, disables system accounting (see section System Accounting). Notice, that this will disable simultaneous use checking as well, unless you supply an alternative MLC method (currently SQL, See section Multiple Login Checking, for the detailed discussion of this).

trace-rules

Enables tracing of the configuration rules that were matched during processing of each received accounting request. See section Rule Tracing, for detailed information about this mode.

Character statement

compare-attribute-flag

The argument to this statement is a character from ‘1’ through ‘9’. This statement modifies the request comparison method for authentication requests. See section Extended Comparison, for a detailed description of its usage.

4.1.5 usedbm statement

Syntax:

usedbm ( yes | no ) ;

Usage

The usedbm statement determines whether the DBM support should be enabled.

no

Do not use DBM support at all.

yes

Use only the DBM database and ignore ‘raddb/users’.

4.1.6 snmp statement

Syntax:

snmp {
 port portno ; 
 listen ( addr-list | no ); 
 max-requests number ; 
 time-to-live number ; 
 request-cleanup-delay number ; 
 ident string ; 
 community name ( rw | ro ) ; 
 network name network [ network ... ] ; 
 acl {
 allow network_name community_name ; 
 deny network_name ; 
 } ; 
 storage {
 file filename ; 
 perms number ; 
 max-nas-count number ; 
 max-port-count number ; 
 } ; 
};

Usage

The snmp statement configures the SNMP service.

listen statement

The listen statement determines on which addresses radiusd will listen for incoming SNMP requests. The argument is a comma-separated list of items in the form ip:port-number. The ip can be either an IP address in familiar “dotted-quad” notation or a hostname. The :port-number part may be omitted, in which case the default SNMP port (161) is used.

If the listen statement is omitted, radiusd will accept incoming requests from any interface on the machine.

The special value no disables listening for SNMP requests.

The following example configures radius to listen for the incoming SNMP requests on the default SNMP port on the address 10.10.10.1 and on port 4500 on address 10.10.11.2.

listen 10.10.10.1, 10.10.11.2:4500;

Numeric statements

port

Sets the number of which port to listen for the SNMP requests.

max-requests

Sets the maximum number of SNMP requests in the queue. Any surplus requests will be discarded.

time-to-live

Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue.

request-cleanup-delay

Sets the request cleanup delay in seconds, i.e. determines how long will the completed SNMP request reside in the queue.

String statements

ident

Sets the SNMP server identification string.

Community and network definitions

community name ( rw | ro )

Defines the community name as read-write (rw) or read-only (ro).

network name network [ network ... ]

Groups several networks or hosts under one logical network name.

Access-Control List definitions

allow network_name community_name

allow hosts from the group network_name access to community community_name.

deny NETWORK_NAME

Deny access to SNMP service from any host in the group network_name.

Storage control

GNU Radius stores the SNMP monitoring data in an area of shared memory mapped to an external file. This allows all subprocesses to share this information and to accumulate the statistics across invocations of the daemon.

The storage statement controls the usage of the storage for the SNMP data.

file

Sets the file name for the SNMP storage file. Unless the filename begins with a ‘/’ it is taken as relative to the current logging directory.

perms

Sets the access permissions for the storage file. Notice, that this statement does not interpret its argument as octal by default, so be sure to prefix it with ‘0’ to use an octal value.

max-nas-count

Sets maximum number of NASes the storage file is able to handle. Default is 512. Raise this number if you see the following message in your log file:

reached SNMP storage limit for the number of
monitored NASes: increase max-nas-count

max-port-count

Sets maximum number of ports the storage file is able to handle. Default is 1024. Raise this number if you see the following message in your log file:

reached SNMP storage limit for the number of
monitored ports: increase max-port-count

4.1.7 rewrite statement.

(This message will disappear, once this node revised.)

Syntax:

rewrite {
 stack-size number ; 
 load-path string ; 
 load string ; 
};

Numeric statements

stack-size

Configures runtime stack size for Rewrite. The number is the size of stack in words. The default value is 4096.

String statements

load-path

Add specified pathname to the list of directories searched for rewrite files.

load

Loads the specified source file on startup. Unless string is an absolute pathname, it will be searched in directories set up by load-path statement.

Loading

The default load path is ‘RADDB’:‘DATADIR’/rewrite.

4.1.8 guile statement

(This message will disappear, once this node revised.)

The guile statement allows to configure server interface with Guile.

Syntax

guile {
 debug bool ; 
 load-path string ; 
 load string ; 
 load-module string [ string ... ] ; 
 eval expression [ expression ... ] ; 
 gc-interval number ; 
 outfile string ; 
};

Usage

Boolean statements

debug

When set to yes, enables debugging evaluator and backtraces on Guile scripts.

Numeric statements

gc-interval

Configures the forced garbage collections. By default the invocation of the garbage collector is run by the internal Guile mechanism. However, you may force Radius to trigger the garbage collection at fixed time intervals. The gc-interval statement sets such interval in seconds.

For more information about Guile memory management system in general and garbage collections in particular, see (guile)Memory Management section `Memory Management and Garbage Collection' in The Guile Reference Manual.

String statements

eval

Evaluates its argument as Scheme expression.

load-path

Adds specified pathname to %load-path variable.

load

Loads the specified source file on startup.

load-module

Loads the specified Scheme module on startup. This statement takes an arbitrary number of arguments. The first argument specifies the name of the module to load, the rest of arguments is passed to the module initialization funtion. Module initialization function is a function named ‘module-init’, where module is the module name. Arguments are converted using usual Guile rules, except that the ones starting with a dash (‘-’) are converted to keyword arguments.

outfile

Redirects the standard output and standard error streams of the Guile functions to the given file. Unless the filename starts with ‘/’, it is taken relative to the current logging directory.

See section Guile, for a detailed description of Guile extensions interface.

4.1.9 message statement

The message statement allows to set up the messages that are returned to the user with authentication-response packets.

Syntax

message {
 account-closed string ; 
 password-expired string ; 
 password-expire-warning string ; 
 access-denied string ; 
 realm-quota string ; 
 multiple-login string ; 
 second-login string ; 
 timespan-violation string ; 
};

All variables in message block take a string argument. In string you can use the usual C backslash notation to represent non-printable characters. The use of %C{} and %R{} sequences is also allowed (see section Macro Substitution).

String statements

account-closed

This message will be returned to the user whose account is administratively closed.

password-expired

This message will be returned to the user whose password has expired.

password-expire-warning

This is a warning message that will be returned along with an authentication-acknowledge packet for the user whose password will expire in less than n seconds. The value of n is set by password-expire-warning variable in auth block. See section auth statement. In this string, you can use the %R{Password-Expire-Days} substitution, to represent the actual number of days left to the expiration date. The default is

Password Will Expire in %R{Password-Expire-Days} Days\r\n

access-denied

This message is returned to the user who supplies an incorrect password or a not-existent user-name as his authentication credentials.

realm-quota

This message is returned when the user is trying to log in using a realm, and number of users that are currently logged in from this realm reaches maximum value. For a description of realms, see Realms.

multiple-login

This message is returned to the user, who has logged in more than allowed number of times. For description of how to set the maximum number of concurrent logins, see Simultaneous-Use.

second-login

This is a special case of multiple-login, which is used when the user's login limit is 1.

timespan-violation

This message is returned to the user who is trying to login outside of allowed time interval. For description of how to limit user's login time, see Login-Time.

4.1.10 filters statement

The filters statement configures user-defined external filters. See section Filters, for the detailed discussion of external filters.

Syntax

filters {
 filter ident {
 exec-path path ;
 error-log filename ;
 common bool [max-wait];
 auth {
 input-format fmt ;
 wait-reply bool ;
 };
 acct {
 input-format fmt ;
 wait-reply bool ;
 };
 };
 …
};

Each filter directive defines a new filter. The ident argument declares the name of the filter. This string must be used in Exec-Program-Wait or Acct-Ext-Program attributes to trigger invocation of this filter (see section Exec-Program-Wait).

Usage

exec-path path

Absolute path to the filter program.

error-log filename

Redirect error output from the filter program to filename. If the filename does not start with a slash, it is taken relative to the current logging directory (see section log-dir).

auth

acct

These compound statements define authentication and accounting parts of this filter. Any one of them may be missing. The two statements allowed within auth and acct blocks are:

input-format fmt

Format of the input line for this filter. Usually this string uses %C{} notations (see section Macro Substitution).

You can also use the return value from a rewrite function as input line to the filter. To do so, declare:

 input-format "=my_func()";

where my_func is the name of the rewrite function to invoke. The function must return string value.

wait-reply bool

If the filter prints a single line of output for each input line, set this to yes. Otherwise, if the filter produces no output, use wait-reply no.

4.1.11 mlc statement

Syntax

mlc {
 method (system|sql); 
 checkrad-assume-logged bool;
};

Usage

Mlc statement configures multiple login checking subsystem (see section Multiple Login Checking).

method

Sets the method of retrieving information about the currently open sessions. Currently two methods are implemented. Setting method to system will use system accounting database (see section System Accounting). This is the default method. Setting it to sql will use SQL database.

checkrad-assume-logged

radiusd consults the value of this variable when the NAS does not responds to checkrad queries (see section Multiple Login Checking). If this variable is set to yes, the daemon will proceed as if the NAS returned “yes”, i.e. it will assume the user is logged in. Otherwise radiusd assumes the user is not logged in.

This document was generated by Sergey Poznyakoff on December, 6 2008 using texi2html 1.78.