GNU Radius Reference Manual

GNU Radius is a suite of programs for performing user authentication and accounting using RADIUS protocol.

This Info file documents the version 1.3 of the package.

Introduction to Radius    An introduction to RADIUS concepts

The RADIUS daemon

2. Naming Conventions    Conventions about naming files and directories

3. How Radius Operates    How radiusd operates

4. How to Start the Daemon.    How to start the daemon

5. Radius Configuration Files    radiusd configuration files

6. Request Comparison Methods    How duplicate requests are dealt with

7. Authentication    How users are authenticated

8. Accounting    Accounting methods

9. Logging    What gets logged and where

10. Problem Tracking    Fixing configuration errors

11. Extensions    Extending GNU Radius

12. Utility Programs

13. Client Package

Radius Attributes

14. Attribute List    Some frequently used attributes

Reporting Bugs and getting information

15. Reporting Bugs    How to report a bug

16. Where to Get Information about GNU Radius    Where to get info about GNU Radius

Obtaining GNU Radius

How to Obtain Radius    How to Obtain the GNU Radius

Radius Glossary    The glossary

Acknowledgements

What Next?

17. New Configuration Approach (draft)    New configuration

Appendices

A. GNU Free Documentation License    The GNU Free Documentation License.

Indices

Index

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

5.1 Run-Time Configuration Options -- `raddb/config'    Run-time configuration options.

5.2 Dictionary of Attributes -- `raddb/dictionary'    Radius dictionary.

5.3 Clients List -- `raddb/clients'    Clients lists the NASes that are allowed to communicate with radius.

5.4 NAS List -- `raddb/naslist'    The naslist file keeps general information about the NASes.

5.5 NAS Types -- `raddb/nastypes'    Information about how to query the NASes about active user sessions.

5.6 Request Processing Hints -- `raddb/hints'    Important user information that is common for the users whose names match some pattern.

5.7 Huntgroups -- `raddb/huntgroups'    Group users by the NAS (and, possibly, a port number) they come from.

5.8 List of Proxy Realms -- `raddb/realms'    Communication with remote radius servers

5.9 User Profiles -- `raddb/users'    User profile.

5.10 List of Blocked Users -- `raddb/access.deny'    List of users which are denied access.

5.11 SQL Configuration -- `raddb/sqlserver'    SQL server configuration.

5.12 Rewrite functions -- `raddb/rewrite'    Rewrite functions allow to change the input packets.

5.13 Login Menus -- `raddb/menus'    Menus allow user to select the type of service.

Client configuration

13.1 Client Configuration    Main client configuration file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

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.

1.0 Overview

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.0 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2. 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 8.2 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:

Directory Short name Default location

Configuration directory `raddb' /usr/local/etc/raddb

Log directory `radlog' /var/log

Accounting directory `radacct' /var/log/radacct

Data directory `datadir' /usr/local/share/radius/1.3

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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3. 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.

3.1 Attributes

3.2 RADIUS Requests    RADIUS requests.

3.3 Matching Rule    Rules for request processing.

3.4 Processing Requests    How GNU Radius processes incoming requests.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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 5.2 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 3.4.2.1 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 5.2.4 ATTRIBUTE statement. For information about particular attributes, see 14. Attribute List.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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.

3.2.1 Authentication Requests

3.2.2 Accounting Requests

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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 14.1.24 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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 8. 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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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 9. 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 5.3 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 5.6 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 5.7 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 3.4.2 Proxying, for the description of this process.
Process individual user profiles: This step applies only to authentication requests.

3.4.1 Checking for Duplicate Requests

3.4.2 Proxying

3.4.3 Hints

3.4.4 Huntgroups

3.4.5 User Profiles

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.4.1 Checking for Duplicate Requests

As described above (see section 3. 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:

The NAS sends a request to the server.
The server processes it and sends back the reply.
The reply is lost due to a network outage, or the load average of the NAS is too high and it drops the response.
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 5.1.3 auth statement, parameter request-cleanup-delay).

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

Both requests come from the same NAS.
They are of the same type.
The request identifier is the same for both requests.
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 6.1 Extended Comparison.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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.

3.4.2.1 Proxy Service

3.4.2.2 Realms

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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 3.1 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 3.4.5 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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:

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'.
A default realm defines the server to which the requests for realms not mentioned explicitly in the configuration are forwarded.
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 5.8 List of Proxy Realms -- `raddb/realms').

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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 3.3 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 5.14 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 5.6 Request Processing Hints -- `raddb/hints').

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.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 3.3 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 14.3.12 Huntgroup-Name).

Huntgroup rules are defined in the `raddb/huntgroups' file (see section 5.7 Huntgroups -- `raddb/huntgroups').

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.4.5 User Profiles

User profiles are per-user matching rules (see section 3.3 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 5.9 User Profiles -- `raddb/users').

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4. 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 5.1 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' 2. 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 5.1.3 auth statement, and see section 5.1.4 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. 12.8 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. 10.2 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 9. 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 5.1 Run-Time Configuration Options -- `raddb/config'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5. 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 2. 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 7.9 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.

5.1 Run-Time Configuration Options -- `raddb/config'    Run-time configuration options.

5.2 Dictionary of Attributes -- `raddb/dictionary'    Radius dictionary.

5.3 Clients List -- `raddb/clients'    Clients lists the NASes that are allowed to communicate with radius.

5.4 NAS List -- `raddb/naslist'    The naslist file keeps general information about the NASes.

5.5 NAS Types -- `raddb/nastypes'    Information about how to query the NASes about active user sessions.

5.6 Request Processing Hints -- `raddb/hints'    Important user information that is common for the users whose names match some pattern.

5.7 Huntgroups -- `raddb/huntgroups'    Group users by the NAS (and, possibly, a port number) they come from.

5.8 List of Proxy Realms -- `raddb/realms'    Communication with remote radius servers

5.9 User Profiles -- `raddb/users'    User profile.

5.10 List of Blocked Users -- `raddb/access.deny'    List of users which are denied access.

5.11 SQL Configuration -- `raddb/sqlserver'    SQL server configuration.

5.12 Rewrite functions -- `raddb/rewrite'    Rewrite functions allow to change the input packets.

5.13 Login Menus -- `raddb/menus'    Menus allow user to select the type of service.

5.14 Macro Substitution    Macros which are expanded by the actual attribute values.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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:

5.1.1 option block    Option block: set the global program options.

5.1.2 logging block    Fine-tune the logging.

5.1.3 auth statement    Configure authentication service.

5.1.4 acct statement    Configure accounting service.

5.1.5 usedbm statement    Enable the DBM feature.

5.1.6 snmp statement    Configure SNMP service.

5.1.7 rewrite statement.    Configure Rewrite interface.

5.1.8 guile statement    Configure Guile interface.

5.1.9 message statement    Configure server reply messages.

5.1.10 filters statement    Configure authentication and accounting filters.

5.1.11 mlc statement    Configure multiple login checking.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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:

All configuration files must be readable for this user.
Authentication type System (see section 7.5 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.
Authentication type PAM (see section 7.7 PAM Authentication Type) may require root provileges. It is reported to always require root privileges on some systems (notably on Solaris).
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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 ; 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.

5.1.2.1 Logging hooks

5.1.2.2 category statement

5.1.2.3 channel statement

5.1.2.4 Example of the logging statement

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 11.2.7 Logging Hook Functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 2. Naming Conventions). The syslog statement sends the channel's output to syslog with the specified facility and severity.

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 5.1.2.1 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 5.1.2.1 Logging hooks). This overrides any global suffix hook.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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; }; };

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 8.2 Detailed Request Accounting).
strip-names: Determines whether radiusd should strip any prefixes/suffixes off the username before logging.
checkrad-assume-logged: See section 5.1.11 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 10.1 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 6.1 Extended Comparison, for a detailed description of its usage.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 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 8.2 Detailed Request Accounting).
system: When set to no, disables system accounting (see section 8.1 System Accounting). Notice, that this will disable simultaneous use checking as well, unless you supply an alternative MLC method (currently SQL, See section 7.9 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 10.1 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 6.1 Extended Comparison, for a detailed description of its usage.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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. <FIXME> Describe the loading process in detail. Also, some kind of autoloading is necessary for Rewrite. </>

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 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. <FIXME> Describe the loading sequence in more detail. Why are modules preferred over plain SCM programs, etc. </>
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 11.3 Guile, for a detailed description of Guile extensions interface.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 5.14 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 5.1.3 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 3.4.2.2 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 14.3.25 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 14.3.14 Login-Time.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.1.10 `filters` statement

The filters statement configures user-defined external filters. See section 11.1 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 14.3.7 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 5.14 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.1.11 `mlc` statement

Syntax

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

Usage

Mlc statement configures multiple login checking subsystem (see section 7.9 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 8.1 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 7.9 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.2 Dictionary of Attributes -- `raddb/dictionary'

The dictionary file `raddb/dictionary' defines the symbolic names for radius attributes and their values (see section 3.1 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.

5.2.1 Comments    Introducing a comment line.

5.2.2 $INCLUDE Statement    Include a file.

5.2.3 VENDOR Statement    Define a vendor-id.

5.2.4 ATTRIBUTE statement    Define an attribute translation.

5.2.5 Blocks of Vendor-Specific Attributes    Blocks of vendor-specific attributes

5.2.6 ALIAS statement    Define alternative name for an attribute.

5.2.7 PROPERTY statement    Define attribute properties.

5.2.8 VALUE Statement    Define a value translation.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 14.1.26 Vendor-Specific.

Example

VENDOR  Livingston  307

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 3.1 Attributes).

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

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'.
The attribute additivity is described by one of the following letters:

=
Additivity = Replace
+
Additivity = Append
N
Additivity = None
The presence of letter `P' in property flags raises the propagation bit.
Letter `l' (lower-case ell) enables logging the given attribute in detail file (see section 8.2 Detailed Request Accounting). This is meaningful only for internal attributes, i.e. the ones whose decimal value is greater than 255 (see section 14.3 Radius Internal Attributes). By default such attributes do not appear in detailed logs. The flag `l' reverts this behavior.
Letter `E' marks attributes encrypted as described in RFC 2138. Currently these are User-Password and CHAP-Password.
Letter `T' marks attribute encrypted according to RFC 2868.
The characters from `1' to `9' denote nine user-defined flags (see section 6.1 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 5.2.3 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 5.2.3 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 5.2.4 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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.

5.3.1 Example of `clients' file An example of clients file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 7.9 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 5.5 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 7.9 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 5.1.3 auth statement) for this particular NAS. See section 6.1 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 5.1.4 acct statement) for this particular NAS. See section 6.1 Extended Comparison, for a detailed description of its usage.

See section 3.4.1 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.

5.4.1 Example of `naslist' file

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.5 NAS Types -- `raddb/nastypes'

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

5.5.1 Syntax of `raddb/nastypes'    Syntax described.

5.5.2 Example of nastypes file.

5.5.3 Standard NAS types    NAS types defined in standard nastypes file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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.3 of GNU Radius supports following querying methods: finger, snmp, external and guile. <FIXME> Describe these fully </> .

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 11.2.5 Login Verification Functions). This argument must be present. For description of how this function is applied, see 7.9 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: <FIXME> Describe new syntax for extendable strings. Notice, that the use of old meta-characters is deprecated. </>

`%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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.5.3 Standard NAS types

The `nastypes' shipped with version 1.3 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 5.4 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 3.4.3 Hints.

