Add documentation for stale-answer-client-timeout

(cherry picked from commit 6ab907045762b3a9ffd8595808197c4e05b7d3cc)

diff --git a/bin/named/named.conf.rst b/bin/named/named.conf.rst
index 6f03f1133a5faa88fa08e9ed90a320bd1e0e6b6c..c23e28bd166691718c7eec9edfec1d88fb6e2047 100644 (file)
--- a/bin/named/named.conf.rst
+++ b/bin/named/named.conf.rst
@@ -411,6 +411,7 @@ OPTIONS
        sig-validity-interval integer [ integer ];
        sortlist { address_match_element; ... };
        stacksize ( default | unlimited | sizeval );
+       stale-answer-client-timeout ( disabled | off | integer );
        stale-answer-enable boolean;
        stale-answer-ttl duration;
        stale-cache-enable boolean;
@@ -796,6 +797,7 @@ VIEW
        sig-signing-type integer;
        sig-validity-interval integer [ integer ];
        sortlist { address_match_element; ... };
+       stale-answer-client-timeout ( disabled | off | integer );
        stale-answer-enable boolean;
        stale-answer-ttl duration;
        stale-cache-enable boolean;

diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst
index 8d93ef91371ddf66cf550f09e198edce5842d383..5ebf0cc4fa1c8e136294a4337053289de7bb6b78 100644 (file)
--- a/doc/arm/reference.rst
+++ b/doc/arm/reference.rst
@@ -1843,6 +1843,20 @@ Boolean Options
    Information about stale answers is logged under the ``serve-stale``
    log category.
 
+``stale-answer-client-timeout``
+   This option defines the amount of time ``named`` waits before attempting to
+   answer the query with a stale RRset from cache. If a stale answer is found,
+   ``named`` continues the ongoing fetches, attempting to refresh the RRset in
+   cache until the ``resolver-query-timeout`` interval is reached.
+
+   The default value is ``1800`` (in milliseconds) and the maximum value is
+   bounded to ``resolver-query-timeout`` minus one second. A value of ``0``
+   immediately returns a cached RRset if available, and still attempts a refresh
+   of the data in cache.
+
+   The option can be disabled by setting the value to ``off`` or ``disabled``.
+   It also has no effect if ``stale-answer-enable`` is disabled.
+
 ``stale-cache-enable``
    If ``yes``, enable the retaining of "stale" cached answers.  Default ``yes``.
 

