mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-31 14:05:33 +00:00
Code Issues Releases Wiki Activity

[#1917] Changes up to and including Chapter 23

Browse Source
This commit is contained in:
peterd
2021-06-08 15:00:54 +00:00
committed by Tomek Mrugalski
parent fac6fa357c
commit d575f854cf
16 changed files with 52 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/sphinx/arm/classify.rst
View File

@@ -59,7 +59,7 @@ The classification process is conducted in several steps:
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.
@@ -87,7 +87,7 @@ The classification process is conducted in several steps:
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.

2
doc/sphinx/arm/congestion-handling.rst
View File

@@ -66,7 +66,7 @@ figure varies widely depending on the specifics of an individual deployment.
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

6
doc/sphinx/arm/ctrl-channel.rst
View File

@@ -313,7 +313,7 @@ invocation looks like this:
}
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:
@@ -644,7 +644,7 @@ The ``status-get`` command returns server's runtime information:
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.
@@ -654,7 +654,7 @@ The ``status-get`` command returns server's runtime information:
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.

2
doc/sphinx/arm/database-connectivity.rst
View File

@@ -48,4 +48,4 @@ connection is lost. It can have one of the following values:
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.

4
doc/sphinx/arm/ddns.rst
View File

@@ -298,7 +298,7 @@ The D2 server supports the following operational commands:
- 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:
@@ -469,7 +469,7 @@ the following parameters:
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

6
doc/sphinx/arm/hooks-bootp.rst
View File

@@ -5,7 +5,7 @@ BOOTP Support
.. 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
@@ -20,7 +20,7 @@ the server's responses and responses shorter than the BOOTP minimum
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.
::
@@ -46,7 +46,7 @@ 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:
::

10
doc/sphinx/arm/hooks-cb-cmds.rst
View File

@@ -37,7 +37,7 @@ There are 5 types of commands supported by this library:
- ``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``.
@@ -774,7 +774,7 @@ the selected shared network, use the `remote-network[46]-get` command.
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".
@@ -907,7 +907,7 @@ code of 1 and belonging to the option space "isc". The default option spaces are
"dhcp4" and "dhcp6" for the DHCPv4 and DHCPv6 top level options respectively. 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:
@@ -1240,8 +1240,8 @@ with the name of the shared network from which the option is to
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.

2
doc/sphinx/arm/hooks-ha.rst
View File

@@ -1589,7 +1589,7 @@ one of them is responding to all DHCP queries and the other one is awaiting
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

8
doc/sphinx/arm/hooks-lease-cmds.rst
View File

@@ -206,7 +206,7 @@ The commands can take several additional optional parameters:
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
@@ -383,7 +383,7 @@ returned codes are the same as the results returned for the commands.
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:
@@ -755,7 +755,7 @@ An example of the ``lease6-get-by-hostname`` is:
}
The by key is the only parameter. The returned response contains a detailed
list of leases in the same format 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:
@@ -808,7 +808,7 @@ When true it instructs the server to queue a request to kea-dhcp-ddns to
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:

4
doc/sphinx/arm/hooks-radius.rst
View File

@@ -52,8 +52,8 @@ on CentOS 7.0. Other systems may differ slightly.
.. 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.

4
doc/sphinx/arm/hooks-run-script.rst
View File

@@ -38,7 +38,7 @@ the script (including next step) to be ignored.
.. 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:
@@ -187,7 +187,7 @@ An example of a script implementing all hook points is presented below.
.. _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:

24
doc/sphinx/arm/hooks.rst
View File

@@ -61,7 +61,7 @@ Installing Hook Packages
.. 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
@@ -306,7 +306,7 @@ loaded by the correct process per the table below.
+=================+===============+============================================================+
| 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 |
@@ -390,19 +390,19 @@ loaded by the correct process per the table below.
| 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. |
@@ -425,7 +425,7 @@ loaded by the correct process per the table below.
| | |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 |
@@ -437,19 +437,19 @@ loaded by the correct process per the table below.
| | |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 |
@@ -1467,7 +1467,7 @@ continue serving clients while this mechanism is activated.
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
@@ -1757,7 +1757,7 @@ name followed by .boot for content.
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

2
doc/sphinx/arm/lfc.rst
View File

@@ -14,7 +14,7 @@ the files used to provide persistent storage for the Memfile database
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

4
doc/sphinx/arm/logging.rst
View File

@@ -679,7 +679,7 @@ That breaks down as like so:
- ``%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
@@ -748,7 +748,7 @@ console using standard output.
}
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.
::

6
doc/sphinx/arm/security.rst
View File

@@ -66,7 +66,7 @@ that must be used:
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.
@@ -75,7 +75,7 @@ that must be used:
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)
@@ -362,7 +362,7 @@ processes that are used to ensure adequate code quality:
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

16
doc/sphinx/arm/stats.rst
View File

@@ -93,7 +93,7 @@ There are several commands defined that can be used for accessing
(-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,
@@ -282,9 +282,9 @@ The statistic-sample-age-set Command
----------------------------------------
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:
::
@@ -311,7 +311,7 @@ The statistic-sample-age-set-all Command
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:
::
@@ -335,7 +335,7 @@ The statistic-sample-count-set Command
------------------------------------------
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:
::
@@ -395,7 +395,7 @@ points, perhaps to do some form of statistical analysis afterwards.
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``,
@@ -403,5 +403,5 @@ to set size limit for single statistic and ``statistic-sample-count-set-all``
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.