GNU Radius Reference Manual

The RADIUS daemon

Radius Attributes

Reporting Bugs and getting information

Obtaining GNU Radius

What Next?

Appendices

Indices

Here are some other nodes which are really inferiors of the ones
already listed, mentioned here so you can get to them in one step:

 --- The Detailed Node Listing ---

Radius Configuration

Client configuration

Introduction to Radius

GNU Radius is a software package that provides authentication and accounting services. The acronym RADIUS stands for Remote Authentication Dial In User Service and (in that form) usually denotes the underlying protocol name.

Historically, RADIUS servers were used as a means to authenticate the user coming from a dial-in connection, but GNU Radius is much more than an authentication system: it is an advanced, customizable, and extensible system for controlling access to the network.

GNU Radius has several built-in authentication and accounting methods. When these methods are not enough, it allows the administrator to implement any new method she deems convenient.

The GNU Radius package includes the server program, radiusd, which responds to authentication and accounting requests, and a set of accompanying programs designed to monitor the activity of the server and analyze the information it provides.

0.1 Overview

To illustrate what GNU Radius does, let's consider an imaginary internet service provider. Our provider has two network access servers (NASes for short)—i.e., two pieces of equipment which directly accept users' connections—and a core router that connects the ISP's internal network with the Internet backbone.

When a user connects to a NAS, the server must verify that the user is actually registered and that the credentials she has supplied are correct. This first step is called authentication.

Upon authenticating the user, the NAS must determine which services the user is permitted to use and to what extent the user may use them. This second step is called authorization.

When the first two stages have been successfully completed, the NAS takes the third step and establishes the connection between the user and the main server. This connection is called a user session. For the purposes of accounting, the NAS remembers the exact time of the start of the session. When the session is terminated, the duration of the session and the number of bytes transferred are recorded as well.

All three tasks can be accomplished by the use of user and accounting databases on each terminal server. However, this is not convenient, and it is error-prone in that the maintenance of separate databases for the same users is not a trivial task. What is worse, as the number of terminal servers grows, this maintenance problem becomes more difficult.

How Does RADIUS Perform These Tasks?

RADIUS allows an administrator to keep authentication and accounting data in a single place, no matter how many network access servers are actually present. Using RADIUS, NASes instead communicate with this central server to perform authentication and accounting, thus easing the burden on the system administrator.

Let's return to our imaginary ISP. Suppose it runs a RADIUS daemon on its central server. Each NAS runs client software to communicate with the RADIUS server by sending radius packets.

An average user session life cycle looks as follows.

A user connects to the nearest NAS and supplies his login and password. The NAS forms an authentication request and sends it to the RADIUS server.

The RADIUS server verifies the user's credentials and finds them sufficient. It then retrieves the user's authorization information from its database, packages it into an acknowledgement packet, and then sends it back to the NAS

The NAS receives the acknowledgement packet and starts the user session. The information brought with the packet tells the NAS to establish a connection between the core router and the user, and to assign the user a certain IP address. Having established the session, the NAS informs the RADIUS server by sending it an accounting start packet. The server acknowledges the receipt of the accounting packet.

Now suppose that after some time the user decides to break the connection. The NAS notices this and terminates the user's session. The NAS then sends an accounting stop packet to the RADIUS server to mark this event. Again, the server acknowledges the receipt of the packet.

RADIUS Attributes

Attributes are means of passing the information between the NAS and the server. Basically, an attribute is an integer number that identifies some piece of information. A set of properties are associated with each attribute, specifying the way to interpret the attribute. The most important property is the data type, which declares the type of data that the attribute identifies (character string, integer number, IP address, or raw binary data).

The information to be transmitted with the request is packaged in a set of attribute-value pairs (or A/V pairs for short). Such pairs consist of attribute numbers and the associated data.

RADIUS Packets

There exist two basic kinds of RADIUS packets: authentication and accounting packets. Each of them is subdivided into requests and replies.

Authentication requests are sent from the NAS to the RADIUS server and contain the information necessary to check the identity of the user. The minimum set of data in such packets consists of the user login name, user password, and NAS IP or identifier.

Authentication replies are sent by the RADIUS server and contain the reply code and a set of additional attributes. According to their reply code the authentication replies are subdivided into authentication acknowledgements, authentication rejections, and authentication challenges.

An authentication acknowledgement packet is sent to the NAS if the credentials supplied with the authentication request were correct. This kind of packet tells the NAS to establish a normal user session. The additional attributes in such packets carry the authorization data, i.e., they determine which kind of service the user is to be provided.

An authentication rejection is sent to the NAS if the authentication has failed. This packet forbids the NAS to provide any service to the user. The additional attributes may carry descriptive text to be displayed as an explanation to the user for the failure of his request.

Finally, an authentication challenge packet is sent to the NAS if the supplied credentials did not suffice to establish the authenticity of the user. This means that the dialog between the NAS and the RADIUS server continues. As the RADIUS server asks for additional authentication credentials, the NAS acts as a liaison, passing server requests to the user and sending user replies back to the server. Such a dialog ends when the RADIUS server sends either an acknowledgement packet or a rejection packet.

An accounting request is sent to the server when the NAS wishes to report some event in the user session: the start of the session, session termination, etc. The attributes carry the actual information about the event.

For each accounting request that has been received and successfully processed, the RADIUS server sends back an accounting acknowledgement. This packet carries no attributes, but simply informs the NAS that the information it had sent was received.

Occasionally, a RADIUS server may fail to receive incoming requests or may fail to process them due to high server load. In order to prevent such requests from being lost, the NAS retransmits the request if no response from the server is received within a predefined interval of time (a timeout interval). Usually the NAS is configured in such a way that it continues retransmitting failed requests until either it receives a reply from the server or a predefined number of retries are exhausted, whichever occurs first. Furthermore, a NAS may be configured to communicate with a set of backup RADIUS servers. In this case it applies the described process to each server from the set, until one of them responds or the set is exhausted.

1. Naming Conventions

This chapter describes file naming conventions used throughout this document.

Programs from the GNU Radius package use the following directories to store various configuration and log files:

Configuration or database directory

A directory where all configuration files are stored.

Log directory

A directory where radiusd stores its log files.

Accounting directory

A directory where radiusd stores accounting detail files (see section Detailed Request Accounting).

Data directory

A directory where shared data files are stored, such as Rewrite or Scheme source files.

The default locations of these directories are determined at compile time. Usually these are:

These locations may differ depending on your local site configuration.

Throughout this document we will refer to these directories by their short names. For example, when we say:

... this information is contained in file ‘raddb/sqlserver’ 

we actually mean ‘/usr/local/etc/raddb/sqlserver’.

To get the default directory names that your version of Radius was compiled with, run radiusd --version.

Locations of these directories may be overridden by specifying the appropriate command line options. For example, any program from the GNU Radius package accepts the command line option ‘-d’ or ‘--directory’, which introduces the configuration directory path.

