Merge branch 'sgoldlust-1826-various-text-edits-needed-in-bind-arm-patch-99571' into 'master'

Text edits in reference.rst

See merge request isc-projects/bind9!3569
This commit is contained in:
Ondřej Surý 2020-06-01 07:32:40 +00:00
commit 3138bdf406
6 changed files with 1664 additions and 2040 deletions

View file

@ -67,8 +67,8 @@ An Authoritative-only Name Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This sample configuration is for an authoritative-only server that is
the master server for "``example.com``" and a slave for the subdomain
"``eng.example.com``".
the primary (master) server for ``example.com`` and a secondary (slave) server for the subdomain
``eng.example.com``.
::
@ -117,7 +117,7 @@ Load Balancing
A primitive form of load balancing can be achieved in the DNS by using
multiple records (such as multiple A records) for one name.
For example, if you have three HTTP servers with network addresses of
For example, assuming three HTTP servers with network addresses of
10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the following
means that clients will connect to each machine one third of the time:
@ -131,14 +131,14 @@ means that clients will connect to each machine one third of the time:
| | 600 | IN | A | 10.0.0.3 |
+-----------+------+----------+----------+----------------------------+
When a resolver queries for these records, BIND will rotate them and
respond to the query with the records in a different order. In the
example above, clients will randomly receive records in the order 1, 2,
3; 2, 3, 1; and 3, 1, 2. Most clients will use the first record returned
When a resolver queries for these records, BIND rotates them and
responds to the query with the records in a different order. In the
example above, clients randomly receive records in the order 1, 2,
3; 2, 3, 1; and 3, 1, 2. Most clients use the first record returned
and discard the rest.
For more detail on ordering responses, check the ``rrset-order``
sub-statement in the ``options`` statement, see :ref:`rrset_ordering`.
sub-statement in the ``options`` statement; see :ref:`rrset_ordering`.
.. _ns_operations:
@ -150,7 +150,7 @@ Name Server Operations
Tools for Use With the Name Server Daemon
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes several indispensable diagnostic, administrative
This section describes several indispensable diagnostic, administrative,
and monitoring tools available to the system administrator for
controlling and debugging the name server daemon.
@ -159,7 +159,7 @@ controlling and debugging the name server daemon.
Diagnostic Tools
^^^^^^^^^^^^^^^^
The ``dig``, ``host``, and ``nslookup`` programs are all command line
The ``dig``, ``host``, and ``nslookup`` programs are all command-line
tools for manually querying name servers. They differ in style and
output format.
@ -198,7 +198,7 @@ output format.
``nslookup [-option][ [host-to-find]|[-[server]] ]``
Interactive mode is entered when no arguments are given (the default
name server will be used) or when the first argument is a hyphen
name server is used) or when the first argument is a hyphen
(``-``) and the second argument is the host name or Internet address of
a name server.
@ -231,13 +231,13 @@ server.
``named-checkzone [-djqvD][-c class][-o output][-t directory][-w directory][-k (ignore|warn|fail)][-n (ignore|warn|fail)][-W (ignore|warn)] zone [filename]``
``named-compilezone``
Similar to ``named-checkzone,`` but it always dumps the zone content
This tool is similar to ``named-checkzone,`` but it always dumps the zone content
to a specified file (typically in a different format).
``rndc``
The remote name daemon control (``rndc``) program allows the system
administrator to control the operation of a name server. If you run
``rndc`` without any options, it will display a usage message as
administrator to control the operation of a name server. If ``rndc`` is run
without any options, it will display a usage message as
follows:
``rndc [-c config][-s server][-p port][-y key] command [command...]``
@ -257,8 +257,8 @@ server.
described in :ref:`controls_statement_definition_and_usage`.
The format of the configuration file is similar to that of
``named.conf``, but limited to only four statements, the ``options``,
``key``, ``server`` and ``include`` statements. These statements are
``named.conf``, but is limited to only four statements: the ``options``,
``key``, ``server``, and ``include`` statements. These statements are
what associate the secret keys to the servers with which they are
meant to be shared. The order of statements is not significant.
@ -278,9 +278,9 @@ server.
be hierarchical; thus, a string like "``rndc_key``" is a valid name.
The ``key`` statement has two clauses: ``algorithm`` and ``secret``.
While the configuration parser will accept any string as the argument
to algorithm, currently only the strings "``hmac-md5``",
"``hmac-sha1``", "``hmac-sha224``", "``hmac-sha256``",
"``hmac-sha384``" and "``hmac-sha512``" have any meaning. The secret
to the algorithm, currently only the strings ``hmac-md5``,
``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``,
``hmac-sha384``, and ``hmac-sha512`` have any meaning. The secret
is a Base64 encoded string as specified in :rfc:`3548`.
The ``server`` statement associates a key defined using the ``key``
@ -304,13 +304,13 @@ server.
default-key rndc_key;
};
This file, if installed as ``/etc/rndc.conf``, would allow the
This file, if installed as ``/etc/rndc.conf``, allows the
command:
``$ rndc reload``
to connect to 127.0.0.1 port 953 and cause the name server to reload,
if a name server on the local machine were running with following
if a name server on the local machine is running with the following
controls statements:
::
@ -320,12 +320,12 @@ server.
allow { localhost; } keys { rndc_key; };
};
and it had an identical key statement for ``rndc_key``.
and it has an identical key statement for ``rndc_key``.
Running the ``rndc-confgen`` program will conveniently create a
``rndc.conf`` file for you, and also display the corresponding
``controls`` statement that you need to add to ``named.conf``.
Alternatively, you can run ``rndc-confgen -a`` to set up a
Running the ``rndc-confgen`` program conveniently creates a
``rndc.conf`` file, and also displays the corresponding
``controls`` statement needed to add to ``named.conf``.
Alternatively, it is possible to run ``rndc-confgen -a`` to set up a
``rndc.key`` file and not modify ``named.conf`` at all.
Signals

