mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-31 05:55:28 +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
parent 63456fab1b e38d72cfb1
commit f09cd12d5b
10 changed files with 847 additions and 817 deletions
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 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 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 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, 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 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 have a class associated with it or that has a class which matches one of
@@ -68,7 +68,8 @@
</para> </para>
<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 (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). "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 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 Expressions are pre-processed during the parsing of the configuration file
and converted to an internal representation. This allows certain types of and converted to an internal representation. This allows certain types of
errors to be caught and logged during parsing. Examples of these errors 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 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. system.
</para> </para>
@@ -146,7 +147,7 @@
<para> <para>
Expressions are a work in progress and the supported operators and Expressions are a work in progress and the supported operators and
values are limited. The expectation is that additional operators and values 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. remain the same.
</para> </para>
@@ -360,7 +361,7 @@
<entry>4491</entry> <entry>4491</entry>
<entry>If the vendor option is present, it returns the <entry>If the vendor option is present, it returns the
value of the enterprise-id field padded to 4 value of the enterprise-id field padded to 4
bytes. Returns '' otherwise.</entry> bytes. Returns "" otherwise.</entry>
</row> </row>
<row> <row>
<entry>Vendor sub-option existence</entry> <entry>Vendor sub-option existence</entry>
@@ -401,7 +402,7 @@
<entry>4491</entry> <entry>4491</entry>
<entry>If the vendor option is present, it returns the <entry>If the vendor option is present, it returns the
value of the enterprise-id field padded to 4 value of the enterprise-id field padded to 4
bytes. Returns '' otherwise.</entry> bytes. Returns "" otherwise.</entry>
</row> </row>
<row> <row>
<entry>First data chunk from vendor class option</entry> <entry>First data chunk from vendor class option</entry>
@@ -409,7 +410,7 @@
<entry>docsis3.0</entry> <entry>docsis3.0</entry>
<entry>Returns content of the first data chunk from <entry>Returns content of the first data chunk from
the vendor class option with specified enterprise-id. the vendor class option with specified enterprise-id.
Returns '' if missing.</entry> Returns "" if missing.</entry>
</row> </row>
<row> <row>
<entry>Specific data chunk from vendor class option</entry> <entry>Specific data chunk from vendor class option</entry>
@@ -423,20 +424,26 @@
</tbody> </tbody>
</tgroup> </tgroup>
</table> </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;0x&quot; is removed and if the string is an odd number of characters a
&quot;0&quot; is prepended to it. &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, 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. 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 Integers in an expression are converted to 32 bit unsigned integers and
are represented as four byte strings. For example 123 is represented as are represented as four-byte strings. For example 123 is represented as
0x0000007b. All expressions that return numeric values use 32 bit 0x0000007b. All expressions that return numeric values use 32-bit
unsigned integers, even if the field in the packet is smaller. In general 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 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 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 bits, e.g. use 0x00000001 instead of 0x1 or 0x01. Also, make
sure the value is specified in network order, e.g. 1 is sure the value is specified in network order, e.g. 1 is
represented as 0x00000001. represented as 0x00000001.
</para> </para></listitem>
<para> <listitem><para>
"option[code].hex" extracts the value of the option with the code "code" "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 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 returns the empty string. The string is presented as a byte string of
the option payload without the type code or length fields. 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 "option[code].exists" checks if an option with the code "code" is present
in the incoming packet. It can be used with empty options. in the incoming packet. It can be used with empty options.
</para> </para></listitem>
<para> <listitem><para>
"relay4[code].hex" attempts to extract the value of the sub-option "relay4[code].hex" attempts to extract the value of the sub-option
"code" from the option inserted as the DHCPv4 Relay Agent Information "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 (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 option doesn't contain the requested sub-option, the expression returns
an empty string. The string is presented as a byte string of the an empty string. The string is presented as a byte string of the
option payload without the type code or length fields. This option payload without the type code or length fields. This
expression is allowed in DHCPv4 only. expression is allowed in DHCPv4 only.
</para> </para></listitem>
<para> <listitem><para>
"relay4" shares the same representation types as "option", for "relay4" shares the same representation types as "option", for
instance "relay4[code].exists" is supported. instance "relay4[code].exists" is supported.
</para> </para></listitem>
<para> <listitem><para>
"relay6[nest]" allows access to the encapsulations used by any DHCPv6 "relay6[nest]" allows access to the encapsulations used by any DHCPv6
relays that forwarded the packet. The "nest" level specifies the relay relays that forwarded the packet. The "nest" level specifies the relay
from which to extract the information, with a value of 0 indicating from which to extract the information, with a value of 0 indicating
the relay closest to the DHCPv6 server. If the requested encapsulation the relay closest to the DHCPv6 server. If the requested encapsulation
doesn't exist an empty string "" is returned. This expression is doesn't exist an empty string "" is returned. This expression is
allowed in DHCPv6 only. allowed in DHCPv6 only.
</para> </para></listitem>
<para> <listitem><para>
"relay6[nest].option[code]" shares the same representation types as "relay6[nest].option[code]" shares the same representation types as
"option", for instance "relay6[nest].option[code].exists" is supported. "option", for instance "relay6[nest].option[code].exists" is supported.
</para> </para></listitem>
<para> <listitem><para>
Expressions starting with "pkt4" can be used only in DHCPv4. Expressions starting with "pkt4" can be used only in DHCPv4.
They allows access to DHCPv4 message fields. They allows access to DHCPv4 message fields.
</para> </para></listitem>
<para> <listitem><para>
"pkt6" refers to information from the client request. To access any "pkt6" refers to information from the client request. To access any
information from an intermediate relay use "relay6". "pkt6.msgtype" information from an intermediate relay use "relay6". "pkt6.msgtype"
and "pkt6.transid" output a 4 byte binary string for the message type and "pkt6.transid" output a 4 byte binary string for the message type
or transaction id. For example the message type SOLICIT will be or transaction id. For example the message type SOLICIT will be
"0x00000001" or simply 1 as in "pkt6.msgtype == 1". "0x00000001" or simply 1 as in "pkt6.msgtype == 1".
</para> </para></listitem>
<para> <listitem><para>
Vendor option means Vendor-Identifying Vendor-specific Information Vendor option means Vendor-Identifying Vendor-specific Information
option (code 125, see Section 4 of RFC3925) in DHCPv4 and option in DHCPv4 (code 125, see
Vendor-specific Information Option (code 17, defined in Section 22.17 of <ulink url="http://tools.ietf.org/html/rfc3925#section-4">Section 4 of RFC 3925</ulink>) and
RFC3315) in DHCPv6. Vendor class option means Vendor-Identifying Vendor Vendor-specific Information Option in DHCPv6 (code 17, defined in
Class Option (code 124, see Section 3 of RFC3925) in DHCPv4 and Vendor <ulink url="https://tools.ietf.org/html/rfc3315#section-22.17">Section 22.17 of
Class Option (code 16, see Section 22.16 of RFC3315). Vendor options may RFC 3315</ulink>). Vendor class option means Vendor-Identifying Vendor
have sub-options that are referenced by their codes. Vendor class Class Option in DHCPv4 (code 124, see
options do not have sub-options, but rather data chunks, which are <ulink url="http://tools.ietf.org/html/rfc3925#section-3">Section 3 of RFC 3925</ulink>) in DHCPv4 and
referenced by index value. Index 0 means the first data chunk, Index 1 Class Option in DHCPv6 (code 16, see
is for the second data chunk (if present), etc. <ulink url="https://tools.ietf.org/html/rfc3315#section-22.16">Section 22.16 of RFC 3315</ulink>).
</para> 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 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 <listitem><para>Vendor Class Identifier (option 60 in DHCPv4) can be
accessed using option[60] expression.</para> 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 to appear in a single message. The client classification code currently
examines the first instance if more than one appear. For vendor.enterprise examines the first instance if more than one appear. For vendor.enterprise
and vendor-class.enterprise expressions, the value from the first instance and vendor-class.enterprise expressions, the value from the first instance
is returned. Please submit a feature request on Kea website if you need 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> <para>
<table frame="all" id="classification-expressions-list"> <table frame="all" id="classification-expressions-list">
@@ -557,7 +577,7 @@ concatenation of the strings</entry></row>
<section> <section>
<title>Logical operators</title> <title>Logical operators</title>
The Not, And and Or logical operators are the common operators. Not 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 associative, parentheses around a logical expression can be used
to enforce a specific grouping, for instance in "A and (B or C)" 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"). (without parentheses "A and B or C" means "(A and B) or C").
@@ -626,7 +646,7 @@ concatenation of the strings</entry></row>
<para> <para>
In the following example the class named &quot;Client_foo&quot; is defined. 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 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. 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> <title>Configuring Subnets With Class Information</title>
<para> <para>
In certain cases it beneficial to restrict access to certain subnets 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. keyword when defining the subnet.
</para> </para>
@@ -784,9 +804,9 @@ concatenation of the strings</entry></row>
expression would either be complex or time consuming and be easier or 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 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 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 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"/>. and <xref linkend="classification-subnets"/>.
</para> </para>
</section> </section>
@@ -817,7 +837,7 @@ concatenation of the strings</entry></row>
<para> <para>
The list of tokens is created when the configuration file is processed with 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 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 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 from the top of the stack and eventually push its result on the top of the
stack. Imagine the following expression: stack. Imagine the following expression:
@@ -836,17 +856,17 @@ concatenation of the strings</entry></row>
</para> </para>
<para> <para>
When debug logging is enabled each time a token is evaluated it will 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 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 off of the value stack and any objects that were pushed onto the value
stack. stack.
</para> </para>
<para> <para>
The values will be displayed as either text if the command is known 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 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 the order they were popped. For most expressions this won't matter
but for the concat expression the values are displayed in reverse but for the concat expression the values are displayed in reverse
order from how they are written in the expression. 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.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.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.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, 2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0, string 0x666F6F626172 pushing result 0x666F6F
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.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' 2016-05-19 13:35:04.168 DEBUG [kea.eval/44478] EVAL_DEBUG_EQUAL Popping 0x666F6F and 0x666F6F pushing result 'true'
</screen> </screen>
@@ -872,7 +891,7 @@ concatenation of the strings</entry></row>
<note><para> <note><para>
The debug logging may be quite verbose if you have a number of expressions 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 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 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 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> <title>Management API</title>
<para>A classic approach to daemon configuration assumes that <para>A classic approach to daemon configuration assumes that
the server's configuration is stored in the configuration files the server's configuration is stored in configuration files
and when the configuration is changed, the daemon is restarted. and, when the configuration is changed, the daemon is restarted.
This approach has the significant disadvantage of introducing periods This approach has the significant disadvantage of introducing periods
of downtime, when client traffic is not handled. Another risk of downtime, when client traffic is not handled. Another risk
is that if the new configuration is invalid for whatever reason, is that if the new configuration is invalid for whatever reason,
the server may refuse to start, which will further extend the 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 <para>To avoid such problems, both the DHCPv4 and DHCPv6 servers
introduced support for a mechanism that will allow include support for a mechanism that allows
on-line reconfiguration, without requiring server shutdown. on-line reconfiguration without requiring server shutdown.
Both servers can be instructed to open control sockets, which Both servers can be instructed to open control sockets, which
is a communication channel. The server is able to receive is a communication channel. The server is able to receive
commands on that channel, act on them and report back status. 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> the number is expected to grow over time.</para>
<para>Currently the only supported type of control channel <para>Currently the only supported type of control channel
@@ -35,10 +35,10 @@
</para> </para>
<section id="ctrl-channel-syntax"> <section id="ctrl-channel-syntax">
<title>Data syntax</title> <title>Data Syntax</title>
<para>Communication over control channel is conducted using JSON <para>Communication over the control channel is conducted using JSON
structures. If configured, Kea will open a socket and will listen structures. If configured, Kea will open a socket and listen
for any incoming connections. A process connecting to this socket for incoming connections. A process connecting to this socket
is expected to send JSON commands structured as follows: is expected to send JSON commands structured as follows:
<screen> <screen>
@@ -55,7 +55,7 @@
<command>command</command> is the name of command to execute and <command>command</command> is the name of command to execute and
is mandatory. <command>arguments</command> is a map of parameters is mandatory. <command>arguments</command> is a map of parameters
required to carry out the given command. The exact content and 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 <para>The server will process the incoming command and then send a
response of the form: response of the form:
@@ -73,23 +73,23 @@
<command>result</command> indicates the outcome of the command. A value of 0 <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 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 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 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 <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> if it contains no data values.</para>
</section> </section>
<section id="ctrl-channel-client"> <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 <para>Kea does not currently provide a client for using the control channel. The primary
reason for that is the expectation is that the entity using control channel 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 is typically an IPAM or similar network management/monitoring software which
may have quite varied expectations regarding the client and is even likely to 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 be written in languages different than C or C++. Therefore only examples are provided to show
examples how one can take advantage of the API.</para> how one can take advantage of the API.</para>
<para>The easiest way is to use a tool called <command>socat</command>, <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 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> </screen>
where <command>/path/to/the/kea/socket</command> is the path specified in the 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 <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 <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 such a simplistic client written in C is available in the Kea Developer's
@@ -110,10 +111,10 @@ configuration file.</para>
</section> </section>
<section id="commands-common"> <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"> <section id="command-leases-reclaim">
<title>leases-reclaim command</title> <title>leases-reclaim</title>
<para> <para>
<emphasis>leases-reclaim</emphasis> command instructs the server to <emphasis>leases-reclaim</emphasis> command instructs the server to
reclaim all expired leases immediately. The command has the following reclaim all expired leases immediately. The command has the following
@@ -140,10 +141,10 @@ configuration file.</para>
</section> </section>
<section id="command-list-commands"> <section id="command-list-commands">
<title>list-commands command</title> <title>list-commands</title>
<para> <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. commands supported by the server. It does not take any arguments.
An example command may look like this: An example command may look like this:
<screen> <screen>
@@ -161,10 +162,10 @@ configuration file.</para>
</section> <!-- end of command-list-commands --> </section> <!-- end of command-list-commands -->
<section id="command-shutdown"> <section id="command-shutdown">
<title>shutdown command</title> <title>shutdown</title>
<para> <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 its shutdown procedure. It is the equivalent of sending a SIGTERM signal
to the process. This command does not take any arguments. An example to the process. This command does not take any arguments. An example
command may look like this: command may look like this:

40
doc/guide/ddns.xml
View File

@@ -8,7 +8,8 @@
<title>The DHCP-DDNS Server</title> <title>The DHCP-DDNS Server</title>
<para> <para>
The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts the client side of 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 servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP servers construct
DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP
lease change events and then post these to D2. D2 attempts to match lease change events and then post these to D2. D2 attempts to match
@@ -87,8 +88,11 @@
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<command>-V</command> - prints out Kea extended version with <command>-W</command> - prints out the Kea configuration report
additional parameters and exits. 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> </simpara>
</listitem> </listitem>
<listitem> <listitem>
@@ -99,19 +103,6 @@
</listitem> </listitem>
</itemizedlist> </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> <para>
The <filename>config.report</filename> may also be accessed more The <filename>config.report</filename> may also be accessed more
directly. The following command may be used to extract this 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> <itemizedlist>
<listitem> <listitem>
<simpara> <simpara>
<command>Global Server Parameters</command> - <emphasis>Global Server Parameters</emphasis> - values which control connectivity and global server behavior
values which control connectivity and global server behavior
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<command>TSIG Key Info</command> - <emphasis>TSIG Key Info</emphasis> - defines the TSIG keys used for secure traffic with DNS servers
defines the TSIG keys used for secure traffic with DNS servers
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<command>Forward DDNS</command> - <emphasis>Forward DDNS</emphasis> - defines the catalog of Forward DDNS Domains
defines the catalog of Forward DDNS Domains
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<command>Reverse DDNS</command> - <emphasis>Reverse DDNS</emphasis> - defines the catalog of Forward DDNS Domains
defines the catalog of Forward DDNS Domains
</simpara> </simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@@ -234,8 +221,7 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
<listitem><simpara> <listitem><simpara>
<command>ncr-protocol</command> - Socket protocol to use when sending requests to D2. <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 Currently only UDP is supported. TCP may be available in a future release.
release.
</simpara></listitem> </simpara></listitem>
<listitem><simpara> <listitem><simpara>
@@ -347,7 +333,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
<simpara> <simpara>
<command>digest-bits</command> - <command>digest-bits</command> -
is used to specify the minimum truncated length in 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 values must be an integral number of octets, be greater
than 80 and the half of the full length. Note in BIND9 than 80 and the half of the full length. Note in BIND9
this parameter is appended after a dash to the algorithm 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. --> it in the known issues list. -->
<section id="faq-generic"> <section id="faq-generic">
<title>Generic Frequently Asked Questions</title> <title>General Frequently Asked Questions</title>
<section id="q1-generic"> <section id="q1-generic">
<title>Where did the Kea name came from?</title> <title>Where did the Kea name came from?</title>
@@ -61,7 +61,8 @@
Accepted contributions range from minor documentation corrections to Accepted contributions range from minor documentation corrections to
significant new features, like support for a new database type. Before significant new features, like support for a new database type. Before
considering writing and submitting a patch, make sure you read 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>
<para>Kea is developed by ISC, which is a non-profit organization. <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 parameter), floor (integer parameter), debug (boolean parameter) and
even lists (list of strings) and maps (containing strings). Nested even lists (list of strings) and maps (containing strings). Nested
parameters could be used if the library supports it. This topic is parameters could be used if the library supports it. This topic is
explained in detail in the Hooks Developer's Guide in Configuring Hooks explained in detail in the Hooks Developer's Guide in the "Configuring
Libraries section. Hooks Libraries" section.
</para> </para>
<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 <para>The primary role of the DHCP server is to assign addresses and/or
delegate prefixes to DHCP clients. These addresses and prefixes are delegate prefixes to DHCP clients. These addresses and prefixes are
often referred to as 'leases'. Leases are typically assigned to clients often referred to as "leases". Leases are typically assigned to clients
for a finite amount of time, known as 'valid lifetime'. DHCP clients who 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 wish to continue using their assigned leases, will periodically renew them
by sending the appropriate message to the DHCP server. The DHCP server records 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 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 available for reassignment is referred to as "lease reclamation" and expired
leases returned to availability through this process are referred to as leases returned to availability through this process are referred to as
"reclaimed". "reclaimed".
The DHCP server attempts to reclaim an expired lease as soon as it detects
The DHCP server should reclaim an expired lease as soon as it detects that it has expired. One way in which the server detects expiration occurs
that it has expired. One way in which the server may detect expiration when it is trying to allocate a lease to a client and finds this
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
lease already present in the database but expired. Another way the is by periodically querying the lease
server detects expired leases is by periodically querying the lease
database for them. Regardless of how an expired lease is detected, before 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 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 for the expired leases and how to minimize the impact of the periodic lease
reclamation process on the server's responsiveness. Finally, 'lease affinity', reclamation process on the server's responsiveness. Finally, it explains
which provides the means to assign the same lease to the returning client "lease affinity", which provides the means to assign the same lease to a
after its lease has expired, is explained. returning client after its lease has expired.
</para> </para>
<para>Although, all configuration examples in this section are provided <para>Although, all configuration examples in this section are provided
@@ -50,14 +50,14 @@
<section id="lease-reclamation"> <section id="lease-reclamation">
<title>Lease Reclamation</title> <title>Lease Reclamation</title>
<para>Lease reclamation is the process through which an expired lease <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: This process involves the following steps for each reclaimed lease:
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<simpara>Invoke callouts for the <command>lease4_expire</command> or <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> supporting those callouts are currently loaded.</simpara>
</listitem> </listitem>
<listitem> <listitem>
@@ -69,9 +69,9 @@
indicate that the lease is now available for re-assignment.</simpara> indicate that the lease is now available for re-assignment.</simpara>
</listitem> </listitem>
<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 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> </listitem>
</itemizedlist> </itemizedlist>
@@ -82,13 +82,13 @@
</section> </section>
<section id="lease-reclaim-config"> <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 <para>Kea can be configured to periodically detect and reclaim expired
leases. During this process the lease entries in the database are 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. messages to avoid issues with concurrent access to database information.
As a result, the server will be unresponsive while lease reclamation 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> sent once the leases reclamation cycle is complete.</para>
<para>In deployments where response time is critical, administrators may <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 <para>The first parameter is expressed in seconds and specifies an
interval between the two consecutive lease reclamation cycles. This interval between the two consecutive lease reclamation cycles. This
is explained on the following diagram. is explained by the following diagram.
<screen> <screen>
@@ -129,7 +129,7 @@
</screen> </screen>
</para> </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 Note that the duration of the reclamation cycle depends on the number
of expired leases detected and processed in the particular cycle. This of expired leases detected and processed in the particular cycle. This
duration is also usually significantly shorter than the interval between duration is also usually significantly shorter than the interval between
@@ -137,19 +137,19 @@
</para> </para>
<para>According to the <command>reclaim-timer-wait-time</command> the <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 and the start of the next cycle. This guarantees the presence of
5s long periods during which the server remains responsive to DHCP 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-leases</command> and
<command>max-reclaim-time</command> are set to 0, which implies that <command>max-reclaim-time</command> are set to 0, which sets
there is no restriction on the maximum number of leases reclaimed no restriction on the maximum number of leases reclaimed
in the particular cycle, or the maximum duration of each cycle. in the particular cycle, or on the maximum duration of each cycle.
</para> </para>
<para>In deployments with high lease pool utilization, relatively <para>In deployments with high lease pool utilization, relatively
short valid lifetimes, and frequently disconnecting clients which 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 at any given time may rise significantly. In this case it is often
desirable to apply restrictions on the maximum duration of a reclamation desirable to apply restrictions on the maximum duration of a reclamation
cycle or the maximum number of leases reclaimed in a cycle. The following cycle or the maximum number of leases reclaimed in a cycle. The following
@@ -164,7 +164,6 @@
"max-reclaim-leases": 100, "max-reclaim-leases": 100,
"max-reclaim-time": 50, "max-reclaim-time": 50,
"unwarned-reclaim-cycles": 10, "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 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 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 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 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 the database. In order to notify the administrator that the current
configuration does not satisfy the needs for reclamation of expired 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 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 number of cycles after which such warning is issued is specified with the
<command>unwarned-reclaim-cycles</command> configuration parameter. <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 <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 inactivity. While the laptop is in sleep mode, its DHCP client will not
renew leases obtained from the server and these leases will eventually 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, using its previous assigned IP addresses. In order to facilitate this,
the server needs to correlate returning clients with their expired leases the server needs to correlate returning clients with their expired leases
When the client returns, the server will first check for those leases and 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 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>
<para>When lease affinity is enabled, the server will still <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 any reclaimed lease may be assigned to another client if that client
specifically asks for it. Therefore, the lease affinity does not specifically asks for it. Therefore, the lease affinity does not
guarantee that the reclaimed lease will be available for the client guarantee that the reclaimed lease will be available for the client
who used it before. It merely increases the chances for the client to 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 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 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>
<para>Consider the following configuration: <para>Consider the following configuration:
@@ -290,7 +289,7 @@
the previous removal attempt was completed. Setting this value to 0 the previous removal attempt was completed. Setting this value to 0
disables lease affinity, in which case leases will be removed from the disables lease affinity, in which case leases will be removed from the
lease database when they are reclaimed. If lease affinity is enabled, it 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 higher than the <command>reclaim-timer-wait-time</command>, as timely
removal of expired-reclaimed leases is less critical while the removal removal of expired-reclaimed leases is less critical while the removal
process may impact server responsiveness.</para> 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 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 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 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> </para>
</section> </section>

