From: Alan T. DeKok <aland@freeradius.org>
Date: Fri, 7 Feb 2020 17:31:57 +0000 (-0500)
Subject: document revive_interval
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ea92e4a271a15838a5ca52aff179cc0895dcf994;p=thirdparty%2Ffreeradius-server.git

document revive_interval
---

diff --git a/raddb/mods-available/radius b/raddb/mods-available/radius
index d558eaef65a..be5ab7ad074 100644
--- 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
 	#