Configuring a Module

The configuration files in mods-available/ file describe the configuration parameters accepted by each module, and what they do. This document explains how to perform generic testing with any module.

The default server configuration should be tested via the following command:

radiusd -XC

If the configuration is correct, then the server will print the following message:

Configuration appears to be OK

If that message does not appear, then it is necessary to correct any and all errors before proceeding to the next step. It is a good idea to ensure that the current configuration works before making changes to it.

Editing mods-available/MODULE

As with all FreeRADIUS configuration files, please change at little as possible in the default configuration. The defaults are usually close to being correct. All that is necessary is to make minor changes, and test them. FreeRADIUS should look for data.

Enabling mods-available/MODULE

A module is enabled by creating a soft link from the mods-enabled/ directory to the mods-available/ directory.

cd raddb/mods-enabled && ln -s ../mods-available/MODULE

Where MODULE is the name of the module that is being enabled.

It is also possible to copy the mods-available/MODULE default configuration file to mods-enabled/MODULE, and then edit that file. This process leaves the original mods-available/MODULE configuration file in place, if there is a need to refer to it in the future. The choice of which method to use is up to the local administrator.

Testing the Server

The configuration of the server can be tested for syntactical correctness via the following command:

radiusd -XC

When the configuration is correct, then the server will print the following message:

Configuration appears to be OK

Note that this test checks only that the configuration files can be parsed. It does not check that the module will correctly process packets.

When the configuration is correct, FreeRADIUS can then be started in debugging mode:

radiusd -X

If the module has been configured correctly, the final (or almost final) message will be

Ready to process requests

This message should be in bold on the console. Depending on which other modules are enabled, there may be a small number messages after this one.

If the server starts, then the next step is then to perform module-specific tests. Please see the individual module "howto" page for more information.

Errors

If the 'Ready to process requests` message does not appear, then the debug output will contain error messages clearly describing what went wrong. These error message must be read in order to gain insight as to the source of the problem.

Otherwise, look for messages containing ERROR or WARNING, or the module name. While the server can produce a large volume of messages, most of those can be ignored when debugging a particular problem. Simply search for a few key strings based on the files you changed, and the solution to the problem should be clear.

We recommend running the radiusd -XC test was performed before making any module changes for other reasons. If previous configuration worked, and the only change was to a particular module, then the source of the error is simple. There is no need to go searching through other configuration files or third-party web sites. Instead, change and test the module configuration until the server works.