From: Tomek Mrugalski Date: Tue, 8 May 2018 14:20:33 +0000 (+0200) Subject: [5478] Changes after review: X-Git-Tag: trac5549a_base~34^2~9 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=307ddf55f81ac6b384ab9e3dfa0be3a38470adf8;p=thirdparty%2Fkea.git [5478] Changes after review: - HA lib description updated - wrote extra text about IETF failover - couple other small nits --- diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index 0610a6bf7c..cd60b4c24c 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -279,23 +279,48 @@ or configuration parameters currently used by the server. + + + Lease Commands + Kea sources + Kea 1.3.0 + The lease commands hook library offers a number of new + commands used to manage leases. Kea provides a way to store lease + information in various backends: memfile, MySQL, PostgreSQL and + Cassandra. This library provides a unified interface that can + manipulate leases in an unified, safe way. In particular, it + allows: manipulate leases in memfile while Kea is running, sanity + check changes, check lease existence and remove all leases + belonging to specific subnet. It can also catch more obscure + errors, like adding a lease with subnet-id that does not exist in + the configuration or configuring a lease to use an address that is + outside of the subnet to which it is supposed to belong. + + + High Availability Support customers Kea 1.4.0 - Minimizing a risk of DHCP service unavailability is achieved - by setting up multiple instances of the DHCP servers in a network. - Each server can serve selected group of clients in this network - (load balancing) or all clients, if it detects that its partner has - crashed or cannot be providing DHCP service for any other reason. - It is also possible to designate one server to serve all DHCP clients, - and leave another server as "standby". This server will activate its - DHCP function when it detects that its partner is not available. - Such cooperation between the DHCP servers requires that these - servers constantly communicate with each other to send updates about - allocated leases and to periodically test whether their partners are still - operational. The "libdhcp_ha" library provides such functionality for - Kea DHCP. + Minimizing a risk of DHCP service unavailability is + achieved by setting up a pair of the DHCP servers in a network. + Two modes of operation are supported. The first one is called load + balancing and is sometimes referred to as active-active. Each + server can handle selected group of clients in this network or all + clients, if it detects that its partner has became unavailable. + It is also possible + to designate one server to serve all DHCP clients, and leave + another server as "standby". This mode is called hot standby and + is sometimes referenced to as active-passive. This server will + activate its DHCP function when it detects that its partner is not + available. Such cooperation between the DHCP servers requires + that these servers constantly communicate with each other to send + updates about allocated leases and to periodically test whether + their partners are still operational. The hook library also + provides and ability to send lease updates to external backup + server, making it much easier to have a replacement that is almost + up to date. The "libdhcp_ha" library provides such functionality + for Kea DHCP. @@ -2830,18 +2855,26 @@ both the command and the response. libdhcp_ha: High Availability High Availability (HA) of the DHCP service is provided by running multiple - cooperating server instances. If any of these instances crashes, a surviving + cooperating server instances. If any of these instances becomes + unavailable for whatever reason (DHCP software crash, control agent + software crash, power failure, hardware + failure), a surviving server instance can continue providing the reliable service to the clients. Many DHCP servers implementations include "DHCP Failover" protocol, which most significant features are: communication between the servers, partner failure detection and leases synchronization between the servers. + However, the DHCPv4 failover standardization process was never completed + at IETF. The DHCPv6 failover standard (RFC 8156) was published, but it + is complex, difficult to use, has significant operational constraints + and is different than its v4 counterpart. Although it may be useful for some users to use a "standard" failover protocol, it seems that most of the Kea users are simply interested in - "some working solution" which guarantees high availability of the DHCP + a working solution which guarantees high availability of the DHCP service. Therefore, Kea HA hook library derives major concepts from the DHCP Failover protocol but uses its own solutions for communication, configuration and its own state machine, which greatly simplifies its - implementation and generally better fits into Kea. This document purposely + implementation and generally better fits into Kea. Also, it provides the + same features in both DHCPv4 and DHCPv6. This document purposely uses the term "High Availability" rather than "Failover" to emphasize that it is not the Failover protocol implementation. @@ -2865,7 +2898,7 @@ both the command and the response. the DHCP client by the server which has allocated the lease. By exchanging the lease updates, both servers get a copy of all leases allocated by the entire HA setup and any of the servers can be switched - to handle the entire DHCP traffic if its partner crashes. + to handle the entire DHCP traffic if its partner becomes unavailable. In the load balancing configuration, one of the servers must be designated as "primary" and the other server is designated as "secondary". @@ -2976,7 +3009,7 @@ both the command and the response. waiting - each started server instance enters this state. The backup server will transition - directly from this statet to the backup state. + directly from this state to the backup state. An active server will send heartbeat to its partner to check its state. If the partner appears to be unavailable the server will transition to the partner-down, otherwise it @@ -3079,8 +3112,8 @@ both the command and the response. In the hot standby mode, there is only one scope ha_server1 because only the server1 - is responding to the DHCP queries. If that server crashes, the - server2 becomes responsible for this scope. + is responding to the DHCP queries. If that server becomes unavailable, + the server2 becomes responsible for this scope. The backup servers do not have their own scopes. In some @@ -3186,8 +3219,8 @@ both the command and the response. Two hook libraries must be loaded to enable HA: libdhcp_lease_cmds.so and - libdhcp_ha.so. The former provides the - implemenation of the HA feature. The latter enables control + libdhcp_ha.so. The latter provides the + implemenation of the HA feature. The former enables control commands required by HA to fetch and manipulate leases on the remote servers. In the example provided above, it is assumed that Kea libraries are installed in the /usr/lib @@ -3262,7 +3295,7 @@ both the command and the response. The values of max-ack-delay and - max-unacked must be selected carefully, taking + max-unacked-clients must be selected carefully, taking into account specifics of the network in which DHCP servers are operating. Note that the server in question may not respond to some of the DHCP clients because these clients are not to be serviced @@ -3299,7 +3332,7 @@ both the command and the response. the server. url - specifies URL to be used to - contact this server over the control channel. Other servers used this + contact this server over the control channel. Other servers use this URL to send control commands to that server. role - denotes the role of the @@ -3327,7 +3360,7 @@ both the command and the response. state, it can serve leases from both pools and it will select the pool which is appropriate for the received query. In other words, if the query would normally be processed by the - server2, but this server has crashed, the + server2, but this server is not available, the server1 will allocate the lease from the pool of "192.0.3.200 - 192.0.3.250". @@ -3371,9 +3404,13 @@ both the command and the response. "client-classes": [ { + // No test expression for this class. Incoming packets will be + // assigned to that class dynamically by the HA Hook library. "name": "ha_server1" }, { + // No test expression for this class. Incoming packets will be + // assigned to that class dynamically by the HA Hook library. "name": "ha_server2" }, {