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 free and open-source implementation of the RADIUS (Remote Authentication Dial In User Service) protocol. It provides centralised authentication, authorisation, and accounting (AAA) support for network access management. FreeRADIUS is a robust, modular, high-performance server that’s deployed in VPNs, Wi-Fi, and enterprise networks.

The default settings are sufficient for a simple install and basic functionality. The software’s flexibility presents challenges when configuring it for advanced or specialized environments. There are many options and customisations for the FreeRADIUS server. Administrators must decide how and what settings to change, which may be complex and problematic.

The FreeRADIUS v4 documentation has been significantly revised compared to version 3. The updated documentation addresses both basic and advanced questions, covering topics such as how the software works, how to configure it, and various use cases. Additionally, the FreeRADIUS team has provided practical examples, developer-focused information, and extra resources to help users better understand and deploy the software. This ensures that users of all experience levels can find the information they need.

Sections in this guide

Why v4?

It’s obvious why a new major release is a good idea. FreeRADIUS v4 was necessary to improve protocol support and enhance security. Using a modernized codebase, a more flexible configuration is available using virtual servers. This change extends the protocol support for DHCP, VMPS, and TACAS+, as they are no longer hardcoded into the server core. Perhaps, a better question is, "Why is v4 taking so long?

Initially, the FreeRADIUS team planned only a minor release of version 3.x. As we examined the codebase, there were many long-standing issues that needed fixing. Because the core team is small, the v4 rework required significant time and effort. The team still released a minor version 3.2 while simultaneously developing version 4. The good news is that, most of the problematic issues are fixed in v4. The FreeRADIUS software is more reliable and easier to use.

Here’s a short list of the most confusing or complicated v3 issues:

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

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

  • Attributes can’t be assigned new values like normal programming languages. 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 terrible and convoluted.

  • 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 standard module failover mechanisms.

  • It’s 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. These issues needed to be fixed, and they have been resolved in v4.

Here is a complete list of issues remaining 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.

As a result of recent improvements, the server has become much simpler to understand and configure. However, there are many more benefits to version 4 as discussed in What’s new in FreeRADIUS v4.

Additionally, the documentation is now structured to help users navigate and find information efficiently. The content is divided into main sections and further broken down into sub-sections with smaller, focused pages. As well, there are links to related topics, making it easier to access relevant details. This hierarchy allows users to find the instructions or guidance they need. For example, all the Howto guides are a series of small steps to guide you through a task.

The unlang policy language is thorough and complete. All configuration files are fully documented along with configuration items such as policies, modules, datastores and virtual servers.

Each keyword and every dynamic expansion function has a dedicated documentation page, making it easy for users to find detailed information about specific features. Additionally, all configuration files are automatically converted to HTML and included in the documentation tree. This approach ensures that users have convenient access to up-to-date and comprehensive reference material for every aspect of the software.

However, some documentation pages may still reference the older version 3 syntax and examples. These outdated pages are clearly labeled, and the FreeRADIUS team is actively working to update them.

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 upgrade 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.

FreeRADIUS version 4 took a long time to incorporate all these changes. We’re confident that the improvements and new features introduced in version 4 make the extended development period worthwhile for users.

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 InkBridge Networks FreeRADIUS experts are available to help you with your software deplyments, configurations, and ongoing support. See Get Help for more information and details.