FreeRADIUS InkBridge

Introduction

This FreeRADIUS version 4 documentation is available under the Creative Commons Non-Commercial license.

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

Please wait for an official release before using version 4 (v4)

FreeRADIUS is a complex piece of software with many configuration options. In most circumstances, the default configuration works with minimal effort to install a server. For more complex requirements, FreeRADIUS can be difficult to setup because of more features and infinite configurations. The question for an administrator, then, is what piece of the configuration to change, and how to change it.

This updated documentation answers your basic and advanced questions about functionality, configuration, and other scenarios. The FreeRADIUS team included examples, developer information, and extra resources to assist you.

These documentation pages have had many updates from version 3. The Unlang policy language is fully documented. There is complete documentation for all configuration files, including all configuration items. However, there may still be some pages which still refer to the old v3 syntax and examples. We will be updating those over time, as we can.

The documentation is organized into main sections, sub-sections with smaller pages, and links to pertinent information. This hierarchy ensures that you can find information easily and extract the instructions you need. For example, all the Howto guides are a series of small steps to guide you through a task. The main sections by subject area and organized by task-based results as follows:

Why v4?

It’s obvious why a new major release is a good idea. Perhaps a better question is "Why is v4 taking so long?"

The original intention was to do a 3.1 release. However, as we dug into the code, we realized that there were a large number of long-standing issues that we would like to solve. As the core FreeRADIUS team is very small, this rework has taken a lot of time.

The good news is that we have fixed pretty much all of the "weird" things which confused people in v3. Here is a short list of the top things are confusing or weird in v3:

  • Access-Request packets were processed though an authorize section. This naming goes back to 2001.

  • Run-time functions (dynamic expansions) had a syntax of %{name: args…​}. The reasons for this are many, but are no longer valid.

  • attributes cannot be assigned new values like normal programming languatges. You have to use an update section.

  • Expressions are not supported. You can’t do foo = 1 + 2. You have to do update { foo = %{expr: 1 + 2} }. This is pretty terrible.

  • Proxying is welded into the server core, which makes it difficult to run policies around proxying.

  • There is a fallback configuration, but this is specific to proxying, and doesn’t use the normal module failover mechanisms

  • It is impossible to send packets as a client, packets can only be proxied. Except for CoA-Request, which has a magic originate-coa functionality.

  • Much of the configuration has special-purpose flags or settings for special cases.

The result is that configuring the server is more difficult than it needs to be. Those issues needed to be fixed.

Here is a complete list of oddities and weirdness in v4, as compared to most programming languages:

  • modules are run in-place. i.e. they act like language keywords on their own.

  • the interpreter tracks return codes for each instruction it runs.

  • function calls use a leading %, e.g. %length('foo').

That’s it.

The result is that the server is much easier to understand and configure. But we’re not done explaining the benefits of v4.

While the documentation in v3 was pretty good, the documentation in v4 is complete. Every single keyword has its own documentation page. Every single dynamic expansion function has its own documentation page. Every single configuration file is automatically converted to HTML and placed into the documentation tree.

Plus, all of the documentation is organized and cross referenced. This means that it is easy to find documentation for anything that the server does, and the documentation explains exactly how that thing works.

The documentation isn’t perfect, of course. We are still working on the How-To documentation. Some of those pages still contain documentation for v3, but they are being actively worked on.

We hope that this discussion explains why v4 took so long. We believe that the result is worth the wait.

What’s new in FreeRADIUS v4

FreeRADIUS v4 is in "alpha" right now. If FreeRADIUS v4 works, continue to use. If you have issues, return to using FreeRADIUS v3.

As of the time of this release, FreeRADIUS:

  • Has the abililty to proxy one packet to several destinations.

  • Can capture a failed proxy, and fall back to local authentication.

  • Server supports many clients with different shared secrets behind one NAT gateway.

  • DHCP and VMPS integrated with full functionality and features.

  • Server supports TACACS+.

  • Connections to databases are asynchronous ensuring stable access, and prevents server lockups.

  • Enums are prefixed with ::, as in Service-Type == ::Framed-User.

    • The server still doesn’t always require (or print) the :: prefix. That will change.

    • By implementing :: for enums, the requirement to use & as a prefix for attribute names is not needed.

    • This change may require an update to all of the configuration. We will try to allow &, but that may not be possible.

  • Dynamic expansions have changed from %{md5:foo} to a more standard syntax of %hash.md5(foo).

    • The new syntax supports multiple comma-separated arguments such as %function(a, b, c).

    • Expansions such as %{User-Name} work in addition to expressions like %{1+2} too.

    • Alternation %{foo || bar} supersedes %{%{foo}:-%{bar}} now.

  • RADIUS/TLS (RadSec) isn’t available.

  • The "haproxy" and "reverse CoA" features aren’t implemented.

Administrators using version 3 that wish to upgrade to version 4 must read the upgrading guide. This guide explains the differences between the two versions and how an existing configuration is reproduced in the latest release. Do not use version 3 configuration files with version 4. These configuration files are not compatible on this major version upgrade.

Don’t open bug reports about previous features as missing. All such bug reports will be closed without comment.

Don’t create 4.0.0-alpha packages for your operating systems or Linux distributions. Creating "alpha" packages results in upset users that install that package. The users believed that the package is stable and they run into issues.

Network Requirements

A RADIUS server requires a network connection with access to UDP ports 1812 for authentication and 1813 for the accounting traffic. These ports must be reachable by network devices like access points or VPN gateways that send authentication requests to the server. All network devices are configured with the appropriate IP address and network settings to facilitate communication with clients on the network.

Operating Systems

The FreeRADIUS protocol works on all Unix based systems. FreeRADIUS doesn’t run natively under Windows.

CPU/RAM/disk space requirements

A FreeRADIUS server has minimal requirements. A FreeRADIUS installation uses 8 MB of RAM, less than 100 MB of disk space, and minimal CPU power. An Internet Service Provider (ISP) with less than 10,000 users have no issues with a basic setup. ISPs with more than 10,000 users, focuses on system design such as more servers and databases.

Datastores

The server reads or writes to any database and both LDAP and SQL can be in the same configuration simultaneously. The database queries are customizable and can be adapted to any custom schema . The server supports fail-over and load balancing across multiple databases. There are no pre-set limits to the number, or type, of databases used.

Debugging

If you have any issues with your server, then restart the server in Debugging mode. Review the logs to determine what the root cause is and make changes. Do only one change at a time and restart your server.

More Information

The RADIUS experts are available to help you with your FreeRADIUS. See Getting Help for more information and details.