mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-22 01:49:48 +00:00
Code Issues Releases Wiki Activity

Fix typos, and other text corrections

Browse Source 
Mostly minor text fixups, with a few edits for clarity
This commit is contained in:
Suzanne Goldlust 2020-11-14 00:00:37 +00:00 committed by Tomek Mrugalski
parent cc8435ae7d
commit 76b25d1836
22 changed files with 352 additions and 351 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/devel/congestion-handling.dox
View File

@ -52,7 +52,7 @@ The default packet queue implementation for both Kea DHCPv4 and DHCPv6 servers
is a simple ring buffer. Once it reaches capacity, new packets get added to
the back of queue by discarding packets from the front of queue. Rather than
always discarding the newest packets, we now always discard the oldest
packets. The capacity of the buffer, (i.e the maximum number of packets the
packets. The capacity of the buffer (i.e. the maximum number of packets the
buffer can contain) is configurable.
@section custom-implementations Custom Packet Queues

41
doc/sphinx/arm/admin.rst
View File

@ -9,7 +9,7 @@ Kea Database Administration
Databases and Database Version Numbers
======================================
Kea may be configured to use a database as a storage for leases or as a
Kea may be configured to use a database as storage for leases or as a
source of servers' configurations and host reservations (i.e. static
assignments of addresses, prefixes, options, etc.). Kea
updates introduce changes to the database schemas to faciliate new
@ -213,7 +213,7 @@ To create the database:
4. Create the database.
You'll need to exit mysql client
Exit the MySQL client
.. code-block:: mysql
@ -226,12 +226,13 @@ To create the database:
$ kea-admin db-init mysql -u database-user -p database-password -n database-name
While it is possible to create the database from within mysql client, we recommend you
use the kea-admin tool as it performs some necessary validations to ensure Kea can
While it is possible to create the database from within the MySQL client, we recommend
using the kea-admin tool as it performs some necessary validations to ensure Kea can
access the database at runtime. Among those checks is that the schema does not contain
any pre-existing tables. If there are any pre-existing tables they must be removed
manaully. An additional check examines the user's ability to create functions and
triggers. If you encounter the following error:
manually. An additional check examines the user's ability to create functions and
triggers. The following error indicates that the user does not have the necessary
permissions to create functions or triggers:
.. code-block:: console
@ -241,23 +242,22 @@ To create the database:
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR/kea-admin: Create failed, the user, keatest, has insufficient privileges.
Then user does not have the necessary permissions to create functions or triggers.
The simplest way around this is to set the global MySQL variable, log_bin_trust_function_creators to 1
via mysql client. Note you must do this as a user with SUPER privileges:
The simplest way around this is to set the global MySQL variable, log_bin_trust_function_creators, to 1
via the MySQL client. Note this must be done as a user with SUPER privileges:
.. code-block:: mysql
mysql> set @@global.log_bin_trust_function_creators = 1;
Query OK, 0 rows affected (0.00 sec)
If you choose to create the database with mysql directly, you may do as as follows:
To create the database with MySQL directly, use these steps:
.. code-block:: mysql
mysql> CONNECT database-name;
mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql
(path-to-kea is the location where Kea is installed.)
(where "path-to-kea" is the location where Kea is installed.)
The database may also be dropped manually as follows:
@ -266,10 +266,10 @@ To create the database:
mysql> CONNECT database-name;
mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_drop.mysql
(path-to-kea is the location where Kea is installed.)
(where "path-to-kea" is the location where Kea is installed.)
.. warning::
Dropping the database will result in the unrecoverable loss of any data it contains.
Dropping the database results in the unrecoverable loss of any data it contains.
5. Exit MySQL:
@ -323,10 +323,9 @@ earlier version. To perform an upgrade, issue the following command:
.. note::
To search host reservations by hostname it is critical the collation of
the hostname column in the host table to be case-insensitive. Fortunately
the default collation in MySQL is case-insensitive. You can verify this
on your MySQL installation by:
To search host reservations by hostname it is critical that the collation of
the hostname column in the host table be case-insensitive. Fortunately, that
is the default in MySQL, but it can be verified via this command:
.. code-block:: mysql
@ -337,7 +336,7 @@ earlier version. To perform an upgrade, issue the following command:
| utf8_general_ci |
+-----------------+
According to the naming of collations when the name finishes by ``_ci``
According to naming convention, when the name ends in ``_ci``,
the collation is case-insensitive.
.. _mysql-performance:
@ -345,8 +344,8 @@ earlier version. To perform an upgrade, issue the following command:
Simple MySQL tweak to gain performance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Changing MySQL internal value ``innodb_flush_log_at_trx_commit`` from default value
``1`` to ``2`` can result with huge gain in Kea performance. It can be set per session for testing:
Changing the MySQL internal value ``innodb_flush_log_at_trx_commit`` from the default value
``1`` to ``2`` can result in a huge gain in Kea performance. It can be set per session for testing:
.. code-block:: mysql
@ -361,7 +360,7 @@ or permanently in ``/etc/mysql/my.cnf``:
innodb_flush_log_at_trx_commit=2
Be aware that changing this value can result with problems during data recovery
after crash, we strongly recommend to check `MySQL documentation <https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_flush_log_at_trx_commit>`__.
after a crash, so we strongly recommend checking the `MySQL documentation <https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_flush_log_at_trx_commit>`__.
.. _pgsql-database:

44
doc/sphinx/arm/config.rst
View File

@ -125,18 +125,18 @@ locations where extra parameters may appear are denoted by an ellipsis
Comments and User Context
-------------------------
You can specify shell, C or C++ style comments in the JSON configuration file if
you use the file locally. This is convenient and works in simple cases where
your configuration is kept statically using local file. However, since comments
are not part of JSON syntax, most JSON tools will detect them as
errors. Another problem with them is once Kea loads its configuration, the
shell, C and C++ style comments are ignored. If you use commands such as
`config-get` or `config-write`, those comments will be lost. An example of such
Shell, C, or C++ style comments are all permitted in the JSON configuration file if
the file is used locally. This is convenient and works in simple cases where
the configuration is kept statically using a local file. However, since comments
are not part of JSON syntax, most JSON tools detect them as
errors. Another problem with them is that once Kea loads its configuration, the
shell, C, and C++ style comments are ignored. If commands such as
`config-get` or `config-write` are used, those comments are lost. An example of such
comments has been presented in the previous section.
Historically, to address the problem Kea code allowed to put `comment` strings
Historically, to address the problem, Kea code allowed the use of `comment` strings
as valid JSON entities. This had the benefit of being retained through various
operations (such as `config-get`) or allowed processing by JSON tools. An
operations (such as `config-get`), or allowing processing by JSON tools. An
example JSON comment looks like this:
::
@ -149,18 +149,18 @@ example JSON comment looks like this:
}]
}
However, users complained that the comment is only a single line and it's not
possible to add any other information in more structured form. One specific
However, the facts that the comment could only be a single line, and that it was not
possible to add any other information in a more structured form, were frustrating. One specific
example was a request to add floor levels and building numbers to subnets. This
was one of the reasons why the concept of user context has been introduced. It
allows adding arbitrary JSON structure to most Kea configuration structures. It
has a number of benefits compared to earlier approaches. First, it is fully
compatible with JSON tools and Kea commands. Second, it allows storing simple
comment strings if you want to, but it can store much more complex data, such as
multiple lines (as string array), extra typed data (such as floor numbers being
actual numbers) and more. Third, the data is exposed to hooks, so it's possible
to develop third party hooks that take advantage of that extra information. An
example user context would look like this:
comment strings, but it can also store much more complex data, such as
multiple lines (as a string array), extra typed data (such as floor numbers being
actual numbers), and more. Third, the data is exposed to hooks, so it is possible
to develop third-party hooks that take advantage of that extra information. An
example user context looks like this:
::
@ -188,12 +188,12 @@ JSON comments, but converts them to user context on the fly. The
comments entries in user-context were converted back to JSON comments to
keep backward compatibility, but that conversion went away in version 1.7.9.
The is one side effect, however. If your configuration uses the old JSON
comment, the `config-get` command will return a slightly modified
configuration. Don't be surprised if you call `config-set` followed by a
`config-get` and receive a slightly different structure. If this bothers you,
the best way to avoid this problem is simply abandon JSON comments and start
using user-context.
The is one side effect, however. If the configuration uses the old JSON
comment, the `config-get` command returns a slightly modified
configuration. It is not uncommon for a call for `config-set` followed by a
`config-get` to receive a slightly different structure.
The best way to avoid this problem is simply to abandon JSON comments and
use user context.
For a discussion about user context used in hooks, see :ref:`user-context-hooks`.

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

@ -58,7 +58,7 @@ The default packet queue implementation for both kea-dhcp4 and kea-dhcp6
is a simple ring buffer. Once it reaches capacity, new packets get added
to the back of the queue by discarding packets from the front of the
queue. Rather than always discarding the newest packets, Kea now always
discards the oldest packets. The capacity of the buffer, i.e the maximum
discards the oldest packets. The capacity of the buffer, i.e. the maximum
number of packets the buffer can contain, is configurable. A reasonable
starting point would be to match the capacity to the number of leases
per second a specific installation of Kea can handle. Please note that this

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

