</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
+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, Kea
-goes through all subnets in a shared network looking for a reservation. This is
+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
<section xml:id="dhcp4-subnet-selection">
<title>How the DHCPv4 Server Selects a Subnet for the Client</title>
<para>
- The DHCPv4 server differentiates between the directly connected clients,
+ The DHCPv4 server differentiates between directly connected clients,
clients trying to renew leases, and clients sending their messages through
relays. For directly connected clients, the server will check the
configuration for the interface on which the message has been received and,
<para>
The following example assumes that there is a subnet 192.0.2.0/24
that is accessible via a relay that uses 10.0.0.1 as its IPv4 address.
- The server will be able to select this subnet for any incoming packets
- that came from a relay that has an address in the 192.0.2.0/24 subnet.
- It will also select that subnet for a relay with address 10.0.0.1.
+ The server is able to select this subnet for any incoming packets
+ that come from a relay that has an address in the 192.0.2.0/24 subnet.
+ It also selects that subnet for a relay with address 10.0.0.1.
<screen>
"Dhcp4": {
"subnet4": [
<title>Segregating IPv4 Clients in a Cable Network</title>
<para>
In certain cases, it is useful to mix relay address information,
- introduced in <xref linkend="dhcp4-relay-override"/> with client
+ introduced in <xref linkend="dhcp4-relay-override"/>, with client
classification, explained in <xref linkend="classify"/>.
One specific example is in a cable network, where typically modems
get addresses from a different subnet than all the devices connected
<title>Duplicate Addresses (DHCPDECLINE Support)</title>
<para>The DHCPv4 server is configured with a certain pool of addresses
- that it is expected to hand out to the DHCPv4 clients. It is
+ that it is expected to hand out to DHCPv4 clients. It is
assumed that the server is authoritative and has complete jurisdiction
over those addresses. However, for various reasons, such as
misconfiguration or a faulty client implementation that retains its
<para>Such an
unwelcome event can be detected by legitimate clients (using ARP or ICMP
Echo Request mechanisms) and reported to the DHCPv4 server using a DHCPDECLINE
- message. The server will do a sanity check (to see if the client declining an
+ 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. Any DNS entries 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
+ 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
+ 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-
}
</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 lease4_decline hook is triggered after the
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
+ 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>
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 under-representing pool utilization. As this has a
- potential for major issues, we decided not to decrease assigned addresses
+ 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 DHCPDECLINE, but to do it later when Kea
recovers the address back to the available pool.</para>
<entry>pkt4-discover-received</entry>
<entry>integer</entry>
<entry>
- Number of DHCPDISCOVER packets received. This statistic is expected to grow.
- Its increase means that clients that just booted started their configuration process
- and their initial packets reached your server.
+ Number of DHCPDISCOVER packets received. This statistic is expected to grow; its
+ increase means that clients that just booted started their configuration process
+ and their initial packets reached your Kea server.
</entry>
</row>
<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 (DHCPOFFER) and accepted it, and they are now requesting
+ received the server's response (DHCPOFFER) and accepted it, and are now requesting
an address (DHCPREQUEST).
</entry>
</row>
<row>
<entry>subnet[id].total-addresses</entry>
<entry>integer</entry>
- <entry>The total number of addresses available for DHCPv4
- management. In other words, this is the sum of all addresses in
+ <entry>Total number of addresses available for DHCPv4
+ management; in other words, this is the sum of all addresses in
all configured pools. This statistic changes only during
configuration changes. Note it does not take into account any
addresses that may be reserved due to host reservation. The
<row>
<entry>subnet[id].assigned-addresses</entry>
<entry>integer</entry>
- <entry>The number of assigned addresses in a
+ <entry>Number of assigned addresses in a
given subnet. It increases every time a new lease is
allocated (as a result of receiving a DHCPREQUEST message) and is
decreased every time a lease is released (a DHCPRELEASE message is
<row>
<entry>reclaimed-leases</entry>
<entry>integer</entry>
- <entry>The number of expired leases that have
+ <entry>Number of expired leases that have
been reclaimed since server startup. It is incremented each time
an expired lease is reclaimed and is reset when the server is
reconfigured.
<row>
<entry>subnet[id].reclaimed-leases</entry>
<entry>integer</entry>
- <entry>The number of expired leases associated
+ <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 and is reset when the
<entry>declined-addresses</entry>
<entry>integer</entry>
<entry>
- The number of IPv4 addresses that are
+ Number of IPv4 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 increasing),
- a network administrator should investigate if there is
+ 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>
- The number of IPv4 addresses that are
+ Number of IPv4 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
statistic should be zero. If this statistic is
- non-zero (or 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>
- The number of IPv4 addresses that were
+ Number of IPv4 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
<entry>subnet[id].reclaimed-declined-addresses</entry>
<entry>integer</entry>
<entry>
- The number of IPv4 addresses that were
+ Number of IPv4 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.
<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 xml:id="dhcp4-std">
- <title>Supported DHCP Standards</title>
- <para>The following standards are currently supported:</para>
- <itemizedlist>
- <listitem>
- <simpara><emphasis>Dynamic Host Configuration Protocol</emphasis>,
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2131">RFC 2131</link>:
- Supported messages are DHCPDISCOVER (1), DHCPOFFER (2),
- DHCPREQUEST (3), DHCPRELEASE (7), DHCPINFORM (8), DHCPACK (5), and
- DHCPNAK(6).</simpara>
- </listitem>
- <listitem>
- <simpara><emphasis>DHCP Options and BOOTP Vendor Extensions</emphasis>,
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2132">RFC 2132</link>:
- Supported options are: PAD (0),
- END(255), Message Type(53), DHCP Server Identifier (54),
- Domain Name (15), DNS Servers (6), IP Address Lease Time
- (51), Subnet mask (1), and Routers (3).</simpara>
- </listitem>
- <listitem>
- <simpara><emphasis>DHCP Relay Agent Information Option</emphasis>,
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc3046">RFC 3046</link>:
- Relay Agent Information option is supported.</simpara>
- </listitem>
- <listitem>
- <simpara><emphasis>Vendor-Identifying Vendor Options for
- Dynamic Host Configuration Protocol version 4</emphasis>,
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc3925">RFC 3925</link>:
- Vendor-Identifying Vendor Class and Vendor-Identifying Vendor-Specific
- Information options are supported.</simpara>
- </listitem>
- <listitem>
- <simpara><emphasis>Client Identifier Option in DHCP Server Replies</emphasis>,
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc6842">RFC 6842</link>:
- Server by default sends back client-id option. That capability may be
- disabled. See <xref linkend="dhcp4-echo-client-id"/> for details.
- </simpara>
- </listitem>
- </itemizedlist>
- </section>
-
<section id="dhcp4-user-contexts">
<title>User Contexts in IPv4</title>
<para>
</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>
<para>
- It should be noted that Kea will not use that information, but will
- simply store and make it available to hook libraries. It is up to the
+ Kea does not use that information; it
+ simply stores it and makes it available to the hook libraries. It is up to each
hook library to extract that information and use it.
- The parser translates a "comment" entry into a user-context
+ 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>
</section>
+ <section xml:id="dhcp4-std">
+ <title>Supported DHCP Standards</title>
+ <para>The following standards are currently supported:</para>
+ <itemizedlist>
+ <listitem>
+ <simpara><emphasis>Dynamic Host Configuration Protocol</emphasis>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2131">RFC 2131</link>:
+ Supported messages are DHCPDISCOVER (1), DHCPOFFER (2),
+ DHCPREQUEST (3), DHCPRELEASE (7), DHCPINFORM (8), DHCPACK (5), and
+ DHCPNAK(6).</simpara>
+ </listitem>
+ <listitem>
+ <simpara><emphasis>DHCP Options and BOOTP Vendor Extensions</emphasis>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2132">RFC 2132</link>:
+ Supported options are: PAD (0),
+ END(255), Message Type(53), DHCP Server Identifier (54),
+ Domain Name (15), DNS Servers (6), IP Address Lease Time
+ (51), Subnet mask (1), and Routers (3).</simpara>
+ </listitem>
+ <listitem>
+ <simpara><emphasis>DHCP Relay Agent Information Option</emphasis>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc3046">RFC 3046</link>:
+ Relay Agent Information option is supported.</simpara>
+ </listitem>
+ <listitem>
+ <simpara><emphasis>Vendor-Identifying Vendor Options for
+ Dynamic Host Configuration Protocol version 4</emphasis>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc3925">RFC 3925</link>:
+ Vendor-Identifying Vendor Class and Vendor-Identifying Vendor-Specific
+ Information options are supported.</simpara>
+ </listitem>
+ <listitem>
+ <simpara><emphasis>Client Identifier Option in DHCP Server Replies</emphasis>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc6842">RFC 6842</link>:
+ Server by default sends back client-id option. That capability may be
+ disabled. See <xref linkend="dhcp4-echo-client-id"/> for details.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+
<section xml:id="dhcp4-limit">
<title>DHCPv4 Server Limitations</title>
<para>These are the current limitations of the DHCPv4 server
projects / thirdparty / kea.git / commitdiff
