4. Radius Configuration Files

At startup, GNU Radius obtains the information vital for its functioning from a number of configuration files. These are normally found in /usr/local/etc/raddb directory, which is defined at configuration time, although their location can be specified at runtime. In the discussion below we will refer to this directory by ‘raddb’. See section Naming Conventions.

Each configuration file is responsible for a certain part of the GNU Radius functionality. The following table lists all configuration files along with a brief description of their purposes.

‘config’

Determines the runtime defaults for radiusd, such as the IP address and ports to listen on, the sizes of the request queues, configuration of the SNMP subsystem, fine-tuning of the extension languages, etc.

‘clients’

Lists the shared secret belonging to each NAS. It is crucial for the normal request processing that each NAS have an entry in this file. The requests from NASes that are not listed in ‘clients’ will be ignored, as well as those from the NASes that have a wrong value for the shared secret configured in this file.

‘naslist’

Defines the types for the known NASes. Its information is used mainly when performing multiple login checking (see section Multiple Login Checking).

‘nastypes’

Declares the known NAS types. The symbolic type names, declared in this file can be used in ‘naslist’.

‘dictionary’

Defines the symbolic names for radius attributes and attribute values. Only the names declared in this file may be used in the files ‘users’, ‘hints’ and ‘huntgroups’.

‘huntgroups’

Contains special rules that process the incoming requests basing on the NAS IP and port number they come from. These can also be used as a kind of access control list.

‘hints’

Defines the matching rules that modify the incoming request depending on the user name and its credentials.

‘users’

Contains the individual users' profiles.

‘realms’

Defines the Radius realms and the servers that are responsible for them.

‘access.deny’

A list of usernames that should not be allowed access via Radius.

‘sqlserver’

Contains the configuration for the SQL system. This includes the type of SQL interface used, the IP and port number of the server and the definition of the SQL requests used by radiusd.

‘rewrite’

Contains the source code of functions in Rewrite extension language.

‘menus’

A subdirectory containing the authentication menus.

The rest of this chapter describes each of these files in detail.

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.

4.2 Dictionary of Attributes — ‘raddb/dictionary’

The dictionary file ‘raddb/dictionary’ defines the symbolic names for radius attributes and their values (see section Attributes). The file consists of a series of statements, each statement occupies one line.

In the detailed discussion below we use the following meta-syntactic characters:

number

Denotes a decimal, octal or hexagesimal number. Usual C conventions are honored, i.e. if number starts with ‘0x’ or ‘0X’ it is read as a hex number, if it starts with ‘0’ it is read as an octal number, otherwise it is read as a decimal one.

type

Denotes an attribute type. These are valid attribute types:

string

A string type.

integer

An integer type.

ipaddr

IP address in a dotted-quad form.

date

A date in the format: "MON DD CCYY", where MON is the usual three-character abbreviation, DD is day of month (1-31), CCYY is the year, including the century.

4.2.1 Comments

