From b89fc52cd1ef5c845b43b9da0de75ed6dcedec19 Mon Sep 17 00:00:00 2001 From: Diego Fronza Date: Wed, 23 Dec 2020 12:16:26 -0300 Subject: [PATCH] Add documentation for stale-answer-client-timeout (cherry picked from commit 6ab907045762b3a9ffd8595808197c4e05b7d3cc) --- bin/named/named.conf.rst | 2 ++ doc/arm/reference.rst | 14 ++++++++++++++ doc/man/named.conf.5in | 2 ++ doc/misc/options | 2 ++ doc/misc/options.active | 2 ++ doc/misc/options.grammar.rst | 1 + doc/notes/notes-current.rst | 17 +++++++++++++++++ 7 files changed, 40 insertions(+) diff --git a/bin/named/named.conf.rst b/bin/named/named.conf.rst index 6f03f1133a..c23e28bd16 100644 --- 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 8d93ef9137..5ebf0cc4fa 100644 --- 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 d347f5f752..cb4a193d8c 100644 --- 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 27b047fba8..7c3460e8de 100644 --- a/doc/misc/options +++ b/doc/misc/options @@ -367,6 +367,7 @@ options { sit-secret ; // obsolete sortlist { ; ... }; stacksize ( default | unlimited | ); + stale-answer-client-timeout ( disabled | off | ); stale-answer-enable ; stale-answer-ttl ; stale-cache-enable ; @@ -751,6 +752,7 @@ view [ ] { sig-signing-type ; sig-validity-interval [ ]; sortlist { ; ... }; + stale-answer-client-timeout ( disabled | off | ); stale-answer-enable ; stale-answer-ttl ; stale-cache-enable ; diff --git a/doc/misc/options.active b/doc/misc/options.active index 8e778f135f..3dcba06b35 100644 --- a/doc/misc/options.active +++ b/doc/misc/options.active @@ -330,6 +330,7 @@ options { sig-validity-interval [ ]; sortlist { ; ... }; stacksize ( default | unlimited | ); + stale-answer-client-timeout ( disabled | off | ); stale-answer-enable ; stale-answer-ttl ; stale-cache-enable ; @@ -679,6 +680,7 @@ view [ ] { sig-signing-type ; sig-validity-interval [ ]; sortlist { ; ... }; + stale-answer-client-timeout ( disabled | off | ); stale-answer-enable ; stale-answer-ttl ; stale-cache-enable ; diff --git a/doc/misc/options.grammar.rst b/doc/misc/options.grammar.rst index 3c5b9d8efb..16362c2abf 100644 --- a/doc/misc/options.grammar.rst +++ b/doc/misc/options.grammar.rst @@ -257,6 +257,7 @@ sig-validity-interval [ ]; sortlist { ; ... }; stacksize ( default | unlimited | ); + stale-answer-client-timeout ( disabled | off | ); stale-answer-enable ; stale-answer-ttl ; stale-cache-enable ; diff --git a/doc/notes/notes-current.rst b/doc/notes/notes-current.rst index 1f43232d27..53a6cafa2b 100644 --- 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 ~~~~~~~~~~~~~~~~