diff options
Diffstat (limited to 'doc/sphinx/arm/config-backend.rst')
| -rw-r--r-- | doc/sphinx/arm/config-backend.rst | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/doc/sphinx/arm/config-backend.rst b/doc/sphinx/arm/config-backend.rst new file mode 100644 index 0000000..58d6b1a --- /dev/null +++ b/doc/sphinx/arm/config-backend.rst @@ -0,0 +1,330 @@ +.. _config-backend: + +Kea Configuration Backend +========================= + +.. _cb-applicability: + +Applicability +------------- + +Kea Configuration Backend (CB or config backend) gives Kea servers the ability +to manage and fetch their configuration from one or more databases. In +this documentation, the term "Configuration Backend" may also refer to +the particular Kea module providing support to manage and fetch the +configuration information from the particular database type. For +example, the MySQL Configuration Backend is the logic implemented within the +``mysql_cb`` hook library, which provides a complete set of functions to +manage and fetch the configuration information from the MySQL database. +The PostgreSQL Configuration Backend is the logic implemented within the +``pgsql_cb`` hook library, which provides a complete set of functions to +manage and fetch the configuration information from the PostgreSQL database. +From herein, the term "database" is used to refer to either a MySQL or +PostgreSQL database. + +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 - in particular the database server, client and libraries. +Once the number of DHCP servers and/or the number of managed subnets in the +network grows, the usefulness of the CB becomes obvious. + +One use case for the CB is a pair of Kea DHCP servers that are configured +to support High Availability as described in +:ref:`hooks-high-availability`. The configurations of both servers +(including the value of the ``server-tag`` parameter) +are almost exactly the same: they may differ by the server identifier +and designation of the server as a primary or standby (or secondary), and/or +by their interfaces' configuration. Typically, the +subnets, shared networks, option definitions, and global parameters are the +same for both servers and can be sourced from a single database instance +to both Kea servers. + +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 are +automatically applied to both servers. + +Another case when the centralized configuration repository is useful is +in deployments including a large number of DHCP servers, possibly +using a common lease database to provide redundancy. New servers can +be added to the pool frequently to fulfill growing scalability +requirements. Adding a new server does not require replicating the +entire configuration to the new server when a common database is used. + +Using the database as a configuration repository for Kea servers also +brings other benefits, such as: + +- the ability to use database specific tools to access the configuration + information; + +- the ability to create customized statistics based on the information + stored in the database; and + +- the ability to backup the configuration information using the database's + built-in replication mechanisms. + +.. _cb-limitations: + +CB Capabilities and Limitations +------------------------------- + +Currently, the Kea CB has the following limitations: + +- It is only supported for MySQL and PostgreSQL databases. + +- It is only supported for the DHCPv4 and DHCPv6 daemons; the Control Agent, + D2 daemon, and the NETCONF daemon cannot be configured from the database, + +- Only certain DHCP configuration parameters can be set in the + database: global parameters, option definitions, global options, client + classes, shared networks, and subnets. Other configuration parameters + must be sourced from a JSON configuration file. + +Kea CB stores data in a schema that is public. It is possible to +insert configuration data into the tables manually or automatically +using SQL scripts, but this requires SQL and schema knowledge. +The supported method for managing the data is through the ``cb-cmds`` hook library, +which provides management commands for config backends. It simplifies many +typical operations, such as listing, adding, retrieving, and deleting global +parameters, shared networks, subnets, pools, options, option definitions, and +client classes. In addition, it provides essential business logic that ensures +the logical integrity of the data. See commands starting with ``remote-`` in +Appendix A of this manual for a complete list. + +.. note:: + + The ``cb_cmds`` hook library is available only to ISC support subscribers. + For more information on subscription options, please complete the form + at https://www.isc.org/contact. + + +The schema creation scripts can be found at `dhcpdb_create.mysql <https://gitlab.isc.org/isc-projects/kea/blob/master/src/share/database/scripts/mysql/dhcpdb_create.mysql>`__ and +; +`dhcpdb_create.pgsql <https://gitlab.isc.org/isc-projects/kea/blob/master/src/share/database/scripts/pgsql/dhcpdb_create.pgsql>`__ and +; +other related design documents are stored in our GitLab: `CB Design <https://gitlab.isc.org/isc-projects/kea/wikis/designs/configuration-in-db-design>`__ and +`Client Classes in CB Design <https://gitlab.isc.org/isc-projects/kea/wikis/designs/client-classes-in-cb>`__. + +We strongly recommend against duplication of configuration information +in both the file and the database. For example, when specifying subnets +for the DHCP server, please store them in either the configuration backend +or in the configuration file, not both. Storing some subnets in the database +and others in the file may put users at risk of potential configuration +conflicts. Note that the configuration instructions from the database take +precedence over instructions from the file, so parts of the configuration +specified in the file may be overridden if contradicted by information in +the database. + +Although it is not recommended, it is possible to specify certain parameter +types both in a configuration file and the database. For example, a subnet +can be specified in the configuration file and another subnet in the database; +in this case, the server will use both subnets. DHCP client classes, however, +must not be specified in both the configuration file and the database, even if +they do not overlap. If any client classes are specified in the database +for a particular DHCP server, this server will use these classes and ignore +all classes present in its configuration file. This behavior was introduced +to ensure that the server receives a consistent set of client classes +specified in an expected order with all inter-class dependencies fulfilled. +It is impossible to guarantee consistency when client classes are specified +in two independent configuration sources. + +.. note:: + + It is recommended that the ``subnet_cmds`` hook library not be used to + manage subnets when the configuration backend is used as a source + of information about the subnets. The ``subnet_cmds`` hook library + modifies the local subnets configuration in the server's memory, + not in the database. Use the ``cb_cmds`` hook library to manage the + subnets information in the database instead. + +.. note:: + + Using custom option formats requires creating definitions for these options. + Suppose a user wishes to set option data in the configuration backend. In + that case, we recommend specifying the definition for that option in the + configuration backend as well. It is essential when multiple servers are + managed via the configuration backend, and may differ in their + configurations. The option data parser can search for an option definition + appropriate for the server for which the option data is specified. + + In a single-server deployment, or when all servers share the same + configuration file information, it is possible to specify option + definitions in the configuration files and option data in the configuration + backend. The server receiving a command to set option data must have a + valid definition in its configuration file, even when it sets option data + for another server. + + It is not supported to specify option definitions in the configuration + backend and the corresponding option data in the server configuration files. + +CB Components +------------- + +To use a MySQL configuration backend you must compile the ``mysql_cb`` open +source hook library and configure the DHCP servers to load it. It is compiled when +the ``--with-mysql`` configuration switch is used during the Kea build. The MySQL +C client libraries must be installed, as explained in :ref:`dhcp-install-configure`. + +To use a PostgreSQL configuration backend you must compile the ``pgsql_cb`` open +source hook library and configure the DHCP servers to load it. It is compiled when +the ``--with-pgsql`` configuration switch is used during the Kea build. The PostgreSQL +C client libraries must be installed, as explained in :ref:`dhcp-install-configure`. + +.. note:: + + An existing database schema must be upgraded to the latest schema + required by the particular Kea version using the ``kea-admin`` tool, + as described in :ref:`kea-admin`. + +The ``cb_cmds`` premium hook library, which is available to ISC's paid support +customers, 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 instances. While it is +possible to manage the configuration information without the ``cb_cmds`` +hook library with commonly available tools, such as MySQL Workbench or +the command-line MySQL client, or by directly working with the database; +these avenues are neither recommended nor supported. + +Refer to :ref:`hooks-cb-cmds` for the details regarding the +``cb_cmds`` hook library. + +The DHCPv4 and DHCPv6 server-specific configurations of the CB, as well as +the list of supported configuration parameters, can be found in +:ref:`dhcp4-cb` and :ref:`dhcp6-cb`, respectively. + +.. _cb-sharing: + +Configuration Sharing and Server Tags +------------------------------------- + +The configuration database is designed to store configuration information +for multiple Kea servers. Depending on the use case, the entire configuration +may be shared by all servers; parts of the configuration may be shared by +multiple servers and the rest of the configuration may be different for these +servers; or each server may have its own non-shared configuration. + +The configuration elements in the database are associated with the servers +by "server tags." The server tag is an arbitrary string holding the name +of the Kea server instance. The tags of the DHCPv4 and DHCPv6 servers are +independent in the database, i.e. the same server tag can be created for +both the DHCPv4 and the DHCPv6 server. The value is configured +using the ``server-tag`` parameter in the Dhcp4 or Dhcp6 scope. The current +server tag can be checked with the ``server-tag-get`` command. + +The server definition, which consists of the server tag and the server +description, must be stored in the configuration database prior to creating +the dedicated configuration for that server. In cases when all servers use +the same configuration, e.g. a pair of servers running as High Availability +peers, there is no need to configure the server tags for these +servers in the database. + +Commands which contain the logical server `all` are applied to all servers +connecting to the database. The `all` server cannot be +deleted or modified, and it is not returned among other servers +as a result of the ``remote-server[46]-get-all`` command. + +In most cases, there are no server tags defined in the configuration +database; all connecting servers get the same configuration +regardless of the server tag they use. The server tag that a +particular Kea instance presents to the database to fetch its configuration +is specified in the Kea configuration file, using the +`config-control` map (please refer to the :ref:`dhcp4-cb-json` and +:ref:`dhcp6-cb-json` for details). All Kea instances presenting the same +server tag to the configuration database +are given the same configuration. + +It is the administrator's choice whether +multiple Kea instances use the same server tag or each Kea instance uses +a different server tag. There is no requirement that the instances +running on the same physical or virtual machine use the same server tag. It is +even possible to configure the Kea server without assigning it a server tag. +In such a case the server will be given the configuration specified for `all` +servers. + +To differentiate between different Kea server configurations, a +list of the server tags used by the servers must be stored in the +database. For the DHCPv4 and DHCPv6 servers, it can be done using the +commands described in :ref:`command-remote-server4-set` and +:ref:`command-remote-server6-set`. The +server tags can then be used to associate the configuration information with +the servers. However, it is important to note that some DHCP +configuration elements may be associated with multiple server tags (known +as "shareable" elements), while +other configuration elements may be associated with only one +server tag ("non-shareable" elements). The :ref:`dhcp4-cb` +and :ref:`dhcp6-cb` sections list the DHCP-specific shareable and +non-shareable configuration elements; however, in this section we +briefly explain the differences between them. + +A shareable configuration element is one which has some unique +property identifying it, and which may appear only once in +the database. An example of a shareable DHCP element is a subnet +instance: the subnet is a part of the network topology and we assume +that any particular subnet may have only one definition within this +network. Each subnet has two unique identifiers: the subnet identifier and the +subnet prefix. The subnet identifier is used in Kea to uniquely +identify the subnet within the network and to connect it with other configuration elements, +e.g. in host reservations. Some commands provided by the +``cb_cmds`` hook library allow the subnet +information to be accessed by either subnet identifier or prefix, and explicitly prohibit +using the server tag to access the subnet. This is because, in +general, the subnet definition is associated with multiple servers +rather than a single server. In fact, it may even be associated +with no servers (unassigned). Still, the unassigned subnet has an +identifier and prefix which can be used to access the subnet. + +A shareable configuration element may be associated with multiple +servers, one server, or no servers. Deletion of the server which is +associated with the shareable element does not cause the deletion of +the shareable element. It merely deletes the association of the +deleted server with the element. + +Unlike a shareable element, a non-shareable element must not be +explicitly associated with more than one server and must not exist +after the server is deleted (must not remain unassigned). A +non-shareable element only exists within the context of the server. +An example of a non-shareable element in DHCP is a global +parameter, e.g. `renew-timer`. The renew timer +is the value to be used by a particular server and only this +server. Other servers may have their respective renew timers +set to the same or different values. The renew timer +parameter has no unique identifier by which it could be +accessed, modified, or otherwise used. Global parameters like +the renew timer can be accessed by the parameter name and the +tag of the server for which they are configured. For example: +the commands described in :ref:`command-remote-global-parameter4-get` allow +the value of the global parameter to be fetched by the parameter name and +the server name. Getting the global parameter only by its name (without +specifying the server tag) is not possible, because there may be many +global parameters with a given name in the database. + +When the server associated with a non-shareable configuration element +is deleted, the configuration element is automatically deleted from +the database along with the server because the non-shareable element +must be always assigned to a server (or the logical server `all`). + +The terms "shareable" and "non-shareable" only apply to associations +with user-defined servers; all configuration elements associated with +the logical server `all` are by definition shareable. For example: the +`renew-timer` associated with `all` servers is used +by all servers connecting to the database which do not have their specific +renew timers defined. In a special case, when none of the configuration +elements are associated with user-defined servers, the entire +configuration in the database is shareable because all its pieces +belong to `all` servers. + +.. note:: + + Be very careful when associating configuration elements with + different server tags. The configuration backend does not protect + against some possible misconfigurations that may arise from the + wrong server tags' assignments. For example: if a shared + network is assigned to one server and the subnets belonging to this shared network + to another server, the servers will fail upon trying to fetch and + use this configuration. The server fetching the subnets will be + aware that the subnets are associated with the shared network, but + the shared network will not be found by this server since it doesn't + belong to it. In such a case, both the shared network and the subnets + should be assigned to the same set of servers. |