= Configuring a Module

The configuration files in
xref:raddb:mods-available/index.adoc[mods-available/] file describe
the configuration parameters accepted by each module, and what they
do.  This document explains how to perform generic testing with any
module.

The default server configuration should be tested via the following command:

[source,shell]
----
radiusd -XC
----

If the configuration is correct, then the server will print the
following message:

[source,log]
----
Configuration appears to be OK
----

If that message does not appear, then it is necessary to correct any
and all errors before proceeding to the next step.  It is a good idea
to ensure that the current configuration works _before_ making changes
to it.

== Editing mods-available/MODULE

As with all FreeRADIUS configuration files, please change at little as
possible in the default configuration.  The defaults are usually close
to being correct.  All that is necessary is to make minor changes, and
_test_ them.  FreeRADIUS should look for data.

== Enabling mods-available/MODULE

A module is enabled by creating a soft link from the `mods-enabled/`
directory to the `mods-available/` directory.

[source,shell]
----
cd raddb/mods-enabled && ln -s ../mods-available/MODULE
----

Where `MODULE` is the name of the module that is being enabled.

It is also possible to copy the `mods-available/MODULE` default
configuration file to `mods-enabled/MODULE`, and then edit that file.
This process leaves the original `mods-available/MODULE` configuration
file in place, if there is a need to refer to it in the future.  The
choice of which method to use is up to the local administrator.

== Testing the Server

The configuration of the server can be tested for syntactical
correctness via the following command:

[source,shell]
----
radiusd -XC
----

When the configuration is correct, then the server will print the
following message:

[source,log]
----
Configuration appears to be OK
----

Note that this test checks only that the configuration files can be
parsed.  It does not check that the module will correctly process packets.

When the configuration is correct, FreeRADIUS can then be started in debugging mode:

[source,shell]
----
radiusd -X
----

If the module has been configured correctly, the final (or almost
final) message will be

[source,log]
----
Ready to process requests
----

This message should be in bold on the console.  Depending on which
other modules are enabled, there may be a small number messages after
this one.

If the server starts, then the next step is then to perform
module-specific tests.  Please see the individual module "howto" page
for more information.

=== Errors

If the 'Ready to process requests` message does not appear, then the
debug output will contain error messages clearly describing what went
wrong.  These error message *must* be read in order to gain insight as
to the source of the problem.

Otherwise, look for messages containing `ERROR` or `WARNING`, or
the module name.  While the server can produce a large volume of
messages, most of those can be ignored when debugging a particular
problem.  Simply search for a few key strings based on the files you
changed, and the solution to the problem should be clear.

We recommend running the `radiusd -XC` test was performed before
making any module changes for other reasons.  If previous
configuration worked, and the only change was to a particular module,
then the source of the error is simple.  There is no need to go
searching through other configuration files or third-party web sites.
Instead, change and test the module configuration until the server
works.
