mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-30 21:45:37 +00:00
Code Issues Releases Wiki Activity

[#2322] Updated the ARM

Browse Source 
doc/sphinx/arm/config-backend.rst
    doc/sphinx/arm/dhcp4-srv.rst
This commit is contained in:
Thomas Markwalder
2022-02-22 10:30:35 -05:00
parent 2e5707aa6a
commit d5b7e8293a
3 changed files with 126 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
doc/sphinx/arm/config-backend.rst
View File

@@ -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 <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
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.

40
doc/sphinx/arm/dhcp4-srv.rst
View File

@@ -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

71
doc/sphinx/arm/hooks-cb-cmds.rst
View File

@@ -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"
}
}
}