Added rlm_always documentation, with examples

diff --git a/doc/configurable_failover b/doc/configurable_failover
index cf1755b..2a050b5 100644 (file)
--- a/doc/configurable_failover
+++ b/doc/configurable_failover
@@ -1,3 +1,5 @@
+       Configurable Fail Over
+
 Before configurable failover, we had this:
 
 authorize {
@@ -32,12 +34,18 @@ module instances which refer to redundant databases. Example:
       server="mysecondserver.example"
       # Insert other necessary parameters here
     }
+    always handled {
+      rcode = handled
+    }
   }
   authenticate {
     authtype SQL {
       redundant {
-        sql1
-        sql2
+        sql1                   # try module sql1
+        sql2                   # if that's down, try module sql2
+       handled                 # otherwise drop the request as
+                               # it's been "handled" by the "always"
+                               # module (see doc/rlm_always)
       }
     }
   }

diff --git a/doc/rlm_always b/doc/rlm_always
new file mode 100644 (file)
index 0000000..4b4fff2
--- /dev/null
+++ b/doc/rlm_always
@@ -0,0 +1,76 @@
+       ALWAYS module configuration.
+
+0. INTRODUCTION
+
+  The 'always' module will always return the same thing, regardless of
+  how it's used.
+
+1. CONFIGURATION
+
+  The module has 3 configuration items:
+
+       rcode = <status>
+
+  Where <status> can be one of:
+
+       reject                  reject the request
+       fail                    fail to handle the request
+       ok                      the request was handled OK.
+       handled                 stop doing any more processing, as the
+                               module has "handled" the request itself.
+       invalid                 some bad configuration was encountered
+       userlock                the user is locked out
+       notfound                the user was not found
+       noop                    the module did nothing
+       updated                 the module touched the request
+
+
+  The return codes can be used to change the default results of
+  configurable fail-over.  (See 'configurable_failover' in this
+  directory.)  For example, the configurable fail-over documentation
+  has an example which is:
+
+#----
+  modules {
+    sql sql1 {
+      server="myfirstserver.example"
+      # Insert other necessary parameters here
+    }
+    sql sql2 {
+      server="mysecondserver.example"
+      # Insert other necessary parameters here
+    }
+    always handled {
+      rcode = handled
+    }
+  }
+  authenticate {
+    authtype SQL {
+      redundant {
+        sql1                   # try module sql1
+        sql2                   # if that's down, try module sql2
+       handled                 # otherwise the request is "handled"
+      }
+    }
+  }
+#----
+
+  This configuration says:
+
+  Try module sql1.  If that's down, try module sql2, if that's down,
+  then the 'always' module will mark the request as 'handled', and the
+  server will stop ALL processing, INCLUDING any response to the
+  client.
+
+  This allows you to configure the server to have it appear to be
+  down (i.e. not responding to requests) when the SQL servers which it
+  depends on are down.  When the SQL servers come back up, then the
+  RADIUS server will also start responding to requests.
+
+  During this time, the server WILL respond to Status-Server messages,
+  although that may not be a good idea.
+
+
+  The other two configuration entries are for testing
+  Simultaneous-Use.  They probably shouldn't be used.
+