View file

@ -18,165 +18,112 @@
See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
+----------------------------+----------------------------------------------------+
| ``client`` | Processing of client requests. |
+----------------------------+----------------------------------------------------+
| ``cname`` | Logs nameservers that are skipped due to them |
| | being a CNAME rather than A / AAAA records. |
+----------------------------+----------------------------------------------------+
| ``config`` | Configuration file parsing and processing. |
+----------------------------+----------------------------------------------------+
| ``database`` | Messages relating to the databases used internally |
| | by the name server to store zone and cache data. |
+----------------------------+----------------------------------------------------+
| ``default`` | The default category defines the logging options |
| | for those categories where no specific |
| | configuration has been defined. |
+----------------------------+----------------------------------------------------+
| ``delegation-only`` | Delegation only. Logs queries that have been |
| | forced to NXDOMAIN as the result of a |
| | delegation-only zone or a ``delegation-only`` in a |
| | forward, hint or stub zone declaration. |
+----------------------------+----------------------------------------------------+
| ``dispatch`` | Dispatching of incoming packets to the server |
| | modules where they are to be processed. |
+----------------------------+----------------------------------------------------+
| ``dnssec`` | DNSSEC and TSIG protocol processing. |
+----------------------------+----------------------------------------------------+
| ``dnstap`` | The "dnstap" DNS traffic capture system. |
+----------------------------+----------------------------------------------------+
| ``edns-disabled`` | Log queries that have been forced to use plain DNS |
| | due to timeouts. This is often due to the remote |
| | servers not being :rfc:`1034` compliant (not |
| | always returning FORMERR or similar to EDNS |
| | queries and other extensions to the DNS when |
| | they are not understood). In other words, this |
| | is targeted at servers that fail to respond to DNS |
| | queries that they don't understand. |
| | |
| | Note: the log message can also be due to packet |
| | loss. Before reporting servers for non-:rfc:`1034` |
| | compliance they should be re-tested to determine |
| | the nature of the non-compliance. This testing |
| | should prevent or reduce the number of |
| | false-positive reports. |
| | |
| | Note: eventually ``named`` will have to stop |
| | treating such timeouts as due to :rfc:`1034` non |
| | compliance and start treating it as plain packet |
| | loss. Falsely classifying packet loss as due to |
| | :rfc:`1034` non compliance impacts on DNSSEC |
| | validation which requires EDNS for the DNSSEC |
| | records to be returned. |
+----------------------------+----------------------------------------------------+
| ``general`` | The catch-all. Many things still aren't classified |
| | into categories, and they all end up here. |
+----------------------------+----------------------------------------------------+
| ``lame-servers`` | Lame servers. These are misconfigurations in |
| | remote servers, discovered by BIND 9 when trying |
| | to query those servers during resolution. |
+----------------------------+----------------------------------------------------+
| ``network`` | Network operations. |
+----------------------------+----------------------------------------------------+
| ``notify`` | The NOTIFY protocol. |
+----------------------------+----------------------------------------------------+
| ``nsid`` | NSID options received from upstream servers. |
+----------------------------+----------------------------------------------------+
| ``queries`` | Specify where queries should be logged to. |
| | |
| | At startup, specifying the category ``queries`` |
| | will also enable query logging unless ``querylog`` |
| | option has been specified. |
| | |
| | The query log entry first reports a client object |
| | identifier in @0x<hexadecimal-number> format. |
| | Next, it reports the client's IP address and port |
| | number, and the query name, class and type. Next, |
| | it reports whether the Recursion Desired flag was |
| | set (+ if set, - if not set), whether the query |
| | was signed (S), whether EDNS was in use along with |
| | the EDNS version number (E(#)), whether TCP was |
| | used (T), whether DO (DNSSEC Ok) was set (D), |
| | whether CD (Checking Disabled) was set (C), |
| | whether a valid DNS Server COOKIE was received |
| | (V), and whether a DNS COOKIE option without a |
| | valid Server COOKIE was present (K). After this |
| | the destination address the query was sent to is |
| | reported. Finally, if any CLIENT-SUBNET option was |
| | present in the client query, it is included in |
| | square brackets in the format [ECS |
| | address/source/scope]. |
| | |
| | ``client 127.0.0.1#62536 (www.example.com):`` |
| | ``query: www.example.com IN AAAA +SE`` |
| | |
| | ``client ::1#62537 (www.example.net):`` |
| | ``query: www.example.net IN AAAA -SE`` |
| | |
| | (The first part of this log message, showing the |
| | client address/port number and query name, is |
| | repeated in all subsequent log messages related to |
| | the same query.) |
+----------------------------+----------------------------------------------------+
| ``query-errors`` | Information about queries that resulted in some |
| | failure. |
+----------------------------+----------------------------------------------------+
| ``rate-limit`` | The start, periodic, and final notices of the rate |
| | limiting of a stream of responses are logged at |
| | ``info`` severity in this category. These messages |
| | include a hash value of the domain name of the |
| | response and the name itself, except when there is |
| | insufficient memory to record the name for the |
| | final notice The final notice is normally delayed |
| | until about one minute after rate limit stops. A |
| | lack of memory can hurry the final notice, in |
| | which case it starts with an asterisk (*). Various |
| | internal events are logged at debug 1 level and |
| | higher. |
| | |
| | Rate limiting of individual requests is logged in |
| | the ``query-errors`` category. |
+----------------------------+----------------------------------------------------+
| ``resolver`` | DNS resolution, such as the recursive lookups |
| | performed on behalf of clients by a caching name |
| | server. |
+----------------------------+----------------------------------------------------+
| ``rpz`` | Information about errors in response policy zone |
| | files, rewritten responses, and at the highest |
| | ``debug`` levels, mere rewriting attempts. |
+----------------------------+----------------------------------------------------+
| ``rpz-passthru`` | Information about RPZ PASSTHRU policy activity. |
| | This category allows the whitelist policy activity |
| | to be logged into a dedicated channel. |
+----------------------------+----------------------------------------------------+
| ``security`` | Approval and denial of requests. |
+----------------------------+----------------------------------------------------+
| ``serve-stale`` | Whether or not a stale answer is used following a |
| | resolver failure. |
+----------------------------+----------------------------------------------------+
| ``spill`` | Logs queries that have been terminated, either by |
| | dropping or responding with SERVFAIL, as a result |
| | of a fetchlimit quota being exceeded. |
+----------------------------+----------------------------------------------------+
| ``trust-anchor-telemetry`` | Logs trust-anchor-telemetry requests received by |
| | named. |
+----------------------------+----------------------------------------------------+
| ``unmatched`` | Messages that ``named`` was unable to determine |
| | the class of or for which there was no matching |
| | ``view``. A one line summary is also logged to the |
| | ``client`` category. This category is best sent to |
| | a file or stderr, by default it is sent to the |
| | ``null`` channel. |
+----------------------------+----------------------------------------------------+
| ``update`` | Dynamic updates. |
+----------------------------+----------------------------------------------------+
| ``update-security`` | Approval and denial of update requests. |
| | |
+----------------------------+----------------------------------------------------+
| ``xfer-in`` | Zone transfers the server is receiving. |
+----------------------------+----------------------------------------------------+
| ``xfer-out`` | Zone transfers the server is sending. |
+----------------------------+----------------------------------------------------+
| ``zoneload`` | Loading of zones and creation of automatic empty |
| | zones. |
+----------------------------+----------------------------------------------------+
``client``
Processing of client requests.
``cname``
Nameservers that are skipped due to them being a CNAME rather than A / AAAA records.
``config``
Configuration file parsing and processing.
``database``
Messages relating to the databases used internally by the name server to store zone and cache data.
``default``
Logging options for those categories where no specific configuration has been defined.
``delegation-only``
Queries that have been forced to NXDOMAIN as the result of a delegation-only zone or a ``delegation-only`` in a forward, hint, or stub zone declaration.
``dispatch``
Dispatching of incoming packets to the server modules where they are to be processed.
``dnssec``
DNSSEC and TSIG protocol processing.
``dnstap``
The "dnstap" DNS traffic capture system.
``edns-disabled``
Log queries that have been forced to use plain DNS due to timeouts. This is often due to the remote servers not being :rfc:`1034`-compliant (not always returning FORMERR or similar to EDNS queries and other extensions to the DNS when they are not understood). In other words, this is targeted at servers that fail to respond to DNS queries that they don't understand.
Note: the log message can also be due to packet loss. Before reporting servers for non-:rfc:`1034` compliance they should be re-tested to determine the nature of the non-compliance. This testing should prevent or reduce the number of false-positive reports.
Note: eventually ``named`` will have to stop treating such timeouts as due to :rfc:`1034` non-compliance and start treating it as plain packet loss. Falsely classifying packet loss as due to :rfc:`1034` non-compliance impacts DNSSEC validation, which requires EDNS for the DNSSEC records to be returned.
``general``
Catch-all for many things that still are not classified into categories.
``lame-servers``
Misconfigurations in remote servers, discovered by BIND 9 when trying to query those servers during resolution.
``network``
Network operations.
``notify``
The NOTIFY protocol.
``nsid``
NSID options received from upstream servers.
``queries``
Location where queries should be logged.
At startup, specifying the category ``queries`` also enables query logging unless the ``querylog`` option has been specified.
The query log entry first reports a client object identifier in @0x<hexadecimal-number> format. Next, it reports the client's IP address and port number, and the query name, class, and type. Next, it reports whether the Recursion Desired flag was set (+ if set, - if not set), whether the query was signed (S), whether EDNS was in use along with the EDNS version number (E(#)), whether TCP was used (T), whether DO (DNSSEC Ok) was set (D), whether CD (Checking Disabled) was set (C), whether a valid DNS Server COOKIE was received (V), and whether a DNS COOKIE option without a valid Server COOKIE was present (K). After this, the destination address the query was sent to is reported. Finally, if any CLIENT-SUBNET option was present in the client query, it is included in square brackets in the format [ECS address/source/scope].
``client 127.0.0.1#62536 (www.example.com):``
``query: www.example.com IN AAAA +SE``
``client ::1#62537 (www.example.net):``
``query: www.example.net IN AAAA -SE``
(The first part of this log message, showing the client address/port number and query name, is repeated in all subsequent log messages related to the same query.)
``query-errors``
Information about queries that resulted in some failure.
``rate-limit``
Start, periodic, and final notices of the rate limiting of a stream of responses that are logged at ``info`` severity in this category. These messages include a hash value of the domain name of the response and the name itself, except when there is insufficient memory to record the name for the final notice. The final notice is normally delayed until about one minute after rate limiting stops. A lack of memory can hurry the final notice, which is indicated by an initial asterisk (*). Various internal events are logged at debug 1 level and higher.
Rate limiting of individual requests is logged in the ``query-errors`` category.
``resolver``
DNS resolution, such as the recursive lookups performed on behalf of clients by a caching name server.
``rpz``
Information about errors in response policy zone files, rewritten responses, and, at the highest ``debug`` levels, mere rewriting attempts.
``rpz-passthru``
Information about RPZ PASSTHRU policy activity. This category allows whitelist policy activity to be logged into a dedicated channel.
``security``
Approval and denial of requests.
``serve-stale``
Indication of whether a stale answer is used following a resolver failure.
``spill``
Queries that have been terminated, either by dropping or responding with SERVFAIL, as a result of a fetchlimit quota being exceeded.
``trust-anchor-telemetry``
Trust-anchor-telemetry requests received by ``named``.
``unmatched``
Messages that ``named`` was unable to determine the class of, or for which there was no matching ``view``. A one-line summary is also logged to the ``client`` category. This category is best sent to a file or stderr; by default it is sent to the ``null`` channel.
``update``
Dynamic updates.
``update-security``
Approval and denial of update requests.
``xfer-in``
Zone transfers the server is receiving.
``xfer-out``
Zone transfers the server is sending.
``zoneload``
Loading of zones and creation of automatic empty zones.

View file

@ -37,7 +37,7 @@ added in the future.
The only plugin currently included in BIND is ``filter-aaaa.so``, which
replaces the ``filter-aaaa`` feature that previously existed natively as
part of ``named``. The code for this feature has been removed from
``named``, and can no longer be configured using standard ``named.conf``
``named`` and can no longer be configured using standard ``named.conf``
syntax, but linking in the ``filter-aaaa.so`` plugin provides identical
functionality.
@ -59,7 +59,7 @@ indicates that this is a query plugin.
Multiple ``plugin`` statements can be specified, to load different
plugins or multiple instances of the same plugin.
*parameters* are passed as an opaque string to the plugin's initialization
``parameters`` are passed as an opaque string to the plugin's initialization
routine. Configuration syntax will differ depending on the module.
Developing Plugins

File diff suppressed because it is too large Load diff

View file

@ -29,11 +29,11 @@ Hardware Requirements
---------------------
DNS hardware requirements have traditionally been quite modest. For many
installations, servers that have been pensioned off from active duty
installations, servers that have been retired from active duty
have performed admirably as DNS servers.
The DNSSEC features of BIND 9 may prove to be quite CPU intensive
however, so organizations that make heavy use of these features may wish
However, the DNSSEC features of BIND 9 may prove to be quite CPU intensive,
so organizations that make heavy use of these features may wish
to consider larger systems for these applications. BIND 9 is fully
multithreaded, allowing full utilization of multiprocessor systems for
installations that need it.
@ -43,9 +43,9 @@ installations that need it.
CPU Requirements
----------------
CPU requirements for BIND 9 range from i386-class machines for serving
of static zones without caching, to enterprise-class machines if you
intend to process many dynamic updates and DNSSEC signed zones, serving
CPU requirements for BIND 9 range from i386-class machines, for serving
static zones without caching, to enterprise-class machines
to process many dynamic updates and DNSSEC-signed zones, serving
many thousands of queries per second.
.. _mem_req:
@ -53,11 +53,11 @@ many thousands of queries per second.
Memory Requirements
-------------------
The memory of the server has to be large enough to fit the cache and
zones loaded off disk. The ``max-cache-size`` option can be used to
Server memory must be sufficient to hold both the cache and the
zones loaded from disk. The ``max-cache-size`` option can be used to
limit the amount of memory used by the cache, at the expense of reducing
cache hit rates and causing more DNS traffic. It is still good practice
to have enough memory to load all zone and cache data into memory
to have enough memory to load all zone and cache data into memory;
unfortunately, the best way to determine this for a given installation
is to watch the name server in operation. After a few weeks the server
process should reach a relatively stable size where entries are expiring
@ -69,9 +69,9 @@ Name Server Intensive Environment Issues
----------------------------------------
For name server intensive environments, there are two alternative
configurations that may be used. The first is where clients and any
configurations that may be used. The first is one where clients and any
second-level internal name servers query a main name server, which has
enough memory to build a large cache. This approach minimizes the
enough memory to build a large cache; this approach minimizes the
bandwidth used by external name lookups. The second alternative is to
set up second-level internal name servers to make queries independently.
In this configuration, none of the individual machines needs to have as
@ -85,6 +85,6 @@ Supported Operating Systems
---------------------------
ISC BIND 9 compiles and runs on a large number of Unix-like operating
systems and on Microsoft Windows Server 2012 R2, 2016 and Windows 10.
systems and on Microsoft Windows Server 2012 R2, 2016, and Windows 10.
For an up-to-date list of supported systems, see the PLATFORMS.md file
in the top level directory of the BIND 9 source distribution.
in the top-level directory of the BIND 9 source distribution.

View file

@ -17,8 +17,7 @@ list1=$(
sort -u
)
list2=$(
awk '$1 == "|" && $3 == "|" && $NF == "|" && $2 ~ /^``.*``$/ { print $2 }' doc/arm/logging-categories.rst |
sed 's/``//g' |
sed -ne 's/^``\(.*\)``/\1/p' doc/arm/logging-categories.rst |
sort -u
)
status=0