Commit 3853b3cf authored by Evan Hunt's avatar Evan Hunt

update documentation

- change references to trusted-keys to dnssec-keys with static-key
- rebuild doc/misc/options and other generated grammar doc
- add a "see MANAGED-KEYS" note when building named.conf.docbook
parent d07053c8
......@@ -218,14 +218,17 @@
</para>
<para>
Note: When reading the trust anchor file,
<command>delv</command> treats <option>managed-keys</option>
statements and <option>trusted-keys</option> statements
identically. That is, for a managed key, it is the
<emphasis>initial</emphasis> key that is trusted; RFC 5011
key management is not supported. <command>delv</command>
will not consult the managed-keys database maintained by
<command>named</command>. This means that if either of the
keys in <filename>/etc/bind.keys</filename> is revoked
<command>delv</command> treats <option>dnssec-keys</option>
<option>initial-key</option> and <option>static-key</option>
entries identically. That is, even if a key is configured
with <command>initial-key</command>, indicating that it is
meant to be used only as an initializing key for RFC 5011
key maintenance, it is still treated by <command>delv</command>
as if it had been configured as a <command>static-key</command>.
<command>delv</command> does not consult the managed keys
database maintained by <command>named</command>. This means
that if either of the keys in
<filename>/etc/bind.keys</filename> is revoked
and rolled over, it will be necessary to update
<filename>/etc/bind.keys</filename> to use DNSSEC
validation in <command>delv</command>.
......
......@@ -13,7 +13,7 @@
<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="man.named.conf">
<info>
<date>2018-12-07</date>
<date>2019-05-10</date>
</info>
<refentryinfo>
<corpname>ISC</corpname>
......@@ -80,14 +80,12 @@
</refsection>
<refsection><info><title>ACL</title></info>
<literallayout class="normal">
acl <replaceable>string</replaceable> { <replaceable>address_match_element</replaceable>; ... };
</literallayout>
</refsection>
<refsection><info><title>CONTROLS</title></info>
<literallayout class="normal">
controls {
inet ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> |
......@@ -104,7 +102,6 @@ controls {
</refsection>
<refsection><info><title>DLZ</title></info>
<literallayout class="normal">
dlz <replaceable>string</replaceable> {
database <replaceable>string</replaceable>;
......@@ -113,8 +110,15 @@ dlz <replaceable>string</replaceable> {
</literallayout>
</refsection>
<refsection><info><title>DYNDB</title></info>
<refsection><info><title>DNSSEC-KEYS</title></info>
<literallayout class="normal">
dnssec-keys { <replaceable>string</replaceable> ( static-key |
initial-key ) <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>quoted_string</replaceable>; ... };
</literallayout>
</refsection>
<refsection><info><title>DYNDB</title></info>
<literallayout class="normal">
dyndb <replaceable>string</replaceable> <replaceable>quoted_string</replaceable> {
<replaceable>unspecified-text</replaceable> };
......@@ -122,7 +126,6 @@ dyndb <replaceable>string</replaceable> <replaceable>quoted_string</replaceable>
</refsection>
<refsection><info><title>KEY</title></info>
<literallayout class="normal">
key <replaceable>string</replaceable> {
algorithm <replaceable>string</replaceable>;
......@@ -132,7 +135,6 @@ key <replaceable>string</replaceable> {
</refsection>
<refsection><info><title>LOGGING</title></info>
<literallayout class="normal">
logging {
category <replaceable>string</replaceable> { <replaceable>string</replaceable>; ... };
......@@ -154,15 +156,15 @@ logging {
<refsection><info><title>MANAGED-KEYS</title></info>
<para>See DNSSEC-KEYS.</para>
<literallayout class="normal">
managed-keys { <replaceable>string</replaceable> <replaceable>string</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... };
managed-keys { <replaceable>string</replaceable> ( static-key |
initial-key ) <replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>quoted_string</replaceable>; ... };
</literallayout>
</refsection>
<refsection><info><title>MASTERS</title></info>
<literallayout class="normal">
masters <replaceable>string</replaceable> [ port <replaceable>integer</replaceable> ] [ dscp
<replaceable>integer</replaceable> ] { ( <replaceable>masters</replaceable> | <replaceable>ipv4_address</replaceable> [
......@@ -172,7 +174,6 @@ masters <replaceable>string</replaceable> [ port <replaceable>integer</replaceab
</refsection>
<refsection><info><title>OPTIONS</title></info>
<literallayout class="normal">
options {
allow-new-zones <replaceable>boolean</replaceable>;
......@@ -251,7 +252,6 @@ options {
dnsrps-options { <replaceable>unspecified-text</replaceable> };
dnssec-accept-expired <replaceable>boolean</replaceable>;
dnssec-dnskey-kskonly <replaceable>boolean</replaceable>;
dnssec-enable <replaceable>boolean</replaceable>;
dnssec-loadkeys-interval <replaceable>integer</replaceable>;
dnssec-lookaside ( <replaceable>string</replaceable> trust-anchor
<replaceable>string</replaceable> | auto | no );
......@@ -403,11 +403,12 @@ options {
resolver-retry-interval <replaceable>integer</replaceable>;
response-padding { <replaceable>address_match_element</replaceable>; ... } block-size
<replaceable>integer</replaceable>;
response-policy { zone <replaceable>string</replaceable> [ log <replaceable>boolean</replaceable> ] [ max-policy-ttl
<replaceable>ttlval</replaceable> ] [ min-update-interval <replaceable>ttlval</replaceable> ] [ policy ( cname |
disabled | drop | given | no-op | nodata | nxdomain | passthru
| tcp-only <replaceable>quoted_string</replaceable> ) ] [ recursive-only <replaceable>boolean</replaceable> ] [
nsip-enable <replaceable>boolean</replaceable> ] [ nsdname-enable <replaceable>boolean</replaceable> ]; ... } [
response-policy { zone <replaceable>string</replaceable> [ add-soa <replaceable>boolean</replaceable> ] [ log
<replaceable>boolean</replaceable> ] [ max-policy-ttl <replaceable>ttlval</replaceable> ] [ min-update-interval
<replaceable>ttlval</replaceable> ] [ policy ( cname | disabled | drop | given | no-op |
nodata | nxdomain | passthru | tcp-only <replaceable>quoted_string</replaceable> ) ] [
recursive-only <replaceable>boolean</replaceable> ] [ nsip-enable <replaceable>boolean</replaceable> ] [
nsdname-enable <replaceable>boolean</replaceable> ]; ... } [ add-soa <replaceable>boolean</replaceable> ] [
break-dnssec <replaceable>boolean</replaceable> ] [ max-policy-ttl <replaceable>ttlval</replaceable> ] [
min-update-interval <replaceable>ttlval</replaceable> ] [ min-ns-dots <replaceable>integer</replaceable> ] [
nsip-wait-recurse <replaceable>boolean</replaceable> ] [ qname-wait-recurse <replaceable>boolean</replaceable> ]
......@@ -474,7 +475,6 @@ options {
</refsection>
<refsection><info><title>PLUGIN</title></info>
<literallayout class="normal">
plugin ( query ) <replaceable>string</replaceable> [ { <replaceable>unspecified-text</replaceable>
} ];
......@@ -482,7 +482,6 @@ plugin ( query ) <replaceable>string</replaceable> [ { <replaceable>unspecified-
</refsection>
<refsection><info><title>SERVER</title></info>
<literallayout class="normal">
server <replaceable>netprefix</replaceable> {
bogus <replaceable>boolean</replaceable>;
......@@ -520,7 +519,6 @@ server <replaceable>netprefix</replaceable> {
</refsection>
<refsection><info><title>STATISTICS-CHANNELS</title></info>
<literallayout class="normal">
statistics-channels {
inet ( <replaceable>ipv4_address</replaceable> | <replaceable>ipv6_address</replaceable> |
......@@ -532,15 +530,15 @@ statistics-channels {
</refsection>
<refsection><info><title>TRUSTED-KEYS</title></info>
<para>Deprecated - see DNSSEC-KEYS.</para>
<literallayout class="normal">
trusted-keys { <replaceable>string</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... };
trusted-keys { <replaceable>string</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>quoted_string</replaceable>; ... };, deprecated
</literallayout>
</refsection>
<refsection><info><title>VIEW</title></info>
<literallayout class="normal">
view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
allow-new-zones <replaceable>boolean</replaceable>;
......@@ -612,7 +610,9 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
dnsrps-options { <replaceable>unspecified-text</replaceable> };
dnssec-accept-expired <replaceable>boolean</replaceable>;
dnssec-dnskey-kskonly <replaceable>boolean</replaceable>;
dnssec-enable <replaceable>boolean</replaceable>;
dnssec-keys { <replaceable>string</replaceable> ( static-key |
initial-key ) <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... };
dnssec-loadkeys-interval <replaceable>integer</replaceable>;
dnssec-lookaside ( <replaceable>string</replaceable> trust-anchor
<replaceable>string</replaceable> | auto | no );
......@@ -650,9 +650,9 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
key-directory <replaceable>quoted_string</replaceable>;
lame-ttl <replaceable>ttlval</replaceable>;
lmdb-mapsize <replaceable>sizeval</replaceable>;
managed-keys { <replaceable>string</replaceable> <replaceable>string</replaceable>
<replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>quoted_string</replaceable>; ... };
managed-keys { <replaceable>string</replaceable> ( static-key |
initial-key ) <replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>; ... };
masterfile-format ( map | raw | text );
masterfile-style ( full | relative );
match-clients { <replaceable>address_match_element</replaceable>; ... };
......@@ -735,11 +735,12 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
resolver-retry-interval <replaceable>integer</replaceable>;
response-padding { <replaceable>address_match_element</replaceable>; ... } block-size
<replaceable>integer</replaceable>;
response-policy { zone <replaceable>string</replaceable> [ log <replaceable>boolean</replaceable> ] [ max-policy-ttl
<replaceable>ttlval</replaceable> ] [ min-update-interval <replaceable>ttlval</replaceable> ] [ policy ( cname |
disabled | drop | given | no-op | nodata | nxdomain | passthru
| tcp-only <replaceable>quoted_string</replaceable> ) ] [ recursive-only <replaceable>boolean</replaceable> ] [
nsip-enable <replaceable>boolean</replaceable> ] [ nsdname-enable <replaceable>boolean</replaceable> ]; ... } [
response-policy { zone <replaceable>string</replaceable> [ add-soa <replaceable>boolean</replaceable> ] [ log
<replaceable>boolean</replaceable> ] [ max-policy-ttl <replaceable>ttlval</replaceable> ] [ min-update-interval
<replaceable>ttlval</replaceable> ] [ policy ( cname | disabled | drop | given | no-op |
nodata | nxdomain | passthru | tcp-only <replaceable>quoted_string</replaceable> ) ] [
recursive-only <replaceable>boolean</replaceable> ] [ nsip-enable <replaceable>boolean</replaceable> ] [
nsdname-enable <replaceable>boolean</replaceable> ]; ... } [ add-soa <replaceable>boolean</replaceable> ] [
break-dnssec <replaceable>boolean</replaceable> ] [ max-policy-ttl <replaceable>ttlval</replaceable> ] [
min-update-interval <replaceable>ttlval</replaceable> ] [ min-ns-dots <replaceable>integer</replaceable> ] [
nsip-wait-recurse <replaceable>boolean</replaceable> ] [ qname-wait-recurse <replaceable>boolean</replaceable> ]
......@@ -801,9 +802,10 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
transfer-source-v6 ( <replaceable>ipv6_address</replaceable> | * ) [ port ( <replaceable>integer</replaceable> | * )
] [ dscp <replaceable>integer</replaceable> ];
trust-anchor-telemetry <replaceable>boolean</replaceable>; // experimental
trusted-keys { <replaceable>string</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable> <replaceable>integer</replaceable> <replaceable>quoted_string</replaceable>;
... };
trusted-keys { <replaceable>string</replaceable>
<replaceable>integer</replaceable> <replaceable>integer</replaceable>
<replaceable>integer</replaceable>
<replaceable>quoted_string</replaceable>; ... };, deprecated
try-tcp-refresh <replaceable>boolean</replaceable>;
update-check-ksk <replaceable>boolean</replaceable>;
use-alt-transfer-source <replaceable>boolean</replaceable>;
......@@ -915,7 +917,6 @@ view <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
</refsection>
<refsection><info><title>ZONE</title></info>
<literallayout class="normal">
zone <replaceable>string</replaceable> [ <replaceable>class</replaceable> ] {
allow-notify { <replaceable>address_match_element</replaceable>; ... };
......
......@@ -458,7 +458,7 @@
<term><userinput>managed-keys <replaceable>(status | refresh | sync | destroy)</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term>
<listitem>
<para>
Inspect and control the "managed-keys" database which
Inspect and control the "managed keys" database which
handles RFC 5011 DNSSEC trust anchor maintenance. If a view
is specified, these commands are applied to that view;
otherwise they are applied to all views.
......@@ -467,14 +467,14 @@
<listitem>
<para>
When run with the <literal>status</literal> keyword, prints
the current status of the managed-keys database.
the current status of the managed keys database.
</para>
</listitem>
<listitem>
<para>
When run with the <literal>refresh</literal> keyword,
forces an immediate refresh query to be sent for all
the managed keys, updating the managed-keys database
the managed keys, updating the managed keys database
if any new keys are found, without waiting the normal
refresh interval.
</para>
......@@ -482,7 +482,7 @@
<listitem>
<para>
When run with the <literal>sync</literal> keyword, forces an
immediate dump of the managed-keys database to disk
immediate dump of the managed keys database to disk
(in the file <filename>managed-keys.bind</filename> or
(<filename><replaceable>viewname</replaceable>.mkeys</filename>).
This synchronizes the database with its journal file, so
......@@ -493,7 +493,7 @@
<listitem>
<para>
When run with the <literal>destroy</literal> keyword, the
managed-keys database is shut down and deleted, and all key
managed keys database is shut down and deleted, and all key
maintenance is terminated. This command should be used only
with extreme caution.
</para>
......@@ -772,9 +772,10 @@
<listitem>
<para>
Dump the security roots (i.e., trust anchors
configured via <command>trusted-keys</command>,
<command>managed-keys</command>, or
<command>dnssec-validation auto</command>) and negative trust
configured via <command>dnssec-keys</command> statements,
or the synonymous <command>managed-keys</command> or
the deprecated <command>trusted-keys</command> statements, or
via <command>dnssec-validation auto</command>) and negative trust
anchors for the specified views. If no view is specified, all
views are dumped. Security roots will indicate whether
they are configured as trusted keys, managed keys, or
......
......@@ -259,8 +259,8 @@ key "non-viewkey" { secret "YWFh" ; algorithm "zzz" ; };
view "test-view" in {
key "viewkey" { algorithm "xxx" ; secret "eXl5" ; };
also-notify { 10.2.2.3; };
trusted-keys {
foo.com. 4 3 2 "abdefghijklmnopqrstuvwxyz";
managed-keys {
foo.com. static 4 3 2 "abdefghijklmnopqrstuvwxyz";
};
sig-validity-interval 45;
max-cache-size 100000;
......@@ -342,8 +342,8 @@ zone "." {
// pubkey 257 255 1 "AQP2fHpZ4VMpKo/jc9Fod821uyfY5p8j5h/Am0V/KpBTMZjdXmp9QJe6yFRoIIzkaNCgTIftASdpXGgCwFB2j2KXP/rick6gvEer5VcDEkLR5Q==";
};
trusted-keys {
"." 257 255 1 "AQP2fHpZ4VMpKo/jc9Fod821uyfY5p8j5h/Am0V/KpBTMZjdXmp9QJe6yFRoIIzkaNCgTIftASdpXGgCwFB2j2KXP/rick6gvEer5VcDEkLR5Q==";
managed-keys {
"." static 257 255 1 "AQP2fHpZ4VMpKo/jc9Fod821uyfY5p8j5h/Am0V/KpBTMZjdXmp9QJe6yFRoIIzkaNCgTIftASdpXGgCwFB2j2KXP/rick6gvEer5VcDEkLR5Q==";
};
......
......@@ -2087,7 +2087,7 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;};
zone key of another zone above this one in the DNS tree.
</para>
<section xml:id="dnssec_keys"><info><title>Generating Keys</title></info>
<section xml:id="generating_dnssec_keys"><info><title>Generating Keys</title></info>
<para>
The <command>dnssec-keygen</command> program is used to
......@@ -2212,8 +2212,9 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;};
<userinput>yes</userinput>, DNSSEC validation will only occur
if at least one trust anchor has been explicitly configured
in <filename>named.conf</filename>
using a <command>trusted-keys</command> or
<command>managed-keys</command> statement.
using a <command>dnssec-keys</command> statement (or the
synonymous <command>managed-keys</command> or the deprecated
<command>trusted-keys</command> statements).
</para>
<para>
When <command>dnssec-validation</command> is set to
......@@ -2226,23 +2227,20 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;};
</para>
<para>
<command>trusted-keys</command> are copies of DNSKEY RRs
for zones that are used to form the first link in the
cryptographic chain of trust. All keys listed in
<command>trusted-keys</command> (and corresponding zones)
are deemed to exist and only the listed keys will be used
to validated the DNSKEY RRset that they are from.
The keys specified in <command>dnssec-keys</command>
copies of DNSKEY RRs for zones that are used to form the
first link in the cryptographic chain of trust. Keys configured
with the keyword <command>static-key</command> are loaded directly
into the table of trust anchors, and can only be changed by
altering the configuration. Keys configured with
<command>initial-key</command> are used to initialize
RFC 5011 trust anchor maintenance, and will be kept up to
date automatically after the first time <command>named</command>
runs.
</para>
<para>
<command>managed-keys</command> are trusted keys which are
automatically kept up to date via RFC 5011 trust anchor
maintenance.
</para>
<para>
<command>trusted-keys</command> and
<command>managed-keys</command> are described in more detail
<command>dnssec-keys</command> is described in more detail
later in this document.
</para>
......@@ -2265,7 +2263,7 @@ allow-update { !{ !localnets; any; }; key host1-host2. ;};
</para>
<programlisting>
managed-keys {
dnssec-keys {
/* Root Key */
"." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS
JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh
......@@ -2277,11 +2275,8 @@ managed-keys {
66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ
97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ
dgxbcDTClU0CRBdiieyLMNzXG3";
};
trusted-keys {
/* Key for our organization's forward zone */
example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6
example.com. static-key 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6
5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z
GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb
4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL
......@@ -2294,7 +2289,7 @@ trusted-keys {
1OTQ09A0=";
/* Key for our reverse zone. */
2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc
2.0.192.IN-ADDRPA.NET. static-key 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc
xOdNax071L18QqZnQQQAVVr+i
LhGTnNGp3HoWQLUIzKrJVZ3zg
gy3WwNT6kZo6c0tszYqbtvchm
......@@ -3205,11 +3200,17 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.
</row>
<row rowsep="0">
<entry colname="1">
<para><command>trusted-keys</command></para>
<para><command>dnssec-keys</command></para>
</entry>
<entry colname="2">
<para>
defines trusted DNSSEC keys.
defines DNSSEC keys: if used with the
<command>initial-key</command> keyword,
keys are kept up to date using RFC 5011
trust anchor maintenance, and if used with
<command>static-key</command>, keys are permanent.
Identical to <command>managed-keys</command>,
but has been added for improved clarity.
</para>
</entry>
</row>
......@@ -3219,8 +3220,22 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.
</entry>
<entry colname="2">
<para>
lists DNSSEC keys to be kept up to date
using RFC 5011 trust anchor maintenance.
is identical to <command>dnssec-keys</command>,
and is retained for backward compatibility.
</para>
</entry>
</row>
<row rowsep="0">
<entry colname="1">
<para><command>trusted-keys</command></para>
</entry>
<entry colname="2">
<para>
defines permanent trusted DNSSEC keys;
this option is deprecated in favor
of <command>dnssec-keys</command> with
the <command>static-key</command> keyword,
and may be removed in a future release.
</para>
</entry>
</row>
......@@ -4595,10 +4610,12 @@ badresp:1,adberr:0,findfail:0,valfail:0]
<listitem>
<para>
Specifies the directory in which to store the files that
track managed DNSSEC keys. By default, this is the working
directory. The directory <emphasis>must</emphasis>
be writable by the effective user ID of the
<command>named</command> process.
track managed DNSSEC keys (i.e., those configured using
the <command>initial-key</command> keyword in a
<command>dnssec-keys</command> statement). By default,
this is the working directory. The directory
<emphasis>must</emphasis> be writable by the effective
user ID of the <command>named</command> process.
</para>
<para>
If <command>named</command> is not configured to use views,
......@@ -5100,10 +5117,10 @@ options {
then <command>named</command> will only accept answers if
they are secure. If <userinput>no</userinput>, then normal
DNSSEC validation applies allowing for insecure answers to
be accepted. The specified domain must be under a
<command>trusted-keys</command> or
<command>managed-keys</command> statement, or
<command>dnssec-validation auto</command> must be active.
be accepted. The specified domain must be defined as a
trust anchor, for instance in a <command>dnssec-keys</command>
statement, or <command>dnssec-validation auto</command> must
be active.
</para>
</listitem>
</varlistentry>
......@@ -6195,8 +6212,8 @@ options {
<para>
Causes <command>named</command> to send specially-formed
queries once per day to domains for which trust anchors
have been configured via <command>trusted-keys</command>,
<command>managed-keys</command>, or
have been configured via, e.g.,
<command>dnssec-keys</command> or
<command>dnssec-validation auto</command>.
</para>
<para>
......@@ -6411,10 +6428,11 @@ options {
<para>
If set to <userinput>yes</userinput>, DNSSEC validation is
enabled, but a trust anchor must be manually configured
using a <command>trusted-keys</command>
or <command>managed-keys</command> statement; if there
is no configured trust anchor, validation will not take
place.
using a <command>dnssec-keys</command> statement (or
the synonymous <command>managed-keys</command>, or the
deprecated <command>trusted-keys</command> statements).
If there is no configured trust anchor, validation will
not take place.
</para>
<para>
If set to <userinput>no</userinput>, DNSSEC validation
......@@ -10709,246 +10727,236 @@ example.com CNAME rpz-tcp-only.
</para>
</section>
<section xml:id="statschannels"><info><title><command>statistics-channels</command> Statement Grammar</title></info>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="statistics-channels.grammar.xml"/>
</section>
<section xml:id="statschannels"><info><title><command>statistics-channels</command> Statement Grammar</title></info>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="statistics-channels.grammar.xml"/>
</section>
<section xml:id="statistics_channels"><info><title><command>statistics-channels</command> Statement Definition and
Usage</title></info>
<section xml:id="statistics_channels"><info><title><command>statistics-channels</command> Statement Definition and
Usage</title></info>
<para>
The <command>statistics-channels</command> statement
declares communication channels to be used by system
administrators to get access to statistics information of
the name server.
</para>
<para>
The <command>statistics-channels</command> statement
declares communication channels to be used by system
administrators to get access to statistics information of
the name server.
</para>
<para>
This statement intends to be flexible to support multiple
communication protocols in the future, but currently only
HTTP access is supported.
It requires that BIND 9 be compiled with libxml2 and/or
json-c (also known as libjson0); the
<command>statistics-channels</command> statement is
still accepted even if it is built without the library,
but any HTTP access will fail with an error.
</para>
<para>
This statement intends to be flexible to support multiple
communication protocols in the future, but currently only
HTTP access is supported.
It requires that BIND 9 be compiled with libxml2 and/or
json-c (also known as libjson0); the
<command>statistics-channels</command> statement is
still accepted even if it is built without the library,
but any HTTP access will fail with an error.
</para>
<para>
An <command>inet</command> control channel is a TCP socket
listening at the specified <command>ip_port</command> on the
specified <command>ip_addr</command>, which can be an IPv4 or IPv6
address. An <command>ip_addr</command> of <literal>*</literal>
(asterisk) is
interpreted as the IPv4 wildcard address; connections will be
accepted on any of the system's IPv4 addresses.
To listen on the IPv6 wildcard address,
use an <command>ip_addr</command> of <literal>::</literal>.
</para>
<para>
An <command>inet</command> control channel is a TCP socket
listening at the specified <command>ip_port</command> on the
specified <command>ip_addr</command>, which can be an IPv4 or IPv6
address. An <command>ip_addr</command> of <literal>*</literal>
(asterisk) is
interpreted as the IPv4 wildcard address; connections will be
accepted on any of the system's IPv4 addresses.
To listen on the IPv6 wildcard address,
use an <command>ip_addr</command> of <literal>::</literal>.
</para>
<para>
If no port is specified, port 80 is used for HTTP channels.
The asterisk "<literal>*</literal>" cannot be used for
<command>ip_port</command>.
</para>
<para>
If no port is specified, port 80 is used for HTTP channels.
The asterisk "<literal>*</literal>" cannot be used for
<command>ip_port</command>.
</para>
<para>
The attempt of opening a statistics channel is
restricted by the optional <command>allow</command> clause.
Connections to the statistics channel are permitted based on the
<command>address_match_list</command>.
If no <command>allow</command> clause is present,
<command>named</command> accepts connection
attempts from any address; since the statistics may
contain sensitive internal information, it is highly
recommended to restrict the source of connection requests
appropriately.
</para>
<para>
The attempt of opening a statistics channel is
restricted by the optional <command>allow</command> clause.
Connections to the statistics channel are permitted based on the
<command>address_match_list</command>.
If no <command>allow</command> clause is present,
<command>named</command> accepts connection
attempts from any address; since the statistics may
contain sensitive internal information, it is highly
recommended to restrict the source of connection requests
appropriately.
</para>
<para>
If no <command>statistics-channels</command> statement is present,
<command>named</command> will not open any communication channels.
</para>
<para>
If no <command>statistics-channels</command> statement is present,
<command>named</command> will not open any communication channels.
</para>
<para>
The statistics are available in various formats and views
depending on the URI used to access them. For example, if
the statistics channel is configured to listen on 127.0.0.1
port 8888, then the statistics are accessible in XML format at
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/">http://127.0.0.1:8888/</link> or
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml">http://127.0.0.1:8888/xml</link>. A CSS file is
included which can format the XML statistics into tables
when viewed with a stylesheet-capable browser, and into
charts and graphs using the Google Charts API when using a
javascript-capable browser.
</para>
<para>
The statistics are available in various formats and views
depending on the URI used to access them. For example, if
the statistics channel is configured to listen on 127.0.0.1
port 8888, then the statistics are accessible in XML format at
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/">http://127.0.0.1:8888/</link> or
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml">http://127.0.0.1:8888/xml</link>. A CSS file is
included which can format the XML statistics into tables
when viewed with a stylesheet-capable browser, and into
charts and graphs using the Google Charts API when using a
javascript-capable browser.
</para>
<para>
Broken-out subsets of the statistics can be viewed at
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/status">http://127.0.0.1:8888/xml/v3/status</link>
(server uptime and last reconfiguration time),
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/server">http://127.0.0.1:8888/xml/v3/server</link>
(server and resolver statistics),
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/zones">http://127.0.0.1:8888/xml/v3/zones</link>
(zone statistics),
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/net">http://127.0.0.1:8888/xml/v3/net</link>
(network status and socket statistics),
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/mem">http://127.0.0.1:8888/xml/v3/mem</link>
(memory manager statistics),
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/tasks">http://127.0.0.1:8888/xml/v3/tasks</link>
(task manager statistics), and
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://127.0.0.1:8888/xml/v3/traffic">http://127.0.0.1:8888/xm