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.

diff --git a/bin/named/server.c b/bin/named/server.c
index 8844cf395331069dfca95a4cbb3634fd88ac06a7..9e1aa022e838d9b86ea5c8ccb7033c1bc1d89d46 100644 (file)
--- a/bin/named/server.c
+++ b/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);

diff --git a/bin/rndc/rndc.docbook b/bin/rndc/rndc.docbook
index afda6f6e8ee4b3a934f3e99be14d260203c9211d..ccf5f8f47771b0b09db053f053eb304b02d1fdb5 100644 (file)
--- a/bin/rndc/rndc.docbook
+++ b/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
-           as configured in named.conf. Serving of stale answers
-           will remain disabled across <filename>named.conf</filename>
-           reloads if disabled via rndc until it is reset via rndc.
+           Enable, disable, reset, or report the current status
+            of the serving of stale answers as configured in
+            <filename>named.conf</filename>.
          </para>
          <para>
-           Status will report whether serving of stale answers is
-           currently enabled, disabled or not configured for a
-           view.  If serving of stale records is configured then
-           the values of stale-answer-ttl and max-stale-ttl are
-           reported.
+            If serving of stale answers is disabled by
+            <command>rndc-serve-stale off</command>, then it
+           will remain disabled even if <command>named</command>
+            is reloaded or reconfigured.
+            <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>

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index fdfa98827588bd0f531ac3b3308c5bfb4ad0acce..80ce9281b1580998011a5563f01207622fb5ae62 100644 (file)
--- a/doc/arm/Bv9ARM-book.xml
+++ b/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,
-               they must be enabled (either in the configuration file
-               using <command>stale-answer-enable</command> or via
-               <command>rndc</command>), and
-               <option>max-stale-ttl</option> must be set to a
-               nonzero value.
+               to 1 second.
+             </para>
+             <para>
+               For stale answers to be returned, they must be enabled,
+               either in the configuration file using
+               <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
-                 nameservers for the zone are not answering.  This
-                 is off by default, but can be enabled/disabled via
-                 <command>rndc serve-stale on</command> and
-                 <command>rndc serve-stale off</command>, which
-                 override the <filename>named.conf</filename>
-                 setting.  <command>rndc serve-stale reset</command>
+                 Enable the returning of "stale" cached answers when
+                 the nameservers for a zone are not answering.  The
+                 default is not to return stale answers.
+               </para>
+               <para>
+                 Stale answers can also be enabled or disabled at
+                 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
-                 reloading or reconfiguring <command>named</command>
-                 will not re-enable serving of stale records if they
-                 have been disabled via <command>rndc</command>.
+                 <filename>named.conf</filename>.  Note that if
+                 stale answers have been disabled by <command>rndc</command>,
+                 then they cannot be re-enabled by reloading or
+                 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
-                 is to not retain the record.
+                 for those records are not reachable.
+                 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
-                 to disable and re-enable the serving of stale
-                 records at runtime.  Reloading or reconfiguring
-                 <command>named</command> will not re-enable serving
-                 of stale records if they have been disabled via
-                 <command>rndc</command>.
+                 For stale answers to be returned, they must be enabled,
+                 either in the configuration file using
+                 <command>stale-answer-enable</command> or via
+                 <command>rndc serve-stale on</command>.
                </para>
              </listitem>
            </varlistentry>