@ -520,7 +520,7 @@ been initiated. The optional parameter, "exit-value", specifies the
numeric value with which the server process will exit to the system.
The default value is zero.
The DDNS deamon supports an extra parameter "type" which controls the way
The DDNS daemon supports an extra parameter "type" which controls the way
the process cleans up on exit. The supported shutdown types are:
- "normal" - Stops the queue manager and finishes all current transactions
@ -619,15 +619,15 @@ The ``status-get`` command returns server's runtime information:
The ``high-availability`` information is returned only when the command is
sent to the DHCP servers being in the HA setup. This parameter is
never returned when the ``status-get`` command is sent to the
Control Agent or DDNS deamon.
Control Agent or DDNS daemon.
The ``thread-pool-size`` and ``packet-queue-size`` parameters are returned only
when the command is sent to DHCP servers with multi-threading enabled. These two
parameters and ``multi-threading-enabled`` are never returned when the
``status-get`` command is sent to the Control Agent or DDNS deamon.
``status-get`` command is sent to the Control Agent or DDNS daemon.
To learn more about the HA status information returned by the
``status-get`` command please refer to the the :ref:`command-ha-status-get`
``status-get`` command please refer to the :ref:`command-ha-status-get`
section.

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

@ -4,31 +4,31 @@
Database Connectivity
*********************
Kea servers (kea-dhcp4 and kea-dhcp6) can be configured to use a variety of
database back ends for leases, hosts and configuration. All of them may be
database backends for leases, hosts, and configuration. All of them may be
configured to support automatic recovery when connectivity is lost (see
``max-reconnect-tries`` and ``reconnect-wait-time``).
It is important to understand how and when automatic recovery comes into play.
Automatic recovery, when configured, only operates after a successful start up
or reconfiguration during which connectivity to all back ends has been
Automatic recovery, when configured, only operates after a successful startup
or reconfiguration during which connectivity to all backends has been
successfully established.
During server start up the inability to connect to any of the configured back
ends is always considered fatal. A fatal error will be logged and the server
will exit. This is done based on the idea that configuration should be valid
at start up. Exiting to the operating system allows nanny scripts to detect
During server startup, the inability to connect to any of the configured
backends is always considered fatal. 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.
During dynamic reconfiguration, all back ends are disconnected and then
reconnected using the new configuration. If connectivity to any of the
back ends cannot be established, the server will log a fatal error but remain
up. It will be able to process commands but will not serve clients. This
During dynamic reconfiguration, all backends are disconnected and then
reconnected using the new configuration. If connectivity to any of the
backends cannot be established, the server logs a fatal error but remains
up. It is able to process commands but does not serve clients. This
allows the configuration to be corrected via command, if required.
During normal operations, if connectivity to any of the back ends is lost and
automatic recovery for that back end is enabled, the server will disconnect
from all back ends, and then attempt to reconnect them. During the recovery
process the server will cease serving clients but continue to respond to
commands. If connectivity to all back ends is restored the server will
return to normal operations. If connectivity cannot be restored after
``max-reconnect-tries``, the server will issue a fatal error and exit.
During normal operations, if connectivity to any of the backends is lost and
automatic recovery for that backend is enabled, the server disconnects
from all backends and then attempts to reconnect. During the recovery
process, the server ceases to serve clients but continues to respond to
commands. If connectivity to all backends is restored, the server
returns to normal operations. If connectivity cannot be restored after
``max-reconnect-tries``, the server issues a fatal error and exits.

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

@ -84,7 +84,7 @@ Dual-Stack Environments
`RFC 4703, section
5.2, <https://tools.ietf.org/html/rfc4703#section-5.2>`__ describes
issues that may arise with dual-stack clients. These are clients that
wish to have have both IPv4 and IPv6 mappings for the same FQDN. For
wish to have both IPv4 and IPv6 mappings for the same FQDN. For
this to work properly, the clients are required to embed their IPv6 DUID
within their IPv4 client identifier option, as described in `RFC
4703 <https://tools.ietf.org/html/rfc4361>`__. In this way, DNS updates

119
doc/sphinx/arm/dhcp4-srv.rst
View File

