diff --git a/doc/guide/config-backend.xml b/doc/guide/config-backend.xml index 562bdfdb56..944e4e82b2 100644 --- a/doc/guide/config-backend.xml +++ b/doc/guide/config-backend.xml @@ -6,7 +6,7 @@ - file, you can obtain one at http://mozilla.org/MPL/2.0/. --> - +
Kea Configuration Backend
@@ -153,4 +153,4 @@
- +
diff --git a/doc/guide/config.xml b/doc/guide/config.xml index b574797803..805c642c6b 100644 --- a/doc/guide/config.xml +++ b/doc/guide/config.xml @@ -151,22 +151,7 @@ -
- Database as a Configuration Source - 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 - ) 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. - - 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. - - -
+ + diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 506e22882b..887d300e6f 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -5581,4 +5581,201 @@ autogenerated IDs are not stable across configuration changes. +
+ Configuration Backend in DHCPv4 + + In the 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 for the + DHCPv6 specific usage of the CB. + + +
+ 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. + + 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. + + + All supported parameters can be configured via cb_cmds + hooks library described in the . The + general rule is that the scalar global parameters are set using the + remote-global-parameter4-set. The shared network + specific parameters are set using the remote-network4-set. + Finally, the subnet and pool level parameters are set using the + remote-subnet4-set. 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 + (option-data) is performed using the + remote-option4-global-set. + + + + List of DHCPv4 Options Supported by the Configuration Backend + + + + + + + + + Parameter + Global + Shared Network + Subnet + Pool + + + + 4o6-interfacen/an/ayesn/a + 4o6-interface-idn/an/ayesn/a + 4o6-subnetn/an/ayesn/a + boot-file-nameyesyesyesn/a + calculate-tee-timesyesyesyesn/a + client-classn/ayesyesno + decline-probation-periodyesn/an/an/a + dhcp4o6-portyesn/an/an/a + echo-client-idyesn/an/an/a + interfacen/ayesyesn/a + match-client-idyesyesyesn/a + next-serveryesyesyesn/a + option-datayes (via remote-option4-global-set)yesyesyes + option-defyes (via remote-option-def4-set)n/an/an/a + rebind-timeryesyesyesn/a + renew-timeryesyesyesn/a + server-hostnameyesyesyesn/a + valid-lifetimeyesyesyesn/a + relayn/ayesyesn/a + require-client-classesnoyesyesno + reservation-modeyesyesyesn/a + t1-percentyesyesyesn/a + t2-percentyesyesyesn/a + + +
+ +
+ +
+ Enabling Configuration Backend + + Consider the following configuration snippet: + +{ + "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" + } + ], + ... + } +} + + + + The config-control contains two parameters. The + config-databases 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 config-databases 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. + + + 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. + + + + + 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 + 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 config-fetch-wait-time 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 + config-fetch-wait-time is 30 seconds. + + + + 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 + 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 + parameter. + + + + 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 + library is only available to the ISC customers with a support contract. + + +
+ +
diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index bf3073456b..73e689fc65 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -62,8 +62,6 @@ - -