The default Virtual Server

All of the configuration for processing RADIUS packets goes here.

It is now possible to have dictionaries which are local to a virtual server. The attributes defined here can be used in policies in this virtual server.

Any attribute defined in this section can only be used in policies in this virtual server. The attributes are "internal", and cannot go into a packet which is sent on the network.

When a request is proxied internally to another virtual server, these attributes are still sent with the proxied request. However, as the definitions do not exist in the other virtual server, they cannot be used in policies.

The other virtual server can even define attributes of the same name. That virtual server will use those definitions for its policies, and will never match the proxied attributes.

In all other aspects, the attributes defined here are just the same as if they had been assigned in a dictionary file.

The syntax is <type> followed by <name>.

The <type> MUST be a leaf type or a group. i.e. not struct, vsa, or vendor.

The <name> MUST NOT exist in the namespace dictionary.

uint32 foo

The contents of the tlv subsection are more variable definitions, including child `tlv`s.

tlv bar { uint32 baz string arg }

The contents of the values section are a list of names and values.

values foo {

<name> = <value>

The <name> must be unique.

The <value> is parsed according to the data type of the attribute.

}

The listen sections in v4 are very different from the `listen sections in v3. The changes were necessary in order to make FreeRADIUS more flexible, and to make the configuration simpler and more consistent.

If there are multiple listen sections in the same virtual server, they need to be given a second name.

Listen sections are identified by virtual server name, then by the namespace, then by transport, finally by a second name.

Multiple types can be accepted by using multiple lines of type = …​.

This change from v3 makes it much clearer what kind of packet is being accepted. The old auth+acct configuration was awkward and potentially confusing.

The allowed transports for RADIUS are currently udp and tcp. A listen section can only have one transport defined. For multiple transports, use multiple listen sections.

You can have a "headless" server by commenting out the "transport" configuration. A "headless" server will process packets from other virtual servers, but will not accept packets from the network.

The inner-tunnel server is an example of a headless server. It accepts packets from the "inner tunnel" portion of PEAP and TTLS. But it does not accept those packets from the network.

require_message_authenticator::Require Message-Authenticator in Access-Requests.

RFC 5080 suggests that all clients should include it in an Access-Request. The configuration item below allows the server to require it. If a client is required to include a Message-Authenticator and it does not, then the packet will be silently discarded.

If value is auto, then if any packet received from the client contains a valid Message-Authenticator attribute, then the server will require it from all future packets from that client.

Allowed values: yes, no, auto

The default is "no".

The blastradius prefix attack allows an attacker to manipulate the contents of response packets without knowing the shared secret.

The attack relies on controlling a portion of the data sent back in the response by the RADIUS server. As Proxy-State is always echoed back verbatim from the request, it can be leveraged to manipulate the data sent back from the server and facilitate the attack.

The attack also relies on defficiencies in the original RADIUS standards that provided no integrity protection for Access-Requests.

The attack is mitigated by requiring the Message-Authenticator, which contains a HMAC over the entire request, preventing modification of the request by the attacker.

If value is auto, and the first packet received from the client does not contain a Proxy-State attribute, Proxy-State will be disallowed in any future packets which do not contain a Message-Authenticator.

This provides some level of protection against the blastradius attack, without requiring Message-Authenticator, or breaking existing deployments.

Allowed values: yes, no, auto

The default is "auto".

The limit section contains configuration items which enforce various limits on the socket. These limits are usually transport-specific.

Limits are used to prevent "run-away" problems.

If dynamic clients are not used, then this configuration item is ignored.

The special value of 0 means "no limit". We do not recommend using 0, as attackers could forge packets from the entire Internet, and cause FreeRADIUS to run out of memory.

This configuration item should be set to the number of individual RADIUS clients (e.g. NAS, AP, etc.) which will be sending packets to FreeRADIUS.

Each connection opens a new socket, so be aware of system file descriptor limitations.

If the listeners do not use connected sockets (e.g. TCP), then this configuration item is ignored.

Useful range of values: 5 to 600

If a dynamic client is disallowed, it is placed onto a "NAK" list for a period of time. This process helps to prevent DoS attacks. When subsequent packets are received from that IP address, they hit the "NAK" cache, and are immediately discarded.

After nak_timeout seconds, the blocked entry will be removed, and the IP will be allowed to try again to define a dynamic client.

Useful range of values: 1 to 600

The reply is normally cached internally for a short period of time, after it is sent to the NAS. The reply packet may be lost in the network, and the NAS will not see it. The NAS will then resend the request, and the server will respond quickly with the cached reply.

If this value is set too low, then duplicate requests from the NAS MAY NOT be detected, and will instead be handled as separate requests.

If this value is set too high, then the server will use more memory for no benefit.

This value can include a decimal number of seconds, e.g. "4.1".

Useful range of values: 2 to 30

The "client" sections can can also be placed here. Unlike v3, they do not need to be wrapped in a "clients" section. They can just co-exist beside the "listen" sections.

Clients listed here will apply to all listeners in this virtual server.

The clients listed here take precedence over the global clients.

The other "client" configuration items can be added here, too.

Take a User-Name, and perform some checks on it, for spaces and other invalid characters. If the User-Name is invalid, reject the request.

See policy.d/filter for the definition of the filter_username policy.

Some broken equipment sends passwords with embedded zeros, i.e. the debug output will show:

User-Password = "password\000\000"

This policy will fix the password to just be "password".

filter_password

If you intend to use CUI and you require that the Operator-Name be set for CUI generation and you want to generate CUI also for your local clients, then uncomment operator-name below and set the operator-name for your clients in clients.conf.

operator-name

Proxying example

The following example will proxy the request if the username ends in example.com.

if (User-Name =~ /@example\.com$/) { control.Auth-Type := "proxy-example.com" }

If you want to generate CUI for some clients that do not send proper CUI requests, then uncomment cui below and set "add_cui = yes" for these clients in clients.conf.

cui

The auth_log module will write all Access-Request packets to a file.

Uncomment the next bit in order to have a log of authentication requests. For more information, see mods-available/detail.log.

auth_log

The chap module will set Auth-Type := ::CHAP if the packet contains a CHAP-Challenge attribute. The module does this only if the Auth-Type attribute has not already been set.

The mschap module will set Auth-Type := ::mschap if the packet contains an MS-CHAP-Challenge attribute. The module does this only if the Auth-Type attribute has not already been set.

The digest module implements the SIP Digest authentication method.

Note that the module does not implement RFC 4590. Instead, it implements an earlier draft of the specification. Since all of the NAS equipment also implements the earlier draft, this limitation is fine.

If you have a Cisco SIP server authenticating against FreeRADIUS, the digest module will set Auth-Type := "Digest" if we are handling a SIP Digest request and the Auth-Type has not already been set.

The eap module takes care of all EAP authentication, including EAP-MD5, EAP-TLS, PEAP and EAP-TTLS.

The module also sets the EAP-Type attribute in the request list, to the incoming EAP type.

The eap module returns ok or updated if it is not yet ready to authenticate the user. The configuration below checks for that return value, and if so, stops processing the current section.

The result is that any LDAP and/or SQL servers will not be queried during the initial set of packets that go back and forth to set up EAP-TTLS or PEAP.

We also recommend doing user lookups in the inner-tunnel virtual server.

The unix module will obtain passwords from /etc/passwd or /etc/shadow. It does this via the system API’s, which are not thread-safe. We do not recommend using the unix module.

unix

Read what used to be the users file. Since v3, this file is located in mods-config/files/authorize.

Look in an SQL database. The schema of the database is meant to mirror the users file.

If you are using /etc/smbpasswd, and are also doing mschap authentication, the uncomment this line, configure the module.

smbpasswd

The ldap module reads passwords and other attributes from an LDAP database.

Enforce daily limits on time spent logged in. This module is a variant of the counter module.

dailycounter

See if the account has expired: check the time in the Expiration attribute and reject if we are past it. If the account has not expired, set Session-Timeout.

The pap module will set Auth-Type := ::PAP if the packet contains a User-Password attribute. The module does this only if the Auth-Type attribute has not already been set.

The pap module is also responsible for "normalizing" the various kinds of "known good" passwords. e.g. Password.NT may come as a 16 byte blob, or as a 32-byte hex string, or as a base-64 encoded string. The pap module will look for common variations of password encoding, and convert them all to a normal form.

This module should be listed last, so that the other modules get a chance to set Auth-Type for themselves.

This section is processed when the server receives a Status-Server packet.

We are still here and responding.

For users who are using PAP authentication. A back-end database listed in the "recv Access-Request" section MUST supply a "known good" password for the user. The password can be clear-text, or encrypted via crypt, bcrypt, or other hashing.

For users who are using CHAP authentication. A back-end database listed in the "recv Access-Request" section MUST supply a Password.Cleartext attribute. Encrypted passwords won’t work.

For users who are using MS-CHAP authentication. A back-end database listed in the "recv Access-Request" section MUST supply either a Password.Cleartext attribute, or a Password.NT attribute. Encrypted passwords won’t work.

For users who are using SIP Digest authentication.

The digest line in the recv Access-Request section should also be uncommented.

Authenticate with PAM (Pluggable Authentication Modules).

We do not recommend using PAM. The server has enough functionality that anything that can be done in PAM can be done easier in FreeRADIUS.

For users who are using PAP, and when you can’t get the "known good" password from LDAP. The module binds to the LDAP directory as the user, along with the password taken from the User-Password attribute. The "bind as user" method means that CHAP, MS-CHAP, and EAP won’t work, as they do not supply a plain-text password.

We do NOT recommend using this. LDAP servers are databases, not authentication servers. It is only here as a last resort for databases such as Active Directory.

We strongly recommend using ldap in the recv Access-Request section. And, ensuring that the account used by FreeRADIUS has read permission on all of the users, groups, and passwords.

For EAP-MD5, EAP-MSCHAP, EAP-TLS, EAP-TTLS, EAP-PEAP, EAP-PWD, etc.

Proxying has changed substantially from v3 to v4. These changes are complex, but were necessary in order to support new features. The result is that configurations which were impossible in v3 are now trivial in v4. For example:

For more information, see: https://www.freeradius.org/documentation/freeradius-server/4.0.0/howto/upgrade/proxy.html

The following example shows how proxying to three remote servers can be configured.

Proxying will be done by setting Auth-Type := example.com, and defining the home servers in mods-available/radius.

If you need to edit the request and/or the reply, you should use the subrequest keyword. See the subrequest documentation for more information.

This section is called when sending an Access-Challenge response. It is configured to filter out all attributes that should not be in the packet.

Once we know that the user has been authenticated successfully, there are additional things that can be done.

If you need to have a State attribute, you can add it here. e.g. for later CoA-Request with State, and Service-Type = ::Authorize-Only.

if (!reply.State) { reply.State := "0x%str.rand(16h)" }

For EAP-TTLS and PEAP, add any cached attributes to the reply. The "session-state" attributes are automatically cached when an Access-Challenge is sent, and retrieved when an Access-Request is received.

The session-state attributes are deleted after an Access-Reject or Access-Accept packet has been sent.

For EAP, ensure that the Access-Accept contains a User-Name attribute.

Get an address from the IP Pool.

sqlippool

Create the CUI value and add the attribute to Access-Accept. Uncomment the line below if returning the CUI to the NAS.

cui

If you want to have a log of authentication replies, uncomment the following line. This is defined in mods-available/detail.log.

reply_log

After authenticating the user, do another SQL query.

Uncomment the following if you want to modify the user’s object in LDAP after a successful login.

ldap

If there is a client certificate (EAP-TLS, and very occasionally PEAP and EAP-TTLS), then some attributes are filled out after the certificate verification has been performed. These fields MAY be available during the authentication, or they may be available only in the appropriate "send" section.

The first set of attributes contains information about the issuing certificate which is being used. The second contains information about the client certificate (if available).

Insert the Class attribute with a unique value into the response, which aids matching auth and acct records and protects against duplicate Acct-Session-Id.

insert_acct_class

MacSEC requires the use of EAP-Key-Name. However, we don’t want to send it for all EAP sessions. Therefore, the EAP modules put required data into the EAP-Session-Id attribute. This attribute is never put into a request or reply packet.

Uncomment the next few lines to copy the required data into the EAP-Key-Name attribute.

Call an instance of linelog to log the authentication success - equivalent to the previous log auth = yes option in v3. See mods-enabled/linelog for message formats and destinations.

log_auth_access_accept

Remove Reply-Message if the response contains an EAP-Message attribute. Some NAS equipment will automatically convert the Reply-Message to an "EAP notification" packet, which will cause end-user machines to drop the network connection.

This section processes Access-Reject packets before they are sent to the NAS.

The session-state list is available while this section is being processed. But all of the attributes in that list are discarded as soon as the section is finished.

Log failed authentications in SQL, too.

Filter out attributes that should not be in Access-Reject packets.

Insert an EAP-Failure message if the request was rejected by policy, instead of from an authentication failure.

Call an instance of linelog to log the authentication failure - equivalent to the previous log auth = yes option in v3. See mods-enabled/linelog for message formats and destinations.

log_auth_access_reject

Remove Reply-Message if the response contains an EAP-Message attribute. Some NAS equipment will automatically convert the Reply-Message to an "EAP notification" packet, which will cause end-user machines to drop the network connection.

Delay sending the Access-Reject packet. This is no longer automatic as it was in version 3.

An Accounting-Request packet has been received. Decide which accounting type to use.

Merge Acct-[Input|Output]-Gigawords and Acct-[Input-Output]-Octets into a single 64-bit counter, Acct-[Input|Output]-Octets64.

acct_counters64

Session start times are implied in RADIUS. The NAS never sends a "start time". Instead, it sends a start packet, possibly with an Acct-Delay-Time, or an Event-Timestamp. The server is supposed to conclude that the start time was "Acct-Delay-Time" seconds in the past.

If there’s no Event-Timestamp, then we create one, using Acct-Delay-Time as an offset if it exists. BUT we only do this if Acct-Delay-Time exists, and has a reasonable value.

Ensure that we have a semi-unique identifier for every request, as many NAS boxes are broken.

Read the 'accounting' file.

Version 4 allows for sections specific to Acct-Status-Type.

Once the recv Accounting-Request section is processed, one of the accounting …​ { …​ } sections will be run, based on the value of the Acct-Status-Type attribute.

After the accounting …​ { …​ } section has been run, it will then process the send Accounting-Response section

Log traffic to an SQL database.

See "Accounting Queries" in mods-available/sql.

Refresh leases when we see a start.

Ensure that control.IP-Pool.Name is set to determine which pool of IPs are used. Set this in recv Accounting-Request so it is available for all the accounting sections.

sqlippool

Log traffic to an SQL database.

If you receive stop packets with zero session length, they will NOT be logged in the database. The SQL module will print a message (only in debugging mode), and will return "noop".

You can ignore these packets by uncommenting the following three lines. Otherwise, the server will not respond to the accounting request, and the NAS will retransmit.

Return an address to the IP Pool when we see a stop record.

sqlippool

Log traffic to an SQL database.

Refresh leases when we see an alive.

sqlippool

Record that the NAS has booted to an SQL database

Return all addresses related to this NAS to the IP Pool

sqlippool

Record that the NAS is shutting down to an SQL database

Return all addresses related to this NAS to the IP Pool

sqlippool

There are many other values for Acct-Status-Type such as:

Some vendors also define their own values, which is a very bad idea.

Log the accounting data before replying. If logging fails then the reply will not be sent, which means the NAS will send the request again.

Add the CUI attribute from the corresponding Access-Accept to the Accounting-Response.

Use it only if your NAS boxes do not support CUI themselves.

cui

Create a 'detail’ed log of the packets. Note that accounting requests which are proxied are also logged in the detail file.

Update counters for daily usage calculations.

daily

Cisco VoIP specific bulk accounting.

pgsql-voip

Filter attributes from the accounting response.