



= FreeRADIUS server configuration file - 4.0

Read `man radiusd` before editing this file.  See the section
titled DEBUGGING.  It outlines a method where you can quickly
obtain the configuration you want, without running into
trouble.

Run the server in debugging mode, and READ the output.

    $ radiusd -X

We cannot emphasize this point strongly enough.  The vast
majority of problems can be solved by carefully reading the
debugging output, which includes warnings about common issues,
and suggestions for how they may be fixed.

There may be a lot of output, but look carefully for words like:
`warning`, `error`, `reject`, or `failure`.  The messages there
will usually be enough to guide you to a solution.

If you are going to ask a question on the mailing list, then
explain what you are trying to do, and include the output from
debugging mode (`radiusd -X`).  Failure to do so means that all
of the responses to your question will be people telling you
to _post the output of `radiusd -X`_.


## Default instance

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.

NOTE: The paths used for installed server files. They are set
automatically at install time and will not normally need to be
changed.



name:: the name of the running server.

See also the `-n` command-line option.



Location of config and logfiles.



libdir:: Where to find the rlm_* modules.

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.

    libdir = /usr/local/lib:/opt/package/lib

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:

    ./configure --disable-shared
    make
    make install



pidfile:: Where to place the PID of the RADIUS server.

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)`



panic_action:: Command to execute if the server dies unexpectedly.

[WARNING]
====
FOR PRODUCTION SYSTEMS, ACTIONS SHOULD ALWAYS EXIT.
AN INTERACTIVE ACTION MEANS THE SERVER IS NOT RESPONDING TO REQUESTS.
AN INTERACTICE ACTION MEANS THE SERVER WILL NOT RESTART.

THE SERVER MUST NOT BE ALLOWED EXECUTE UNTRUSTED PANIC ACTION CODE
PATTACH CAN BE USED AS AN ATTACK VECTOR.
====

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:


NOTE: That command can be used on a production system.



max_request_time:: The maximum time (in seconds) to handle a request.

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

WARNING: If you notice that requests take a long time to be handled,
then this MAY INDICATE a bug in the server, in one of the modules
used to handle a request, OR in your local configuration.

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`



max_requests:: The maximum number of requests which the server
keeps track of.  This should be at least `256` multiplied by the
number of clients.  e.g. With `4` clients, this number should be
`1024`.

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`



reverse_lookups:: Log the names of clients or just their IP addresses

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}



hostname_lookups:: Global toggle for preventing hostname resolution

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:

|===
| Destination | Description
| file        | Log to `file`, as defined below.
| syslog      | To syslog (see also the `syslog_facility`, below.
| stdout      | Standard output.
| stderr      | Standard error.
|===

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



colourise:: Highlight important messages sent to stderr and stdout.

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



timestamp:: Add a timestamp to the start of every log message.

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.

NOTE: Is overridden by the `-T` command line option.



file:: The logging messages for the server are appended to the
tail of this file `if ${destination} == "file"`

NOTE: If the server is running in debugging mode, this file is
NOT used.



syslog_facility:: Which syslog facility to use, `if ${destination} == "syslog"`.

The exact values permitted here are _OS-dependent_.  You probably
don't want to change this.


suppress_secrets:: Suppress "secret" values when printing
them in debug mode.


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.




.ENVIRONMENT VARIABLES

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

NOTE: Note that you MUST use '='.  You CANNOT use '+=' to append
values.



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.




.Templates

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.



.Security Configuration

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.



user::
group::

The name (or `#number`) of the `user`/`group` to run `radiusd` as.

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

NOTE: Some kernels refuse to `setgid(group)` when the
value of (unsigned)group is above 60000; don't use group
`nobody` on these systems!

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.



allow_core_dumps:: Core dumps are a bad thing.

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

allowed values: {no, yes}



max_attributes:: The maximum number of attributes
permitted in a RADIUS packet.  Packets which have MORE
than this number of attributes in them will be dropped.

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.



openssl_fips_mode:: Enable OpenSSL FIPS mode.

This disables non-FIPS compliant digests and algorithms



.Clients Configuration

Client configuration is defined in `clients.conf`.

