[5682] Docs written

doc/guide/dhcp4-srv.xml

@@ -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 -->
 

doc/guide/dhcp6-srv.xml

@@ -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,