(e.g. only VoIP phones allowed on a given link).</para>
<para>
- Note that it is possible to achieve similar effect as presented in this
+ Note that it is possible to achieve an effect similar to the one presented in this
section without the use of shared networks. If the subnets are placed in
the global subnets scope, rather than in the shared network, the server
will still use classification rules to pick the right subnet for a given
class of devices. The major benefit of placing subnets within the
shared network is that common parameters for the logically grouped
- subnets can be specified once, in the shared network scope, e.g.
+ subnets can be specified once, in the shared network scope, e.g. the
"interface" or "relay" parameter. All subnets belonging to this shared
network will inherit those parameters.
</para>
</section>
<section>
- <title>Host reservations in shared networks</title>
+ <title>Host Reservations in Shared Networks</title>
<para>
- Subnets being part of a shared network allow host reservations, similar to
+ Subnets that are part of a shared network allow host reservations, similar to
regular subnets:
<screen>
{
</screen>
</para>
<para>It is worth noting that Kea conducts additional checks when processing a
-packet if shared networks are defined. First, instead of simply checking if
-there's a reservation for a given client in his initially selected subnet, it
-goes through all subnets in a shared network looking for a reservation. This is
+packet if shared networks are defined. First, instead of simply checking whether
+there's a reservation for a given client in its initially selected subnet, it
+looks through all subnets in a shared network for a reservation. This is
one of the reasons why defining a shared network may impact performance. If
there is a reservation for a client in any subnet, that particular subnet will
be picked for the client. Although it's technically not an error, it is
<para>While not strictly mandatory, it is strongly recommended to use explicit
"id" values for subnets if you plan to use database storage for host
-reservations. If ID is not specified, the values for it be autogenerated,
-i.e. it will assign increasing integer values starting from 1. Thus, the
+reservations. If ID is not specified, the values for it are autogenerated,
+i.e. it assigns increasing integer values starting from 1. Thus, the
autogenerated IDs are not stable across configuration changes.
</para>
</section>
<section xml:id="dhcp6-serverid">
<title>Server Identifier in DHCPv6</title>
<para>The DHCPv6 protocol uses a "server identifier" (also known
- as a DUID) for clients to be able to discriminate between several
+ as a DUID) to allow clients to discriminate between several
servers present on the same link.
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc8415">RFC 8415</link>
- defines four DUID types: DUID-LLT, DUID-EN, DUID-LL and DUID-UUID.
- Future specifications may introduce new DUID types.</para>
+ currently defines four DUID types: DUID-LLT, DUID-EN, DUID-LL, and DUID-UUID.
+ </para>
<para>The Kea DHCPv6 server generates a server identifier once, upon
- the first startup, and stores it in a file. This identifier isn't
+ the first startup, and stores it in a file. This identifier is not
modified across restarts of the server and so is a stable identifier.</para>
- <para>Kea follows recommendation from
+ <para>Kea follows the recommendation from
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc8415">RFC 8415</link>
to use DUID-LLT as the default server identifier. However, we have
received reports that some deployments require different DUID
</para>
<para>Currently supported values for <command>type</command>
- parameter are: "LLT", "EN" and "LL", for DUID-LLT, DUID-EN and
+ parameter are: "LLT", "EN", and "LL", for DUID-LLT, DUID-EN, and
DUID-LL respectively.</para>
- <para>When a new DUID type is selected the server will generate its
- value and replace any existing DUID in the file. The server will then
- use the new server identifier in all future interactions with the
+ <para>When a new DUID type is selected the server generates its
+ value and replaces any existing DUID in the file. The server then
+ uses the new server identifier in all future interactions with the
clients.</para>
<note><para>If the new server identifier is created after some clients
- have obtained their leases, the clients using the old identifier will not
- be able to renew the leases: the server will ignore messages
+ have obtained their leases, the clients using the old identifier are not
+ able to renew the leases; the server will ignore messages
containing the old server identifier. Clients will continue sending
- Renew until they transition to the rebinding state. In this state they
- will start sending Rebind messages to multicast address without
+ Renew until they transition to the rebinding state. In this state, they
+ will start sending Rebind messages to the multicast address without
a server identifier. The server will respond to the Rebind messages
- with a new server identifier and the clients will associate the
+ with a new server identifier, and the clients will associate the
new server identifier with their leases. Although the clients will
be able to keep their leases and will eventually learn the new server
- identifier, this will be at the cost of increased number of renewals
- and multicast traffic due to a need to rebind. Therefore it is
+ identifier, this will be at the cost of an increased number of renewals
+ and multicast traffic due to a need to rebind. Therefore, it is
recommended that modification of the server identifier type
and value is avoided if the server has already assigned leases and these
leases are still valid.</para></note>
<itemizedlist>
<listitem><simpara><command>htype</command> is a 16-bit unsigned value
specifying hardware type,</simpara></listitem>
- <listitem><simpara><command>identifier</command> is a link layer
- address, specified as a string of hexadecimal digits,</simpara>
+ <listitem><simpara><command>identifier</command> is a link-layer
+ address, specified as a string of hexadecimal digits, and</simpara>
</listitem>
<listitem><simpara><command>time</command> is a 32-bit unsigned
time value.</simpara></listitem>
</screen>
</para>
- <para>It is allowed to use special value of 0 for "htype" and "time",
+ <para>A special value of 0 for "htype" and "time" is allowed,
which indicates that the server should use ANY value for these
components. If the server already uses a DUID-LLT it will use the
- values from this DUID. If the server uses a DUID of a different type
+ values from this DUID; if the server uses a DUID of a different type
or doesn't use any DUID yet, it will generate these values.
Similarly, if the "identifier" is assigned an empty string, the
value of the identifier will be generated. Omitting any of these
}
</screen>
- indicates that the server should use ANY link layer address and
- hardware type. If the server is already using DUID-LLT it will
- use the link layer address and hardware type from the existing DUID.
- If the server is not using any DUID yet, it will use link layer
+ indicates that the server should use ANY link-layer address and
+ hardware type. If the server is already using DUID-LLT, it will
+ use the link-layer address and hardware type from the existing DUID.
+ If the server is not using any DUID yet, it will use the link-layer
address and hardware type from one of the available network
- interfaces. The server will use an explicit value of time. If it
+ interfaces. The server will use an explicit value of time; if it
is different than a time value present in the currently used
- DUID, that value will be replaced, effectively causing
- modification of the current server identifier.
+ DUID, that value will be replaced, effectively
+ modifying the current server identifier.
</para>
<para>
where:
<itemizedlist>
<listitem><simpara><command>enterprise-id</command> is a 32-bit
- unsigned value holding enterprise number,</simpara></listitem>
- <listitem><simpara><command>identifier</command> is a variable
+ unsigned value holding an enterprise number, and </simpara></listitem>
+ <listitem><simpara><command>identifier</command> is a variable-
length identifier within DUID-EN.</simpara></listitem>
</itemizedlist>
</para>
</para>
<para>As in the case of the DUID-LLT, special values can be used for the
- configuration of the DUID-EN. If <command>enterprise-id</command> is 0, the server
+ configuration of the DUID-EN. If the <command>enterprise-id</command> is 0, the server
will use a value from the existing DUID-EN. If the server is not using
any DUID or the existing DUID has a different type, the ISC enterprise
- id will be used. When an empty string is used for <command>identifier</command>, the
+ id will be used. When an empty string is entered for <command>identifier</command>, the
identifier from the existing DUID-EN will be used. If the server is
- not using any DUID-EN the new 6-bytes long identifier will be generated.
+ not using any DUID-EN, a new 6-byte-long identifier will be generated.
</para>
- <para>DUID-LL is configured in the same way as DUID-LLT with an exception
+ <para>DUID-LL is configured in the same way as DUID-LLT except
that the <command>time</command> parameter has no effect for DUID-LL,
- because this DUID type only comprises a hardware type and link layer
+ because this DUID type only comprises a hardware type and link-layer
address. The following example demonstrates how to configure DUID-LL:
<screen>
<para>In some uncommon deployments where no stable storage is
available, the server should be configured not to try to
store the server identifier. This choice is controlled
- by the value of <command>persist</command> boolean parameter:
+ by the value of the <command>persist</command> boolean parameter:
<screen>
"Dhcp6": {
"server-id": {
</screen>
</para>
<para>The default value of the "persist" parameter is
- <command>true</command> which configures the server to store the
+ <command>true</command>, which configures the server to store the
server identifier on a disk.</para>
- <para>In the example above, the server is configured to not store
- the generated server identifier on a disk. But, if the server
- identifier is not modified in the configuration the same value
- will be used after server restart, because entire server
+ <para>In the example above, the server is configured not to store
+ the generated server identifier on a disk. But if the server
+ identifier is not modified in the configuration, the same value
+ will be used after server restart, because the entire server
identifier is explicitly specified in the configuration.</para>
</section>
<section xml:id="stateless-dhcp6">
<title>Stateless DHCPv6 (Information-Request Message)</title>
<para>Typically DHCPv6 is used to assign both addresses and options. These
- assignments (leases) have state that changes over time, hence
+ assignments (leases) have a state that changes over time, hence
their name, stateful. DHCPv6 also supports a stateless mode,
where clients request configuration options only. This mode is
- considered lightweight from the server perspective as it does not require
- any state tracking; hence its name.</para>
+ considered lightweight from the server perspective, as it does not require
+ any state tracking, and carries the stateless name.</para>
<para>The Kea server supports stateless mode. Clients can send
- Information-Request messages and the server will send back
+ Information-Request messages and the server sends back
answers with the requested options (providing the options are
- available in the server configuration). The server will attempt to
+ available in the server configuration). The server attempts to
use per-subnet options first. If that fails - for whatever reason - it
- will then try to provide options defined in the global scope.</para>
+ then tries to provide options defined in the global scope.</para>
<para>Stateless and stateful mode can be used together. No special
- configuration directives are required to handle this. Simply use the
+ configuration directives are required to handle this; simply use the
configuration for stateful clients and the stateless clients will get
- just options they requested.</para>
+ just the options they requested.</para>
<para>This usage of global options allows for an interesting case.
- It is possible to run a server that provides just options and no
+ It is possible to run a server that provides only options and no
addresses or prefixes. If the options have the same value in each
subnet, the configuration can define required options in the global
scope and skip subnet definitions altogether. Here's a simple example of
</screen>
This very simple configuration will provide DNS server information
to all clients in the network, regardless of their location. Note the
- specification of the memfile lease database: this is needed as
+ specification of the memfile lease database; this is needed as
Kea requires a lease database to be specified
even if it is not used.</para>
</section>
<section xml:id="dhcp6-rfc7550">
- <title>Support for RFC 7550 (being now part of RFC 8415)</title>
- <para>The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7550">RFC 7550</link>
+ <title>Support for RFC 7550 (now part of RFC 8415)</title>
+ <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7550">RFC 7550</link>
introduced some changes to the previous DHCPv6 specifications,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc3315">RFC 3315</link>
and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc3633">RFC 3633</link>,
allocated addresses and the IA_PD(s) containing the NoPrefixAvail status code.
According to the updated specifications, if the client can operate without
prefixes it should accept allocated addresses and transition to
- the 'bound' state. When the client subsequently sends Renew/Rebind messages
+ the "bound" state. When the client subsequently sends Renew/Rebind messages
to the server, according to the T1 and T2 times, to extend the lifetimes of
- the allocated addresses, if the client is still interested in obtaining
+ the allocated addresses, and if the client is still interested in obtaining
prefixes from the server, it may also include an IA_PD in the Renew/Rebind
to request allocation of the prefixes. If the server still cannot
- allocate the prefixes it will respond with the IA_PD(s) containing
+ allocate the prefixes, it will respond with the IA_PD(s) containing the
NoPrefixAvail status code. However, if the server can allocate the
prefixes it will allocate and send them in the IA_PD(s) to the client.
- Similar situation occurs when the server is unable to allocate addresses
+ A similar situation occurs when the server is unable to allocate addresses
for the client but can delegate prefixes. The client may request allocation
of the addresses while renewing the delegated prefixes. Allocating leases for
other IA types while renewing existing leases is by default supported by
to disable this behavior.</para>
<para>
- The following are the other behaviors first introduced in the
+ The following are the other behaviors first introduced in
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7550">RFC 7550</link>
- (now being part of the
+ (now part of
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc8415">RFC 8415</link>)
and supported by the Kea DHCPv6 server:
<itemizedlist>
<listitem><simpara>Set T1/T2 timers to the same value for all
stateful (IA_NA and IA_PD) options to facilitate renewal of all
- client's leases at the same time (in a single message exchange),
+ a client's leases at the same time (in a single message exchange),
</simpara></listitem>
- <listitem><simpara>NoAddrsAvail and NoPrefixAvail status codes
- are placed in the IA_NA and IA_PD options in the Advertise message,
- rather than as the top level options.</simpara></listitem>
+ <listitem><simpara>Place NoAddrsAvail and NoPrefixAvail status codes
+ in the IA_NA and IA_PD options in the Advertise message,
+ rather than as the top-level options.</simpara></listitem>
</itemizedlist>
</para>
</section>
<section xml:id="dhcp6-relay-override">
- <title>Using Specific Relay Agent for a Subnet</title>
+ <title>Using a Specific Relay Agent for a Subnet</title>
<para>
- The relay has to have an interface connected to the link on which
+ The relay must have an interface connected to the link on which
the clients are being configured. Typically the relay has a global IPv6
address configured on the interface that belongs to the subnet from which
- the server will assign addresses. In the typical case, the
+ the server will assign addresses. Normally, the
server is able to use the IPv6 address inserted by the relay (in the link-addr
field in RELAY-FORW message) to select the appropriate subnet.
</para>
However, that is not always the case. The relay
address may not match the subnet in certain deployments. This
usually means that there is more than one subnet allocated for a given
- link. The two most common examples where this is the case are long lasting
+ link. The two most common examples where this is the case are long-lasting
network renumbering (where both old and new address space is still being
- used) and a cable network. In a cable network both cable modems and the
+ used) and a cable network. In a cable network, both cable modems and the
devices behind them are physically connected to the same link, yet
- they use distinct addressing. In such case, the DHCPv6 server needs
- additional information (like the value of interface-id option or IPv6
- address inserted in the link-addr field in RELAY-FORW message) to
+ they use distinct addressing. In such a case, the DHCPv6 server needs
+ additional information (like the value of the interface-id option or the IPv6
+ address inserted in the link-addr field in the RELAY-FORW message) to
properly select an appropriate subnet.
</para>
<para>
The following example assumes that there is a subnet 2001:db8:1::/64
that is accessible via a relay that uses 3000::1 as its IPv6 address.
- The server will be able to select this subnet for any incoming packets
- that came from a relay with an address in 2001:db8:1::/64 subnet.
- It will also select that subnet for a relay with address 3000::1.
+ The server is able to select this subnet for any incoming packets
+ that come from a relay with an address in 2001:db8:1::/64 subnet.
+ It also selects that subnet for a relay with address 3000::1.
<screen>
"Dhcp6": {
"subnet6": [
<note>
<para>
- As of Kea 1.4, the "ip-address" parameter in "relay" has been deprecated
- in favor of "ip-addresses" which supports specifying a list of addresses.
- Configuration parsing, will honor the singular form for now but users are
- encouraged to migrate.
+ The current version of Kea uses the "ip-addresses" parameter, which supports specifying a list of addresses.
</para>
</note>
<title>Segregating IPv6 Clients in a Cable Network</title>
<para>
In certain cases, it is useful to mix relay address information,
- introduced in <xref linkend="dhcp6-relay-override"/> with client
+ introduced in <xref linkend="dhcp6-relay-override"/>, with client
classification, explained in <xref linkend="classify"/>.
- One specific example is a cable network, where typically modems
+ One specific example is in a cable network, where typically modems
get addresses from a different subnet than all devices connected
behind them.
</para>
<para>
- Let's assume that there is one CMTS (Cable Modem Termination System)
+ Let us assume that there is one CMTS (Cable Modem Termination System)
with one CM MAC (a physical link that modems are connected to).
We want the modems to get addresses from the 3000::/64 subnet,
- while everything connected behind modems should get addresses from
+ while everything connected behind the modems should get addresses from
another subnet (2001:db8:1::/64). The CMTS that acts as a relay
- an uses address 3000::1. The following configuration can serve
+ uses address 3000::1. The following configuration can serve
that configuration:
<screen>
"Dhcp6": {
<section xml:id="mac-in-dhcpv6">
<title>MAC/Hardware Addresses in DHCPv6</title>
<para>MAC/hardware addresses are available in DHCPv4 messages
- from the clients and administrators
- frequently use that information to perform certain tasks, like per host
- configuration, address reservation for specific MAC addresses and other.
+ from the clients, and administrators
+ frequently use that information to perform certain tasks like per-host
+ configuration and address reservation for specific MAC addresses.
Unfortunately, the DHCPv6 protocol does not provide any completely reliable way
- to retrieve that information. To mitigate that issue a number of mechanisms
- have been implemented in Kea that attempt to gather it. Each
- of those mechanisms works in certain cases, but may fail in other cases.
- Whether the mechanism works or not in the particular deployment is
+ to retrieve that information. To mitigate that issue, a number of mechanisms
+ have been implemented in Kea. Each
+ of these mechanisms works in certain cases, but may fail in others.
+ Whether the mechanism works in a particular deployment is
somewhat dependent on the network topology and the technologies used.</para>
- <para>Kea allows configuration of which of the supported methods should be
+ <para>Kea allows specification of which of the supported methods should be
used and in what order. This configuration may be considered a fine tuning
of the DHCP deployment. In a typical deployment the default
value of <command>"any"</command> is sufficient and there is no
need to select specific methods. Changing the value of this parameter
is the most useful in cases when an administrator wants to disable
- certain method, e.g. if the administrator trusts the network infrastructure
- more than the information provided by the clients themselves, the
- administrator may prefer information provided by the relays over that
+ certain methods; for example, if the administrator trusts the network infrastructure
+ more than the information provided by the clients themselves, they
+ may prefer information provided by the relays over that
provided by the clients.
</para>
<para>
</screen>
When not specified, a special value of "any" is used, which
- instructs the server to attempt to use all the methods in sequence and use
+ instructs the server to attempt to try all the methods in sequence and use the
value returned by the first one that succeeds. If specified, it
- has to have at least one value.</para>
+ must have at least one value.</para>
<para>Supported methods are:
<itemizedlist>
</listitem>
<listitem>
<simpara><command>duid</command> - DHCPv6 uses DUID identifiers instead of
- MAC addresses. There are currently four DUID types defined, with two of them
- (DUID-LLT, which is the default one and DUID-LL) convey MAC address information.
+ MAC addresses. There are currently four DUID types defined, and two of them
+ (DUID-LLT, which is the default, and DUID-LL) convey MAC address information.
Although <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="" utl="http://tools.ietf.org/html/rfc8415">RFC 8415</link> forbids
it, it is possible to parse those DUIDs and extract
necessary information from them. This method is not completely reliable, as
<simpara><command>ipv6-link-local</command> - Another possible acquisition
method comes from the source IPv6 address. In typical usage, clients are
sending their packets from IPv6 link-local addresses. There is a good chance
- that those addresses are based on EUI-64, which contains MAC address. This
+ that those addresses are based on EUI-64, which contains a MAC address. This
method is not completely reliable, as clients may use other link-local address
- types. In particular, privacy extensions, defined in
+ types. In particular, privacy extensions, defined in
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc4941">RFC 4941</link>, do not use
- MAC addresses. Also note that successful extraction requires that the
+ MAC addresses. Also note that successful extraction requires that the
address's u-bit must be set to 1 and its g-bit set to 0, indicating that it
is an interface identifier as per
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2373#section-2.5.1">
</listitem>
<listitem>
<simpara><command>client-link-addr-option</command> - One extension defined
- to alleviate missing MAC issues is client link-layer address option, defined
+ to alleviate missing MAC issues is the client link-layer address option, defined
in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc6939">RFC 6939</link>. This is
- an option that is inserted by a relay and contains information about client's
+ an option that is inserted by a relay and contains information about a client's
MAC address. This method requires a relay agent that supports the option and
is configured to insert it. This method is useless for directly connected
clients. This parameter can also be specified as <command>rfc6939</command>,
<simpara><command>subscriber-id</command> - Another option
that is somewhat similar to the previous one is subscriber-id,
defined in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc4580">RFC
- 4580</link>. It is, too, inserted by a relay agent that is
+ 4580</link>. It, too, is inserted by a relay agent that is
configured to insert it. This parameter can also be specified
as <command>rfc4580</command>, which is an alias for
<command>subscriber-id</command>. This method is currently not
<simpara><command>docsis-cmts</command> - Yet another possible source of MAC
address information are the DOCSIS options inserted by a CMTS that acts
as a DHCPv6 relay agent in cable networks. This method attempts to extract
- MAC address information from suboption 1026 (cm mac) of the vendor specific option
+ MAC address information from suboption 1026 (cm mac) of the vendor-specific option
with vendor-id=4491. This vendor option is extracted from the relay-forward message,
not the original client's message.
</simpara>
</listitem>
<listitem>
- <simpara><command>docsis-modem</command> - Yet another possible source of MAC
+ <simpara><command>docsis-modem</command> - The final possible source of MAC
address information are the DOCSIS options inserted by the cable modem itself.
This method attempts to extract MAC address information from suboption 36 (device id)
- of the vendor specific option with vendor-id=4491. This vendor option is extracted from
+ of the vendor-specific option with vendor-id=4491. This vendor option is extracted from
the original client's message, not from any relay options.
</simpara>
</listitem>
</para>
<para>Empty mac-sources is not allowed. If you do not want to specify it,
- either simply omit mac-sources definition or specify it with the "any" value
+ either simply omit the mac-sources definition or specify it with the "any" value
which is the default.</para>
</section>
<title>Duplicate Addresses (DECLINE Support)</title>
<para>The DHCPv6 server is configured with a certain pool of
- addresses that it is expected to hand out to the DHCPv6 clients.
+ addresses that it is expected to hand out to DHCPv6 clients.
It is assumed that the server is authoritative and has complete
- jurisdiction over those addresses. However, due to various
+ jurisdiction over those addresses. However, for various
reasons, such as misconfiguration or a faulty client implementation
that retains its address beyond the valid lifetime, there may be
devices connected that use those addresses without the server's
<para>Such an unwelcome event can be detected
by legitimate clients (using Duplicate Address Detection) and
- reported to the DHCPv6 server using a DECLINE message. The server
- will do a sanity check (if the client declining an address really
- was supposed to use it), then will conduct a clean up operation
+ reported to the DHCPv6 server using a DHCPDECLINE message. The server
+ will do a sanity check (to see whether the client declining an address really
+ was supposed to use it), and then will conduct a clean-up operation
and confirm it by sending back a REPLY message. Any DNS entries
- related to that address will be removed, the fact will be logged
- and hooks will be triggered. After that is done, the address
+ related to that address will be removed, the fact will be logged,
+ and hooks will be triggered. After that is complete, the address
will be marked as declined (which indicates that it is used by
- an unknown entity and thus not available for assignment to
- anyone) and a probation time will be set on it. Unless otherwise
- configured, the probation period lasts 24 hours. After that
+ an unknown entity and thus not available for assignment)
+ and a probation time will be set on it. Unless otherwise
+ configured, the probation period lasts 24 hours; after that
period, the server will recover the lease (i.e. put it back into
the available state) and the address will be available for assignment
again. It should be noted that if the underlying issue of a
- misconfigured device is not resolved, the duplicate address
- scenario will repeat. On the other hand, it provides an
+ misconfigured device is not resolved, the duplicate-address
+ scenario will repeat. If reconfigured correctly, this mechanism provides an
opportunity to recover from such an event automatically, without
any sysadmin intervention.</para>
}
</screen>
The parameter is expressed in seconds, so the example above will instruct
- the server to recycle declined leases after an hour.</para>
+ the server to recycle declined leases after one hour.</para>
<para>There are several statistics and hook points associated with the
Decline handling procedure. The lease6_decline hook is triggered after the
- incoming Decline message has been sanitized and the server is about to decline
+ incoming DHCPDECLINE message has been sanitized and the server is about to decline
the lease. The declined-addresses statistic is increased after the
- hook returns (both global and subnet specific variants). (See
- <xref linkend="dhcp4-stats"/> and <xref linkend="hooks-libraries"/> for more details
- on DHCPv4 statistics and Kea hook points.)</para>
+ hook returns (both global and subnet-specific variants). (See
+ <xref linkend="dhcp6-stats"/> and <xref linkend="hooks-libraries"/> for more details
+ on DHCPv6 statistics and Kea hook points.)</para>
<para>Once the probation time elapses, the declined lease is recovered
- using the standard expired lease reclamation procedure, with several
+ using the standard expired-lease reclamation procedure, with several
additional steps. In particular, both declined-addresses statistics
- (global and subnet specific) are decreased. At the same time,
+ (global and subnet-specific) are decreased. At the same time,
reclaimed-declined-addresses statistics (again in two variants, global and
- subnet specific) are increased.</para>
+ subnet-specific) are increased.</para>
- <para>Note about statistics: The server does not decrease the
- assigned-addresses statistics when a DECLINE message is received and
+ <para>A note about statistics: The server does not decrease the
+ assigned-addresses statistics when a DHCPDECLINE message is received and
processed successfully. While technically a declined address is no longer
assigned, the primary usage of the assigned-addresses statistic is to
monitor pool utilization. Most people would forget to include
- declined-addresses in the calculation, and simply do
- assigned-addresses/total-addresses. This would have a bias towards
+ declined-addresses in the calculation, and simply use
+ assigned-addresses/total-addresses. This would cause a bias towards
under-representing pool utilization. As this has a potential for major
- issues, we decided not to decrease assigned addresses immediately after
- receiving Decline, but to do it later when we recover the address back to
+ issues, we decided not to decrease assigned-addresses immediately after
+ receiving DHCPDECLINE, but to do it later when Kea recovers the address back to
the available pool.</para>
</section>
<entry>pkt6-received</entry>
<entry>integer</entry>
<entry>Number of DHCPv6 packets received. This includes all packets:
- valid, bogus, corrupted, rejected etc. This statistic is expected
+ valid, bogus, corrupted, rejected, etc. This statistic is expected
to grow rapidly.</entry>
</row>
<entry>integer</entry>
<entry>Number of incoming packets that were dropped. The exact reason
for dropping packets is logged, but the most common reasons may
- be: an unacceptable or not supported packet type, direct responses
+ be: an unacceptable or not supported packet type is received, direct responses
are forbidden, the server-id sent by the client does not match the
- server's server-id or the packet is malformed.</entry>
+ server's server-id, or the packet is malformed.</entry>
</row>
<row>
<entry>Number of incoming packets that could not be parsed.
A non-zero value of this statistic indicates that the server
received a malformed or truncated packet. This may indicate problems
- in your network, faulty clients, faulty relay agents or a bug in the
+ in your network, faulty clients, faulty relay agents, or a bug in the
server.</entry>
</row>
<entry>integer</entry>
<entry>
Number of SOLICIT packets received. This statistic is expected
- to grow. Its increase means that clients that just booted
+ to grow; its increase means that clients that just booted
started their configuration process and their initial packets
- reached your server.
+ reached your Kea server.
</entry>
</row>
by the server and the server is never expected to receive them. A non-zero
value of this statistic indicates an error occurring in the network.
One likely cause would be a misbehaving relay agent that incorrectly
- forwards ADVERTISE messages towards the server rather back to the
+ forwards ADVERTISE messages towards the server, rather than back to the
clients.
</entry>
</row>
<row>
<entry>pkt6-request-received</entry>
<entry>integer</entry>
- <entry>Number of REQUEST packets received. This statistic
+ <entry>Number of DHCPREQUEST packets received. This statistic
is expected to grow. Its increase means that clients that just booted
- received the server's response (ADVERTISE), accepted it and are now
- requesting an address (REQUEST).
+ received the server's response (DHCPADVERTISE) and accepted it, and are now
+ requesting an address (DHCPREQUEST).
</entry>
</row>
the server and the server is never expected to receive
them. A non-zero value indicates an error. One likely cause would be
a misbehaving relay agent that incorrectly forwards REPLY messages
- towards the server, rather back to the clients.
+ towards the server, rather than back to the clients.
</entry>
</row>
<entry>pkt6-renew-received</entry>
<entry>integer</entry>
<entry>Number of RENEW packets received. This statistic
- is expected to grow. Its increase means that clients received their
+ is expected to grow; its increase means that clients received their
addresses and prefixes and are trying to renew them.
</entry>
</row>
<entry>integer</entry>
<entry>Number of REBIND packets received. A non-zero value
indicates that clients didn't receive responses to their RENEW messages
- (regular lease renewal mechanism) and are attempting to find any server
- that is able to take over their leases. It may mean that some server's
+ (through the regular lease-renewal mechanism) and are attempting to find any server
+ that is able to take over their leases. It may mean that some servers'
REPLY messages never reached the clients.
</entry>
</row>
<entry>pkt6-release-received</entry>
<entry>integer</entry>
<entry>Number of RELEASE packets received. This statistic is expected
- to grow when a device is being shut down in the network. It
+ to grow when a device is being shut down in the network; it
indicates that the address or prefix assigned is reported as no longer
needed. Note that many devices, especially wireless, do not send RELEASE
packets either because of design choice or due to the client moving out
Number of DHCPv4-QUERY packets received. This
statistic is expected to grow if there are devices
that are using DHCPv4-over-DHCPv6. DHCPv4-QUERY
- messages are used by DHCPv4 clients on an IPv6 only
+ messages are used by DHCPv4 clients on an IPv6-only
line which encapsulates the requests over DHCPv6.
</entry>
</row>
statistic is expected to remain zero at all times, as
DHCPv4-RESPONSE packets are sent by the server and the
server is never expected to receive them. A non-zero
- value indicates an error. One likely cause would be a
+ value indicates an error. One likely cause would be a
misbehaving relay agent that incorrectly forwards
- DHCPv4-RESPONSE message towards the server rather
+ DHCPv4-RESPONSE message towards the server rather than
back to the clients.
</entry>
</row>
<entry>integer</entry>
<entry>Number of packets received of an unknown type. A non-zero
value of this statistic indicates that the server received a
- packet that it wasn't able to recognize: either it had an unsupported
+ packet that it wasn't able to recognize; either it had an unsupported
type or was possibly malformed.</entry>
</row>
to grow every time the server transmits a packet. In general, it
should roughly match pkt6-received, as most incoming packets cause
the server to respond. There are exceptions (e.g. server receiving a
- REQUEST with server-id matching other server), so do not worry, if
- it is lesser than pkt6-received.</entry>
+ REQUEST with server-id matching other server), so do not worry if
+ it is less than pkt6-received.</entry>
</row>
<row>
<entry>integer</entry>
<entry>Number of ADVERTISE packets sent. This statistic is
expected to grow in most cases after a SOLICIT is processed. There
- are certain uncommon, but valid cases where incoming SOLICIT is
+ are certain uncommon, but valid, cases where incoming SOLICIT packets are
dropped, but in general this statistic is expected to be close to
pkt6-solicit-received.</entry>
</row>
<entry>integer</entry>
<entry>Number of REPLY packets sent. This statistic is expected to
grow in most cases after a SOLICIT (with rapid-commit), REQUEST,
- RENEW, REBIND, RELEASE, DECLINE or INFORMATION-REQUEST is
+ RENEW, REBIND, RELEASE, DECLINE, or INFORMATION-REQUEST is
processed. There are certain cases where there is no response.
</entry>
</row>
<entry>subnet[id].total-nas</entry>
<entry>integer</entry>
<entry>
- This statistic shows the total number of NA addresses available for
- DHCPv6 management for a given subnet. In other words, this is the sum
+ Total number of NA addresses available for
+ DHCPv6 management for a given subnet; in other words, this is the sum
of all addresses in all configured pools. This statistic changes only
during configuration changes. Note that it does not take into account any
addresses that may be reserved due to host reservation. The
<emphasis>id</emphasis> is the subnet-id of a given subnet. This
- statistic is exposed for each subnet separately and is
+ statistic is exposed for each subnet separately, and is
reset during a reconfiguration event.
</entry>
</row>
<entry>subnet[id].assigned-nas</entry>
<entry>integer</entry>
<entry>
- This statistic shows the number of NA addresses in a given subnet that
- are assigned. This statistic increases every time a new lease is allocated
+ Number of NA addresses in a given subnet that
+ are assigned. It increases every time a new lease is allocated
(as a result of receiving a REQUEST message) and is decreased every time a
lease is released (a RELEASE message is received) or expires. The
<emphasis>id</emphasis> is the subnet-id of a given subnet. This
- statistic is exposed for each subnet separately and is
+ statistic is exposed for each subnet separately, and is
reset during a reconfiguration event.
</entry>
</row>
<entry>subnet[id].total-pds</entry>
<entry>integer</entry>
<entry>
- This statistic shows the total number of PD prefixes available for
- DHCPv6 management for a given subnet. In other words, this is the sum
+ Total number of PD prefixes available for
+ DHCPv6 management for a given subnet; in other words, this is the sum
of all prefixes in all configured pools. This statistic changes only
during configuration changes. Note it does not take into account any
prefixes that may be reserved due to host reservation. The
<emphasis>id</emphasis> is the subnet-id of a given subnet. This
- statistic is exposed for each subnet separately and is
+ statistic is exposed for each subnet separately, and is
reset during a reconfiguration event.
</entry>
</row>
<entry>subnet[id].assigned-pds</entry>
<entry>integer</entry>
<entry>
- This statistic shows the number of PD prefixes in a given subnet that
- are assigned. This statistic increases every time a new lease is allocated
+ Number of PD prefixes in a given subnet that
+ are assigned. It increases every time a new lease is allocated
(as a result of receiving a REQUEST message) and is decreased every time a
lease is released (a RELEASE message is received) or expires. The
<emphasis>id</emphasis> is the subnet-id of a given subnet. This statistic
- is exposed for each subnet separately and is reset during a
+ is exposed for each subnet separately, and is reset during a
reconfiguration event.
</entry>
</row>
<row>
<entry>reclaimed-leases</entry>
<entry>integer</entry>
- <entry> This statistic is the number of expired leases that have been
+ <entry> Number of expired leases that have been
reclaimed since server startup. It is incremented each time an expired
- lease is reclaimed (it counts both NA and PD reclamations) and is reset
+ lease is reclaimed (counting both NA and PD reclamations) and is reset
when the server is reconfigured.
</entry>
</row>
<row>
<entry>subnet[id].reclaimed-leases</entry>
<entry>integer</entry>
- <entry>This statistic is the number of expired leases associated with
+ <entry>Number of expired leases associated with
a given subnet (<emphasis>"id"</emphasis> is the subnet-id) that have
been reclaimed since server startup. It is incremented each time an expired
- lease is reclaimed (it counts both NA and PD reclamations) and is reset
+ lease is reclaimed (counting both NA and PD reclamations) and is reset
when the server is reconfigured.
</entry>
</row>
<entry>declined-addresses</entry>
<entry>integer</entry>
<entry>
- This statistic shows the number of IPv6 addresses that are
- currently declined and so counts the number of leases
+ Number of IPv6 addresses that are
+ currently declined; a count of the number of leases
currently unavailable. Once a lease is recovered, this
- statistic will be decreased. Ideally, this statistic should be
- zero. If this statistic is non-zero (or worse, increasing),
- the network administrator should investigate if there is
+ statistic will be decreased; ideally, this statistic should be
+ zero. If this statistic is non-zero or increasing,
+ a network administrator should investigate whether there is
a misbehaving device in the network. This is a global statistic
that covers all subnets.
</entry>
<entry>subnet[id].declined-addresses</entry>
<entry>integer</entry>
<entry>
- This statistic shows the number of IPv6 addresses that are
- currently declined in a given subnet. This statistic counts the
+ Number of IPv6 addresses that are
+ currently declined in a given subnet; a count of the
number of leases currently unavailable. Once a lease is
- recovered, this statistic will be decreased. Ideally, this
+ recovered, this statistic will be decreased; ideally, this
statistic should be zero. If this statistic is
- non-zero (or worse, increasing), a network administrator should
- investigate if there is a misbehaving device in the network. The
+ non-zero or increasing, a network administrator should
+ investigate whether there is a misbehaving device in the network. The
<emphasis>id</emphasis> is the subnet-id of a given subnet. This
statistic is exposed for each subnet separately.
</entry>
<entry>reclaimed-declined-addresses</entry>
<entry>integer</entry>
<entry>
- This statistic shows the number of IPv6 addresses that were
+ Number of IPv6 addresses that were
declined, but have now been recovered. Unlike
declined-addresses, this statistic never decreases. It can be used
- as a long term indicator of how many actual valid Declines were
+ as a long-term indicator of how many actual valid Declines were
processed and recovered from. This is a global statistic that
covers all subnets.
</entry>
<entry>subnet[id].reclaimed-declined-addresses</entry>
<entry>integer</entry>
<entry>
- This statistic shows the number of IPv6 addresses that were
+ Number of IPv6 addresses that were
declined, but have now been recovered. Unlike
declined-addresses, this statistic never decreases. It can be used
- as a long term indicator of how many actual valid Declines were
+ as a long-term indicator of how many actual valid Declines were
processed and recovered from. The
<emphasis>id</emphasis> is the subnet-id of a given subnet. This
statistic is exposed for each subnet separately.
<title>Management API for the DHCPv6 Server</title>
<para>
The management API allows the issuing of specific
- management commands, such as statistics retrieval, reconfiguration or shutdown.
- For more details, see <xref linkend="ctrl-channel"/>. Currently the only
+ management commands, such as statistics retrieval, reconfiguration, or shutdown.
+ For more details, see <xref linkend="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
+ are no sockets open; to instruct Kea to open a socket, the following entry
in the configuration file can be used:
<screen>
"Dhcp6": {
<para>
The length of the path specified by the <command>socket-name</command>
- parameter is restricted by the maximum length for the unix socket name
+ parameter is restricted by the maximum length for the UNIX socket name
on your operating system, i.e. the size of the <command>sun_path</command>
field in the <command>sockaddr_un</command> structure, decreased by 1.
This value varies on different operating systems between 91 and 107
</para>
<para>
- 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 <uri
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen/d2/d96/ctrlSocket.html">Control Channel section in the Kea Developer's Guide</uri> for more
+ details.
</para>
<para>The DHCPv6 server supports the following operational commands:
<listitem>shutdown</listitem>
<listitem>version-get</listitem>
</itemizedlist>
- as described in <xref linkend="commands-common"/>. In addition,
- it supports the following statistics related commands:
+ as described in <xref linkend="commands-common"/>. In addition,
+ it supports the following statistics-related commands:
<itemizedlist>
<listitem>statistic-get</listitem>
<listitem>statistic-reset</listitem>
<listitem>statistic-reset-all</listitem>
<listitem>statistic-remove-all</listitem>
</itemizedlist>
- as described here <xref linkend="command-stats"/>.
+ as described in <xref linkend="command-stats"/>.
</para>
</section>
<section id="dhcp6-user-contexts">
- <title>User contexts in IPv6</title>
+ <title>User Contexts in IPv6</title>
<para>
Kea allows loading hook libraries that sometimes could benefit from
additional parameters. If such a parameter is specific to the whole
</para>
<para>
- User contexts can store arbitrary data as long as it is valid JSON
+ 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
- enclosed in curly brackets). Some hook libraries may expect specific
- formatting, though. Please consult specific hook library
+ enclosed in curly brackets). However, some hook libraries may expect specific
+ formatting; please consult the specific hook library
documentation for details.
</para>
<para>
User contexts can be specified at either global scope,
- shared network, subnet, pool, client class, option data or
+ shared network, subnet, pool, client class, option data, or
definition level, and host reservation. One other useful
usage is the ability to store comments or descriptions.
</para>
<para>
Let's consider a lightweight 4over6 deployment as an example. It is an
- IPv6 transition technology that allows mapping IPv6 prefix into full
- or parts of IPv4 addresses. In DHCP context, these are certain
- parameters that are supposed to be delivered to clients in form of
- additional options. Values of those options are correlated to
- delegated prefixes, so it is reasonable to keep those parameters
+ IPv6 transition technology that allows mapping IPv6 prefixes into full
+ or partial IPv4 addresses. In the DHCP context, these are specific
+ parameters that are supposed to be delivered to clients in the form of
+ additional options. Values of these options are correlated to
+ delegated prefixes, so it is reasonable to keep these parameters
together with the PD pool. On the other hand, lightweight 4over6 is
not a commonly used feature, so it is not a part of the base Kea
code. The solution to this problem is to use user context. For each PD
- pool that is expected to be used for lightweight 4over6, user context
+ pool that is expected to be used for lightweight 4over6, a user context
with extra parameters is defined. Those extra parameters will be used
- by hook library that would be loaded only when dynamic calculation of
+ by a hook library that would be loaded only when dynamic calculation of
the lightweight 4over6 option is actually needed. An example
configuration looks as follows:
<screen>
</para>
<para>
- Kea does not interpret or use the content of the user context:
- it just stores it, making it available to the hook
+ Kea does not interpret or use the content of the user context;
+ it simply stores it, making it available to the hook
libraries. It is up to each hook library to extract the information
- and make use of it.
- The parser translates a "comment" entry into a user-context
- with the entry, this allows to attach a comment inside the
+ and use it.
+ The parser translates a "comment" entry into a user context
+ with the entry, which allows a comment to be attached inside the
configuration itself.
</para>
<para>
<simpara><emphasis>DHCPv6 Options for Configuration of Softwire
Address and Port-Mapped Clients</emphasis>,
<ulink url="http://tools.ietf.org/html/rfc7598">RFC
- 7598</ulink>: All options specified in this specification are
+ 7598</ulink>: All options indicated in this specification are
supported by the DHCPv6 server.</simpara>
</listitem>
<listitem>
<simpara><emphasis>Dynamic Host Configuration Protocol for IPv6 (DHCPv6)</emphasis>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc8415">RFC 8415</link>:
New DHCPv6 protocol specification which obsoletes RFC 3315, RFC 3633, RFC 3736, RFC 4242, RFC 7083,
- RFC 7283 and RFC 7550</simpara>
+ RFC 7283, and RFC 7550</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="dhcp6-limit">
<title>DHCPv6 Server Limitations</title>
<para> These are the current limitations of the DHCPv6 server
- software. Most of them are reflections of the early stage of
+ software. Most of them are reflections of the current stage of
development and should be treated as <quote>not implemented
yet</quote>, rather than actual limitations.</para>
<itemizedlist>
<listitem>
<simpara>
- The server will allocate, renew or rebind a maximum of one lease
+ The server will allocate, renew, or rebind a maximum of one lease
for a particular IA option (IA_NA or IA_PD) sent by a client.
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc8415">RFC 8415</link>
allows for multiple addresses or prefixes to be allocated for a single IA.
<title>Kea DHCPv6 server examples</title>
<para>
- A collection of simple to use examples for DHCPv6 component of Kea is
- available with the sources. It is located in doc/examples/kea6
- directory. At the time of writing this text there were 18 examples,
- but the number is growing slowly with each release.
+ A collection of simple-to-use examples for the DHCPv6 component of Kea is
+ available with the source files, located in the doc/examples/kea6
+ directory.
</para>
</section>
projects / thirdparty / kea.git / commitdiff
