From: Marcin Siodelski Date: Wed, 22 May 2019 14:16:30 +0000 (+0200) Subject: [#71,!314] Improved wording and corrected errors in the CB docs. X-Git-Tag: Kea-1.6.0-beta~55 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fb340125603ba500c4418f18e7e0c3fa2380b068;p=thirdparty%2Fkea.git [#71,!314] Improved wording and corrected errors in the CB docs. --- diff --git a/doc/guide/config-backend.xml b/doc/guide/config-backend.xml index 944e4e82b2..e28fa6f093 100644 --- a/doc/guide/config-backend.xml +++ b/doc/guide/config-backend.xml @@ -17,7 +17,7 @@ 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 @@ -26,30 +26,31 @@ - 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. A good example is a pair of the Kea DHCP servers which can be configured to support High Availability as described in . - 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. - 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. @@ -67,14 +68,14 @@ Using the database as a configuration repository for Kea servers also - brings other benefits such as: + brings other benefits, such as: - ability to use database specific tools to access + an ability to use database specific tools to access the configuration information, - ability to create customized statistics based + an ability to create customized statistics based on the information stored in the database, - ability to backup the configuration information - using database builtin replication mechanisms. + an ability to backup the configuration information + using the database builtin replication mechanisms. @@ -83,13 +84,13 @@
CB Capabilities and Limitations - 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: @@ -103,8 +104,8 @@ 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. It is not supported to differentiate configurations of multiple @@ -112,9 +113,7 @@ particular database instance share the configuration stored in this database. This limitation will be removed in Kea 1.6.0 final release. - -
@@ -122,7 +121,7 @@ In order to use the Kea CB feature, the Kea 1.6.0 version or later is required. The mysql_cb 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 --with-mysql configuration switch is used during Kea build. The MySQL C client libraries must be installed @@ -137,12 +136,12 @@ The cb_cmds 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 cb_cmds 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. @@ -151,6 +150,13 @@ the cb_cmds hooks library. + + The DHCPv4 and DHCPv6 server specific configuration of the CB as well as + the list of supported configuration parameters can be found in the + and + respectively. + +
diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 066336c0de..173b2988a5 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -5584,7 +5584,7 @@ autogenerated IDs are not stable across configuration changes.
Configuration Backend in DHCPv4 - In the section we have introduced the + In the 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 @@ -5597,21 +5597,20 @@ autogenerated IDs are not stable across configuration changes. Supported Parameters 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 config-control 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. + 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 config-control + 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. 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. @@ -5694,7 +5693,7 @@ autogenerated IDs are not stable across configuration changes. "port": 3302 } ], - "config-fetch-wait-time": 30 + "config-fetch-wait-time": 20 }, "hooks-libraries": [ { @@ -5717,7 +5716,7 @@ autogenerated IDs are not stable across configuration changes. 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 - 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. @@ -5727,8 +5726,8 @@ autogenerated IDs are not stable across configuration changes. 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 @@ -5738,10 +5737,10 @@ autogenerated IDs are not stable across configuration changes. - 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 config-fetch-wait-time - 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 config-fetch-wait-time 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 @@ -5758,9 +5757,9 @@ autogenerated IDs are not stable across configuration changes. - Finally, the configuration example above loads two hooks libraries. The - former, libdhcp_mysql_cb.so, 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, libdhcp_mysql_cb.so, 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 config-control @@ -5768,7 +5767,7 @@ autogenerated IDs are not stable across configuration changes. - The latter hooks library, libdhcp_cb_cmds.so is + The latter hooks library, libdhcp_cb_cmds.so, is optional. It should be loaded when the Kea server instance is to be used for managing the configuration in the database. See the for the details. Note that this hooks diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index a383bd3e32..3814911082 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -5646,7 +5646,7 @@ autogenerated IDs are not stable across configuration changes.
Configuration Backend in DHCPv6 - In the section we have introduced the + In the 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 @@ -5659,21 +5659,20 @@ autogenerated IDs are not stable across configuration changes. Supported Parameters 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 config-control 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. + 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 config-control + 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. 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. @@ -5758,7 +5757,7 @@ autogenerated IDs are not stable across configuration changes. "port": 3302 } ], - "config-fetch-wait-time": 30 + "config-fetch-wait-time": 20 }, "hooks-libraries": [ { diff --git a/doc/guide/hooks-cb-cmds.xml b/doc/guide/hooks-cb-cmds.xml index a191101952..b29c701c31 100644 --- a/doc/guide/hooks-cb-cmds.xml +++ b/doc/guide/hooks-cb-cmds.xml @@ -10,12 +10,12 @@ cb_cmds: Configuration Backend Commands This section describes the cb_cmds 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 mysql_cb hooks library - released in Kea 1.6.0 implements this API for MySQL. In order to manage + databases. For example: the mysql_cb 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 mysql_cb and cb_cmds libraries must be loaded by the server used for the configuration management. @@ -53,7 +53,7 @@ . - All types commands accept optional remote map which + All types of commands accept optional remote map which selects the database instance to which the command refers. For example: { @@ -69,25 +69,25 @@ - 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 remote are optional. The port parameter can be only specified in conjuction with the host. If no parameters in the remote 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 config-control map within the configuration of the server receiving the command. - 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 - config-control parameter. That's why in this - release the remote parameter may be omitted in - the commands because the cb_cmds hooks library will by default use + config-control parameter. That's why, in this + release, the remote parameter may be omitted in + the commands because the cb_cmds hooks library will use by default the sole backend. @@ -96,15 +96,15 @@
Control Commands for DHCP Servers This section describes and gives some examples of the control - commands provided by the cb_cmds 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 cb_cmds 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. - In the following sections various commands are described and the + 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 remote-subnet[46]-set is the wildcard @@ -113,29 +113,26 @@ 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.
Metadata - A typical response to the get or list + The typical response to the get or list command includes a list of returned objects (e.g. subnets) and each such - object contains the metadata 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 server-tag, which describes - the association of the object with the particular server. The server tag - is always set to all 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 metadata 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 + server-tag, which describescthe association of the object + with the particular server or all servers. The server tag is always set to + all in the Kea 1.6.0 beta release. The following is the example response to the remote-network4-list - including the metadata: + command, which includes the metadata: { "result": 0,