From: Stephen Morris Date: Tue, 20 Sep 2016 14:20:43 +0000 (+0100) Subject: [5008] Editing changes to chapters 9 through 18 of the Kea guide X-Git-Tag: trac5049_base~1^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=316f3b2f3972b9c380795a05376125891fd16d63;p=thirdparty%2Fkea.git [5008] Editing changes to chapters 9 through 18 of the Kea guide --- diff --git a/doc/guide/classify.xml b/doc/guide/classify.xml index 3ddfab98c7..bba282e775 100644 --- a/doc/guide/classify.xml +++ b/doc/guide/classify.xml @@ -58,7 +58,7 @@ 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 @@ -68,7 +68,8 @@ - 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 @@ -131,9 +132,9 @@ 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. @@ -146,7 +147,7 @@ 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. @@ -360,7 +361,7 @@ 4491 If the vendor option is present, it returns the value of the enterprise-id field padded to 4 - bytes. Returns '' otherwise. + bytes. Returns "" otherwise. Vendor sub-option existence @@ -401,7 +402,7 @@ 4491 If the vendor option is present, it returns the value of the enterprise-id field padded to 4 - bytes. Returns '' otherwise. + bytes. Returns "" otherwise. First data chunk from vendor class option @@ -409,7 +410,7 @@ docsis3.0 Returns content of the first data chunk from the vendor class option with specified enterprise-id. - Returns '' if missing. + Returns "" if missing. Specific data chunk from vendor class option @@ -423,20 +424,26 @@ - Hex Strings are converted into a string as expected. The starting "0X" or + Notes: + + + + + + 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. - + - + 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. - + - + 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 @@ -444,88 +451,101 @@ 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. - + - + "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. - + - + "option[code].exists" checks if an option with the code "code" is present in the incoming packet. It can be used with empty options. - + - - "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. - + + "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. + - - "relay4" shares the same representation types as "option", for - instance "relay4[code].exists" is supported. - + + "relay4" shares the same representation types as "option", for + instance "relay4[code].exists" is supported. + - - "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. - + + "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. + - - "relay6[nest].option[code]" shares the same representation types as - "option", for instance "relay6[nest].option[code].exists" is supported. - + + "relay6[nest].option[code]" shares the same representation types as + "option", for instance "relay6[nest].option[code].exists" is supported. + - - Expressions starting with "pkt4" can be used only in DHCPv4. - They allows access to DHCPv4 message fields. - + + Expressions starting with "pkt4" can be used only in DHCPv4. + They allows access to DHCPv4 message fields. + - - "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". - + + "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". + - - 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. - + + Vendor option means Vendor-Identifying Vendor-specific Information + option (code 125, see + Section 4 of RFC 3925) in DHCPv4 and + Vendor-specific Information Option (code 17, defined in + Section 22.17 of + RFC 3315) in DHCPv6. Vendor class option means Vendor-Identifying Vendor + Class Option (code 124, see + Section 3 of RFC 3925) in DHCPv4 and + Class Option (code 16, see + Section 22.16 of RFC 3315). + 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. + - In the vendor and vendor-class constructs Asterisk (*) or 0 can be + + 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. + enterprise-id value. + - Vendor Class Identifier (option 60 in DHCPv4) can be - accessed using option[60] expression. + Vendor Class Identifier (option 60 in DHCPv4) can be + accessed using option[60] expression. - RFC3925 and RFC3315 allow for multiple instances of vendor options + + RFC3925 and + RFC3315 + 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. + support for multiple instances. + + + @@ -557,7 +577,7 @@ concatenation of the strings
Logical operators 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"). @@ -626,7 +646,7 @@ concatenation of the strings 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. @@ -685,7 +705,7 @@ concatenation of the strings Configuring Subnets With Class Information 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. @@ -784,9 +804,9 @@ concatenation of the strings 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 , for a description on - configuring he classes see + configuring classes see and .
@@ -817,7 +837,7 @@ concatenation of the strings 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: @@ -836,17 +856,17 @@ concatenation of the strings - 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. 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. @@ -863,8 +883,7 @@ concatenation of the strings 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' @@ -872,7 +891,7 @@ concatenation of the strings 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 diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index 473089e021..8db374be5f 100644 --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@ -10,21 +10,21 @@ Management API A classic approach to daemon configuration assumes that - the server's configuration is stored in the configuration files - and when the configuration is changed, the daemon is restarted. + the server's configuration is stored in configuration files + and, when the configuration is changed, the daemon is restarted. This approach has the significant disadvantage of introducing periods of downtime, when client traffic is not handled. Another risk is that if the new configuration is invalid for whatever reason, the server may refuse to start, which will further extend the - downtime period, until the issue is resolved. + downtime period until the issue is resolved. - To avoid such problems, both DHCPv4 and DHCPv6 servers - introduced support for a mechanism that will allow - on-line reconfiguration, without requiring server shutdown. + To avoid such problems, both the DHCPv4 and DHCPv6 servers + include support for a mechanism that allows + on-line reconfiguration without requiring server shutdown. Both servers can be instructed to open control sockets, which is a communication channel. The server is able to receive commands on that channel, act on them and report back status. - While the set of commands supported in Kea 0.9.2 is limited, + While the set of commands in Kea 1.1.0 is limited, the number is expected to grow over time. Currently the only supported type of control channel @@ -35,10 +35,10 @@
- Data syntax - Communication over control channel is conducted using JSON - structures. If configured, Kea will open a socket and will listen - for any incoming connections. A process connecting to this socket + Data Syntax + Communication over the control channel is conducted using JSON + structures. If configured, Kea will open a socket and listen + for incoming connections. A process connecting to this socket is expected to send JSON commands structured as follows: @@ -55,7 +55,7 @@ command is the name of command to execute and is mandatory. arguments is a map of parameters required to carry out the given command. The exact content and - format is command specific. + format of the map is command specific. The server will process the incoming command and then send a response of the form: @@ -73,23 +73,23 @@ result indicates the outcome of the command. A value of 0 means success while any non-zero value designates an error. Currently 1 is used as a generic error, but additional error codes may be added in the - future. text field typically appears when result is + future. The text field typically appears when result is non-zero and contains a description of the error encountered, but it may - also appear for successful results. That's command specific. + also appear for successful results (that is command specific). arguments is a map of additional data values returned by - the server, specific to the command issued. The map is always present, even + the server which is specific to the command issued. The map is always present, even if it contains no data values.
- Using control channel + Using the Control Channel - ISC does not provide a client for using control channel. The primary - reason for that is the expectation is that the entity using control channel + Kea does not currently provide a client for using the control channel. The primary + reason for this is the expectation is that the entity using the control channel is typically an IPAM or similar network management/monitoring software which may have quite varied expectations regarding the client and is even likely to - be written in languages different than C or C++. Therefore we only provide - examples how one can take advantage of the API. + be written in languages different than C or C++. Therefore only examples are provided to show + how one can take advantage of the API. The easiest way is to use a tool called socat, a tool available from socat @@ -101,7 +101,8 @@ $ socat UNIX:/path/to/the/kea/socket - where /path/to/the/kea/socket is the path specified in the Dhcp4/control-socket/socket-name parameter in the Kea -configuration file. +configuration file. Text passed to socat +will be sent to Kea and the responses received from Kea printed to standard output. It is also easy to open UNIX socket programmatically. An example of such a simplistic client written in C is available in the Kea Developer's @@ -110,10 +111,10 @@ configuration file.
- Commands supported by both DHCPv4 and DHCPv6 servers + Commands Supported by Both the DHCPv4 and DHCPv6 Servers
- leases-reclaim command + leases-reclaim leases-reclaim command instructs the server to reclaim all expired leases immediately. The command has the following @@ -140,10 +141,10 @@ configuration file.
- list-commands command + list-commands - list-commands command retrieves a list of all + The list-commands command retrieves a list of all commands supported by the server. It does not take any arguments. An example command may look like this: @@ -161,10 +162,10 @@ configuration file.
- shutdown command + shutdown - shutdown command instructs the server to initiate + The shutdown command instructs the server to initiate its shutdown procedure. It is the equivalent of sending a SIGTERM signal to the process. This command does not take any arguments. An example command may look like this: diff --git a/doc/guide/ddns.xml b/doc/guide/ddns.xml index 5f741bb8f7..4a069f72b3 100644 --- a/doc/guide/ddns.xml +++ b/doc/guide/ddns.xml @@ -8,7 +8,8 @@ The DHCP-DDNS Server The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts the client side of - the DDNS protocol (defined in RFC 2136) on behalf of the DHCPv4 and DHCPv6 + the DDNS protocol (defined in RFC 2136) + on behalf of the DHCPv4 and DHCPv6 servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP servers construct DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP lease change events and then post these to D2. D2 attempts to match @@ -87,8 +88,11 @@ - -V - prints out Kea extended version with - additional parameters and exits. + -W - prints out the Kea configuration report + and exits. The report is a copy of the + config.report file produced by + ./configure: it is embedded in the + executable binary. @@ -99,19 +103,6 @@ - - The -V command returns the versions of the - external libraries dynamically linked. - - - - The -W command describes the environment used - to build Kea. This command displays a copy of the - config.report file produced by - ./configure that is embedded in the - executable binary. - - The config.report may also be accessed more directly. The following command may be used to extract this @@ -188,26 +179,22 @@ strings path/kea-dhcp-ddns | sed -n 's/;;;; //p' - Global Server Parameters - - values which control connectivity and global server behavior + Global Server Parameters - values which control connectivity and global server behavior - TSIG Key Info - - defines the TSIG keys used for secure traffic with DNS servers + TSIG Key Info - defines the TSIG keys used for secure traffic with DNS servers - Forward DDNS - - defines the catalog of Forward DDNS Domains + Forward DDNS - defines the catalog of Forward DDNS Domains - Reverse DDNS - - defines the catalog of Forward DDNS Domains + Reverse DDNS - defines the catalog of Forward DDNS Domains @@ -234,8 +221,7 @@ strings path/kea-dhcp-ddns | sed -n 's/;;;; //p' ncr-protocol - Socket protocol to use when sending requests to D2. - Currently only UDP is supported. TCP may be available in an upcoming - release. + Currently only UDP is supported. TCP may be available in a future release. @@ -347,7 +333,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. digest-bits - is used to specify the minimum truncated length in bits. - The default value 0 means truncation is forbidden, not 0 + The default value 0 means truncation is forbidden, non-zero values must be an integral number of octets, be greater than 80 and the half of the full length. Note in BIND9 this parameter is appended after a dash to the algorithm diff --git a/doc/guide/faq.xml b/doc/guide/faq.xml index 43badeddb2..66157bf292 100644 --- a/doc/guide/faq.xml +++ b/doc/guide/faq.xml @@ -18,7 +18,7 @@ it in the known issues list. -->
- Generic Frequently Asked Questions + General Frequently Asked Questions
Where did the Kea name came from? @@ -61,7 +61,8 @@ Accepted contributions range from minor documentation corrections to significant new features, like support for a new database type. Before considering writing and submitting a patch, make sure you read - the Contributor's Guide in Kea Developer's Guide. + the Contributor's Guide in the + Kea Developer's Guide. Kea is developed by ISC, which is a non-profit organization. diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index 3aeefebfb9..e25300add5 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -75,14 +75,6 @@ - - This is a change to the syntax used in Kea 0.9.2 and earlier, where - hooks-libraries was a list of strings, each string being the name of - a library. The change has been made in Kea 1.0 to facilitate the - specification of library-specific parameters, a feature that will be - added to a future version of Kea. - - The library reloading behavior has changed in Kea 1.1. Libraries are @@ -102,8 +94,8 @@ parameter), floor (integer parameter), debug (boolean parameter) and even lists (list of strings) and maps (containing strings). Nested parameters could be used if the library supports it. This topic is - explained in detail in the Hooks Developer's Guide in Configuring Hooks - Libraries section. + explained in detail in the Hooks Developer's Guide in the "Configuring + Hooks Libraries" section. diff --git a/doc/guide/lease-expiration.xml b/doc/guide/lease-expiration.xml index 2116dc4997..abca79b0f3 100644 --- a/doc/guide/lease-expiration.xml +++ b/doc/guide/lease-expiration.xml @@ -8,8 +8,8 @@ The primary role of the DHCP server is to assign addresses and/or delegate prefixes to DHCP clients. These addresses and prefixes are - often referred to as 'leases'. Leases are typically assigned to clients - for a finite amount of time, known as 'valid lifetime'. DHCP clients who + often referred to as "leases". Leases are typically assigned to clients + for a finite amount of time, known as the "valid lifetime". DHCP clients who wish to continue using their assigned leases, will periodically renew them by sending the appropriate message to the DHCP server. The DHCP server records the time when these leases are renewed and calculates new expiration times @@ -26,20 +26,20 @@ available for reassignment is referred to as "lease reclamation" and expired leases returned to availability through this process are referred to as "reclaimed". - - The DHCP server should reclaim an expired lease as soon as it detects - that it has expired. One way in which the server may detect expiration - is when it is trying to allocate a lease to a client and finds this - lease already present in the database but expired. Another way the - server detects expired leases is by periodically querying the lease + The DHCP server attempts to reclaim an expired lease as soon as it detects + that it has expired. One way in which the server detects expiration occurs + when it is trying to allocate a lease to a client and finds this + lease already present in the database but expired. Another way + is by periodically querying the lease database for them. Regardless of how an expired lease is detected, before - it my assigned to a client, it must be reclaimed. - + it may assigned to a client, it must be reclaimed. + + This chapter explains how to configure the server to periodically query - for the expired leases and how to minimize the impact of the periodic leases - reclamation process on the server's responsiveness. Finally, 'lease affinity', - which provides the means to assign the same lease to the returning client - after its lease has expired, is explained. + for the expired leases and how to minimize the impact of the periodic lease + reclamation process on the server's responsiveness. Finally, it explains + "lease affinity", which provides the means to assign the same lease to a + returning client after its lease has expired. Although, all configuration examples in this section are provided @@ -50,14 +50,14 @@
Lease Reclamation Lease reclamation is the process through which an expired lease - becomes available for assignment to the same or a different client. + becomes available for assignment to the same or different client. This process involves the following steps for each reclaimed lease: Invoke callouts for the lease4_expire or - lease6_expire hook points, if hook libraries + lease6_expire hook points if hook libraries supporting those callouts are currently loaded. @@ -69,9 +69,9 @@ indicate that the lease is now available for re-assignment. - Update statistics of the server, which includes + Update counters on the server, which includes increasing the number of reclaimed leases and decreasing the - number of assigned addresses or delegated prefixes etc. + number of assigned addresses or delegated prefixes. @@ -82,13 +82,13 @@
- Configuring Leases Reclamation + Configuring Lease Reclamation Kea can be configured to periodically detect and reclaim expired leases. During this process the lease entries in the database are - modified or removed. Therefore the server will not process incoming DHCP + modified or removed. While this is happening the server will not process incoming DHCP messages to avoid issues with concurrent access to database information. As a result, the server will be unresponsive while lease reclamation - is performed. DHCP queries will accumulate and responses will be + is performed and DHCP queries will accumulate; responses will be sent once the leases reclamation cycle is complete. In deployments where response time is critical, administrators may @@ -117,7 +117,7 @@ The first parameter is expressed in seconds and specifies an interval between the two consecutive lease reclamation cycles. This - is explained on the following diagram. + is explained by the following diagram. @@ -129,7 +129,7 @@ - This diagram shows 4 leases reclamation cycles of variable duration. + This diagram shows four lease reclamation cycles (c1 through c4) of variable duration. Note that the duration of the reclamation cycle depends on the number of expired leases detected and processed in the particular cycle. This duration is also usually significantly shorter than the interval between @@ -137,19 +137,19 @@ According to the reclaim-timer-wait-time the - server keeps fixed intervals of 5 seconds between the end of one cycle + server keeps fixed intervals of five seconds between the end of one cycle and the start of the next cycle. This guarantees the presence of 5s long periods during which the server remains responsive to DHCP - queries and does not perform leases reclamation. The + queries and does not perform lease reclamation. The max-reclaim-leases and - max-reclaim-time are set to 0, which implies that - there is no restriction on the maximum number of leases reclaimed - in the particular cycle, or the maximum duration of each cycle. + max-reclaim-time are set to 0, which sets + no restriction on the maximum number of leases reclaimed + in the particular cycle, or on the maximum duration of each cycle. In deployments with high lease pool utilization, relatively short valid lifetimes, and frequently disconnecting clients which - allow leases to expire; the number of expired leases requiring reclamation + allow leases to expire, the number of expired leases requiring reclamation at any given time may rise significantly. In this case it is often desirable to apply restrictions on the maximum duration of a reclamation cycle or the maximum number of leases reclaimed in a cycle. The following @@ -164,7 +164,6 @@ "max-reclaim-leases": 100, "max-reclaim-time": 50, "unwarned-reclaim-cycles": 10, - "flush-reclaimed-timer-wait-time": 0, }, ... @@ -212,11 +211,11 @@ is a risk that expired leases will accumulate faster than the server can reclaim them. This should not be the problem if the server is dealing with a temporary burst of expirations, because it should be able to - eventually deal with them over time. However, if leases expire at the high + eventually deal with them over time. However, if leases expire at a high rate for a longer period of time, the unreclaimed leases will pile up in the database. In order to notify the administrator that the current configuration does not satisfy the needs for reclamation of expired - leases, the server issues a warning message in the log, if it was unable + leases, the server issues a warning message in the log if it was unable to reclaim all leases within the last couple of reclamation cycles. The number of cycles after which such warning is issued is specified with the unwarned-reclaim-cycles configuration parameter. @@ -231,13 +230,13 @@ Suppose that a laptop goes to a sleep mode after a period of user inactivity. While the laptop is in sleep mode, its DHCP client will not renew leases obtained from the server and these leases will eventually - expire. When the laptop wakes up, it is often desired that it continue + expire. When the laptop wakes up, it is often desirable for it to continue using its previous assigned IP addresses. In order to facilitate this, the server needs to correlate returning clients with their expired leases When the client returns, the server will first check for those leases and - re-assign them if they have not assigned to another client. The ability + re-assign them if they have not been assigned to another client. The ability of the server to re-assign the same lease to a returning client is - referred to as 'lease affinity'. + referred to as "lease affinity". When lease affinity is enabled, the server will still @@ -250,10 +249,10 @@ any reclaimed lease may be assigned to another client if that client specifically asks for it. Therefore, the lease affinity does not guarantee that the reclaimed lease will be available for the client - who used it before. It merely increases the chances for the client to - be assigned the same lease. If the lease pool is small (mostly applies + who used it before; it merely increases the chances for the client to + be assigned the same lease. If the lease pool is small (this mostly applies to DHCPv4 for which address space is small), there is an increased - likelihood that the expired lease will be hijacked by another client. + likelihood that the expired lease will be assigned to another client. Consider the following configuration: @@ -290,7 +289,7 @@ the previous removal attempt was completed. Setting this value to 0 disables lease affinity, in which case leases will be removed from the lease database when they are reclaimed. If lease affinity is enabled, it - is recommended that hold-reclaim-time be set to a value significantly + is recommended that hold-reclaim-time be set to a value significantly higher than the reclaim-timer-wait-time, as timely removal of expired-reclaimed leases is less critical while the removal process may impact server responsiveness. diff --git a/doc/guide/lfc.xml b/doc/guide/lfc.xml index e177d7344a..f6580e83fa 100644 --- a/doc/guide/lfc.xml +++ b/doc/guide/lfc.xml @@ -22,7 +22,7 @@ of the lease entries and to indicate where it is in the process in case of an interruption. Currently the caller must supply names for all of the files, in the future this requirement may be relaxed with the process getting the names - from either the config file or from defaults. + from either the configuration file or from defaults.
diff --git a/doc/guide/libdhcp.xml b/doc/guide/libdhcp.xml index 841cec6a97..851c87469f 100644 --- a/doc/guide/libdhcp.xml +++ b/doc/guide/libdhcp.xml @@ -5,9 +5,9 @@ ]> - libdhcp++ library + The libdhcp++ Library - libdhcp++ is a common library written in C++ that handles + libdhcp++ is a library written in C++ that handles many DHCP-related tasks, including: @@ -40,7 +40,7 @@ OpenBSD), Mac OS X and Solaris 11 systems. DHCPv4 requires special raw socket processing to send and receive - packets from hosts that do not have IPv4 address assigned yet. Support + packets from hosts that do not have IPv4 address assigned. Support for this operation is implemented on Linux, FreeBSD, NetBSD and OpenBSD. It is likely that DHCPv4 component will not work in certain cases on other systems. diff --git a/doc/guide/logging.xml b/doc/guide/logging.xml index 3693142793..82344bc309 100644 --- a/doc/guide/logging.xml +++ b/doc/guide/logging.xml @@ -16,135 +16,143 @@ - module => daemon --> - - Logging + + 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 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. +
- Logging Configuration + 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 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. + - 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. - 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. + 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. + -
- Loggers + + The three main elements of a logger configuration are: + name (the component that is generating the messages), + the severity (what to log), and the + output_commands (where to log). There is also a + debuglevel element, which is only relevant if + debug-level logging has been selected. + +
+ name (string) - 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 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). - 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. - 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 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. - 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). + 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. -
- 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. - + + 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. + - - 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. - + + 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: - + + 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 - the root logger for the DHCPv4 + server. All components used by the DHCPv4 server inherit the + settings from this logger. + + - 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.alloc-engine - 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.bad-packets - 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. + + - kea-dhcp4.callouts - this logger is used - to log messages pertaining to the callouts registration and execution - for the particular hook point. + + kea-dhcp4.callouts - 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.commands - 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.ddns - 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.dhcp4 - used by the DHCPv4 server + daemon to log basic operations. + + - kea-dhcp4.dhcpsrv - this is a base - logger for the libdhcpsrv library. + + kea-dhcp4.dhcpsrv - the 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.eval - 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.hooks - 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.hosts - 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.leases - 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.options - 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-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 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. + - 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 - 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.alloc-engine - 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. + + - kea-dhcp6.bad-packets - this is the - logger used by the DHCPv6 server daemon for logging inbound client - packets that were dropped. + + kea-dhcp6.bad-packets - used 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.callouts - 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.commands - 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.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.dhcp6 - used DHCPv6 server daemon to + log basic operations. + + - kea-dhcp6.dhcpsrv - this is a base - logger for the libdhcpsrv library. + + kea-dhcp6.dhcpsrv - the 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.eval - 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.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.hosts - 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.leases - 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.options - 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-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 - 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.dhcpddns - 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.dhcp-to-d2 - 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. + + kea-dhcp-ddns.d2-to-dns - 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 + loggers but 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. + 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, something + that can be overridden by an entry in the configuration file. 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. - 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) + + 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 + 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): + 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 + + FATAL - associated with messages generated by a condition that is + so serious that the server cannot continue executing. + - ERROR + + ERROR- associated with messages generated by an error condition. + The server will continue executing, but the results may not be as + expected. + - WARN + + WARN - indicates an out of the ordinary condition. However, the + server will continue executing normally. + - INFO + + INFO - an informational message marking some event. + - DEBUG + + DEBUG - messages produced for debugging purposes. + - - 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. - - - + 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. The keactrl tool, described in , 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 kea_verbose 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 + kea_verbose value is set to "no" within the + keactrl configuration. +
-
- -
- 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). - - - - - +
+ debuglevel (integer) - - 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. - -
- Output Options - + output_options (list) - - The main settings for an output option are the - and a value called - , the meaning of which depends on - the destination that is set. - + Each logger can have zero or more . + These specify where log messages are sent. These are explained in + detail below.
- destination (string) - + output (string) - - 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: 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 to which messages should be written. - - - - - 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. + 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". -
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.) + 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. + If this is set to 0 or omitted, 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. - - - + 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. + +
maxver (integer) - - Maximum number of old log files to keep around when - rolling the output file. Only relevant when - is file. + 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. + In this example we want to set the global logging to write to the + console using standard output. - -"Logging": { +"Logging": { "loggers": [ { "name": "kea-dhcp4", @@ -653,17 +658,16 @@ TODO; there's a ticket to determine these levels, see #1074 "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. + + 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": { +"Logging": { "loggers": [ { "name": "kea-dhcp6", @@ -686,158 +690,171 @@ file be created.
Logging Message Format - - 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. - Consider the message below logged to a file: - 2014-04-11 12:58:01.005 INFO [kea-dhcp4.dhcpsrv/27456] + Consider the message below logged to a file: + +2014-04-11 12:58:01.005 INFO [kea-dhcp4.dhcpsrv/27456] DHCPSRV_MEMFILE_DB opening memory file lease database: type=memfile universe=4 - 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. The log message comprises a number of components: - - - 2014-04-11 12:58:01.005 + + + 2014-04-11 12:58:01.005 - - The date and time at which the message was generated. - + + + The date and time at which the message was generated. + + - INFO - - The severity of the message. - + INFO + + + The severity of the message. + + - [kea-dhcp4.dhcpsrv/27456] - - The source of the message. This comprises two elements: - the Kea process generating the message (in this - case, kea-dhcp4) 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). - + [kea-dhcp4.dhcpsrv/27456] + + + The source of the message. This comprises two elements: the Kea + process generating the message (in this case, + kea-dhcp4) and the component within the + program from which the message originated + (dhcpsrv, which is the name of the common + library used by DHCP server implementations). The number after + the slash is a process id (pid). + + - DHCPSRV_MEMFILE_DB - - The message identification. Every message in Kea - has a unique identification, which can be used as an - index into the Kea Messages - Manual () from which more information can be obtained. - + DHCPSRV_MEMFILE_DB + + + The message identification. Every message in Kea has a unique + identification, which can be used as an index into the + Kea Messages + Manual + () + from which more information can be obtained. + + - opening memory file lease database: type=memfile universe=4 - - 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. - + opening memory file lease database: type=memfile universe=4 + + + 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. + + - + -
Logging During Kea Startup - 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. - 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: - - + + KEA_LOCKFILE_DIR - + + Specifies a directory where the logging system should create its lock file. If not specified, it is prefix/var/run/kea, where - prefix 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. - - + prefix 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. + + + - + KEA_LOGGER_DESTINATION - + + Specifies logging output. There are several special values. - - stdout - - Log to standard output. - - - - stderr - - Log to standard error. - - - - syslog:fac - - Log via syslog. The optional - fac (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". - - + + stdout + + + Log to standard output. + + + + + + stderr + + + Log to standard error. + + + + + + syslog:fac + + + Log via syslog. The optional + fac (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". + + + - Any other value is treated as a name - of the output file. If not specified otherwise, Kea will log to - standard output. - - - - + Any other value is treated as a name of the output file. If not + specified otherwise, Kea will log to standard output. + + + +
- - +
+ diff --git a/doc/guide/stats.xml b/doc/guide/stats.xml index 335b25f672..17164c4df6 100644 --- a/doc/guide/stats.xml +++ b/doc/guide/stats.xml @@ -10,13 +10,13 @@
Statistics Overview - Both Kea DHCP servers support statistics gathering since - 0.9.2-beta version. A working DHCP server encounters various events + Both Kea DHCP servers support statistics gathering. + A working DHCP server encounters various events that can cause certain statistics to be collected. For example, a DHCPv4 server may receive a packet (pkt4-received - statistic increases by one) that after parsing was identifier as + statistic increases by one) that after parsing was identified as a DHCPDISCOVER (pkt4-discover-received). The Server processed it and - decided to send DHCPOFFER representing its answer (pkt4-offer-sent + decided to send a DHCPOFFER representing its answer (pkt4-offer-sent and pkt4-sent statistics increase by one). Such events happen frequently, so it is not uncommon for the statistics to have values in high thousands. They can serve as an easy and powerful @@ -73,7 +73,7 @@ statistics. When statistic-get-all is executed, an empty list is returned. Once the server performs an operation that causes a statistic to change, the related statistic will be created. In the general - case once a statistic is recorded even once, it is kept in the manager, until + case, once a statistic is recorded even once, it is kept in the manager, until explicitly removed, by statistic-remove or statistic-remove-all being called or the server is shut down. Per subnet statistics are explicitly removed when reconfiguration @@ -114,6 +114,12 @@ it. + + The following sections describe commands that can be sent to the server: the + examples are not fragments of a configuration file. For more information on + sending commands to Kea, see . + +
statistic-get command