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

[5682] Docs written

Browse Source
This commit is contained in:
Tomek Mrugalski
2018-07-26 13:15:44 +02:00
parent 229b95b86a
commit 7ad59a27fb
2 changed files with 153 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
doc/guide/dhcp4-srv.xml
View File

@@ -3318,7 +3318,116 @@ It is merely echoed by the server
}
</screen>
</para>
</section>
</section>
<section xml:id="sanity-checks4">
<title>Sanity checks in DHCPv4</title>
<para>
An important aspect of a well running DHCP system is an assurance that
the data remains consisent. However, in some cases it may be convenient
to tolerate certain inconsistent data. For example, a network
administrator that temporarily removed a subnet from a configuration
wouldn't want all the leases associated with it disappear from the
lease database. Kea 1.5 introduced a mechanism to better control sanity
checks such as this. While currently the scope of configurable sanity
checks is limited and their default value is set low, it is expected
that over time the default settings will be set to more aggressive
values and more parameters of similar nature will be added in the
future.
</para>
<para>
Kea now supports a new configuration scope called
<command>sanity-checks</command>. It currently allows only a single
parameter called <command>lease-checks</command>. It governs what sort
of verification is done when a new lease is being added to the
system. There are three ways how a lease can appear in the system:
can be loaded from a lease file from disk, can be added by REST command
or be added internally using LeaseMgr programmatic interface. While
the REST commands already had sanity-checks implemented, they were
boolean in nature - either the lease passed all checks and was accepted
or it failed and was rejected. With the introduction of sanity checks
mechanism, it is now possible to tell Kea to try to correct
inconsistent data.
</para>
<para>
Every subnet has a subnet-id value. This is how Kea internally
identifies subnets. Each lease has a subnet-id parameter as well, which
identifies which subnet it belongs to. However, if configuration has
changed, it is possible that a lease could exist with a subnet-id
without any subnet that matches it. Also, it may be possible that
subnets configuration has changed and the subnet-id now belongs to a
subnet that does not match the lease. Kea corrective algorithm first
checks if there is a subnet with subnet-id specified by the lease. If
there is, it checks whether the lease belongs to that subnet. If not,
depending on the lease-checks setting, the lease is discarded, a
warning is printed or a new subnet is selected for the lease that
matches it topologically.
</para>
<para>
There are five levels which are supported:
</para>
<itemizedlist>
<listitem>
<simpara><command>none</command> - do no special checks, accept the
lease as is</simpara>
</listitem>
<listitem>
<simpara><command>warn</command> - if problems are detected, a
warning will be printed, but the lease data will be accepted
anyway. This is the default value. If not explicitly configured to
some other value, this level will be used.</simpara>
</listitem>
<listitem>
<simpara><command>fix</command> - If data inconsistency is
discovered, Kea will try to correct it. If the correction is
not successful, the data will be inserted anyway.</simpara>
</listitem>
<listitem>
<simpara><command>fix-del</command> - If data inconsistency is
discovered, Kea will try to correct it. If the correction is not
succesful, the lease will be rejected. This setting ensures the data
correctness, but some incorrect data may be lost. Use with
care.</simpara>
</listitem>
<listitem>
<simpara><command>del</command> - This is the strictest mode. If any
inconsistency is detected, the lease is rejected. Use with care.
</simpara>
</listitem>
</itemizedlist>
<para>This feature is currently implemented for memfile backend and for
lease4-add command.</para>
<para>
An example configuration that sets this parameter looks as follows:
<screen>
"Dhcp4": {
"sanity-checks": {
// This parameter determines what to do when a new lease appears in the
// system (i.e. either is read from disk during memfile startup or is
// added via lease commands). There are five modes supported:
// none - do nothing, accept them as is
// warn - if subnet-id problems are detected, print a warning, but
// otherwise load the lease as is. This is the default value.
// fix - attempt to fix the lease by finding appropriate subnet-id value.
// if there is no suitable subnet, the lease is loaded as is.
// fix-del - attempt to fix the lease by findind appropriate subnet-id
// value. If there is no suitable subnet, the lease is deleted.
// del - delete leases that have incorrect subnet-id values.
<userinput>"lease-checks": "fix-del"</userinput>
},
...
}</screen>
</para>
</section>
</section> <!-- end of configuring kea-dhcp4 server section -->

43
doc/guide/dhcp6-srv.xml
View File

@@ -3022,6 +3022,49 @@ should include options from the isc option space:
</note>
</section>
<section xml:id="sanity-checks6">
<title>Sanity checks in DHCPv6</title>
<para>
The sanity checks mechanism works exactly the same as its
DHCPv4 counterpart. See <xref linkend="sanity-checks4"/> for
details.
</para>
<para>
The only difference is that the sanity checks mechanism works
for address leases only. Since delegated prefixes do not have
to belong to a subnet in which they're offered, there is no
way to implement such a mechanism for IPv6 prefixes.
</para>
<para>This feature is currently implemented for memfile backend and for
lease6-add command.</para>
<para>
An example configuration that sets this parameter looks as follows:
<screen>
"Dhcp6": {
"sanity-checks": {
// This parameter determines what to do when a new lease appears in the
// system (i.e. either is read from disk during memfile startup or is
// added via lease commands). There are five modes supported:
// none - do nothing, accept them as is
// warn - if subnet-id problems are detected, print a warning, but
// otherwise load the lease as is. This is the default value.
// fix - attempt to fix the lease by finding appropriate subnet-id value.
// if there is no suitable subnet, the lease is loaded as is.
// fix-del - attempt to fix the lease by findind appropriate subnet-id
// value. If there is no suitable subnet, the lease is deleted.
// del - delete leases that have incorrect subnet-id values.
<userinput>"lease-checks": "fix-del"</userinput>
},
...
}</screen>
</para>
</section>
</section>
<!-- Host reservation is a large topic. There will be many subsections,