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
<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>
termination are output.
</para>
- </section>
+ </section> -->
<section>
<title>maxsize (integer)</title>
<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>
</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 "]
-> <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)
+ 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>> <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/kea.log</userinput>
-> <userinput> config set Logging/loggers[0]/output_options[0]/maxsize 204800</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/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>> <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 Dhcp4</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/dhcp4_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 DHCP 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 <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>
projects / thirdparty / kea.git / commitdiff