The file contains data in Matching Rule format (see section 3.3 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.

5.6.1 Example of `hints' file An example of `hints' file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.7 Huntgroups -- `raddb/huntgroups'

The `raddb/huntgroups' contains the definitions of the huntgroups. For a detailed description of huntgroup concept, See section 3.4.4 Huntgroups.

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

5.7.1 Example of `huntgroups' file. An example of the `huntgroups' file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 3.4.2 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 3.4.2.2 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.

5.8.1 Example of `realms' file An example of `realms' file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.9 User Profiles -- `raddb/users'

File `raddb/users' contains the list of User Profiles. See section 3.4.5 User Profiles, for a description of its purpose.

5.9.1 Example of `users' file An example of `users' file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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.

5.11.1 SQL Client Parameters

5.11.2 Authentication Server Parameters

5.11.3 Authorization Parameters

5.11.4 Accounting Parameters

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 7.10 Controlling Authentication Probes, for the detailed discussion of its purpose.
auth_failure_query string: This query is executed upon an authentication failure. See section 7.10 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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:

=

user_name attr value op

jsmith NAS-IP-Address 10.10.10.1

jsmith NAS-Port-Id 20 <=

jsmith Framed-Protocol PPP NULL

jsmith Framed-IP-Address 10.10.10.11 NULL

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

Radius finds the matching entry (DEFAULT) in the `raddb/users'.
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
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.
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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 3.2.2 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 5.11.4.1 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 7.9 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.

5.11.4.1 Writing SQL Accounting Query Templates Writing SQL accounting query templates.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 7.9 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 7.9.1 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 7.9.2 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}'

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.12 Rewrite functions -- `raddb/rewrite'

The file `raddb/rewrite' contains definitions of Rewrite extension functions. For information regarding Rewrite extension language See section 11.2 Rewrite.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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'.

5.13.1 A menu file syntax.

5.13.2 An example of menu files

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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"

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.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 5.2.8 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.

<FIXME> The quoting rules are not flexible enough. For example, a string 'isn't it a string' may be produced, but backslash escape within a singly quoted string is useless in most implementations (e.g. in shell or SQL). Besides, quoting unconditionally replaces unprintable characters with their octal values, where the notion of "unprintable" is determined by the current locale. Is it always the right thing to do? </>

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.

<FIXME> Should the quoting rules apply for defval as well? I'd say they should... </>

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)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6. Request Comparison Methods

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

6.1 Extended Comparison

6.2 Fine-Tuning the Request Queue

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.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:

The comparable attributes are extracted from each request. They form two sorted attribute lists.
If lengths of both lists differ, the requests are considered different.
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:

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 5.2.7 PROPERTY statement), instead of modifying ATTRIBUTE statements in the underlying dictionary files.
See section 5.2.4 ATTRIBUTE statement, for detailed description of attribute property flags.
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.
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 5.4 NAS List -- `raddb/naslist', for a description of naslist file syntax.

6.1.1 An example of extended comparison configuration

6.1.2 List of attributes that can be declared comparable.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.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; };

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.2 Fine-Tuning the Request Queue

As described in 3.4.1 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7. 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.

7.1 Accept Authentication Type    Accept unconditionally.

7.2 Reject Authentication Type    Reject unconditionally.

7.3 Local Password Authentication Type    Authenticate using plaintext password.

7.4 Encrypted Password Authentication Type    Authenticate using MD5 encrypted password.

7.5 System Authentication Type    Authenticate using system account.

7.6 SQL Authentication Type    Authenticate using SQL.

7.7 PAM Authentication Type    Authenticate using PAM.

7.8 Defining Custom Authentication Types

7.9 Multiple Login Checking    Checking for Simultaneous Logins.

7.10 Controlling Authentication Probes

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.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 5.10 List of Blocked Users -- `raddb/access.deny').

This authentication type is used for each `users' entry, whose LHS contains

Auth-Type = Reject

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.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 5.11.2 Authentication Server Parameters.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.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 5.11.2 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.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 7.4 Encrypted Password Authentication Type. The configuration of SQL subsystem is described in 5.11 SQL Configuration -- `raddb/sqlserver'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.8 Defining Custom Authentication Types

The are three ways to define custom authentication types:

Write a PAM module.
Use a Guile procedure.
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 7.7 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 11.3.2 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 5.14 Macro Substitution).

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.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 14.3.25 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.

7.9.1 Retrieving Session Data

7.9.2 Verifying Active Sessions

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.9.1 Retrieving Session Data

Radius retrieves the list of sessions currently opened by the user either from the system database (see section 8.1 System Accounting), or from the SQL database (see section 8.3 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 8.3 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 5-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:

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:

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.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 5.4 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 5.5 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 11.2.5 Login Verification Functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.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 countrer 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 sufficiantly high.

The version 1.3 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:

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).
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());

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8. 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:

System accounting
Detailed request accounting
SQL accounting
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 7.9 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.

8.1 System Accounting    UNIX style utmp/wtmp accounting.

8.2 Detailed Request Accounting    Detailed requests.

8.3 SQL Accounting    Accounting to SQL server.

8.4 Defining Custom Accounting Types

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.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. <FIXME> Should they work if other mlc method is used? </>

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.2 Detailed Request Accounting

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

By default, this accounting type is always enabled, provided that `radacct' directory exists and is writable (see section 2. Naming Conventions). To turn the detailed accounting off, use the detail statement in the `config' file. For more information about it, see 5.1.4 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 14.3 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 5.2.4 ATTRIBUTE statement).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.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 5.11 SQL Configuration -- `raddb/sqlserver').

This version of GNU Radius (1.3) 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 5.11 SQL Configuration -- `raddb/sqlserver').

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.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:

