= Modules

The server includes a number of "plug-in" modules which perform a
variety of actions.  A full and annotated
xref:mods-available/all_modules.adoc[module list] available on a
separate page.

Modules are divided up into a few categories:

Authentication xref:mods-available/all_modules.adoc#_authentication_modules[list]::
Modules which implement authentication protocols such as PAP, CHAP, MS-CHAP, EAP, etc.

Datastore xref:mods-available/all_modules.adoc#_datastore_modules[list]::
Modules which connect to external data stores such as SQL, LDAP, etc.

IO xref:mods-available/all_modules.adoc#_io_modules[list]::
Modules which write to disk, external log systems, etc.

Language xref:mods-available/all_modules.adoc#_language_modules[list]::
Modules which encapsulate a scripting language into the server such as
Perl, Python, Lua, etc.

Miscelleanous xref:mods-available/all_modules.adoc#_miscellaneous_modules[list]::
Modules which do not belong elsewhere.

Policy xref:mods-available/all_modules.adoc#_policy_modules[list]::
Modules which implement policies to filter or enforce packets.

== Enabling a Module

Modules are enabled by creating a file in the `mods-enabled/` directory.
You can also create a soft-link from one directory to another:

[source,shell]
----
$ cd mods-enabled/
$ ln -s ../mods-available/foo
----

This will enable module `foo`. Be sure that you have configured the
module correctly before enabling it, otherwise the server will not
start. You can verify the server configuration by running
`radiusd -XC`.

A large number of modules are enabled by default. This allows the server
to work with the largest number of authentication protocols. Please be
careful when disabling modules. You will likely need to edit the
`sites-enabled/` files to remove references to any disabled modules.

== Conditional Modules

FreeRADIUS allows modules to be conditionally loaded. This is useful
when you want to have a virtual server which references a module, but
does not require it. Instead of editing the virtual server file, you can
just conditionally enable the module.

Modules are conditionally enabled by adding a `-` before their name in
a virtual server. For example, you can do:

[source,unlang]
----
server {
    ...
    recv Access-Request {
        ...
        ldap
        -sql
        ...
    }
}
----

This configuration means that the server will _require the LDAP
module, but use the SQL module only if it is configured._

This feature is not very useful for production configurations. It is,
however, very useful for the default examples that ship with the
server.

=== Ignoring A Module

If you see this message:

----
Ignoring "sql" as it is commented out.
----

then it signifies that the module is commented out as desceribed
above.  Most of the time this message can be ignored. The message can
be fixed by find the references to `-module` in the virtual server,
and deleting them.

Another way to fix it is to configure the module, as described above.

== Simplification

Allowing conditional modules simplifies the default virtual servers that
are shipped with FreeRADIUS. This means that if you want to enable LDAP
(for example), you no longer need to edit the files in
`sites-available/` in order to enable it.

Instead, you should edit the `mods-available/ldap` file to point to
your local LDAP server. Then, enable the module via the soft-link method
described above.

Once the module is enabled, it will automatically be used in the default
configuration.

== Module-Specific Configuration Files

Some modules require the use of additional configuration files.  These
additional files are located in the
xref:mods-config/index.adoc[mods-config/] directory.  The meaning and
interpretation of those files is documented there.  These files are
often in a custom, module-specific format, instead of using the
standard configuration file format.
