clarify serve-stale documentation, and add a floor for max-stale-ttl

- added a 1-second floor to max-stale-ttl similar to stale-answer-ttl;
  if set to 0, it will be silently updated to 1.
- fixed the ARM entry on max-stale-ttl, which incorrectly suggested that
  the default was 0 instead of 1 week.
- clarified rndc serve-stale documentation.

bin/named/server.c

@@ -4093,7 +4093,7 @@ configure_view(dns_view_t *view, dns_viewlist_t *viewlist,
 	obj = NULL;
 	result = named_config_get(maps, "max-stale-ttl", &obj);
 	INSIST(result == ISC_R_SUCCESS);
-	max_stale_ttl = cfg_obj_asuint32(obj);
+	max_stale_ttl = ISC_MAX(cfg_obj_asuint32(obj), 1);
 
 	obj = NULL;
 	result = named_config_get(maps, "stale-answer-enable", &obj);

bin/rndc/rndc.docbook

@@ -785,20 +785,28 @@
       </varlistentry>
 
       <varlistentry>
-	<term><userinput>serve-stale ( on | off | status | reset ) <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term>
+	<term><userinput>serve-stale ( on | off | reset | status ) <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 	<listitem>
 	  <para>
-	    Enable, disable, or reset the serving of stale answers
+	    Enable, disable, reset, or report the current status
-	    as configured in named.conf. Serving of stale answers
+            of the serving of stale answers as configured in
-	    will remain disabled across <filename>named.conf</filename>
+            <filename>named.conf</filename>.
-	    reloads if disabled via rndc until it is reset via rndc.
 	  </para>
 	  <para>
-	    Status will report whether serving of stale answers is
+            If serving of stale answers is disabled by
-	    currently enabled, disabled or not configured for a
+            <command>rndc-serve-stale off</command>, then it
-	    view.  If serving of stale records is configured then
+	    will remain disabled even if <command>named</command>
-	    the values of stale-answer-ttl and max-stale-ttl are
+            is reloaded or reconfigured.
-	    reported.
+            <command>rndc serve-stale reset</command> restores
+            the setting as configured in <filename>named.conf</filename>.
+	  </para>
+	  <para>
+	    <command>rndc serve-stale status</command> will report
+            whether serving of stale answers is currently enabled,
+            disabled by the configuration, or disabled by
+            <command>rndc</command>.  It will also report the
+	    values of <command>stale-answer-ttl</command> and
+	    <command>max-stale-ttl</command>.
 	  </para>
 	</listitem>
       </varlistentry>

doc/arm/Bv9ARM-book.xml

@@ -5349,12 +5349,13 @@ options {
 		Specifies the TTL to be returned on stale answers.
 		The default is 1 second. The minimum allowed is
 		also 1 second; a value of 0 will be updated silently
-		to 1 second.  For stale answers to be returned,
+		to 1 second.
-		they must be enabled (either in the configuration file
+	      </para>
-		using <command>stale-answer-enable</command> or via
+	      <para>
-		<command>rndc</command>), and
+		For stale answers to be returned, they must be enabled,
-		<option>max-stale-ttl</option> must be set to a
+		either in the configuration file using
-		nonzero value.
+		<command>stale-answer-enable</command> or via
+		<command>rndc serve-stale on</command>.
 	      </para>
 	    </listitem>
 	  </varlistentry>
@@ -6098,18 +6099,28 @@ options {
 	      <term><command>stale-answer-enable</command></term>
 	      <listitem>
 		<para>
-		  Enable the returning of stale answers when the
+		  Enable the returning of "stale" cached answers when
-		  nameservers for the zone are not answering.  This
+		  the nameservers for a zone are not answering.  The
-		  is off by default, but can be enabled/disabled via
+		  default is not to return stale answers.
-		  <command>rndc serve-stale on</command> and
+		</para>
-		  <command>rndc serve-stale off</command>, which
+		<para>
-		  override the <filename>named.conf</filename>
+		  Stale answers can also be enabled or disabled at
-		  setting.  <command>rndc serve-stale reset</command>
+		  runtime via <command>rndc serve-stale on</command> or
+		  <command>rndc serve-stale off</command>; these
+		  override the configured setting.
+		  <command>rndc serve-stale reset</command>
 		  restores the setting to the one specified in
-		  <filename>named.conf</filename>.  Note that
+		  <filename>named.conf</filename>.  Note that if
-		  reloading or reconfiguring <command>named</command>
+		  stale answers have been disabled by <command>rndc</command>,
-		  will not re-enable serving of stale records if they
+		  then they cannot be re-enabled by reloading or
-		  have been disabled via <command>rndc</command>.
+		  reconfiguring <command>named</command>;
+		  they must be re-enabled with
+		  <command>rndc serve-stale on</command>,
+		  or the server must be restarted.
+		</para>
+		<para>
+		  Information about stale answers is logged under
+		  the <command>serve-stale</command> log category.
 		</para>
 	      </listitem>
 	    </varlistentry>
@@ -8901,19 +8912,21 @@ avoid-v6-udp-ports { 40000; range 50000 60000; };
 	      <term><command>max-stale-ttl</command></term>
 	      <listitem>
 		<para>
-		  Sets the maximum time for which the server will
+		  If stale answers are enabled,
+		  <command>max-stale-ttl</command>
+		  sets the maximum time for which the server will
 		  retain records past their normal expiry to
 		  return them as stale records when the servers
-		  for those records are not reachable.  The default
+		  for those records are not reachable.
-		  is to not retain the record.
+		  The default is 1 week. The minimum allowed is
+		  1 second; a value of 0 will be updated silently
+		  to 1 second.
 		</para>
 		<para>
-		  <command>rndc serve-stale</command> can be used
+		  For stale answers to be returned, they must be enabled,
-		  to disable and re-enable the serving of stale
+		  either in the configuration file using
-		  records at runtime.  Reloading or reconfiguring
+		  <command>stale-answer-enable</command> or via
-		  <command>named</command> will not re-enable serving
+		  <command>rndc serve-stale on</command>.
-		  of stale records if they have been disabled via
-		  <command>rndc</command>.
 		</para>
 	      </listitem>
 	    </varlistentry>