2. How Radius Operates

The main purpose of GNU Radius is to centralize authentication of users coming from various network stations, pursuant to the RADIUS specification. Its primary usage is for dial-in users, though it can be used for any kind of network connection.

2.1 Attributes

Information carried by RADIUS requests is stored as a list of attribute-value pairs. Each pair consists of an attribute number and an attribute value. The attribute number identifies the type of information the pair carries, and the attribute value keeps the actual data.

The value part of an attribute can contain data of one of the following types:

Integer

A 32-bit unsigned integer value.

IP-number

An IPv4 IP-number.

String

A character string up to 253 characters long.

For convenience, the attributes and the values of some frequently used integer attributes are given symbolic names. These names are assigned to attributes and values in the dictionary file (see section Dictionary of Attributes — ‘raddb/dictionary’).

Attribute numbers range from 1 to 255. Attributes with numbers greater than 255 are used internally by the server and cannot be sent to the NAS.

The vendor-specific attribute number 26 is special, allowing vendors of the NAS hardware or software to support their own extended attributes. vendor-specific attribute.

Each attribute has a set of properties associated with it. The properties are:

Usage flags

These flags determine the usage of the attribute in the configuration files ‘huntgroups’, ‘hints’, and ‘users’.

Propagation

When a RADIUS server functions in proxy mode, it uses the propagation flag to determine which attributes from the reply packet should be passed back to the requesting NAS (see section Proxy Service).

additivity

Some configuration rules may cause the addition of new A/V pairs to the incoming request. Before the addition of a new pair, radiusd scans the request to see if it already contains a pair with the same attribute. If it does, the value of the additivity determines the following additional actions:

None

The old pair is retained in the request; the new pair is not added to it.

Replace

The old pair is retained in the request, but its value is replaced with that of the new pair.

Append

The new pair is appended to the end of the pair list.

Attributes are declared in the ‘raddb/dictionary’ file. For a detailed description, see ATTRIBUTE statement. For information about particular attributes, see Attribute List.

2.2 RADIUS Requests

The term request refers to both the authentication/accounting request packet from a NAS to a RADIUS server and the response packet that the server sends back to the NAS.

Each request contains the following fields:

‘Code’

The code field identifies the type of the request.

‘Identifier’

The number in the range 0–255 used to match the request with the reply.

‘Length’

The length of the request packet.

‘Authenticator’

The 16-byte hash value used to authenticate the packet.

‘Attributes’

The list of attribute-value pairs carrying actual information about the request.

2.2.1 Authentication Requests

A NAS sends authentication requests (packets with code field set to Access-Request) to a RADIUS server when a user is trying to connect to that NAS. Such requests convey information used to determine whether a user is allowed access to the NAS, and whether any special services are requested for that user.

An Access-Request must contain a User-Name attribute User-Name. This packet should contain a NAS-IP-Address attribute, a NAS-Identifier attribute, or both. It also must contain either a User-Password attribute or a CHAP-Password attribute. These attributes are passed after being encoded using a method based on the RSA Message Digest Algorithm MD5.

The Access-Request should contain a NAS-Port or NAS-Port-Type attribute or both, unless the type of access being requested does not involve a port or the NAS does not distinguish among its ports.

Upon receiving an Access-Request packet for a particular user and authenticating that user, the RADIUS server replies to the NAS that has sent the packet with any one of the following packets:

• Access-Accept
• Access-Reject
• Access-Challenge

GNU Radius replies with an Access-Accept packet when it has successfully authenticated the user. Such a reply packet provides the configuration information necessary to begin delivery of service to the user.

GNU Radius replies with an Access-Reject packet when it is unable to authenticate the user. Such a packet may contain a descriptive text encapsulated in one or more Reply-Message attributes. The NAS may display this text along with its response to the user.

GNU Radius replies with an Access-Challenge packet when it needs to obtain more information from the user in order to determine the user's authenticity or to determine the kind of service to be provided to the user.

An Access-Challenge packet may include one or more Reply-Message attributes, and it may or may not include a single State attribute. No other attributes are permitted in an Access-Challenge packet.

Upon receipt of an Access-Challenge, the Identifier field is matched with a pending Access-Request. Additionally, the Response Authenticator field must contain the correct response for the pending Access-Request. In the event of an invalid packet, GNU Radius discards the offending packet and issues the appropriate log message.

If the NAS does not support challenge/response, it treats an Access-Challenge as though it had received an Access-Reject instead. Otherwise, upon receipt of a valid Access-Challenge the NAS prompts the user for a response, possibly displaying the text message provided in the Reply-Message attributes of the request. It then sends its original Access-Request with a new request ID and request authenticator, along with the User-Password attribute replaced by the encrypted user's response, and including the State attribute from the Access-Challenge, if any.

2.2.2 Accounting Requests

Accounting-Request packets are sent from a NAS to a RADIUS server to allow for accounting of a service provided to a user.

Upon receipt of an Accounting-Request packet, the server attempts to record it (see section Accounting), and if it succeeds in doing so, it replies with an Accounting-Response packet. Otherwise, it sends no reply, which then causes the NAS to retransmit its request within a preconfigured interval of time. Such retransmits will continue until either the server responds with an Accounting-Response packet or a preconfigured number of retransmits is reached, whichever occurs first.

Any attribute valid in an Access-Request or Access-Accept packet is also valid in an Accounting-Request packet, except the following attributes, which are never present in any Accounting-Request packet:

• User-Password
• CHAP-Password
• Reply-Message
• State

Either a NAS-IP-Address or a NAS-Identifier must be present in an Accounting-Request packet. It should contain either a NAS-Port or a NAS-Port-Type attribute (or both), unless the service does not involve a port or the NAS does not distinguish among its ports.

If the Accounting-Request packet includes a Framed-IP-Address, that attribute must contain the actual IP of the user.

There are five types of accounting packets, differentiated by the value of the Acct-Status-Type attribute. These are:

Session Start Packet

The session start packet is sent after the user has successfully passed the authentication and has started to receive the requested service. It must contain at least following attributes:

• Acct-Status-Type = Start
• User-Name
• Acct-Session-Id
• NAS-IP-Address
• NAS-Port-Id

Session Stop Packet

The session stop packet is sent after the user has disconnected. It conveys the information about the duration of the session, number of octets transferred, etc. It must contain at least the following attributes:

• Acct-Status-Type = Stop
• User-Name
• NAS-IP-Address
• Acct-Session-Id

The last three of them are used to find the corresponding session start packet.

Keepalive Packet

The keepalive packet is sent by the NAS when it obtains some new information about the user's session, e.g. it has determined its IP or has changed the connection speed. The packet must contain at least the following attributes:

• Acct-Status-Type = Alive
• User-Name
• NAS-IP-Address
• Acct-Session-Id

Accounting-Off Packet

