Commit 88adde43 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[3427] User's Guide updated

parent 4c99c520
......@@ -126,7 +126,7 @@ Right now you can only see what their names are if they are running
One final note about the naming. When specifying the
module name within a logger, use the name of the module
as specified in <command>bindctl</command>, e.g.
as specified in JSON configuration, e.g.
<quote>Dhcp4</quote> for the Dhcp4 module,
<quote>Dhcp6</quote> for the Dhcp6 module, etc. When
the message is logged, the message will include the name
......@@ -297,65 +297,22 @@ TODO; there's a ticket to determine these levels, see #1074
<title>output (string)</title>
<para>
Depending on what is set as the output destination, this
value is interpreted as follows:
This value determines the type of output. There are several
special values allowed here: <command>stdout</command> (messages
are printed on standard output), <command>stderr</command>
(messages are printed on stderr), <command>syslog</command> (messages
are logged to syslog using default name, <command>syslog:name</command>
(messages are logged to syslog using specified name). Any other
value is interpreted as a filename that the logs should be written to.
</para>
<variablelist>
<varlistentry>
<term><option>destination</option> is <quote>console</quote></term>
<listitem>
<para>
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).
</para>
<para>
Note: if output is set to <quote>stderr</quote> and a lot of
messages are produced in a short time (e.g. if the logging
level is set to DEBUG), you may occasionally see some messages
jumbled up together. This is due to a combination of the way
that messages are written to the screen and the unbuffered
nature of the standard error stream. If this occurs, it is
recommended that output be set to <quote>stdout</quote>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>destination</option> is <quote>file</quote></term>
<listitem>
<para>
The value of output is interpreted as a file name;
log messages will be appended to this file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>destination</option> is <quote>syslog</quote></term>
<listitem>
<para>
The value of output is interpreted as the
<command>syslog</command> facility (e.g.
<emphasis>local0</emphasis>) that should be used
for log messages.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The other options for <option>output_options</option> are:
</para>
<!-- configuration of flush is not supported yet.
<section>
<title>flush (true of false)</title>
......@@ -366,7 +323,7 @@ TODO; there's a ticket to determine these levels, see #1074
termination are output.
</para>
</section>
</section> -->
<section>
<title>maxsize (integer)</title>
......@@ -409,7 +366,7 @@ TODO; there's a ticket to determine these levels, see #1074
<para>
Maximum number of old log files to keep around when
rolling the output file. Only relevant when
<option>destination</option> is <quote>file</quote>.
<option>output</option> is <quote>file</quote>.
</para>
</section>
......@@ -419,216 +376,53 @@ TODO; there's a ticket to determine these levels, see #1074
</section>
<section>
<title>Example session</title>
<title>Example Logger configurations</title>
<para>
In this example we want to set the global logging to
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 <command>bindctl</command>.
</para>
<para>
<screen>["login success "]
&gt; <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>&gt; <userinput>config add Logging/loggers</userinput>
&gt; <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>&gt; <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>&gt; <userinput>config set Logging/loggers[0]/name *</userinput>
&gt; <userinput>config set Logging/loggers[0]/severity WARN</userinput>
&gt; <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)
write to the console using standard output.
</para>
<screen><userinput>
"Logging": {
"loggers": [
{
"name": "*",
"output_options": [
{
"output": "stdout"
}
],
"severity": "WARN"
}
]
}
</userinput>
</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>&gt; <userinput> config add Logging/loggers[0]/output_options</userinput>
&gt; <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>&gt; <userinput> config set Logging/loggers[0]/output_options[0]/destination file</userinput>
&gt; <userinput> config set Logging/loggers[0]/output_options[0]/output /var/log/kea.log</userinput>
&gt; <userinput> config set Logging/loggers[0]/output_options[0]/maxsize 204800</userinput>
&gt; <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>&gt; <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/kea.log" string (modified)
Logging/loggers[0]/output_options[0]/flush false boolean (default)
Logging/loggers[0]/output_options[0]/maxsize 204800 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>&gt; <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>&gt; <userinput> config add Logging/loggers</userinput>
&gt; <userinput> config set Logging/loggers[1]/name Dhcp4</userinput>
&gt; <userinput> config set Logging/loggers[1]/severity DEBUG</userinput>
&gt; <userinput> config set Logging/loggers[1]/debuglevel 40</userinput>
&gt; <userinput> config add Logging/loggers[1]/output_options</userinput>
&gt; <userinput> config set Logging/loggers[1]/output_options[0]/destination file</userinput>
&gt; <userinput> config set Logging/loggers[1]/output_options[0]/output /tmp/dhcp4_debug.log</userinput>
&gt; <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 DHCP server use the
same settings as the rest.
</para>
<para>
<screen>&gt; <userinput> config remove Logging/loggers[1]</userinput>
&gt; <userinput> config commit</userinput>
</screen>
</para>
<para>
And every module will now be using the values from the
logger named <quote>*</quote>.
</para>
<para>In this second example, we want to store debug log messages
in a file that is at most 2MB and keep up to 8 copies of old logfiles.
Once the logfile grows to 2MB, it will be renamed and a new file
file be created.</para>
<screen><userinput>
"Logging": {
"loggers": [
{
"name": "kea",
"output_options": [
{
"output": "/var/log/kea-debug.log",
"maxver": 8,
"maxsize": 204800,
"destination": "file"
}
],
"severity": "DEBUG",
"debuglevel": 99
}
]
}</userinput></screen>
</section>
</section>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment