mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-22 09:57:41 +00:00
Code Issues Releases Wiki Activity

[#3586] updated documentation

Browse Source
This commit is contained in:
Razvan Becheriu 2024-10-04 18:13:17 +03:00
parent 17b0dcfadb
commit 264b7100cb
40 changed files with 432 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/examples/kea4/all-keys-netconf.json
View File

@ -342,11 +342,11 @@
"parameters": { }
},
{
// The MySql host backend hook library required for host storage.
// The MySQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
},
{
// The PgSql host backend hook library required for host storage.
// The PostgreSQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
}
],

4
doc/examples/kea4/all-keys.json
View File

@ -436,11 +436,11 @@
"parameters": { }
},
{
// The MySql host backend hook library required for host storage.
// The MySQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
},
{
// The PgSql host backend hook library required for host storage.
// The PostgreSQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
}
],

14
doc/examples/kea4/backends.json
View File

@ -45,6 +45,13 @@
// "retry-on-startup": false,
// "connect-timeout": 3
// },
// Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to
// store leases in the MySQL Lease Database Backend.
// Specify the lease backend hook library location.
// {
// // the MySQL lease backend hook library required for lease storage.
// "library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
// },
// 3. PostgreSQL backend. Leases will be stored in PostgreSQL database. Make
// sure it is up, running and properly initialized. See kea-admin documentation
@ -66,6 +73,13 @@
// "retry-on-startup": false,
// "connect-timeout": 3
// },
// Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to
// store leases in the PostgreSQL Lease Database Backend.
// Specify the lease backend hook library location.
// {
// // the PostgreSQL lease backend hook library required for lease storage.
// "library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
// },
// Addresses will be assigned with a lifetime of 4000 seconds.
"valid-lifetime": 4000,

18
doc/examples/kea4/config-backend.json
View File

@ -1,6 +1,6 @@
// This is an example configuration file for the DHCPv4 server in Kea.
// It demonstrates how to enable Kea Configuration Backend using MySQL.
// It requires that libdhcp_mysql_cb.so library is available and
// It requires that libdhcp_mysql.so library is available and
// optionally libdhcp_cb_cmds.so hook library.
{ "Dhcp4":
@ -23,8 +23,11 @@
},
// This parameter controls how the server accesses the configuration
// database. Currently only one database type is available - "mysql".
// It requires that the libdhcp_mysql_cb.so hook library is loaded.
// database. Currently only two database types are available - "mysql" and
// "postgresql".
// Using "mysql" requires that the libdhcp_mysql.so hook library is loaded.
// If using "postgresql", then loading libdhcp_pgsql.so hook library is
// required.
"config-control": {
// A list of database backends to connect to. Currently, it is limited
// to a single backend.
@ -57,11 +60,16 @@
// Hooks libraries that enable configuration backend are loaded.
"hooks-libraries": [
// The libdhcp_mysql_cb.so is required to use MySQL Configuration
// The libdhcp_mysql.so is required to use MySQL Configuration
// Backend.
{
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so"
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql.so"
}
// If using PostgreSQL Configuration Backend, the "libdhcp_pgsql.so" is
// required.
// {
// "library": "/usr/local/lib/kea/hooks/libdhcp_pgsql.so"
// }
// The libdhcp_cb_cmds.so is optional. It allows for managing the
// configuration in the database. If this library is not loaded,
// the configuration can be managed directly using available

5
doc/examples/kea4/mysql-reservations.json
View File

@ -69,11 +69,12 @@
"key-file": "my-key",
"cipher-list": "AES"
},
// Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to
// store host reservations in the MySQL Host Database Backend.
// Specify the host backend hook library location.
"hooks-libraries": [
{
// the MySql host backend hook library required for host storage.
// the MySQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
}
],

5
doc/examples/kea4/pgsql-reservations.json
View File

@ -67,11 +67,12 @@
"host": "localhost"
}
],
// Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to
// store host reservations in the PostgreSQL Host Database Backend.
// Specify the host backend hook library location.
"hooks-libraries": [
{
// the PgSql host backend hook library required for host storage.
// the PostgreSQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
}
],

4
doc/examples/kea6/all-keys-netconf.json
View File

@ -284,11 +284,11 @@
"parameters": { }
},
{
// The MySql host backend hook library required for host storage.
// The MySQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
},
{
// The PgSql host backend hook library required for host storage.
// The PostgreSQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
}
],

4
doc/examples/kea6/all-keys.json
View File

@ -378,11 +378,11 @@
"parameters": { }
},
{
// The MySql host backend hook library required for host storage.
// The MySQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
},
{
// The PgSql host backend hook library required for host storage.
// The PostgreSQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
}
],