By sending this packet, the NAS requests that radiusd mark all sessions registered from this particular NAS as finished. Receiving this packet usually means that the NAS is to be shut down, or is about to change its configuration in a way that requires all currently opened sessions to be closed. The packet must contain at least the following attributes:

• Acct-Status-Type = Accounting-Off
• NAS-IP-Address

Accounting-On Packet

By sending this packet, the NAS informs radiusd that it is ready to accept the incoming connections. Usually this packet is sent after startup, or after a major reconfiguration of the NAS. It must contain at least the following attributes:

• Acct-Status-Type = Accounting-On
• NAS-IP-Address

2.3 Matching Rule

A record in the GNU Radius database describing a particular rule for matching an incoming request is called a matching rule. Each such rule defines an action to be taken when the match occurs.

The matching rule consists of three distinct parts:

Label

This is used to identify the rule. The special usernames DEFAULT and BEGIN are reserved. These will be described in detail below.

Left-Hand Side (LHS)

The list of attribute-value pairs used for matching the profile against an incoming request.

Right-Hand Side (RHS)

The list of attribute-value pairs that define the action to be taken if the request matches LHS.

The following GNU Radius configuration files keep data in a matching rule format: ‘hints’, ‘huntgroups’, and ‘users’. Although they keep data in a similar format, the rules that are used to match incoming requests against the contents of these files differ from file to file. The following section describes these rules in detail.

2.4 Processing Requests

Upon receiving a request, radiusd applies to it a number of checks to determine whether the request comes from an authorized source. If these checks succeed, the request is processed and answered. Otherwise, the request is dropped and corresponding error message is issued (see section Logging).

The following checks are performed:

Check if the username is supplied.

If the packet lacks the User-Name attribute, it is not processed.

Check if the NAS is allowed to speak.

The source IP of the machine that sent the packet is looked up in the ‘clients’ file (see section Clients List — ‘raddb/clients’). If no match is found, the request is rejected.

Compute the encryption key.

Using the data from the packet and the shared key value from the ‘clients’ file, Radius computes the MD5 encryption key that will be used to decrypt the value of the User-Password attribute.

Process user-name hints.

User-name hints are special rules that modify the request depending on the user's name and her credentials. These rules allow an administrator to divide users into distinct groups, each group having its own authentication and/or accounting methods. The user-name hints are stored in ‘raddb/hints’ (see section Request Processing Hints — ‘raddb/hints’).

Process huntgroup rules.

Huntgroup rules allow an administrator to segregate incoming requests depending on the NAS and/or port number they came from. These rules are stored in ‘raddb/huntgroups’ (see section Huntgroups — ‘raddb/huntgroups’).

Determine whether the request must be proxied to another RADIUS server.

The requests pertaining to another realm are immediately forwarded to the remote RADIUS server for further processing. See section Proxying, for the description of this process.

Process individual user profiles

This step applies only to authentication requests.

2.4.1 Checking for Duplicate Requests

As described above (see section How Radius Operates), a NAS may decide to retransmit the request under certain circumstances. This behavior ensures that no requests are lost. For example, consider the following scenario:

1. The NAS sends a request to the server.
2. The server processes it and sends back the reply.
3. The reply is lost due to a network outage, or the load average of the NAS is too high and it drops the response.
4. The NAS retransmits the request.

Thus the RADIUS server will receive and process the same request twice. This probably won't do any harm if the request in question is an authentication one, but for accounting requests it will lead to duplicate accounting. To avoid such an undesirable effect, radiusd keeps a queue of received requests. When an incoming request arrives, radiusd first scans the request queue to see if the request is a duplicate. If so, it drops the request; otherwise, it inserts the request into the queue for processing. After the request is completed, it will still reside in the queue for a preconfigured interval of time (see section auth statement, parameter request-cleanup-delay).

By default, radiusd considers two requests to be equal if the following conditions are met:

1. Both requests come from the same NAS.
2. They are of the same type.
3. The request identifier is the same for both requests.
4. The request authenticator is the same for both requests.

Additionally, radiusd may be configured to take into account the contents of both requests. This may be necessary, since some NASes modify the request authenticator or request identifier before retransmitting the request, so the method described above fails to recognize the request as a duplicate. This extended comparison is described in detail in Extended Comparison.

2.4.2 Proxying

Proxying is a mode of operation where a RADIUS server forwards incoming requests from a NAS to another RADIUS server, waits for the latter to reply, and then forwards the reply back to the requesting NAS. A common use for such operation mode is to provide roaming between several internet service providers (ISPs). Roaming permits ISPs to share their resources, allowing each party's users to connect to other party's equipment. Thus, users traveling outside the area of one ISP's coverage are still able to access their services through another ISP.

2.4.2.1 Proxy Service

Suppose the ISP ‘Local’ has a roaming arrangement with the ISP ‘Remote’. When the user of ‘Remote’ dials in to the NAS of ‘Local’, the NAS sends the authentication request to the ‘Local’ RADIUS server. The server then determines that this is a roaming user, stores a copy of the request in its internal queue, and forwards the request to the ‘Remote’ RADIUS server for processing. Thus, the ‘Local’ RADIUS server acts as a client for the ‘Remote’ RADIUS server.

When the ‘Remote’ RADIUS server responds, the ‘Local’ RADIUS server receives the response, and passes it back to the NAS. The copy of the request from the server's queue determines which NAS originated the request. Before passing the request back to the NAS, the server removes information specific to the ‘Remote’ site, such as Framed-IP-Address, Framed-Netmask, etc. Only the attributes marked with a ‘propagation’ flag (see section Attributes) are passed back to the NAS. After removing site-specific attributes, the ‘Local’ RADIUS server passes the request through its user profiles (see section User Profiles) to insert any local, site-specific information that might be needed. Finally, it passes the reply back to the NAS.

Proxied accounting requests are processed in a similar manner, except that no attribute filtering takes place, as accounting responses do not carry any A/V pairs.

This example illustrates only the simplest proxy chain, consisting of two servers; real-life proxy chains may consist of several servers. For example, our ‘Remote’ RADIUS server might also act as a proxy, forwarding the request to yet another RADIUS server, and so on.

Note that when the accounting request passes through a chain of forwarding servers, the accounting records are stored on all servers in the chain.

2.4.2.2 Realms

GNU Radius determines which server a request must be forwarded to by the request's authentication realm. There are three kinds of realms:

1. A named realm is the part of a user name following the at sign (‘@’). For example, if the user name is ‘jsmith@this.net’, then ‘this.net’ is the realm. The named realms can be cascaded; e.g., a request with user name ‘jsmith@this.net@remote.net’ will first be forwarded to the RADIUS server of the realm ‘remote.net’, which in turn will forward it to ‘this.net’.
2. A default realm defines the server to which the requests for realms not mentioned explicitly in the configuration are forwarded.
3. An empty realm defines the server to which the requests without explicitly named realms are forwarded. If the configuration does not define an empty realm, such requests are processed by the server itself.

