Radius Module

In most cases, the v3 configuration be moved to v4 without too many problems. For each home_server foo { …​ } in v3, create a v4 module `radius foo { …​ } `. Copy over the IP address, port, and secret configuration items. When this step is finished, the bulk of the basic work is done.

Converting a home_server_pool foo { …​ } can be done by creating a module in mods-enabled, either load-balance foo { …​ }, or redundant foo { …​ }. i.e. the v3 module configuration does not have any instantiate section. You can just list "virtual" modules directly in the modules directory!

The contents of the load-balance or redundant section will be the list of home servers which will part of that load-balance or redundant pool.

Then, anywhere you want to use a home server, just list it’s name in an unlang processing section. Anywhere you want to list a home server pool, just list it’s name in an unlang processing section.

Unlike v3, there is no Proxy-To-Realm attribute, or Home-Server-Pool, or Home-Server-Name. Instead, you just configure a module (radius, or load-balance), and then use the module anywhere you want to proxy packets.

In most cases, you can just set something like Auth-Type := example.com, and then have a section authenticate example.com { …​ }, which contains the radius modules which do proxying. See sites-available/default for sample configuration which uses this pattern.

The module adds a Proxy-State attribute to all proxied packets. This Proxy-State contains a 32-bit random number, which is unique to this module. This unique number helps to detect proxy loops.

The reply from home server is appended to the reply list for the current packet.

Any proxied packet (including Accounting-Request) can receive a Protocol-Error response packet. This packet is an explicit NAK that something went wrong processing the request.

Unlike v3, the server does not support any "pre-proxy" or "post-proxy" processing sections. Similarly, this module does not support any "proxy" or "proxy-reply" list. Instead, the current request is proxied as-is, and the proxied reply is added to the current reply list. If you want to modify the proxied request and/or proxied reply, then you should use a subrequest block to create a child request. That child request can then be modified independently of the parent. Any reply attributes will have to be copied back manually to the parent request.

The configuration settings of this module are similar to the home_server settings in v3.

The module has the following return codes:

proxy - forward packets which are received from a NAS - each packet has a Proxy-State attribute added. - it looks for, and stops proxy loops - retransmissions are sent only when the NAS retransmits - the module fails if it does not receive a reply

client - originate packet, and do retransmissions ourselves - no Proxy-State is added. - the module retransmits as needed - the module fails if it does not receive a reply

replicate - send packets without waiting for a reply. - no Proxy-State is added - the module does not expect any reply - all replies are discarded - the module continues with "ok" immediately after sending the packet.

unconnected-replicate - replicate packets to dynamic destinations - For unconnected UDP sockets only. - It MUST have transport = udp - It MUST have src_ipaddr = * and no src_port - You CANNOT use the module "in place" as with normal proxying. - It is only supported via the function %replicate.sendto.ipaddr(ipaddr, port, secret)

dynamic-proxy - proxy packets to dynamic destinations - RFC 7585 dynamic DNS lookups are not supported - It MUST have src_ipaddr = * and no src_port - You CANNOT use the module "in place" as with normal proxying. - Proxying is only supported via the function %proxy.sendto.ipaddr(ipaddr, port, secret)

The server can still be used to create (i.e. originate) packets via this module when mode = proxy is set. The module can automatically detect the difference between proxied packets and client packets it originates. Originated packets are taken from the detail file, or result when changing packet type (e.g. Accounting-Request to Disconnect-Request), or when the current request is a subrequest, and the parent request is from a different protocol.

Note that there is no mode = unconnected, where the module then both proxies packets, and replicates them. The need to track replies when proxying means that it’s difficult to both proxy and replicate at the same time. As a result, there are two "unconnected" modes, one for each of "proxy" and "replicate".

Default is 255.

The module will only send packets types which are listed here. Other types of packets will be ignored. The main purpose of the type configuration is to ensure that the correct packets are being sent to the home server. This entry serves as a double-check against misconfigurations.

In v3, the home_server configuration of auth, acct, or auth+acct is used to find a home server. That is, when FreeRADIUS has an Access-Request packet in v3, it proxies it by looking up a matching home_server.

In v4, proxying is done by listing the radius module in a processing section, such as authenticate radius { …​ }, or recv Accounting-Request { …​ }. So unlike v3, the module doesn’t have to find a proxy destination for a particular kind of packet. Instead, the administrator configures the module to send packets to a destination.

As a result, the module doesn’t really care about what kind of packets it sends. It has a packet, a destination where that packet should be sent, and it sends the packet.

In order to change packet types, see the subrequest keyword.

Unlike v3, all packet types are allocated from the same 8-bit ID space. This change does not affect the majority of RADIUS proxying, which only sends one type of packet. This change does not affect the home server which receives these packets, as the home server does not track IDs except to correlate requests to replies.

The only visible difference, then, between v3 and v4 is that in some cases, the new radius module will use more source ports when proxying.

This change simplifies the implementation of the RADIUS client.

require_message_authenticator::Require Message-Authenticator in responses.

A server should include Message-Authenticator attribute as the first attribute in responses to Access-Request packets. This behavior mitigates against the BlastRADIUS attack.

However, not all servers follow this security practice. As a result, this module can be configured to either not require, or require, Message-Authenticator.

