Updated timestamp

[freeradius.git] / doc / configurable_failover

diff --git a/doc/configurable_failover b/doc/configurable_failover
index 313b43d..2598e89 100644 (file)
--- a/doc/configurable_failover
+++ b/doc/configurable_failover
@@ -62,8 +62,8 @@ server to process the second module if the first one fails.  Any
 number of modules can be listed in a "redundant" section.  The server
 will process each in turn, until one of the modules succeeds.  It willthen stop processing the "redundant" list.
 
-  Rewriting results for single modules
-  ------------------------------------
+1. Rewriting results for single modules
+   ------------------------------------
 
   Normally, when a module fails, the entire section ("authorize",
 "accounting", etc.) stops being processed.  In some cases, we may want
@@ -100,8 +100,8 @@ with priority "1".  The normal configuration is "fail = return", which
 means "if the detail module fails, stop processing the accounting
 section".
 
-  Fail-over configuration entries
-  -------------------------------
+2. Fail-over configuration entries
+   -------------------------------
 
   Modules normally return on of the following codes as their result:
 
@@ -122,6 +122,10 @@ listed, with a value.  If the code is not listed, or a configurable
 fail-over section is not defined, then values that make sense for the
 requested "group" (group, redundant, load-balance, etc) are used.
 
+  The special code "default" can be used to set all return codes to
+the specified value.  This value will be used with a lower priority
+than ones that are explicitly set.
+
   The values for each code may be one of two things:
 
        Value           Meaning
@@ -142,8 +146,8 @@ modules will be "ok", because it has higher priority than "fail".
 to fail, so long as a later module succeeds.
 
 
-  More Complex Configurations
-  ---------------------------
+3. More Complex Configurations
+   ---------------------------
 
   The "authorize" section is normally a list of module names.  We can
 create sub-lists by using the section name "group".  The "redundant"
@@ -197,8 +201,43 @@ return code found by processing the list.
 "group" section.
 
 
-  The Gory Details
-  ----------------
+4. Virtual Modules
+   ---------------
+
+  Some configurations may require using the same list of modules, in
+the same order, in multiple sections.  For those systems, the
+configuration can be simplified through the use of "virtual" modules.
+These modules are configured as named sub-sections of the
+"instantiate" section, as follows:
+
+       instantiate {
+               ...
+
+               redundant sql1_or_2 {
+                       sql1
+                       sql2
+               }
+       }
+
+  The name "sql1_or_2" can then be used in any other section, such as
+"authorize" or "accounting".  The result will be *exactly* as if that
+section was placed at the location of the "sql1_or_2" reference.
+
+  These virtual modules are full-fledged objects in and of themselves.
+One virtual module can refer to another virtual module, and they can
+contain "if" conditions, or any other configuration permitted in a
+section.
+
+
+5. Redundancy and Load-Balancing
+   -----------------------------
+
+  See "man unlang" or doc/load-balance.txt for information on simple
+redundancy (fail-over) and load balancing.
+
+
+6. The Gory Details
+   ----------------
 
 The fundamental object is called a MODCALLABLE, because it is something that
 can be passed a specific radius request and returns one of the RLM_MODULE_*
@@ -272,6 +311,33 @@ authorize{...} GROUP as a whole returns RLM_MODULE_NOOP, which makes sense
 because to say the user was not found at all would be a lie, since preprocess
 apparently found him, or else it would have returned RLM_MODULE_NOTFOUND too.
 
+We could use the "default" code to simplify the above example a
+little.  The following two configurations are identical:
+
+...
+  files {
+    notfound = 1
+    noop     = 2
+    ok       = 3
+    updated  = 4
+    default  = return
+  }
+...
+
+When putting the "default" first, later definitions over-ride it's
+return code:
+
+...
+  files {
+    default  = return
+    notfound = 1
+    noop     = 2
+    ok       = 3
+    updated  = 4
+  }
+...
+
+
 [Take a deep breath - the worst is over]
 
 That RESULT preference/desirability stuff is pretty complex, but my hope is