GNU Radius keeps the information about the realms it serves in the ‘raddb/realms’ configuration file (see section List of Proxy Realms — ‘raddb/realms’).

2.4.3 Hints

User-name hints are special rules that modify the incoming request depending on the user name and its credentials. Hints are stored as a list of matching rules (see section Matching Rule). Upon receiving a request, radiusd scans the hint entries sequentially, comparing each rule's label with the value of the User-Name attribute from the request. If they coincide, then radiusd appends the contents of the rule's RHS to the request's pair list.

The two user names must match exactly in order for a hint to take effect, unless the hint's checklist contains either the Prefix or the Suffix attribute. The special name ‘DEFAULT’ or ‘DEFAULT%d’ (where %d denotes any decimal number), used as a hint's label, matches any user name.

Two special attributes, Prefix and Suffix, may be used in LHS to restrict the match to a specified part of a user name. Both are string attributes. The Prefix instructs radiusd to accept the hint only if the user name begins with the given prefix. Similarly, Suffix instructs radiusd to accept the hint only if the user name ends with the given suffix. A hint may contain both Prefix and Suffix attributes.

In addition to these two attributes, a hint's LHS may contain User-ID and Group attributes.

The following attributes, when used in a hint's RHS have special meaning. They are not appended to the request pair list. Instead, they are removed after completing their function:

Fall-Through

If this attribute is present and is set to Yes, radiusd continues scanning the hints after processing the current entry. This allows radiusd to apply several hints to a single packet.

Rewrite-Function

If this attribute is present, the specified rewrite function is invoked.

Replace-User-Name

The value of this attribute is expanded (see section Macro Substitution) and replaces the value of the User-Name attribute from the request.

Hint rules are defined in the ‘raddb/hints’ file (see section Request Processing Hints — ‘raddb/hints’).

2.4.4 Huntgroups

Huntgroups are special rules that allow an administrator to provide alternate processing of certain incoming requests depending on the NAS IP and port number they come from. These rules are stored as a list of matching rules (see section Matching Rule).

Upon receiving a request, radiusd scans this list sequentially until it finds an entry such that the conditions set forth in its LHS are matched by the request. If such an entry is found, radiusd verifies that the request meets the conditions described by RHS. If it does not, the request is rejected. In short, a huntgroup requires that any request matching its LHS must match also its RHS.

The label part of the rule is not used in comparisons; instead it is used to label huntgroups. All entries with the same label form a single huntgroup. The special attribute Huntgroup-Name can be used to request a match against a particular huntgroup (see section Huntgroup-Name).

Huntgroup rules are defined in the ‘raddb/huntgroups’ file (see section Huntgroups — ‘raddb/huntgroups’).

2.4.5 User Profiles

User profiles are per-user matching rules (see section Matching Rule). All incoming authentication requests are compared with the user profiles after they have passed both hints and huntgroups. radiusd selects the user profiles whose label matches the value of the User-Name attribute from the incoming request.

The selected profiles form the list of authentication rules for the request. In order for a profile to be selected, its label must either coincide literally with the User-Name value, or be one of the special labels, DEFAULT or BEGIN.

Rules in an authentication list are ordered as follows: first go all the profiles with the BEGIN label, followed by the profiles whose labels match the User-Name literally, followed finally by the rules labeled with the DEFAULT. (1)

Within each of the three sublists, the rules preserve the order in which they appear in the ‘raddb/users’ file. Once the list is constructed, it is scanned sequentially until the rule is found whose LHS matches the incoming request. If no such rule is found, the authentication fails. Otherwise, the contents of its RHS are appended to the reply list being constructed. If the RHS of the matched rule contains the attribute Fall-Through with the value Yes, the matching continues. When the list is exhausted, the authentication result is sent back to the NAS along with the A/V pairs collected in the reply list.

User profiles are defined in the ‘raddb/users’ file (see section User Profiles — ‘raddb/users’).

3. How to Start the Daemon.

When started radiusd uses the configuration values from the following sources (in order of increasing precedence):

• Compiled-in defaults
• ‘raddb/config’ file.
• Command line arguments

Whenever a command line options has its equivalent in config file the use of this equivalent should be preferred (see section Run-Time Configuration Options — ‘raddb/config’).

The following command line options are accepted:

‘-A’

‘--log-auth-detail’

Enable detailed authentication logging. When this option is specified each authentication request is logged to the file ‘radacct/NASNAME/detail.auth’, where NASNAME is replaced by the short name of the NAS from ‘raddb/naslist’ Naming Conventions.

Config file equivalent: auth { detail yes; };.

‘-a DIR’

‘--acct-directory DIR’

Specify accounting directory.

Config file equivalent: option { acct-dir DIR; };.

‘-b’

‘--dbm’

Enable DBM support.

Config file equivalent: usedbm yes;.

‘-d DIR’

‘--config-directory DIR’

‘--directory D’

Specify alternate configuration directory. Default is ‘/usr/local/etc/raddb’.

‘-f’

‘--foreground’

Stay in foreground. We recommend to use it for debugging purposes only.

‘-i IP’

‘--ip-address’

Specifies the IP address radiusd will listen on. If this option is not specified, the program will listen on all IP addresses, assigned to the machine it runs on.

Config file equivalent: option { source-ip IP; };.

Note that listen statement in ‘raddb/config’ provides a better control over IP addresses to listen on (see section auth statement, and see section acct statement).

‘-L’

‘--license’

Display GNU General Public License and exit.

‘-l DIR’

‘--logging-directory DIR’

Specify alternate logging directory.

Config file equivalent: option { log-dir DIR; };.

‘-mb’

‘--mode b’

“Builddbm” mode. Builds a DBM version of a plaintext users database. builddbm.

‘-mc’

‘--mode c’

Check configuration files and exit. All errors are reported via usual log channels.

‘-mt’

‘--mode t’

Test mode. In this mode radiusd starts an interactive interpreter which allows to test various aspects of its configuration.

‘-N’

‘--auth-only’

Process only authentication requests.

‘-n’

‘--do-not-resolve’

Do not resolve IP addresses for diagnostic output. This can reduce the amount of network traffic and speed up the server.

Config file equivalent: option { resolve no };.

‘-p PORTNO’

‘--port PORTNO’

Listen the UDP port PORTNO. The accounting port is computed as PORTNO + 1.

‘-P DIR’

‘--pid-file-dir DIR’

Specifies the alternate path for the pidfile.

‘-S’

‘--log-stripped-names’

Log usernames stripped off any prefixes/suffixes.

Config file equivalent: auth { strip-names yes };.

‘-s’

‘--single-process’

Run in single process mode. This is for debugging purposes only. We strongly recommend against using this option. Use it only when absolutely necessary.

‘-v’

‘--version’

Display program version and compilation options.

‘-x DEBUG_LEVEL’

