From: Alan T. DeKok Date: Fri, 9 Dec 2022 15:34:56 +0000 (-0500) Subject: add docs for redundant, etc. as modules and as xlats X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f0e8eec1104c43abb5a1692f90c5c1a410f68eeb;p=thirdparty%2Ffreeradius-server.git 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 8cd391c71b3..1d2c4139879 100644 --- 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 c84a50820ab..f54d8995e66 100644 --- 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 0b575227add..f9b43c60801 100644 --- 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.