Upgrading from v3 to v4

When upgrading, please start with the default configuration of v4. Then, move your v3 configuration over, one module at a time. Check this file for differences in module configuration, and update the module to use the new configuration. Start the server after every change via radiusd -XC to see if the configuration is OK. Then, convert the listen sections, followed by the server sections.

Take your time. It is better to make small incremental progress, than to make massive changes, and then to spend weeks debugging it. Use a revision control system such as git to save and track your changes. If the changes work as you expect, do git commit, and continue with the next change. If the changes do not work, either keep at it, or move to a different portion of the configuration

All of the attribute names used in v3 have been changed in v4. Please see the attribute names document for more information. This change was necessary in order to support the new "grouped" attributes, which are required for DHCPv6 and other protocols.

If you are upgrading from v2 you should read the v3 version of this file. It describes changed from v2 to v3. This file describes only the changes from v3 to v4.

The instantiate section has been removed. It originally started out as a way to ensure that modules were instantiated in a particular order. A later use of the instantiate section was to define "virtual modules" for dynamic expansion. That functionality has been moved to the mods-available/ and mods-enabled/ directories. i.e. in version 4, just list the virtual module in a file, as if it was a real module.

See the redundant_sql module for more information. In short, a virtual module can be put into the mods-enabled directory as with any other module, as with the following text:

In this case, this definition creates a redundant_sql virtual module.

The listen sections have changed. There is now a type entry, which lists the packet type by their correct name (e.g._`Access-Request` instead of auth). To accept multiple kinds of packets, just list type multiple times:

Each listen section also has a transport entry. This configuration can be left out for headless servers, such as inner-tunnel. For example, setting UDP transport is done via:

Each type of transport has its configuration stored in a subsection named for that transport:

For udp, the configuration entries are largely the same as for v3. e.g. ipaddr, port, etc.

The listen section then compiles each Processing Section based on the named packet types. It has a recv section for receiving packets, and a send section for sending packets, as seen in the following example:

This configuration is different from v3. The benefit of the change is that it is much easier to understand. Instead of using confusing names such as Post-Auth-Type Reject, the server now just uses send Access-Reject.

See also Processing Section for how the unlang statements are parsed.

The server supports global clients in the clients.conf file, as with v3.

Client can also be defined in a client subsection of a virtual server. Unlike v3, there is no need to have a clients section which "wraps" one or more client definitions. See sites-available/default for examples.

The server also supports dynamic clients. See sites-available/dynamic_clients for a worked example. There are many changes from v3. First, there is no need to have a client definition which contains a network. Instead, there is a network section which has a number of allow and deny rules. Second, dynamic clients can be defined on a per-connection basis. Finally, the sites-available/dynamic_clients virtual server has full access to the entire RADIUS packet.

The result of these changes is that it is now possible to have multiple clients behind a NAT gateway, and to have different shared secrets for each client. e.g._by keying off of the NAS-Identifier attribute.

The dynamic client functionality behaves the same for all protocols supported by the server. e.g. RADIUS, DHCP, VMPS, TACACS+, etc.

A major difference between v3 and v4 is that update sections are no longer necessary. It is now possible to just edit attributes "in place", as with:

See the update documentation for a description of what has changed, and how to use the attribute new edit functionality.

For example, instead of doing this:

You can now do this:

As with any upgrade across major version numbers, there are caveats. See the full update documentation and edit documentation for details.

The home_server configuration has been replaced with the radius module. See raddb/mods-available/radius for examples and documentation.

The home_server_pool configuration has been replaced with standard unlang configurations. The various load-balancing options can be re-created using in-place unlang configuration.

The mappings for type are as follows:

While the Load-Balance-Key was a special attribute in v3, it has no special meaning in v4. You can use any attribute or string expansion as part of the load-balance key.

In v3, it was impossible to proxy the same request to multiple destinations. This is now trivial. In any processing section, do:

When processing reaches that point, it will proxy the request to home_server_1, followed by home_server_2.

