From: Thomas Markwalder Date: Tue, 18 Aug 2020 15:28:26 +0000 (-0400) Subject: [#1284] Added database-connectivity section to ARM X-Git-Tag: Kea-1.8.0~41 X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=72738ca3b6dcb60eb7fcc8ce1b197f760fd2465c;p=thirdparty%2Fkea.git [#1284] Added database-connectivity section to ARM --- diff --git a/ChangeLog b/ChangeLog index 9c266b54a9..02eb278e6c 100644 --- 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 index 0000000000..240435f45f --- /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 fde3c52255..282312b8a6 100644 --- 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 222ef83ee1..401579be8f 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -28,6 +28,7 @@ Kea, can be found in ISC's `Knowledgebase