FreeRADIUS server configuration file - 4.0

The location of other config files and logfiles are declared in this file.

Also general configuration for modules can be done in this file, it is exported through the API to modules that ask for it.

See man radiusd.conf for documentation on the format of this file. Note that the individual configuration items are NOT documented in that "man" page. They are only documented here, in the comments.

The unlang policy language can be used to create complex if / else policies. See man unlang for details.

See also the -n command-line option.

Location of config and logfiles.

This should be automatically set at configuration time.

If the server builds and installs, but fails at execution time with an 'undefined symbol' error, then you can use the libdir directive to work around the problem.

The cause is usually that a library has been installed on your system in a place where the dynamic linker cannot find it. When executing as root (or another user), your personal environment may be set up to allow the dynamic linker to find the library. When executing as a daemon, FreeRADIUS may not have the same personalized configuration.

To work around the problem, find out which library contains that symbol, and add the directory containing that library to the end of libdir, with a colon separating the directory names. No spaces are allowed. e.g.

You can also try setting the LD_LIBRARY_PATH environment variable in a script which starts the server.

If that does not work, then you can re-configure and re-build the server to NOT use shared libraries, via:

The server may be signalled while it’s running by using this file.

This file is written when only running in daemon mode.

e.g.: kill -HUP $(cat /var/run/radiusd/radiusd.pid)

The panic action is a command which will be executed if the server receives a fatal, non user generated signal, i.e. SIGSEGV, SIGBUS, SIGABRT or SIGFPE.

This can be used to start an interactive debugging session so that information regarding the current state of the server can be acquired.

The following string substitutions are available: - %e The currently executing program e.g. /sbin/radiusd - %p The PID of the currently executing program e.g. 12345

Standard ${} substitutions are also allowed.

An example panic action for opening an interactive session in GDB would be:

Again, don’t use that on a production system.

An example panic action for opening an automated session in GDB would be:

Requests which take more time than this to process may be killed, and a REJECT message is returned.

This problem is most often seen when using an SQL database. If it takes more than a second or two to receive an answer from the SQL database, then it probably means that you haven’t indexed the database. See your SQL server documentation for more information.

Useful range of values: 5 to 120

If this number is too low, then when the server becomes busy, it will not respond to any new requests, until the 'cleanup_delay' time has passed, and it has removed the old requests.

If this number is set too high, then the server will use a bit more memory for no real benefit.

If you aren’t sure what it should be set to, it’s better to set it too high than too low. Setting it to 1000 per client is probably the highest it should be.

Unlike v3, this setting is per worker thread, and is not global to the server.

Useful range of values: 256 to infinity

e.g., www.freeradius.org (on) or 206.47.27.232 (off).

The default is off because it would be overall better for the net if people had to knowingly turn this feature on, since enabling it means that each client request will result in AT LEAST one lookup request to the nameserver. Enabling hostname_lookups will also mean that your server may stop randomly for 30 seconds from time to time, if the DNS requests take too long.

Turning hostname lookups off also means that the server won’t block for 30 seconds, if it sees an IP address which has no name associated with it.

allowed values: {no, yes}

The default is on because people often use hostnames in configuration files. The main disadvantage of enabling this is the server may block at inopportune moments (like opening new connections) if the DNS servers are unavailable

allowed values: {no, yes}

Logging section. The various log_* configuration items will eventually be moved here.

destination: Destination for log messages.

This can be one of:

The command-line option -X over-rides this option, and forces logging to go to stdout.

Option will be ignored (disabled) if output of TERM is not an xterm or output is not to a TTY.

By default this is done with log levels of -Xx or -xxx where the destination is not syslog, or at all levels where the output is a file.

The config option below forcefully enables or disables timestamps irrespective of the log destination.

The exact values permitted here are OS-dependent. You probably don’t want to change this.

Setting this to "yes" means that the server does not print the contents of "secret" values such as passwords. It instead prints a place-holder value "<<< secret >>>", as follows:

…​ &User-Password = "<<< secret >>>" …​

Note that secret values are tracked across string expansions, string modifications, concatenations, etc.! i.e. if a User-Password is placed into a Reply-Message, then the value of the Reply-Message is also marked "secret".

This configuration is disabled by default. It is extremely important for administrators to be able to debug user logins by seeing what is actually being sent.

In most cases it is not useful to suppress secrets in an attempt to "be more secure". Any administrator who can see the debug ouput is usually also able to view and/or modify the servers configuration (including passwords in databases!). And any "low level" administrator who can only see the debug output will usually need to see the actual passwords in order to verify what the user is entering.

Perform debug logging to a special file.

This log section is generally used for per-request debug logging. For example, the following function calls can be placed in an unlang block, where it will:

The file will be closed when the request exits. It is the admins responsibility to ensure that the debug files are periodically cleaned up. The server does not do this automatically.

You can reference environment variables using an expansion like $ENV{PATH}. However it is sometimes useful to be able to also set environment variables. This section lets you do that.

The main purpose of this section is to allow administrators to keep RADIUS-specific configuration in the RADIUS configuration files. For example, if you need to set an environment variable which is used by a module. You could put that variable into a shell script, but that’s awkward. Instead, just list it here.

Note that these environment variables are set AFTER the configuration file is loaded. So you cannot set FOO here, and expect to reference it via $ENV{FOO} in another configuration file. You should instead just use a normal configuration variable for that.

Set environment variable FOO to value '/bar/baz'.

Delete environment variable BAR.

If the server needs kerberos credentials, then they can be placed into the following keytab file.

This also permits the server to use those credentials when it is run in debug mode.

LD_PRELOAD is special. It is normally set before the application runs, and is interpreted by the dynamic linker. Which means you cannot set it inside of an application, and expect it to load libraries.

