introduced in 1.6.0 release, which provides Kea servers with the
ability to manage and fetch their configuration from one or more
databases. In the documentation, the term "Configuration Backend"
- may also refer to the particular Kea module implementing support
+ may also refer to the particular Kea module providing support
to manage and fetch the configuration information from the particular
database type. For example: MySQL Configuration Backend is the logic
implemented within the "mysql_cb" hooks library which provides a
</para>
<para>
- In small deplyments, e.g. comprising a single DHCP server instance
+ 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, e.g. MySQL server, MySQL client. Once the number of
- DHCP servers and/or the number of managed subnets in the network
- grows, the usefulness of the CB gets obvious.
+ configured - in particular the MySQL server and MySQL client.
+ Once the number of DHCP servers and/or the number of managed
+ subnets in the network grows, the usefulness of the CB becomes
+ obvious.
</para>
<para>
A good example is a pair of the Kea DHCP servers which can be
configured to support High Availability as described in
<xref linkend="high-availability-library"/>.
- The configurations of both servers is almost exactly the same.
- It may differ by server identifier and designation of the
+ The configurations of both servers are almost exactly the same.
+ They may differ by the server identifier and designation of the
server as a primary or standby (or secondary). They may also
differ by the interfaces configuration. Typically, the subnets,
shared networks, option definitions, global parameters are
the same for both servers and can be sourced from a single
- database instance to both servers.
+ database instance to both Kea servers.
</para>
<para>
- Using a database as a single source of configuration for subnets
+ Using the database as a single source of configuration for subnets
and/or other configuration information supported by the CB has
the advantage that any modifications to the configuration in
the database is automatically applied to both servers.
<para>
Using the database as a configuration repository for Kea servers also
- brings other benefits such as:
+ brings other benefits, such as:
<itemizedlist>
- <listitem><simpara>ability to use database specific tools to access
+ <listitem><simpara>an ability to use database specific tools to access
the configuration information,</simpara></listitem>
- <listitem><simpara>ability to create customized statistics based
+ <listitem><simpara>an ability to create customized statistics based
on the information stored in the database,</simpara></listitem>
- <listitem><simpara>ability to backup the configuration information
- using database builtin replication mechanisms.</simpara></listitem>
+ <listitem><simpara>an ability to backup the configuration information
+ using the database builtin replication mechanisms.</simpara></listitem>
</itemizedlist>
</para>
<section xml:id="cb-limitations">
<title>CB Capabilities and Limitations</title>
<para>
- Kea CB has been first introduced in 1.6.0 release, but this
- implementation comes with a number of limitations caused by the
- overall complexity of this feature and the development time
- constraints. The fature will evolve over time and the new
+ Kea CB has been introduced in the 1.6.0 release, but this
+ implementation comes with a number of limitations being the
+ result of the overall complexity of this feature and the development
+ time constraints. This feature will evolve over time and the new
capabilities will be added in subsequent releases. In this
- section we present the limitations of the CB present in the
- current Kea release:
+ section we present the limitations of the CB, present in the
+ current Kea 1.6.0 release:
</para>
<itemizedlist>
<listitem><simpara>
Configuration to be stored for the DHCP servers includes: global parameters,
option definitions, global options, shared networks and subnets. Other
- configuration parameters aren't stored in the database at the moment. They
- have to be configured via the JSON configuration file.
+ configuration parameters are not stored in the database at the moment.
+ They have to be configured via the JSON configuration file.
</simpara></listitem>
<listitem><simpara>
It is not supported to differentiate configurations of multiple
particular database instance share the configuration stored in this
database. This limitation will be removed in Kea 1.6.0 final release.
</simpara></listitem>
-
</itemizedlist>
-
</section>
<section xml:id="cb-components">
<para>
In order to use the Kea CB feature, the Kea 1.6.0 version or later is
required. The <command>mysql_cb</command> open source hooks library
- implementing Configuration Backend for MySQL must be compiled and
+ implementing the Configuration Backend for MySQL must be compiled and
loaded by the DHCP servers. This hooks library is compiled when the
<filename>--with-mysql</filename> configuration switch is used during
Kea build. The MySQL C client libraries must be installed
<para>
The <command>cb_cmds</command> premium hooks library is available to
- our paid supported customers, which provides a complete set of commands
+ ISC paid supported customers, which 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 instance.
It is still possible to manage the configuration information without the
<command>cb_cmds</command> hooks library with commonly available tools
- such as MySQL Workbench or command line MySQL client by directly working
+ such as MySQL Workbench or command line MySQL client, by directly working
with the database.
</para>
the <command>cb_cmds</command> hooks library.
</para>
+ <para>
+ The DHCPv4 and DHCPv6 server specific configuration of the CB as well as
+ the list of supported configuration parameters can be found in the
+ <xref linkend="dhcp4-cb"/> and <xref linkend="dhcp6-cb"/>
+ respectively.
+ </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
+ In the <xref linkend="config-backend"/> we have described 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
<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>
+ In the future it will be possible to store the most of the server's configuration
+ in the database and reduce the configuration file to bare minimum, i.e.
+ the only mandatory parameter will be the <command>config-control</command>
+ which includes the necessary 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
+ hierarchy it is currently supported. The "n/a" 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
+ level of the hierarchy or in cases when the parameter is not supported
+ by the server on this level of hierarchy. The "no" 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>
"port": 3302
}
],
- "config-fetch-wait-time": 30
+ "config-fetch-wait-time": 20
},
"hooks-libraries": [
{
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 connect to this database during the startup or 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>
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
+ is not enforced by the Kea servers. In particular, if the subnets'
+ configuration is sourced from 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
</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
+ Once the Kea server is configured, it starts periodically polling for
+ the configuration changes in the database. The frequency of polling
+ 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
</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
+ Finally, in the configuration example above, two hooks libraries are loaded.
+ The former, <filename>libdhcp_mysql_cb.so</filename>, 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 <command>config-control</command>
</para>
<para>
- The latter hooks library, <filename>libdhcp_cb_cmds.so</filename> is
+ 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
<section id="dhcp6-cb">
<title>Configuration Backend in DHCPv6</title>
<para>
- In the <xref linkend="config-backend"/> section we have introduced the
+ In the <xref linkend="config-backend"/> we have described the
Configuration Backend feature, its applicability and limitations. This
section focuses on the usage of the CB with the DHCPv6 server. It lists
the supported parameters, describes limitations and gives examples of the
<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 DHCPv6 server parameters can be stored
- in the database. All other parameters must be specified in the JSON
- configuration file, if required.</para>
+ In the future it will be possible to store the most of the server's configuration
+ in the database and reduce the configuration file to bare minimum, i.e.
+ the only mandatory parameter will be the <command>config-control</command>
+ which includes the necessary 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 DHCPv6 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
+ hierarchy it is currently supported. The "n/a" 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
+ level of the hierarchy or in cases when the parameter is not supported
+ by the server on this level of hierarchy. The "no" 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>
"port": 3302
}
],
- "config-fetch-wait-time": 30
+ "config-fetch-wait-time": 20
},
"hooks-libraries": [
{
<title>cb_cmds: Configuration Backend Commands</title>
<para>
This section describes the <command>cb_cmds</command> hooks library
- which is used to manage Kea servers' configurations with the Configuration
- Backends. This library must be used in conjuction with available CB
- implementations, which provide the common APIs to create, read, update
+ which is used to manage Kea servers' configurations in the Configuration
+ Backends. This library must be used in conjuction 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 <command>mysql_cb</command> hooks library
- released in Kea 1.6.0 implements this API for MySQL. In order to manage
+ databases. For example: the <command>mysql_cb</command> hooks library,
+ released in Kea 1.6.0, implements this API for MySQL. In order to manage
the configuration information in the MySQL database both
<command>mysql_cb</command> and <command>cb_cmds</command> libraries
must be loaded by the server used for the configuration management.
.</simpara></listitem>
</itemizedlist>
- <para>All types commands accept optional <command>remote</command> map which
+ <para>All types of commands accept optional <command>remote</command> map which
selects the database instance to which the command refers. For example:
<screen>
{
</screen>
</para>
<para>
- selects the MySQL database running on host 192.0.2.33 and port 3302 to
+ selects the MySQL database, running on host 192.0.2.33 and port 3302, to
fetch the list of subnets from. All parameters in the
<command>remote</command> are optional. The <command>port</command>
parameter can be only specified in conjuction with the
<command>host</command>. If no parameters in the <command>remote</command>
parameter are to be specified, the parameter should be omitted. In this
- case the server will use the first backend listed in the
+ case, the server will use the first backend listed in the
<command>config-control</command> map within the configuration of the
server receiving the command.
</para>
<note>
<para>
- In the Kea 1.6.0 release, it is possible to configure Kea server to
- use only one configuration backend. Strictly speaking it is possible
+ In the Kea 1.6.0 release, it is possible to configure the Kea server to
+ use only one configuration backend. Strictly speaking, it is possible
to point Kea server to at most one MySQL database using the
- <command>config-control</command> parameter. That's why in this
- release the <command>remote</command> parameter may be omitted in
- the commands because the cb_cmds hooks library will by default use
+ <command>config-control</command> parameter. That's why, in this
+ release, the <command>remote</command> parameter may be omitted in
+ the commands because the cb_cmds hooks library will use by default
the sole backend.
</para>
</note>
<section id="cb-cmds-dhcp">
<title>Control Commands for DHCP Servers</title>
<para>This section describes and gives some examples of the control
- commands provided by the <command>cb_cmds</command> hooks library to manage
- the configuration information for the DHCPv4 and DHCPv6 server. Many of the
- commands are almost identical between DHCPv4 and DHCPv6, i.e. only differ by
+ commands implemented by the <command>cb_cmds</command> hooks library, to manage
+ the configuration information of the DHCPv4 and DHCPv6 servers. Many of the
+ commands are almost identical between DHCPv4 and DHCPv6, i.e. only differ by the
command name. Other commands slightly differ by the structure of the inserted
- data, e.g. structure of the IPv4 subnet information is different than the
+ data, e.g. the structure of the IPv4 subnet information is different than the
structure of the IPv6 subnet. Nevertheless, they still share the structure of
the command arguments and thus it makes sense to describe them together.</para>
- <para>In the following sections various commands are described and the
+ <para>In the following sections, various commands are described and the
usage examples are provided. In the sections jointly describing the DHCPv4 and
DHCPv6 variants of the particular command we sometimes use the following
notation - the <command>remote-subnet[46]-set</command> is the wildcard
<para>In addition, whenever the text in the subsequent sections refers to a
DHCP command or DHCP parameter, it refers to both DHCPv4 and DHCPv6
- case. The text specific to the particular server type refers to them as:
+ variants. The text specific to the particular server type refers to them as:
DHCPv4 command, DHCPv4 parameter, DHCPv6 command, DHCPv6 parameter etc.
</para>
<section id="cb-cmds-metadata">
<title>Metadata</title>
- <para>A typical response to the <command>get</command> or <command>list</command>
+ <para>The typical response to the <command>get</command> or <command>list</command>
command includes a list of returned objects (e.g. subnets) and each such
- object contains the <command>metadata</command> map including some
- database specific information for this object. In other words, the metadata
- is meant to contain any information about the fetched object which may be
- useful for the administrator, but is not the part of the object
- specification from the DHCP server standpoint. In the Kea 1.6.0 release, the
- metadata is limited to the <command>server-tag</command>, which describes
- the association of the object with the particular server. The server tag
- is always set to <command>all</command> in the Kea 1.6.0 beta release because
- this release does not provide API calls to make associatiions of the
- configuration objects with any specific servers, i.e. every object is
- associated with all servers using the particular database instance.
+ object contains the <command>metadata</command> map with some database specific
+ information describing this object. In other words, the metadata contains any
+ information about the fetched object which may be useful for the administrator,
+ but is not the part of the object specification from the DHCP server standpoint.
+ In the Kea 1.6.0 release, the metadata is limited to the
+ <command>server-tag</command>, which describescthe association of the object
+ with the particular server or all servers. The server tag is always set to
+ <command>all</command> in the Kea 1.6.0 beta release.
</para>
<para>The following is the example response to the <command>remote-network4-list</command>
- including the metadata:
+ command, which includes the metadata:
<screen>
{
"result": 0,
projects / thirdparty / kea.git / commitdiff