Using a Guile procedure.
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 11.3.3 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 5.14 Macro Substitution).

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9. 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 (10.2 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 3.4.2 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.

By default, all messages in all levels are output to the file `radlog/radius.log'. In addition, messages in level CRIT are also duplicated to the system console. These defaults can be overridden using logging statement in the `raddb/config' file. (See section logging statement, for the description of logging statement syntax; see section 2. Naming Conventions for information about the locations of different Radius configuration files.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10. Problem Tracking

10.1 Rule Tracing    Tracing rules.

10.2 Debugging    Enabling full debugging information.

10.3 Test Mode    Running radius in test mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.1 Rule Tracing

If you have more than one entry in your `users' file it is not always obvious which of the entries were used for authentication. The authentication data flow becomes even harder to understand if there are some complex rules in the `hints' and `huntgroups' files.

The rule tracing mode is intended to help you find out the exact order of the rules that each request matched during processing. The mode is toggled by trace-rules statement in auth or acct block of your `config' file. When rule tracing mode is on for a given type of requests, radiusd will display the data flow diagram for each processed request of this type. The diagram is output on info logging category, it represents the list of rules in reverse chronological order. Each rule is represented by its location in the form filename:line. To make the output more compact, if several rules appear in the same configuration file, their locations are listed as a comma-separated list of numbers after the file name. Furthermore, if the configuration files have the same path prefix, then only the first file name appears with the full prefix.

Here is an example of trace rule diagram:

Oct 31 11:37:17 [28322]: Auth.info: (Access-Request foo 170 bar): rule trace: /etc/raddb/users:157,22,3; huntgroups:72; hints:34

This diagram means, that the authentication request from server `foo' for user `bar' with ID 170 matched the following rules

File name Line number

`/etc/raddb/hints' 34

`/etc/raddb/huntgroups' 72

`/etc/raddb/users' 3

`/etc/raddb/users' 22

`/etc/raddb/users' 157

As a practical example, let's suppose you have the following setup. There are three classes of users:

Users from group "root" are authenticated using system password database and get rlogin access to the server 192.168.10.1
Users from group "staff" are also authenticated using system password database, but they are granted only telnet access to the server 192.168.10.2
Finally, the rest of users is authenticated against SQL database and get usual PPP access.

In addition, users from the first two classes are accounted using custom Scheme procedure staff-acct.

The configuration files for this setup are showed below:

Contents of `hints':

DEFAULT Group = "root" Scheme-Acct-Procedure = "staff-acct", Hint = "admin" DEFAULT Group = "staff" Scheme-Acct-Procedure = "staff-acct", Hint = "staff"

Contents of file `users':

DEFAULT Auth-Type = SQL, Simultaneous-Use = 1 Service-Type = Framed-User, Framed-Protocol = PPP DEFAULT Hint = "admin", Auth-Type = System Service-Type = Login-User, Login-IP-Host = 192.168.0.1, Login-Service = Rlogin DEFAULT Hint = "staff", Auth-Type = System, Simultaneous-Use = 1 Service-Type = Login-User, Login-IP-Host = 192.168.0.2, Login-Service = Telnet

Now, let's suppose that user `svp' is in the group `staff' and is trying to log in. However, he fails to do so and in radiusd logs you see:

Nov 06 21:25:24: Auth.notice: (Access-Request local 61 svp): Login incorrect [svp]

Why? To answer this question, you add to auth block of your `config' the statement

trace-rules yes;

and ask user `svp' to retry his attempt. Now you see in your logs:

Nov 06 21:31:24: Auth.notice: (Access-Request local 13 svp): Login incorrect [svp] Nov 06 21:31:24: Auth.info: (Access-Request local 13 svp): rule trace: /etc/raddb/users:1, hints: 5

This means that the request for `svp' has first matched rule on the line 1 of file `hints', then the rule on line 1 of file `users'. Now you see the error: the entries in `users' appear in wrong order! After fixing it your `users' looks like:

DEFAULT Hint = "admin", Auth-Type = System Service-Type = Login-User, Login-IP-Host = 192.168.0.1, Login-Service = Rlogin DEFAULT Hint = "staff", Auth-Type = System, Simultaneous-Use = 1 Service-Type = Login-User, Login-IP-Host = 192.168.0.2, Login-Service = Telnet DEFAULT Auth-Type = SQL, Simultaneous-Use = 1 Service-Type = Framed-User, Framed-Protocol = PPP

Now, you ask `svp' to log in again, and see:

Nov 06 21:35:14: Auth.notice: (Access-Request local 42 svp): Login OK [svp] Nov 06 21:35:14: Auth.info: (Access-Request local 42 svp): rule trace: /etc/raddb/users:7, hints: 5

Let's also suppose that user `plog' is not listed in groups "root" and "staff", so he is supposed to authenticate using SQL. When he logs in, you see in your logs:

Nov 06 21:39:05: Auth.notice: (Access-Request local 122 plog): Login OK [svp] Nov 06 21:39:05: Auth.info: (Access-Request local 122 plog): rule trace: /etc/raddb/users:14

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.2 Debugging

GNU Radius provides extensive debugging features. These are enabled either by the `--debug' (`-x') command line option to radiusd (see section 4. How to Start the Daemon.), or by the level statement in the debug category (see section logging statement). Both cases require as an argument a valid debug specification.

A debug specification sets the module for which the debugging should be enabled and the debugging level. The higher the level is, the more detailed information is provided. The module name and level are separated by an equal sign. If the level is omitted, the highest possible level (100) is assumed. The module name may be abbreviated to the first N characters, in which case the first matching module is selected. Several such specifications can be specified, in which case they should be separated by commas. For example, the following is a valid debug specification:

proxy.c=10,files.c,config.y=1

It sets debug level 10 for module proxy.c, 100 for files.c, and 1 for config.y.

The modules and debugging levels are subject to change from release to release.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.3 Test Mode

Test mode is used to test various aspects of radius configuration, without starting the daemon. To enter test mode, run

radiusd -mt

You will see usual radiusd diagnostics and the following two lines:

** TEST SHELL ** (radiusd) _

The string `** TEST SHELL **' indicates that radiusd has entered test mode, the string `(radiusd)' is the shell prompt, indicating that radiusd is waiting for your commands.

The syntax of test shell command resembles that of Bourne shell: each command consists of a list of words separated by any amount of whitespace. Each word is either a sequence of allowed word characters (i.e. alphabetical characters, decimal digits, dashes and underscores), or any sequence of characters enclosed in a pair of double quotes. The very first word is a command verb, the rest of words are arguments to this command verb. A command verb may be used in its full form, in its abbreviated form (i.e. you may type only several first characters of the verb, the only condition being that they do not coincide with another command verb), or in it's short form.

The first command you should know is help (or, in its short form, h). This command takes no arguments and displays the short summary of all the available commands. Here is an example of its output:

(radiusd) help h help Print this help screen q query-nas NAS LOGIN SID PORT [IP] Query the given NAS g guile Enter Guile rs rewrite-stack [NUMBER] Print or set the Rewrite stack size r run-rewrite FUNCTION(args..) Run given Rewrite function s source FILE Source the given Rewrite file t timespan TIMESPAN [DOW [HH [MM]]] Check the timespan interval d debug LEVEL Set debugging level rd request-define [PAIR [,PAIR]] Define a request rp request-print Print the request quit quit Quit the shell

Each line of the output consists of three fields. The first field shows the short command form. The second one lists its full form and its arguments, optional arguments being enclosed in square brackets. The third field contains short textual description of the command.

Test Shell Command: query-nas nas login sid port [ip]

Test Shell Abbreviation: q

Queries the given NAS about the session described by its arguments. This command is useful in testing simultaneous login verification (see section 7.9 Multiple Login Checking. Its arguments are

nas: Specifies the NAS to query. It cn be its short name as defined in `raddb/naslist', or its fully qualified domain name, or its IP address.
login: Name of the user whose session should be verified.
sid: Session ID.
port: Port number on the NAS.
ip: Framed IP address, assigned to the user.

The command displays the following result codes:

0: The session is not active.
1: The session is active
-1: Some error occurred.

Test Shell Command: guile
Test Shell Abbreviation: g: Enter Guile shell. The command is only available if the package has been compiled with Guile support. For more information, See section 11.3 Guile.

Test Shell Command: rewrite-stack [number]
Test Shell Abbreviation: rs: Prints or sets the Rewrite stack size.

Test Shell Command: run-rewrite function(args ...)

Test Shell Abbreviation: r

Runs given Rewrite function and displays its return value. Function arguments are specified in the usual way, i.e. as a comma-separated list of Rewrite tokens.

If the function being tested operates on request contents (see section 11.2.4 Rewriting Incoming Requests), you may supply the request using request-define command (see below).

Test Shell Command: source file
Test Shell Abbreviation: s: Reads and compiles ("source") the given Rewrite file. The command prints `0' if the file was compiled successfully. Otherwise, it prints `1' and any relevant diagnostics.

Test Shell Command: timespan timespan [day-of-week [hour [minutes]]]

Test Shell Abbreviation: t

Checks whether the given time falls within the timespan interval. Its first argument, timespan, contains the valid radiusd timespan specification (see section 14.3.14 Login-Time). Rest of arguments define the time. If any of these is omitted, the corresponding value from current local time is used.

day-of-week: Ordinal day of week number, counted from 0. I.e.: Sunday -- 0, Monday -- 1, etc.
hour: Hours counted from 0 to 24.
minutes: Minutes.

The following set of samples illustrates this command:

(radiusd) timespan Wk0900-1800 ctime: Tue Dec 2 16:08:47 2003 inside Wk0900-1800: 6720 seconds left (radiusd) timespan Wk0900-1800 0 ctime: Sun Nov 30 16:09:03 2003 OUTSIDE Wk0900-1800: 60660 seconds to wait (radiusd) timespan Wk0900-1800 0 12 30 ctime: Sun Nov 30 12:30:13 2003 OUTSIDE Wk0900-1800: 73800 seconds to wait (radiusd) timespan Wk0900-1800 1 05 00 ctime: Mon Dec 1 05:00:33 2003 OUTSIDE Wk0900-1800: 14400 seconds to wait (radiusd) timespan Wk0900-1800 1 09 10 ctime: Wed Jan 7 22:09:41 2004 OUTSIDE Wk0900-1800: 39060 seconds to wait (radiusd) timespan Wk0900-1800 1 09 10 ctime: Mon Dec 1 09:10:44 2003 inside Wk0900-1800: 31800 seconds left (radiusd)

Test Shell Command: debug level
Test Shell Abbreviation: d: Set debugging level. Level is any valid debug level specification (see section 10.2 Debugging).

Test Shell Command: request-define [pair [,pair]]

Test Shell Abbreviation: rd

Define a request for testing Rewrite functions. The optional arguments are a comma-separated list of A/V pairs. If they are omitted, the command enters interactive mode, allowing you to enter the desired A/V pairs, as in the following example:

(radiusd) request-define Enter the pair list. End with end of file [radiusd] User-Name = smith, User-Password = guessme [radiusd] NAS-IP-Address = 10.10.10.1 [radiusd] NAS-Port-Id = 34 [radiusd] (radiusd)

Notice that any number of A/V pairs may be specified in a line. To finish entering the request, either type an EOF character or enter an empty line.

Test Shell Command: request-print

Test Shell Abbreviation: rp

Prints the request, defined by request-define.

(radiusd) request-print User-Name = (STRING) smith User-Password = (STRING) guessme NAS-IP-Address = (IPADDR) 10.10.10.1 NAS-Port-Id = (INTEGER) 34 (radiusd)

Test Shell Command: quit: Immediately quits the shell.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11. Extensions

The use of extension language allows extending the functionality of GNU Radius without having to modify its source code. The two extension languages supported are Rewrite and Scheme. Use of Rewrite is always enabled. Use of Scheme requires Guile version 1.4 or higher.

11.1 Filters    Using external filter programs.

11.2 Rewrite    The built-in extension language.

11.3 Guile    Using Scheme.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.1 Filters

The simplest way to extend the functionality of Radius is to use filters. A filter is an external program that communicates with Radius via its standard input and output channels.

11.1.1 Getting Acquainted with Filters

11.1.2 Declaring the Filter

11.1.3 Invoking the Filter from a User Profile

11.1.4 Adding Reply Attributes

11.1.5 Accounting Filters

11.1.6 Invoking the Accounting Filter

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.1.1 Getting Acquainted with Filters

Suppose we wish to implement an authentication method based on the user name and the user's calling station ID. We have a database of user names with valid IDs, and the new method should authenticate a user only if the combination {user_name, id} is found in this database.

We write a filter program that reads its standard input line by line. Each input line must consist of exactly two words: the user name and the calling station ID. For each input line, the program prints 0 if the {user_name, id} is found in the database and 1 otherwise. Let's suppose for the sake of example that the database is a plaintext file and the filter is written in a shell programming language. Then it will look like

#! /bin/sh DB=/var/db/userlist while read NAME CLID do if grep "$1:$2" $DB; then echo "0" else echo "1" fi done

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.1.2 Declaring the Filter

Here is how this filter is declared in the `raddb/config' file:

filters { filter check_clid { exec-path "/usr/libexec/myfilter"; error-log "myfilter.log"; auth { input-format "%C{User-Name} %C{Calling-Station-Id}"; wait-reply yes; }; }; };

Let's analyze this declaration line by line:

filters {
This keyword opens the filters declaration block. The block may contain several declarations.
filter check_clid {
This line starts the declaration of this particular filter and names it `check_clid'.
exec-path "/usr/libexec/myfilter";
This line tells radiusd where to find the executable image of this filter.
error-log "myfilter.log";
The diagnostic output from this filter must be redirected to the file `myfilter.log' in the current logging directory
auth {
This filter will process authentication requests.
input-format "%C{User-Name} %C{Calling-Station-Id}";
Define the input line format for this filter. The %C{} expressions will be replaced by the values of the corresponding attributes from the incoming request (see section 5.14 Macro Substitution).
wait-reply yes;
radiusd will wait for the reply from this filter to decide whether to authenticate the user.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.1.3 Invoking the Filter from a User Profile

To invoke this filter from the user profile, specify its name prefixed with `|' in the value of Exec-Program-Wait attribute, like this:

DEFAULT Auth-Type = System, Simultaneous-Use = 1 Exec-Program-Wait = "|check_clid"

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.1.4 Adding Reply Attributes

Apart from simply deciding whether to authenticate a user, the filter can also modify the reply pairs.

#! /bin/sh DB=/var/db/userlist while read NAME CLID do if grep "$1:$2" $DB; then echo "0 Service-Type = Login, Session-Timeout = 1200" else echo "1 Reply-Message = \"You are not authorized to log in\"" fi done

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.1.5 Accounting Filters

Let's suppose we further modify our filter to also handle accounting requests. To discern between the authentication and accounting requests we'll prefix each authentication request with the word `auth' and each accounting request with the word `acct'. Furthermore, the input line for accounting requests will contain a timestamp.

Now, our filter program will look as follows:

#! /bin/sh AUTH_DB=/var/db/userlist ACCT_DB=/var/db/acct.db while read CODE NAME CLID DATE do case CODE auth) if grep "$1:$2" $DB; then echo "0 Service-Type = Login, \ Session-Timeout = 1200" else echo "1 Reply-Message = \ \"You are not authorized to log in\"" fi acct) echo "$CODE $NAME $CLID $DATE" >> $ACCT_DB done

Its declaration in the `raddb/config' will also change:

filter check_clid { exec-path "/usr/libexec/myfilter"; error-log "myfilter.log"; auth { input-format "auth %C{User-Name} %C{Calling-Station-Id}"; wait-reply yes; }; acct { input-format "acct %C{User-Name} %C{Calling-Station-Id} %D"; wait-reply no; }; };

(The input-format lines are split for readability. Each of them is actually one line).

Notice wait-reply no in the acct statement. It tells radiusd that it shouldn't wait for the response on accounting requests from the filter.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.1.6 Invoking the Accounting Filter

To invoke the accounting filter, specify its name prefixed with a vertical bar character as a value of Acct-Ext-Program in our `raddb/hints' file. For example:

DEFAULT NULL Acct-Ext-Program = "|check_clid:

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2 Rewrite

Rewrite is the GNU Radius extension language. Its name reflects the fact that it was originally designed to rewrite the broken request packets so they could be processed as usual (see section 11.2.4 Rewriting Incoming Requests). Beside this basic use, however, Rewrite functions are used to control various aspects of GNU Radius functionality, such as verifying the activity of user sessions, controlling the amount of information displayed in log messages, etc (see section 11.2.3 Interaction with Radius).

11.2.1 Syntax Overview

11.2.2 Quick Start

11.2.3 Interaction with Radius

11.2.4 Rewriting Incoming Requests

11.2.5 Login Verification Functions

11.2.6 Attribute Creation Functions

11.2.7 Logging Hook Functions

11.2.8 Full Syntax Description

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.1 Syntax Overview

The syntax of Rewrite resembles that of C. Rewrite has two basic data types: integer and string. It does not have global variables; all variables are automatic. The only exceptions are the A/V pairs from the incoming request, which are accessible to Rewrite functions via the special notation %[attr].

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.2 Quick Start

As an example, let's consider the following Rewrite function:

string foo(integer i) { string rc; if (i % 2) rc = "odd"; else rc = "even"; return "the number is " + rc; }

The function takes an integer argument and returns the string `the number is odd' or `the number is even', depending on the value of i. This illustrates the fact that in Rewrite the addition operator is defined on the string type. The result of such operation is the concatenation of operands.

Another example is a function that adds a prefix to the User-Name attribute:

integer px_add() { %[User-Name] = "pfx-" + %[User-Name]; return 0; }

This function manipulates the contents of the incoming request; its return value has no special meaning.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.3 Interaction with Radius

A Rewrite function can be invoked in several ways, depending on its purpose. There are three major kinds of Rewrite functions:

Functions used to rewrite the incoming requests.
Functions designed for simultaneous login verification.
Functions used to generate Radius attribute values.
Logging hooks.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.4 Rewriting Incoming Requests

The need for rewriting the incoming requests arises from the fact that some NASes are very particular about the information they send with the requests. There are cases when the information they send is hardly usable or even completely unusable. For example, a Cisco AS5300 terminal server used as a voice-over IP router packs a lot of information into its Acct-Session-Id attribute. Though the information stored there is otherwise relevant, it makes proper accounting impossible, since the Acct-Session-Id attributes in the start and stop packets of the same session become different, and thus Radius cannot determine the session start to which the given session stop request corresponds (see section 14.2.7 Acct-Session-Id).

In order to cope with such NASes, GNU Radius is able to invoke a Rewrite function upon arrival of the packet and before processing it further. This function can transform the packet so that it obtains the form prescribed by RFCs and its further processing becomes possible.

For example, in the case of the AS5300 router, a corresponding Rewrite function parses the Acct-Session-Id attribute; breaks it down into fields; stores them into proper attributes, creating them if necessary; and finally replaces Acct-Session-Id with its real value, which is the same for the start and stop records corresponding to a single session. Thus all the information that came with the packet is preserved, but the packet itself is made usable for proper accounting.

A special attribute, Rewrite-Function, is used to trigger invocation of a Rewrite function. Its value is a name of the function to be invoked.

When used in a `naslist' profile, the attribute causes the function to be invoked when the incoming request matches the huntgroup (see section 3.4.4 Huntgroups). For example, to have a function fixup invoked for each packet from the NAS 10.10.10.11, the following huntgroup rule may be used:

DEFAULT NAS-IP-Address = 11.10.10.11 Rewrite-Function = "fixup"

The Rewrite-Function attribute may also be used in a `hints' rule. In this case, it will invoke the function if the request matches the rule (see section 3.4.3 Hints). For example, this `hints' rule will cause the function to be invoked for each request containing the user name starting with `P':

DEFAULT Prefix = "P" Rewrite-Function = "fixup"

Note that in both cases the attribute can be used either in LHS or in RHS pairs of a rule.

The packet rewrite function must be declared as having no arguments and returning an integer value:

integer fixup() { }

The actual return value from such a function is ignored, the integer return type is just a matter of convention.

The following subsection present some examples of packet rewrite functions.

11.2.4.1 Examples of Various Rewrite Functions

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.4.1 Examples of Various Rewrite Functions

The examples found in this chapter are working functions that can be used with various existing NAS types. They are taken from the `rewrite' file contained in distribution of GNU Radius.

1. Port rewriting for MAX Ascend terminal servers

Some MAX Ascend terminal servers pack additional information into the NAS-Port-Id attribute. The port number is constructed as XYYZZ, where X = 1 for digital, X = 2 for analog, YY is the line number (1 for first PRI/T1/E1, 2 for second, and so on), and ZZ is the channel number (on the PRI or channelized T1/E1).

The following rewrite functions are intended to compute the integer port number in the range (1 .. portcnt), where portcnt represents the real number of physical ports available on the NAS. Such a port number can be used, for example, to create a dynamic pool of IP addresses (see section 14.1.8 Framed-IP-Address).

/* * decode MAX port number * input: P -- The value of NAS-Port-Id attribute * portcnt -- number of physical ports on the NAS */ integer max_decode_port(integer P, integer portcnt) { if (P > 9999) { integer s, l, c; s = P / 10000; l = (P - (10000 * s))/100; c = P - ((10000 * s) + (100 * l)); return (c-1) + (l-1) * portcnt; } return P; } /* * Interface function for MAX terminal server with 23 ports. * Note that it saves the received NAS-Port-Id attribute in * the Orig-NAS-Port-Id attribute. The latter must be * defined somewhere in the dictionary */ integer max_fixup() { %[Orig-NAS-Port-Id] = %[NAS-Port-Id]; # Preserve original data %[NAS-Port-Id] = max_decode_port(%[NAS-Port-Id], 23); return 0; }

2. Session ID parsing for Cisco AS 5300 series

Cisco VOIP IOS encodes a lot of other information into its Acct-Session-Id. The pieces of information are separated by `/' characters. The part of Acct-Session-Id up to the first `/' character is the actual session ID.

On the other hand, its accounting packets lack NAS-Port-Id, though they may contain the vendor-specific pair with code 2 (vendor PEC 9), which is a string in the form `ISDN 9:D:999' (`9' represents any decimal digit). The number after the last `:' character can be used as a port number.

The following code parses Acct-Session-Id attribute and stores the information it contains in various other attributes, generates a normal Acct-Session-Id, and attempts to generate a NAS-Port-Id attribute.

/* * The port rewriting function for Cisco AS5300 used for * VoIP. This function is used to generate NAS-Port-Id pair * on the basis of vendor-specific pair 2. If the latter is * in the form "ISDN 9:D:999" (where each 9 represents a * decimal digit), then the function returns the number * after the last colon. This is used as a port number. */ integer cisco_pid(string A) { if (A =~ ".*$[0-9][0-9]*$: [A-Z0-9][A-Z0-9]*:$[0-9][0-9]*$") { return (integer)\2; } return -1; } /* * This function parses the packed session id. * The actual sid is the number before the first slash * character. Other possibly relevant fields are also * parsed out and saved in the Voip-* A/V pairs. The latter * should be defined somewhere in the dictionary. * Note that the regular expression in this example * spans several lines for readability. It should be on one * line in real file. */ string cisco_sid(string S) { if (S =~ "$.[^/]*$/[^/]*/[^/]*/$[^/]*$/$[^/]*$/ $[^/]*$/$[^/]*$/$[^/]*$/$[^/]*$ /$[^/]*$.*") { %[Voip-Connection-ID] = \2; %[Voip-Call-Leg-Type] = \3; %[Voip-Connection-Type] = \4; %[Voip-Connect-Time] = \5; %[Voip-Disconnect-Time] = \6; %[Voip-Disconnect-Cause] = \7; %[Voip-Remote-IP] = \8; return \1; } return S; } /* * Normalize cisco AS5300 packets */ integer cisco_fixup() { integer pid; if ((pid = cisco_pid(%[Cisco-PRI-Circuit])) != -1) { if (*%[NAS-Port-Id]) %[Orig-NAS-Port-Id] = %[NAS-Port-Id]; %[NAS-Port-Id] = pid; } if (*%[Acct-Session-Id]) { %[Orig-Acct-Session-Id] = %[Acct-Session-Id]; %[Acct-Session-Id] = cisco_sid(%[Acct-Session-Id]); } return 0; }

3. User-name rewriting for NT machines

Users coming from Windows NT machines often authenticate themselves as `NT_DOMAIN\username'. The following function selects the user-name part and stores it in the User-Name attribute:

integer login_nt(string uname) { integer i; if ((i = index(uname, '\\')) != -1) return substr(uname, i+1, -1); return uname; } integer nt_rewrite() { %[Orig-User-Name] = %[User-Name]; %[User-Name] = login_nt(%[User-Name]); return 0; }

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.5 Login Verification Functions

A login verification function is invoked to process the output from the NAS. This process is described in 7.9 Multiple Login Checking. The function to be invoked for given NAS is defined by a function flag in the `raddb/nastypes' or `raddb/naslist' file (see section 5.5 NAS Types -- `raddb/nastypes'). It must be defined as follows:

Function Template: integer check (string str, string name, integer pid, string sid)

Its arguments are:

str: Input string. If the query method is finger, this is the string of output received from the NAS with trailing newline stripped off. If the query method is snmp, it is the received variable value converted to its string representation.
name: User name.
pid: Port ID of the session.
sid: Session ID.

The function should return non-0 if its arguments match the user's session, and 0 otherwise.

11.2.5.1 Examples of Login Verification Functions

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.5.1 Examples of Login Verification Functions

As an example, let's consider the function for analyzing a line of output from a standard UNIX finger service. In each line of finger output the first field contains the user name; the third field, the The function must return 1 if the three fields match the input user name and port and session IDs:

integer check_unix(string str, string name, integer pid, string sid) { return field(str, 1) == name && field(str, 3) == pid && field(str, 7) == sid; }

The next example is a function to analyze a line of output from an SNMP query returning a user name. This function must return 1 if the entire input line matches the user name:

integer check_username(string str, string name, integer pid, string sid) { return str == name; }

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.6 Attribute Creation Functions

These are the functions used to create Radius reply attributes. An attribute creation function can take any number of arguments. The type of its return is determined by the type of Radius attribute the value will be assigned to. To invoke the function, write its name in the A/V pair of the RHS in the `raddb/users' file, e.g.:

DEFAULT Auth-Type = SQL Service-Type = Framed-User, Framed-IP-Address = "=get_ip_addr(10.10.10.1)"

The function get_ip_addr will be invoked after successful authentication and it will be passed the IP 10.10.10.1 as its argument. An example of a useful function that can be invoked this way is

integer get_ip_address(integer base) { return base + %[NAS-Port-Id] - %[NAS-Port-Id]/16; }

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.7 Logging Hook Functions

A logging hook functions should be declared as follows:

Function Template: string hook (integer reqtype, string nasid, integer reqid)

reqtype: Type of the request. It can be converted to string using request_code_string function (see section 11.2.8.7 Rewrite Built-in Functions).
nasid: NAS identifier from `raddb/naslist', or its host name if not declared there
reqid: Request identifier.

Notice that the hook function shall not produce any side effects, in particular it shall not modify the incoming request in any way.

Following is an example prefix hook function that formats the incoming request data:

string compat_log_prefix(integer reqtype, string nas, integer id) { string result; return "(" + request_code_string(reqtype) + " " + nas + " " + (string)id + " " + %[User-Name] + ")"; }

Here is a sample log produced by radiusd before and after enabling this function:

Auth.notice: Login OK [jsmith] ... Auth.notice: (AUTHREQ nas-2 251 jsmith): Login OK [jsmith]

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.8 Full Syntax Description

11.2.8.1 Rewrite Data Types

11.2.8.2 Rewrite Symbols

11.2.8.3 Rewrite Identifiers

11.2.8.4 Rewrite Declarations

11.2.8.5 Rewrite Statements

11.2.8.6 Regular Expressions

11.2.8.7 Rewrite Built-in Functions

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.8.1 Rewrite Data Types

There are only two data types: integer and string, the two being coercible to each other in the sense that a string can be coerced to an integer if it contains a valid ASCII representation of a decimal, octal, or hex number, and an integer can always be coerced to a string, the result of such coercion being the ASCII string that is the decimal representation of the number.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.8.2 Rewrite Symbols

A symbol is a lexical token. The following symbols are recognized:

Arithmetical operators

These are `+', `-', `*', `/' representing the basic arithmetical operations, and `%' meaning remainder.

Comparison operators

These are: `==', `!=', `<', `<=', `>', `>=' with the same meaning they have in C. Special operators are provided for regular-expression matching. The binary operator `=~' returns true if its left-hand-side operand matches the regular expression on its right-hand side (see section 11.2.8.6 Regular Expressions). `!~' returns true if its left-hand-side operand does not match the regexp on its right-hand side. The right-hand-side operand of `!~' or `=~' must be a literal string, i.e., the regular expression must be known at compile time.

Unary operators

The unary operators are `-' and `+' for unary plus and minus, `!' for boolean negation, and `*' for testing for the existence of an attribute.

Boolean operators

These are `&&' and `||'.

Parentheses `(' and `)'

These are used to change the precedence of operators, to introduce type casts (type coercions), to declare functions, and to pass actual arguments to functions.

Curly braces (`{' and `}')

These are used to delimit blocks of code.

Numbers

Numbers follow the usual C convention for integers. A number consisting of a sequence of digits is taken to be octal if it begins with `0' (digit zero), and decimal otherwise. If the sequence of digits is preceded by `0x' or `0X', it is taken to be a hexadecimal integer.

IP Numbers

IP numbers are represented by a standard numbers-and-dots notation. IP numbers do not constitute a separate data type, rather they are in all respects similar to initeger numbers.

Characters

These follow the usual C convention for characters, i.e., they consist either of an ASCII character itself or of its value, enclosed in a pair of singlequotes. The character value begins with `\' (backslash) and consists either of three octal or of two hexadecimal digits. A character does not form a special data type; it is represented internally by an integer.

Quoted strings

These follow slightly modified C conventions for strings. A string is a sequence of characters surrounded by double quotes, as in `"..."'. In a string, the double quote character `"' must be preceeded by a backslash `\'. A `\' and an immediately following newline are ignored. Following escape sequences have special meaning:

\a: Audible bell character (ASCII 7)
\b: Backspace (ASCII 8)
\e: Escape character (ASCII 27)
\f: Form feed (ASCII 12)
\n: Newline (ASCII 10)
\r: Carriage return (ASCII 13)
\t: Horizontal tab (ASCII 9)
\\: Backslash
\ooo: (`o' represents an octal digit) A character whose ASCII value is represented by the octal number `ooo'.
\xHH
\XHH: (`H' represents a hex digit) A character whose ASCII value is represented by the hex number `HH'.
\(: Two characters `\('.
\): Two characters `\)'.

If the character following the backslash is not one of those specified, the backslash is ignored.

Attribute values

The incoming request is passed implicitly to functions invoked via the Rewrite-Function attribute. It is kept as an associative array, whose entries can be accessed using the following syntax:

`%[' attribute-name `]' `%[' attribute-name `]' `(' n `)'

The first form returns the value of the attribute attribute-name. Here attribute-name should be a valid Radius dictionary name (see section 5.2 Dictionary of Attributes -- `raddb/dictionary').

The second form returns the value of the nth attribute of type attribute-name. The index n is counted from zero, so

%[attribute-name](0)

is equivalent to

%[attribute-name]

Identifiers

Identifiers represent functions and variables. These are described in the next sub-subsection.

Regexp group references

A sequence of characters in the form

`\number'

refers to the contents of parenthesized group number number obtained as a result of the last executed `=~' command. The regexp group reference has always string data type. For example:

string basename(string arg) { if (arg =~ ".*/$.*$\..*") return \1; else return arg; }

This function strips from arg all leading components up to the last slash character, and all trailing components after the last dot character. It returns arg unaltered if it does not contain slashes and dots. It is roughly analogous to the system basename utility.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.8.3 Rewrite Identifiers

A valid identifier is a string of characters meeting the following requirements:

It starts with either a lower- or an uppercase letter of the Latin alphabet or either of the following symbols: `_', `$'.
It consists of alphanumeric characters, underscores(`_'), and dollar signs (`$').

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.8.4 Rewrite Declarations

Function declarations

A Rewrite function is declared as follows:

type function-name (parameter-list)

where type specifies the return type of the function, function-name declares the symbolic name of the function, and parameter-list declares the formal parameters to the function. It is a comma-separated list of declarations in the form

type parm-name

type being the parameter type, and parm-name being its symbolic name. Both function-name and parm-name should be valid identifiers.

Variable declarations

There are no global variables in Rewrite. All variables are local. The local variables are declared right after the opening curly brace (`{') and before any executable statements. The declaration syntax is

type ident_list ;

Here ident_list is either a valid Rewrite identifier or a comma-separated list of such identifiers.

Note that, unlike in C, no assignments are allowed in variable declarations.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.8.5 Rewrite Statements

The Rewrite statements are: expressions, assignments, conditional statements, and return statements. A statement is terminated by a semicolon.

Expressions

An expression is one of the following:

A variable identifier
A type coercion expression
An arithmetic expression
A boolean expression
An assignment
A function call
A delete statement

Type coercion

The type coercion is like a type cast in C. Its syntax is

`(' type `)' ident

The result of type coercion is as follows:

type Variable type Resulting conversion

integer integer No conversion. This results in the same integer value.

integer string If the string value of the variable is a valid ASCII representation of the integer number (either decimal, octal, or hex), it is converted to the integer; otherwise the result of the conversion is undefined.

string integer The ASCII representation (in decimal) of the integer number.

string string No conversion. This results in the same string value.

Assignment

An assignment is

ident = expression ;

The variable ident is assigned the value of expression.

Function calls

These take the form

ident ( arg-list )

where ident is the identifier representing the function, and arg-list is a comma-separated list of expressions supplying actual arguments to the function. The number of the expressions must correspond exactly to the number of formal parameters in the function definition. The function that ident references can be either a compiled function or a built-in function.

`delete' statement

The `delete' statement is used to delete an attribute or attributes from the incoming request. Its syntax is:

delete attribute-name; delete attribute-name(n);

The first variant deletes all the attributes of the given type. The second variant deletes only the nth occurrence of the matching attribute.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.8.6 Regular Expressions

Rewrite uses POSIX regular expressions (See section `Regular Expression Library' in Regular Expression Library, for the detailed description of these).

You control the exact type of regular expressions by the use of the pragmatic comment regex. Its syntax is as follows:

#pragma regex option-list

Option-list is a whitespace-separated list of options. Each option is one of the following words prefixed with `+' or `-':

extended

Use POSIX extended regular expression syntax when interpreting regular expressions.

icase

Do not differentiate case. Subsequent regular expression comparisons will be case insensitive.

newline

Match-any-character operators don't match a newline.

A non-matching list (`[^...]') not containing a newline does not match a newline.

Match-beginning-of-line operator (`^') matches the empty string immediately after a newline.

Match-end-of-line operator (`$') matches the empty string immediately before a newline.

Prefixing an option with `+' means to enable the corresponding behavior. Prefixing it with `-' means to disable it. Thus, the following statement:

#pragma regex +extended +icase

will enable extended POSIX regular expressions using case-insensitive comparison.

Using the following comment:

#pragma regex -extended

will switch to the basic POSIX regular expressions.

The settings of a regex pragmatic comment remain in force up to the end of current source file, or to the next regex comment, whichever occurs first.

For compatibility with previous versions, GNU Radius uses the following defaults:

#pragma regex -extended -icase -newline

i.e. all regular expressions are treated as basic POSIX, comparison is case-sensitive.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2.8.7 Rewrite Built-in Functions

The following built-in functions are provided:

Function: integer length (string s)

Returns the length of the string s.

length("string") => 6

Function: integer index (string s, integer c)

Returns the index of the first occurrence of the character c in the string s. Returns -1 if no such occurrence is found.

index("/raddb/users", 47) => 0 index("/raddb/users", 45) => -1

Function: integer rindex (string s, integer i)

Returns the index of the last occurrence of the character c in the string s. Returns -1 if no such occurrence is found.

rindex("/raddb/users", 47) => 6

Function: string substr (string s, integer start, integer length)

Returns the substring of s of length at most length starting at position start.

substr("foo-bar-baz", 3, 5) => "-bar-"

All character positions in strings are counted from 0.

Function: string field (string buffer, integer n)

This function regards the buffer argument as consisting of fields separated with any amount of whitespace. It extracts and returns the nth field. n is counted from 1.

field("GNU's not UNIX", 1) => "GNU's" field("GNU's not UNIX", 2) => "not" field("GNU's not UNIX", 3) => "UNIX" field("GNU's not UNIX", 4) => ""

Function: integer logit (string msg): Outputs its argument to the Radius log channel info. Returns 0. For debugging purposes.

Function: integer inet_aton (string str)

Converts the Internet host address str from the standard numbers-and-dots notation into the equivalent integer in host byte order.

inet_aton("127.0.0.1") => 2130706433

Function: string inet_ntoa (integer ip)

Converts the Internet host address ip given in host byte order to a string in standard numbers-and-dots notation.

inet_ntoa(2130706433) => "127.0.0.1"

Function: integer htonl (integer n): Converts the integer n, regarded as long, from host to network byte order.

Function: integer ntohl (integer n): Converts the integer n, regarded as long, from network to host byte order.

Function: integer htons (integer n): Converts the integer n, regarded as short, from host to network byte order.

Function: integer ntohs (integer n): Converts the integer n, regarded as short, from network to host byte order.

Function: string gsub (string regex, string repl, string str)

For each substring matching the regular expression regex in the string str, substitute the string repl, and return the resulting string.

gsub("s","S","strings") => "StringS" gsub("[0-9][0-9]*","N","28 or 29 days") => "N or N days" gsub("[()'\"]","/","\"a\" (quoted) 'string'") => "/a/ /quoted/ /string/"

Function: string qprn (string str)

Replace all non-printable characters in string S by their corresponding hex value preceeded by a percent sign. Return the resulting string. Printable are alphabetical characters, decimal digits and dash (`-'). Other characters are considered non-printable. For example:

qprn("a string/value") => "a%20string%2Fvalue"

Function: string quote_string (string str)

Replace all non-printable characters in string str by their three-digit octal code prefixed with a backslash, or by their C escape notation, as appropriate. Non-printable characters depend on the locale settings. For example, suppose that the current locale is set to ISO-8859-1 (a so called "Latin-1" character set) and -!- represents a tab character. Then:

quote_string("François contains non-!-printable chars") => "Fran\347ois contains non\tprintable chars"

Function: string unquote_string (string str)

Replace C escape notations in string str with corresponding characters using current locale. For example, for ISO-8859-1 locale:

unquote_string("Fran\347ois") => "François"

Function: string toupper (string str)

Returns the copy of the string str with all alphabetical characters converted to upper case. For example:

toupper("a-string") => "A-STRING"

Function: string tolower (string str)

Returns the copy of the string str with all alphabetical characters converted to lower case. For example:

tolower("A-STRING") => "a-string"

Function: string request_code_string (integer code)

Converts integer RADIUS request code to its textual representation as per RFC 3575. This function is useful in logging hooks (see section 5.1.2.1 Logging hooks).

request_code_string(4) => "Accounting-Request"

Native Language Support

The native language support is provided via the functions described below. These functions are interfaces to GNU gettext library. For the information about general concepts and principles of Native Language Support, please refer to section `gettext' in GNU gettext utilities.

The default current textual domain is `radius'.

Function: string textdomain (string domain): Sets the new value for the current textual domain. This domain is used by the functions gettext and ngettext. Returns the name of the previously used domain.

Function: string gettext (string msgid)

Function: string _ (string msgid)

The function returns the translation of the string msgid if it is available in the current domain. If it is not available, the argument itself is returned.

The second form of this function provides a traditional shortcut notation.

For a detailed description of the GNU gettext interface, refer to section `Interface to gettext' in GNU gettext utilities.

Function: string dgettext (string domain, string msgid): Returns the translation of the string msgid if it is available in the domain domain. If it is not available, the argument itself is returned.

Function: string ngettext (string msgid_singular, string msgid_plural, integer number)

The ngettext function is used to translate the messages that have singular and plural forms. The msgid_singular parameter must contain the singular form of the string to be converted. It is also used as the key for the search in the catalog. The msgid_plural parameter is the plural form. The parameter number is used to determine the plural form. If no message catalog is found msgid_singular is returned if number == 1, otherwise msgid_plural.

For a detailed description of the GNU gettext interface for the plural translation, refer to section `Additional functions for plural forms' in GNU gettext utilities.

Function: string dngettext (string domain, string msg_sing, string msg_plur, integer number): Similar to ngettext, but searches translation in the given domain.

Request Accessors

The following functions are used to read some internal fields of a RADIUS request.

Function: Integer request_source_ip ()

Returns source IP address of the currently processed request. This function can be used to add NAS-IP-Address attribute to the requests lacking one, e.g.:

integer restore_nas_ip() { if (!*%[NAS-IP-Address]) %[NAS-IP-Address] = request_source_ip(); return 0; }

Function: Integer request_source_port (): Returns the source UDP port.

Function: Integer request_id (): Returns the request identifier.

Function: Integer request_code (): Returns the request code.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.3 Guile

The name Guile stands for GNU's Ubiquitous Intelligent Language for Extensions. It provides a Scheme interpreter conforming to the R4RS language specification. This section describes use of Guile as an extension language for GNU Radius. It assumes that the reader is sufficiently familiar with the Scheme language. For information about the language, refer to section `Top' in Revised(4) Report on the Algorithmic Language Scheme. For more information about Guile, see section `Overview' in The Guile Reference Manual.

Scheme procedures can be called for processing both authentication and accounting requests. The invocation of a Scheme procedure for an authentication request is triggered by the Scheme-Procedure attribute; the invocation for an accounting request is triggered by the Scheme-Acct-Procedure attribute. The following sections address these issues in more detail.

11.3.1 Data Representation

11.3.2 Authentication with Scheme

11.3.3 Accounting with Scheme

11.3.4 Radius-Specific Functions

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.3.1 Data Representation

A/V pair lists are the main object Scheme functions operate upon. Scheme is extremely convenient for representation of such objects. A Radius A/V pair is represented by a Scheme pair; e.g.,

Session-Timeout = 10

is represented in Guile as

(cons "Session-Timeout" 10)

The car of the pair can contain either the attribute dictionary name or the attribute number. Thus, the above pair may also be written in Scheme as

(cons 27 10)

(because Session-Timeout corresponds to attribute number 27).

Lists of A/V pairs are represented by Scheme lists. For example, the Radius pair list

User-Name = "jsmith", User-Password = "guessme", NAS-IP-Address = 10.10.10.1, NAS-Port-Id = 10

is written in Scheme as

(list (cons "User-Name" "jsmith") (cons "User-Password" "guessme") (cons "NAS-IP-Address" "10.10.10.1") (cons "NAS-Port-Id" 10))

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.3.2 Authentication with Scheme

The Scheme procedure used for authentication must be declared as follows:

Function Template: auth-function request-list check-list reply-list

Its arguments are:

request-list: The list of A/V pairs from the incoming request
check-list: The list of A/V pairs from the LHS of the profile entry that matched the request
reply-list: The list of A/V pairs from the RHS of the profile entry that matched the request

The function return value determines whether the authentication will succeed. The function must return either a boolean value or a pair. The return of #t causes authentication to succeed. The return of #f causes it to fail.

For a function to add something to the reply A/V pairs, it should return a pair in the form

(cons return-code list)

where return-code is a boolean value of the same meaning as described above. list is a list of A/V pairs to be added to the reply list. For example, the following function will always deny the authentication, returning an appropriate message to the user:

(define (decline-auth request-list check-list reply-list) (cons #f (list (cons "Reply-Message" "\r\nSorry, you are not allowed to log in\r\n"))))

As a more constructive example, let's consider a function that allows the authentication only if a user name is found in its internal database:

(define staff-data (list (list "scheme" (cons (list (cons "NAS-IP-Address" "127.0.0.1")) (list (cons "Framed-MTU" "8096"))) (cons '() (list (cons "Framed-MTU" "256")))))) (define (auth req check reply) (let* ((username (assoc "User-Name" req)) (reqlist (assoc username req)) (reply-list '())) (if username (let ((user-data (assoc (cdr username) staff-data))) (rad-log L_INFO (format #f "~A" user-data)) (if user-data (call-with-current-continuation (lambda (xx) (for-each (lambda (pair) (cond ((avl-match? req (car pair)) (set! reply-list (avl-merge reply-list (cdr pair))) (xx #t)))) (cdr user-data)) #f))))) (cons #t reply-list)))

To trigger the invocation of the Scheme authentication function, assign its name to the Scheme-Procedure attribute in the RHS of a corresponding `raddb/users' profile. For example:

DEFAULT Auth-Type = SQL Scheme-Procedure = "auth"

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.3.3 Accounting with Scheme

The Scheme accounting procedure must be declared as follows:

Function Template: acct-function-name request-list

Its argument is:

request-list: The list of A/V pairs from the incoming request

The function must return a boolean value. The accounting succeeds only if it has returned #t.

Here is an example of a Scheme accounting function. The function dumps the contents of the incoming request to a file:

(define radius-acct-file "/var/log/acct/radius") (define (acct req) (call-with-output-file radius-acct-file (lambda (port) (for-each (lambda (pair) (display (car pair) port) (display "=" port) (display (cdr pair) port) (newline port)) req) (newline port))) #t)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.3.4 Radius-Specific Functions

Scheme Function: avl-delete av-list attr: Delete from av-list the pairs with attribute attr.

Scheme Function: avl-merge dst src: Merge src into dst.

Scheme Function: avl-match? target list: Return #t if all pairs from list are present in target.

Scheme Function: rad-dict-name->attr name

Return a dictionary entry for the given attribute name or #f if no such name was found in the dictionary.

A dictionary entry is a list in the form

Scheme List: dict-entry name-string attr-number type-number vendor

where the arguments are as follows:

name-string: The attribute name
value-number: The attribute number
type-number: The attribute type
vendor: The vendor PEC, if the attribute is a vendor-specific one, or #f otherwise.

Scheme Function: rad-dict-value->name attr value: Returns the dictionary name of the given value for an integer-type attribute attr, which can be either an attribute number or its dictionary name.

Scheme Function: rad-dict-name->value attr value: Convert a symbolic attribute value name into its integer representation.

Scheme Function: rad-dict-pec->vendor pec: Convert a PEC to the vendor name.

Scheme Function: rad-log-open prio: Open Radius logging to the severity level prio.

Scheme Function: rad-log-close: Close a Radius logging channel opened by a previous call to rad-log-open.

Scheme Function: rad-rewrite-execute-string string

Interpret string as an invocation of a function in Rewrite language and execute it.

Return value: return of the corresponding Rewrite call, translated to the Scheme data type.

Scheme Function: rad-rewrite-execute arglist

Execute a Rewrite language function. (car arglist) is interpreted as a name of the Rewrite function to execute, and (cdr arglist) as a list of arguments to be passed to it.

Return value: return of the corresponding Rewrite call, translated to the Scheme data type.

Scheme Function: rad-openlog ident option facility: Scheme interface to the system openlog() call.

Scheme Function: rad-syslog prio text: Scheme interface to the system syslog() call.

Scheme Function: rad-closelog: Scheme interface to the system closelog() call.

Scheme Function: rad-utmp-putent status delay list radutmp_file radwtmp_file

Write the supplied data into the radutmp file. If radwtmp_file is not nil, the constructed entry is also appended to wtmp_file.

list is:

Scheme List: utmp-entry user-name orig-name port-id port-type session-id caller-id framed-ip nas-ip proto

user-name: The user name
orig-name: The original user name from the request
port-id: The value of the NAS-Port-Id attribute
port-type: A number or character indicating the port type
session-id: The session ID
caller-id: The value of the Calling-Station-Id attribute from the request
framed-ip: The framed IP assigned to the user
nas-ip: The NAS IP
proto: A number or character indicating the type of the connection

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12. Utility Programs

Controlling who and when was logged in

12.1 radwho    Show who is logged in by radius now.

12.2 radlast    Show the history of logins by radius.

Maintenance commands

12.3 radzap    Modify the login records.

12.4 radgrep    Quickly find the login record.

12.5 radping    Ping the remote machine by the username.

12.6 radauth    Check if a user can be authenticated.

12.7 radctl    Radctl monitor.

12.8 builddbm    Create DBM version of the `raddb/users' file.

Guile interface

12.9 radscm: A Guile Interface to Radius Functions    A Guile interface to radius functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.1 `radwho`

Radwho displays the list of users currently logged in by the Radius server.

Default output information is made compatible with that of the standard UNIX finger(1) utility. For each user the following information is displayed: login name, name, connection protocol, NAS port, login date, NAS name, assigned IP or corresponding network name.

When used with `-l' option, the long output format is used. In this format the following information is output:

`Login': Login name of the user
`SessionID': Unique session ID assigned by the terminal server.
`Proto': Connection prototype.
`Port': Port number
`When': Login date and time
`From': Name of the NAS that accepted the connection.
`Location': Framed IP or the corresponding network name.
`Caller': Caller station ID ad reported by the NAS.
`Duration': Duration of the session.

12.1.1 radwho Command Line Options    Command line options.

12.1.2 radwho Format Strings

12.1.3 radwho Predefined Formats

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.1.1 `radwho` Command Line Options

The following command line options can be used to modify the behavior of the program:

`-A'

`--all'

Display the information about logged-out users as well. The logged-out users are shown with `Proto' field set to HUP.

`-c'

`--calling-id'

Display the calling station ID in the second column. Equivalent to `--format clid'.

`-d NAME'

`--directory NAME'

Set the Radius configuration directory name.

`-D fmt'

`--date-format fmt'

Set the date representation. Th fmt is usual strftime(3) format string. It defaults to %a %H:%M, i.e. the abbreviated weekday name according to the current locale, and the hour and the minutes as two-digit decimal numbers.

`-e STRING'

`--empty STRING'

Display any empty field as STRING. This is useful when the output of radwho is fed to some analyzing program, as it helps to keep the same number of columns on each line of output.

`-F'

`--finger'

Start in fingerd mode. In this mode radwho emulates the behavior of the fingerd(8) utility. Use this option if starting radwho from the `/etc/inetd.conf' line like this (5):

finger stream tcp nowait nobody /usr/sbin/radwho radwho -fL

This mode is also enabled by default if radwho notices that its name (argv[0]) is `fingerd' or `in.fingerd'.

`-H'

`--no-header'

Don't display header line.

`-i'

`--session-id'

Display session ID instead of GECOS in the second column. Equivalent to `--format sid'.

`-I'

`--ip-strip-domain'

Display hostnames without domain part.

`-u'

`--local-also'

Display information about local users from the system `utmp' file. May prove useful when running radwho as a finger daemon.

`-n'

`--no-resolve'

Do not resolve IP.

`-o format'

`--format format'

Select customized output format. This can also be changed by setting the value of environment variable RADWHO_FORMAT. The format is either a symbolic name of one of the predefined formats or a format specification (see next subsection).

`-s'

`--secure'

Run in secure mode. Queries without a user name are rejected.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.1.2 `radwho` Format Strings

A format string controls the output of every record from `radutmp'. It contains two types of objects: ordinary characters, which are simply copied to the output, and format specifications, each of which causes output of a particular piece of information from the `radutmp' record.

Each format specification starts with an opening brace and ends with a closing brace. The first word after the brace is the name of the format specification. The rest of words are positional arguments followed by keyword arguments. Both are optional. The keyword arguments begin with a colon and must follow the positional arguments.

The full list of format specifications follows.

Format Spec: newline [count]: Causes the newline character to be output. If the optional count is supplied, that many newlines will be printed

Format Spec: tab [num]: Advance to the next tabstop in the output stream. If optional num is present, then skip num tabstops. Each tabstop is eight characters long.

The following specifications output particular fields of a `radutmp' record. They all take two positional arguments: width and title.

The first argument, width sets the maximum output length for this specification. If the number of characters actually output is less than the width, they will be padded with whitespace either to the left or to the right, depending on the presence of the :right keyword argument. If the number of characters is greater than width, they will be truncated to fit. If width is not given, the exact data are output as is.

The second argument, title, gives the title of this column for the heading line. By default no title is output.

Every field specification accepts at least two keyword arguments. The keyword :right may be used to request alignment to the right for the data. This keyword is ignored if width is not given.

The keyword :empty followed by a string causes radwho to output that string if the resulting value for this specification would otherwise be empty.

Format Spec: login width title [:empty repl][:right]: Print the user login name.

Format Spec: orig-login width title [:empty repl][:right]: Print original login name as supplied with the request.

Format Spec: gecos width title [:empty repl][:right]: The GECOS field from the local `/etc/passwd' corresponding to the login name. If the user does not have a local account, his login name is output.

Format Spec: nas-port width title [:empty repl][:right]: NAS port number

Format Spec: session-id width title [:empty repl][:right]: The session ID.

Format Spec: nas-address width title [:empty repl][:right][:nodomain]

The NAS name or IP.

The :nodomain keyword suppresses the output of the domain part of the name, i.e., the hostname is displayed only up to the first dot.

Format Spec: framed-address width title [:empty repl][:right][:nodomain]

Framed IP assigned to the user, if any.

The :nodomain keyword suppresses the output of the domain part of the name, i.e. the hostname is displayed only up to the first dot.

Format Spec: protocol width title [:empty repl][:right]: Connection protocol as reported by Framed-Protocol attribute. If the symbolic value is found in the dictionary file, it will be displayed. Otherwise, the numeric value will be displayed as is.

Format Spec: time width title [:empty repl][:right][:format date-format]

Date and time when the session started.

The :format keyword introduces the strftime format string to be used when converting the date for printing. The default value is %a %H:%M.

Format Spec: duration width title [:empty repl][:right]: Total time of the session duration.

Format Spec: delay width title [:empty repl][:right]: Delay time (see section 14.2.2 Acct-Delay-Time).

Format Spec: port-type width title [:empty repl][:right]: Port type as reported by the value of the NAS-Port-Type attribute. If the symbolic value is found in the dictionary file, it will be displayed. Otherwise, the numeric value will be displayed as is.

Format Spec: clid width title [:empty repl][:right]: The calling station ID.

Format Spec: realm width title [:empty repl][:right][:nodomain]: If the request was forwarded to a realm server, print the symbolic name of the realm from the `raddb/realms' file. If no symbolic name is found, print the remote server IP or hostname. In the latter case, the :nodomain keyword may be used to suppress the output of the domain part of the name, i.e. to display the hostname only up to the first dot.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.1.3 `radwho` Predefined Formats

The predefined formats are:

`default'

Default output format. Each record occupies one line. The fields output are: login name, GECOS name, connection protocol, port number, time when the connection was initiated, NAS IP, and assigned framed IP. This corresponds to the following format specification (split in several lines for readability:

(login 10 Login) (gecos 17 Name) \ (protocol 5 Proto) (nas-port 5 TTY) \ (time 9 When) (nas-address 9 From) \ (framed-address 16 Location)

`sid'

The same as `default', except that the session ID is output in the second column.

`clid'

The same as `default', except that the calling station ID is output in the second column.

`long'

Outputs all information from each `radutmp' record. It is equivalent to specifying the following format string:

(login 32 Login) (session-id 32 SID) \ (protocol 5 Proto) (nas-port 5 Port) \ (time 27 Date) (nas-address 32 NAS) \ (clid 17 CLID) (duration 7 Duration) \ (framed-address 16 Location) (realm 16 Realm)

`gnu'

Each `radutmp' record is represented as a table. It is equivalent to specifying the following format string:

User: (login)(newline)\ In real life: (gecos)(newline)\ Logged in: (time)(newline)\ NAS: (nas-address)(newline)\ Port: (nas-port)(newline)\ CLID: (clid)(newline)\ Protocol: (protocol)(newline)\ Session ID: (session-id)(newline)\ Uptime: (duration)(newline)\ Assigned IP: (framed-address)(newline)\ Realm: (realm)(newline)"

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.2 `radlast`

The radlast utility lists sessions of specified users, NASes, NAS ports, and hosts, in reverse time order. By default, each line of output contains the login name, the NAS short name and port number from where the session was conducted, the host IP or name, the start and stop times for the session, and the duration of the session. If the session is still continuing, radlast will so indicate.

When the `-l' option is specified, radlast produces long output. It includes following fields:

Login name
NAS short name
Port number
Connection protocol
Port type
Session ID
Caller ID
Framed IP address
Session Start Time
Session Stop Time
Duration of the Session

12.2.1 radlast Command Line Options Command line options.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.2.1 `radlast` Command Line Options

Use following command line options to control the behavior of the radlast utility:

`-number'
`-c number'
`--count number': When given this option, radlast will output at most this many lines of information.
`-f'
`--file name': Read the specified file instead of the default `/var/log/radwtmp'.
`-h hostname'
`--host hostname': Report the logins from given host. Host can be either a name or a dotted-quad Internet address.
`-n shortname'
`--nas shortname': Report the logins from the given NAS.
`-l'
`--long-format': Long output format. Report all the information stored in `radwtmp' file.
`-p number'
`--port number': Report the logins on a given port. The port may be specified either fully or abbreviated, e.g. radlast -p S03 or radlast -p 3.
`-s'
`--show-seconds': Report the duration of the login session in seconds instead of the default days, hours, and minutes.
`-t': The same as `-p'. This flag is provided for compatibility with last(1).
`-w'
`--wide': Widen the duration field to show seconds as well as the default days, hours and minutes.

If multiple arguments are given, the logical OR operation between them is assumed, i.e., the information selected by each argument is printed. This, however, does not apply to the `-c' option. That option is always combined with the rest of command line by logical AND.

The pseudo-user `~reboot' logs in on every reboot of the network access server.

If radlast is interrupted, it indicates to what date the search had progressed.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.3 `radzap`

radzap searches the Radius accounting database for matching login records and closes them.

At least one of the options `-n', `-p', or the user name must be specified. If they are used in conjunction, they are taken as if joined by the logical AND operation.

radzap operates in two modes: silent and confirm. The silent mode is enabled by default. When run in this mode, radzap deletes every record that matches the search conditions given.

In confirm mode radzap will ask for a confirmation before zapping each matching record. Any line beginning with a `y' is taken as a positive response; any other line is taken as a negative response.

The confirm mode is toggled by the command line option `-c'.

Syntax

radzap [options] [username]

Options are:

`-c'
`--confirm': Enable confirm mode.
`-d dir'
`--directory dir': Specify alternate configuration directory. Default is `/usr/local/etc/raddb'.
`-f file'
`--file file': Operate on file instead of the default `RADLOG/radutmp'.
`-l dir'
`--log-directory dir': Search the file `radutmp' in the given directory.
This option is deprecated. It is currently retained for backward compatibility with previous versions.
`-q'
`--quiet': Disable confirm mode.
`-h'
`--help': Display a short help summary, and exit.
`-n name'
`--nas name': Specify NAS name to zap user from.
`-p port'
`--port port': Specify the port number of the session to be zapped. The port number can be specified either in its full form, e.g. radzap -p S02, or in its short form, e.g. radzap -p 2.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.4 `radgrep`

This utility allows one to quickly look up the user in the Radius accounting database, using a regular expression match. radgrep scans the output of radwho utility and outputs only the lines that match given regular expressions.

Syntax

radgrep accepts two sets of options separated by `--' (double hyphen). The first subset is passed as the command line to the radwho utility. The second one is passed to grep.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.5 `radping`

This utility is a shell program that determines the user's framed IP and runs ping on that address.

Syntax

radping username
radping -c calling-station-id

The second way of invoking the program allows one to use the calling station ID to indicate the user.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.6 `radauth`

The radauth utility sends the Radius server an Access-Request packet and displays the result it gets. If the server responds with Access-Accept radauth can also send an Accounting-Request thereby initiating user's session.

The utility is a radtest program. See section 13.2.12 Sample Radtest Program, for the detailed discussion of its internals.

Invocation

radauth [options] [command] user-name [password]

Options are:

`-v': Print verbose descriptions of what is being done.
`-n nas-ip': Set NAS IP address
`-s sid': Set accounting session ID
`-P port': Set NAS port number.

<FIXME> GNU long options are not yet supported </>

Valid commands are:

auth: Send only Access-Request. This is the default.
acct: Send Access-Request. If successfull, send Accounting-Request with Acct-Status-Type = Start.
start: Send Accounting-Request with Acct-Status-Type = Start.
stop: Accounting-Request with Acct-Status-Type = Stop.

The program determines which Radius server to use, the authentication port number, and the shared secret, following the procedure common to all client scripts (see section 13.1 Client Configuration).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.7 `radctl`

Radctl is a control interface to the radiusd daemon. It allows the user running it to query radiusd about various aspects of its work and to issue administrative commands to it. The syntax is

radctl command [args]

where command is a command telling radctl which actions to take, and args are optional arguments to the command. Only one command can be specified per invocation.

The valid commands are as follows:

start [args]

If radiusd is not running already, it is started. When present, args are passed as the command line to the server.

stop

Stops running radiusd.

restart [args]

Stops the server and then starts it again. When present, args are passed as the command line to the server.

reload

Causes the running radiusd server to reread its configuration files.

dumpdb

Tells radiusd to dump its user hash table into the file `radlog/radius.parse'. This can be used for debugging configuration files.

which

Reports the running version of radiusd. This command shows the line of ps(1) describing the running copy of radiusd program. The exact look depends on the version of operating system you are running. Please refer to "man ps" for more detail on ps output.

Here is an example of what radctl which prints on GNU/Linux:

19692 ? 01:53:11 radiusd

Here, first field is the PID of the process, second field (`?') indicates that the running program has detached from the controlling terminal, the third field gives total amount of CPU time used by the program, and, finally, the last field shows the full name under which the command was invoked.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.8 `builddbm`

Usage

builddbm converts the plaintext Radius users database into DBM files. Some versions of the Radius daemon have used this to speed up the access to the users database. However, with GNU Radius things go the other way around. The server reads the entire plaintext database, converts it into internal form, and stores into a hash table, which provides for fast access. Actually, using a DBM version of the users database slows down the access unless the machine that runs the Radius daemon is short of address space for the daemon to store the users database.

Syntax

When used without arguments, the builddbm utility attempts to convert the file `raddb/users' to `raddb/users.db' or to the pair `raddb/users.pag', `raddb/users.dir', depending on the version of the DBM library used.

If used with one argument, that argument is taken as the name of the plaintext database file to operate upon.

Use the following command line options to modify the operation of buildbm:

`-d dir': Specifies alternate directory for the Radius configuration files. This defaults to `/usr/local/etc/raddb'.
`-h': Outputs short usage summary and exits with 0 exit code.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.9 `radscm`: A Guile Interface to Radius Functions

radscm is a Scheme interpreter based on Guile with the addition of special functions and variables for communicating with radiusd. This chapter concentrates on the special features provided by radscm. Refer to Guile documentation for information about Scheme and Guile (see section `Overview' in The Guile Reference Manual).

Variables

Variable: %raddb-path: A path to the Radius configuration directory.

Function: rad-server-list

A list of radius servers. Each element of the list is:

(list id-str host-str secret-str auth-num acct-num cntl-num)

where the arguments are as follows:

id-str Server ID

host-str Server hostname or IP

secret-str Shared secret key to use

auth-num Authentication port number

acct-num Accounting port number

cntl-num Control channel port number
Thus, each entry can be used as an argument to rad-client-set-server or rad-client-add-server.

Functions

Function: rad-send-internal port-number code-number pair-list

Sends the request to currently selected server. Arguments are:

port-number

Port number to use. These values are allowed:

0 Authentication port

1 Accounting port

2 Control port
The actual port numbers are those configured for the given server.

code-number

Request code.

pair-list

List of attribute-value pairs. Each pair is either

        (cons attr-name-str value)

        (cons attr-number value)

Return: On success,

(list return-code-number pair-list)
On failure,

'()

Function: rad-send port-number code-number pair-list . verbose: Sends a radius request. Actually it does the same work as rad-send-internal, but if verbose is specified, the verbose report about interaction with the radius server is printed.

Function: rad-client-list-servers: List currently configured servers. Two columns for each server are displayed: server ID and IP.

Function: rad-get-server: Returns the ID of the currently selected server.

Function: rad-client-set-server list

Selects for use the server described by list. Here list takes the form

(list id-str host-str secret-str auth-num acct-num cntl-num)
where the elements are as follows:

id-str Server ID

host-str Server hostname or IP

secret-str Shared secret key to use

auth-num Authentication port number

acct-num Accounting port number

cntl-num Control channel port number

Function: rad-client-add-server list

Adds the server described by list to the list of active servers. Here list takes the form

(list id-str host-str secret-str auth-num acct-num cntl-num)

where the elements are as follows:

id-str Server ID

host-str Server hostname or IP

secret-str Shared secret key to use

auth-num Authentication port number

acct-num Accounting port number

cntl-num Control channel port number

Function: rad-read-no-echo prompt-str: Prints the given prompt-str, disables echoing, reads a string up to the next newline character, restores echoing, and returns the string entered. This is the interface to the C getpass(3) function.

Function: rad-client-source-ip ip-str: Sets the IP to be used as source. ip-str can be either an IP in dotted-quad form or a hostname.

Function: rad-client-timeout number: Sets the timeout in seconds for waiting for a server reply.

Function: rad-client-retry number: Sets the number of retries for sending requests to a Radius server.

Function: rad-format-code dest-bool code-number: Format a radius reply code into a human-readable form. dest-bool has the same meaning as in format (see section `Formatted Output' in The Guile Reference Manual.)

Function: rad-format-pair dest-bool pair

Format a radius attribute-value pair for output. dest-bool has the same meaning as in format. pair is either

                (cons name-str value)

                (cons attr-number value)

where value may be of any type appropriate for the given attribute.

Function: rad-print-pairs dest-bool pair-list

Output the radius attribute-value pairs from pair-list. dest-bool has the same meaning as in format. pair-list is a list of pairs in the form

(cons name-str value)
or

(cons attr-number value)
where value may be of any type appropriate for the given attribute.

All Reply-Message pairs from the list are concatenated and displayed as one.

Function: rad-format-reply-msg pair-list . text: Concatenate and print text from all Reply-Message pairs from pair-list. If text is specified, it is printed before the concatenated text.

Function: rad-list-servers: For each server from rad-server-list, print its ID and hostname or IP.

Function: rad-select-server ID-STR: Select the server identified by id-str as a current server. The server data are looked up in rad-server-list variable.

Function: rad-add-server id-str: Add the server identified by id-str to the list of current servers. The server data are looked up in rad-server-list variable.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13. Client Package

Beside the Radius server and accompanying utilities, GNU Radius provides a set of utilities to be used as Radius clients.

The following sections describe in detail the parts of the Radius client package.

13.1 Client Configuration    Configuration file is common for all client utilities.

13.2 radtest    Radius client shell.

13.3 radsession    Send arbitrary requests to Radius server.

13.4 nas.scm    A NAS implementation for GNU/Linux machines.

13.5 pam_radius.so    A PAM module for authentication via Radius.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.1 Client Configuration

All programs from the client package share the same configuration file: `raddb/client.conf'. The file uses simple line-oriented syntax. Empty lines are ignored; the command `#' introduces an end-of-line comment.

The source IP is introduced with the source_ip statement. Its syntax is:

source_ip ip-addr

where ip-addr must be the IP in dotted-quad notation.

The Radius server to send the requests to is introduced with server statement:

server name ip-addr secret auth-port acct-port

Its parts are:

name: The server name. It is reserved for further use.
ip-addr: The server IP.
secret: The shared secret to be used when sending requests to this server.
auth-port: The authentication port number.
acct-port: The accounting port number.

If several server statement are present, they are tried in turn until one of them replies to the request.

The amount of time a client program waits for the reply from a server is configured using the timeout statement:

timeout number

If the program does not receive any response within number seconds, it assumes the server does not respond and either retries the transmission or tries the next available server. The number of retries is set with the retry statement:

retry number

The example `raddb/client.conf' follows:

server first 10.11.10.1 secret 1645 1646 server second 10.11.10.1 secret 1645 1646 source_ip 127.0.0.1 timeout 3 retry 5

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.2 radtest

Radtest is a radius client shell, providing a simple and convenient language for sending requests to RADIUS servers and analyzing their reply packets.

13.2.1 Invoking radtest

13.2.2 Literal Values

13.2.3 Reserved Keywords

13.2.4 Variables

13.2.5 Positional Parameters

13.2.6 Expressions

13.2.7 Function Definitions

13.2.8 Interacting with Radius Servers

13.2.9 Conditional Statements

13.2.10 Loops

13.2.11 Built-in Primitives

13.2.12 Sample Radtest Program

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.2.1 Invoking radtest

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

`-a variable=value'
`--assign=variable=value': Assign a value to variable. See section 13.2.4.5 Assignment Options, for a detailed discussion.
`-f file'
`--file=file': Read input from file. Stops further processing of the command line.
`-i'
`--no-interactive': Disable interactive mode.
`-n'
`--dry-run': Check the input file syntax and exit.
`-q'
`--quick': Do not read the configuration file. <FIXME> </>
`-r number'
`--retry=number': Set number of retries.
`-s server'
`--server=server': Set radius server parameters.
`-t number'
`--timeout=number': Set timeout
`-v'
`--verbose': Verbose mode
`-x debugspec'
`--debug=debugspec': Set debugging level
`-d dir'
`--directory dir': Specify alternate configuration directory. Default is `/usr/local/etc/raddb'.
`-L'
`--license': Print license and exit.
`-?'
`--help': Print short usage summary
`--usage': Print even shorter usage summary.
`-V'
`--version': Print program version.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.2.2 Literal Values

There are four basic data types in radtest language: integer, ipaddr, string and avlist.

13.2.2.1 Numeric Values    Integers and IP addresses.

13.2.2.2 Character Strings

13.2.2.3 Lists of A/V pairs

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.2.2.1 Numeric Values

Integer means a signed integer value in the range -2147483648..2147483647.

Ipaddr is an unsigned integer value suitable for representing IPv4 addresses. These can be input either as decimal numbers or as IP addresss in usual "dotted-quad" notation.

As a convenience measure, RADIUS request code names can be used in integer context. The following table lists currently defined request names with their integer codes:

Access-Request 1

Access-Accept 2

Access-Reject 3

Accounting-Request 4

Accounting-Response 5

Accounting-Status 6

Password-Request 7

Password-Ack 8

Password-Reject 9

Accounting-Message 10

Access-Challenge 11

Status-Server 12

Status-Client 13

Ascend-Terminate-Session 31

Ascend-Event-Request 33

Ascend-Event-Response 34

Ascend-Allocate-IP 51

Ascend-Release-IP 52

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.2.2.2 Character Strings

String is an arbitrary string of characters. Any input token consisting of letters of Latin alphabet, decimal digits, underscores dashes and dots and starting with a Latin alphabet letter or underscores is considered a string. To input strings containing other letters, surround them by double quotes. The following are valid strings:

A-string "String, containing white space"

The double quote character `"' must be preceeded by a backslash `\' if it is part of a string:

"Always quote \" character"

Generally speaking, `\' is an escape character, that alters the meaning of the immediately following character. If it is located at the end of the line, it allows to input newline character to strings:

"This string contains a \ newline character."

Other special escape sequences are:

\a: Audible bell character (ASCII 7)
\b: Backspace (ASCII 8)
\e: Escape character (ASCII 27)
\f: Form feed (ASCII 12)
\n: Newline (ASCII 10)
\r: Carriage return (ASCII 13)
\t: Horizontal tab (ASCII 9)
\\: Backslash
\ooo: (`o' represents an octal digit) A character whose ASCII value is represented by the octal number `ooo'.
\xHH
\XHH: (`H' represents a hex digit) A character whose ASCII value is represented by the hex number `HH'.

If the character following the backslash is not one of those specified, the backslash is ignored.

An important variant of string is a numeric string, or STRNUM for short. A numeric string is a string that can be converted to a number, for example "+2". This concept is used for type conversion between integer and string values.

Another way to represent strings is using here document syntax. Its format is as follows:

<<[-]delimiter text delimiter

Delimiter is any word you choose to delimit the text, text represent the text of the string. If delimiter is prepended by a dash, any leading tabulation characters will be removed from text. This allows for natural indentation of `here document' constructs.

The `here document' construct is especially useful to represent strings containing embedded newlines, as shown in the example below:

print <<EOT usage: foo [OPTIONS] [NAME...] OPTIONS are: -h Print this help list. EOT

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.2.2.3 Lists of A/V pairs

Avlist are whitespace or comma-separated lists of RADIUS attribute-value pairs. A syntax for A/V pair is

name op value

where name is attribute name, op is a comparison operator (`=', `!=', `<', `<=', `>', `>='), and value is any valid radtest data or expression. An A/V pair list must be enclosed in parentheses. This is an example of an A/V pair list consisting of two pairs:

( User-Name = "test" NAS-IP-Address = 10.10.10.1 )

An empty pair list is represented by a pair of parentheses: ().

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.2.3 Reserved Keywords

The following keywords are reserved in radtest:

acct, and, auth, begin, break, case, continue, do, else, end, exit, expect, getopt, if, in, input, not, or, print, return, send, set, shift, while

The reserved keywords may be used as variable names, provided that the following requrements are met:

In assignment, these names are quoted using single quotes.
'case' = 1
When dereferencing, the use of curly braces is obligatory:
${case} + 2

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.2.4 Variables

Variables are means of storing data values at one point of your program for using them in another parts of it. Variables can be assigned either in the program itself, or from the radtest command line.

13.2.4.1 Using Variables

13.2.4.2 Variable Assignments

13.2.4.3 Dereferencing Variables

13.2.4.4 Accessing Elements of A/V Pair Lists

13.2.4.5 Assignment Options

13.2.4.6 Built-in Variables

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.2.4.1 Using Variables

The name of a variable must be a sequence of letters, digits, underscores and dashes, but it may not begin with a digit or dash. Notice, that in contrast to the majority of programming languages, use of dashes (minus signs) is allowed in user names. This is because traditionally RADIUS attribute names contain dashes, so extending this practice to variable names makes radtest programs more consistent. On the other hand, this means that you should be careful when using minus sign as a subtraction operator (see minus-ambiguity<

2. Naming Conventions		Conventions about naming files and directories
3. How Radius Operates		How `radiusd` operates
4. How to Start the Daemon.		How to start the daemon
5. Radius Configuration Files		`radiusd` configuration files
6. Request Comparison Methods		How duplicate requests are dealt with
7. Authentication		How users are authenticated
8. Accounting		Accounting methods
9. Logging		What gets logged and where
10. Problem Tracking		Fixing configuration errors
11. Extensions		Extending GNU Radius

15. Reporting Bugs		How to report a bug
16. Where to Get Information about GNU Radius		Where to get info about GNU Radius

How to Obtain Radius		How to Obtain the GNU Radius
Radius Glossary		The glossary
Acknowledgements

5.1 Run-Time Configuration Options -- `raddb/config'		Run-time configuration options.
5.2 Dictionary of Attributes -- `raddb/dictionary'		Radius dictionary.
5.3 Clients List -- `raddb/clients'		Clients lists the NASes that are allowed to communicate with radius.
5.4 NAS List -- `raddb/naslist'		The naslist file keeps general information about the NASes.
5.5 NAS Types -- `raddb/nastypes'		Information about how to query the NASes about active user sessions.
5.6 Request Processing Hints -- `raddb/hints'		Important user information that is common for the users whose names match some pattern.
5.7 Huntgroups -- `raddb/huntgroups'		Group users by the NAS (and, possibly, a port number) they come from.
5.8 List of Proxy Realms -- `raddb/realms'		Communication with remote radius servers
5.9 User Profiles -- `raddb/users'		User profile.
5.10 List of Blocked Users -- `raddb/access.deny'		List of users which are denied access.
5.11 SQL Configuration -- `raddb/sqlserver'		SQL server configuration.
5.12 Rewrite functions -- `raddb/rewrite'		Rewrite functions allow to change the input packets.
5.13 Login Menus -- `raddb/menus'		Menus allow user to select the type of service.

Directory	Short name	Default location
Configuration directory	`raddb'	/usr/local/etc/raddb
Log directory	`radlog'	/var/log
Accounting directory	`radacct'	/var/log/radacct
Data directory	`datadir'	/usr/local/share/radius/1.3

3.1 Attributes
3.2 RADIUS Requests		RADIUS requests.
3.3 Matching Rule		Rules for request processing.
3.4 Processing Requests		How GNU Radius processes incoming requests.

5.1.1 `option` block		`Option` block: set the global program options.
5.1.2 `logging` block		Fine-tune the logging.
5.1.3 `auth` statement		Configure authentication service.
5.1.4 `acct` statement		Configure accounting service.
5.1.5 `usedbm` statement		Enable the DBM feature.
5.1.6 `snmp` statement		Configure SNMP service.
5.1.7 `rewrite` statement.		Configure Rewrite interface.
5.1.8 `guile` statement		Configure Guile interface.
5.1.9 `message` statement		Configure server reply messages.
5.1.10 `filters` statement		Configure authentication and accounting filters.
5.1.11 `mlc` statement		Configure multiple login checking.

5.1.2.1 Logging hooks
5.1.2.2 `category` statement
5.1.2.3 `channel` statement
5.1.2.4 Example of the `logging` statement

5.2.1 Comments		Introducing a comment line.
5.2.2 $INCLUDE Statement		Include a file.
5.2.3 VENDOR Statement		Define a vendor-id.
5.2.4 ATTRIBUTE statement		Define an attribute translation.
5.2.5 Blocks of Vendor-Specific Attributes		Blocks of vendor-specific attributes
5.2.6 ALIAS statement		Define alternative name for an attribute.
5.2.7 PROPERTY statement		Define attribute properties.
5.2.8 VALUE Statement		Define a value translation.

5.5.1 Syntax of `raddb/nastypes'		Syntax described.
5.5.2 Example of nastypes file.
5.5.3 Standard NAS types		NAS types defined in standard nastypes file.

user_name	attr	value	op
`jsmith`	`NAS-IP-Address`	`10.10.10.1`
`jsmith`	`NAS-Port-Id`	`20`	`<=`
`jsmith`	`Framed-Protocol`	`PPP`	`NULL`
`jsmith`	`Framed-IP-Address`	`10.10.10.11`	`NULL`

7.1 Accept Authentication Type		Accept unconditionally.
7.2 Reject Authentication Type		Reject unconditionally.
7.3 Local Password Authentication Type		Authenticate using plaintext password.
7.4 Encrypted Password Authentication Type		Authenticate using MD5 encrypted password.
7.5 System Authentication Type		Authenticate using system account.
7.6 SQL Authentication Type		Authenticate using SQL.
7.7 PAM Authentication Type		Authenticate using PAM.
7.8 Defining Custom Authentication Types
7.9 Multiple Login Checking		Checking for Simultaneous Logins.
7.10 Controlling Authentication Probes

8.1 System Accounting		UNIX style utmp/wtmp accounting.
8.2 Detailed Request Accounting		Detailed requests.
8.3 SQL Accounting		Accounting to SQL server.
8.4 Defining Custom Accounting Types

10.1 Rule Tracing		Tracing rules.
10.2 Debugging		Enabling full debugging information.
10.3 Test Mode		Running radius in test mode.

File name	Line number
`/etc/raddb/hints'	34
`/etc/raddb/huntgroups'	72
`/etc/raddb/users'	3
`/etc/raddb/users'	22
`/etc/raddb/users'	157

11.1 Filters		Using external filter programs.
11.2 Rewrite		The built-in extension language.
11.3 Guile		Using Scheme.

type	Variable type	Resulting conversion
integer	integer	No conversion. This results in the same integer value.
integer	string	If the string value of the variable is a valid ASCII representation of the integer number (either decimal, octal, or hex), it is converted to the integer; otherwise the result of the conversion is undefined.
string	integer	The ASCII representation (in decimal) of the integer number.
string	string	No conversion. This results in the same string value.

12.1 `radwho`		Show who is logged in by radius now.
12.2 `radlast`		Show the history of logins by radius.

12.3 `radzap`		Modify the login records.
12.4 `radgrep`		Quickly find the login record.
12.5 `radping`		Ping the remote machine by the username.
12.6 `radauth`		Check if a user can be authenticated.
12.7 `radctl`		Radctl monitor.
12.8 `builddbm`		Create DBM version of the `raddb/users' file.

12.1.1 `radwho` Command Line Options		Command line options.
12.1.2 `radwho` Format Strings
12.1.3 `radwho` Predefined Formats

GNU Radius Reference Manual

Introduction to Radius

1.0 Overview

How Does RADIUS Perform These Tasks?

RADIUS Attributes

RADIUS Packets

2. Naming Conventions

3. How Radius Operates

3.1 Attributes

3.2 RADIUS Requests

3.2.1 Authentication Requests

3.2.2 Accounting Requests

3.3 Matching Rule

3.4 Processing Requests

3.4.1 Checking for Duplicate Requests

3.4.2 Proxying

3.4.2.1 Proxy Service

3.4.2.2 Realms

3.4.3 Hints

3.4.4 Huntgroups

3.4.5 User Profiles

4. How to Start the Daemon.

5. Radius Configuration Files

5.1 Run-Time Configuration Options -- `raddb/config'

5.1.1 option block

Syntax:

Usage

Boolean statements

Numeric statements

String statements

5.1.2 logging block

Syntax:

Usage

5.1.2.1 Logging hooks

5.1.2.2 category statement

5.1.2.3 channel statement

5.1.2.4 Example of the logging statement

5.1.3 auth statement

Syntax:

Usage:

listen statement

forward statement

Numeric statements

Boolean statements

Character statement

5.1.4 acct statement

Syntax:

Usage:

listen statement

forward statement

Numeric statements

Boolean statements

Character statement

5.1.5 usedbm statement

Syntax:

Usage

5.1.6 snmp statement

Syntax:

Usage

listen statement

Numeric statements

String statements

Community and network definitions

Access-Control List definitions

Storage control

5.1.7 rewrite statement.

Syntax:

Numeric statements

String statements

Loading

5.1.8 guile statement

Syntax

Usage

Boolean statements

Numeric statements

String statements

5.1.9 message statement

Syntax

String statements

5.1.10 filters statement

5.1.1 `option` block

5.1.2 `logging` block

5.1.2.2 `category` statement

5.1.2.3 `channel` statement

5.1.2.4 Example of the `logging` statement

5.1.3 `auth` statement

`listen` statement

`forward` statement

5.1.4 `acct` statement

`listen` statement

`forward` statement

5.1.5 `usedbm` statement

5.1.6 `snmp` statement

`listen` statement

5.1.7 `rewrite` statement.

5.1.8 `guile` statement

5.1.9 `message` statement

5.1.10 `filters` statement

5.1.11 `mlc` statement

id-str	Server ID
host-str	Server hostname or IP
secret-str	Shared secret key to use
auth-num	Authentication port number
acct-num	Accounting port number
cntl-num	Control channel port number

13.1 Client Configuration		Configuration file is common for all client utilities.
13.2 radtest		Radius client shell.
13.3 radsession		Send arbitrary requests to Radius server.
13.4 `nas.scm`		A NAS implementation for GNU/Linux machines.
13.5 `pam_radius.so`		A PAM module for authentication via Radius.

13.2.2.1 Numeric Values		Integers and IP addresses.
13.2.2.2 Character Strings
13.2.2.3 Lists of A/V pairs

Access-Request	1
Access-Accept	2
Access-Reject	3
Accounting-Request	4
Accounting-Response	5
Accounting-Status	6
Password-Request	7
Password-Ack	8
Password-Reject	9
Accounting-Message	10
Access-Challenge	11
Status-Server	12
Status-Client	13
Ascend-Terminate-Session	31
Ascend-Event-Request	33
Ascend-Event-Response	34
Ascend-Allocate-IP	51
Ascend-Release-IP	52

13.2.4.1 Using Variables
13.2.4.2 Variable Assignments
13.2.4.3 Dereferencing Variables
13.2.4.4 Accessing Elements of A/V Pair Lists
13.2.4.5 Assignment Options
13.2.4.6 Built-in Variables