Since this functionality is useful, we extend it here.

You can set

LD_PRELOAD = /path/to/library.so

and the server will load the named libraries. Multiple libraries can be loaded by specificing multiple individual LD_PRELOAD entries.

Template files hold common definitions that can be used in other server sections. When a template is referenced, the configuration items within the referenced template are copied to the referencing section.

Using templates reduces repetition of common configuration items, which in turn makes the server configuration easier to maintain.

See template.d/default for examples of using templates, and the referencing syntax.

There may be multiple methods of attacking on the server. This section holds the configuration items which minimize the impact of those attacks

chroot: directory where the server does "chroot".

The chroot is done very early in the process of starting the server. After the chroot has been performed it switches to the user listed below (which MUST be specified). If group is specified, it switches to that group, too. Any other groups listed for the specified user in /etc/group are also added as part of this process.

The current working directory (chdir / cd) is left outside of the chroot until all of the modules have been initialized. This allows the raddb directory to be left outside of the chroot. Once the modules have been initialized, it does a chdir to ${logdir}. This means that it should be impossible to break out of the chroot.

If you are worried about security issues related to this use of chdir, then simply ensure that the raddb directory is inside of the chroot, and be sure to do cd raddb BEFORE starting the server.

If the server is statically linked, then the only files that have to exist in the chroot are ${run_dir} and ${logdir}. If you do the cd raddb as discussed above, then the raddb directory has to be inside of the chroot directory, too.

If these are commented out, the server will run as the user/group that started it. In order to change to a different user/group, you MUST be root ( or have root privileges ) to start the server.

We STRONGLY recommend that you run the server with as few permissions as possible. That is, if you’re not using shadow passwords, the user and group items below should be set to radius'.

On systems with shadow passwords, you might have to set group = shadow for the server to be able to read the shadow password file. If you can authenticate users while in debug mode, but not in daemon mode, it may be that the debugging mode server is running as a user that can read the shadow info, and the user listed below can not.

The server will also try to use initgroups to read /etc/groups. It will join all groups where "user" is a member. This can allow for some finer-grained access controls.

This should only be set to yes if you’re debugging a problem with the server.

allowed values: {no, yes}

If this number is set too low, then no RADIUS packets will be accepted.

If this number is set too high, then an attacker may be able to send a small number of packets which will cause the server to use all available memory on the machine.

Setting this number to 0 means "allow any number of attributes"

allow_vulnerable_openssl: Allow the server to start with versions of OpenSSL known to have critical vulnerabilities.

This check is based on the version number reported by libssl and may not reflect patches applied to libssl by distribution maintainers.

This disables non-FIPS compliant digests and algorithms

Client configuration is defined in clients.conf.

In v4, the thread pool does not change size dynamically. Instead, there are a small number of threads which read from the network, and a slightly larger number of threads which process a request.

Defaults to the number of cores available on the system, or, 1, if this cannot be determined.

Note: Setting this to 0 will mean unlimited async contexts will be created. But as of 3.0.0, OpenSSL has no mechanism to shrink the async pool. This means if there’s a significant traffic spike the process will continue to use large amounts of memory until it’s restarted.

Uncomment the following line to enable snmptraps. Note that you MUST also configure the full path to the snmptrap command in the trigger.conf file.

Each library which has global settings will have its own configuration file in global.d

These flags are only for the "alpha" release of v4. They will be removed (and made into errors!) in the final release.

Some of these flags can also be passed on the command line as -S flag=value.

When this flag is set to true, the server will read the update section, and swap the internal implementation to use the new code. The configuration file can still contain the update keyword.

Not all update sections can be automatically converted. If the conversion process does not work, then the server will produce an error instead of doing the wrong thing.

This flag allows us to remove the last bits of the v2 configuration from the server.

The names and configuration of each module is located in this section.

After the modules are defined here, they may be referred to by name, in other sections of this configuration file.

Each module has a configuration as follows:

The name is used to load the rlm_name library which implements the functionality of the module.

The 'instance' is optional. To have two different instances of a module, it first must be referred to by 'name'. The different copies of the module are then created by inventing two 'instance' names, e.g. 'instance1' and 'instance2'

The instance names can then be used in later configuration INSTEAD of the original 'name'. See the 'radutmp' configuration for an example.

Some modules have ordering issues.

e.g. sqlippool uses the configuration from sql. In that case, the sql module must be read off of disk before the sqlippool.

However, the directory inclusion below just reads the directory from start to finish. Which means that the modules are read off of disk randomly.

As of >= 3.0.18, you can list individual modules before the directory inclusion. Those modules will be loaded first. Then, when the directory is read, those modules will be skipped and not read twice.

Modules are in mods-enabled/. Files matching the regex /[a-zA-Z0-9_.]+/ are loaded. The modules are initialized ONLY if they are referenced in a processing section, such as authorize, authenticate, accounting, pre/post-proxy, etc.

Policies are virtual modules.

Defining a policy in one of the policy.d files means that it can be referenced in multiple places as a name, rather than as a series of conditions to match, and actions to take.

Policies are something like subroutines in a normal language, but they cannot be called recursively. They MUST be defined in order. If policy A calls policy B, then B MUST be defined before A.

This next $INCLUDE line loads files in the directory that match the regular expression: /[a-zA-Z0-9_.]+/

It allows you to define new virtual servers simply by placing a file into the raddb/sites-enabled/ directory.

All of the other configuration sections like:

Have been moved to the the file:

raddb/sites-available/default

This is the default virtual server that has the same configuration as in version 1.0.x and 1.1.x. The default installation enables this virtual server. You should edit it to create policies for your local site.

For more documentation on virtual servers, see:

doc/raddb/sites-available/index.adoc