<title>Logging Configuration</title>
<para>
During its operation Kea may produce many messages. They differ in
- severity (some are more important than others) and source (some are
- produced by specific components, e.g. hooks). It is useful to understand
+ severity (some are more important than others) and source (different components
+ (e.g. hooks) produce different messages). It is useful to understand
which log messages are critical and which are not, and configure your
logging appropriately. For example, debug-level messages can be safely
ignored in a typical deployment. They are, however, very useful when
processes, may use multiple loggers to log messages pertaining
to different logical functions of the component. For example,
the DHCPv4 server uses one logger for messages
- pertaining to packet reception and transmission, another
+ about packet reception and transmission, another
logger for messages related to lease allocation, and so on.
Some of the libraries used by the Kea server, e.g. libdhcpsrv,
use their own loggers.
messages produced by the hooks library can be distinguished from
messages issued by the core Kea code. Unique names also allow
the loggers to be configured independently of loggers used
- by Kea. Whenever it makes sense, a hook library can use multiple
+ by Kea. Whenever it makes sense, a hooks library can use multiple
loggers to log messages pertaining to different logical parts
of the library.
</para>
configuration for zero or more loggers (including loggers used by the
proprietary hooks libraries). If there are no loggers specified, the
code will use default values; these cause Kea to log messages of INFO
- severity or greater to standard output. There is also a small
+ severity or greater to standard output. There is a small
time window after Kea has been started but before it has read its
configuration; logging in this short period can be controlled
using environment variables. For details, see <xref linkend="logging-during-startup"/>.
that might match a particular logger, the specification with the
more specific logger name takes precedence. For example, if there
are entries for both <quote>kea-dhcp4</quote> and
- <quote>kea-dhcp4.dhcpsrv</quote>, the DHCPv4 server — and all
- libraries it uses that are not dhcpsrv — will log messages
+ <quote>kea-dhcp4.dhcpsrv</quote>, the main DHCPv4 server program — and all
+ libraries it uses other than the dhcpsrv library (libdhcpsrv) — will log messages
according to the configuration in the first entry
- (<quote>kea-dhcp4</quote>).
+ (<quote>kea-dhcp4</quote>). Messages generated by the dhcpsrv library
+ will be logged according to the configuration set by the second entry.
</para>
<para>
<row><entry><command>kea-ctrl-agent.http</command></entry><entry>core</entry><entry>A logger which outputs log messages related to receiving, parsing, and sending HTTP messages.</entry></row>
<row><entry><command>kea-dhcp4</command></entry><entry>core</entry><entry>The root logger for the DHCPv4 server. All components used by the DHCPv4 server inherit the settings from this logger.</entry></row>
<row><entry><command>kea-dhcp6</command></entry><entry>core</entry><entry>The root logger for the DHCPv6 server. All components used by the DHCPv6 server inherit the settings from this logger.</entry></row>
- <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.alloc-engine</command></member><member><command>kea-dhcp6.alloc-engine</command></member></simplelist></entry><entry>core</entry><entry>Used by the lease allocation engine, which is responsible for managing leases in the lease database, i.e. create, modify, and remove DHCP leases as a result of processing messages from the clients.</entry></row>
+ <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.alloc-engine</command></member><member><command>kea-dhcp6.alloc-engine</command></member></simplelist></entry><entry>core</entry><entry>Used by the lease allocation engine, which is responsible for managing leases in the lease database, i.e. creating, modifying, and removing DHCP leases as a result of processing messages from the clients.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.bad-packets</command></member><member><command>kea-dhcp6.bad-packets</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP servers for logging inbound client packets that were dropped or to which the server responded with a DHCPNAK. It allows administrators to configure a separate log output that contains only packet drop and reject entries.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.callouts</command></member><member><command>kea-dhcp6.callouts</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages pertaining to the callouts registration and execution for the particular hook point.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.commands</command></member><member><command>kea-dhcp6.commands</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages relating to the handling of commands received by the DHCP server over the command channel.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.host-cache-hooks</command></member><member><command>kea-dhcp6.host-cache-hooks</command></member></simplelist></entry><entry>libdhcp_host_cache premium hook library</entry><entry>This logger is used to log messages related to the operation of the Host Cache Hook Library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.flex-id-hooks</command></member><member><command>kea-dhcp6.flex-id-hooks</command></member></simplelist></entry><entry>libdhcp_flex_id premium hook library</entry><entry>This logger is used to log messages related to the operation of the Flexible Identifiers Hook Library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.ha-hooks</command></member><member><command>kea-dhcp6.ha-hooks</command></member></simplelist></entry><entry>libdhcp_ha hook library</entry><entry>This logger is used to log messages related to the operation of the High Availability Hook Library.</entry></row>
- <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.hooks</command></member><member><command>kea-dhcp6.hooks</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages related to management of hooks libraries, e.g. registration and deregistration of the libraries, and to the initialization of the callouts execution for various hook points within the DHCP server.</entry></row>
- <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.host-cmds-hooks</command></member><member><command>kea-dhcp6.host-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_host_cmds premium hook library</entry><entry>This logger is used to log messages related to the operation of the Host Cmds hooks library. In general, these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
+ <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.hooks</command></member><member><command>kea-dhcp6.hooks</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages related to the management of hooks libraries, e.g. registration and deregistration of the libraries, and to the initialization of the callouts execution for various hook points within the DHCP server.</entry></row>
+ <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.host-cmds-hooks</command></member><member><command>kea-dhcp6.host-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_host_cmds premium hook library</entry><entry>This logger is used to log messages related to the operation of the Host Cmds hooks library. In general, these will pertain to the loading and unloading of the library and the execution of commands by the library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.hosts</command></member><member><command>kea-dhcp6.hosts</command></member></simplelist></entry><entry>core</entry><entry>Used within the libdhcpsrv, it logs messages related to the management of the DHCP host reservations, i.e. retrieval of the reservations and adding new reservations.</entry></row>
- <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.lease-cmds-hooks</command></member><member><command>kea-dhcp6.lease-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_lease_cmds hook library</entry><entry>This logger is used to log messages related to the operation of the Lease Cmds hooks library. In general, these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
- <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.leases</command></member><member><command>kea-dhcp6.leases</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP server to log messages related to the lease allocation. The messages include detailed information about the allocated or offered leases, errors during the lease allocation, etc.</entry></row>
+ <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.lease-cmds-hooks</command></member><member><command>kea-dhcp6.lease-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_lease_cmds hook library</entry><entry>This logger is used to log messages related to the operation of the Lease Cmds hooks library. In general, these will pertain to the loading and unloading of the library and the execution of commands by the library.</entry></row>
+ <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.leases</command></member><member><command>kea-dhcp6.leases</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP server to log messages related to lease allocation. The messages include detailed information about the allocated or offered leases, errors during the lease allocation, etc.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.legal-log-hooks</command></member><member><command>kea-dhcp6.legal-log-hooks</command></member></simplelist></entry><entry>libdhcp_legal_log premium hook library</entry><entry>This logger is used to log messages related to the operation of the Forensic Logging Hooks Library.</entry></row>
- <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.options</command></member><member><command>kea-dhcp4.options</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP server to log messages related to processing of the options in the DHCP messages, i.e. parsing options, encoding options into on-wire format, and packet classification using options contained in the received packets.</entry></row>
- <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.packets</command></member><member><command>kea-dhcp6.packets</command></member></simplelist></entry><entry>core</entry><entry>This logger is mostly used to log messages related to transmission of the DHCP packets, i.e. packet reception and sending a response. Such messages include information about the source and destination IP addresses and interfaces used to transmit packets. The logger is also used to log messages related to subnet selection, as this selection is usually based on the IP addresses, relay addresses, and/or interface names, which can be retrieved from the received packet even before the DHCP message carried in the packet is parsed.</entry></row>
+ <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.options</command></member><member><command>kea-dhcp4.options</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP server to log messages related to the processing of options in the DHCP messages, i.e. parsing options, encoding options into on-wire format, and packet classification using options contained in the received packets.</entry></row>
+ <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.packets</command></member><member><command>kea-dhcp6.packets</command></member></simplelist></entry><entry>core</entry><entry>This logger is mostly used to log messages related to transmission of the DHCP packets, i.e. packet reception and the sending of a response. Such messages include information about the source and destination IP addresses and interfaces used to transmit packets. The logger is also used to log messages related to subnet selection, as this selection is usually based on the IP addresses, relay addresses, and/or interface names, which can be retrieved from the received packet even before the DHCP message carried in the packet is parsed.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.radius-hooks</command></member><member><command>kea-dhcp6.radius-hooks</command></member></simplelist></entry><entry>libdhcp_radius premium hook library</entry><entry>This logger is used to log messages related to the operation of the Radius Hook Library.</entry></row>
- <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.stat-cmds-hooks</command></member><member><command>kea-dhcp6.stat-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_stat_cmds hook library</entry><entry>This logger is used to log messages related to the operation of the Stats Cmds hooks library. In general, these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
- <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.subnet-cmds-hooks</command></member><member><command>kea-dhcp6.subnet-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_subnet_cmds hook library</entry><entry>This logger is used to log messages related to the operation of the Subnet Cmds hooks library. In general, these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
- <row><entry><command>kea-dhcp-ddns</command></entry><entry>core</entry><entry>The root logger for the kea-dhcp-ddns daemon. All components used by this daemon inherit the settings from this logger if there is no specialized logger provided.</entry></row>
+ <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.stat-cmds-hooks</command></member><member><command>kea-dhcp6.stat-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_stat_cmds hook library</entry><entry>This logger is used to log messages related to the operation of the Statistics Commands hooks library. In general, these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
+ <row><entry><simplelist type="horiz"><member><command>kea-dhcp4.subnet-cmds-hooks</command></member><member><command>kea-dhcp6.subnet-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_subnet_cmds hook library</entry><entry>This logger is used to log messages related to the operation of the Subnet Commands hooks library. In general, these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
+ <row><entry><command>kea-dhcp-ddns</command></entry><entry>core</entry><entry>The root logger for the kea-dhcp-ddns daemon. All components used by this daemon inherit the settings from this logger unless there are configurations for more specialized loggers..</entry></row>
<row><entry><command>kea-dhcp-ddns.dctl</command></entry><entry>core</entry><entry>The logger used by the kea-dhcp-ddns daemon for logging basic information about the process, received signals, and triggered reconfigurations.</entry></row>
<row><entry><command>kea-dhcp-ddns.dhcpddns</command></entry><entry>core</entry><entry>The logger used by the kea-dhcp-ddns daemon for logging events related to DDNS operations.</entry></row>
<row><entry><command>kea-dhcp-ddns.dhcp-to-d2</command></entry><entry>core</entry><entry>Used by the kea-dhcp-ddns daemon for logging information about events dealing with receiving messages from the DHCP servers and adding them to the queue for processing.</entry></row>
</para>
<para>
- Note that user-defined hook libraries should not use any of those
- loggers, but should define new loggers with names that correspond to
+ Note that user-defined hook libraries should not use any of the loggers
+ mentioned above, but should define new loggers with names that correspond to
the libraries using them. Suppose that the user created the library
called <quote>libdhcp-packet-capture</quote> to dump packets received and
transmitted by the server to the file. An appropriate name for the
projects / thirdparty / kea.git / commitdiff
