document revive_interval

diff --git a/raddb/mods-available/radius b/raddb/mods-available/radius
index d558eaef65a4703fdd618b20708dea7c9eee46ff..be5ab7ad0745a22b75cb46a4e6896ae96115ba6c 100644 (file)
--- a/raddb/mods-available/radius
+++ b/raddb/mods-available/radius
@@ -176,11 +176,50 @@ radius {
        #
        #  The connection is marked `zombie`, and isn't used to send new packets.
        #  If there are no responses within `zombie_period`, the server either
-       #  closes the connection (no `status_check`), or starts pinging the
-       #  home server (`status_check = Status-Server`).
+       #  closes the connection (no `status_checks` subsection), or starts pinging the
+       #  home server (`status_checks.type = Status-Server`).
        #
        zombie_period = 10
 
+       #
+       #  revive_interval:: If there are no status checks, mark the
+       #  home server alive after `revive_interval` timeout.
+       #
+       #  Some home servers do not support status checks via the
+       #  `Status-Server` packet.  Others may not have a "test" user
+       #  configured that can be used to query the server, to see if
+       #  it is alive.  For those servers, we have NO WAY of knowing
+       #  when it becomes alive again.  Therefore, after the server
+       #  has been marked dead, we wait a period of time, and mark
+       #  it alive again, in the hope that it has come back to
+       #  life.
+       #
+       #  If it has NOT come back to life, then the module will wait
+       #  for `zombie_period` before marking it dead again.  During
+       #  the `zombie_period`, ALL AUTHENTICATIONS WILL FAIL, because
+       #  the home server is still dead.  There is NOTHING that can
+       #  be done about this, other than to enable the status checks,
+       #  as documented above.
+       #
+       #  e.g. if `zombie_period` is 40 seconds, and `revive_interval`
+       #  is 300 seconds, the for 40 seconds out of every 340, or about
+       #  10% of the time, all authentications will fail.
+       #
+       #  If the `zombie_period` and `revive_interval` configurations
+       #  are set smaller, than it is possible for up to 50% of
+       #  authentications to fail.
+       #
+       #  As a result, we recommend enabling status checks, and
+       #  we do NOT recommend using `revive_interval`.
+       #
+       #  The `revive_interval` configuration is used ONLY if the
+       #  `status_checks` subsection is not used.  Otherwise,
+       #  `revive_interval` is not necessary, and should be deleted.
+       #
+       #  Useful range of values: 10 to 3600
+       #
+       revive_interval = 3600
+
        #
        #  ## Connection trunking
        #