@ -732,9 +732,9 @@ entry, as in:
For additional Cassandra-specific parameters, see
:ref:`cassandra-database-configuration4`.
If the same host is configured both in-file and in-database, Kea won't warn of
the duplicate like it would if you specified them both in the same data source.
Instead the host configured in-file will have priority over the one configured
If the same host is configured both in-file and in-database, Kea does not issue a warning,
as it would if both were specified in the same data source.
Instead, the host configured in-file has priority over the one configured
in-database.
.. _read-only-database-configuration4:
@ -2229,14 +2229,14 @@ The definition used to decode a VSI option is:
sub-option code 0 and 255 mean PAD and END respectively according to
`RFC 2132 <https://tools.ietf.org/html/rfc2132>`_. In other words, the
sub-option code values of 0 and 255 are reserved. Kea does, however,
allow you to define sub-option codes from 0 to 255. If you define
sub-options with codes 0 and/or 255, bytes with that value will
no longer be treated as a PAD or an END, but as the sub-option code
allow users to define sub-option codes from 0 to 255. If
sub-options with codes 0 and/or 255 are defined, bytes with that value are
no longer treated as a PAD or an END, but as the sub-option code
when parsing a VSI option in an incoming query.
Option 43 input processing (aka unpacking) is deferred so that it
happens after classification. This means you cannot classify clients
using option 43 suboptions. The definition used to unpack option 43
Option 43 input processing (also called unpacking) is deferred so that it
happens after classification. This means clients cannot be classified
using option 43 suboptions. The definition used to unpack option 43
is determined as follows:
- If defined at the global scope this definition is used
@ -2247,12 +2247,12 @@ The definition used to decode a VSI option is:
definition only says the sub-option space is
"vendor-encapsulated-options-space"
The output definition selection is a bit simpler:
The output definition selection is a bit simpler:
- If the packet belongs to a client class which defines the option
43 use this definition
- If defined at the global scope use this definition
- Otherwise use the built-in last resot definition.
- Otherwise use the built-in last-resort definition.
Note as they use a specific/per vendor option space the sub-options
are defined at the global scope.
@ -2999,19 +2999,19 @@ The default configuration would appear as follows:
...
}
As of Kea 1.7.1, there are two parameters which determine if kea-dhcp4
can generate DDNS requests to D2. The existing, ``dhcp-ddns:enable-updates``
parameter which now only controls whether kea-dhcp4 connects to D2.
And the new behavioral parameter, ``ddns-send-updates``, which determines
if DDNS updates are enabled at a given level (i.e global, shared-network,
or subnet). The following table shows how the two parameters function
As of Kea 1.7.1, there are two parameters which determine whether kea-dhcp4
can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates``
parameter, which now only controls whether kea-dhcp4 connects to D2;
and the new behavioral parameter, ``ddns-send-updates``, which determines
whether DDNS updates are enabled at a given level (i.e. global, shared-network,
or subnet). The following table shows how the two parameters function
together:
.. table:: Enabling and Disabling DDNS Updates
+-----------------+--------------------+-------------------------------+
| dhcp-ddns: | Global | Outcome |
| enable-updates | ddns-send-udpates | |
| enable-updates | ddns-send-updates | |
+=================+====================+===============================+
| false (default) | false | no updates at any scope |
+-----------------+--------------------+-------------------------------+
@ -3026,12 +3026,12 @@ together:
| | | false for ddns-enable-updates |
+-----------------+--------------------+-------------------------------+
Kea 1.9.1 adds two new parameters. The first new parameter is ``ddns-update-on-renew``.
Normally, when leases are renewed the server will only update DNS if the DNS
Kea 1.9.1 adds two new parameters. The first new parameter is ``ddns-update-on-renew``.
Normally, when leases are renewed the server only updates DNS if the DNS
information for the lease (e.g. FQDN, DNS update direction flags) has changed.
Setting ``ddns-update-on-renew`` to true instructs the server to always update
the DNS information when a lease is renewed even if its DNS information has not
changed. This allows Kea to "self-heal" in the event it was previously unable
changed. This allows Kea to "self-heal" in the event it was previously unable
to add DNS entries or they were somehow lost by the DNS server.
.. note::
@ -3072,7 +3072,7 @@ conflict with existing entries owned by other DHCP4 clients.
FQDN while new entries for Client-B will still be added.
Disabling conflict resolution should be done only after careful review of
your specific use cases. The best way to avoid unwanted DNS entries is to
specific use cases. The best way to avoid unwanted DNS entries is to
always ensure leases changes are processed through Kea, whether they are
released, expire, or are deleted via the lease-del4 command, prior to
reassigning either FQDNs or IP addresses. Doing so will cause kea-dhcp4
@ -3328,9 +3328,9 @@ its value, simply set it to the desired string:
}
The suffix used when generating an FQDN, or when qualifying a partial
name, is specified by the ``ddns-qualifying-suffix`` parameter. It is
strongly recommended that you supply a value for qualifying prefix when
DDNS updates are enabled. For obvious reasons, we cannot supply a
name, is specified by the ``ddns-qualifying-suffix`` parameter. It is
strongly recommended that the user supply a value for the qualifying prefix when
DDNS updates are enabled. For obvious reasons, we cannot supply a
meaningful default.
::
@ -3341,7 +3341,7 @@ meaningful default.
...
}
When generating a name, kea-dhcp4 will construct the name in the format:
When generating a name, kea-dhcp4 constructs the name in the format:
[**ddns-generated-prefix**]-[**address-text**].[**ddns-qualifying-suffix**].
@ -3366,12 +3366,12 @@ and '-'. This may be accomplished with the following two parameters:
- ``hostname-char-set`` - a regular expression describing the invalid
character set. This can be any valid, regular expression using POSIX
extended expression syntax. Embedded nuls (0x00) will always be
extended expression syntax. Embedded nulls (0x00) are always
considered an invalid character to be replaced (or omitted).
- ``hostname-char-replacement`` - a string of zero or more characters
with which to replace each invalid character in the host name. An empty
string and will cause invalid characters to be OMITTED rather than replaced.
with which to replace each invalid character in the host name. An empty
string causes invalid characters to be OMITTED rather than replaced.
.. note::
@ -3380,10 +3380,10 @@ and '-'. This may be accomplished with the following two parameters:
- "hostname-char-set": "[^A-Za-z0-9.-]",
- "hostname-char-replacement": ""
This enables sanitizing and will omit any character that is not
a letter,digit, hyphen, dot or nul.
This enables sanitizing and omits any character that is not
a letter, digit, hyphen, dot, or null.
The following configuration will replace anything other than a letter,
The following configuration replaces anything other than a letter,
digit, hyphen, or dot with the letter 'x':
::
@ -3433,11 +3433,11 @@ qualifying suffix (if one is defined and needed).
.. note::
Since the 1.6.0 Kea release it is possible to specify hostname-char-set
Since the 1.6.0 Kea release, it is possible to specify hostname-char-set
and/or hostname-char-replacement at the global scope. This allows
to sanitize host names without requiring a dhcp-ddns entry. When
sanitizing host names without requiring a dhcp-ddns entry. When
a hostname-char parameter is defined at the global scope and
in a dhcp-ddns entry the second (local) value is used.
in a dhcp-ddns entry, the second (local) value is used.
.. _dhcp4-next-server:
@ -3862,8 +3862,8 @@ be retained on the lease. The lease's user-context will look something like thi
.. note::
It is possible that other hook libraries are already making use of user-context.
Enabling store-extended-info should not interfere with any other user-context
content so long as it does not also use an element labled "ISC". In other
words, user-context is intended to be a flexible container serving mulitple
content so long as it does not also use an element labeled "ISC". In other
words, user-context is intended to be a flexible container serving multiple
purposes. As long as no other purpose also writes an "ISC" element to
user-context there should not be a conflict.
@ -3906,10 +3906,10 @@ Multi-threading settings in different backends
Both kea-dhcp4 and kea-dhcp6 are tested internally to determine which settings
gave the best performance. Although this section describes our results, those are just
recommendations and are very dependent on the particular hardware that was used
for testing. We strongly advice to run your own performance tests.
for testing. We strongly advise that administrators run their own performance tests.
Full report of Kea 1.7 performance results can be found `here <https://jenkins.isc.org/job/kea-1.7/job/performance/KeaPerformanceReport/>`_.
This include hardware description, test scenario descriptions and
A full report of Kea 1.7 performance results can be found `here <https://jenkins.isc.org/job/kea-1.7/job/performance/KeaPerformanceReport/>`_.
This includes hardware descriptions, test scenario descriptions, and
current results.
After enabling multi-threading, the number of threads is set by ``thread-pool-size``
@ -3951,8 +3951,9 @@ IPv6 connectivity is available and they can shut down their IPv4 stack. The new
should disable its stack for. The value is expressed in seconds.
The RFC mentions V6ONLY_WAIT timer. This is implemented in Kea by setting the value of
v6-only-preferred option. This follows the usual practice of setting options. You can specify the
option value on pool, subnet, shared network, global levels or even specify it in host reservations.
v6-only-preferred option. This follows the usual practice of setting options. The
option value can be specified on pool, subnet, shared network, or global levels, or even
via host reservations.
Note there is no special processing involved. This follows the standard Kea option processing
regime. The option will not be sent back, unless the client explicitly requests it. For example, to
@ -4401,7 +4402,7 @@ to them.
} ]
}
In some cases the host reservations can be used in conjuction with client
In some cases the host reservations can be used in conjunction with client
classes specified within the Kea configuration. In particular, when a
host reservation exists for a client within a given subnet, the "KNOWN"
built-in class is assigned to the client. Conversely, when there is no
@ -4427,7 +4428,7 @@ evaluation of the class after the lease has been allocated and thus the
reserved class has been also assigned.
.. note::
Be aware that the classes specified in non global host reservations
Be aware that the classes specified in non-global host reservations
are assigned to the processed packet after all classes with the
``only-if-required`` parameter set to ``false`` have been evaluated.
This has an implication that these classes must not depend on the
@ -4539,8 +4540,8 @@ The ``reservation-mode`` parameter can be specified at:
``.Dhcp4["shared-networks"][].subnet4[]["reservation-mode"]`` (highest
priority: overrides all others)
For deciding what ``"reservation-mode"`` to choose, you may refer to the
following decision diagram:
To decide which ``"reservation-mode"`` to choose, the
following decision diagram may be useful:
::
@ -5125,24 +5126,24 @@ It is possible to control the ``ip-reservations-unique`` via the
the currently used backends (backends do not support the new setting),
the new setting is ignored and the warning log message is output.
The backends continue to use the default setting, i.e. expecting that
IP reservations are unique within each subnet. In order to allow
creating non unique IP reservations the administrator must remove
the backends which lack support for it from the configuration file.
IP reservations are unique within each subnet. To allow the
creation of non-unique IP reservations, the administrator must remove
the backends which lack support for them from the configuration file.
The administrators must be careful when they have been using multiple
reservations for the same IP address and later decided to return to
Administrators must be careful when they have been using multiple
reservations for the same IP address and later decide to return to
the default mode in which this is no longer allowed. The administrators
must make sure that at most one reservation for the given IP address
exists within a subnet prior to switching back to the default mode.
If such duplicates are left in the configuration file, the server
will report a configuration error. Leaving such reservations in the host
reports a configuration error. Leaving such reservations in the host
databases does not cause configuration errors but may lead to lease
allocation errors during the server operation when it unexpectedly
allocation errors during the server's operation, when it unexpectedly
finds multiple reservations for the same IP address.
.. note::
Currently the server does not verify if multiple reservations for
Currently the server does not verify whether multiple reservations for
the same IP address exist in the host databases (MySQL and/or
PostgreSQL) when ``ip-reservations-unique`` is updated from
``true`` to ``false``. This may cause issues with lease allocations.
@ -6385,14 +6386,14 @@ Beginning with Kea 1.7.7 the DHCPv4 server provides two global
parameters to control statistics default sample limits:
- ``statistic-default-sample-count`` - determines the default maximum
number of samples which will be kept. The special value of zero
means to use a default maximum age.
number of samples which are kept. The special value of zero
indicates that a default maximum age should be used.
- ``statistic-default-sample-age`` - determines the default maximum
age in seconds of samples which will be kept.
age in seconds of samples which are kept.
For instance to reduce the statistic keeping overhead you can set
the default maximum sample count to 1 so only one sample will be kept by:
For instance, to reduce the statistic keeping overhead, set
the default maximum sample count to 1 so only one sample is kept:
::

106
doc/sphinx/arm/dhcp6-srv.rst
View File