14
doc/examples/kea6/backends.json
View File

@ -45,6 +45,13 @@
// "retry-on-startup": false,
// "connect-timeout": 3
// },
// Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to
// store leases in the MySQL Lease Database Backend.
// Specify the lease backend hook library location.
// {
// // the MySQL lease backend hook library required for lease storage.
// "library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
// },
// 3. PostgreSQL backend. Leases will be stored in PostgreSQL database. Make
// sure it is up, running and properly initialized. See kea-admin documentation
@ -66,6 +73,13 @@
// "retry-on-startup": false,
// "connect-timeout": 3
// },
// Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to
// store leases in the PostgreSQL Lease Database Backend.
// Specify the lease backend hook library location.
// {
// // the PostgreSQL lease backend hook library required for lease storage.
// "library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
// },
// Addresses will be assigned with preferred and valid lifetimes
// being 3000 and 4000, respectively. Client is told to start

18
doc/examples/kea6/config-backend.json
View File

@ -1,6 +1,6 @@
// This is an example configuration file for the DHCPv4 server in Kea.
// It demonstrates how to enable Kea Configuration Backend using MySQL.
// It requires that libdhcp_mysql_cb.so library is available and
// It requires that libdhcp_mysql.so library is available and
// optionally libdhcp_cb_cmds.so hook library.
{ "Dhcp6":
@ -23,8 +23,11 @@
},
// This parameter controls how the server accesses the configuration
// database. Currently only one database type is available - "mysql".
// It requires that libdhcp_mysql_cb.so hook library is loaded.
// database. Currently only two database types are available - "mysql" and
// "postgresql".
// Using "mysql" requires that the libdhcp_mysql.so hook library is loaded.
// If using "postgresql", then loading libdhcp_pgsql.so hook library is
// required.
"config-control": {
// A list of database backends to connect to. Currently, it is limited
// to a single backend.
@ -57,11 +60,16 @@
// Hooks libraries that enable configuration backend are loaded.
"hooks-libraries": [
// The libdhcp_mysql_cb.so is required to use MySQL Configuration
// The libdhcp_mysql.so is required to use MySQL Configuration
// Backend.
{
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so"
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql.so"
}
// If using PostgreSQL Configuration Backend, the "libdhcp_pgsql.so" is
// required.
// {
// "library": "/usr/local/lib/kea/hooks/libdhcp_pgsql.so"
// }
// The libdhcp_cb_cmds.so is optional. It allows for managing the
// configuration in the database. If this library is not loaded,
// the configuration can be managed directly using available

5
doc/examples/kea6/mysql-reservations.json
View File

@ -57,11 +57,12 @@
"key-file": "my-key",
"cipher-list": "AES"
},
// Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to
// store host reservations in the MySQL Host Database Backend.
// Specify the host backend hook library location.
"hooks-libraries": [
{
// the MySql host backend hook library required for host storage.
// the MySQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
}
],

5
doc/examples/kea6/pgsql-reservations.json
View File

@ -54,11 +54,12 @@
"host": "localhost"
}
],
// Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to
// store host reservations in the PostgreSQL Host Database Backend.
// Specify the host backend hook library location.
"hooks-libraries": [
{
// the PgSql host backend hook library required for host storage.
// the PostgreSQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
}
],

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

