following its client class or global (or, for option 43, last
resort) definition.
-5. When the incoming packet belongs the special class, `DROP`, it is
+5. When the incoming packet belongs to the special class, `DROP`, it is
dropped and an informational message is logged with the packet
information.
possible to use KNOWN/UNKNOWN classes to select a shared network or
a subnet.
-9. When the incoming packet belongs the special class, `DROP`, it is
+9. When the incoming packet belongs to the special class, `DROP`, it is
dropped and an informational message is logged with the packet
information. Since Kea version 1.9.8 it is allowed to make DROP
class dependent of KNOWN/UNKNOWN classes.
As there is no one algorithm that will best handle the dynamics of all
sites, and because over time new approaches will evolve, the packet
-queue is implemented as a plug-in, which can replaced by a custom queue
+queue is implemented as a plug-in, which can be replaced by a custom queue
implementation via a hook library. This should make it straightforward
for interested parties to experiment with their own solutions.
(Developers can refer to isc::dhcp::PacketQueue and
}
If the configuration file is incorrect reloading it can raise an error
-which leaves the server in unusable state.. Look at :ref:`command-config-set`
+which leaves the server in an unusable state.. Look at :ref:`command-config-set`
what to do to recover a working server.
.. _command-config-test:
processing).
* remote: for the remote server the last known state, served
- HA scopes and the role of the server in HA relationship.
+ HA scopes and the role of the server in the HA relationship.
- multi-threading-enabled: flag indicating if multi-threading is enabled.
regardless of how many threads are running.
- packet-queue-statistics: average queue size for last 10, 100 and 1000
- packets. This statistic uses approach similar to Unix ``top`` command.
+ packets. Statistics using an approach similar to the Unix ``top`` command.
The averaged queue size for the last 10 packets can be considered an
instantaneous value, while average for the last 1000 packets shows
longer term trend.
If connectivity to all backends is restored, the server returns to normal
operations. If the connection can not be restored and the server is configured
-to exit, it issues a fatal error before shut down.
+to exit, it issues a fatal error before shutdown.
- status-get
- version-get
-The ``shutdown`` command supports extra ``type`` argument which controls the
+The ``shutdown`` command supports the extra ``type`` argument which controls the
way the D2 server cleans up on exit.
The supported shutdown types are:
used in a first-to-last preference; in other words, when D2 begins to
process a request for this domain, it will pick the first server in
this list and attempt to communicate with it. If that attempt fails,
- D2 will move to next one in the list and so on until either it
+ D2 will move to the next one in the list and so on until either it
is successful or the list is exhausted.
To create a new Forward DDNS Domain, add a new domain element and set
.. note::
- This is library is still in experimental phase. Use with care!
+ This library is still in the experimental phase. Use with care!
This hooks library adds support for BOOTP with vendor information extensions
size (300 octets) are padded to this size.
The library is available since Kea 1.7.2 and can be loaded in a
-similar way as other hook libraries by the ``kea-dhcp4`` process.
+similar way to other hook libraries by the ``kea-dhcp4`` process.
It takes no parameter.
::
.. _hooks-bootp-config:
Incoming BOOTP packets are added to the BOOTP class. This can be used
-to segregate BOOTP clients to separate pool. For example you can do
+to segregate BOOTP clients to separate pools. For example you can do
the following:
::
- ``list`` - list all objects of the particular type in the database,
e.g. ``remote-network4-list``; this class of commands returns brief
- information about each object comparing to the output of ``get-all``.
+ information about each object compared to the output of ``get-all``.
- ``set`` - creates or replaces an object of the given type in the
database, e.g. ``remote-option4-global-set``.
The example response above contains three shared networks. One of the
shared networks is associated will all servers, so it is included in
-the list of shared networks to be used by the "server1" and "server2".
+the list of shared networks to be used by "server1" and "server2".
The remaining two shared networks are returned because one of them
is associated with the "server1" and another one is associated with
the "server2".
"dhcp4" and "dhcp6" for the DHCPv4 and DHCPv6 top level options respectively. If
there is no such option explicitly associated with the server1, no option is
deleted. In order to delete an option belonging to "all" servers, the keyword
-"all" must be used as server tag. The `server-tags` list must contain exactly
+"all" must be used as the server tag. The `server-tags` list must contain exactly
one tag. It must not include the `null` value.
.. _command-remote-option-def4-get:
be deleted. If the option is not explicitly specified for this
shared network, no option is deleted. In particular, the given
option may be present for a subnet belonging to the shared network.
-Such option instance is not affected by this command as this
-command merely deletes shared network level option. In order to
+Such an option instance is not affected by this command as this
+command merely deletes the shared network level option. In order to
delete subnet level option the `remote-option[46]-subnet-del`
command must be used instead.
a shutdown.
Suppose that the HA setup includes two active servers, e.g. ``server1``
-and ``server2`` and the latter needs to be shut down for the maintenance.
+and ``server2`` and the latter needs to be shut down for maintenance.
The administrator should send the ``ha-maintenance-start`` to server1,
as this is the server which is going to handle the DHCP traffic while the
other one is offline. The server1 may respond with an error if its state
true.
- ``fqdn-rev`` - specifies whether the lease should be marked as if
- reverse DNS update were conducted. Note this only affects the the
+ reverse DNS update were conducted. Note this only affects the
data stored in the lease database, and no DNS update will be
performed.. If configured, a DNS update to remove the PTR record will
be conducted when the lease is removed due to expiration or being
In particular, the result of 1 indicates an error while processing the
lease, e.g. a communication error with the database. The result of 3
indicates that an attempt to delete the lease was unsuccessful because
-such lease doesn't exist (empty result).
+such a lease doesn't exist (empty result).
.. _command-lease4-get:
}
The by key is the only parameter. The returned response contains a detailed
-list of leases in the same format than ``leaseX-get-all``. This list can be
+list of leases in the same format as ``leaseX-get-all``. This list can be
empty and usually is never large.
.. _command-lease4-del:
remove DNS entries after the lease is successfully deleted if:
- DDNS updating is enabled. (i.e. "dhcp-ddns":{ "enable-updates": true })
-- The lease's hostname is not be empty.
+- The lease's hostname is not empty.
- At least one of the lease's DNS direction flags (fdqn_fwd or fdqn_rev) is true.
This parameter defaults to false. An example of its use is shown below:
.. note::
Starting with Kea 1.7.0, ISC now provides Kea software and hooks in convenient to use
- native DEB and RPM packages. This includes RADIUS hook and the required patched version
- of FreeRADIUS client library. The software compilation for RADIUS is complicated. unless
+ native DEB and RPM packages. This includes the RADIUS hook and the required patched version
+ of the FreeRADIUS client library. The software compilation for RADIUS is complicated. unless
you have specific reasons to compile it yourself, you should seriously consider using
native packages.
.. note::
Currently the functionality underneath 'sync' parameter is not implemented
- and enabling synchronous calls to external script is not supported.
+ and enabling synchronous calls to external scripts is not supported.
.. _hooks-run-script-hook-points:
.. _hooks-run-script-exported-environment-variables:
-Available parameters for each hook points are presented below.
+Available parameters for each hook point are presented below.
DHCPv4:
.. note::
For more details about installing the Kea Premium Hooks package, please read
- `this Knowledgebase article <https://kb.isc.org/docs/aa-01587>`__.
+ `this Knowledge Base article <https://kb.isc.org/docs/aa-01587>`__.
Some hook packages are included in the base Kea sources. There is no
need to do anything special to compile or install them, as they are covered
+=================+===============+============================================================+
| User Check | Kea sources |Reads known users list from a file. Unknown users will be |
| | (since 0.8) |assigned a lease from the last subnet defined in the |
- | | |configuration file, e.g. to redirect them a captive |
+ | | |configuration file, e.g. to redirect them to a captive |
| | |portal. This demonstrates how an external source of |
| | |information can be used to influence the Kea allocation |
| | |engine. This hook is part of the Kea source code and is |
| Availability | (since 1.4) |by setting up a pair of the DHCP servers in a network. Two |
| | |modes of operation are supported. The first one is called |
| | |load balancing and is sometimes referred to as |
- | | |active-active. Each server can handle selected group of |
+ | | |active-active. Each server can handle selected groups of |
| | |clients in this network or all clients, if it detects that |
| | |its partner has become unavailable. It is also possible to |
| | |designate one server to serve all DHCP clients, and leave |
| | |another server as "standby". This mode is called hot standby|
- | | |and is sometimes referenced to as active-passive. This |
+ | | |and is sometimes referred to as active-passive. This |
| | |server will activate its DHCP function when it detects that |
| | |its partner is not available. Such cooperation between the |
| | |DHCP servers requires that these servers constantly |
| | |communicate with each other to send updates about allocated |
| | |leases and to periodically test whether their partners are |
| | |still operational. The hook library also provides an ability|
- | | |to send lease updates to external backup server, making it |
+ | | |to send lease updates to external backup servers, making it |
| | |much easier to have a replacement that is almost up to |
| | |date. The "libdhcp_ha" library provides such functionality |
| | |for Kea DHCP servers. |
| | |specific IPv4 or IPv6 addresses reserved by RADIUS, |
| | |dynamically assigning addresses from designated pools chosen|
| | |by RADIUS or rejecting the client's messages altogether. The|
- | | |accounting mechanism allows RADIUS server to keep track of |
+ | | |accounting mechanism allows a RADIUS server to keep track of|
| | |device activity over time. |
+-----------------+---------------+------------------------------------------------------------+
| Host Cache | Support |Some of the database backends, such as RADIUS, are |
| | |includes negative caching, i.e. the ability to remember that|
| | |there is no client information in the database. |
+-----------------+---------------+------------------------------------------------------------+
- | Class Commands | Support |This Class Cmds hooks library allows for adding, updating |
+ | Class Commands | Support |This Class Cmds hooks library allows for adding, updating, |
| | customers |deleting and fetching configured DHCP client classes without|
| | (since 1.5) |the need to restart the DHCP server. |
+-----------------+---------------+------------------------------------------------------------+
| MySQL | Kea sources |The MySQL CB hooks library is an implementation of the Kea |
- | Configuration | (since 1.6) |Configuration Backend for MySQL. It uses MySQL database as a|
- | Backend | |repository for the Kea configuration information. The Kea |
+ | Configuration | (since 1.6) |Configuration Backend for MySQL. It uses a MySQL database as|
+ | Backend | |a repository for the Kea configuration information. The Kea |
| | |servers use this library to fetch their configurations. |
+-----------------+---------------+------------------------------------------------------------+
| Configuration | Support |The Configuration Backend Commands (CB Commands) hooks |
| Backend | customers |library implements a collection of commands to manage the |
| Commands | (since 1.6) |configuration information of the Kea servers in the |
- | | |database. This library may only be used in conjuction with |
+ | | |database. This library may only be used in conjunction with |
| | |one of the supported configuration backend implementations. |
+-----------------+---------------+------------------------------------------------------------+
| BOOTP | Kea sources |The BOOTP hooks library adds BOOTP support, as defined in |
flex_id: Flexible Identifiers for Host Reservations
===================================================
-This section describes a hook application dedicated to generate flexible
+This section describes a hook application dedicated to generating flexible
identifiers for host reservations. The Kea software provides a way to handle
host reservations that include addresses, prefixes, options, client
classes, and other features. The reservation can be based on hardware
The flexible option library supports both DHCPv4 and DHCPv6.
-Since Kea 1.9.0, the add and supersede actions take an optional cvs-format
+Since Kea 1.9.0, the add and supersede actions take an optional csv-format
boolean parameter. If not specified or configured 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 the option data
backend. This service is written to run as a standalone process.
While ``kea-lfc`` can be started externally, there is usually no need to
-do s. ``kea-lfc`` is run on a periodic basis by the Kea DHCP servers.
+do so. ``kea-lfc`` is run on a periodic basis by the Kea DHCP servers.
The process operates on a set of files, using them to receive input and
output of the lease entries and to indicate what stage the process is
- ``%t``
The thread ID. From the example log: ``12345``.
Note the format of the thread ID is OS dependent: e.g. on some systems
- it is an address so is displayed in hexadecimal.
+ it is an address so it is displayed in hexadecimal.
- ``%m``
The log message itself. Kea log messages all begin with a message identifier
}
In this second example, we want to store debug log messages in a file
-that is at most 2MB and keep up to eight copies of old logfiles. Once the
+that is at most 2MB and keep up to eight copies of old log files. Once the
logfile grows to 2MB, it will be renamed and a new file will be created.
::
packages / installation only when Botan was configured with the
``--with-boost`` option.
- Sadly, many packages provided by operating systens, such as Ubuntu 20.10,
+ Sadly, many packages provided by operating systems, such as Ubuntu 20.10,
did not build Botan with boost support, therefore making those packages
unusable directly for Kea.
directory but of course this should be a last resort procedure.
Note that without these header files or with a Botan version older
- than 2.14.0 Kea can still build but the TLS/HHTPS support is disabled:
+ than 2.14.0 Kea can still build but the TLS/HTTPS support is disabled:
any attempt to use it will fail with a fatal error.
- Very old boost versions provide SSL support (based on OpenSSL)
Fuzz testing
------------
-Kea team has a process for running fuzz testing, using `AFL <https://github.com/google/AFL>`_. There
+The Kea team has a process for running fuzz testing, using `AFL <https://github.com/google/AFL>`_. There
are two modes which are run. The first mode fuzzes incoming packets, effectively throwing millions of mostly
broken packets at Kea per day. The second mode fuzzes configuration structures and forces Kea to
attempt to load them. Kea has been fuzzed since around 2018 in both modes. The input seeds
(-get), resetting to zero or a neutral value (-reset), or removing a
statistic completely (-remove). We can change the statistics time based
limit (-sample-age-set) and size based limit (-sample-count-set) which
-control how long or how many samples of the given statistic are retained.
+control how long or how many samples of a given statistic are retained.
The difference between reset and remove is somewhat subtle.
The reset command sets the value of the statistic to zero or a neutral value,
----------------------------------------
The ``statistic-sample-age-set`` command sets time based limit
-for collecting samples for given statistic. It takes two parameters a string
-called ``name``, which specifies the statistic name and integer value called
-``duration``, which specifies the time limit for given statistic in seconds.
+for collecting samples for a given statistic. It takes two parameters a string
+called ``name``, which specifies the statistic name and an integer value called
+``duration``, which specifies the time limit for the given statistic in seconds.
An example command may look like this:
::
The ``statistic-sample-age-set-all`` command sets time based limits
for collecting samples for all statistics. It takes single-integer parameter
-called ``duration``, which specifies the time limit for given statistic
+called ``duration``, which specifies the time limit for statistic
in seconds. An example command may look like this:
::
------------------------------------------
The ``statistic-sample-count-set`` command sets size based limit
-for collecting samples for given statistic. An example command may look
+for collecting samples for a given statistic. An example command may look
like this:
::
Since Kea 1.6, by default, each statistic holds 20 data points. Setting such
-limit prevent unlimited memory consumption growth.
+a limit prevents unlimited memory growth.
There are two ways to define the limts: time based (e.g. keep samples from
the last 5 minutes) and size based. It's possible to change the size based
limit by using one of two commands: ``statistic-sample-count-set``,
for setting size based limits for all statistics. To set time based
limit for single statistic use ``statistic-sample-age-set``, and
``statistic-sample-age-set-all`` to set time based limits for all statistics.
-For given statistic only one type of limit can be active. It means that storage
+For a given statistic only one type of limit can be active. It means that storage
is limited only by time based limit or size based, never by both of them.
projects / thirdparty / kea.git / commitdiff