diff --git a/doc/man/named.conf.5in b/doc/man/named.conf.5in
index d347f5f752c24158a51ea25d42d6f3b5b48101fc..cb4a193d8ce19a054be675d8d82b273839650a5f 100644 (file)
--- a/doc/man/named.conf.5in
+++ b/doc/man/named.conf.5in
@@ -464,6 +464,7 @@ options {
       sig\-validity\-interval integer [ integer ];
       sortlist { address_match_element; ... };
       stacksize ( default | unlimited | sizeval );
+      stale\-answer\-client\-timeout ( disabled | off | integer );
       stale\-answer\-enable boolean;
       stale\-answer\-ttl duration;
       stale\-cache\-enable boolean;
@@ -877,6 +878,7 @@ view string [ class ] {
       sig\-signing\-type integer;
       sig\-validity\-interval integer [ integer ];
       sortlist { address_match_element; ... };
+      stale\-answer\-client\-timeout ( disabled | off | integer );
       stale\-answer\-enable boolean;
       stale\-answer\-ttl duration;
       stale\-cache\-enable boolean;

diff --git a/doc/misc/options b/doc/misc/options
index 27b047fba8bbfde846172f5769a4b8336887977a..7c3460e8def2ea078514c51dc51693654f5512dc 100644 (file)
--- a/doc/misc/options
+++ b/doc/misc/options
@@ -367,6 +367,7 @@ options {
         sit-secret <string>; // obsolete
         sortlist { <address_match_element>; ... };
         stacksize ( default | unlimited | <sizeval> );
+        stale-answer-client-timeout ( disabled | off | <integer> );
         stale-answer-enable <boolean>;
         stale-answer-ttl <duration>;
         stale-cache-enable <boolean>;
@@ -751,6 +752,7 @@ view <string> [ <class> ] {
         sig-signing-type <integer>;
         sig-validity-interval <integer> [ <integer> ];
         sortlist { <address_match_element>; ... };
+        stale-answer-client-timeout ( disabled | off | <integer> );
         stale-answer-enable <boolean>;
         stale-answer-ttl <duration>;
         stale-cache-enable <boolean>;

diff --git a/doc/misc/options.active b/doc/misc/options.active
index 8e778f135fbd77cd12a623b2dadfc6cc1cf23a44..3dcba06b35f27cde77fa5ca17b0af37e4c9636b3 100644 (file)
--- a/doc/misc/options.active
+++ b/doc/misc/options.active
@@ -330,6 +330,7 @@ options {
         sig-validity-interval <integer> [ <integer> ];
         sortlist { <address_match_element>; ... };
         stacksize ( default | unlimited | <sizeval> );
+        stale-answer-client-timeout ( disabled | off | <integer> );
         stale-answer-enable <boolean>;
         stale-answer-ttl <duration>;
         stale-cache-enable <boolean>;
@@ -679,6 +680,7 @@ view <string> [ <class> ] {
         sig-signing-type <integer>;
         sig-validity-interval <integer> [ <integer> ];
         sortlist { <address_match_element>; ... };
+        stale-answer-client-timeout ( disabled | off | <integer> );
         stale-answer-enable <boolean>;
         stale-answer-ttl <duration>;
         stale-cache-enable <boolean>;

diff --git a/doc/misc/options.grammar.rst b/doc/misc/options.grammar.rst
index 3c5b9d8efbc4a3f0259ab83ac7396bb376582c28..16362c2abfce3bcd6aacf3c293a6f11ed48b6761 100644 (file)
--- a/doc/misc/options.grammar.rst
+++ b/doc/misc/options.grammar.rst
@@ -257,6 +257,7 @@
        sig-validity-interval <integer> [ <integer> ];
        sortlist { <address_match_element>; ... };
        stacksize ( default | unlimited | <sizeval> );
+       stale-answer-client-timeout ( disabled | off | <integer> );
        stale-answer-enable <boolean>;
        stale-answer-ttl <duration>;
        stale-cache-enable <boolean>;

diff --git a/doc/notes/notes-current.rst b/doc/notes/notes-current.rst
index 1f43232d27b91b6659ca38477b545abe5691ea59..53a6cafa2b89f325b090b72f2b84536e7cb588e3 100644 (file)
--- a/doc/notes/notes-current.rst
+++ b/doc/notes/notes-current.rst
@@ -37,6 +37,23 @@ New Features
   to the size of a full zone transfer. This value cannot exceed
   100%, which is also the default. [GL #1515]
 
+- A new option, ```stale-answer-client-timeout``, has been added to
+  improve ``named``'s behavior with respect to serving stale data. The option
+  defines the amount of time ``named`` waits before attempting
+  to answer the query with a stale RRset from cache. If a stale answer
+  is found, ``named`` continues the ongoing fetches, attempting to
+  refresh the RRset in cache until the ``resolver-query-timeout`` interval is
+  reached.
+
+  The default value is ``1800`` (in milliseconds) and the maximum value is
+  bounded to ``resolver-query-timeout`` minus one second. A value of
+  ``0`` immediately returns a cached RRset if available, and still
+  attempts a refresh of the data in cache.
+
+  The option can be disabled by setting the value to ``off`` or
+  ``disabled``. It also has no effect if ``stale-answer-enable`` is
+  disabled.
+
 Removed Features
 ~~~~~~~~~~~~~~~~