mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-31 14:05:33 +00:00
[#71,!314] Added CB section to DHCPv4 configuration.
This commit is contained in:
Marcin Siodelski
@@ -6,7 +6,7 @@
|
||||
- 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>
|
||||
|
||||
<section xml:id="cb-applicability">
|
||||
@@ -153,4 +153,4 @@
|
||||
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
</section>
|
||||
|
||||
@@ -151,22 +151,7 @@
|
||||
|
||||
</section>
|
||||
|
||||
<section xml:id="cb">
|
||||
<title>Database as a Configuration Source</title>
|
||||
<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>
|
||||
<!-- Include large section about Kea Config Backend -->
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config-backend.xml"/>
|
||||
|
||||
</chapter>
|
||||
|
||||
@@ -5581,4 +5581,201 @@ autogenerated IDs are not stable across configuration changes.</para>
|
||||
|
||||
</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>
|
||||
|
||||
@@ -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-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="agent.xml"/>
|
||||
|
||||
Reference in New Issue
Block a user