‘--debug DEBUG_LEVEL’

Set debugging level. DEBUG_LEVEL is a comma-separated list of assignments in the forms

MODULE MODULE = LEVEL

where MODULE is the module name or any non-ambiguous assignment thereof, LEVEL is the debugging level in the range 0-100. Debugging

Config file equivalent:

logging { category debug { level DEBUG_LEVEL; }; };

‘-y’

‘--log-auth’

Log authentications. With this option enabled, Radius will log any authentication attempt into its log file Logging.

Config file equivalent: logging { category auth { detail yes; }; }; .

‘-z’

‘--log-auth-pass’

Log passwords along with authentication information. Do not use this option. It is very insecure, since all users' passwords will be echoed in the logfile. This option is provided only for debugging purposes.

Config file equivalent:

logging { category auth { print-pass yes; }; };

See section Run-Time Configuration Options — ‘raddb/config’.

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)

5. Request Comparison Methods

The basic notions about comparison of the incoming requests and why it is necessary were given in Checking for Duplicate Requests. This chapter concentrates on extended methods of request comparison and on the configuration issues.

5.1 Extended Comparison

The default comparison method may fail to recognize duplicate requests. if the originating NAS has modified the request authenticator or request identifier before retransmitting the request. If you happen to use such NASes, you will have to enable extended request comparison to compensate for their deficiencies.

The extended request comparison consists in comparing the contents of both requests. However, blindly comparing each A/V pair from both requests won't work, since many attributes do change their values between successive retransmits. Therefore, radiusd uses only comparable attribute, i.e. a user-defined subset of such attributes that can safely be used in comparison. Thus, extended request comparison works as follows:

1. The comparable attributes are extracted from each request. They form two sorted attribute lists.
2. If lengths of both lists differ, the requests are considered different.
3. Otherwise, the value of each A/V pair from the first list is compared against that of the corresponding A/V pair from the second list. If at least one A/V pair differs, then the requests are considered different. Notice, that values of Password and CHAP-Password are decoded prior to comparison.

To use the extended comparison, follow the procedure below:

1. Select user-defined attribute properties.

   The syntax of dictionary file allows for nine user-defined properties, denoted by characters ‘1’ through ‘9’. You should select one of them to mark comparable attributes for authentication and another one to mark those for accounting. It is strongly suggested that you use PROPERTY statement in your main dictionary file (see section PROPERTY statement), instead of modifying ATTRIBUTE statements in the underlying dictionary files.

   See section ATTRIBUTE statement, for detailed description of attribute property flags.

2. To enable the extended comparison for requests coming from any NAS, declare extended comparison flags in ‘raddb/config’.

   To enable the extended comparison for authentication requests, add to your auth block the statement

   compare-attribute-flag flag;

   The flag is the same symbol you used in the dictionary to mark comparable attributes for authentication.

   To enable the extended comparison for accounting requests, insert compare-attribute-flag statement into the acct block.

3. To enable the extended comparison for requests coming from selected NASes, declare extended comparison flags in ‘raddb/naslist’.

   Add the following statement to the declaration of those NASes, that require using the extended comparison (in flags column):

   compare-auth-flag=flag,compare-acct-flag=flag

   See section NAS List — ‘raddb/naslist’, for a description of naslist file syntax.

5.1.1 An example of extended comparison configuration

In this example configuration, the user-defined flag ‘1’ marks authentication comparable attributes, and the flag ‘2’ marks the accounting comparable attributes.

‘raddb/dictionary’

PROPERTY       User-Name               +12
PROPERTY       Password                +1
PROPERTY       NAS-Port-Id             +12
PROPERTY       State                   +1
PROPERTY       Called-Station-Id       +12
PROPERTY       Calling-Station-Id      +12
PROPERTY       Acct-Status-Type        +2
PROPERTY       Acct-Session-Id         +2
PROPERTY       Acct-Session-Time       +2

‘raddb/config’

        auth {
                max-requests 127;
                request-cleanup-delay 2;
                compare-attribute-flag 1;
        };
        acct {
                max-requests 127;
                request-cleanup-delay 2;
                compare-attribute-flag 2;
        };                

5.1.2 List of attributes that can be declared comparable.

The following attributes can be declared as comparable:

• User-Name
• Password
• CHAP-Password
• NAS-Port-Id
• State
• Called-Station-Id
• Calling-Station-Id
• NAS-Identifier
• Acct-Status-Type
• Acct-Session-Id
• Acct-Session-Time
• User-UID
• User-GID

Notice that this list is by no means an exhaustive one. Depending on a particular NAS other attributes may be safe to be used in comparisons, or, vice-versa, some attributes from this list may not be used. You should carefully analyze packets coming from your NAS before deciding which attributes to mark as comparable.

5.2 Fine-Tuning the Request Queue

As described in Checking for Duplicate Requests, each request is added to the request queue when radiusd starts processing it and is removed from there a certain amount of time after its processing was finished. The configuration parameter request-cleanup-delay defines how long each already processed request is kept in the queue. Its value must be synchronized with the NAS settings.

Each NAS allows to configure two parameters:

Ntimeout

The amount of time in seconds during which the NAS is waiting for a response from radius server.

Nretries

The number of times the NAS tries to re-send the request if it received no response from the radius server.

Of course, these parameters are named differently for different makes of NASes. Refer to your NAS documentation to find out where these values are configured.

In general, these parameters must satisfy the following relation:

     request-cleanup-delay = Nretries * Ntimeout + const

where const is an empirical constant that depends on the average time of processing a single request. Usually its value lies between 0 and 10 seconds.

For example, if the configuration of your NAS sets

   Nretries = 3
   Ntimeout = 10

then your raddb/config should contain:

auth { 
        request-cleanup-delay 40;
};
acct { 
        request-cleanup-delay 40;
};

Notice the duplication of request-cleanup-delay: radiusd uses distinct values for authentication and accounting requests, however most existing NASes do not make such distinction.

6. Authentication

An Authentication Type specifies which credentials the user is required to supply in order to be authenticated and where the user's authentication data are stored. It is defined by the value of Auth-Type attribute in LHS of a ‘users’ entry.

6.1 Accept Authentication Type

Accept is the simplest authentication type. Users with this authentication type will be authenticated successfully without checking any credentials. Actually this means that only username is required for authentication.

This authentication type is used for each ‘users’ entry, whose LHS contains

Auth-Type = Accept

This authentication type can be used for guest accounts, e.g. the following profile in ‘users’:

guest   Auth-Type = Accept,
                Simultaneous-Use = 10
        Service-Type = Framed-User,
                Framed-Protocol = PPP

allows up to 10 simultaneous guest PPP accounts. To log in using such guest account it is sufficient to use username ‘guest’ and any password.

6.2 Reject Authentication Type

The Reject authentication type causes the request to be rejected unconditionally. It can be used to disable a user account (For another method of disabling user accounts, see section List of Blocked Users — ‘raddb/access.deny’).

