add docs for redundant, etc. as modules and as xlats

diff --git a/doc/antora/modules/reference/pages/unlang/load-balance.adoc b/doc/antora/modules/reference/pages/unlang/load-balance.adoc
index 8cd391c71b3f5669d007622088586aadd70aada2..1d2c41398792845fbec2f92e5bd2319047c568d7 100644 (file)
--- a/doc/antora/modules/reference/pages/unlang/load-balance.adoc
+++ b/doc/antora/modules/reference/pages/unlang/load-balance.adoc
@@ -38,5 +38,46 @@ load-balance &User-Name {
 }
 ----
 
+=== load-balance Sections as Modules
+
+It can be useful to use the same `load-balance` section in multiple
+places.  Instead of copying the same text multiple times, a
+`load-balance` section can be defined as a module in the `mods-enabled/`
+directory.
+
+For example, the following file can be placed into
+`mods-enabled/sql123`.  Once it is there, it can be used as a module
+named `sql123`, and used anywhere a module is allowed to use.
+
+.Example of Load-Balance SQL module
+[source,unlang]
+----
+load-balance sql123 {
+    sql1
+    sql2
+    sql3
+}
+----
+
+In previous versions of the server, this definition would be placed
+into the `instantiate` section of `radiusd.conf.  This configuration
+is no longer used, and the `sql123` definition can just be placed into
+a module definition in the `mods-enabled/` directory.
+
+==== Load-Balance Expansions
+
+When the `sql123` module is defined as above, it can also be used as
+in a xref:xlat/index.adoc[dynamic expansion]:
+
+.Example of Load-Balance SQL module
+[source,unlang]
+----
+&Reply-Message := %{sql123:SELECT message FROM table WHERE name='%{User-Name}'}
+}
+----
+
+The expansion works exactly like a `load-balance` block.  One of the
+modules is chosen to run the expansion, in load-balance fashion.
+
 // Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // Development of this documentation was sponsored by Network RADIUS SAS.

diff --git a/doc/antora/modules/reference/pages/unlang/redundant-load-balance.adoc b/doc/antora/modules/reference/pages/unlang/redundant-load-balance.adoc
index c84a50820ab962b7dd1d9dd91da4760de255c042..f54d8995e66f35e8dc3b9d95cc1aee7473746993 100644 (file)
--- a/doc/antora/modules/reference/pages/unlang/redundant-load-balance.adoc
+++ b/doc/antora/modules/reference/pages/unlang/redundant-load-balance.adoc
@@ -45,5 +45,52 @@ redundant-load-balance &User-Name {
 }
 ----
 
+=== Redundant-load-balance Sections as Modules
+
+It can be useful to use the same `redundant-load-balance` section in multiple
+places.  Instead of copying the same text multiple times, a
+`redundant-load-balance` section can be defined as a module in the `mods-enabled/`
+directory.
+
+For example, the following file can be placed into
+`mods-enabled/sql123`.  Once it is there, it can be used as a module
+named `sql123`, and used anywhere a module is allowed to use.
+
+.Example of Redundant-Load-Balance SQL module
+[source,unlang]
+----
+redundant-load-balance sql123 {
+    sql1
+    sql2
+    sql3
+}
+----
+
+In previous versions of the server, this definition would be placed
+into the `instantiate` section of `radiusd.conf.  This configuration
+is no longer used, and the `sql123` definition can just be placed into
+a module definition in the `mods-enabled/` directory.
+
+==== Redundant-Load-Balance Expansions
+
+When the `sql123` module is defined as above, it can also be used as
+in a xref:xlat/index.adoc[dynamic expansion]:
+
+.Example of Redundant-Load-Balance SQL module
+[source,unlang]
+----
+&Reply-Message := %{sql123:SELECT message FROM table WHERE name='%{User-Name}'}
+}
+----
+
+The expansion works exactly like a `redundant-load-balance` block.
+One of the underlying modules is chosen.  If it fails, the next one is
+chosen, etc.
+
+The one caveat here is that the arguments passed to the underlying
+modules are expanded again _for each call_.  If the expansion
+arguments have side effects, then those side effects can be applied
+multiple times, once for each `redundant-load-balance` attempt.
+
 // Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // Development of this documentation was sponsored by Network RADIUS SAS.

diff --git a/doc/antora/modules/reference/pages/unlang/redundant.adoc b/doc/antora/modules/reference/pages/unlang/redundant.adoc
index 0b575227add16712f8ca319fa46a5a91915f9335..f9b43c6080110c79ee6d611a3c00df023ac547d3 100644 (file)
--- a/doc/antora/modules/reference/pages/unlang/redundant.adoc
+++ b/doc/antora/modules/reference/pages/unlang/redundant.adoc
@@ -38,5 +38,53 @@ redundant {
 }
 ----
 
+=== Redundant Sections as Modules
+
+It can be useful to use the same `redundant` section in multiple
+places.  Instead of copying the same text multiple times, a
+`redundant` section can be defined as a module in the `mods-enabled/`
+directory.
+
+For example, the following file can be placed into
+`mods-enabled/sql123`.  Once it is there, it can be used as a module
+named `sql123`, and used anywhere a module is allowed to use.
+
+.Example of Redundant SQL module
+[source,unlang]
+----
+redundant sql123 {
+    sql1
+    sql2
+    sql3
+}
+----
+
+In previous versions of the server, this definition would be placed
+into the `instantiate` section of `radiusd.conf.  This configuration
+is no longer used, and the `sql123` definition can just be placed into
+a module definition in the `mods-enabled/` directory.
+
+==== Redundant Expansions
+
+When the `sql123` module is defined as above, it can also be used as
+in a xref:xlat/index.adoc[dynamic expansion]:
+
+.Example of Redundant SQL module
+[source,unlang]
+----
+&Reply-Message := %{sql123:SELECT message FROM table WHERE name='%{User-Name}'}
+}
+----
+
+The expansion works exactly like a `redundant` block.  First `sql1` is
+tried.  If that fails, `sql2` is tried.  Then if that fails, `sql3` is
+tried.
+
+The one caveat here is that the arguments passed to the underlying
+modules are expanded again _for each call_.  If the expansion
+arguments have side effects, then those side effects can be applied
+multiple times, once for each `redundant` attempt.
+
+
 // Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // Development of this documentation was sponsored by Network RADIUS SAS.