BIND 10 trac1011, updated. 7b0201a4f98ee1b1288ae3b074cd1007707b6b21 trac1011: some XML formatting
BIND 10 source code commits
bind10-changes at lists.isc.org
Tue Jul 26 22:58:41 UTC 2011
The branch, trac1011 has been updated
via 7b0201a4f98ee1b1288ae3b074cd1007707b6b21 (commit)
via ba7bc1e14fcf1a223a9a42ede2e9cd7d290c8b61 (commit)
via c6ef5865b3fd8e5d5fb8c891467b3722fde4d685 (commit)
from 589965360a98152e8c783e4736080e06a895feb0 (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 7b0201a4f98ee1b1288ae3b074cd1007707b6b21
Author: reed <reed at .(none)>
Date: Tue Jul 26 17:57:53 2011 -0500
trac1011: some XML formatting
Add some docbook formatting.
This is not complete.
commit ba7bc1e14fcf1a223a9a42ede2e9cd7d290c8b61
Author: reed <reed at .(none)>
Date: Tue Jul 26 17:06:50 2011 -0500
trac1011: add Logging configuration docs
This is a copy and paste from
http://bind10.isc.org/wiki/LoggingConfigurationGuide
No formatting or cleanup or XML-ization yet.
commit c6ef5865b3fd8e5d5fb8c891467b3722fde4d685
Author: reed <reed at .(none)>
Date: Tue Jul 26 17:04:33 2011 -0500
trac1011: a TODO to research for logging docs
-----------------------------------------------------------------------
Summary of changes:
doc/guide/bind10-guide.xml | 536 +++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 535 insertions(+), 1 deletions(-)
-----------------------------------------------------------------------
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index 6a42182..98070c7 100644
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -1498,6 +1498,7 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
<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>
@@ -1549,8 +1550,541 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
</para></listitem>
</varlistentry>
</variablelist>
-
</para>
+
+ <section>
+ <title>Logging configuration</title>
+
+ <para>
+
+ The logging system in BIND 10 is configured through the
+ Logging module. All BIND 10 modules will look at the
+ configuration in Logging to see what should be logged and
+ to where.
+
+<!-- TODO: what is context of Logging module for readers of this guide? -->
+
+ </para>
+
+ <section>
+ <title>Loggers</title>
+
+ <para>
+
+ Within BIND 10, a message is logged through a component
+ called a "logger". Different parts of BIND 10 log messages
+ through different loggers, and each logger can be configured
+ independently of one another.
+
+ </para>
+
+ <para>
+
+ In the Logging module, you can specify the configuration
+ for zero or more loggers; any that are not specified will
+ take appropriate default values..
+
+ </para>
+
+ <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 (where to log).
+
+ </para>
+
+ <para>
+
+
+name (string)
+
+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 configuration will then be used by the loggers in the Resolver module, and all the libraries used by it.
+
+ </para>
+
+ <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 there is no entry in Logging for a particular library, it will use the configuration given for the module.
+
+ </para>
+
+ <para>
+
+
+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.
+
+
+ </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).
+
+ </para>
+
+ <para>
+
+
+If there are multiple logger specifications in the 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'.
+
+ </para>
+
+ <para>
+
+
+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 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').
+
+
+ </para>
+
+ <para>
+
+severity (string)
+
+
+ </para>
+
+ <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):
+
+ FATAL
+ ERROR
+ WARN
+ INFO
+ DEBUG
+
+
+ </para>
+
+ <para>
+
+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 NONE, in which case all messages from that logger are inhibited.
+
+
+ </para>
+
+ <para>
+
+output_options (list)
+
+ </para>
+
+ <para>
+
+
+Each logger can have zero or more output_options. These specify where log messages are sent to. These are explained in detail below.
+
+
+ </para>
+
+ <para>
+
+The other options for a logger are:
+
+
+ </para>
+
+ <para>
+
+debuglevel (integer)
+
+ </para>
+
+ <para>
+
+
+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
+
+
+ </para>
+
+ <para>
+
+TODO; there's a ticket to determine these levels, see #1074
+
+
+ </para>
+
+ <para>
+
+If severity for the logger is not DEBUG, this value is ignored.
+
+
+ </para>
+
+ <para>
+
+additive (true or false)
+
+
+ </para>
+
+ <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'.
+
+ </para>
+
+ <para>
+
+
+TODO: check this
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Output Options</title>
+
+ <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.
+
+
+ </para>
+
+ <para>
+
+destination (string)
+
+
+ </para>
+
+ <para>
+
+The destination is the type of output. It can be one of:
+
+
+ </para>
+
+ <para>
+
+ * console
+ * file
+ * syslog
+
+ </para>
+
+ <para>
+
+
+output (string)
+
+ </para>
+
+ <para>
+
+
+Depending on what is set as the output destination, this value is interpreted as follows:
+
+ </para>
+
+ <para>
+
+
+ * destination is 'console'
+ 'output' must be one of 'stdout' (messages printed to standard output) or 'stderr' (messages printed to standard error).
+
+
+ </para>
+
+ <para>
+
+ * destination is 'file'
+ The value of output is interpreted as a file name; log messages will be appended to this file.
+
+
+ </para>
+
+ <para>
+
+ * destination is 'syslog'
+ The value of output is interpreted as the syslog facility (e.g. 'local0') that should be used for log messages.
+
+ </para>
+
+ <para>
+
+
+The other options for output_options are:
+
+
+ </para>
+
+ <para>
+
+flush (true of false)
+
+
+ </para>
+
+ <para>
+
+Flush buffers after each log message. Doing this will reduce performance but will ensure that if the program terminates abnormally, all messages up to the point of termination are output.
+
+
+ </para>
+
+ <para>
+
+maxsize (integer)
+
+
+ </para>
+
+ <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.
+
+
+ </para>
+
+ <para>
+
+If this is 0, no maximum file size is used.
+
+
+ </para>
+
+ <para>
+
+maxver (integer)
+
+
+ </para>
+
+ <para>
+
+Maximum number of old log files to keep around when rolling the output file. Only relevant when destination if 'file'.
+
+ </para>
+
+ </section>
+
+ <section>
+ <title>Example session</title>
+
+ <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).
+
+
+ </para>
+
+ <para>
+
+Start bindctl
+
+
+ </para>
+
+ <para>
+
+ <screen>["login success "]
+> <userinput>config show Logging</userinput>
+Logging/loggers [] list
+</screen>
+
+
+ </para>
+
+ <para>
+
+By default, no specific loggers are configured, in which case the severity defaults to INFO and the output is written to stderr.
+
+
+ </para>
+
+ <para>
+
+Let's first add a default logger;
+
+
+ </para>
+
+<!-- TODO: adding the empty loggers makes no sense -->
+ <para>
+
+ <screen><userinput>> config add Logging/loggers</userinput>
+> <userinput>config show Logging</userinput>
+Logging/loggers/ list (modified)
+</screen>
+
+ </para>
+
+ <para>
+
+
+The loggers value line changed to indicate that it is no longer an empty list;
+
+ </para>
+
+ <para>
+
+ <screen>> <userinput>config show Logging/loggers</userinput>
+Logging/loggers[0]/name "" string (default)
+Logging/loggers[0]/severity "INFO" string (default)
+Logging/loggers[0]/debuglevel 0 integer (default)
+Logging/loggers[0]/additive false boolean (default)
+Logging/loggers[0]/output_options [] list (default)
+</screen>
+
+ </para>
+
+ <para>
+
+
+The name is mandatory, so we must set it. We will also change the severity as well. Let's start with the global logger.
+
+
+ </para>
+
+ <para>
+
+ <screen>> <userinput>config set Logging/loggers[0]/name *</userinput>
+> <userinput>config set Logging/loggers[0]/severity WARN</userinput>
+> <userinput>config show Logging/loggers</userinput>
+Logging/loggers[0]/name "*" string (modified)
+Logging/loggers[0]/severity "WARN" string (modified)
+Logging/loggers[0]/debuglevel 0 integer (default)
+Logging/loggers[0]/additive false boolean (default)
+Logging/loggers[0]/output_options [] list (default)
+</screen>
+
+ </para>
+
+ <para>
+
+
+Of course, we need to specify where we want the log messages to go, so we add an entry for an output option.
+
+
+ </para>
+
+ <para>
+
+ <screen>> <userinput> config add Logging/loggers[0]/output_options</userinput>
+> <userinput> config show Logging/loggers[0]/output_options</userinput>
+Logging/loggers[0]/output_options[0]/destination "console" string (default)
+Logging/loggers[0]/output_options[0]/output "stdout" string (default)
+Logging/loggers[0]/output_options[0]/flush false boolean (default)
+Logging/loggers[0]/output_options[0]/maxsize 0 integer (default)
+Logging/loggers[0]/output_options[0]/maxver 0 integer (default)
+</screen>
+
+
+ </para>
+
+ <para>
+
+These aren't the values we are looking for.
+
+
+ </para>
+
+ <para>
+
+ <screen>> <userinput> config set Logging/loggers[0]/output_options[0]/destination file</userinput>
+> <userinput> config set Logging/loggers[0]/output_options[0]/output /var/log/bind10.log</userinput>
+> <userinput> config set Logging/loggers[0]/output_options[0]/maxsize 30000</userinput>
+> <userinput> config set Logging/loggers[0]/output_options[0]/maxver 8</userinput>
+</screen>
+
+ </para>
+
+ <para>
+
+Which would make the entire configuration for this logger look like:
+
+ </para>
+
+ <para>
+
+ <screen>> <userinput> config show all Logging/loggers</userinput>
+Logging/loggers[0]/name "*" string (modified)
+Logging/loggers[0]/severity "WARN" string (modified)
+Logging/loggers[0]/debuglevel 0 integer (default)
+Logging/loggers[0]/additive false boolean (default)
+Logging/loggers[0]/output_options[0]/destination "file" string (modified)
+Logging/loggers[0]/output_options[0]/output "/var/log/bind10.log" string (modified)
+Logging/loggers[0]/output_options[0]/flush false boolean (default)
+Logging/loggers[0]/output_options[0]/maxsize 30000 integer (modified)
+Logging/loggers[0]/output_options[0]/maxver 8 integer (modified)
+</screen>
+
+ </para>
+
+ <para>
+
+That looks OK, so let's commit it before we add the configuration for the authoritative server's logger.
+
+
+ </para>
+
+ <para>
+
+ <screen>> <userinput> config commit</userinput></screen>
+
+
+ </para>
+
+ <para>
+
+Now that we have set it, and checked each value along the way, adding a second entry is quite similar.
+
+
+ </para>
+
+ <para>
+
+ <screen>> <userinput> config add Logging/loggers</userinput>
+> <userinput> config set Logging/loggers[1]/name Auth</userinput>
+> <userinput> config set Logging/loggers[1]/severity DEBUG</userinput>
+> <userinput> config set Logging/loggers[1]/debuglevel 40</userinput>
+> <userinput> config add Logging/loggers[1]/output_options</userinput>
+> <userinput> config set Logging/loggers[1]/output_options[0]/destination file</userinput>
+> <userinput> config set Logging/loggers[1]/output_options[0]/output /tmp/auth_debug.log</userinput>
+> <userinput> config commit</userinput>
+</screen>
+
+ </para>
+
+ <para>
+
+
+And that's it. Once we have found whatever it was we needed the debug messages for, we can simply remove the second logger to let the authoritative server use the same settings as the rest.
+
+
+ </para>
+
+ <para>
+
+ <screen>> <userinput> config remove Logging/loggers[1]</userinput>
+> <userinput> config commit</userinput>
+</screen>
+
+ </para>
+
+ <para>
+
+And every module will now be using the values from the logger named '*'.
+
+ </para>
+
+ </section>
+
+ </section>
+
</chapter>
<!-- TODO: how to help: run unit tests, join lists, review trac tickets -->
More information about the bind10-changes
mailing list