Logging

Logging Configuration 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 which log messages are needed 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 debugging a problem. The logging system in Kea is configured through the Logging structure in your configuration file. All daemons (e.g. DHCPv4 and DHCPv6 servers) will use the configuration in the Logging structure to see what should be logged and to where. This allows for sharing identical logging configuration between daemons.

Loggers Within Kea, a message is logged through an entity called a "logger". Different components log messages through different loggers, and each logger can be configured independently of one another. Some components, in particular the DHCP server processes, may use multiple loggers to log messages pertaining to different logical functions of the component. For example, the DHCPv4 server is using one logger for messages pertaining to packet reception and transmission, another logger for messages related to lease allocation and so on. Some of the libraries used by the Kea servers, e.g. libdhcpsrv or libhooks library, use their own loggers. Users implementing hooks libraries (code attached to the server at runtime) are responsible for creating the loggers used by those libraries. Such loggers should have unique names, different from the logger names used by Kea. In this way the messages emitted from the hooks library can be distingued 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 loggers to log messages pertaining to different logical parts of the library. In the Logging structure of a configuration file you can specify the 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 which cause Kea to log messages on at least INFO severity to standard output. The three most important elements of a logger configuration are the (the component that is generating the messages), the (what to log), and the (where to log).

name (string) Each logger in the system has a name, the name being that of the component binary file using it to log messages. For instance, if you want to configure logging for the DHCPv4 server, you add an entry for a logger named kea-dhcp4. This configuration will then be used by the loggers in the DHCPv4 server, and all the libraries used by it (unless a library defines its own logger and there is specific logger configuration that applies to that logger). When diagnosing the problem with the server's operation, it is often desired to use the DEBUG logging level to obtain the verbose output from the server and libraries it uses. However, high verbosity may be an overkill for the logging system in cases when the server is processing high volume traffic. To mitigate this problem, Kea is using multiple loggers, which can be configured independently and which are responsible for logging messages from different functional parts of the server. If the user, trying to diagnose the problem, has a reasonably high confidence that the problem origins in a specific function of the server, or the problem is related to the specific type of operation, he may enable high verbosity only for the relevant logger, thus limiting the debug messages to the required minimum. The loggers are associated with a particular library or binary of Kea. However, each library or binary may (and usually does) include multiple loggers. For example, the DHCPv4 server binary contains separate loggers for: packet parsing, for dropped packets, for callouts etc. Each logger "derives" its configuration from the root logger. In the typical case, the root logger configuration is the only logging configuration specified in the configuration file. Creating a specific configuration for the selected logger, thus overriding the configuration settings specified in the root logger configuration, requires putting its configuration aside of the root logger's configuration with some of the parameters modified. To illustrate this, suppose you are using the DHCPv4 server with the root logger kea-dhcp4 logging at the INFO level. In order to enable DEBUG verbosity for the DHCPv4 packet drops, you must create configuration entry for the logger called kea-dhcp4.bad-packets and specify severity DEBUG for this logger. All other configuration parameters may be omited for this logger if the logger should use the default values specified in the root logger's configuration. 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 both kea-dhcp4 and kea-dhcp4.dhcpsrv, the DHCPv4 server — and all libraries it uses that are not dhcpsrv — will log messages according to the configuration in the first entry (kea-dhcp4). Currently defined loggers are: kea-dhcp4 - this is the root logger for the DHCPv4 server. All components used by the DHCPv4 server inherit the settings from this logger if there is no specialized logger provided. kea-dhcp4.alloc-engine - this is the logger used by the lease allocation engine, which is responsible for managing leases in the lease database, i.e. create, modify and remove DHCPv4 leases as a result of processing messages from the clients. kea-dhcp4.bad-packets - this is the logger used by the DHCPv4 server daemon for logging inbound client packets that were dropped or to which the server responded with a DHCPNAK. The allows administrators to configure a separate log output that contains only packet drop and reject entries. kea-dhcp4.callouts - this logger is used to log messages pertaining to the callouts registration and execution for the particular hook point. kea-dhcp4.commands - this logger is used to log messages relating to the handling of commands received by the the DHCPv4 server over the command channel. kea-dhcp4.ddns - this logger is used by the DHCPv4 server to log messages related to the Client FQDN and Hostname option processing. It also includes log messages related to the relevant DNS updates. kea-dhcp4.dhcp4 - this is the logger by the DHCPv4 server daemon to log basic operations. kea-dhcp4.dhcpsrv - this is a base logger for the libdhcpsrv library. kea-dhcp4.eval - this logger is used to log messages relating to the client classification expression evaluation code. kea-dhcp4.hooks - this logger is 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 DHCPv4 server. kea-dhcp4.hosts - this logger is used within the libdhcpsrv and it logs messages related to the management of the DHCPv4 host reservations, i.e. retrieval of the reservations and adding new reservations. kea-dhcp4.leases - this logger is used by the DHCPv4 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. kea-dhcp4.options - this logger is used by the DHCPv4 server to log messages related to processing of the options in the DHCPv4 messages, i.e. parsing options, encoding options into on-wire format and packet classification using options contained in the received packets. kea-dhcp4.packets - this logger is mostly used to log messages related to transmission of the DHCPv4 packets, i.e. packet reception and sending a response. Such messages include the information about the source and destination IP addresses and interfaces used to transmit packets. This logger is also used to log messages related to subnet selection, as this selection is usually based on the IP addresses and/or interface names, which can be retrieved from the received packet, even before the DHCPv4 message carried in the packet is parsed. kea-dhcp6 - this is the root logger for the DHCPv6 server. All components used by the DHCPv6 server inherit the settings from this logger if there is no specialized logger provided. kea-dhcp6.alloc-engine - this is the logger used by the lease allocation engine, which is responsible for managing leases in the lease database, i.e. create, modify and remove DHCPv6 leases as a result of processing messages from the clients. kea-dhcp6.bad-packets - this is the logger used by the DHCPv6 server daemon for logging inbound client packets that were dropped. kea-dhcp6.callouts - this logger is used to log messages pertaining to the callouts registration and execution for the particular hook point. kea-dhcp6.commands - this logger is used to log messages relating to the handling of commands received by the the DHCPv6 server over the command channel. kea-dhcp6.ddns - this logger is used by the DHCPv6 server to log messages related to the Client FQDN option processing. It also includes log messages related to the relevant DNS updates. kea-dhcp6.dhcp6 - this is the logger used DHCPv6 server daemon to log basic operations. kea-dhcp6.dhcpsrv - this is a base logger for the libdhcpsrv library. kea-dhcp6.eval - this logger is used to log messages relating to the client classification expression evaluation code. kea-dhcp6.hooks - this logger is 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 DHCPv6 server. kea-dhcp6.hosts - this logger is used within the libdhcpsrv and it logs messages related to the management of the DHCPv6 host reservations, i.e. retrieval of the reservations and adding new reservations. kea-dhcp6.leases - this logger is used by the DHCPv6 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. kea-dhcp6.options - this logger is used by the DHCPv6 server to log messages related to processing of the options in the DHCPv6 messages, i.e. parsing options, encoding options into on-wire format and packet classification using options contained in the received packets. kea-dhcp6.packets - this logger is mostly used to log messages related to transmission of the DHCPv6 packets, i.e. packet reception and sending a response. Such messages include the information about the source and destination IP addresses and interfaces used to transmit packets. This logger is also used to log messages related to subnet selection, as this selection is usually based on the IP addresses and/or interface names, which can be retrieved from the received packet, even before the DHCPv6 message carried in the packet is parsed. kea-dhcp-ddns - this is 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. kea-dhcp-ddns.dhcpddns - this is the logger used by the kea-dhcp-ddns daemon for logging configuration and global event information. This logger does not specify logging settings for libraries used by the daemon. kea-dhcp-ddns.dhcp-to-d2 - this is the logger 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. kea-dhcp-ddns.d2-to-dns - this is the logger used by the kea-dhcp-ddns daemon for logging information about events dealing with sending and receiving messages with the DNS servers. Note that user-defined hook libraries should not use any of those loggers, and should define new loggers with names that correspond to the libraries using them. Suppose that the user created the library called libpacket-capture to dump packets received and transmitted by the server to the file. The appropriate name for the logger could be kea-dhcp4.packet-capture. Note that the hook library implementor only specifies the second part of this name, i.e. packet-capture. The first part is a root logger name and is prepended by the Kea logging system. It is also important to note that since this new logger is a child of a root logger, it inherits the configuration from the root logger, unless there is a separate configuration entry for the child logger which overrides the default configuration. The list of loggers above excludes any loggers implemented in hooks libraries. Please consult the documentation of the specific hooks libraries for the names of loggers they define. Additional loggers may be defined in the future. The easiest way to find out the logger name is to configure all logging to go to a single destination and look for specific logger names. See for details.

