Commit d1ca21d5 authored by Evan Hunt's avatar Evan Hunt
Browse files

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.
parent 58ad54e7
......@@ -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);
......
......@@ -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>
......
......@@ -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>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment