From: Tomek Mrugalski Date: Thu, 26 Jul 2018 11:15:44 +0000 (+0200) Subject: [5682] Docs written X-Git-Tag: ha_phase2~14 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7ad59a27fbb1ac0fcddd296a1e760bceebb15f21;p=thirdparty%2Fkea.git [5682] Docs written --- diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index e8ca422461..2c576ecdf6 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -3318,7 +3318,116 @@ It is merely echoed by the server } - + + + +
+ Sanity checks in DHCPv4 + + + 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. + + + + Kea now supports a new configuration scope called + sanity-checks. It currently allows only a single + parameter called lease-checks. 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. + + + + 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. + + + + There are five levels which are supported: + + + + + none - do no special checks, accept the + lease as is + + + warn - 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. + + + fix - If data inconsistency is + discovered, Kea will try to correct it. If the correction is + not successful, the data will be inserted anyway. + + + fix-del - 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. + + + del - This is the strictest mode. If any + inconsistency is detected, the lease is rejected. Use with care. + + + + + This feature is currently implemented for memfile backend and for + lease4-add command. + + + An example configuration that sets this parameter looks as follows: + +"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. + "lease-checks": "fix-del" + }, + ... +} + + +
diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 2488ced5d0..c4553c9d69 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -3022,6 +3022,49 @@ should include options from the isc option space: +
+ Sanity checks in DHCPv6 + + + The sanity checks mechanism works exactly the same as its + DHCPv4 counterpart. See for + details. + + + + 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. + + + This feature is currently implemented for memfile backend and for + lease6-add command. + + + An example configuration that sets this parameter looks as follows: + +"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. + "lease-checks": "fix-del" + }, + ... +} + + +
+