[#1284] Added database-connectivity section to ARM

diff --git a/ChangeLog b/ChangeLog
index 9c266b54a9483cc9af221571288e1ac9f1844499..02eb278e6c847fbb61b87f66a480aaf3af9fdcd9 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+1792.  [doc]           tmark
+       Added the Database Connectivity section to the ARM which explains
+       how Kea servers respond to back end database connectivity issues.
+       (Gitlab #1284)
+
 1791.  [doc]           tmark
        Updated the ARM section for the Lease Commands hook library
        which incorrectly stated that a command return value of 2 would

diff --git a/doc/sphinx/arm/database-connectivity.rst b/doc/sphinx/arm/database-connectivity.rst
new file mode 100644 (file)
index 0000000..240435f
--- /dev/null
+++ b/doc/sphinx/arm/database-connectivity.rst
@@ -0,0 +1,32 @@
+.. _database-connectivity:
+
+*********************
+Database Connectivity
+*********************
+Kea servers (kea-dhcp4 and kea-dhcp6) can be configured to use a variety of 
+database back ends for leases, hosts and configuration.  All of them may be 
+configured to support automatic recovery when connectivity is lost (see 
+``max-reconnect-tries`` and ``reconnect-wait-time``).
+
+It is important to understand how and when automatic recovery comes into play.  Automatic recovery, when configured, only operates after a successful start up 
+or reconfiguration during which connectivity to all back ends has been 
+successfully established.
+
+During server start up the inability to connect to any of the configured back
+ends is always considered fatal.  A fatal error will be logged and server will
+exit.  This is done based on the idea that configuration should be valid at 
+start up. Exiting to the system allows nanny scripts to detect the problem.
+
+During dynamic reconfiguration, all back ends are disconnected and then
+reconnected using the new configuration.  If connectivity to any of the
+back ends cannot be established, the server will log a fatal error but remain
+up. It will be able to process commands but will not serve clients. This 
+allows the configuration to be corrected via command, if required.
+
+During normal operations, if connectivity to any of the back ends is lost and 
+automatic recovery for that back end is enabled, the server will disconnect 
+from all back ends, and then attempt to reconnect them.  During the recovery
+process the server will cease serving clients but continue to respond to 
+commands.  If connectivity to all back ends is restored the server will 
+return to normal operations.  If connectivity cannot be restored after
+``max-reconnect-tries``,  the server will issue a fatal error and exit.

diff --git a/doc/sphinx/arm/rst_arm_sources.mk b/doc/sphinx/arm/rst_arm_sources.mk
index fde3c522554dfcff011dbbf2438881327705d9c0..282312b8a6bb54c1eb1368eaba7c93e89fc1e7ce 100644 (file)
--- a/doc/sphinx/arm/rst_arm_sources.mk
+++ b/doc/sphinx/arm/rst_arm_sources.mk
@@ -31,3 +31,4 @@ rst_arm_sources += arm/quickstart.rst
 rst_arm_sources += arm/shell.rst
 rst_arm_sources += arm/stats.rst
 rst_arm_sources += arm/stork.rst
+rst_arm_sources += arm/database-connectivity.rst

diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index 222ef83ee1d8fac072251e4fb7f361ba48e1d927..401579be8fbd3afdcf4d93ff2d9397cbee144e07 100644 (file)
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -28,6 +28,7 @@ Kea, can be found in ISC's `Knowledgebase <https://kb.isc.org/docs/kea-administr
    arm/agent
    arm/dhcp4-srv
    arm/dhcp6-srv
+   arm/database-connectivity
    arm/lease-expiration
    arm/congestion-handling
    arm/ddns