mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-09-02 15:45:25 +00:00
Code Issues Releases Wiki Activity

Grammar, clarity, and content fixes in reference.rst

Browse Source 
Also converted logging-categories.rst from a table to text and adjusted
the util/check-categories.sh script.
This commit is contained in:
Suzanne Goldlust
2020-05-14 22:19:00 +00:00
committed by Ondřej Surý
parent c7264db658
commit 1e067c4d0b
3 changed files with 1527 additions and 1870 deletions
Download Patch File Download Diff File Expand all files Collapse all files

271
doc/arm/logging-categories.rst
View File

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

3123
doc/arm/reference.rst
View File

File diff suppressed because it is too large Load Diff

3
util/check-categories.sh
View File

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