@ -670,9 +670,9 @@ entry, as in:
For additional Cassandra-specific parameters, see
:ref:`cassandra-database-configuration4`.
If the same host is configured both in-file and in-database, Kea won't warn of
the duplicate like it would if you specified them both in the same data source.
Instead the host configured in-file will have priority over the one configured
If the same host is configured both in-file and in-database, Kea does not issue a warning,
as it would if both were specified in the same data source.
Instead, the host configured in-file has priority over the one configured
in-database.
.. _read-only-database-configuration6:
@ -2717,18 +2717,18 @@ The default configuration and values would appear as follows:
}
As of Kea 1.7.1, there are two parameters which determine if kea-dhcp6
can generate DDNS requests to D2. The existing, ``dhcp-ddns:enable-updates``
parameter which now only controls whether kea-dhcp6 connects to D2.
And the new behavioral parameter, ``ddns-send-updates``, which determines
if DDNS updates are enabled at a given level (i.e global, shared-network,
or subnet). The following table shows how the two parameters function
can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates``
parameter, which now only controls whether kea-dhcp6 connects to D2;
and the new behavioral parameter, ``ddns-send-updates``, which determines
whether DDNS updates are enabled at a given level (i.e. global, shared-network,
or subnet). The following table shows how the two parameters function
together:
.. table:: Enabling and Disabling DDNS Updates
+-----------------+--------------------+-------------------------------+
| dhcp-ddns: | Global | Outcome |
| enable-updates | ddns-send-udpates | |
| enable-updates | ddns-send-updates | |
+=================+====================+===============================+
| false (default) | false | no updates at any scope |
+-----------------+--------------------+-------------------------------+
@ -2790,10 +2790,10 @@ conflict with existing entries owned by other DHCP6 clients.
FQDN while new entries for Client-B will still be added.
Disabling conflict resolution should be done only after careful review of
your specific use cases. The best way to avoid unwanted DNS entries is to
specific use cases. The best way to avoid unwanted DNS entries is to
always ensure leases changes are processed through Kea, whether they are
released, expire, or are deleted via the lease-del6 command, prior to
reassigning either FQDNs or IP addresses. Doing so will cause kea-dhcp6
reassigning either FQDNs or IP addresses. Doing so causes kea-dhcp6
to generate DNS removal requests to D2.
@ -3027,7 +3027,7 @@ follows:
"Dhcp6": {
...
"ddsn-replace-client-name": "always",
"ddns-replace-client-name": "always",
...
}
@ -3056,14 +3056,14 @@ are enabled. To set its value simply set it to the desired string:
...
}
When qualifying a partial name, kea-dhcp6 will construct the name in the
When qualifying a partial name, kea-dhcp6 constructs the name in the
format:
[**candidate-name**].[**ddns-qualifying-suffix**].
where **candidate-name** is the partial name supplied in the DHCPREQUEST.
For example, if the FQDN domain name value is "some-computer" and the
``ddsn-qualifying-suffix`` "example.com", the generated FQDN is:
``ddns-qualifying-suffix`` "example.com", the generated FQDN is:
**some-computer.example.com.**
@ -3093,12 +3093,12 @@ accomplished with the following two parameters:
- ``hostname-char-set`` - a regular expression describing the invalid
character set. This can be any valid, regular expression using POSIX
extended expression syntax. Embedded nuls (0x00) will always be
extended expression syntax. Embedded nulls (0x00) are always
considered an invalid character to be replaced (or omitted).
- ``hostname-char-replacement`` - a string of zero or more characters
with which to replace each invalid character in the host name. An empty
string and will cause invalid characters to be OMITTED rather than replaced.
string causes invalid characters to be OMITTED rather than replaced.
.. note::
@ -3107,10 +3107,10 @@ accomplished with the following two parameters:
- "hostname-char-set": "[^A-Za-z0-9.-]",
- "hostname-char-replacement": ""
This enables sanitizing and will omit any character that is not
a letter,digit, hyphen, dot or nul.
This enables sanitizing and omits any character that is not
a letter, digit, hyphen, dot, or null.
The following configuration will replace anything other than a letter,
The following configuration replaces anything other than a letter,
digit, hyphen, or dot with the letter 'x':
::
@ -3156,11 +3156,11 @@ qualifying suffix (if one is defined and needed).
.. note::
Since the 1.6.0 Kea release it is possible to specify hostname-char-set
Since the 1.6.0 Kea release, it is possible to specify hostname-char-set
and/or hostname-char-replacement at the global scope. This allows
to sanitize host names without requiring a dhcp-ddns entry. When
sanitizing of host names without requiring a dhcp-ddns entry. When
a hostname-char parameter is defined at the global scope and
in a dhcp-ddns entry the second (local) value is used.
in a dhcp-ddns entry, the second (local) value is used.
.. _dhcp6-dhcp4o6-config:
@ -3371,16 +3371,16 @@ pretty-printed for clarity):
information within Kea.
.. note::
It is possible that other hook libraries are already making use of
user-context. Enabling store-extended-info should not interfere with
any other user-context content so long as it does not also use an element
labled "ISC". In other words, user-context is intended to be a flexible
container serving mulitple purposes. As long as no other purpose also
It is possible that other hook libraries are already using
user-context. Enabling store-extended-info should not interfere with
any other user-context content, as long as it does not also use an element
labeled "ISC". In other words, user-context is intended to be a flexible
container serving multiple purposes. As long as no other purpose also
writes an "ISC" element to user-context there should not be a conflict.
.. _dhcp6-multi-threading-settings:
Multi-threading settings
Multi-Threading Settings
------------------------
The Kea server can be configured to process packets in parallel using multiple
@ -3411,16 +3411,16 @@ An example configuration that sets these parameter looks as follows:
...
}
Multi-threading settings in different backends
Multi-Threading Settings in Different Backends
----------------------------------------------
Both kea-dhcp4 and kea-dhcp6 are tested internally to determine which settings
gave the best performance. Although this section describes our results, those are just
give the best performance. Although this section describes our results, they are merely
recommendations and are very dependent on the particular hardware that was used
for testing. We strongly advice to run your own performance tests.
for testing. We strongly advise that administrators run their own performance tests.
Full report of Kea 1.7 performance results can be found `here <https://jenkins.isc.org/job/kea-1.7/job/performance/KeaPerformanceReport/>`_.
This includes hardware description, test scenario descriptions and
A full report of Kea 1.7 performance results can be found `here <https://jenkins.isc.org/job/kea-1.7/job/performance/KeaPerformanceReport/>`_.
This includes hardware descriptions, test scenario descriptions, and
current results.
After enabling multi-threading, the number of threads is set by ``thread-pool-size``
@ -3846,7 +3846,7 @@ to them.
} ]
}
In some cases the host reservations can be used in conjuction with client
In some cases the host reservations can be used in conjunction with client
classes specified within the Kea configuration. In particular, when a
host reservation exists for a client within a given subnet, the "KNOWN"
built-in class is assigned to the client. Conversely, when there is no
@ -3872,7 +3872,7 @@ evaluation of the class after the lease has been allocated and thus the
reserved class has been also assigned.
.. note::
Be aware that the classes specified in non global host reservations
Be aware that the classes specified in non-global host reservations
are assigned to the processed packet after all classes with the
``only-if-required`` parameter set to ``false`` have been evaluated.
This has an implication that these classes must not depend on the
@ -3984,8 +3984,8 @@ The ``reservation-mode`` parameter can be specified at:
``.Dhcp6["shared-networks"][].subnet6[]["reservation-mode"]`` (highest
priority: overrides all others)
For deciding what ``"reservation-mode"`` to choose, you may refer to the
following decision diagram:
To decide which ``"reservation-mode"`` to choose, the
following decision diagram may be useful:
::
@ -4557,25 +4557,25 @@ It is possible to control the ``ip-reservations-unique`` via the
the currently used backends (backends do not support the new setting),
the new setting is ignored and the warning log message is output.
The backends continue to use the default setting, i.e. expecting that
IP reservations are unique within each subnet. In order to allow
creating non unique IP reservations the administrator must remove
IP reservations are unique within each subnet. To allow the
creation of non-unique IP reservations, the administrator must remove
the backends which lack support for it from the configuration file.
The administrators must be careful when they have been using multiple
Administrators must be careful when they have been using multiple
reservations for the same IP address and/or delegated prefix and later
decided to return to the default mode in which this is no longer allowed.
decide to return to the default mode in which this is no longer allowed.
The administrators must make sure that at most one reservation for
the given IP address or delegated prefix exists within a subnet prior
to switching back to the default mode. If such duplicates are left in
the configuration file, the server will report a configuration error.
the configuration file, the server reports a configuration error.
Leaving such reservations in the host databases does not cause
configuration errors but may lead to lease allocation errors during
the server operation when it unexpectedly finds multiple reservations
the server operation, when it unexpectedly finds multiple reservations
for the same IP address or delegated prefix.
.. note::
Currently the server does not verify if multiple reservations for
Currently the server does not verify whether multiple reservations for
the same IP address and/or delegated prefix exist in the host
databases (MySQL and/or PostgreSQL) when ``ip-reservations-unique``
is updated from ``true`` to ``false``. This may cause issues with
@ -4932,7 +4932,7 @@ host reservation in this subnet or simply the initially selected subnet has no
more addresses available. Therefore, it is strongly recommended to always
specify subnet selectors (interface or a relay address) at shared network
level if the subnets belong to a shared network, as it is rarely useful to
specify them at the subnet level and it may lead to the configurtion errors
specify them at the subnet level and it may lead to the configuration errors
described above.
Client Classification in Shared Networks
@ -5459,7 +5459,7 @@ Using a Specific Relay Agent for a Subnet
=========================================
The DHCPv6 server follows the same principles as the DHCPv4 server to
select a subnet for the client with noticable differences mainly for
select a subnet for the client, with noticeable differences mainly for
relays.
.. note::
@ -5729,7 +5729,7 @@ default, the following syntax can be used:
The parameter is expressed in seconds, so the example above will
instruct the server to recycle declined leases after one hour.
There are several statistics and hook points associated with the Decline
There are several statistics and hook points associated with the decline
handling procedure. The lease6_decline hook is triggered after the
incoming DHCPDECLINE message has been sanitized and the server is about
to decline the lease. The declined-addresses statistic is increased
@ -6371,18 +6371,18 @@ The DHCPv6 server supports the following statistics:
This section describes DHCPv6-specific statistics. For a general
overview and usage of statistics, see :ref:`stats`.
Beginning with Kea 1.7.7 the DHCPv6 server provides two global
Beginning with Kea 1.7.7, the DHCPv6 server provides two global
parameters to control statistics default sample limits:
- ``statistic-default-sample-count`` - determines the default maximum
number of samples which will be kept. The special value of zero
means to use a default maximum age.
number of samples which are kept. The special value of zero
indicates that a default maximum age should be used.
- ``statistic-default-sample-age`` - determines the default maximum
age in seconds of samples which will be kept.
age in seconds of samples which are kept.
For instance to reduce the statistic keeping overhead you can set
the default maximum sample count to 1 so only one sample will be kept by:
For instance, to reduce the statistic keeping overhead, set
the default maximum sample count to 1 so that only one sample is kept:
::

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

