From: Razvan Becheriu Date: Fri, 19 Mar 2021 08:04:27 +0000 (+0200) Subject: [#1621] added documentation X-Git-Tag: Kea-1.9.6~19 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f2e1f082a151fd50d096f2ab52cf2e9c25b26037;p=thirdparty%2Fkea.git [#1621] added documentation --- diff --git a/doc/examples/kea4/all-keys.json b/doc/examples/kea4/all-keys.json index e73799e731..722ea18b8a 100644 --- a/doc/examples/kea4/all-keys.json +++ b/doc/examples/kea4/all-keys.json @@ -370,6 +370,9 @@ // Disable DHCP on database connection loss. "disable-dhcp-on-db-loss": true, + // Enable database connection recovery. + "enable-connection-recovery": true, + // Connection connect timeout. "connect-timeout": 100, diff --git a/doc/examples/kea4/backends.json b/doc/examples/kea4/backends.json index b91e2b49a0..cc306cbfa6 100644 --- a/doc/examples/kea4/backends.json +++ b/doc/examples/kea4/backends.json @@ -43,6 +43,7 @@ // "reconnect-wait-time": 3000, // expressed in ms // "max-reconnect-tries": 3, // "disable-dhcp-on-db-loss": true, +// "enable-connection-recovery": true, // "connect-timeout": 3 // }, @@ -63,6 +64,7 @@ // "reconnect-wait-time": 3000, // expressed in ms // "max-reconnect-tries": 3, // "disable-dhcp-on-db-loss": true, +// "enable-connection-recovery": true, // "connect-timeout": 3 // }, diff --git a/doc/examples/kea6/all-keys.json b/doc/examples/kea6/all-keys.json index c89697c76c..cb3201dbe6 100644 --- a/doc/examples/kea6/all-keys.json +++ b/doc/examples/kea6/all-keys.json @@ -312,6 +312,9 @@ // Disable DHCP on database connection loss. "disable-dhcp-on-db-loss": true, + // Enable database connection recovery. + "enable-connection-recovery": true, + // Connection connect timeout. "connect-timeout": 100, diff --git a/doc/examples/kea6/backends.json b/doc/examples/kea6/backends.json index 60104f5b31..123b7b344a 100644 --- a/doc/examples/kea6/backends.json +++ b/doc/examples/kea6/backends.json @@ -43,6 +43,7 @@ // "reconnect-wait-time": 3000, // expressed in ms // "max-reconnect-tries": 3, // "disable-dhcp-on-db-loss": true, +// "enable-connection-recovery": true, // "connect-timeout": 3 // }, @@ -63,6 +64,7 @@ // "reconnect-wait-time": 3000, // expressed in ms // "max-reconnect-tries": 3, // "disable-dhcp-on-db-loss": true, +// "enable-connection-recovery": true, // "connect-timeout": 3 // }, diff --git a/doc/sphinx/arm/database-connectivity.rst b/doc/sphinx/arm/database-connectivity.rst index a077b9bd66..9a9cdff81f 100644 --- a/doc/sphinx/arm/database-connectivity.rst +++ b/doc/sphinx/arm/database-connectivity.rst @@ -6,8 +6,8 @@ Database Connectivity Kea servers (kea-dhcp4 and kea-dhcp6) can be configured to use a variety of database backends for leases, hosts, and configuration. All of them may be configured to support automatic recovery when connectivity is lost (see -``max-reconnect-tries``, ``reconnect-wait-time`` and -``disable-dhcp-on-db-loss``). +``max-reconnect-tries``, ``reconnect-wait-time``, ``disable-dhcp-on-db-loss`` +and ``enable-connection-recovery``). It is important to understand how and when automatic recovery comes into play. Automatic recovery, when configured, only operates after a successful startup @@ -30,7 +30,14 @@ 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 ``disable-dhcp-on-db-loss`` -configured option, but continues to respond to commands. If connectivity to all +configured option, and continues to respond to commands. If connectivity to all backends is restored, the server returns to normal operations. If connectivity cannot be restored after ``max-reconnect-tries``, the server issues a fatal error and exits. + +The entire database connection mechanism can be completely disabled by setting +``enable-connection-recovery`` to false. This will cause the server to ignore +the failure of the database connections and it is highly discouraged. This will +cause the server to not function properly and log errors. The default value for +``enable-connection-recovery`` is true. This feature is mainly used by hook +libraries which can function properly without permanent database connections. diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index 95fb595ad0..6f28661272 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -511,6 +511,13 @@ loss of connectivity. The default value for Cassandra is 2000 ms. The default value for MySQL and PostgreSQL is true, which disables the dhcp service while trying to automatically recover lost connections. +:: + + "Dhcp4": { "lease-database": { "enable-connection-recovery" : true, ... }, ... } + +The default value for MySQL and PostgreSQL is true, which enables the server to +automatically recover lost connections. + .. note:: Automatic reconnection to database backends is configured @@ -723,11 +730,20 @@ The default value for MySQL and PostgreSQL is 0, which disables automatic recovery and causes the server to exit immediately upon detecting the loss of connectivity. The default value for Cassandra is 2000 ms. +:: + "Dhcp4": { "hosts-database": { "disable-dhcp-on-db-loss" : true, ... }, ... } The default value for MySQL and PostgreSQL is true, which disables the dhcp service while trying to automatically recover lost connections. +:: + + "Dhcp4": { "hosts-database": { "enable-connection-recovery" : true, ... }, ... } + +The default value for MySQL and PostgreSQL is true, which enables the server to +automatically recover lost connections. + .. note:: Automatic reconnection to database backends is configured diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index 861b91ffb0..58b482a441 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -473,11 +473,20 @@ The default value for MySQL and PostgreSQL is 0, which disables automatic recovery and causes the server to exit immediately upon detecting the loss of connectivity. The default value for Cassandra is 2000 ms. +:: + "Dhcp6": { "lease-database": { "disable-dhcp-on-db-loss" : true, ... }, ... } The default value for MySQL and PostgreSQL is true, which disables the dhcp service while trying to automatically recover lost connections. +:: + + "Dhcp6": { "lease-database": { "enable-connection-recovery" : true, ... }, ... } + +The default value for MySQL and PostgreSQL is true, which enables the server to +automatically recover lost connections. + .. note:: Automatic reconnection to database backends is configured @@ -640,11 +649,20 @@ The default value for MySQL and PostgreSQL is 0, which disables automatic recovery and causes the server to exit immediately upon detecting the loss of connectivity. The default value for Cassandra is 2000 ms. +:: + "Dhcp6": { "hosts-database": { "disable-dhcp-on-db-loss" : true, ... }, ... } The default value for MySQL and PostgreSQL is true, which disables the dhcp service while trying to automatically recover lost connections. +:: + + "Dhcp6": { "hosts-database": { "enable-connection-recovery" : true, ... }, ... } + +The default value for MySQL and PostgreSQL is true, which enables the server to +automatically recover lost connections. + .. note:: Automatic reconnection to database backends is configured