mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-22 18:19:42 +00:00
Code Issues Releases Wiki Activity
bind/doc/arm/logging-categories.inc.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

121 lines
5.8 KiB
ReStructuredText
Raw Normal View History

Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
Update the copyright information in all files in the repository This commit converts the license handling to adhere to the REUSE specification. It specifically: 1. Adds used licnses to LICENSES/ directory 2. Add "isc" template for adding the copyright boilerplate 3. Changes all source files to include copyright and SPDX license header, this includes all the C sources, documentation, zone files, configuration files. There are notes in the doc/dev/copyrights file on how to add correct headers to the new files. 4. Handle the rest that can't be modified via .reuse/dep5 file. The binary (or otherwise unmodifiable) files could have license places next to them in <foo>.license file, but this would lead to cluttered repository and most of the files handled in the .reuse/dep5 file are system test files.
2021-06-03 08:37:05 +02:00
..
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
.. SPDX-License-Identifier: MPL-2.0
Update the copyright information in all files in the repository This commit converts the license handling to adhere to the REUSE specification. It specifically: 1. Adds used licnses to LICENSES/ directory 2. Add "isc" template for adding the copyright boilerplate 3. Changes all source files to include copyright and SPDX license header, this includes all the C sources, documentation, zone files, configuration files. There are notes in the doc/dev/copyrights file on how to add correct headers to the new files. 4. Handle the rest that can't be modified via .reuse/dep5 file. The binary (or otherwise unmodifiable) files could have license places next to them in <foo>.license file, but this would lead to cluttered repository and most of the files handled in the .reuse/dep5 file are system test files.
2021-06-03 08:37:05 +02:00
..
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
.. This Source Code Form is subject to the terms of the Mozilla Public
.. License, v. 2.0. If a copy of the MPL was not distributed with this
Fix typos and change http to https Fixed minor typographical errors and changed URLs from "http" to "https" where appropriate.
2020-09-14 21:04:19 +00:00
.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
Update the copyright information in all files in the repository This commit converts the license handling to adhere to the REUSE specification. It specifically: 1. Adds used licnses to LICENSES/ directory 2. Add "isc" template for adding the copyright boilerplate 3. Changes all source files to include copyright and SPDX license header, this includes all the C sources, documentation, zone files, configuration files. There are notes in the doc/dev/copyrights file on how to add correct headers to the new files. 4. Handle the rest that can't be modified via .reuse/dep5 file. The binary (or otherwise unmodifiable) files could have license places next to them in <foo>.license file, but this would lead to cluttered repository and most of the files handled in the .reuse/dep5 file are system test files.
2021-06-03 08:37:05 +02:00
..
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
.. See the COPYRIGHT file distributed with this work for additional
.. information regarding copyright ownership.
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
``client``
Processing of client requests.
``cname``
Various text edits and fixes to the documentation
2020-06-08 15:33:45 +00:00
Name servers that are skipped for being a CNAME rather than A/AAAA records.
Remove links from logging category names Some logging categories have the same names as configuration statements. This caused some category names to be replaced with links to statement definitions, which confuses util/check-categories.sh script.
2022-07-04 08:39:28 +02:00
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
``config``
Configuration file parsing and processing.
Remove links from logging category names Some logging categories have the same names as configuration statements. This caused some category names to be replaced with links to statement definitions, which confuses util/check-categories.sh script.
2022-07-04 08:39:28 +02:00
``database``
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
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.
``dispatch``
Dispatching of incoming packets to the server modules where they are to be processed.
``dnssec``
DNSSEC and TSIG protocol processing.
Remove links from logging category names Some logging categories have the same names as configuration statements. This caused some category names to be replaced with links to statement definitions, which confuses util/check-categories.sh script.
2022-07-04 08:39:28 +02:00
``dnstap``
The :any:`dnstap` DNS traffic capture system.
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
``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.
Remove trailing whitespace from all text files I've used the following command to remove the trailing whitespace for all tracked text files: git grep -Il '' | xargs sed -i 's/[ \t]*$//'
2023-06-07 16:00:00 +02:00
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
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.
Remove trailing whitespace from all text files I've used the following command to remove the trailing whitespace for all tracked text files: git grep -Il '' | xargs sed -i 's/[ \t]*$//'
2023-06-07 16:00:00 +02:00
Hyperlink program names to their manual pages Use the new role :iscman: to replace all occurences or ``binary`` with :iscman:`binary`, creating a hyperlink to the manual page. Generated using: find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done Additional hand-edits were done mainly around filter-aaaa and filter-a which are program names and and option names at the same time. Couple more edits was neede to fix .rst syntax broken by automatic replacement.
2022-03-03 22:17:04 +01:00
Note: eventually :iscman:`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.
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
``general``
Fix various typos in the documentation Generally, the issues fixed here are missing articles, wrong articles and double articles. We especially like "the the".
2020-12-16 10:24:01 +01:00
A catch-all for many things that still are not classified into categories.
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
``lame-servers``
Misconfigurations in remote servers, discovered by BIND 9 when trying to query those servers during resolution.
``network``
Network operations.
Manual fixups for new hyperlinks It turns out that many manual edits were required: - Heading underlines were too short because :any:`` is longer than ```` - Some statement names clashed with manually defined _link_anchors (notify, trust-anchors etc.) - Zone types are defined like "type primary" in the internal grammar and that caused mayhem in the replacement script as it took "type" and individual types ("primary", "secondary") as separate statements. For that reason :any:`primary` had to be manually replaced with :any:`primary <type primary>` where appropriate. - Sometimes option name is also the same as a value name (e.g. "notify") and then it did not make sense to do the replacement.
2022-07-01 12:29:18 +02:00
``notify``
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
The NOTIFY protocol.
``nsid``
NSID options received from upstream servers.
``queries``
Fix various typos in the documentation Generally, the issues fixed here are missing articles, wrong articles and double articles. We especially like "the the".
2020-12-16 10:24:01 +01:00
A location where queries should be logged.
Remove trailing whitespace from all text files I've used the following command to remove the trailing whitespace for all tracked text files: git grep -Il '' | xargs sed -i 's/[ \t]*$//'
2023-06-07 16:00:00 +02:00
Add hyperlinks to all unique statement names This shell script added hyperlinks to all unique statement names: UNIQSTATEMENTS=$(\ sort \ <(git grep '.. namedconf:statement::' '*.rst' | sed -e 's/^.*:: //') \ <(git grep '.. rndcconf:statement::' '*.rst' | sed -e 's/^.*:: //') \ | uniq --unique) ARMFILES=$(git ls-files 'doc/*.rst' | grep -v 'doc/man') for STATEMENT in $UNIQSTATEMENTS; \ do sed -i -e "s/\`\`$STATEMENT\`\`/:any:\`$STATEMENT\`/g" $ARMFILES; \ done This needs manual cleanup (see next commit) to fix syntax errors.
2022-07-01 12:29:18 +02:00
At startup, specifying the category ``queries`` also enables query logging unless the :any:`querylog` option has been specified.
Remove trailing whitespace from all text files I've used the following command to remove the trailing whitespace for all tracked text files: git grep -Il '' | xargs sed -i 's/[ \t]*$//'
2023-06-07 16:00:00 +02:00
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
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``
Remove trailing whitespace from all text files I've used the following command to remove the trailing whitespace for all tracked text files: git grep -Il '' | xargs sed -i 's/[ \t]*$//'
2023-06-07 16:00:00 +02:00
Various text edits and fixes to the documentation
2020-06-08 15:33:45 +00:00
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.
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
``query-errors``
Information about queries that resulted in some failure.
Remove links from logging category names Some logging categories have the same names as configuration statements. This caused some category names to be replaced with links to statement definitions, which confuses util/check-categories.sh script.
2022-07-04 08:39:28 +02:00
``rate-limit``
Various text edits and fixes to the documentation
2020-06-08 15:33:45 +00:00
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 level 1 and higher.
Remove trailing whitespace from all text files I've used the following command to remove the trailing whitespace for all tracked text files: git grep -Il '' | xargs sed -i 's/[ \t]*$//'
2023-06-07 16:00:00 +02:00
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
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``
Update logging-categories.rst and reference.rst Remove references to "blacklist" and "whitelist"
2020-06-15 17:01:37 +00:00
Information about RPZ PASSTHRU policy activity. This category allows pre-approved policy activity to be logged into a dedicated channel.
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
``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.
Add a logging category for TLS pre-master secrets TLS pre-master secrets will be dumped to disk using the logging framework provided by libisc. Add a new logging category for this type of debugging data in order to enable exporting it to a dedicated channel. Derive the name of the new category from the name of the relevant environment variable, SSLKEYLOGFILE.
2021-12-22 18:17:26 +01:00
``sslkeylog``
TLS pre-master secrets (for debugging purposes).
Remove links from logging category names Some logging categories have the same names as configuration statements. This caused some category names to be replaced with links to statement definitions, which confuses util/check-categories.sh script.
2022-07-04 08:39:28 +02:00
``trust-anchor-telemetry``
:any:`trust-anchor-telemetry` requests received by :iscman:`named`.
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
``unmatched``
Add hyperlinks to all unique statement names This shell script added hyperlinks to all unique statement names: UNIQSTATEMENTS=$(\ sort \ <(git grep '.. namedconf:statement::' '*.rst' | sed -e 's/^.*:: //') \ <(git grep '.. rndcconf:statement::' '*.rst' | sed -e 's/^.*:: //') \ | uniq --unique) ARMFILES=$(git ls-files 'doc/*.rst' | grep -v 'doc/man') for STATEMENT in $UNIQSTATEMENTS; \ do sed -i -e "s/\`\`$STATEMENT\`\`/:any:\`$STATEMENT\`/g" $ARMFILES; \ done This needs manual cleanup (see next commit) to fix syntax errors.
2022-07-01 12:29:18 +02:00
Messages that :iscman:`named` was unable to determine the class of, or for which there was no matching :any:`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 :any:`null` channel.
Grammar, clarity, and content fixes in reference.rst Also converted logging-categories.rst from a table to text and adjusted the util/check-categories.sh script.
2020-05-14 22:19:00 +00:00
``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.
Reference in New Issue Copy Permalink