``backend``. Additional, non-mandatory options may be specified. The
currently supported commands are:
-- ``db-init`` — initializes a new database schema. This is useful
- during a new Kea installation. The database is initialized to the
- latest version supported by the version of the software being installed.
- Called automatically on startup or reconfiguration of Kea DHCP servers if
- required.
+- ``db-init`` — initializes a new database schema, which is useful
+ during a new Kea installation. The new database is updated to
+ match the Kea version being installed. :iscman:`kea-admin` is
+ automatically invoked with this command if a missing schema is
+ detected during startup or reconfiguration of Kea DHCP servers.
- ``db-version`` — reports the database backend version number. This
is not necessarily equal to the Kea version number, as each backend
+-----------------------+-------------------------+-----------------------+
| Lcase | lcase('LoWeR') | Converts the value of |
| | | a string expression |
- | | | to lower case e.g. |
+ | | | to lower case, e.g. |
| | | 'lower' |
+-----------------------+-------------------------+-----------------------+
| Ucase | ucase('uPpEr') | Converts the value of |
| | | a string expression |
- | | | to upper case e.g. |
+ | | | to upper case, e.g. |
| | | 'UPPER' |
+-----------------------+-------------------------+-----------------------+
| Split | split('foo.bar', '.', 2)| Return the second |
...
}
-The next example shows a client class being defined for use by the DHCPv6
-server. In it the class named "Client_enterprise" is defined. It is
+The next example shows a client class named "Client_enterprise" being defined
+for use by the DHCPv6 server. It is
comprised of all clients whose client identifiers start with the given
-hex string (which would indicate a DUID based on an enterprise ID of
-``0x0002AABBCCDD``). Members of this class will be given 2001:db8:0::1 and
+hex string, which would indicate a DUID based on an enterprise ID of
+``0x0002AABBCCDD``. Members of this class will be given 2001:db8:0::1 and
2001:db8:2::1 as their domain name servers.
::
configuration (vs. alphabetical order). Required classes follow the order in
which they are required.
-When determining which client-class information (comprising of
-options, lease lifetimes or DHCPv4 field values) that is part of class
-definitions, to include in the response, the server examines the union of
+When determining which client-class information (comprised of
+options, lease lifetimes, or DHCPv4 field values) is part of the class
+definitions to be included in the response, the server examines the union of
options from all of the assigned classes. If two or more classes include the
same class information, the value from the first assigned class is used.
-``ALL`` is always the first class, hence the class with the highest
+``ALL`` is always the first class, i.e. the class with the highest
priority, and matching required classes are last, so they have the
lowest priority.
-Optons defined in classes override any global options, and in turn will be
-overridden by options defined for an individual subnet, shared network, pool or
+Options defined in classes override any global options, and in turn are
+overridden by options defined for an individual subnet, shared network, pool, or
reservation.
On the other hand, lease lifetimes and DHCPv4 field values defined at class
to manage and fetch their configuration from one or more databases. In
this documentation, the term "Configuration Backend" may also refer to
the particular Kea module providing support to manage and fetch the
-configuration information from the particular database type. For
+configuration information from the particular database type. For
example, the MySQL Configuration Backend is the logic implemented within
:ischooklib:`libdhcp_mysql_cb.so`, which provides a complete set of functions to
manage and fetch the configuration information from the MySQL database.
The PostgreSQL Configuration Backend is the logic implemented within
:ischooklib:`libdhcp_pgsql_cb.so`, which provides a complete set of functions to
manage and fetch the configuration information from the PostgreSQL database.
-From herein, the term "database" is used to refer to either a MySQL or
+From here on, the term "database" is used to refer to either a MySQL or
PostgreSQL database.
In small deployments, e.g. those comprising a single DHCP server
instance with limited and infrequently changing number of subnets, it
may be impractical to use the CB as a configuration repository because
it requires additional third-party software to be installed and
-configured - in particular the database server, client and libraries.
+configured - in particular the database server, client, and libraries.
Once the number of DHCP servers and/or the number of managed subnets in the
network grows, the usefulness of the CB becomes obvious.
Using the database as a configuration repository for Kea servers also
brings other benefits, such as:
-- the ability to use database specific tools to access the configuration
+- the ability to use database-specific tools to access the configuration
information;
- the ability to create customized statistics based on the information
CB Components
-------------
-To use a MySQL configuration backend you must compile
-:ischooklib:`libdhcp_mysql_cb.so` and configure the DHCP servers to load it.
+To use a MySQL configuration backend, :ischooklib:`libdhcp_mysql_cb.so`
+must be compiled and the DHCP servers must be configured to load it.
It is compiled when the ``--with-mysql`` configuration switch is used during the Kea build.
The MySQL C client libraries must be installed, as explained in :ref:`dhcp-install-configure`.
-To use a PostgreSQL configuration backend you must compile :ischooklib:`libdhcp_pgsql_cb.so`
-and configure the DHCP servers to load it. It is compiled when
+To use a PostgreSQL configuration backend, :ischooklib:`libdhcp_pgsql_cb.so` must
+be compiled and the DHCP servers must be configured to load it. It is compiled when
the ``--with-pgsql`` configuration switch is used during the Kea build. The PostgreSQL
C client libraries must be installed, as explained in :ref:`dhcp-install-configure`.
servers' configuration information within the database. This library can
be attached to both DHCPv4 and DHCPv6 server instances. While it is
possible to manage the configuration information without :ischooklib:`libdhcp_cb_cmds.so`
-with commonly available tools, such as MySQL Workbench or
-the command-line MySQL client, or by directly working with the database;
+using commonly available tools, such as MySQL Workbench or
+the command-line MySQL client, or by directly working with the database,
these avenues are neither recommended nor supported.
The DHCPv4 and DHCPv6 server-specific configurations of the CB, as well as
Commands which contain the logical server `all` are applied to all servers
connecting to the database. The `all` server cannot be
deleted or modified, and it is not returned among other servers
-as a result of the :isccmd:`remote-server4-get-all`, :isccmd:`remote-server6-get-all` commands.
+as a result of the :isccmd:`remote-server4-get-all` and :isccmd:`remote-server6-get-all` commands.
In most cases, there are no server tags defined in the configuration
database; all connecting servers get the same configuration
To differentiate between different Kea server configurations, a
list of the server tags used by the servers must be stored in the
-database. For the DHCPv4 and DHCPv6 servers, it can be done using the
+database. For the DHCPv4 and DHCPv6 servers, this can be done using the
:isccmd:`remote-server4-set` and :isccmd:`remote-server6-set` commands. The
server tags can then be used to associate the configuration information with
the servers. However, it is important to note that some DHCP
curly brackets). However, some hook libraries may expect specific formatting;
please consult the specific hook library documentation for details.
-In a sense the user-context mechanism has superseded the JSON comment
-capabilities; ISC encourages administrators to use user-context instead of
-the older mechanisms. To promote this way of storing comments, Kea compared
-converts JSON comments to user-context on the fly.
+The user-context mechanism has superseded the JSON comment
+capabilities; ISC encourages administrators to use user context instead of
+the older mechanisms. To promote this way of storing comments, Kea
+converts JSON comments to user context on the fly.
However, if the configuration uses the old JSON
-comment, the :isccmd:`config-get` command returns a slightly modified
-configuration. It is not uncommon for a call for :isccmd:`config-set` followed by a
+comment method, the :isccmd:`config-get` command returns a slightly modified
+configuration. It is not uncommon for a call for :isccmd:`config-set` followed by
:isccmd:`config-get` to receive a slightly different structure.
The best way to avoid this problem is simply to abandon JSON comments and
-use user-context.
+use user context.
Kea supports user contexts at the following levels: global scope,
interfaces configuration, shared networks,
:isccmd:`config-set` command. However, there may be certain differences, as
comments are not retained. If the original configuration used file
inclusion, the returned configuration includes all parameters from
-all included files. Starting with 2.4.0, the successful response also
-contains a SHA-256 digest that can be used to easily determine if a
-configuration has changed or not.
+all included files. In Kea 2.4.0 and later, the successful response also
+contains a SHA-256 digest that can be used to easily determine whether a
+configuration has changed.
.. warning::
}
}
-Starting with 2.4.0, also ``config-set`` and ``config-get`` return the SHA-256 hash
-of the new or current configuration. This may be used to later determine if a configuration
-has changed or not.
+In Kea 2.4.0 and later, ``config-set`` and ``config-get`` also return the SHA-256 hash
+of the new or current configuration. This may be used to determine whether a configuration
+has changed.
.. isccmd:: config-reload
.. _command-config-reload:
configuration file that was used previously. This operation is useful if
the configuration file has been changed by some external source; for
example, a system administrator can tweak the configuration file and use this
-command to force Kea pick up the changes.
+command to force Kea to pick up the changes.
-Caution should be taken when mixing this with the :isccmd:`config-set` command. Kea
+Care should be taken when using this in conjunction with the :isccmd:`config-set` command. Kea
remembers the location of the configuration file it was started with,
and this configuration can be significantly changed using the :isccmd:`config-set`
command. When :isccmd:`config-reload` is issued after :isccmd:`config-set`, Kea attempts
hook libraries to be replaced with newer versions, without requiring Kea
servers to be reconfigured or restarted. The hook libraries
are passed the same parameter values (if any) that were passed when they
-originally loaded.
+were originally loaded.
::
{"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }
-Starting with 2.4.0, the successful response from a DHCPv4, DHCPv6, or DHCP-DDNS daemons
-also contain a SHA-256 digest of the newly set configuration. The digest can be used to easily
-determine if a configuration has changed or not.
+In Kea 2.4.0 and later, the successful response from a DHCPv4, DHCPv6, or DHCP-DDNS daemon
+also contains a SHA-256 digest of the newly set configuration. The digest can be used to easily
+determine whether a configuration has changed.
.. isccmd:: shutdown
.. _command-shutdown:
------------------------
The :isccmd:`shutdown` command instructs the server to initiate its shutdown
-procedure. It is the equivalent of sending a ``SIGTERM`` signal to the
+procedure; it is the equivalent of sending a ``SIGTERM`` signal to the
process. This command does not take any arguments. An example command
may look like this:
Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
command source. A server administrator should typically omit this parameter
because the default value "user" indicates that the administrator sent the
-command. In Kea 2.5.5 thru 2.5.7 this parameter was also used in communication
+command. In Kea 2.5.5 through 2.5.7, this parameter was also used in communication
between the HA partners to specify the identifier of an HA service sending the command
-in a numeric format. However, due to the compatibility issues with the older
-Kea versions that did not properly parse the numeric values, it was necessary
+in a numeric format. However, due to compatibility issues with older
+Kea versions that did not properly parse numeric values, it was necessary
to introduce the new parameter, ``origin-id``, in Kea 2.5.8.
It holds a numeric value representing the origin of the command. The same value
can still be passed using the ``origin`` parameter, but it can cause the
-aforementioned compatibility issues between the HA partners running different
-Kea versions. Therefore, new Kea versions favor using ``origin-id`` in communication
-between the HA partners. The ``origin`` parameter can still be used, but the
-``origin-id`` takes precedence. Overall, it is recommended that both parameters be
-omitted from the user commands.
+aforementioned compatibility issues between HA partners running different
+Kea versions; if both are used, ``origin-id`` takes precedence. New Kea versions
+favor using ``origin-id`` in communication between the HA partners, but
+overall, it is recommended that both parameters be
+omitted and the default value used.
The following codes represent the supported origins in numeric format:
- - ``1`` - a user command, same as specifying ``"origin": "user"``,
- - ``2000``, ``2001``, ``2002`` etc. - origins specified by HA partners where
+ - ``1`` - a user command; the same as specifying ``"origin": "user"``.
+ - ``2000``, ``2001``, ``2002``, etc. - origins specified by HA partners where
the increments above ``2000`` are distinct HA service identifiers used when
the partners have many relationships.
}
}
-the effective origin will be ``2002`` which indicates it is an HA partner
+the effective origin is ``2002``, which indicates it is an HA partner
sending the command for the service with ID of ``2``. The ``origin``
parameter will be ignored in this case.
Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
command source. A server administrator should typically omit this parameter
because the default value "user" indicates that the administrator sent the
-command. In Kea 2.5.5 thru 2.5.7 this parameter was also used in communication
+command. In Kea 2.5.5 through 2.5.7, this parameter was also used in communication
between the HA partners to specify the identifier of an HA service sending the command
-in a numeric format. However, due to the compatibility issues with the older
-Kea versions that did not properly parse the numeric values, it was necessary
+in a numeric format. However, due to compatibility issues with older
+Kea versions that did not properly parse numeric values, it was necessary
to introduce the new parameter, ``origin-id``, in Kea 2.5.8.
It holds a numeric value representing the origin of the command. The same value
can still be passed using the ``origin`` parameter, but it can cause the
-aforementioned compatibility issues between the HA partners running different
-Kea versions. Therefore, new Kea versions favor using ``origin-id`` in communication
-between the HA partners. The ``origin`` parameter can still be used, but the
-``origin-id`` takes precedence. Overall, it is recommended that both parameters be
-omitted from the user commands.
+aforementioned compatibility issues between HA partners running different
+Kea versions.; if both are used, ``origin-id`` takes precedence. New Kea versions
+favor using ``origin-id`` in communication between the HA partners, but
+overall, it is recommended that both
The following codes represent the supported origins in numeric format:
- - ``1`` - a user command, same as specifying ``"origin": "user"``,
- - ``2000``, ``2001``, ``2002`` etc. - origins specified by HA partners where
+ - ``1`` - a user command; the same as specifying ``"origin": "user"``.
+ - ``2000``, ``2001``, ``2002``, etc. - origins specified by HA partners where
the increments above ``2000`` are distinct HA service identifiers used when
the partners have many relationships.
}
}
-the effective origin will be ``2002`` which indicates it is an HA partner
+the effective origin is ``2002``, which indicates it is an HA partner
sending the command for the service with ID of ``2``. The ``origin``
parameter will be ignored in this case.
---------------------------
The :isccmd:`version-get` command returns extended information about the Kea
-version. It is the same information available via the ``-V``
+version; it is the same information available via the ``-V``
command-line argument. This command does not take any parameters.
::
attempts even at server startup or on reconfigure events, and will honor the
action specified in the ``on-fail`` parameter.
Database connection retries are not attempted on startup if the
-:ischooklib:`libdhcp_limits.so` is loaded because the hook library requires a
-valid connection to the database to check if JSON format is supported and to
+:ischooklib:`libdhcp_limits.so` is loaded, because the hook library requires a
+valid connection to the database to check whether JSON format is supported and to
recount class limits.
During dynamic reconfiguration, all backends are disconnected and then
operations. If the connection cannot be restored and the server is configured
to exit, it issues a fatal error before shutdown.
-For Kea DHCP servers to work with database backends, the schema has to be
-created and has to have the version specific to the version of the running Kea
-server. If the version check fails on a database backend that is not configured
-as readonly, Kea attempts to initialize the schema.
+For Kea DHCP servers to work with database backends, the database schema must be
+created and must match the version of the Kea
+server. If the version check fails and the database backend is not configured
+as read-only, Kea attempts to initialize the schema.
.. note::
- Schema upgrades are not attempted to not accidentally remove the
- opportunity for prior administrative actions that users may be interested in,
- like, for example, backing up the database or temporarily shutting off running
+ Kea does not automatically attempt to upgrade an existing schema; doing so
+ might deprive users of the opportunity to take precautions, such as
+ backing up the database or temporarily shutting off running
Kea servers that are currently operating on the database.
The connection to the database server can optionally be protected by TLS.
The DHCP-DDNS Server (:iscman:`kea-dhcp-ddns`, known informally as D2) conducts
the client side of the Dynamic DNS protocol (DDNS, defined in `RFC
2136 <https://tools.ietf.org/html/rfc2136>`__) on behalf of the DHCPv4
-and DHCPv6 servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` respectively).
+and DHCPv6 servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`, respectively).
The DHCP servers construct DDNS update requests, known as NameChangeRequests
(NCRs), based on DHCP lease change events and then post them to D2. D2
attempts to match each request to the appropriate DNS server(s) and
carries out the necessary conversation with those servers to update the
DNS data.
-For the ability to generate host names procedurally, based on an expression, and
-for the ability to skip DDNS updates on a per-client basis, or fine-tuning
-various DNS update aspects, the :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` can
-load the premium hook library `libdhcp_ddns_tuning.so` which is available from
-ISC. Please refer to :ref:`hooks-ddns-tuning` documentation for the
-configuration options.
+The Kea hook library :ischooklib:`libdhcp_ddns_tuning.so` provides the ability
+for both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` to generate host names
+procedurally based on an expression, to skip DDNS updates on a per-client basis,
+or to fine-tune various DNS update aspects. Please refer to the :ref:`hooks-ddns-tuning`
+documentation for the configuration options.
.. _dhcp-ddns-dns-server-selection:
key. This value is case-sensitive and must exactly match the value
specified on the DNS server(s). It is a base64-encoded text value.
-- ``secret-file`` - since Kea 2.5.8 a more secure alternative is supported:
- specify a file name where the secret can be found, i.e. the base64-encoded
+- ``secret-file`` - since Kea 2.5.8, this more secure alternative is supported.
+ This value specifies the file name where the secret can be found, i.e. the base64-encoded
secret is the content of the file.
As an example, suppose that a domain D2 will be updating is maintained
The possible values are:
- ``stop-retry-exit`` - disables the DHCP service while trying to automatically
- recover lost connections. Shuts down the server on failure after exhausting
+ recover lost connections, and shuts down the server on failure after exhausting
``max-reconnect-tries``. This is the default value for the lease backend,
the host backend, and the configuration backend.
- ``serve-retry-exit`` - continues the DHCP service while trying to
- automatically recover lost connections. Shuts down the server on failure
+ automatically recover lost connections, and shuts down the server on failure
after exhausting ``max-reconnect-tries``.
- ``serve-retry-continue`` - continues the DHCP service and does not shut down
(the default). A fatal error is logged and the server exits, based on the idea
that the configuration should be valid at startup. Exiting to the operating
system allows nanny scripts to detect the problem.
-If ``retry-on-startup`` is set to ``true``, the server will start reconnection
-attempts even at server startup or on reconfigure events, and will honor the
+If ``retry-on-startup`` is set to ``true``, the server starts reconnection
+attempts even at server startup or on reconfigure events, and honors the
action specified in the ``on-fail`` parameter.
The host parameter is used by the MySQL and PostgreSQL backends.
(the default). A fatal error is logged and the server exits, based on the idea
that the configuration should be valid at startup. Exiting to the operating
system allows nanny scripts to detect the problem.
-If ``retry-on-startup`` is set to ``true``, the server will start reconnection
-attempts even at server startup or on reconfigure events, and will honor the
+If ``retry-on-startup`` is set to ``true``, the server starts reconnection
+attempts even at server startup or on reconfigure events, and honors the
action specified in the ``on-fail`` parameter.
Database connection retries are not attempted on startup if the
-:ischooklib:`libdhcp_limits.so` is loaded because the hook library requires a
-valid connection to the database to check if JSON format is supported and to
+:ischooklib:`libdhcp_limits.so` is loaded, because the hook library requires a
+valid connection to the database to verify whether JSON format is supported and to
recount class limits.
Finally, the credentials of the account under which the server will
compatibility flag (:ref:`dhcp4-compatibility`) does this
automatically, rather than requiring explicit configuration of many pools or
reservations for fake hosts. When ``true``, it applies only to subnets of
-24 prefix length or smaller i.e. larger address space; the default is ``false``.
+prefix length 24 or smaller, i.e. larger address space; the default is ``false``.
In this case, "exclude" means to skip these addresses in the free address pickup
routine of the allocation engine; if a client explicitly requests or
The ``default-url`` option was replaced with ``v4-captive-portal`` in Kea 2.1.2, as introduced by
`RFC 8910 <https://tools.ietf.org/html/rfc8910>`_. The new option has exactly the same format as the
- old one. The general perception is that ``default-url`` was seldom used. If you used it and migrating,
- please replace ``default-url`` with ``v4-captive-portal`` and your configuration will continue to work
- as before.
+ old one. The general perception is that ``default-url`` was seldom used. Migrating users should
+ replace ``default-url`` with ``v4-captive-portal`` in their configurations.
Kea also supports other options than those listed above; the following options
are returned by the Kea engine itself and in general should not be configured
option, or simply option 82. The option itself is just a container and does not convey any information
on its own. The following table contains a list of RAI sub-options that Kea can understand. The RAI
and its sub-options are inserted by the relay agent and received by Kea; there is no need for Kea
-to be configured with those options. Kea's classification and flex-id in host reservations can be
-used to process those and other options no listed in the table below.
+to be configured with those options. Kea's classification and flexible ID features in host reservations can be
+used to process those and other options not listed in the table below.
.. table:: List of RAI sub-options that Kea can understand
+--------------------+------+----------------------------------------------------------------------+
All other RAI sub-options (including those not listed here) can be used in client classification to
-classify incoming packets to specific classes and/or by :ischooklib:`libdhcp_flex_id.so` to
+classify incoming packets to specific classes, and/or by :ischooklib:`libdhcp_flex_id.so` to
construct a unique device identifier. For more information about expressions used in client
-classification, and flex-id, see :ref:`classify`. The RAI sub-options can be
-referenced using ``relay4[option-code].hex``. For example, to classify packets based on the
+classification and flexible identifiers, see :ref:`classify`. The RAI sub-options can be
+referenced using ``relay4[option-code].hex``; for example, to classify packets based on the
``remote-id`` (sub-option code 2), one would use ``relay4[2].hex``. An example client class that
-would include all packets with a specific ``remote-id`` value would looks as follows:
+includes all packets with a specific ``remote-id`` value would look as follows:
::
}
Classes may be used to segregate traffic into a relatively small number of groups, which then
-can be used to select specific subnets, pools and extra options and more. If per host behavior
-is necessary, using host reservations with flex-id is strongly recommended.
+can be used to select specific subnets, pools and extra options, and more. If per-host behavior
+is necessary, using host reservations with flexible identifiers is strongly recommended.
.. _dhcp4-custom-options:
not set its value(s).
The ``name``, ``code``, and ``type`` parameters are required; all others
-are optional. The ``array`` parameter default value is ``false``. The
-``record-types`` and ``encapsulate`` parameters default values are blank
+are optional. The ``array`` parameter's default value is ``false``. The
+``record-types`` and ``encapsulate`` parameters' default values are blank
(``""``). The default ``space`` is ``dhcp4``.
Once the new option format is defined, its value is set in the same way
with vendor space 25167.
This is also how :iscman:`kea-dhcp4` can be configured to send multiple vendor options
-from different vendors, along with each of their specific vendor ID.
+from different vendors, along with each of their specific vendor IDs.
If these options need to be sent by the server regardless of whether the client
specified any enterprise number, ``"always-send": true`` must be configured
for the suboptions that will be included in the ``vivso-suboptions`` option (code 125).
# vivso-suboptions (code 125), and that is enough for Kea to understand that it needs to
# send the option. These options still need to be defined in the configuration, one per
# each vendor, but they don't need "always-send" enabled in that case. For misbehaving
- # clients that to do not explicitly request it, one may alternatively set "always-send"
+ # clients that do not explicitly request it, one may alternatively set "always-send"
# to true for them as well. This is referring to the following two entries in option-data.
{
"name": "vivso-suboptions",
.. note::
:iscman:`kea-dhcp4` is able to recognize multiple Vendor Class Identifier
- options (code 60) with different vendor IDs in the client requests and to
+ options (code 60) with different vendor IDs in the client requests, and to
send multiple vivso options (code 125) in the responses, one for each vendor.
:iscman:`kea-dhcp4` honors DOCSIS sub-option 1 (ORO) and adds only requested options
Support for Long Options
------------------------
-The :iscman:`kea-dhcp4` server partially supports long options (RFC3396).
+The :iscman:`kea-dhcp4` server partially supports long options (RFC 3396).
Since Kea 2.1.6, the server accepts configuring long options and sub-options
(longer than 255 bytes). The options and sub-options are stored internally
in their unwrapped form and they can be processed as usual using the parser
.. note::
Currently the server does not support storing long options in databases,
- either host reservations or the configuration backend.
+ either via host reservations or the configuration backend.
The server is also able to receive packets with split options (options using
the same option code) and to fuse the data chunks into one option. This is
...
}
-The first ``option-data`` entry does not hide the second one, because
+The first ``option-data`` entry does not hide the second one, because the
vendor identifiers (1234 and 5678) are different: the responses will carry
two instances of the ``vivco-suboptions`` option, each for a different vendor.
.. note::
- Behavioral parameters that affect the FQDN are in-effect even in
- if both ``enable-updates`` and ``ddns-send-updates`` are false. They
- behave this way to support environments in which clients are responsible
- for their own DNS updates. This applies to ``ddns-replace-client-name``,
+ Behavioral parameters that affect the FQDN are in effect even
+ if both ``enable-updates`` and ``ddns-send-updates`` are ``false``,
+ to support environments in which clients are responsible
+ for their own DNS updates. This applies to ``ddns-replace-client-name``,
``ddns-generated-prefix``, ``ddns-qualifying-suffix``, ``hostname-char-set``,
and ``hostname-char-replacement``.
...
}
-There are two parameters which determine if :iscman:`kea-dhcp4`
+There are two parameters which determine whether :iscman:`kea-dhcp4`
can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates``
parameter, which now only controls whether :iscman:`kea-dhcp4` connects to D2;
and the new behavioral parameter, ``ddns-send-updates``, which determines
The second parameter added in Kea 1.9.1 is ``ddns-use-conflict-resolution``. This
boolean parameter was passed through to D2 and enabled or disabled conflict resolution
as described in `RFC 4703 <https://tools.ietf.org/html/rfc4703>`__. Beginning with
-Kea 2.5.0, it is deprecated and replaced by ``ddns-conflict-resolution-mode`` which
+Kea 2.5.0, it is deprecated and replaced by ``ddns-conflict-resolution-mode``, which
offers four modes of conflict resolution-related behavior:
- - ``check-with-dhcid`` - The default mode, it instructs D2 to carry out RFC
+ - ``check-with-dhcid`` - This mode, the default, instructs D2 to carry out RFC
4703-compliant conflict resolution. Existing DNS entries may only be
overwritten if they have a DHCID record and it matches the client's DHCID.
- This is equivalent to ``ddns-use-conflict-resolution``: true;
+ This is equivalent to ``ddns-use-conflict-resolution``: ``true``;
- ``no-check-with-dhcid`` - Existing DNS entries may be overwritten by any
- client, whether or not those entries include a DHCID record. The new entries
+ client, whether those entries include a DHCID record or not. The new entries
will include a DHCID record for the client to whom they belong.
- This is equivalent to ``ddns-use-conflict-resolution``: false;
+ This is equivalent to ``ddns-use-conflict-resolution``: ``false``;
- ``check-exists-with-dhcid`` - Existing DNS entries may only be overwritten
if they have a DHCID record. The DHCID record need not match the client's DHCID.
This mode provides a way to protect static DNS entries (those that do not have
a DHCID record) while allowing dynamic entries (those that do have a DHCID
- record) to be overwritten by any client. This behavior was not supported
+ record) to be overwritten by any client. This behavior was not supported
prior to Kea 2.4.0.
- ``no-check-without-dhcid`` - Existing DNS entries may be overwritten by
- any client. New entries will not include DHCID records. This behavior was
+ any client; new entries will not include DHCID records. This behavior was
not supported prior to Kea 2.4.0.
.. note::
- For backward compatibility, ddns-use-conflict-resolution is still accepted in
- JSON configuration. The server will replace the value internally, with the
- ``ddns-conflict-resolution-mode`` and an appropriate value: `
- `check-with-dhcid`` for ``true`` and ``no-check-with-dhcid`` for ``false``.
+ For backward compatibility, ``ddns-use-conflict-resolution`` is still accepted in
+ JSON configuration. The server replaces the value internally with
+ ``ddns-conflict-resolution-mode`` and an appropriate value:
+ ``check-with-dhcid`` for ``true`` and ``no-check-with-dhcid`` for ``false``.
.. note::
Setting ``ddns-conflict-resolution-mode`` to any value other than
- ``check-with-dhcid`` disables the one or more overwrite safeguards
+ ``check-with-dhcid`` disables the overwrite safeguards
that the rules of conflict resolution (from
`RFC 4703 <https://tools.ietf.org/html/rfc4703>`__) are intended to
prevent. This means that existing entries for an FQDN or an
1. Client-B uses the same FQDN as Client-A but a different IP address.
In this case, the forward DNS entries (A and DHCID RRs) for
- Client-A will be deleted as they match the FQDN and new entries for
+ Client-A will be deleted as they match the FQDN, and new entries for
Client-B will be added. The reverse DNS entries (PTR and DHCID RRs)
for Client-A, however, will not be deleted as they belong to a different
IP address, while new entries for Client-B will still be added.
2. Client-B uses the same IP address as Client-A but a different FQDN.
- In this case the reverse DNS entries (PTR and DHCID RRs) for Client-A
+ In this case, the reverse DNS entries (PTR and DHCID RRs) for Client-A
will be deleted as they match the IP address, and new entries for
Client-B will be added. The forward DNS entries (A and DHCID RRs)
for Client-A, however, will not be deleted, as they belong to a different
Disabling conflict resolution should be done only after careful review of
specific use cases. The best way to avoid unwanted DNS entries is to
- always ensure lease changes are processed through Kea, whether they are
+ always ensure that lease changes are processed through Kea, whether they are
released, expire, or are deleted via the :isccmd:`lease4-del` command, prior to
reassigning either FQDNs or IP addresses. Doing so causes :iscman:`kea-dhcp4`
to generate DNS removal requests to D2.
In the second case, lease renewal, two DDNS requests are issued: one
request to remove entries for the previous FQDN, and a second request to
add entries for the new FQDN. In the third case, a lease release - a
-single DDNS request - to remove its entries will be made.
+single DDNS request - to remove its entries is made.
As for the first case, the decisions involved when granting a new lease are
more complex. When a new lease is granted, :iscman:`kea-dhcp4` generates a
(Note that the flag combination N=1, S=1 is prohibited according to `RFC
4702 <https://tools.ietf.org/html/rfc4702>`__. If such a combination is
-received from the client, the packet will be dropped by :iscman:`kea-dhcp4`.)
+received from the client, the packet is dropped by :iscman:`kea-dhcp4`.)
To override client delegation, set the following values in the
configuration file:
a ``hostname-char`` parameter is defined at both the global scope and
in a ``dhcp-ddns`` entry, the second (local) value is used.
- For the ability to generate host names procedurally, based on an expression, and
- for the ability to skip DDNS updates on a per-client basis, or fine-tuning various
- DNS update aspects, the :iscman:`kea-dhcp4` can load the premium hook library
- `libdhcp_ddns_tuning.so` which is available from ISC. Please refer to
- :ref:`hooks-ddns-tuning` documentation for the configuration options.
+ The Kea hook library :ischooklib:`libdhcp_ddns_tuning.so` provides the ability
+ for both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` to generate host names
+ procedurally based on an expression, to skip DDNS updates on a per-client basis,
+ or to fine-tune various DNS update aspects. Please refer to the :ref:`hooks-ddns-tuning`
+ documentation for the configuration options.
.. _dhcp4-next-server:
new lease will be allocated.
For a more visual representation of how Kea recognizes the same client,
-check :ref:`uml-recognizing-same-client`.
+please refer to :ref:`uml-recognizing-same-client`.
.. _dhcp4-authoritative:
This feature is currently implemented for the memfile backend. The
sanity check applies to the lease database in memory, not to the lease file,
-i.e. inconsistent leases will stay in the lease file.
+i.e. inconsistent leases stay in the lease file.
An example configuration that sets this parameter looks as follows:
To support such features as DHCP Leasequery
(`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__) and
-stash agent options (:ref:`stash-agent-options`)
+stash agent options (:ref:`stash-agent-options`),
additional information must be stored with each lease. Because the amount
of information for each lease has ramifications in terms of
performance and system resource consumption, storage of this additional
}
When set to ``true``, information relevant to the DHCPREQUEST asking for the lease is
-added into the lease's user-context as a map element labeled "ISC". Since
-Kea version 2.3.2, when the DHCPREQUEST received contains the option
+added into the lease's user context as a map element labeled "ISC".
+When the DHCPREQUEST received contains the option
(DHCP Option 82), the map contains the ``relay-agent-info`` map
with the content option (DHCP Option 82) in the ``sub-options`` entry and,
when present, the ``remote-id`` and ``relay-id`` options.
Since DHCPREQUESTs sent as renewals are not likely to contain this
information, the values taken from the last DHCPREQUEST that did contain it are
-retained on the lease. The lease's user-context looks something like this:
+retained on the lease. The lease's user context looks something like this:
::
Stash Agent Options
-------------------
-Introduced in version 2.5.8 the ``stash-agent-options`` global parameter
-when set to ``true`` (defaults to ``false``) allows to solve a common
-problem with host reservations using an identifier based on the content
-of the dhcp-agent-options option inserted by relays. When a client tries
-to renew its reserved address the request is sent directly to the server
-so not through the relay: the server is not able to recognize the client
-as the host identifier can't be found in a direct request.
-
-Setting in flex-id (:ref:`hooks-flex-id`) the ``replace-client-id`` to ``true``
-allows the use of the same identifier for leases and host reservations.
-This solves some problems but not this one. In fact this configuration
-is incompatible with ``stash-agent-options``.
-
-When ``stash-agent-options`` is true for direct renewal requests the
-lease for the client address is fetched: if it exists, is not yet expired,
-belongs to the client and has additional information with the
-dhcp-agent-options option content. When all these conditions are met the
-server behaves as the option was included.
-
-.. note::
+This global parameter was added in version 2.5.8 to mirror a feature that was
+previously available in ISC DHCP. When the ``stash-agent-option`` parameter
+is ``true``, the server records the relay agent information options sent
+during the client's initial DHCPREQUEST message (when the client was in the
+SELECTING state) and behaves as if those options are included in all
+subsequent DHCPREQUEST messages sent in the RENEWING state. This works around
+a problem with relay agent information options, which do not usually appear
+in DHCPREQUEST messages sent by the client in the RENEWING state; such messages are
+unicast directly to the server and are not sent through a relay agent.
- Belongs to the client here is implemented the same way as for Releases.
- This guarantees the security of the feature but does not allow the use
- the same identity for both leases and host reservations based on the
- content of the dhcp-agent-options option, i.e. if the client changes
- its identity (client id and/or hardware address) and there is an existing
- not expired lease for the reserved address the lease will conflict.
+The default is ``false``.
.. _dhcp4-multi-threading-settings:
IPv6-Only Preferred Networks
----------------------------
-`RFC8925 <https://tools.ietf.org/html/rfc8925>`_, recently published by the IETF,
+`RFC 8925 <https://tools.ietf.org/html/rfc8925>`_, recently published by the IETF,
specifies a DHCPv4 option to indicate that a host supports an IPv6-only mode and is willing to
forgo obtaining an IPv4 address if the network provides IPv6 connectivity. The general idea is that
a network administrator can enable this option to signal to compatible dual-stack devices that
------------------------------------
By default, :iscman:`kea-dhcp4` does not allocate or store a lease when offering an address
-to a client in response to a DHCPDISCOVER. In general, :iscman:`kea-dhcp4` can fulfill client
+to a client in response to a DHCPDISCOVER. In general, :iscman:`kea-dhcp4` can fulfill client
demands faster by deferring lease allocation and storage until it receives DHCPREQUESTs
-for them. Release 2.3.6 added a new parameter to :iscman:`kea-dhcp4`, ``offer-lifetime``, which
+for them. The ``offer-lifetime`` parameter in :iscman:`kea-dhcp4`
(when not zero) instructs the server to allocate and persist a lease when generating a
DHCPOFFER. In addition:
DNR (Discovery of Network-designated Resolvers) Options for DHCPv4
------------------------------------------------------------------
-One of the more recently added options is the Discovery of
-Network-designated Resolvers or DNR option,
-introduced in `RFC 9463 <https://tools.ietf.org/html/rfc9463>`__. The goal of that RFC is
-to provide a way to communicate location of DNS resolvers available over means other than
-the classic DNS over UDP over port 53. At the time of this writing, the supported technologies
+The Discovery of Network-designated Resolvers, or DNR option, was
+introduced in `RFC 9463 <https://tools.ietf.org/html/rfc9463>`__ as
+a way to communicate location of DNS resolvers available over means other than
+the classic DNS over UDP over port 53. As of spring 2024, the supported technologies
are DoT (DNS-over-TLS), DoH (DNS-over-HTTPS), and DoQ (DNS-over-QUIC), but the option was
designed to be extensible to accommodate other protocols in the future.
The DHCPv4 option and its corresponding DHCPv6 options are almost exactly the same,
-with the exception of cardinality. Only one DHCPv4 option is allowed, while for DHCPv6
-multiple options are allowed. To be able to convey multiple entries, the DHCPv4 is an
+with the exception of cardinality: only one DHCPv4 option is allowed, while multiple
+options are allowed for DHCPv6. To be able to convey multiple entries, the DHCPv4 DNR is an
array that allows multiple DNS instances. Each instance is logically equal to one
-DHCPv6 option, except the minor difference of using IPv4 rather than IPv6 addresses.
+DHCPv6 option; the only difference is that it uses IPv4 rather than IPv6 addresses.
+DNR DHCPv4 options allow more than one DNR instance to be configured, and the DNR
+instances are separated with the "pipe" (``0x7C``) character.
+
+For a detailed example of how to configure the DNR option, see :ref:`dnr6-options`.
-For detailed example how to configure DNR option, see :ref:`dnr6-options`.
-The only difference for DNR DHCPv4 options configuration is that it allows
-to configure more than one DNR instance and the DNR instances are separated
-with the "pipe" (``0x7C``) character.
-For each DNR Instance comma delimited fields must be provided in the following order:
+For each DNR instance, comma-delimited fields must be provided in the following order:
- Service Priority (mandatory),
- ADN FQDN (mandatory),
-- IP address(es) (optional - if more than one - they must be space-separated)
-- SvcParams as a set of key=value pairs (optional - if more than one - they must be space-separated;
- to provide more than one alpn-id separate them with double backslash escaped comma like in the
- example below).
+- IP address(es) (optional; if more than one, they must be separated by spaces)
+- SvcParams as a set of key=value pairs (optional; if more than one - they must be separated by spaces)
+ To provide more than one ``alpn-id``, separate them with double backslash-escaped commas
+ as in the example below).
Example usage:
"name": "v4-dnr",
// 2 DNR Instances:
// - Service priority 2, ADN, resolver IPv4 address and Service Parameters
- // - Service priority 3, ADN - this is ADN-only mode as per RFC9463 3.1.6
+ // - Service priority 3, ADN - this is ADN-only mode as per RFC 9463 3.1.6
"data": "2, resolver.example., 10.0.5.6, alpn=dot\\,doq port=8530 | 3, fooexp.resolver.example."
}
.. note::
- Note that whenever "comma" or "pipe" characters need to be used not as the delimiters, they must be escaped with
- double backslash (``\\,`` or ``\\|``). E.g. one must use escaped commas when configuring more than one ``ALPN``
- protocol to separate them. One might want to use "pipe" (``0x7C``) character in ``dohpath`` Service Parameter,
- as it is allowed in URI. In that case it must be escaped with double backslash.
+ If "comma" or "pipe" characters are used as text rather than as field delimiters, they must be escaped with
+ double backslashes (``\\,`` or ``\\|``). Escaped commas must be used when configuring more than one ``ALPN``
+ protocol, to separate them. The "pipe" (``0x7C``) character can be used in the ``dohpath`` service parameter,
+ as it is allowed in a URI.
-Examples for DNR DHCPv4 options are provided in the Kea sources in
+Examples for DNR DHCPv4 options are provided in the Kea sources, in
`all-options.json` in the `doc/examples/kea4` directory.
}
The ``only-if-required`` parameter is needed here to force evaluation
-of the class after the lease has been allocated and thus the reserved
+of the class after the lease has been allocated, and thus the reserved
class has been also assigned.
.. note::
.. note::
- As soon as a host reservation is found the search is stopped so
+ As soon as a host reservation is found, the search is stopped;
when a client has two host reservations using different enabled
- identifier types the first is always returned and the second
- ignored. In other words, this is usually a configuration mistake.
- In rare cases when having two reservations for the same host makes sense,
- you can control which of those will be used by ordering the list of
- identifier types in `host-reservation-identifiers`.
-
+ identifier types, the first is always returned and the second
+ ignored. In other words, this is usually a configuration error.
+ In those rare cases when having two reservations for the same host makes sense,
+ the one to be used can be specified by ordering the list of
+ identifier types in ``host-reservation-identifiers``.
.. _global-reservations4:
Global Reservations in DHCPv4
-----------------------------
-In some deployments, such as mobile, clients can roam within the network
+In some deployments, such as mobile networks, clients can roam within the network
and certain parameters must be specified regardless of the client's
current location. To meet such a need, Kea offers a global reservation
mechanism. The idea behind it is that regular host
release as an optional mode of operation, enabled with the
``ip-reservations-unique`` global parameter.
-The ``ip-reservations-unique`` is a boolean parameter that defaults to
+``ip-reservations-unique`` is a boolean parameter that defaults to
``true``, which forbids the specification of more than one reservation
for the same IP address within a given subnet. Setting this parameter to
``false`` allows such reservations to be created both in the Kea configuration
file and in the host database backend, via :ischooklib:`libdhcp_host_cmds.so`.
-Setting ``ip-reservations-unique`` to ``false`` when using memfile, MySQL or PostgreSQL is supported.
-This setting is not supported when using Host Cache (see :ref:`hooks-host-cache`), and the RADIUS backend
-(see :ref:`hooks-radius`). These reservation backends simply do not support multiple reservations for the
-same IP. If either of these hooks are loaded and ``ip-reservations-unique`` is set to ``false``, then a
-configuration error will be emitted and the server will fail to start.
+Setting ``ip-reservations-unique`` to ``false`` when using memfile, MySQL, or PostgreSQL is supported.
+This setting is not supported when using Host Cache (see :ref:`hooks-host-cache`) or the RADIUS backend
+(see :ref:`hooks-radius`). These reservation backends do not support multiple reservations for the
+same IP; if either of these hooks is loaded and ``ip-reservations-unique`` is set to ``false``, then a
+configuration error is emitted and the server fails to start.
.. note::
.. note::
- Currently the Kea server does not verify whether multiple reservations for
+ Currently, the Kea server does not verify whether multiple reservations for
the same IP address exist in MySQL and/or PostgreSQL host databases when
``ip-reservations-unique`` is updated from ``false`` to ``true``. This may
cause issues with lease allocations. The administrator must ensure that there
Host Reservations as Basic Access Control
-----------------------------------------
-Starting with Kea 2.3.5, it is possible to define a host reservation that
+It is possible to define a host reservation that
contains just an identifier, without any address, options, or values. In some
deployments this is useful, as the hosts that have a reservation belong to
the KNOWN class while others do not. This can be used as a basic access control
The following example demonstrates this concept. It indicates a single IPv4 subnet
and all clients will get an address from it. However, only known clients (those that
-have reservations) will get their default router configured. Empty reservations
+have reservations) will get their default router configured. Empty reservations,
i.e. reservations that only have the identification criterion, can be
-specifically useful in this regard of making the clients known.
+useful as a way of making the clients known.
::
| | | This statistic is expected to grow |
| | | every time the server transmits a |
| | | packet. In general, it should |
- | | | roughly match pkt4-received, as |
+ | | | roughly match ``pkt4-received``, as|
| | | most incoming packets cause the |
| | | server to respond. There are |
| | | exceptions (e.g. DHCPRELEASE), so |
| | | This statistic is expected to grow |
| | | in most cases after a DHCPDISCOVER |
| | | is processed. There are certain |
- | | | uncommon, but valid, cases where |
+ | | | uncommon but valid cases where |
| | | incoming DHCPDISCOVER packets are |
| | | dropped, but in general this |
| | | statistic is expected to be close |
- | | | to pkt4-discover-received. |
+ | | | to ``pkt4-discover-received``. |
+----------------------------------------------------+----------------+------------------------------------+
| pkt4-ack-sent | integer | Number of DHCPACK packets sent. |
| | | This statistic is expected to grow |
| | | in most cases after a DHCPREQUEST |
- | | | is processed. There are certain |
+ | | | is processed; there are certain |
| | | cases where DHCPNAK is sent |
| | | instead. In general, the sum of |
- | | | pkt4-ack-sent and pkt4-nak-sent |
- | | | should be close to |
- | | | pkt4-request-received. |
+ | | | ``pkt4-ack-sent`` and |
+ | | | ``pkt4-nak-sent`` should be close |
+ | | | to ``pkt4-request-received``. |
+----------------------------------------------------+----------------+------------------------------------+
| pkt4-nak-sent | integer | Number of DHCPNAK packets sent. |
| | | This statistic is expected to grow |
| | | when the server chooses not to |
| | | honor the address requested by a |
| | | client. In general, the sum of |
- | | | pkt4-ack-sent and pkt4-nak-sent |
- | | | should be close to |
- | | | pkt4-request-received. |
+ | | | ``pkt4-ack-sent`` and |
+ | | | ``pkt4-nak-sent`` should be close |
+ | | | to ``pkt4-request-received``. |
+----------------------------------------------------+----------------+------------------------------------+
| pkt4-parse-failed | integer | Number of incoming packets that |
| | | could not be parsed. A non-zero |
| pkt4-receive-drop | integer | Number of incoming packets that |
| | | were dropped. The exact reason for |
| | | dropping packets is logged, but |
- | | | the most common reasons may be: an |
- | | | unacceptable packet type was |
+ | | | the most common reasons may be that|
+ | | | an unacceptable packet type was |
| | | received, direct responses are |
- | | | forbidden, or the server-id sent |
+ | | | forbidden, or the server ID sent |
| | | by the client does not match the |
- | | | server's server-id. |
+ | | | server's server ID. |
+----------------------------------------------------+----------------+------------------------------------+
| subnet[id].total-addresses | integer | Total number of addresses |
| | | available for DHCPv4 management |
| | | take into account any addresses |
| | | that may be reserved due to host |
| | | reservation. The *id* is the |
- | | | the subnet-id of a given subnet. |
+ | | | the subnet ID of a given subnet. |
| | | This statistic is exposed for each |
| | | subnet separately, and is reset |
| | | during a reconfiguration event. |
| | | does not take into account any |
| | | addresses that may be reserved due |
| | | to host reservation. The *id* is |
- | | | the subnet-id of a given subnet. |
- | | | The *pid* is the pool-id of a |
+ | | | the subnet ID of a given subnet. |
+ | | | The *pid* is the pool ID of a |
| | | given pool. This statistic is |
| | | exposed for each subnet pool |
| | | separately, and is reset during a |
| | | is allocated (as a result of |
| | | receiving a DHCPREQUEST message) |
| | | and never decreases. The *id* is |
- | | | the subnet-id of the subnet. This |
+ | | | the subnet ID of the subnet. This |
| | | statistic is exposed for each |
| | | subnet separately, and is reset |
| | | during a reconfiguration event. |
| | | lease is allocated (as a result of |
| | | receiving a DHCPREQUEST message) |
| | | and never decreases. The *id* is |
- | | | the subnet-id of the subnet. The |
- | | | *pid* is the pool-id of the pool. |
+ | | | the subnet ID of the subnet. The |
+ | | | *pid* is the pool ID of the pool. |
| | | This statistic is exposed for each |
| | | subnet pool separately, and is |
| | | reset during a reconfiguration |
| | | every time a lease is released (a |
| | | DHCPRELEASE message is received) |
| | | or expires. The *id* is the |
- | | | subnet-id of the subnet. This |
+ | | | subnet ID of the subnet. This |
| | | statistic is exposed for each |
| | | subnet separately, and is reset |
| | | during a reconfiguration event. |
| | | and decreases every time a lease |
| | | is released (a DHCPRELEASE message |
| | | is received) or expires. The *id* |
- | | | is the subnet-id of the subnet. |
- | | | The *pid* is the pool-id of the |
+ | | | is the subnet ID of the subnet. |
+ | | | The *pid* is the pool ID of the |
| | | pool. This statistic is exposed |
| | | for each subnet pool separately, |
| | | and is reset during a |
| | | server startup. It is incremented |
| | | each time an expired lease is |
| | | reclaimed. The *id* is the |
- | | | subnet-id of a given subnet. This |
+ | | | subnet ID of a given subnet. This |
| | | statistic is exposed for each |
| | | subnet separately. |
+----------------------------------------------------+----------------+------------------------------------+
| | | since server startup. It is |
| | | incremented each time an expired |
| | | lease is reclaimed. The *id* is |
- | | | the subnet-id of a given subnet. |
- | | | The *pid* is the pool-id of the |
+ | | | the subnet ID of a given subnet. |
+ | | | The *pid* is the pool ID of the |
| | | pool. This statistic is exposed |
| | | for each subnet pool separately. |
+----------------------------------------------------+----------------+------------------------------------+
| | | administrator should investigate |
| | | whether there is a misbehaving |
| | | device in the network. The *id* is |
- | | | the subnet-id of a given subnet. |
+ | | | the subnet ID of a given subnet. |
| | | This statistic is exposed for each |
| | | subnet separately. |
+----------------------------------------------------+----------------+------------------------------------+
| | | administrator should investigate |
| | | whether there is a misbehaving |
| | | device in the network. The *id* is |
- | | | the subnet-id of a given subnet. |
- | | | The *pid* is the pool-id of the |
+ | | | the subnet ID of a given subnet. |
+ | | | The *pid* is the pool ID of the |
| | | pool. This statistic is exposed |
| | | for each subnet pool separately. |
+----------------------------------------------------+----------------+------------------------------------+
| reclaimed-declined-addresses | integer | Number of IPv4 addresses that were |
| | | declined, but have now been |
| | | recovered. Unlike |
- | | | declined-addresses, this statistic |
- | | | never decreases. It can be used as |
- | | | a long-term indicator of how many |
- | | | actual valid declines were |
+ | | | ``declined-addresses``, this |
+ | | | statistic never decreases. It can |
+ | | | be used as a long-term indicator of|
+ | | | how many actual valid declines were|
| | | processed and recovered from. This |
| | | is a global statistic that covers |
| | | all subnets. |
| subnet[id].reclaimed-declined-addresses | integer | Number of IPv4 addresses that were |
| | | declined, but have now been |
| | | recovered. Unlike |
- | | | declined-addresses, this statistic |
- | | | never decreases. It can be used as |
- | | | a long-term indicator of how many |
- | | | actual valid declines were |
+ | | | ``declined-addresses``, this |
+ | | | statistic never decreases. It can |
+ | | | be used as a long-term indicator of|
+ | | | how many actual valid declines were|
| | | processed and recovered from. The |
- | | | *id* is the subnet-id of a given |
+ | | | *id* is the subnet ID of a given |
| | | subnet. This statistic is exposed |
| | | for each subnet separately. |
+----------------------------------------------------+----------------+------------------------------------+
| subnet[id].pool[pid].reclaimed-declined-addresses | integer | Number of IPv4 addresses that were |
| | | declined, but have now been |
| | | recovered. Unlike |
- | | | declined-addresses, this statistic |
- | | | never decreases. It can be used as |
- | | | a long-term indicator of how many |
- | | | actual valid declines were |
+ | | | ``declined-addresses``, this |
+ | | | statistic never decreases. It can |
+ | | | be used as a long-term indicator of|
+ | | | how many actual valid declines were|
| | | processed and recovered from. The |
- | | | *id* is the subnet-id of a given |
- | | | subnet. The *pid* is the pool-id |
+ | | | *id* is the subnet ID of a given |
+ | | | subnet. The *pid* is the pool ID |
| | | of the pool. This statistic is |
| | | exposed for each subnet pool |
| | | separately. |
+----------------------------------------------------+----------------+------------------------------------+
| pkt4-lease-query-received | integer | Number of IPv4 DHCPLEASEQUERY |
| | | packets received. (Only exists if |
- | | | Leasequery hook library is |
+ | | | the Leasequery hook library is |
| | | loaded.) |
+----------------------------------------------------+----------------+------------------------------------+
| pkt4-lease-query-response-unknown-sent | integer | Number of IPv4 DHCPLEASEUNKNOWN |
| | | responses sent. (Only exists if |
- | | | Leasequery hook library is |
+ | | | the Leasequery hook library is |
| | | loaded.) |
+----------------------------------------------------+----------------+------------------------------------+
| pkt4-lease-query-response-unassigned-sent | integer | Number of IPv4 DHCPLEASEUNASSIGNED |
| | | responses sent. (Only exists if |
- | | | Leasequery hook library is |
+ | | | the Leasequery hook library is |
| | | loaded.) |
+----------------------------------------------------+----------------+------------------------------------+
| pkt4-lease-query-response-active-sent | integer | Number of IPv4 DHCPLEASEACTIVE |
| | | responses sent. (Only exists if |
- | | | Leasequery hook library is |
+ | | | the Leasequery hook library is |
| | | loaded.) |
+----------------------------------------------------+----------------+------------------------------------+
| v4-allocation-fail | integer | Number of total address allocation |
| | | failures for a particular client. |
- | | | This consists in the number of |
+ | | | This consists of the number of |
| | | lease allocation attempts that the |
- | | | server made before giving up and |
+ | | | server made before giving up, if it|
| | | was unable to use any of the |
| | | address pools. This is a global |
| | | statistic that covers all subnets. |
+----------------------------------------------------+----------------+------------------------------------+
| subnet[id].v4-allocation-fail | integer | Number of total address allocation |
| | | failures for a particular client. |
- | | | This consists in the number of |
+ | | | This consists of the number of |
| | | lease allocation attempts that the |
- | | | server made before giving up and |
+ | | | server made before giving up, if it|
| | | was unable to use any of the |
| | | address pools. The *id* is the |
- | | | subnet-id of a given subnet. This |
+ | | | subnet ID of a given subnet. This |
| | | statistic is exposed for each |
| | | subnet separately. |
+----------------------------------------------------+----------------+------------------------------------+
| subnet[id].v4-allocation-fail-shared-network | integer | Number of address allocation |
| | | failures for a particular client |
| | | connected to a shared network. |
- | | | The *id* is the subnet-id of a |
+ | | | The *id* is the subnet ID of a |
| | | given subnet. This statistic is |
| | | exposed for each subnet |
| | | separately. |
| | | failures for a particular client |
| | | connected to a subnet that does |
| | | not belong to a shared network. |
- | | | The *id* is the subnet-id of a |
+ | | | The *id* is the subnet ID of a |
| | | given subnet. This statistic is |
| | | exposed for each subnet |
| | | separately. |
| | | operator expects that some clients |
| | | should be assigned dynamic |
| | | addresses. The *id* is the |
- | | | subnet-id of a given subnet. This |
+ | | | subnet ID of a given subnet. This |
| | | statistic is exposed for each |
| | | subnet separately. |
+----------------------------------------------------+----------------+------------------------------------+
| | | failures when the client's packet |
| | | belongs to one or more classes. |
| | | There may be several reasons why a |
- | | | lease was not assigned. One of |
- | | | them may be a case when all pools |
- | | | require packet to belong to |
- | | | certain classes and the incoming |
- | | | packet didn't belong to any of |
- | | | them. Another case where this |
+ | | | lease was not assigned: for |
+ | | | example, if all pools |
+ | | | require packets to belong to |
+ | | | certain classes and an incoming |
+ | | | packet does not belong to any. |
+ | | | Another case where this |
| | | information may be useful is to |
- | | | point out that the pool reserved |
- | | | to a given class has ran out of |
+ | | | indicate that the pool reserved |
+ | | | for a given class has run out of |
| | | addresses. This is a global |
| | | statistic that covers all subnets. |
+----------------------------------------------------+----------------+------------------------------------+
| | | failures when the client's packet |
| | | belongs to one or more classes. |
| | | There may be several reasons why a |
- | | | lease was not assigned. One of |
- | | | them may be a case when all pools |
- | | | require packet to belong to |
- | | | certain classes and the incoming |
- | | | packet didn't belong to any of |
- | | | them. Another case where this |
+ | | | lease was not assigned: for |
+ | | | example, if all pools |
+ | | | require packets to belong to |
+ | | | certain classes and an incoming |
+ | | | packet does not belong to any. |
+ | | | Another case where this |
| | | information may be useful is to |
- | | | point out that the pool reserved |
- | | | to a given class has ran out of |
+ | | | indicate that the pool reserved |
+ | | | for a given class has run out of |
| | | addresses. The *id* is the |
- | | | subnet-id of a given subnet. This |
+ | | | subnet ID of a given subnet. This |
| | | statistic is exposed for each |
| | | subnet separately. |
+----------------------------------------------------+----------------+------------------------------------+
| v4-lease-reuses | integer | Number of times an IPv4 lease had |
| | | its CLTT increased in memory and |
| | | its expiration time left unchanged |
- | | | in persistent storage as part of |
+ | | | in persistent storage, as part of |
| | | the lease caching feature. This is |
| | | referred to as a lease reuse. |
| | | This statistic is global. |
| subnet[id].v4-lease-reuses | integer | Number of times an IPv4 lease had |
| | | its CLTT increased in memory and |
| | | its expiration time left unchanged |
- | | | in persistent storage as part of |
+ | | | in persistent storage, as part of |
| | | the lease caching feature. This is |
| | | referred to as a lease reuse. |
| | | This statistic is on a per-subnet |
- | | | basis. The *id* is the subnet-id |
+ | | | basis. The *id* is the subnet ID |
| | | of a given subnet. |
+----------------------------------------------------+----------------+------------------------------------+
| v4-reservation-conflicts | integer | Number of host reservation |
The pool ID can be configured on each pool by explicitly setting the ``pool-id``
parameter in the pool parameter map. If not configured, ``pool-id`` defaults to 0.
The statistics related to pool ID 0 refer to all the statistics of all the pools
- that have unconfigured ``pool-id``.
+ that have an unconfigured ``pool-id``.
The pool ID does not need to be unique within the subnet or across subnets.
- The statistics regarding a specific pool ID within a subnet will be combined with the
+ The statistics regarding a specific pool ID within a subnet are combined with the
other statistics of all other pools with the same pool ID in the respective subnet.
.. note::
limits of statistics:
- ``statistic-default-sample-count`` - determines the default maximum
- number of samples which are kept. The special value of 0
+ number of samples to be kept. The special value of 0
indicates that a default maximum age should be used.
- ``statistic-default-sample-age`` - determines the default maximum
- age in seconds of samples which are kept.
+ age, in seconds, of samples to be kept.
For instance, to reduce the statistic-keeping overhead, set
the default maximum sample count to 1 so only one sample is kept:
--------------------
In principle, Kea aspires to be a reference implementation and aims to implement 100% of the RFC standards.
-However, in some cases there are practical aspects that prevent Kea from completely adhering to the text of the RFC documents.
+However, in some cases there are practical aspects that prevent Kea from completely adhering to the text of all RFC documents.
- `RFC 2131 <https://tools.ietf.org/html/rfc2131>`__, page 30, says that if the incoming DHCPREQUEST packet has no
"requested IP address" option and ``ciaddr`` is not set, the server is supposed to respond with NAK. However,
These are the current known limitations of the Kea DHCPv4 server software. Most of
them are reflections of the current stage of development and should be
-treated as “not implemented yet”, rather than as actual limitations.
+treated as “not yet implemented,” rather than as actual limitations.
However, some of them are implications of the design choices made. Those
are clearly marked as such.
used by all servers connecting to the configuration database.
The following table lists DHCPv4-specific parameters supported by the
-Configuration Backend, with an indication of the level of the hierarchy
+configuration backend, with an indication of the level of the hierarchy
at which it is currently supported.
-.. table:: List of DHCPv4 parameters supported by the Configuration Backend
+.. table:: List of DHCPv4 parameters supported by the configuration backend
+-----------------------------+----------------------------+--------------+-------------+-------------+-------------+
| Parameter | Global | Client | Shared | Subnet | Pool |
+-----------------------------+----------------------------+--------------+-------------+-------------+-------------+
- ``yes`` - indicates that the parameter is supported at the given
- level of the hierarchy and can be configured via the Configuration Backend.
+ level of the hierarchy and can be configured via the configuration backend.
- ``no`` - indicates that a parameter is supported at the given level
- of the hierarchy but cannot be configured via the Configuration Backend.
+ of the hierarchy but cannot be configured via the configuration backend.
- ``n/a`` - indicates that a given parameter is not applicable
at the particular level of the hierarchy or that the
server does not support the parameter at that level.
-Some scalar parameters contained by top level global maps are supported by the Configuration Backend.
+Some scalar parameters contained by top-level global maps are supported by the configuration backend.
-.. table:: List of DHCPv4 map parameters supported by the Configuration Backend
+.. table:: List of DHCPv4 map parameters supported by the configuration backend
+------------------------------------------------------------------+------------------------------+----------------------------------+
| Parameter name (flat naming format) | Global map | Parameter name |
waiting for the next fetch cycle.
In the configuration examples above, two hook libraries are loaded. The first
-is a library which implements the Configuration Backend for a specific database
+is a library which implements the configuration backend for a specific database
type: :ischooklib:`libdhcp_mysql_cb.so` provides support for MySQL and :ischooklib:`libdhcp_pgsql_cb.so`
-provides support for PostgreSQL. The library loaded must match the database
-``type`` specified within the ``config-control`` parameter or an will error be
-logged when the server attempts to load its configuration and the load will
-fail.
+provides support for PostgreSQL. The library loaded must match the database
+``type`` specified within the ``config-control`` parameter; otherwise an error
+is logged when the server attempts to load its configuration, and the load
+fails.
The second hook library, :ischooklib:`libdhcp_cb_cmds.so`, is optional. It should
be loaded when the Kea server instance is to be used to manage the
configuration in the database. See the :ref:`hooks-cb-cmds` section for
-details. This hook library is only available to ISC
-customers with a paid support contract.
+details.
.. _dhcp4-compatibility:
By default, tuple fields defined in custom options are parsed as a set of
length-value pairs.
-With ``"lenient-option-parsing": true``, if a length ever exceeds the rest of
+With ``"lenient-option-parsing": true``, if a length ever exceeded the rest of
the option's buffer, previous versions of Kea returned a log message ``unable to
parse the opaque data tuple, the buffer length is x, but the tuple length is y``
with ``x < y``; this no longer occurs. Instead, the value is considered to be the rest of the buffer,
}
}
-Starting with Kea version 2.5.8 this is extended to silently ignore
-fqdn (81) options with some invalid domain names.
+Starting with Kea version 2.5.8, this parsing is extended to silently ignore
+FQDN (81) options with some invalid domain names.
Ignore DHCP Server Identifier
-----------------------------
Allocators Comparison
---------------------
-In the table below, we briefly compare the supported allocators. The
-detailed allocators' descriptions are in later sections.
+In the table below, we briefly compare the supported allocators, all of which
+are described in detail in later sections.
.. table:: Comparison of the lease allocators supported by Kea DHCPv4
startup and reconfiguration time, because the allocator has to populate the
list of free leases for each subnet where it is used. These delays can be
observed both during the configuration reload and when the subnets are
-created using :ischooklib:`libdhcp_subnet_cmds.so`. The allocator increases the
+created using :ischooklib:`libdhcp_subnet_cmds.so`. This allocator increases
memory consumption to hold the list of free leases, proportional
-to the total size of the address pools for which this allocator is used.
+to the total size of the address pools for which the FLQ allocator is used.
Finally, lease reclamation must be enabled with a low value of the
``reclaim-timer-wait-time`` parameter, to ensure that the server frequently
collects expired leases and makes them available for allocation via the
-free lease queue. Expired leases are not considered free by
+free lease queue; expired leases are not considered free by
the allocator until they are reclaimed by the server. See
:ref:`lease-reclamation` for more details about the lease reclamation process.
The possible values are:
- ``stop-retry-exit`` - disables the DHCP service while trying to automatically
- recover lost connections. Shuts down the server on failure after exhausting
+ recover lost connections, and shuts down the server on failure after exhausting
``max-reconnect-tries``. This is the default value for the lease backend,
the host backend, and the configuration backend.
- ``serve-retry-exit`` - continues the DHCP service while trying to
- automatically recover lost connections. Shuts down the server on failure
+ automatically recover lost connections, and shuts down the server on failure
after exhausting ``max-reconnect-tries``.
- ``serve-retry-continue`` - continues the DHCP service and does not shut down
(the default). A fatal error is logged and the server exits, based on the idea
that the configuration should be valid at startup. Exiting to the operating
system allows nanny scripts to detect the problem.
-If ``retry-on-startup`` is set to ``true``, the server will start reconnection
-attempts even at server startup or on reconfigure events, and will honor the
+If ``retry-on-startup`` is set to ``true``, the server starts reconnection
+attempts even at server startup or on reconfigure events, and honors the
action specified in the ``on-fail`` parameter.
The host parameter is used by the MySQL and PostgreSQL backends.
(the default). A fatal error is logged and the server exits, based on the idea
that the configuration should be valid at startup. Exiting to the operating
system allows nanny scripts to detect the problem.
-If ``retry-on-startup`` is set to ``true``, the server will start reconnection
-attempts even at server startup or on reconfigure events, and will honor the
+If ``retry-on-startup`` is set to ``true``, the server starts reconnection
+attempts even at server startup or on reconfigure events, and honors the
action specified in the ``on-fail`` parameter.
Database connection retries are not attempted on startup if the
-:ischooklib:`libdhcp_limits.so` is loaded because the hook library requires a
-valid connection to the database to check if JSON format is supported and to
+:ischooklib:`libdhcp_limits.so` is loaded, because the hook library requires a
+valid connection to the database to verify whether JSON format is supported and to
recount class limits.
Finally, the credentials of the account under which the server will
are listed here.
Some options are more complex to configure than others. In particular, the Softwire46 family of options
-and DNR are discussed in separate sections below.
+and Discovery of Network-designated Resolvers (DNR) are discussed in separate sections below.
Kea supports more options than those listed above. The following list is mostly useful for readers who
want to understand whether Kea is able to support certain options. The following options are
DNR (Discovery of Network-designated Resolvers) Options for DHCPv6
------------------------------------------------------------------
-One of the more recently added options is the Discovery of
-Network-designated Resolvers or DNR option,
-introduced in `RFC 9463 <https://www.rfc-editor.org/rfc/rfc9463>`__. The goal of that RFC is
-to provide a way to communicate location of DNS resolvers available over means other than
-the classic DNS over UDP port 53. At the time of this writing, the supported technologies
+The Discovery of Network-designated Resolvers, or DNR option, was
+introduced in `RFC 9463 <https://tools.ietf.org/html/rfc9463>`__ as
+a way to communicate location of DNS resolvers available over means other than
+the classic DNS over UDP over port 53. As of spring 2024, the supported technologies
are DoT (DNS-over-TLS), DoH (DNS-over-HTTPS), and DoQ (DNS-over-QUIC), but the option was
designed to be extensible to accommodate other protocols in the future.
-DNR option may be configured using convenient notation. Comma delimited fields must be provided in the following order:
+The DNR option may be configured using convenient notation: comma-delimited fields must be provided in the following order:
- Service Priority (mandatory),
- ADN FQDN (mandatory),
-- IP address(es) (optional - if more than one - they must be space-separated)
-- SvcParams as a set of key=value pairs (optional - if more than one - they must be space-separated;
- to provide more than one alpn-id separate them with double backslash escaped comma like in the
+- IP address(es) (optional; if more than one, they must be separated by spaces)
+- SvcParams as a set of key=value pairs (optional; if more than one, they must be separated by spaces)
+ To provide more than one ``alpn-id``, separate them with double backslash-escaped commas as in the
example below).
-Let's imagine an example that we want to convey a DoT server operating at ``dot1.example.org``
+Let's imagine that we want to convey a DoT server operating at ``dot1.example.org``
(which resolves to two IPv6 addresses: ``2001:db8::1`` and ``2001:db8::2``) on a non-standard port 8530.
An example option that would convey this information looks as follows:
"name": "v6-dnr", // name of the option
// The following fields should be specified:
- // - service priority (unsigned 16 bit integer)
- // - authentication-domain-name (fqdn of the encrypted resolver)
+ // - service priority (unsigned 16-bit integer)
+ // - authentication-domain-name (FQDN of the encrypted resolver)
// - a list of one or more IPv6 addresses
// - list of parameters in key=value format, space separated; any comma
- // characters in this field must be escaped with double backslash
+ // characters in this field must be escaped with double backslashes
"data": "100, dot1.example.org., 2001:db8::1 2001:db8::2, alpn=dot port=8530"
}
::
- 00 64 - service priority (100 in hex as unsigned 16 bit integer)
- 00 12 - length of the Authentication Domain Name (name of the resolver) FQDN (18 in hex as unsigned 16 bit integer)
+ 00 64 - service priority (100 in hex as unsigned 16-bit integer)
+ 00 12 - length of the Authentication Domain Name (name of the resolver) FQDN (18 in hex as unsigned 16-bit integer)
04 64 6f 74 31 07 65 78 61 6d 70 6c 65 03 6f 72 67 00 - 18 octets of the ADN FQDN
00 20 - 32 octets is the length of the following two IPv6 addresses
20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01 - 2001:db8::1
{
"name": "v6-dnr", // name of the option
- // Note the double backslash escaped commas in alpn-id list.
+ // Note the double backslash-escaped commas in the alpn-id list.
"data": "150, resolver.example., 2001:db8::1 2001:db8::2, alpn=dot\\,doq\\,h2\\,h3 dohpath=/q{?dns}"
}
::
- 00 96 - service priority (150 in hex as unsigned 16 bit integer)
- 00 12 - length of the Authentication Domain Name (name of the resolver) FQDN (18 in hex as unsigned 16 bit integer)
+ 00 96 - service priority (150 in hex as unsigned 16-bit integer)
+ 00 12 - length of the Authentication Domain Name (name of the resolver) FQDN (18 in hex as unsigned 16-bit integer)
08 72 65 73 6f 6c 76 65 72 07 65 78 61 6d 70 6c 65 00 - 18 octets of the ADN FQDN
00 20 - 32 octets is the length of the following two IPv6 addresses
20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01 - 2001:db8::1
20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 02 - 2001:db8::2
- 00 01 - SvsParams begin - this is alpn SvcParamKey
+ 00 01 - SvsParams begin - this is the alpn SvcParamKey
00 0e - length of the alpn SvcParamValue field (14 octets)
03 - length of the following alpn-id coded on one octet
64 6f 74 - "dot" - value of the alpn
.. note::
- Note that whenever "comma" characters need to be used not as the delimiters, they must be escaped with
- double backslash (``\\,``). E.g. one must use escaped commas when configuring more than one ``ALPN``
- protocol to separate them.
-
-The `RFC 9463 <https://www.rfc-editor.org/rfc/rfc9463#name-option-format>`__ Section 4.1 is encouraging to include
-at least the ``ALPN`` (Application-Layer Protocol Negotiation) SvcParam, as it will be required in most cases.
-It defines the protocol how the encrypted resolver could be reached. The most common values are
-``dot``, ``doq``, ``h2`` (meaning HTTP/2.0 over TLS, used in DoH).
+ If "comma" or "pipe" characters are used as text rather than as field delimiters, they must be escaped with
+ double backslashes (``\\,`` or ``\\|``). Escaped commas must be used when configuring more than one ``ALPN``
+ protocol, to separate them. The "pipe" (``0x7C``) character can be used in the ``dohpath`` service parameter,
+ as it is allowed in a URI.
-As per `RFC 9461 <https://www.rfc-editor.org/rfc/rfc9461.html#name-new-svcparamkey-dohpath>`__ Section 5:
+`RFC 9463 <https://www.rfc-editor.org/rfc/rfc9463#name-option-format>`__, Section 4.1
+encourages the use of the ``ALPN`` (Application-Layer Protocol Negotiation) SvcParam, as it is required in most cases.
+It defines the protocol for reaching the encrypted resolver. The most common values are
+``dot``, ``doq``, and ``h2`` (meaning HTTP/2.0 over TLS, used in DoH).
-If the ``alpn`` SvcParam indicates support for HTTP, ``dohpath`` MUST be present. The URI Template MUST contain
-a "dns" variable. For example, when advertising DoH resolver available at
+Per `RFC 9461 <https://www.rfc-editor.org/rfc/rfc9461.html#name-new-svcparamkey-dohpath>`__ Section 5: if the
+``alpn`` SvcParam indicates support for HTTP, ``dohpath`` MUST be present. The URI Template MUST contain
+a "dns" variable. For example, when advertising a DoH resolver available at
``https://doh1.example.org/query{?dns}``, the ``dohpath`` should be set to relative URI ``/query{?dns}``.
-A reader interested in configuring this option is encouraged to read the following materials:
+Users interested in configuring this option are encouraged to read the following materials:
- A very nice set of examples is available in Section 7 of `RFC 9461
<https://www.rfc-editor.org/rfc/rfc9461#name-examples>`__.
-- List of all currently defined service parameters is maintained on `IANA registry
+- A list of all currently defined service parameters is maintained in the `IANA registry
<https://www.iana.org/assignments/dns-svcb/dns-svcb.xhtml>`__. This specifies records that can be
stored in the svcParams field of the DNR option.
-- List of currently allowed protocols in the ALPN parameter is maintained on `another IANA registry
+- A list of currently allowed protocols in the ALPN parameter is maintained in `another IANA registry
<https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids>`__.
-- `RFC 9463 <https://www.rfc-editor.org/rfc/rfc9463>`__ which provides option definitions. In terms of SvcParams, it states
- that at `alpn` and `port` must be supported, and `dohpath` (used for DoH) is recommended to be supported.
-- Section 2.2 of `RFC 9460 <https://www.rfc-editor.org/rfc/rfc9460>`__, which defines the on-wire format for SvcParams.
-- Sections 7.1, 7.2 of `RFC 9460 <https://www.rfc-editor.org/rfc/rfc9460>`__, which defines the on-wire format for alpn and port.
-- Section 5 of `RFC 9461 <https://www.rfc-editor.org/rfc/rfc9461#name-new-svcparamkey-dohpath>`__, which defines
- on-wire format for `dohpath`.
+- `RFC 9463 <https://www.rfc-editor.org/rfc/rfc9463>`__ provides option definitions. In terms of SvcParams, it states
+ that ``alpn`` and ``port`` must be supported, and support for ``dohpath`` (used for DoH) is recommended.
+- Section 2.2 of `RFC 9460 <https://www.rfc-editor.org/rfc/rfc9460>`__ defines the on-wire format for SvcParams.
+- Sections 7.1 and 7.2 of `RFC 9460 <https://www.rfc-editor.org/rfc/rfc9460>`__ define the on-wire format for alpn and port.
+- Section 5 of `RFC 9461 <https://www.rfc-editor.org/rfc/rfc9461#name-new-svcparamkey-dohpath>`__ defines the
+ on-wire format for ``dohpath``.
Kea currently supports the following service parameters:
+-----------------+------+------------------------------------------------------------------------+
| Name | Code | Description |
+=================+======+========================================================================+
- | alpn | 1 | Specifies comma separated protocol types (DoT, DoH, etc.) |
+ | alpn | 1 | Specifies comma-separated protocol types (DoT, DoH, etc.) |
+-----------------+------+------------------------------------------------------------------------+
- | port | 3 | Unsigned 16 bit integer. Indicated non-standard TCP or UDP port. |
+ | port | 3 | Unsigned 16-bit integer. Indicates a non-standard TCP or UDP port. |
+-----------------+------+------------------------------------------------------------------------+
| dohpath | 7 | Mandatory for DoH. Contains URL path for the DoT resolver. |
+-----------------+------+------------------------------------------------------------------------+
-Other currently defined service parameters: mandatory (0), no-default-alpn (2), ipv4hint (4), ech (5),
+The other currently defined service parameters mandatory (0), no-default-alpn (2), ipv4hint (4), ech (5),
ipv6hint (6), and ohttp (8) are not usable in the DNR option.
-Further examples are provided in Kea sources in ``all-options.json`` file
-in the ``doc/examples/kea6`` directory. The DHCPv4 option is almost equivalent, and is described
+Further examples are provided in Kea sources in the ``all-options.json`` file
+in the ``doc/examples/kea6`` directory. The DHCPv4 option is nearly identical, and is described
in :ref:`dnr4-options`.
not set its value(s).
The ``name``, ``code``, and ``type`` parameters are required; all others
-are optional. The ``array`` parameter default value is ``false``. The
-``record-types`` and ``encapsulate`` parameters default values are blank
+are optional. The ``array`` parameter's default value is ``false``. The
+``record-types`` and ``encapsulate`` parameters' default values are blank
(``""``). The default ``space`` is ``dhcp6``.
Once the new option format is defined, its value is set in the same way
vendor option is sent even when the client did not specify it in the query.
This is also how :iscman:`kea-dhcp6` can be configured to send multiple vendor options
-from different vendors, along with each of their specific enterprise number.
-If these options need to be sent by the server regardless of whether the client
-specified any enterprise number, ``"always-send": true`` must be configured
-for the suboptions that will be included in the Vendor-Specific Information option (code 17).
+from different vendors, along with each of their specific enterprise numbers.
+To send these options regardless of whether the client specifies an enterprise number,
+the server must be configured with ``"always-send": true``, including the Vendor-Specific
+Information option (code 17).
.. code-block:: json
.. note::
The :iscman:`kea-dhcp6` server is able to recognize multiple Vendor Class
- options (code 16) with different enterprise numbers in the client requests
+ options (code 16) with different enterprise numbers in the client requests,
and to send multiple Vendor-Specific Information options (code 17) in the
responses, one for each vendor.
Nested DHCPv6 Options (Custom Option Spaces)
--------------------------------------------
-It is sometimes useful to define a completely new option space, such as
-when a user creates a new option to convey sub-options that
+It is sometimes useful to define a completely new option space: for example,
+a user might create a new option to convey sub-options that
use a separate numbering scheme, such as sub-options with codes 1
and 2. Those option codes conflict with standard DHCPv6 options, so a
separate option space must be defined.
- ``max-valid-lifetime`` - specifies the maximum valid lifetime (optional).
-Since Kea 1.9.11, these values may be specified within client classes.
+These values may be specified within client classes.
When the client does not specify lifetimes, the default is used.
A specified lifetime - using the IAADDR or IAPREFIX sub-option with
.. note::
- As of Kea 2.3.8, if the preferred-lifetime has not been explicitly specified
- or the specified value is larger than the value of valid-lifetime, the server
- will use the value given by 0.625 * valid-lifetime.
+ If the ``preferred-lifetime`` has not been explicitly specified,
+ or if the specified value is larger than the value of ``valid-lifetime``, the server
+ uses the value of ``valid-lifetime`` multiplied by 0.625.
To send specific fixed values, use the following two parameters:
.. note::
- Behavioral parameters that affect the FQDN are in-effect even in
- if both ``enable-updates`` and ``ddns-send-updates`` are false. They
- behave this way to support environments in which clients are responsible
+ Behavioral parameters that affect the FQDN are in effect even
+ if both ``enable-updates`` and ``ddns-send-updates`` are ``false``,
+ to support environments in which clients are responsible
for their own DNS updates. This applies to ``ddns-replace-client-name``,
``ddns-generated-prefix``, ``ddns-qualifying-suffix``, ``hostname-char-set``,
and ``hostname-char-replacement``.
...
}
-There are two parameters which determine if :iscman:`kea-dhcp6`
+There are two parameters which determine whether :iscman:`kea-dhcp6`
can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates``
parameter, which now only controls whether :iscman:`kea-dhcp6` connects to D2;
and the new behavioral parameter, ``ddns-send-updates``, which determines
The second parameter added in Kea 1.9.1 is ``ddns-use-conflict-resolution``. This
boolean parameter was passed through to D2 and enabled or disabled conflict resolution
as described in `RFC 4703 <https://tools.ietf.org/html/rfc4703>`__. Beginning with
-Kea 2.5.0, it is deprecated and replaced by ``ddns-conflict-resolution-mode`` which
+Kea 2.5.0, it is deprecated and replaced by ``ddns-conflict-resolution-mode``, which
offers four modes of conflict resolution-related behavior:
- - ``check-with-dhcid`` - The default mode, it instructs D2 to carry out RFC
- 4703-compliant conflict resolution. Existing DNS entries may only be
+ - ``check-with-dhcid`` - This mode, the default, instructs D2 to carry out RFC
+ 4703-compliant conflict resolution. Existing DNS entries may only be
overwritten if they have a DHCID record and it matches the client's DHCID.
- This is equivalent to ``ddns-use-conflict-resolution``: true;
+ This is equivalent to ``ddns-use-conflict-resolution``: ``true``;
- ``no-check-with-dhcid`` - Existing DNS entries may be overwritten by any
- client, whether or not those entries include a DHCID record. The new entries
+ client, whether those entries include a DHCID record or not. The new entries
will include a DHCID record for the client to whom they belong.
- This is equivalent to ``ddns-use-conflict-resolution``: false;
+ This is equivalent to ``ddns-use-conflict-resolution``: ``false``;
- ``check-exists-with-dhcid`` - Existing DNS entries may only be overwritten
if they have a DHCID record. The DHCID record need not match the client's DHCID.
This mode provides a way to protect static DNS entries (those that do not have
a DHCID record) while allowing dynamic entries (those that do have a DHCID
- record) to be overwritten by any client. This behavior was not supported
+ record) to be overwritten by any client. This behavior was not supported
prior to Kea 2.4.0.
- ``no-check-without-dhcid`` - Existing DNS entries may be overwritten by
- any client. New entries will not include DHCID records. This behavior was
+ any client; new entries will not include DHCID records. This behavior was
not supported prior to Kea 2.4.0.
.. note::
- For backward compatibility, ddns-use-conflict-resolution is still accepted in
- JSON configuration. The server will replace the value internally, with the
+ For backward compatibility, ``ddns-use-conflict-resolution`` is still accepted in
+ JSON configuration. The server replaces the value internally with
``ddns-conflict-resolution-mode`` and an appropriate value: `
- `check-with-dhcid`` for ``true`` and ``no-check-with-dhcid`` for ``false``.
+ ``check-with-dhcid`` for ``true`` and ``no-check-with-dhcid`` for ``false``.
.. note::
Setting ``ddns-conflict-resolution-mode`` to any value other than
- ``check-with-dhcid`` disables the one or more overwrite safeguards
+ ``check-with-dhcid`` disables the overwrite safeguards
that the rules of conflict resolution (from
`RFC 4703 <https://tools.ietf.org/html/rfc4703>`__) are intended to
prevent. This means that existing entries for an FQDN or an
1. Client-B uses the same FQDN as Client-A but a different IP address.
In this case, the forward DNS entries (AAAA and DHCID RRs) for
- Client-A will be deleted as they match the FQDN and new entries for
+ Client-A will be deleted as they match the FQDN, and new entries for
Client-B will be added. The reverse DNS entries (PTR and DHCID RRs)
for Client-A, however, will not be deleted as they belong to a different
IP address, while new entries for Client-B will still be added.
2. Client-B uses the same IP address as Client-A but a different FQDN.
- In this case the reverse DNS entries (PTR and DHCID RRs) for Client-A
+ In this case, the reverse DNS entries (PTR and DHCID RRs) for Client-A
will be deleted as they match the IP address, and new entries for
Client-B will be added. The forward DNS entries (AAAA and DHCID RRs)
for Client-A, however, will not be deleted, as they belong to a different
Disabling conflict resolution should be done only after careful review of
specific use cases. The best way to avoid unwanted DNS entries is to
- always ensure lease changes are processed through Kea, whether they are
+ always ensure that lease changes are processed through Kea, whether they are
released, expire, or are deleted via the :isccmd:`lease6-del` command, prior to
reassigning either FQDNs or IP addresses. Doing so causes :iscman:`kea-dhcp6`
to generate DNS removal requests to D2.
with it. :iscman:`kea-dhcp6` uses the following configuration parameters to
control this communication:
-- ``enable-updates`` - Enables connectivity to :iscman:`kea-dhcp-ddns` such that DDNS
+- ``enable-updates`` - This enables connectivity to :iscman:`kea-dhcp-ddns` such that DDNS
updates can be constructed and sent.
It must be ``true`` for NCRs to be generated and sent to D2.
It defaults to ``false``.
transmission reaches this value, DDNS updating is turned off
until the queue backlog has been sufficiently reduced. The intent is
to allow the :iscman:`kea-dhcp4` server to continue lease operations without
- running the risk that its memory usage grows without limit. The
+ running the risk that its memory usage may grow without limit. The
default value is ``1024``.
- ``ncr-protocol`` - This specifies the socket protocol to use when sending requests to
(see :ref:`dhcp-ddns-server`). This section describes when :iscman:`kea-dhcp6`
generates NCRs and the configuration parameters that can be used to
influence this decision. It assumes that both the connectivity parameter
-``enable-updates`` and the behavioral parameter ``ddns-send-updates``,
+``enable-updates`` and the behavioral parameter ``ddns-send-updates``
are ``true``.
.. note::
override client delegation requests. When this parameter is ``true``,
:iscman:`kea-dhcp6` disregards requests for client delegation and generates a
DDNS request to update both forward and reverse DNS data. In this case,
-the N-S-O flags in the server's response to the client will be 0-1-1
+the N-S-O flags in the server's response to the client will be 0-1-1,
respectively.
(Note that the flag combination N=1, S=1 is prohibited according to `RFC
The :iscman:`kea-dhcp6` server always generates DDNS update requests if the
client request only contains the Host Name option. In addition, it includes
-an FQDN option in the response to the client with the FQDN N-S-O flags
+an FQDN option in the response to the client, with the FQDN N-S-O flags
set to 0-1-0, respectively. The domain name portion of the FQDN option
is the name submitted to D2 in the DDNS update request.
In early versions of Kea, this parameter was a boolean and permitted only
values of ``true`` and ``false``. Boolean values have been deprecated
- and are no longer accepted. Administrators currently using booleans
+ and are no longer accepted; administrators currently using booleans
must replace them with the desired mode name. A value of ``true``
maps to ``when-present``, while ``false`` maps to ``never``.
mechanism should consider writing a hook that can carry out
sufficiently complex logic to address their needs.
- Make sure that the dot, "." is considered a valid character by the
+ Make sure that the dot, ".", is considered a valid character by the
``hostname-char-set`` expression, such as this: ``"[^A-Za-z0-9.-]"``.
When scrubbing FQDNs, dots are treated as delimiters and used to separate
the option value into individual domain labels that are scrubbed and
a ``hostname-char`` parameter is defined at both the global scope and
in a ``dhcp-ddns`` entry, the second (local) value is used.
- For the ability to generate host names procedurally, based on an expression, and
- for the ability to skip DDNS updates on a per-client basis, or fine-tuning various
- DNS update aspects, the :iscman:`kea-dhcp6` can load the premium hook library
- `libdhcp_ddns_tuning.so` which is available from ISC. Please refer to
- :ref:`hooks-ddns-tuning` documentation for the configuration options.
+ The Kea hook library :ischooklib:`libdhcp_ddns_tuning.so` provides the ability
+ for both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` to generate host names
+ procedurally based on an expression, to skip DDNS updates on a per-client basis,
+ or to fine-tune various DNS update aspects. Please refer to the :ref:`hooks-ddns-tuning`
+ documentation for the configuration options.
.. _dhcp6-dhcp4o6-config:
.. note::
- As soon as a host reservation is found the search is stopped so
+ As soon as a host reservation is found, the search is stopped;
when a client has two host reservations using different enabled
- identifier types the first is always returned and the second
- ignored. In other words, this is usually a configuration mistake.
- In rare cases when having two reservations for the same host makes sense,
- you can control which of those will be used by ordering the list of
- identifier types in `host-reservation-identifiers`.
+ identifier types, the first is always returned and the second
+ ignored. This is usually a configuration error.
+ In those rare cases when having two reservations for the same host makes sense,
+ the one to be used can be specified by ordering the list of
+ identifier types in ``host-reservation-identifiers``.
.. _global-reservations6:
Global Reservations in DHCPv6
-----------------------------
-In some deployments, such as mobile, clients can roam within the network
+In some deployments, such as mobile networks, clients can roam within the network
and certain parameters must be specified regardless of the client's
current location. To meet such a need, Kea offers a global reservation
mechanism. The idea behind it is that regular host
is supported since Kea release 1.9.1 as an optional mode of operation
enabled with the ``ip-reservations-unique`` global parameter.
-The ``ip-reservations-unique`` is a boolean parameter that defaults to
+``ip-reservations-unique`` is a boolean parameter that defaults to
``true``, which forbids the specification of more than one reservation
for the same lease in a given subnet. Setting this parameter to ``false``
allows such reservations to be created both in the Kea configuration
file and in the host database backend, via :ischooklib:`libdhcp_host_cmds.so`.
-Setting ``ip-reservations-unique`` to ``false`` when using memfile, MySQL or PostgreSQL is supported.
-This setting is not supported when using Host Cache (see :ref:`hooks-host-cache`), and the RADIUS backend
-(see :ref:`hooks-radius`). These reservation backends simply do not support multiple reservations for the
-same IP. If either of these hooks are loaded and ``ip-reservations-unique`` is set to ``false``, then a
-configuration error will be emitted and the server will fail to start.
+Setting ``ip-reservations-unique`` to ``false`` when using memfile, MySQL, or PostgreSQL is supported.
+This setting is not supported when using Host Cache (see :ref:`hooks-host-cache`) or the RADIUS backend
+(see :ref:`hooks-radius`). These reservation backends do not support multiple reservations for the
+same IP; if either of these hooks is loaded and ``ip-reservations-unique`` is set to ``false``, then a
+configuration error is emitted and the server fails to start.
.. note::
.. note::
- Currently the Kea server does not verify whether multiple reservations for
+ Currently, the Kea server does not verify whether multiple reservations for
the same IP address and/or delegated prefix exist in
MySQL and/or PostgreSQL) host databases when ``ip-reservations-unique``
is updated from ``false`` to ``true``. This may cause issues with
most one reservation for each IP address and/or delegated prefix
within each subnet, prior to the configuration update.
-The ``reservations-lookup-first`` is a boolean parameter which controls whether
+``reservations-lookup-first`` is a boolean parameter which controls whether
host reservations lookup should be performed before lease lookup. This parameter
has effect only when multi-threading is disabled. When multi-threading is
enabled, host reservations lookup is always performed first to avoid lease-lookup
Host Reservations as Basic Access Control
-----------------------------------------
-Starting with Kea 2.3.5, it is possible to define a host reservation that
+It is possible to define a host reservation that
contains just an identifier, without any address, options, or values. In some
deployments this is useful, as the hosts that have a reservation belong to
the KNOWN class while others do not. This can be used as a basic access control
The following example demonstrates this concept. It indicates a single IPv6 subnet
and all clients will get an address from it. However, only known clients (those that
-have reservations) will get their default DNS server configured. Empty reservations
+have reservations) will get their default DNS server configured. Empty reservations,
i.e. reservations that only have the identification criterion, can be
-specifically useful in this regard of making the clients known.
+useful as a way of making the clients known.
::
| pkt6-receive-drop | integer | Number of incoming packets that |
| | | were dropped. The exact reason for |
| | | dropping packets is logged, but |
- | | | the most common reasons may be: an |
- | | | unacceptable or not supported |
+ | | | the most common reasons may be that|
+ | | | an unacceptable or not-supported |
| | | packet type is received, direct |
| | | responses are forbidden, the |
- | | | server-id sent by the client does |
- | | | not match the server's server-id, |
+ | | | server ID sent by the client does |
+ | | | not match the server's server ID, |
| | | or the packet is malformed. |
+---------------------------------------------------+----------------+------------------------------------+
| pkt6-parse-failed | integer | Number of incoming packets that |
| pkt6-advertise-received | integer | Number of ADVERTISE packets |
| | | received. ADVERTISE packets are |
| | | sent by the server and the server |
- | | | is never expected to receive them. |
- | | | A non-zero value of this statistic |
+ | | | is never expected to receive them; |
+ | | | a non-zero value of this statistic |
| | | indicates an error occurring in |
| | | the network. One likely cause |
| | | would be a misbehaving relay |
| | | longer needed. Note that many |
| | | devices, especially wireless, do |
| | | not send RELEASE packets either |
- | | | because of design choice or due to |
+ | | | because of design choices or due to|
| | | the client moving out of range. |
+---------------------------------------------------+----------------+------------------------------------+
| pkt6-decline-received | integer | Number of DECLINE packets |
| | | This statistic is expected to grow |
| | | every time the server transmits a |
| | | packet. In general, it should |
- | | | roughly match pkt6-received, as |
+ | | | roughly match ``pkt6-received``, as|
| | | most incoming packets cause the |
| | | server to respond. There are |
- | | | exceptions (e.g. server receiving |
- | | | a REQUEST with server-id matching |
+ | | | exceptions (e.g. a server receiving|
+ | | | a REQUEST with server ID matching |
| | | another server), so do not worry |
- | | | if it is less than pkt6-received. |
+ | | | if it is less than |
+ | | | ``pkt6-received``. |
+---------------------------------------------------+----------------+------------------------------------+
| pkt6-advertise-sent | integer | Number of ADVERTISE packets sent. |
| | | This statistic is expected to grow |
| | | in most cases after a SOLICIT is |
| | | processed. There are certain |
- | | | uncommon, but valid, cases where |
+ | | | uncommon but valid cases where |
| | | incoming SOLICIT packets are |
| | | dropped, but in general this |
| | | statistic is expected to be close |
- | | | to pkt6-solicit-received. |
+ | | | to ``pkt6-solicit-received``. |
+---------------------------------------------------+----------------+------------------------------------+
| pkt6-reply-sent | integer | Number of REPLY packets sent. This |
| | | statistic is expected to grow in |
| | | take into account any addresses |
| | | that may be reserved due to host |
| | | reservation. The *id* is the |
- | | | subnet-id of a given subnet. This |
+ | | | subnet ID of a given subnet. This |
| | | statistic is exposed for each |
| | | subnet separately, and is reset |
| | | during a reconfiguration event. |
| | | does not take into account any |
| | | addresses that may be reserved due |
| | | to host reservation. The *id* is |
- | | | the subnet-id of a given subnet. |
- | | | The *pid* is the pool-id of a |
+ | | | the subnet ID of a given subnet. |
+ | | | The *pid* is the pool ID of a |
| | | given pool. This statistic is |
| | | exposed for each subnet pool |
| | | separately, and is reset during a |
| | | a new lease is allocated (as a |
| | | result of receiving a REQUEST |
| | | message) and is never decreased. |
- | | | The *id* is the subnet-id of a |
+ | | | The *id* is the subnet ID of a |
| | | given subnet. This statistic is |
| | | exposed for each subnet |
| | | separately, and is reset during a |
| | | a new lease is allocated (as a |
| | | result of receiving a REQUEST |
| | | message) and is never decreased. |
- | | | The *id* is the subnet-id of a |
+ | | | The *id* is the subnet ID of a |
| | | given subnet. The *pid* is the |
- | | | pool-id of a given pool. This |
+ | | | pool ID of a given pool. This |
| | | statistic is exposed for each |
| | | subnet pool separately, and is |
| | | reset during a reconfiguration |
| | | is decreased every time a lease is |
| | | released (a RELEASE message is |
| | | received) or expires. The *id* is |
- | | | the subnet-id of a given subnet. |
+ | | | the subnet ID of a given subnet. |
| | | This statistic is exposed for each |
| | | subnet separately, and is reset |
| | | during a reconfiguration event. |
| | | is decreased every time a lease is |
| | | released (a RELEASE message is |
| | | received) or expires. The *id* is |
- | | | the subnet-id of a given subnet. |
- | | | The *pid* is the pool-id of the |
+ | | | the subnet ID of a given subnet. |
+ | | | The *pid* is the pool ID of the |
| | | pool. This statistic is exposed |
| | | for each subnet pool separately, |
| | | and is reset during a |
| | | words, this is the count of all |
| | | prefixes in all configured pools. |
| | | This statistic changes only during |
- | | | configuration changes. Note it |
+ | | | configuration changes. Note that it|
| | | does not take into account any |
| | | prefixes that may be reserved due |
| | | to host reservation. The *id* is |
- | | | the subnet-id of a given subnet. |
+ | | | the subnet ID of a given subnet. |
| | | This statistic is exposed for each |
| | | subnet separately, and is reset |
| | | during a reconfiguration event. |
| | | available for DHCPv6 management |
| | | for a given subnet pool; in other |
| | | words, this is the count of all |
- | | | prefixes in configured subnet |
- | | | pd-pool. This statistic changes |
+ | | | prefixes in a configured subnet |
+ | | | PD pool. This statistic changes |
| | | only during configuration changes. |
| | | It does not take into account any |
| | | prefixes that may be reserved due |
| | | to host reservation. The *id* is |
- | | | the subnet-id of a given subnet. |
- | | | The *pid* is the pool-id of a |
+ | | | the subnet ID of a given subnet. |
+ | | | The *pid* is the pool ID of a |
| | | given pool. This statistic is |
- | | | exposed for each subnet pd-pool |
+ | | | exposed for each subnet PD pool |
| | | separately, and is reset during a |
| | | reconfiguration event. |
+---------------------------------------------------+----------------+------------------------------------+
| | | a new lease is allocated (as a |
| | | result of receiving a REQUEST |
| | | message) and is never decreased. |
- | | | The *id* is the subnet-id of a |
+ | | | The *id* is the subnet ID of a |
| | | given subnet. This statistic is |
| | | exposed for each subnet |
| | | separately, and is reset during a |
| | | reconfiguration event. |
+---------------------------------------------------+----------------+------------------------------------+
| subnet[id].pd-pool[pid].cumulative-assigned-pds | integer | Cumulative number of PD prefixes |
- | | | in a given subnet pd-pool that |
+ | | | in a given subnet PD pool that |
| | | were assigned. It increases every |
| | | time a new lease is allocated (as |
| | | a result of receiving a REQUEST |
| | | message) and is never decreased. |
- | | | The *id* is the subnet-id of a |
+ | | | The *id* is the subnet ID of a |
| | | given subnet. The *pid* is the |
- | | | pool-id of a given pd-pool. This |
+ | | | pool ID of a given PD pool. This |
| | | statistic is exposed for each |
- | | | subnet pd-pool separately, and is |
+ | | | subnet PD pool separately, and is |
| | | reset during a reconfiguration |
| | | event. |
+---------------------------------------------------+----------------+------------------------------------+
| | | is decreased every time a lease is |
| | | released (a RELEASE message is |
| | | received) or expires. The *id* is |
- | | | the subnet-id of a given subnet. |
+ | | | the subnet ID of a given subnet. |
| | | This statistic is exposed for each |
| | | subnet separately, and is reset |
| | | during a reconfiguration event. |
| | | is decreased every time a lease is |
| | | released (a RELEASE message is |
| | | received) or expires. The *id* is |
- | | | the subnet-id of a given subnet. |
- | | | The *pid* is the pool-id of the |
- | | | pd-pool. This statistic is exposed |
- | | | for each subnet pd-pool |
+ | | | the subnet ID of a given subnet. |
+ | | | The *pid* is the pool ID of the |
+ | | | PD pool. This statistic is exposed |
+ | | | for each subnet PD pool |
| | | separately, and is reset during a |
| | | reconfiguration event. |
+---------------------------------------------------+----------------+------------------------------------+
| | | each time an expired lease is |
| | | reclaimed (counting both NA and PD |
| | | reclamations). The *id* is the |
- | | | subnet-id of a given subnet. This |
+ | | | subnet ID of a given subnet. This |
| | | statistic is exposed for each |
| | | subnet separately. |
+---------------------------------------------------+----------------+------------------------------------+
| | | since server startup. It is |
| | | incremented each time an expired |
| | | lease is reclaimed. The *id* is |
- | | | the subnet-id of a given subnet. |
- | | | The *pid* is the pool-id of the |
+ | | | the subnet ID of a given subnet. |
+ | | | The *pid* is the pool ID of the |
| | | pool. This statistic is exposed |
| | | for each subnet pool separately, |
| | | and is reset during a |
+---------------------------------------------------+----------------+------------------------------------+
| subnet[id].pd-pool[pid].reclaimed-leases | integer | Number of expired PD prefixes |
| | | associated with a given subnet |
- | | | pd-pool that have been reclaimed |
+ | | | PD pool that have been reclaimed |
| | | since server startup. It is |
| | | incremented each time an expired |
| | | lease is reclaimed. The *id* is |
- | | | the subnet-id of a given subnet. |
- | | | The *pid* is the pool-id of the |
- | | | pd-pool. This statistic is exposed |
- | | | for each subnet pd-pool |
+ | | | the subnet ID of a given subnet. |
+ | | | The *pid* is the pool ID of the |
+ | | | PD pool. This statistic is exposed |
+ | | | for each subnet PD pool |
| | | separately, and is reset during a |
| | | reconfiguration event. |
+---------------------------------------------------+----------------+------------------------------------+
| | | currently declined; a count of the |
| | | number of leases currently |
| | | unavailable. Once a lease is |
- | | | recovered, this statistic will be |
+ | | | recovered, this statistic is |
| | | decreased; ideally, this statistic |
| | | should be zero. If this statistic |
| | | is non-zero or increasing, a |
| | | subnet; a count of the number of |
| | | leases currently unavailable. Once |
| | | a lease is recovered, this |
- | | | statistic will be decreased; |
+ | | | statistic is decreased; |
| | | ideally, this statistic should be |
| | | zero. If this statistic is |
| | | non-zero or increasing, a network |
| | | administrator should investigate |
| | | whether there is a misbehaving |
| | | device in the network. The *id* is |
- | | | the subnet-id of a given subnet. |
+ | | | the subnet ID of a given subnet. |
| | | This statistic is exposed for each |
| | | subnet separately. |
+---------------------------------------------------+----------------+------------------------------------+
| | | subnet pool; a count of the number |
| | | of leases currently unavailable. |
| | | Once a lease is recovered, this |
- | | | statistic will be decreased; |
+ | | | statistic is decreased; |
| | | ideally, this statistic should be |
| | | zero. If this statistic is |
| | | non-zero or increasing, a network |
| | | administrator should investigate |
| | | whether there is a misbehaving |
| | | device in the network. The *id* is |
- | | | the subnet-id of a given subnet. |
- | | | The *pid* is the pool-id of the |
+ | | | the subnet ID of a given subnet. |
+ | | | The *pid* is the pool ID of the |
| | | pool. This statistic is exposed |
| | | for each subnet pool separately. |
+---------------------------------------------------+----------------+------------------------------------+
| reclaimed-declined-addresses | integer | Number of IPv6 addresses that were |
| | | declined, but have now been |
| | | recovered. Unlike |
- | | | declined-addresses, this statistic |
- | | | never decreases. It can be used as |
- | | | a long-term indicator of how many |
- | | | actual valid declines were |
+ | | | ``declined-addresses``, this |
+ | | | statistic never decreases. It can |
+ | | | be used as a long-term indicator of|
+ | | | how many actual valid declines were|
| | | processed and recovered from. This |
| | | is a global statistic that covers |
| | | all subnets. |
| subnet[id].reclaimed-declined-addresses | integer | Number of IPv6 addresses that were |
| | | declined, but have now been |
| | | recovered. Unlike |
- | | | declined-addresses, this statistic |
- | | | never decreases. It can be used as |
- | | | a long-term indicator of how many |
- | | | actual valid declines were |
+ | | | ``declined-addresses``, this |
+ | | | statistic never decreases. It can |
+ | | | be used as a long-term indicator of|
+ | | | how many actual valid declines were|
| | | processed and recovered from. The |
- | | | *id* is the subnet-id of a given |
+ | | | *id* is the subnet ID of a given |
| | | subnet. This statistic is exposed |
| | | for each subnet separately. |
+---------------------------------------------------+----------------+------------------------------------+
| subnet[id].pool[pid].reclaimed-declined-addresses | integer | Number of IPv6 addresses that were |
| | | declined, but have now been |
| | | recovered. Unlike |
- | | | declined-addresses, this statistic |
- | | | never decreases. It can be used as |
- | | | a long-term indicator of how many |
- | | | actual valid declines were |
+ | | | ``declined-addresses``, this |
+ | | | statistic never decreases. It can |
+ | | | be used as a long-term indicator of|
+ | | | how many actual valid declines were|
| | | processed and recovered from. The |
- | | | *id* is the subnet-id of a given |
- | | | subnet. The *pid* is the pool-id |
+ | | | *id* is the subnet ID of a given |
+ | | | subnet. The *pid* is the pool ID |
| | | of the pool. This statistic is |
| | | exposed for each subnet pool |
| | | separately. |
+---------------------------------------------------+----------------+------------------------------------+
| v6-allocation-fail | integer | Number of total address allocation |
| | | failures for a particular client. |
- | | | This consists in the number of |
+ | | | This consists of the number of |
| | | lease allocation attempts that the |
- | | | server made before giving up and |
+ | | | server made before giving up, if it|
| | | was unable to use any of the |
| | | address pools. This is a global |
| | | statistic that covers all subnets. |
+---------------------------------------------------+----------------+------------------------------------+
| subnet[id].v6-allocation-fail | integer | Number of total address allocation |
| | | failures for a particular client. |
- | | | This consists in the number of |
+ | | | This consists of the number of |
| | | lease allocation attempts that the |
- | | | server made before giving up and |
+ | | | server made before giving up, if it|
| | | was unable to use any of the |
| | | address pools. The *id* is the |
- | | | subnet-id of a given subnet. This |
+ | | | subnet ID of a given subnet. This |
| | | statistic is exposed for each |
| | | subnet separately. |
+---------------------------------------------------+----------------+------------------------------------+
| subnet[id].v6-allocation-fail-shared-network | integer | Number of address allocation |
| | | failures for a particular client |
| | | connected to a shared network. |
- | | | The *id* is the subnet-id of a |
+ | | | The *id* is the subnet ID of a |
| | | given subnet. This statistic is |
| | | exposed for each subnet |
| | | separately. |
| | | failures for a particular client |
| | | connected to a subnet that does |
| | | not belong to a shared network. |
- | | | The *id* is the subnet-id of a |
+ | | | The *id* is the subnet ID of a |
| | | given subnet. This statistic is |
| | | exposed for each subnet |
| | | separately. |
| | | operator expects that some clients |
| | | should be assigned dynamic |
| | | addresses. The *id* is the |
- | | | subnet-id of a given subnet. This |
+ | | | subnet ID of a given subnet. This |
| | | statistic is exposed for each |
| | | subnet separately. |
+---------------------------------------------------+----------------+------------------------------------+
| | | failures when the client's packet |
| | | belongs to one or more classes. |
| | | There may be several reasons why a |
- | | | lease was not assigned. One of |
- | | | them may be a case when all pools |
- | | | require packet to belong to |
+ | | | lease was not assigned: for |
+ | | | example, if all pools |
+ | | | require packets to belong to |
| | | certain classes and the incoming |
- | | | packet didn't belong to any of |
- | | | them. Another case where this |
+ | | | packet does not belong to any. |
+ | | | Another case where this |
| | | information may be useful is to |
- | | | point out that the pool reserved |
- | | | to a given class has ran out of |
+ | | | indicate that the pool reserved |
+ | | | for a given class has run out of |
| | | addresses. This is a global |
| | | statistic that covers all subnets. |
+---------------------------------------------------+----------------+------------------------------------+
| | | failures when the client's packet |
| | | belongs to one or more classes. |
| | | There may be several reasons why a |
- | | | lease was not assigned. One of |
- | | | them may be a case when all pools |
- | | | require packet to belong to |
+ | | | lease was not assigned: for |
+ | | | example, if all pools |
+ | | | require packets to belong to |
| | | certain classes and the incoming |
- | | | packet didn't belong to any of |
- | | | them. Another case where this |
+ | | | packet does not belong to any |
+ | | | Another case where this |
| | | information may be useful is to |
- | | | point out that the pool reserved |
- | | | to a given class has ran out of |
+ | | | indicate that the pool reserved |
+ | | | for a given class has run out of |
| | | addresses. The *id* is the |
- | | | subnet-id of a given subnet. This |
+ | | | subnet ID of a given subnet. This |
| | | statistic is exposed for each |
| | | subnet separately. |
+---------------------------------------------------+----------------+------------------------------------+
| v6-ia-na-lease-reuses | integer | Number of times an IA_NA lease had |
| | | its CLTT increased in memory and |
| | | its expiration time left unchanged |
- | | | in persistent storage as part of |
+ | | | in persistent storage, as part of |
| | | the lease caching feature. This is |
| | | referred to as a lease reuse. |
| | | This statistic is global. |
| subnet[id].v6-ia-na-lease-reuses | integer | Number of times an IA_NA lease had |
| | | its CLTT increased in memory and |
| | | its expiration time left unchanged |
- | | | in persistent storage as part of |
+ | | | in persistent storage, as part of |
| | | the lease caching feature. This is |
| | | referred to as a lease reuse. |
| | | This statistic is on a per-subnet |
- | | | basis. The *id* is the subnet-id |
+ | | | basis. The *id* is the subnet ID |
| | | of a given subnet. |
+---------------------------------------------------+----------------+------------------------------------+
| v6-ia-pd-lease-reuses | integer | Number of times an IA_PD lease had |
| | | its CLTT increased in memory and |
| | | its expiration time left unchanged |
- | | | in persistent storage as part of |
+ | | | in persistent storage, as part of |
| | | the lease caching feature. This is |
| | | referred to as a lease reuse. |
| | | This statistic is global. |
| subnet[id].v6-ia-pd-lease-reuses | integer | Number of times an IA_PD lease had |
| | | its CLTT increased in memory and |
| | | its expiration time left unchanged |
- | | | in persistent storage as part of |
+ | | | in persistent storage, as part of |
| | | the lease caching feature. This is |
| | | referred to as a lease reuse. |
| | | This statistic is on a per-subnet |
- | | | basis. The *id* is the subnet-id |
+ | | | basis. The *id* is the subnet ID |
| | | of a given subnet. |
+---------------------------------------------------+----------------+------------------------------------+
The pool ID can be configured on each pool by explicitly setting the ``pool-id``
parameter in the pool parameter map. If not configured, ``pool-id`` defaults to 0.
The statistics related to pool ID 0 refer to all the statistics of all the pools
- that have unconfigured ``pool-id``.
+ that have an unconfigured ``pool-id``.
The pool ID does not need to be unique within the subnet or across subnets.
- The statistics regarding a specific pool ID within a subnet will be combined with the
+ The statistics regarding a specific pool ID within a subnet are combined with the
other statistics of all other pools with the same pool ID in the respective subnet.
.. note::
limits of statistics:
- ``statistic-default-sample-count`` - determines the default maximum
- number of samples which are kept. The special value of 0
+ number of samples to be kept. The special value of 0
indicates that a default maximum age should be used.
- ``statistic-default-sample-age`` - determines the default maximum
- age in seconds of samples which are kept.
+ age, in seconds, of samples to be kept.
For instance, to reduce the statistic-keeping overhead, set
the default maximum sample count to 1 so only one sample is kept:
"prefix-len": 56,
"delegated-len": 64,
- # This is a pool specific context.
+ # This is a pool-specific context.
"user-context": {
"threshold-percent": 85,
"v4-network": "192.168.0.0/16",
- *Relay-Supplied DHCP Options*, `RFC
6422 <https://tools.ietf.org/html/rfc6422>`__: The full functionality is
- supported: OPTION_RSOO; the ability of the server to echo back the
- options; verification of whether an option is RSOO-enabled; the ability to mark
+ supported, including OPTION_RSOO; the ability of the server to echo back the
+ options; verification of whether an option is RSOO-enabled; and the ability to mark
additional options as RSOO-enabled.
- *Prefix Exclude Option for DHCPv6-based Prefix Delegation*, `RFC
- *Generalized UDP Source Port for DHCP Relay*, `RFC 8357
<https://tools.ietf.org/html/rfc8357>`__: The Kea server is able
- to handle Relay Source Port option in a received Relay-forward
- message, remembers the UDP port and sends back Relay-reply with a
+ to handle the Relay Source Port option in a received Relay-forward
+ message, remembers the UDP port, and sends back Relay-reply with a
copy of the option to the relay agent using this UDP port.
- *Dynamic Host Configuration Protocol for IPv6 (DHCPv6)*, `RFC 8415
These are the current known limitations of the Kea DHCPv6 server software. Most of
them are reflections of the current stage of development and should be
-treated as “not implemented yet”, rather than actual limitations.
+treated as “not yet implemented,” rather than actual limitations.
-- The server will allocate, renew, or rebind a maximum of one lease for
+- The server allocates, renews, or rebinds a maximum of one lease for
a particular IA option (IA_NA or IA_PD) sent by a client. `RFC
8415 <https://tools.ietf.org/html/rfc8415>`__ allows for multiple
addresses or prefixes to be allocated for a single IA.
used by all servers connecting to the configuration database.
The following table lists DHCPv6-specific parameters supported by the
-Configuration Backend, with an indication of the level of the hierarchy
+configuration backend, with an indication of the level of the hierarchy
at which it is currently supported.
-.. table:: List of DHCPv6 parameters supported by the Configuration Backend
+.. table:: List of DHCPv6 parameters supported by the configuration backend
+-----------------------------+----------------------------+-----------+-----------+-----------+-----------+------------+
| Parameter | Global | Client | Shared | Subnet | Pool | Prefix |
+-----------------------------+----------------------------+-----------+-----------+-----------+-----------+------------+
- ``yes`` - indicates that the parameter is supported at the given
- level of the hierarchy and can be configured via the Configuration Backend.
+ level of the hierarchy and can be configured via the configuration backend.
- ``no`` - indicates that a parameter is supported at the given level
- of the hierarchy but cannot be configured via the Configuration Backend.
+ of the hierarchy but cannot be configured via the configuration backend.
- ``n/a`` - indicates that a given parameter is not applicable
at the particular level of the hierarchy or that the
server does not support the parameter at that level.
-Some scalar parameters contained by top level global maps are supported by the Configuration Backend.
+Some scalar parameters contained by top level global maps are supported by the configuration backend.
-.. table:: List of DHCPv6 map parameters supported by the Configuration Backend
+.. table:: List of DHCPv6 map parameters supported by the configuration backend
+------------------------------------------------------------------+------------------------------+----------------------------------+
| Parameter name (flat naming format) | Global map | Parameter name |
----------------------
By default, DHCPv6 option 16's ``vendor-class-data`` field is parsed as a set of
-length-value pairs. Same for tuple fields defined in custom options.
+length-value pairs; the same is true for tuple fields defined in custom options.
With ``"lenient-option-parsing": true``, if a length ever exceeds the rest of
the option's buffer, previous versions of Kea returned a log message ``unable to
}
}
-Starting with Kea version 2.5.8 this is extended to silently ignore
+Starting with Kea version 2.5.8, this parsing is extended to silently ignore
client-fqdn (39) options with some invalid domain names.
.. _dhcp6_allocation_strategies:
It prefers assigning specific addresses or delegated prefixes requested by the client
and the ones for which the client has reservations.
-When the client requests a specific delegated prefix, there are a few steps that
-:iscman:`kea-dhcp6` goes through to try to satisfy the request, in the following
+When the client requests a specific delegated prefix,
+:iscman:`kea-dhcp6` follows a series of steps to try to satisfy the request, in this
order:
1. It searches for a lease that matches the requested prefix and prefix length.
The Kea DHCPv6 server provides configuration parameters to select different allocators
at the global, shared-network, and subnet levels. It also
-allows for selecting different allocation strategies for address assignments and
+allows different allocation strategies to be selected for address assignments and
prefix delegation.
Consider the following example:
Allocators Comparison
---------------------
-In the table below, we briefly compare the supported allocators. The
-detailed allocators' descriptions are in later sections.
+In the table below, we briefly compare the supported allocators, all of which
+are described in detail in later sections.
.. table:: Comparison of the lease allocators supported by Kea DHCPv6
For example, it may offer addresses in this order: ``2001:db8:1::10``,
``2001:db8:1::11``, ``2001:db8:1::12``, and so on. Similarly, it offers the
next sequential delegated prefix after the previous one to the next client. The time to
-find and offer the next lease is very short; thus, this is the most performant
+find and offer the next lease or delegated prefix is very short; thus, this is the most performant
allocator when pool utilization is low and there is a high probability
that the next selected lease is available.
The Free Lease Queue allocator can only be used for DHCPv6 prefix delegation.
An attempt to use this allocator for address assignment (with the ``allocator``
parameter) will cause a configuration error. DHCPv6 address pools are
- typically very large and their utilization is low; in these situation, the benefits
+ typically very large and their utilization is low; in this situation, the benefits
of using the FLQ allocator diminish. The amount of time required for the
allocator to populate the free lease queue would cause the server to freeze
upon startup.
impact the server's startup and reconfiguration time, because the allocator
has to populate the list of free leases for each subnet where it is used.
These delays can be observed both during the configuration reload and when
-the subnets are created using :ischooklib:`libdhcp_subnet_cmds.so`. The allocator
-increases the memory consumption to hold the list of free leases,
+the subnets are created using :ischooklib:`libdhcp_subnet_cmds.so`. This allocator
+increases memory consumption to hold the list of free leases,
proportional to the total size of the pools for which this allocator is used.
Finally, lease reclamation must be enabled with a low value of the
``reclaim-timer-wait-time`` parameter, to ensure that the server frequently
We recommend that the FLQ allocator be selected
only after careful consideration. The server puts no restrictions on the
-delegated prefix pool sizes used with the FLQ allocator, so we advise users to
+delegated-prefix pool sizes used with the FLQ allocator, so we advise users to
test how long it takes for the server to load the pools before deploying the
configuration using the FLQ allocator in production. We also recommend
specifying another allocator type in the global configuration settings
---------------
This hook library allows Kea to interact with two types of RADIUS
-services: access and accounting. Although the most common DHCP and RADIUS
-integration is done on the DHCP relay-agent level (DHCP clients send
+services: access and accounting. The most common DHCP and RADIUS
+integration is done on the DHCP relay-agent level: DHCP clients send
DHCP packets to DHCP relays; those relays contact the RADIUS server and
-depending on the response either send the packet to the DHCP server or
-drop it), it does require DHCP relay hardware to support RADIUS
-communication. Also, even if the relay has the necessary support, it is
+either send the packet to the DHCP server or drop it, depending on the
+response. It does require DHCP relay hardware to support RADIUS
+communication, though, and even if the relay has the necessary support, it is
often not flexible enough to send and receive additional RADIUS
-attributes. As such, the alternative looks more appealing: to extend the
+attributes. There is a more appealing alternative: to extend the
DHCP server to talk to RADIUS directly. That is the goal of this library.
.. note::
then sends back either an Access-Accept with specific client attributes,
or an Access-Reject. There are two cases supported here: first, the
Access-Accept includes a Framed-IP-Address attribute (for DHCPv4) or a
-Framed-IPv6-Address attribute or a Delegated-IPv6-Prefix (for DHCPv6),
+Framed-IPv6-Address attribute/Delegated-IPv6-Prefix (for DHCPv6),
which are interpreted by Kea as instructions to assign the specified IPv4
-or IPv6 address, or IPv6 prefix. This effectively means RADIUS can act
+or IPv6 address/IPv6 prefix. This effectively means RADIUS can act
as an address-reservation database.
The second supported case is the ability to assign clients to specific
{
"Dhcp4": {
- // Your regular DHCPv4 configuration parameters goes here.
+ // Your regular DHCPv4 configuration parameters go here.
"hooks-libraries": [
{
RADIUS is a complicated environment. As such, it is not feasible
to provide a default configuration that works for everyone.
However, we do have an example that showcases some of the more common
-features. Please see ``doc/examples/kea4/hooks-radius.json`` in the Kea
+features; please see ``doc/examples/kea4/hooks-radius.json`` in the Kea
sources.
The RADIUS hook library supports the following global configuration
flags:
- ``bindaddr`` (default ``"*"``) - specifies the address to be used by the
- hook library in communication with RADIUS servers. The ``"*"`` special
+ hook library in communication with the RADIUS servers. The ``"*"`` special
value tells the kernel to choose the address at hook library load time.
- ``canonical-mac-address`` (default ``false``) - specifies whether MAC
pairs of hexadecimal digits separated by ``-``).
- ``client-id-pop0`` (default ``false``) - is used with
- :ischooklib:`libdhcp_flex_id.so`. Removes the leading zero (or pair of zeroes
- in DHCPv6) type in the client id (duid in DHCPv6). See
+ :ischooklib:`libdhcp_flex_id.so`; it removes the leading zero (or pair of zeroes
+ in DHCPv6) type in the client ID (DUID in DHCPv6). See
``client-id-printable`` for any value implications when used in conjunction
with it.
- ``client-id-printable`` (default ``false``) - checks whether the
``client-id``/``duid`` content is printable and uses it as is instead of in
- hexadecimal. Implies ``client-id-pop0`` and ``extract-duid`` as 0 and 255 are
+ hexadecimal. It implies that ``client-id-pop0`` and ``extract-duid`` as 0 and 255 are
not printable.
- ``deadtime`` (default ``0``) - is a mechanism that helps in sorting the
- servers such that the servers that have proved responsive so far are inquired
- first, and the servers that have proved unresponsive are left at the end. The
+ servers so those that have proved responsive so far are contacted
+ first, and the servers that have proved unresponsive are left to try later. The
deadtime value specifies the number of seconds after which a server is
considered unresponsive. 0 disables the mechanism.
- ``dictionary`` (default ``"/etc/kea/radius/dictionary"``) - is the
- attribute and value dictionary. Note that it is a critical parameter.
+ attribute and value dictionary; note that it is a critical parameter.
A dictionary is provided by Kea and is set by default.
-- ``extract-duid`` (default ``true``) - extracts the embedded duid from an
- RFC-4361-compliant DHCPv4 client id. See ``client-id-printable`` for any
+- ``extract-duid`` (default ``true``) - extracts the embedded DUID from an
+ RFC 4361-compliant DHCPv4 client ID. See ``client-id-printable`` for any
value implications when used in conjunction with it.
- ``identifier-type4`` (default ``"client-id"``) - specifies the identifier
- type to build the User-Name attribute. It should be the same as the
+ type to build the User-Name attribute for DHCPv4; it should be the same as the
host identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
``replace-client-id`` must be set to ``true`` and ``client-id`` must be used
with ``client-id-pop0`` enabled.
- ``identifier-type6`` (default ``"duid"``) - specifies the identifier type to
- build the User-Name attribute. It should be the same as the host
+ build the User-Name attribute for DHCPv6; it should be the same as the host
identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
``replace-client-id`` must be set to ``true`` and ``duid`` must be used with
``client-id-pop0`` enabled.
- ``nas-ports`` (default ``[]``), specifies the NAS port to use in place of
a subnet ID (default behavior). It is an array of maps, each map having two
- elements at most: the mandatory NAS port value, and, optionally, a selector
- consisting of either a subnet id, a subnet prefix, or a shared-network name.
+ elements at most: the mandatory NAS port value, and optionally, a selector
+ consisting of either a subnet ID, a subnet prefix, or a shared-network name.
If the selector is applied to the packet, the NAS port is used instead of the
- subnet id. When the subnet id is 0 or missing, the specified NAS port acts as
- a default. Its substition happens for all packets that did not match a
+ subnet ID. When the subnet ID is 0 or missing, the specified NAS port acts as
+ a default. The substitution happens for all packets that did not match a
selector.
- ``realm`` (default ``""``) - is the default realm.
- ``reselect-subnet-address`` (default ``false``) - enables subnet reselection
according to the value of the Framed-IP-Address or, respectively,
the Framed-IPv6-Address attribute from the RADIUS access response. With this
- flag enabled, if the IP address is not in range of the currently selected
- subnet, but is in range of another subnet that is selectable with regards to
+ flag enabled, if the IP address is not in the range of the currently selected
+ subnet, but is in the range of another subnet that is selectable with regards to
other criteria, the latter subnet is selected and used further in the lease
assignment process.
another selectable subnet that is guarded by it, the latter subnet is
selected and used further in the lease assignment process.
This reselection is attempted first, and if successful, it prevents the
- function of reselect-subnet-address from coming into effect.
+ function of ``reselect-subnet-address`` from coming into effect.
- ``retries`` (default ``3``) - is the number of retries before trying the
next server.
persistent storage for accounting session history.
- ``thread-pool-size`` (default ``0``) indicates the number of threads that
- is used for sending RADIUS requests and processing RADIUS responses for both
- access and accounting services before passing it to the core thread pool. A
+ are used for sending RADIUS requests and processing RADIUS responses for both
+ access and accounting services before passing them to the core thread pool. A
value of ``0`` instructs the RADIUS hook library to use the same number of
- threads used for core DHCP processing. This value is only relevant if Kea
- core is configured as multi-threaded. Single-threaded Kea core results in
+ threads used for core DHCP processing. This value is only relevant if the Kea
+ core is configured as multi-threaded; a single-threaded Kea core results in
single-threaded RADIUS processing.
- ``timeout`` (default ``10``) - is the number of seconds during which a
defines the value in hex), or ``expr`` (which defines an expression
that is evaluated for each incoming packet independently).
- - ``name`` - the name of the attribute.
+ - ``name`` - is the name of the attribute.
- - ``type`` - the type of the attribute. Either the type or the name must be
+ - ``type`` - is the type of the attribute. Either the type or the name must be
provided, and the attribute must be defined in the dictionary.
- - ``data`` - the first of three ways to specify the attribute content.
+ - ``data`` - is the first of three ways to specify the attribute content.
It specifies the textual representation of the attribute content.
- - ``raw`` - the second of three ways to specify the attribute content.
+ - ``raw`` - is the second of three ways to specify the attribute content.
It specifies the content in hexadecimal.
- - ``expr`` - the last of the three ways to specify the attribute content.
+ - ``expr`` - is the last of the three ways to specify the attribute content.
It specifies an evaluation expression on the DHCP query packet.
- Currently this is restricted to the access service.
+
Attributes are supported only for the access service.
- The ``peer-updates`` boolean flag (default ``true``) controls whether lease
updates coming from an active High-Availability (HA) partner should result in
an accounting request. This may be desirable to remove duplicates if HA
- partners are configured to send request to the same RADIUS server. The flag is
+ partners are configured to send requests to the same RADIUS server. The flag is
only supported by the accounting service. The lease synchronization process at
the startup of an HA node does not trigger a RADIUS accounting request,
regardless of the value of this flag.
- The ``max-pending-requests`` positive integer (default ``0``) limits the
- number of pending RADIUS requests. The value ``0`` means no limit. It is
- supported only by the access service. ``64`` can be a good value to set it to.
+ number of pending RADIUS requests. It is supported only by the access service.
+ The value ``0`` means no limit; ``64`` is a recommended setting.
For example, to specify a single access server available on localhost
that uses ``"xyz123"`` as a secret, and tell Kea to send three additional
For :ischooklib:`libdhcp_radius.so` to operate properly in DHCPv4,
:ischooklib:`libdhcp_host_cache.so` must also be loaded. The reason for this
-is somewhat complex. In a typical deployment, the DHCP clients send
+is somewhat complex. In a typical deployment, DHCP clients send
their packets via DHCP relay, which inserts certain Relay Agent
Information options, such as ``circuit-id`` or ``remote-id``. The values of
those options are then used by the Kea DHCP server to formulate the
necessary attributes in the Access-Request message sent to the RADIUS
server. However, once the DHCP client gets its address, it then renews
-by sending packets directly to the DHCP server. As a result, the relays
-are not able to insert their RAI options, and the DHCP server cannot send
+by sending packets directly to the DHCP server. The relays cannot
+insert their RAI options at that point, and the DHCP server cannot send
the Access-Request queries to the RADIUS server by using just the
information from incoming packets. Kea needs to keep the information
received during the initial Discover/Offer exchanges and use it again
This mechanism is implemented based on user context in host
reservations. (See :ref:`user-context` and :ref:`user-context-hooks` for
details.) The host-cache mechanism allows the information retrieved by
-RADIUS to be stored and later used for sending access and accounting
+RADIUS to be stored and used later to send access and accounting
queries to the RADIUS server. In other words, the host-cache mechanism
is mandatory, unless administrators do not want RADIUS communication for messages
other than Discover and the first Request from each client.
.. note::
Currently the RADIUS hook library is incompatible with the
- ``early-global-reservations-lookup`` global parameter i.e.
+ ``early-global-reservations-lookup`` global parameter, i.e.
setting the parameter to ``true`` raises an error when the
hook library is loaded.
---------------------------
The RADIUS hook library requires at least one RADIUS server to function. One
-popular open-source implementation is FreeRADIUS. This is how it can be
-set up to enable basic functionality in Kea.
+popular open source implementation is FreeRADIUS; here's how to
+set it up to enable basic functionality in Kea.
1. Install FreeRADIUS through the package manager or from the tarballs available
on [the freeradius.org download page](https://freeradius.org/releases/).
5. If the Kea DHCP server and the RADIUS server are on different machines,
edit ``/etc/freeradius/clients.conf`` with the proper address under
- ``ipadddr``. This file is also where the secret is set, which needs to match
+ ``ipadddr``. This file is also where the secret is set; it needs to match
the one set in the hook library's configuration.
-6. If RADIUS is used for the purpose of authorizing DHCP clients, each DHCP
+6. If RADIUS is used to authorize DHCP clients, each DHCP
client needs to have an entry in the authorize file, which can be commonly
found at:
- ``/etc/freeradius/3.0/mods-config/files/authorize``
- ``/etc/freeradius/users`` (for RADIUS 2.x series)
- Entries need to have the password set which needs to match the password
- configured in the configuration of the RADIUS hook library under the
- ``User-Password`` attribute. Each entry can have zero, one or multiple
+ The passwords for entries must match the passwords
+ in the configuration of the RADIUS hook library under the
+ ``User-Password`` attribute. Each entry can have zero or more
attributes.
- In the following example, there are 6 entries with the password set to the
- client ID, which would need to be dynamically set in the hook library's
- configuration. Here's how the entries can look like:
+ In the following example, there are six entries with the password set to the
+ client ID, which needs to be dynamically set in the hook library's
+ configuration. Here's how the entries might look:
::
Framed-IPv6-Address = "2001:db8::9",
Framed-Pool = "classroom"
-7. Accounting should work out of the box with Kea, but customizations are
- possible in the accounting file, which can be commonly found at:
+7. Accounting does not need to be modified to work with Kea, but customizations are
+ possible in the accounting file, which can commonly be found at:
- ``/etc/radius-config/mods-config/files/accounting``
- ``/etc/freeradius/3.0/mods-config/files/accounting``
RADIUS Workflows for Lease Allocation
-------------------------------------
-The following diagrams show a high level view of how RADIUS assists with the
+The following diagrams show a high-level view of how RADIUS assists with the
lease allocation process in :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`.
.. figure:: ../uml/radius.*
Refer to :ref:`parked-packet-limit` for a basic introduction to packet parking.
-The RADIUS hook library makes use of this mechanism. To allow for asynchronous
+The RADIUS hook library uses this mechanism. To allow for asynchronous
communication between Kea and the RADIUS server and concurrent processing of
DHCP packets by the Kea server, the DHCP request is parked, before the access
request is sent on the subnet select callout. When the access response becomes
available to the Kea DHCP server, the request is unparked, and the server
-continues processing on it.
+continues processing it.
.. _radius-differences:
-Differences Between RADIUS Hook Libraries Prior To 2.4.0 and As Of 2.6.0
-------------------------------------------------------------------------
+Differences Between RADIUS Hook Libraries Prior To Kea 2.4.0 and As Of 2.6.0
+----------------------------------------------------------------------------
The RADIUS hook library in 2.4.0 and prior versions relied on the FreeRADIUS
-client library to function. Starting with 2.6.0 and onwards, the RADIUS hook
-library is standalone with its own RADIUS client implementation and its own
+client library to function. Starting with 2.6.0 and onward, the RADIUS hook
+library is standalone, with its own RADIUS client implementation and its own
RADIUS dictionary. There are differences:
.. list-table::
- Taken from the FreeRADIUS dictionary.
- - Taken from the Kea RADIUS dictionary and the IANA registry. There is an aliasing mechanism built into the library that ensures backward compatibility e.g. ``Password`` translates to the standard name of the attribute ``User-Password``.
+ - Taken from the Kea RADIUS dictionary and the IANA registry. There is an aliasing mechanism built into the library that ensures backward compatibility, e.g. ``Password`` translates to the standard name of the attribute ``User-Password``.
* - Resolution of RADIUS Server Domain Names
$ ./hammer.py build -p local -x install docs
The basic scope can be extended by mysql, pgsql, native-pkg, shell, and forge.
-Please check ``./hammer.py build --help`` for more details.
+Please refer to ``./hammer.py build --help`` for more details.
.. note::
:ischooklib:`libdhcp_pgsql_cb.so` implements this API for PostgreSQL.
To manage the configuration information in a MySQL database, both
:ischooklib:`libdhcp_mysql_cb.so` and :ischooklib:`libdhcp_cb_cmds.so`
-must be loaded by the server used for the configuration management.
+must be loaded by the server used for configuration management.
To manage the configuration information in a PostgreSQL database, both
:ischooklib:`libdhcp_pgsql_cb.so` and :ischooklib:`libdhcp_cb_cmds.so`
-must be loaded by the server used for the configuration management.
+must be loaded by the server used for configuration management.
More information on how to configure the Configuration Backend hook library for
use with a MySQL or PostgreSQL database can be found in the :ref:`dhcp4-cb`
This command includes the ``interface`` parameter, which sets the shared
-network-level interface name. Any remaining shared-network level parameters,
+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 uses the global
values for unspecified parameters or, if the global values are not
shared network, no option is deleted. In particular, the given
option may be present for a subnet belonging to the shared network.
Such an option instance is not affected by this command as this
-command merely deletes the shared-network level option. To
+command merely deletes the shared-network-level option. To
delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`,
:isccmd:`remote-option6-subnet-del` commands must be used instead.
In particular, the given option may exist for a subnet containing
the specified pool. Such an option instance is not affected by this
command, as this command merely deletes a prefix delegation pool-level
-option. To delete a subnet level option, the
+option. To delete a subnet-level option, the
:isccmd:`remote-option6-subnet-del` command must be used instead.
.. code-block:: json
In particular, the given option may exist for a subnet containing
the specified pool. Such an option instance is not affected by this
command, as this command merely deletes a pool-level option. To
-delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`,
-:isccmd:`remote-option6-subnet-del` commands must be used instead.
+delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`
+or :isccmd:`remote-option6-subnet-del` command must be used instead.
The following command attempts to delete an option having the
option code 5 in the top-level option space from an IPv4 address
The returned information about each subnet is limited to the subnet identifier,
prefix, and associated shared network name. To retrieve full
information about the selected subnet, use
-the :isccmd:`remote-subnet4-get-by-id`, :isccmd:`remote-subnet6-get-by-id` commands
-or the :isccmd:`remote-subnet4-get-by-prefix`, :isccmd:`remote-subnet6-get-by-prefix` commands.
+the :isccmd:`remote-subnet4-get-by-id` / :isccmd:`remote-subnet6-get-by-id` command
+or the :isccmd:`remote-subnet4-get-by-prefix` / :isccmd:`remote-subnet6-get-by-prefix` command.
The example response above contains two subnets. One of the subnets is
associated with both servers: "server1" and "server2". The second subnet is
The structure of the subnet information is similar to the structure used
in the configuration file (see :ref:`dhcp4-configuration` and
:ref:`dhcp6-configuration`). The subnet information conveyed in the
-:isccmd:`remote-subnet4-set`, :isccmd:`remote-subnet6-set` commands
+:isccmd:`remote-subnet4-set` or :isccmd:`remote-subnet6-set` command
must include the additional parameter
``shared-network-name``, which denotes whether the subnet belongs to a
shared network.
.. note::
:ischooklib:`libdhcp_mysql_cb.so` is part of the open source code and is
- available to every Kea user, but it requires :ischooklib:`libdhcp_cb_cmds.so`
- which is available only to ISC customers with
- a paid support contract. For more information on subscription options,
- please complete the form at https://www.isc.org/contact.
+ available to every Kea user. However, this hook library only works
+ with :ischooklib:`libdhcp_cb_cmds.so`, which allows easy configuration
+ management with the use of API commands. :ischooklib:`libdhcp_cb_cmds.so`
+ is available only to ISC customers with a paid support contract; for more information
+ on subscription options, please complete the form at https://www.isc.org/contact.
.. note::
:ischooklib:`libdhcp_pgsql_cb.so` is part of the open source code and is
- available to every Kea user, but it requires :ischooklib:`libdhcp_cb_cmds.so`
- which is available only to ISC customers with
- a paid support contract. For more information on subscription options,
- please complete the form at https://www.isc.org/contact.
+ available to every Kea user. However, this hook library only works
+ with :ischooklib:`libdhcp_cb_cmds.so`, which allows easy configuration
+ management with the use of API commands. :ischooklib:`libdhcp_cb_cmds.so`
+ is available only to ISC customers with a paid support contract; for more information
+ on subscription options, please complete the form at https://www.isc.org/contact.
different name using :isccmd:`class-add`. Note, however, that the class with
the new name will be added at the end of the list of configured classes.
-As with other update commands, this command overwrites all the contents of the
+As with other update commands, this command overwrites all the contents of an
entry. If the client class previously had a resource assigned to it, and the
:isccmd:`class-update` command is missing the resource, it is deleted from the server
-configuration. If an incremental update of the class is desired, then this can
-be achieved by doing a :isccmd:`class-get` to get the current state
-of the client class, picking the client class out of the response, modifying it
+configuration. If an incremental update of the class is desired, it can
+be achieved by issuing a :isccmd:`class-get` to get the current state
+of the client class, selecting the client class from the response, modifying it
to the required outcome, and then issuing the ``client-update`` command with the
resulting client class attached.
specified. The option space is DHCPv4 or DHCPv6, depending
on the server where the hook library is loaded.
-Similar to other hook libraries, :ischooklib:`libdhcp_flex_option.so` can be loaded
+:ischooklib:`libdhcp_flex_option.so` can be loaded
by either the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
process. It takes a mandatory ``options`` parameter with a list of
per-option parameter maps, with ``code``, ``name``, ``add``, ``supersede``, and
followed by ``.boot`` for content.
A commonly discussed use case is modifying the DHCPv4 subnet mask option
-(code 1). The following example demonstrates that capability. All ingress
+(code 1). The following example demonstrates that capability, as all ingress
packets identified by the gateway address 192.168.0.1 are met with a /32 subnet
-mask in the response.
+mask in the response:
.. code-block:: json
}
}
-The flexible option library supports both DHCPv4 and DHCPv6.
+The Flexible Option library supports both DHCPv4 and DHCPv6.
-Since Kea 1.9.0, the ``add`` and ``supersede`` actions take an optional
+The ``add`` and ``supersede`` actions take an optional
```csv-format``` boolean parameter. If not specified or set to ``false``, the
option data is set using the raw value of the evaluated expression. When it is
configured to ``true``, this value is parsed using the option definition from
for options using complex record formats or fully qualified domain names.
For instance, if the expression evaluation returns "example.com" and
-the option is defined with the ``fqdn`` type, the domain name will be
+the option is defined with the ``fqdn`` type, the domain name is
encoded into DNS binary format.
-Since Kea 2.1.4, the ``client-class`` parameter specifies a class guard.
-It takes a client class name. If not empty, the client's packet needs to
-belong to specified class for this entry to be used.
+Since Kea 2.1.4, the ``client-class`` parameter specifies a class guard,
+and takes a client-class name. If not empty, the client's packet needs to
+belong to tne specified class for this entry to be used.
-Since Kea 2.1.4, it is allowed to have multiple entries for the same option,
+It is also possible to have multiple entries for the same option,
but each entry must have exactly one action. If the option is not defined
-in the ``dhcp4`` for DHCPv4 or ``dhcp6`` for DHCPv6 you can specify the
-space where to find the option definition using its name with the new
+in ``dhcp4`` for DHCPv4 or ``dhcp6`` for DHCPv6, the location of
+the option definition can be specified using its name, with the new
``space`` parameter.
-Since Kea 2.1.4, sub-options are supported with a new entry ``sub-options``
+Since Kea 2.1.4, sub-options are supported with a new entry, ``sub-options``,
which replaces the action in the configuration of the container option,
i.e. the option where sub-options are located.
-The ``sub-options`` entry takes a list of sub-option configuration similar
-to the option one with:
+The ``sub-options`` parameter takes a list of sub-option entries, each
+containing:
-- ``code`` - specifies the sub-option code, either the ``code`` or ``name``
- must be specified. When both are given they must match or the configuration
+- ``code`` - specifies the sub-option code; either the ``code`` or ``name``
+ must be specified. If both are given, they must match or the configuration
is rejected at load time.
-- ``name`` - specifies the sub-option name, either the ``code`` or ``name``
- must be specified. When both are given they must match or the configuration
+- ``name`` - specifies the sub-option name; either the ``code`` or ``name``
+ must be specified. If both are given, they must match or the configuration
is rejected at load time.
- ``space`` - specifies the space where the sub-option can be defined. This
- parameter is optional because it can be found in the container option
+ parameter is optional, because it can be found in the container option
definition. The configuration is rejected if no valid space name is
available at load time. Note that vendor spaces are supported for the
DHCPv4 ``vivso-suboptions`` and for the DHCPv6 ``vendor-opts``, both
- ``remove`` - (action) removes a sub-option if it already exists and the
expression evaluates to true.
-- ``container-add`` - boolean value which specifies if the container option
- should be created if it does not exit in the ``add`` and ``supersede``
- action. When not specified, it defaults to true.
+- ``container-add`` - a boolean value that specifies whether the container option
+ should be created, if it does not exist in the ``add`` and ``supersede``
+ action. If not specified, it defaults to ``true``.
-- ``container-remove`` - boolean value which specifies if the container option
- should be deleted if it remains empty after the removal of a sub-option by
- the ``remove`` action. When not specified, it defaults to true.
+- ``container-remove`` - a boolean value that specifies whether the container option
+ should be deleted, if it remains empty after the removal of a sub-option by
+ the ``remove`` action. If not specified, it defaults to ``true``.
-- ``csv-format`` - boolean value which specifies if the raw value of the
+- ``csv-format`` - a boolean value that specifies whether the raw value of the
evaluated expression is used (false, default) or parsed using the sub-option
definition (true).
-- ``client-class`` - specifies if the sub-option entry must be skipped when
- the **query** does not belong to the specified client class. Note the similar
+- ``client-class`` - specifies whether the sub-option entry must be skipped when
+ the **query** does not belong to the specified client class. Note that the similar
parameter in the container option entry applies to the whole ``sub-options``
list.
-For instance this configuration adds a string sub-option in the DHCPv4
-``vendor-encapsulated-options`` (code 43) option. Note this option
-in last resort encapsulates the ``vendor-encapsulated-options`` space.
+For instance, this configuration adds a string sub-option in the DHCPv4
+``vendor-encapsulated-options`` (code 43) option. This option
+encapsulates the ``vendor-encapsulated-options`` space.
.. code-block:: json
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An HA-enabled server initiates synchronization of the lease database after
-downtime or upon receiving the :isccmd:`ha-sync` command. The server uses commands
+downtime or upon receiving the :isccmd:`ha-sync` command. The server uses the commands
:isccmd:`lease4-get-page` and :isccmd:`lease6-get-page`
to fetch leases from its partner server (lease queries). The size of the results
page (the maximum number of leases to be returned in a single response to one of
Multi-Threaded Configuration (HA+MT)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-HA peer communication consists of specialized API commands sent between HA peers.
-Prior to Kea 1.9.7, each peer had to be paired with a local instance of
-:iscman:`kea-ctrl-agent` in order to exchange commands. The agent received HA commands
-via HTTP, communicated via Linux socket with the local peer to carry out the
-command, and then sent the response back to the requesting peer via HTTP. To
-send HA commands, each peer opened its own HTTP client connection to the URL of
-each of its peers.
-
-In Kea 1.9.7 and newer, it is possible to configure HA to use direct
+It is possible to configure HA to use direct
multi-threaded communication between peers. We refer to this mode as HA+MT.
With HA+MT enabled, each peer runs its own dedicated, internal HTTP listener
(i.e. server) which receives and responds to commands directly, thus eliminating
-the need for an agent to carry out HA protocol between peers. In addition, both
-the listener and client components use multi-threading to support multiple,
+the need for an agent to carry out the HA protocol between peers. In addition, both
+the listener and client components use multi-threading to support multiple
concurrent connections between peers. By eliminating the agent and executing
-multiple command exchanges in parallel, HA throughput between peers should
-improve considerably in most situations.
+multiple command exchanges in parallel, HA throughput between peers
+improves considerably over earlier versions of Kea in most situations.
The following parameters have been added to the HA configuration, to support
HA+MT operation:
Refer to :ref:`parked-packet-limit` for a basic introduction to packet parking.
-The HA hook library makes use of this mechanism. When an HA server
+The HA hook library uses this mechanism. When an HA server
needs to send a lease update to its peers to notify them of the change to the
-lease, it will park the client response until the peers acknowledge the lease
-update. At that point, the server will unpark the response and send it to the
-client. This applies to client queries which cause lease changes, such as
+lease, it parks the client response until the peers acknowledge the lease
+update. At that point, the server unparks the response and sends it to the
+client. This applies to client queries that cause lease changes, such as
DHCPREQUEST for DHCPv4 and Request, Renew, and Rebind for DHCPv6. It does not
apply to DHPCDISCOVERs (v4) or Solicits (v6).
stop serving any DHCP clients, so it can be safely shut down.
The maintenance feature of the High Availability hook library addresses this
-situation. The :isccmd:`ha-maintenance-start` command was introduced to allow the
-administrator to put the pairs of the active servers in a state in which one of
+situation. The :isccmd:`ha-maintenance-start` command allows the
+administrator to put the pairs of the active servers into a state in which one of
them is responding to all DHCP queries and the other one is awaiting shutdown.
Suppose that the HA setup includes two active servers, ``server1`` and
If the server has many relationships with different partners, the ``ha-maintenance-start``
command attempts to transition all of the relationships into the
-``partner-in-maintenance`` state by sending the ``ha-mainteance-notify`` to all
-partner servers. If this step fails for any server an error is returned.
-In that case, send the ``ha-maintenance-cancel`` command to resume normal
-operation and fix the issue.
+``partner-in-maintenance`` state by sending ``ha-maintenance-notify`` to all
+partner servers. If this step fails for any server, an error is returned.
+If that happens, the ``ha-maintenance-cancel`` command can be used to resume normal
+operations and fix the issue.
Upgrading From Older HA Versions
}
}
-The optional ``server-name`` parameter specifies a name of one of the partners belonging
-to the HA relationship this command pertains to. This parameter can be omitted if the
-server receiving this command has only one HA relationship in the configuration.
+The optional ``server-name`` parameter specifies the name of one of the partners in
+the HA relationship that this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in its configuration.
.. isccmd:: ha-continue
.. _command-ha-continue:
}
}
-The optional ``server-name`` parameter specifies a name of one of the partners belonging
-to the HA relationship this command pertains to. This parameter can be omitted if the
-server receiving this command has only one HA relationship in the configuration.
+The optional ``server-name`` parameter specifies the name of one of the partners in
+the HA relationship that this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in its configuration.
.. isccmd:: ha-heartbeat
.. _command-ha-heartbeat:
}
}
-The optional ``server-name`` parameter specifies a name of one of the partners belonging
-to the HA relationship this command pertains to. This parameter can be omitted if the
-server receiving this command has only one HA relationship in the configuration.
+The optional ``server-name`` parameter specifies the name of one of the partners in
+the HA relationship that this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in its configuration.
Upon successful communication with the server, a response similar to this should
be returned:
The ``ha-maintenance-start`` Command
------------------------------------
-This command is used to initiate the transition of the server's partners into the
-``in-maintenance`` state and the transition of the server receiving the command
-into the ``partner-in-maintenance`` state in each HA relationship. See the
+This command initiates the transition of the server's partners into the
+``in-maintenance`` state, and the transition of the server receiving the command
+into the ``partner-in-maintenance`` state, in each HA relationship. See the
:ref:`ha-maintenance` section for details.
::
-------------------------------------
This command is used to cancel the maintenance previously initiated using the
-:isccmd:`ha-maintenance-start` command. The server receiving this command will first
-send :isccmd:`ha-maintenance-notify`, with the ``cancel`` flag set to ``true``, to its
+:isccmd:`ha-maintenance-start` command. The server receiving this command first
+sends :isccmd:`ha-maintenance-notify`, with the ``cancel`` flag set to ``true``, to its
partners. Next, the server reverts from the ``partner-in-maintenance`` state to
its previous state. See the :ref:`ha-maintenance` section for details.
}
}
-The optional ``server-name`` parameter specifies a name of one of the partners belonging
-to the HA relationship this command pertains to. This parameter can be omitted if the
-server receiving this command has only one HA relationship in the configuration.
+The optional ``server-name`` parameter specifies the name of one of the partners in
+the HA relationship that this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in its configuration.
.. warning::
}
}
-The optional ``server-name`` parameter specifies a name of one of the partners belonging
-to the HA relationship this command pertains to. This parameter can be omitted if the
-server receiving this command has only one HA relationship in the configuration.
+The optional ``server-name`` parameter specifies the name of one of the partners in
+the HA relationship that this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in its configuration.
It elicits the response:
}
}
-The optional ``server-name`` parameter specifies a name of one of the partners belonging
-to the HA relationship this command pertains to. This parameter can be omitted if the
-server receiving this command has only one HA relationship in the configuration.
+The optional ``server-name`` parameter specifies the name of one of the partners in
+the HA relationship that this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in its configuration.
The ``origin-id`` parameter is used to select the HA service for which the receiving server should
enable the DHCP service when it receives this notification. This is the same origin the
Hub and Spoke Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The hub-and-spoke is a common arrangement of the DHCP servers for resiliency. It contains
-one central server and multiple branch servers. The branch servers are the primary servers
+A hub-and-spoke arrangement, with one central server and multiple branch servers,
+is a common way to ensure resiliency of the DHCP servers. The branch servers are the primary servers
in the ``hot-standby`` mode and respond to the local DHCP traffic in their respective
locations. The central server acts as a standby server for each branch server.
It maintains independent state machines with the branch servers, called relationships.
If one of the branch servers experiences a failure, the central server can take over its
-DHCP traffic. In this case, we say that one of the central server's relationships is in
+DHCP traffic. In this case, one of the central server's relationships is in
the ``partner-down`` state. The remaining relationships may still be in the ``hot-standby``
state and not actively respond to DHCP traffic. When the branch server becomes active again,
-it synchronizes the lease database with the central server, and the central server becomes
-fully passive again. In rare cases, when multiple branch servers stop, the central server
-takes responsibility for all their traffic (possibly the entire DHCP traffic in the network
-when all branch servers are down). A simple hub-and-spoke arrangement consisting of two
+it synchronizes the lease database with the central server and the central server becomes
+fully passive again. In rare cases, if multiple branch servers stop, the central server
+takes responsibility for all their traffic, and potentially all DHCP traffic in the entire network
+if every branch server is down. A simple hub-and-spoke arrangement consisting of two
branch servers and one central server is shown below.
::
+---------------------------+
Each branch server's configuration comprises a set of subnets appropriate for the branch
-server. Different branch servers serve different subnets. The central server's configuration
-comprises all subnets of the branch servers so that it can respond to the DHCP traffic
-directed to any of the failing branch servers. The subnets in the central server must be
-grouped into relationships like in the snippet below:
+server; different branch servers serve different subnets. The central server's configuration
+includes all subnets of the branch servers, so that it can respond to DHCP traffic
+directed to any branch servers that fail. The subnets in the central server must be
+grouped into relationships as in the snippet below:
.. code-block:: json
The peer names in the relationships must be unique. The user context for each subnet contains
-the ``ha-server-name`` parameter associating a subnet with a relationship. The ``ha-server-name``
-can be any of the peer names in the relationship. Suppose a relationship contains peer names
-``server1`` and ``server2``. It doesn't matter whether the ``ha-server-name`` is ``server1`` or
+the ``ha-server-name`` parameter, associating a subnet with a relationship. The ``ha-server-name``
+can be any of the peer names in the relationship. For example, if a relationship contains peer names
+``server1`` and ``server2``, it does not matter whether the ``ha-server-name`` is ``server1`` or
``server2``. In both cases, it associates a subnet with that relationship.
It is not required to specify the ``ha-server-name`` in the branch servers, assuming that the
.. note::
- Even though it is not required to include the ``ha-server-name`` user context parameters in the
+ Even though it is possible to omit the ``ha-server-name`` user context parameters in the
branch servers, we recommend including them. The servers fetch all leases from the
- partners during the database synchronization. If the subnets are not explicitly associated with
+ partners during the database synchronization; if the subnets are not explicitly associated with
the relationship, the branch server inserts all fetched leases from the central server (including
- those from other relationships) into its database. Specifying ``ha-server-name`` parameter for
+ those from other relationships) into its database. Specifying the ``ha-server-name`` parameter for
each configured subnet in the branch server guarantees that only the leases belonging to its
relationship are inserted into the branch server's database.
.. note::
The peer names in the branch servers must match the peer names in the respective central
- server's relationships because these names are used for signaling between the HA partners.
+ server's relationships, because these names are used for signaling between the HA partners.
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before examining the individual commands, it is worth discussing the
-parameter ``subnet-id``. Currently this parameter is mandatory for all of the
+parameter ``subnet-id``. Currently, this parameter is mandatory for all of the
commands supplied by this library, with the exception of
:isccmd:`reservation-get-by-hostname` and :isccmd:`reservation-get-by-address`,
-where it is optional. Since Kea 1.9.0,
-``subnet-id`` is also optional in :isccmd:`reservation-get-page`, and
-it is forbidden in :isccmd:`reservation-get-by-id`.
+where it is optional. ``subnet-id`` is also optional in
+:isccmd:`reservation-get-page`, and it is forbidden
+in :isccmd:`reservation-get-by-id`.
Reservations can be specified globally, and are not necessarily specific to any
subnet. When reservations are supplied via the configuration file, the
On the other hand, when the ``subnet-id`` is not specified in the command
parameters, it is added to each host in responses. If the ``subnet-id``
has the unused special value, this means the host entry belongs only
-to the other IP version (i.e. IPv6 in DHCPv4 server or IPv4 in DHCPv6
+to the other IP version (i.e. IPv6 in the DHCPv4 server or IPv4 in the DHCPv6
server) and this entry is ignored.
The ``operation-target`` Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Most host commands accept the ``operation-target`` parameter that selects
+Most host commands accept the ``operation-target`` parameter, which selects
the host data source. The commands may process data from the server
configuration (i.e., memory operation target), a database (database target),
-or both of them (all sources). The operation target parameter is optional.
+or both (all sources). The operation-target parameter is optional.
By default, the commands that only read the data use all data sources
-(memory and database); the commands that modify the state (i.e., :isccmd:`reservation-add`,
+(memory and database); the commands that modify the state (i.e. :isccmd:`reservation-add`,
:isccmd:`reservation-del`, and :isccmd:`reservation-update`) only use the
database target.
The ``operation-target`` parameter accepts the following values:
-- ``memory`` - query or update the runtime server configuration.
-- ``database`` - query or update host database(s).
-- ``all`` - query or update both runtime configuration and host database(s).
-- ``default`` - query or update a default host data source - it is command specific.
+- ``memory`` - query or update the runtime server configuration
+- ``database`` - query or update host database(s)
+- ``all`` - query or update both runtime configuration and host database(s)
+- ``default`` - query or update a default host data source - it is command-specific
.. isccmd:: reservation-add
.. _command-reservation-add:
}
In that case, however, it does not assign any resources to the host. An IPv4
-address can be assigned like so:
+address can be assigned as in this example:
.. code-block:: json
}
}
-It can also take many more parameters, for example:
+It can also take many more parameters, such as:
.. code-block:: json
}
The command accepts the ``operation-target`` argument. By default, it gets the
-reservation from both JSON configuration and the hosts database.
+reservation from both the JSON configuration and the hosts database.
.. code-block:: json
consider using :isccmd:`reservation-get-page` instead.
The command accepts the ``operation-target`` argument. By default, it gets the
-reservation from both JSON configuration and the hosts database.
+reservation from both the JSON configuration and the hosts database.
.. code-block:: json
"text": "0 IPv4 host(s) found."
}
-The command doesn't accept the ``operation-target`` argument.
+The command does not accept the ``operation-target`` argument.
-This command is more complex than :isccmd:`reservation-get-all`, but lets
+This command is more complex than :isccmd:`reservation-get-all`, but it lets
users retrieve larger host reservations lists in smaller chunks. For
small deployments with few reservations, it is easier to use
:isccmd:`reservation-get-all`.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:isccmd:`reservation-get-by-address` can be used to query the host database and
-retrieve all reservations for given IP address or a delegated prefix (without
-a prefix length) in a specified subnet or in all subnets. This command uses
+retrieve all reservations for a given IP address or a delegated prefix (without
+a prefix length), in a specified subnet or in all subnets. This command uses
parameters providing the mandatory ``ip-address`` and the optional ``subnet-id``
and ``operation-target``.
"text": "2 IPv4 host(s) found."
}
-To search for all reservations in all subnets simply skip the ``subnet-id`` parameter:
+To search for all reservations in all subnets, simply skip the ``subnet-id`` parameter:
::
]
}
-An example response can be:
+An example response could be:
::
When using the command for retrieving DHCP6 host reservations, one can provide
either an IPv6 address or a delegated prefix as the ``ip-address`` parameter.
Please notice that this command does not take prefix length as a parameter in the
-current implementation. That's why searching by an IP address ``2001:db8:2:cafe::``
-can return host reservations having delegated prefixes matching this search with
-different lengths. For example: ``2001:db8:2:cafe::/63``, ``2001:db8:2:cafe::/64`` etc.
+current implementation. Thus, searching by an IP address ``2001:db8:2:cafe::``
+can return host reservations with delegated prefixes of different lengths matching
+this search. For example: ``2001:db8:2:cafe::/63``, ``2001:db8:2:cafe::/64``, etc.
Please consider the example below:
::
}
The command accepts the ``operation-target`` argument. By default, it gets the
-reservation from both JSON configuration and the hosts database.
+reservation from both the JSON configuration and the hosts database.
.. code-block:: json
This command is useful in specific cases. By default, having more than
one host reservation for the same IP address in a given subnet is not allowed,
- as explained in the
+ as explained in
:ref:`Multiple Reservations for the Same IPv4 <multiple-reservations-same-ip4>`
- or in the
+ or
:ref:`Multiple Reservations for the Same IPv6 <multiple-reservations-same-ip6>`.
That's why this command comes in handy
when the ``ip-reservations-unique`` boolean parameter is set to ``false``.
- Other use case of this command is having overlapping subnets and having
- the same IP address reservation (but with different identifier) in different
+ Another use case of this command is having overlapping subnets with
+ the same IP address reservations (but with different identifiers) in different
subnets.
.. isccmd:: reservation-get-by-hostname
particularly when responses are not limited to a subnet.
The command accepts the ``operation-target`` argument. By default, it gets the
-reservation from both JSON configuration and the hosts database.
+reservation from both the JSON configuration and the hosts database.
.. code-block:: json
particularly when responses are not limited to a subnet.
The command accepts the ``operation-target`` argument. By default, it gets the
-reservation from both JSON configuration and the hosts database.
+reservation from both the JSON configuration and the hosts database.
.. code-block:: json
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:isccmd:`reservation-update` allows for the update of an existing host. It takes the
-same set of arguments as :isccmd:`reservation-add`, and just as well,
+same set of arguments as :isccmd:`reservation-add`, and also
requires a host identifier and a subnet ID to identify the host that is being
updated. The command can be as simple as having only the two mandatory entries:
}
In that case, however, it does not assign any resources to the host. An IPv4
-address can be assigned like so:
+address can be assigned as in this example:
.. code-block:: json
}
}
-It can also take many more parameters, for example:
+It can also take many more parameters, such as:
.. code-block:: json
}
The command returns a status that indicates either success (result ``0``) or
-failure (result ``1``) and a text parameter that confirms success or explains
+failure (result ``1``), and a text parameter that confirms success or explains
the cause of the failure. Here's an example of a successful update:
.. code-block:: json
As with other update and set commands, this command overwrites all the contents
of the entry. If the host previously had a resource assigned to it, and the
:isccmd:`reservation-update` command is missing the resource, it is deleted from the
-database. If an incremental update of the host is desired, then this can be
-achieved by doing a :isccmd:`reservation-get-by-id` to get the current state of the
-host, picking the host out of the response, modifying it to the required
+database. If an incremental update of the host is desired, this can be
+achieved by issuing a :isccmd:`reservation-get-by-id` to get the current state of the
+host, selecting the host from the response, modifying it to the required
outcome, and then issuing the :isccmd:`reservation-update` command with the resulting
host attached.
.. note::
- The host cache and RADIUS hook libraries are two host backends that do not
+ The host backends for the host cache and RADIUS hook libraries do not
respond to commands that return a collection of host reservations, such as
:isccmd:`reservation-get-all`. Commands returning one host entry or dedicated host
cache commands should be used instead.
entry. If the lease previously had a resource assigned to it, and the
:isccmd:`lease4-update` / :isccmd:`lease6-update` command is missing the resource, it is
deleted from the lease database. If an incremental update of the lease is
-desired, then this can be achieved by doing a :isccmd:`lease4-get` / :isccmd:`lease6-get`
-command to get the current state of the lease, picking the lease out of the
+desired, then this can be achieved by issuing a :isccmd:`lease4-get` / :isccmd:`lease6-get`
+command to get the current state of the lease, selecting the lease from the
response, modifying it to the required outcome, and then issuing the
:isccmd:`lease4-update` / :isccmd:`lease6-update` command with the resulting lease attached.
of the file as the ``filename`` argument. If the specified output file
is the same as the configured memfile one, the backend closes and reopens
the file in an attempt to synchronize both the files and the in-memory images
-of the lease database. The extension ``.bak`` with server PID number is added
-to the previous filename. For example ``.bak14326``.
+of the lease database. The extension ``.bak`` and the server PID number are added
+to the previous filename: for example, ``.bak14326``.
.. note::
`RFC 5007, Section 3.3 <https://tools.ietf.org/html/rfc5007#section-3.3>`__
states that querying by IP address should return either a lease (e.g.
binding) for the address itself or a lease for a delegated prefix that
- contains the address. The latter case is not supported by releases
- prior to Kea 2.3.7.
+ contains the address.
``DHCPV6_LEASEQUERY`` queries are only honored if the source address of
the query matches an entry in a list of known IP addresses which are
+------------------------------+-------+-----------------------------------------------+
If the lease with the most recent client-last-transaction-time (CLTT)
-value has relay information in its user-context (see
+value has relay information in its user context (see
:ref:`store-extended-info-v6`), then an ``OPTION_LQ_RELAY_DATA`` option is
added to the reply (see
`RFC 5007, Section 4.1.2.4 <https://tools.ietf.org/html/rfc5007#section-4.1.2.4>`__).
When a query by IP address does not match an existing address lease,
a search for a matching delegated prefix is conducted. This is carried
-out by iterating over a list of prefix lengths, in descending order,
-extracting a prefix of that length from the query address and searching
+out by iterating over a list of prefix lengths in descending order,
+extracting a prefix of that length from the query address, and searching
for a delegation matching the resulting prefix. This continues for each
length in the list until a match is found or the list is exhausted.
By default, the list of prefix lengths to use in the search is determined
-dynamically after (re)configuration events. This resulting list will
-contain unique values of ``delegated-len`` gleaned from the currently
+dynamically after (re)configuration events. The resulting list
+contains unique values of ``delegated-len``, gleaned from the currently
configured set of PD pools.
-There is an optional parameter, ``prefix-lengths``, shown above which
+There is an optional parameter, ``prefix-lengths``, which
provides the ability to explicitly configure the list rather than having
it be determined dynamically. This provides tighter control over which
-prefix lengths are searched. In the above example, the prefix length
-search will be restricted to single pass, using a length of 72, regardless
-of whether or not there are pools using other values for ``delegated-len``.
+prefix lengths are searched. In the above example, the prefix-length
+search is restricted to a single pass, using a length of 72, regardless
+of whether there are pools using other values for ``delegated-len``.
Specifying an empty list, as shown below:
::
- query-start-time (154)
- This query option specifies a start query time; replies will only
+ This query option specifies a start-query time; replies will only
contain leases that are older than this value.
- query-end-time (155)
- This query option specifies an end query time; replies will only
+ This query option specifies an end-query time; replies will only
contain leases that are newer than this value.
- dhcp-state (156)
Bulk Leasequery Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Bulk Leasequery configuration is done via a new map parameter, ``advanced``,
+Bulk Leasequery configuration is specified via a new map parameter, ``advanced``,
with these possible entries:
- ``bulk-query-enabled``
When ``true``, Kea accepts connections from IP addresses in the requesters
- list and processes received Bulk Leasequeries. The default is ``false``.
+ list and processes received bulk leasequeries. The default is ``false``.
- ``active-query-enabled``
- ``lease-query-ip``
This is the IP address upon which to listen for connections. The address must be
- of the same family as the server, e.g. IPv6 for DHCPv6 server.
+ of the same family as the server, e.g. IPv6 for the DHCPv6 server.
- ``lease-query-port``
This is the port upon which to listen. The default is 67 for IPv4 and 547 for IPv6,
- i.e. the same value as for the UDP DHCP service but for TCP.
+ i.e. the same value as for the UDP DHCP service, but for TCP.
- ``max-bulk-query-threads``
- This indicates the maximum number of threads that Bulk Leasequery processing
+ This indicates the maximum number of threads that bulk leasequery processing
should use. A value of 0 instructs the server to use the same number of
threads that the Kea core is using for DHCP multi-threading.
The default is 0.
Updating Existing Leases in SQL Lease Backends
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Bulk Lease Query required additions to the lease data stored. With SQL lease
-backends, leases created prior to the server being configured for Bulk Lease
-Query will not contain the new data required. In order to populate this data
-it is necessary to run API commands:
+Bulk Leasequery requires additions to the lease data that is stored. With SQL lease
+backends, leases created prior to the server being configured for bulk lease
+query do not contain the new data required. In order to populate this data,
+it is necessary to run these API commands:
.. isccmd:: extended-info4-upgrade
.. _command-extended-info4-upgrade:
.. isccmd:: extended-info6-upgrade
.. _command-extended-info6-upgrade:
-for extended info used for by relay id and by remote id the command is:
+For extended info used by relay ID and by remote ID, the command is:
::
}
-In all cases the response will indicate whether it succeeded or failed
-and include either the count of leases updated or the nature of the failure:
+In all cases, the response indicates whether it succeeded or failed
+and includes either the count of leases updated or the nature of the failure:
::
This ``extended-info6-upgrade`` command must be called when:
-- the database schema was upgraded from a previous version
+- the database schema was upgraded from a previous version.
-- Bulk Lease Query was not enabled (tables are maintained only when v6 BLQ is
- enabled)
+- Bulk Leasequery was not enabled; tables are maintained only when v6 BLQ is
+ enabled.
-- data in tables do not seem to be consistent (tables are not maintained in
- an atomic way so consistency is not guaranteed. For instance when a database
- is shared between several servers races can happen between updates)
+- data in tables does not seem to be consistent; tables are not maintained in
+ an atomic way, so consistency is not guaranteed. For instance, when a database
+ is shared between several servers, races can happen between updates.
-The operation of extended info command is governed by ``extended-info-checks``
-parameter under the sanity-checks element. Please see :ref:`sanity-checks4`
+The operation of the extended info command is governed by the ``extended-info-checks``
+parameter, under the ``sanity-checks`` element. Please see :ref:`sanity-checks4`
or :ref:`sanity-checks6`.
-For large numbers of leases this command may take some time to complete.
+For large numbers of leases, this command may take some time to complete.
.. note::
Existing leases must have been created by Kea with ``store-extended-info``
- enabled in order for the new data from extended info to be extracted
+ enabled, in order for the new data from extended info to be extracted
and stored.
2018-01-06 01:02:12 CET Administrator deleted a lease for a device identified by: hw-address of 1a:1b:1c:1d:1e:1f
-If High availability module is enabled, the partner will periodically send lease
-commands which have a similar format, the only difference is that the issuer of
-the command is 'HA partner' instead of 'Administrator'.
+If the High Availability hook library is enabled, the partner periodically sends lease
+commands in a similar format; the only difference is that the issuer of
+the command is "HA partner" instead of "Administrator."
::
2018-01-06 01:02:11 PST Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e:1f:20:21:22:23:24
-If High availability module is enabled, the partner will periodically send lease
-commands which have a similar format, the only difference is that the issuer of
-the command is 'HA partner' instead of 'Administrator'.
+If the High Availability hook library is enabled, the partner periodically sends lease
+commands in a similar format; the only difference is that the issuer of
+the command is "HA partner" instead of "Administrator."
::
(the default). A fatal error is logged and the server exits, based on the idea
that the configuration should be valid at startup. Exiting to the operating
system allows nanny scripts to detect the problem.
-If ``retry-on-startup`` is set to ``true``, the server will start reconnection
-attempts even at server startup or on reconfigure events, and will honor the
+If ``retry-on-startup`` is set to ``true``, the server starts reconnection
+attempts even at server startup or on reconfigure events, and honors the
action specified in the ``on-fail`` parameter.
.. note::
- Database connection retries are not attempted on startup if the
- :ischooklib:`libdhcp_limits.so` is loaded because the hook library requires a
- valid connection to the database to check if JSON format is supported and to
+ If :ischooklib:`libdhcp_limits.so` is loaded, database connection retries are not attempted
+ on startup. The hook library requires a
+ valid connection to the database to check whether JSON format is supported and to
recount class limits.
.. _hooks-limits-lease-limiting:
.. ischooklib:: libdhcp_perfmon.so
.. _hooks-perfmon:
-``libdhcp_perfmon.so``: PerfMon
-===============================
+``libdhcp_perfmon.so``: Performance Monitoring
+==============================================
-This hook library can be loaded by either kea-dhcp4 or kea-dhcp6 servers
-to extend them with the ability to track and report performance related data.
+The Performance Monitoring (perfmon) hook library gives the Kea DHCPv4 and DHCPv6 server
+the ability to track and report performance-related data.
.. note::
This library is experimental and not recommended for use in production
environments.
+.. note::
+
+ :ischooklib:`libdhcp_perfmon.so` is part of the open source code and is
+ available to every Kea user.
+
Overview
~~~~~~~~
-The library, added in Kea 2.5.6, can be loaded by the :iscman:`kea-dhcp4` or
+The perfmon library, added in Kea 2.5.6, can be loaded by the :iscman:`kea-dhcp4` or
:iscman:`kea-dhcp6` daemon by adding it to the ``hooks-libraries`` element of
the server's configuration:
...
}
-It tracks the life cycle of client query packets as they are processed by Kea,
-beginning with when the query was received by the kernel to when the response
-is ready to be sent. This tracking is driven by a packet event stack which
+The library tracks the lifecycle of client query packets as they are processed by Kea,
+from when the query was received by the kernel to when the response
+is ready to be sent. This tracking is driven by a packet event stack, which
contains a list of event/timestamp pairs for significant milestones that
-occur during the processing of a client query. The list of possible events is
+occur during the processing of a client query. The list of possible events is
shown below:
-#. socket_received - Kernel placed the client query into the socket buffer
-#. buffer_read - Server read the client query from the socket buffer
-#. mt_queued - Server placed the client query into its thread-pool work queue (MT mode only)
-#. process_started - Server has begun processing the query
-#. process_completed - Server has constructed the response and is ready to send it
+#. socket_received - kernel placed the client query into the socket buffer
+#. buffer_read - server read the client query from the socket buffer
+#. mt_queued - server placed the client query into its thread-pool work queue (multi-threaded mode only)
+#. process_started - server has begun processing the query
+#. process_completed - server has constructed the response and is ready to send it
-This list is likely to expand over time. It will also be possible for hook developers
-to add their own events. This will be detailed in a future release.
+This list is likely to expand over time; it will also be possible for hook developers
+to add their own events. This will be detailed in future releases.
Passive Event Logging
~~~~~~~~~~~~~~~~~~~~~
-As long as the PerfMon hook library is loaded it will log the packet event stack
-contents for each client query which generates a response packet. The log entry
-will contain client query identifiers followed the list of event/timestamp pairs
-as they occurred in the order they occurred.
+When the perfmon hook library is loaded, it logs the packet event stack
+contents for each client query that generates a response packet. The log entry
+contains client query identifiers, followed by the list of event/timestamp pairs
+in the order that they occurred.
-For :iscman:`kea-dhcp4` the log is identified by the label, ``PERFMON_DHCP4_PKT_EVENTS``,
+For :iscman:`kea-dhcp4`, the log is identified by the label ``PERFMON_DHCP4_PKT_EVENTS``,
and emitted at logger debug level 50 or higher. For a DHCPDISCOVER it is emitted
-once the DHCPOFFER is ready to send and will look similar to the following (see
+once the DHCPOFFER is ready to send, and looks similar to the following (see
the second entry)::
2024-03-20 10:52:20.069 INFO [kea-dhcp4.leases/50033.140261252249344] DHCP4_LEASE_OFFER [hwtype=1 08:00:27:25:d3:f4], cid=[no info], tid=0xc288f9: lease 178.16.2.0 will be offered
..
-For :iscman:`kea-dhcp6` the log is identified by the label, ``PERFMON_DHCP6_PKT_EVENTS``,
-and emitted only at logger debug level 50 or higher. For a DHCPV6_SOLICIT it is emitted
-once the DHCPV6_ADVERTISE is ready to send and will look similar to the following (see
+For :iscman:`kea-dhcp6`, the log is identified by the label ``PERFMON_DHCP6_PKT_EVENTS``,
+and emitted at logger debug level 50 or higher. For a DHCPV6_SOLICIT it is emitted
+once the DHCPV6_ADVERTISE is ready to send, and looks similar to the following (see
the second entry)::
2024-03-20 10:22:14.030 INFO [kea-dhcp6.leases/47195.139913679886272] DHCP6_LEASE_ADVERT duid=[00:03:00:01:08:00:27:25:d3:f4], [no hwaddr info], tid=0xb54806: lease for address 3002:: and iaid=11189196 will be advertised
Duration Monitoring
~~~~~~~~~~~~~~~~~~~
-When monitoring is enabled, stack event data will be aggregated over a specified interval. These
-aggregates are referred to as monitored durations or simply durations for ease. Durations are
+When monitoring is enabled, stack event data is aggregated over a specified interval. These
+aggregates are referred to as "monitored durations" or simply "durations" for ease. Durations are
uniquely identified by a "duration key" which consists of the following values:
-* query message type - Message type of the client query (e.g.DHCPDISCOVER, DHCPV6_REQUEST)
-* response message type - Message type of the server response (e.g. DHCPOFFER, DHCPV6_REPLY)
-* start event label - Event that defines the beginning of the task (e.g. socket_received, process_started)
-* stop event label - Event that defines the end of the task (e.g. buffer_read, process_completed)
+* query message type - message type of the client query (e.g.DHCPDISCOVER, DHCPV6_REQUEST)
+* response message type - message type of the server response (e.g. DHCPOFFER, DHCPV6_REPLY)
+* start event label - event that defines the beginning of the task (e.g. socket_received, process_started)
+* stop event label - event that defines the end of the task (e.g. buffer_read, process_completed)
* subnet id - subnet selected during message processing (or 0 for global durations)
Once the server has finished constructing a response to a query, the query's event stack
-is processed into a series of updates to monitored durations. If upon updating, a
+is processed into a series of updates to monitored durations. If, upon updating, a
duration's sample interval is found to have been completed, it is sent to reporting
-and a new sample interval is begun. The interval width is dictacted by configuration
+and a new sample interval is begun. The interval width is dictated by configuration
parameter ``interval-width-secs``.
The event stack for the multi-threaded mode DHCPDISCOVER/DHCPOFFER cycle shown above
| 2024-Mar-20 14:52:20.069614 | process_completed |
+-----------------------------+--------------------+
-Assuming the selected subnet's ID was 100, the duration updates formed by PerfMon
+Assuming the selected subnet's ID was 100, the duration updates created by perfmon
from these events are shown below:
+--------------------------------------------------------------+--------------+
Notice that in addition to the adjacent event updates, there is an additional duration
update for the total duration of the entire stack whose key contains the event-pair
-``composite-total_response``. This tracks the total time to responds from query
-received until the response is ready to send. Finally, there would also be global
+``composite-total_response``. This tracks the total time to respond from when the query
+is received until the response is ready to send. Finally, there are also global
duration updates for each of the above:
+--------------------------------------------------------------+--------------+
Statistics Reporting
~~~~~~~~~~~~~~~~~~~~
-When enabled (see ``stats-mgr-reporting``), PerfMon will report a duration's data
-each time the duration completes a sampling interval. Each statistic employs the
-following naming convention:
+When enabled, perfmon reports a duration's data each time the duration completes a
+sampling interval (see ``stats-mgr-reporting`` under :ref:`perfmon-configuration`). Each
+statistic employs the following naming convention:
::
{subnet-id[x]}.perfmon.<query type>-<response type>.<start event>-<end event>.<value-name>
-And there will be both a global and a subnet-specific value for each. Currently the only
-value reported for a given duration key is "average-ms". This statistic is the average time
-between the duration's event pair over the most recently completed interval. In other
-words if during a given interval there were 7 occurrences (i.e. updates) totaling
-350ms, the the average-ms reported would be 50ms. Continuing with example above, the
-statistics reported would be named as follows for subnet level values:
+There is both a global and a subnet-specific value for each. Currently, the only
+value reported for a given duration key is ``average-ms``; this statistic is the average time
+between the duration's event pair over the most recently completed interval. In other
+words, if during a given interval there were seven occurrences (i.e. updates) totaling
+350ms, the ``average-ms`` reported would be 50ms. Continuing with the example above, the
+statistics reported are named as follows for the subnet-level values:
::
perfmon.DHCPDISCOVER.DHCPOFFER.process_started-process_completed.average-ms
perfmon.DHCPDISCOVER.DHCPOFFER.composite-total_response.average-ms
-Since they are reported to StatsMgr they may be fetched using the commands :isccmd:`statistic-get-all`
-or :isccmd:`statistic-get`.
+The results are reported to StatsMgr, an internal Kea component that reports data as statistics
+that can be retrieved using statistics commands. They can be fetched using the commands
+:isccmd:`statistic-get-all` or :isccmd:`statistic-get`.
Alarms
~~~~~~
Alarms may be defined to watch specific durations. Each alarm defines a high-water mark,
-``high-water-ms`` and a low-water mark, ``low-water-ms``. When the reported average value
-for duration exceeds the high-water mark, a WARN level alarm log will be emitted at which
-point the alarm is considered "triggered". Once triggered the WARN level log will be
-repeated at a specified alarm report interval, ``alarm-report-secs`` as long the reported
+``high-water-ms``, and a low-water mark, ``low-water-ms``. If the reported average value
+for the duration exceeds the high-water mark a WARN level alarm log is emitted, at which
+point the alarm is considered "triggered." Once triggered, the WARN level log is
+repeated at the alarm report interval specified by ``alarm-report-secs``, as long as the reported
average for the duration remains above the low-water mark. Once the average falls below the
-low-water mark the alarm is "cleared" and an INFO level log will be emitted.
+low-water mark the alarm is cleared and an INFO level log is emitted.
-The alarm triggered WARN log will look similar to the following:
+The alarm-triggered WARN log looks similar to the following:
::
2024-03-20 10:22:14.030 WARN [kea-dhcp6.leases/47195.139913679886272] PERFMON_ALARM_TRIGGERED Alarm for DHCPDISCOVER.DHCPOFFER.composite-total_response.0 has been triggered since 2024-03-20 10:18:20.070000, reported average duration 00:00:00.700000 exceeds high-water-ms: 500
-and the alarm cleared INFO log will look similar to the following:
+The alarm-cleared INFO log looks like this:
::
Commands to enable or disable monitoring, clear or alter alarms, and fetch duration data
are anticipated but not yet supported.
+.. _perfmon-configuration:
+
Configuration
~~~~~~~~~~~~~
-An example of the anticipated configuration is shown below:
+Use of the performance monitoring hook library is configured via several parameters:
+
+* enable-monitoring
+ This parameter enables event data aggregation for reporting, statistics, and alarms. It defaults to ``false``.
+* interval-width-secs
+ This specifies the amount of time, in seconds, that individual task durations are accumulated into an
+ aggregate before they are reported. The default is 60 seconds.
+* stats-mgr-reporting
+ This enables the reporting of aggregates to StatsMgr. It defaults to ``true``.
+* alarm-report-secs
+ This specifies the amount of time, in seconds, between logging instances for an alarm once it has been triggered.
+ It defaults to 300 seconds.
+* alarms
+ This is an optional list of alarms that monitor specific duration aggregates. Each alarm is
+ defined by these four parameters:
+
+ * duration-key
+ Identifies the monitored duration for the following:
+
+ * query-type - message type of the client query (e.g.DHCPDISCOVER, DHCPV6_REQUEST)
+ * response-type - message type of the server response (e.g. DHCPOFFER, DHCPV6_REPLY)
+ * start-event - event that defines the beginning of the task (e.g. socket_received, process_started)
+ * stop-event - event that defines the end of the task
+ * subnet-id - subnet selected during message processing (or 0 for global durations)
+
+ * enable-alarm
+ Enables or disables this alarm; defaults to ``true``.
+
+ * high-water-ms
+ Specifies the value, in milliseconds, over which the duration must occur to trigger this alarm;
+ must be greater than zero.
+
+ * low-water-ms
+ Specifies the value, in milliseconds, under which the duration must fall to clear this alarm;
+ must be greater than zero but less than ``high-water-ms``.
+
+.. note::
+ Passive event logging is always enabled, even without specifying the "parameters" section.
+
+A sample configuration is shown below:
.. code-block:: javascript
}
}]
}
-
-Where:
-
-* enable-monitoring
- Enables event data aggregation for reporting, statistics, and alarms. Defaults to false.
-* interval-width-secs
- The amount of time, in seconds, that individual task durations are accumulated into an
- aggregate before it is reported. Default is 60 seconds.
-* stats-mgr-reporting
- Enables reporting aggregates to StatsMgr. Defaults to true.
-* alarm-report-secs
- The amount of time, in seconds, between logging for an alarm once it has been triggered.
- Defaults to 300 seconds.
-* alarms
- A optional list of alarms that monitor specific duration aggregates. Each alarm is
- defined by the following:
-
- * duration-key
- Identifies the monitored duration to watch
-
- * query-type - Message type of the client query (e.g.DHCPDISCOVER, DHCPV6_REQUEST)
- * response-type - Message type of the server response (e.g. DHCPOFFER, DHCPV6_REPLY)
- * start-event - Event that defines the beginning of the task (e.g. socket_received, process_started)
- * stop-event - Event that defines the end of the task
- * subnet-id - subnet selected during message processing (or 0 for global durations)
-
- * enable-alarm
- Enables or disables this alarm. Defaults to true.
-
- * high-water-ms
- The value, in milliseconds, that must be exceeded to trigger this alarm.
- Must be greater than zero.
-
- * low-water-ms
- The value, in milliseconds, that must be subceeded to clear this alarm
- Must be greater than zero but less than high-water-ms.
-
-.. note::
- Passive event logging is always enabled, even without specifying the 'parameters' section.
-
This hook library adds the ability to perform a "ping check" of a candidate
IPv4 address prior to offering it to a DHCP client. This feature is similar
to a behavior available in ISC DHCP and one suggested in `RFC
-2131 <https://tools.ietf.org/html/rfc2131>`__ , see section 3.1, item 2.
+2131 <https://tools.ietf.org/html/rfc2131>`__, section 3.1, item 2.
+
+.. note::
+
+ This library is experimental and not recommended for use in production
+ environments.
.. note::
Overview
~~~~~~~~
-The library, added in Kea 2.5.4, can be loaded by the :iscman:`kea-dhcp4` daemon
+The Ping Check library, added in Kea 2.5.4, can be loaded by the :iscman:`kea-dhcp4` daemon
by adding it to the ``hooks-libraries`` element of the server's configuration:
.. code-block:: javascript
...
}
-When the library is loaded :iscman:`kea-dhcp4` will conduct a ping-check prior to
-offering a lease to client if all of the following conditions are true:
+When the library is loaded, :iscman:`kea-dhcp4` conducts a ping check prior to
+offering a lease to a client if all of the following conditions are true:
-1. Ping check hook library is loaded.
+1. The ping check hook library is loaded.
2. Ping checking is enabled.
a. This is the first offer of this lease to this client. This check
can only be done if ``offer-lifetime`` is greater than zero (i.e. temporary
allocation on DHCPDISCOVER is enabled). If ``offer-lifetime`` is zero
- ping checks are done for every DHCPOFFER as the server has no way to
- know it has made prior offers.
+ ping checks are done for every DHCPOFFER, as the server has no way to
+ know whether prior offers were made.
b. The lease is being offered to a client other than its previous owner.
- c. The lease is being offered to its previous owner and more than a
- configurable number of seconds, ``ping-cltt-secs``, have elapsed since
+ c. The lease is being offered to its previous owner and more than the
+ number of seconds specified by ``ping-cltt-secs`` have elapsed since the
CLTT of the original lease.
-When the ping check library is loaded, in response to a DHCPDISCOVER the
-:iscman:`kea-dhcp4` will:
+When the ping check library is loaded, the :iscman:`kea-dhcp4` server
+responds to a DHCPDISCOVER by:
-1. Select a candidate IPv4 address through normal processes and use it to
+1. Selecting a candidate IPv4 address through normal processes and using it to
construct a DHCPOFFER.
-2. Park the DHCPOFFER and request a ping-check from the ping-check hook
-library via its ``lease4_offer`` callout. Refer to :ref:`parked-packet-limit` for
+2. Parking the DHCPOFFER and requesting a ping check from the ping check hook
+library, via its ``lease4_offer`` callout. Refer to :ref:`parked-packet-limit` for
a basic introduction to packet parking.
-3. The callout will test conditions described above. If they are not
-satisfied it will return without conducting a check, and the server
-will send the DHCPOFFER to the client. Otherwise the callout will
-initiate a ping-check for the lease address.
+3. Testing the callout conditions described above: if they are not
+satisfied, it returns without conducting a check, and the server
+sends the DHCPOFFER to the client. Otherwise, the callout
+initiates a ping check for the lease address.
-4. Upon conclusion of the ping-check, the server will either send the DHCPOFFER
-to the client if the check concluded that the address is available, or discard
-the DHCPFOFFER and create a DECLINED lease for the address.
+4. Upon conclusion of the ping check, the server either sends the DHCPOFFER
+to the client, if the check concluded that the address is available, or discards
+the DHCPFOFFER and creates a DECLINED lease for the address.
-Each ping-check consists of the following steps:
+Each ping check consists of the following steps:
1. If the number of ECHO REPLYs sent is less than the configured
minimum number to send, send an ICMP ECHO REQUEST to the lease address.
Otherwise, conclude that the address is available.
-2. If no ECHO REPLY is received within a configurable amount of time
+2. If no ECHO REPLY is received within a configurable amount of time,
return to step 1.
3. Upon receipt of an ICMP ECHO REPLY, conclude that the lease is NOT available.
-4. Any of the following occur:
+4. If any of the following occur:
a. Receipt of an ICMP DESTINATION UNREACHABLE message
- b. Send fail of an ICMP ECHO REQUEST due to a network error (e.g. network is unreachable)
- c. Send fail of an ICMP ECHO REQUEST due to a permissions error (e.g. lease address is a broadcast address)
- d. Send fail of an ICMP ECHO REQUEST with socket buffer full error
+ b. Send failure of an ICMP ECHO REQUEST due to a network error (e.g. network is unreachable)
+ c. Send failure of an ICMP ECHO REQUEST due to a permissions error (e.g. lease address is a broadcast address)
+ d. Send failure of an ICMP ECHO REQUEST with socket buffer full error
- In each of these instances the address could not be checked and is treated as
- available.
+ skip the address check and treat it as available.
.. note::
- Socket buffer full of errors indicates that the OS rate limits on ICMP are
- being exceeded. The server will not retry them as this would likely only
- exacerbate the situation. If this occurs continuously then the client load
+ "Socket buffer full" errors indicate that the OS rate limits on ICMP are
+ being exceeded. The server does not retry them, as this would likely only
+ exacerbate the situation. If this occurs continuously, then the client load
on the server may be too high to accommodate ping checking. Ping checking is
not recommended for systems with high throughput demands.
Configuration
~~~~~~~~~~~~~
-The ping-check hook library currently supports the following configuration parameters
-that may be set at the global and subnet levels. Subnet values override global values.
+The ping check hook library currently supports the following configuration parameters
+that may be set at the global and subnet levels; subnet values override global values:
-- ``enable-ping-check`` - Enables or disables ping checking at a given scope.
+- ``enable-ping-check`` - This parameter enables or disables ping checking at a given scope.
-- ``min-ping-requests`` - The minimum number of ECHO REQUESTs sent without receiving a reply needed to declare an address available. The default is 1, it must be greater than zero.
+- ``min-ping-requests`` - This is the minimum number of ECHO REQUESTs sent without receiving a reply, before an address is declared available. The default is 1; it must be greater than zero.
-- ``reply-timeout`` - The maximum amount of time to wait for a reply to a single ECHO REQUEST. Specified in milliseconds, it must be greater than zero, it defaults to 100.
+- ``reply-timeout`` - This is the maximum amount of time to wait for a reply to a single ECHO REQUEST. Specified in milliseconds, it must be greater than zero; the default is 100.
-- ``ping-cltt-secs`` - The number of seconds that must elapse after the lease's CLTT before a ping check will be conducted when the client is the lease's previous owner. The default value is sixty seconds.
+- ``ping-cltt-secs`` - This specifies the number of seconds that must elapse after the lease's CLTT before a ping check is conducted, when the client is the lease's previous owner. The default value is 60 seconds.
The following parameter is only supported at the global level:
-- ``ping-channel-threads`` - In multi-threaded mode, this is the number of threads in the channel's thread pool. The default is 0 which instructs the library to use the same number of threads as Kea core. The value is ignored if given when Kea is in single-threaded mode.
+- ``ping-channel-threads`` - In multi-threaded mode, this is the number of threads in the channel's thread pool. The default is 0, which instructs the library to use the same number of threads as the Kea core. This value is ignored if given when Kea is in single-threaded mode.
-The following configuration excerpt illustrates global level configuration:
+The following configuration excerpt illustrates a global-level configuration:
.. code-block:: javascript
}]
}
-The following excerpt demonstrates subnet level configuration:
+The following excerpt demonstrates a subnet-level configuration:
.. code-block:: javascript
}
}]
}
-
-.. note::
-
- Ping checking is an experimental feature. It is not currently recommended for
- production environments.
============================================
This hook library allows the Kea DHCP servers to use the RADIUS protocol to
-authorize DHCP clients through the access service or for DHCP lease journaling
+authorize DHCP clients through the access service, or for DHCP lease journaling
through the accounting service. For details on RADIUS in Kea, please see
:ref:`radius`.
.. note::
- The role assignment may fail, for instance with ``cert-subject`` when
+ The role assignment may fail with ``cert-subject`` when
the client certificate was not required, or it may have no subject common
name and instead have a DNS alternative subject name. In this case, the role
assignment returns the empty role and the ``default-role`` entry is used.
:ischooklib:`libdhcp_run_script.so` is part of the open source code and is
available to every Kea user.
-The library, which was added in Kea 1.9.5, can be loaded in a
-similar way to other hook libraries by the :iscman:`kea-dhcp4` and
-:iscman:`kea-dhcp6` processes.
+.. note::
+
+ This library can only be loaded by the :iscman:`kea-dhcp4` or
+ :iscman:`kea-dhcp6` process.
.. code-block:: json
}
}
-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
+As of Kea 2.6.0, Kea no longer automatically generates subnet IDS; they must
+be specified for :isccmd:`subnet4-add` and :isccmd:`subnet6-add`. If not
+specified, Kea tries to assign the next ``subnet-id`` value. This
automatic ID value generator is simple; it returns the previous
automatically assigned value, increased by 1. This works well, unless
a subnet is manually created with a larger value than one previously used. For
example, if :isccmd:`subnet4-add` is called five times, each without an ID, Kea will
-assign IDs 1, 2, 3, 4, and 5 and it will work just fine. However, if
+assign IDs 1, 2, 3, 4, and 5 and everything will work properly. However, if
:isccmd:`subnet4-add` is called five times, with the first subnet having the
``subnet-id`` of value 3 and the remaining ones having no ``subnet-id``, the operation will
fail. The first command (with the explicit value) will use ``subnet-id`` 3; the
-second command will create a subnet with and ID of 1; the third will use a
+second command will create a subnet with an ID of 1; the third will use a
value of 2; and finally the fourth will have its ``subnet-id`` value
auto-generated as 3. However, since there is already a subnet with that
ID, the process will fail.
}
As with other update commands, this command overwrites all the contents of the
-entry. If the IPv4 subnet previously had a resource assigned to it, and the
+entry. If the IPv4 subnet previously had a resource assigned to it and the
:isccmd:`subnet4-update` command is missing the resource, it is deleted from the
-server configuration. If an incremental update of the subnet is desired, then
-this can be achieved with :isccmd:`subnet4-delta-add`.
+server configuration. If an incremental update of the subnet is desired,
+use :isccmd:`subnet4-delta-add`.
.. isccmd:: subnet6-update
.. _command-subnet6-update:
}
As with other update commands, this command overwrites all the contents of the
-entry. If the IPv6 subnet previously had a resource assigned to it, and the
+entry. If the IPv6 subnet previously had a resource assigned to it and the
:isccmd:`subnet6-update` command is missing the resource, it is deleted from the
-server configuration. If an incremental update of the subnet is desired, then
-this can be achieved with :isccmd:`subnet6-delta-add`.
+server configuration. If an incremental update of the subnet is desired,
+use :isccmd:`subnet6-delta-add`.
.. isccmd:: subnet4-del
.. _command-subnet4-del:
}
}
-Assuming there was such a network configured, the response will look
+Assuming such a network was configured, the response looks
similar to the following:
::
There is one case where this is not true: if Kea is running with a
configuration that contains a ``hooks-libraries`` item, and that
- item is removed and the configuration reloaded, the removal will
- be ignored and the libraries remain loaded. As a workaround,
+ item is removed and the configuration reloaded, the removal is
+ ignored and the libraries remain loaded. As a workaround,
instead of removing the ``hooks-libraries`` item, change it to an
empty list.
It is important to recognize that the order in which hook libraries are
configured determines the order in which their callouts will be executed,
-in cases where more than one hook library implements the same callout. For
-example, if you wish to use the flex-id hook library to formulate the client
-IDs in conjunction with HA hook library for load-balanced HA, it is essential
-that the flex-id library be specified first in your server's ``hooks-libraries``
-section. This ensures that the client ID is formulated by the flex-id library
-before the HA library uses it for load-balancing. Similarly it would be best to
-specify forensic logging last, to ensure any other install hooks have made
-their contributions to the packet processing.
+in cases where more than one hook library implements the same callout. For
+example, to use the Flexible Identifier (also called Flex ID) hook library to formulate the client
+IDs in conjunction with the High Availability (HA) hook library for load-balanced HA, it is essential
+that the Flex ID library be specified first in the server's ``hooks-libraries``
+section. This ensures that the client ID is formulated by the Flex ID library
+before the HA library uses it for load-balancing. Similarly, it is best to
+specify the Forensic Logging library last, to ensure that any other installed hooks have already made
+their contributions to the packet processing before that one is loaded.
.. _user-context-hooks:
Some hooks use user context for a configuration that can be easily edited
without the need to restart the server.
-The DDNS-Tuning Hook uses user-context to configure per subnet behavior. Example:
+The DDNS Tuning Hook uses user context to configure per-subnet behavior. Here's an example:
::
~~~~~~~~~~~~~~~~~~~
Kea servers contain a mechanism by which the response to a client packet may
-be held, pending completion of hook library work. We refer to this as parking
-the packet. When work is ready to continue, the server will unpark the response
-and continue processing.
+be held, pending completion of hook library work. We refer to this as "parking
+the packet." When work is ready to continue, the server unparks the response
+and continues processing.
There is a global parameter, ``parked-packet-limit``, that may be used to limit
the number of responses that may be parked at any given time. This acts as a
parking spaces are available.
In general, smaller values for the parking lot limit are likely to cause more
-drops but with shorter response times. Larger values are likely to result in
+drops but with shorter response times; larger values are likely to result in
fewer drops but with longer response times. Currently, the default value for
``parked-packet-limit`` is 256.
recommend users initially leave it at the default value of 256 and observe
how the system behaves over time with varying load conditions.
-Here is an example of the global parameter used with ischooklib:`libdhcp_ha.so`.
+Here is an example of the global parameter used with :ischooklib:`libdhcp_ha.so`.
It lowers the number of concurrently parked packets to 128.
.. code-block:: json
.. note::
- Some of these libraries are available with the base code, while others are
- premium libraries available for purchase, or only shared with organizations
- who contribute to Kea's development through paid ISC support contracts. Paid support
+ Some of these libraries are available at no cost with the open source base code; others are
+ premium libraries available for standalone purchase, while some are only available to organizations
+ that contribute to Kea's development through paid ISC support contracts. Paid support
includes professional engineering assistance, advance security notifications, input
into ISC's roadmap planning, and many other benefits, while helping
keep Kea sustainable in the long term. ISC encourages companies and organizations
| | | a repository for the Kea configuration information. Kea |
| | | servers use this library to fetch their configurations. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
- | :ref:`PerfMon <hooks-perfmon>` | Kea open | With this hook library, :iscman:`kea-dhcp4` server and |
- | | source | :iscman:`kea-dhcp6` servers can track and report performance |
- | | | data. CURRENTLY UNDER DEVELOPMENT |
+ | :ref:`PerfMon <hooks-perfmon>` | Kea open | With this hook library, :iscman:`kea-dhcp4` and |
+ | CURRENTLY EXPERIMENTAL | source | :iscman:`kea-dhcp6` servers can track and report performance |
+ | | | data. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
- | :ref:`Ping Check <hooks-ping-check>` | ISC support | With this hook library, :iscman:`kea-dhcp4` server can |
- | | customers | perform ping checks of candidate lease addresses before |
- | | | offering them to clients. |
+ | :ref:`Ping Check <hooks-ping-check>` | ISC support | With this hook library, the :iscman:`kea-dhcp4` server can |
+ | | source | perform ping checks of candidate lease addresses before |
+ | | customers | offering them to clients. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`PostgreSQL Configuration Backend <hooks-cb-pgsql>` | Kea open | This hook library is an implementation of the Kea |
| | source | Configuration Backend for PostgreSQL. It uses a PostgreSQL |
Packages
========
-ISC publishes native RPM, deb, and APK packages, along with the tarballs
-with the source code. The packages are available on
-`Cloudsmith <https://cloudsmith.io/~isc/repos/>`_ at
-https://cloudsmith.io/~isc/repos. The native packages can be downloaded
+ISC publishes native RPM, deb, and APK packages, as well as tarballs
+with the source code. The packages are available in
+`ISC's Cloudsmith repositories <https://cloudsmith.io/~isc/repos>`_.
+The native packages can be downloaded
and installed using the system available in a specific distribution (such
as dpkg or rpm). The Kea repository can also be added to the system,
making it easier to install updates. For details, please
-go to https://cloudsmith.io/~isc/repos, choose the repository of
-interest, and then click the ``Set Me Up`` button. For detailed
-instructions or refer to ISC `KB article <https://kb.isc.org/docs/isc-kea-packages>`_.
+go to https://cloudsmith.io/~isc/repos, choose the desired Kea version,
+and then click the "Set Me Up" button. For detailed
+instructions, please refer to this `Knowledgebase article <https://kb.isc.org/docs/isc-kea-packages>`_.
Installation From Cloudsmith Packages
-------------------------------------
ISC provides Kea packages for Alpine, Debian, Fedora, RHEL, and Ubuntu.
-The recommended method for installing Kea on any of these systems, from the
-Cloudsmith repository for Kea release 2.3.1 or later, is to install the ``isc-kea``
-metapackage. This metapackage is included on all supported distros and
+The recommended method for installing Kea on any of these systems is to
+install the ``isc-kea`` metapackage from the Cloudsmith repository.
+This metapackage is included on all supported distros and
installs all of the services offered by the Kea software suite.
Specific Kea components
- ``isc-kea-hooks`` — Kea open source DHCP hooks
-Kea Premium hook packages are not included in the ``isc-kea-hooks`` package.
+Kea premium hook packages are not included in the ``isc-kea-hooks`` package.
For ISC customers with access to the premium hooks, those packages have the
-``isc-kea-premium-`` prefix.
+``isc-kea-premium-`` prefix. Users wishing to purchase the premium hooks
+can find them on ISC's website, at https://www.isc.org/shop/.
Once installed, the services can be managed through the distribution's
service manager. The services are named: :iscman:`kea-dhcp4`, :iscman:`kea-dhcp6`,
:iscman:`kea-dhcp-ddns`, and :iscman:`kea-ctrl-agent`.
.. note::
- The real service names on Debian and Ubuntu follow the names of the older
- packages, to maintain compatibility with pre-existing scripts. A
+ The real service names on Debian and Ubuntu use slightly different
+ package names, to maintain compatibility with some older scripts. A
systemd service alias is used to allow users to refer to them with shorter
names. Calling ``systemctl enable`` on these services requires
the real service names, which are: ``isc-kea-dhcp4-server``,
Caveats When Upgrading Kea Packages
-----------------------------------
-To upgrade to Kea 2.3.2 or later from an earlier version of Kea on Debian
+To upgrade to a current version of Kea from version 2.3.2 or earlier on Debian
and Ubuntu systems, run ``apt dist-upgrade`` instead of the usual ``apt upgrade``.
Once this upgrade has been completed, it is possible to upgrade to later versions
normally using ``apt upgrade`` on Debian and Ubuntu systems.
``apt install isc-kea`` after upgrading, which
will install all of the relevant subpackages that make up Kea.
-This upgrade path issue does not apply to RPM and Alpine systems; however,
-customers with ISC support contracts who experience difficulties with upgrading
-past 2.3.1 are invited to open a ticket in their support queue. Other users
-are encouraged to describe their situation on the kea-users mailing list for
-best-effort support from other list members.
+This upgrade path issue does not apply to RPM and Alpine systems.
+
+Customers with ISC support contracts who experience difficulties with upgrading
+are invited to open a ticket in their support queue. Other users
+are encouraged to describe their situation on the `kea-users mailing list <https://lists.isc.org/mailman/listinfo/kea-users>`_
+for best-effort support from other list members.
.. _install-hierarchy:
or on a machine reachable over a network is required. Note that running
the unit tests requires a local PostgreSQL server.
-- Sysrepo v1.4.140 and libyang v1.0.240 are needed to connect to a Sysrepo
+- Sysrepo v1.4.140 and libyang v1.0.240, needed to connect to a Sysrepo
datastore. Earlier versions are no longer supported. When compiling from
sources, the configure switches that can be used are ``--with-libyang`` and
``--with-sysrepo`` without any parameters. If these dependencies were
- The MIT Kerberos 5 or Heimdal libraries are needed by Kea DDNS server to sign
and verify DNS updates using GSS-TSIG. The configuration switch which enables
- this functionality is ``--with-gssapi`` without any parameters. If these
+ this functionality is ``--with-gssapi``, without any parameters. If these
dependencies were installed in custom paths, point the switch to them.
- googletest (version 1.8 or later) is required when using the ``--with-gtest``
The code checked out from the git repository does not include the
generated configure script or the Makefile.in files, nor their related build
-files. They can be created by running ``autoreconf`` with the
-``--install`` switch. This will run ``autoconf``, ``aclocal``,
+files. Those can be created by running ``autoreconf`` with the
+``--install`` switch, which will run ``autoconf``, ``aclocal``,
``libtoolize``, ``autoheader``, ``automake``, and related commands.
Write access to the Kea repository is only granted to ISC staff.
found, Kea searches for OpenSSL. Normally this is not necessary.
- ``--enable-shell``
- Build the optional :iscman:`kea-shell` tool (more in :ref:`kea-shell`).
+ Build the optional :iscman:`kea-shell` tool (see :ref:`kea-shell`).
The default is to not build it.
- ``--with-site-packages``
- Only useful when :iscman:`kea-shell` is enabled, this switch causes the kea-shell
- Python packages to be installed in the specified directory. This is
- mostly useful for Debian-related distributions. While most systems store
+ Install the kea-shell Python packages in the specified directory; this
+ is only useful when :iscman:`kea-shell` is enabled, and is
+ mostly helpful for Debian-related distributions. While most systems store
Python packages in ``${prefix}/usr/lib/pythonX/site-packages``, Debian
introduced a separate directory for packages installed from DEB. Such
Python packages are expected to be installed in
When ``configure`` succeeds, it displays a report with the parameters used
to build the code. This report is saved into the file ``config.report``
-and is also embedded into the executable binaries, e.g., :iscman:`kea-dhcp4`.
+and is also embedded into the executable binaries, e.g. :iscman:`kea-dhcp4`.
Build
-----
It is outside of the scope of common administrator operations and requires
some developer skills, but the Developer Guide explains how to do that
using an x86_64 Linux system to build Kea for a Raspberry Pi box running
-Raspbian: `Kea Cross-Compiling Example
+Raspbian: see this `Kea Cross-Compiling Example
<https://reports.kea.isc.org/dev_guide/de/d9a/crossCompile.html>`__.
.. _dhcp-install-configure:
Kea stores its leases in a lease database. The software has been written
in a way that makes it possible to choose which database product should
be used to store the lease information. Kea supports three
-database backends: MySQL, PostgreSQL and memfile. To limit external
+database backends: MySQL, PostgreSQL, and memfile. To limit external
dependencies, MySQL and PostgreSQL support are disabled by default and only
memfile is available. Support for the optional external database backend must
be explicitly included when Kea is built.
User=admin
Group=admin
-The most important step is to set the capabilities of the binaries. Refer to `man capabilities` to get
-more information.
+The most important step is to set the capabilities of the binaries. Refer to the operating system man page
+for `capabilities` for more information.
.. code-block:: console
===================
This section lists significant features that have been or will be removed. We try to
-deprecate features before removing them to signal
+deprecate features before removing them, to signal
to current users to plan a migration. New users should not rely on deprecated features.
Sysrepo 0.x or 1.x
Kea 2.3.2 introduced support for Sysrepo 2.x. Unfortunately,
Sysrepo continues to undergo major changes that are backward-incompatible,
-and Kea versions 2.3.2 do not support Sysrepo earlier than versions 2.x.
+and current Kea versions do not support Sysrepo earlier than versions 2.x.
:isccmd:`libreload` command
----------------------------------------
The :isccmd:`libreload` command was deprecated in Kea 2.3.4. The code to handle this command is
still there, but there are reports of it being buggy and not really usable.
-Kea 2.3 and 2.4 versions will produce a warning when this command
+Kea 2.3 and 2.4 versions produce a warning when this command
is used, and it will be removed entirely sometime in the 2.5 branch.
first entry (:iscman:`kea-dhcp4`). Messages generated by the ``dhcpsrv`` library
are logged according to the configuration set by the second entry.
-Currently defined loggers are listed in the following table. The
+The currently defined loggers are listed in the following table. The
"Software Package" column of this table specifies whether the particular
loggers belong to the core Kea code (open source Kea binaries and
libraries), or hook libraries (open source or premium).
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.auth`` | core | A logger which covers |
| | | access control details, such as|
- | | | a result of the basic HTTP |
+ | | | the result of basic HTTP |
| | | authentication. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.ctrl-agent`` | core | Used to log results of |
| | | configuration checks, |
| | | information about services |
| | | starting or failing to start, |
- | | | command receival and |
+ | | | command reception, and |
| | | forwarding. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.http`` | core | A logger which |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.callouts``, | core | Used to log messages |
| ``kea-dhcp4.callouts``, | | pertaining to the |
- | ``kea-dhcp6.callouts``, | | callouts registation and |
+ | ``kea-dhcp6.callouts``, | | callouts registration and |
| ``kea-dhcp-ddns.callouts`` | | execution for a particular |
| | | hook point. |
+----------------------------------+---------------------------------------+--------------------------------+
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.database``, | core | Used to log messages |
| ``kea-dhcp6.database`` | | relating to general |
- | | | operations on the |
+ | | | operations of the |
| | | relational databases. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.ddns-tuning-hooks``, | :ischooklib:`libdhcp_ddns_tuning.so` | Used to log messages related |
| | | library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.hooks``, | core | Used to log messages related |
- | ``kea-dhcp4.hooks``, | | to the maagemet of hook |
+ | ``kea-dhcp4.hooks``, | | to the management of hook |
| ``kea-dhcp6.hooks``, | | libraries, e.g. |
- | ``kea-dhcp-ddns.hooks`` | | registatin and |
+ | ``kea-dhcp-ddns.hooks`` | | registration and |
| | | deregistration of the |
| | | libraries, and to the |
| | | initialization of the |
| | | by the library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.hosts``, | core | Used within |
- | ``kea-dhcp6.hosts`` | | ``libdhcpsrv``, it logs |
+ | ``kea-dhcp6.hosts`` | | ``libdhcpsrv`` to log |
| | | messages related to |
| | | the management of |
| | | DHCP host |
| ``kea-dhcp4.packets``, | core | Mostly |
| ``kea-dhcp6.packets`` | | used to log messages |
| | | related to |
- | | | transmission of the |
+ | | | transmission of |
| | | DHCP packets, i.e. |
| | | packet reception and |
| | | the sending of a |
| | | the packet is parsed. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.perfmon-hooks``, | :ischooklib:`libdhcp_perfmon.so` | Used to log messages related |
- | ``kea-dhcp6.perfmon-hooks`` | open-source hook library | to performance monitoring. |
+ | ``kea-dhcp6.perfmon-hooks`` | open-source hook library | to the operation of the |
+ | | | Performance Monitoring hook |
+ | | | library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.ping-check-hooks`` | :ischooklib:`libdhcp_ping_check.so` | Used |
| | subscription hook library | to log messages related to |
- | | | carrying out pre-offer ping |
- | | | checks of candidate leases. |
+ | | | the operation of the Ping |
+ | | | Check hook library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.pgsql-cb-hooks``, | :ischooklib:`libdhcp_pgsql_cb.so` | Used |
| ``kea-dhcp6.pgsql-cb-hooks`` | open-source hook library | to log messages |
| ``kea-dhcp6.tcp`` | | to TCP traffic. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.user_chk``, | :ischooklib:`libdhcp_user_chk.so` | Used to log messages related |
- | ``kea-dhcp6.user_chk`` | hook library | to the operaton of the |
+ | ``kea-dhcp6.user_chk`` | hook library | to the operation of the |
| | | User Check hook library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp-ddns`` | core | The root logger for |
| | | more specialized |
| | | loggers. |
+----------------------------------+---------------------------------------+--------------------------------+
- | ``kea-ctrl-agent.dctl``, | core | Used to log basic inofrmaton |
+ | ``kea-ctrl-agent.dctl``, | core | Used to log basic information |
| ``kea-dhcp-ddns.dctl`` | | about the process, |
| | | received signals, and |
| | | triggered |
.. note::
- As of Kea 2.5.1, alias ``output-options`` was added that can be used
- interchangeably with previous ``output_options`` configuration key.
- The reason behind this was to keep all configuration keys consistent i.e.
- to use "dash" instead of "underscore" in the key name. For the time being
+ The alias ``output-options`` was added in Kea 2.5.1, to be used
+ interchangeably with the previous ``output_options`` configuration key.
+ This was done to keep all configuration keys consistent, i.e.
+ using a hyphen (`-`) instead of an underscore (`_`) in the key name. Currently,
both configuration keys are considered correct and mean the same to Kea parsers.
- As of Kea 2.5.2, the ``output-options`` becomes the default configuration key
+ As of Kea 2.5.2, ``output-options`` becomes the default configuration key
and ``output_options`` can be used as an alias.
The ``output`` (string) Option
This flushes the buffers after each log message. Doing this reduces performance
but ensures that if the program terminates abnormally, all messages
-up to the point of termination are output. The default is ``true``.
+up to the point of termination are recorded. The default is ``true``.
The ``maxsize`` (integer) Option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------+------------------------------------------------------------------------+
| ``%M`` | Outputs caller (function name) of the log message |
+-----------+------------------------------------------------------------------------+
- | ``%n`` | Outputs line separator suppored by platform e.g., ``\n`` in Linux |
+ | ``%n`` | Outputs line separator supported by platform e.g., ``\n`` in Linux |
+-----------+------------------------------------------------------------------------+
| ``%p`` | Outputs log severity e.g., INFO |
+-----------+------------------------------------------------------------------------+
| ``%r`` | Outputs milliseconds since program start e.g., 1235 |
+-----------+------------------------------------------------------------------------+
- | ``%t`` | Outputs thread id that generated the log message e.g., 281472855306256 |
+ | ``%t`` | Outputs thread ID that generated the log message e.g., 281472855306256 |
+-----------+------------------------------------------------------------------------+
| ``%T`` | Outputs thread name that generated the log message e.g., 168005 |
+-----------+------------------------------------------------------------------------+
- | ``%i`` | Outputs process id that generated the log message e.g., 168030 |
+ | ``%i`` | Outputs process ID that generated the log message e.g., 168030 |
+-----------+------------------------------------------------------------------------+
| ``%%`` | Outputs a literal percent sign |
+-----------+------------------------------------------------------------------------+
-Padding and truncation are also possible with modifiers preceeding the component. This is
+Padding and truncation are also possible with modifiers preceding the component; this is
done by placing a number and other modifier characters between the component and the %
-sign. There are five ways of modifying the output shown by example here.
+sign. There are five ways of modifying the output:
- ``%20p``
Left pads with spaces (align right) if the severity is shorter than 20 characters.
- ``%10.35E{PATH}``
Left pad with spaces (align right) if the environment variable "PATH" is shorter than
- 10 characters. If the content is longer than 35 characters, then truncate from the
+ 10 characters. If the content is longer than 35 characters, then truncate from the
beginning of the string.
- ``%-15.40m``
Right pad with spaces (align left) if the log message is shorter than 15 characters.
If the message is longer than 40 characters, truncate from the beginning.
-Supported parameters depend on the liblog4cplus version used to compile Kea. This can
-be checked by executing ``kea-dhcp4 -W | grep -i log4cplus`` which will produce output
-like this: ``LOG4CPLUS_VERSION: 2.0.5``. Consult the documentation in the
+Supported parameters depend on the liblog4cplus version used to compile Kea, which can
+be checked by executing ``kea-dhcp4 -W | grep -i log4cplus``. This produces a result
+such as: ``LOG4CPLUS_VERSION: 2.0.5``. Consult the documentation in the
`log4cplus wiki <https://github.com/log4cplus/log4cplus/wiki>`__ for further information
-about the version you have installed.
+about the installed version.
Example Logger Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
default values, although it is possible to modify some aspects of the
settings by means of environment variables. In the absence of
any logging configuration in the configuration file, the settings of the
-(possibly modified) default configuration will persist while the program
+(possibly modified) default configuration persist while the program
is running.
The following environment variables can be used to control the behavior
:ref:`build-requirements` for details.
2. Download the Kea source tarball from
- `the ISC.org downloads page <https://www.isc.org/download/>`__ or
- `the ISC downloads site <https://downloads.isc.org/isc/kea/>`__ or
+ `the main isc.org downloads page <https://www.isc.org/download/>`__,
+ `the ISC downloads site <https://downloads.isc.org/isc/kea/>`__, or
`the ISC Cloudsmith page <https://cloudsmith.io/~isc/packages/?q=format%3Araw>`__.
3. Extract the tarball. For example:
=======================================
ISC provides native Alpine, deb, and RPM packages, which make Kea installation
-much easier. Unless specific compilation options are desired, it is usually
+much easier than building from source. Unless specific compilation options are desired, it is usually
easier to install Kea using native packages.
1. Go to `Kea on cloudsmith.io <https://cloudsmith.io/~isc/repos/>`__.
2. Choose the Cloudsmith repository e.g. |cloudsmith_repo| for Kea |version|.
-3. Click on the arrow besides the ``Set Me Up`` button and select your OS flavor
- out of: ``Alpine``, ``Debian``, ``RedHat``.
+3. Click on the arrow beside the "Set Me Up" button and select the desired OS flavor:
+ Alpine, Debian, or RedHat.
-4. Follow the instructions written there.
+4. Follow the onscreen instructions.
.. note::
For example, the Debian setup instructions for Kea 2.4 can be found here:
$ apk add isc-kea-dhcp6
-or every single Kea-related package, including development headers, debug
+or ALL Kea-related packages, including development headers, debug
symbols, and premium hooks (if available):
.. list-table::
# apk search isc-kea | sed 's/-[0-9].*//g' | grep r20230921141113 | xargs apk add
-8. All installed packages should be now available directly.
+8. All installed packages should be now available.
- You can start a server up manually:
+ You can start a server manually:
.. code-block:: console
:iscman:`keactrl` is not available in packages, as similar functionality is provided
by the native systemctl scripts.
-9. On Debian/Ubuntu systems, the service is enabled at boot time automatically
+9. On Debian/Ubuntu systems, the service is automatically enabled at boot time
when the package is installed. On Fedora/RHEL and Alpine, the service is not
- enabled automatically, so, if desired, it must be enabled manually.
+ automatically enabled, so if desired, it must be enabled manually.
With systemd on Fedora/RedHat:
Quick Start Guide Using Docker Containers
=========================================
-1. Go to `ISC docker repository on cloudsmith.io <https://cloudsmith.io/~isc/repos/docker/packages/>`__.
+1. Go to the `ISC docker repository on cloudsmith.io <https://cloudsmith.io/~isc/repos/docker/packages/>`__.
2. Create an ipvlan network attached to the client-facing host interface and
assigned to the subnet that is served by Kea.
$ docker pull docker.cloudsmith.io/isc/docker/kea-dhcp6
-
-4. Create a container out of the image. Mount the configuration volume and the
+4. Create a container from the image. Mount the configuration volume and the
data volume if needed.
.. code-block:: console
1. Edit the Kea configuration files, which by default are installed in
the ``[kea-install-dir]/etc/kea/`` directory. These are:
``kea-dhcp4.conf``, ``kea-dhcp6.conf``, ``kea-dhcp-ddns.conf`` and
- ``kea-ctrl-agent.conf``, ``keactrl.conf`` for DHCPv4 server, DHCPv6 server,
- D2, Control Agent, and the keactrl script, respectively.
+ ``kea-ctrl-agent.conf``, ``keactrl.conf`` for the DHCPv4 server, DHCPv6 server,
+ D2, Control Agent, and keactrl script, respectively.
2. To start the DHCPv4 server in the background, run the
following command (as root):
.. note::
- From Kea 2.4.0 version, the :iscman:`kea-shell` no longer supports Python 2.7.
+ Beginning with Kea 2.4.0, :iscman:`kea-shell` no longer supports Python 2.7.
The Kea shell is intended to serve more as a demonstration of the
RESTful interface's capabilities (and, perhaps, an illustration for
TLS Support
===========
-Since Kea 1.9.6, :iscman:`kea-shell` supports HTTPS connections. The TLS/HTTPS
+:iscman:`kea-shell` supports HTTPS connections; the TLS/HTTPS
support requires Python 3. The additional command-line arguments are:
- ``--ca`` specifies the file or directory name of the Certification
64-bit integer (int64_t in C++), so it can hold any value between
-2^63 to 2^63-1.
-- *big integer* - this type is inteded for holding large numbers. It is
+- *big integer* - this type is intended to hold large numbers. It is
implemented as a 128-bit integer (boost::multiprecision::int128_t in C++), so
it can hold any value between -2^127 to 2^127-1.
for the Cassandra backend has been deprecated.)
The first line of the file contains the column names. This can be used
as a way to switch from a database backend to a memfile backend.
- Alternatively, it can be used as a diagnostic tool, so it provides a
+ It can also be used as a diagnostic tool, as it provides a
portable form of the lease data. There are other mandatory arguments
- that must be used together with this command. Either ``-4`` or ``-6`` must
- be specified. Also ``-o`` or ``--output`` must be provided.
+ that must be used together with this command: either ``-4`` or ``-6`` must
+ be specified, and either ``-o`` or ``--output`` must be provided.
``lease-upload``
Uploads leases from a CSV (comma-separated values) text file to a MySQL or
a PostgreSQL lease database. The CSV file needs to be in memfile format.
There are other mandatory arguments that must be used together with this
- command. Either ``-4`` or ``-6`` must be specified.
- Also ``-i`` or ``--input`` must be provided.
+ command: either ``-4`` or ``-6`` must be specified,
+ and either ``-i`` or ``--input`` must be provided.
``stats-recount``
Recounts lease statistics for a MySQL or PostgreSQL database.
The default value is ``localhost``.
``-i|--input input_file``
- Specifies the CSV (comma-separated values) text file with leases to be uploaded.
- Required for ``lease-upload``.
+ Specifies the CSV (comma-separated values) text file with the leases to be uploaded;
+ required for ``lease-upload``.
``-P|--port port``
Specifies the port when connecting to a database. If not specified,
``-o code,hexstring``
Forces ``perfdhcp`` to insert the specified extra option (or options if
- used several times) into packets being transmitted. The code
- specifies the option code and the hexstring is a hexadecimal string that
- defines the content of the option. Care should be taken as ``perfdhcp``
- does not offer any kind of logic behind those options; they are simply
+ used multiple times) into packets being transmitted. The code
+ specifies the option code, and the hexstring is a hexadecimal string that
+ defines the content of the option. Care should be taken, as ``perfdhcp``
+ does not offer any kind of logic behind the options; they are simply
inserted into packets and sent as is. Be careful not to duplicate
- options that are already inserted. For example, to insert client
- class identifier (option code 60) with a string "docsis", use
- "-o 60,646f63736973". The ``-o`` may be used multiple times. It is
- necessary to specify the protocol family (either ``-4`` or ``-6``) before
- using ``-o``.
+ options that are already inserted. For example, to insert the
+ client-class identifier (option code 60) with the string "docsis", use
+ ``-o 60,646f63736973``. The ``-o`` may be used multiple times. The protocol
+ family (``-4`` or ``-6``) must be specified before using ``-o``.
``-P preload``
Initiates preload exchanges back-to-back at startup. Must be 0
traffic passing through a single relay agent.
``--or encapsulation-level:code,hexstring``
- This option is very similar to ``-o``, only that it forces ``perfdhcp``
- to insert the specified extra option (or options if used several times)
- into relayed DHCPv6 message at given level of encapsulation (currently
- the only supported encapsulation-level value is 1). The code
- specifies the option code and the hexstring is a hexadecimal string that
- defines the content of the option. Care should be taken as ``perfdhcp``
- does not offer any kind of logic behind those options; they are simply
- inserted into packets and sent as is. Please notice that ``encapsulation-level:``
- is optional and if omitted, default encapsulation-level value 1 is used.
- For example, to insert Subscriber identifier (option code 38) with a
- value 1234 at first level of encapsulation, use ``--or 38,31323334``
- or ``--or 1:38,31323334``. The ``--or`` may be used multiple times.
- It must be used together with ``-A``.
+ Forces ``perfdhcp`` to insert the specified extra option (or options if
+ used multiple times) into a relayed DHCPv6 message at the given level of
+ encapsulation; currently, the only supported encapsulation-level value is 1.
+ This option is very similar to ``-o``: the code
+ specifies the option code, and the hexstring is a hexadecimal string that
+ defines the content of the option. Care should be taken, as ``perfdhcp``
+ does not offer any kind of logic behind the options; they are simply
+ inserted into packets and sent as is. ``encapsulation-level:``
+ is optional; if it is omitted, the default encapsulation-level value 1 is used.
+ For example, to insert the Subscriber identifier (option code 38) with a
+ value 1234 at the first level of encapsulation, use ``--or 38,31323334``
+ or ``--or 1:38,31323334``. The ``--or`` may be used multiple times, and
+ it must be used in conjunction with ``-A``.
Template-Related Options
~~~~~~~~~~~~~~~~~~~~~~~~
Sets the delay (in seconds) between two successive reports.
``-C separator``
- Suppresses the preliminary output and causes the interim data to
- only contain the values delimited by ``separator``. Used in
- conjunction with ``-t`` to produce easily parsable
- reports at ``-t`` intervals.
+ Suppresses the preliminary output and causes the interim data to
+ only contain the values delimited by ``separator``. Used in
+ conjunction with ``-t`` to produce easily parsable
+ reports at ``-t`` intervals.
Arguments
~~~~~~~~~
projects / thirdparty / kea.git / commitdiff
