From bc7dce5cebe07bf4dd4d1d5fc777bdaa64d95e1a Mon Sep 17 00:00:00 2001 From: Mark Andrews Date: Wed, 30 Sep 2015 12:56:31 +1000 Subject: [PATCH] split out logging-categories [RT #40844] (cherry picked from commit 6c4f9b5cf604f77de996e0066bf8b53fb880c3a6) --- doc/arm/Bv9ARM-book.xml | 350 +-------------------------------- doc/arm/logging-categories.xml | 349 ++++++++++++++++++++++++++++++++ util/check-categories.sh | 36 ++++ 3 files changed, 386 insertions(+), 349 deletions(-) create mode 100644 doc/arm/logging-categories.xml create mode 100644 util/check-categories.sh diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml index ad2fbe0adc..393af9393f 100644 --- a/doc/arm/Bv9ARM-book.xml +++ b/doc/arm/Bv9ARM-book.xml @@ -3997,355 +3997,7 @@ category notify { null; }; of the types of log information they contain. More categories may be added in future BIND releases. - - - - - - - - default - - - - The default category defines the logging - options for those categories where no specific - configuration has been - defined. - - - - - - general - - - - The catch-all. Many things still aren't - classified into categories, and they all end up here. - - - - - - database - - - - Messages relating to the databases used - internally by the name server to store zone and cache - data. - - - - - - security - - - - Approval and denial of requests. - - - - - - config - - - - Configuration file parsing and processing. - - - - - - resolver - - - - DNS resolution, such as the recursive - lookups performed on behalf of clients by a caching name - server. - - - - - - xfer-in - - - - Zone transfers the server is receiving. - - - - - - xfer-out - - - - Zone transfers the server is sending. - - - - - - notify - - - - The NOTIFY protocol. - - - - - - client - - - - Processing of client requests. - - - - - - 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. - - - - - - network - - - - Network operations. - - - - - - update - - - - Dynamic updates. - - - - - - update-security - - - - Approval and denial of update requests. - - - - - - 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 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), if the query was signed (S), - EDNS was in use (E), if TCP was used (T), if - DO (DNSSEC Ok) was set (D), or if CD (Checking - Disabled) was set (C). After this the - destination address the query was sent to is - reported. - - - - 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. - - - - - - dispatch - - - - Dispatching of incoming packets to the - server modules where they are to be processed. - - - - - - dnssec - - - - DNSSEC and TSIG protocol processing. - - - - - - lame-servers - - - - Lame servers. These are misconfigurations - in remote servers, discovered by BIND 9 when trying to - query those servers during resolution. - - - - - - 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. - - - - - - 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. - - - - - - RPZ - - - - Information about errors in response policy zone files, - rewritten responses, and at the highest - debug levels, mere rewriting - attempts. - - - - - - rate-limit - - - - (Only available when BIND 9 is - configured with the --enable-rrl - option at compile time.) - - - 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. - - - - - - cname - - - - Logs nameservers that are skipped due to them being - a CNAME rather than A / AAAA records. - - - - - - + The <command>query-errors</command> Category diff --git a/doc/arm/logging-categories.xml b/doc/arm/logging-categories.xml new file mode 100644 index 0000000000..5c8056ad82 --- /dev/null +++ b/doc/arm/logging-categories.xml @@ -0,0 +1,349 @@ + + + + + + + + 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. + + + + + + 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. + + + + + + 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 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), if the query was signed (S), + EDNS was in use (E), if TCP was used (T), if + DO (DNSSEC Ok) was set (D), or if CD (Checking + Disabled) was set (C). After this the + destination address the query was sent to is + reported. + + + + 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 + + + + (Only available when BIND 9 is + configured with the --enable-rrl + option at compile time.) + + + 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. + + + + + + security + + + + Approval and denial of requests. + + + + + + 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. + + + + + + diff --git a/util/check-categories.sh b/util/check-categories.sh new file mode 100644 index 0000000000..617bf51da6 --- /dev/null +++ b/util/check-categories.sh @@ -0,0 +1,36 @@ +list1=`grep LOGCATEGORY lib/*/include/*/*.h bin/named/include/named/*.h | +grep "#define.*(&" | +sed -e 's/.*LOGCATEGORY_\([A-Z_]*\).*/\1/' -e 's/^RRL$/rate-limit/' | +tr '[A-Z]' '[a-z]' | +tr _ - | sort -u` +list2=`sed -n 's;.*\(.*\);\1;p' doc/arm/logging-categories.xml | tr '[A-Z]' '[a-z]' | sort -u` +for i in $list1 +do + ok=no + for j in $list2 + do + if test $i = $j + then + ok=yes + fi + done + if test $ok = no + then + echo "$i missing from documentation." + fi +done +for i in $list2 +do + ok=no + for j in $list1 + do + if test $i = $j + then + ok=yes + fi + done + if test $ok = no + then + echo "$i not in code." + fi +done