cb_cmds: Configuration Backend Commands
=======================================
-This section describes the ``cb_cmds`` hooks library which is used to
+This section describes the ``cb_cmds`` hooks library, which is used to
manage Kea servers' configurations in the Configuration Backends. This
-library must be used in conjuction with the available CB hooks libraries
-implementing the common APIs to create, read, update and delete (CRUD)
+library must be used in conjunction with the available CB hooks libraries
+implementing the common APIs to create, read, update, and delete (CRUD)
the configuration information in the respective databases. For example:
the ``mysql_cb`` hooks library, released in Kea 1.6.0, implements this
API for MySQL. In order to manage the configuration information in the
-MySQL database both ``mysql_cb`` and ``cb_cmds`` libraries must be
+MySQL database, both the ``mysql_cb`` and ``cb_cmds`` libraries must be
loaded by the server used for the configuration management.
-The ``cb_cmds`` library is only available to ISC customers with a
+The ``cb_cmds`` library is only available to ISC customers with a paid
support contract.
**Note**
- This library may only be loaded by the ``kea-dhcp4`` or the
+ This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
Commands Structure
There are 5 types of commands supported by this library:
-- ``del`` - delete selected object from the database, e.g.
- ``remote-global-parameter4-del``
+- ``del`` - delete the selected object from the database, e.g.
+ ``remote-global-parameter4-del``.
-- ``get`` - fetch selected object from the database, e.g.
- ``remote-subnet4-get``,
+- ``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. ``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
- information about each object comparing to the output of ``get-all``,
+ information about each object comparing 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. ``remote-option4-global-set``.
-All types of commands accept optional ``remote`` map which selects the
+All types of commands accept an optional ``remote`` map which selects the
database instance to which the command refers. For example:
::
}
selects the MySQL database, running on host 192.0.2.33 and port 3302, to
-fetch the list of subnets from. All parameters in the ``remote`` are
-optional. The ``port`` parameter can be only specified in conjuction
-with the ``host``. If no parameters in the ``remote`` parameter are to
+fetch the list of subnets from. All parameters in the ``remote`` argument are
+optional. The ``port`` parameter can be only specified in conjunction
+with the ``host``. If no options in the ``remote`` parameter are to
be specified, the parameter should be omitted. In this case, the server
will use the first backend listed in the ``config-control`` map within
the configuration of the server receiving the command.
**Note**
- In the Kea 1.6.0 release, it is possible to configure the Kea server
+ As of the Kea 1.6.0 release, it is possible to configure the Kea server
to use only one configuration backend. Strictly speaking, it is
- possible to point Kea server to at most one MySQL database using the
+ possible to point the Kea server to at most one MySQL database using the
``config-control`` parameter. That's why, in this release, the
- ``remote`` parameter may be omitted in the commands because the
- cb_cmds hooks library will use by default the sole backend.
+ ``remote`` parameter may be omitted in the commands, because the
+ cb_cmds hooks library will use the sole backend by default.
.. _cb-cmds-dhcp:
This section describes and gives some examples of the control commands
implemented by the ``cb_cmds`` hooks library, to manage the
configuration information of the DHCPv4 and DHCPv6 servers. Many of the
-commands are almost identical between DHCPv4 and DHCPv6, i.e. only
-differ by the command name. Other commands slightly differ by the
-structure of the inserted data, e.g. the structure of the IPv4 subnet
-information is different than the structure of the IPv6 subnet.
-Nevertheless, they still share the structure of the command arguments
+commands are almost identical between DHCPv4 and DHCPv6; they only
+differ by the command name. Other commands differ slightly by the
+structure of the inserted data; for example, the structure of the IPv4 subnet
+information is different than that of the IPv6 subnet.
+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 the usage
+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
+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
-as: DHCPv4 command, DHCPv4 parameter, DHCPv6 command, DHCPv6 parameter
+as: DHCPv4 command, DHCPv4 parameter, DHCPv6 command, DHCPv6 parameter,
etc.
.. _cb-cmds-metadata:
~~~~~~~~
The typical response to the ``get`` or ``list`` command includes a list
-of returned objects (e.g. subnets) and each such object contains the
-``metadata`` map with some database specific information describing this
+of returned objects (e.g. subnets), and each such object contains the
+``metadata`` map with some database-specific information describing this
object. In other words, the metadata contains any information about the
-fetched object which may be useful for the administrator, but is not the
+fetched object which may be useful for the administrator, but which is not
part of the object specification from the DHCP server standpoint. In the
Kea 1.6.0 release, the metadata is limited to the ``server-tag``, which
-describescthe association of the object with the particular server or
+describes the association of the object with a particular server or
all servers. The server tag is always set to ``all`` in the Kea 1.6.0
beta release.
"count": 1
}
}
-
+
Client implementations must not assume that the metadata contains only
-the ``server-tag`` parameter. In the future releases this map will be
+the ``server-tag`` parameter. In future releases, this map will be
extended with additional information, e.g. object modification time, log
-message created during the last modification etc.
+message created during the last modification, etc.
.. _command-remote-global-parameter4-del:
-remote-global-parameter4-del, remote-global-parameter6-del commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-global-parameter4-del, remote-global-parameter6-del Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This command is used to delete a global DHCP parameter from the
-configuration database. When the parameter is deleted from the database
+These commands are used to delete a global DHCP parameter from the
+configuration database. When the parameter is deleted from the database,
the server will use the value specified in the configuration file for
-this parameter or a default value if the parameter is not specified in
+this parameter, or a default value if the parameter is not specified in
the configuration file.
The following command attempts to delete the DHCPv4 ``renew-timer``
}
}
}
-
+
.. _command-remote-global-parameter4-get:
-remote-global-parameter4-get, remote-global-parameter6-get commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-global-parameter4-get, remote-global-parameter6-get Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch a scalar global DHCP parameter from the
configuration database.
}
}
}
-
+
The returned value has one of the four scalar types: string, integer,
-real or boolean. Non scalar global configuration parameters, such as map
+real, or boolean. Non-scalar global configuration parameters, such as map
or list, are not returned by this command.
-In case of the example above the string value is returned, e.g.:
+In the case of the example above, the string value is returned, e.g.:
::
"count": 1
}
}
-
+
The example response for the integer value is:
"count": 1
}
}
-
+
The real value:
"count": 1
}
}
-
+
Finally, the boolean value:
"count": 1
}
}
-
+
.. _command-remote-global-parameter4-get-all:
-remote-global-parameter4-get-all, remote-global-parameter6-get-all commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-global-parameter4-get-all, remote-global-parameter6-get-all Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch all global DHCP parameters from the
database. They include no arguments besides the optional ``remote`` map.
.. _command-remote-global-parameter4-set:
-remote-global-parameter4-set
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-global-parameter4-set Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to create scalar global DHCP parameters in the
database. If any of the parameters already exists, its value is replaced
as a result of this command. It is possible to set multiple parameters
-within a single command, each having one of the four types: a string,
-integer, real and boolean. For example:
+within a single command, each having one of the four types: string,
+integer, real, and boolean. For example:
::
}
}
}
-
+
An error is returned if any of the parameters is not supported by the
DHCP server or its type does not match. Care should be taken when
-multiple parameters are specified in a single command because it is
+multiple parameters are specified in a single command, because it is
possible that only some of the parameters are stored successfully and
-some fail. If an error occurred when processing this command, it is
+some 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 been stored/updated successfully and which
-failed.
+have failed.
.. _command-remote-network4-del:
-remote-network4-del, remote-network6-del commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-network4-del, remote-network6-del Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to delete an IPv4 or IPv6 shared network from
the database. The optional parameter ``subnets-action`` determines
whether the subnets belonging to the deleted shared network should also
-be deleted or preserved. The ``subnets-action`` defaults to ``keep``,
+be deleted or preserved. The ``subnets-action`` parameter defaults to ``keep``,
which preserves the subnets. If it is set to ``delete``, the subnets are
deleted along with the shared network.
}
}
}
-
-deletes the "level3" IPv6 shared network. The subnets are preserved but
+
+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``.
+``network[46]-del`` commands with respect to the ``subnets-action`` parameter.
.. _command-remote-network4-get:
-remote-network4-get, remote-network6-get commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-network4-get, remote-network6-get Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These commands are used to retrieve the information about an IPv4 or
+These commands are used to retrieve information about an IPv4 or
IPv6 shared network. The optional parameter ``subnets-include`` denotes
whether the subnets belonging to the shared network should also be
-returned. This parameter defaults to ``no`` in which case the subnets
+returned. This parameter defaults to ``no``, in which case the subnets
are not returned. If this parameter is set to ``full``, the subnets are
returned together with the shared network.
}
}
}
-
+
.. _command-remote-network4-list:
-remote-network4-list, remote-network6-list commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-network4-list, remote-network6-list Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to list all IPv4 or IPv6 shared networks in the
particular database. The returned information about each shared network
-merely contains the shared network name and the metadata. In order to
-fetch the detailed information about the selected shared network, use
+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 ``remote-network[46]-list`` takes no argument except the optional
.. _command-remote-network4-set:
-remote-network4-set
-~~~~~~~~~~~~~~~~~~~
+The remote-network4-set, remote-network6-set Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These commands creates new or replaces an existing IPv4 or IPv6 shared
+These commands create a new or replace an existing IPv4 or IPv6 shared
network in the database. The structure of the shared network information
is the same as in the Kea configuration file (see
-`??? <#shared-network4>`__ and `??? <#shared-network6>`__ for details),
-except that it is not allowed to specify subnets along with the shared
-network information. Including the ``subnet4`` or ``subnet6`` parameter
+:ref:`shared-network4` and :ref:`shared-network6` for details),
+except that specifying subnets along with the shared
+network information is not allowed. Including the ``subnet4`` or ``subnet6`` parameter
within the shared network information will result in an error.
-These commands are intended to be used for managing the shared network
-specific information and DHCP options. In order to associate and
-disassociate the subnets with the shared networks the
+These commands are intended to be used for managing the shared
+network-specific information and DHCP options. In order to associate and
+disassociate the subnets with the shared networks, the
``remote-subnet[46]-set`` commands should be used.
The following command adds the IPv6 shared network "level3" to the
}
}
}
-
-This command includes the ``interface`` parameter which sets the shared
-network level interface name. Remaining shared network level parameters,
+
+This command includes the ``interface`` parameter, which sets the shared
+network-level interface name. Any remaining shared network-level parameters,
which are not specified with the command, will be marked as
"unspecified" in the database. The DHCP server will use the global
values for unspecified parameters or, if the global values are not
**Note**
- Same as for other "set" commands, this command replaces the entire
- information about the given shared network in the database if the
+ As with other "set" commands, this command replaces all the
+ information about the given shared network in the database, if the
shared network already exists. Therefore, when sending this command,
make sure to always include all parameters that must be specified for
- the updated shared network instance. Any unspecified parameter will
+ the updated shared-network instance. Any unspecified parameter will
be marked unspecified in the database, even if its value was present
prior to sending the command.
.. _command-remote-option-def4-del:
-remote-option-def4-del, remote-option-def6-del commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-option-def4-del, remote-option-def6-del Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to delete a DHCP option definition from the
database. The option definition is identified by an option code and
}
}
}
-
+
deletes the definition of the option having the code of 1 and belonging
to the option space "isc". The default option spaces are "dhcp4" and
-"dhcp6" for the DHCPv4 and DHCPv6 top level options respectively.
+"dhcp6" for the DHCPv4 and DHCPv6 top-level options, respectively.
.. _command-remote-option-def4-get:
-remote-option-def4-get, remote-option-def6-get commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-option-def4-get, remote-option-def6-get Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch a specified DHCP option definition from
the database. The option definition is identified by the option code and
option space. The default option spaces are "dhcp4" and "dhcp6" for the
-DHCPv4 and DHCPv6 top level options respectively.
+DHCPv4 and DHCPv6 top-level options, respectively.
The following command retrieves a DHCPv4 option definition having the
code of 1 and belonging to option space "isc":
}
}
}
-
+
.. _command-remote-option-def4-get-all:
-remote-option-def4-get-all, remote-option-def6-get-all commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-option-def4-get-all, remote-option-def6-get-all Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch all DHCP option definitions from the
-database. It takes no arguments except the optional ``remote`` map.
+database. They take no arguments except the optional ``remote`` map.
.. _command-remote-option-def4-set:
-remote-option-def4-set, remote-option-def6-set commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-option-def4-set, remote-option-def6-set Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands create a new DHCP option definition or replace an
existing option definition in the database. The structure of the option
definition information is the same as in the Kea configuration file (see
-`??? <#dhcp4-custom-options>`__ and `??? <#dhcp6-custom-options>`__).
-The following command creates the DHCPv4 option definition in the top
-level "dhcp4" option space:
+:ref:`dhcp4-custom-options` and :ref:`dhcp6-custom-options`).
+The following command creates the DHCPv4 option definition in the
+top-level "dhcp4" option space:
::
}
}
}
-
+
.. _command-remote-option4-global-del:
-remote-option4-global-del, remote-option6-global-del commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-option4-global-del, remote-option6-global-del Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to delete a global DHCP option from the
database. The option is identified by an option code and option space.
}
}
}
-
-The "dhcp4" is the top level option space where the standard DHCPv4
+
+The "dhcp4" is the top-level option space where the standard DHCPv4
options belong.
.. _command-remote-option4-global-get:
-remote-option4-global-get, remote-option6-global-get commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-option4-global-get, remote-option6-global-get Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch a global DHCP option from the database.
-The option is identified by the code and option space. The top level
+The option is identified by the code and option space. The top-level
option spaces where DHCP standard options belong are called "dhcp4" and
-"dhcp6" for the DHCPv4 and DHCPv6 servers respectively.
+"dhcp6" for the DHCPv4 and DHCPv6 servers, respectively.
The following command retrieves the IPv6 "DNS Servers" (code 23) option:
}
}
}
-
+
.. _command-remote-option4-global-get-all:
-remote-option4-global-get-all, remote-option6-global-get-all commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-option4-global-get-all, remote-option6-global-get-all Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to fetch all global DHCP options from the
-configuration database. It takes no arguments except the optional
+configuration database. They take no arguments except the optional
``remote`` map.
.. _command-remote-option4-global-set:
-remote-option4-global-set, remote-option6-global-set command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-option4-global-set, remote-option6-global-set Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands create a new global DHCP option or replace an existing
option in the database. The structure of the option information is the
-same as in the Kea configuration file (see `??? <#dhcp4-std-options>`__
-and see `??? <#dhcp4-std-options>`__). For example:
+same as in the Kea configuration file (see :ref:`dhcp4-std-options`
+and :ref:`dhcp4-std-options`). For example:
::
}
}
}
-
+
Note that specifying an option name instead of the option code only
works reliably for the standard DHCP options. When specifying a value
-for the user defined DHCP option, the option code should be specified
+for the user-defined DHCP option, the option code should be specified
instead of the name. For example:
::
]
}
}
-
+
.. _command-remote-subnet4-del-by-id:
-remote-subnet4-del-by-id, remote-subnet6-del-by-id command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-subnet4-del-by-id, remote-subnet6-del-by-id Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the first variant of the commands used to delete an IPv4 or IPv6
-subnet from the database. It uses subnet ID to identify the subnet. For
-example, in order to delete the IPv4 subnet with ID of 5:
+subnet from the database. It uses the subnet ID to identify the subnet. For
+example, to delete the IPv4 subnet with an ID of 5:
::
}
}
}
-
+
.. _command-remote-subnet4-del-by-prefix:
-remote-subnet4-del-by-prefix, remote-subnet6-del-by-prefix commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-subnet4-del-by-prefix, remote-subnet6-del-by-prefix Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the second variant of the commands used to delete an IPv4 or
IPv6 subnet from the database. It uses the subnet prefix to identify the
}
}
}
-
+
.. _command-remote-subnet4-get-by-id:
-remote-subnet4-get-by-id, remote-subnet6-get-by-id commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-subnet4-get-by-id, remote-subnet6-get-by-id Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the first variant of the commands used to fetch an IPv4 or IPv6
subnet from the database. It uses a subnet ID to identify the subnet.
}
}
}
-
+
.. _command-remote-subnet4-get-by-prefix:
-remote-subnet4-get-by-prefix, remote-subnet6-get-by-prefix command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-subnet4-get-by-prefix, remote-subnet6-get-by-prefix Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the second variant of the commands used to fetch an IPv4 or IPv6
subnet from the database. It uses a subnet prefix to identify the
}
}
}
-
+
.. _command-remote-subnet4-list:
-remote-subnet4-list, remote-subnet6-list commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-subnet4-list, remote-subnet6-list Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to list all IPv4 or IPv6 subnets from the
-database. It takes no parameters except the optional ``remote`` map. The
+database. They take no parameters except the optional ``remote`` map. The
returned information about each subnet is limited to subnet identifier,
-prefix and associated shared network name. In order to retrieve full
-information about the selected subnet use the
-``remote-subnet[46]-get-by-id`` or ``remote-subnet[46]-get-by-prefix``.
+prefix, and associated shared network name. To retrieve full
+information about the selected subnet, use the
+``remote-subnet[46]-get-by-id`` or ``remote-subnet[46]-get-by-prefix`` command.
.. _command-remote-subnet4-set:
-remote-subnet4-set, remote-subnet6-set commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The remote-subnet4-set, remote-subnet6-set Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to create a new IPv4 or IPv6 subnet or replace
an existing subnet in the database. Setting the subnet also associates
or disassociates the subnet with a shared network.
The structure of the subnet information is similar to the structure used
-in the configuration file (see `??? <#dhcp4-configuration>`__ and
-`??? <#dhcp6-configuration>`__). The subnet information conveyed in the
-``remote-subnet[46]-set`` must include additional parameter
-``shared-network-name`` which denotes whether the subnet belongs to a
-shared network or not.
+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
+``shared-network-name``, which denotes whether the subnet belongs to a
+shared network.
Consider the following example:
}
}
}
-
-It creates the subnet and associates the subnet with the "level3" shared
-network. The "level3" must be created with the ``remote-network4-set``
-prior to creating the subnet.
-If the created subnet must be global (not associated with any shared
-network), the ``shared-network-name`` must be explicitly set to
+It creates the subnet and associates it with the "level3" shared
+network. The "level3" shared network must be created with the ``remote-network4-set``
+command prior to creating the subnet.
+
+If the created subnet must be global - that is, not associated with any shared
+network - the ``shared-network-name`` must be explicitly set to
``null``:
::
]
}
}
-
+
The subnet created in the previous example is replaced with the new
-subnet having the same parameters but it becomes global.
+subnet having the same parameters, but it becomes global.
The ``shared-network-name`` parameter is mandatory for the
``remote-subnet4-set`` command.
**Note**
- Same as for other "set" commands, this command replaces the entire
+ As with other "set" commands, this command replaces all the
information about the particular subnet in the database, if the
subnet information is already present. Therefore, when sending this
command, make sure to always include all parameters that must be
**Note**
- This library may only be loaded by the ``kea-dhcp4`` or the
+ This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
High Availability (HA) of the DHCP service is provided by running
------------------------
The Kea HA hook library supports two configurations, also known as HA
-modes: load balancing and hot standby. In the load-balancing mode, two
+modes: load-balancing and hot-standby. In the load-balancing mode, two
servers respond to DHCP requests. The load-balancing function is
implemented as described in `RFC
-3074 <http://tools.ietf.org/html/rfc3074>`__, with each server
+3074 <https://tools.ietf.org/html/rfc3074>`__, with each server
responding to half the received DHCP queries. When one of the servers
allocates a lease for a client, it notifies the partner server over the
-control channel (RESTful API), so the partner can save the lease
+control channel (the RESTful API), so the partner can save the lease
information in its own database. If the communication with the partner
is unsuccessful, the DHCP query is dropped and the response is not
returned to the DHCP client. If the lease update is successful, the
it starts the synchronization.
In the hot-standby configuration, one of the servers is also designated
-as "primary" and the second as "secondary". However, during normal
+as "primary" and the second as "secondary." However, during normal
operation, the primary server is the only one that responds to DHCP
requests. The secondary or standby server receives lease updates from
the primary over the control channel; however, it does not respond to
secondary server detects the failure of the primary, it starts
responding to all DHCP queries.
-In the configurations described above, the primary, secondary, and
-standby are referred to as "active" servers, because they receive lease
+In the configurations described above, the primary and secondary/standby
+are referred to as "active" servers, because they receive lease
updates and can automatically react to the partner's failures by
responding to the DHCP queries which would normally be handled by the
partner. The HA hook library supports another server type/role: backup
-server. The use of a backup server is optional. They can be used in both
-load balancing and hot standby setup, in addition to the active servers.
+server. The use of a backup server is optional, and can be implemented in both
+load-balancing and hot-standby setup, in addition to the active servers.
There is no limit on the number of backup servers in the HA setup;
however, the presence of backup servers increases the latency of DHCP
responses, because not only do active servers send lease updates to each
Synchronized clocks are essential for the HA setup to operate reliably.
The servers share lease information via lease updates and during
synchronization of the databases. The lease information includes the
-time when the lease has been allocated and when it expires. Some clock
+time when the lease was allocated and when it expires. Some clock
skew between the servers participating in the HA setup usually exists;
this is acceptable as long as the clock skew is relatively low, compared
to the lease lifetimes. However, if the clock skew becomes too high, the
heartbeat command. If the clock skew exceeds 30 seconds, a warning log
message is issued. The administrator may correct this problem by
synchronizing the clocks (e.g. using NTP); the servers should notice the
-clock skew correction and stop issuing the warning
+clock skew correction and stop issuing the warning.
If the clock skew is not corrected and exceeds 60 seconds, the HA
service on each of the servers is terminated, i.e. the state machine
``ha-heartbeat`` command sent over the RESTful API. If the partner
server doesn't respond to the ``ha-heartbeat`` command within the
specified amount of time, the communication is considered interrupted
-and the server may (depending on the configuration) use additional
+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 the entire
+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
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 partner from which the leases are
- fetched. The DHCP service is disabled for the maximum time of 60
+ 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 is completed, the syncing server issues the
exchanged and the heartbeats are not sent. Once a server has entered
the "terminated" state, it will remain in this state until it is
restarted. The administrator must correct the issue which caused this
- situation prior to restarting the server (e.g. synchronize clocks).
- Otherwise, the server will return to the "terminated" state once it
+ situation prior to restarting the server (e.g. synchronize the clocks);
+ otherwise, the server will return to the "terminated" state once it
finds that the issue persists.
- ``waiting`` - each started server instance enters this state. The
The DHCP service scopes require some explanation. The HA configuration
must specify a unique name for each server within the HA setup. This
-document uses the following convention within provided examples:
+document uses the following convention within the provided examples:
``server1`` for a primary server, ``server2`` for the secondary or
standby server, and ``server3`` for the backup server. In real life any
names can be used as long as they remain unique.
-In the load-balancing mode there are two scopes named after the active
+In the load-balancing mode there are two scopes specified for the active
servers: ``HA_server1`` and ``HA_server2``. The DHCP queries
load-balanced to ``server1`` belong to the ``HA_server1`` scope and the
queries load-balanced to ``server2`` belong to the ``HA_server2`` scope.
it is greater than the duration of multiple ``heartbeat-delay``
values. When the server detects that communication is interrupted, it
may transition to the ``partner-down`` state (when
- ``max-unacked-clients`` is 0) or trigger the failure- detection
+ ``max-unacked-clients`` is 0) or trigger the failure-detection
procedure using the values of the two parameters below. The default
- value of this parameter is 60000.
+ value of this parameter is 60000 ms.
- ``max-ack-delay`` - is one of the parameters controlling partner
failure-detection. When communication with the partner is
transition to the ``partner-down`` state even though the partner is
still operating. On the other hand, selecting too high a value may
result in never transitioning to the ``partner-down`` state if the DHCP
-traffic in the network is very low (e.g. nighttime), because the number
+traffic in the network is very low (e.g. at nighttime), because the number
of distinct clients trying to communicate with the server could be lower
than the ``max-unacked-clients`` setting.
which already use some other client classification.
Suppose there is a system which classifies devices into two groups:
-phones and laptops, based on some classification criteria specified in
+phones and laptops, based on some classification criteria specified in the
Kea configuration file. Both types of devices are allocated leases from
different address pools. Introducing HA in the load-balancing mode
results in a further split of each of those pools, as each server
- laptops_server2
The corresponding server configuration using advanced classification
-(and ``member`` expression) is provided below. For brevity's sake, the
+(and the ``member`` expression) is provided below. For brevity's sake, the
HA hook library configuration has been removed from this example.
::
can assign leases to both phones and laptops. Both groups of devices are
assigned addresses from different pools. The ``HA_server1`` and
``HA_server2`` classes are built-in (see
-`??? <#classification-using-vendor>`__) and do not need to be declared.
+:ref:`classification-using-vendor`) and do not need to be declared.
They are assigned dynamically by the HA hook library as a result of the
load-balancing algorithm. ``phones_*`` and ``laptop_*`` evaluate to
"true" when the query belongs to a given combination of other classes,
e.g. ``HA_server1`` and ``phones``. The pool is selected accordingly as
a result of such an evaluation.
-Consult `??? <#classify>`__ for details on how to use the ``member``
+Consult :ref:`classify` for details on how to use the ``member``
expression and class dependencies.
.. _ha-hot-standby-config:
}
This configuration is very similar to the load-balancing configuration
-described in `Load-Balancing
-Configuration <#ha-load-balancing-config>`__, with a few notable
+described in :ref:`ha-load-balancing-config`, with a few notable
differences.
The ``mode`` is now set to ``hot-standby``, in which only one server
database synchronization between the active servers, if the exchange of
information about the allocated leases is performed using some other
mechanism. Kea supports various database types that can be used to store
-leases, including MySQL, Postgres, and Cassandra. Those databases
+leases, including MySQL, PostgreSQL, and Cassandra. Those databases
include built-in solutions for data replication which are often used by
Kea administrators to provide redundancy.
An HA-enabled server initiates synchronization of the lease database
after downtime or upon receiving the ``ha-sync`` command. The server
-uses commands described in `??? <#lease-get-page-cmds>`__ to fetch
+uses commands described in :ref:`lease-get-page-cmds` 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 these commands) can be controlled via HA hooks library
-configuration. Increasing the page size decreases the number of lease
+to one of these commands) can be controlled via configuration of the HA hooks
+library. Increasing the page size decreases the number of lease
queries sent to the partner server, but it causes the partner server to
generate larger responses, which lengthens transmission time as well as
increases memory and CPU utilization on both servers. Decreasing the
time-consuming operation. The synchronizing server must gather all
leases from its partner, which yields a large response over the RESTful
interface. The server receives leases using the paging mechanism
-described in `Controlling Lease-Page Size
-Limit <#ha-syncing-page-limit>`__. Before the page of leases is fetched,
+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 the service is already disabled,
this command will reset the timeout for the DHCP service being disabled.
also protected by the timeout. If the synchronization of a single page
of leases takes longer than the specified time, the synchronizing server
terminates the connection and the synchronization fails. Both timeout
-values are controlled by a single configuration parameter:
+values are controlled by a single configuration parameter,
``sync-timeout``. The following configuration snippet demonstrates how
to modify the timeout for automatic re-enabling of the DHCP service on
the partner server and how to increase the timeout for fetching a single
------------------------
The high-availability state machine includes many different states
-described in detail in `Server States <#ha-server-states>`__. The server
+described in detail in :ref:`ha-server-states`. The server
enters each state when certain conditions are met, most often taking
into account the partner server's state. In some states the server
performs specific actions, e.g. synchronization of the lease database in
By default, transitions between the states are performed automatically
and the server administrator has no direct control when the transitions
-take place; in most cases, the administrator doesn't need such control.
+take place; in most cases, the administrator does not need such control.
In some situations, however, the administrator may want to "pause" the
HA state machine in a selected state to perform some additional
administrative actions before the server transitions to the next state.
but it is possible that the partner was also experiencing a failure and
lacks lease information. In this case, it may be required to reconstruct
lease databases on both servers from some external source, e.g. a backup
-server. If the lease database is to be reconstructed via RESTful API,
+server. If the lease database is to be reconstructed via the RESTful API,
the servers should be started in the initial, i.e. ``waiting``, state
and remain in this state while leases are being added. In particular,
the servers should not attempt to synchronize their lease databases nor
The ``pause`` parameter value ``once`` denotes that the state machine
should be paused upon the first transition to the ``waiting`` state;
later transitions to this state will not cause the state machine to
-pause. Two other supported values of the ``pause`` parameter are:
+pause. Two other supported values of the ``pause`` parameter are
``always`` and ``never``. The latter is the 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 sent to the paused server. This command does not take any
-arguments. See `Control Commands for High
-Availability <#ha-control-commands>`__ for details about commands
+arguments. See :ref:`ha-control-commands` for details about commands
specific to the HA hooks library.
It is possible to configure the state machine to pause in more than one
time it transitions to the ``ready`` state and upon the first transition
to the ``partner-down`` state.
-Refer to `Server States <#ha-server-states>`__ for a complete list of
+Refer to :ref:`ha-server-states` for a complete list of
server states. The state machine can be paused in any of the supported
states; however, it is not practical for the ``backup`` and
``terminated`` states because the server never transitions out of these
Control Agent Configuration
---------------------------
-`??? <#kea-ctrl-agent>`__ describes in detail the Kea daemon, which
-provides a RESTful interface to control Kea servers. The same
-functionality is used by the High Availability hook library to establish
+:ref:`kea-ctrl-agent` describes in detail the Kea daemon, which
+provides a RESTful interface to control the Kea servers. The same
+functionality is used by the High Availability hooks library to establish
communication between the HA peers. Therefore, the HA library requires
that the Control Agent (CA) be started for each DHCP instance within the
HA setup. If the Control Agent is not started, the peers will not be
to manually set the HA scopes that are being served.
Note that the backup server can sometimes be used to handle DHCP traffic
-if both active servers are down. The backup servers do not perform
-failover function automatically. Thus, in order to use the backup server
+if both active servers are down. The backup server does not perform
+failover function automatically; thus, in order to use the backup server
to respond to DHCP queries, the server administrator must enable this
function manually.
-The following sections describe commands supported by the HA hook
+The following sections describe commands supported by the HA hooks
library which are available for the administrator.
.. _command-ha-sync:
-ha-sync Command
-~~~~~~~~~~~~~~~
+The ha-sync Command
+~~~~~~~~~~~~~~~~~~~
The ``ha-sync`` command instructs the server to synchronize its local
lease database with the selected peer. The server fetches all leases
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. In order to synchronize the
-peer's database a separate ``ha-sync`` has to be issued to that peer.
+peer's database a separate ``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
``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 will fetch leases from the remote server by issuing
-one or more ``lease4-get-page`` commands. When the lease- database
+synchronizing server fetches leases from the remote server by issuing
+one or more ``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.
The ``max-period`` value should be sufficiently long to guarantee that
-it doesn't elapse before the synchronization is completed. Otherwise,
+it does not elapse before the synchronization is completed. Otherwise,
the DHCP server will automatically enable its DHCP function while the
synchronization is still in progress. If the DHCP server subsequently
allocates any leases during the synchronization, those new (or updated)
.. _command-ha-scopes:
-ha-scopes Command
-~~~~~~~~~~~~~~~~~
+The ha-scopes Command
+~~~~~~~~~~~~~~~~~~~~~
This command allows modification of the HA scopes that the server is
-serving. Consult `Load-Balancing
-Configuration <#ha-load-balancing-config>`__ and `Hot-Standby
-Configuration <#ha-hot-standby-config>`__ to learn what scopes are
+serving. Consult :ref:`ha-load-balancing-config` and
+:ref:`ha-hot-standby-config` to learn what scopes are
available for different HA modes of operation. The ``ha-scopes`` command
has the following structure (DHCPv4 server case):
}
}
-This command configures the server to handle traffic from both
-``HA_server1`` and ``HA_server2`` scopes. In order to disable all scopes
+This command configures the server to handle traffic from both the
+``HA_server1`` and ``HA_server2`` scopes. To disable all scopes
specify an empty list:
::
.. _command-ha-continue:
-ha-continue Command
-~~~~~~~~~~~~~~~~~~~
+The ha-continue Command
+~~~~~~~~~~~~~~~~~~~~~~~
This command is used to resume the operation of the paused HA state
-machine, as described in `Pausing HA State
-Machine <#ha-pause-state-machine>`__. It takes no arguments, so the
+machine, as described in :ref:`ha-pause-state-machine`. It takes no arguments, so the
command structure is as simple as:
::
Introduction
============
-Although Kea offers a lot of flexibility, there may be cases where its
-behavior needs customization. To accommodate this possibility, Kea
-includes the idea of "Hooks". This feature lets Kea load one or more
-dynamically-linked libraries (known as "hooks libraries") and, at
+Kea is both flexible and customizable, via the use of "hooks." This feature
+lets Kea load one or more
+dynamically linked libraries (known as "hooks libraries") and, at
various points in its processing ("hook points"), call functions in
them. Those functions perform whatever custom processing is required.
-The hooks concept also allows keeping the core Kea code reasonably small
-by moving features that some, but not all users find useful to external
-libraries. People who don't need specific functionality simply don't
-load the libraries.
+The hooks concept allows the core Kea code to remain reasonably small
+by moving features to external libraries that some, but not all, users
+find useful. Those with no need for specific functions can simply choose not
+to load the libraries.
-Hooks libraries are loaded by individual Kea processes, not to Kea as a
-whole. This means (for example) that it is possible to associate one set
-of libraries with the DHCP4 server and a different set to the DHCP6
+Hooks libraries are loaded by individual Kea processes, not by Kea as a
+whole. This means, among other things, that it is possible to associate one set
+of libraries with the DHCP4 server and a different set with the DHCP6
server.
Another point to note is that it is possible for a process to load
hooks library functions attached to it. If multiple libraries have
attached a function to a given hook point, Kea calls all of them, in the
order in which the libraries are specified in the configuration file.
-The order may be important: consult the documentation of the libraries
-to see if this is the case.
+The order may be important; consult the documentation of the libraries
+for specifics.
-The next section describes how to configure hooks libraries. If you are
-interested in writing your own hooks library, information can be found
-in the `Kea Developer's
-Guide <https://jenkins.isc.org/job/Kea_doc/doxygen>`__.
+The next section describes how to configure hooks libraries. Users who are
+interested in writing their own hooks library can find information
+in the `Hooks Developer's Guide section of the Kea Developer's
+Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/df/d46/hooksdgDevelopersGuide.html>`__.
Note that some libraries are available under different licenses.
-Note that some libraries may require additional dependencies and/or
-compilation switches to be enabled, e.g. Radius library introduced in
-Kea 1.4 requires FreeRadius-client library to be present. If
---with-free-radius option is not specified, the Radius library will not
+Please also note that some libraries may require additional dependencies and/or
+compilation switches to be enabled, e.g. the RADIUS library introduced in
+Kea 1.4 requires the FreeRadius-client library to be present. If
+--with-free-radius option is not specified, the RADIUS library will not
be built.
-Installing Hook packages
+Installing Hook Packages
========================
**Note**
- The installation procedure has changed in 1.4.0. Kea 1.3.0 and
- earlier needed special switches passed to configure script to detect
- the hook libraries. Please see this KB article:
- https://kb.isc.org/article/AA-01587 .
+ For more details about installing the Kea Premium Hooks package, please read
+ `this Knowledgebase article <https://kb.isc.org/docs/aa-01587>`__.
Some hook packages are included in the base Kea sources. There is no
-need to do anything special to compile or install them, they are covered
-by the usual building and installation procedure. ISC also provides
-several additional hooks in form of various packages. All of those
-packages follow the same installation procedure that is similar to base
-Kea, but has several additional steps. For your convenience, the whole
-procedure is described here. Please refer to `??? <#installation>`__ for
-general overview.
-
-1. Download the package. You will receive detailed instructions how to
-get it separately. This will be a file with a name similar to
-kea-premium-KEAVERSION.tar.gz. Your name may differ depending on which
-package you got.
-
-2. If you have the sources for the corresponding version of the
-open-source Kea package still on your system (from when you installed
-Kea), skip this step. Otherwise extract the Kea source from the original
-tarball you downloaded. For example, if you downloaded Kea KEAVERSION.,
-you should have a tarball called kea-KEAVERSION.tar.gz on your system.
+need to do anything special to compile or install them, as they are covered
+by the usual building and installation procedures. Please
+refer to :ref:`installation` for a general overview of the installation process.
+
+ISC provides several additional premium hooks in the form of packages, which
+follow a similar installation procedure but with several additional steps.
+For your convenience, the premium hooks installation procedure is described in this section.
+
+1. Download the package; detailed instructions are provided separately on how
+to get it. The package will be a file with a name similar to
+kea-premium-KEAVERSION.tar.gz. (The name may vary depending on the package
+purchased.)
+
+2. Administrators who still have the sources for the corresponding version of the
+open-source Kea package still on their system from the initial Kea installation
+should skip this step. Otherwise, extract the Kea source from the original
+tarball that was downloaded. For example, with a download of Kea KEAVERSION.,
+there should be a tarball called kea-KEAVERSION.tar.gz on the system.
Unpack this tarball:
::
your current working directory.
3. Unpack the Kea premium tarball into the directory into which Kea was
-unpacked. For example, assuming that you followed step 2 and that Kea
-KEAVERSION has been unpacked into a kea-KEAVERSION subdirectory and that
-the Kea premium tarball is in your current directory, the following
+unpacked. Once Kea KEAVERSION has been unpacked into a kea-KEAVERSION
+subdirectory and the Kea premium tarball is in the current directory, the following
steps will unpack the premium tarball into the correct location:
::
$ tar xvf ../kea-premium-KEAVERSION.tar.gz
Note that unpacking the Kea premium package will put the files into a
-directory named premium. Regardless of the name of your package, the
-directory will always be called premium, just its content may vary.
+directory named "premium". Regardless of the name of the package, the
+directory will always be called "premium", although its contents will vary
+depending on the premium package.
4. Run autoreconf tools. This step is necessary to update Kea's build
-script to include additional directory. If this tool is not already
-available on your system, you need to install automake and autoconf
-tools. To generate configure script, please use:
+script to include the additional directory. If this tool is not already
+available on the system, install the automake and autoconf
+tools. To generate the configure script, please use:
::
$ autoreconf -i
-5. Rerun configure, using the same configure options as you used when
-originally building Kea. You can check if configure has detected the
+5. Rerun configure, using the same configure options that were used when
+originally building Kea. It is possible to verify that configure has detected the
premium package by inspecting the summary printed when it exits. The
-first section of the output should look something like:
+first section of the output should look something like this:
::
Included Hooks: forensic_log flex_id host_cmds
The last line indicates which specific hooks were detected. Note that
-some hooks may require its own dedicated switches, e.g. radius hook
+some hooks may require their own dedicated switches, e.g. the RADIUS hook
requires extra switches for FreeRADIUS. Please consult later sections of
this chapter for details.
$ make
-If your machine has multiple CPU cores, interesting option to consider
-here is -j X, where X is the number of available cores.
+If the machine has multiple CPU cores, an interesting option to consider
+here is using the argument -j X, where X is the number of available cores.
-7. Install Kea sources together with hooks:
+7. Install Kea sources along with the hooks:
::
$ sudo make install
Note that as part of the installation procedure, the install script will
-eventually venture into premium/ directory and will install additional
+eventually venture into the premium/ directory and will install additional
hook libraries and associated files.
-The installation location of the hooks libraries depends whether you
-specified --prefix parameter to the configure script. If you did not,
-the default location will be /usr/local/lib/kea/hooks. You can verify
-the libraries are installed properly with this command:
+The installation location of the hooks libraries depends on whether the
+--prefix parameter was specified in the configure script. If not,
+the default location will be /usr/local/lib/kea/hooks. The proper installation
+of the libraries can be verified with this command:
::
/usr/local/lib/kea/hooks/libdhcp_legal_log.so
/usr/local/lib/kea/hooks/libdhcp_subnet_cmds.so
-The exact list you see will depend on the packages you have. If you
-specified directory via --prefix, the hooks libraries will be located in
+The exact list returned will depend on the packages installed. If the
+directory was specified via --prefix, the hooks libraries will be located in
{prefix directory}/lib/kea/hooks.
Configuring Hooks Libraries
The hooks libraries for a given process are configured using the
``hooks-libraries`` keyword in the configuration for that process. (Note
-that the word "hooks" is plural). The value of the keyword is an array
-of map structures, each structure corresponding to a hooks library. For
+that the word "hooks" is plural.) The value of the keyword is an array
+of map structures, with each structure corresponding to a hooks library. For
example, to set up two hooks libraries for the DHCPv4 server, the
configuration would be:
**Note**
- This is a change to the syntax used in Kea 0.9.2 and earlier, where
- hooks-libraries was a list of strings, each string being the name of
- a library. The change was made in Kea 1.0 to facilitate the
- specification of library-specific parameters, a capability available
- in Kea 1.1.0 onwards. Libraries should allow a parameter entry where
- to put comments as it is done for many configuration scopes with
- comment and user context.
+ This syntax is effective as of Kea 1.1.0, to facilitate the
+ specification of library-specific parameters. Libraries should allow a
+ parameter entry for comments, as is the case with many configuration
+ scopes.
**Note**
- The library reloading behavior has changed in Kea 1.1.0. Libraries
- are reloaded, even if their list hasn't changed. Kea does that,
+ In all versions of Kea since 1.1.0, libraries
+ are reloaded even if their lists have not changed,
because the parameters specified for the library (or the files those
parameters point to) may have changed.
-Libraries may have additional parameters. Those are not mandatory in the
-sense that there may be libraries that don't require them. However, for
-specific library there is often specific requirement for specify certain
-set of parameters. Please consult the documentation for your library for
+Libraries may have additional parameters that are not mandatory, in the
+sense that there may be libraries that do not require them. However, for a
+specific library there is often a specific requirement to specify a certain
+set of parameters. Please consult the documentation for each individual library for
details. In the example above, the first library has no parameters. The
-second library has five parameters, specifying mail (string parameter),
-floor (integer parameter), debug (boolean parameter) and even lists
-(list of strings) and maps (containing strings). Nested parameters could
+second library has five parameters: specifying mail (string parameter),
+floor (integer parameter), debug (boolean parameter), lists
+(list of strings), and maps (containing strings). Nested parameters can
be used if the library supports it. This topic is explained in detail in
-the Hooks Developer's Guide in the "Configuring Hooks Libraries"
-section.
+the `Hooks Developer's Guide section of the Kea Developer's Guide
+<https://jenkins.isc.org/job/Kea_doc/doxygen/df/d46/hooksdgDevelopersGuide.html>`__.
Notes:
- The full path to each library should be given.
-- As noted above, order may be important - consult the documentation
- for each library.
+- As noted above, the order in which the hooks are called may be important;
+ consult the documentation for each library for specifics.
- An empty list has the same effect as omitting the ``hooks-libraries``
- configuration element all together.
+ configuration element altogether.
**Note**
As described above, the hooks functionality provides a way to customize
a Kea server without modifying the core code. ISC has chosen to take
advantage of this feature to provide functions that may only be useful
-to a subset of Kea users. To this end ISC has created some hooks
-libraries; these discussed in the following sections.
+to a subset of Kea users. To this end, ISC has created some hooks
+libraries, discussed in the following sections.
**Note**
- Some of these libraries will be available with the base code while
+ Some of these libraries are available with the base code, while
others will be shared with organizations supporting development of
- Kea , possibly as a 'benefit' or 'thank you' for helping to sustain
- the larger Kea project. If you would like to get access to those
- libraries, please consider taking out a support contract: this
+ Kea. Users who would like to get access to those premium
+ libraries should consider purchasing a support contract from ISC. This
includes professional support, advance security notifications, input
- into our roadmap planning, and many other benefits, while helping
- making Kea sustainable in the long term.
+ into ISC's roadmap planning, and many other benefits, while helping
+ make Kea sustainable in the long term.
The following table provides a list of libraries currently available
from ISC. It is important to pay attention to which libraries may be
loaded by which Kea processes. It is a common mistake to configure the
``kea-ctrl-agent`` process to load libraries that should, in fact, be
loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` processes. If a library
-from ISC doesn't work as expected, please make sure that it has been
+from ISC does not work as expected, please make sure that it has been
loaded by the correct process per the table below.
**Warning**
hooks libraries can be loaded by this process), none of ISC's current
hooks libraries should be loaded by the Control Agent.
-.. table:: List of available hooks libraries
+.. table:: List of Available Hooks Libraries
+-----------------+-----------------+-----------------+-----------------+
| Name | Availability | Since | Load by process |
| Statistics | Kea sources | Kea 1.4.0 | kea-dhcp4, |
| Commands | | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
- | Radius | Support | Kea 1.4.0 | kea-dhcp4, |
+ | RADIUS | Support | Kea 1.4.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Host Cache | Support | Kea 1.4.0 | kea-dhcp4, |
+-----------------+-----------------+-----------------+-----------------+
ISC hopes to see more hooks libraries become available as time
-progresses, both developed internally and externally. Since this list
-may evolve dynamically, we decided to keep it on a wiki page, available
+progresses, developed both internally and externally. Since this list
+may evolve dynamically, it is maintained on a wiki page, available
at this link:
-https://gitlab.isc.org/isc-projects/kea/wikis/Hooks-available. If you
-are a developer or are aware of any hooks libraries not listed there,
-please send a note to the kea-users or kea-dev mailing lists and someone
-will update it.
+https://gitlab.isc.org/isc-projects/kea/wikis/Hooks-available.
+Developers or others who are aware of any hooks libraries not listed there
+are asked to please send a note to the kea-users or kea-dev mailing lists for
+updating.
The libraries developed by ISC are described in detail in the following
sections.
------------------------------
The user_chk library is the first hooks library published by ISC. It
-attempts to serve several purposes:
+serves several purposes:
- To assign "new" or "unregistered" users to a restricted subnet, while
"known" or "registered" users are assigned to unrestricted subnets.
- To allow DHCP response options or vendor option values to be
- customized based upon user identity.
+ customized based on user identity.
-- To provide a real time record of the user registration activity which
+- To provide a real-time record of user registration activity, which
can be sampled by an external consumer.
- To serve as a demonstration of various capabilities possible using
the hooks interface.
-Once loaded, the library allows segregating incoming requests into known
-and unknown clients. For known clients, the packets are processed mostly
-as usual, except it is possible to override certain options being sent.
-That can be done on a per host basis. Clients that are not on the known
+Once loaded, the library allows the separation of incoming requests into known
+and unknown clients. For known clients, packets are processed
+as usual, although it is possible to override the sending of certain options
+on a per-host basis. Clients that are not on the known
hosts list will be treated as unknown and will be assigned to the last
subnet defined in the configuration file.
-As an example of use, this behavior may be used to put unknown users
-into a separate subnet that leads to a walled garden, where they can
+As an example of a use case, this behavior may be implemented to put unknown users
+into a separate subnet that leads to a "walled garden," where they can
only access a registration portal. Once they fill in necessary data,
their details are added to the known clients file and they get a proper
address after their device is restarted.
**Note**
This library was developed several years before the host reservation
- mechanism has become available. Currently host reservation is much
- more powerful and flexible, but nevertheless the user_chk capability
- to consult and external source of information about clients and alter
- Kea's behavior is useful and remains of educational value.
+ mechanism became available. Host reservation is much
+ more powerful and flexible, but the user_chk capability
+ to consult an external source of information about clients and alter
+ Kea's behavior remains useful and of educational value.
The library reads the /tmp/user_chk_registry.txt file while being loaded
-and each time an incoming packet is processed. The file is expected to
-have each line contain a self-contained JSON snippet which must have the
+and each time an incoming packet is processed. Each line of the file is expected to
+contain a self-contained JSON snippet which must have the
following two entries:
-- ``type``, whose value is "HW_ADDR" for IPv4 users or "DUID" for IPv6
- users
+- ``type`` - whose value is "HW_ADDR" for IPv4 users or "DUID" for IPv6
+ users.
-- ``id``, whose value is either the hardware address or the DUID from
+- ``id`` - whose value is either the hardware address or the DUID from
the request formatted as a string of hex digits, with or without ":"
delimiters.
-and may have the zero or more of the following entries:
+and may have zero or more of the following entries:
-- ``bootfile`` whose value is the pathname of the desired file
+- ``bootfile`` - whose value is the pathname of the desired file.
-- ``tftp_server`` whose value is the hostname or IP address of the
- desired server
+- ``tftp_server`` - whose value is the hostname or IP address of the
+ desired server.
A sample user registry file is shown below:
{ "type" : "DUID", "id" : "00:01:00:01:19:ef:e6:3b:00:0c:01:02:03:06", "tftp_server" : "tftp.v6.example.com" }
As with any other hooks libraries provided by ISC, internals of the
-user_chk code are well documented. You can take a look at the `Kea
-Developer's Guide section dedicated to the user_chk
-library <https://jenkins.isc.org/job/Kea_doc/doxygen/d8/db2/libdhcp_user_chk.html>`__
-that discusses how the code works internally. That, together with our
-general entries in `Hooks Framework
-section <https://jenkins.isc.org/job/Kea_doc/doxygen>`__ should give you
-some pointers how to extend this library and perhaps even write your own
+user_chk code are well-documented. Users may refer to the `user_chk
+library section of the Kea Developer's Guide
+<https://jenkins.isc.org/job/Kea_doc/doxygen/d8/db2/libdhcp_user_chk.html>`__
+for information on how the code works internally. That, together with the
+`Hooks Framework section of the Kea Developer's Guide
+<https://jenkins.isc.org/job/Kea_doc/doxygen/index.html#hooksFramework>`__ should give users
+some pointers on how to extend this library and perhaps even write one
from scratch.
legal_log: Forensic Logging Hooks
This section describes the forensic log hooks library. This library
provides hooks that record a detailed log of lease assignments and
-renewals into a set of log files. Currently this library is only
-available to ISC customers with a support contract.
+renewals into a set of log files.
+
+Currently this library is only
+available to ISC customers with a paid support contract.
**Note**
- This library may only be loaded by ``kea-dhcp4`` or ``kea-dhcp6``
+ This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
-In many legal jurisdictions companies, especially ISPs, must record
+In many legal jurisdictions, companies, especially ISPs, must record
information about the addresses they have leased to DHCP clients. This
library is designed to help with that requirement. If the information
-that it records is sufficient it may be used directly. If your
-jurisdiction requires that you save a different set of information you
-may use it as a template or example and create your own custom logging
+that it records is sufficient, it may be used directly. If a
+jurisdiction requires that a different set of information be saved, users
+may use this library as a template or example to create their own custom logging
hooks.
This logging is done as a set of hooks to allow it to be customized to
any particular need. Modifying a hooks library is easier and safer than
-updating the core code. In addition by using the hooks features those
-users who don't need to log this information can leave it out and avoid
+updating the core code. In addition by using the hooks features, those
+users who do not need to log this information can leave it out and avoid
any performance penalties.
Log File Naming
path/base-name.CCYYMMDD.txt
The "path" and "base-name" are supplied in the configuration as
-described below see `Configuring the Forensic Log
-Hooks <#forensic-log-configuration>`__. The next part of the name is the
+described below; see :ref:`forensic-log-configuration`. The next part of the name is the
date the log file was started, with four digits for year, two digits for
-month and two digits for day. The file is rotated on a daily basis.
+month, and two digits for day. The file is rotated on a daily basis.
**Note**
- When running Kea servers for both DHCPv4 and DHCPv6 the log names
- must be distinct. See the examples in `Configuring the Forensic Log
- Hooks <#forensic-log-configuration>`__.
+ When running Kea servers for both DHCPv4 and DHCPv6, the log names
+ must be distinct. See the examples in :ref:`forensic-log-configuration`.
DHCPv4 Log Entries
~~~~~~~~~~~~~~~~~~
-For DHCPv4 the library creates entries based on DHCPREQUEST messages and
-corresponding DHCPv4 leases intercepted by lease4_select (for new
-leases) and lease4_renew (for renewed leases) hooks.
+For DHCPv4, the library creates entries based on DHCPREQUEST messages and
+corresponding DHCPv4 leases intercepted by the lease4_select (for new
+leases) and the lease4_renew (for renewed leases) hooks.
-An entry is a single string with no embedded end-of-line markers, a
-prepended timestamp and has the following sections:
+An entry is a single string with no embedded end-of-line markers and a
+prepended timestamp, and has the following sections:
::
assigned or renewed.
- duration - the lease lifetime expressed in days (if present), hours,
- minutes and seconds. A lease lifetime of 0xFFFFFFFF will be denoted
+ minutes, and seconds. A lease lifetime of 0xFFFFFFFF will be denoted
with the text "infinite duration".
- device-id - the client's hardware address shown as numerical type and
hex string.
- relay-info - for relayed packets the giaddr and the RAI circuit-id,
- remote-id and subscriber-id options (option 82 sub options: 1, 2 and
+ remote-id, and subscriber-id options (option 82 sub options: 1, 2 and
6) if present. The circuit id and remote id are presented as hex
- strings
+ strings.
-- user-context - the optional user context associated to the lease.
+- user-context - the optional user context associated with the lease.
-For instance (line breaks added for readability, they would not be
-present in the log file).
+For instance (line breaks added for readability; they will not be
+present in the log file):
::
identified by circuit-id: 68:6f:77:64:79 and remote-id: 87:f6:79:77:ef
In addition to logging lease activity driven by DHCPv4 client traffic,
-it also logs entries for the following lease management control channel
+the hooks library also logs entries for the following lease management control channel
commands: lease4-add, lease4-update, and lease4-del. Each entry is a
-single string with no embedded end-of-line markers and they will
-typically have the following forms:
+single string with no embedded end-of-line markers, and it will
+typically have the following form:
``lease4-add:``
*timestamp* Administrator added a lease of address: *address* to a device with hardware address: *device-id*
-Dependent on the arguments of the add command, it may also include the
+Depending on the arguments of the add command, it may also include the
client-id and duration.
Example:
*timestamp* Administrator updated information on the lease of address: *address* to a device with hardware address: *device-id*
-Dependent on the arguments of the update command, it may also include
+Depending on the arguments of the update command, it may also include
the client-id and lease duration.
Example:
2018-01-06 01:02:03 CET Administrator updated information on the lease of address: 192.0.2.202 to a device
with hardware address: 1a:1b:1c:1d:1e:1f, client-id: 1234567890
-``lease4-del:`` Deletes have two forms, one by address and one by
+``lease4-del:`` deletes have two forms, one by address and one by
identifier and identifier type:
::
~~~~~~~~~~~~~~~~~~
For DHCPv6 the library creates entries based on lease management actions
-intercepted by the lease6_select (for new leases), lease6_renew (for
-renewed leases) and lease6_rebind (for rebound leases).
+intercepted by lease6_select (for new leases), lease6_renew (for
+renewed leases), and lease6_rebind (for rebound leases).
-An entry is a single string with no embedded end-of-line markers, a
-prepended timestamp and has the following sections:
+An entry is a single string with no embedded end-of-line markers and a
+prepended timestamp, and has the following sections:
::
was assigned or renewed.
- duration - the lease lifetime expressed in days (if present), hours,
- minutes and seconds. A lease lifetime of 0xFFFFFFFF will be denoted
+ minutes, and seconds. A lease lifetime of 0xFFFFFFFF will be denoted
with the text "infinite duration".
- device-id - the client's DUID and hardware address (if present).
- relay-info - for relayed packets the content of relay agent messages,
- remote-id (code 37), subscriber-id (code 38) and interface-id (code
- 18) options if present. Note that interface-id option, if present,
+ remote-id (code 37), subscriber-id (code 38), and interface-id (code
+ 18) options, if present. Note that interface-id option, if present,
identifies the whole interface the relay agent received the message
- on. This typically translates to a single link in your network, but
- it depends on your specific network topology. Nevertheless, this is
+ on. This typically translates to a single link in the network, but
+ it depends on the specific network topology. Nevertheless, this is
useful information to better scope down the location of the device,
- so it is being recorded, if present.
+ so it is recorded, if present.
-- user-context - the optional user context associated to the lease.
+- user-context - the optional user context associated with the lease.
-For instance (line breaks added for readability, they would not be
-present in the log file).
+For instance (line breaks added for readability; they will not be
+present in the log file):
::
hop count: 1, identified by remote-id: 01:02:03:04:0a:0b:0c:0d:0e:0f and subscriber-id: 1a:2b:3c:4d:5e:6f
In addition to logging lease activity driven by DHCPv6 client traffic,
-it also logs entries for the following lease management control channel
+the hooks library also logs entries for the following lease management control channel
commands: lease6-add, lease6-update, and lease6-del. Each entry is a
-single string with no embedded end-of-line markers and they will
-typically have the following forms:
+single string with no embedded end-of-line markers, and it will
+typically have the following form:
``lease6-add:``
*timestamp* Administrator added a lease of address: *address* to a device with DUID: *DUID*
-Dependent on the arguments of the add command, it may also include the
+Depending on the arguments of the add command, it may also include the
hardware address and duration.
Example:
*timestamp* Administrator updated information on the lease of address: *address* to a device with DUID: *DUID*
-Dependent on the arguments of the update command, it may also include
+Depending on the arguments of the update command, it may also include
the hardware address and lease duration.
Example:
2018-01-06 01:02:03 PST Administrator updated information on the lease of address: 2001:db8::3 to a device with
DUID: 1a:1b:1c:1d:1e:1f:20:21:22:23:24, hardware address: 1a:1b:1c:1d:1e:1f
-``lease6-del:`` Deletes have two forms, one by address and one by
+``lease6-del:`` deletes have two forms, one by address and one by
identifier and identifier type:
::
Configuring the Forensic Log Hooks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To use this functionality the hook library must be included in the
+To use this functionality, the hook library must be included in the
configuration of the desired DHCP server modules. The legal_log library
is installed alongside the Kea libraries in ``[kea-install-dir]/lib``
where ``kea-install-dir`` is determined by the "--prefix" option of the
configure script. It defaults to ``/usr/local``. Assuming the default
-value then, configuring kea-dhcp4 to load the legal_log library could be
+value, configuring kea-dhcp4 to load the legal_log library could be
done with the following Kea4 configuration:
::
]
}
-To configure it for kea-dhcp6, the commands are simply as shown below:
+To configure it for kea-dhcp6, the commands are:
::
]
}
-Two Hook Library parameters are supported:
+Two hooks library parameters are supported:
- path - the directory in which the forensic file(s) will be written.
The default value is ``[prefix]/kea/var``. The directory must exist.
]
}
-disables legal logging for the subnet "192.0.2.0/24". If this parameter
-is not specified, it defaults to 'true', which enables legal logging for
-the subnet.
+This configuration disables legal logging for the subnet "192.0.2.0/24". If the
+"legal-logging" parameter is not specified, it defaults to 'true', which
+enables legal logging for the subnet.
The following example demonstrates how to selectively disable legal
-logging for an IPv6 subnet.
+logging for an IPv6 subnet:
::
]
}
-See `??? <#dhcp4-user-contexts>`__ and `??? <#dhcp6-user-contexts>`__ to
+See :ref:`dhcp4-user-contexts` and :ref:`dhcp6-user-contexts` to
learn more about user contexts in Kea configuration.
.. _forensic-log-database:
-Database backend
+Database Backend
~~~~~~~~~~~~~~~~
Log entries can be inserted into a database when Kea is configured with
-database backend support: a table named 'logs' is used with a timestamp
-(timeuuid for Cassandra CQL) generated by the database software and a
-text log with the same format than for files without the timestamp.
+database backend support. A table named "logs" is used that includes a timestamp
+(timeuuid for Cassandra) generated by the database software, and a
+text log with the same format as files without the timestamp.
-Please refer to `??? <#mysql-database>`__ for MySQL, to
-`??? <#pgsql-database>`__ for PostgreSQL or to `??? <#cql-database>`__
-for Cassandra CQL. The logs table is part of the Kea database schemas.
+Please refer to :ref:`mysql-database` for information on using a MySQL database; to
+:ref:`pgsql-database` for PostgreSQL database information; or to :ref:`cql-database`
+for information on using a Cassandra (CQL) database. The logs table is part of the Kea database schemas.
Configuration parameters are extended by standard lease database
-parameters as defined in `??? <#database-configuration4>`__. The "type"
-parameter should be "mysql", "postgresql", "cql" or be "logfile". When
-it is absent or set to "logfile" files are used.
+parameters as defined in :ref:`database-configuration4`. The "type"
+parameter should be "mysql", "postgresql", "cql", or "logfile". When
+it is absent or set to "logfile", files are used.
This database feature is experimental and will be likely improved, for
-instance to add an address / prefix index (currently the only index is
-the timestamp). No specific tools is provided to operate the database
-but standard tools are applicable, for instance to dump the logs table
+instance to add an address/prefix index (currently the only index is
+the timestamp). No specific tools are provided to operate the database,
+but standard tools may be used, for example, to dump the logs table
from a CQL database:
::
---------------------------------------------------
This section describes a hook application dedicated to generate flexible
-identifiers for host reservation. Kea software provides a way to handle
+identifiers for host reservations. The Kea software provides a way to handle
host reservations that include addresses, prefixes, options, client
-classes and other features. The reservation can be based on hardware
-address, DUID, circuit-id or client-id in DHCPv4 and using hardware
+classes, and other features. The reservation can be based on hardware
+address, DUID, circuit-id, or client-id in DHCPv4 and on hardware
address or DUID in DHCPv6. However, there are sometimes scenarios where
-the reservation is more complex, e.g. uses other options that mentioned
-above, uses part of specific options or perhaps even a combination of
+the reservation is more complex; it may use options other than those mentioned
+above, use parts of specific options, or perhaps even use a combination of
several options and fields to uniquely identify a client. Those
scenarios are addressed by the Flexible Identifiers hook application.
-Currently this library is only available to ISC customers with a support
+Currently this library is only available to ISC customers with a paid support
contract.
**Note**
- This library may only be loaded by ``kea-dhcp4`` or ``kea-dhcp6``
+ This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
-The library allows for defining an expression, using notation initially
-used for client classification only. See
-`??? <#classification-using-expressions>`__ for detailed description of
-the syntax available. One notable difference is that for client
-classification the expression currently has to evaluate to either true
+The library allows the definition of an expression, using notation initially
+used only for client classification. (See
+:ref:`classification-using-expressions` for a detailed description of
+the syntax available.) One notable difference is that for client
+classification, the expression currently has to evaluate to either true
or false, while the flexible identifier expression is expected to
-evaluate to a string that will be used as identifier. It is a valid case
-for the expression to evaluate to empty string (e.g. in cases where a
-client does not sent specific options). This expression is then
-evaluated for each incoming packet. This evaluation generates an
+evaluate to a string that will be used as an identifier. It is a valid case
+for the expression to evaluate to an empty string (e.g. in cases where a
+client does not send specific options). This expression is then
+evaluated for each incoming packet, and this evaluation generates an
identifier that is used to identify the client. In particular, there may
be host reservations that are tied to specific values of the flexible
identifier.
-The library can be loaded in similar way as other hook libraries. It
-takes a mandatory parameter identifier-expression and optional boolean
-parameter replace-client-id:
+The library can be loaded in a similar way as other hook libraries. It
+takes a mandatory parameter ``identifier-expression`` and optional boolean
+parameter ``replace-client-id``:
::
The flexible identifier library supports both DHCPv4 and DHCPv6.
-EXAMPLE: Let's consider a case of an IPv6 network that has an
-independent interface for each of the connected customers. Customers are
+Let's consider a case of an IPv6 network that has an
+independent interface for each of its connected customers. Customers are
able to plug in whatever device they want, so any type of identifier
-(e.g. a client-id) is unreliable. Therefore the operator may decide to
+(e.g. a client-id) is unreliable. Therefore, the operator may decide to
use an option inserted by a relay agent to differentiate between
-clients. In this particular deployment, the operator verified that the
-interface-id is unique for each customer facing interface. Therefore it
-is suitable for usage as reservation. However, only the first 6 bytes of
+clients. In this particular deployment, the operator has verified that the
+interface-id is unique for each customer-facing interface, so it
+is suitable for usage as a reservation. However, only the first six bytes of
the interface-id are interesting, because remaining bytes are either
-randomly changed or not unique between devices. Therefore the customer
-decided to use first 6 bytes of the interface-id option inserted by the
-relay agent. After adding "flex-id" host-reservation-identifiers goal
+randomly changed or not unique between devices. Therefore, the customer
+decided to use the first six bytes of the interface-id option inserted by the
+relay agent. After adding ``flex-id``, the ``host-reservation-identifiers`` goal
can be achieved by using the following configuration:
::
]
}
-NOTE: Care should be taken when adjusting the expression. If the
-expression changes, then all the flex-id values may change, possibly
-rendering all reservations based on flex-id unusable until they're
-manually updated. Therefore it is strongly recommended to start with the
-expression and a handful reservations, adjust the expression as needed
-and only after it was confirmed the expression does exactly what is
-expected out of it go forward with host reservations on any broader
-scale.
+ **Note**
+
+ Care should be taken when adjusting the expression. If the expression
+ changes, then all the ``flex-id`` values may change, possibly rendering
+ all reservations based on ``flex-id`` unusable until they are manually updated.
+ It is strongly recommended that administrators start with the expression and a
+ handful of reservations, and then adjust the expression as needed. Once
+ the expression is confirmed to do what is desired of it, host reservations
+ can be deployed on a broader scale.
flex-id values in host reservations can be specified in two ways. First,
-they can be expressed as hex string, e.g. bar string can be represented
-as 626174. Alternatively, it can be expressed as quoted value (using
+they can be expressed as a hex string, e.g. bar string can be represented
+as 626174. Alternatively, it can be expressed as a quoted value (using
double and single quotes), e.g. "'bar'". The former is more convenient
for printable characters, while hex string values are more convenient
-for non-printable characters and does not require the use of the
+for non-printable characters and do not require the use of the
``hexstring`` operator.
::
]
}
-When "replace-client-id" is set to false (which is the default setting),
-the flex-id hook library uses evaluated flexible identifier solely for
+When ``replace-client-id`` is set to "false" (which is the default setting),
+the flex-id hook library uses the evaluated flexible identifier solely for
identifying host reservations, i.e. searching for reservations within a
-database. This is a functional equivalent of other identifiers, similar
-to hardware address or circuit-id. However, this mode of operation has
-an implication that if a client device is replaced, it may cause a
-conflict between an existing lease (allocated for old device) and the
-new lease being allocated for the new device. The conflict arises
-because the same flexible identifier is computed for the replaced device
-and the server will try to allocate the same lease. The mismatch between
-client identifiers sent by new device and old device causes the server
+database. This is the functional equivalent of other identifiers, similar
+to hardware address or circuit-id. However, this mode of operation
+implies that if a client device is replaced, it may cause a
+conflict between an existing lease (allocated to the old device) and the
+new lease being allocated to the new device. The conflict arises
+because the same flexible identifier is computed for the replaced device,
+so the server will try to allocate the same lease. The mismatch between
+client identifiers sent by the new device and the old device causes the server
to refuse this new allocation until the old lease expires. A
-manifestation of this problem is dependant on specific expression used
-as flexible identifier and is likely to appear if you only use options
-and other parameters that are identifying where the device is connected
+manifestation of this problem is dependent on the specific expression used
+as the flexible identifier and is likely to appear if only options
+and other parameters are used that identify where the device is connected
(e.g. circuit-id), rather than the device identification itself (e.g.
MAC address).
The flex-id library offers a way to overcome the problem with lease
-conflicts by dynamically replacing client identifier (or DUID in DHCPv6
-case) with a value derived from flexible identifier. The server
-processes the client's query as if flexible identifier was sent in the
-client identifier (or DUID) option. This guarantees that returning
+conflicts by dynamically replacing the client identifier (or DUID in DHCPv6)
+with a value derived from the flexible identifier. The server
+processes the client's query as if the flexible identifier were sent in the
+client identifier (or DUID) option. This guarantees that a returning
client (for which the same flexible identifier is evaluated) will be
assigned the same lease despite the client identifier and/or MAC address
change.
}
In the DHCPv4 case, the value derived from the flexible identifier is
-formed by prepending 1 byte with a value of zero to flexible identifier.
-In the IPv6 case, it is formed by prepanding two zero bytes before the
+formed by prepending one byte with a value of zero to the flexible identifier.
+In the DHCPv6 case, it is formed by prepending two zero bytes before the
flexible identifier.
Note that for this mechanism to take effect, the DHCPv4 server must be
configured to respect the client identifier option value during lease
-allocation, i.e. "match-client-id" must be set to true. See
-`??? <#dhcp4-match-client-id>`__ for details. No additional settings are
+allocation, i.e. ``match-client-id`` must be set to "true". See
+:ref:`dhcp4-match-client-id` for details. No additional settings are
required for DHCPv6.
-If "replace-client-id" option is set to true, the value of
-"echo-client-id" parameter (that governs whether to send back a
-client-id option or not) is ignored.
+If the ``replace-client-id`` option is set to "true", the value of the
+``echo-client-id`` parameter (which governs whether to send back a
+client-id option) is ignored.
-The `??? <#lease-cmds>`__ section describes commands used to retrieve,
-update and delete leases using various identifiers, e.g. "hw-address",
+The :ref:`lease-cmds` section describes commands used to retrieve,
+update, and delete leases using various identifiers, such as "hw-address" and
"client-id". The lease_cmds library doesn't natively support querying
-for leases by flexible identifier. However, when "replace-client-id" is
-set to true, it makes it possible to query for leases using a value
+for leases by flexible identifier. However, when ``replace-client-id`` is
+set to "true", it makes it possible to query for leases using a value
derived from the flexible identifier. In the DHCPv4 case, the query will
look similar to this:
}
}
-where hexadecimal value of "54:64:45:66" is a flexible identifier
+where the hexadecimal value of "54:64:45:66" is a flexible identifier
computed for the client.
In the DHCPv6 case, the corresponding query will look similar to this:
commands used to query and manipulate host reservations. Kea provides a
way to store host reservations in a database. In many larger deployments
it is useful to be able to manage that information while the server is
-running. This library provides management commands for adding, querying
+running. This library provides management commands for adding, querying,
and deleting host reservations in a safe way without restarting the
server. In particular, it validates the parameters, so an attempt to
-insert incorrect data e.g. add a host with conflicting identifier in the
-same subnet will be rejected. Those commands are exposed via command
-channel (JSON over unix sockets) and Control Agent (JSON over RESTful
+insert incorrect data - such as adding a host with a conflicting identifier in the
+same subnet - will be rejected. Those commands are exposed via the command
+channel (JSON over UNIX sockets) and the Control Agent (JSON over a RESTful
interface). Additional commands and capabilities related to host
reservations will be added in the future.
-Currently this library is only available to ISC customers with a support
+Currently this library is only available to ISC customers with a paid support
contract.
**Note**
- This library may only be loaded by ``kea-dhcp4`` or ``kea-dhcp6``
+ This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
-Currently five commands are supported: reservation-add (which adds new
-host reservation), reservation-get (which returns existing reservation
+Currently, five commands are supported: reservation-add (which adds a new
+host reservation), reservation-get (which returns an existing reservation
if specified criteria are matched), reservation-get-all (which returns
-all reservations in a specified subnet), reservation-get-page (variant
+all reservations in a specified subnet), reservation-get-page (a variant
of reservation-get-all which returns all reservations in a specified
-subnet by pages) and reservation-del (which attempts to delete a
+subnet by pages), and reservation-del (which attempts to delete a
reservation matching specified criteria). To use commands that change
the reservation information (currently these are reservation-add and
reservation-del, but this rule applies to other commands that may be
-implemented in the future), hosts database must be specified (see
-hosts-databases description in `??? <#hosts-databases-configuration4>`__
-and `??? <#hosts-databases-configuration6>`__) and it must not operate
-in read-only mode. If the hosts-databases are not specified or are
+implemented in the future), the hosts database must be specified and it must not operate
+in read-only mode (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 or reservation-del will fail.
-Additional host reservation commands are planned in the future. For a
-description of envisaged commands, see `Control API
+Additional host reservation commands are planned in future releases of Kea. For a
+description of envisaged commands, see the `Control API
Requirements <https://gitlab.isc.org/isc-projects/kea/wikis/designs/commands>`__
document.
-All commands are using JSON syntax. They can be issued either using
-control channel (see `??? <#ctrl-channel>`__) or via Control Agent (see
-`??? <#kea-ctrl-agent>`__).
+All commands use JSON syntax. They can be issued either using the
+control channel (see :ref:`ctrl-channel`) or via the Control Agent (see
+:ref:`kea-ctrl-agent`).
-The library can be loaded in similar way as other hook libraries. It
-does not take any parameters. It supports both DHCPv4 and DHCPv6
+The library can be loaded similarly to other hook libraries. It
+does not take any parameters, and it supports both DHCPv4 and DHCPv6
servers.
::
]
}
-The subnet-id parameter
+The subnet-id Parameter
~~~~~~~~~~~~~~~~~~~~~~~
Prior to diving into the individual commands, it is worth discussing the
-parameter, ``subnet-id``. Currently it is mandatory for all of the
-commands supplied by this library. Prior to Kea 1.5.0, reservations had
-to belong to specific subnet. Beginning with Kea 1.5.0, reservations may
-now be specified globally. In other words, they are not specific to any
+parameter, ``subnet-id``. Currently this parameter is mandatory for all of the
+commands supplied by this library. In previous versions of Kea, reservations had
+to belong to a specific subnet; as of Kea 1.5.0, reservations may
+be specified globally. In other words, they are not specific to any
subnet. When reservations are supplied via the configuration file, the
ID of the containing subnet (or lack thereof) is implicit in the
-configuration structure. However, when managing reservations using the
+configuration structure. However, when managing reservations using
host commands, it is necessary to explicitly identify the scope to which
the reservation belongs. This is done via the ``subnet-id`` parameter.
For global reservations, use a value of zero (0). For reservations
.. _command-reservation-add:
-reservation-add command
-~~~~~~~~~~~~~~~~~~~~~~~
+The reservation-add Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
``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
-IPv4 reservations, see `??? <#host-reservation-v4>`__ and
-`??? <#host-reservation-v6>`__. The ``subnet-id`` is manadatory. Use a
+IPv4 reservations, see :ref:`host-reservation-v4`; for IPv6 reservations, see
+:ref:`host-reservation-v6`. The ``subnet-id`` is mandatory. Use a
value of zero (0) to add a global reservation, or the id of the subnet
to which the reservation should be added. An example command can be as
simple as:
}
}
-but can also take many more parameters, for example:
+but it can also take many more parameters, for example:
::
}
}
-Here is an example of complex IPv6 reservation:
+Here is an example of a complex IPv6 reservation:
::
}
The command returns a status that indicates either a success (result 0)
-or a failure (result 1). Failed command always includes text parameter
-that explains the cause of failure. Example results:
+or a failure (result 1). A failed command always includes a text parameter
+that explains the cause of the failure. Example results:
::
{ "result": 1, "text": "Mandatory 'subnet-id' parameter missing." }
-As ``reservation-add`` is expected to store the host, hosts-databases
-parameter must be specified in your configuration and databases must not
-run in read-only mode. In the future versions it will be possible to
+As ``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. In future versions of Kea, it will be possible to
modify the reservations read from a configuration file. Please contact
ISC if you are interested in this functionality.
.. _command-reservation-get:
-reservation-get command
-~~~~~~~~~~~~~~~~~~~~~~~
+The reservation-get Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
``reservation-get`` can be used to query the host database and retrieve
existing reservations. There are two types of parameters this command
supports: (subnet-id, address) or (subnet-id, identifier-type,
identifier). The first type of query is used when the address (either
-IPv4 or IPv6) is known, but the details of the reservation aren't. One
+IPv4 or IPv6) is known, but the details of the reservation are not. One
common use case of this type of query is to find out whether a given
-address is reserved or not. The second query uses identifiers. For
+address is reserved. The second query uses identifiers. For
maximum flexibility, Kea stores the host identifying information as a
-pair of values: type and the actual identifier. Currently supported
-identifiers are "hw-address", "duid", "circuit-id", "client-id" and
+pair of values: the type and the actual identifier. Currently supported
+identifiers are "hw-address", "duid", "circuit-id", "client-id", and
"flex-id", but additional types may be added in the future. If any new
-identifier types are defined in the future, reservation-get command will
+identifier types are defined in the future, the reservation-get command will
support them automatically. The ``subnet-id`` is mandatory. Use a value
of zero (0) to fetch a global reservation, or the id of the subnet to
which the reservation belongs.
-An example command for getting a host reservation by (subnet-id,
+An example command for getting a host reservation by a (subnet-id,
address) pair looks as follows:
::
}
}
-``reservation-get`` typically returns result 0 when the query was
+``reservation-get`` typically returns the result 0 when the query was
conducted properly. In particular, 0 is returned when the host was not
-found. If the query was successful a number of host parameters will be
+found. If the query was successful, a number of host parameters will be
returned. An example of a query that did not find the host looks as
follows:
{ "result": 0, "text": "Host not found." }
-An example result returned when the host was found:
+An example result returned when the host was found looks like this:
::
"text": "Host found."
}
-An example result returned when the query was malformed:
+An example result returned when the query was malformed might look like this:
::
.. _command-reservation-get-all:
-reservation-get-all command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The reservation-get-all Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``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 subnet-id value of zero (0).
+can be retrieved by using a subnet-id value of zero (0).
-For instance for retrieving host reservations for the subnet 1:
+For instance, retrieving host reservations for the subnet 1:
::
}
}
-returns found some IPv4 hosts:
+returns some IPv4 hosts:
::
The response returned by ``reservation-get-all`` can be very long. The
DHCP server does not handle DHCP traffic when preparing a response to
-reservation-get-all. If there are many reservations in a subnet, this
+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
-`reservation-get-page command <#command-reservation-get-page>`__).
+:ref:`command-reservation-get-page`).
-For a reference, see `??? <#ref-reservation-get-all>`__.
+For a reference, see :ref:`ref-reservation-get-all`.
.. _command-reservation-get-page:
uses parameters providing the mandatory subnet-id. Use a value of zero
(0) to fetch global reservations. The second mandatory parameter is the
page size limit. Optional source-index and from host id, both defaulting
-to 0, are uses to chain page queries.
+to 0, are used to chain page queries.
The usage of from and source-index parameters requires additional
-explanation. For the first call those parameters should not be specified
-(or specified as zeros). For any follow up calls they should be set to
+explanation. For the first call, those parameters should not be specified
+(or specified as zeros). For any follow-up calls, they should be set to
the values returned in previous calls in a next map holding from and
-source-index values. The subsequent calls should be issued until all
+source-index values. Subsequent calls should be issued until all
reservations are returned. The end is reached once the returned list is
-empty, count is 0, no next map is present and result status 3 (empty) is
+empty, the count is 0, no next map is present, and result status 3 (empty) is
returned.
**Note**
- The from and source-index parameters are reflecting internal state of
- the search. There is no need to understand what they represent, it's
+ The from and source-index parameters are reflecting the internal state of
+ the search. There is no need to understand what they represent; it is
simply a value that is supposed to be copied from one response to the
- next query. However, if you are curious, from field represents a 64
- bits representation of host identifier used by a host backend. The
- source-index represents internal representation of multiple host
+ next query. However, for those who are curious, the from field represents a
+ 64-bit representation of the host identifier used by a host backend. The
+ source-index is an internal representation of multiple host
backends: 0 is used to represent hosts defined in a configuration
- file, 1 represents the first database backend. In some uncommon cases
+ file, and 1 represents the first database backend. In some uncommon cases
there may be more than one database backend configured, so
- potentially there may be 2. In any case, Kea will iterate over all
+ potentially there may be a 2. In any case, Kea will iterate over all
backends configured.
-For instance for retrieving host reservations for the subnet 1
+For instance, retrieving host reservations for the subnet 1 and
requesting the first page can be done by:
::
Since this is the first call, source-index and from should not be
specified. They will default to their zero default values.
-Some hosts are returned with informations to get the next page:
+Some hosts are returned with information to get the next page:
::
"text": "72 IPv4 host(s) found."
}
-Note that from and source-index fields were specified in the response in
+Note that the from and source-index fields were specified in the response in
the next map. Those two must be copied to the next command, so Kea
continues from the place where the last command finished. To get the
next page the following command can be sent:
}
}
-. The response will contain a list of hosts with updated source-index
-and from fields. Continue calling the command until you get the last
-page. Its response will look like this:
+The response will contain a list of hosts with updated source-index
+and from fields. Continue calling the command until the last
+page is received. Its response will look like this:
::
}
This command is more complex than ``reservation-get-all``, but lets
-users retrieve larger host reservations lists by smaller chunks. For
-small deployments with few reservations, is it easier to use
-``reservation-get-all`` (see `reservation-get-all
-command <#command-reservation-get-all>`__.
+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`.
-For a reference, see `??? <#ref-reservation-get-page>`__.
+For a reference, see :ref:`ref-reservation-get-page`.
**Note**
.. _command-reservation-del:
-reservation-del command
-~~~~~~~~~~~~~~~~~~~~~~~
+The reservation-del Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
``reservation-del`` can be used to delete a reservation from the host
database. There are two types of parameters this command supports:
(subnet-id, address) or (subnet-id, identifier-type, identifier). The
first type of query is used when the address (either IPv4 or IPv6) is
-known, but the details of the reservation aren't. One common use case of
-this type of query is to remove a reservation (e.g. you want a specific
-address to no longer be reserved). The second query uses identifiers.
+known, but the details of the reservation are not. One common use case of
+this type of query is to remove a reservation (e.g. a specific
+address should no longer be reserved). The second query uses identifiers.
For maximum flexibility, Kea stores the host identifying information as
-a pair of values: type and the actual identifier. Currently supported
-identifiers are "hw-address", "duid", "circuit-id", "client-id" and
+a pair of values: the type and the actual identifier. Currently supported
+identifiers are "hw-address", "duid", "circuit-id", "client-id", and
"flex-id", but additional types may be added in the future. If any new
-identifier types are defined in the future, reservation-get command will
-support them automatically. The ``subnet-id`` is manadatory. Use a value
+identifier types are defined in the future, the reservation-get command will
+support them automatically. The ``subnet-id`` is mandatory. Use a value
of zero (0) to delete a global reservation, or the id of the subnet from
which the reservation should be deleted.
}
}
-``reservation-del`` returns result 0 when the host deletion was
-successful or 1 if it was not. A descriptive text is provided in case of
-error. Example results look as follows:
+``reservation-del`` returns a result 0 when the host deletion was
+successful or 1 if it was not. Descriptive text is provided in the event of
+an error. Example results look as follows:
::
subnet_cmds: Subnet Commands
----------------------------
-This section describes a hook application that offers a number of new
+This section describes a hook application that offers some new
commands used to query and manipulate subnet and shared network
configurations in Kea. This application is very useful in deployments
-with a large number of subnets being managed by the DHCP servers and
-when the subnets are frequently updated. The commands offer lightweight
+with a large number of subnets being managed by the DHCP servers,
+when those subnets are frequently updated. The commands offer a lightweight
approach for manipulating subnets without a need to fully reconfigure
the server and without affecting existing servers' configurations. An
ability to manage shared networks (listing, retrieving details, adding
-new ones, removing existing ones, adding subnets to and removing from
+new ones, removing existing ones, and adding subnets to and removing them from
shared networks) is also provided.
-Currently this library is only available to ISC customers with a support
+Currently this library is only available to ISC customers with a paid support
contract.
**Note**
- This library may only be loaded by ``kea-dhcp4`` or ``kea-dhcp6``
+ This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
The following commands are currently supported:
-- ``subnet4-list/subnet6-list``: lists all configured subnets
+- ``subnet4-list/subnet6-list`` - lists all configured subnets.
-- ``subnet4-get/subnet6-get``: retrieves detailed information about a
- specified subnet
+- ``subnet4-get/subnet6-get`` - retrieves detailed information about a
+ specified subnet.
-- ``subnet4-add/subnet6-add``: adds new subnet into server's
- configuration
+- ``subnet4-add/subnet6-add`` - adds a new subnet into the server's
+ configuration.
-- ``subnet4-update/subnet6-update``: updates subnet in server's
- configuration
+- ``subnet4-update/subnet6-update`` - updates a subnet in the server's
+ configuration.
-- ``subnet4-del/subnet6-del``: removes a subnet from the server's
- configuration
+- ``subnet4-del/subnet6-del`` - removes a subnet from the server's
+ configuration.
-- ``network4-list/network6-list``: lists all configured shared networks
+- ``network4-list/network6-list`` - lists all configured shared networks.
-- ``network4-get/network6-get``: retrieves detailed information about
- specified shared network
+- ``network4-get/network6-get`` - retrieves detailed information about a
+ specified shared network.
-- ``network4-add/network6-add``: adds a new shared network to the
- server's configuration
+- ``network4-add/network6-add`` - adds a new shared network to the
+ server's configuration.
-- ``network4-del/network6-del``: removes a shared network from the
- server's configuration
+- ``network4-del/network6-del`` - removes a shared network from the
+ server's configuration.
-- ``network4-subnet-add/network6-subnet-add``: adds existing subnet to
- existing shared network
+- ``network4-subnet-add/network6-subnet-add`` - adds an existing subnet to
+ an existing shared network.
-- ``network4-subnet-del/network6-subnet-del``: removes a subnet from
- existing shared network and demotes it to a plain subnet.
+- ``network4-subnet-del/network6-subnet-del`` - removes a subnet from
+ an existing shared network and demotes it to a plain subnet.
.. _command-subnet4-list:
-subnet4-list command
-~~~~~~~~~~~~~~~~~~~~
+The subnet4-list Command
+~~~~~~~~~~~~~~~~~~~~~~~~
-This command is used to list all currently configured subnets. The
-subnets are returned in a brief form, i.e. a subnet identifier and
-subnet prefix is included for each subnet. In order to retrieve the
-detailed information about the subnet the ``subnet4-get`` should be
-used.
+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.
This command has the simple structure:
"command": "subnet4-list"
}
-The list of subnets returned as a result of this command is returned in
-the following format:
+The list of subnets is returned in the following format:
::
.. _command-subnet6-list:
-subnet6-list command
-~~~~~~~~~~~~~~~~~~~~
+The subnet6-list Command
+~~~~~~~~~~~~~~~~~~~~~~~~
-This command is used to list all currently configured subnets. The
-subnets are returned in a brief form, i.e. a subnet identifier and
-subnet prefix is included for each subnet. In order to retrieve the
-detailed information about the subnet the ``subnet6-get`` should be
-used.
+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.
This command has the simple structure:
"command": "subnet6-list"
}
-The list of subnets returned as a result of this command is returned in
-the following format:
+The list of subnets is returned in the following format:
::
.. _command-subnet4-get:
-subnet4-get command
-~~~~~~~~~~~~~~~~~~~
+The subnet4-get Command
+~~~~~~~~~~~~~~~~~~~~~~~
This command is used to retrieve detailed information about the
-specified subnet. This command usually follows the ``subnet4-list``,
+specified subnet. This command usually follows ``subnet4-list``,
which is used to discover available subnets with their respective subnet
identifiers and prefixes. Any of those parameters can be then used in
``subnet4-get`` to fetch subnet information:
.. _command-subnet6-get:
-subnet6-get command
-~~~~~~~~~~~~~~~~~~~
+The subnet6-get Command
+~~~~~~~~~~~~~~~~~~~~~~~
This command is used to retrieve detailed information about the
-specified subnet. This command usually follows the ``subnet6-list``,
+specified subnet. This command usually follows ``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:
.. _command-subnet4-add:
-subnet4-add
-~~~~~~~~~~~
+The subnet4-add Command
+~~~~~~~~~~~~~~~~~~~~~~~
-This command is used to create and add new subnet to the existing server
+This command is used to create and add a new subnet to the existing server
configuration. This operation has no impact on other subnets. The subnet
identifier must be specified and must be unique among all subnets. If
-the identifier or a subnet prefix is not unique an error is reported and
+the identifier or a subnet prefix is not unique, an error is reported and
the subnet is not added.
The subnet information within this command has the same structure as the
-subnet information in the server configuration file with the exception
+subnet information in the server configuration file, with the exception
that static host reservations must not be specified within
-``subnet4-add``. The commands described in `host_cmds: Host
-Commands <#host-cmds>`__ should be used to add, remove and modify static
-reservations.
+``subnet4-add``. The commands described in :ref:`host-cmds` should be used to
+add, remove, and modify static reservations.
::
.. _command-subnet6-add:
-subnet6-add
-~~~~~~~~~~~
+The subnet6-add Command
+~~~~~~~~~~~~~~~~~~~~~~~
-This command is used to create and add new subnet to the existing server
+This command is used to create and add a new subnet to the existing server
configuration. This operation has no impact on other subnets. The subnet
identifier must be specified and must be unique among all subnets. If
-the identifier or a subnet prefix is not unique an error is reported and
+the identifier or a subnet prefix is not unique, an error is reported and
the subnet is not added.
The subnet information within this command has the same structure as the
-subnet information in the server configuration file with the exception
+subnet information in the server configuration file, with the exception
that static host reservations must not be specified within
-``subnet6-add``. The commands described in `host_cmds: Host
-Commands <#host-cmds>`__ should be used to add, remove and modify static
-reservations.
+``subnet6-add``. The commands described in :ref:`host-cmds` should be used
+to add, remove, and modify static reservations.
::
}
}
-It is recommended, but not mandatory to specify subnet id. If not
+It is recommended, but not mandatory, to specify the subnet ID. If not
specified, Kea will try to assign the next subnet-id value. This
-automatic ID value generator is simple. It returns a previously
-automatically assigned value increased by 1. This works well, unless you
-manually create a subnet with a value bigger than previously used. For
-example, if you call subnet4-add five times, each without id, Kea will
-assign IDs: 1,2,3,4 and 5 and it will work just fine. However, if you
-try to call subnet4-add five times, with the first subnet having
-subnet-id of value 3 and remaining ones having no subnet-id, it will
-fail. The first command (with explicit value) will use subnet-id 3, the
-second command will create a subnet with id of 1, the third will use
-value of 2 and finally the fourth will have the subnet-id value
+automatic ID value generator is simple; it returns a previously
+automatically assigned value, increased by 1. This works well, unless
+a subnet is manually created with a value bigger than one previously used. For
+example, if 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
+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 id of 1; the third will use a
+value of 2; and finally the fourth will have the subnet-id value
auto-generated as 3. However, since there is already a subnet with that
-id, it will fail.
+ID, the process will fail.
-The general recommendation is to either: never use explicit values (so
-the auto-generated values will always work) or always use explicit
-values (so the auto-generation is never used). You can mix those two
-approaches only if you understand how the internal automatic subnet-id
-generation works.
+The general recommendation is either never use explicit values, so
+the auto-generated values will always work; or always use explicit
+values, so the auto-generation is never used. The two
+approaches can be mixed only if the administrator understands how internal
+automatic subnet-id generation works in Kea.
**Note**
.. _command-subnet4-update:
-subnet4-update
-~~~~~~~~~~~~~~
+The subnet4-update Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to update a subnet in the existing server
configuration. This operation has no impact on other subnets. The subnet
-identifier is used to identify the subnet to replace, it must be
+identifier is used to identify the subnet to replace; it must be
specified and must be unique among all subnets. The subnet prefix should
not be updated.
The subnet information within this command has the same structure as the
-subnet information in the server configuration file with the exception
+subnet information in the server configuration file, with the exception
that static host reservations must not be specified within
-``subnet4-update``. The commands described in `host_cmds: Host
-Commands <#host-cmds>`__ should be used to update, remove and modify
-static reservations.
+``subnet4-update``. The commands described in :ref:`host-cmds` should be used
+to update, remove, and modify static reservations.
::
.. _command-subnet6-update:
-subnet6-update
-~~~~~~~~~~~~~~
+The subnet6-update Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to update a subnet in the existing server
configuration. This operation has no impact on other subnets. The subnet
-identifier is used to identify the subnet to replace, it must be
+identifier is used to identify the subnet to replace; it must be
specified and must be unique among all subnets. The subnet prefix should
not be updated.
The subnet information within this command has the same structure as the
-subnet information in the server configuration file with the exception
+subnet information in the server configuration file, with the exception
that static host reservations must not be specified within
-``subnet6-update``. The commands described in `host_cmds: Host
-Commands <#host-cmds>`__ should be used to update, remove and modify
-static reservations.
+``subnet6-update``. The commands described in :ref:`host-cmds` should be used
+to update, remove, and modify static reservations.
::
.. _command-subnet4-del:
-subnet4-del command
-~~~~~~~~~~~~~~~~~~~
+The subnet4-del Command
+~~~~~~~~~~~~~~~~~~~~~~~
This command is used to remove a subnet from the server's configuration.
-This command has no effect on other configured subnets but removing a
+This command has no effect on other configured subnets, but removing a
subnet has certain implications which the server's administrator should
be aware of.
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`` removes neither the leases nor
-host reservations associated with a subnet. This is the safest approach
-because the server doesn't loose track of leases assigned to the clients
+implementation of the ``subnet4-del`` command removes neither the leases nor
+the host reservations associated with a subnet. This is the safest approach
+because the server doesn't lose track of leases assigned to the clients
from this subnet. However, removal of the subnet may still cause
configuration errors and conflicts. For example: after removal of the
subnet, the server administrator may update a new subnet with the ID
used previously for the removed subnet. This means that the existing
leases and static reservations will be in conflict with this new subnet.
-Thus, we recommend that this command is used with extreme caution.
+Thus, we recommend that this command be used with extreme caution.
This command can also be used to completely delete an IPv4 subnet that
-is part of a shared network. If you want to simply remove the subnet
-from a shared network and keep the subnet configuration, use
+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.
The command has the following structure:
.. _command-subnet6-del:
-subnet6-del command
-~~~~~~~~~~~~~~~~~~~
+The subnet6-del Command
+~~~~~~~~~~~~~~~~~~~~~~~
This command is used to remove a subnet from the server's configuration.
-This command has no effect on other configured subnets but removing a
+This command has no effect on other configured subnets, but removing a
subnet has certain implications which the server's administrator should
be aware of.
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`` removes neither the leases nor
-host reservations associated with a subnet. This is the safest approach
-because the server doesn't loose track of leases assigned to the clients
+implementation of the ``subnet6-del`` command removes neither the leases nor
+the host reservations associated with a subnet. This is the safest approach
+because the server doesn't lose track of leases assigned to the clients
from this subnet. However, removal of the subnet may still cause
configuration errors and conflicts. For example: after removal of the
subnet, the server administrator may add a new subnet with the ID used
previously for the removed subnet. This means that the existing leases
and static reservations will be in conflict with this new subnet. Thus,
-we recommend that this command is used with extreme caution.
+we recommend that this command be used with extreme caution.
This command can also be used to completely delete an IPv6 subnet that
-is part of a shared network. If you want to simply remove the subnet
-from a shared network and keep the subnet configuration, use
+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.
The command has the following structure:
.. _command-network4-list:
-network4-list, network6-list commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The network4-list, network6-list Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These commands are used to retrieve full list of currently configured
+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
.. _command-network4-get:
-network4-get, network6-get commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The network4-get, network6-get Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to retrieve detailed information about shared
-networks, including subnets currently being part of a given network.
-Both commands take one mandatory parameter ``name``, which specify the
-name of shared network. An example command to retrieve details about
-IPv4 shared network with a name "floor13" looks as follows:
+networks, including subnets that are currently part of a given network.
+Both commands take one mandatory parameter, ``name``, which specifies the
+name of the shared network. An example command to retrieve details about
+an IPv4 shared network with the name "floor13" looks as follows:
::
{
"subnet": "192.0.2.0/24",
"id": 5,
- // many other subnet specific details here
+ // many other subnet-specific details here
},
{
"id": 6,
"subnet": "192.0.3.0/31",
- // many other subnet specific details here
+ // many other subnet-specific details here
}
],
"valid-lifetime": 120
}
}
-Note that actual response contains many additional fields that are
+Note that 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 is limited to returning shared networks
+used in ``config-get``, just limited to returning the shared network's
information.
.. _command-network4-add:
-network4-add, network6-add commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The network4-add, network6-add Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These commands are used to add a new shared network. New network has to
-have unique name. This command requires one parameter
+These commands are used to add a new shared network, which must
+have a unique name. This command requires one parameter,
``shared-networks``, which is a list and should contain exactly one
entry that defines the network. The only mandatory element for a network
-is its name. Although it does not make operational sense, it is allowed
+is its name. Although it does not make operational sense, it is possible
to add an empty shared network that does not have any subnets in it.
That is allowed for testing purposes, but having empty networks (or with
only one subnet) is discouraged in production environments. For details
-regarding syntax, see `??? <#shared-network4>`__ and
-`??? <#shared-network6>`__.
+regarding syntax, see :ref:`shared-network4` and
+:ref:`shared-network6`.
**Note**
- As opposed to parameter inheritance during full new configuration
- processing, this command does not fully handle parameter inheritance
- and any missing parameters will be filled with default values, rather
- than inherited from global scope.
+ As opposed to parameter inheritance during the processing of a full new
+ configuration, this command does not fully handle parameter inheritance.
+ Any missing parameters will be filled with default values, rather
+ than inherited from the global scope.
An example that showcases how to add a new IPv4 shared network looks as
follows:
}
}
-Assuming there was no shared network with a name floor13 and no subnets
-with id 100 and 101 previously configured, the command will be
+Assuming there was no shared network with a name "floor13" and no subnets
+with IDs 100 and 101 previously configured, the command will be
successful and will return the following response:
::
"text": "A new IPv4 shared network 'floor13' added"
}
-The ``network6-add`` uses the same syntax for both the query and the
+The ``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 are IPv6-only (e.g. interface-id). The same
+match-client-id) and some that are IPv6-only (e.g. interface-id). The same
applies to subnets within the network.
.. _command-network4-del:
-network4-del, network6-del commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The network4-del, network6-del Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 ``network4-del``
+commands take exactly one parameter, ``name``, that specifies the name of
+the network to be removed. An example invocation of the ``network4-del``
command looks as follows:
::
they will be demoted to a plain subnet. There is an optional parameter
called ``subnets-action`` that, if specified, takes one of two possible
values: ``keep`` (which is the default) and ``delete``. It controls
-whether the subnets be demoted to plain subnets or removed. An example
-usage in network6-del command that deletes the shared network and all
-subnets in it could looks like as follows:
+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
+subnets in it could look as follows:
::
}
}
-Alternatively, if you want to completely remove the subnets, you may use
+Alternatively, to completely remove the subnets, it is possible to use the
``subnet4-del`` or ``subnet6-del`` commands.
.. _command-network4-subnet-add:
-network4-subnet-add, network6-subnet-add commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The network4-subnet-add, network6-subnet-add Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to add existing subnets to existing shared
-networks. There are several ways to add new shared network. System
+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 ``network4-add`` or
-``network6-add`` commands with desired subnets in it. This approach
+editing a configuration file or by calling the ``network4-add`` or
+``network6-add`` command with the desired subnets in it. This approach
works better 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
-has to be added on top of it. For this scenario, a system administrator
-can use ``network4-add`` or ``network6-add`` and then add existing
+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
subnet to this newly created shared network using
``network4-subnet-add`` or ``network6-subnet-add``.
The ``network4-subnet-add`` and ``network6-subnet-add`` commands take
-two parameters: ``id``, which is an integer and specifies subnet-id of
-existing subnet to be added to a shared network; and ``name``, which
-specifies name of the shared network the subnet will be added to. The
-subnet must not belong to any existing network. In case you want to
-reassign a subnet from one shared network to another, please use
+two parameters: ``id``, which is an integer and specifies the subnet-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, please use the
``network4-subnet-del`` or ``network6-subnet-del`` commands first.
-An example invocation of ``network4-subnet-add`` command looks as
+An example invocation of the ``network4-subnet-add`` command looks as
follows:
::
}
}
-Assuming there is a network named 'floor13', there is a subnet with
-subnet-id 5 and it is not a part of existing network, the command will
+Assuming there is a network named "floor13", and there is a subnet with
+subnet-id 5 that is not a part of existing network, the command will
return a response similar to the following:
::
{
"result": 0,
- "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'"
+ "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
**Note**
- As opposed to parameter inheritance during full new configuration
- processing or when adding a new shared network with new subnets, this
- command does not fully handle parameter inheritance and any missing
- parameters will be filled with default values, rather than inherited
- from global scope or from the shared network.
+ As opposed to parameter inheritance during the processing of a full new
+ configuration or when adding a new shared network with new subnets,
+ this command does not fully handle parameter inheritance.
+ Any missing parameters will be filled with default values, rather
+ than inherited from the global scope or from the shared network.
.. _command-network4-subnet-del:
-network4-subnet-del, network6-subnet-del commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The network4-subnet-del, network6-subnet-del Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These commands are used to remove a subnet that is part of existing
-shared network and demote it to a plain, stand-alone subnet. If you want
-to remove a subnet completely, use ``subnet4-del`` or ``subnet6-del``
+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
-an integer and specifies subnet-id of existing subnet to be removed from
-a shared network; and ``name``, which specifies name of the shared
-network the subnet will be removed from.
+an integer and specifies the subnet-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
follows:
}
}
-Assuming there was a subnet with subnet-id equal to 5 that was part of a
-shared network named 'floor13', the response would look similar to the
+Assuming there was a subnet with subnet-id equal to 5, that was part of a
+shared network named "floor13", the response would look similar to the
following:
::
projects / thirdparty / kea.git / commitdiff