If value is auto, then the module will automatically detect the existence of Message-Authenticator in response packets. Once the module sees a Message-Authenticator, it will automatically change the configuration internally to yes. This change prevents security "down-bidding" attacks.

Allowed values: yes, no, auto

The default is auto.

When zombie_period starts, a connection is marked zombie, and then is not used to send new packets. If there are no responses on this connection within zombie_period, the module either closes the connection (no status_check subsection), or starts pinging the home server (status_check.type = Status-Server).

Some home servers do not support status checks via the Status-Server packet. Others may not have a "test" user configured that can be used to query the server, to see if it is alive. For those servers, we have NO WAY of knowing when it becomes alive again. Therefore, after the server has been marked dead, we wait a period of time, and mark it alive again, in the hope that it has come back to life.

If it has NOT come back to life, then the module will wait for zombie_period before marking it dead again. During the zombie_period, ALL AUTHENTICATIONS WILL FAIL, because the home server is still dead. There is NOTHING that can be done about this, other than to enable the status checks, as documented above.

e.g. if zombie_period is 40 seconds, and revive_interval is 300 seconds, the for 40 seconds out of every 340, or about 10% of the time, all authentications will fail.

If the zombie_period and revive_interval configurations are set smaller, than it is possible for up to 50% of authentications to fail.

As a result, we recommend enabling status checks, and we do NOT recommend using revive_interval.

The revive_interval configuration is used ONLY if the status_check subsection is not used. Otherwise, revive_interval is not necessary, and should be deleted.

Useful range of values: 10 to 3600

The module supports multiple transport protocols.

Each worker thread (see radiusd.conf, num_workers), has it’s own set of connections. These connections are grouped together into a "pool".

Much of the configuration here is similar to the old connection "pool" configuration in v3. However, there are more configuration parameters, and therefore more control over the behavior.

If the server cannot create specified number of connections during instantiation it will exit.

Set to 0 to allow the server to start without the database being available.

If these connections are all in use and a new one is requested, the request will NOT get a connection.

If a home server goes down, the module will close old / broken connections, and try to open new ones. In order to avoid flooding the home server with connection attempts, set the connecting value to a small number.

After uses packets have been sent the connection will be closed, and a new one opened. For no limits, set uses = 0.

After lifetime seconds have passed, no new packets will be sent on the connection. When all replies have been received, the connection will be closed.

For no limits, set lifetime = 0.

It is possible to use precise times, such as lifetime = 1.023, or even qualifiers such as lifetime = 400ms.

Parsing of this field is the same as for lifetime.

There can be a balance between overloading a connection, and under-utilizing it. The default is to fill each connection before opening a new one.

Each packet can have its own retransmission timers.

The sections are named for each packet type. The contents are the same for all packet types.

The module supports replication of packets to new destinations at run time. In this context, replication means "send the packet, and do not wait for the response". This functionality is most useful when copying large amounts of accounting data to multiple destinations.

The module can then only be used as a dynamic expansion. That is, you cannot specify the replicate module directly in a processing section.

This module supports dynamic proxying via a run-time function:

The first part of the function name (e.g. proxy) is taken from the module name. The rest is fixed as sendto.ipaddr()

The arguments to the function are:

The function will return the type of response packet if it receives as a response, or else the function all will fail.

The packet name must be a quoted string.

The proxying is done asynchronously. i.e. the packet is sent, and the server goes on to do other work. At some point in the future, a response is received, the module processes it, and the server continues.

The timeouts are controlled as described above.

The mode.

Both UDP and TCP are supported.

Timeouts for proxying are controlled in sections named for the packet type. See the examples above for full documentation.

See above for documentation on connection trunking.

If the server cannot create specified number of connections during instantiation it will exit.

Set to 0 to allow the server to start without the database being available.

If these connections are all in use and a new one is requested, the request will NOT get a connection.

If a home server goes down, the module will close old / broken connections, and try to open new ones. In order to avoid flooding the home server with connection attempts, set the connecting value to a small number.

After uses packets have been sent the connection will be closed, and a new one opened. For no limits, set uses = 0.

After lifetime seconds have passed, no new packets will be sent on the connection. When all replies have been received, the connection will be closed.

For no limits, set lifetime = 0.

It is possible to use precise times, such as lifetime = 1.023, or even qualifiers such as lifetime = 400ms.

Parsing of this field is the same as for lifetime.

There can be a balance between overloading a connection, and under-utilizing it. The default is to fill each connection before opening a new one.

The proxy policy overrides enables functionality similar to the version 3 pre/post-proxy sections.

Create a subrequest which we can edit. When the subrequest section is done,

Initialize the proxied packet from the request.

This is the "pre-proxy" section.

Run the "radius proxy" module noted above.

Edit the reply from the home server here.

This is the "post-proxy" section.

Note that the Proxy-State attributes have already been deleted from the reply, so you don’t need to do that here. Those attributes are not needed by anyone for anything, and confuse things if they’re copied to the original request. The radius module therefore deletes them, to make your life easier.

Like v3, remove all pre-existing attributes in the original reply, and replace them with the reply from the home server.

It is also possible to copy over some, or none of the attributes in the reply from the home server. The configuration here is just an example, and can be edited.