BIND 10 trac1011, updated. c46b0bc28c22f2ae4b46c592f450e745774846d4 [1011] move Logging Message Format section after Logging configuration section
BIND 10 source code commits
bind10-changes at lists.isc.org
Fri Aug 12 13:21:34 UTC 2011
The branch, trac1011 has been updated
via c46b0bc28c22f2ae4b46c592f450e745774846d4 (commit)
via 7740b9810bc093a9083e8c3404afc627c8b78242 (commit)
from f6a1807c25d85a0ca762bfa276ebac4a3430e7c7 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit c46b0bc28c22f2ae4b46c592f450e745774846d4
Author: Jeremy C. Reed <jreed at ISC.org>
Date: Fri Aug 12 08:21:22 2011 -0500
[1011] move Logging Message Format section after Logging configuration section
commit 7740b9810bc093a9083e8c3404afc627c8b78242
Author: Jeremy C. Reed <jreed at ISC.org>
Date: Fri Aug 12 08:18:32 2011 -0500
[1011] many docbook tag additions, minor grammar, some clarifications and comments
-----------------------------------------------------------------------
Summary of changes:
doc/guide/bind10-guide.xml | 355 +++++++++++++++++++++++---------------------
1 files changed, 188 insertions(+), 167 deletions(-)
-----------------------------------------------------------------------
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index 5c8840b..9f3ee80 100644
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -1470,96 +1470,6 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<chapter id="logging">
<title>Logging</title>
-<!-- TODO: how to configure logging, logging destinations etc. -->
-
- <section>
- <title>Logging Message Format</title>
-
- <para>
- Each message written by BIND 10 to the configured logging
- destinations comprises a number of components that identify
- the origin of the message and, if the message indicates
- a problem, information about the problem that may be
- useful in fixing it.
- </para>
-
- <para>
- Consider the message below logged to a file:
- <screen>2011-06-15 13:48:22.034 ERROR [b10-resolver.asiolink]
- ASIODNS_OPENSOCK error 111 opening TCP socket to 127.0.0.1(53)</screen>
- </para>
-
- <para>
- Note: the layout of messages written to the system logging
- file (syslog) may be slightly different. This message has
- been split across two lines here for display reasons; in the
- logging file, it will appear on one line.)
- </para>
-
- <para>
- The log message comprises a number of components:
-
- <variablelist>
- <varlistentry>
- <term>2011-06-15 13:48:22.034</term>
-<!-- TODO: timestamp repeated even if using syslog? -->
- <listitem><para>
- The date and time at which the message was generated.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ERROR</term>
- <listitem><para>
- The severity of the message.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>[b10-resolver.asiolink]</term>
- <listitem><para>
- The source of the message. This comprises two components:
- the BIND 10 process generating the message (in this
- case, <command>b10-resolver</command>) and the module
- within the program from which the message originated
- (which in the example is the asynchronous I/O link
- module, asiolink).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ASIODNS_OPENSOCK</term>
- <listitem><para>
- The message identification. Every message in BIND 10
- has a unique identification, which can be used as an
- index into the <ulink
- url="bind10-messages.html"><citetitle>BIND 10 Messages
- Manual</citetitle></ulink> (<ulink
- url="http://bind10.isc.org/docs/bind10-messages.html"
- />) from which more information can be obtained.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>error 111 opening TCP socket to 127.0.0.1(53)</term>
- <listitem><para>
- A brief description of the cause of the problem.
- Within this text, information relating to the condition
- that caused the message to be logged will be included.
- In this example, error number 111 (an operating
- system-specific error number) was encountered when
- trying to open a TCP connection to port 53 on the
- local system (address 127.0.0.1). The next step
- would be to find out the reason for the failure by
- consulting your system's documentation to identify
- what error number 111 means.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- </section>
-
<section>
<title>Logging configuration</title>
@@ -1597,8 +1507,9 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<para>
The three most important elements of a logger configuration
- are the name (the component that is generating the
- messages), the severity (what to log), and the output_options
+ are the <option>name</option> (the component that is
+ generating the messages), the <option>severity</option>
+ (what to log), and the <option>output_options</option>
(where to log).
</para>
@@ -1610,48 +1521,62 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
Each logger in the system has a name, the name being that
of the component using it to log messages. For instance,
if you want to configure logging for the resolver module,
- you add an entry for a logger named 'Resolver'. This
+ you add an entry for a logger named <quote>Resolver</quote>. This
configuration will then be used by the loggers in the
Resolver module, and all the libraries used by it.
</para>
-<!-- TODO: how to know these names? -->
+<!-- TODO: later we will have a way to know names of all modules
+
+Right now you can only see what their names are if they are running
+(a simple 'help' without anything else in bindctl for instance).
+
+ -->
<para>
If you want to specify logging for one specific library
- within the module, you set the name to 'module.library'.
- For example, the logger used by the nameserver address
- store component has the full name of 'Resolver.nsas'. If
+ within the module, you set the name to
+ <replaceable>module.library</replaceable>. For example, the
+ logger used by the nameserver address store component
+ has the full name of <quote>Resolver.nsas</quote>. If
there is no entry in Logging for a particular library,
it will use the configuration given for the module.
-<!-- TODO: how to know these specific names? -->
+<!-- TODO: how to know these specific names?
+
+We will either have to document them or tell the administrator to
+specify module-wide logging and see what appears...
+
+-->
</para>
<para>
+<!-- TODO: severity has not been covered yet -->
+
To illustrate this, suppose you want the cache library
to log messages of severity DEBUG, and the rest of the
resolver code to log messages of severity INFO. To achieve
- this you specify two loggers, one with the name 'Resolver'
- and severity INFO, and one with the name 'Resolver.cache'
- with severity DEBUG. As there are no entries for other
- libraries (e.g. the nsas), they will use the configuration
- for the module ('Resolver'), so giving the desired
- behavior.
+ this you specify two loggers, one with the name
+ <quote>Resolver</quote> and severity INFO, and one with
+ the name <quote>Resolver.cache</quote> with severity
+ DEBUG. As there are no entries for other libraries (e.g.
+ the nsas), they will use the configuration for the module
+ (<quote>Resolver</quote>), so giving the desired behavior.
</para>
<para>
- One special case is that of a module name of '*', which
- is interpreted as 'any module'. You can set global logging
- options by using this, including setting the logging
- configuration for a library that is used by multiple
- modules (e.g. '*.config" specifies the configuration
- library code in whatever module is using it).
+ One special case is that of a module name of <quote>*</quote>
+ (asterisks), which is interpreted as <emphasis>any</emphasis>
+ module. You can set global logging options by using this,
+ including setting the logging configuration for a library
+ that is used by multiple modules (e.g. <quote>*.config</quote>
+ specifies the configuration library code in whatever
+ module is using it).
</para>
@@ -1661,13 +1586,15 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
configuration that might match a particular logger, the
specification with the more specific logger name takes
precedence. For example, if there are entries for for
- both '*' and 'Resolver', the resolver module - and all
- libraries it uses - will log messages according to the
- configuration in the second entry ('Resolver'). All other
- modules will use the configuration of the first entry
- ('*'). If there was also a configuration entry for
- 'Resolver.cache', the cache library within the resolver
- would use that in preference to the entry for 'Resolver'.
+ both <quote>*</quote> and <quote>Resolver</quote>, the
+ resolver module — and all libraries it uses —
+ will log messages according to the configuration in the
+ second entry (<quote>Resolver</quote>). All other modules
+ will use the configuration of the first entry
+ (<quote>*</quote>). If there was also a configuration
+ entry for <quote>Resolver.cache</quote>, the cache library
+ within the resolver would use that in preference to the
+ entry for <quote>Resolver</quote>.
</para>
@@ -1675,14 +1602,15 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
One final note about the naming. When specifying the
module name within a logger, use the name of the module
- as specified in bindctl, e.g. 'Resolver' for the resolver
- module, 'Xfrout' for the xfrout module etc. When the
- message is logged, the message will include the name of
- the logger generating the message, but with the module
+ as specified in <command>bindctl</command>, e.g.
+ <quote>Resolver</quote> for the resolver module,
+ <quote>Xfrout</quote> for the xfrout module, etc. When
+ the message is logged, the message will include the name
+ of the logger generating the message, but with the module
name replaced by the name of the process implementing
the module (so for example, a message generated by the
- 'Auth.cache' logger will appear in the output with a
- logger name of 'b10-auth.cache').
+ <quote>Auth.cache</quote> logger will appear in the output
+ with a logger name of <quote>b10-auth.cache</quote>).
</para>
@@ -1694,11 +1622,6 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<para>
This specifies the category of messages logged.
-
- </para>
-
- <para>
-
Each message is logged with an associated severity which
may be one of the following (in descending order of
severity):
@@ -1730,7 +1653,7 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
When the severity of a logger is set to one of these
values, it will only log messages of that severity, and
- the severities below it. The severity may also be set to
+ the severities above it. The severity may also be set to
NONE, in which case all messages from that logger are
inhibited.
@@ -1745,9 +1668,9 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<para>
- Each logger can have zero or more output_options. These
- specify where log messages are sent to. These are explained
- in detail below.
+ Each logger can have zero or more
+ <option>output_options</option>. These specify where log
+ messages are sent to. These are explained in detail below.
</para>
@@ -1766,14 +1689,17 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
When a logger's severity is set to DEBUG, this value
specifies what debug messages should be printed. It ranges
- from 0 (least verbose) to 99 (most verbose). The general
- classification of debug message types is
+ from 0 (least verbose) to 99 (most verbose).
+ </para>
-<!-- TODO: complete this sentence -->
- </para>
+<!-- TODO: complete this sentence:
-<!-- TODO; there's a ticket to determine these levels, see #1074 -->
+ The general classification of debug message types is
+
+TODO; there's a ticket to determine these levels, see #1074
+
+ -->
<para>
@@ -1788,13 +1714,15 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<para>
- If this is true, the output_options from the parent will
- be used. For example, if there are two loggers configured;
- 'Resolver' and 'Resolver.cache', and additive is true in
- the second, it will write the log messages not only to
- the destinations specified for 'Resolver.cache', but also
- to the destinations as specified in the output_options
- in the logger named Resolver'.
+ If this is true, the <option>output_options</option> from
+ the parent will be used. For example, if there are two
+ loggers configured; <quote>Resolver</quote> and
+ <quote>Resolver.cache</quote>, and <option>additive</option>
+ is true in the second, it will write the log messages
+ not only to the destinations specified for
+ <quote>Resolver.cache</quote>, but also to the destinations
+ as specified in the <option>output_options</option> in
+ the logger named <quote>Resolver</quote>.
<!-- TODO: check this -->
@@ -1809,9 +1737,10 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<para>
- The main settings for an output option are the 'destination'
- and a value called 'output', the meaning of which depends
- on the destination that is set.
+ The main settings for an output option are the
+ <option>destination</option> and a value called
+ <option>output</option>, the meaning of which depends on
+ the destination that is set.
</para>
@@ -1855,18 +1784,19 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<variablelist>
<varlistentry>
- <term>destination is 'console'</term>
+ <term><option>destination</option> is <quote>console</quote></term>
<listitem>
<simpara>
- The value of output must be one of 'stdout'
- (messages printed to standard output) or 'stderr'
- (messages printed to standard error).
+ The value of output must be one of <quote>stdout</quote>
+ (messages printed to standard output) or
+ <quote>stderr</quote> (messages printed to standard
+ error).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
- <term>destination is 'file'</term>
+ <term><option>destination</option> is <quote>file</quote></term>
<listitem>
<simpara>
The value of output is interpreted as a file name;
@@ -1876,12 +1806,13 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
</varlistentry>
<varlistentry>
- <term>destination is 'syslog'</term>
+ <term><option>destination</option> is <quote>syslog</quote></term>
<listitem>
<simpara>
- The value of output is interpreted as the syslog
- facility (e.g. 'local0') that should be used for
- log messages.
+ The value of output is interpreted as the
+ <command>syslog</command> facility (e.g.
+ <emphasis>local0</emphasis>) that should be used
+ for log messages.
</simpara>
</listitem>
</varlistentry>
@@ -1890,7 +1821,7 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<para>
- The other options for output_options are:
+ The other options for <option>output_options</option> are:
</para>
@@ -1912,9 +1843,10 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<para>
Only relevant when destination is file, this is maximum
file size of output files in bytes. When the maximum
- size is reached, the file is renamed (a ".1" is appended
- to the name - if a ".1" file exists, it is renamed ".2"
- etc.) and a new file opened.
+ size is reached, the file is renamed and a new file opened.
+ (For example, a ".1" is appended to the name —
+ if a ".1" file exists, it is renamed ".2",
+ etc.)
</para>
<para>
@@ -1928,8 +1860,8 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<para>
Maximum number of old log files to keep around when
- rolling the output file. Only relevant when destination
- if 'file'.
+ rolling the output file. Only relevant when
+ <option>destination</option> is <quote>file</quote>.
</para>
</section>
@@ -1944,15 +1876,16 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<para>
In this example we want to set the global logging to
- write to the file /var/log/my_bind10.log, at severity
- WARN. We want the authoritative server to log at DEBUG
- with debuglevel 40, to a different file (/tmp/debug_messages).
+ write to the file <filename>/var/log/my_bind10.log</filename>,
+ at severity WARN. We want the authoritative server to
+ log at DEBUG with debuglevel 40, to a different file
+ (<filename>/tmp/debug_messages</filename>).
</para>
<para>
-Start bindctl
+ Start <command>bindctl</command>.
</para>
@@ -2144,7 +2077,7 @@ Logging/loggers[0]/output_options[0]/maxver 8 integer (modified)
<para>
And every module will now be using the values from the
- logger named '*'.
+ logger named <quote>*</quote>.
</para>
@@ -2152,6 +2085,94 @@ Logging/loggers[0]/output_options[0]/maxver 8 integer (modified)
</section>
+ <section>
+ <title>Logging Message Format</title>
+
+ <para>
+ Each message written by BIND 10 to the configured logging
+ destinations comprises a number of components that identify
+ the origin of the message and, if the message indicates
+ a problem, information about the problem that may be
+ useful in fixing it.
+ </para>
+
+ <para>
+ Consider the message below logged to a file:
+ <screen>2011-06-15 13:48:22.034 ERROR [b10-resolver.asiolink]
+ ASIODNS_OPENSOCK error 111 opening TCP socket to 127.0.0.1(53)</screen>
+ </para>
+
+ <para>
+ Note: the layout of messages written to the system logging
+ file (syslog) may be slightly different. This message has
+ been split across two lines here for display reasons; in the
+ logging file, it will appear on one line.)
+ </para>
+
+ <para>
+ The log message comprises a number of components:
+
+ <variablelist>
+ <varlistentry>
+ <term>2011-06-15 13:48:22.034</term>
+<!-- TODO: timestamp repeated even if using syslog? -->
+ <listitem><para>
+ The date and time at which the message was generated.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ERROR</term>
+ <listitem><para>
+ The severity of the message.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>[b10-resolver.asiolink]</term>
+ <listitem><para>
+ The source of the message. This comprises two components:
+ the BIND 10 process generating the message (in this
+ case, <command>b10-resolver</command>) and the module
+ within the program from which the message originated
+ (which in the example is the asynchronous I/O link
+ module, asiolink).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ASIODNS_OPENSOCK</term>
+ <listitem><para>
+ The message identification. Every message in BIND 10
+ has a unique identification, which can be used as an
+ index into the <ulink
+ url="bind10-messages.html"><citetitle>BIND 10 Messages
+ Manual</citetitle></ulink> (<ulink
+ url="http://bind10.isc.org/docs/bind10-messages.html"
+ />) from which more information can be obtained.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>error 111 opening TCP socket to 127.0.0.1(53)</term>
+ <listitem><para>
+ A brief description of the cause of the problem.
+ Within this text, information relating to the condition
+ that caused the message to be logged will be included.
+ In this example, error number 111 (an operating
+ system-specific error number) was encountered when
+ trying to open a TCP connection to port 53 on the
+ local system (address 127.0.0.1). The next step
+ would be to find out the reason for the failure by
+ consulting your system's documentation to identify
+ what error number 111 means.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ </section>
+
</chapter>
<!-- TODO: how to help: run unit tests, join lists, review trac tickets -->
More information about the bind10-changes
mailing list