Introduction

VERSION 4 IS IN DEVELOPMENT AND HAS NOT BEEN OFFICIALLY RELEASED. USE AT YOUR OWN RISK.

The configuration may change. The behavior may change. The documentation may change.

Please wait for an official release before using version 4.

This is the documentation for FreeRADIUS, version 4. The documentation is available under the Creative Commons Non-Commercial license, as given in the LICENSE file in this directory.

FreeRADIUS is a complex piece of software with many configuration options. However, we have taken great care to make the default configuration work in most circumstances. The result is that for most simple systems, it is trivial to install and configure the server. For those situations, this documentation will serve to answer basic questions about functionality, configuration, etc.

For more complex requirements, FreeRADIUS can be difficult to configure. The reason for this difficulty is that the server can do almost anything, which means that there are a near-infinite number of ways to configure it. The question for an administrator, then, is what piece of the configuration to change, and how to change it.

This documentation will answer those questions. The FreeRADIUS team has put substantial effort into writing the documentation for this release. Everything in the server is fully documented, and there are many how-to guides available.

The documentation is split into sections by subject area, oganized by desired outcome. At a high level, the subject areas describe:

Concepts and introduction for newcomers.
Installing and upgrading FreeRADIUS.
The syntax of the unlang processing language.
The configuration files located in /etc/raddb/, or /etc/freeradius/
Various how-to guides.
Developer documentation.

This organization means that for example, the ldap module will have documentation located in multiple places. We feel that organizing the documentation by desired goal is better than the alternatives.

Within each section, the documentation is split into small pages, which are generally no more than a few screens worth of information. We feel that having multiple small pages with cross-links is more helpful than having a smaller number of enormous pages. This division ensures that (for example) the how-to guides are split into a series of small steps, each of which can be performed quickly.

We hope that this extended documentation will address any lingering concerns about the quality of the FreeRADIUS documentation.

Current Limitations of 4.0.0

As of the time of writing this documentation, the server has the following limitations:

RADIUS/TLS (RadSec) is not implemented.
TTLS, PEAP, TEAP, and EAP-FAST are not implemented.
The "haproxy" and "reverse CoA' features are not implemented
The Perl, Python, and Lua modules do not fully support the v4 "nested" attributes.
Enums are now prefixed with ::, as in Service-Type == ::Framed-User.
The server still does not always require (or print) the :: prefix. That will change.
As a result of adding :: for enums, we can then remove the requirement to use & as a prefix for attribute names.
This change may require changes to all of the configuration. We will try to allow & or not, but that may not be possible.
Dynamic expansions have changed from %{md5:foo} to %md5(foo).
The new syntax is much clearer, and supports multiple comma-separated arguments: %function(a, b, c)
Expansions such as %{User-Name} will still work. We plan on making %{1+2} work, too.
Alternation %{%{foo}:-%{bar}} has been replaced by %{&foo || &bar}, which is clearer and uses less nesting.

Please be aware that v4 is in "alpha" right now. If it works, great. If it doesn’t work, then please return to using v3.

Please do not open bug reports about those features being missing. All such bug reports will be closed without comment.

We do not recommend that operating systems or Linux distributions create their own packages for 4.0.0-alpha. Our experience has been that packaging "alpha" releases results in confused and upset users. People will install it due to the belief that "it’s stable because it is packaged". They will then run into issues, and will blame us.

Such behavior is antisocial and is strongly discouraged.

Changes From Earlier Versions

In previous releases, FreeRADIUS had the following limitations:

it was impossible to proxy one packet to multiple destinations
it was impossible to catch a failed proxy, and fall back to local authentication
the server could not support multiple clients with different shared secrets behind one NAT gateway
the DHCP and VMPS was implemented by making them pretend to be RADIUS, which limited their functionality
the server did not support TACACS+
connections to databases were synchronous. If a database blocked, it could eventually lock up the server

All of these limitations and more have been removed. The downside of these changes is that the some of the configuration has been changed.

Administrators who have version 3 and wish to upgrade to version 4 should read the upgrading documentation. That documentation explains the differences between the two versions, and how an existing configuration can be reproduced in the latest release. We do not recommend using version 3 configuration files with version 4. The configuration files are not compatible across a major version upgrade.

Getting Started with FreeRADIUS

FreeRADIUS can be installed using the pre-built packages available from Network RADIUS. That page contains packages for all common OS distributions. New packages are available as soon as a new version has been released. Packages for older releases are also available for historical purposes.

FreeRADIUS can also be installed from the source code. Please see the installation guide for instructions.

Many Operating System distributions ship versions of FreeRADIUS which are years out of date. Those versions may contain bugs which have been fixed in newer releases. We recommend using the Network RADIUS packages where possible.

Administrators who are new to FreeRADIUS should read the concepts section as it describes the concepts behind FreeRADIUS. It is vital for newcomers to understand these concepts, as the rest of the documentation assumes familiarity with them.

A detailed unlang reference guide is also available. This section describes the syntax and functionality of the keywords, data types, etc. used in the unlang processing language.

All of the configuration files are available in hypertext format. It can often be easier to read the configuration files in a nicely formatted version, instead of as a fixed-width font in a text editor.

For specific problem solving, we recommend the how-to guides. These guides give instructions for reaching high-level goals, or for configuring and testing individual modules.

There is also developer documentation. This section documents the APIs for developers. Most people can ignore it.

Debugging

If you have ANY problems, concerns, or surprises when running the server, the the server should be run in debugging mode as root, from the command line:

# radiusd -X

It will produce a large number of messages. The answers to many questions, and the solution to many problems, can usually be found in these messages. When run in a terminal window, error messages will be shown in red text, and warning messages will be shown in yellow text.

For other use-cases, please look for ERROR or WARNING in the debug output. In many cases, those messages describe exactly what is going wrong, and how to fix it.

For further details, about the debug output see the radiusd-X page on the wiki.

Getting Help

We also recommend joining the mailing list in order to ask questions and receive answers. The developers are not on Stack Overflow, IRC, or other web sites. While the FreeRADIUS source is available on GitHub, questions posted there will not be answered.

Before posting to the list, please read the list help page. That page explains how to run the server in debugging mode; how to understand the debug output; and what information to post to the list.

Commercial support for FreeRADIUS is available from Network RADIUS.