From d1ca21d50ab5cc196828db6ff8e548c6a26f86d5 Mon Sep 17 00:00:00 2001 From: Evan Hunt Date: Fri, 25 May 2018 22:00:37 -0700 Subject: [PATCH] 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 | 2 +- bin/rndc/rndc.docbook | 28 +++++++++++------- doc/arm/Bv9ARM-book.xml | 65 ++++++++++++++++++++++++----------------- 3 files changed, 58 insertions(+), 37 deletions(-) diff --git a/bin/named/server.c b/bin/named/server.c index 8844cf3953..9e1aa022e8 100644 --- 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 afda6f6e8e..ccf5f8f477 100644 --- a/bin/rndc/rndc.docbook +++ b/bin/rndc/rndc.docbook @@ -785,20 +785,28 @@ - serve-stale ( on | off | status | reset ) class view + serve-stale ( on | off | reset | status ) class view - Enable, disable, or reset the serving of stale answers - as configured in named.conf. Serving of stale answers - will remain disabled across named.conf - 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 + named.conf. - 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 + rndc-serve-stale off, then it + will remain disabled even if named + is reloaded or reconfigured. + rndc serve-stale reset restores + the setting as configured in named.conf. + + + rndc serve-stale status will report + whether serving of stale answers is currently enabled, + disabled by the configuration, or disabled by + rndc. It will also report the + values of stale-answer-ttl and + max-stale-ttl. diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml index fdfa988275..80ce9281b1 100644 --- 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 stale-answer-enable or via - rndc), and - must be set to a - nonzero value. + to 1 second. + + + For stale answers to be returned, they must be enabled, + either in the configuration file using + stale-answer-enable or via + rndc serve-stale on. @@ -6098,18 +6099,28 @@ options { stale-answer-enable - 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 - rndc serve-stale on and - rndc serve-stale off, which - override the named.conf - setting. rndc serve-stale reset + Enable the returning of "stale" cached answers when + the nameservers for a zone are not answering. The + default is not to return stale answers. + + + Stale answers can also be enabled or disabled at + runtime via rndc serve-stale on or + rndc serve-stale off; these + override the configured setting. + rndc serve-stale reset restores the setting to the one specified in - named.conf. Note that - reloading or reconfiguring named - will not re-enable serving of stale records if they - have been disabled via rndc. + named.conf. Note that if + stale answers have been disabled by rndc, + then they cannot be re-enabled by reloading or + reconfiguring named; + they must be re-enabled with + rndc serve-stale on, + or the server must be restarted. + + + Information about stale answers is logged under + the serve-stale log category. @@ -8901,19 +8912,21 @@ avoid-v6-udp-ports { 40000; range 50000 60000; }; max-stale-ttl - Sets the maximum time for which the server will + If stale answers are enabled, + max-stale-ttl + 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. - rndc serve-stale can be used - to disable and re-enable the serving of stale - records at runtime. Reloading or reconfiguring - named will not re-enable serving - of stale records if they have been disabled via - rndc. + For stale answers to be returned, they must be enabled, + either in the configuration file using + stale-answer-enable or via + rndc serve-stale on.