As mentioned in :ref:`agent-overview`, the CA can forward
received commands to the Kea servers for processing. For example,
-``config-get`` is sent to retrieve the configuration of one of the Kea
+:isccmd:`config-get` is sent to retrieve the configuration of one of the Kea
services. When the CA receives this command, including a ``service``
parameter indicating that the client wishes to retrieve the
configuration of the DHCPv4 server, the CA forwards the command to that
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.
+using the ``server-tag`` parameter in the ``Dhcp4`` or ``Dhcp6`` scope. The current
+server tag can be checked with the :isccmd:`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
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.
+as a result of the :isccmd:`remote-server4-get-all`, :isccmd:`remote-server6-get-all` commands.
In most cases, there are no server tags defined in the configuration
database; all connecting servers get the same configuration
are not part of JSON syntax, most JSON tools detect them as
errors. Another problem with them is that once Kea loads its configuration, the
shell, C, and C++ style comments are ignored. If commands such as
-``config-get`` or ``config-write`` are used, those comments are lost. An example of such
+:isccmd:`config-get` or :isccmd:`config-write` are used, those comments are lost. An example of such
comments was presented in the previous section.
Historically, to address the problem, Kea code allowed the use of `comment` strings
as valid JSON entities. This had the benefit of being retained through various
-operations (such as ``config-get``), or allowing processing by JSON tools. An
+operations (such as :isccmd:`config-get`), or allowing processing by JSON tools. An
example JSON comment looks like this:
::
converts JSON comments to user-context on the fly.
However, if the configuration uses the old JSON
-comment, the ``config-get`` command returns a slightly modified
-configuration. It is not uncommon for a call for ``config-set`` followed by a
-``config-get`` to receive a slightly different structure.
+comment, the :isccmd:`config-get` command returns a slightly modified
+configuration. It is not uncommon for a call for :isccmd:`config-set` followed by a
+:isccmd:`config-get` to receive a slightly different structure.
The best way to avoid this problem is simply to abandon JSON comments and
use user-context.
We encourage Kea users to utilize these functions to store information
used by other systems and custom hooks.
-For example, the ``subnet4-update`` command can be used to add user context data
+For example, the :isccmd:`subnet4-update` command can be used to add user context data
to an existing subnet.
::
If the command received by the CA does not include a ``service``
parameter or this list is empty, the CA simply processes this message on
-its own. For example, a ``config-get`` command which includes no service
-parameter returns the Control Agent's own configuration. The ``config-get``
+its own. For example, a :isccmd:`config-get` command which includes no service
+parameter returns the Control Agent's own configuration. The :isccmd:`config-get`
command with a service value "dhcp4" is forwarded to the DHCPv4 server and
returns the DHCPv4 server's configuration.
The ``build-report`` Command
----------------------------
-The ``build-report`` command returns on the control channel what the
+The :isccmd:`build-report` command returns on the control channel what the
command line ``-W`` argument displays, i.e. the embedded content of the
``config.report`` file. This command does not take any parameters.
The ``config-get`` Command
--------------------------
-The ``config-get`` command retrieves the current configuration used by the
+The :isccmd:`config-get` command retrieves the current configuration used by the
server. This command does not take any parameters. The configuration
returned is roughly equal to the configuration that was loaded using the
``-c`` command-line option during server start-up, or was later set using the
-``config-set`` command. However, there may be certain differences, as
+:isccmd:`config-set` command. However, there may be certain differences, as
comments are not retained. If the original configuration used file
inclusion, the returned configuration includes all parameters from
all included files.
The ``config-reload`` Command
-----------------------------
-The ``config-reload`` command instructs Kea to load again the
+The :isccmd:`config-reload` command instructs Kea to load again the
configuration file that was used previously. This operation is useful if
the configuration file has been changed by some external source; for
example, a system administrator can tweak the configuration file and use this
command to force Kea pick up the changes.
-Caution should be taken when mixing this with ``config-set`` commands. Kea
+Caution should be taken when mixing this with the :isccmd:`config-set` command. Kea
remembers the location of the configuration file it was started with,
-and this configuration can be significantly changed using the ``config-set``
-command. When ``config-reload`` is issued after ``config-set``, Kea attempts
+and this configuration can be significantly changed using the :isccmd:`config-set`
+command. When :isccmd:`config-reload` is issued after :isccmd:`config-set`, Kea attempts
to reload its original configuration from the file, possibly losing all
-changes introduced using ``config-set`` or other commands.
+changes introduced using :isccmd:`config-set` or other commands.
-The ``config-reload`` command does not take any parameters. An example command
+The :isccmd:`config-reload` command does not take any parameters. An example command
invocation looks like this:
::
The ``config-test`` Command
---------------------------
-The ``config-test`` command instructs the server to check whether the new
+The :isccmd:`config-test` command instructs the server to check whether the new
configuration supplied in the command's arguments can be loaded. The
supplied configuration is expected to be the full configuration for the
target server, along with an optional logger configuration. The configuration
is sanity-checked to the extent possible without the server actually
attempting to load it; it is possible for a configuration which successfully
-passes this command to still fail in the ``config-set`` command or at launch
+passes this command to still fail in the :isccmd:`config-set` command or at launch
time. The structure of the command is as follows:
::
The ``config-write`` Command
----------------------------
-The ``config-write`` command instructs the Kea server to write its current
+The :isccmd:`config-write` command instructs the Kea server to write its current
configuration to a file on disk. It takes one optional argument, called
"filename", that specifies the name of the file to write the
configuration to. If not specified, the name used when starting Kea
The ``leases-reclaim`` Command
------------------------------
-The ``leases-reclaim`` command instructs the server to reclaim all expired
+The :isccmd:`leases-reclaim` command instructs the server to reclaim all expired
leases immediately. The command has the following JSON syntax:
::
This command is now deprecated and will be removed in future Kea versions.
-The ``libreload`` command first unloads and then loads all currently
+The :isccmd:`libreload` command first unloads and then loads all currently
loaded hook libraries. This is primarily intended to allow one or more
hook libraries to be replaced with newer versions, without requiring Kea
servers to be reconfigured or restarted. The hook libraries
The ``list-commands`` Command
-----------------------------
-The ``list-commands`` command retrieves a list of all commands supported
+The :isccmd:`list-commands` command retrieves a list of all commands supported
by the server. It does not take any arguments. An example command may
look like this:
The ``config-set`` Command
--------------------------
-The ``config-set`` command instructs the server to replace its current
+The :isccmd:`config-set` command instructs the server to replace its current
configuration with the new configuration supplied in the command's
arguments. The supplied configuration is expected to be the full
configuration for the target server, along with an optional logger
The ``shutdown`` Command
------------------------
-The ``shutdown`` command instructs the server to initiate its shutdown
+The :isccmd:`shutdown` command instructs the server to initiate its shutdown
procedure. It is the equivalent of sending a ``SIGTERM`` signal to the
process. This command does not take any arguments. An example command
may look like this:
The ``dhcp-disable`` Command
----------------------------
-The ``dhcp-disable`` command globally disables the DHCP service. The
+The :isccmd:`dhcp-disable` command globally disables the DHCP service. The
server continues to operate, but it drops all received DHCP messages.
This command is useful when the server's maintenance requires that the
server temporarily stop allocating new leases and renew existing leases.
synchronization of the lease databases at startup, or recovery after a
failure. The optional parameter ``max-period`` specifies the time in
seconds after which the DHCP service should be automatically re-enabled,
-if the ``dhcp-enable`` command is not sent before this time elapses.
+if the :isccmd:`dhcp-enable` command is not sent before this time elapses.
Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
command source. A server administrator should typically omit this parameter
The ``dhcp-enable`` Command
---------------------------
-The ``dhcp-enable`` command globally enables the DHCP service.
+The :isccmd:`dhcp-enable` command globally enables the DHCP service.
Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
command source. A server administrator should typically omit this parameter
The ``status-get`` Command
--------------------------
-The ``status-get`` command returns the server's runtime information:
+The :isccmd:`status-get` command returns the server's runtime information:
- ``pid``: the process ID.
The ``high-availability`` information is returned only when the command is
sent to the DHCP servers in an HA setup. This parameter is
-never returned when the ``status-get`` command is sent to the
+never returned when the :isccmd:`status-get` command is sent to the
Control Agent or DDNS daemon.
The ``thread-pool-size``, ``packet-queue-size`` and
``packet-queue-statistics`` parameters are returned only when the
command is sent to DHCP servers with multi-threading enabled. These
three parameters and ``multi-threading-enabled`` are never returned when
-the ``status-get`` command is sent to the Control Agent or DDNS daemon.
+the :isccmd:`status-get` command is sent to the Control Agent or DDNS daemon.
To learn more about the HA status information returned by the
-``status-get`` command, please refer to the :ref:`command-ha-status-get`
+:isccmd:`status-get` command, please refer to the :ref:`command-ha-status-get`
section.
The ``server-tag-get`` Command:
-------------------------------
-The ``server-tag-get`` command returns the configured server tag of
+The :isccmd:`server-tag-get` command returns the configured server tag of
the DHCPv4 or DHCPv6 server (:ref:`cb-sharing` explains the server tag concept).
.. isccmd:: config-backend-pull
The ``config-backend-pull`` Command:
------------------------------------
-The ``config-backend-pull`` command triggers the polling of configuration backends
+The :isccmd:`config-backend-pull` command triggers the polling of configuration backends
(which must be configured for this command to have an effect),
explained in :ref:`dhcp4-cb-json`.
The ``version-get`` Command
---------------------------
-The ``version-get`` command returns extended information about the Kea
+The :isccmd:`version-get` command returns extended information about the Kea
version. It is the same information available via the ``-V``
command-line argument. This command does not take any parameters.
The D2 server supports only a subset of the DHCPv4/DHCPv6 server commands:
-- ``build-report``
+- :isccmd:`build-report`
-- ``config-get``
+- :isccmd:`config-get`
-- ``config-reload``
+- :isccmd:`config-reload`
-- ``config-set``
+- :isccmd:`config-set`
-- ``config-test``
+- :isccmd:`config-test`
-- ``config-write``
+- :isccmd:`config-write`
-- ``list-commands``
+- :isccmd:`list-commands`
-- ``shutdown``
+- :isccmd:`shutdown`
-- ``status-get``
+- :isccmd:`status-get`
-- ``version-get``
+- :isccmd:`version-get`
.. _agent-commands:
Control Agent; when the ``service`` parameter is blank, the
commands are handled by the CA and they relate to the CA process itself:
-- ``build-report``
+- :isccmd:`build-report`
-- ``config-get``
+- :isccmd:`config-get`
-- ``config-reload``
+- :isccmd:`config-reload`
-- ``config-set``
+- :isccmd:`config-set`
-- ``config-test``
+- :isccmd:`config-test`
-- ``config-write``
+- :isccmd:`config-write`
-- ``list-commands``
+- :isccmd:`list-commands`
-- ``shutdown``
+- :isccmd:`shutdown`
-- ``status-get``
+- :isccmd:`status-get`
-- ``version-get``
+- :isccmd:`version-get`
reconnected using the new configuration. If connectivity to any of the
backends cannot be established, the server logs a fatal error but remains
up. It is able to process commands but does not serve clients. This
-allows the configuration to be corrected via the ``config-set`` or
+allows the configuration to be corrected via the :isccmd:`config-set` or
``remote-*`` commands, if required.
During normal operations, if connectivity to any of the backends is lost and
The D2 server supports the following operational commands:
-- build-report
-- config-get
-- config-reload
-- config-set
-- config-test
-- config-write
-- list-commands
-- shutdown
-- status-get
-- version-get
+- :isccmd:`build-report`
+- :isccmd:`config-get`
+- :isccmd:`config-reload`
+- :isccmd:`config-set`
+- :isccmd:`config-test`
+- :isccmd:`config-write`
+- :isccmd:`list-commands`
+- :isccmd:`shutdown`
+- :isccmd:`status-get`
+- :isccmd:`version-get`
Since Kea version 2.0.0, the D2 server also supports the following
operational commands for statistics:
-- statistic-get
-- statistic-get-all
-- statistic-reset
-- statistic-reset-all
+- :isccmd:`statistic-get`
+- :isccmd:`statistic-get`-all
+- :isccmd:`statistic-reset`
+- :isccmd:`statistic-reset`-all
-The ``shutdown`` command supports the extra ``type`` argument, which controls the
+The :isccmd:`shutdown` command supports the extra ``type`` argument, which controls the
way the D2 server cleans up on exit.
The supported shutdown types are:
}
-Note that interfaces are not re-detected during ``config-test``.
+Note that interfaces are not re-detected during :isccmd:`config-test`.
Usually loopback interfaces (e.g. the ``lo`` or ``lo0`` interface) are not
configured, but if a loopback interface is explicitly configured and
Disabling conflict resolution should be done only after careful review of
specific use cases. The best way to avoid unwanted DNS entries is to
always ensure lease changes are processed through Kea, whether they are
- released, expire, or are deleted via the ``lease-del4`` command, prior to
+ released, expire, or are deleted via the :isccmd:`lease4-del` command, prior to
reassigning either FQDNs or IP addresses. Doing so causes :iscman:`kea-dhcp4`
to generate DNS removal requests to D2.
When using the default settings, the server returns a configuration error
when it finds two or more reservations for the same IP address within
a subnet in the Kea configuration file. The :ref:`hooks-host-cmds` hook
-library returns an error in response to the ``reservation-add`` command
+returns an error in response to the :isccmd:`reservation-add` command
when it detects that the reservation exists in the database for the IP
address for which the new reservation is being added.
The DHCPv4 server supports the following operational commands:
-- build-report
-- config-get
-- config-reload
-- config-set
-- config-test
-- config-write
-- dhcp-disable
-- dhcp-enable
-- leases-reclaim
-- list-commands
-- shutdown
-- status-get
-- version-get
+- :isccmd:`build-report`
+- :isccmd:`config-get`
+- :isccmd:`config-reload`
+- :isccmd:`config-set`
+- :isccmd:`config-test`
+- :isccmd:`config-write`
+- :isccmd:`dhcp-disable`
+- :isccmd:`dhcp-enable`
+- :isccmd:`leases-reclaim`
+- :isccmd:`list-commands`
+- :isccmd:`shutdown`
+- :isccmd:`status-get`
+- :isccmd:`version-get`
as described in :ref:`commands-common`. In addition, it supports the
following statistics-related commands:
-- statistic-get
-- statistic-reset
-- statistic-remove
-- statistic-get-all
-- statistic-reset-all
-- statistic-remove-all
-- statistic-sample-age-set
-- statistic-sample-age-set-all
-- statistic-sample-count-set
-- statistic-sample-count-set-all
+- :isccmd:`statistic-get`
+- :isccmd:`statistic-reset`
+- :isccmd:`statistic-remove`
+- :isccmd:`statistic-get`-all
+- :isccmd:`statistic-reset`-all
+- :isccmd:`statistic-remove`-all
+- :isccmd:`statistic-sample-age-set`
+- :isccmd:`statistic-sample-age-set`-all
+- :isccmd:`statistic-sample-count-set`
+- :isccmd:`statistic-sample-count-set`-all
as described in :ref:`command-stats`.
All supported parameters can be configured via the ``cb_cmds`` hook library
described in the :ref:`hooks-cb-cmds` section. The general rule is that
scalar global parameters are set using
-``remote-global-parameter4-set``; shared-network-specific parameters
-are set using ``remote-network4-set``; and subnet-level and pool-level
-parameters are set using ``remote-subnet4-set``. Whenever
+:isccmd:`remote-global-parameter4-set`; shared-network-specific parameters
+are set using :isccmd:`remote-network4-set`; and subnet-level and pool-level
+parameters are set using :isccmd:`remote-subnet4-set`. Whenever
there is an exception to this general rule, it is highlighted in the
table. Non-scalar global parameters have dedicated commands; for example,
the global DHCPv4 options (``option-data``) are modified using
-``remote-option4-global-set``. Client classes, together with class-specific
+:isccmd:`remote-option4-global-set`. Client classes, together with class-specific
option definitions and DHCPv4 options, are configured using the
-``remote-class4-set`` command.
+:isccmd:`remote-class4-set` command.
The :ref:`cb-sharing` section explains the concept of shareable
and non-shareable configuration elements and the limitations for
}
}
-The ``config-control`` command contains two parameters. ``config-databases``
+The ``config-control`` map contains two parameters. ``config-databases``
is a list that contains one element, which includes the database type, its location,
and the credentials to be used to connect to this database. (Note that
the parameters specified here correspond to the database specification
to the database to discover any pending configuration updates. The
default value of ``config-fetch-wait-time`` is 30 seconds.
-The ``config-backend-pull`` command can be used to force the server to
+The :isccmd:`config-backend-pull` command can be used to force the server to
immediately poll any configuration changes from the database and avoid
waiting for the next fetch cycle.
Disabling conflict resolution should be done only after careful review of
specific use cases. The best way to avoid unwanted DNS entries is to
always ensure lease changes are processed through Kea, whether they are
- released, expire, or are deleted via the ``lease-del6`` command, prior to
+ released, expire, or are deleted via the :isccmd:`lease6-del` command, prior to
reassigning either FQDNs or IP addresses. Doing so causes :iscman:`kea-dhcp6`
to generate DNS removal requests to D2.
returns a configuration error when it finds two or more reservations for
the same lease within a subnet in the Kea configuration file. The
:ref:`hooks-host-cmds` hook library returns an error in response to the
-``reservation-add`` command when it detects that the reservation exists
+:isccmd:`reservation-add` command when it detects that the reservation exists
in the database for the lease for which the new reservation is being added.
Similar to DHCPv4 (see :ref:`multiple-reservations-same-ip4`), the DHCPv6
The DHCPv6 server supports the following operational commands:
-- build-report
-- config-get
-- config-reload
-- config-set
-- config-test
-- config-write
-- dhcp-disable
-- dhcp-enable
-- leases-reclaim
-- list-commands
-- shutdown
-- status-get
-- version-get
+- :isccmd:`build-report`
+- :isccmd:`config-get`
+- :isccmd:`config-reload`
+- :isccmd:`config-set`
+- :isccmd:`config-test`
+- :isccmd:`config-write`
+- :isccmd:`dhcp-disable`
+- :isccmd:`dhcp-enable`
+- :isccmd:`leases-reclaim`
+- :isccmd:`list-commands`
+- :isccmd:`shutdown`
+- :isccmd:`status-get`
+- :isccmd:`version-get`
as described in :ref:`commands-common`. In addition, it supports the
following statistics-related commands:
-- statistic-get
-- statistic-reset
-- statistic-remove
-- statistic-get-all
-- statistic-reset-all
-- statistic-remove-all
-- statistic-sample-age-set
-- statistic-sample-age-set-all
-- statistic-sample-count-set
-- statistic-sample-count-set-all
+- :isccmd:`statistic-get`
+- :isccmd:`statistic-reset`
+- :isccmd:`statistic-remove`
+- :isccmd:`statistic-get`-all
+- :isccmd:`statistic-reset`-all
+- :isccmd:`statistic-remove`-all
+- :isccmd:`statistic-sample-age-set`
+- :isccmd:`statistic-sample-age-set`-all
+- :isccmd:`statistic-sample-count-set`
+- :isccmd:`statistic-sample-count-set`-all
as described in :ref:`command-stats`.
All supported parameters can be configured via the ``cb_cmds`` hook library
described in the :ref:`hooks-cb-cmds` section. The general rule is that
scalar global parameters are set using
-``remote-global-parameter6-set``; shared-network-specific parameters
-are set using ``remote-network6-set``; and subnet-level and pool-level
-parameters are set using ``remote-subnet6-set``. Whenever
+:isccmd:`remote-global-parameter6-set`; shared-network-specific parameters
+are set using :isccmd:`remote-network6-set`; and subnet-level and pool-level
+parameters are set using :isccmd:`remote-subnet6-set`. Whenever
there is an exception to this general rule, it is highlighted in the
table. Non-scalar global parameters have dedicated commands; for example,
the global DHCPv6 options (``option-data``) are modified using
-``remote-option6-global-set``. Client classes, together with class-specific
+:isccmd:`remote-option6-global-set`. Client classes, together with class-specific
option definitions and DHCPv6 options, are configured using the
-``remote-class6-set`` command.
+:isccmd:`remote-class6-set` command.
The :ref:`cb-sharing` section explains the concept of shareable
and non-shareable configuration elements and the limitations for
The server periodically deletes keys after they have been expired more than three times the
length of the maximum key lifetime (the ``tkey-lifetime`` parameter).
-The user has the option to purge keys on demand by using the ``gss-tsig-purge-all``
-command (see :ref:`command-gss-tsig-purge-all`) or the ``gss-tsig-purge`` command
+The user has the option to purge keys on demand by using the :isccmd:`gss-tsig-purge-all`
+command (see :ref:`command-gss-tsig-purge-all`) or the :isccmd:`gss-tsig-purge` command
(see :ref:`command-gss-tsig-purge`).
There are 5 types of commands supported by this library:
- ``del`` - delete the selected object from the database, e.g.
- ``remote-global-parameter4-del``.
+ :isccmd:`remote-global-parameter4-del`.
- ``get`` - fetch the selected object from the database, e.g.
``remote-subnet4-get``.
- ``get-all`` - fetch all objects of the particular type from the
- database, e.g. ``remote-option-def4-get-all``.
+ database, e.g. :isccmd:`remote-option-def4-get-all`.
- ``list`` - list all objects of the particular type in the database,
- e.g. ``remote-network4-list``; this class of commands returns brief
+ e.g. :isccmd:`remote-network4-list`; this class of commands returns brief
information about each object compared to the output of ``get-all``.
- ``set`` - creates or replaces an object of the given type in the
- database, e.g. ``remote-option4-global-set``.
+ database, e.g. :isccmd:`remote-option4-global-set`.
All types of commands accept an optional ``remote`` map which selects the
database instance to which the command refers. For example:
Nevertheless, they still share the structure of their command arguments
and thus it makes sense to describe them together.
-In the following sections, various commands are described and some 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 name for the
-two commands: ``remote-subnet4-set`` and ``remote-subnet6-set``.
-
In addition, whenever the text in the subsequent sections refers to a
DHCP command or DHCP parameter, it refers to both DHCPv4 and DHCPv6
variants. The text specific to the particular server type refers to them
describes the association of the object with a particular server or
all servers.
-The following is the example response to the ``remote-network4-list``
+The following is the example response to the :isccmd:`remote-network4-list`
command, which includes the metadata:
.. code-block:: json
preserved. If any of the shareable configuration elements was associated only
with the deleted server, this object becomes unassigned (orphaned). For
example: if a subnet has been created and associated with "server1" using
-the ``remote-subnet4-set`` command and "server1" is subsequently deleted, the
+the :isccmd:`remote-subnet4-set` command and "server1" is subsequently deleted, the
subnet remains in the database but no servers can use this subnet. The
-subnet can be updated using the ``remote-subnet4-set`` command, and can be
+subnet can be updated using the :isccmd:`remote-subnet4-set` command, and can be
associated with either another server or with all servers, using the special
server tag "all". Such a subnet can be also deleted from the database
-using the ``remote-subnet4-del-by-id`` or
-``remote-subnet4-del-by-prefix`` command, if it is no longer needed.
+using the :isccmd:`remote-subnet4-del-by-id` or
+:isccmd:`remote-subnet4-del-by-prefix` command, if it is no longer needed.
-The following is the successful response to the ``remote-server4-del`` command:
+The following is the successful response to the :isccmd:`remote-server4-del` command:
.. code-block:: json
.. warning::
- The ``remote-server4-del`` and ``remote-server6-del`` commands must be used with
+ The :isccmd:`remote-server4-del` and
+ :isccmd:`remote-server6-del` commands must be used with
care, because an accidental deletion of the server can cause some parts of the
existing configurations to be lost permanently from the database. This
operation is not reversible. Re-creation of the accidentally deleted server
(using server tags as identifiers), allowing only these servers to use the
respective configuration elements. Using the particular server tag to make such
associations is only possible when the server information has been stored in the
-database via the ``remote-server4-set`` or ``remote-server6-set`` commands. The
+database via the :isccmd:`remote-server4-set` or
+:isccmd:`remote-server6-set` commands. The
following command creates a new (or updates an existing) DHCPv6 server in the
database:
are specified in a single command, because it is possible that only some of the
parameters will be stored successfully and some will fail. If an error occurs when
processing this command, it is recommended to use
-``remote-global-parameter[46]-get-all`` to check which of the parameters have
+:isccmd:`remote-global-parameter4-get-all` or
+:isccmd:`remote-global-parameter6-get-all`
+to check which of the parameters have
been stored/updated successfully and which have failed.
The ``server-tags`` list is mandatory and must contain a single server tag or
deletes the "level3" IPv6 shared network. The subnets are preserved, but
they are disassociated from the deleted shared network and become
global. This behavior corresponds to the behavior of the
-``network[46]-del`` commands with respect to the ``subnets-action`` parameter.
+:isccmd:`network4-del`, :isccmd:`network6-del` commands with respect to the
+``subnets-action`` parameter.
Note that the ``server-tags`` parameter cannot be used for this command.
The returned information about each shared network merely contains the shared
network name and the metadata. To fetch detailed information about
-the selected shared network, use the ``remote-network[46]-get`` command.
+the selected shared network, use the :isccmd:`remote-network4-get` or
+:isccmd:`remote-network6-get` command.
The example response above contains three shared networks. One of the
shared networks is associated with all servers, so it is included in
These commands are intended to be used for managing the shared
network-specific information and DHCP options. To associate and
disassociate the subnets with the shared networks, the
-``remote-subnet[46]-set`` commands should be used.
+:isccmd:`remote-subnet4-set`, :isccmd:`remote-subnet6-set`
+commands should be used.
The following command adds the IPv6 shared network "level3" to the
database:
option may be present for a subnet belonging to the shared network.
Such an option instance is not affected by this command as this
command merely deletes the shared-network level option. To
-delete a subnet-level option, the ``remote-option[46]-subnet-del``
-command must be used instead.
+delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`,
+:isccmd:`remote-option6-subnet-del` commands must be used instead.
The following command attempts to delete an option having the
option code 5 in the top-level option space from the shared
.. isccmd:: remote-option6-pd-pool-del
.. _command-remote-option6-pd-pool-del:
-The ``remote-option6-pd-pool-del`` Command
+The remote-option6-pd-pool-del Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to delete a prefix delegation pool-specific DHCPv6
the specified pool. Such an option instance is not affected by this
command, as this command merely deletes a prefix delegation pool-level
option. To delete a subnet level option, the
-``remote-option6-subnet-del`` command must be used instead.
+:isccmd:`remote-option6-subnet-del` command must be used instead.
.. code-block:: json
.. isccmd:: remote-option6-pd-pool-set
.. _command-remote-option6-pd-pool-set:
-The ``remote-option6-pd-pool-set`` Command
+The remote-option6-pd-pool-set Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command creates a new prefix delegation pool-specific DHCPv6 option or
In particular, the given option may exist for a subnet containing
the specified pool. Such an option instance is not affected by this
command, as this command merely deletes a pool-level option. To
-delete a subnet-level option, the ``remote-option[46]-subnet-del``
-command must be used instead.
+delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`,
+:isccmd:`remote-option6-subnet-del` commands must be used instead.
The following command attempts to delete an option having the
option code 5 in the top-level option space from an IPv4 address
The returned information about each subnet is limited to the subnet identifier,
prefix, and associated shared network name. To retrieve full
information about the selected subnet, use
-``remote-subnet[46]-get-by-id`` or
-``remote-subnet[46]-get-by-prefix``.
+the :isccmd:`remote-subnet4-get-by-id`, :isccmd:`remote-subnet6-get-by-id` commands
+or the :isccmd:`remote-subnet4-get-by-prefix`, :isccmd:`remote-subnet6-get-by-prefix` commands.
The example response above contains two subnets. One of the subnets is
associated with both servers: "server1" and "server2". The second subnet is
The structure of the subnet information is similar to the structure used
in the configuration file (see :ref:`dhcp4-configuration` and
:ref:`dhcp6-configuration`). The subnet information conveyed in the
-``remote-subnet[46]-set`` command must include the additional parameter
+:isccmd:`remote-subnet4-set`, :isccmd:`remote-subnet6-set` commands
+must include the additional parameter
``shared-network-name``, which denotes whether the subnet belongs to a
shared network.
}
It creates the subnet and associates it with the "level3" shared
-network. The "level3" shared network must be created with the ``remote-network4-set``
+network. The "level3" shared network must be created with the :isccmd:`remote-network4-set`
command prior to creating the subnet.
If the created subnet must be global - that is, not associated with any shared
subnet having the same parameters, but it becomes global.
The ``shared-network-name`` parameter is mandatory for the
-``remote-subnet4-set`` command. The ``server-tags`` list is mandatory and must
+:isccmd:`remote-subnet4-set` command. The ``server-tags`` list is mandatory and must
include one or more server tags. As a result, the subnet is associated with all
of the listed servers. It may also be associated with all servers connecting
to the database when the keyword "all" is used as the server tag.
classes in the database depend on the deleted class, an error is returned in
response to this command. In this case, to successfully delete the class,
the dependent client classes must be deleted first. Use the
-``remote-class4-get-all`` command to fetch all client classes and find
+:isccmd:`remote-class4-get-all` command to fetch all client classes and find
the dependent ones.
.. code-block:: json
The ``class-add`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``class-add`` command adds a new client class to the DHCP server
+The :isccmd:`class-add` command adds a new client class to the DHCP server
configuration. This class is appended at the end of the list of classes
used by the server and may depend on any of the already-configured
client classes.
Note that the ``client-classes`` parameter is a JSON list, but it allows
only a single client class to be present.
-Here is the response to the ``class-add`` command in our example:
+Here is the response to the :isccmd:`class-add` command in our example:
::
The ``class-update`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``class-update`` command updates an existing client class in the
+The :isccmd:`class-update` command updates an existing client class in the
DHCP server configuration. If the client class with the given name
does not exist, the server returns the result code of 3, which means that
the server configuration is not modified and the client class does not
-exist. The ``class-add`` command must be used instead to create the new
+exist. The :isccmd:`class-add` command must be used instead to create the new
client class.
-The ``class-update`` command has the same argument structure as the
-``class-add`` command:
+The :isccmd:`class-update` command has the same argument structure as the
+:isccmd:`class-add` command:
::
except ``name``. There is currently no way to rename the class, because
the class name is used as a key for searching the class to be updated.
To achieve a similar effect to renaming the class, an existing class can
-be removed with the ``class-del`` command and then added again with a
-different name using ``class-add``. Note, however, that the class with
+be removed with the :isccmd:`class-del` command and then added again with a
+different name using :isccmd:`class-add`. Note, however, that the class with
the new name will be added at the end of the list of configured classes.
As with other update commands, this command overwrites all the contents of the
entry. If the client class previously had a resource assigned to it, and the
-``class-update`` command is missing the resource, it is deleted from the server
+:isccmd:`class-update` command is missing the resource, it is deleted from the server
configuration. If an incremental update of the class is desired, then this can
-be achieved by doing a `class-get <command-class-get_>`_ to get the current state
+be achieved by doing a :isccmd:`class-get` to get the current state
of the client class, picking the client class out of the response, modifying it
to the required outcome, and then issuing the ``client-update`` command with the
resulting client class attached.
~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``class-del`` command is used to remove a particular class from the server
+The :isccmd:`class-del` command is used to remove a particular class from the server
configuration. The class to be removed is identified by name. The class
is not removed if there are other classes depending on it; to remove
such a class, the dependent classes must be removed first.
}
}
-Here is the response to the ``class-del`` command in our example, when
+Here is the response to the :isccmd:`class-del` command in our example, when
the specified client class has been found:
::
~~~~~~~~~~~~~~~~~~~~~~~~~~
-``class-list`` is used to retrieve a list of all client classes. This
+:isccmd:`class-list` is used to retrieve a list of all client classes. This
command includes no arguments:
::
Note that the returned list does not contain full class definitions, but
merely class names. To retrieve full class information, the
-``class-get`` command should be used.
+:isccmd:`class-get` command should be used.
.. isccmd:: class-get
.. _command-class-get:
The ``class-get`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~
-``class-get`` is used to retrieve detailed information about a specified
+:isccmd:`class-get` is used to retrieve detailed information about a specified
class. The command structure is very simple:
::
}]
}
+<<<<<<< HEAD
The ``ddns-tuning`` library notes the presence of the "SKIP_DDNS" class in the
+||||||| parent of 0e20e5ed8c (isccmd)
+:ischooklib:`libdhcp_ddns_tuning.so` notes the presence of the ``"SKIP_DDNS"`` class in the
+=======
+The :ischooklib:`libdhcp_ddns_tuning.so` hook library notes the presence of the ``"SKIP_DDNS"`` class in the
+>>>>>>> 0e20e5ed8c (isccmd)
client's class list each time the client requests, renews, or releases its lease,
and instructs :iscman:`kea-dhcp4` to bypass sending DDNS updates. A similar workflow is
supported for :iscman:`kea-dhcp6`:
.. note::
- The ``ddns-tuning`` hook library must be loaded for the "SKIP_DDNS" class
- to have an effect.
+ The :ischooklib:`libdhcp_ddns_tuning.so` hook library must be
+ loaded for the ``"SKIP_DDNS"`` class to have an effect.
~~~~~~~~~~~~~
A DHCP server operating within an HA setup runs a state machine, and the state
-of the server can be retrieved by its peers using the ``ha-heartbeat`` command
+of the server can be retrieved by its peers using the :isccmd:`ha-heartbeat` command
sent over the RESTful API. If the partner server does not respond to the
-``ha-heartbeat`` command within the specified amount of time, the communication
+:isccmd:`ha-heartbeat` command within the specified amount of time, the communication
is considered interrupted and the server may, depending on the configuration,
use additional measures (described later in this document) to verify that the
partner is still operating. If it finds that the partner is not operating, the
server transitions to the ``partner-down`` state to handle all the DHCP traffic
directed to the system.
-In this case, the surviving server continues to send the ``ha-heartbeat``
+In this case, the surviving server continues to send the :isccmd:`ha-heartbeat`
command to detect when the partner wakes up. At that time, the partner
synchronizes the lease database. When it is again ready to operate, the
surviving server returns to normal operation, i.e. the ``load-balancing`` or
- ``in-maintenance`` - an active server transitions to this state as a result
of being notified by its partner that the administrator requested maintenance
of the HA setup. The administrator requests the maintenance by sending the
- ``ha-maintenance-start`` command to the server which is supposed to take over
+ :isccmd:`ha-maintenance-start` command to the server which is supposed to take over
the responsibility for responding to the DHCP clients while the other server
is taken offline for maintenance. If the server is in the ``in-maintenance``
state it can be safely shut down. The partner transitions to the
unavailable.
- ``partner-in-maintenance`` - an active server transitions to this state
- after receiving a ``ha-maintenance-start`` command from the administrator.
+ after receiving a :isccmd:`ha-maintenance-start` command from the administrator.
The server in this state becomes responsible for responding to all DHCP
- requests. The server sends a ``ha-maintenance-notify`` command to the partner,
+ requests. The server sends a :isccmd:`ha-maintenance-notify` command to the partner,
which should enter the ``in-maintenance`` state. The server remaining in the
``partner-in-maintenance`` state keeps sending lease updates to the partner
until it finds that the partner has stopped responding to those lease updates,
- ``syncing`` - an active server transitions to this state to fetch leases from
the active partner and update the local lease database. When in this state,
- the server issues the ``dhcp-disable`` command to disable the DHCP service of
+ the server issues the :isccmd:`dhcp-disable` command to disable the DHCP service of
the partner from which the leases are fetched. The DHCP service is disabled
for a maximum time of 60 seconds, after which it is automatically re-enabled,
in case the syncing partner was unable to re-enable the service. If the
synchronization completes successfully, the synchronizing server issues the
- ``ha-sync-complete-notify`` command to notify the partner. In most states,
+ :isccmd:`ha-sync-complete-notify` command to notify the partner. In most states,
the partner re-enables its DHCP service to continue responding to the DHCP
queries. In the ``partner-down`` state, the partner first ensures that
communication between the servers is re-established before enabling the DHCP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An HA-enabled server initiates synchronization of the lease database after
-downtime or upon receiving the ``ha-sync`` command. The server uses commands
+downtime or upon receiving the :isccmd:`ha-sync` command. The server uses commands
described in :ref:`command-lease4-get-page` and :ref:`command-lease6-get-page`
to fetch leases from its partner server (lease queries). The size of the results
page (the maximum number of leases to be returned in a single response to one of
which yields a large response over the RESTful interface. The server receives
leases using the paging mechanism described in :ref:`ha-syncing-page-limit`.
Before the page of leases is fetched, the synchronizing server sends a
-``dhcp-disable`` command to disable the DHCP service on the partner server. If
+:isccmd:`dhcp-disable` command to disable the DHCP service on the partner server. If
the service is already disabled, this command resets the timeout for the DHCP
service being disabled, which by default is set to 60 seconds. If fetching a
single page of leases takes longer than the specified time, the partner server
default value for each state, which instructs the server never to pause the
state machine.
-In order to "unpause" the state machine, the ``ha-continue`` command must be
+In order to "unpause" the state machine, the :isccmd:`ha-continue` command must be
sent to the paused server. This command does not take any arguments. See
:ref:`ha-control-commands` for details about commands specific to the HA hook
library.
stop serving any DHCP clients, so it can be safely shut down.
The maintenance feature of the High Availability hook library addresses this
-situation. The ``ha-maintenance-start`` command was introduced to allow the
+situation. The :isccmd:`ha-maintenance-start` command was introduced to allow the
administrator to put the pair of the active servers in a state in which one of
them is responding to all DHCP queries and the other one is awaiting shutdown.
Suppose that the HA setup includes two active servers, ``server1`` and
``server2``, and the latter needs to be shut down for maintenance.
-The administrator can send the ``ha-maintenance-start`` command to ``server1``,
+The administrator can send the :isccmd:`ha-maintenance-start` command to ``server1``,
as this is the server which is going to handle the DHCP traffic while the other
one is offline. ``server1`` responds with an error if its state or the partner's
state does not allow for a maintenance shutdown: for example, if maintenance is
not supported for the backup server or if the server is in the ``terminated``
-state. Also, an error is returned if the ``ha-maintenance-start`` request was
+state. Also, an error is returned if the :isccmd:`ha-maintenance-start` request was
already sent to the other server.
-Upon receiving the ``ha-maintenance-start`` command, ``server1`` sends the
-``ha-maintenance-notify`` command to ``server2`` to put it in the
+Upon receiving the :isccmd:`ha-maintenance-start` command, ``server1`` sends the
+:isccmd:`ha-maintenance-notify` command to ``server2`` to put it in the
``in-maintenance`` state. If ``server2`` confirms, ``server1`` transitions to
the ``partner-in-maintenance`` state. This is similar to the ``partner-down``
state, except that in the ``partner-in-maintenance`` state ``server1`` continues
``server2``. Restarting ``server2`` after the maintenance will trigger normal
state negotiation, lease-database synchronization, and, ultimately, a transition
to the normal ``load-balancing`` or ``hot-standby`` state. Maintenance can then
-be performed on ``server1``, after sending the ``ha-maintenance-start`` command
+be performed on ``server1``, after sending the :isccmd:`ha-maintenance-start` command
to ``server2``.
-If the ``ha-maintenance-start`` command was sent to the server and the server
+If the :isccmd:`ha-maintenance-start` command was sent to the server and the server
has transitioned to the ``partner-in-maintenance`` state, it is possible to
transition both it and its partner back to their previous states to resume the
normal operation of the HA pair. This is achieved by sending the
-``ha-maintenance-cancel`` command to the server that is in the
+:isccmd:`ha-maintenance-cancel` command to the server that is in the
``partner-in-maintenance`` state. However, if the server has already
transitioned to the ``partner-down`` state as a result of detecting that the
partner is offline, canceling the maintenance is no longer possible. In that
administrator must shut down one of the servers and rely on the failover
mechanism to force the online server to transition to the ``partner-down`` state,
where it starts serving all DHCP clients. Once the hook library on the first
-server is upgraded to a current version, the ``ha-maintenance-start`` command
+server is upgraded to a current version, the :isccmd:`ha-maintenance-start` command
can be used to upgrade the second server.
In such a case, shut down the server running the old version. Next, send the
-``ha-maintenance-start`` command to the server that has been upgraded. This
+:isccmd:`ha-maintenance-start` command to the server that has been upgraded. This
server should immediately transition to the ``partner-down`` state as it cannot
communicate with its offline partner. In the ``partner-down`` state the first
(upgraded) server will respond to all DHCP requests, allowing the administrator
.. note::
- Do not send the ``ha-maintenance-start`` command while the server running the
+ Do not send the :isccmd:`ha-maintenance-start` command while the server running the
old hook library is still online. The server receiving this command will
return an error.
The ``ha-sync`` Command
-----------------------
-The ``ha-sync`` command instructs the server to synchronize its local lease
+The :isccmd:`ha-sync` command instructs the server to synchronize its local lease
database with the selected peer. The server fetches all leases from the peer and
updates any locally stored leases which are older than those fetched. It also
creates new leases when any of those fetched do not exist in the local database.
All leases that are not returned by the peer but are in the local database are
preserved. The database synchronization is unidirectional; only the database on
the server to which the command has been sent is updated. To synchronize the
-peer's database, a separate ``ha-sync`` command must be issued to that peer.
+peer's database, a separate :isccmd:`ha-sync` command must be issued to that peer.
Database synchronization may be triggered for both active and backup server
-types. The ``ha-sync`` command has the following structure (in a DHCPv4 example):
+types. The :isccmd:`ha-sync` command has the following structure (in a DHCPv4 example):
::
}
When the server receives this command it first disables the DHCP service of the
-server from which it will be fetching leases, by sending the ``dhcp-disable``
+server from which it will be fetching leases, by sending the :isccmd:`dhcp-disable`
command to that server. The ``max-period`` parameter specifies the maximum
duration (in seconds) for which the DHCP service should be disabled. If the DHCP
service is successfully disabled, the synchronizing server fetches leases from
-the remote server by issuing one or more ``lease4-get-page`` commands. When the
+the remote server by issuing one or more :isccmd:`lease4-get-page` commands. When the
lease-database synchronization is complete, the synchronizing server sends the
-``dhcp-enable`` command to the peer to re-enable its DHCP service.
+:isccmd:`dhcp-enable` command to the peer to re-enable its DHCP service.
The ``max-period`` value should be sufficiently long to guarantee that it does
not elapse before the synchronization is completed. Otherwise, the DHCP server
This command allows an administrator to modify the HA scopes being served.
Consult :ref:`ha-load-balancing-config` and :ref:`ha-hot-standby-config` to
learn which scopes are available for the different HA modes of operation. The
-``ha-scopes`` command has the following structure (in a DHCPv4 example):
+:isccmd:`ha-scopes` command has the following structure (in a DHCPv4 example):
::
The ``ha-heartbeat`` Command
----------------------------
-The :ref:`ha-server-states` section describes how the ``ha-heartbeat`` command
+The :ref:`ha-server-states` section describes how the :isccmd:`ha-heartbeat` command
is used by a pair of active HA servers to detect one partner's failure. This
command, however, can also be sent by the system administrator to one or both
servers to check their HA state. This allows a monitoring system to be deployed
on the HA enabled servers to periodically check whether they are operational or
-whether any manual intervention is required. The ``ha-heartbeat`` command takes
+whether any manual intervention is required. The :isccmd:`ha-heartbeat` command takes
no arguments:
::
returned, which indicates that the server which responded to the command
believes that its partner is offline; thus, it is serving all DHCP requests sent
to the servers. To ensure that the partner is indeed offline, the administrator
-should send the ``ha-heartbeat`` command to the second server. If sending the
+should send the :isccmd:`ha-heartbeat` command to the second server. If sending the
command fails, e.g. due to an inability to establish a TCP connection to the
Control Agent, or if the Control Agent reports issues with communication with
the DHCP server, it is very likely that the server is not running.
}
}
-In most cases, the ``ha-heartbeat`` command should be sent to both HA-enabled
+In most cases, the :isccmd:`ha-heartbeat` command should be sent to both HA-enabled
servers to verify the state of the entire HA setup. In particular, if one of the
servers indicates that it is in the ``load-balancing`` state, it means that this
server is operating as if its partner is functional. When a partner goes down,
it takes some time for the surviving server to realize it. The
:ref:`ha-scope-transition` section describes the algorithm which the surviving
server follows before it transitions to the ``partner-down`` state. If the
-``ha-heartbeat`` command is sent during the time window between the failure of
+:isccmd:`ha-heartbeat` command is sent during the time window between the failure of
one of the servers and the transition of the surviving server to the
``partner-down`` state, the response from the surviving server does not reflect
the failure. Resending the command detects the failure once the surviving server
.. note:
- Always send the ``ha-heartbeat`` command to both active HA servers to check
+ Always send the :isccmd:`ha-heartbeat` command to both active HA servers to check
the state of the entire HA setup. Sending it to only one of the servers may
not reflect issues that just began with one of the servers.
The ``status-get`` Command
--------------------------
-``status-get`` is a general-purpose command supported by several Kea daemons,
+:isccmd:`status-get` is a general-purpose command supported by several Kea daemons,
not only the DHCP servers. However, when sent to a DHCP server with HA enabled,
it can be used to get insight into the details of the HA-specific server status.
Not only does the response contain the status information of the server
receiving this command, but also the information about its partner if it is
available.
-The following is an example response to the ``status-get`` command, including
+The following is an example response to the :isccmd:`status-get` command, including
the HA status of two ``load-balancing`` servers:
.. code-block:: json
configuration file, and thus should always be available. The remaining status
information, such as ``last-scopes`` and ``last-state``, is not available until
the local server communicates with the remote by successfully sending the
-``ha-heartbeat`` command. If at least one such communication has taken place,
+:isccmd:`ha-heartbeat` command. If at least one such communication has taken place,
the returned value of the ``in-touch`` parameter is set to ``true``. By
examining this value, the command's sender can determine whether the information
about the remote server is reliable.
HA scopes served by the partner and its state. This information is gathered
during the heartbeat command exchange, so it may not be accurate if a
communication problem occurs between the partners and this status information is
-not refreshed. In such a case, it may be useful to send the ``status-get``
+not refreshed. In such a case, it may be useful to send the :isccmd:`status-get`
command to the partner server directly to check its current state. The ``age``
parameter specifies the age of the information from the partner, in seconds.
The ``communication-interrupted`` boolean value indicates whether the server
-receiving the ``status-get`` command (the local server) has been unable to
+receiving the :isccmd:`status-get` command (the local server) has been unable to
communicate with the partner longer than the duration specified as
``max-response-delay``. In such a situation, the active servers are considered
to be in the ``communication-interrupted`` state. At this point, the local
``mode`` parameter in the configuration file. It can hold one of the following
values: ``load-balancing``, ``hot-standby``, or ``passive-backup``.
-The ``status-get`` response has the format described above only in the
+The :isccmd:`status-get` response has the format described above only in the
``load-balancing`` and ``hot-standby`` modes. In the ``passive-backup`` mode the
``remote`` map is not included in the response because in this mode there is
only one active server (local). The response includes no information about the
-------------------------------------
This command is used to cancel the maintenance previously initiated using the
-``ha-maintenance-start`` command. The server receiving this command will first
-send ``ha-maintenance-notify``, with the ``cancel`` flag set to ``true``, to its
+:isccmd:`ha-maintenance-start` command. The server receiving this command will first
+send :isccmd:`ha-maintenance-notify`, with the ``cancel`` flag set to ``true``, to its
partner. Next, the server reverts from the ``partner-in-maintenance`` state to
its previous state. See the :ref:`ha-maintenance` section for details.
The ``ha-maintenance-notify`` Command
-------------------------------------
-This command is sent by the server receiving the ``ha-maintenance-start`` or the
-``ha-maintenance-cancel`` command to its partner, to cause the partner to
+This command is sent by the server receiving the :isccmd:`ha-maintenance-start` or the
+:isccmd:`ha-maintenance-cancel` command to its partner, to cause the partner to
transition to the ``in-maintenance`` state or to revert from this state to a
previous state. See the :ref:`ha-maintenance` section for details.
.. warning::
- The ``ha-maintenance-notify`` command is not meant to be used by system
+ The :isccmd:`ha-maintenance-notify` command is not meant to be used by system
administrators. It is used for internal communication between a pair of
HA-enabled DHCP servers. Direct use of this command is not supported and may
produce unintended consequences.
.. warning::
- The ``ha-sync-complete-notify`` command is not meant to be used by system
+ The :isccmd:`ha-sync-complete-notify` command is not meant to be used by system
administrators. It is used for internal communication between a pair of
HA-enabled DHCP servers. Direct use of this command is not supported and may
produce unintended consequences.
}
This command removes 1000 hosts; to delete *all* cached
-hosts, use ``cache-clear`` instead. The hosts are stored in FIFO
+hosts, use :isccmd:`cache-clear` instead. The hosts are stored in FIFO
(first-in, first-out) order, so the oldest entries are always removed.
.. isccmd:: cache-clear
}
This command removes all hosts. To delete only a certain
-number of cached hosts, please use ``cache-flush`` instead.
+number of cached hosts, please use :isccmd:`cache-flush` instead.
.. isccmd:: cache-size
.. _command-cache-size:
}
This causes the contents to be stored in the ``/tmp/kea-host-cache.json``
-file. That file can then be loaded with the ``cache-load`` command or
+file. That file can then be loaded with the :isccmd:`cache-load` command or
processed by any other tool that is able to understand JSON format.
.. isccmd:: cache-load
}
This command stores the contents to the ``/tmp/kea-host-cache.json``
-file. That file can then be loaded with the ``cache-load`` command or
+file. That file can then be loaded with the :isccmd:`cache-load` command or
processed by any other tool that is able to understand JSON format.
.. isccmd:: cache-get
The ``cache-get`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~
-This command is similar to ``cache-write``, but instead of writing the cache
+This command is similar to :isccmd:`cache-write`, but instead of writing the cache
contents to disk, it returns the contents to whoever sent the command.
This command allows the contents of a file on disk to be loaded into an
The ``cache-get-by-id`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This command is similar to ``cache-get``, but instead of returning the whole
+This command is similar to :isccmd:`cache-get`, but instead of returning the whole
content it returns only the entries matching the given identifier.
It takes one parameter, which defines the identifier of wanted cached
been upgraded to better service), the information in the backend database
(e.g. MySQL or RADIUS) is being updated. However, since the cache is in use,
Kea does not notice the change as the cached values are used. The
-``cache-remove`` command can solve this problem by removing a cached entry
+:isccmd:`cache-remove` command can solve this problem by removing a cached entry
after administrative changes.
-The ``cache-remove`` command works similarly to the ``reservation-get`` command.
+The :isccmd:`cache-remove` command works similarly to the :isccmd:`reservation-get` command.
It allows querying by two parameters: either ``subnet-id4`` or ``subnet-id6``;
or ``ip-address`` (may be an IPv4 or IPv6 address), ``hw-address`` (specifies
a hardware/MAC address), ``duid``, ``circuit-id``, ``client-id``, or ``flex-id``.
Currently, the following commands are supported:
-- ``reservation-add``, which adds a new host reservation.
+- :isccmd:`reservation-add`, which adds a new host reservation.
-- ``reservation-get``, which returns an existing reservation if specified
+- :isccmd:`reservation-get`, which returns an existing reservation if specified
criteria are matched.
-- ``reservation-get-all``, which returns all reservations in a specified subnet.
+- :isccmd:`reservation-get-all`, which returns all reservations in a specified subnet.
-- ``reservation-get-page``, a variant of ``reservation-get-all`` that returns
+- :isccmd:`reservation-get-page`, a variant of :isccmd:`reservation-get-all` that returns
reservations by pages, either all or in a specified subnet.
-- ``reservation-get-by-hostname``, which returns all reservations with a
+- :isccmd:`reservation-get-by-hostname`, which returns all reservations with a
specified hostname and optionally in a subnet.
-- ``reservation-get-by-id``, which returns all reservations with a specified
+- :isccmd:`reservation-get-by-id`, which returns all reservations with a specified
identifier (since Kea version 1.9.0).
-- ``reservation-del``, which attempts to delete a reservation matching specified
+- :isccmd:`reservation-del`, which attempts to delete a reservation matching specified
criteria.
-- ``reservation-update``, which updates (replaces) an existing reservation
+- :isccmd:`reservation-update`, which updates (replaces) an existing reservation
matching the given identifiers in a subnet.
To use the commands that change reservation information
-(i.e. ``reservation-add``, ``reservation-del``, and ``reservation-update``) to
+(i.e. :isccmd:`reservation-add`, :isccmd:`reservation-del`, and :isccmd:`reservation-update`) to
modify data stored in the host database, the hosts database must be specified
and it must not operate in read-only mode (for details, see the
``hosts-databases`` descriptions in :ref:`hosts-databases-configuration4` and
:ref:`hosts-databases-configuration6`). If the ``hosts-databases`` are not
specified or are running in read-only mode, the ``host_cmds`` library will
-load, but any attempts to use ``reservation-add``, ``reservation-del``, and
-``reservation-update`` to modify data in that database will fail.
+load, but any attempts to use :isccmd:`reservation-add`, :isccmd:`reservation-del`, and
+:isccmd:`reservation-update` to modify data in that database will fail.
These commands can also modify hosts from the JSON configuration independently
from the hosts database. The changes provided in the JSON configuration are
Before examining the individual commands, it is worth discussing the
parameter ``subnet-id``. Currently this parameter is mandatory for all of the
commands supplied by this library, with the exception of
-``reservation-get-by-hostname``, where it is optional. Since Kea 1.9.0,
-``subnet-id`` is also optional in ``reservation-get-page``, and
-it is forbidden in ``reservation-get-by-id``.
+:isccmd:`reservation-get-by-hostname`, where it is optional. Since Kea 1.9.0,
+:isccmd:``subnet-id`` is also optional in `reservation-get-page`, and
+it is forbidden in :isccmd:`reservation-get-by-id`.
Reservations can be specified globally, and are not necessarily specific to any
subnet. When reservations are supplied via the configuration file, the
(primary source), the hosts database (alternate source), or both of them
(all sources). The operation target parameter is optional. By default, the
commands that only read the data use all data sources (JSON configuration and
-hosts database); the commands that modify the state (as ``reservation-add``,
-``reservation-del``, and ``reservation-update``) only use the alternate source.
+hosts database); the commands that modify the state (as :isccmd:`reservation-add`,
+:isccmd:`reservation-del`, and :isccmd:`reservation-update`) only use the alternate source.
The operation target accepts the following values:
The ``reservation-add`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``reservation-add`` allows for the insertion of a new host. It takes a
+:isccmd:`reservation-add` allows for the insertion of a new host. It takes a
set of arguments that vary depending on the nature of the host
reservation. Any parameters allowed in the configuration file that
pertain to host reservation are permitted here. For details regarding
}
-As ``reservation-add`` is expected to store the host, the ``hosts-databases``
+As :isccmd:`reservation-add` is expected to store the host, the ``hosts-databases``
parameter must be specified in the configuration, and databases must not
run in read-only mode.
The ``reservation-get`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``reservation-get`` can be used to query the host database and retrieve
+:isccmd:`reservation-get` can be used to query the host database and retrieve
existing reservations. This command supports two types of parameters:
(``subnet-id``, ``address``) or (``subnet-id``, ``identifier-type``,
``identifier``). The first type of query is used when the address (either
}
}
-``reservation-get`` typically returns the result 0 when a query was
+Command :isccmd:`reservation-get` typically returns the result 0 when a query was
conducted properly. In particular, 0 is returned when the host was not
found. If the query was successful, the host parameters are
returned. An example of a query that did not find the host looks as
The ``reservation-get-all`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``reservation-get-all`` can be used to query the host database and
+:isccmd:`reservation-get-all` can be used to query the host database and
retrieve all reservations in a specified subnet. This command uses
parameters providing the mandatory ``subnet-id``. Global host reservations
can be retrieved by using a ``subnet-id`` value of zero (0).
"text": "72 IPv4 host(s) found."
}
-The response returned by ``reservation-get-all`` can be very long. The
+The response returned by :isccmd:`reservation-get-all` can be very long. The
DHCP server does not handle DHCP traffic while preparing a response to
-``reservation-get-all``, so if there are many reservations in a subnet, this
+:isccmd:`reservation-get-all`, so if there are many reservations in a subnet, this
may be disruptive; use with caution. For larger deployments, please
-consider using ``reservation-get-page`` instead (see
+consider using :isccmd:`reservation-get-page` instead (see
:ref:`command-reservation-get-page`).
The command accepts the ``operation-target`` argument. By default, it gets the
.. isccmd:: reservation-get-page
.. _command-reservation-get-page:
-The ``reservation-get-page`` command
+The ``reservation-get-page`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``reservation-get-page`` can be used to query the host database and
+:isccmd:`reservation-get-page` can be used to query the host database and
retrieve all reservations in a specified subnet, by pages. This command
uses parameters providing the mandatory ``subnet-id``. Use a value of zero
(0) to fetch global reservations. The second mandatory parameter is the
The command doesn't accept the ``operation-target`` argument.
-This command is more complex than ``reservation-get-all``, but lets
+This command is more complex than :isccmd:`reservation-get-all`, but lets
users retrieve larger host reservations lists in smaller chunks. For
small deployments with few reservations, it is easier to use
-``reservation-get-all`` (see :ref:`command-reservation-get-all`).
+:isccmd:`reservation-get-all` (see :ref:`command-reservation-get-all`).
.. isccmd:: reservation-get-by-hostname
.. _command-reservation-get-by-hostname:
The ``reservation-get-by-hostname`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``reservation-get-by-hostname`` can be used to query the host database and
+:isccmd:`reservation-get-by-hostname` can be used to query the host database and
retrieve all reservations with a specified hostname or in
a specified subnet. This command uses parameters providing the mandatory
``hostname`` and the optional ``subnet-id``. Global host reservations
"text": "5 IPv4 host(s) found."
}
-The response returned by ``reservation-get-by-hostname`` can be long,
+The response returned by :isccmd:`reservation-get-by-hostname` can be long,
particularly when responses are not limited to a subnet.
The command accepts the ``operation-target`` argument. By default, it gets the
The ``reservation-get-by-id`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``reservation-get-by-id`` can be used to query the host database and
+:isccmd:`reservation-get-by-id` can be used to query the host database and
retrieve all reservations with a specified identifier (``identifier-type``
and ``identifier`` parameters), independently of subnets. The syntax for
parameters is the same as for ref:`command-reservation-get`.
"text": "5 IPv4 host(s) found."
}
-The response returned by ``reservation-get-by-id`` can be long,
+The response returned by :isccmd:`reservation-get-by-id` can be long,
particularly when responses are not limited to a subnet.
The command accepts the ``operation-target`` argument. By default, it gets the
The ``reservation-del`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``reservation-del`` can be used to delete a reservation from the host
+:isccmd:`reservation-del` can be used to delete a reservation from the host
database and/or JSON configuration. This command supports two types of parameters:
(``subnet-id``, ``address``) or (``subnet-id``, ``identifier-type``, ``identifier``). The
first type of query is used when the address (either IPv4 or IPv6) is
}
}
-``reservation-del`` returns a result of 0 when the host deletion was
+Command :isccmd:`reservation-del` returns a result of 0 when the host deletion was
successful, or 1 if it failed. Descriptive text is provided in the event of
an error. Here are some examples of possible results:
The ``reservation-update`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``reservation-update`` allows for the update of an existing host. It takes the
+:isccmd:`reservation-update` allows for the update of an existing host. It takes the
same set of arguments as :ref:``command-reservation-add``, and just as well,
requires a host identifier and a subnet ID to identify the host that is being
updated. The command can be as simple as having only the two mandatory entries:
}
The command accepts the ``operation-target`` argument. By default, it adds the
-reservation to the hosts database only. As ``reservation-update`` is expected
+reservation to the hosts database only. As :isccmd:`reservation-update` is expected
to store the host, the ``hosts-databases`` parameter must be specified in the
configuration, and databases must not run in read-only mode if the operation
target is not the JSON configuration.
As with other update and set commands, this command overwrites all the contents
of the entry. If the host previously had a resource assigned to it, and the
-``reservation-update`` command is missing the resource, it is deleted from the
+:isccmd:`reservation-update` command is missing the resource, it is deleted from the
database. If an incremental update of the host is desired, then this can be
-achieved by doing a ``reservation-get-by-id`` to get the current state of the
+achieved by doing a :isccmd:`reservation-get-by-id` to get the current state of the
host, picking the host out of the response, modifying it to the required
-outcome, and then issuing the ``reservation-update`` command with the resulting
+outcome, and then issuing the :isccmd:`reservation-update` command with the resulting
host attached.
.. _hooks-host-cmds-general-mentions:
The host cache and RADIUS hook libraries are two host backends that do not
respond to commands that return a collection of host reservations, such as
- ``reservation-get-all``. Commands returning one host entry or dedicated host
+ :isccmd:`reservation-get-all`. Commands returning one host entry or dedicated host
cache commands should be used instead.
This library provides the following commands:
-- ``lease4-add`` - adds a new IPv4 lease.
+- :isccmd:`lease4-add` - adds a new IPv4 lease.
-- ``lease6-add`` - adds a new IPv6 lease.
+- :isccmd:`lease6-add` - adds a new IPv6 lease.
-- ``lease6-bulk-apply`` - creates, updates, and/or deletes multiple
+- :isccmd:`lease6-bulk-apply` - creates, updates, and/or deletes multiple
IPv6 leases in a single transaction.
-- ``lease4-get`` - checks whether an IPv4 lease with the specified
+- :isccmd:`lease4-get` - checks whether an IPv4 lease with the specified
parameters exists and returns it if it does.
-- ``lease6-get`` - checks whether an IPv6 lease with the specified
+- :isccmd:`lease6-get` - checks whether an IPv6 lease with the specified
parameters exists and returns it if it does.
-- ``lease4-get-all`` - returns all IPv4 leases or all IPv4 leases for
+- :isccmd:`lease4-get-all` - returns all IPv4 leases or all IPv4 leases for
the specified subnets.
-- ``lease6-get-all`` - returns all IPv6 leases or all IPv6 leases for
+- :isccmd:`lease6-get-all` - returns all IPv6 leases or all IPv6 leases for
the specified subnets.
-- ``lease4-get-page`` - returns a set ("page") of leases from the list
+- :isccmd:`lease4-get-page` - returns a set ("page") of leases from the list
of all IPv4 leases in the database. By iterating through the pages it
is possible to retrieve all the leases.
-- ``lease6-get-page`` - returns a set ("page") of leases from the list
+- :isccmd:`lease6-get-page` - returns a set ("page") of leases from the list
of all IPv6 leases in the database. By iterating through the pages it
is possible to retrieve all the leases.
-- ``lease4-get-by-hw-address`` - returns all IPv4 leases with the specified
+- :isccmd:`lease4-get-by-hw-address` - returns all IPv4 leases with the specified
hardware address.
-- ``lease4-get-by-client-id`` - returns all IPv4 leases with the specified
+- :isccmd:`lease4-get-by-client-id` - returns all IPv4 leases with the specified
``client-id``.
-- ``lease6-get-by-duid`` - returns all IPv6 leases with the specified DUID.
+- :isccmd:`lease6-get-by-duid` - returns all IPv6 leases with the specified DUID.
-- ``lease4-get-by-hostname`` - returns all IPv4 leases with the specified
+- :isccmd:`lease4-get-by-hostname` - returns all IPv4 leases with the specified
hostname.
-- ``lease6-get-by-hostname`` - returns all IPv6 leases with the specified
+- :isccmd:`lease6-get-by-hostname` - returns all IPv6 leases with the specified
hostname.
-- ``lease4-del`` - deletes an IPv4 lease with the specified parameters.
+- :isccmd:`lease4-del` - deletes an IPv4 lease with the specified parameters.
-- ``lease6-del`` - deletes an IPv6 lease with the specified parameters.
+- :isccmd:`lease6-del` - deletes an IPv6 lease with the specified parameters.
-- ``lease4-update`` - updates (replaces) an existing IPv4 lease.
+- :isccmd:`lease4-update` - updates (replaces) an existing IPv4 lease.
-- ``lease6-update`` - updates (replaces) an existing IPv6 lease.
+- :isccmd:`lease6-update` - updates (replaces) an existing IPv6 lease.
-- ``lease4-wipe`` - removes all leases from a specific IPv4 subnet or
+- :isccmd:`lease4-wipe` - removes all leases from a specific IPv4 subnet or
from all subnets.
-- ``lease6-wipe`` - removes all leases from a specific IPv6 subnet or
+- :isccmd:`lease6-wipe` - removes all leases from a specific IPv6 subnet or
from all subnets.
-- ``lease4-resend-ddns`` - resends a request to update DNS entries for
+- :isccmd:`lease4-resend-ddns` - resends a request to update DNS entries for
an existing lease.
-- ``lease6-resend-ddns`` - resends a request to update DNS entries for
+- :isccmd:`lease6-resend-ddns` - resends a request to update DNS entries for
an existing lease.
-- ``lease4-write`` - writes the IPv4 memfile lease database into a file.
+- :isccmd:`lease4-write` - writes the IPv4 memfile lease database into a file.
-- ``lease6-write`` - writes the IPv6 memfile lease database into a file.
+- :isccmd:`lease6-write` - writes the IPv6 memfile lease database into a file.
All commands use JSON syntax and can be issued either using the control
channel (see :ref:`ctrl-channel`) or Control Agent (see
The ``lease4-add``, ``lease6-add`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``lease4-add`` and ``lease6-add`` commands allow a new lease
+The :isccmd:`lease4-add` and
+:isccmd:`lease6-add` commands allow a new lease
to be created. Typically Kea creates a lease when it first sees a new
device; however, sometimes it may be convenient to create the lease
-manually. The ``lease4-add`` command requires at least two parameters:
+manually. The :isccmd:`lease4-add` command requires at least two parameters:
an IPv4 address and an identifier, i.e. hardware (MAC) address. A third
parameter, ``subnet-id``, is optional. If the ``subnet-id`` is not specified or
the specified value is 0, Kea tries to determine the value by running
}
}
-The ``lease6-add`` command requires three parameters: an IPv6 address,
+The :isccmd:`lease6-add` command requires three parameters: an IPv6 address,
an IAID value (identity association identifier, a value sent by
-clients), and a DUID. As with ``lease4-add``, the ``subnet-id`` parameter is
+clients), and a DUID. As with :isccmd:`lease4-add`, the ``subnet-id`` parameter is
optional. If the ``subnet-id`` is not specified or the provided value is 0,
Kea tries to determine the value by running a subnet-selection
procedure. If specified, however, its value must match the existing
}
}
-The ``lease6-add`` command can also be used to add leases for IPv6 prefixes.
+The :isccmd:`lease6-add` command can also be used to add leases for IPv6 prefixes.
In this case there are three additional parameters that must be specified:
``subnet-id``, ``type`` (set to "IA_PD"), and prefix length. The actual
prefix is set using the ``ip-address`` field. Note that Kea cannot guess
.. isccmd:: lease6-bulk-apply
.. _command-lease6-bulk-apply:
-The ``lease6-bulk-apply`` Command
+The lease6-bulk-apply Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``lease6-bulk-apply`` was implemented to address
+The :isccmd:`lease6-bulk-apply` was implemented to address
the performance penalty in High-Availability mode when a single DHCPv6
transaction resulted in multiple lease updates sent to the partner, if
multiple address and/or prefix leases were allocated. Consider the case
DHCPv6 may assign a different address than the one requested by the client during
the renew or rebind stage, and delete the leases previously used by this client.
There are six lease changes sent between the HA partners in this case.
-Sending these updates as individual commands, e.g. via ``lease6-update``,
+Sending these updates as individual commands, e.g. via :isccmd:`lease6-update`,
is highly inefficient and produces unnecessary delays in communication,
both between the HA partners and in sending the response to the DHCPv6 client.
-The ``lease6-bulk-apply`` command deals with this
+The :isccmd:`lease6-bulk-apply` command deals with this
problem by aggregating all lease changes - both deleted leases and
new or updated leases - in a single command.
The receiving server iterates over the deleted leases and deletes them
The ``lease4-get``, ``lease6-get`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``lease4-get`` and ``lease6-get`` can be used to query the lease database
+:isccmd:`lease4-get` and :isccmd:`lease6-get` can be used to query the lease database
and retrieve existing leases. There are two types of parameters the
-``lease4-get`` command supports: (``address``) or (``subnet-id``,
+:isccmd:`lease4-get` command supports: (``address``) or (``subnet-id``,
``identifier-type``, ``identifier``). There are also two types for
-``lease6-get``: (``address``, ``type``) or (``subnet-id``, ``identifier-type``,
+:isccmd:`lease6-get`: (``address``, ``type``) or (``subnet-id``, ``identifier-type``,
``identifier``, ``IAID``, ``type``). The first type of query is used when the
address (either IPv4 or IPv6) is known, but the details of the lease are
not; one common use case of this type of query is to find out whether a
currently supported identifiers for leases are: ``"hw-address"`` (IPv4
only), ``"client-id"`` (IPv4 only), and ``"duid"`` (IPv6 only).
-An example ``lease4-get`` command for getting a lease using an IPv4
+An example :isccmd:`lease4-get` command for getting a lease using an IPv4
address is:
::
}
}
-An example of the ``lease6-get`` query is:
+An example of the :isccmd:`lease6-get` query is:
::
(non-temporary address) and ``IA_PD`` (IPv6 prefix). If not specified, ``IA_NA``
is assumed.
-``lease4-get`` and ``lease6-get`` return an indication of the result of the operation
+:isccmd:`lease4-get` and :isccmd:`lease6-get` return an indication of the result of the operation
and lease details, if found. The result has one of the following values: 0
(success), 1 (error), or 3 (empty). An empty result means that a query
has been completed properly, but the object (a lease in this case) has
The ``lease4-get-all``, ``lease6-get-all`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``lease4-get-all`` and ``lease6-get-all`` are used to retrieve all IPv4
+:isccmd:`lease4-get-all` and :isccmd:`lease6-get-all` are used to retrieve all IPv4
or IPv6 leases, or all leases for the specified set of subnets. All
leases are returned when there are no arguments specified with the
command, as in the following example:
.. warning::
- The ``lease4-get-all`` and ``lease6-get-all`` commands may result in
+ The :isccmd:`lease4-get-all` and
+ :isccmd:`lease6-get-all` commands may result in
very large responses. This may have a negative impact on the DHCP
server's responsiveness while the response is generated and
transmitted over the control channel, as the server imposes no
The ``lease4-get-page``, ``lease6-get-page`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``lease4-get-all`` and ``lease6-get-all`` commands may result in
+The :isccmd:`lease4-get-all` and
+:isccmd:`lease6-get-all` commands may result in
very large responses; generating such a response may consume CPU
bandwidth as well as memory. It may even cause the server to become
unresponsive. In the case of large lease databases it is usually better to
retrieve leases in chunks, using the paging mechanism.
-``lease4-get-page`` and ``lease6-get-page`` implement a paging mechanism
+:isccmd:`lease4-get-page` and :isccmd:`lease6-get-page` implement a paging mechanism
for DHCPv4 and DHCPv6 servers, respectively. The following command
retrieves the first 1024 IPv4 leases:
}
Similarly, the IPv6 zero address can be specified in the
-``lease6-get-page`` command:
+:isccmd:`lease6-get-page` command:
::
page.
To fetch the next page, the client must use the last address of the
-current page as an input to the next ``lease4-get-page`` or
-``lease6-get-page`` command call. In this example it is:
+current page as an input to the next :isccmd:`lease4-get-page` or
+:isccmd:`lease6-get-page` command call. In this example it is:
::
can include a specified hardware address (IPv4
only), ``client-id`` IPv4 only), ``duid`` (IPv6 only) identifiers, or hostname.
-An example ``lease4-get-by-hw-address`` command for getting IPv4 leases
+An example :isccmd:`lease4-get-by-hw-address` command for getting IPv4 leases
with a given hardware address is:
::
}
}
-An example of the ``lease6-get-by-hostname`` is:
+An example of the :isccmd:`lease6-get-by-hostname` is:
::
}
The ``by`` key is the only parameter. The returned response contains a detailed
-list of leases in the same format as ``lease4-get-all`` or ``lease6-get-all``. This list can be
+list of leases in the same format as :isccmd:`lease4-get-all` or :isccmd:`lease6-get-all`. This list can be
empty and is usually not large.
.. isccmd:: lease4-del
The ``lease4-del``, ``lease6-del`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``lease4-del`` and ``lease6-del`` can be used to delete a lease from the lease database.
+:isccmd:`lease4-del` and :isccmd:`lease6-del` can be used to delete a lease from the lease database.
There are two types of parameters these commands support, similar to the
-``lease4-get`` and ``lease6-get`` commands: (``address``) for both v4 and v6, (``subnet-id``,
+:isccmd::isccmd:`lease4-get` and `lease6-get` commands: (``address``) for both v4 and v6, (``subnet-id``,
``identifier-type``, ``identifier``) for v4, and (``subnet-id``, ``identifier-type``,
``identifier``, ``type``, ``IAID``) for v6. The first type of query is used when the
address (either IPv4 or IPv6) is known, but the details of the lease are
}
-``lease4-del`` and ``lease6-del`` return a result that indicates the outcome
+Commands :isccmd:`lease4-del` and :isccmd:`lease6-del` return a result that indicates the outcome
of the operation. It has one of the following values: 0 (success), 1 (error),
or 3 (empty). The empty result means that a query has been completed properly,
but the object (a lease, in this case) has not been found.
The ``lease4-update``, ``lease6-update`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``lease4-update`` and ``lease6-update`` commands can be used to
+The :isccmd:`lease4-update` and
+:isccmd:`lease6-update` commands can be used to
update existing leases. Since all lease database backends are indexed by
IP addresses, it is not possible to update an address, but all other
fields may be altered. If an address needs to be changed, please use
-``lease4-del``/``lease6-del`` followed by ``lease4-add``/``lease6-add``.
+:isccmd:`lease4-del` / :isccmd:`lease6-del` followed by :isccmd:`lease4-add` / :isccmd:`lease6-add`.
The ``subnet-id`` parameter is optional. If not specified, or if the
specified value is 0, Kea tries to determine its value by running a
exist. In such a case, an error is returned when trying to
update a non-existing lease. If the ``"force-create"`` parameter is set to
``true`` and the updated lease does not exist, the new lease is created as a
-result of receiving the ``lease4-update``/``lease6-update`` command.
+result of receiving the :isccmd::isccmd:`lease4-update`/`lease6-update` command.
An example of a command to update an IPv4 lease is:
As with other update commands, this command overwrites all the contents of the
entry. If the lease previously had a resource assigned to it, and the
-``lease4-update``/``lease6-update`` command is missing the resource, it is
+:isccmd::isccmd:`lease4-update`/`lease6-update` command is missing the resource, it is
deleted from the lease database. If an incremental update of the lease is
-desired, then this can be achieved by doing a
-`lease4-get <command-lease4-get_>`_ / `lease6-get <command-lease6-get_>`_
+desired, then this can be achieved by doing a :isccmd:`lease4-get` / :isccmd:`lease6-get`
command to get the current state of the lease, picking the lease out of the
response, modifying it to the required outcome, and then issuing the
-``lease4-update``/``lease6-update`` command with the resulting lease attached.
+:isccmd::isccmd:`lease4-update`/`lease6-update` command with the resulting lease attached.
.. isccmd:: lease4-wipe
.. _command-lease4-wipe:
The ``lease4-wipe``, ``lease6-wipe`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``lease4-wipe`` and ``lease6-wipe`` are designed to remove all leases
+:isccmd:`lease4-wipe` and :isccmd:`lease6-wipe` are designed to remove all leases
associated with a given subnet. This administrative task is expected to
be used when an existing subnet is being retired. The leases
are not properly expired; no DNS updates are carried out, no log
messages are created, and hooks are not called for the leases being
removed.
-An example of ``lease4-wipe`` is:
+An example of :isccmd:`lease4-wipe` is:
::
}
}
-An example of ``lease6-wipe`` is:
+An example of :isccmd:`lease6-wipe` is:
::
The ``lease4-resend-ddns``, ``lease6-resend-ddns`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``lease4-resend-ddns`` and ``lease6-resend-ddns`` can be used to generate
+:isccmd:`lease4-resend-ddns` and :isccmd:`lease6-resend-ddns` can be used to generate
a request to :iscman:`kea-dhcp-ddns` to update the DNS entries for an existing
lease. The desired lease is selected by a single parameter, ``"ip-address"``.
For an update request to be generated, DDNS updating must be enabled
- The lease's hostname must not be empty.
- At least one of the lease's DNS direction flags (``fqdn_fwd`` or ``fqdn_rev``) must be true.
-An example ``lease4-resend-ddns`` command for getting a lease using an IPv4
+An example :isccmd:`lease4-resend-ddns` command for getting a lease using an IPv4
address is:
::
}
}
-An example of the ``lease6-resend-ddns`` query is:
+An example of the :isccmd:`lease6-resend-ddns` query is:
::
}
}
-``lease4-resend-ddns`` and ``lease6-resend-ddns`` return an indication of the
+Commands :isccmd:`lease4-resend-ddns` and :isccmd:`lease6-resend-ddns` return an indication of the
result of the operation. It has one of the following values: 0 (success), 1 (error),
or 3 (empty). An empty result means that a query has been completed properly, but the
object (a lease in this case) has not been found.
The ``lease4-write``, ``lease6-write`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``lease4-write`` and ``lease6-write`` can be used for recovery in emergency
+:isccmd:`lease4-write` and :isccmd:`lease6-write` can be used for recovery in emergency
situations where the memfile lease file is damaged, e.g. removed by
accident or truncated by a full file system, but the in-memory database
is still valid. These commands are supported only by the memfile database
In addition to logging lease activity driven by DHCPv4 client traffic,
the hook library also logs entries for the following lease management control
-channel commands: ``lease4-add``, ``lease4-update``, and ``lease4-del``. These cannot have
+channel commands: :isccmd:`lease4-add`, :isccmd:`lease4-update`, and :isccmd:`lease4-del`. These cannot have
custom formatting. Each entry is a single string with no embedded end-of-line
markers, and it will typically have the following form:
In addition to logging lease activity driven by DHCPv6 client traffic,
the hook library also logs entries for the following lease management control channel
-commands: ``lease6-add``, ``lease6-update``, and ``lease6-del``. Each entry is a
+commands: :isccmd:`lease6-add`, :isccmd:`lease6-update`, and :isccmd:`lease6-del`. Each entry is a
single string with no embedded end-of-line markers, and it will
typically have the following form:
~~~~~~~~~~~~~~~~~
Here is an extensive example for a role accepting all read commands, with
-the exception of ``config-get``, e.g. for hiding passwords. For any remote
+the exception of :isccmd:`config-get`, e.g. for hiding passwords. For any remote
user who is not recognized as "user1", all commands should be rejected.
The first option is to put the allowed commands in the "accept-commands"
The commands provided by this library are:
-- ``stat-lease4-get`` - fetches DHCPv4 lease statistics.
+- :isccmd:`stat-lease4-get` - fetches DHCPv4 lease statistics.
-- ``stat-lease6-get`` - fetches DHCPv6 lease statistics.
+- :isccmd:`stat-lease6-get` - fetches DHCPv6 lease statistics.
The Statistics Commands library is part of the open source code and is
available to every Kea user.
In a deployment with multiple Kea DHCP servers sharing a common lease
storage, this hook library may be loaded by any or all of the servers. However,
-a server's response to a
+a server's response to a :isccmd:`stat-lease4-get` / :isccmd:`stat-lease6-get`
``stat-lease[46]-get`` command will only contain data for subnets known to
that server. In other words, if a subnet does not appear in a server's
configuration, Kea will not retrieve statistics for it.
The ``stat-lease4-get``, ``stat-lease6-get`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``stat-lease4-get`` and ``stat-lease6-get`` commands fetch lease
+The :isccmd:`stat-lease4-get` and
+:isccmd:`stat-lease6-get` commands fetch lease
statistics for a range of known subnets. The range of subnets is
determined through the use of optional command input parameters:
The following commands are currently supported:
-- ``subnet4-list``/``subnet6-list`` - lists all configured subnets.
+- :isccmd:`subnet4-list` / :isccmd:`subnet6-list` - lists all configured subnets.
-- ``subnet4-get``/``subnet6-get`` - retrieves detailed information about a
+- :isccmd:`subnet4-get` / :isccmd:`subnet6-get` - retrieves detailed information about a
specified subnet.
-- ``subnet4-add``/``subnet6-add`` - adds a new subnet into the server's
+- :isccmd:`subnet4-add` / :isccmd:`subnet6-add` - adds a new subnet into the server's
configuration.
-- ``subnet4-update``/``subnet6-update`` - updates (replaces) a single subnet in
+- :isccmd:`subnet4-update` / :isccmd:`subnet6-update` - updates (replaces) a single subnet in
the server's configuration.
-- ``subnet4-del``/``subnet6-del`` - removes a subnet from the server's
+- :isccmd:`subnet4-del` / :isccmd:`subnet6-del` - removes a subnet from the server's
configuration.
-- ``subnet4-delta-add``/``subnet6-delta-add`` - updates (replaces) parts of a
+- :isccmd:`subnet4-delta-add` / :isccmd:`subnet6-delta-add` - updates (replaces) parts of a
single subnet in the server's configuration.
-- ``subnet4-delta-del``/``subnet6-delta-del`` - removes parts of a single subnet in
+- :isccmd:`subnet4-delta-del` / :isccmd:`subnet6-delta-del` - removes parts of a single subnet in
the server's configuration.
-- ``network4-list``/``network6-list`` - lists all configured shared networks.
+- :isccmd:`network4-list` / :isccmd:`network6-list` - lists all configured shared networks.
-- ``network4-get``/``network6-get`` - retrieves detailed information about a
+- :isccmd:`network4-get` / :isccmd:`network6-get` - retrieves detailed information about a
specified shared network.
-- ``network4-add``/``network6-add`` - adds a new shared network to the
+- :isccmd:`network4-add` / :isccmd:`network6-add` - adds a new shared network to the
server's configuration.
-- ``network4-del``/``network6-del`` - removes a shared network from the
+- :isccmd:`network4-del` / :isccmd:`network6-del` - removes a shared network from the
server's configuration.
-- ``network4-subnet-add``/``network6-subnet-add`` - adds an existing subnet to
+- :isccmd:`network4-subnet-add` / :isccmd:`network6-subnet-add` - adds an existing subnet to
an existing shared network.
-- ``network4-subnet-del``/``network6-subnet-del`` - removes a subnet from
+- :isccmd:`network4-subnet-del` / :isccmd:`network6-subnet-del` - removes a subnet from
an existing shared network and demotes it to a plain subnet.
.. isccmd:: subnet4-list
.. _command-subnet4-list:
-The ``subnet4-list`` Command
+The subnet4-list Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to list all currently configured subnets. Each
subnet is returned with a subnet identifier and
subnet prefix. To retrieve
-detailed information about the subnet, use the ``subnet4-get`` command.
+detailed information about the subnet, use the :isccmd:`subnet4-get` command.
This command has a simple structure:
.. isccmd:: subnet6-list
.. _command-subnet6-list:
-The ``subnet6-list`` Command
+The subnet6-list Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to list all currently configured subnets. Each
subnet is returned with a subnet identifier and
subnet prefix. To retrieve
-detailed information about the subnet, use the ``subnet6-get`` command.
+detailed information about the subnet, use the :isccmd:`subnet6-get` command.
This command has a simple structure:
.. isccmd:: subnet4-get
.. _command-subnet4-get:
-The ``subnet4-get`` Command
+The subnet4-get Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to retrieve detailed information about the
-specified subnet. This command usually follows ``subnet4-list``,
+specified subnet. This command usually follows :isccmd:`subnet4-list`,
which is used to discover available subnets with their respective subnet
identifiers and prefixes. Any of those parameters can then be used in
-``subnet4-get`` to fetch subnet information:
+:isccmd:`subnet4-get` to fetch subnet information:
::
.. isccmd:: subnet6-get
.. _command-subnet6-get:
-The ``subnet6-get`` Command
+The subnet6-get Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to retrieve detailed information about the
-specified subnet. This command usually follows ``subnet6-list``,
+specified subnet. This command usually follows :isccmd:`subnet6-list`,
which is used to discover available subnets with their respective subnet
identifiers and prefixes. Any of those parameters can be then used in
-``subnet6-get`` to fetch subnet information:
+:isccmd:`subnet6-get` to fetch subnet information:
::
.. isccmd:: subnet4-add
.. _command-subnet4-add:
-The ``subnet4-add`` Command
+The subnet4-add Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to create and add a new subnet to the existing server
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
-``subnet4-add``. The commands described in :ref:`hooks-host-cmds` should be used to
+:isccmd:`subnet4-add`. The commands described in :ref:`hooks-host-cmds` should be used to
add, remove, and modify static reservations.
::
.. isccmd:: subnet6-add
.. _command-subnet6-add:
-The ``subnet6-add`` Command
+The subnet6-add Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to create and add a new subnet to the existing server
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
-``subnet6-add``. The commands described in :ref:`hooks-host-cmds` should be used
+:isccmd:`subnet6-add`. The commands described in :ref:`hooks-host-cmds` should be used
to add, remove, and modify static reservations.
::
automatic ID value generator is simple; it returns the previous
automatically assigned value, increased by 1. This works well, unless
a subnet is manually created with a larger value than one previously used. For
-example, if ``subnet4-add`` is called five times, each without an ID, Kea will
+example, if :isccmd:`subnet4-add` is called five times, each without an ID, Kea will
assign IDs 1, 2, 3, 4, and 5 and it will work just fine. However, if
-``subnet4-add`` is called five times, with the first subnet having the
+:isccmd:`subnet4-add` is called five times, with the first subnet having the
``subnet-id`` of value 3 and the remaining ones having no ``subnet-id``, the operation will
fail. The first command (with the explicit value) will use ``subnet-id`` 3; the
second command will create a subnet with and ID of 1; the third will use a
.. isccmd:: subnet4-update
.. _command-subnet4-update:
-The ``subnet4-update`` Command
+The subnet4-update Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to update (overwrite) a single subnet in the existing
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
-``subnet4-update``. The commands described in :ref:`hooks-host-cmds` should be
+:isccmd:`subnet4-update`. The commands described in :ref:`hooks-host-cmds` should be
used to update, remove, and modify static reservations.
::
As with other update commands, this command overwrites all the contents of the
entry. If the IPv4 subnet previously had a resource assigned to it, and the
-``subnet4-update`` command is missing the resource, it is deleted from the
+:isccmd:`subnet4-update` command is missing the resource, it is deleted from the
server configuration. If an incremental update of the subnet is desired, then
-this can be achieved with `subnet4-delta-add <command-subnet4-delta-add_>`_.
+this can be achieved with :isccmd:`subnet4-delta-add`.
.. isccmd:: subnet6-update
.. _command-subnet6-update:
-The ``subnet6-update`` Command
+The subnet6-update Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to update (overwrite) a single subnet in the existing
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
-``subnet6-update``. The commands described in :ref:`hooks-host-cmds` should be
+:isccmd:`subnet6-update`. The commands described in :ref:`hooks-host-cmds` should be
used to update, remove, and modify static reservations.
::
As with other update commands, this command overwrites all the contents of the
entry. If the IPv6 subnet previously had a resource assigned to it, and the
-``subnet6-update`` command is missing the resource, it is deleted from the
+:isccmd:`subnet6-update` command is missing the resource, it is deleted from the
server configuration. If an incremental update of the subnet is desired, then
-this can be achieved with `subnet6-delta-add <command-subnet6-delta-add_>`_.
+this can be achieved with :isccmd:`subnet6-delta-add`.
.. isccmd:: subnet4-del
.. _command-subnet4-del:
-The ``subnet4-del`` Command
+The subnet4-del Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to remove a subnet from the server's configuration.
In most cases the server has assigned some leases to the clients
belonging to the subnet. The server may also be configured with static
host reservations which are associated with this subnet. The current
-implementation of the ``subnet4-del`` command removes neither the leases nor
+implementation of the :isccmd:`subnet4-del` command removes neither the leases nor
the host reservations associated with a subnet. This is the safest approach
because the server does not lose track of leases assigned to clients
from this subnet. However, removal of the subnet may still cause
This command can also be used to completely delete an IPv4 subnet that
is part of a shared network. To simply remove the subnet
from a shared network and keep the subnet configuration, use the
-``network4-subnet-del`` command instead.
+:isccmd:`network4-subnet-del` command instead.
The command has the following structure:
.. isccmd:: subnet6-del
.. _command-subnet6-del:
-The ``subnet6-del`` Command
+The subnet6-del Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to remove a subnet from the server's configuration.
In most cases the server has assigned some leases to the clients
belonging to the subnet. The server may also be configured with static
host reservations which are associated with this subnet. The current
-implementation of the ``subnet6-del`` command removes neither the leases nor
+implementation of the :isccmd:`subnet6-del` command removes neither the leases nor
the host reservations associated with a subnet. This is the safest approach
because the server does not lose track of leases assigned to clients
from this subnet. However, removal of the subnet may still cause
This command can also be used to completely delete an IPv6 subnet that
is part of a shared network. To simply remove the subnet
from a shared network and keep the subnet configuration, use the
-``network6-subnet-del`` command instead.
+:isccmd:`network6-subnet-del` command instead.
The command has the following structure:
.. isccmd:: subnet4-delta-add
.. _command-subnet4-delta-add:
-The ``subnet4-delta-add`` Command
+The subnet4-delta-add Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to update a subnet by adding or overwriting its parts in
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
-``subnet4-delta-add``. The commands described in :ref:`hooks-host-cmds` should
+:isccmd:`subnet4-delta-add`. The commands described in :ref:`hooks-host-cmds` should
be used to update, remove, and modify static reservations.
::
.. isccmd:: subnet6-delta-add
.. _command-subnet6-delta-add:
-The ``subnet6-delta-add`` Command
+The subnet6-delta-add Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to update a subnet by adding or overwriting its parts in
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
-``subnet6-delta-add``. The commands described in :ref:`hooks-host-cmds` should
+:isccmd:`subnet6-delta-add`. The commands described in :ref:`hooks-host-cmds` should
be used to update, remove, and modify static reservations.
::
.. isccmd:: subnet4-delta-del
.. _command-subnet4-delta-del:
-The ``subnet4-delta-del`` Command
+The subnet4-delta-del Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to update a subnet by removing its parts in the existing
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
-``subnet4-delta-del``. The commands described in :ref:`hooks-host-cmds` should
+:isccmd:`subnet4-delta-del`. The commands described in :ref:`hooks-host-cmds` should
be used to update, remove, and modify static reservations.
The command is flexible and can delete the part of the subnet by either
.. isccmd:: subnet6-delta-del
.. _command-subnet6-delta-del:
-The ``subnet6-delta-del`` Command
+The subnet6-delta-del Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to update a subnet by removing its parts in the existing
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations cannot be specified within
-``subnet6-delta-del``. The commands described in :ref:`hooks-host-cmds` should
+:isccmd:`subnet6-delta-del`. The commands described in :ref:`hooks-host-cmds` should
be used to update, remove, and modify static reservations.
The command is flexible and can delete the part of the subnet by either
These commands are used to retrieve the full list of currently configured
shared networks. The list contains only very basic information about
each shared network. If more details are needed, please use
-``network4-get`` or ``network6-get`` to retrieve all information
+:isccmd:`network4-get` or :isccmd:`network6-get` to retrieve all information
available. This command does not require any parameters and its
invocation is very simple:
"command": "network4-list"
}
-An example response for ``network4-list`` looks as follows:
+An example response for :isccmd:`network4-list` looks as follows:
::
"text": "2 IPv4 network(s) found"
}
-The ``network6-list`` command uses exactly the same syntax for both the
+The :isccmd:`network6-list` command uses exactly the same syntax for both the
command and the response.
.. isccmd:: network4-get
The actual response contains many additional fields that are
omitted here for clarity. The response format is exactly the same as
-used in ``config-get``, just limited to returning the shared network's
+used in :isccmd:`config-get`, just limited to returning the shared network's
information.
.. isccmd:: network4-add
"text": "A new IPv4 shared network 'floor13' added"
}
-The ``network6-add`` command uses the same syntax for both the query and the
+The :isccmd:`network6-add` command uses the same syntax for both the query and the
response. However, there are some parameters that are IPv4-only (e.g.
``match-client-id``) and some that are IPv6-only (e.g. ``interface-id``). The same
applies to subnets within the network.
These commands are used to delete existing shared networks. Both
commands take exactly one parameter, ``name``, that specifies the name of
-the network to be removed. An example invocation of the ``network4-del``
+the network to be removed. An example invocation of the :isccmd:`network4-del`
command looks as follows:
::
"text": "IPv4 shared network 'floor13' deleted"
}
-The ``network6-del`` command uses exactly the same syntax for both the
+The :isccmd:`network6-del` command uses exactly the same syntax for both the
command and the response.
If there are any subnets belonging to the shared network being deleted,
called ``subnets-action`` that, if specified, takes one of two possible
values: ``keep`` (which is the default) and ``delete``. It controls
whether the subnets are demoted to plain subnets or removed. An example
-usage in the ``network6-del`` command that deletes the shared network and all
+usage in the :isccmd:`network6-del` command that deletes the shared network and all
subnets in it could look as follows:
::
}
Alternatively, to completely remove the subnets, it is possible to use the
-``subnet4-del`` or ``subnet6-del`` commands.
+:isccmd:`subnet4-del` or :isccmd:`subnet6-del` commands.
.. isccmd:: network4-subnet-add
.. _command-network4-subnet-add:
These commands are used to add existing subnets to existing shared
networks. There are several ways to add a new shared network. The system
administrator can add the whole shared network at once, either by
-editing a configuration file or by calling the ``network4-add`` or
-``network6-add`` command with the desired subnets in it. This approach
+editing a configuration file or by calling the :isccmd:`network4-add` or
+:isccmd:`network6-add` command with the desired subnets in it. This approach
works well for completely new shared subnets. However, there may be
cases when an existing subnet is running out of addresses and needs to
be extended with additional address space; in other words, another subnet
needs to be added on top of it. For this scenario, a system administrator
-can use ``network4-add`` or ``network6-add``, and then add an existing
+can use :isccmd:`network4-add` or :isccmd:`network6-add`, and then add an existing
subnet to this newly created shared network using
-``network4-subnet-add`` or ``network6-subnet-add``.
+:isccmd:`network4-subnet-add` or :isccmd:`network6-subnet-add`.
-The ``network4-subnet-add`` and ``network6-subnet-add`` commands take
+The :isccmd:`network4-subnet-add` and
+:isccmd:`network6-subnet-add` commands take
two parameters: ``id``, which is an integer and specifies the ID of
an existing subnet to be added to a shared network; and ``name``, which
specifies the name of the shared network to which the subnet will be added. The
subnet must not belong to any existing network; to
reassign a subnet from one shared network to another, use the
-``network4-subnet-del`` or ``network6-subnet-del`` commands first.
+:isccmd:`network4-subnet-del` or
+:isccmd:`network6-subnet-del` command commands first.
-An example invocation of the ``network4-subnet-add`` command looks as
+An example invocation of the :isccmd:`network4-subnet-add` command looks as
follows:
::
"text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor13'"
}
-The ``network6-subnet-add`` command uses exactly the same syntax for both the
+The :isccmd:`network6-subnet-add` command uses exactly the same syntax for both the
command and the response.
.. note::
These commands are used to remove a subnet that is part of an existing
shared network and demote it to a plain, stand-alone subnet.
-To remove a subnet completely, use the ``subnet4-del`` or ``subnet6-del``
-commands instead. The ``network4-subnet-del`` and
-``network6-subnet-del`` commands take two parameters: ``id``, which is
+To remove a subnet completely, use the :isccmd:`subnet4-del` or :isccmd:`subnet6-del`
+commands instead. The :isccmd:`network4-subnet-del` and
+:isccmd:`network6-subnet-del` commands take two parameters: ``id``, which is
an integer and specifies the ID of an existing subnet to be removed from
a shared network; and ``name``, which specifies the name of the shared
network from which the subnet will be removed.
-An example invocation of the ``network4-subnet-del`` command looks as
+An example invocation of the :isccmd:`network4-subnet-del` command looks as
follows:
::
"text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
}
-The ``network6-subnet-del`` command uses exactly the same syntax for both the
+The :isccmd:`network6-subnet-del` command uses exactly the same syntax for both the
command and the response.
Another use case for user contexts may be storing comments and other
information that will be retained by Kea. Regular comments are discarded
when the configuration is loaded, but user contexts are retained. This is
-useful if administrators want their comments to survive ``config-set`` or ``config-get``
+useful if administrators want their comments to survive :isccmd:`config-set` or :isccmd:`config-get`
operations, for example.
If user context is supported in a given context, the parser translates
Sysrepo continues to undergo major changes that are backward-incompatible,
and Kea versions 2.3.2 do not support Sysrepo earlier than versions 2.x.
-``libreload`` command
----------------------
+:isccmd:`libreload` command
+----------------------------------------
-The ``libreload`` command was deprecated in Kea 2.3.4. The code to handle this command is
+The :isccmd:`libreload` command was deprecated in Kea 2.3.4. The code to handle this command is
still there, but there are reports of it being buggy and not really usable.
Kea 2.3 and 2.4 versions will produce a warning when this command
is used, and it will be removed entirely sometime in the 2.5 branch.
Reclaiming Expired Leases via Command
=====================================
-The ``leases-reclaim`` command can be used to trigger lease reclamation at
+The :isccmd:`leases-reclaim` command can be used to trigger lease reclamation at
any time. Please consult the :ref:`command-leases-reclaim` section
for details about using this command.
to specify multiple targets.
- ``command`` specifies the command to be sent. If not specified, the
- ``list-commands`` command is used.
+ :isccmd:`list-commands` command is used.
Other switches are:
For a list of available commands, see :ref:`ctrl-channel`;
additional commands may be provided by hook libraries. For a list of
-all supported commands from the CA, use the ``list-commands`` command.
+all supported commands from the CA, use the :isccmd:`list-commands` command.
The following shows a simple example of usage:
^D
After the command line is entered, the program waits for command
-parameters to be entered. Since ``list-commands`` does not take any
+parameters to be entered. Since :isccmd:`list-commands` does not take any
arguments, Ctrl-D (represented in the above example by "^D")
indicates end-of-file and terminates the parameter input. The shell
then contacts the CA and prints out the list of available commands
The Kea shell will likely be most frequently used in
scripts; the next example shows a simple scripted execution. It sends
-the command ``config-write`` to the CA (the ``--service`` parameter has not
+the command :isccmd:`config-write` to the CA (the ``--service`` parameter has not
been used), along with the parameters specified in param.json. The
result will be stored in result.json.
All of the statistics supported by Kea's servers are initialized upon the servers' startup
and are returned in response to the commands such as
-``statistic-get-all``. The runtime statistics concerning DHCP packets
+:isccmd:`statistic-get-all`. The runtime statistics concerning DHCP packets
processed are initially set to 0 and are reset upon the server
restart.
Per-subnet statistics are recalculated when reconfiguration takes place.
In general, once a statistic is initialized it is held in the manager until
-explicitly removed, via ``statistic-remove`` or ``statistic-remove-all``,
+explicitly removed, via :isccmd:`statistic-remove` or
+:isccmd:`statistic-remove-all`,
or when the server is shut down.
Removing a statistic that is updated frequently makes little sense, as
it will be re-added when the server code next records that statistic.
-The ``statistic-remove`` and ``statistic-remove-all`` commands are
+The :isccmd:`statistic-remove` and
+:isccmd:`statistic-remove-all` commands are
intended to remove statistics that are not expected to be observed in
the near future. For example, a misconfigured device in a network may
cause clients to report duplicate addresses, so the server will report
The ``statistic-get`` Command
-----------------------------
-The ``statistic-get`` command retrieves a single statistic. It takes a
+The :isccmd:`statistic-get` command retrieves a single statistic. It takes a
single-string parameter called ``name``, which specifies the statistic
name. An example command may look like this:
The ``statistic-reset`` Command
-------------------------------
-The ``statistic-reset`` command sets the specified statistic to its
+The :isccmd:`statistic-reset` command sets the specified statistic to its
neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time
duration, and "" for string type. It takes a single-string parameter
called ``name``, which specifies the statistic name. An example command
The ``statistic-remove`` Command
--------------------------------
-The ``statistic-remove`` command deletes a single statistic. It
+The :isccmd:`statistic-remove` command deletes a single statistic. It
takes a single-string parameter called ``name``, which specifies the
statistic name. An example command may look like this:
The ``statistic-get-all`` Command
---------------------------------
-The ``statistic-get-all`` command retrieves all statistics recorded. An
+The :isccmd:`statistic-get-all` command retrieves all statistics recorded. An
example command may look like this:
::
The ``statistic-reset-all`` Command
-----------------------------------
-The ``statistic-reset`` command sets all statistics to their neutral
+The :isccmd:`statistic-reset` command sets all statistics to their neutral
values: 0 for integer, 0.0 for float, 0h0m0s0us for time duration, and
"" for string type. An example command may look like this:
The ``statistic-remove-all`` Command
------------------------------------
-The ``statistic-remove-all`` command attempts to delete all statistics. An
+The :isccmd:`statistic-remove-all` command attempts to delete all statistics. An
example command may look like this:
::
The ``statistic-sample-age-set`` Command
----------------------------------------
-The ``statistic-sample-age-set`` command sets a time-based limit
+The :isccmd:`statistic-sample-age-set` command sets a time-based limit
on samples for a given statistic. It takes two parameters: a string
called ``name``, which specifies the statistic name, and an integer value called
``duration``, which specifies the time limit for the given statistic in seconds.
The ``statistic-sample-age-set-all`` Command
--------------------------------------------
-The ``statistic-sample-age-set-all`` command sets time-based limits
+The :isccmd:`statistic-sample-age-set-all` command sets time-based limits
on samples for all statistics. It takes a single-integer parameter
called ``duration``, which specifies the time limit for the statistic
in seconds. An example command may look like this:
The ``statistic-sample-count-set`` Command
------------------------------------------
-The ``statistic-sample-count-set`` command sets a size-based limit
+The :isccmd:`statistic-sample-count-set` command sets a size-based limit
on samples for a given statistic. An example command may look
like this:
The ``statistic-sample-count-set-all`` Command
----------------------------------------------
-The ``statistic-sample-count-set-all`` command sets size-based limits
+The :isccmd:`statistic-sample-count-set-all` command sets size-based limits
on samples for all statistics. An example command may look
like this:
a limit prevents unlimited memory growth.
There are two ways to define the limits: time-based (e.g. keep samples from
the last 5 minutes) and size-based. The size-based
-limit can be changed using one of two commands: ``statistic-sample-count-set``,
-to set a size limit for a single statistic, and ``statistic-sample-count-set-all``,
+limit can be changed using one of two commands: :isccmd:`statistic-sample-count-set`,
+to set a size limit for a single statistic, and :isccmd:`statistic-sample-count-set-all`,
to set size-based limits for all statistics. To set time-based
-limits for a single statistic, use ``statistic-sample-age-set``; use
-``statistic-sample-age-set-all`` to set time-based limits for all statistics.
+limits for a single statistic, use :isccmd:`statistic-sample-age-set`; use
+:isccmd:`statistic-sample-age-set-all` to set time-based limits for all statistics.
For a given statistic only one type of limit can be active; storage
is limited by either time or size, not both.
projects / thirdparty / kea.git / commitdiff
