[#2322] Updated the ARM

doc/sphinx/arm/config-backend.rst
    doc/sphinx/arm/dhcp4-srv.rst

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
+configured - in particular the database server, client and libraries.
-number of DHCP servers and/or the number of managed subnets in the
+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
+- It is only supported for the DHCPv4 and DHCPv6 daemons; the Control Agent,
-  the NETCONF daemon cannot be configured from the database,
+  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
+Kea CB stores data in a schema that is public. It is possible to
-insert configuration data into the MySQL tables manually or automatically
+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 <https://gitlab.isc.org/isc-projects/kea/blob/master/src/share/database/scripts/mysql/dhcpdb_create.mysql>`__;
+The schema creation scripts can be found at `dhcpdb_create.mysql <https://gitlab.isc.org/isc-projects/kea/blob/master/src/share/database/scripts/mysql/dhcpdb_create.mysql>`__ and
+;
+`dhcpdb_create.pgsql <https://gitlab.isc.org/isc-projects/kea/blob/master/src/share/database/scripts/pgsql/dhcpdb_create.pgsql>`__ and
+;
 other related design documents are stored in our GitLab: `CB Design <https://gitlab.isc.org/isc-projects/kea/wikis/designs/configuration-in-db-design>`__ and
 `Client Classes in CB Design <https://gitlab.isc.org/isc-projects/kea/wikis/designs/client-classes-in-cb>`__.
 
@@ -154,25 +162,30 @@ in two independent configuration sources.
 CB Components
 -------------
 
-The ``mysql_cb`` open source hook library implementing the configuration
+To use a MySQL configuration backend you must compile the ``mysql_cb`` open
-backend for MySQL must be compiled and loaded by the DHCP servers. This
+source hook library and configre the DHCP servers to load it.  It is compiled when
-hook library is compiled when the ``--with-mysql`` configuration switch
+the ``--with-mysql`` configuration switch is used during the Kea build. The MySQL C
-is used during the Kea build. The MySQL C client libraries must be
+client libraries must be installed, as explained in :ref:`dhcp-install-configure`.
-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.

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
+In the configuration examples above, two hook libraries are loaded. The first 
-loaded. The first, ``libdhcp_mysql_cb.so``, is the implementation of
+is a library which implements the Configuration Backend for a specific database
-the Configuration Backend for MySQL. It must be always present when the
+type: ``libdhcp_mysql_cb.so`` provides support for MySQL and ``libdhcp_pgsql_cb.so``
-server uses MySQL as the configuration repository. Failing to load this
+provides support for PostgreSQL.  The library loaded must match the database
-library will result in an error during the server configuration if the
+``type`` specified within the ``config-control`` parameter or an will error be 
-"mysql" database is selected with the ``config-control`` parameter.
+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

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
+the ``mysql_cb`` hooks library implements this API for MySQL while the
-manage the configuration information in the MySQL database, both 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
+   possible to point the Kea server to at most one database (either MySQL or
-   ``config-control`` parameter. That's why the ``remote`` parameter may
+   PostgreSQL) using the ``config-control`` parameter. That's why the ``remote`` 
-   be omitted in the commands and the cb_cmds hooks library will use the
+   parameter may be omitted in the commands and the cb_cmds hooks library will use the
-   sole backend by default.
+   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"
             }
         }
     }