summaryrefslogtreecommitdiffstats
path: root/raddb/mods-available/README.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-13 14:11:00 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-13 14:11:00 +0000
commitaf754e596a8dbb05ed8580c342e7fe02e08b28e0 (patch)
treeb2f334c2b55ede42081aa6710a72da784547d8ea /raddb/mods-available/README.rst
parentInitial commit. (diff)
downloadfreeradius-af754e596a8dbb05ed8580c342e7fe02e08b28e0.tar.xz
freeradius-af754e596a8dbb05ed8580c342e7fe02e08b28e0.zip
Adding upstream version 3.2.3+dfsg.upstream/3.2.3+dfsg
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'raddb/mods-available/README.rst')
-rw-r--r--raddb/mods-available/README.rst116
1 files changed, 116 insertions, 0 deletions
diff --git a/raddb/mods-available/README.rst b/raddb/mods-available/README.rst
new file mode 100644
index 0000000..79ed5c3
--- /dev/null
+++ b/raddb/mods-available/README.rst
@@ -0,0 +1,116 @@
+Modules in Version 3
+====================
+
+As of Version 3, all of the modules have been placed in the
+"mods-available/" directory. This practice follows that used by other
+servers such as Nginx, Apache, etc. The "modules" directory should
+not be used.
+
+Modules are enabled by creating a file in the mods-enabled/ directory.
+You can also create a soft-link from one directory to another::
+
+ $ cd raddb/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
+-------------------
+
+Version 3 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::
+
+ server {
+ authorize {
+ ...
+ ldap
+ -sql
+ ...
+ }
+ }
+
+This says "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 module
+---------------
+
+If you see this message::
+
+ Ignoring module (see raddb/mods-available/README.rst)
+
+Then you are in the right place. Most of the time this message can be
+ignored. The message can be fixed by finding 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
+raddb/sites-available/ in order to enable it.
+
+Instead, you should edit the raddb/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.
+
+Multiple Instances
+------------------
+
+It is sometimes necessary to have the same module do two different
+things. The server supports this functionality via "instances" of
+modules.
+
+Normally, a module configuration looks like this:
+
+ sql {
+ ... sql stuff ...
+ }
+
+This module is then refereed to as the "sql" module.
+
+
+But what happens if you want to connect to two different SQL
+databases? The solution is simple; copy the "sql" module
+configuration, and add an instance name after the "sql" string:
+
+ sql mysql1 {
+ ... configuration for connecting to mysql11 ...
+ }
+
+ sql mysql2 {
+ ... configuration for connecting to mysql12 ...
+ }
+
+This configuration says "load the SQL module, but create two copies of
+it, with different configurations". The different configurations can
+be referred to by name, as "mysql1" and "mysql2". That is, anywhere
+you would normally use "sql", you could use either "mysql1" or
+"mysql2".
+
+For further examples of using module instances, see the "attr_filter"
+module configuration in this directory.