5.3 In-depth Configuration

At this point, you've compiled, installed, configured, started, and tested a simple FreeRADIUS implementation that is functional. However, 99.5% of the RADIUS/AAA implementations around the world are just not that simple. In this section, I'll delve into the two major configuration files and discuss how to tweak, tune, customize, and effect change to the default FreeRADIUS installation. In Chapter 6, I'll discuss advanced topics, such as pluggable authentication module (PAM) support, integration with MySQL, LDAP usage, and other topics.

5.3.1 Configuring radiusd.conf

radiusd.conf file is the central location to configure most aspects of the FreeRADIUS product. It includes configuration directives as well as pointers and two other configuration files that may be located elsewhere on the machine. There are also general configuration options for the multitude of modules available now and in the future for FreeRADIUS. The modules can request generic options, and FreeRADIUS will pass those defined options to the module through its API.

Before we begin, some explanation is needed of the operators used in the statements and directives found in these configuration files. The = operator, as you might imagine, sets the value of an attribute. The := operator sets the value of an attribute and overwrites any previous value that was set for that attribute. The == operator compares a state with a set value. It's critical to understand how these operators work in order to obtain your desired configuration.

In this chapter, I'll look at several of the general configuration options inside radiusd.conf. Some of the more advanced directives in this file will be covered in Chapter 6.

This file contains the process identification number for the radiusd daemon. You can use this file from the command line to perform any action to a running instance of FreeRADIUS. For example, to shut FreeRADIUS down without any protests, issue:

