Getting started with FreeRADIUS for the first time

I've installed it. Now what?

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, many administrators are left wandering around the configuration files and documentation, wondering what to do next.

Naturally, your final configuration will depend on your unique network architecture and components. However, before you start, make sure to follow these two simple rules which will make configuring and debugging the server much simpler. These rules will also reduce the feeling of being overwhelmed with options. The rules come in handy when configuring anything, but because of the highly customizable nature of FreeRADIUS, they are especially important here.

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 only be changed with 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. The changes you make might not break the thing you’re trying to configure. They might break something else. And you might not notice until much later. Debugging those kind of problems can be a nightmare.

This brings us to the second rule:

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

It can be 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 here. "first commit" is fine.

We recommend Mercurial here because if you’re unfamiliar with revision control systems, it can be easier to use than Git. But in truth, any revision control system will work.

Then, edit the configuration files to your liking, but do so gradually. Test the configuration frequently, and every time the tests pass, 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 away the broken configuration, and restart from the previous “known working” one.

$ hg revert --all

This process also helps for debugging changes to production systems. If a production system stops working after an update, you can simply revert to a known working configuration. The production systems will immediately start working properly, and you can debug the problems in a lab system, at your leisure.

i.e. The last thing you want to do is to debug complex changes in production, while the systems are down, and while you have 100,000 angry users calling support!

The bottom line

Don’t be deceived by the apparent simplicity of these rules. Like any fundamental best practice, following them will have a huge, positive, impact on your success.

Even expert practitioners (especially expert practitioners!) follow simple fundamental rules. Surgeons use checklists to make sure they didn’t forget anything inside a patient, woodworkers “measure twice, cut once”, scuba divers and rock climbers do a “buddy check” before diving in the water or starting a climb. These methods work, and you can benefit enormously by using them.

Likewise, successful system administrators should follow these two rules:
1) Don't change anything
2) If you do, use revision control

This practice, simple as it is, will make a significant difference in the speed with 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.

Next steps

Now that we’ve laid a basic foundation for you, we can dive into some more detail.

Usually, the best next step is to configure PAP (clear-text passwords). While PAP is not likely to be be your final implementation, it is the most straightforward to configure and will help you understand how all the elements of FreeRADIUS work together.

We walk through how to set up PAP configuration in this article.

Need more help?

Network RADIUS has been helping clients around the world design and deploy their RADIUS infrastructure for 20 years. We specialize in complex systems and have seen pretty much every variation and problem out there. If you want help from the people who wrote FreeRADIUS, contact us for a customized quote.


Getting started with FreeRADIUS

FreeRADIUS and Active Directory

EAP configuration articles

Additional resources