This authentication type is used for each ‘users’ entry, whose LHS contains

Auth-Type = Reject

6.3 Local Password Authentication Type

The Local Password authentication type allows to keep plaintext user passwords. Although the use of this authentication type is strongly discouraged for security reasons, this is the only authentication type that can be used with CHAP authentication.

There are two ways of using this authentication type

Specifying Passwords in users File.

To keep the plaintext passwords in ‘users’ file, the profile entry must follow this pattern:

user-name  Auth-Type = Local,
                     User-Password = plaintext

The plaintext is the user's plaintext password. Obviously, user-name may not be DEFAULT nor BEGIN.

Specifying Passwords in SQL Database.

user-name   Auth-Type = Local,
                      Password-Location = SQL

When the user is authenticated using such profile, its password is retrieved from the authentication database using auth_query. The configuration of SQL authentication is described in detail in Authentication Server Parameters.

6.4 Encrypted Password Authentication Type

The Encrypted Password type allows to keep user's passwords encrypted via DES or MD5 algorithm. There are two ways of using this authentication type.

Specifying Passwords in users File.

user-name  Auth-Type = Crypt-Local,
                     User-Password = crypt-pass

The Crypt-Password is a shortcut for the above notation:

user-name  Crypt-Password = crypt-pass

Specifying Passwords in SQL Database.

user-name   Auth-Type = Crypt-Local,
                      Password-Location = SQL

Using this profile, the user's password is retrieved from the authentication database using auth_query. The configuration of SQL authentication is described in detail on Authentication Server Parameters.

The shortcut for this notation is Auth-Type = SQL.

In any case, the passwords used with this authentication type must be either DES or MD5 hashed.

6.5 System Authentication Type

The System authentication type requires that the user have a valid system account on the machine where the radius server is running. The use of this type is triggered by setting

Auth-Type = System

in the LHS of a ‘users’ entry.

6.6 SQL Authentication Type

Setting Auth-Type = SQL or Auth-Type = Mysql in the LHS of a ‘users’ entry is a synonym for

Auth-Type = Crypt-Local, Password-Location = SQL

and is provided as a shortcut and for backward compatibility with previous versions of GNU Radius.

For description of SQL authentication, see Encrypted Password Authentication Type. The configuration of SQL subsystem is described in SQL Configuration — ‘raddb/sqlserver’.

6.7 PAM Authentication Type

PAM authentication type indicates that a user should be authenticated using PAM (Pluggable Authentication Module) framework. The simplest way of usage is:

Auth-Type = PAM

Any user whose ‘users’ profile contains the above, will be authenticated via PAM, using service name ‘radius’. If you wish to use another service name, set it using Auth-Data attribute, e.g.:

Auth-Type = PAM,
    Auth-Data = pam-service

6.8 Defining Custom Authentication Types

The are three ways to define custom authentication types:

1. Write a PAM module.
2. Use a Guile procedure.
3. Use an external program

You can write a PAM module implementing the new authentication type. Then, specifying Auth-Type = PAM allows to apply it (see section PAM Authentication Type).

Alternatively, you may write a Scheme procedure implementing the new authentication type. To apply it, use Scheme-Procedure attribute in RHS. The Auth-Type = Accept can be used in LHS if the whole authentication burden is to be passed to the Scheme procedure. For example, if one wrote a procedure my-auth, to apply it to all users, one will place the following profile in his ‘users’ file:

DEFAULT  Auth-Type = Accept
         Scheme-Procedure = "my-auth"

For a discussion of how to write Scheme authentication procedures, See section Authentication with Scheme.

The third way to implement your own authentication method is using an external program. This is less effective than the methods described above, but may be necessary sometimes. To invoke the program, use the following statement in the RHS of ‘users’ entry:

Exec-Program-Wait = "progname args"

The progname must be the full path to the program, args — any arguments it needs. The usual substitutions may be used in args to pass any request attributes to the program (see section Macro Substitution).

For a detailed description of Exec-Program-Wait attribute and an example of its use, see Exec-Program-Wait.

6.9 Multiple Login Checking

The number of sessions a user can have open simultaneously can be restricted by setting Simultaneous-Use attribute in the user's profile LHS (see section Simultaneous-Use). By default the number of simultaneous sessions is unlimited.

When a user with limited number of simultaneous logins authenticates himself, Radius counts the number of the sessions that are already opened by this user. If this number is equal to the value of Simultaneous-Use attribute the authentication request is rejected.

This process is run in several stages. First, Radius retrieves the information about currently opened sessions from one of its accounting databases. Then, it verifies whether all these sessions are still active. This pass is necessary since an open entry might be a result of missing Stop request. Finally, the server counts the sessions and compares their count with the value of Simultaneous-Use attribute.

The following subsections address each stage in detail.

6.9.1 Retrieving Session Data

Radius retrieves the list of sessions currently opened by the user either from the system database (see section System Accounting), or from the SQL database (see section sql Accounting). The system administrator determines which method to use.

By default, system accounting database is used. Its advantages are simplicity and ease of handling. It has, however, a serious deficiency: the information is kept in the local files. If you run several radius servers, each of them has no easy way of knowing about the sessions initiated by other servers.

This problem is easy to solve if you run SQL accounting (see section sql Accounting). In this case, each radius server stores the data in your SQL database and can easily retrieve them from there.

To enable use of SQL database for multiple login checking, do the following:

In your ‘raddb/config’ file set:

mlc {
    method sql;
};

In your ‘raddb/sqlserver’ file, specify the queries for retrieving the information about open sessions and, optionally, a query to close an existing open record.

There are two queries for retrieving the information: mlc_user_query returns the list of sessions opened by the user, mlc_realm_query returns the list of sessions opened for the given realm. Each of them should return a list of 4-element tuples(4):

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

Here is an example of mlc_user_query and mlc_realm_query:

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}'     

Apart from these two queries you may also wish to provide a query for closing a hung record. By default, radiusd will use acct_stop_query. If you wish to override it, supply a query named mlc_stop_query, for example:

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}' 

See section Writing SQL Accounting Query Templates, for detailed information on how to write these queries.

6.9.2 Verifying Active Sessions

Whatever database radiusd uses, an open entry in it does not necessary mean that the corresponding session is still being active. So, after retrieving the information about user sessions, Radius verifies on corresponding NASes whether these are actually active.

For each entry in the session list, if its NAS acknowledges the session, the session count is incremented. Otherwise, such entry is marked as closed in the database and is not counted.

There may also be cases when the NAS is unreachable due to some reasons. In such cases the Radius behavior is determined by the value of checkrad-assume-logged in ‘config’ file auth statement (raddb/config). If the value is yes, Radius assumes the session is still active and increases the session count, otherwise it proceeds as if the NAS returned negative reply.