This functionality can be used to send Accounting-Request packets to multiple destinations.

You can also catch failed proxying, and do something else. In the example below, try to proxy to home_server_1, if that fails, just accept the request.

The sites-available/originate-coa virtual server has been updated to use the new subrequest feature. Please see that virtual server, and the subrequest keyword for details.

The old-style "tagged" RADIUS format has been removed. Instead of using

you should use

It is also possible to "group" tagged attributes together, as in the following example:

There are 31 such attributes, Tag-1 through Tag-31. There is no Tag-0 attribute, as it is not needed.

After much investigation, it was unfortunately impossible to continue supporting the Attribute-Name:tag syntax for tagged attributes. This change requires modifications to all configuration files and databases which use tags. This change means also that detail files from v3 are not readable by v4.

The old-style request: and reply: syntax for lists has been deprecated. Please use request. and reply. instead.

Many lists have been removed. e.g._`proxy`, proxy-reply, coa, coa-reply, disconnect, and disconnect-reply. The underlying functionality still exists, but it has been moved to different keywords, such as subrequest.

We recommend manually converting the update sections to the new method. The biggest change that confuses people is the old += operator does not work the same way as before.

Instead of doing:

you should edit the reply list, using the += operator:

We also recommend removing double-quotes from xlat expansions where possible. The temptation in v3 is to just add double quotes to everything, and hope it all works out. This is no longer necessary in v4.

For example, in v3 you would do:

In v4, you can remove the update, and rewrite the SQL call to:

Using double quotes everywhere means that every bit of data gets converted to printable strings, and then back to it’s real data type (ipaddr in the above example). Removing the double quotes means that there is less work going on, which means higher performance.

%{integer:…​} has been removed. Just use a cast, such as (integer) &Service-Type.

%{expr:…​} has been removed. You can instead use in-place expressions, such as %{1 + 2} or %{&NAS-Port + 14}.

This module handles the %{client:..} xlat expansions.

The Client-Shortname attribute has been removed. You should use %client(shortname) instead.

The radius module has taken over much of the functionality of proxy.conf. See raddb/mods-available/radius for documentation and configuration examples.

The radius module connects to one home server, just like the home_server configuration in v3. Some of the configuration items are similar to the home_server configuration, but not all.

The module can send multiple packet types to one home server. e.g. Access-Request and Accounting-Request.

This module also replaces the old coa and originate-coa configuration. See also subrequest for creating child requests that are different from the parent requests.

Unlike v3, the module can do asynchronous proxying. That is, proxying where the server controls the retransmission behavior. In v3, the server retransmitted proxied packets only when it received a retransmission from the NAS. That behavior is good, but there are times where retransmitting packets at the proxy is better.

&control.Cache-Merge has been renamed to &control.Cache-Merge-New and controls whether new entries are merged into the current request. It defaults to no. The primary use case, is if you’re using xlat expansions in the cache module itself to retrieve information for caching, and need the result of those expensions to be available immediately.

Two new control attributes &control.Cache-Allow-Merge and &control.Cache-Allow-Insert have been added. These control whether existing entries are to be merged, and new entries created on the next call to a cache module instance. Both default to yes.

All certificate attributes are available in the &session-state. list, immediately after they are parsed from their ASN1 form.

The certificates are no longer added to the &request. list. Instead, they are added to the session-state list. You are advised to update any references during the upgrade to 4.0:

The rlm_eap_ikev2 module was removed. It does not follow RFC 5106, and no one was maintaining it.

The rlm_eap_tnc module was removed. No one was using or maintaining it.

The in-memory SSL cache was removed. Changes in OpenSSL and FreeRADIUS made it difficult to continue using the OpenSSL implementation of a cache. See raddb/sites-available/tls-cache for a better replacement. The OpenSSL cache can now be placed on disk, in memory, in memcache, or in a redis cache. The result is both higher performance, and more configurable.

