</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>
projects / thirdparty / kea.git / commitdiff