To query a NAS, Radius first looks up its type and additional parameters in ‘naslist’ file (see section NAS List — ‘raddb/naslist’). There are two predefined NAS types that cause Radius to act immediately without querying tne NAS: the special type ‘true’ forces Radius to act as if the NAS returned 1, the type ‘false’ forces it to act as if the NAS returned 0. If the type is neither of this predefined types, Radius uses it as a look up key into the ‘nastypes’ file (see section NAS Types — ‘raddb/nastypes’) and tries to retrieve an entry which has matching type. If such entry does not exist, Radius issues the error message and acts accordingly to the value of configuration variable checkrad-assume-logged. Otherwise, Radius determines the query method to use from the second field of this entry, and constructs method arguments by appending arguments from the ‘naslist’ entry to those of nastypes entry. Note, that the former take precedence over the latter, and can thus be used to override default values specified in ‘nastypes’.

Having determined the query method and its argument, Radius queries NAS and analyzes its output by invoking a user-supplied Rewrite function. The function to use is specified by the function= argument to the method. It is called each time a line of output is received from the NAS (for finger queries) or a variable is received (for SNMP queries). The process continues until the function returns 1 or the last line of output is read or a timeout occurs whichever comes first.

If the user-function returns 1 it is taken to mean the user's session is now active at the NAS, otherwise, if it replies 0 or if the end of output is reached, it is taken to mean the user's session is not active.

The syntax conventions for user-supplied functions are described in detail in Login Verification Functions.

6.10 Controlling Authentication Probes

Authentication probe is an attempt of a user to use other user's account, by guessing his password. The obvious indication of an authentication probe is appearence of several consecutive authentication failures for the same user. Of course, if the intruder is given sufficient number of such probes he will sooner or later succeed in finding the actual password. The conventional method to prevent this from occurring is to keep failure counters for each user and to lock the account when its failure counter reaches a predefined limit. Notice that a legitimate user may fail (sometimes even several times in sequence) in entering his password, so two important points should always be observed. First, failure counters record the number of consecutive authentication failures and they are reset after each successive authentication. Secondly, the maximum number of allowed consecutive failures should be set sufficiently high.

The version 1.6 offers two ways for controlling authentication probes: using external programs and using special SQL queries.

To control authentication probes using external programs, use the combination of Exec-Program-Wait and Auth-Failure-Trigger. The program specified by Auth-Failure-Trigger is executed each time an authentication attempt failed. When both attributes are used together, the program invoked by Auth-Failure-Trigger can update the failure counter, and the one invoked by Exec-Program-Wait can compare the counter value with the predefined limit and reject authentication when both values become equal. Such approach is most useful in conjunction with BEGIN profile.

Let's suppose the program ‘/sbin/check_failure’ accepts a user name and returns 1 if the failure counter for this user has reached maximum allowed value. Otherwise it returns 0 and clears the counter. Another program, ‘/sbin/count_failure’ increases failure counter value for the given user name. Assuming our basic authentication type is ‘PAM’, the ‘raddb/users’ file will look as follows:

BEGIN   NULL
        Exec-Program-Wait = "/sbin/check_failure  %C{User-Name}",
        Auth-Failure-Trigger = "/sbin/count_failure %C{User-Name}",
                Fall-Through = Yes

DEFAULT Auth-Type = PAM
        Service-Type = Framed-User,
                Framed-Protocol = PPP

[… Other profiles …]                

The BEGIN profile will be executed before any other profile. It will add to the RHS Exec-Program-Wait and Auth-Failure-Trigger attributes and then radiusd will proceed to finding a matching profile (due to Fall-Through attribute). When such profile is found, the user will be authenticated according to the method set up by the profile's Auth-Type attribute. If authentication fails, ‘/sbin/count_failure’ will be called and the user name passed to it as the argument. Otherwise, ‘/sbin/check_failure’ will be invoked.

To complete the example, here are working versions of both programs. Failure counters for each user name are kept in separate file in ‘/var/log/radius/fails’ directory. Both programs are written in bash.

The /sbin/count_failure program

#! /bin/bash

test $# -eq 1 || exit 1

MAXFAIL=8
REGDIR=/var/log/radius/fails

if [ -r "$REGDIR/$1" ]; then
  read COUNT < "$REGDIR/$1"
  COUNT=$((COUNT+1))
else
  COUNT=1
fi
echo $COUNT > "$REGDIR/$1"      
# End of /sbin/count_failure

The /sbin/check_failure program

#! /bin/bash

test $# -eq 1 || exit 1

MAXFAIL=8
REGDIR=/var/log/radius/fails

if [ -r "$REGDIR/$1" ]; then
  read COUNT < "$REGDIR/$1"
  if [ $COUNT -ge $MAXFAIL ]; then
    echo "Reply-Message=\"Too many login failures. Your account is locked\""
    exit 1
  else
    rm "$REGDIR/$1"
  fi
fi
exit 0

# End of check_failure

Another way of controlling authentication probes is by using SQL database to store failure counters. Two queries are provided for this purpose in ‘raddb/sqlserver’ file: auth_success_query is executed upon each successful authentication, and auth_failure_query is executed upon each authentication failure. Both queries are not expected to return any values. One obvious purpose of auth_failure_query would be to update failure counters and that of auth_success_query would be to clear them. The auth_query or group_query should then be modified to take into account the number of authentication failures.

The default SQL configuration GNU Radius is shipped with provides a working example of using these queries. Let's consider this example.

First, we create a special table for keeping authentication failure counters for each user:

CREATE TABLE authfail (
  # User name this entry refers to
  user_name           varchar(32) binary default '' not null,
  # Number of successive authentication failures for this user
  count               int,
  # Timestamp when this entry was last updated
  time                datetime DEFAULT '1970-01-01 00:00:00' NOT NULL,
  # Create a unique index on user_name
  UNIQUE uname (user_name)
);

The query auth_fail_query will increment the value of count column for the user in question:

auth_failure_query UPDATE authfail \
                   SET count=count+1,time=now() \
                   WHERE user_name='%C{User-Name}'

The query auth_success_query will clear count:

auth_success_query UPDATE authfail \
                   SET count=0,time=now() \
                   WHERE user_name='%C{User-Name}'

Now, the question is: how to use this counter in authentication? The answer is quite simple. First, let's create a special group for all the users whose authentication failure counter has reached its maximum value. Let this group be called ‘*LOCKED_ACCOUNT*’. We'll add the following entry to ‘raddb/users’:

DEFAULT Group = "*LOCKED_ACCOUNT*",
                Auth-Type = Reject
        Reply-Message = "Your account is currently locked.\n\
Please, contact your system administrator\n"

which will reject all such users with an appropriate reply message.

The only thing left now is to rewrite group_query so that it returns ‘*LOCKED_ACCOUNT*’ when authfail.count reaches its maximum value. Let's say this maximum value is 8. Then the following query will do the job:

