mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-30 05:27:55 +00:00
Code Issues Releases Wiki Activity

[master] Merge branch 'trac5008'

Browse Source
This commit is contained in:
Stephen Morris 2016-09-21 19:13:22 +01:00
commit f09cd12d5b
10 changed files with 847 additions and 817 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
doc/guide/classify.xml
View File

@ -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 @@
</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
@ -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.
</para>
@ -146,7 +147,7 @@
<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>
@ -360,7 +361,7 @@
<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>
@ -401,7 +402,7 @@
<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>
@ -409,7 +410,7 @@
<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>
@ -423,20 +424,26 @@
</tbody>
</tgroup>
</table>
Hex Strings are converted into a string as expected. The starting &quot;0X&quot; or
Notes:
</para>
<itemizedlist>
<listitem><para>
Hexadecimal strings are converted into a string as expected. The starting &quot;0X&quot; or
&quot;0x&quot; is removed and if the string is an odd number of characters a
&quot;0&quot; 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
@ -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.
</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 in DHCPv4 (code 125, see
<ulink url="http://tools.ietf.org/html/rfc3925#section-4">Section 4 of RFC 3925</ulink>) and
Vendor-specific Information Option in DHCPv6 (code 17, defined in
<ulink url="https://tools.ietf.org/html/rfc3315#section-22.17">Section 22.17 of
RFC 3315</ulink>). Vendor class option means Vendor-Identifying Vendor
Class Option in DHCPv4 (code 124, see
<ulink url="http://tools.ietf.org/html/rfc3925#section-3">Section 3 of RFC 3925</ulink>) in DHCPv4 and
Class Option in DHCPv6 (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">
@ -557,7 +577,7 @@ concatenation of the strings</entry></row>
<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").
@ -626,7 +646,7 @@ concatenation of the strings</entry></row>
<para>
In the following example the class named &quot;Client_foo&quot; 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 &quot;foo&quot;. 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</entry></row>
<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>
@ -784,9 +804,9 @@ concatenation of the strings</entry></row>
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>
@ -817,7 +837,7 @@ concatenation of the strings</entry></row>
<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:
@ -836,17 +856,17 @@ concatenation of the strings</entry></row>
</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.
@ -863,8 +883,7 @@ concatenation of the strings</entry></row>
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>
@ -872,7 +891,7 @@ concatenation of the strings</entry></row>
<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

55
doc/guide/ctrl-channel.xml
View File

@ -10,21 +10,21 @@
<title>Management API</title>
<para>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.</para>
downtime period until the issue is resolved.</para>
<para>To avoid such problems, both DHCPv4 and DHCPv6 servers
introduced support for a mechanism that will allow
on-line reconfiguration, without requiring server shutdown.
<para>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.</para>
<para>Currently the only supported type of control channel
@ -35,10 +35,10 @@
</para>
<section id="ctrl-channel-syntax">
<title>Data syntax</title>
<para>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
<title>Data Syntax</title>
<para>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:
<screen>
@ -55,7 +55,7 @@
<command>command</command> is the name of command to execute and
is mandatory. <command>arguments</command> is a map of parameters
required to carry out the given command. The exact content and
format is command specific.</para>
format of the map is command specific.</para>
<para>The server will process the incoming command and then send a
response of the form:
@ -73,23 +73,23 @@
<command>result</command> 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. <command>text</command> field typically appears when result is
future. The <command>text</command> 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).
<command>arguments</command> 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.</para>
</section>
<section id="ctrl-channel-client">
<title>Using control channel</title>
<title>Using the Control Channel</title>
<para>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
<para>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.</para>
be written in languages different than C or C++. Therefore only examples are provided to show
how one can take advantage of the API.</para>
<para>The easiest way is to use a tool called <command>socat</command>,
a tool available from <ulink url="http://www.dest-unreach.org/socat/">socat
@ -101,7 +101,8 @@ $ socat UNIX:/path/to/the/kea/socket -
</screen>
where <command>/path/to/the/kea/socket</command> is the path specified in the
<command>Dhcp4/control-socket/socket-name</command> parameter in the Kea
configuration file.</para>
configuration file. Text passed to <command>socat</command>
will be sent to Kea and the responses received from Kea printed to standard output.</para>
<para>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.</para>
</section>
<section id="commands-common">
<title>Commands supported by both DHCPv4 and DHCPv6 servers</title>
<title>Commands Supported by Both the DHCPv4 and DHCPv6 Servers</title>
<section id="command-leases-reclaim">
<title>leases-reclaim command</title>
<title>leases-reclaim</title>
<para>
<emphasis>leases-reclaim</emphasis> command instructs the server to
reclaim all expired leases immediately. The command has the following
@ -140,10 +141,10 @@ configuration file.</para>
</section>
<section id="command-list-commands">
<title>list-commands command</title>
<title>list-commands</title>
<para>
<emphasis>list-commands</emphasis> command retrieves a list of all
The <emphasis>list-commands</emphasis> command retrieves a list of all
commands supported by the server. It does not take any arguments.
An example command may look like this:
<screen>
@ -161,10 +162,10 @@ configuration file.</para>
</section> <!-- end of command-list-commands -->
<section id="command-shutdown">
<title>shutdown command</title>
<title>shutdown</title>
<para>
<emphasis>shutdown</emphasis> command instructs the server to initiate
The <emphasis>shutdown</emphasis> 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:

