mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-03 15:35:17 +00:00
Code Issues Releases Wiki Activity

[#71,!314] Added CB section to DHCPv4 configuration.

Browse Source
This commit is contained in:
Marcin Siodelski
2019-05-22 09:44:53 +02:00
parent 2c7f3338c7
commit e6330c948e
4 changed files with 201 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/guide/config-backend.xml
View File

@@ -6,7 +6,7 @@
- file, you can obtain one at http://mozilla.org/MPL/2.0/. - file, you can obtain one at http://mozilla.org/MPL/2.0/.
--> -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="config-backend"> <section xml:id="config-backend">
<title>Kea Configuration Backend</title> <title>Kea Configuration Backend</title>
<section xml:id="cb-applicability"> <section xml:id="cb-applicability">
@@ -153,4 +153,4 @@
</section> </section>
</chapter> </section>

19
doc/guide/config.xml
View File

@@ -151,22 +151,7 @@
</section> </section>
<section xml:id="cb"> <!-- Include large section about Kea Config Backend -->
<title>Database as a Configuration Source</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config-backend.xml"/>
<para>As of Kea 1.6.0 release, the parts of the DHCP servers'
configurations can be sourced from a database. The server using
the database as a configuration repository combines the configuration
specified for this server in the file (as described in the
<xref linkend="json"/>) with the configuration fetched from the
database. In this case the server configuration file must also contain
appropriate credentials and the location of the database holding this
supplementary configuration.</para>
<para>This feature is called Configuration Backend (sometimes
also Config Backend or CB for breivity) and is described in detail
in the further sections of this document.
</para>
</section>
</chapter> </chapter>

197
doc/guide/dhcp4-srv.xml
View File

@@ -5581,4 +5581,201 @@ autogenerated IDs are not stable across configuration changes.</para>
</section> </section>
<section id="dhcp4-cb">
<title>Configuration Backend in DHCPv4</title>
<para>
In the <xref linkend="config-backend"/> section we have introduced the
Configuration Backend feature, its applicability and limitations. This
section focuses on the usage of the CB with the DHCPv4 server. It lists
the supported parameters, describes limitations and gives examples of the
DHCPv4 server configuration to take advantage of the CB. Please also refer
to the sibling section <xref linkend="dhcp6-config-backend"/> for the
DHCPv6 specific usage of the CB.
</para>
<section id="dhcp4-cb-parameters">
<title>Supported Parameters</title>
<para>The ultimate goal for the CB is to serve as a central configuration
repository for one or multiple Kea servers connected to the database.
In the future it will be possible to store the most of the server configuration
in the database and it will be possible to reduce the configuration file
to a minimum, i.e. the only mandatory part of the configuration file will be
the <command>config-control</command> parameter which specifies the
neccessary information to connect to the database. In the Kea 1.6.0 release,
however, only the subset of the DHCPv4 server parameters can be stored
in the database. All other parameters must be specified in the JSON
configuration file, if required.</para>
<para>The following table lists DHCPv4 specific parameters supported by
the Configuration Backend with an indication on which level of the
hierarchy it is currently supported. The "n/a" tag is used in cases
when the particular parameter is not applicable on the particular
level of the hierarchy on in cases when the parameter is not supported
by the server on this level of hierarchy. The "no" tag is used when
the parameter is supported by the server on the particular level of
hierarchy but is not configurable via the Configuration Backend.
</para>
<para>All supported parameters can be configured via <command>cb_cmds</command>
hooks library described in the <xref linkend="cb-cmds-library"/>. The
general rule is that the scalar global parameters are set using the
<command>remote-global-parameter4-set</command>. The shared network
specific parameters are set using the <command>remote-network4-set</command>.
Finally, the subnet and pool level parameters are set using the
<command>remote-subnet4-set</command>. Whenever there is an exception from
this general rule, it is highlighted in the table. The non-scalar global
parameters have dedicated commands, e.g. modifying the global DHCPv4 options
(<command>option-data</command>) is performed using the
<command>remote-option4-global-set</command>.</para>
<para>
<table frame="all" xml:id="dhcp4-cb-parameters">
<title>List of DHCPv4 Options Supported by the Configuration Backend</title>
<tgroup cols="5">
<colspec colname="parameter"/>
<colspec colname="global" align="center"/>
<colspec colname="shared network" align="center"/>
<colspec colname="subnet" align="center"/>
<colspec colname="pool" align="center"/>
<thead>
<row>
<entry>Parameter</entry>
<entry>Global</entry>
<entry>Shared Network</entry>
<entry>Subnet</entry>
<entry>Pool</entry>
</row>
</thead>
<tbody>
<row><entry>4o6-interface</entry><entry>n/a</entry><entry>n/a</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>4o6-interface-id</entry><entry>n/a</entry><entry>n/a</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>4o6-subnet</entry><entry>n/a</entry><entry>n/a</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>boot-file-name</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>calculate-tee-times</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>client-class</entry><entry>n/a</entry><entry>yes</entry><entry>yes</entry><entry>no</entry></row>
<row><entry>decline-probation-period</entry><entry>yes</entry><entry>n/a</entry><entry>n/a</entry><entry>n/a</entry></row>
<row><entry>dhcp4o6-port</entry><entry>yes</entry><entry>n/a</entry><entry>n/a</entry><entry>n/a</entry></row>
<row><entry>echo-client-id</entry><entry>yes</entry><entry>n/a</entry><entry>n/a</entry><entry>n/a</entry></row>
<row><entry>interface</entry><entry>n/a</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>match-client-id</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>next-server</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>option-data</entry><entry>yes (via remote-option4-global-set)</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry></row>
<row><entry>option-def</entry><entry>yes (via remote-option-def4-set)</entry><entry>n/a</entry><entry>n/a</entry><entry>n/a</entry></row>
<row><entry>rebind-timer</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>renew-timer</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>server-hostname</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>valid-lifetime</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>relay</entry><entry>n/a</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>require-client-classes</entry><entry>no</entry><entry>yes</entry><entry>yes</entry><entry>no</entry></row>
<row><entry>reservation-mode</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>t1-percent</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
<row><entry>t2-percent</entry><entry>yes</entry><entry>yes</entry><entry>yes</entry><entry>n/a</entry></row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section id="dhcp4-cb-json">
<title>Enabling Configuration Backend</title>
<para>
Consider the following configuration snippet:
<screen>
{
"Dhcp4": {
"config-control": {
"config-databases": [
{
"type": "mysql",
"name": "kea",
"user": "kea",
"password": "kea",
"host": "192.0.2.1",
"port": 3302
}
],
"config-fetch-wait-time": 30
},
"hooks-libraries": [
{
"library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so"
},
{
"library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so"
}
],
...
}
}
</screen>
</para>
<para>
The <command>config-control</command> contains two parameters. The
<command>config-databases</command> is a list which contains one
element comprising database type, 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 <command>config-databases</command> list. The server
will connect to this database during the startup and reconfiguration and
will fetch the configuration available for this server from the database.
This configuration is merged into the configuration read from the
configuration file.</para>
<note>
<para>Whenever there is a conflict between the parameters specified
in the configuration file and the database, the parameters from the
database take precedence. We strongly recommend to avoid
duplicating parameters in the file and the database but this recommendation
is not enforced by the Kea servers. In particular, if the subnets
configuration is provided in the database, we recommend that all
subnets are specified in the database and no subnets are specified
in the configuration file. It is possible to specify the
subnets in both places, but that must be done with care. The subnets in
the configuration file with overlapping ids and/or prefixes with the
subnets from the database will be superseded by those from the database.
</para>
</note>
<para>
Once the Kea server is configured it starts periodically polling for
the configuration changes in the database. The frequency in which such
polling occurs is controlled by the <command>config-fetch-wait-time</command>
parameter. It is expressed in seconds and it is the period between the
time when the server completed last polling (and possibly the local
configuration update) and the time when it begins polling again. In
the example above, this period is set to 20 seconds. This means that
after adding a new configuration into the database (e.g. added new
subnet), it will take up to 20 seconds (plus the time needed to fetch
and apply the new configuration) before the server starts using this
subnet. The lower the <command>config-fetch-wait-time</command> value,
the shorter the time for the server to react to the incremental
configuration updates in the database. On the other hand, polling the
database too frequently may impact the DHCP server's performance because
the server needs to make at least one query to the database to discover
the pending configuration updates.The default value of the
<command>config-fetch-wait-time</command> is 30 seconds.
</para>
<para>
Finally, the configuration example above loads two hooks libraries. The
former, <filename>libdhcp_mysql_cb.so</filename>, is the implementation of
the Configuration Backend for MySQL. It must be always loaded 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 <command>config-control</command>
parameter.
</para>
<para>
The latter hooks library, <filename>libdhcp_cb_cmds.so</filename> is
optional. It should be loaded when the Kea server instance is to be used
for managing the configuration in the database. See the
<xref linkend="cb-cmds-library"/> for the details. Note that this hooks
library is only available to the ISC customers with a support contract.
</para>
</section>
</section>
</chapter> </chapter>

2
doc/guide/kea-guide.xml
View File

@@ -62,8 +62,6 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config-backend.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="keactrl.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="keactrl.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="agent.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="agent.xml"/>