group_query       SELECT user_group FROM groups \
                  WHERE user_name='%u' \
                  UNION \
                  SELECT CASE WHEN (SELECT count > 8 FROM authfail \
                                                 WHERE user_name='%u')
                         THEN '*LOCKED_ACCOUNT*' END

The default configuration comes with these queries commented out. It is up to you to uncomment them if you wish to use SQL-based control over authentication failures.

Notice the following important points when using this approach:

1. Your SQL server must support UNION. Earlier versions of MySQL lacked this support, so if you run MySQL make sure you run a reasonably new version (at least 4.0.18).
2. Both auth_failure_query and auth_success_query assume the database already contains an entry for each user. So, when adding a new user to the database, make sure to insert an appropriate record into authfails table, e.g.

   INSERT INTO authfail VALUES('new-user',0,now());

7. Accounting

By default GNU Radius supports three types of accounting. Any additional accounting methods can be defined using extension mechanisms.

The accounting methods are applied to a request in a following sequence:

1. System accounting
2. Detailed request accounting
3. sql accounting
4. Custom accounting

Any method can be enabled or disabled. Thus, you can even disable them all, thereby disabling accounting altogether.

Notice, that the multiple login checking scheme relies on accounting being enabled. By default it uses system accounting, but can also be configured to use sql accounting. So, if you disable system accounting and still wish to use reliable multiple login checking, make sure you configure radiusd to use sql for this purpose. See section Multiple Login Checking, for the detailed information about the subject.

If any accounting type in this sequence fails, the accounting is deemed to fail and all subsequent methods are not invoked.

7.1 System Accounting

Radius keeps files ‘radutmp’ and ‘radwtmp’ in its logging directory and stores the accounting data there. The utilities radwho and radlast can be used to list information about users' sessions.

This accounting method is enabled by default. To disable it, use system no statement in ‘raddb/config’. See section acct statement, for more information. Please notice that disabling this authentication method will disable multiple login checking as well. Refer to Multiple Login Checking, for the detailed discussion of this.

7.2 Detailed Request Accounting

Radius stores the detailed information about accounting packets it receives in files ‘radacct/nasname/detail’ (see section Naming Conventions), where nasname is replaced with the short name of the NAS from the ‘raddb/naslist’ file (see section NAS List — ‘raddb/naslist’).

By default, this accounting type is always enabled, provided that ‘radacct’ directory exists and is writable (see section Naming Conventions). To turn the detailed accounting off, use the detail statement in the ‘config’ file. For more information about it, see acct statement.

The accounting detail files consist of a record for each accounting request. A record includes the timestamp and detailed dump of attributes from the packet, e.g.:

Fri Dec 15 18:00:24 2000
        Acct-Session-Id = "2193976896017"
        User-Name = "e2"
        Acct-Status-Type = Start
        Acct-Authentic = RADIUS
        Service-Type = Framed-User
        Framed-Protocol = PPP
        Framed-IP-Address = 11.10.10.125
        Calling-Station-Id = "+15678023561"
        NAS-IP-Address = 11.10.10.11
        NAS-Port-Id = 8
        Acct-Delay-Time = 0
        Timestamp = 976896024
        Request-Authenticator = Unverified

Fri Dec 15 18:32:09 2000
        Acct-Session-Id = "2193976896017"
        User-Name = "e2"
        Acct-Status-Type = Stop
        Acct-Authentic = RADIUS
        Acct-Output-Octets = 5382
        Acct-Input-Octets = 7761
        Service-Type = Framed-User
        Framed-Protocol = PPP
        Framed-IP-Address = 11.10.10.125
        Acct-Session-Time = 1905
        NAS-IP-Address = 11.10.10.11
        NAS-Port-Id = 8
        Acct-Delay-Time = 0
        Timestamp = 976897929
        Request-Authenticator = Unverified

Notice that radiusd always adds two pseudo-attributes to detailed listings. Attribute Timestamp shows the UNIX timestamp when radiusd has received the request. Attribute Request-Authenticator shows the result of checking the request authenticator. Its possible values are:

Verified

The authenticator check was successful.

Unverified

The authenticator check failed. This could mean that either the request was forged or that the remote NAS and radiusd do not agree on the value of the shared secret.

None

The authenticator check is not applicable for this request type.

Notice also that the so-called internal attributes by default are not logged in the detail file. Internal attributes are those whose decimal value is greater than 255. Such attributes are used internally by radius and cannot be transferred via RADIUS protocol. Examples of such attributes are Fall-Through, Hint and Huntgroup-Name. See section Radius Internal Attributes, for detailed listing of all internal attributes. The special attribute flag l (lower-case ell) may be used to force logging of such attributes (see section ATTRIBUTE statement).

7.3 sql Accounting

The sql accounting method is enabled when Radius is configured with ‘--enable-sql’ option and the ‘sqlserver’ file in its configuration directory is properly set up (see section SQL Configuration — ‘raddb/sqlserver’).

This version of GNU Radius (1.6) supports MySQL and PostgreSQL servers. It also supports odbc, which can be used to build interfaces to another database management systems.

With this accounting method enabled, radiusd will store the information about accounting requests in the configured sql database. The accounting method is fully configurable: the Radius administrator defines both the types of requests to be accounted and the information to be stored into the database (see section SQL Configuration — ‘raddb/sqlserver’).

7.4 Defining Custom Accounting Types

If the built-in accounting methods do not meet your requirements, you can implement your own. There are two ways of doing so:

1. Using a Guile procedure.
2. Using an external program

To use a Guile procedure for accounting, the name of the procedure must be specified as a value to the Scheme-Acct-Procedure attribute in the RHS list of a ‘hints’ entry, e.g.:

DEFAULT NULL Scheme-Acct-Procedure = "my-acct"

For a detailed description of Scheme accounting procedures, see section Accounting with Scheme.

Another way of implementing your own accounting method is using an external program. This is less effective than the methods described above, but may be necessary sometimes. To invoke the program, use the following statement in the LHS of the ‘hints’ entry:

Acct-Ext-Program = "progname args"

The progname must be the full path to the program, and args any arguments it needs. The usual substitutions may be used in args to pass any request attributes to the program (see section Macro Substitution).

For a detailed description of Acct-Ext-Program, see section Acct-Ext-Program.

8. Logging

GNU Radius reports every event worth mentioning. The events are segregated by their severity level. Radius discerns the following levels (in order of increasing severity):

Debug

The debug messages (Debugging).

Auth

Under this level every authentication attempt is logged. This is enabled by setting

level auth;

in the category auth statement of the ‘config’ file.

Proxy

Messages regarding proxy requests (see section Proxying).

Info

Informational messages.

Notice

Normal, but significant conditions.

Warning

Warning conditions. These mean some deviations from normal work.

Error

Error conditions. Usually these require special attention.

CRIT

Critical conditions due to which Radius is no longer able to continue working. These require urgent actions from the site administrator.