severity (string) This specifies the category of messages logged. 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 When the severity of a logger is set to one of these values, it will only log messages of that severity, and the severities above it. The severity may also be set to NONE, in which case all messages from that logger are inhibited.

output_options (list) Each logger can have zero or more . These specify where log messages are sent. These are explained in detail below. The other options for a logger are:

debuglevel (integer) 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). If severity for the logger is not DEBUG, this value is ignored.

Output Options The main settings for an output option are the and a value called , the meaning of which depends on the destination that is set.

destination (string) The destination is the type of output. It can be one of: console file syslog

output (string) This value determines the type of output. There are several special values allowed here: stdout (messages are printed on standard output), stderr (messages are printed on stderr), syslog (messages are logged to syslog using default name, syslog:name (messages are logged to syslog using specified name). Any other value is interpreted as a filename that the logs should be written to. The other options for are:

flush (true of false) 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. Default is true.

maxsize (integer) 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 and a new file opened. (For example, a ".1" is appended to the name — if a ".1" file exists, it is renamed ".2", etc.) If this is 0, no maximum file size is used. Due to a limitation of the underlying logging library (log4cplus), rolling over the log files (from ".1" to ".2", etc) may show odd results: There can be multiple small files at the timing of roll over. This can happen when multiple processes try to roll over the files simultaneously. Version 1.1.0 of log4cplus solved this problem, so if this or higher version of log4cplus is used to build Kea, it shouldn't happen. Even for older versions it is normally expected to happen rarely unless the log messages are produced very frequently by multiple different processes.

maxver (integer) Maximum number of old log files to keep around when rolling the output file. Only relevant when is file.

Example Logger Configurations In this example we want to set the global logging to write to the console using standard output. "Logging": { "loggers": [ { "name": "kea-dhcp4", "output_options": [ { "output": "stdout" } ], "severity": "WARN" } ] } 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. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { "output": "/var/log/kea-debug.log", "maxver": 8, "maxsize": 204800, "flush": true } ], "severity": "DEBUG", "debuglevel": 99 } ] }