Setting up FreeRADIUS for the first time.

After an administrator installs FreeRADIUS for the first time, the big question is "Now what?". Most sites need complex policies, interactions with databases, and logging. Yet the documentation for the server doesn't give detailed instructions for how to configure the server for your particular location. As a result, most adminstrators are left wandering around the configuration files and documentation, wondering what to do next.

We will now give direction to that search. The directions are a few simple rules that should be followed, which will make configuring and debugging the server much simpler. The first rule is:

Rule #1: Don't change anything.

This rule sounds strange at first, because the whole point of installing the server is to change its configuration for the local deployment. However, the default configuration of the server was designed by people with combined decades of experience in RADIUS deployments. It should be changed only with great care and consideration.

That is, the default configuration of the server is set up to work in the widest possible range of situations, with the widest possible range of authentication protocols and networking equipment. Changing that configuration without fully understanding the consequences means it's likely that those changes will break something. This brings us to the second rule:

Rule #2: If you do change anything, use revision control.

It is frustrating to discover that recent changes broke a working configuration, and you can't figure out what changed, or why. Revision control helps track those changes, and lets you "back up" to a previous known working configuration. Therefore, for any new installation of the server, we recommend using the Mercurial revision control tool. Perform the following steps right after the make install (or package install) process.

$ cd /etc/raddb
$ hg init
$ hg add
$ hg commit
    Type a commit message. Almost anything will do.

Then, edit the configuration files to your liking, but do so gradually. Test the configuration frequently, and every time the server does what you want, check in the changes again.

$ hg commit
    Type a commit message describing what was changed, and why.

If at any time the server doesn't work, or doesn't do what you want, there's no problem. Rather than spending a lot of time figuring out what's wrong with the current configuration, it's often easier simply to throw it away, and start from the previous "known working" configuration.

$ hg revert --all

This practice, simple as it is, can make a significant difference in the speed in which you update your configuration. It can also make a significant difference in the confidence you have in your changes. You can change anything in the confidence that if something goes wrong, you can easily and quickly move back to a proven configuration.


Proceed to Step 1: PAP.