From: Marcin Siodelski Date: Tue, 16 Jul 2019 14:59:03 +0000 (+0200) Subject: [#643,!421] Written section "Configuration Sharing and Server Tags". X-Git-Tag: Kea-1.6.0-beta2~19 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=738acc162f235af6a12a2affeb6857a3f5311705;p=thirdparty%2Fkea.git [#643,!421] Written section "Configuration Sharing and Server Tags". --- diff --git a/doc/guide/config-backend.xml b/doc/guide/config-backend.xml index b40674bc34..181d05cebb 100644 --- a/doc/guide/config-backend.xml +++ b/doc/guide/config-backend.xml @@ -176,7 +176,151 @@ and respectively. + + +
+ Configuration Sharing and Server Tags + + The configuration database is designed to store the 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, finally, 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 names of the DHCPv4 and DHCPv6 servers are + independent. If there are both types of servers running on the same machine, + the instances of these servers may have different names or the same name + depending on the administrator's choice. The uniqueness of the server tag + is only checked for the particular server type, i.e. server tags for the + DHCPv4 servers are unique but there may be an instance of the DHCPv4 server + carrying the same name as the instance of the DHCPv6 server. There is no + requirement that these DHCP instances are running on the same system. + It is even possible to have multiple DHCP servers using the same tag + when connecting to the configuration database. From the database perspective + they are treated as a single DHCP server instance. Using such configuration + is useful when one group of servers should get the same configuration and + some other group of servers should get a different configuration. + + + + 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 the High Availability + peers, there is no need to configure the server tags for these + servers in the database. The database by default includes the logical + server all, which is used as a keyword to indicate that + the particular piece of configuration must be shared between all servers + connecting to the database. The all server can't be + deleted or modified. It is not even returned among other servers + as a result of the remote-server[46]-get-all + commands. Also, slightly different rules may apply to "all" keyword + than to any user defined server when running the commands provided by + the cb_cmds hooks library + (see for details). + + + + + In the simplest case there are no server tags defined in the configuration + database and all connecting servers will get the same configuration + regardless of the server tag they are using. The server tag that the + 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 + and + for details). + + + + + In order to differentiate the configurations between the Kea servers, a + collection 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 and + . Next, the + server tags can 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 and + other configuration elements may be associated with exactly one + server tag. The former configuration elements are referred to as + shareable configuration elements and the latter are referred to as + non-shareable configuration elements. The + and list the DHCP specific shareable and + non-shareable configuration elements. However, in this section we + want to briefly explain the difference between them. + + + + The shareable configuration element is the one having some unique + property identifying it and which instance may appear only once in + the database. An example of the shareable DHCP element is a subnet + instance. The subnet is a part of the network topology and we assume + that the particular subnet may have only one definition within this + network. The subnet has two unique identifiers: subnet id and the + subnet prefix. The subnet identifier is used in Kea to uniquely + identify the subnet in many areas, e.g. in host reservations. The + subnet identifier uniquely identifies the subnet within the network. + Some commands provided by the cb_cmds hooks library + allow for accessing the subnet information by subnet identifier + (or prefix) and explicitly prohibit using the server tag to identify + the subnet. This is because, in a general case, the subnet definition + is not associated with a single server. In fact, it may even be associated + with no servers (unassigned) but still has an identifier and prefix + which uniquely identify 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 the shareable element, the 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). The + non-shareable element only exists within the context of the server. + An example of the non-shareable element in DHCP is a global + parameter, e.g. renew-timer. The renew timer + is the value to be used by the particular server and only this + server. Other servers may have their respective renew timers + set to the same or different value. The renew timer is the + parameter which has no unique identifier by which it could be + accessed, modified or otherwise used. The global parameters like + the renew timer can be accessed by their name and the server for + which they are configured. For example: the commands described in + allow for + fetching the value of the global parameter by parameter name and + the server name. Getting the global parameter only by its name is not + possible because there may be many global parameters with the given + name within 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 some server (or the logical server "all"). + + + + The terms "shareable" and "non-shareable" only apply to the associations + with user defined servers. All configuration elements associated with + the logical server "all" are by definition shareable. For example: a + renew-timer associated with "all" servers is used + by all servers connecting to the database which don't have their specific + renew timers defined. In the 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. +