Comments are introduced by a pound sign (‘#’). Everything starting from the first occurrence of ‘#’ up to the end of line is ignored.

4.2.2 $INCLUDE Statement

Syntax

$INCLUDE ‘filename’

Usage

The $INCLUDE statement causes the contents of the file ‘filename’ to be read in and processed. The file is looked up in the Radius database directory, unless its name starts with a slash.

4.2.3 VENDOR Statement

Syntax

VENDOR  vendor-name vendor-id

Usage

A VENDOR statement defines the symbolic name vendor-name for vendor identifier vendor-id. This name can subsequently be used in ATTRIBUTE statements to define Vendor-Specific attribute translations. See section Vendor-Specific.

Example

VENDOR  Livingston  307

4.2.4 ATTRIBUTE statement

Syntax

ATTRIBUTE  name  number  type [vendor] [flags]

Usage

The ATTRIBUTE statement defines the internal representation of an attribute: its symbolic name, data type and syntactical usage. Its parts have the following meaning:

name

The attribute name.

number

The attribute ID (number).

type

The attribute type.

vendor

Vendor name for vendor-specific attributes. For usual attributes this field is empty or contains a dash (‘-’). The latter usage is for compatibility with previos version of GNU Radius

flags

Flags, defining attribute properties (see section Attributes).

The attribute property flags consist of a sequence of letters, whose meaning is determined by the following rules: (2)

1. The attribute usage is described by three pairs of symbols, enclosed in square brackets. Each pair describes how the attribute can be used in each of three configuration files. The first pair corresponds to ‘raddb/users’, the second one corresponds to ‘raddb/hints’, and the third one corresponds to ‘raddb/huntgroups’. Within each pair, the letter ‘L’ in first position means that the attribute is allowed in LHS of a rule. The letter ‘R’ in second position means that the attribute is allowed in RHS of a rule. The absence of any of these letters is indicated by dash (‘-’). Thus, the following usage specification:

   [L--RLR]

   means that the attribute may be used in LHS of a rule in ‘raddb/users’, in RHS of a rule in ‘raddb/hints’, and in both sides of a rule in ‘raddb/huntgroups’.

2. The attribute additivity is described by one of the following letters:

   =

   Additivity = Replace

   +

   Additivity = Append

   N

   Additivity = None

3. The presence of letter ‘P’ in property flags raises the propagation bit.
4. Letter ‘l’ (lower-case ell) enables logging the given attribute in detail file (see section Detailed Request Accounting). This is meaningful only for internal attributes, i.e. the ones whose decimal value is greater than 255 (see section Radius Internal Attributes). By default such attributes do not appear in detailed logs. The flag ‘l’ reverts this behavior.
5. Letter ‘E’ marks attributes encrypted as described in RFC 2138. Currently these are User-Password and CHAP-Password.
6. Letter ‘T’ marks attribute encrypted according to RFC 2868.
7. The characters from ‘1’ to ‘9’ denote nine user-defined flags (see section Extended Comparison).

Example

ATTRIBUTE  Service-Type  6 integer - [LR-RLR]=P 

This statement declares that the attribute number 6 will be referred to by the symbolic name ‘Service-Type’. The attribute is of integer data type and it may be used in any part of matching rules, except in LHS of a ‘raddb/hints’ rule. The additivity of Service-Type is set to ‘Replace’. The attribute will be propagated through the proxy chain.

4.2.5 Blocks of Vendor-Specific Attributes

Syntax

BEGIN VENDOR vendor-name [vendor-id]
…
END 

Usage

The BEGIN keyword marks start of the block of definitions of vendor-specific attributes. The block is terminated by END keyword, optionally followed by an arbitrary number of words, which are regarded as a comment. The block may contain any valid dictionary declarations, except other blocks: nesting of declaration blocks is not allowed.

If vendor-id is absent, the value of vendor ID is looked up in the internal table of vendors; therefore, it must be defined before BEGIN statement (see section VENDOR Statement).

BEGIN---END block alters the handling of ATTRIBUTE statements within it. If ATTRIBUTE statement does not contain an explicit vendor-id specification, the value of vendor-id is used instead.

For compatibility with FreeRadius an alternative syntax is also supported:

BEGIN-VENDOR vendor-name
…
END-VENDOR vendor-name

Such compatibility blocks must appear only ater the declaration of vendor-name (see section VENDOR Statement).

Example

The following is the usual way of definig vendor-specific attributes:

VENDOR          Livingston      307

ATTRIBUTE       LE-Terminate-Detail     2       string  Livingston
ATTRIBUTE       LE-Advice-of-Charge     3       string  Livingston

The following two examples show the alternative ways:

VENDOR Livingston 307
BEGIN VENDOR Livingston
ATTRIBUTE       LE-Terminate-Detail     2       string  
ATTRIBUTE       LE-Advice-of-Charge     3       string
END

BEGIN VENDOR Livingston 307
ATTRIBUTE       LE-Terminate-Detail     2       string  
ATTRIBUTE       LE-Advice-of-Charge     3       string
END

These three examples are completely equivalent to each other.

4.2.6 ALIAS statement

Syntax

ALIAS name  alt-name

Usage

The ALIAS statement defines an altenative name alt-name for attribute name. The latter should already be defined, otherwise an error occurs.

Example

ALIAS User-Password Password

4.2.7 PROPERTY statement

Syntax

PROPERTY  name  flags
PROPERTY  name  +flags [-flags ...]

Usage

The PROPERTY statement redefines property flags for attribute name. The attribute must be defined, otherwise an error occurs. The PROPERTY statement has two forms. In first form, it takes a single argument, representing new property flags for the attribute. In its second form it takes any number of arguments, each of them preceeded by ‘+’ sign, inidicating addition of properties, or by ‘-’ sign, indicating removal of these.

See section ATTRIBUTE statement, for the discussion of attribute property flags.

Example

The following example defines that the attribute User-Password may be used only on left-hand side of a ‘raddb/users’ entry, and that it is transmitted in encrypted form.

PROPERTY  User-Password [L-----]E

Next example illustrates adding and removing attribute properties:

PROPERTY  My-Attrib     +P -=

it adds propagation bit (‘P’) and removes ‘replace’ additivity from My-Attrib attribute.

4.2.8 VALUE Statement

Syntax

VALUE   Attribute-Translation       Value-Translation       number

Usage

The VALUE statement assigns a translation string to a given value of an integer attribute. Attribute-Translation specifies the attribute and the Value-Translation specifies the name assigned to the value number of this attribute.

Example

The following assigns the translation string ‘Login-User’ to the value 1 of the attribute ‘Service-Type’.

VALUE  Service-Type  Login-User  1

4.3 Clients List — ‘raddb/clients’

The ‘raddb/clients’ lists NASes which are allowed to make authentication requests. As usual, the ‘#’ character introduces a comment. Each record in the file consists of two fields, separated by whitespace. The fields are:

NAS name

Specifies a hostname or IP address of the NAS.

Key

Lists the encryption key shared between the server and this NAS.

If the set of NASes share the same encryption key, there are two ways to list it in ‘raddb/clients’. First, if these NASes lie in a single network, you can specify this network address in NAS name field, e.g.:

10.10.10.0/27   seCRet

Notice also that specifying full netmask after the ‘/’ character is also allowed, so that the above example could also be written as follows:

10.10.10.0/255.255.255.224   seCRet

Otherwise, the keyword DEFAULT may be used as NAS name. This notation will match any IP address, so it should be used with caution.

4.3.1 Example of ‘clients’ file

# This is a list of clients which are allowed to make authentication 
# requests.
# Each record consists of two fields:
#       i.  Valid hostname.
#       ii. The shared encryption key for this hostname. 
#
#Client Name            Key
#----------------       -------------------
myhost.dom.ain          guessme         
merlin                  emrys           
11.10.10.10             secRet

4.4 NAS List — ‘raddb/naslist’

The ‘raddb/naslist’ file contains a list of NASes known to the Radius server. Each record in the file consist of the following four fields, the first two being mandatory, the last two being optional:

NAS name

Specifies either a hostname or IP address for a single NAS or a CIDR net block address for a set of NASes. The word ‘DEFAULT’ may be used in this field to match any NAS. (3)

Short Name

This field defines a short name under which this NAS will be listed in logfiles. The short name is also used as a name of the subdirectory where the detailed logs are stored.

Type

Specifies the type of this NAS. Using this value radiusd determines the way to query NAS about the presence of a given user on it (see section Multiple Login Checking). The two special types: ‘true’ and ‘false’, can be used to disable NAS querying. When the type field contains ‘true’, radiusd assumes the user is logged in to the NAS, when it contains ‘false’, radiusd assumes the user is not logged in. Otherwise, the type is used as a link to ‘nastypes’ entry (see section NAS Types — ‘raddb/nastypes’).

If this field is not present ‘true’ is assumed.

Arguments

Additional arguments describing the NAS. Multiple arguments must be separated by commas. No intervening whitespace is allowed in this field.

There are two groups of nas arguments: nas-specific arguments and nas-querying arguments. Nas-specific arguments are used to modify a behavior of radiusd when sending or receiving the information to or from a particular NAS.

Nas-querying arguments control the way radiusd queries a NAS for confirmation of a user's session (see section Multiple Login Checking). These arguments override the ones specified in ‘nastypes’ and can thus be used to override the default values.

The nas-specific arguments currently implemented are:

broken_pass

This is a boolean argument that controls the encryption of user passwords, longer than 16 octets. By default, radiusd uses method specified by RFC 2865. However some NASes, most notably MAX Ascend series, implement a broken method of encoding long passwords. This flag instructs radiusd to use broken method of password encryption for the given NAS.

compare-auth-flag=flag

Instructs radius to use attributes marked with a given user-defined flag when comparing authentication requests. It overrides compare-attribute-flag (see section auth statement) for this particular NAS. See section Extended Comparison, for a detailed description of its usage.

compare-acct-flag=flag

Instructs radius to use attributes marked with a given user-defined flag when comparing accounting requests. It overrides compare-attribute-flag (see section acct statement) for this particular NAS. See section Extended Comparison, for a detailed description of its usage.

See section Checking for Duplicate Requests, for general description of request comparison methods.

For the list of nas-querying arguments, See section Full list of allowed arguments.

4.4.1 Example of ‘naslist’ file

# raddb/naslist: contains a list of Network Access Servers 
#
# Each record consists of following fields:
#
#       i.      A valid hostname or IP address for the client.
#       ii.     The short name to use in the logfiles for this NAS.
#       iii.    Type of device. Valid values are `true', `false' and
#               those defined in raddb/nastypes file.

# NAS Name              Short Name      Type
#----------------       ----------      ----
myhost.dom.ain          myhost          unix
merlin                  merlin          max 
11.10.10.10             arthur          livingston

4.5 NAS Types — ‘raddb/nastypes’

The ‘raddb/nastypes’ file describes the ways to query NASes about active user sessions.

4.5.1 Syntax of ‘raddb/nastypes’

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

Syntax

Each record consists of three fields separated by any amount of whitespace. The fields are:

Type

Type of the NAS which is described in this record.

Method

Method to use to query a NAS of given type.

Arguments

Arguments to pass to this method. Each argument is a pair arg=value, where arg is its name and value is a value assigned to it. The list of predefined argument names follows. Note, that no intervening whitespace is allowed in this field.

Methods

Version 1.6 of GNU Radius supports following querying methods: finger, snmp, external and guile. .

Arguments

In the discussion below n means numeric and s string value.

The following arguments are predefined:

Common for all methods

function=s

Specifies the check function to use with this method (see section Login Verification Functions). This argument must be present. For description of how this function is applied, see Multiple Login Checking.

port=n

Use port number n instead of the default for the given method.

Method snmp

password=s

Use community s instead of the default. This argument must be present.

retries=n

Retry n times before giving up.

timeout=n

Timeout n seconds on each retry.

Method finger

timeout=n

Give up if the NAS does not respond within n seconds.

notcp

tcp=0

Disable the use of T/TCP for hosts with a broken TCP implementation.

arg=subst

Send subst to finger, instead of username. subst must be one of macro variables, described below.

Macro variables

The following macro-variables are recognized and substituted when encountered in the value pair of an argument:

‘%u’

Expands to username.

‘%s’

Expands to session id.

‘%d’

Expands to session id converted to decimal representation.

‘%p’

Expands to port number.

‘%P’

Expands to port number + 1.

4.5.2 Example of nastypes file.

Note, that in the following example the long lines are broken into several lines for readability.

# Type     Method          Args
# ----     ------          ----
unix       finger       function=check_unix
max-f      finger       function=check_max_finger
max        snmp         oid=.1.3.6.1.4.1.529.12.3.1.4.%d,
                        function=check_snmp_u
as5300-f   finger       function=check_as5300_finger
as5300     snmp         oid=.1.3.6.1.4.1.9.9.150.1.1.3.1.2.%d,
                        function=check_snmp_u
livingston snmp         oid=.1.3.6.1.4.1.307.3.2.1.1.1.5.%P,
                        function=check_snmp_s

4.5.3 Standard NAS types

The ‘nastypes’ shipped with version 1.6 of GNU Radius defines following NAS types:

unix — UNIX boxes running Finger

This type suits for UNIX boxes running finger service able to return information about dial-up users active on them. To enable finger checking of a unix host add following to your ‘naslist’ file:

#Hostname Shortname Type #-------- --------- ---- nas.name T unix

max-f — MAX Ascend with Finger

Use this type if you have MAX Ascend terminal server that answers finger queries. The ‘naslist’ entry for such NAS will look like:

#Hostname Shortname Type Flags #-------- --------- ---- ----- nas.name T max-f broken_pass

Note the use of broken_pass flag. It is needed for most MAX Ascend servers (see section NAS List — ‘raddb/naslist’).

max — MAX Ascend, answering SNMP

Use this type if you have MAX Ascend terminal server that answers SNMP queries. The ‘naslist’ entry for such NAS will look like:

#Hostname Shortname Type Flags #-------- --------- ---- ----- nas.name T max-f broken_pass,community=comm

Replace comm with your actual SNMP community name.

as5300-f — Cisco AS5300 running finger

as5300 — Cisco AS5300 answering SNMP

livingston — Livingston Portmaster

Type livingston queries portmaster using SNMP.

4.6 Request Processing Hints — ‘raddb/hints’

The ‘raddb/hints’ file is used to modify the contents of the incoming request depending on the username. For a detailed description of this, See section Hints.

The file contains data in Matching Rule format (see section Matching Rule).

Notice, that versions of GNU Radius up to 1.0 allowed to use only a subset of attributes in the check list of a ‘hints’ entry, namely:

• Suffix
• Prefix
• Group
• User-ID

This requirement has been removed in version 1.0.

4.6.1 Example of ‘hints’ file

## If the username starts with `U', append the UUCP hint 
DEFAULT         Prefix = "U", Strip-User-Name = No
                Hint = "UUCP"
## If the username ends with `.slip', append the SLIP service data
## and remove the suffix from the user name.
DEFAULT         Suffix = ".slip",
                   Strip-User-Name = Yes
                Hint = "SLIP",
                   Service-Type = Framed-User,
                   Framed-Protocol = SLIP

4.7 Huntgroups — ‘raddb/huntgroups’

The ‘raddb/huntgroups’ contains the definitions of the huntgroups. For a detailed description of huntgroup concept, See section Huntgroups.

The file contains data in Matching Rule format (see section Matching Rule).

4.7.1 Example of ‘huntgroups’ file.

## This defines the packet rewriting function for the server 11.10.10.11
DEFAULT NAS-IP-Address = 11.10.10.11, Rewrite-Function = "max_fixup"
        NULL

4.8 List of Proxy Realms — ‘raddb/realms’

The ‘raddb/realms’ file lists remote Radius servers that are allowed to communicate with the local Radius server (see section Proxying).

Each record consists of up to three fields, separated by whitespace. Two of them are mandatory. The fields are:

Realm name

Specifies the name of the realm being defined, i.e. part of the login name after the ‘@’ symbol. There are three special forms of this field.

The name ‘NOREALM’ defines the empty realm, i.e. lines marked with this name will match user names without any realm suffix.

The name ‘DEFAULT’ defines the default realm (see section Realms). The lines with this realm name will match any user name, not matched by any other line in ‘raddb/realms’.

Remote server list

A comma-separated list of remote servers to which the requests for this realm should be forwarded. Each item in the list is:

servername[:auth-port[:acct-port]]

Optional auth-port and acct-port are the authentication and accounting port numbers. If acct-port is omitted, it is computed as auth-port + 1. If auth-port is omitted, the default authentication port number is used.

The servers from this list are tried in turn until any of them replies or the list is exhausted, whichever occurs first. The timeout value and number of retries for each server are set via timeout and retry flags (see below).

There may be cases where you would wish a particular realm to be served by the server itself. It is tempting to write

# Wrong! realm.name localhost

however, this will not work. The special form of the server list is provided for this case. It is the word ‘LOCAL’. The correct configuration line for the above case will thus be:

# Use this to declare a locally handled realm realm.nam LOCAL

Flags (optional)

The flags meaningful in ‘raddb/realms’ are

ignorecase

Boolean value. When set, enables case-insensitive comparison of realm names. For example, if a realm were defined as

myrealm.net remote.server.net:1812 ignorecase

then user name ‘user@MyREAlm.NeT’ will match this definition.

strip

Boolean value. Controls whether the realm name should be stripped off the username before forwarding the request to the remote server. Setting strip enables stripping, setting nostrip disables it. Default is to always strip user names.

quota=num

Set maximum number of concurrent logins allowed from this realm to the given value (num).

timeout

Number of seconds to wait for reply from the remote server before retransmitting the request.

retries

Number of attempts to connect a server. If the server does not respond after the last attempt, the next server from the list is tried.

auth

Proxy only authentication requests.

acct

Proxy only accounting requests.

4.8.1 Example of ‘realms’ file

Example 1.

# Realm                 Remote server[:port]            flags
#----------------       ---------------------           --------
that.net                radius.that.net                 nostrip
dom.ain                 server.dom.ain:3000             strip,quota=20
remote.net              srv1.remote.net,srv2.remote.net 

Example 2.

# Realm                 Remote server[:port]            flags
#----------------       ---------------------           --------
NOREALM                 radius.server.net               
that.net                radius.that.net                 nostrip
dom.ain                 server.dom.ain:3000             strip,quota=20

4.9 User Profiles — ‘raddb/users’

File ‘raddb/users’ contains the list of User Profiles. See section User Profiles, for a description of its purpose.

4.9.1 Example of ‘users’ file

## The following entry is matched when the user appends ``.ppp'' to his
## username when logging in.
## The suffix is removed from the user name, then the password is
## looked up in the SQL database.
## Users may log in at any time. They get PPP service.
DEFAULT Suffix = ".ppp",
                Auth-Type = SQL,
                Login-Time = "Al",
                Simultaneous-Use = 1,
                Strip-User-Name = Yes
        Service-Type = Framed-User,
                Framed-Protocol = PPP

## This is for SLIP users.
## This entry is matched when the auth request matches ``SLIP'' hint
DEFAULT Hint = "SLIP",
                Auth-Type = Mysql
        Service-Type = Framed-User
                Framed-Protocol = SLIP

## The following authenticates users using system passwd files.
## The users are allowed to log in from 7:55 to 23:05 on any weekday,
## except the weekend, and from 07:55 to 12:00 on Sunday.
## Only one login is allowed per user.
## The program telauth is used to further check the authentication
## information and provide the reply pairs
## Note the use of backslashes to split a long line.
DEFAULT Auth-Type = System,
                Login-Time = "Wk0755-2305,Su0755-1200",
                Simultaneous-Use = 1
        Exec-Program-Wait = "/usr/local/sbin/telauth \
                             %C{User-Name} \
                             %C{Calling-Station-Id} \
                             %C{NAS-IP-Address} \
                             %C{NAS-Port-Id}"

## This particular user is authenticated via PAM. He is presented a
## choice from ‘raddb/menus/menu1’ file.
gray    Auth-Type = Pam
        Menu = menu1

4.10 List of Blocked Users — ‘raddb/access.deny’

The ‘raddb/access.deny’ file contains a list of user names which are not allowed to log in via Radius. Each user name is listed on a separate line. As usual, the ‘#’ character introduces an end-of-line comment.

4.11 SQL Configuration — ‘raddb/sqlserver’

The ‘raddb/sqlserver’ file configures the connection to SQL server.

The file uses simple line-oriented ‘keyword --- value’ format. Comments are introduced by ‘#’ character.

The ‘sqlserver’ statements can logically be subdivided into following groups: SQL Client Parameters, configuring the connection between SQL client and the server, Authentication Server Parameters, Authorization Parameters, and Accounting server parameters.

4.11.1 SQL Client Parameters

These parameters configure various aspects of connection between SQL client and the server.

interface iface-type

Specifies the SQL interface to use. Currently supported values for iface-type are mysql and postgres. Depending on this, the default communication port number is set: it is 3306 for interface mysql and 5432 for interface postgres. Use of this statement is only meaningful when the package was configured with both ‘--with-mysql’ and ‘--with-postgres’ option.

server string

Specifies the hostname or IP address of the SQL server.

port number

Sets the SQL communication port number. It can be omitted if your server uses the default port.

login string

Sets the SQL user login name.

password password

Sets the SQL user password.

keepopen bool

Specify whether radiusd should try to keep the connection open. When set to no (the default), radiusd will open new connection before the transaction and close it right after finishing it. We recommend setting keepopen to yes for heavily loaded servers, since opening the new connection can take a substantial amount of time and slow down the operation considerably.

idle_timeout number

Set idle timeout in seconds for an open SQL connection. The connection is closed if it remains inactive longer that this amount of time.

4.11.2 Authentication Server Parameters

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

These parameters configure the SQL authentication. The general syntax is:

doauth bool

When set to yes, enables authentication via SQL. All auth_ keywords are ignored if doauth is set to no.

auth_db string

Specifies the name of the database containing authentication information.

auth_query string

Specifies the SQL query to be used to obtain user's password from the database. The query should return exactly one string value — the password.

group_query string

Specifies the query that retrieves the list of user groups the user belongs to. This query is used when Group or Group-Name attribute appears in the LHS of a user's or hint's profile.

auth_success_query string

This query is executed when an authentication succeeds. See section Controlling Authentication Probes, for the detailed discussion of its purpose.

auth_failure_query string

This query is executed upon an authentication failure. See section Controlling Authentication Probes, for the detailed discussion of its purpose.

Example of Authentication Server Parameters

Let's suppose the authentication information is kept in the tables passwd and groups.

The passwd table contains user passwords. A user is allowed to have different passwords for different services. The table structure is:

CREATE TABLE passwd (
  user_name           varchar(32) binary default '' not null,
  service             char(16) default 'Framed-PPP' not null,
  password            char(64) 
);

Additionally, the table groups contains information about user groups a particular user belongs to. Its structure is:

CREATE TABLE groups (
  user_name           char(32) binary default '' not null,
  user_group          char(32) 
);

The queries used to retrieve the information from these tables will then look like:

auth_query  SELECT password
            FROM passwd
            WHERE user_name = '%C{User-Name}'
            AND service = '%C{Auth-Data}'

group_query SELECT user_group
            FROM groups
            WHERE user_name = '%C{User-Name}'

It is supposed, that the information about the particular service a user is wishing to obtain, will be kept in Auth-Data attribute in LHS of a user's profile.

4.11.3 Authorization Parameters

These parameters define queries used to retrieve the authorization information from the SQL database. All the queries refer to the authentication database.

check_attr_query string

This query must return a list of triplets:

attr-name, attr-value, opcode

The query is executed before comparing the request with the profile entry. The values returned by the query are added to LHS of the entry. opcode here means one of valid operation codes: ‘=’, ‘!=’, ‘<’, ‘>’, ‘<=’, ‘>=’.

reply_attr_query string

This query must return pairs:

attr-name, attr-value

The query is executed after a successful match, the values it returns are added to the RHS list of the matched entry, and are therefore returned to the NAS in the reply packet.

Example of Authorization Parameters

Suppose your attribute information is stored in a SQL table of the following structure:

CREATE TABLE attrib (
  user_name varchar(32) default '' not null,
  attr      char(32) default '' not null,
  value     char(128),
  op enum("=", "!=", "<", ">", "<=", ">=") default null
);

Each row of the table contains the attribute-value pair for a given user. If op field is NULL, the row describes RHS (reply) pair. Otherwise, it describes a LHS (check) pair. The authorization queries for this table will look as follows:

check_attr_query  SELECT attr,value,op \
                  FROM attrib \
                  WHERE user_name='%u' \
                  AND op IS NOT NULL

reply_attr_query  SELECT attr,value \
                  FROM attrib \
                  WHERE user_name='%u' \
                  AND op IS NULL

Now, let's suppose the ‘raddb/users’ contains only one entry:

DEFAULT Auth-Type = SQL
        Service-Type = Framed-User   

And the attrib table contains following rows:

Then, when the user jsmith is trying to authenticate, the following happens:

1. Radius finds the matching entry (DEFAULT) in the ‘raddb/users’.
2. It queries the database using the check_attr_query. The triplets it returns are then added to the LHS of the profile entry. Thus, the LHS will contain:

   Auth-Type = SQL, NAS-IP-Address = 10.10.10.1, NAS-Port-Id <= 20

3. Radius compares the incoming request with the LHS pairs thus obtained. If the comparison fails, it rejects the authentication. Note that the Auth-Type attributes itself triggers execution of auth_query, described in the previous section.
4. After a successful authentication, Radius queries the database, using reply_attr_query, and adds its return to the list of RHS pairs. The RHS pairs will then be:

   Service-Type = Framed-User, Framed-Protocol = PPP, Framed-IP-Address = 10.10.10.11

   This list is returned to the NAS along with the authentication accept packet.

Thus, this configuration allows the user jsmith to use only NAS 10.10.10.1, ports from 1 to 20 inclusive. If the user meets these conditions, he is allowed to use PPP service, and is assigned IP address 10.10.10.11.

4.11.4 Accounting Parameters

To perform the SQL accounting radiusd needs to know the database where it is to store the accounting information. This information is supplied by the following statements:

doacct bool

When set to yes enables SQL accounting. All acct_ keywords are ignored if doacct is set to no.

acct_db string

Specifies the name of the database where the accounting information is to be stored.

Further, radiusd needs to know which information it is to store into the database and when. Each of five accounting request types (see section Accounting Requests) has a SQL query associated with it. Thus, when radius receives an accounting request, it determines the query to use by the value of Acct-Status-Type attribute.

Following statements define the accounting queries:

acct_start_query string

Specifies the SQL query to be used when Session Start Packet is received. Typically, this would be some INSERT statement (see section Writing SQL Accounting Query Templates).

acct_stop_query string

Specifies the SQL query to be used when Session Stop Packet is received. Typically, this would be some UPDATE statement.

acct_stop_query string

Specifies the SQL query to be executed upon arrival of a Keepalive Packet. Typically, this would be some UPDATE statement.

acct_nasup_query string

Specifies the SQL query to be used upon arrival of an Accounting Off Packet.

acct_nasdown_query string

Specifies the SQL query to be used when a NAS sends Accounting On Packet.

None of these queries should return any values.

Three queries are designed for use by multiple login checking mechanism (see section Multiple Login Checking):

mlc_user_query string

A query retrieving a list of sessions currently opened by the given user.

mlc_realm_query string

A query to retrieve a list of sessions currently open for the given realm.

mlc_stop_query string

A query to mark given record as hung.

4.11.4.1 Writing SQL Accounting Query Templates

Let's suppose you have an accounting table of the following structure:

CREATE TABLE calls (
  status              int(3),
  user_name           char(32),
  event_date_time     datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
  nas_ip_address      char(17),
  nas_port_id         int(6),
  acct_session_id     char(16) DEFAULT '' NOT NULL,
  acct_session_time   int(11),
  acct_input_octets   int(11),
  acct_output_octets  int(11),
  connect_term_reason int(4),
  framed_ip_address   char(17),
  called_station_id   char(32),
  calling_station_id  char(32)
);

On receiving the Session Start Packet we would insert a record into this table with status set to 1. At this point the columns acct_session_time, acct_input_octets, acct_output_octets as well as connect_term_reason are unknown, so we will set them to 0:

# Query to be used on session start
acct_start_query     INSERT INTO calls \
                     VALUES(%C{Acct-Status-Type},\
                            '%u',\
                            '%G',\
                            '%C{NAS-IP-Address}',\
                            %C{NAS-Port-Id},\
                            '%C{Acct-Session-Id}',\
                            0,\
                            0,\
                            0,\
                            0,\
                            '%C{Framed-IP-Address}',\
                            '%C{Called-Station-Id}',\
                            '%C{Calling-Station-Id}')

Then, when the Session Stop Packet request arrives we will look up the record having status = 1, user_name matching the value of User-Name attribute, and acct_session_id matching that of Acct-Session-Id attribute. Once the record is found, we will update it, setting

status = 2
acct_session_time = value of Acct-Session-Time attribute
acct_input_octets = value of Acct-Input-Octets attribute
acct_output_octets = value of Acct-Output-Octets attribute
connect_term_reason = value of Acct-Terminate-Cause attribute

Thus, every record with status = 1 will represent the active session and every record with status = 2 will represent the finished and correctly closed record. The constructed acct_stop_query is then:

# Query to be used on session end
acct_stop_query      UPDATE calls \
                     SET status=%C{Acct-Status-Type},\
                         acct_session_time=%C{Acct-Session-Time},\
                         acct_input_octets=%C{Acct-Input-Octets},\
                         acct_output_octets=%C{Acct-Output-Octets},\
                         connect_term_reason=%C{Acct-Terminate-Cause} \
                     WHERE user_name='%C{User-Name}' \
                     AND status = 1 \
                     AND acct_session_id='%C{Acct-Session-Id}' 

Upon receiving a Keepalive Packet we will update the information stored with acct_start_query:

acct_alive_query  UPDATE calls \
                  SET acct_session_time=%C{Acct-Session-Time},\
                      acct_input_octets=%C{Acct-Input-Octets},\
                      acct_output_octets=%C{Acct-Output-Octets},\
                      framed_ip_address=%C{Framed-IP-Address} \
                  WHERE user_name='%C{User-Name}' \
                  AND status = 1 \
                  AND acct_session_id='%C{Acct-Session-Id}'

Further, there may be times when it is necessary to bring some NAS down. To correctly close the currently active sessions on this NAS we will define a acct_nasdown_query so that it would set status column to 2 and update acct_session_time in all records having status = 1 and nas_ip_address equal to IP address of the NAS. Thus, all sessions on a given NAS will be closed correctly when it brought down. The acct_session_time can be computed as difference between the current time and the time stored in event_date_time column:

# Query to be used when a NAS goes down, i.e. when it sends 
# Accounting-Off packet
acct_nasdown_query UPDATE calls \
                   SET status=2,\
                       acct_session_time=unix_timestamp(now())-\
                               unix_timestamp(event_date_time) \
                   WHERE status=1 \
                   AND nas_ip_address='%C{NAS-IP-Address}'

We have not covered only one case: when a NAS crashes, e.g. due to a power failure. In this case it does not have a time to send Accounting-Off request and all its records remain open. But when the power supply is restored, the NAS will send an Accounting On packet, so we define a acct_nasup_query to set status column to 3 and update acct_session_time in all open records belonging to this NAS. Thus we will know that each record having status = 3 represents a crashed session. The query constructed will be:

# Query to be used when a NAS goes up, i.e. when it sends 
# Accounting-On packet
acct_nasup_query   UPDATE calls \
                   SET status=3,\
                       acct_session_time=unix_timestamp(now())-\
                               unix_timestamp(event_date_time) \
                   WHERE status=1 \
                   AND nas_ip_address='%C{NAS-IP-Address}'

If you plan to use SQL database for multiple login checking (see section Multiple Login Checking), you will have to supply at least two additional queries for retrieving the information about currently active sessions for a given user and realm (see section Retrieving Session Data). Each of these queries must return a list consisting of 5-element tuples:

user-name, nas-ip-address, nas-port-id, acct-session-id

For example, in our setup these queries will be:

mlc_user_query SELECT user_name,nas_ip_address,\
                      nas_port_id,acct_session_id \
               FROM calls \
               WHERE user_name='%C{User-Name}' \
               AND status = 1

mlc_realm_query SELECT user_name,nas_ip_address,\
                       nas_port_id,acct_session_id \
                FROM calls \
                WHERE realm_name='%C{Realm-Name}'     

While performing multiple login checking radiusd will eventually need to close hung records, i.e. such records that are marked as open in the database (status=1, in our setup), but are actually not active (See section Verifying Active Sessions, for the description of why it may be necessary). It will by default use acct_stop_query for that, but it has a drawback that hung records will be marked as if they were closed correctly. This may not be suitable for accounting purposes. The special query mlc_stop_query is provided to override acct_stop_query. If we mark hung records with status=4, then the mlc_stop_query will look as follows:

mlc_stop_query UPDATE calls \
               SET status=4,\
                acct_session_time=unix_timestamp(now())-\
                                  unix_timestamp(event_date_time) \
               WHERE user_name='%C{User-Name}' \
                 AND status = 1 \
                 AND acct_session_id='%C{Acct-Session-Id}' 

4.12 Rewrite functions — ‘raddb/rewrite’

The file ‘raddb/rewrite’ contains definitions of Rewrite extension functions. For information regarding Rewrite extension language See section Rewrite.

4.13 Login Menus — ‘raddb/menus’

The menus is a way to allow user the choice between various services he could be provided. The menu functionality is enabled when Radius is compiled with ‘--enable-livingston-menus’ option.

A user is presented a menu after it is authenticated if the RHS of his profile record consists of a single A/V pair in the form:

Menu = <menu-name>

The menu files are stored in directory ‘raddb/menus’.

4.13.1 A menu file syntax.

A menu file is a text file containing a menu declaration and any number of choice descriptions. The menus can be nested to an arbitrary depth.

A comment is introduced by a ‘#’ character. All characters from this one up to the end of line are discarded.

The menu declaration is contained between the words ‘menu’ and ‘end’. Each of these must be the only word on a line and must start in column 1.

Choice descriptions follow the menu declaration. Each description starts with a line containing choice identifier. A choice identifier is an arbitrary word identifying this choice, or a word ‘DEFAULT’. It is followed by comma-separated list of A/V pairs which will be returned to the server when a user selects this choice.

4.13.2 An example of menu files

Single-Level Menu

Suppose the following file is stored under ‘raddb/menus/menu1’:

menu
        *** Welcome EEE user! ***
Please select an option:

        1. Start CSLIP session
        2. Start PPP session
        3. Quit

        Option:
end
# CSLIP choice
# Framed-IP-Address of 255.255.255.254 indicates that the NAS should
# select an address for the user from its own IP pool.
1
        Service-Type = Framed-User,
        Framed-Protocol = SLIP,
        Framed-IP-Address = 255.255.255.254,
        Termination-Menu = "menu1"
# PPP choice
2
        Service-Type = Framed-User,
        Framed-Protocol = PPP,
        Framed-IP-Address = 255.255.255.254,
        Termination-Menu = "menu1"
# A special menu EXIT means abort the session
3
        Menu = "EXIT"
# Return to this menu if no valid choice have been entered 
DEFAULT
        Menu = "menu1"

Now, suppose the ‘raddb/users’ contains the following profile entry:

DEFAULT Auth-Type = System
        Menu = "menu1"

and user ‘jsmith’ has a valid system account and tries to log in from some NAS. Upon authenticating the user, the Radius server sees that his reply pairs contain the Menu attribute. Radius then sends Access-Challenge packet to the NAS with the text of the menu in it. The ‘jsmith’ then sees on his terminal:

        *** Welcome EEE user! ***
Please select an option:

        1. Start CSLIP session
        2. Start PPP session
        3. Quit

        Option:

He then enters ‘2’. The NAS sends the Access-Request packet to the server, which sees that user wishes to use option 2 and replies to the NAS with an Access-Accept packet containing the following attributes:

        Service-Type = Framed-User,
        Framed-Protocol = PPP,
        Framed-IP-Address = 255.255.255.254,
        Termination-Menu = "menu1"

The Termination-Menu in this list makes sure the same process will continue when ‘jsmith’ logs out, i.e. he will be presented the same menu again until he enters choice ‘3’ which will disconnect him.

Nested menus

In this example, the ‘other’ choice refers to the menu above.

menu
        *** Welcome here! ***
Please enter an option:
        ppp     ---     Start PPP session
        telnet  ---     Begin guest login session
        other   ---     Select other option

        Enter your choice:
end
ppp
        Service-Type = Framed-User,
        Framed-Protocol = PPP
telnet
        Service-Type = Login-User,
        Login-IP-Host = 10.11.11.7,
        Login-Service = Telnet,
        Login-TCP-Port = 23
other
        Menu = "menu1"
DEFAULT
        menu = "menu2"

4.14 Macro Substitution

Some statements in the configuration files need to use the actual values of the attributes supplied with the request. These are:

• Exec-Program and Exec-Program-Wait assignments in ‘users’ database
• SQL query templates in ‘sqlserver’

In these statements the following macros are replaced by the value of corresponding attributes:

%Cnum

(num is a decimal number). This variable is replaced by the value of attribute number `num'. The attribute is looked up in the incoming request pairlist.

%C{attr-name}

This is replaced by the value of attribute named `attr-name'. The attribute is looked up in the incoming request pairlist.

%Rnum

(num is a decimal number). This variable is replaced by the value of attribute number `num'. The attribute is looked up in the reply pairlist.

%R{attr-name}

This is replaced by the value of attribute named `attr-name'. The attribute is looked up in the reply pairlist.

%D

This is replaced by current date/time (localtime).

%G

This is replaced by current date/time in GMT.

The exact substitution procedure varies depending on the type of the attribute referenced by macro. If the attribute is of string or date type, radiusd first checks if the resulting substitution should be quoted. It does so by looking at the character immediately preceeding ‘%’. If it is a single or double quote, then radiusd assumes the macro must be quoted and replaces it by an appropriately modified attribute value. The purpose of the modification is to ensure that no characters within the expanded string would conflict with the quoting characters. In particular, radiusd searches the attribute value for any of the characters ‘\’, ‘'’, ‘"’ and prepends a ‘\’ to any occurrence of these. For example, suppose that attribute NAS-Identifier has the value ‘A "new" host’. Then:

nasid=%C{NAS-Identifier} → nasid=A "new" host
nasid="%C{NAS-Identifier}" → nasid="A \"new\" host"
nasid=%\C{NAS-Identifier} → nasid=A \"new\" host

The last example illustrates the use of backslash character to force string quoting in the absense of explicit quotation marks.

If an integer attribute reference is quoted, radiusd looks up the string translation of its value in the dictionary (see section VALUE Statement) and uses this string as a replacement. If no translation is found, the numeric value is used. The following example assumes that the value of Acct-Terminate-Cause attribute is 10:

reason=%C{Acct-Terminate-Cause} → reason=10
reason='%C{Acct-Terminate-Cause}' → reason='NAS-Request'
reason=%\C{Acct-Terminate-Cause} → reason=NAS-Request

Again, a backslash after percent sign can be used to force dictionary lookup.

The “‘{}’ form” allows to specify default value for the substitution. The default value will be used when no such attribute is encountered in the pairlist. The syntax for specifying the default value resembles that of shell environment variables.

The substitution %C{attr-name:-defval} is expanded to the value of attr-name attribute, if it is present in the request pairlist, and to defval otherwise. For example:

        %C{Acct-Session-Time:-0}

will return the value of Acct-Session-Time attribute or 0 if it doesn't exist in the request pairlist.

The substitution %C{attr-name:=defval} is expanded to the value of attr-name attribute. If this attribute is not present in the request pairlist, it will be created and assigned the value defval. E.g.:

        %C{Acct-Session-Time:=0}

The substitution %C{attr-name:?message} is expanded to the value of attr-name attribute, if it is present. Otherwise the diagnostic message “attr-name: message” is issued to the log error channel, and string “message” is returned.

The substitution %C{attr-name:+retval} is expanded to empty string if the attribute attr-name is present in the referenced pairlist. Otherwise it is expanded to retval.

You can also use the following shortcuts:

%p

Port number

%n

NAS IP address

%f

Framed IP address

%u

User name

%c

Callback-Number

%i

Calling-Station-Id

%t

MTU

%a

Protocol (SLIP/PPP)

%s

Speed (Connect-Info attribute)

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