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.

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

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

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

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.

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:

This policy will fix the password to just be "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.

Proxying example

The following example will proxy the request if the username ends in 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.

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.

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 wimax module fixes up various WiMAX-specific stupidities.

The WiMAX specification says that the Calling-Station-Id is 6 octets of the MAC. This definition conflicts with RFC 3580, and all common RADIUS practices. Uncommenting the wimax module here allows the module to change the Calling-Station-Id attribute to the normal format as specified in RFC 3580 Section 3.21.

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

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. For a full description of the module behavior, please see https://wiki.freeradius.org/modules/Rlm_sql

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

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

For a full description of the module behavior, please see https://wiki.freeradius.org/modules/Rlm_ldap

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

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.

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.

EAP Authentication

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://wiki.freeradius.org/upgrading/version4/proxy.

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

The Auth-Type attribute would need to be set to proxy-example.com. The home servers MUST be defined in mods-available/radius.

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.

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.

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

If you want to have a log of authentication replies, uncomment the following line. This is defined in mods-available/detail.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.

Calculate the various WiMAX keys. In order for this to work, you will need to define the WiMAX NAI, usually via:

If you want various keys to be calculated, you will need to update the reply with "template" values. The module will see this, and replace the template values with the correct ones taken from the cryptographic calculations, e.g.

You may want to delete the MS-MPPE-*-Keys from the reply, as some WiMAX clients behave badly when those attributes are included. See the configuration entry delete_mppe_keys in mods-available/wimax for more information.

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.

Note: This only works if the NAS has implemented RFC 2865 behaviour for the Class attribute, AND if the NAS supports long Class attributes. Many older or cheap NASes only support 16-octet Class attributes.

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.

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.

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.

Accounting

This section deals with receiving Accounting requests and sending Accounting responses.

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.

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. The server is supposed to conclude that the start time was "Acct-Delay-Time" seconds in the past.

The unlang below creates an explicit start time, which can then be used in other modules. It will be mostly correct. Any errors are due to the 1-second resolution of RADIUS, and the possibility that the time on the NAS may be off.

The start time is: NOW - delay - session_length

The packet should have a timestamp. If not, use "now" from the server.

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

Session start

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.

Session stop

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.

Session is still alive

Log traffic to an SQL database.

Refresh leases when we see an alive.

The NAS has just booted up.

Record that the NAS has booted to an SQL database

Return all addresses related to this NAS to the IP Pool

The NAS is about to go down

Record that the NAS is shutting down to an SQL database

Return all addresses related to this NAS to the IP Pool

Session failed to do something

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

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

Send Accounting-Response.

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.

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.

Update the wtmp file.

This is only relevant if you use "radlast".

For Simultaneous-Use tracking.

Due to packet losses in the network, the data here may be incorrect. There is little we can do about it.

Cisco VoIP specific bulk accounting.

Filter attributes from the accounting response.