10. Database Connectivity

The Kea servers (kea-dhcp4 and 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 Lease Database Configuration and Lease Database Configuration.)

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 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 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.