Kea HA hook library.
Supported Configurations
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
The Kea HA hook library supports two configurations, also known as HA
modes: load-balancing and hot-standby. In the load-balancing mode, two
other, but also to the backup servers.
Clocks on Active Servers
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
Synchronized clocks are essential for the HA setup to operate reliably.
The servers share lease information via lease updates and during
.. _ha-server-states:
Server States
--------------
+~~~~~~~~~~~~~
.. _command-ha-heartbeat:
.. _ha-scope-transition:
Scope Transition in a Partner-Down Case
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When one of the servers finds that its partner is unavailable, it starts
serving clients from both its own scope and the scope of the unavailable
.. _ha-load-balancing-config:
Load-Balancing Configuration
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following is the configuration snippet to enable high availability
on the primary server within the load-balancing configuration. The same
.. _ha-load-balancing-advanced-config:
Load Balancing with Advanced Classification
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the previous section, we provided an example of a load-balancing
configuration with client classification limited to the ``HA_server1``
.. _ha-hot-standby-config:
Hot-Standby Configuration
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
The following is an example configuration of the primary server in the
hot-standby configuration:
.. _ha-sharing-lease-info:
Lease Information Sharing
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
An HA-enabled server informs its active partner about allocated or
renewed leases by sending appropriate control commands, and the partner
.. _ha-syncing-page-limit:
Controlling Lease-Page Size Limit
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An HA-enabled server initiates synchronization of the lease database
after downtime or upon receiving the ``ha-sync`` command. The server
.. _ha-syncing-timeouts:
Timeouts
---------
+~~~~~~~~
In deployments with a large number of clients connected to the network,
lease-database synchronization after a server failure may be a
.. _ha-pause-state-machine:
Pausing the HA State Machine
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The high-availability state machine includes many different states
described in detail in :ref:`ha-server-states`. The server
.. _ha-ctrl-agent-config:
Control Agent Configuration
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
:ref:`kea-ctrl-agent` describes in detail the Kea daemon, which
provides a RESTful interface to control the Kea servers. The same
.. _ha-control-commands:
Control Commands for High Availability
---------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Even though the HA hook library is designed to automatically resolve
issues with DHCP service interruptions by redirecting the DHCP traffic
.. _command-ha-sync:
The ha-sync Command
-~~~~~~~~~~~~~~~~~~~
+-------------------
The ``ha-sync`` command instructs the server to synchronize its local
lease database with the selected peer. The server fetches all leases
.. _command-ha-scopes:
The ha-scopes Command
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
This command allows modification of the HA scopes that the server is
serving. Consult :ref:`ha-load-balancing-config` and
.. _command-ha-continue:
The ha-continue Command
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
This command is used to resume the operation of the paused HA state
machine, as described in :ref:`ha-pause-state-machine`. It takes no arguments, so the
.. _command-cache-flush:
The cache-flush Command
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
This command allows removal of a specified number of cached host
entries. It takes one parameter, which defines the number of hosts to be
.. _command-cache-clear:
The cache-clear Command
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
This command allows removal of all cached host entries. An example usage
looks as follows:
.. _command-cache-size:
The cache-size Command
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
This command returns the number of host entries. An example usage looks
as follows:
.. _command-cache-write:
The cache-write Command
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
In general, the cache content is considered a runtime state and the
server can be shut down or restarted as usual; the cache will then be
.. _command-cache-load:
The cache-load Command
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
See the previous section for a discussion of use cases where it may be
useful to write and load contents of the host cache to disk.
.. _command-cache-get:
The cache-get Command
----------------------
+~~~~~~~~~~~~~~~~~~~~~
This command is similar to cache-write, but instead of writing the cache
contents to disk, it returns the contents to whoever sent the command.
.. _command-cache-get-by-id:
The cache-get-by-id Command
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is similar to cache-get, but instead of returning the whole
content it returns only the entries matching the given identifier.
.. _command-cache-insert:
The cache-insert Command
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
This command may be used to manually insert a host into the cache; there
are very few use cases when this command might be useful. This command
.. _command-cache-remove:
The cache-remove Command
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes it is useful to remove a single entry from the host cache. A
good use case is a situation where the device is up, Kea has already
projects / thirdparty / kea.git / commitdiff
