diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/examples/kea4/all-keys.json | 4 | ||||
| -rw-r--r-- | doc/examples/kea4/backends.json | 2 | ||||
| -rw-r--r-- | doc/examples/kea6/all-keys.json | 4 | ||||
| -rw-r--r-- | doc/examples/kea6/backends.json | 2 | ||||
| -rw-r--r-- | doc/sphinx/arm/database-connectivity.rst | 17 | ||||
| -rw-r--r-- | doc/sphinx/arm/dhcp4-srv.rst | 26 | ||||
| -rw-r--r-- | doc/sphinx/arm/dhcp6-srv.rst | 26 | ||||
| -rw-r--r-- | doc/sphinx/arm/hooks-legal-log.rst | 9 |
8 files changed, 83 insertions, 7 deletions
diff --git a/doc/examples/kea4/all-keys.json b/doc/examples/kea4/all-keys.json index 4334c25eb8..d5e0a02bf1 100644 --- a/doc/examples/kea4/all-keys.json +++ b/doc/examples/kea4/all-keys.json @@ -408,6 +408,10 @@ // serve-retry-continue "on-fail": "stop-retry-exit", + // Flag which indicates if the DB recovery should be attempted + // at server startup and on reconfiguration events. + "retry-on-startup": false, + // Connection connect timeout in seconds. "connect-timeout": 100, diff --git a/doc/examples/kea4/backends.json b/doc/examples/kea4/backends.json index e7c1a48b3b..62817c05d2 100644 --- a/doc/examples/kea4/backends.json +++ b/doc/examples/kea4/backends.json @@ -42,6 +42,7 @@ // "reconnect-wait-time": 3000, // expressed in ms // "max-reconnect-tries": 3, // "on-fail": "stop-retry-exit", +// "retry-on-startup": false, // "connect-timeout": 3 // }, @@ -62,6 +63,7 @@ // "reconnect-wait-time": 3000, // expressed in ms // "max-reconnect-tries": 3, // "on-fail": "stop-retry-exit", +// "retry-on-startup": false, // "connect-timeout": 3 // }, diff --git a/doc/examples/kea6/all-keys.json b/doc/examples/kea6/all-keys.json index fac0218af5..90ff5bb03f 100644 --- a/doc/examples/kea6/all-keys.json +++ b/doc/examples/kea6/all-keys.json @@ -350,6 +350,10 @@ // serve-retry-continue "on-fail": "stop-retry-exit", + // Flag which indicates if the DB recovery should be attempted + // at server startup and on reconfiguration events. + "retry-on-startup": false, + // Connection connect timeout in seconds. "connect-timeout": 100, diff --git a/doc/examples/kea6/backends.json b/doc/examples/kea6/backends.json index df1072cfb1..350c8d60f5 100644 --- a/doc/examples/kea6/backends.json +++ b/doc/examples/kea6/backends.json @@ -42,6 +42,7 @@ // "reconnect-wait-time": 3000, // expressed in ms // "max-reconnect-tries": 3, // "on-fail": "stop-retry-exit", +// "retry-on-startup": false, // "connect-timeout": 3 // }, @@ -62,6 +63,7 @@ // "reconnect-wait-time": 3000, // expressed in ms // "max-reconnect-tries": 3, // "on-fail": "stop-retry-exit", +// "retry-on-startup": false, // "connect-timeout": 3 // }, diff --git a/doc/sphinx/arm/database-connectivity.rst b/doc/sphinx/arm/database-connectivity.rst index 12d9df7510..44f8208bc1 100644 --- a/doc/sphinx/arm/database-connectivity.rst +++ b/doc/sphinx/arm/database-connectivity.rst @@ -6,9 +6,9 @@ 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`` parameter. (The ``reconnect-wait-time`` and -``max-reconnect-tries`` parameters are described -in :ref:`database-configuration4` and :ref:`database-configuration6`.) +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 @@ -16,10 +16,13 @@ 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 always considered fatal. 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. +backends is considered fatal only if ``retry-on-startup`` is set to ``false``. +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 ``on-fail`` parameter. During dynamic reconfiguration, all backends are disconnected and then reconnected using the new configuration. If connectivity to any of the diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index 8bfd703740..5d6acad94a 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -576,6 +576,19 @@ The possible values are: active while processing DHCP traffic. Change this only if the server is used exclusively as a configuration tool. +:: + + "Dhcp4": { "lease-database": { "retry-on-startup" : true, ... }, ... } + +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``. +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 ``on-fail`` parameter. + The host parameter is used by the MySQL and PostgreSQL backends. Finally, the credentials of the account under which the server will @@ -798,6 +811,19 @@ The possible values are: the lease database backend and the hosts database backend are connected to the same database instance. +:: + + "Dhcp4": { "hosts-database": { "retry-on-startup" : true, ... }, ... } + +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``. +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 ``on-fail`` parameter. + Finally, the credentials of the account under which the server will access the database should be set: diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index 76d9d1c1e9..a9f69d49ba 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -532,6 +532,19 @@ The possible values are: active while processing DHCP traffic. Change this only if the server is used exclusively as a configuration tool. +:: + + "Dhcp6": { "lease-database": { "retry-on-startup" : true, ... }, ... } + +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``. +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 ``on-fail`` parameter. + The host parameter is used by the MySQL and PostgreSQL backends. Finally, the credentials of the account under which the server will @@ -754,6 +767,19 @@ The possible values are: the lease database backend and the hosts database backend are connected to the same database instance. +:: + + "Dhcp6": { "hosts-database": { "retry-on-startup" : true, ... }, ... } + +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``. +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 ``on-fail`` parameter. + Finally, the credentials of the account under which the server will access the database should be set: diff --git a/doc/sphinx/arm/hooks-legal-log.rst b/doc/sphinx/arm/hooks-legal-log.rst index 41dc34e08c..a1af7f677f 100644 --- a/doc/sphinx/arm/hooks-legal-log.rst +++ b/doc/sphinx/arm/hooks-legal-log.rst @@ -1083,3 +1083,12 @@ If ``on-fail`` is set to ``serve-retry-exit``, the server will shut down if the connection to the database backend is not restored according to the ``max-reconnect-tries`` and ``reconnect-wait-time`` parameters, but it continues serving clients while this mechanism is activated. + +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``. +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 ``on-fail`` parameter. |