The use_tunneled_reply and copy_request_to_tunnel configuration items have been removed. Their functionality has been replaced with the use_tunneled_reply and copy_request_to_tunnel policies. See raddb/sites-available/inner-tunnel and raddb/policy.d/eap for more information.

These configuration items were removed because they caused issues for a number of users, and they made the code substantially more complicated. Experience shows that having configurable policies in unlang is preferable to having them hard-coded in C.

The virtual_server configuration has been removed from EAP-PWD. The module now looks for &request.control.Password.Cleartext.

The LEAP protocol has been removed from the server. It is insecure, non-standard, and should not be used.

Exec-Program and Exec-Program-Wait have been removed.

The packet_type configuration has been removed. Use unlang checks to see if you want to execute the module.

The expr module is no longer necessary and has been removed.

The xlat expansions just support math natively. For example:

will return the string 1 + 2 = 3. The contents of the expansion can be any math or condition. Attribute assignments in expansions are not supported.

The expiration module has been replaced with an unlang policy. The policy is located in raddb/policy.d/time. The Expiration attribute should continue to work the same as with v3.

The ldap module provides an expansion %ldap.memberof(<name>) instead of LDAP-Group for dynamically testing group membership. The old method of

will no longer work. Instead, use

The cacheing of group membership into attributes in the control list is still available, so

can also be used to test membership after having called the ldap module, if cacheable_name or cacheable_dn are enabled.

The winbind_* configuration options are now in a winbind subsection. See mods-available/mschap for details.

Attributes of type octets are now passed directly to Perl as binary data, instead of as hex strings.

All data received from the network is marked tainted by default.

The case_sensitive option has been removed. Administrators should not be permitting users to log in with multiple different user names. If your system needs to be case insensitive, we suggest changing all names to lowercase:

REST-HTTP-Code is now inserted into the &request. list instead of the &reply. list, to be compliant with the list usage guidelines.

Driver-specific options have moved from mods-available/sql to mods-config/sql/driver/<drivername>.

If caching is enabled, the SQL-Group attribute is cached in the control list after the module has run. This means it is possible to do regular expression comparison on group names.

It also means that any comparison of &SQL-Group == "foo" has to be updated to use &control.SQL-Group == "foo" instead.

This caching also means that the group comparison will be done internally, and will not result in a database lookup. This also means that it is now possible to do group comparisons based on regular expressions.

It is possible to force a dynamic group lookup via the expansion %sql.group(foo). This expansion returns true if the user is a member of that SQL group, and false otherwise.

will return true.

Attribute references:

Just adding the & prefix to the attribute name is not sufficient. Attributes must be qualified with the list to search in, or add to.

This allows significantly greater flexibility, and better integration with newer features in the server such as CoA, where reply_name can now be &coa:Session-Timeout. That allows the server to send a CoA packet which updates the Session-Timeout for the user.

In v4, when the key field was set to User-Name, the module would also look for Stripped-User-Name as the key. In v4, this functionality has been moved to the configuration. To get the same functionality, the key should now be specified as a dynamic expansion:

The count_attribute has been removed, as it is no longer necessary.

The old expansions %%b and %%e have been removed. This should only affect people who are editing the queries manually. See the file mods-availble/sqlcounter for more information.

The attribute comparison has been removed. It is no longer possible to check Daily-Session-Time > 4 everywhere. Instead, the attribute exists only after the sqlcounter module has been run.

Instead, use attribute-name. See mods-available/sqlippool for more information.

The unix module uses an expansion %unix.group(<name>) instead of Unix-Group, Group or Group-Name. The old method of doing

will no longer work.

The winbind module uses an expansion %(winbind.group(<name>) instead of Winbind-Group == <name>.

Instead of using this, please use the sqlcounter module with sqlite.

It is difficult to maintain multiple implementations of the same functionality. As a result, we have simplified the server by removing duplicate functionality.

Instead of using this, please use the sql_ippool module with sqlite.

It is difficult to maintain multiple implementations of the same functionality. As a result, we have simplified the server by removing duplicate functionality.