40
doc/guide/ddns.xml
View File

@ -8,7 +8,8 @@
<title>The DHCP-DDNS Server</title>
<para>
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 <ulink url="http://tools.ietf.org/html/rfc2136">RFC 2136</ulink>)
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 @@
</listitem>
<listitem>
<simpara>
<command>-V</command> - prints out Kea extended version with
additional parameters and exits.
<command>-W</command> - prints out the Kea configuration report
and exits. The report is a copy of the
<filename>config.report</filename> file produced by
<userinput>./configure</userinput>: it is embedded in the
executable binary.
</simpara>
</listitem>
<listitem>
@ -99,19 +103,6 @@
</listitem>
</itemizedlist>
<para>
The <command>-V</command> command returns the versions of the
external libraries dynamically linked.
</para>
<para>
The <command>-W</command> command describes the environment used
to build Kea. This command displays a copy of the
<filename>config.report</filename> file produced by
<userinput>./configure</userinput> that is embedded in the
executable binary.
</para>
<para>
The <filename>config.report</filename> may also be accessed more
directly. The following command may be used to extract this
@ -188,26 +179,22 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
<itemizedlist>
<listitem>
<simpara>
<command>Global Server Parameters</command> -
values which control connectivity and global server behavior
<emphasis>Global Server Parameters</emphasis> - values which control connectivity and global server behavior
</simpara>
</listitem>
<listitem>
<simpara>
<command>TSIG Key Info</command> -
defines the TSIG keys used for secure traffic with DNS servers
<emphasis>TSIG Key Info</emphasis> - defines the TSIG keys used for secure traffic with DNS servers
</simpara>
</listitem>
<listitem>
<simpara>
<command>Forward DDNS</command> -
defines the catalog of Forward DDNS Domains
<emphasis>Forward DDNS</emphasis> - defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
<listitem>
<simpara>
<command>Reverse DDNS</command> -
defines the catalog of Forward DDNS Domains
<emphasis>Reverse DDNS</emphasis> - defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
</itemizedlist>
@ -234,8 +221,7 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
<listitem><simpara>
<command>ncr-protocol</command> - 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.
</simpara></listitem>
<listitem><simpara>
@ -347,7 +333,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
<simpara>
<command>digest-bits</command> -
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

5
doc/guide/faq.xml
View File