@ -14,10 +14,10 @@ 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
example, the MySQL Configuration Backend is the logic implemented within
:ischooklib:`libdhcp_mysql_cb.so`, which provides a complete set of functions to
:ischooklib:`libdhcp_mysql.so`, 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
:ischooklib:`libdhcp_pgsql_cb.so`, which provides a complete set of functions to
:ischooklib:`libdhcp_pgsql.so`, which provides a complete set of functions to
manage and fetch the configuration information from the PostgreSQL database.
From here on, the term "database" is used to refer to either a MySQL or
PostgreSQL database.
@ -163,15 +163,17 @@ in two independent configuration sources.
CB Components
-------------
To use a MySQL configuration backend, :ischooklib:`libdhcp_mysql_cb.so`
must be compiled and the DHCP servers must be configured 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 MySQL configuration backend, :ischooklib:`libdhcp_mysql.so` must
be compiled and the DHCP servers must be configured 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, :ischooklib:`libdhcp_pgsql_cb.so` must
be compiled and the DHCP servers must be configured 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`.
To use a PostgreSQL configuration backend, :ischooklib:`libdhcp_pgsql.so` must
be compiled and the DHCP servers must be configured 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::

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

@ -660,6 +660,30 @@ error.
``host`` parameter is ``localhost``, but establishes a TCP connection
for ``127.0.0.1``.
Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to
store leases in the MySQL Lease Database Backend.
Specify the lease backend hook library location:
::
"Dhcp4": { "hooks-libraries": [
{
// the MySQL lease backend hook library required for lease storage.
"library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
}, ... ], ... }
Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to
store leases in the PostgreSQL Lease Database Backend.
Specify the lease backend hook library location.
::
"Dhcp4": { "hooks-libraries": [
{
// the PostgreSQL lease backend hook library required for lease storage.
"library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
}, ... ], ... }
.. _hosts4-storage:
@ -893,6 +917,30 @@ the parameter is not specified.
The ``readonly`` parameter is only supported for MySQL and
PostgreSQL databases.
Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to
store host reservations in the MySQL Host Database Backend.
Specify the lease backend hook library location:
::
"Dhcp4": { "hooks-libraries": [
{
// the MySQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
}, ... ], ... }
Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to
store host reservations in the PostgreSQL Host Database Backend.
Specify the lease backend hook library location.
::
"Dhcp4": { "hooks-libraries": [
{
// the PostgreSQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
}, ... ], ... }
Tuning Database Timeouts for Hosts Storage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -8289,25 +8337,15 @@ database:
},
"hooks-libraries": [
{
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so"
}, {
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql.so"
},
{
"library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so"
}
]
}
}
The ``config-control`` map contains two parameters. ``config-databases``
is a list that contains one element, which includes the database type, its location,
and the credentials to be used to connect to this database. (Note that
the parameters specified here correspond to the database specification
for the lease database backend and hosts database backend.) Currently
only one database connection can be specified on the
``config-databases`` list. The server connects to this database
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:
.. code-block:: json
@ -8323,21 +8361,33 @@ The following snippet illustrates the use of a PostgreSQL database:
"user": "kea",
"password": "kea",
"host": "192.0.2.1",
"port": 5432
"port": 3302
}
],
"config-fetch-wait-time": 20
},
"hooks-libraries": [
{
"library": "/usr/local/lib/kea/hooks/libdhcp_pgsql_cb.so"
}, {
"library": "/usr/local/lib/kea/hooks/libdhcp_pgsql.so"
},
{
"library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so"
}
]
}
}
The ``config-control`` map contains two parameters. ``config-databases``
is a list that contains one element, which includes the database type, its location,
and the credentials to be used to connect to this database. (Note that
the parameters specified here correspond to the database specification
for the lease database backend and hosts database backend.) Currently
only one database connection can be specified on the
``config-databases`` list. The server connects to this database
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.
.. note::
Whenever there is a conflict between the parameters specified in the
@ -8376,11 +8426,11 @@ waiting for the next fetch cycle.
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: :ischooklib:`libdhcp_mysql_cb.so` provides support for MySQL and :ischooklib:`libdhcp_pgsql_cb.so`
provides support for PostgreSQL. The library loaded must match the database
``type`` specified within the ``config-control`` parameter; otherwise an error
is logged when the server attempts to load its configuration, and the load
fails.
type: :ischooklib:`libdhcp_mysql.so` provides support for MySQL and
:ischooklib:`libdhcp_pgsql.so` provides support for PostgreSQL. The library
loaded must match the database ``type`` specified within the ``config-control``
parameter; otherwise an error is logged when the server attempts to load its
configuration, and the load fails.
The second hook library, :ischooklib:`libdhcp_cb_cmds.so`, is optional. It should
be loaded when the Kea server instance is to be used to manage the

81
doc/sphinx/arm/dhcp6-srv.rst
View File

@ -616,6 +616,30 @@ error.
``host`` parameter is ``localhost``, but establishes a TCP connection
for ``127.0.0.1``.
Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to
store leases in the MySQL Lease Database Backend.
Specify the lease backend hook library location:
::
"Dhcp6": { "hooks-libraries": [
{
// the MySQL lease backend hook library required for lease storage.
"library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
}, ... ], ... }
Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to
store leases in the PostgreSQL Lease Database Backend.
Specify the lease backend hook library location.
::
"Dhcp6": { "hooks-libraries": [
{
// the PostgreSQL lease backend hook library required for lease storage.
"library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
}, ... ], ... }
.. _hosts6-storage:
@ -849,6 +873,30 @@ the parameter is not specified.
The ``readonly`` parameter is only supported for MySQL and
PostgreSQL databases.
Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to
store host reservations in the MySQL Host Database Backend.
Specify the lease backend hook library location:
::
"Dhcp6": { "hooks-libraries": [
{
// the MySQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
}, ... ], ... }
Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to
store host reservations in the PostgreSQL Host Database Backend.
Specify the lease backend hook library location.
::
"Dhcp6": { "hooks-libraries": [
{
// the PostgreSQL host backend hook library required for host storage.
"library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
}, ... ], ... }
Tuning Database Timeouts for Hosts Storage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -8101,7 +8149,38 @@ database:
},
"hooks-libraries": [
{
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so"
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql.so"
},
{
"library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so"
}
]
}
}
The following snippet illustrates the use of a PostgreSQL database:
.. code-block:: json
{
"Dhcp6": {
"server-tag": "my DHCPv6 server",
"config-control": {
"config-databases": [
{
"type": "postgresql",
"name": "kea",
"user": "kea",
"password": "kea",
"host": "2001:db8:1::1",
"port": 3302
}
],
"config-fetch-wait-time": 20
},
"hooks-libraries": [
{
"library": "/usr/local/lib/kea/hooks/libdhcp_pgsql.so"
},
{
"library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so"

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

@ -4,19 +4,18 @@
``libdhcp_cb_cmds.so``: Configuration Backend Commands
======================================================
This hook library is used to manage Kea
servers' configurations in a configuration backend database. This library must
be used in conjunction with the available CB hook libraries implementing
the common APIs to create, read, update, and delete (CRUD) the
configuration information in the respective databases. For example:
:ischooklib:`libdhcp_mysql_cb.so` implements this API for MySQL while
:ischooklib:`libdhcp_pgsql_cb.so` implements this API for PostgreSQL.
This hook library is used to manage Kea servers' configurations in a
configuration backend database. This library must be used in conjunction with
the available CB hook libraries implementing the common APIs to create, read,
update, and delete (CRUD) the configuration information in the respective
databases. For example: :ischooklib:`libdhcp_mysql.so` implements this API for
MySQL while :ischooklib:`libdhcp_pgsql.so` implements this API for PostgreSQL.
To manage the configuration information in a MySQL database, both
:ischooklib:`libdhcp_mysql_cb.so` and :ischooklib:`libdhcp_cb_cmds.so`
must be loaded by the server used for configuration management.
:ischooklib:`libdhcp_mysql.so` and :ischooklib:`libdhcp_cb_cmds.so` must be
loaded by the server used for configuration management.
To manage the configuration information in a PostgreSQL database, both
:ischooklib:`libdhcp_pgsql_cb.so` and :ischooklib:`libdhcp_cb_cmds.so`
must be loaded by the server used for configuration management.
:ischooklib:`libdhcp_pgsql.so` and :ischooklib:`libdhcp_cb_cmds.so` must be
loaded by the server used for configuration management.
More information on how to configure the Configuration Backend hook library for
use with a MySQL or PostgreSQL database can be found in the :ref:`dhcp4-cb`

19
doc/sphinx/arm/hooks-cb-mysql.rst
View File

@ -1,19 +0,0 @@
.. ischooklib:: libdhcp_mysql_cb.so
.. _hooks-cb-mysql:
``libdhcp_mysql_cb.so``: Configuration Backend for MySQL
========================================================
This hook library works in conjunction with :ischooklib:`libdhcp_cb_cmds.so` to
implement the API to create, read, update, and delete (CRUD) the
configuration in a MySQL database. Please see :ref:`hooks-cb-cmds`
for more details.
.. note::
:ischooklib:`libdhcp_mysql_cb.so` is part of the open source code and is
available to every Kea user. However, this hook library only works
with :ischooklib:`libdhcp_cb_cmds.so`, which allows easy configuration
management with the use of API commands. :ischooklib:`libdhcp_cb_cmds.so`
is available only to ISC customers with a paid support contract; for more information
on subscription options, please complete the form at https://www.isc.org/contact.

19
doc/sphinx/arm/hooks-cb-pgsql.rst
View File

@ -1,19 +0,0 @@
.. ischooklib:: libdhcp_pgsql_cb.so
.. _hooks-cb-pgsql:
``libdhcp_pgsql_cb.so``: Configuration Backend for PostgreSQL
=============================================================
This hook library works in conjunction with :ischooklib:`libdhcp_cb_cmds.so` to
implement the API to create, read, update, and delete (CRUD) the
configuration in a PostgreSQL database. Please see :ref:`hooks-cb-cmds`
for more details.
.. note::
:ischooklib:`libdhcp_pgsql_cb.so` is part of the open source code and is
available to every Kea user. However, this hook library only works
with :ischooklib:`libdhcp_cb_cmds.so`, which allows easy configuration
management with the use of API commands. :ischooklib:`libdhcp_cb_cmds.so`
is available only to ISC customers with a paid support contract; for more information
on subscription options, please complete the form at https://www.isc.org/contact.

24
doc/sphinx/arm/hooks-mysql.rst Normal file
View File

@ -0,0 +1,24 @@
.. ischooklib:: libdhcp_mysql.so
.. _hooks-mysql:
``libdhcp_mysql.so``: Database Backend for MySQL
================================================
This hook library implements MySQL database storage for:
- Lease Backend
- Host Backend
- Configuration Backend
This hook library works in conjunction with :ischooklib:`libdhcp_cb_cmds.so` to
implement the API to create, read, update, and delete (CRUD) the configuration
in a MySQL database. Please see :ref:`hooks-cb-cmds` for more details.
.. note::
:ischooklib:`libdhcp_mysql.so` is part of the open source code and is
available to every Kea user. However, this hook library only works with
:ischooklib:`libdhcp_cb_cmds.so`, which allows easy configuration
management with the use of API commands. :ischooklib:`libdhcp_cb_cmds.so`
is available only to ISC customers with a paid support contract; for more
information on subscription options, please complete the form at
https://www.isc.org/contact.

24
doc/sphinx/arm/hooks-pgsql.rst Normal file
View File

@ -0,0 +1,24 @@
.. ischooklib:: libdhcp_pgsql.so
.. _hooks-pgsql:
``libdhcp_pgsql.so``: Database Backend for PostgreSQL
=====================================================
This hook library implements PostgreSQL database storage for:
- Lease Backend
- Host Backend
- Configuration Backend
This hook library works in conjunction with :ischooklib:`libdhcp_cb_cmds.so` to
implement the API to create, read, update, and delete (CRUD) the configuration
in a PostgreSQL database. Please see :ref:`hooks-cb-cmds` for more details.
.. note::
:ischooklib:`libdhcp_pgsql.so` is part of the open source code and is
available to every Kea user. However, this hook library only works with
:ischooklib:`libdhcp_cb_cmds.so`, which allows easy configuration
management with the use of API commands. :ischooklib:`libdhcp_cb_cmds.so`
is available only to ISC customers with a paid support contract; for more
information on subscription options, please complete the form at
https://www.isc.org/contact.

25
doc/sphinx/arm/hooks.rst
View File

@ -593,10 +593,12 @@ loaded by the correct process per the table below.
| | | which packets receive a response. The limit can be applied |
| | | per-client class or per-subnet. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`MySQL Configuration Backend <hooks-cb-mysql>` | Kea open | This hook library is an implementation of the Kea |
| | source | Configuration Backend for MySQL. It uses a MySQL database as |
| | | a repository for the Kea configuration information. Kea |
| | | servers use this library to fetch their configurations. |
| :ref:`MySQL Configuration Backend <hooks-mysql>` | Kea open | This hook library is an implementation of the Kea Lease, |
| | source | Host and Configuration Backend for MySQL. It uses a |
| | | MySQL database as a repository for the Kea leases, host |
| | | reservations and configuration information. Kea servers use |
| | | this library to fetch their configurations if Configuration |
| | | Backend is used. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`PerfMon <hooks-perfmon>` | Kea open | With this hook library, :iscman:`kea-dhcp4` and |
| CURRENTLY EXPERIMENTAL | source | :iscman:`kea-dhcp6` servers can track and report performance |
@ -606,11 +608,12 @@ loaded by the correct process per the table below.
| | source | perform ping checks of candidate lease addresses before |
| | customers | offering them to clients. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`PostgreSQL Configuration Backend <hooks-cb-pgsql>` | Kea open | This hook library is an implementation of the Kea |
| | source | Configuration Backend for PostgreSQL. It uses a PostgreSQL |
| | | database as a repository for the Kea configuration |
| | | information. Kea servers use this library to fetch their |
| | | configurations. |
| :ref:`PostgreSQL Database Backend <hooks-pgsql>` | Kea open | This hook library is an implementation of the Kea Lease, |
| | source | Host and Configuration Backend for PostgreSQL. It uses a |
| | | PostgreSQL database as a repository for the Kea leases, host |
| | | reservations and configuration information. Kea servers use |
| | | this library to fetch their configurations if Configuration |
| | | Backend is used. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`RADIUS <hooks-radius>` | ISC support | The RADIUS hook library allows Kea to interact with |
| | customers | RADIUS servers using access and accounting mechanisms. The |
@ -685,10 +688,10 @@ sections.
.. include:: hooks-lease-query.rst
.. include:: hooks-legal-log.rst
.. include:: hooks-limits.rst
.. include:: hooks-cb-mysql.rst
.. include:: hooks-mysql.rst
.. include:: hooks-perfmon.rst
.. include:: hooks-ping-check.rst
.. include:: hooks-cb-pgsql.rst
.. include:: hooks-pgsql.rst
.. include:: hooks-radius.rst
.. include:: hooks-rbac.rst
.. include:: hooks-run-script.rst

36
doc/sphinx/arm/logging.rst
View File

@ -374,7 +374,7 @@ libraries), or hook libraries (open source or premium).
| | | Forensic Logging |
| | | hook library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.mysql-cb-hooks``, | :ischooklib:`libdhcp_mysql_cb.so` | Used |
| ``kea-dhcp4.mysql-cb-hooks``, | :ischooklib:`libdhcp_mysql.so` | Used |
| ``kea-dhcp6.mysql-cb-hooks`` | open-source hook library | to log messages |
| | | related to the |
| | | operation of the |
@ -382,6 +382,22 @@ libraries), or hook libraries (open source or premium).
| | | Backend hook |
| | | library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.mysql-hb-hooks``, | :ischooklib:`libdhcp_mysql.so` | Used |
| ``kea-dhcp6.mysql-hb-hooks`` | open-source hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | MySQL Host |
| | | Backend hook |
| | | library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.mysql-lb-hooks``, | :ischooklib:`libdhcp_mysql.so` | Used |
| ``kea-dhcp6.mysql-lb-hooks`` | open-source hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | MySQL Lease |
| | | Backend hook |
| | | library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.options``, | core | Used by the DHCP |
| ``kea-dhcp6.options`` | | server to log |
| | | messages related to |
@ -437,7 +453,7 @@ libraries), or hook libraries (open source or premium).
| | | the operation of the Ping |
| | | Check hook library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.pgsql-cb-hooks``, | :ischooklib:`libdhcp_pgsql_cb.so` | Used |
| ``kea-dhcp4.pgsql-cb-hooks``, | :ischooklib:`libdhcp_pgsql.so` | Used |
| ``kea-dhcp6.pgsql-cb-hooks`` | open-source hook library | to log messages |
| | | related to the |
| | | operation of the |
@ -445,6 +461,22 @@ libraries), or hook libraries (open source or premium).
| | | Backend hook |
| | | library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.pgsql-hb-hooks``, | :ischooklib:`libdhcp_pgsql.so` | Used |
| ``kea-dhcp6.pgsql-hb-hooks`` | open-source hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | PostgreSQL Host |
| | | Backend hook |
| | | library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.pgsql-lb-hooks``, | :ischooklib:`libdhcp_pgsql.so` | Used |
| ``kea-dhcp6.pgsql-lb-hooks`` | open-source hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | PostgreSQL Lease |
| | | Backend hook |
| | | library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.run-script-hooks``, | :ischooklib:`libdhcp_run_script.so` | Used to log messages related |
| ``kea-dhcp6.run-script-hooks`` | open-source hook library | to the operation of the |
| | | Run Script hook library. |

4
doc/sphinx/arm/rst_arm_sources.mk
View File

@ -28,8 +28,8 @@ rst_arm_sources += arm/hooks-host-cmds.rst
rst_arm_sources += arm/hooks-lease-cmds.rst
rst_arm_sources += arm/hooks-lease-query.rst
rst_arm_sources += arm/hooks-limits.rst
rst_arm_sources += arm/hooks-cb-mysql.rst
rst_arm_sources += arm/hooks-cb-pgsql.rst
rst_arm_sources += arm/hooks-mysql.rst
rst_arm_sources += arm/hooks-pgsql.rst
rst_arm_sources += arm/hooks-legal-log.rst
rst_arm_sources += arm/hooks-perfmon.rst
rst_arm_sources += arm/hooks-ping-check.rst

4
doc/sphinx/conf.py
View File

@ -124,8 +124,8 @@ exclude_patterns = [
'arm/hooks-legal-log.rst',
'arm/hooks-gss-tsig.rst',
'arm/hooks-host-cmds.rst',
'arm/hooks-cb-mysql.rst',
'arm/hooks-cb-pgsql.rst',
'arm/hooks-mysql.rst',
'arm/hooks-pgsql.rst',
'arm/hooks-limits.rst',
'arm/hooks-rbac.rst',
'arm/hooks-run-script.rst',

5
src/bin/dhcp4/tests/config_parser_unittest.cc
View File

@ -7378,8 +7378,9 @@ TEST_F(Dhcp4ParserTest, configControlInfoNoFactory) {
// Should fail because "type=mysql" has no factories.
configure(config, CONTROL_RESULT_ERROR,
"during update from config backend database: "
"The type of the configuration backend: "
"'mysql' is not supported");
"The Kea server has not been compiled with support for database "
"type: mysql. Did you forget to use --with-mysql during "
"compilation or to load libdhcp_mysql hook library?");
}
// This test verifies that configuration control info gets populated.

5
src/bin/dhcp6/tests/config_parser_unittest.cc
View File

@ -8219,8 +8219,9 @@ TEST_F(Dhcp6ParserTest, configControlInfoNoFactory) {
// Should fail because "type=mysql" has no factories.
configure(config, CONTROL_RESULT_ERROR,
"during update from config backend database: "
"The type of the configuration backend: "
"'mysql' is not supported");
"The Kea server has not been compiled with support for database "
"type: mysql. Did you forget to use --with-mysql during "
"compilation or to load libdhcp_mysql hook library?");
}
// This test verifies that configuration control info gets populated.

4
src/bin/keactrl/kea-dhcp4.conf.pre
View File

@ -276,6 +276,10 @@
// "parameters": {
// "identifier-expression": "relay4[2].hex"
// }
// },
// {
// // the MySQL host backend hook library required for host storage.
// "library": "@libdir@/kea/hooks/libdhcp_mysql.so"
// }
// ],

4
src/bin/keactrl/kea-dhcp6.conf.pre
View File

@ -222,6 +222,10 @@
// "parameters": {
// "identifier-expression": "relay6[0].option[37].hex"
// }
// },
// {
// // the MySQL host backend hook library required for host storage.
// "library": "@libdir@/kea/hooks/libdhcp_mysql.so"
// }
// ],

2
src/hooks/dhcp/mysql/mysql_cb_dhcp4.h
View File

@ -19,7 +19,7 @@ namespace dhcp {
class MySqlConfigBackendDHCPv4Impl;
/// @brief Implementation of the MySql Configuration Backend for
/// @brief Implementation of the MySQL Configuration Backend for
/// Kea DHCPv4 server.
///
/// All POSIX times specified in the methods belonging to this

2
src/hooks/dhcp/mysql/mysql_cb_dhcp6.h
View File

@ -19,7 +19,7 @@ namespace dhcp {
class MySqlConfigBackendDHCPv6Impl;
/// @brief Implementation of the MySql Configuration Backend for
/// @brief Implementation of the MySQL Configuration Backend for
/// Kea DHCPv6 server.
///
/// All POSIX times specified in the methods belonging to this

2
src/hooks/dhcp/mysql/mysql_lease_mgr.cc
View File

@ -1823,7 +1823,7 @@ private:
my_bool user_context_null_; ///< Used when user context is null
};
/// @brief MySql derivation of the statistical lease data query
/// @brief MySQL derivation of the statistical lease data query
///
/// This class is used to recalculate lease statistics for MySQL
/// lease storage. It does so by executing a query which returns a result

2
src/hooks/dhcp/pgsql/pgsql_cb_dhcp4.h
View File

@ -19,7 +19,7 @@ namespace dhcp {
class PgSqlConfigBackendDHCPv4Impl;
/// @brief Implementation of the PgSql Configuration Backend for
/// @brief Implementation of the PostgreSQL Configuration Backend for
/// Kea DHCPv4 server.
///
/// All POSIX times specified in the methods belonging to this

2
src/hooks/dhcp/pgsql/pgsql_cb_dhcp6.h
View File

@ -19,7 +19,7 @@ namespace dhcp {
class PgSqlConfigBackendDHCPv6Impl;
/// @brief Implementation of the PgSql Configuration Backend for
/// @brief Implementation of the PostgreSQL Configuration Backend for
/// Kea DHCPv6 server.
///
/// All POSIX times specified in the methods belonging to this

2
src/hooks/dhcp/pgsql/pgsql_lease_mgr.cc
View File

@ -1335,7 +1335,7 @@ private:
//@}
};
/// @brief Base PgSql derivation of the statistical lease data query
/// @brief Base PostgreSQL derivation of the statistical lease data query
///
/// This class provides the functionality such as results storage and row
/// fetching common to fulfilling the statistical lease data query.

8
src/lib/config_backend/base_config_backend_mgr.h
View File

@ -162,6 +162,14 @@ public:
// No match?
if (index == factories_.end()) {
if ((db_type == "mysql") || (db_type == "postgresql")) {
std::string with = (db_type == "postgresql" ? "pgsql" : db_type);
isc_throw(db::InvalidType, "The Kea server has not been compiled with "
"support for configuration database type: " << db_type
<< ". Did you forget to use --with-"
<< with << " during compilation or to load libdhcp_"
<< with << " hook library?");
}
isc_throw(db::InvalidType, "The type of the configuration backend: '" <<
db_type << "' is not supported");
}

12
src/lib/dhcpsrv/database_backends.dox
View File

@ -23,13 +23,17 @@
- The MySQL lease manager uses the freely available MySQL as its backend
database. This is not included in Kea DHCP by default:
the \--with-mysql switch must be supplied to "configure" for support
to be compiled into the software.
the \--with-mysql switch must be supplied to "configure" for support to be
compiled into the software. This will also compile the "libdhcp_mysql.so" hook
library which must be loaded by adding it to the "hooks-libraries"
configuration parameter.
- The PostgreSQL lease manager uses the freely available PostgreSQL as its
backend database. This is not included in Kea DHCP by default:
the \--with-pgsql switch must be supplied to "configure" for
support to be compiled into the software.
the \--with-pgsql switch must be supplied to "configure" for support to be
compiled into the software. This will also compile the "libdhcp_pgsql.so" hook
library which must be loaded by adding it to the "hooks-libraries"
configuration parameter.
@section dhcpdb-instantiation Instantiation of Lease Managers

7
src/lib/dhcpsrv/host_data_source_factory.cc
View File

@ -49,10 +49,11 @@ HostDataSourceFactory::add(HostDataSourceList& sources,
if (index == map_.end()) {
if ((db_type == "mysql") || (db_type == "postgresql")) {
string with = (db_type == "postgresql" ? "pgsql" : db_type);
isc_throw(InvalidType, "The type of host backend: '" << db_type
<< "' is not compiled in. Did you forget to use --with-"
isc_throw(InvalidType, "The Kea server has not been compiled with "
"support for host database type: " << db_type
<< ". Did you forget to use --with-"
<< with << " during compilation or to load libdhcp_"
<< with << "_hb hook library?");
<< with << " hook library?");
}
isc_throw(InvalidType, "The type of host backend: '" <<
db_type << "' is not supported");

4
src/lib/dhcpsrv/lease_mgr_factory.cc
View File

@ -64,10 +64,10 @@ LeaseMgrFactory::create(const std::string& dbaccess) {
LOG_ERROR(dhcpsrv_logger, DHCPSRV_UNKNOWN_DB).arg(db_type);
string with = (db_type == "postgresql" ? "pgsql" : db_type);
isc_throw(InvalidType, "The Kea server has not been compiled with "
"support for database type: " << db_type
"support for lease database type: " << db_type
<< ". Did you forget to use --with-"
<< with << " during compilation or to load libdhcp_"
<< with << "_lb hook library?");
<< with << " hook library?");
}
// Get here on no match
LOG_ERROR(dhcpsrv_logger, DHCPSRV_UNKNOWN_DB).arg(parameters[type]);

2
src/lib/dhcpsrv/libdhcpsrv.dox
View File

@ -151,7 +151,7 @@ documentation.
@subsection postgreSQLHostMgr PostgreSQL Host Reservation Management
Storing and retrieving host reservations within a PostgreSQL schema is
provided by the class, \ref isc::dhcp::PgSqlHostDataSource, a derivation of
provided by the class, isc::dhcp::PgSqlHostDataSource, a derivation of
\ref isc::dhcp::BaseHostDataSource and is depicted in the following
class diagram:

8
src/share/api/status-get.json
View File

@ -25,7 +25,7 @@
" \"disabled-by-remote-command\": [],",
" \"disabled-by-user\": false,",
" \"globally-disabled\": false",
" }",
" },",
" \"extended-info-tables\": <whether relay information is held in lease tables>,",
" \"high-availability\": [",
" {",
@ -47,7 +47,7 @@
" \"in-touch\": <indicates if this server communicated with partner>,",
" \"last-scopes\": <list of scopes served by partner>,",
" \"last-state\": <HA state name of the partner>,",
" \"role\": <partner role>",
" \"role\": <partner role>,",
" \"server-name\": <name of the partner server>,",
" \"system-time\": <system time in format '%Y-%m-%d %H:%M:%S' on UTC timezone>,",
" \"unacked-clients\": <number of unacked clients>,",
@ -64,9 +64,9 @@
" \"sockets\": {",
" \"errors\": <list of errors received during the last attempt to open all sockets; only appears when status is failed or retrying>,",
" \"status\": <ready, retrying, or failed>",
" }",
" },",
" \"thread-pool-size\": 4,",
" \"uptime\": <uptime in seconds>,",
" \"uptime\": <uptime in seconds>",
" }",
"}"
],