Skip to content

GitLab

Commit 64350f69 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[master] Merge branch 'trac3427' (logging configuration in kea4,kea6,d2) 

Conflicts:
	ChangeLog
	configure.ac
	src/bin/dhcp4/kea_controller.cc
	src/bin/dhcp6/kea_controller.cc
	src/bin/dhcp6/main.cc
	src/lib/log/logger_manager.cc
	src/lib/log/logger_unittest_support.cc
	src/lib/log/logger_unittest_support.h
parents 884f3051 23285903
Hide whitespace changes
Inline Side-by-side
ChangeLog
View file @ 64350f69
814. [func,doc] tomek
It is now possible to specify logging parameters in a
configuration file for DHCPv4, DHCPv6 and DHCP-DDNS components.
(Trac #3427, git 23285903645c36fc35c6866a74c50c74089cd255)
813. [func] tomek
Functions, methods and variables referring to BIND10 were renamed
to Kea. In particular, system variables (B10_LOGGER_ROOT,
......
Makefile.am
View file @ 64350f69
......@@ -129,6 +129,7 @@ cppcheck:
### include tool to generate documentation from log message specifications
### in the distributed tarball:
EXTRA_DIST = tools/system_messages.py
EXTRA_DIST += tools/path_replacer.sh
#### include external sources in the distributed tarball:
EXTRA_DIST += ext/asio/README
......
configure.ac
View file @ 64350f69
......@@ -1455,6 +1455,7 @@ AC_CONFIG_FILES([compatcheck/Makefile
src/lib/util/threads/Makefile
src/lib/util/threads/tests/Makefile
src/lib/util/unittests/Makefile
tools/path_replacer.sh
tests/Makefile
tests/tools/Makefile
])
......@@ -1472,6 +1473,7 @@ AC_CONFIG_FILES([compatcheck/Makefile
chmod +x src/lib/log/tests/logger_lock_test.sh
chmod +x src/lib/log/tests/severity_test.sh
chmod +x src/lib/util/python/gen_wiredata.py
chmod +x tools/path_replacer.sh
])
AC_OUTPUT
......
doc/Makefile.am
View file @ 64350f69
......@@ -4,6 +4,7 @@ EXTRA_DIST = version.ent.in differences.txt Doxyfile Doxyfile-xml
nobase_dist_doc_DATA = examples/kea4/single-subnet.json
nobase_dist_doc_DATA += examples/kea4/several-subnets.json
nobase_dist_doc_DATA += examples/kea6/simple.json
nobase_dist_doc_DATA += examples/kea6/several-subnets.json
devel:
......
doc/examples/kea4/several-subnets.json
View file @ 64350f69
......@@ -4,7 +4,7 @@
{ "Dhcp4":
{
{
# Kea is told to listen on eth0 interface only.
"interfaces": [ "eth0" ],
......@@ -26,13 +26,30 @@
# The following list defines subnets. Each subnet consists of at
# least subnet and pool entries.
"subnet4": [
"subnet4": [
{ "pool": [ "192.0.2.1 - 192.0.2.200" ],
"subnet": "192.0.2.0/24" },
{ "pool": [ "192.0.3.100 - 192.0.3.200" ],
"subnet": "192.0.3.0/24" },
{ "pool": [ "192.0.4.1 - 192.0.4.254" ],
"subnet": "192.0.4.0/24" } ]
},
# The following configures logging. Kea will log all debug messages
# to /var/log/kea-debug.log file.
"Logging": {
"loggers": [
{
"name": "kea-dhcp4",
"output_options": [
{
"output": "/var/log/kea-debug.log"
}
],
"debuglevel": 99,
"severity": "DEBUG"
}
]
}
}
doc/examples/kea4/single-subnet.json
View file @ 64350f69
......@@ -4,7 +4,7 @@
{ "Dhcp4":
{
{
# Kea is told to listen on eth0 interface only.
"interfaces": [ "eth0" ],
......@@ -30,10 +30,27 @@
# "rebind-timer": 2000,
# The following list defines subnets. We have only one subnet
# here.
"subnet4": [
# here. We tell Kea that it is directly available over local interface.
"subnet4": [
{ "pool": [ "192.0.2.1 - 192.0.2.200" ],
"subnet": "192.0.2.0/24" } ]
"subnet": "192.0.2.0/24",
"interface": "eth0" } ]
},
# The following configures logging. It assumes that messages with at least
# informational level (info, warn, error) will will be logged to stdout.
"Logging": {
"loggers": [
{
"name": "kea-dhcp4",
"output_options": [
{
"output": "stdout"
}
],
"severity": "INFO"
}
]
}
}
doc/examples/kea6/several-subnets.json
View file @ 64350f69
......@@ -4,7 +4,7 @@
{ "Dhcp6":
{
{
# Kea is told to listen on eth0 interface only.
"interfaces": [ "eth0" ],
......@@ -28,16 +28,31 @@
# The following list defines subnets. Each subnet consists of at
# least subnet and pool entries.
"subnet6": [
"subnet6": [
{ "pool": [ "2001:db8:1::/80" ],
"subnet": "2001:db8:1::/64" },
{ "pool": [ "2001:db8:2::/80" ],
"subnet": "2001:db8:2::/64" },
"subnet": "2001:db8:2::/64" },
{ "pool": [ "2001:db8:3::/80" ],
"subnet": "2001:db8:3::/64" },
{ "pool": [ "2001:db8:4::/80" ],
"subnet": "2001:db8:4::/64" } ]
}
},
# The following configures logging. It assumes that warning messages
# will be logged to stdout.
"Logging": {
"loggers": [
{
"name": "kea-dhcp6",
"output_options": [
{
"output": "stdout"
}
],
"severity": "WARN"
}
]
}
}
doc/examples/kea6/simple.json 0 → 100644
View file @ 64350f69
# This is an example configuration file for DHCPv6 server in Kea.
# It's a basic scenario with four IPv6 subnets configured. It is
# assumed that one subnet (2001:db8:1::/64 is available directly
# over eth0 interface.
{ "Dhcp6":
{
# Kea is told to listen on eth0 interface only.
"interfaces": [ "eth0" ],
# We need to specify lease type. As of May 2014, three backends are supported:
# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require
# any prior set up.
"lease-database": {
"type": "memfile"
},
# Addresses will be assigned with preferred and valid lifetimes
# being 3000 and 4000, respectively. Client is told to start
# renewing after 1000 seconds. If the server does not repond
# after 2000 seconds since the lease was granted, client is supposed
# to start REBIND procedure (emergency renewal that allows switching
# to a different server).
"preferred-lifetime": 3000,
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
# The following list defines subnets. Each subnet consists of at
# least subnet and pool entries.
"subnet6": [
{
"pool": [ "2001:db8:1::/80" ],
"subnet": "2001:db8:1::/64",
"interface": "eth0"
}
]
},
# The following configures logging. Kea will log all debug messages
# to /var/log/kea-debug.log file.
"Logging": {
"loggers": [
{
"name": "kea-dhcp6",
"output_options": [
{
"output": "/var/log/kea-debug.log"
}
],
"debuglevel": 99,
"severity": "DEBUG"
}
]
}
}
doc/guide/logging.xml
View file @ 64350f69
......@@ -55,13 +55,14 @@
<title>name (string)</title>
<para>
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 Dhcp4 module,
you add an entry for a logger named <quote>Dhcp4</quote>. This
configuration will then be used by the loggers in the
Dhcp4 module, and all the libraries used by it.
</para>
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 Dhcp4 module,
you add an entry for a logger named <quote>Dhcp4</quote>. This
configuration will then be used by the loggers in the
Dhcp4 module, and all the libraries used by it (unless
a library defines its own logger).
</para>
<!-- TODO: later we will have a way to know names of all modules
......@@ -78,7 +79,6 @@ Right now you can only see what their names are if they are running
has the full name of <quote>Dhcp4.dhcpsrv</quote>. If
there is no entry in Logging for a particular library,
it will use the configuration given for the module.
</para>
<para>
......@@ -125,19 +125,40 @@ Right now you can only see what their names are if they are running
<para>
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.
<quote>Dhcp4</quote> for the Dhcp4 module,
<quote>Dhcp6</quote> for the Dhcp6 module, etc. When
module name within a logger, use the name of the binary file,
e.g. <quote>kea-dhcp4</quote> for the DHCPv4 module,
<quote>kea-dhcp6</quote> for the DHCPv6 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
<quote>Dhcp4</quote> logger will appear in the output
<quote>DHCPv4</quote> logger will appear in the output
with a logger name of <quote>kea-dhcp4</quote>).
</para>
<para>
Currently defined loggers are:
</para>
<itemizedlist>
<listitem>
<simpara>kea-dhcp4.dhcp4</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp6.dhcp6</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp-ddns.dhcpddns</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp4.dhcpsrv</simpara>
</listitem>
<listitem>
<simpara>kea-dhcp6.dhcpsrv</simpara>
</listitem>
</itemizedlist>
<para>Additional loggers may be defined in the future.</para>
</section>
<section>
......@@ -297,65 +318,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 +344,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 +387,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 +397,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)
write to the console using standard output.
</para>
<screen><userinput>
"Logging": {
"loggers": [
{
"name": "kea-dhcp4",
"output_options": [
{
"output": "stdout"
}
],
"severity": "WARN"
}
]
}
</userinput>
</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)
</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>