From: Alan T. DeKok <aland@freeradius.org>
Date: Tue, 3 Feb 2026 19:46:14 +0000 (-0500)
Subject: update docs for configurable failover and module behavior
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=98a7685f8e08e27cd082385a5124bafcf31236e7;p=thirdparty%2Ffreeradius-server.git

update docs for configurable failover and module behavior
---

diff --git a/doc/antora/modules/reference/pages/raddb/mods-available/index.adoc b/doc/antora/modules/reference/pages/raddb/mods-available/index.adoc
index fa1dbf0b5e7..4942cfb8478 100644
--- a/doc/antora/modules/reference/pages/raddb/mods-available/index.adoc
+++ b/doc/antora/modules/reference/pages/raddb/mods-available/index.adoc
@@ -1,9 +1,40 @@
 = Modules
 
 The server includes a number of "plug-in" modules which perform a
-variety of actions.  A full and annotated
-xref:raddb/mods-available/all_modules.adoc[module list] available on a
-separate page.
+variety of actions.  Each module has a small set of functionality,
+such as "connect to SQL database", or "check passwords".  This
+structure means that most of the complexity of the server is hidden
+behind (or encapsulated into) simple modular blocks.
+
+For example, a simple policy which says "get password from SQL, and
+then check it" is little more than two lines of text in a
+configuration file:
+
+[source,text]
+----
+sql
+pap
+----
+
+Each of the above modules has a complex configuration file, but the
+above policy does not contain the full configuration of SQL server
+address, admin login, queries, etc.  Instead, the policy focusses on
+the functional aspects of the requirements, which means that it is
+easier to create and understand.  A simple policy also means that (for
+example) the underlying SQL module can be reconfigured for a different
+SQL server or even a different SQL database, and the policy does not
+need to change.
+
+The full syntax for using modules in policies can be found in the
+`unlang` xref:reference:unlang/module.adoc[module] page.
+
+The full and annotated
+xref:raddb/mods-available/all_modules.adoc[module list] is large, and
+is therefore available on a separate page.
+
+
+
+== Categories
 
 Modules are divided up into a few categories:
 
@@ -26,6 +57,7 @@ Modules which do not belong elsewhere.
 Policy xref:raddb/mods-available/all_modules.adoc#_policy_modules[list]::
 Modules which implement policies to filter or enforce packets.
 
+[#enabling]
 == Enabling a Module
 
 Modules are enabled by creating a file in the `mods-enabled/` directory.
diff --git a/doc/antora/modules/reference/pages/unlang/module.adoc b/doc/antora/modules/reference/pages/unlang/module.adoc
index 66800ff6c35..7a8e254e6b5 100644
--- a/doc/antora/modules/reference/pages/unlang/module.adoc
+++ b/doc/antora/modules/reference/pages/unlang/module.adoc
@@ -52,10 +52,11 @@ if (notfound) {
 }
 ----
 
-== Module Return Code priority overrides
+[#configurable_failover]
+== Configurable Failover
 
-In the case of modules, rcodes can be modified on a per-call basis.
-These over-rides use the same syntax as the
+The return codes for a module can be can be modified on a per-call basis.
+These over-rides use the same syntax as theq
 xref:unlang/actions.adoc[actions] subsection.
 
 Module priority overrides are specified in a block inline with the module call.
@@ -86,5 +87,5 @@ ldap { <1>
 See the xref:unlang/actions.adoc[actions] page for more information on
 the syntax of the `actions` section.
 
-// Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
+// Copyright (C) 2026 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // This documentation was developed by Network RADIUS SAS.