When determining which options to include in the response the server will examine
the union of options from all of the assigned classes. In the case two or more
classes include the same option, the value from the first class examined will
- be used. When choosing a subnet the server will iterate over all of the
+ be used. When choosing a subnet, the server will iterate over all of the
subnets that are feasible given the information found in the packet (client address,
relay address etc). It will use the first subnet it finds that either doesn't
have a class associated with it or that has a class which matches one of
</para>
<para>
- As an example, imagine two classes. Class "foo" defines values for an NTP server
+ As an example, imagine that an incoming packet matches two classes.
+ Class "foo" defines values for an NTP server
(option 42 in DHCPv4) and an SMTP server (option 69 in DHCPv4) while class
"bar" defines values for an NTP server and a POP3 server (option 70 in DHCPv4).
The server will examine the three options NTP, SMTP and POP3 and return any
Expressions are pre-processed during the parsing of the configuration file
and converted to an internal representation. This allows certain types of
errors to be caught and logged during parsing. Examples of these errors
- include incorrect number or types of arguments to an operator. The
+ include an incorrect number or types of arguments to an operator. The
evaluation code will also check for this class of error and generally
- throw an exception, though they should not occur in a normally functioning
+ throw an exception, though this should not occur in a normally functioning
system.
</para>
<para>
Expressions are a work in progress and the supported operators and
values are limited. The expectation is that additional operators and values
- will be added over time, however it is expected the basic mechanisms will
+ will be added over time, however the basic mechanisms will
remain the same.
</para>
<entry>4491</entry>
<entry>If the vendor option is present, it returns the
value of the enterprise-id field padded to 4
- bytes. Returns '' otherwise.</entry>
+ bytes. Returns "" otherwise.</entry>
</row>
<row>
<entry>Vendor sub-option existence</entry>
<entry>4491</entry>
<entry>If the vendor option is present, it returns the
value of the enterprise-id field padded to 4
- bytes. Returns '' otherwise.</entry>
+ bytes. Returns "" otherwise.</entry>
</row>
<row>
<entry>First data chunk from vendor class option</entry>
<entry>docsis3.0</entry>
<entry>Returns content of the first data chunk from
the vendor class option with specified enterprise-id.
- Returns '' if missing.</entry>
+ Returns "" if missing.</entry>
</row>
<row>
<entry>Specific data chunk from vendor class option</entry>
</tbody>
</tgroup>
</table>
- Hex Strings are converted into a string as expected. The starting "0X" or
+ Notes:
+ </para>
+
+ <itemizedlist>
+
+ <listitem><para>
+ Hexadecimal strings are converted into a string as expected. The starting "0X" or
"0x" is removed and if the string is an odd number of characters a
"0" is prepended to it.
- </para>
+ </para></listitem>
- <para>
+ <listitem><para>
IP addresses are converted into strings of length 4 or 16. IPv4, IPv6,
and IPv4 embedded IPv6 (e.g., IPv4 mapped IPv6) addresses are supported.
- </para>
+ </para></listitem>
- <para>
+ <listitem><para>
Integers in an expression are converted to 32 bit unsigned integers and
- are represented as four byte strings. For example 123 is represented as
- 0x0000007b. All expressions that return numeric values use 32 bit
+ are represented as four-byte strings. For example 123 is represented as
+ 0x0000007b. All expressions that return numeric values use 32-bit
unsigned integers, even if the field in the packet is smaller. In general
it is easier to use decimal notation to represent integers, but it is also
possible to use hex notation. When using hex notation to represent an
bits, e.g. use 0x00000001 instead of 0x1 or 0x01. Also, make
sure the value is specified in network order, e.g. 1 is
represented as 0x00000001.
- </para>
+ </para></listitem>
- <para>
+ <listitem><para>
"option[code].hex" extracts the value of the option with the code "code"
from the incoming packet. If the packet doesn't contain the option, it
returns the empty string. The string is presented as a byte string of
the option payload without the type code or length fields.
- </para>
+ </para></listitem>
- <para>
+ <listitem><para>
"option[code].exists" checks if an option with the code "code" is present
in the incoming packet. It can be used with empty options.
- </para>
+ </para></listitem>
- <para>
- "relay4[code].hex" attempts to extract the value of the sub-option
- "code" from the option inserted as the DHCPv4 Relay Agent Information
- (82) option. If the packet doesn't contain a RAI option, or the RAI
- option doesn't contain the requested sub-option, the expression returns
- an empty string. The string is presented as a byte string of the
- option payload without the type code or length fields. This
- expression is allowed in DHCPv4 only.
- </para>
+ <listitem><para>
+ "relay4[code].hex" attempts to extract the value of the sub-option
+ "code" from the option inserted as the DHCPv4 Relay Agent Information
+ (82) option. If the packet doesn't contain a RAI option, or the RAI
+ option doesn't contain the requested sub-option, the expression returns
+ an empty string. The string is presented as a byte string of the
+ option payload without the type code or length fields. This
+ expression is allowed in DHCPv4 only.
+ </para></listitem>
- <para>
- "relay4" shares the same representation types as "option", for
- instance "relay4[code].exists" is supported.
- </para>
+ <listitem><para>
+ "relay4" shares the same representation types as "option", for
+ instance "relay4[code].exists" is supported.
+ </para></listitem>
- <para>
- "relay6[nest]" allows access to the encapsulations used by any DHCPv6
- relays that forwarded the packet. The "nest" level specifies the relay
- from which to extract the information, with a value of 0 indicating
- the relay closest to the DHCPv6 server. If the requested encapsulation
- doesn't exist an empty string "" is returned. This expression is
- allowed in DHCPv6 only.
- </para>
+ <listitem><para>
+ "relay6[nest]" allows access to the encapsulations used by any DHCPv6
+ relays that forwarded the packet. The "nest" level specifies the relay
+ from which to extract the information, with a value of 0 indicating
+ the relay closest to the DHCPv6 server. If the requested encapsulation
+ doesn't exist an empty string "" is returned. This expression is
+ allowed in DHCPv6 only.
+ </para></listitem>
- <para>
- "relay6[nest].option[code]" shares the same representation types as
- "option", for instance "relay6[nest].option[code].exists" is supported.
- </para>
+ <listitem><para>
+ "relay6[nest].option[code]" shares the same representation types as
+ "option", for instance "relay6[nest].option[code].exists" is supported.
+ </para></listitem>
- <para>
- Expressions starting with "pkt4" can be used only in DHCPv4.
- They allows access to DHCPv4 message fields.
- </para>
+ <listitem><para>
+ Expressions starting with "pkt4" can be used only in DHCPv4.
+ They allows access to DHCPv4 message fields.
+ </para></listitem>
- <para>
- "pkt6" refers to information from the client request. To access any
- information from an intermediate relay use "relay6". "pkt6.msgtype"
- and "pkt6.transid" output a 4 byte binary string for the message type
- or transaction id. For example the message type SOLICIT will be
- "0x00000001" or simply 1 as in "pkt6.msgtype == 1".
- </para>
+ <listitem><para>
+ "pkt6" refers to information from the client request. To access any
+ information from an intermediate relay use "relay6". "pkt6.msgtype"
+ and "pkt6.transid" output a 4 byte binary string for the message type
+ or transaction id. For example the message type SOLICIT will be
+ "0x00000001" or simply 1 as in "pkt6.msgtype == 1".
+ </para></listitem>
- <para>
- Vendor option means Vendor-Identifying Vendor-specific Information
- option (code 125, see Section 4 of RFC3925) in DHCPv4 and
- Vendor-specific Information Option (code 17, defined in Section 22.17 of
- RFC3315) in DHCPv6. Vendor class option means Vendor-Identifying Vendor
- Class Option (code 124, see Section 3 of RFC3925) in DHCPv4 and Vendor
- Class Option (code 16, see Section 22.16 of RFC3315). Vendor options may
- have sub-options that are referenced by their codes. Vendor class
- options do not have sub-options, but rather data chunks, which are
- referenced by index value. Index 0 means the first data chunk, Index 1
- is for the second data chunk (if present), etc.
- </para>
+ <listitem><para>
+ Vendor option means Vendor-Identifying Vendor-specific Information
+ option (code 125, see
+ <ulink url="http://tools.ietf.org/html/rfc3925#section-4">Section 4 of RFC 3925</ulink>) in DHCPv4 and
+ Vendor-specific Information Option (code 17, defined in
+ <ulink url="https://tools.ietf.org/html/rfc3315#section-22.17">Section 22.17 of
+ RFC 3315</ulink>) in DHCPv6. Vendor class option means Vendor-Identifying Vendor
+ Class Option (code 124, see
+ <ulink url="http://tools.ietf.org/html/rfc3925#section-3">Section 3 of RFC 3925</ulink>) in DHCPv4 and
+ Class Option (code 16, see
+ <ulink url="https://tools.ietf.org/html/rfc3315#section-22.16">Section 22.16 of RFC 3315</ulink>).
+ Vendor options may
+ have sub-options that are referenced by their codes. Vendor class
+ options do not have sub-options, but rather data chunks, which are
+ referenced by index value. Index 0 means the first data chunk, Index 1
+ is for the second data chunk (if present), etc.
+ </para></listitem>
- <para>In the vendor and vendor-class constructs Asterisk (*) or 0 can be
+ <listitem><para>
+ In the vendor and vendor-class constructs Asterisk (*) or 0 can be
used to specify a wildcard enterprise-id value, i.e. it will match any
- enterprise-id value.</para>
+ enterprise-id value.
+ </para></listitem>
- <para>Vendor Class Identifier (option 60 in DHCPv4) can be
- accessed using option[60] expression.</para>
+ <listitem><para>Vendor Class Identifier (option 60 in DHCPv4) can be
+ accessed using option[60] expression.</para></listitem>
- <para>RFC3925 and RFC3315 allow for multiple instances of vendor options
+ <listitem><para>
+ <ulink url="http://tools.ietf.org/html/rfc3925">RFC3925</ulink> and
+ <ulink url="http://tools.ietf.org/html/rfc3315">RFC3315</ulink>
+ allow for multiple instances of vendor options
to appear in a single message. The client classification code currently
examines the first instance if more than one appear. For vendor.enterprise
and vendor-class.enterprise expressions, the value from the first instance
is returned. Please submit a feature request on Kea website if you need
- support for multiple instances.</para>
+ support for multiple instances.
+ </para></listitem>
+
+ </itemizedlist>
<para>
<table frame="all" id="classification-expressions-list">
<section>
<title>Logical operators</title>
The Not, And and Or logical operators are the common operators. Not
- has the highest precedence, Or the lowest. And and Or are (left)
+ has the highest precedence and Or the lowest. And and Or are (left)
associative, parentheses around a logical expression can be used
to enforce a specific grouping, for instance in "A and (B or C)"
(without parentheses "A and B or C" means "(A and B) or C").
<para>
In the following example the class named "Client_foo" is defined.
- It is comprised of all clients who's client ids (option 61) start with the
+ It is comprised of all clients whose client ids (option 61) start with the
string "foo". Members of this class will be given 192.0.2.1 and
192.0.2.2 as their domain name servers.
<title>Configuring Subnets With Class Information</title>
<para>
In certain cases it beneficial to restrict access to certain subnets
- only to clients that belong to a given class using the "client-class"
+ only to clients that belong to a given class, using the "client-class"
keyword when defining the subnet.
</para>
expression would either be complex or time consuming and be easier or
better to write as code. Once the hook has added the proper class name
to the packet the rest of the classification system will work as normal
- in choosing a subnet and selecting options. For a description of the
+ in choosing a subnet and selecting options. For a description of
hooks see <xref linkend="hooks-libraries"/>, for a description on
- configuring he classes see <xref linkend="classification-configuring"/>
+ configuring classes see <xref linkend="classification-configuring"/>
and <xref linkend="classification-subnets"/>.
</para>
</section>
<para>
The list of tokens is created when the configuration file is processed with
most expressions and values being converted to a token. The list is organized
- in reverse Polish notation. During execution the list will be traversed
+ in reverse Polish notation. During execution, the list will be traversed
in order. As each token is executed it will be able to pop values
from the top of the stack and eventually push its result on the top of the
stack. Imagine the following expression:
</para>
<para>
- When debug logging is enabled each time a token is evaluated it will
- emit a log line indicating the values of any objects that were popped
+ When debug logging is enabled, each time a token is evaluated it will
+ emit a log message indicating the values of any objects that were popped
off of the value stack and any objects that were pushed onto the value
stack.
</para>
<para>
The values will be displayed as either text if the command is known
- to use text values or hex if the command either uses binary values or
+ to use text values or hexadecimal if the command either uses binary values or
can manipulate either text or binary values. For expressions that
- pop multiple values off the stack the values will be displayed in
+ pop multiple values off the stack, the values will be displayed in
the order they were popped. For most expressions this won't matter
but for the concat expression the values are displayed in reverse
order from how they are written in the expression.
2016-05-19 13:35:04.163 DEBUG [kea.eval/44478] EVAL_DEBUG_OPTION Pushing option 61 with value 0x666F6F626172
2016-05-19 13:35:04.164 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '0'
2016-05-19 13:35:04.165 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '3'
- 2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0,
- string 0x666F6F626172 pushing result 0x666F6F
+ 2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0, string 0x666F6F626172 pushing result 0x666F6F
2016-05-19 13:35:04.167 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string 'foo'
2016-05-19 13:35:04.168 DEBUG [kea.eval/44478] EVAL_DEBUG_EQUAL Popping 0x666F6F and 0x666F6F pushing result 'true'
</screen>
<note><para>
The debug logging may be quite verbose if you have a number of expressions
- to evaluate. It is intended as an aide in helping you create and debug
+ to evaluate. It is intended as an aid in helping you create and debug
your expressions. You should plan to disable debug logging when you have your
expressions working correctly. You also may wish to include only one set of
expressions at a time in the configuration file while debugging them in order
- module => daemon
-->
- <chapter id="logging">
- <title>Logging</title>
+<chapter id="logging">
+ <title>Logging</title>
+
+ <section>
+ <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
+ 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.
+ </para>
+
+ <para>
+ The logging system in Kea is configured through the
+ Logging section in your configuration
+ file. All daemons (e.g. DHCPv4 and DHCPv6 servers) will use the
+ configuration in the Logging section to see
+ what should be logged and to where. This allows for sharing identical
+ logging configuration between daemons.
+ </para>
<section>
- <title>Logging Configuration</title>
+ <title>Loggers</title>
+ <para>
+ 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 uses 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,
+ use their own loggers.
+ </para>
<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
- 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.
+ 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 output by 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.
</para>
<para>
- The logging system in Kea is configured through the
- <replaceable>Logging</replaceable> structure in your configuration
- file. All daemons (e.g. DHCPv4 and DHCPv6 servers) will use the
- configuration in the <replaceable>Logging</replaceable> structure to see
- what should be logged and to where. This allows for sharing identical
- logging configuration between daemons.
+ In the Logging section 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: these cause Kea to log messages of INFO
+ severity or greater to standard output.
+ <!-- @todo: add reference to section about controlling default
+ behavior with env. variables, after #3591 is merged. -->
</para>
- <section>
- <title>Loggers</title>
+ <para>
+ The three main elements of a logger configuration are:
+ <command>name</command> (the component that is generating the messages),
+ the <command>severity</command> (what to log), and the
+ <command>output_commands</command> (where to log). There is also a
+ <command>debuglevel</command> element, which is only relevant if
+ debug-level logging has been selected.
+ </para>
+ <section>
+ <title>name (string)</title>
<para>
- 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.
+ 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 <quote>kea-dhcp4</quote>. 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).
</para>
<para>
- 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.
+ When tracking down an issue with the server's operation, use of
+ DEBUG logging is required to obtain the verbose output needed for
+ problems diagnosis. However, the high verbosity is likely to
+ overwhelm the logging system in cases when the server
+ is processing high volume traffic. To mitigate this problem, use
+ can be made of the fact that Kea uses multiple loggers for different
+ functional parts of the server and that each of these can be configured independently.
+ If the user is reasonably confident that a problem originates
+ in a specific function of the server, or that the problem is related
+ to the specific type of operation, they may enable high verbosity
+ only for the relevant logger, so limiting the debug messages
+ to the required minimum.
</para>
<para>
- In the <quote>Logging</quote> 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.
- <!-- @todo: add reference to section about controlling default
- behavior with env. variables, after #3591 is merged. -->
+ 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.
</para>
<para>
- The three most important elements of a logger configuration
- are the <option>name</option> (the component that is
- generating the messages), the <option>severity</option>
- (what to log), and the <option>output_options</option>
- (where to log).
+ The loggers form a hierarchy. For each program in Kea, there is
+ a "root" logger, named after the program (e.g. the root logger for
+ kea-dhcp (the DHCPv4 server) is named kea-dhcp4. All other loggers
+ are children of this logger, and are named accordingly, e.g. the
+ the allocation engine in the DHCPv4 server logs messages using
+ a logger called kea-dhcp4.alloc-engine.
</para>
- <section>
- <title>name (string)</title>
-
- <para>
- 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 <quote>kea-dhcp4</quote>. 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).
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
+ <para>
+ This relationship is important as each child logger derives its
+ default configuration from its parent root logger.
+ In the typical case, the root logger configuration
+ is the only logging configuration specified in the configuration
+ file and so applies to all loggers. If an entry is made for
+ a given logger, any attributes specified override those of
+ the root logger, whereas any not specified are inherited from it.
+ </para>
- To illustrate this, suppose you are using the DHCPv4 server
- with the root logger <quote>kea-dhcp4</quote> 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 <quote>kea-dhcp4.bad-packets</quote> 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.
- </para>
+ <para>
+ To illustrate this, suppose you are using the DHCPv4 server
+ with the root logger <quote>kea-dhcp4</quote> 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 <quote>kea-dhcp4.bad-packets</quote> 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.
+ </para>
<!-- we don't support asterisk anymore.
<para>
daemon is using it).
</para> -->
- <para>
- 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 <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
- according to the configuration in the first entry
- (<quote>kea-dhcp4</quote>).
- </para>
-
- <para>
- Currently defined loggers are:
- </para>
+ <para>
+ 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 <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
+ according to the configuration in the first entry
+ (<quote>kea-dhcp4</quote>).
+ </para>
+ <para>
+ Currently defined loggers are:
+ </para>
<itemizedlist>
<listitem>
- <simpara><command>kea-dhcp4</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp4</command> - the root logger for the DHCPv4
+ server. All components used by the DHCPv4 server inherit the
+ settings from this logger.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.alloc-engine</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp4.alloc-engine</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.bad-packets</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp4.bad-packets</command> - used by the DHCPv4
+ server daemon 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.callouts</command> - this logger is used
- to log messages pertaining to the callouts registration and execution
- for the particular hook point.
+ <simpara>
+ <command>kea-dhcp4.callouts</command> - used to log messages
+ pertaining to the callouts registration and execution for the
+ particular hook point.
</simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.commands</command> - this logger is used
- to log messages relating to the handling of commands received by the
- the DHCPv4 server over the command channel.
+ <simpara>
+ <command>kea-dhcp4.commands</command> - used to log messages
+ relating to the handling of commands received by the the DHCPv4
+ server over the command channel.
</simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.ddns</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp4.ddns</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.dhcp4</command> - this is the logger
- by the DHCPv4 server daemon to log basic operations.</simpara>
+ <simpara>
+ <command>kea-dhcp4.dhcp4</command> - used by the DHCPv4 server
+ daemon to log basic operations.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.dhcpsrv</command> - this is a base
- logger for the libdhcpsrv library.</simpara>
+ <simpara>
+ <command>kea-dhcp4.dhcpsrv</command> - the base logger for the
+ libdhcpsrv library.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.eval</command> - this logger is used
- to log messages relating to the client classification expression
- evaluation code.</simpara>
+ <simpara>
+ <command>kea-dhcp4.eval</command> - used to log messages relating
+ to the client classification expression evaluation code.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.hooks</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp4.hooks</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.hosts</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp4.hosts</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.leases</command> - 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.
+ <simpara>
+ <command>kea-dhcp4.leases</command> - 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.
</simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.options</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp4.options</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp4.packets</command> - 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.
+ <simpara>
+ <command>kea-dhcp4.packets</command> - 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 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 and/or interface names, which
+ can be retrieved from the received packet, even before the DHCPv4
+ message carried in the packet is parsed.
</simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp6</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.alloc-engine</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp6.alloc-engine</command> - used 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.bad-packets</command> - this is the
- logger used by the DHCPv6 server daemon for logging inbound client
- packets that were dropped.</simpara>
+ <simpara>
+ <command>kea-dhcp6.bad-packets</command> - used used by the DHCPv6
+ server daemon for logging inbound client packets that were
+ dropped.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.callouts</command> - this logger is used
- to log messages pertaining to the callouts registration and execution
- for the particular hook point.
+ <simpara>
+ <command>kea-dhcp6.callouts</command> - used to log messages
+ pertaining to the callouts registration and execution for the
+ particular hook point.
</simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.commands</command> - this logger is used
- to log messages relating to the handling of commands received by the
- the DHCPv6 server over the command channel.
+ <simpara>
+ <command>kea-dhcp6.commands</command> - used to log messages
+ relating to the handling of commands received by the the DHCPv6
+ server over the command channel.
</simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.ddns</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp6.ddns</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.dhcp6</command> - this is the logger
- used DHCPv6 server daemon to log basic operations.</simpara>
+ <simpara>
+ <command>kea-dhcp6.dhcp6</command> - used DHCPv6 server daemon to
+ log basic operations.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.dhcpsrv</command> - this is a base
- logger for the libdhcpsrv library.</simpara>
+ <simpara>
+ <command>kea-dhcp6.dhcpsrv</command> - the base logger for the
+ libdhcpsrv library.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.eval</command> - this logger is used
- to log messages relating to the client classification expression
- evaluation code.</simpara>
+ <simpara>
+ <command>kea-dhcp6.eval</command> - used to log messages relating
+ to the client classification expression evaluation code.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.hooks</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp6.hooks</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.hosts</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp6.hosts</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.leases</command> - 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.
+ <simpara>
+ <command>kea-dhcp6.leases</command> - 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.
</simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.options</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp6.options</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp6.packets</command> - 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.
+ <simpara>
+ <command>kea-dhcp6.packets</command> - 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.
</simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp-ddns</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp-ddns</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp-ddns.dhcpddns</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp-ddns.dhcpddns</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp-ddns.dhcp-to-d2</command> - 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.</simpara>
+ <simpara>
+ <command>kea-dhcp-ddns.dhcp-to-d2</command> - 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.
+ </simpara>
</listitem>
+
<listitem>
- <simpara><command>kea-dhcp-ddns.d2-to-dns</command> - 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.
+ <simpara>
+ <command>kea-dhcp-ddns.d2-to-dns</command> - used by the
+ kea-dhcp-ddns daemon for logging information about events dealing
+ with sending and receiving messages with the DNS servers.
</simpara>
</listitem>
-
</itemizedlist>
<para>
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
- <quote>libpacket-capture</quote> to dump packets received and
+ loggers but should define new loggers with names that correspond to
+ the libraries using them. Suppose that the user created the library
+ called <quote>libpacket-capture</quote> to dump packets received and
transmitted by the server to the file. The appropriate name for the
- logger could be <command>kea-dhcp4.packet-capture</command>. Note
- that the hook library implementor only specifies the second part
- of this name, i.e. <quote>packet-capture</quote>. 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.
+ logger could be <command>kea-dhcp4.packet-capture</command>. (Note
+ that the hook library implementor only specifies the second part of
+ this name, i.e. <quote>packet-capture</quote>. 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, something
+ that can be overridden by an entry in the configuration file.
</para>
<para>
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.
+ libraries. Please consult the documentation for the libraries for the
+ names of the loggers they define.
</para>
- <para>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
- <xref linkend="logging-message-format"/> for details.</para>
- </section>
-
- <section>
- <title>severity (string)</title>
+ <para>
+ Additional loggers may be defined in future versions of Kea. 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
+ <xref linkend="logging-message-format"/> for details.
+ </para>
+ </section>
+ <section>
+ <title>severity (string)</title>
<para>
- 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):
+ 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):
</para>
<itemizedlist>
<listitem>
- <simpara> FATAL </simpara>
+ <simpara>
+ FATAL - associated with messages generated by a condition that is
+ so serious that the server cannot continue executing.
+ </simpara>
</listitem>
<listitem>
- <simpara> ERROR </simpara>
+ <simpara>
+ ERROR- associated with messages generated by an error condition.
+ The server will continue executing, but the results may not be as
+ expected.
+ </simpara>
</listitem>
<listitem>
- <simpara> WARN </simpara>
+ <simpara>
+ WARN - indicates an out of the ordinary condition. However, the
+ server will continue executing normally.
+ </simpara>
</listitem>
<listitem>
- <simpara> INFO </simpara>
+ <simpara>
+ INFO - an informational message marking some event.
+ </simpara>
</listitem>
<listitem>
- <simpara> DEBUG </simpara>
+ <simpara>
+ DEBUG - messages produced for debugging purposes.
+ </simpara>
</listitem>
</itemizedlist>
<para>
-
- 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.
-
-<!-- TODO: worded wrong? If I set to INFO, why would it show DEBUG which is literally below in that list? -->
-
+ When the severity of a logger is set to one of these values, it will
+ only log messages of that severity and above (e.g. setting the logging
+ severity to INFO will log INFO, WARN, ERROR and FATAL messages). The
+ severity may also be set to NONE, in which case all messages from that
+ logger are inhibited.
</para>
<note>
<para>
The keactrl tool, described in <xref linkend="keactrl"/>, can be
- configured to start the servers in the verbose mode. If this is
- the case, the settings of the logging severity in the configuration
- file will have no effect, i.e. the servers will use logging severity
- of DEBUG regardless of the logging settings specified in the configuration
- file. If you need to control severity via configuration file, please
- make sure that the <parameter>kea_verbose</parameter> value is set to
- "no" within the keactrl configuration.
+ configured to start the servers in the verbose mode. If this is the
+ case, the settings of the logging severity in the configuration file
+ will have no effect, i.e. the servers will use logging severity of
+ DEBUG regardless of the logging settings specified in the
+ configuration file. If you need to control severity via
+ configuration file, please make sure that the
+ <parameter>kea_verbose</parameter> value is set to "no" within the
+ keactrl configuration.
</para>
</note>
+ </section>
- </section>
-
- <section>
- <title>output_options (list)</title>
-
- <para>
-
- Each logger can have zero or more
- <option>output_options</option>. These specify where log
- messages are sent. These are explained in detail below.
-
- </para>
-
- <para>
-
- The other options for a logger are:
-
- </para>
-
- </section>
-
- <section>
- <title>debuglevel (integer)</title>
-
- <para>
-
- 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).
- </para>
-
-
-<!-- TODO: complete this sentence:
-
- The general classification of debug message types is
-
-TODO; there's a ticket to determine these levels, see #1074
-
- -->
-
+ <section>
+ <title>debuglevel (integer)</title>
<para>
-
- If severity for the logger is not DEBUG, this value is ignored.
-
+ When a logger's severity is set to DEBUG, this value specifies what
+ level of 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.
</para>
-
- </section>
</section>
<section>
- <title>Output Options</title>
-
+ <title>output_options (list)</title>
<para>
-
- The main settings for an output option are the
- <option>destination</option> and a value called
- <option>output</option>, the meaning of which depends on
- the destination that is set.
-
+ Each logger can have zero or more <option>output_options</option>.
+ These specify where log messages are sent. These are explained in
+ detail below.
</para>
<section>
- <title>destination (string)</title>
-
+ <title>output (string)</title>
<para>
-
- The destination is the type of output. It can be one of:
-
+ 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 to which messages should be written.
</para>
-
- <itemizedlist>
-
- <listitem>
- <simpara> console </simpara>
- </listitem>
-
- <listitem>
- <simpara> file </simpara>
- </listitem>
-
- <listitem>
- <simpara> syslog </simpara>
- </listitem>
-
- </itemizedlist>
-
</section>
- <section>
- <title>output (string)</title>
-
- <para>
- 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>
-
- <para>
-
- The other options for <option>output_options</option> are:
-
- </para>
-
<section>
<title>flush (true of false)</title>
-
<para>
- 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.
+ 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.
+ The default is "true".
</para>
-
</section>
<section>
<title>maxsize (integer)</title>
-
<para>
- 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.)
+ 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.)
</para>
-
<para>
- If this is 0, no maximum file size is used.
+ If this is set to 0 or omitted, no maximum file size is used.
</para>
<note>
<simpara>
- 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.
- </simpara>
- </note>
-
+ 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 version or later of log4cplus is used to
+ build Kea, it should not happen. Even for older versions it is
+ normally expected to happen rarely unless the log messages are
+ produced very frequently by multiple different processes.
+ </simpara>
+ </note>
</section>
<section>
<title>maxver (integer)</title>
-
<para>
- Maximum number of old log files to keep around when
- rolling the output file. Only relevant when
- <option>output</option> is <quote>file</quote>.
+ Maximum number of old log files to keep around when rolling the
+ output file. Only relevant when <option>output</option> is
+ <quote>file</quote>.
</para>
-
</section>
-
- </section>
-
</section>
<section>
<title>Example Logger Configurations</title>
-
<para>
- In this example we want to set the global logging to
- write to the console using standard output.
+ In this example we want to set the global logging to write to the
+ console using standard output.
</para>
-<screen><userinput>
-"Logging": {
+<screen><userinput>"Logging": {
"loggers": [
{
"name": "kea-dhcp4",
"severity": "WARN"
}
]
-}
-</userinput>
-</screen>
+}</userinput> </screen>
-<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>
+ <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": {
+<screen><userinput>"Logging": {
"loggers": [
{
"name": "kea-dhcp6",
<section id="logging-message-format">
<title>Logging Message Format</title>
-
<para>
- Each message written to the configured logging
- destinations comprises a number of components that identify
- the origin of the message and, if the message indicates
- a problem, information about the problem that may be
- useful in fixing it.
+ Each message written to the configured logging destinations comprises a
+ number of components that identify the origin of the message and, if the
+ message indicates a problem, information about the problem that may be
+ useful in fixing it.
</para>
<para>
- Consider the message below logged to a file:
- <screen>2014-04-11 12:58:01.005 INFO [kea-dhcp4.dhcpsrv/27456]
+ Consider the message below logged to a file:
+
+<screen>2014-04-11 12:58:01.005 INFO [kea-dhcp4.dhcpsrv/27456]
DHCPSRV_MEMFILE_DB opening memory file lease database: type=memfile universe=4</screen>
</para>
<para>
- Note: the layout of messages written to the system logging
- file (syslog) may be slightly different. This message has
- been split across two lines here for display reasons; in the
- logging file, it will appear on one line.
+ Note: the layout of messages written to the system logging file (syslog)
+ may be slightly different. This message has been split across two lines
+ here for display reasons; in the logging file, it will appear on one
+ line.
</para>
<para>
The log message comprises a number of components:
- <variablelist>
- <varlistentry>
- <term>2014-04-11 12:58:01.005</term>
+ <variablelist>
+ <varlistentry>
+ <term>2014-04-11 12:58:01.005</term>
<!-- TODO: timestamp repeated even if using syslog? -->
- <listitem><para>
- The date and time at which the message was generated.
- </para></listitem>
+ <listitem>
+ <para>
+ The date and time at which the message was generated.
+ </para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>INFO</term>
- <listitem><para>
- The severity of the message.
- </para></listitem>
+ <term>INFO</term>
+ <listitem>
+ <para>
+ The severity of the message.
+ </para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>[kea-dhcp4.dhcpsrv/27456]</term>
- <listitem><para>
- The source of the message. This comprises two elements:
- the Kea process generating the message (in this
- case, <command>kea-dhcp4</command>) and the component
- within the program from which the message originated
- (which is the name of the common library used by DHCP server
- implementations). The number after the slash is a process id
- (pid).
- </para></listitem>
+ <term>[kea-dhcp4.dhcpsrv/27456]</term>
+ <listitem>
+ <para>
+ The source of the message. This comprises two elements: the Kea
+ process generating the message (in this case,
+ <command>kea-dhcp4</command>) and the component within the
+ program from which the message originated
+ (<command>dhcpsrv</command>, which is the name of the common
+ library used by DHCP server implementations). The number after
+ the slash is a process id (pid).
+ </para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>DHCPSRV_MEMFILE_DB</term>
- <listitem><para>
- The message identification. Every message in Kea
- has a unique identification, which can be used as an
- index into the <ulink
- url="kea-messages.html"><citetitle>Kea Messages
- Manual</citetitle></ulink> (<ulink
- url="http://kea.isc.org/docs/kea-messages.html"
- />) from which more information can be obtained.
- </para></listitem>
+ <term>DHCPSRV_MEMFILE_DB</term>
+ <listitem>
+ <para>
+ The message identification. Every message in Kea has a unique
+ identification, which can be used as an index into the
+ <ulink url="kea-messages.html"><citetitle>Kea Messages
+ Manual</citetitle></ulink>
+ (<ulink url="http://kea.isc.org/docs/kea-messages.html" />)
+ from which more information can be obtained.
+ </para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>opening memory file lease database: type=memfile universe=4</term>
- <listitem><para>
- A brief description.
- Within this text, information relating to the condition
- that caused the message to be logged will be included.
- In this example, the information is logged that the in-memory
- lease database backend will be used to store DHCP leases.
- </para></listitem>
+ <term>opening memory file lease database: type=memfile universe=4</term>
+ <listitem>
+ <para>
+ A brief description. Within this text, information relating to
+ the condition that caused the message to be logged will be
+ included. In this example, the information is logged that the
+ in-memory lease database backend will be used to store DHCP
+ leases.
+ </para>
+ </listitem>
</varlistentry>
- </variablelist>
+ </variablelist>
</para>
-
</section>
<section>
<title>Logging During Kea Startup</title>
-
<para>
The logging configuration is specified in the configuration file.
However, when Kea starts, the file is not read until some way into the
- initialization process. Prior to that, the logging settings are
- set to default values, although it is possible to modify some
- aspects of the settings by means of environment variables. Note
- that in the absence of any logging configuration in the configuration
- file, the settings of (possibly modified) default configuration will
- persist while the program is running.
+ initialization process. Prior to that, the logging settings are set to
+ default values, although it is possible to modify some aspects of the
+ settings by means of environment variables. Note that in the absence of
+ any logging configuration in the configuration file, the settings of
+ (possibly modified) default configuration will persist while the program
+ is running.
</para>
<para>
- The following environment variables can be used to control the
- behavior of logging during startup:
+ The following environment variables can be used to control the behavior
+ of logging during startup:
</para>
- <variablelist>
- <varlistentry>
+ <variablelist>
+ <varlistentry>
<term>KEA_LOCKFILE_DIR</term>
- <listitem><para>
+ <listitem>
+ <para>
Specifies a directory where the logging system should create its
lock file. If not specified, it is
<replaceable>prefix</replaceable>/var/run/kea, where
- <replaceable>prefix</replaceable> defaults to /usr/local.
- This variable must not end
- with a slash. There is one special value: "none", which
- instructs Kea to not create lock file at all. This may cause
- issues if several processes log to the same file.
- </para></listitem>
- </varlistentry>
+ <replaceable>prefix</replaceable> defaults to /usr/local. This
+ variable must not end with a slash. There is one special value:
+ "none", which instructs Kea to not create lock file at all. This
+ may cause issues if several processes log to the same file.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
+ <varlistentry>
<term>KEA_LOGGER_DESTINATION</term>
- <listitem><para>
+ <listitem>
+ <para>
Specifies logging output. There are several special values.
<variablelist>
- <varlistentry>
- <term>stdout</term>
- <listitem><para>
- Log to standard output.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>stderr</term>
- <listitem><para>
- Log to standard error.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>syslog<optional>:<replaceable>fac</replaceable></optional></term>
- <listitem><para>
- Log via syslog. The optional
- <replaceable>fac</replaceable> (which is
- separated from the word "syslog" by a colon)
- specifies the
- facility to be used for the log messages. Unless
- specified, messages will be logged using the
- facility "local0".
- </para></listitem>
- </varlistentry>
+ <varlistentry>
+ <term>stdout</term>
+ <listitem>
+ <para>
+ Log to standard output.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>stderr</term>
+ <listitem>
+ <para>
+ Log to standard error.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>syslog<optional>:<replaceable>fac</replaceable></optional></term>
+ <listitem>
+ <para>
+ Log via syslog. The optional
+ <replaceable>fac</replaceable> (which is separated from
+ the word "syslog" by a colon) specifies the facility to be
+ used for the log messages. Unless specified, messages will
+ be logged using the facility "local0".
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
- Any other value is treated as a name
- of the output file. If not specified otherwise, Kea will log to
- standard output.
- </para></listitem>
- </varlistentry>
-
- </variablelist>
+ Any other value is treated as a name of the output file. If not
+ specified otherwise, Kea will log to standard output.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
-
- </chapter>
+ </section>
+</chapter>
projects / thirdparty / kea.git / commitdiff
