From: Ben Scott Date: Wed, 21 May 2025 22:50:46 +0000 (-0400) Subject: [#3881] Overhaul my overhaul X-Git-Tag: Kea-3.0.0~38 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7b06537aedef60e65ed121926bc3d4b7c1c5779f;p=thirdparty%2Fkea.git [#3881] Overhaul my overhaul --- diff --git a/doc/sphinx/arm/config-backend.rst b/doc/sphinx/arm/config-backend.rst index d53a1ba2a0..7e4871ebdd 100644 --- a/doc/sphinx/arm/config-backend.rst +++ b/doc/sphinx/arm/config-backend.rst @@ -39,7 +39,9 @@ Potential drawbacks include: .. note:: - Use of a database for storage of leases and/or reservations is still possible without the CB. See the ``host-databases`` and ``lease-database`` config directives. + Use of a database for storage of leases and/or host reservations is + possible without using the CB. See the ``host-databases`` and + ``lease-database`` config directives. Example Scenario ^^^^^^^^^^^^^^^^ @@ -68,64 +70,34 @@ Preparation is Required The Configuration Backend is not a "plug-and-play" solution. Supported scenarios require use of the CB API commands. Configuration information must be loaded into the CB database using the API for the CB to have any effect. -The general intent is for the CB to be integrated with external software. -Please do not define ``config-databases`` unless you have done the necessary -preparation work. - -Incompatibilities -^^^^^^^^^^^^^^^^^ - -Use of the :ischooklib:`libdhcp_subnet_cmds.so` hook with the CB is -contraindicated. The API commands starting with ``subnet`` all modify the -in-memory configuration of Kea. The only way to save that config would be to -write out a JSON config file. That would conflict with any subnets defined by -the CB. Use :ischooklib:`libdhcp_cb_cmds.so` to manage the -subnets information in the database instead. - -The Stork management suite does not currently support the CB. Stork operates -by direct configuration modification, with accompanying ``config-write`` of -the JSON config file. That would create duplicate definitions vs the CB. -Support for the CB is planned for a future release of Stork. - -In certain carefully-controlled scenarios, it may be possible to use these tools with the CB. Namely, if they are used in strictly "read-only" fashion, to retrieve Kea information, but never to modify it. However, no protection against accidental modification is provided, so this is not recommended. - -Implementation -^^^^^^^^^^^^^^ - -Currently, the Kea CB has the following limitations: - -- It is only supported for MySQL and PostgreSQL databases. - -- It is only supported for the DHCPv4 and DHCPv6 daemons; the Control Agent, - D2 daemon, and the NETCONF daemon cannot be configured from the database, - -- Only certain DHCP configuration parameters can be set in the - database: global parameters, option definitions, global options, client - classes, shared networks, and subnets. Other configuration parameters - must be sourced from a JSON configuration file. +The general intent is for the CB to be integrated as part of a larger +provisioning solution. Please do not define ``config-databases`` unless you +have done the necessary preparation work. Database Management ^^^^^^^^^^^^^^^^^^^ -While it is possible to manage the configuration information in the database -without :ischooklib:`libdhcp_cb_cmds.so` (using commonly available tools, such -as MySQL Workbench or the command-line MySQL client), these avenues are -neither recommended nor supported. The supported method for managing the -database contents is through :ischooklib:`libdhcp_cb_cmds.so`, which provides -management commands for config backends. +The only supported method for managing the contents of the CB database is +through the :ischooklib:`libdhcp_cb_cmds.so` hook, which provides API commands +for config backends. As a practical matter, to use the CB, you must do almost +all Kea configuration through the CB API. -Duplicate Definitions -^^^^^^^^^^^^^^^^^^^^^ +While it is theoretically possible to use the CB without the API (using tools +such as MySQL Workbench or the command-line MySQL client), these avenues are +neither recommended nor supported. + +Config Conflicts +^^^^^^^^^^^^^^^^ -We strongly recommend against storing configuration information in both the -config file and the CB database. In other words, do not use both JSON config -files (like ``kea-dhcp4.conf``) and CB to configure the same items. Ideally, -when using the CB, the Kea config files should contain the absolute bare -minimum necessary, with everything else coming from the CB. +We strongly recommend against mixing configuration information from the CB and +JSON. In other words, do not use both JSON config declarations and CB to +configure the same types of objects. Ideally, when using the CB, the Kea +config files should contain the absolute bare minimum necessary, with +everything else coming from the CB. Using both CB and JSON as a source of configuration risks conflicting -definitions, which is confusing at best, and usually leads to undesired -behavior. +definitions. Such conflicts are confusing at best, and usually lead to +undesired behavior or errors from Kea. In the event of a conflict, configuration instructions from the CB database generally take precedence over instructions from a JSON file. @@ -137,7 +109,47 @@ structures are replaced entirely. For example, if client classes are defined in the CB database, the DHCP server disregards any client classes defined in the JSON file. - Note that use of a database for storage of leases and/or reservations is still possible without the CB (with the ``host-databases`` and ``lease-database`` config directives). Such databases also load their config independently from the CB, and will conflict the same way JSON would. +In short, if you are using the CB, you should use only the CB. + +Incompatible Software +^^^^^^^^^^^^^^^^^^^^^ + +The preceding cautions about conflicting configuration information apply to software-driven configuration sources as well. + +Kea supports databases outside of the CB, such as with the ``host-databases`` +directive. Such databases load their config independently from the CB, and +will conflict the same way JSON declarations would. If using the CB, +such mechanisms should be avoided. + +Likewise, API commands which modify Kea's configuration (other than the +CB API) are contraindicated. This includes the +:ischooklib:`libdhcp_subnet_cmds.so` and :ischooklib:`libdhcp_host_cmds.so` +hooks. These APIs modify Kea's in-memory configuration, and can only be made +persist by using ``config-write`` to write a new JSON config file. + +The Stork management suite does not currently support the CB. Stork makes all +configuration changes through API avenues which expect to write a new JSON +file. Support for the CB is planned for a future release of Stork. + +In certain carefully-controlled scenarios, it may be possible to use these +tools with the CB. Namely, if they are used in strictly "read-only" fashion, +to retrieve Kea information, but never to modify it. However, no protection +against accidental modification is provided, so this is not recommended. + +Implementation +^^^^^^^^^^^^^^ + +Currently, the Kea CB has the following limitations: + +- It is only supported for MySQL and PostgreSQL databases. + +- It is only supported for the DHCPv4 and DHCPv6 daemons; the Control Agent, + D2 daemon, and the NETCONF daemon cannot be configured from the database, + +- Only certain DHCP configuration parameters can be set in the + database: global parameters, option definitions, global options, client + classes, shared networks, and subnets. Other configuration parameters + must be sourced from a JSON configuration file. Custom Options ^^^^^^^^^^^^^^