1 files changed, 104 insertions, 0 deletions
diff --git a/doc/sphinx/arm/database-connectivity.rst b/doc/sphinx/arm/database-connectivity.rst
new file mode 100644
index 0000000..8d61d64
--- /dev/null
+++ b/doc/sphinx/arm/database-connectivity.rst
@@ -0,0 +1,104 @@
+.. _database-connectivity:
+
+*********************
+Database Connectivity
+*********************
+
+The Kea servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`) can be configured to use a variety of
+database backends for leases, hosts, and configuration. They can be
+configured to support automatic recovery when connectivity is lost, via
+the ``on-fail`` and ``retry-on-startup`` parameters.
+(The ``reconnect-wait-time`` and ``max-reconnect-tries`` parameters are
+described in :ref:`database-configuration4` and :ref:`database-configuration6`.)
+
+It is important to understand how and when automatic recovery comes into play.
+Automatic recovery, when configured, only operates after a successful startup
+or reconfiguration during which connectivity to all backends has been
+successfully established.
+
+During server startup, the inability to connect to any of the configured
+backends is considered fatal only if ``retry-on-startup`` is set to ``false``
+(the default). A fatal error is logged and the server exits, based on the idea
+that the configuration should be valid at startup. Exiting to the operating
+system allows nanny scripts to detect the problem.
+If ``retry-on-startup`` is set to ``true``, the server will start reconnection
+attempts even at server startup or on reconfigure events, and will honor the
+action specified in the ``on-fail`` parameter.
+Database connection retries are not attempted on startup if the
+:ischooklib:`libdhcp_limits.so` is loaded because the hook library requires a
+valid connection to the database to check if JSON format is supported and to
+recount class limits.
+
+During dynamic reconfiguration, all backends are disconnected and then
+reconnected using the new configuration. If connectivity to any of the
+backends cannot be established, the server logs a fatal error but remains
+up. It is able to process commands but does not serve clients. This
+allows the configuration to be corrected via the :isccmd:`config-set` or
+``remote-*`` commands, if required.
+
+During normal operations, if connectivity to any of the backends is lost and
+automatic recovery for that backend is enabled, the server disconnects from the
+respective backend and then attempts to reconnect. During the recovery process,
+the server ceases to serve clients according to the ``on-fail`` configured
+option but continues to respond to commands.
+
+The ``on-fail`` parameter configures the actions the server should take when a
+connection is lost. It can have one of the following values:
+
+-  ``stop-retry-exit`` - indicates that the server should stop the service
+   while it tries to recover the connection, and exit if recovery is not
+   successful after ``max-reconnect-tries``.
+
+-  ``serve-retry-exit`` - indicates that the server should not stop the
+   service while it tries to recover the connection, and exit if recovery is not
+   successful after ``max-reconnect-tries``.
+
+-  ``serve-retry-continue`` - indicates that the server should not stop the
+   service while it tries to recover the connection, and not exit if recovery is
+   not successful after ``max-reconnect-tries``.
+
+If connectivity to all backends is restored, the server returns to normal
+operations. If the connection cannot be restored and the server is configured
+to exit, it issues a fatal error before shutdown.
+
+For Kea DHCP servers to work with database backends, the schema has to be
+created and has to have the version specific to the version of the running Kea
+server. If the version check fails on a database backend that is not configured
+as readonly, Kea attempts to initialize the schema.
+
+.. note::
+
+    Schema upgrades are not attempted to not accidentally remove the
+    opportunity for prior administrative actions that users may be interested in,
+    like, for example, backing up the database or temporarily shutting off running
+    Kea servers that are currently operating on the database.
+
+The connection to the database server can optionally be protected by TLS.
+Corresponding database configuration parameters for Kea servers are:
+
+-  The ``trust-anchor`` specifies the Certification Authority file name or
+   directory path.
+
+-  The ``cert-file`` specifies the client certificate file name.
+
+-  The ``key-file`` specifies the private key file name.
+
+-  The ``cipher-list`` specifies the list of TLS ciphers (the syntax of
+   the content of this parameter is described in the OpenSSL ciphers
+   manual).
+
+These parameters are similar to the parameters of the secure connections
+with the agent but are interpreted by different backends using database
+configurations too.
+
+Currently the support for each database is:
+
+-  MySQL supports the whole set, additional configuration must be done
+   in the MySQL local setup, for instance certificate revocation list,
+   choice of a specific TLS version, mutual authentication, etc.
+   When a TLS connection was required but the actual connection is in
+   clear text an error log is emitted.
+
+-  PostgreSQL only uses the configuration to enable the SSL/TLS support
+   in the client library (libpq). Anything else must be done in the
+   PostgreSQL local configuration.