@ -18,7 +18,7 @@
it in the known issues list. -->
<section id="faq-generic">
<title>Generic Frequently Asked Questions</title>
<title>General Frequently Asked Questions</title>
<section id="q1-generic">
<title>Where did the Kea name came from?</title>
@ -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 <ulink url="http://git.kea.isc.org/~tester/kea/doxygen/">Kea Developer's Guide</ulink>.
the Contributor's Guide in the
<ulink url="http://git.kea.isc.org/~tester/kea/doxygen/">Kea Developer's Guide</ulink>.
</para>
<para>Kea is developed by ISC, which is a non-profit organization.

4
doc/guide/hooks.xml
View File

@ -102,8 +102,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.
</para>
<para>

77
doc/guide/lease-expiration.xml
View File

@ -8,8 +8,8 @@
<para>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.
</para>
<para>
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.
</para>
<para>Although, all configuration examples in this section are provided
@ -50,14 +50,14 @@
<section id="lease-reclamation">
<title>Lease Reclamation</title>
<para>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:
</para>
<itemizedlist>
<listitem>
<simpara>Invoke callouts for the <command>lease4_expire</command> or
<command>lease6_expire</command> hook points, if hook libraries
<command>lease6_expire</command> hook points if hook libraries
supporting those callouts are currently loaded.</simpara>
</listitem>
<listitem>
@ -69,9 +69,9 @@
indicate that the lease is now available for re-assignment.</simpara>
</listitem>
<listitem>
<simpara>Update statistics of the server, which includes
<simpara>Update counters on the server, which includes
increasing the number of reclaimed leases and decreasing the
number of assigned addresses or delegated prefixes etc.</simpara>
number of assigned addresses or delegated prefixes.</simpara>
</listitem>
</itemizedlist>
@ -82,13 +82,13 @@
</section>
<section id="lease-reclaim-config">
<title>Configuring Leases Reclamation</title>
<title>Configuring Lease Reclamation</title>
<para>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.</para>
<para>In deployments where response time is critical, administrators may
@ -117,7 +117,7 @@
<para>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.
<screen>
@ -129,7 +129,7 @@
</screen>
</para>
<para>This diagram shows 4 leases reclamation cycles of variable duration.
<para>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 @@
</para>
<para>According to the <command>reclaim-timer-wait-time</command> 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
<command>max-reclaim-leases</command> and
<command>max-reclaim-time</command> 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.
<command>max-reclaim-time</command> 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.
</para>
<para>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
<command>unwarned-reclaim-cycles</command> configuration parameter.
@ -231,13 +230,13 @@
<para>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".
</para>
<para>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.
</para>
<para>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 <command>hold-reclaim-time</command> be set to a value significantly
higher than the <command>reclaim-timer-wait-time</command>, as timely
removal of expired-reclaimed leases is less critical while the removal
process may impact server responsiveness.</para>

2
doc/guide/lfc.xml
View File

@ -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.
</para>
</section>

6
doc/guide/libdhcp.xml
View File

@ -5,9 +5,9 @@
]>
<chapter id="libdhcp">
<title>libdhcp++ library</title>
<title>The libdhcp++ Library</title>
<para>
libdhcp++ is a common library written in C++ that handles
libdhcp++ is a library written in C++ that handles
many DHCP-related tasks, including:
<itemizedlist>
<listitem>
@ -40,7 +40,7 @@
OpenBSD), Mac OS X and Solaris 11 systems.</para>
<para>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.</para>

1266
doc/guide/logging.xml
View File

File diff suppressed because it is too large Load Diff

16
doc/guide/stats.xml
View File

@ -10,13 +10,13 @@
<section>
<title>Statistics Overview</title>
<para>Both Kea DHCP servers support statistics gathering since
0.9.2-beta version. A working DHCP server encounters various events
<para>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 <command>statistic-get-all</command> 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 <command>statistic-remove</command> or
<command>statistic-remove-all</command> being called or the server is shut
down. Per subnet statistics are explicitly removed when reconfiguration
@ -114,6 +114,12 @@
it.
</para>
<note><para>
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 <xref linkend="ctrl-channel"/>.
</para></note>
<section id="command-statistic-get">
<title>statistic-get command</title>