Client Classification Overview
==============================
-In certain cases it is useful to differentiate between different types
+In certain cases it is useful to differentiate among different types
of clients and treat them accordingly. Common reasons include:
- The clients represent different pieces of topology, e.g. a cable
modem is not the same as the clients behind that modem.
-- The clients have different behavior, e.g. a smart phone behaves
+- The clients have different behavior, e.g. a smartphone behaves
differently from a laptop.
- The clients require different values for some options, e.g. a
- Using a hook.
-It is envisaged that client classification will be used for changing the
+It is envisaged that client classification will be used to change the
behavior of almost any part of the DHCP message processing. There are
currently five mechanisms that take advantage of client classification:
subnet selection, pool selection, definition of DHCPv4 private (codes
2. Vendor class options are processed.
-3. Classes with matching expressions and not marked for later ("on
+3. Classes with matching expressions and not marked for later evaluation ("on
request" or depending on the KNOWN/UNKNOWN builtin classes)
- evaluation are processed in the order they are defined in the
+ are processed in the order they are defined in the
configuration; the boolean expression is evaluated and, if it
returns true ("match"), the incoming packet is associated with the
class.
some subnets are reserved. More precisely: when choosing a subnet,
the server iterates over all of the subnets that are feasible given
the information found in the packet (client address, relay address,
- etc). It uses the first subnet it finds that either doesn't have a
+ etc.). It uses the first subnet it finds that either doesn't have a
class associated with it, or has a class which matches one of the
packet's classes.
classes of the host reservation. If a reservation is not found, the
packet is assigned to the UNKNOWN class.
-7. Classes with matching expressions - directly or indirectly using the
- KNOWN/UNKNOWN builtin classes and not marked for later ("on
- request") evaluation - are processed in the order they are defined
+7. Classes with matching expressions - directly, or indirectly using the
+ KNOWN/UNKNOWN builtin classes and not marked for later evaluation ("on
+ request") - are processed in the order they are defined
in the configuration; the boolean expression is evaluated and, if it
returns true ("match"), the incoming packet is associated with the
class. After a subnet is selected, the server determines whether
**Note**
- Care should be taken with client classification as it is easy for
+ Care should be taken with client classification, as it is easy for
clients that do not meet any class criteria to be denied service
altogether.
======================
Some classes are builtin, so they do not need to be defined. The main
-example uses Vendor Class information: The server checks whether an
+example uses Vendor Class information: the server checks whether an
incoming DHCPv4 packet includes the vendor class identifier option (60)
or an incoming DHCPv6 packet includes the vendor class option (16). If
it does, the content of that option is prepended with "VENDOR_CLASS_"
designate certain servers to process DHCP packets as a result of load
balancing. The class name is constructed by prepending the "HA_" prefix
to the name of the server which should process the DHCP packet. This
-server will use an appropriate pool or subnet to allocate IP addresses
+server uses an appropriate pool or subnet to allocate IP addresses
(and/or prefixes), based on the assigned client classes. The details can
-be found in `??? <#high-availability-library>`__.
+be found in :ref:`high-availability-library`.
-Other examples are: the ALL class, which all incoming packets belong to,
+Other examples are the ALL class, which all incoming packets belong to,
and the KNOWN class, assigned when host reservations exist for a
particular client. By convention, builtin classes' names begin with all
capital letters.
-Currently recognized builtin class names are ALL, KNOWN and UNKNOWN, and
+Currently recognized builtin class names are ALL, KNOWN and UNKNOWN, and the
prefixes VENDOR_CLASS_, HA_, AFTER_, and EXTERNAL_. Although the AFTER\_
prefix is a provision for an as-yet-unwritten hook, the EXTERNAL\_
prefix can be freely used; builtin classes are implicitly defined so
generally throws an exception, though this should not occur in a
normally functioning system.
-Other issues, for example the starting position of a substring being
+Other issues, such as the starting position of a substring being
outside of the substring or an option not existing in the packet, result
in the operator returning an empty string.
.. table:: List of Classification Values
- +-----------------------+-----------------------+-----------------------+
- | Name | Example expression | Example value |
- +=======================+=======================+=======================+
- | String literal | 'example' | 'example' |
- +-----------------------+-----------------------+-----------------------+
- | Hexadecimal string | 0x5a7d | 'Z}' |
- | literal | | |
- +-----------------------+-----------------------+-----------------------+
- | IP address literal | 10.0.0.1 | 0x0a000001 |
- +-----------------------+-----------------------+-----------------------+
- | Integer literal | 123 | '123' |
- +-----------------------+-----------------------+-----------------------+
- | | | |
- +-----------------------+-----------------------+-----------------------+
- | Binary content of the | option[123].hex | '(content of the |
- | option | | option)' |
- +-----------------------+-----------------------+-----------------------+
- | Option existence | option[123].exists | 'true' |
- +-----------------------+-----------------------+-----------------------+
- | Client class | member('foobar') | 'true' |
- | membership | | |
- +-----------------------+-----------------------+-----------------------+
- | Known client | known | member('KNOWN') |
- +-----------------------+-----------------------+-----------------------+
- | Unknown client | unknown | not member('KNOWN') |
- +-----------------------+-----------------------+-----------------------+
- | DHCPv4 relay agent | relay4[123].hex | '(content of the RAI |
- | sub-option | | sub-option)' |
- +-----------------------+-----------------------+-----------------------+
- | DHCPv6 Relay Options | relay6[nest].option[c | (value of the option) |
- | | ode].hex | |
- +-----------------------+-----------------------+-----------------------+
- | DHCPv6 Relay Peer | relay6[nest].peeraddr | 2001:DB8::1 |
- | Address | | |
- +-----------------------+-----------------------+-----------------------+
- | DHCPv6 Relay Link | relay6[nest].linkaddr | 2001:DB8::1 |
- | Address | | |
- +-----------------------+-----------------------+-----------------------+
- | Interface name of | pkt.iface | eth0 |
- | packet | | |
- +-----------------------+-----------------------+-----------------------+
- | Source address of | pkt.src | 10.1.2.3 |
- | packet | | |
- +-----------------------+-----------------------+-----------------------+
- | Destination address | pkt.dst | 10.1.2.3 |
- | of packet | | |
- +-----------------------+-----------------------+-----------------------+
- | Length of packet | pkt.len | 513 |
- +-----------------------+-----------------------+-----------------------+
- | Hardware address in | pkt4.mac | 0x010203040506 |
- | DHCPv4 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | Hardware length in | pkt4.hlen | 6 |
- | DHCPv4 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | Hardware type in | pkt4.htype | 6 |
- | DHCPv4 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | ciaddr field in | pkt4.ciaddr | 192.0.2.1 |
- | DHCPv4 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | giaddr field in | pkt4.giaddr | 192.0.2.1 |
- | DHCPv4 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | yiaddr field in | pkt4.yiaddr | 192.0.2.1 |
- | DHCPv4 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | siaddr field in | pkt4.siaddr | 192.0.2.1 |
- | DHCPv4 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | Message type in | pkt4.msgtype | 1 |
- | DHCPv4 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | Transaction ID (xid) | pkt4.transid | 12345 |
- | in DHCPv4 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | Message type in | pkt6.msgtype | 1 |
- | DHCPv6 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | Transaction ID in | pkt6.transid | 12345 |
- | DHCPv6 packet | | |
- +-----------------------+-----------------------+-----------------------+
- | Vendor option | vendor[*].exists | true |
- | existence (any | | |
- | vendor) | | |
- +-----------------------+-----------------------+-----------------------+
- | Vendor option | vendor[4491].exists | true |
- | existence (specific | | |
- | vendor) | | |
- +-----------------------+-----------------------+-----------------------+
- | Enterprise-id from | vendor.enterprise | 4491 |
- | vendor option | | |
- +-----------------------+-----------------------+-----------------------+
- | Vendor sub-option | vendor[4491].option[1 | true |
- | existence | ].exists | |
- +-----------------------+-----------------------+-----------------------+
- | Vendor sub-option | vendor[4491].option[1 | docsis3.0 |
- | content | ].hex | |
- +-----------------------+-----------------------+-----------------------+
- | Vendor class option | vendor-class[*].exist | true |
- | existence (any | s | |
- | vendor) | | |
- +-----------------------+-----------------------+-----------------------+
- | Vendor class option | vendor-class[4491].ex | true |
- | existence (specific | ists | |
- | vendor) | | |
- +-----------------------+-----------------------+-----------------------+
- | Enterprise-id from | vendor-class.enterpri | 4491 |
- | vendor class option | se | |
- +-----------------------+-----------------------+-----------------------+
- | First data chunk from | vendor-class[4491].da | docsis3.0 |
- | vendor class option | ta | |
- +-----------------------+-----------------------+-----------------------+
- | Specific data chunk | vendor-class[4491].da | docsis3.0 |
- | from vendor class | ta[3] | |
- | option | | |
- +-----------------------+-----------------------+-----------------------+
+ +-----------------------+-------------------------------+-----------------------+
+ | Name | Example expression | Example value |
+ +=======================+===============================+=======================+
+ | String literal | 'example' | 'example' |
+ +-----------------------+-------------------------------+-----------------------+
+ | Hexadecimal string | 0x5a7d | 'Z}' |
+ | literal | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | IP address literal | 10.0.0.1 | 0x0a000001 |
+ +-----------------------+-------------------------------+-----------------------+
+ | Integer literal | 123 | '123' |
+ +-----------------------+-------------------------------+-----------------------+
+ | Binary content of the | option[123].hex | '(content of the |
+ | option | | option)' |
+ +-----------------------+-------------------------------+-----------------------+
+ | Option existence | option[123].exists | 'true' |
+ +-----------------------+-------------------------------+-----------------------+
+ | Client class | member('foobar') | 'true' |
+ | membership | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Known client | known | member('KNOWN') |
+ +-----------------------+-------------------------------+-----------------------+
+ | Unknown client | unknown | not member('KNOWN') |
+ +-----------------------+-------------------------------+-----------------------+
+ | DHCPv4 relay agent | relay4[123].hex | '(content of the RAI |
+ | sub-option | | sub-option)' |
+ +-----------------------+-------------------------------+-----------------------+
+ | DHCPv6 Relay Options | relay6[nest].option[code].hex | (value of the option) |
+ +-----------------------+-------------------------------+-----------------------+
+ | DHCPv6 Relay Peer | relay6[nest].peeraddr | 2001:DB8::1 |
+ | Address | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | DHCPv6 Relay Link | relay6[nest].linkaddr | 2001:DB8::1 |
+ | Address | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Interface name of | pkt.iface | eth0 |
+ | packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Source address of | pkt.src | 10.1.2.3 |
+ | packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Destination address | pkt.dst | 10.1.2.3 |
+ | of packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Length of packet | pkt.len | 513 |
+ +-----------------------+-------------------------------+-----------------------+
+ | Hardware address in | pkt4.mac | 0x010203040506 |
+ | DHCPv4 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Hardware length in | pkt4.hlen | 6 |
+ | DHCPv4 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Hardware type in | pkt4.htype | 6 |
+ | DHCPv4 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | ciaddr field in | pkt4.ciaddr | 192.0.2.1 |
+ | DHCPv4 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | giaddr field in | pkt4.giaddr | 192.0.2.1 |
+ | DHCPv4 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | yiaddr field in | pkt4.yiaddr | 192.0.2.1 |
+ | DHCPv4 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | siaddr field in | pkt4.siaddr | 192.0.2.1 |
+ | DHCPv4 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Message type in | pkt4.msgtype | 1 |
+ | DHCPv4 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Transaction ID (xid) | pkt4.transid | 12345 |
+ | in DHCPv4 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Message type in | pkt6.msgtype | 1 |
+ | DHCPv6 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Transaction ID in | pkt6.transid | 12345 |
+ | DHCPv6 packet | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Vendor option | vendor[*].exists | true |
+ | existence (any | | |
+ | vendor) | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Vendor option | vendor[4491].exists | true |
+ | existence (specific | | |
+ | vendor) | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Enterprise-id from | vendor.enterprise | 4491 |
+ | vendor option | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Vendor sub-option | vendor[4491].option[1].exists | true |
+ | existence | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Vendor sub-option | vendor[4491].option[1].hex | docsis3.0 |
+ | content | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Vendor class option | vendor-class[*].exist | true |
+ | existence (any | s | |
+ | vendor) | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Vendor class option | vendor-class[4491].exists | true |
+ | existence (specific | | |
+ | vendor) | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Enterprise-id from | vendor-class.enterprise | 4491 |
+ | vendor class option | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | First data chunk from | vendor-class[4491].data | docsis3.0 |
+ | vendor class option | | |
+ +-----------------------+-------------------------------+-----------------------+
+ | Specific data chunk | vendor-class[4491].data[3] | docsis3.0 |
+ | from vendor class | | |
+ | option | | |
+ +-----------------------+-------------------------------+-----------------------+
Notes:
of characters a "0" is prepended to it.
- IP addresses are converted into strings of length 4 or 16. IPv4,
- IPv6, and IPv4-embedded IPv6 (e.g., IPv4-mapped IPv6) addresses are
+ IPv6, and IPv4-embedded IPv6 (e.g. IPv4-mapped IPv6) addresses are
supported.
- Integers in an expression are converted to 32-bit unsigned integers
- "member('foobar')" checks whether the packet belongs to the client
class "foobar". To avoid dependency loops, the configuration file
parser verifies whether client classes were already defined or are
- builtin, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the to
- come "after" hook) and "EXTERNAL_" or equal to "ALL", "KNOWN",
- "UNKNOWN"etc.
+ builtin, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the
+ to-come "after" hook) and "EXTERNAL_" or equal to "ALL", "KNOWN",
+ "UNKNOWN", etc.
- "known" and "unknown" are short hands for "member('KNOWN')" and "not
- member('KNOWN')". Note the evaluation of any expression using
+ "known" and "unknown" are shorthand for "member('KNOWN')" and "not
+ member('KNOWN')". Note that the evaluation of any expression using
directly or indirectly the "KNOWN" class is deferred after the host
reservation lookup (i.e. when the "KNOWN" or "UNKNOWN" partition is
determined).
the option payload without the type code or length fields. This
expression is allowed in DHCPv4 only.
-- "relay4" shares the same representation types as "option", for
- instance "relay4[code].exists" is supported.
+- "relay4" shares the same representation types as "option"; for
+ instance, "relay4[code].exists" is supported.
- "relay6[nest]" allows access to the encapsulations used by any DHCPv6
relays that forwarded the packet. The "nest" level specifies the
relay from which to extract the information, with a value of 0
indicating the relay closest to the DHCPv6 server. Negative values
- allow to specify relays counted from the DHCPv6 client, -1 indicating
- the relay closest to the client. In general negative "nest" level is
+ allow specifying relays counted from the DHCPv6 client, -1 indicating
+ the relay closest to the client. In general, negative "nest" level is
the same as the number of relays + "nest" level. If the requested
- encapsulation doesn't exist an empty string "" is returned. This
+ encapsulation doesn't exist, an empty string "" is returned. This
expression is allowed in DHCPv6 only.
- "relay6[nest].option[code]" shares the same representation types as
- "option", for instance "relay6[nest].option[code].exists" is
+ "option"; for instance, "relay6[nest].option[code].exists" is
supported.
- Expressions starting with "pkt4" can be used only in DHCPv4. They
- allows access to DHCPv4 message fields.
+ allow access to DHCPv4 message fields.
- "pkt6" refers to information from the client request. To access any
information from an intermediate relay use "relay6". "pkt6.msgtype"
- and "pkt6.transid" output a 4 byte binary string for the message type
+ and "pkt6.transid" output a 4-byte binary string for the message type
or transaction id. For example the message type SOLICIT will be
"0x00000001" or simply 1 as in "pkt6.msgtype == 1".
-- Vendor option means Vendor-Identifying Vendor-specific Information
- option in DHCPv4 (code 125, see `Section 4 of RFC
- 3925 <http://tools.ietf.org/html/rfc3925#section-4>`__) and
- Vendor-specific Information Option in DHCPv6 (code 17, defined in
+- Vendor option means the Vendor-Identifying Vendor-Specific Information
+ option in DHCPv4 (code 125; see `Section 4 of RFC
+ 3925 <https://tools.ietf.org/html/rfc3925#section-4>`__) and
+ Vendor-Specific Information Option in DHCPv6 (code 17, defined in
`Section 21.17 of RFC
8415 <https://tools.ietf.org/html/rfc8415#section-21.17>`__). Vendor
class option means Vendor-Identifying Vendor Class Option in DHCPv4
- (code 124, see `Section 3 of RFC
- 3925 <http://tools.ietf.org/html/rfc3925#section-3>`__) in DHCPv4 and
- Class Option in DHCPv6 (code 16, see `Section 21.16 of RFC
+ (code 124; see `Section 3 of RFC
+ 3925 <https://tools.ietf.org/html/rfc3925#section-3>`__) in DHCPv4 and
+ Class Option in DHCPv6 (code 16; see `Section 21.16 of RFC
8415 <https://tools.ietf.org/html/rfc8415#section-21.16>`__). 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.
+ chunk, index 1 is for the second data chunk (if present), etc.
-- In the vendor and vendor-class constructs Asterisk (*) or 0 can be
+- In the vendor and vendor-class constructs an asterisk (*) or 0 can be
used to specify a wildcard enterprise-id value, i.e. it will match
any enterprise-id value.
-- Vendor Class Identifier (option 60 in DHCPv4) can be accessed using
+- Vendor Class Identifier (option 60 in DHCPv4) can be accessed using the
option[60] expression.
-- `RFC 3925 <http://tools.ietf.org/html/rfc3925>`__ and `RFC
- 8415 <http://tools.ietf.org/html/rfc8415>`__ allow for multiple
+- `RFC 3925 <https://tools.ietf.org/html/rfc3925>`__ and `RFC
+ 8415 <https://tools.ietf.org/html/rfc8415>`__ 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
+ than one appear. For the 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.
+ submit a feature request on the
+ `Kea GitLab site <https://gitlab.isc.org/isc-projects/kea>`__ if you need
+ support for multiple instances.
.. table:: List of Classification Expressions
- +-----------------------+-----------------------+-----------------------+
- | Name | Example | Description |
- +=======================+=======================+=======================+
- | Equal | 'foo' == 'bar' | Compare the two |
- | | | values and return |
- | | | "true" or "false" |
- +-----------------------+-----------------------+-----------------------+
- | Not | not ('foo' == 'bar') | Logical negation |
- +-----------------------+-----------------------+-----------------------+
- | And | ('foo' == 'bar') and | Logical and |
- | | ('bar' == 'foo') | |
- +-----------------------+-----------------------+-----------------------+
- | Or | ('foo' == 'bar') or | Logical or |
- | | ('bar' == 'foo') | |
- +-----------------------+-----------------------+-----------------------+
- | Substring | substring('foobar',0, | Return the requested |
- | | 3) | substring |
- +-----------------------+-----------------------+-----------------------+
- | Concat | concat('foo','bar') | Return the |
- | | | concatenation of the |
- | | | strings |
- +-----------------------+-----------------------+-----------------------+
- | Ifelse | ifelse('foo' == | Return the branch |
- | | 'bar','us','them') | value according to |
- | | | the condition |
- +-----------------------+-----------------------+-----------------------+
- | Hexstring | hexstring('foo', '-') | Converts the value to |
- | | | a hexadecimal string, |
- | | | e.g. 0a:1b:2c:3e |
- +-----------------------+-----------------------+-----------------------+
+ +-----------------------+-------------------------+-----------------------+
+ | Name | Example | Description |
+ +=======================+=========================+=======================+
+ | Equal | 'foo' == 'bar' | Compare the two |
+ | | | values and return |
+ | | | "true" or "false" |
+ +-----------------------+-------------------------+-----------------------+
+ | Not | not ('foo' == 'bar') | Logical negation |
+ +-----------------------+-------------------------+-----------------------+
+ | And | ('foo' == 'bar') and | Logical and |
+ | | ('bar' == 'foo') | |
+ +-----------------------+-------------------------+-----------------------+
+ | Or | ('foo' == 'bar') or | Logical or |
+ | | ('bar' == 'foo') | |
+ +-----------------------+-------------------------+-----------------------+
+ | Substring | substring('foobar',0,3) | Return the requested |
+ | | | substring |
+ +-----------------------+-------------------------+-----------------------+
+ | Concat | concat('foo','bar') | Return the |
+ | | | concatenation of the |
+ | | | strings |
+ +-----------------------+-------------------------+-----------------------+
+ | Ifelse | ifelse('foo' == | Return the branch |
+ | | 'bar','us','them') | value according to |
+ | | | the condition |
+ +-----------------------+-------------------------+-----------------------+
+ | Hexstring | hexstring('foo', '-') | Converts the value to |
+ | | | a hexadecimal string, |
+ | | | e.g. 0a:1b:2c:3e |
+ +-----------------------+-------------------------+-----------------------+
Logical operators
-----------------
-The Not, And and Or logical operators are the common operators. Not has
+The Not, And, and Or logical operators are the common operators. Not 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
+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").
+
Substring
---------
the last byte. If the starting point is outside of the original string
an empty string is returned. "length" is the number of bytes to extract.
A negative number means to count towards the beginning of the string but
-doesn't include the byte pointed to by "start". The special value "all"
-means to return all bytes from start to the end of the string. If length
-is longer than the remaining portion of the string then the entire
+does not include the byte pointed to by "start". The special value "all"
+means to return all bytes from start to the end of the string. If the length
+is longer than the remaining portion of the string, then the entire
remaining portion is returned. Some examples may be helpful:
::
The expression for each class is executed on each packet received. If
the expressions are overly complex, the time taken to execute them
- may impact the performance of the server. If you need complex or time
- consuming expressions you should write a `hook <#hooks-libraries>`__
- to perform the necessary work.
+ may impact the performance of the server. Administrators who need complex or
+ time-consuming expressions should consider writing a
+ `hook <#hooks-libraries>`__ to perform the necessary work.
.. _classification-configuring:
===================
A class contains five items: a name, a test expression, option data,
-option definition and only-if-required flag. The name must exist and
-must be unique amongst all classes. The test expression, option data and
+an option definition, and an only-if-required flag. The name must exist and
+must be unique among all classes. The test expression, option data and
definition, and only-if-required flag are optional.
The test expression is a string containing the logical expression used
assigned to members of this class.
The option definition is for DHCPv4 option 43
-(`??? <#dhcp4-vendor-opts>`__ and DHCPv4 private options
-(`??? <#dhcp4-private-opts>`__).
+(:ref:`dhcp4-vendor-opts` and DHCPv4 private options
+(:ref:`dhcp4-private-opts`).
-Usually the test expression is evaluated before subnet selection but in
+Usually the test expression is evaluated before subnet selection, but in
some cases it is useful to evaluate it later when the subnet,
-shared-network or pools are known but output option processing not yet
-done. The only-if-required flag, false by default, allows to perform the
-evaluation of the test expression only when it was required, i.e. in a
-require-client-classes list of the selected subnet, shared-network or
+shared network, or pools are known but output option processing has not yet
+been done. The only-if-required flag, false by default, allows the
+evaluation of the test expression only when it is required, i.e. in a
+require-client-classes list of the selected subnet, shared network, or
pool.
The require-client-classes list which is valid for shared-network,
-subnet and pool scope specifies the classes which are evaluated in the
+subnet, and pool scope specifies the classes which are evaluated in the
second pass before output option processing. The list is built in the
-reversed precedence order of option data, i.e. an option data in a
-subnet takes precedence on one in a shared-network but required class in
-a subnet is added after one in a shared-network. The mechanism is
+reversed precedence order of option data, i.e. an option data item in a
+subnet takes precedence over one in a shared network, but required class in
+a subnet is added after one in a shared network. The mechanism is
related to the only-if-required flag but it is not mandatory that the
-flag was set to true.
+flag be set to true.
-In the following example the class named "Client_foo" is defined. It is
+In the following example, the class named "Client_foo" is defined. It is
comprised of all clients whose client ids (option 61) start with the
string "foo". Members of this class will be given 192.0.2.1 and
192.0.2.2 as their domain name servers.
This example shows a client class being defined for use by the DHCPv6
server. In it the class named "Client_enterprise" is defined. It is
-comprised of all clients who's client identifiers start with the given
+comprised of all clients whose client identifiers start with the given
hex string (which would indicate a DUID based on an enterprise id of
0xAABBCCDD). Members of this class will be given an 2001:db8:0::1 and
2001:db8:2::1 as their domain name servers.
================================================
Classes can be statically assigned to the clients using techniques
-described in `??? <#reservation4-client-classes>`__ and
-`??? <#reservation6-client-classes>`__.
+described in :ref:`reservation4-client-classes` and
+:ref:`reservation6-client-classes`.
.. _classification-subnets:
Configuring Subnets With Class Information
==========================================
-In certain cases it beneficial to restrict access to certain subnets
+In certain cases it is beneficial to restrict access to certain subnets
only to clients that belong to a given class, using the "client-class"
keyword when defining the subnet.
Let's assume that the server is connected to a network segment that uses
-the 192.0.2.0/24 prefix. The Administrator of that network has decided
-that addresses from range 192.0.2.10 to 192.0.2.20 are going to be
+the 192.0.2.0/24 prefix. The administrator of that network has decided
+that addresses from the range 192.0.2.10 to 192.0.2.20 are going to be
managed by the DHCP4 server. Only clients belonging to client class
Client_foo are allowed to use this subnet. Such a configuration can be
achieved in the following way:
...
}
-The following example shows restricting access to a DHCPv6 subnet. This
+The following example shows how to restrict access to a DHCPv6 subnet. This
configuration will restrict use of the addresses 2001:db8:1::1 to
2001:db8:1::FFFF to members of the "Client_enterprise" class.
Configuring Pools With Class Information
========================================
-Similar to subnets in certain cases access to certain address or prefix
+Similar to subnets, in certain cases access to certain address or prefix
pools must be restricted to only clients that belong to a given class,
using the "client-class" when defining the pool.
Let's assume that the server is connected to a network segment that uses
-the 192.0.2.0/24 prefix. The Administrator of that network has decided
-that addresses from range 192.0.2.10 to 192.0.2.20 are going to be
+the 192.0.2.0/24 prefix. The administrator of that network has decided
+that addresses from the range 192.0.2.10 to 192.0.2.20 are going to be
managed by the DHCP4 server. Only clients belonging to client class
Client_foo are allowed to use this pool. Such a configuration can be
achieved in the following way:
}
-The following example shows restricting access to an address pool. This
+The following example shows how to restrict access to an address pool. This
configuration will restrict use of the addresses 2001:db8:1::1 to
2001:db8:1::FFFF to members of the "Client_enterprise" class.
Using Classes
=============
-Currently classes can be used for two functions. They can supply options
-to the members of the class and they can be used to choose a subnet from
-which an address will be assigned to the class member.
+Currently classes can be used for two functions: they can supply options
+to members of the class, and they can be used to choose a subnet from
+which an address will be assigned to a class member.
When supplying options, options defined as part of the class definition
-are considered "class globals". They will override any global options
+are considered "class globals." They will override any global options
that may be defined and in turn will be overridden by any options
defined for an individual subnet.
Classes and Hooks
=================
-You may use a hook to classify your packets. This may be useful if the
-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 hooks
-see `??? <#hooks-libraries>`__, for a description on configuring classes
-see `Configuring Classes <#classification-configuring>`__ and
-`Configuring Subnets With Class
-Information <#classification-subnets>`__.
+Hooks may be used to classify packets. This may be useful if the
+expression would be complex or time-consuming to write, and could be
+better or more easily written as code. Once the hook has added the proper class name
+to the packet, the rest of the classification system will work as expected
+in choosing a subnet and selecting options. For a description of hooks,
+see :ref:`hooks-libraries>`__; for information on configuring classes,
+see :ref:`classification-configuring` and :ref:`classification-subnets`.
Debugging Expressions
=====================
-While you are constructing your classification expressions you may find
-it useful to enable logging see `??? <#logging>`__ for a more complete
+While constructing classification expressions, administrators may find
+it useful to enable logging; see :ref:`logging` for a more complete
description of the logging facility.
-To enable the debug statements in the classification system you will
-need to set the severity to "DEBUG" and the debug level to at least 55.
+To enable the debug statements in the classification system,
+the severity must be set to "DEBUG" and the debug level to at least 55.
The specific loggers are "kea-dhcp4.eval" and "kea-dhcp6.eval".
-In order to understand the logging statements, one must understand a bit
-about how expressions are evaluated; for a more complete description
+To understand the logging statements, it is essential to understand a bit
+about how expressions are evaluated; for a more complete description,
refer to the design document at
https://gitlab.isc.org/isc-projects/kea/wikis/design%20documents. In
-brief there are two structures used during the evaluation of an
-expression: a list of tokens which represent the expressions and a value
+brief, there are two structures used during the evaluation of an
+expression: a list of tokens which represent the expressions, and a value
stack which represents the values being manipulated.
-The list of tokens is created when the configuration file is processed
+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 order. As each token is executed it will be able to pop
+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:
off of the value stack and any objects that were pushed onto the value
stack.
-The values will be displayed as either text if the command is known to
-use text values or hexadecimal if the command either uses binary values
+The values will be displayed as either text, if the command is known 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 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.
+they were popped. For most expressions this will not matter, but for the
+concat expression the values are displayed in reverse order from their
+written order in the expression.
Let us assume that the following test has been entered into the
configuration. This example skips most of the configuration to
**Note**
- The debug logging may be quite verbose if you have a number of
- expressions 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 to limit the log
- statements. For example when adding a new set of expressions you
+ The debug logging may be quite verbose if there are a number of
+ expressions to evaluate; that is intended as an aid in helping
+ create and debug expressions. Administrators should plan to disable debug
+ logging when the expressions are working correctly. Users may also
+ wish to include only one set of expressions at a time in the
+ configuration file while debugging them, to limit the log
+ statements. For example, when adding a new set of expressions, an administrator
might find it more convenient to create a configuration file that
- only includes the new expressions until you have them working
- correctly and then add the new set to the main configuration file.
+ only includes the new expressions until they are working
+ correctly, and then add the new set to the main configuration file.
The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts
the client side of the Dynamic DNS protocol (DDNS, defined in `RFC
-2136 <http://tools.ietf.org/html/rfc2136>`__) on behalf of the DHCPv4
+2136 <https://tools.ietf.org/html/rfc2136>`__) on behalf of the DHCPv4
and DHCPv6 servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP
-servers construct DDNS update requests, known as NameChangeRequests
+servers construct DDNS update requests, known as Name Change Requests
(NCRs), based on DHCP lease change events and then post them to D2. D2
attempts to match each request to the appropriate DNS server(s) and
carries out the necessary conversation with those servers to update the
named DDNS Domains. Further, each DDNS Domain has a list of one or more
DNS servers that publish the DNS data for that domain.
-When conducting forward domain matching, D2 compares the fully-qualified
+When conducting forward domain matching, D2 compares the fully qualified
domain name (FQDN) in the request against the name of each Forward DDNS
Domain in its catalog. The domain whose name matches the longest portion
of the FQDN is considered the best match. For example, if the FQDN is
former is the best match. As with forward matching, it may not find a
suitable match. Given the same two domains, there would be no match for
the lease address, "192.168.1.50", and the request would be rejected.
-Finally, if there are no Reverse DDNS Domains defined, D2 will simply
-disregard the reverse update portion of requests.
+Finally, if there are no Reverse DDNS Domains defined, D2 simply
+disregards the reverse update portion of requests.
.. _dhcp-ddns-conflict-resolution:
-------------------
D2 implements the conflict resolution strategy prescribed by `RFC
-4703 <http://tools.ietf.org/html/rfc4703>`__. Conflict resolution is
+4703 <https://tools.ietf.org/html/rfc4703>`__. Conflict resolution is
intended to prevent different clients from mapping to the same FQDN at
the same time. To make this possible, the RFC requires that forward DNS
entries for a given FQDN must be accompanied by a DHCID resource record
-----------------------
`RFC 4703, section
-5.2, <http://tools.ietf.org/html/rfc4703#section-5.2>`__ describes
+5.2, <https://tools.ietf.org/html/rfc4703#section-5.2>`__ describes
issues that may arise with dual-stack clients. These are clients that
wish to have have both IPv4 and IPv6 mappings for the same FQDN. For
this to work properly, the clients are required to embed their IPv6 DUID
-within their IPv4 client identifier option as described in `RFC
-4703 <http://tools.ietf.org/html/rfc4361>`__. In this way, DNS updates
-for both IPv4 and IPv6 can be managed under the same DHCID RR. Support
-for this does not yet exist in Kea.
+within their IPv4 client identifier option, as described in `RFC
+4703 <https://tools.ietf.org/html/rfc4361>`__. In this way, DNS updates
+for both IPv4 and IPv6 can be managed under the same DHCID RR. Kea does not
+currently support this feature.
.. _dhcp-ddns-server-start-stop:
``kea-dhcp-ddns`` is the Kea DHCP-DDNS server and, due to the nature of
DDNS, it runs alongside either the DHCPv4 or DHCPv6 component (or both).
Like other parts of Kea, it is a separate binary that can be run on its
-own or through ``keactrl`` (see `??? <#keactrl>`__). In normal
+own or through ``keactrl`` (see :ref:`keactrl`). In normal
operation, controlling ``kea-dhcp-ddns`` with ``keactrl`` is
recommended; however, it is also possible to run the DHCP-DDNS server
directly. It accepts the following command-line switches:
is a copy of the ``config.report`` file produced by ``./configure``;
it is embedded in the executable binary.
-- ``-t file`` specifies the configuration file to be tested.
+- ``-t file`` - specifies the configuration file to be tested.
Kea-dhcp-ddns will attempt to load it and will conduct sanity checks.
Note that certain checks are possible only while running the actual
server. The actual status is reported with an exit code (0 =
strings path/kea-dhcp-ddns | sed -n 's/;;;; //p'
-Upon startup the module will load its configuration and begin listening
+Upon startup, the module will load its configuration and begin listening
for NCRs based on that configuration.
-During startup the server will attempt to create a PID file of the form:
+During startup, the server will attempt to create a PID file of the form:
[localstatedir]/[conf name].kea-dhcp-ddns.pid where:
-- ``localstatedir``: The value as passed into the build configure
+- ``localstatedir`` - is the value as passed into the build configure
script; it defaults to "/usr/local/var". Note that this value may be
overridden at runtime by setting the environment variable
KEA_PIDFILE_DIR. This is intended primarily for testing purposes.
-- ``conf name``: The configuration file name used to start the server,
+- ``conf name`` - is the configuration file name used to start the server,
minus all preceding paths and the file extension. For example, given
a pathname of "/usr/local/etc/kea/myconf.txt", the portion used would
be "myconf".
Configuring the DHCP-DDNS Server
================================
-Before starting ``kea-dhcp-ddns`` module for the first time, a
+Before starting the ``kea-dhcp-ddns`` module for the first time, a
configuration file must be created. The following default configuration
-is a template that can be customized to your requirements.
+is a template that can be customized to individual requirements.
::
The configuration can be divided into the following sections, each of
which is described below:
-- *Global Server Parameters* - values which control connectivity and
+- *Global Server Parameters* - define values which control connectivity and
global server behavior.
- *Control Socket* - defines the Control Socket type and name.
Global Server Parameters
------------------------
-- ``ip-address`` - IP address on which D2 listens for requests. The
- default is the local loopback interface at address 127.0.0.1. You may
- specify either an IPv4 or IPv6 address.
+- ``ip-address`` - the IP address on which D2 listens for requests. The
+ default is the local loopback interface at address 127.0.0.1.
+ Either an IPv4 or IPv6 address may be specified.
-- ``port`` - Port on which D2 listens for requests. The default value
+- ``port`` - the port on which D2 listens for requests. The default value
is 53001.
-- ``dns-server-timeout`` - Maximum amount of time, in milliseconds,
+- ``dns-server-timeout`` - the maximum amount of time, in milliseconds,
that D2 will wait for a response from a DNS server to a single DNS
update message.
-- ``ncr-protocol`` - Socket protocol to use when sending requests to
+- ``ncr-protocol`` - the socket protocol to use when sending requests to
D2. Currently only UDP is supported.
-- ``ncr-format`` - Packet format to use when sending requests to D2.
+- ``ncr-format`` - the packet format to use when sending requests to D2.
Currently only JSON format is supported.
D2 must listen for change requests on a known address and port. By
It is possible for a malicious attacker to send bogus
NameChangeRequests to the DHCP-DDNS server. Addresses other than the
IPv4 or IPv6 loopback addresses (127.0.0.1 or ::1) should only be
- used for testing purposes, but note that local users may still
+ used for testing purposes; note that local users may still
communicate with the DHCP-DDNS server.
**Note**
The management API allows the issuing of specific management commands,
such as configuration retrieval or shutdown. For more details, see
-`??? <#ctrl-channel>`__. Currently the only supported communication
+:ref:`ctrl-channel`. Currently, the only supported communication
channel type is UNIX stream socket. By default there are no sockets
-open. To instruct Kea to open a socket, the following entry in the
+open; to instruct Kea to open a socket, the following entry in the
configuration file can be used:
::
}
The length of the path specified by the ``socket-name`` parameter is
-restricted by the maximum length for the unix socket name on your
+restricted by the maximum length for the UNIX socket name on the
operating system, i.e. the size of the ``sun_path`` field in the
``sockaddr_un`` structure, decreased by 1. This value varies on
different operating systems between 91 and 107 characters. Typical
values are 107 on Linux and 103 on FreeBSD.
-Communication over control channel is conducted using JSON structures.
-See the Control Channel section in the Kea Developer's Guide for more
-details.
+Communication over the control channel is conducted using JSON structures.
+See the `Control Channel section in the Kea Developer's
+Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/d2/d96/ctrlSocket.html>`__
+for more details.
The D2 server supports the following operational commands:
-------------
A DDNS protocol exchange can be conducted with or without TSIG (defined
-in `RFC 2845 <http://tools.ietf/org/html/rfc2845>`__). This
+in `RFC 2845 <https://tools.ietf/org/html/rfc2845>`__). This
configuration section allows the administrator to define the set of TSIG
keys that may be used in such exchanges.
-To use TSIG when updating entries in a DNS Domain, a key must be defined
-in the TSIG Key List and referenced by name in that domain's
+To use TSIG when updating entries in a DNS domain, a key must be defined
+in the TSIG Key list and referenced by name in that domain's
configuration entry. When D2 matches a change request to a domain, it
checks whether the domain has a TSIG key associated with it. If so, D2
-will use that key to sign DNS update messages sent to and verify
+uses that key to sign DNS update messages sent to and verify
responses received from the domain's DNS server(s). For each TSIG key
required by the DNS servers that D2 will be working with, there must be
a corresponding TSIG key in the TSIG Key list.
by one or more DNS servers to authenticate requests and sign responses.
Every entry in the list has three parameters:
-- ``name`` - a unique text label used to identify this key within the
+- ``name`` - is a unique text label used to identify this key within the
list. This value is used to specify which key (if any) should be used
when updating a specific domain. As long as the name is unique its
content is arbitrary, although for clarity and ease of maintenance it
~~~~~~~~~~~~~~~~~~~~~~~~~~~
A Forward DDNS Domain maps a forward DNS zone to a set of DNS servers
-which maintain the forward DNS data (i.e. name-to- address mapping) for
+which maintain the forward DNS data (i.e. name-to-address mapping) for
that zone. Each zone served needs one Forward DDNS Domain. It may very
well be that some or all of the zones are maintained by the same
-servers, but you will still need one DDNS Domain per zone. Remember that
+servers, but one DDNS Domain is still needed for each zone. Remember that
matching a request to the appropriate server(s) is done by zone and a
DDNS Domain only defines a single zone.
during forward matching. It must be unique within the catalog.
- ``key-name`` - if TSIG is used with this domain's servers, this value
- should be the name of the key from within the TSIG Key List. If the
+ should be the name of the key from the TSIG Key list. If the
value is blank (the default), TSIG will not be used in DDNS
conversations with this domain's servers.
used in a first-to-last preference; in other words, when D2 begins to
process a request for this domain, it will pick the first server in
this list and attempt to communicate with it. If that attempt fails,
- it will move to next one in the list and so on until either it
- achieves success or the list is exhausted.
+ D2 will move to next one in the list and so on until either it
+ is successful or the list is exhausted.
To create a new Forward DDNS Domain, add a new domain element and set
its parameters:
It is possible to add a domain without any servers; however, if that
domain matches a request, the request will fail. To make the domain
-useful, we must add at least one DNS server to it.
+useful, at least one DNS server must be added to it.
.. _add-forward-dns-servers:
- ``port`` - the port on which the server listens for DDNS requests. It
defaults to the standard DNS service port of 53.
-To create a new forward DNS Server, one must add a new server element to
-the domain and fill in its parameters. If, for example, the service is
-running at "172.88.99.10", then set the forward DNS Server as follows:
+To create a new Forward DNS Server, a new server element must be added to
+the domain and its parameters filled in. If, for example, the service is
+running at "172.88.99.10", set the Forward DNS Server as follows:
::
which maintain the reverse DNS data (address-to-name mapping) for that
zone. Each zone served needs one Reverse DDNS Domain. It may very well
be that some or all of the zones are maintained by the same servers, but
-you will still need one DDNS Domain entry for each zone. Remember that
+one DDNS Domain entry is still needed for each zone. Remember that
matching a request to the appropriate server(s) is done by zone and a
DDNS Domain only defines a single zone.
2001:db8:1, the name should be "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa."
Whatever the name, it must be unique within the catalog.
-- ``key-name`` - if TSIG should be used with this domain's servers,
- this value should be the name of that key from the TSIG Key List. If
+- ``key-name`` - if TSIG is used with this domain's servers,
+ this value should be the name of the key from the TSIG Key List. If
the value is blank (the default), TSIG will not be used in DDNS
conversations with this domain's servers. Currently this value is not
used as TSIG has not been implemented.
servers are used in a first-to-last preference; in other words, when
D2 begins to process a request for this domain, it will pick the
first server in this list and attempt to communicate with it. If that
- attempt fails, it will move to the next one in the list and so on
- until either it achieves success or the list is exhausted.
+ attempt fails, D2 will move to the next one in the list and so on
+ until either it is successful or the list is exhausted.
-To create a new Reverse DDNS Domain, one must add a new domain element
-and set its parameters. For example, to support subnet 2001:db8:1::, the
+To create a new Reverse DDNS Domain, a new domain element must be added
+and its parameters set. For example, to support subnet 2001:db8:1::, the
following configuration could be used:
::
It is possible to add a domain without any servers; however, if that
domain matches a request, the request will fail. To make the domain
-useful, you must add at least one DNS server to it.
+useful, at least one DNS server must be added to it.
.. _add-reverse-dns-servers:
- ``port`` - the port on which the server listens for DDNS requests. It
defaults to the standard DNS service port of 53.
-To create a new reverse DNS Server, one must first add a new server
-element to the domain and fill in its parameters. If, for example, the
+To create a new reverse DNS Server, a new server
+element must be added to the domain and its parameters filled in. If, for example, the
service is running at "172.88.99.10", then set it as follows:
::
User contexts were designed for hook libraries, which are not yet
supported for DHCP-DDNS server configuration.
-User contexts can store arbitrary data as long as it has valid JSON
-syntax and its top level element is a map (i.e. the data must be
+User contexts can store arbitrary data as long as the file has valid JSON
+syntax and the top-level element is a map (i.e. the data must be
enclosed in curly brackets).
-User contexts can be specified on global scope, ddns domain, dns server,
-tsig key, and loggers. One other useful usage is the ability to store
+User contexts can be specified on global scope, DDNS domain, DNS server,
+TSIG key, and loggers. One other useful usage is the ability to store
comments or descriptions; the parser translates a "comment" entry into a
user context with the entry, which allows a comment to be attached
inside the configuration itself.
.. table:: Our Example Network
- +-----------------+-----------------+-----------------+-----------------+
- | Domain | Subnet | Forward DNS | Reverse DNS |
- | | | Servers | Servers |
- +=================+=================+=================+=================+
- | four.example.co | 192.0.2.0/24 | 172.16.1.5, | 172.16.1.5, |
- | m | | 172.16.2.5 | 172.16.2.5 |
- +-----------------+-----------------+-----------------+-----------------+
- | six.example.com | 2001:db8:1::/64 | 3001:1::50 | 3001:1::51 |
- +-----------------+-----------------+-----------------+-----------------+
- | example.com | 192.0.0.0/16 | 172.16.2.5 | 172.16.2.5 |
- +-----------------+-----------------+-----------------+-----------------+
+ +------------------+-----------------+-----------------+-----------------+
+ | Domain | Subnet | Forward DNS | Reverse DNS |
+ | | | Servers | Servers |
+ +==================+=================+=================+=================+
+ | four.example.com | 192.0.2.0/24 | 172.16.1.5, | 172.16.1.5, |
+ | | | 172.16.2.5 | 172.16.2.5 |
+ +------------------+-----------------+-----------------+-----------------+
+ | six.example.com | 2001:db8:1::/64 | 3001:1::50 | 3001:1::51 |
+ +------------------+-----------------+-----------------+-----------------+
+ | example.com | 192.0.0.0/16 | 172.16.2.5 | 172.16.2.5 |
+ +------------------+-----------------+-----------------+-----------------+
We need to construct three Forward DDNS Domains:
The following are the current limitations of the DHCP-DDNS Server.
- Requests received from the DHCP servers are placed in a queue until
- they are processed. Currently, all queued requests are lost when the
+ they are processed. Currently, all queued requests are lost if the
server shuts down.
number of reclaimed leases and decreasing the number of assigned
addresses or delegated prefixes.
-Please refer to `??? <#dhcp-ddns-server>`__ to see how to configure DNS
-updates in Kea, and to `??? <#hooks-libraries>`__ for information about
+Please refer to :ref:`dhcp-ddns-server` to see how to configure DNS
+updates in Kea, and to :ref:`hooks-libraries` for information about
using hooks libraries.
.. _lease-reclamation-defaults:
The following list presents all configuration parameters pertaining to
processing expired leases with their default values:
-- ``reclaim-timer-wait-time`` - This parameter governs intervals
- between completion of previous reclaimation cycle and a start of the
+- ``reclaim-timer-wait-time`` - this parameter governs intervals
+ between the completion of the previous reclaimation cycle and the start of the
next one. Specified in seconds. The default value is 10 [seconds].
-- ``flush-reclaimed-timer-wait-time`` - This parameter controls how
- often the server initiates lease reclaimation procedure. Expressed in
+- ``flush-reclaimed-timer-wait-time`` - this parameter controls how
+ often the server initiates the lease reclaimation procedure. Expressed in
seconds. The default value is 25 [seconds].
-- ``hold-reclaimed-time`` - This parameter governs how long the lease
- should be kept after it was reclaimed. This enables lease affinity
+- ``hold-reclaimed-time`` - this parameter governs how long the lease
+ should be kept after it is reclaimed. This enables lease affinity
when set to a non-zero value. Expressed in seconds. The default value
is 3600 [seconds].
-- ``max-reclaim-leases`` - This parameter specifies the maximum number
- of reclaimed leases that can be processed in one go. Zero means
+- ``max-reclaim-leases`` - this parameter specifies the maximum number
+ of reclaimed leases that can be processed at one time. Zero means
unlimited (i.e. process all reclaimed leases). The default value is
100.
-- ``max-reclaim-time`` - This parameter specifies an upper bound of how
- long a lease reclaimation procedure can take. Zero means no time
+- ``max-reclaim-time`` - this parameter specifies an upper limit to the
+ length of time a lease reclamation procedure can take. Zero means no time
limit. Expressed in milliseconds. The default value is 250
[milliseconds].
-- ``unwarned-reclaim-cycles`` - If lease reclaimation limits are
- specifed (``max-reclaim-leases`` and/oor ``max-reclaim-time``), then
+- ``unwarned-reclaim-cycles`` - if lease reclamation limits are
+ specified (``max-reclaim-leases`` and/or ``max-reclaim-time``), then
under certain circumstances the server may not be able to deal with
- leases to be reclaimed fast enough. This parameter specifies how many
- consecutive clean up cycles must end with remaining leases to be
+ the leases to be reclaimed fast enough. This parameter specifies how many
+ consecutive clean-up cycles must end with remaining leases to be
processed before a warning is printed. The default is 5 [cycles].
The parameters are explained in more detail in the rest of this chapter.
-The default value for any parameter is used when this parameter is not
-explicitly specified in the configuration. Also, the
-``expired-leases-processing`` map may be omitted entirely in the
-configuration, in which case the default values are used for all
+The default value for any parameter is used when the parameter is not
+explicitly specified in the configuration. If the
+``expired-leases-processing`` map is omitted entirely in the
+configuration, the default values are used for all
parameters listed above.
.. _lease-reclaim-config:
In deployments where response time is critical, administrators may wish
to minimize the interruptions in service caused by lease reclamation.
-Toward this end, Kea provides configuration parameters to control the
+To this end, Kea provides configuration parameters to control the
frequency of lease reclamation cycles, the maximum number of leases
processed in a single reclamation cycle, and the maximum amount of time
a single reclamation cycle is allowed to run before being interrupted.
According to the ``reclaim-timer-wait-time``, the 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
+the next cycle. This guarantees the presence of 5-second-long periods during
which the server remains responsive to DHCP queries and does not perform
lease reclamation. The ``max-reclaim-leases`` and ``max-reclaim-time``
are set to 0, which sets no restriction on the maximum number of leases
``max-reclaim-time``. This results in equal durations of all reclamation
cycles over time. Note that in this example the limitation of the
maximum 100 leases is not reached. This may be the case when database
-transactions are slow or callouts in the hook libraries attached to the
+transactions or callouts in the hook libraries attached to the
server are slow. Regardless, the chosen values for either the maximum
number of leases or a maximum cycle time strongly depend on the
particular deployment, the lease database backend being used, and any
reclaim them. This should not be a 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 a high
-rate for a longer period of time, the unreclaimed leases will pile up in
+rate for a long period of time, the unreclaimed leases will pile up in
the database. 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 is unable to reclaim all
When lease affinity is enabled (i.e. when ``hold-reclaimed-time`` is
configured to a value greater than zero), the server will still reclaim
-leases according to the parameters described in `Configuring Lease
-Reclamation <#lease-reclaim-config>`__, but the reclaimed leases will be
-held in the database (rather than removed) for a specified amount of
-time. When the client returns, the server will first verify whether
+leases according to the parameters described in :ref:`lease-reclaim-config`,
+but the reclaimed leases will be
+held in the database for a specified amount of
+time rather than removed. When the client returns, the server will first verify whether
there are any reclaimed leases associated with this client and will
re-assign them if possible. However, it is important to note that any
reclaimed lease may be assigned to another client if that client
specifically asks for it. Therefore, 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 (this mostly applies to
-DHCPv4 for which address space is small), there is an increased
+before; it merely increases the chances of the client being assigned
+the same lease. If the lease pool is small - namely, in
+DHCPv4, for which address space is small - there is an increased
likelihood that the expired lease will be assigned to another client.
Consider the following configuration:
the same client. In the example given above, reclaimed leases will be
held for 30 minutes (1800s) after their expiration. During this time,
the server will likely be able to re-assign the same lease to the
-returning client, unless another client requests this lease and the
+returning client, unless another client specifically requests this lease and the
server assigns it.
The server must periodically remove reclaimed leases for which the time
indicated by ``hold-reclaim-time`` has elapsed. The
``flush-reclaimed-timer-wait-time`` parameter controls how often the
server removes such leases. In the example provided above, the server
-will initiate removal of such leases 5 seconds after the previous
+will initiate removal of such leases five seconds after 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
+affinity, meaning 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 higher than
the ``reclaim-timer-wait-time``, as timely removal of expired-reclaimed
leases is less critical than the removal process, which may impact
server responsiveness.
-There is no guarantee that lease affinity will work every time. If a
+There is no guarantee that lease affinity will work every time; if a
server is running out of addresses, it will reassign expired addresses
to new clients. Also, clients can request specific addresses and the
-server will try to honor such a request if possible. If you want to
+server will try to honor such requests if possible. Administrators who want to
ensure a client keeps its address, even after periods of inactivity,
-consider using host reservations or leases with very long lifetimes.
+should consider using host reservations or leases with very long lifetimes.
.. _leases-reclamation-using-command:
======================================
The *leases-reclaim* command can be used to trigger lease reclamation at
-any time. Please consult the `??? <#command-leases-reclaim>`__ section
+any time. Please consult the :ref:`command-leases-reclaim` section
for details about using this command.
projects / thirdparty / kea.git / commitdiff