6
doc/guide/libdhcp.xml
View File

@@ -5,9 +5,9 @@
]> ]>
<chapter id="libdhcp"> <chapter id="libdhcp">
<title>libdhcp++ library</title> <title>The libdhcp++ Library</title>
<para> <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: many DHCP-related tasks, including:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@@ -40,7 +40,7 @@
OpenBSD), Mac OS X and Solaris 11 systems.</para> OpenBSD), Mac OS X and Solaris 11 systems.</para>
<para>DHCPv4 requires special raw socket processing to send and receive <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. for this operation is implemented on Linux, FreeBSD, NetBSD and OpenBSD.
It is likely that DHCPv4 component will not work in certain cases on It is likely that DHCPv4 component will not work in certain cases on
other systems.</para> 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> <section>
<title>Statistics Overview</title> <title>Statistics Overview</title>
<para>Both Kea DHCP servers support statistics gathering since <para>Both Kea DHCP servers support statistics gathering.
0.9.2-beta version. A working DHCP server encounters various events A working DHCP server encounters various events
that can cause certain statistics to be collected. For that can cause certain statistics to be collected. For
example, a DHCPv4 server may receive a packet (pkt4-received 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 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 and pkt4-sent statistics increase by one). Such events happen
frequently, so it is not uncommon for the statistics to have frequently, so it is not uncommon for the statistics to have
values in high thousands. They can serve as an easy and powerful 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 statistics. When <command>statistic-get-all</command> is executed, an
empty list is returned. Once the server performs an operation that causes 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 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 explicitly removed, by <command>statistic-remove</command> or
<command>statistic-remove-all</command> being called or the server is shut <command>statistic-remove-all</command> being called or the server is shut
down. Per subnet statistics are explicitly removed when reconfiguration down. Per subnet statistics are explicitly removed when reconfiguration
@@ -114,6 +114,12 @@
it. it.
</para> </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"> <section id="command-statistic-get">
<title>statistic-get command</title> <title>statistic-get command</title>