Merge branch 'serve-stale-doc-and-logging' into 'master'

Serve stale doc and logging

See merge request isc-projects/bind9!323

CHANGES

@@ -1,3 +1,7 @@
+4954.	[func]		Messages about serving of stale answers are now
+			directed to the "serve-stale" logging category.
+			Also clarified serve-stale documentation. [GL !323]
+
 4953.	[bug]		Removed the option to build the red black tree
 			database without a hash table; the non-hashing
 			version was buggy and is not needed. [GL #184]

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>

doc/arm/logging-categories.xml

@@ -315,6 +315,17 @@
 	  </para>
 	</entry>
       </row>
+      <row rowsep="0">
+	<entry colname="1">
+	  <para><command>serve-stale</command></para>
+	</entry>
+	<entry colname="2">
+	  <para>
+	    Whether or not a stale answer is used
+	    following a resolver failure.
+	  </para>
+	</entry>
+      </row>
       <row rowsep="0">
 	<entry colname="1">
 	  <para><command>spill</command></para>

lib/ns/include/ns/log.h

@@ -28,6 +28,7 @@ LIBNS_EXTERNAL_DATA extern isc_logmodule_t ns_modules[];
 #define NS_LOGCATEGORY_UPDATE_SECURITY	(&ns_categories[4])
 #define NS_LOGCATEGORY_QUERY_ERRORS	(&ns_categories[5])
 #define NS_LOGCATEGORY_TAT		(&ns_categories[6])
+#define NS_LOGCATEGORY_SERVE_STALE	(&ns_categories[7])
 
 /*
  * Backwards compatibility.

lib/ns/log.c

@@ -34,6 +34,7 @@ LIBNS_EXTERNAL_DATA isc_logcategory_t ns_categories[] = {
 	{ "update-security",            0 },
 	{ "query-errors",               0 },
 	{ "trust-anchor-telemetry",     0 },
+	{ "serve-stale",                0 },
 	{ NULL, 			0 }
 };
 

lib/ns/query.c

@@ -5493,7 +5493,7 @@ query_lookup(query_ctx_t *qctx) {
 
 		dns_name_format(qctx->client->query.qname,
 				namebuf, sizeof(namebuf));
-		isc_log_write(ns_lctx, NS_LOGCATEGORY_GENERAL,
+		isc_log_write(ns_lctx, NS_LOGCATEGORY_SERVE_STALE,
 			      NS_LOGMODULE_QUERY, ISC_LOG_INFO,
 			      "%s resolver failure, stale answer %s",
 			      namebuf, success ? "used" : "unavailable");