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.

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.

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

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.

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

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.

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

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:

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

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

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

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

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

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

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.

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:

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

GNU Radius keeps the information about the realms it serves in the `raddb/realms' configuration file (see section 5.8 List of Proxy Realms -- `raddb/realms').

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

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

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