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. The database by default includes the logical
-server `all`, which is used as a keyword to indicate that
-a particular piece of configuration must be shared between all servers
+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``
-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` hook library :ref:`cb-cmds-library`.
+as a result of the ``remote-server[46]-get-all`` command.
-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
+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).
+:ref:`dhcp6-cb-json` for details). All Kea instances presenting the same
+server tag to the configuration database
+are given the same configuration.
-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 is using
-a different server tag. Also, there is no requirement that the instances
+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"
+In such a case the server will be given the configuration specified for `all`
servers.
-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
+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`. Next, the
-server tags can be used to associate the configuration information with
+: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 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 :ref:`dhcp4-cb`
-and :ref:`dhcp6-cb` list the DHCP specific shareable and
-non-shareable configuration elements. However, in this section we
-want to briefly explain the difference between them.
-
-A 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
+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 and to connect it with other configuration elements,
-e.g. in host reservations. The subnet identifier uniquely identifies
-the subnet within the network. Some commands provided by the
-`cb_cmds` hook library allow for accessing the subnet
-information by subnet identifier (or prefix) and explicitly prohibit
-using the server tag to access the subnet. This is because, in a
-general case, the subnet definition is associated with multiple servers
+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
+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
+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). The
+after the server is deleted (must not remain unassigned). A
non-shareable element only exists within the context of the server.
-An example of the non-shareable element in DHCP is a global
+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 the particular server and only this
+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 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
+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 for
-fetching the value of the global parameter by the parameter name and
+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 the given name in the database.
+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 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: the
-`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
+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.
+belong to `all` servers.
.. note::
- Be very careful when associating the configuration elements with
- different server tags. The configuration backend doesn't protect
+ 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 as it doesn't
+ 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.
projects / thirdparty / kea.git / commitdiff