@ -335,9 +335,9 @@ database:
}
}
The server tag must be unique accross all servers in the database. When the
The server tag must be unique across all servers in the database. When the
server information under the given server tag already exists, it is replaced
with the new information. The specified server tag is case insensitive. The
with the new information. The specified server tag is case-insensitive, and the
maximum length of the server tag is 256 characters. The following keywords are
reserved and must not be used as server tags: "all" and "any".
@ -1366,12 +1366,12 @@ belong. The `server-tags` parameter must not be specified for this command.
The remote-option6-pd-pool-set Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command creates a new prefix delefation pool specific DHCPv6 option or
This command creates a new prefix delegation pool-specific DHCPv6 option or
replaces an existing option in the database. The structure of the option
information is the same as in the Kea configuration file (see :ref:`dhcp4-std-options`
and :ref:`dhcp6-std-options`). The option information is carried in the
`options` list. Another list, `pd-pools`, contains a map with the prefix
delegation pool prefix and the prefix length identifying the pool. If such
delegation pool prefix and the prefix length identifying the pool. If such an
option already exists for the prefix delegation pool, it is replaced with
the new instance.
@ -1518,7 +1518,7 @@ option is deleted.
The following command attempts to delete an option having the
option code 5 in the top-level option space from the subnet
having an identifer of 123.
having an identifier of 123.
::
@ -1727,10 +1727,10 @@ be used by the "server1" and "server2":
}
}
The `server-tags` parameter is mandatory and it contains one or
more server tags. It may contain the keyword "all" to fetchg the subnets
The `server-tags` parameter is mandatory and contains one or
more server tags. It may contain the keyword "all", to fetch the subnets
associated with all servers. When the `server-tags` list
contains the `null` value the returned response contains a list
contains the `null` value, the returned response contains a list
of unassigned subnets, i.e. the subnets which are associated with no servers.
For example:

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

@ -238,12 +238,12 @@ The following is the list of all possible server states:
- ``partner-in-maintenance`` - an active server transitions to this state
after receiving a ``ha-maintenance-start`` command from the
administrator. The server in this state becomes responsible
for responding to all DHCP requests. The server sends
``ha-maintenance-notify`` command to the partner which is supposed
to enter the ``in-maintenance`` state. If that is the case, the server
for responding to all DHCP requests. The server sends a
``ha-maintenance-notify`` command to the partner, which should
enter the ``in-maintenance`` state. The server
remaining in the ``partner-in-maintenance`` state keeps sending lease
updates to the partner until it finds that the parter stops
responding to those lease updates, heartbeats or any other commands.
updates to the partner until it finds that the partner has stopped
responding to those lease updates, heartbeats, or any other commands.
In this case, the server in the ``partner-in-maintenance`` state
transitions to the ``partner-down`` state and keeps responding to
the queries, but no longer sends lease updates.
@ -259,7 +259,7 @@ The following is the list of all possible server states:
is still provisioned. This default configuration can be changed by
setting the ``wait-backup-ack`` configuration parameter to ``true``,
in which case the primary server always waits for the acknowledgements
and drops the DHCP query if sending any of the correponding lease
and drops the DHCP query if sending any of the corresponding lease
updates fails. This improves lease database consistency between the
primary and the secondary. However, if a communication failure between
the active server and any of the backups occurs, it effectively causes
@ -565,7 +565,7 @@ low a value for the ``max-unacked-clients`` parameter may result in a
transition to the ``partner-down`` state even though the partner is
still operating. On the other hand, selecting too high a value may
result in never transitioning to the ``partner-down`` state if the DHCP
traffic in the network is very low (e.g. at nighttime), because the number
traffic in the network is very low (e.g. at night), because the number
of distinct clients trying to communicate with the server could be lower
than the ``max-unacked-clients`` setting.
@ -879,16 +879,16 @@ mode, thus they are not specified here. For example: ``heartbeat-delay``,
should not be specified in the passive-backup mode. The ``wait-backup-ack``
is a boolean parameter not present in previous examples. It defaults to ``false`` and
must not be modified in the load-balancing and hot-standby modes. In the passive-backup
mode this parameter can be set to ``true`` which causes the primary server to expect
mode this parameter can be set to ``true``, which causes the primary server to expect
acknowledgments to the lease updates from the backup servers prior to responding
to the DHCP client. It ensures that the lease was propagated to all servers before
the client is given the lease, but it poses a risk of loosing a DHCP service if
to the DHCP client. It ensures that the lease has propagated to all servers before
the client is given the lease, but it poses a risk of losing a DHCP service if
there is a communication problem with one of the backup servers. This setting
also increases the latency of the DHCP response because of the time that the
also increases the latency of the DHCP response, because of the time that the
primary spends waiting for the acknowledgements. We recommend that the
``wait-backup-ack`` is left at its default value if the DHCP service reliability
``wait-backup-ack`` setting be left at its default value, if the DHCP service reliability
is more important than consistency of the lease information between the
primary and the backups and in all cases when the DHCP service latency should
primary and the backups, and in all cases when the DHCP service latency should
be minimal.
.. _ha-sharing-lease-info:
@ -1305,16 +1305,16 @@ the servers while the other one continues to respond to the DHCP queries.
When the upgraded server is back online, the upgrade can be performed for
the second server. The typical problem reported for the earlier versions
of the High Availability hooks library was that the administrator did not
have a direct control over the state of the DHCP server. Shutting down
one of the servers for maintenance didn't necessarily cause the other
server to start reponding to all DHCP queries because the failure
have direct control over the state of the DHCP server. Shutting down
one of the servers for maintenance did not necessarily cause the other
server to start responding to all DHCP queries, because the failure
detection algorithm described in :ref:`ha-scope-transition` requires that
the partner does not respond for a configured period of time and,
the partner not respond for a configured period of time and,
depending on the configuration, may also require that a number of DHCP
requests are not responded for a configured period of time. The
maintenance procedure, however, requires that the administrator is able
to instruct one of the servers to instantly start serving all DHCP clients
and the other server to instantly stop serving any DHCP clients so as it
requests are not responded to for a configured period of time. The
maintenance procedure, however, requires that the administrator be able
to instruct one of the servers to instantly start serving all DHCP clients,
and the other server to instantly stop serving any DHCP clients, so it
can be safely shut down.
The maintenance feature of the High Availability hooks library addresses
@ -1597,15 +1597,15 @@ to the failing server allows for detecting the failure.
The status-get Command
------------------------
The ``status-get`` is the general purpose command supported by several Kea deamons,
``status-get`` is a general-purpose command supported by several Kea daemons,
not only DHCP servers. However, when sent to the DHCP server with HA enabled, it
can be used to get insight into the details of the HA specific status information
of the servers being in the HA configuration. Not only does the response contain
the status information of the server receiving this command but also the
information about its partner, if this information is available.
can be used to get insight into the details of the HA-specific status information
of the servers used in the HA configuration. Not only does the response contain
the status information of the server receiving this command, but also the
information about its partner if it is available.
The following is the example response to the ``status-get`` command including
the HA status of two load balancing servers:
The following is an example response to the ``status-get`` command, including
the HA status of two load-balancing servers:
::

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

@ -280,17 +280,17 @@ The lease6-bulk-apply Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``lease6-bulk-apply`` was implemented to address
the performance penalty in the High Availability when a single DHCPv6
transaction resulted in multiple lease updates sent to the partner if
the performance penalty in the High-Availability mode when a single DHCPv6
transaction resulted in multiple lease updates sent to the partner, if
multiple address and/or prefix leases were allocated. Consider the case
when a DHCPv6 client requests the assignment of two IPv6 addresses and two IPv6
prefixes. That may result in allocation of 4 leases. In addition, the
DHCPv6 may assign different address than requested by the client during
the renew or rebind and delete the leases previously used by this client.
The are 6 of lease changes sent between the HA partners is in this case.
Sending these updates in individual commands, e.g. ``lease6-update``
is highly inefficient and produces unnecessary delays in communication
between the HA partners and in sending the response to the DHCPv6 client.
prefixes: that may result in allocation of 4 leases. In addition,
DHCPv6 may assign a different address than the one requested by the client during
the renew or rebind stage, and delete the leases previously used by this client.
There are six lease changes sent between the HA partners in this case.
Sending these updates in individual commands, e.g. via ``lease6-update``,
is highly inefficient and produces unnecessary delays in communication,
both between the HA partners and in sending the response to the DHCPv6 client.
The ``lease6-bulk-apply`` command deals with this
problem by aggregating all lease changes in a single command. Both
@ -299,7 +299,7 @@ The receiving server iterates over the deleted leases and deletes them
from its lease database. Next, it iterates over the new/updated leases
and adds them to the database or updates them if they already exist.
Even though the High Avialability is the major application for
Even though High Availability is the major application for
this command, it can be freely used in all cases when it is desired to
send multiple lease changes in a single command.
@ -342,10 +342,10 @@ or update two other leases in the database:
}
If any of the leases is malformed, no leases changes are applied
to the lease database. If the leases are well formed but there is a
to the lease database. If the leases are well-formed but there is a
failure to apply any of the lease changes to the database, the command
will continue to be processed for other leases. All the leases for which
the command was unable to apply the changes in the database will be
continues to be processed for other leases. All the leases for which
the command was unable to apply the changes in the database are
listed in the response. For example:
::

