FreeRADIUS Documentation

Configuring the server can be a complex task. This task is made easier in recent versions, as we gradually improve the documentation and "default" configurations.

You can help! Just edit the wiki. It takes less than five minutes, and it will help thousands of other people

If you are using Version 1 of the server, we suggest upgrading to Version 2. Version 1 is no longer supported. Version 2 is much easier to install and configure.

If you want new features, you should use Version 3. The raddb/ directory has been reorganized to be simpler and clearer. The configuration items now have consistent names, so that it is easier to understand what a configuration item does.

Getting Started

A number of "getting started" guides are available from Network RADIUS. In particular, we recommend the Technical Guide, which should be read by every new RADIUS administrator. It explains RADIUS concepts, and covers how to perform introductory administation and maintenance. More in-depth guides are available on the same page.


Nearly all other documentation and How-To's on third party web sites are wrong and outdated. We strongly suggest that you do not follow any documentation which is more than 4 years old. If you do follow such ancient documentation, the result will likely be a server that does not work.

Installing the Server

Where possible, we recommend using the packaging system that is used by your operating system. The version that is supplied by your OS might be out of date, but it is likely to work "out of the box".

If you need to install it yourself, the Wiki installation page contains detailed instructions for a number of platforms.

Starting the Server

Once it has been installed, the first thing to do is change as little as possible. The default configuration is designed to work everywhere, and to perform nearly every authentication method.


Do not edit the default configuration files until you understand what they do. This means reading the documentation contained in the comments of the configuration files.

Many common configurations are documented as suggestions or examples in the configuration files. Many common problems are discussed in the configuration files, along with suggested solutions.

We recommend reading the configuration files, in large part because most of the configuration items are documented only in the comments in the configuration files.

When the server has been installed on a new machine, the first step is to start it in debugging mode, as user root:

$ radiusd -X

This step demonstrates that the server is installed and configured properly. If you have installed Version 2 from source, this step will also create the default certificates used for EAP authentication.

Initial Tests

Testing authentication is simple. Edit the users file, and add the following line of text at the top, before anything else:

testing Cleartext-Password := "password"

Start the server in debugging mode (radiusd -X), and run radtest from another terminal window:

$ radtest testing password 127.0.0.1 0 testing123

You should see the server respond with an Access-Accept. If it doesn't, the debug log will show why. Paste the output into the debug form, and a colorized HTML version will be produced. Look for red or yellow text, and read the messages.

If you do see an Access-Accept, then congratulations, the following authentication methods now work for the testing user:

PAP, CHAP, MS-CHAPv1, MS-CHAPv2, PEAP, EAP-TTLS, EAP-GTC, EAP-MD5.

The next step is to add more users, and to configure databases. Those steps are outside of the scope of this short web page, but the general method to use is important, and is outlined in the next section.


The following steps outline the best known method for configuring the server. Following them lets you create complex configurations with a minimm of effort. Failure to follow them leads to days of frustration and wasted effort.

Configuring the Server

Changing the server configuration should be done via the following steps:

  1. Start with a "known working" configuration, such as supplied by the default installation.
  2. Make one small change to the configuration files.
  3. Start the server in debugging mode (radiusd -X).
  4. Verify that the results are what you expect
    • The debug output shows any configuration changes you have made.
    • Databases (if used) are connected and operating.
    • Test packets are accepted by the server.
    • The debug output shows that the packets are being processed as you expect.
    • The response packets are contain the attributes you expect to see.
  5. If everything is OK, save a copy of the configuration, go back to step (2), and make another change.
  6. If anything goes wrong,
    • double-check the configuration
    • read the entire debug output, looking for words like error or warning. These messages usually contain descriptions of what went wrong, and suggestions for how it can be fixed. (see also the debug form)
    • Try replace your configuration with a saved copy of a "known working" configuration, and start again. This process can clean up errors caused by temporary edits, or edits that you have forgotten about.
    • Ask for help on the freeradius-users mailing list. Include a description of what you are trying to do, and the entire debugging output, especially output showing the server receiving and processing test packets. You may want to scrub "secret" information from the output before posting it. (Shared secrets, passwords, etc.)

Debugging the Server

This process is the same as configuring the server. See the section above.

Also:


Run the server in debugging mode as suggested in the FAQ, README, INSTALL, man page, and daily on the mailing list.

We cannot emphasize that strongly enough. There is no way for anyone to help you unless you post the debugging output along with your question. If you do not post the debugging output, your question will either be ignored, or you will receive a number of responses saying


Post the debug output as suggested in the FAQ, README, INSTALL, man page, and daily on the mailing list.

A large number of problems can be trivially solved by having an expert read the debug output. If you do not post it to the list, you are making it impossible for anyone to help you.


Other sources of Documentation

Wiki

The Wiki has a fair amount of documentation and How-To's. It is also searchable.

Manual pages

The on-line man pages contain documentation for programs, configuration files, and modules.

Useful How-To's

The web site Deploying RADIUS has a number of useful documents that are kept up to date with newer versions of the server. These documents include:

Older Documents

Novell eDirectory Integration

An administration guide to FreeRADIUS and Novell eDirectory is available. For the latest version of the "Integrating Novell eDirectory with FreeRADIUS" administration guide, refer to http://www.novell.com/documentation/edir_radius/index.html To edit the document, use the XML version of the document at http://www.novell.com/documentation/edir_radius/xml/edir_radius_xml.zip.

If all else fails

If all else fails, commercial support is available.