[WARNING]
====
The `clients.conf` file contains all of the information from the old
`clients` and `naslist` configuration files.  We recommend that you
do NOT use `client's` or `naslist`, although they are still
supported.

Anything listed in 'clients.conf' will take precedence over the
information from the old-style configuration files.
====



.Thread Pool Configuration

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.


num_networks:: Only one network thread is supported for now.



num_workers:: The worker threads can be varied.  It should be
at least one, and no more than 128.  Since each request is
non-blocking, there is no reason to run hundreds of threads
as in v3.

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



openssl_async_pool_init:: Controls the initial number of async
contexts that are allocated when a worker thread is created.
One async context is required for every TLS session (every
RADSEC connection, every TLS based method still in progress).



openssl_async_pool_max:: Controls the maximum number of async
contexts which are allocated to a worker thread.
If the maximum is reached, then no more TLS sessions can be
created.

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.



.SNMP notifications.

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.



.Global Library Settings

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



.Migration Flags

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


rewrite_update:: Rewrite old `update` sections to use the new
"edit" code.

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.



forbid_update:: Forbid the use of the `update` keyword.

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



.Module Configuration

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:

```
name [ instance ] {
	config_item = value
	...
}
```

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

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.



.Load virtual servers.

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:

  * `recv Access-Request {}`
  * `process Access-Request {}`
  * `process Accounting-Request {}`

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`


== Default Configuration

```
prefix = /Users/alandekok/git/wrapper//install
exec_prefix = ${prefix}
sysconfdir = ${prefix}/etc
localstatedir = ${prefix}/var
sbindir = ${exec_prefix}/sbin
logdir = ${localstatedir}/log/radius
raddbdir = ${sysconfdir}/raddb
radacctdir = ${logdir}/radacct
name = radiusd
confdir = ${raddbdir}
modconfdir = ${confdir}/mods-config
certdir = ${confdir}/certs
cadir   = ${confdir}/certs
run_dir = ${localstatedir}/run/${name}
db_dir = ${localstatedir}/lib/${name}
libdir = ${exec_prefix}/lib
pidfile = ${run_dir}/${name}.pid
#panic_action = "gdb %e %p"
#panic_action = "gdb -silent -x ${raddbdir}/panic.gdb %e %p 2>&1 | tee ${logdir}/gdb-${name}-%p.log"
max_request_time = 30
max_requests = 16384
reverse_lookups = no
hostname_lookups = yes
log {
	destination = file
	colourise = yes
#	timestamp = no
	file = ${logdir}/radius.log
	syslog_facility = daemon
#	suppress_secrets = no
}
#	* delete any pre-exising debug log for this user
#	  do not do this for EAP sessions, as they use multiple round trips.
#	* use the 'log debug' section as a template
#	* set the debug level for this request to '2'
#	* over-ride the log file, and set it to be based on the `link:https://freeradius.org/rfc/rfc2865.html#User-Name[User-Name]`.
#	%file.rm("${logdir}/debug/%{User-Name}.log")
#	%log.destination('debug', 2, "${logdir}/debug/%{User-Name}.log")
log debug {
	destination = null
	colourise = no
	timestamp = yes
}
ENV {
#	FOO = '/bar/baz'
#	BAR
#	KRB5_CLIENT_KTNAME = ${raddbdir}/radiusd.keytab
#	LD_PRELOAD = /path/to/library1.so
#	LD_PRELOAD = /path/to/library2.so
}
templates {
	$INCLUDE template.d/
}
security {
#	chroot = /path/to/chroot/directory
#	user = radius
#	group = radius
	allow_core_dumps = no
	max_attributes = 200
	allow_vulnerable_openssl = no
#	openssl_fips_mode = no
}
$INCLUDE clients.conf
thread pool {
#	num_networks = 1
#	num_workers = 1
#	openssl_async_pool_init = 64
#	openssl_async_pool_max = 1024
}
#$INCLUDE trigger.conf
global {
	$INCLUDE global.d/
}
migrate {
	rewrite_update = false
	forbid_update = false
}
modules {
#	$INCLUDE mods-enabled/sql
	$INCLUDE mods-enabled/
}
policy {
	$INCLUDE policy.d/
}
$INCLUDE sites-enabled/
```
