diff --git a/doc/sphinx/arm/config-backend.rst b/doc/sphinx/arm/config-backend.rst index 92249bf3ee..773757d5bf 100644 --- a/doc/sphinx/arm/config-backend.rst +++ b/doc/sphinx/arm/config-backend.rst @@ -12,17 +12,22 @@ Kea Configuration Backend (CB or config backend) gives Kea servers the ability to manage and fetch their configuration from one or more databases. In this documentation, the term "Configuration Backend" may also refer to the particular Kea module providing support to manage and fetch the -configuration information from the particular database type. For +configuration information from the particular database type. For example, MySQL Configuration Backend is the logic implemented within the ``mysql_cb`` hook library, which provides a complete set of functions to manage and fetch the configuration information from the MySQL database. +The PostgreSQL Configuration Backend is the logic implemented within the +``pgsql_cb`` hook library, which provides a complete set of functions to +manage and fetch the configuration information from the PostgreSQL database. +From herein, the term "database" is used to refer to either a MySQL or +PostgreSQL database. In small deployments, e.g. those comprising a single DHCP server instance with limited and infrequently changing number of subnets, it may be impractical to use the CB as a configuration repository because it requires additional third-party software to be installed and -configured - in particular the MySQL server and MySQL client. Once the -number of DHCP servers and/or the number of managed subnets in the +configured - in particular the database server, client and libraries. +Once the number of DHCP servers and/or the number of managed subnets in the network grows, the usefulness of the CB becomes obvious. One use case for the CB is a pair of Kea DHCP servers that are configured @@ -67,18 +72,18 @@ CB Capabilities and Limitations Currently, the Kea CB has the following limitations: -- It is only supported for the MySQL database. +- 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, +- 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. -Kea CB stores data in a MySQL schema that is public. It is possible to -insert configuration data into the MySQL tables manually or automatically +Kea CB stores data in a schema that is public. It is possible to +insert configuration data into the tables manually or automatically using SQL scripts, but this requires SQL and schema knowledge. The supported method for managing the data is through the ``cb-cmds`` hook library, which provides management commands for config backends. It simplifies many @@ -95,7 +100,10 @@ Appendix A of this manual for a complete list. at https://www.isc.org/contact. -The schema creation script can be found at `dhcpdb_create.mysql `__; +The schema creation scripts can be found at `dhcpdb_create.mysql `__ and +; +`dhcpdb_create.pgsql `__ and +; other related design documents are stored in our GitLab: `CB Design `__ and `Client Classes in CB Design `__. @@ -154,25 +162,30 @@ in two independent configuration sources. CB Components ------------- -The ``mysql_cb`` open source hook library implementing the configuration -backend for MySQL must be compiled and loaded by the DHCP servers. This -hook library is compiled when the ``--with-mysql`` configuration switch -is used during the Kea build. The MySQL C client libraries must be -installed, as explained in :ref:`dhcp-install-configure`. +To use a MySQL configuration backend you must compile the ``mysql_cb`` open +source hook library and configre the DHCP servers to load it. It is compiled when +the ``--with-mysql`` configuration switch is used during the Kea build. The MySQL C +client libraries must be installed, as explained in :ref:`dhcp-install-configure`. + +To use a PostgreSQL configuration backend you must compile the ``pgsql_cb`` open +source hook library and configre the DHCP servers to load it. It is compiled when +the ``--with-pgsql`` configuration switch is used during the Kea build. The PostgreSQL +C client libraries must be installed, as explained in :ref:`dhcp-install-configure`. .. note:: - Any existing MySQL schema must be upgraded to the latest schema + An existing database schema must be upgraded to the latest schema required by the particular Kea version using the ``kea-admin`` tool, as described in :ref:`kea-admin`. The ``cb_cmds`` premium hook library, which is available to ISC's paid support customers, provides a complete set of commands to manage the servers' configuration information within the database. This library can -be attached to both DHCPv4 and DHCPv6 server instances. It is +Be attached to both DHCPv4 and DHCPv6 server instances. While it is possible to manage the configuration information without the ``cb_cmds`` hook library with commonly available tools, such as MySQL Workbench or -the command-line MySQL client, by directly working with the database. +the command-line MySQL client, or by directly working with the database; +these avenues are neither recommended nor supported. Refer to :ref:`cb-cmds-library` for the details regarding the ``cb_cmds`` hook library. diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index aff1d5c88f..3a3f221bd2 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -6976,7 +6976,8 @@ at which it is currently supported. Enabling the Configuration Backend ---------------------------------- -Consider the following configuration snippet: +Consider the following configuration snippet, which uses a MySQL configuration +database: :: @@ -7011,6 +7012,30 @@ during startup or reconfiguration, and fetches the configuration available for this server from the database. This configuration is merged into the configuration read from the configuration file. +The following snippet illustrates the use of a PostgreSQL database: + +:: + + "Dhcp4": { + "server-tag": "my DHCPv4 server", + "config-control": { + "config-databases": [{ + "type": "postgresql", + "name": "kea", + "user": "kea", + "password": "kea", + "host": "192.0.2.1", + "port": 5432 + }], + "config-fetch-wait-time": 20 + }, + "hooks-libraries": [{ + "library": "/usr/local/lib/kea/hooks/libdhcp_pgsql_cb.so" + }, { + "library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so" + }], + } + .. note:: Whenever there is a conflict between the parameters specified in the @@ -7047,12 +7072,13 @@ The ``config-backend-pull`` command can be used to force the server to immediately poll any configuration changes from the database and avoid waiting for the next fetch cycle. -Finally, in the configuration example above, two hook libraries are -loaded. The first, ``libdhcp_mysql_cb.so``, is the implementation of -the Configuration Backend for MySQL. It must be always present when the -server uses MySQL as the configuration repository. Failing to load this -library will result in an error during the server configuration if the -"mysql" database is selected with the ``config-control`` parameter. +In the configuration examples above, two hook libraries are loaded. The first +is a library which implements the Configuration Backend for a specific database +type: ``libdhcp_mysql_cb.so`` provides support for MySQL and ``libdhcp_pgsql_cb.so`` +provides support for PostgreSQL. The library loaded must match the database +``type`` specified within the ``config-control`` parameter or an will error be +logged when the server attempts to load its configuration and the load will +fail. The second hook library, ``libdhcp_cb_cmds.so``, is optional. It should be loaded when the Kea server instance is to be used to manage the diff --git a/doc/sphinx/arm/hooks-cb-cmds.rst b/doc/sphinx/arm/hooks-cb-cmds.rst index ba414ab5ef..1ba162d605 100644 --- a/doc/sphinx/arm/hooks-cb-cmds.rst +++ b/doc/sphinx/arm/hooks-cb-cmds.rst @@ -8,10 +8,63 @@ servers' configurations in the Configuration Backends. This library must be used in conjunction with the available CB hooks libraries implementing the common APIs to create, read, update, and delete (CRUD) the configuration information in the respective databases. For example: -the ``mysql_cb`` hooks library implements this API for MySQL. In order to -manage the configuration information in the MySQL database, both the +the ``mysql_cb`` hooks library implements this API for MySQL while the +``pgsql_cg`` hooks library implements this API for PostgreSQL. In order to +manage the configuration information in a MySQL database, both the ``mysql_cb`` and ``cb_cmds`` libraries must be loaded by the server -used for the configuration management. +used for the configuration management. To manage configuration information +in a PostgreSQL database, both the ``pgsql_cb`` and ``cb_cmds`` libraries +must be loaded by the server used for the configuration management. + +The ``cb_cmds`` library is only available to ISC customers with a paid +support contract. + +.. note:: + + This library may only be loaded by the ``kea-dhcp4`` or + ``kea-dhcp6`` process. + +.. note:: + + Please read about :ref:`cb-limitations` before using the commands + described in this section. + +Commands Structure +~~~~~~~~~~~~~~~~~~ + +There are 5 types of commands supported by this library: + +- ``del`` - delete the selected object from the database, e.g. + ``remote-global-parameter4-del``. + +- ``get`` - fetch the selected object from the database, e.g. + ``remote-subnet4-get``. + +- ``get-all`` - fetch all objects of the particular type from the + database, e.g. ``remote-option-def4-get-all``. + +- ``list`` - list all objects of the particular type in the database, + e.g. ``remote-network4-list``; this class of commands returns brief + information about each object compared to the output of ``get-all``. + +- ``set`` - creates or replaces an object of the given type in the + database, e.g. ``remote-option4-global-set``. + +All types of commands accept an optional ``remote`` map which selects the +database instance to which the command refers. For example: + +.. code-block:: json + + { + "command": "remote-subnet4-list", + "arguments": { + "remote": { + "type": "mysql", + "host": "192.0.2.33", + "port": 3302 + } + } + } The ``cb_cmds`` library is only available to ISC customers with a paid support contract. @@ -75,10 +128,12 @@ the configuration of the server receiving the command. In the present Kea release, it is possible to configure the Kea server to use only one configuration backend. Strictly speaking, it is - possible to point the Kea server to at most one MySQL database using the - ``config-control`` parameter. That's why the ``remote`` parameter may - be omitted in the commands and the cb_cmds hooks library will use the - sole backend by default. + possible to point the Kea server to at most one database (either MySQL or + PostgreSQL) using the ``config-control`` parameter. That's why the ``remote`` + parameter may be omitted in the commands and the cb_cmds hooks library will use the + sole backend by default. The example command below most often show a value of + "mysql" for the ``type`` parameter. It should be assumed that a value + would be "postgresql" for installations using a PostgreSQL database. .. _cb-cmds-dhcp: @@ -170,7 +225,7 @@ insensitive server tag. For example: } ], "remote": { - "type": "mysql" + "type": "postgresql" } } }