20
doc/sphinx/arm/hooks-lease-query.rst
View File

@ -86,19 +86,19 @@ In addition, one or more of the following options will be included:
+------------------------------+-------+-----------------------------------------------+
| Option | Code | Content |
+==============================+=======+===============================================+
| dhcp-client-identifier | 61 | copied from the lease (if one) |
| dhcp-client-identifier | 61 | copied from the lease (if appropriate) |
+------------------------------+-------+-----------------------------------------------+
| client-last-transaction-time | 91 | amount of time that has elapsed since the |
| | | lease's client-last-transaction-time (CLTT) |
| | | This value will also be used by the server to |
| | | adjust life time and timer values. |
| client-last-transaction-time | 91 | the amount of time that has elapsed since the |
| | | lease's client-last-transaction-time (CLTT). |
| | | This value is also used by the server to |
| | | adjust lifetime and timer values. |
+------------------------------+-------+-----------------------------------------------+
| dhcp-lease-time | 51 | lease's life time reduced by CLTT |
| dhcp-lease-time | 51 | lease's lifetime reduced by CLTT |
+------------------------------+-------+-----------------------------------------------+
| dhcp-renewal-time | 58 | as controlled by kea-dhcp4 configuration and |
| | | then reduced by CLTT |
+------------------------------+-------+-----------------------------------------------+
| dhcp-rebind-time | 59 | as dictacted by kea-dhcp4 configuration and |
| dhcp-rebind-time | 59 | as dictated by kea-dhcp4 configuration and |
| | | then reduced by CLTT |
+------------------------------+-------+-----------------------------------------------+
| dhcp-agent-options | 82 | if stored on the lease. (See |
@ -288,9 +288,9 @@ The client-data option will encapsulate the following options:
| | | - preferred life time reduced by CLTT |
+------------------------------+-------+-----------------------------------------------+
If the lease with the most recent CLTT value (Client Last
Transmission Time) has relay information in it's user-context (see
:ref:`store-extended-info-v6`), then an OPTION_LQ_RELAY_DATA option will be
If the lease with the most recent client-last-transaction-time (CLTT)
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>`__).

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

@ -111,7 +111,7 @@ To download and compile Boost 1.65, please use the following commands:
.. code-block:: console
$ wget -nd https://dl.bintray.com/boostorg/release/1.65.1/source/boost_1_65_1.tar.gz
$ tar zxvf boost_1_65_1.tar.gz
$ tar -zxvf boost_1_65_1.tar.gz
$ cd boost_1_65_1/
$ ./bootstrap.sh
$ ./b2 --without-python
@ -137,7 +137,7 @@ Choice 2: get a tarball and extract it
.. parsed-literal::
$ tar zxvf kea-|release|.tar.gz
$ tar -zxvf kea-|release|.tar.gz
The next step is to extract the premium Kea package that contains the
RADIUS repository into the Kea sources. After the tarball is extracted,
@ -146,7 +146,7 @@ the Kea sources should have a premium/ subdirectory.
.. parsed-literal::
$ cd kea
$ tar zxvf ../kea-premium-radius-|release|.tar.gz
$ tar -zxvf ../kea-premium-radius-|release|.tar.gz
Once this is done, verify that the Kea sources look similar to this:
@ -283,7 +283,7 @@ Please make sure that the compilation includes the following:
- FreeRADIUS client directories printed and pointing to the right
directories;
- Boost version at least 1.65.1. The versions available in CentOS 7
(1.48 and and 1.53) are too old.
(1.48 and 1.53) are too old.
Once the configuration is complete, compile Kea using make. If the
system has more than one core, using the "-j N"

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

@ -86,7 +86,7 @@ Unpack this tarball:
.. parsed-literal::
$ tar zxvf kea-|release|.tar.gz
$ tar -zxvf kea-|release|.tar.gz
This will unpack the tarball into the kea-|release| subdirectory of
the current working directory.
@ -99,7 +99,7 @@ steps will unpack the premium tarball into the correct location:
.. parsed-literal::
$ cd kea-|release|
$ tar xvf ../kea-premium-|release|.tar.gz
$ tar -xvf ../kea-premium-|release|.tar.gz
Note that unpacking the Kea premium package will put the files into a
directory named "premium". Regardless of the name of the package, the
@ -390,7 +390,7 @@ loaded by the correct process per the table below.
| | |load balancing and is sometimes referred to as |
| | |active-active. Each server can handle selected group of |
| | |clients in this network or all clients, if it detects that |
| | |its partner has became unavailable. It is also possible to |
| | |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 |
@ -406,7 +406,7 @@ loaded by the correct process per the table below.
| | |for Kea DHCP servers. |
+-----------------+---------------+------------------------------------------------------------+
| Statistics | Kea sources |The Statistics Commands library provides additional |
| Commands | (since 1.4) |commmands for retrieving accurate DHCP lease statistics for |
| Commands | (since 1.4) |commands for retrieving accurate DHCP lease statistics for |
| | |Kea DHCP servers that share the same lease database. This |
| | |setup is common in deployments where DHCP service redundancy|
| | |is required and a shared lease database is used to avoid |
@ -2977,8 +2977,8 @@ entries at the beginning of maps, but this was withdrawn in 1.7.9.
As of Kea 1.3, the structures that allow user contexts are pools of all
types (addresses and prefixes) and subnets. Kea 1.4 extended user
context support to the global scope, interfaces config, shared networks,
subnets, client classes, option datas and definitions, host
reservations, control socket, dhcp ddns, loggers and server id. These
are supported in both DHCPv4 and DHCPv6, with the exception of server id
context support to the global scope, interfaces configuration, shared networks,
subnets, client classes, option data and definitions, host
reservations, control socket, dhcp ddns, loggers and server ID. These
are supported in both DHCPv4 and DHCPv6, with the exception of server ID
which is DHCPv6 only.

116
doc/sphinx/arm/install.rst
View File

@ -7,13 +7,13 @@ Installation
Packages
========
Starting with Kea 1.6.0, ISC now publishes native RPM, deb and APK
packages along with the tarballs with the source code. The packages
Starting with Kea 1.6.0, ISC now 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. You can download the native packages
and install them using the system available in your distribution (such
as dpkg or rpm). Also, you can add the Kea repository to your system,
which will make it easier to install updates. For details, please
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.
@ -63,9 +63,9 @@ various development include headers and program development tools.
.. note::
Some operating systems have split their distribution packages into a
run-time and a development package. You will need to install the
run-time and a development package. The
development package versions, which include header files and
libraries, to build Kea from the source code.
libraries, must be installed to build Kea from the source code.
Building from source code requires the following software installed on
the system:
@ -137,7 +137,7 @@ Although Kea may be available in pre-compiled, ready-to-use packages
from operating system vendors, it is open source software written in
C++. As such, it is freely available in source code form from ISC as a
downloadable tar file. The source code can also be obtained from the Kea
Gitlab repository at https://gitlab.isc.org/isc-projects/kea. This
GitLab repository at https://gitlab.isc.org/isc-projects/kea. This
section describes how to build Kea from the source code.
Download Tar File
@ -146,7 +146,7 @@ Download Tar File
The Kea release tarballs may be downloaded from:
https://downloads.isc.org/isc/kea/ .
Retrieve from Git
Retrieve From Git
-----------------
Downloading this "bleeding edge" code is recommended only for developers
@ -176,13 +176,13 @@ files. They can be created by running ``autoreconf`` with the
``--install`` switch. This will run ``autoconf``, ``aclocal``,
``libtoolize``, ``autoheader``, ``automake``, and related commands.
Write access to the Kea repository is only granted to ISC staff. If you
are a developer planning to contribute to Kea, please check our
Write access to the Kea repository is only granted to ISC staff.
Developers planning to contribute to Kea, should check our
`Contributor's
Guide <https://gitlab.isc.org/isc-projects/kea/blob/master/contributors-guide.md>`__.
The `Kea Developer's
Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/>`__ contains more
information about the process, as well as describes the requirements for
information about the process, and describes the requirements for
contributed code to be accepted by ISC.
.. _configure:
@ -255,11 +255,11 @@ options. Some commonly used options are:
This option requires subscription-only RADIUS hook.
- ``--with-freeradius-dictionary``
Specifies a non-standard location for a FreeRADIUS dictionary file. That
Specify a non-standard location for a FreeRADIUS dictionary file. That
file contains list of supported RADIUS attributes. Available in subscriber
only version. This option requires subscription-only RADIUS hook.
If you don't see the RADIUS options, make sure you have RADIUS hook sources in
If the RADIUS options are not available, ensure that the RADIUS hook sources are in
the ``premium`` directory and rerun ``autoreconf -i``.
.. note::
@ -267,15 +267,15 @@ the ``premium`` directory and rerun ``autoreconf -i``.
The ``--runstatedir`` in the installation directories is particular.
There are three cases:
- You use autoconf 2.70 or greater which supports this, but this autoconf
- The system uses autoconf 2.70 or greater which supports this, but this autoconf
version has not been released yet.
- You use autoconf 2.69 patched to add support of this. In this case and the
previous simply use when needed the``--runstatedir`` configure parameter.
- The system uses autoconf 2.69 patched to add this support. In this case and the
previous, simply use the ``--runstatedir`` configure parameter when needed.
- There is no support (the configure parameter is not recognized and configure
directly raises an error). For autoconf 2.69 the ``runstatedir`` environment
variable is supported so simply remove the ``--`` before ``runstatedir``
variable is supported, so simply remove the ``--`` before ``runstatedir``
in the configure script call, e.g.: ``./configure runstatedir=/opt/run ...``
..
@ -292,14 +292,14 @@ developers, or people who want to extend Kea code or send patches:
- ``--with-gtest``, ``--with-gtest-source``
Enable the building of the C++ Unit Tests using the Google Test
framework. This option specifies the path to the gtest source. (If
the framework is not installed on your system, it can be downloaded
the framework is not installed on the system, it can be downloaded
from https://github.com/google/googletest.)
- ``--enable-generate-docs``
Enable the rebuilding Kea documentation. ISC publishes Kea
documentation for each release; however, in some cases you may want
to rebuild it. For example, if you want to change something in the
docs, or want to generate new ones from git sources that are not
documentation for each release; however, in some cases it may be
desirable to rebuild it: for example, to change something in the
docs, or to generate new ones from git sources that are not
released yet.
- ``--enable-generate-parser``
@ -307,23 +307,23 @@ developers, or people who want to extend Kea code or send patches:
and bison (.yy files). Kea sources have C++/h files generated out
from them. By default Kea does not use flex or bison to avoid
requiring installation of unnecessary dependencies for users.
However, if you change anything in the parses (such as adding a new
parameter), you will need to use flex and bison to regenerate
parsers. This option lets you do that.
However, anything in the parses is changed (such as adding a new
parameter), flex and bison are required to regenerate
parsers. This option permits that.
- ``--enable-generate-messages``
Enable the regeneration of messages files from their messages source
files, e.g. regenerate xxx_messages.h and xxx_messages.cc from
xxx_messages.mes using the Kea message compiler. By default Kea is
built using these .h and .cc files from the distribution. However, if
you change anything in a .mes file (such as adding a new message), you
will need to build and use the Kea message compiler. This option lets
you do that.
anything in a .mes file is changed (such as adding a new message),
the Kea message compiler needs to be built and used. This option
permits that.
- ``--with-benchmark``, ``--with-benchmark-source``
Enable the building of the database backend benchmarks using the
Google Benchmark framework. This option specifies the path to the
gtest source. (If the framework is not installed on your system, it
gtest source. (If the framework is not installed on the system, it
can be downloaded from https://github.com/google/benchmark.)
This support is experimental.
@ -338,9 +338,10 @@ enabled, and sets the installation location to /opt/kea:
--with-pgsql=/usr/local/bin/pg_config \
--prefix=/opt/kea
If you have any problems with building Kea using the header-only Boost
code, or you'd like to use the Boost system library (assumed for the
sake of this example to be located in /usr/pkg/lib):
Users who have any problems with building Kea using the header-only Boost
code, or who would like to use the Boost system library (assumed for the
sake of this example to be located in /usr/pkg/lib), should issue these
commands:
.. code-block:: console
@ -384,7 +385,7 @@ errors.
If required, run ``ldconfig`` as root with ``/usr/local/lib`` (or with
prefix/lib if configured with --prefix) in ``/etc/ld.so.conf`` (or the
relevant linker cache configuration file for your OS):
relevant linker cache configuration file for the OS):
.. code-block:: console
@ -394,7 +395,7 @@ relevant linker cache configuration file for your OS):
.. note::
If you do not run ``ldconfig`` where it is required, you may see
If ``ldconfig`` is not run where required, users may see
errors like the following:
::
@ -406,13 +407,13 @@ relevant linker cache configuration file for your OS):
Cross-Building
--------------
It is possible to cross-build Kea, i.e. to create binaries in another
system (the ``build`` system) than the system where Kea will run
It is possible to cross-build Kea, i.e. to create binaries in a separate
system (the ``build`` system) from the one where Kea runs
(the ``host`` system).
It is outside of the scope of common administrator operations and requires
some developer skills so the Developer Guide explains how to do that
using a x86_64 Linux system to build Kea for a Raspberry Pi box running
some developer skills, so 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
<https://jenkins.isc.org/job/Kea_doc/doxygen/de/d9a/crossCompile.html>`__.
@ -442,7 +443,7 @@ optional backends and the creation of the lease database.
Building with MySQL Support
---------------------------
Install MySQL according to the instructions for your system. The client
Install MySQL according to the instructions for the system. The client
development libraries must be installed.
Build and install Kea as described in :ref:`installation`,
@ -468,7 +469,7 @@ database configuration.
Building with PostgreSQL support
--------------------------------
Install PostgreSQL according to the instructions for your system. The
Install PostgreSQL according to the instructions for the system. The
client development libraries must be installed. Client development
libraries are often packaged as "libpq".
@ -494,11 +495,11 @@ database configuration.
Building with CQL (Cassandra) Support
-------------------------------------
Install Cassandra according to the instructions for your system. The
Install Cassandra according to the instructions for the system. The
Cassandra project website contains useful pointers:
https://cassandra.apache.org.
If you have a cpp-driver package available as binary or as source,
If a cpp-driver package is available as binary or as source,
simply install or build and install the package. Then build and install
Kea as described in :ref:`installation`. To enable the
Cassandra (CQL) database code, at the "configure" step (see :ref:`configure`), enter:
@ -507,10 +508,10 @@ Cassandra (CQL) database code, at the "configure" step (see :ref:`configure`), e
$ ./configure [other-options] --with-cql=path-to-pkg-config
Note if ``pkg-config`` is at its standard location (and thus in the
shell path) you do not need to supply its path. If it does not work
Note that if ``pkg-config`` is at its standard location (and thus in the
shell path), the path does not need to be specified. If it does not work
(e.g. no pkg-config, package not available in pkg-config with the
cassandra name), you can still use the ``cql_config`` script in tools/
cassandra name), the ``cql_config`` script in tools/ can still be used
as described below.
Download and compile cpp-driver from DataStax. For details regarding
@ -533,7 +534,7 @@ but, until that is complete, intermediate steps need to be conducted. A
cql_config script is present in the tools/ directory of the Kea sources.
Before using it, please create a cql_config_defines.sh file in the same
directory (there is an example available in cql_config_define.sh.sample;
you may copy it over to cql_config_defines.sh and edit the path
copy it over to cql_config_defines.sh and edit the path
specified in it) and change the environment variable CPP_DRIVER_PATH to
point to the directory where the cpp-driver sources are located. Make
sure that appropriate access rights are set on this file. It should be
@ -565,7 +566,7 @@ First, a regular user account must be created:
useradd admin
Then, change the binaries ownership and group to new user. Note your path may be different. Please
Then, change the binaries ownership and group to new user. Note that the specific path may be different. Please
refer to the ``--prefix`` parameter passed to the configure script.:
.. code-block:: console
@ -577,7 +578,7 @@ refer to the ``--prefix`` parameter passed to the configure script.:
chown -R admin /var/log/kea-dhcp6.log
chgrp -R admin /var/log/kea-dhcp6.log
Assuming you are using systemd, you also should modify its service file
If using systemd, modify its service file
(e.g. /etc/systemd/system/kea-dhcp6.service):
.. code-block:: console
@ -595,19 +596,18 @@ more information.
setcap 'cap_net_bind_service=+ep' /opt/kea/sbin/kea-dhcp6
After this step is complete, the admin user should be able to run Kea. Note that DHCPv4 server by
default opens raw sockets. If your network is only using relayed traffic, you can instruct Kea to
default opens raw sockets. If the network is only using relayed traffic, Kea can be instructed to
use regular UDP sockets (refer to ``dhcp-socket-type`` parameter in the
:ref:`dhcp4-interface-configuration` section) and the ``cap_net_raw`` capability can be skipped.
.. note::
An alternative approach to avoiding running Kea with root privileges assumes instructing Kea to
use non-privileged (greater than 1024) posts and redirecting traffic. This, however, will work
only for relayed traffic. This approach in general is considered experimental and not tested
enough for deployment in production environment. Use with caution!
An alternative approach to running Kea with root privileges is to configure Kea to use
non-privileged ports (i.e. those greater than 1024) and redirecting traffic. Note that this
only works for relayed traffic. Furthermore, we consider it experimental and untested in
production environments. Use it only after careful consideration.
To use this approach, configure the server to listen on other non privileged port (eg: 1547
To use this approach, configure the server to listen on other non-privileged ports (e.g. 1547
and 1548) by running the process with ``-p`` option in ``/etc/systemd/system/kea-dhcp4.service``:
.. code-block:: console
@ -620,8 +620,8 @@ and ``/etc/systemd/system/kea-dhcp4.service``:
ExecStart=/opt/kea/sbin/kea-dhcp6 -d -c /etc/kea/kea-dhcp6.conf -p 1547
and then configure port redirection with iptables and ip6tables for new ports (eg: 1547
and 1548). Make sure you replace ens4 with your specific interface name.
and then configure port redirection with iptables and ip6tables for new ports (e.g. 1547
and 1548). Be sure to replace ens4 with the specific interface name.
.. code-block:: console

6
doc/sphinx/arm/lease-expiration.rst
View File

@ -8,7 +8,7 @@ The primary role of the DHCP server is to assign addresses and/or
delegate prefixes to DHCP clients. These addresses and prefixes are
often referred to as "leases." Leases are typically assigned to clients
for a finite amount of time, known as the "valid lifetime." DHCP clients
who wish to continue using their assigned leases will periodically renew
who wish to continue using their assigned leases periodically renew
them by sending the appropriate message to the DHCP server. The DHCP
server records the time when these leases are renewed and calculates new
expiration times for them.
@ -75,11 +75,11 @@ The following list presents all configuration parameters pertaining to
processing expired leases with their default values:
- ``reclaim-timer-wait-time`` - this parameter governs intervals
between the completion of the previous reclaimation cycle and the start of the
between the completion of the previous reclamation cycle and the start of the
next one. Specified in seconds. The default value is 10 [seconds].
- ``flush-reclaimed-timer-wait-time`` - this parameter controls how
often the server initiates the lease reclaimation procedure. Expressed in
often the server initiates the lease reclamation procedure. Expressed in
seconds. The default value is 25 [seconds].
- ``hold-reclaimed-time`` - this parameter governs how long the lease

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

@ -598,14 +598,14 @@ The pattern (string) Option
This option can be used to specify the layout pattern of log messages for
a logger. Kea logging is implemented using the Log4Cplus library and whose
output formatting is based, conceptually, on the printf formatting from C
and is discussed in detail in the the next section
and is discussed in detail in the next section
:ref:`logging-message-format`.
Each output type (stdout, file, or syslog) has a default ``pattern`` which
describes the content of its log messages. This parameter can be used to
specifiy your own pattern. The pattern for each logger is governed
individually so each configured logger can have it's own pattern. Omitting
the ``pattern`` parameter or setting it to an empty string, "", will cause
specify a desired pattern. The pattern for each logger is governed
individually so each configured logger can have its own pattern. Omitting
the ``pattern`` parameter or setting it to an empty string, "", causes
Kea to use the default pattern for that logger's output type.
In addition to the log text itself, the default patterns used for ``stdout``
@ -644,7 +644,7 @@ below:
"%D{%Y-%m-%d %H:%M:%S.%q} %-5p [%c/%i.%t] %m\n";
and a typical log produced by this pattern would look somethng like this:
and a typical log produced by this pattern looks something like this:
::

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

@ -50,7 +50,7 @@ For detailed installation instructions, see the `CentOS installation notes page
CentOS 7.5's gcc compiler (version 4.8.5) is very old. Some Sysrepo
dependencies require at least version 4.9, which unfortunately means
that a new compiler has to be installed. Also, many of the Sysrepo
dependencies are not avalable in CentOS as packages, so for the time
dependencies are not available in CentOS as packages, so for the time
being they must be installed from sources.
Quick Sysrepo Overview

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

@ -24,7 +24,7 @@ Quick Start Guide for using tarball
.. parsed-literal::
$ tar xvzf kea-|release|.tar.gz
$ tar -xvzf kea-|release|.tar.gz
4. Go into the source directory and run the configure script:

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

@ -113,7 +113,7 @@ servers, the default empty path in the URL is not enough, so the
$ kea-shell --host 192.0.2.1 --port 8001 --path kea ...
The Kea shell requires Python to to be installed on the system. It has been
The Kea shell requires Python to be installed on the system. It has been
tested with Python 2.7 and various versions of Python 3, up to 3.5.
Since not every Kea deployment uses this feature and there are
deployments that do not have Python, the Kea shell is not enabled by

63
doc/sphinx/arm/stork.rst
View File

@ -1,49 +1,50 @@
.. _stork:
*************************
Monitoring Kea with Stork
Monitoring Kea With Stork
*************************
It is usually desired to monitor running Kea services. Kea exposes many sources of informations:
configuration files, API, statistics, logs, open database content and more. It may be sometimes
overwhelming to keep up. ISC started the Stork project to address this problem for both Kea
and BIND 9. Stork can address a variety of scenarios:
Most administrators want to be able to monitor any Kea services that are running. Kea offers so many
pieces of information - configuration files, API, statistics, logs, open database content, and more -
that it may sometimes
be overwhelming to keep up. ISC's Stork project is intended to address this problem for both Kea
and BIND 9. Stork is useful in a variety of scenarios:
- you can use Stork as a dashboard. It provides you with an insight into what exactly is going
on with your servers. In particular, it can provide up to date details regarding pool
utilization in your subnets and shared networks, can monitor state of your HA pair (and
provide extra insight in case of failover and recovery events), lets you list, filter and
search for specific host reservations and more. For this capability, you need to deploy
a single Stork server and one Stork agent on each machine you want to monitor.
- Stork can be used as a dashboard. It provides insight into what exactly is happening
on the servers. In particular, it allows users to: see up-to-date details regarding pool
utilization in subnets and shared networks; monitor the state of the HA pair (and
provide extra insight in case of failover and recovery events); list, filter, and
search for specific host reservations; and more. Only
a single Stork server needs to be deployed, and one Stork agent on each machine to be monitored.
- you can use Stork agent to integrate Kea with Prometheus and Grafana. Once you deploy a Stork
agent, it starts acting as Prometheus exporter. If you deploy Prometheus in your network, you
will be able to visualize statistics as time-series using Grafana.
- The Stork agent can integrate Kea with Prometheus and Grafana. Once the Stork
agent is active on the server, it serves as a Prometheus exporter. Users who have deployed
Prometheus in their networks can visualize statistics as time series using Grafana.
- you can do both of the above. If you have Grafana deployed in your network, you can let Stork
know its location. In this configuration, Stork will let you inspect the current status and
will provide a customized link to Grafana to see how a given property behaved over time.
- Stork can act as both a dashboard and an integrator for Prometheus/Grafana. Once Stork
is linked to where Grafana is deployed on the network, users can inspect the current status and
visit a customized link to Grafana to see how a given property behaves over time.
Stork is available in source code, but also as native Deb and RPM packages, which makes it easy
to install on most popular systems. For more details, please see
`Stork ARM <https://stork.readthedocs.io>`_ or `Stork project page <https://gitlab.isc.org/isc-projects/stork>`_.
The former has a nice collection of screenshots that is frequently updated. It will let you quickly
formulate a first impression of what is currently available. Stork is being rapidly developed with
monthly release. Please check back frequently.
Stork is available as source code, but also as native deb and RPM packages, which makes it easy
to install on most popular systems. For more details, please see the
`Stork ARM <https://stork.readthedocs.io>`_ or the `Stork project page <https://gitlab.isc.org/isc-projects/stork>`_.
The former has a nice collection of screenshots that is frequently updated, to give users
an impression of what is currently available. Stork is in the midst of full development with
monthly releases, so please check back frequently.
.. _grafana:
.. _prometheus:
Kea statistics in Grafana
Kea Statistics in Grafana
=========================
The ISC Stork project provides an agent, that can be deployed along side Kea and BIND 9. It will
expose Kea statistics in a format that's acceptable by Prometheus.
One of the major benefits of Prometheus is that it turns repeated one time observation into time series,
which lets you monitor how certain behaviors change over time. It is easy to use other tools
to visualize data available in Prometheus. The most common approach is to use
The ISC Stork project provides an agent that can be deployed alongside Kea and BIND 9. It
exposes Kea statistics in a format that is accepted by Prometheus.
One of the major benefits of Prometheus is that it turns repeated one-time observations into time series,
which lets users monitor how certain behaviors change over time. It is easy to use other tools
to visualize data available in Prometheus; the most common approach is to use
Grafana to provide visual dashboards. The Stork project provides dashboard
definitions for Kea and BIND 9 that can be imported into Grafana very easily.
You can learn more about Prometheus and Grafana on their websites: `Prometheus homepage <https://prometheus.io/>`_
and `Grafana homepage <https://grafana.com/>`_.
Learn more about Prometheus and Grafana on their websites: `Prometheus <https://prometheus.io/>`_
and `Grafana <https://grafana.com/>`_.