kill -9 `cat /var/run/radiusd.pid'

Usage:

pidfile = [path]

Suggestion:

pidfile = ${run_dir}/radiusd.pid

These options dictate under what user and group radiusd runs. It is not prudent to allow FreeRADIUS to run under a user and group with excessive permissions. In fact, to minimize the permissions granted to FreeRADIUS, use the user and group "nobody." However, on systems configured to use shadow passwords, you may need to set the user to "nobody" and the group to "shadow" so that radiusd can read the shadow file. This is not a desirable idea. On some systems, you may need to set both the user and group to "root," although it's clear why that is an even worse idea.

Usage:

user = [username]; group = [groupname]

Suggestion:

user = nobody; group = nobody

This option specifies the maximum number of seconds a request will be processed by FreeRADIUS. If the handling of a request takes longer than this threshold, the process can be killed off and an Access-Reject message returned. This value can range from 5 to 120 seconds.

Usage:

max_request_time = 30

Suggestion:

max_request_time = 60

This directive is paired with the max_request_time directive in that it controls when requests that exceed the time threshold should be killed. Most of the time, this value should be set to "no."

Usage:

delete_blocked_requests = [yes/no]

Suggestion:

delete_blocked_requests = no

When FreeRADIUS sends a reply to RADIUS client equipment, it generally caches that request internally for a few seconds to ensure that the RADIUS client will receive the message (sometimes network problems, offline servers, and large traffic loads might prevent the client from picking up the packet). The client receives a quick reply on its prompting for a second copy of the packet, since the internal cache mechanism for FreeRADIUS is much quicker than processing the request again. This value should be set between 2 and 10: this range is the happy medium between treating every request as a new request and caching so many processed requests that some new requests are turned away.

Usage:

cleanup_delay = [value]

Suggestion:

cleanup_delay = 6

This directive specifies the maximum number of requests FreeRADIUS will keep tabs on during operation. The value starts at 256 and scales with no upper limit, and ideally this is set at the number of RADIUS clients you have multiplied by 256. Setting this value too high causes the server to eat up more system memory, while setting it too low causes a delay in processing new requests once this threshold has been met. New requests must wait for the cleanup delay period to finish before they can be serviced.

Usage:

max_requests = [value]

Suggestion:

max_requests = [256 * x number of clients]

This directive specifies the address under which radiusd will accept requests and reply to them. The "address" can be an IP address, fully qualified domain name, or the * wildcard character (to instruct the daemon to listen on all interfaces).

Usage:

bind_address = [value]

Suggestion:

bind_address = *

This setting instructs FreeRADIUS to listen on a specific port. While the RADIUS RFC specifies that the official RADIUS port is 1812, historically NAS equipment and some RADIUS servers have used port 1645. You should be aware of the port your implementation uses. While you can specify a certain port here, you can also instruct radiusd to use the machine's /etc/services file to find the port to use. Additionally, using the -p switch when executing radiusd will override any port setting provided here.

Usage:

port = [value]

Suggestion:

port = 1645

This directive tells FreeRADIUS whether to look up the canonical names of the requesting clients or simply log their IP address and move on. Much like with Apache, DNS queries take a long time and, especially on highly loaded servers, can be a detriment to performance. Turning this option on also causes radiusd to block the request for 30 seconds while it determines the CNAME associates with that IP address. Only turn this option on if you are sure you need it.

Usage:

hostname_lookups = [yes/no]

Suggestion:

hostname_lookups = no

This directive determines whether FreeRADIUS should dump to core when it encounters an error or simply silently quit with the error. Only enable this option if you're developing for FreeRADIUS or attempting to debug a problem with the code.

Usage:

allow_core_dumps = [yes/no]

Suggestion:

allow_core_dumps = no

This set of controls configures regular and extended expression support. Realistically, you shouldn't need to alter these as they're set when running the ./configure command upon initial install.

Usage:

regular_expressions = [yes/no]; extended_expressions = [yes/no]

Suggestion:

regular_expressions = yes; extended expressions = yes

These directives control how access to and requests of the FreeRADIUS server are logged. The log_stripped_names control instructs FreeRADIUS whether to include the full User-Name attribute as it appeared in the packet. The log_auth directive specifies whether to log authentication requests or simply carry them out without logging. The log_auth_badpass control, when set to yes, causes radiusd to log the bad password that was attempted, while the log_auth_goodpass logs the password if it's correct.

Usage:

log_stripped_names = [yes/no]; log_auth = [yes/no];
log_auth_badpass = [yes/no]; log_auth_goodpass = [yes/no]

Suggestion:

log_stripped_names = no; log_auth = yes;
log_auth_badpass = yes; log_auth_goodpass = no

To eliminate case problems that often plague authentication methods such as RADIUS, the FreeRADIUS developers have included a feature that will attempt to modify the User-Name and User-Password attributes to make them all lowercase; this is done either before an authentication request, after a failed authentication request using the values of the attributes as they came, or not at all.

Clearly setting the lower_user directive to after makes the most sense: it adds processing time to each request, but unless this particular machine normally carries a high load, the reduced troubleshooting time is worth the extra performance cost. However, a secure password often makes use of a combination of uppercase and lowercase letters, so security dictates leaving the password attribute alone.

Usage:

lower_user = [before/after/no]; lower_pass = [before/after/no]

Suggestion:

lower_user = after; lower_pass = no

Much like the lower_user and lower_pass controls, these directives preprocess an Access-Request packet and ensure that no spaces are included. The available options are the same: before, after, or no. Again, the most obvious choice is to set nospace_user to after to save helpdesk time. Some administrators have a tendency to not allow spaces in passwords; if this is the case, set nospace_pass to before (since there is a system-wide policy against spaces in passwords, testing a request as-is is not required).

Usage:

nospace_user = [before/after/no]; nospace_password = [before/after/no]

Suggestion:

nospace_user = after; nospace_password = before

5.3.2 Configuring the users File

The users file, located at /etc/raddb/users, is the home of all authentication security information for each user configured to access the system. Each user has an individual stanza, or entry. The file has a standard format for each stanza:

The users file also comes with a default username of—you guessed it—DEFAULT, which is generally the catchall configuration. That is to say, if there is no explicit match for a particular user, or perhaps the attribute information for a user is incomplete, radiusd will configure the session based on the information in the DEFAULT entry.

FreeRADIUS processes this file in the order in which the entries are listed. When information received from the RADIUS client equipment matches an entry in the users file, FreeRADIUS stops processing and sets the service up based on that users file entry. However, you can alter this behavior by setting the Fall-Through attribute to yes in an entry. When radiusd encounters a positive fall-through entry, it will continue processing the users file and then select the best match for the particular session. The DEFAULT user can also have a Fall-Through attribute, which means you can have multiple DEFAULT entries for various connection scenarios.

If you don't want to issue a password for each user via their entry in the users file, then simply set Auth-Type := System on the first line for each user. FreeRADIUS will then query the system password database for the correct password, which saves some administrative headache.

5.3.2.1 A sample complete entry

The following is a complete entry for the user jhassell, dialing into a NAS server using PPP. Note that (a) there is no Fall-Through attribute set, so FreeRADIUS will stop processing when it encounters this entry, and (b) no DEFAULT entry will be used to add attribute information to this connection:

jhassell    Auth-Type := System
            Service-Type = Framed-User,
            Framed-Protocol = PPP,
            Framed-IP-Address = 192.168.1.152,
            Framed-IP-Netmask = 255.255.255.0,
            Framed-Routing = Broadcast-Listen,
            Framed-Filter-Id = "20modun",
            Framed-MTU = 1500,
            Framed-Compression = Van-Jacobsen-TCP-IP

Next, here's a complete entry for the user Anna Watson. She has a space in her user-name and she also has a password specified in her entry. She also gets a positive fall-through so that she can use some of the DEFAULT user's attributes with her connection:

"Anna Watson"    Auth-Type := Local, User-Password == "yes123"
                 Reply-Message = "Hello, %u"
                 Service-Type = Framed-User,
                 Framed-Routing = Broadcast-Listen,
                 Framed-Filter-Id = "20modun",
                 Fall-Through = Yes

5.3.2.2 DEFAULT entries

These DEFAULT user configurations match with all usernames that can get to them (i.e., the individual users must have a positive Fall-Through attribute). Recall from the earlier discussion that DEFAULT entries may also have Fall-Through attributes.

First, let's make sure that all users are checked against the system password file unless they have a password explicitly assigned in the entry.

DEFAULT    Auth-Type := System
           Fall-Through = Yes

Now, include a DEFAULT entry for all users connecting via a framed protocol, such as PPP or SLIP. Note that I tell the RADIUS client to assign the IP address via the Framed-IP-Address attribute's value (see Chapter 3 for details).

DEFAULT    Service-Type = Framed-User
           Framed-IP-Address = 255.255.255.254,
           Framed-MTU = 576,
           Service-Type = Framed-User,
           Fall-Through = Yes

Finally, set the DEFAULT entry for PPP users. I've already told FreeRADIUS to assign framed protocol users with a dynamic IP address, so all I need to do is set the compression method and explicitly designate PPP as the framed protocol for this default.

DEFAULT    Framed-Protocol == PPP
           Framed-Protocol = PPP,
           Framed-Compression = Van-Jacobsen-TCP-IP

If a user attempts to connect and matches neither any of the explicit user entries nor any of the DEFAULT entries, then he will be denied access. Notice that with the last DEFAULT entry, Fall-Through isn't set: this ensures the user is kicked off if he doesn't match any of the scenarios.

5.3.2.3 Prefixes and suffixes

You can use prefixes and suffixes appended to the user name to determine what kind of service to provision for that particular connection. For example, if a user adds .shell to their username, you add the following DEFAULT entry to the users file to provision a shell service for her. FreeRADIUS authenticates her against the system password file, telnets to your shell account machine, and logs her in.

DEFAULT    Suffix == ".shell", Auth-Type := System
           Service-Type = Login-User,
           Login-Service = Telnet,
           Login-IP-Host = shellacct1.rduinternet.com

Similarly, you can set up an entry in the users file where if a user connects with a prefix of "s.", then you can provision SLIP service for him. FreeRADIUS can authenticate him against the system passwords, and then fall through to pick up the SLIP attributes from another DEFAULT entry. Here is an example:

DEFAULT    Prefix == "s.", Auth-Type := System
           Service-Type = Framed-User,
           Framed-Protocol = SLIP,
           Fall-Through = Yes

5.3.2.4 Using RADIUS callback

The callback feature of the RADIUS protocol is one of the most interesting and useful security measures that you, as an administrator, can enforce. You can configure FreeRADIUS to call a specific user back via his individual entry in the users file. (Of course, you could make a DEFAULT entry that calls every user back, but the application of that technique is more limited and requires many more resources than a standard implementation.) The following is an example of a callback configuration for user rneis: she dials in, is then called back, is authenticated, and then given a session on the shell account machine.

rneis    Auth-Type := System
         Service-Type = Callback-Login-User,
         Login-Service = Telnet,
         Login-IP-Host = shellacct1.rduinternet.com,
         Callback-Number = "9,1-919-555-1212"

5.3.2.5 Completely denying access to users

You can set up a specific user entry to deny access to him. For example, you may have an automated script that takes input from your billing system (a list of usernames that have not paid their bills, possibly) and re-writes user entries to deny access. They would write something like the following, for the user aslyter:

aslyter    Auth-Type := Reject
           Reply-Message = "Account disabled for nonpayment."

Alternatively, you could also set up a group on your system called "suspended," and FreeRADIUS could detect whether an individual username was contained within that group and reject access as necessary. To do this, create a DEFAULT entry much like the following:

DEFAULT    Group == "suspended", Auth-Type := Reject
           Reply-Message = "Account suspended for late payment."