mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-22 09:57:41 +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 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 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 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. buffer can contain) is configurable.
@section custom-implementations Custom Packet Queues @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 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 source of servers' configurations and host reservations (i.e. static
assignments of addresses, prefixes, options, etc.). Kea assignments of addresses, prefixes, options, etc.). Kea
updates introduce changes to the database schemas to faciliate new updates introduce changes to the database schemas to faciliate new
@ -213,7 +213,7 @@ To create the database:
4. Create the database. 4. Create the database.
You'll need to exit mysql client Exit the MySQL client
.. code-block:: mysql .. 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 $ 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 While it is possible to create the database from within the MySQL client, we recommend
use the kea-admin tool as it performs some necessary validations to ensure Kea can 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 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 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 manually. An additional check examines the user's ability to create functions and
triggers. If you encounter the following error: triggers. The following error indicates that the user does not have the necessary
permissions to create functions or triggers:
.. code-block:: console .. code-block:: console
@ -241,23 +242,22 @@ To create the database:
mysql: [Warning] Using a password on the command line interface can be insecure. mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR/kea-admin: Create failed, the user, keatest, has insufficient privileges. 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
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:
via mysql client. Note you must do this as a user with SUPER privileges:
.. code-block:: mysql .. code-block:: mysql
mysql> set @@global.log_bin_trust_function_creators = 1; mysql> set @@global.log_bin_trust_function_creators = 1;
Query OK, 0 rows affected (0.00 sec) 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 .. code-block:: mysql
mysql> CONNECT database-name; mysql> CONNECT database-name;
mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql 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: The database may also be dropped manually as follows:
@ -266,10 +266,10 @@ To create the database:
mysql> CONNECT database-name; mysql> CONNECT database-name;
mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_drop.mysql 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:: .. 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: 5. Exit MySQL:
@ -323,10 +323,9 @@ earlier version. To perform an upgrade, issue the following command:
.. note:: .. note::
To search host reservations by hostname it is critical the collation of To search host reservations by hostname it is critical that the collation of
the hostname column in the host table to be case-insensitive. Fortunately the hostname column in the host table be case-insensitive. Fortunately, that
the default collation in MySQL is case-insensitive. You can verify this is the default in MySQL, but it can be verified via this command:
on your MySQL installation by:
.. code-block:: mysql .. code-block:: mysql
@ -337,7 +336,7 @@ earlier version. To perform an upgrade, issue the following command:
| utf8_general_ci | | 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. the collation is case-insensitive.
.. _mysql-performance: .. _mysql-performance:
@ -345,8 +344,8 @@ earlier version. To perform an upgrade, issue the following command:
Simple MySQL tweak to gain performance Simple MySQL tweak to gain performance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Changing MySQL internal value ``innodb_flush_log_at_trx_commit`` from default value Changing the MySQL internal value ``innodb_flush_log_at_trx_commit`` from the default value
``1`` to ``2`` can result with huge gain in Kea performance. It can be set per session for testing: ``1`` to ``2`` can result in a huge gain in Kea performance. It can be set per session for testing:
.. code-block:: mysql .. code-block:: mysql
@ -361,7 +360,7 @@ or permanently in ``/etc/mysql/my.cnf``:
innodb_flush_log_at_trx_commit=2 innodb_flush_log_at_trx_commit=2
Be aware that changing this value can result with problems during data recovery 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: .. _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 Comments and User Context
------------------------- -------------------------
You can specify shell, C or C++ style comments in the JSON configuration file if Shell, C, or C++ style comments are all permitted in the JSON configuration file if
you use the file locally. This is convenient and works in simple cases where the file is used locally. This is convenient and works in simple cases where
your configuration is kept statically using local file. However, since comments the configuration is kept statically using a local file. However, since comments
are not part of JSON syntax, most JSON tools will detect them as are not part of JSON syntax, most JSON tools detect them as
errors. Another problem with them is once Kea loads its configuration, the errors. Another problem with them is that once Kea loads its configuration, the
shell, C and C++ style comments are ignored. If you use commands such as shell, C, and C++ style comments are ignored. If commands such as
`config-get` or `config-write`, those comments will be lost. An example of such `config-get` or `config-write` are used, those comments are lost. An example of such
comments has been presented in the previous section. 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 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: 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 However, the facts that the comment could only be a single line, and that it was not
possible to add any other information in more structured form. One specific 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 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 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 allows adding arbitrary JSON structure to most Kea configuration structures. It
has a number of benefits compared to earlier approaches. First, it is fully 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 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 comment strings, but it can also store much more complex data, such as
multiple lines (as string array), extra typed data (such as floor numbers being 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's possible 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 to develop third-party hooks that take advantage of that extra information. An
example user context would look like this: 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 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. 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 The is one side effect, however. If the configuration uses the old JSON
comment, the `config-get` command will return a slightly modified comment, the `config-get` command returns a slightly modified
configuration. Don't be surprised if you call `config-set` followed by a configuration. It is not uncommon for a call for `config-set` followed by a
`config-get` and receive a slightly different structure. If this bothers you, `config-get` to receive a slightly different structure.
the best way to avoid this problem is simply abandon JSON comments and start The best way to avoid this problem is simply to abandon JSON comments and
using user-context. use user context.
For a discussion about user context used in hooks, see :ref:`user-context-hooks`. 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 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 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 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 number of packets the buffer can contain, is configurable. A reasonable
starting point would be to match the capacity to the number of leases 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 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. numeric value with which the server process will exit to the system.
The default value is zero. 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: the process cleans up on exit. The supported shutdown types are:
- "normal" - Stops the queue manager and finishes all current transactions - "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 The ``high-availability`` information is returned only when the command is
sent to the DHCP servers being in the HA setup. This parameter 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 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 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 when the command is sent to DHCP servers with multi-threading enabled. These two
parameters and ``multi-threading-enabled`` are never returned when the 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 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. section.

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

@ -4,31 +4,31 @@
Database Connectivity Database Connectivity
********************* *********************
Kea servers (kea-dhcp4 and kea-dhcp6) can be configured to use a variety of 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 configured to support automatic recovery when connectivity is lost (see
``max-reconnect-tries`` and ``reconnect-wait-time``). ``max-reconnect-tries`` and ``reconnect-wait-time``).
It is important to understand how and when automatic recovery comes into play. It is important to understand how and when automatic recovery comes into play.
Automatic recovery, when configured, only operates after a successful start up Automatic recovery, when configured, only operates after a successful startup
or reconfiguration during which connectivity to all back ends has been or reconfiguration during which connectivity to all backends has been
successfully established. successfully established.
During server start up the inability to connect to any of the configured back During server startup, the inability to connect to any of the configured
ends is always considered fatal. A fatal error will be logged and the server backends is always considered fatal. A fatal error is logged and the server
will exit. This is done based on the idea that configuration should be valid exits, based on the idea that the configuration should be valid
at start up. Exiting to the operating system allows nanny scripts to detect at startup. Exiting to the operating system allows nanny scripts to detect
the problem. the problem.
During dynamic reconfiguration, all back ends are disconnected and then During dynamic reconfiguration, all backends are disconnected and then
reconnected using the new configuration. If connectivity to any of the 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 backends cannot be established, the server logs a fatal error but remains
up. It will be able to process commands but will not serve clients. This up. It is able to process commands but does not serve clients. This
allows the configuration to be corrected via command, if required. allows the configuration to be corrected via command, if required.
During normal operations, if connectivity to any of the back ends is lost and During normal operations, if connectivity to any of the backends is lost and
automatic recovery for that back end is enabled, the server will disconnect automatic recovery for that backend is enabled, the server disconnects
from all back ends, and then attempt to reconnect them. During the recovery from all backends and then attempts to reconnect. During the recovery
process the server will cease serving clients but continue to respond to process, the server ceases to serve clients but continues to respond to
commands. If connectivity to all back ends is restored the server will commands. If connectivity to all backends is restored, the server
return to normal operations. If connectivity cannot be restored after returns to normal operations. If connectivity cannot be restored after
``max-reconnect-tries``, the server will issue a fatal error and exit. ``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 `RFC 4703, section
5.2, <https://tools.ietf.org/html/rfc4703#section-5.2>`__ describes 5.2, <https://tools.ietf.org/html/rfc4703#section-5.2>`__ describes
issues that may arise with dual-stack clients. These are clients that 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 this to work properly, the clients are required to embed their IPv6 DUID
within their IPv4 client identifier option, as described in `RFC within their IPv4 client identifier option, as described in `RFC
4703 <https://tools.ietf.org/html/rfc4361>`__. In this way, DNS updates 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 For additional Cassandra-specific parameters, see
:ref:`cassandra-database-configuration4`. :ref:`cassandra-database-configuration4`.
If the same host is configured both in-file and in-database, Kea won't warn of If the same host is configured both in-file and in-database, Kea does not issue a warning,
the duplicate like it would if you specified them both in the same data source. as it would if both were specified in the same data source.
Instead the host configured in-file will have priority over the one configured Instead, the host configured in-file has priority over the one configured
in-database. in-database.
.. _read-only-database-configuration4: .. _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 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 `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, 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 allow users to define sub-option codes from 0 to 255. If
sub-options with codes 0 and/or 255, bytes with that value will sub-options with codes 0 and/or 255 are defined, bytes with that value are
no longer be treated as a PAD or an END, but as the sub-option code no longer treated as a PAD or an END, but as the sub-option code
when parsing a VSI option in an incoming query. when parsing a VSI option in an incoming query.
Option 43 input processing (aka unpacking) is deferred so that it Option 43 input processing (also called unpacking) is deferred so that it
happens after classification. This means you cannot classify clients happens after classification. This means clients cannot be classified
using option 43 suboptions. The definition used to unpack option 43 using option 43 suboptions. The definition used to unpack option 43
is determined as follows: is determined as follows:
- If defined at the global scope this definition is used - 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 definition only says the sub-option space is
"vendor-encapsulated-options-space" "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 - If the packet belongs to a client class which defines the option
43 use this definition 43 use this definition
- If defined at the global scope 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 Note as they use a specific/per vendor option space the sub-options
are defined at the global scope. 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 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`` can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates``
parameter which now only controls whether kea-dhcp4 connects to D2. parameter, which now only controls whether kea-dhcp4 connects to D2;
And the new behavioral parameter, ``ddns-send-updates``, which determines and the new behavioral parameter, ``ddns-send-updates``, which determines
if DDNS updates are enabled at a given level (i.e global, shared-network, 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 or subnet). The following table shows how the two parameters function
together: together:
.. table:: Enabling and Disabling DDNS Updates .. table:: Enabling and Disabling DDNS Updates
+-----------------+--------------------+-------------------------------+ +-----------------+--------------------+-------------------------------+
| dhcp-ddns: | Global | Outcome | | dhcp-ddns: | Global | Outcome |
| enable-updates | ddns-send-udpates | | | enable-updates | ddns-send-updates | |
+=================+====================+===============================+ +=================+====================+===============================+
| false (default) | false | no updates at any scope | | false (default) | false | no updates at any scope |
+-----------------+--------------------+-------------------------------+ +-----------------+--------------------+-------------------------------+
@ -3026,12 +3026,12 @@ together:
| | | false for ddns-enable-updates | | | | false for ddns-enable-updates |
+-----------------+--------------------+-------------------------------+ +-----------------+--------------------+-------------------------------+
Kea 1.9.1 adds two new parameters. The first new parameter is ``ddns-update-on-renew``. 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 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. 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 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 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. to add DNS entries or they were somehow lost by the DNS server.
.. note:: .. 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. FQDN while new entries for Client-B will still be added.
Disabling conflict resolution should be done only after careful review of 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 always ensure leases changes are processed through Kea, whether they are
released, expire, or are deleted via the lease-del4 command, prior to released, expire, or are deleted via the lease-del4 command, prior to
reassigning either FQDNs or IP addresses. Doing so will cause kea-dhcp4 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 The suffix used when generating an FQDN, or when qualifying a partial
name, is specified by the ``ddns-qualifying-suffix`` parameter. It is name, is specified by the ``ddns-qualifying-suffix`` parameter. It is
strongly recommended that you supply a value for qualifying prefix when strongly recommended that the user supply a value for the qualifying prefix when
DDNS updates are enabled. For obvious reasons, we cannot supply a DDNS updates are enabled. For obvious reasons, we cannot supply a
meaningful default. 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**]. [**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 - ``hostname-char-set`` - a regular expression describing the invalid
character set. This can be any valid, regular expression using POSIX 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). considered an invalid character to be replaced (or omitted).
- ``hostname-char-replacement`` - a string of zero or more characters - ``hostname-char-replacement`` - a string of zero or more characters
with which to replace each invalid character in the host name. An empty 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:: .. note::
@ -3380,10 +3380,10 @@ and '-'. This may be accomplished with the following two parameters:
- "hostname-char-set": "[^A-Za-z0-9.-]", - "hostname-char-set": "[^A-Za-z0-9.-]",
- "hostname-char-replacement": "" - "hostname-char-replacement": ""
This enables sanitizing and will omit any character that is not This enables sanitizing and omits any character that is not
a letter,digit, hyphen, dot or nul. 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': digit, hyphen, or dot with the letter 'x':
:: ::
@ -3433,11 +3433,11 @@ qualifying suffix (if one is defined and needed).
.. note:: .. 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 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 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: .. _dhcp4-next-server:
@ -3862,8 +3862,8 @@ be retained on the lease. The lease's user-context will look something like thi
.. note:: .. note::
It is possible that other hook libraries are already making use of user-context. 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 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 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 mulitple 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 purposes. As long as no other purpose also writes an "ISC" element to
user-context there should not be a conflict. 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 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 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 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/>`_. 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 include hardware description, test scenario descriptions and This includes hardware descriptions, test scenario descriptions, and
current results. current results.
After enabling multi-threading, the number of threads is set by ``thread-pool-size`` 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. 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 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 v6-only-preferred option. This follows the usual practice of setting options. The
option value on pool, subnet, shared network, global levels or even specify it in host reservations. 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 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 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 classes specified within the Kea configuration. In particular, when a
host reservation exists for a client within a given subnet, the "KNOWN" 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 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. reserved class has been also assigned.
.. note:: .. 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 are assigned to the processed packet after all classes with the
``only-if-required`` parameter set to ``false`` have been evaluated. ``only-if-required`` parameter set to ``false`` have been evaluated.
This has an implication that these classes must not depend on the 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 ``.Dhcp4["shared-networks"][].subnet4[]["reservation-mode"]`` (highest
priority: overrides all others) priority: overrides all others)
For deciding what ``"reservation-mode"`` to choose, you may refer to the To decide which ``"reservation-mode"`` to choose, the
following decision diagram: 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 currently used backends (backends do not support the new setting),
the new setting is ignored and the warning log message is output. the new setting is ignored and the warning log message is output.
The backends continue to use the default setting, i.e. expecting that The backends continue to use the default setting, i.e. expecting that
IP reservations are unique within each subnet. In order to allow IP reservations are unique within each subnet. To allow the
creating non unique IP reservations the administrator must remove creation of non-unique IP reservations, the administrator must remove
the backends which lack support for it from the configuration file. the backends which lack support for them 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 later decided to return to reservations for the same IP address and later decide to return to
the default mode in which this is no longer allowed. The administrators 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 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. exists within a subnet prior to switching back to the default mode.
If such duplicates are left in the configuration file, the server 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 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. finds multiple reservations for the same IP address.
.. note:: .. 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 the same IP address exist in the host databases (MySQL and/or
PostgreSQL) when ``ip-reservations-unique`` is updated from PostgreSQL) when ``ip-reservations-unique`` is updated from
``true`` to ``false``. This may cause issues with lease allocations. ``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: parameters to control statistics default sample limits:
- ``statistic-default-sample-count`` - determines the default maximum - ``statistic-default-sample-count`` - determines the default maximum
number of samples which will be kept. The special value of zero number of samples which are kept. The special value of zero
means to use a default maximum age. indicates that a default maximum age should be used.
- ``statistic-default-sample-age`` - determines the default maximum - ``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 For instance, to reduce the statistic keeping overhead, set
the default maximum sample count to 1 so only one sample will be kept by: 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 For additional Cassandra-specific parameters, see
:ref:`cassandra-database-configuration4`. :ref:`cassandra-database-configuration4`.
If the same host is configured both in-file and in-database, Kea won't warn of If the same host is configured both in-file and in-database, Kea does not issue a warning,
the duplicate like it would if you specified them both in the same data source. as it would if both were specified in the same data source.
Instead the host configured in-file will have priority over the one configured Instead, the host configured in-file has priority over the one configured
in-database. in-database.
.. _read-only-database-configuration6: .. _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 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`` can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates``
parameter which now only controls whether kea-dhcp6 connects to D2. parameter, which now only controls whether kea-dhcp6 connects to D2;
And the new behavioral parameter, ``ddns-send-updates``, which determines and the new behavioral parameter, ``ddns-send-updates``, which determines
if DDNS updates are enabled at a given level (i.e global, shared-network, 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 or subnet). The following table shows how the two parameters function
together: together:
.. table:: Enabling and Disabling DDNS Updates .. table:: Enabling and Disabling DDNS Updates
+-----------------+--------------------+-------------------------------+ +-----------------+--------------------+-------------------------------+
| dhcp-ddns: | Global | Outcome | | dhcp-ddns: | Global | Outcome |
| enable-updates | ddns-send-udpates | | | enable-updates | ddns-send-updates | |
+=================+====================+===============================+ +=================+====================+===============================+
| false (default) | false | no updates at any scope | | 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. FQDN while new entries for Client-B will still be added.
Disabling conflict resolution should be done only after careful review of 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 always ensure leases changes are processed through Kea, whether they are
released, expire, or are deleted via the lease-del6 command, prior to 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. to generate DNS removal requests to D2.
@ -3027,7 +3027,7 @@ follows:
"Dhcp6": { "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: format:
[**candidate-name**].[**ddns-qualifying-suffix**]. [**candidate-name**].[**ddns-qualifying-suffix**].
where **candidate-name** is the partial name supplied in the DHCPREQUEST. where **candidate-name** is the partial name supplied in the DHCPREQUEST.
For example, if the FQDN domain name value is "some-computer" and the 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.** **some-computer.example.com.**
@ -3093,12 +3093,12 @@ accomplished with the following two parameters:
- ``hostname-char-set`` - a regular expression describing the invalid - ``hostname-char-set`` - a regular expression describing the invalid
character set. This can be any valid, regular expression using POSIX 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). considered an invalid character to be replaced (or omitted).
- ``hostname-char-replacement`` - a string of zero or more characters - ``hostname-char-replacement`` - a string of zero or more characters
with which to replace each invalid character in the host name. An empty 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:: .. note::
@ -3107,10 +3107,10 @@ accomplished with the following two parameters:
- "hostname-char-set": "[^A-Za-z0-9.-]", - "hostname-char-set": "[^A-Za-z0-9.-]",
- "hostname-char-replacement": "" - "hostname-char-replacement": ""
This enables sanitizing and will omit any character that is not This enables sanitizing and omits any character that is not
a letter,digit, hyphen, dot or nul. 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': digit, hyphen, or dot with the letter 'x':
:: ::
@ -3156,11 +3156,11 @@ qualifying suffix (if one is defined and needed).
.. note:: .. 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 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 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: .. _dhcp6-dhcp4o6-config:
@ -3371,16 +3371,16 @@ pretty-printed for clarity):
information within Kea. information within Kea.
.. note:: .. note::
It is possible that other hook libraries are already making use of It is possible that other hook libraries are already using
user-context. Enabling store-extended-info should not interfere with 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 any other user-context content, as long as it does not also use an element
labled "ISC". In other words, user-context is intended to be a flexible labeled "ISC". In other words, user-context is intended to be a flexible
container serving mulitple purposes. As long as no other purpose also container serving multiple purposes. As long as no other purpose also
writes an "ISC" element to user-context there should not be a conflict. writes an "ISC" element to user-context there should not be a conflict.
.. _dhcp6-multi-threading-settings: .. _dhcp6-multi-threading-settings:
Multi-threading settings Multi-Threading Settings
------------------------ ------------------------
The Kea server can be configured to process packets in parallel using multiple 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 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 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/>`_. 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 description, test scenario descriptions and This includes hardware descriptions, test scenario descriptions, and
current results. current results.
After enabling multi-threading, the number of threads is set by ``thread-pool-size`` 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 classes specified within the Kea configuration. In particular, when a
host reservation exists for a client within a given subnet, the "KNOWN" 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 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. reserved class has been also assigned.
.. note:: .. 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 are assigned to the processed packet after all classes with the
``only-if-required`` parameter set to ``false`` have been evaluated. ``only-if-required`` parameter set to ``false`` have been evaluated.
This has an implication that these classes must not depend on the 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 ``.Dhcp6["shared-networks"][].subnet6[]["reservation-mode"]`` (highest
priority: overrides all others) priority: overrides all others)
For deciding what ``"reservation-mode"`` to choose, you may refer to the To decide which ``"reservation-mode"`` to choose, the
following decision diagram: 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 currently used backends (backends do not support the new setting),
the new setting is ignored and the warning log message is output. the new setting is ignored and the warning log message is output.
The backends continue to use the default setting, i.e. expecting that The backends continue to use the default setting, i.e. expecting that
IP reservations are unique within each subnet. In order to allow IP reservations are unique within each subnet. To allow the
creating non unique IP reservations the administrator must remove creation of non-unique IP reservations, the administrator must remove
the backends which lack support for it from the configuration file. 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 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 administrators must make sure that at most one reservation for
the given IP address or delegated prefix exists within a subnet prior 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 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 Leaving such reservations in the host databases does not cause
configuration errors but may lead to lease allocation errors during 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. for the same IP address or delegated prefix.
.. note:: .. 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 the same IP address and/or delegated prefix exist in the host
databases (MySQL and/or PostgreSQL) when ``ip-reservations-unique`` databases (MySQL and/or PostgreSQL) when ``ip-reservations-unique``
is updated from ``true`` to ``false``. This may cause issues with 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 more addresses available. Therefore, it is strongly recommended to always
specify subnet selectors (interface or a relay address) at shared network 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 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. described above.
Client Classification in Shared Networks 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 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. relays.
.. note:: .. note::
@ -5729,7 +5729,7 @@ default, the following syntax can be used:
The parameter is expressed in seconds, so the example above will The parameter is expressed in seconds, so the example above will
instruct the server to recycle declined leases after one hour. 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 handling procedure. The lease6_decline hook is triggered after the
incoming DHCPDECLINE message has been sanitized and the server is about incoming DHCPDECLINE message has been sanitized and the server is about
to decline the lease. The declined-addresses statistic is increased 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 This section describes DHCPv6-specific statistics. For a general
overview and usage of statistics, see :ref:`stats`. 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: parameters to control statistics default sample limits:
- ``statistic-default-sample-count`` - determines the default maximum - ``statistic-default-sample-count`` - determines the default maximum
number of samples which will be kept. The special value of zero number of samples which are kept. The special value of zero
means to use a default maximum age. indicates that a default maximum age should be used.
- ``statistic-default-sample-age`` - determines the default maximum - ``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 For instance, to reduce the statistic keeping overhead, set
the default maximum sample count to 1 so only one sample will be kept by: 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 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 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". 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 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 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` 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 and :ref:`dhcp6-std-options`). The option information is carried in the
`options` list. Another list, `pd-pools`, contains a map with the prefix `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 option already exists for the prefix delegation pool, it is replaced with
the new instance. the new instance.
@ -1518,7 +1518,7 @@ option is deleted.
The following command attempts to delete an option having the The following command attempts to delete an option having the
option code 5 in the top-level option space from the subnet 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 The `server-tags` parameter is mandatory and contains one or
more server tags. It may contain the keyword "all" to fetchg the subnets more server tags. It may contain the keyword "all", to fetch the subnets
associated with all servers. When the `server-tags` list 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. of unassigned subnets, i.e. the subnets which are associated with no servers.
For example: 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 - ``partner-in-maintenance`` - an active server transitions to this state
after receiving a ``ha-maintenance-start`` command from the after receiving a ``ha-maintenance-start`` command from the
administrator. The server in this state becomes responsible administrator. The server in this state becomes responsible
for responding to all DHCP requests. The server sends for responding to all DHCP requests. The server sends a
``ha-maintenance-notify`` command to the partner which is supposed ``ha-maintenance-notify`` command to the partner, which should
to enter the ``in-maintenance`` state. If that is the case, the server enter the ``in-maintenance`` state. The server
remaining in the ``partner-in-maintenance`` state keeps sending lease remaining in the ``partner-in-maintenance`` state keeps sending lease
updates to the partner until it finds that the parter stops updates to the partner until it finds that the partner has stopped
responding to those lease updates, heartbeats or any other commands. responding to those lease updates, heartbeats, or any other commands.
In this case, the server in the ``partner-in-maintenance`` state In this case, the server in the ``partner-in-maintenance`` state
transitions to the ``partner-down`` state and keeps responding to transitions to the ``partner-down`` state and keeps responding to
the queries, but no longer sends lease updates. 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 is still provisioned. This default configuration can be changed by
setting the ``wait-backup-ack`` configuration parameter to ``true``, setting the ``wait-backup-ack`` configuration parameter to ``true``,
in which case the primary server always waits for the acknowledgements 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 updates fails. This improves lease database consistency between the
primary and the secondary. However, if a communication failure between primary and the secondary. However, if a communication failure between
the active server and any of the backups occurs, it effectively causes 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 transition to the ``partner-down`` state even though the partner is
still operating. On the other hand, selecting too high a value may still operating. On the other hand, selecting too high a value may
result in never transitioning to the ``partner-down`` state if the DHCP 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 of distinct clients trying to communicate with the server could be lower
than the ``max-unacked-clients`` setting. 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`` 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 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 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 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 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 loosing a DHCP service if 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 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 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 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. be minimal.
.. _ha-sharing-lease-info: .. _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 When the upgraded server is back online, the upgrade can be performed for
the second server. The typical problem reported for the earlier versions the second server. The typical problem reported for the earlier versions
of the High Availability hooks library was that the administrator did not 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 have direct control over the state of the DHCP server. Shutting down
one of the servers for maintenance didn't necessarily cause the other one of the servers for maintenance did not necessarily cause the other
server to start reponding to all DHCP queries because the failure server to start responding to all DHCP queries, because the failure
detection algorithm described in :ref:`ha-scope-transition` requires that 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 depending on the configuration, may also require that a number of DHCP
requests are not responded for a configured period of time. The requests are not responded to for a configured period of time. The
maintenance procedure, however, requires that the administrator is able maintenance procedure, however, requires that the administrator be able
to instruct one of the servers to instantly start serving all DHCP clients 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 and the other server to instantly stop serving any DHCP clients, so it
can be safely shut down. can be safely shut down.
The maintenance feature of the High Availability hooks library addresses 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 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 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 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 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 the status information of the server receiving this command, but also the
information about its partner, if this information is available. information about its partner if it is available.
The following is the example response to the ``status-get`` command including The following is an example response to the ``status-get`` command, including
the HA status of two load balancing servers: 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 ``lease6-bulk-apply`` was implemented to address
the performance penalty in the High Availability when a single DHCPv6 the performance penalty in the High-Availability mode when a single DHCPv6
transaction resulted in multiple lease updates sent to the partner if transaction resulted in multiple lease updates sent to the partner, if
multiple address and/or prefix leases were allocated. Consider the case 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 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 prefixes: that may result in allocation of 4 leases. In addition,
DHCPv6 may assign different address than requested by the client during DHCPv6 may assign a different address than the one requested by the client during
the renew or rebind and delete the leases previously used by this client. the renew or rebind stage, and delete the leases previously used by this client.
The are 6 of lease changes sent between the HA partners is in this case. There are six lease changes sent between the HA partners in this case.
Sending these updates in individual commands, e.g. ``lease6-update`` Sending these updates in individual commands, e.g. via ``lease6-update``,
is highly inefficient and produces unnecessary delays in communication is highly inefficient and produces unnecessary delays in communication,
between the HA partners and in sending the response to the DHCPv6 client. both between the HA partners and in sending the response to the DHCPv6 client.
The ``lease6-bulk-apply`` command deals with this The ``lease6-bulk-apply`` command deals with this
problem by aggregating all lease changes in a single command. Both 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 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. 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 this command, it can be freely used in all cases when it is desired to
send multiple lease changes in a single command. 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 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 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 continues to be processed for other leases. All the leases for which
the command was unable to apply the changes in the database will be the command was unable to apply the changes in the database are
listed in the response. For example: 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 | | 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 | | client-last-transaction-time | 91 | the amount of time that has elapsed since the |
| | | lease's client-last-transaction-time (CLTT) | | | | lease's client-last-transaction-time (CLTT). |
| | | This value will also be used by the server to | | | | This value is also used by the server to |
| | | adjust life time and timer values. | | | | 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 | | dhcp-renewal-time | 58 | as controlled by kea-dhcp4 configuration and |
| | | then reduced by CLTT | | | | 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 | | | | then reduced by CLTT |
+------------------------------+-------+-----------------------------------------------+ +------------------------------+-------+-----------------------------------------------+
| dhcp-agent-options | 82 | if stored on the lease. (See | | 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 | | | | - preferred life time reduced by CLTT |
+------------------------------+-------+-----------------------------------------------+ +------------------------------+-------+-----------------------------------------------+
If the lease with the most recent CLTT value (Client Last If the lease with the most recent client-last-transaction-time (CLTT)
Transmission Time) has relay information in it's user-context (see value has relay information in its user-context (see
:ref:`store-extended-info-v6`), then an OPTION_LQ_RELAY_DATA option will be :ref:`store-extended-info-v6`), then an OPTION_LQ_RELAY_DATA option is
added to the reply (see added to the reply (see
`RFC 5007, Section 4.1.2.4 <https://tools.ietf.org/html/rfc5007#section-4.1.2.4>`__). `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 .. code-block:: console
$ wget -nd https://dl.bintray.com/boostorg/release/1.65.1/source/boost_1_65_1.tar.gz $ 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/ $ cd boost_1_65_1/
$ ./bootstrap.sh $ ./bootstrap.sh
$ ./b2 --without-python $ ./b2 --without-python
@ -137,7 +137,7 @@ Choice 2: get a tarball and extract it
.. parsed-literal:: .. 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 The next step is to extract the premium Kea package that contains the
RADIUS repository into the Kea sources. After the tarball is extracted, 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:: .. parsed-literal::
$ cd kea $ 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: 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 - FreeRADIUS client directories printed and pointing to the right
directories; directories;
- Boost version at least 1.65.1. The versions available in CentOS 7 - 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 Once the configuration is complete, compile Kea using make. If the
system has more than one core, using the "-j N" 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:: .. 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 This will unpack the tarball into the kea-|release| subdirectory of
the current working directory. the current working directory.
@ -99,7 +99,7 @@ steps will unpack the premium tarball into the correct location:
.. parsed-literal:: .. parsed-literal::
$ cd kea-|release| $ 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 Note that unpacking the Kea premium package will put the files into a
directory named "premium". Regardless of the name of the package, the 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 | | | |load balancing and is sometimes referred to as |
| | |active-active. Each server can handle selected group of | | | |active-active. Each server can handle selected group of |
| | |clients in this network or all clients, if it detects that | | | |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 | | | |designate one server to serve all DHCP clients, and leave |
| | |another server as "standby". This mode is called hot standby| | | |another server as "standby". This mode is called hot standby|
| | |and is sometimes referenced to as active-passive. This | | | |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. | | | |for Kea DHCP servers. |
+-----------------+---------------+------------------------------------------------------------+ +-----------------+---------------+------------------------------------------------------------+
| Statistics | Kea sources |The Statistics Commands library provides additional | | 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 | | | |Kea DHCP servers that share the same lease database. This |
| | |setup is common in deployments where DHCP service redundancy| | | |setup is common in deployments where DHCP service redundancy|
| | |is required and a shared lease database is used to avoid | | | |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 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 types (addresses and prefixes) and subnets. Kea 1.4 extended user
context support to the global scope, interfaces config, shared networks, context support to the global scope, interfaces configuration, shared networks,
subnets, client classes, option datas and definitions, host subnets, client classes, option data and definitions, host
reservations, control socket, dhcp ddns, loggers and server id. These reservations, control socket, dhcp ddns, loggers and server ID. These
are supported in both DHCPv4 and DHCPv6, with the exception of server id are supported in both DHCPv4 and DHCPv6, with the exception of server ID
which is DHCPv6 only. which is DHCPv6 only.

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

@ -7,13 +7,13 @@ Installation
Packages Packages
======== ========
Starting with Kea 1.6.0, ISC now publishes native RPM, deb and APK 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 packages, along with the tarballs with the source code. The packages
are available on `Cloudsmith <https://cloudsmith.io/~isc/repos/>`_ at are available on `Cloudsmith <https://cloudsmith.io/~isc/repos/>`_ at
https://cloudsmith.io/~isc/repos. You can download the native packages https://cloudsmith.io/~isc/repos. The native packages can be downloaded
and install them using the system available in your distribution (such and installed using the system available in a specific distribution (such
as dpkg or rpm). Also, you can add the Kea repository to your system, as dpkg or rpm). The Kea repository can also be added to the system,
which will make it easier to install updates. For details, please making it easier to install updates. For details, please
go to https://cloudsmith.io/~isc/repos, choose the repository of go to https://cloudsmith.io/~isc/repos, choose the repository of
interest and then click the ``Set Me Up`` button for detailed interest and then click the ``Set Me Up`` button for detailed
instructions. instructions.
@ -63,9 +63,9 @@ various development include headers and program development tools.
.. note:: .. note::
Some operating systems have split their distribution packages into a 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 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 Building from source code requires the following software installed on
the system: 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 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 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 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. section describes how to build Kea from the source code.
Download Tar File Download Tar File
@ -146,7 +146,7 @@ Download Tar File
The Kea release tarballs may be downloaded from: The Kea release tarballs may be downloaded from:
https://downloads.isc.org/isc/kea/ . https://downloads.isc.org/isc/kea/ .
Retrieve from Git Retrieve From Git
----------------- -----------------
Downloading this "bleeding edge" code is recommended only for developers 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``, ``--install`` switch. This will run ``autoconf``, ``aclocal``,
``libtoolize``, ``autoheader``, ``automake``, and related commands. ``libtoolize``, ``autoheader``, ``automake``, and related commands.
Write access to the Kea repository is only granted to ISC staff. If you Write access to the Kea repository is only granted to ISC staff.
are a developer planning to contribute to Kea, please check our Developers planning to contribute to Kea, should check our
`Contributor's `Contributor's
Guide <https://gitlab.isc.org/isc-projects/kea/blob/master/contributors-guide.md>`__. Guide <https://gitlab.isc.org/isc-projects/kea/blob/master/contributors-guide.md>`__.
The `Kea Developer's The `Kea Developer's
Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/>`__ contains more 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. contributed code to be accepted by ISC.
.. _configure: .. _configure:
@ -255,11 +255,11 @@ options. Some commonly used options are:
This option requires subscription-only RADIUS hook. This option requires subscription-only RADIUS hook.
- ``--with-freeradius-dictionary`` - ``--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 file contains list of supported RADIUS attributes. Available in subscriber
only version. This option requires subscription-only RADIUS hook. 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``. the ``premium`` directory and rerun ``autoreconf -i``.
.. note:: .. note::
@ -267,15 +267,15 @@ the ``premium`` directory and rerun ``autoreconf -i``.
The ``--runstatedir`` in the installation directories is particular. The ``--runstatedir`` in the installation directories is particular.
There are three cases: 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. version has not been released yet.
- You use autoconf 2.69 patched to add support of this. In this case and the - The system uses autoconf 2.69 patched to add this support. In this case and the
previous simply use when needed the``--runstatedir`` configure parameter. previous, simply use the ``--runstatedir`` configure parameter when needed.
- There is no support (the configure parameter is not recognized and configure - There is no support (the configure parameter is not recognized and configure
directly raises an error). For autoconf 2.69 the ``runstatedir`` environment 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 ...`` 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`` - ``--with-gtest``, ``--with-gtest-source``
Enable the building of the C++ Unit Tests using the Google Test Enable the building of the C++ Unit Tests using the Google Test
framework. This option specifies the path to the gtest source. (If 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.) from https://github.com/google/googletest.)
- ``--enable-generate-docs`` - ``--enable-generate-docs``
Enable the rebuilding Kea documentation. ISC publishes Kea Enable the rebuilding Kea documentation. ISC publishes Kea
documentation for each release; however, in some cases you may want documentation for each release; however, in some cases it may be
to rebuild it. For example, if you want to change something in the desirable to rebuild it: for example, to change something in the
docs, or want to generate new ones from git sources that are not docs, or to generate new ones from git sources that are not
released yet. released yet.
- ``--enable-generate-parser`` - ``--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 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 from them. By default Kea does not use flex or bison to avoid
requiring installation of unnecessary dependencies for users. requiring installation of unnecessary dependencies for users.
However, if you change anything in the parses (such as adding a new However, anything in the parses is changed (such as adding a new
parameter), you will need to use flex and bison to regenerate parameter), flex and bison are required to regenerate
parsers. This option lets you do that. parsers. This option permits that.
- ``--enable-generate-messages`` - ``--enable-generate-messages``
Enable the regeneration of messages files from their messages source Enable the regeneration of messages files from their messages source
files, e.g. regenerate xxx_messages.h and xxx_messages.cc from files, e.g. regenerate xxx_messages.h and xxx_messages.cc from
xxx_messages.mes using the Kea message compiler. By default Kea is xxx_messages.mes using the Kea message compiler. By default Kea is
built using these .h and .cc files from the distribution. However, if 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 anything in a .mes file is changed (such as adding a new message),
will need to build and use the Kea message compiler. This option lets the Kea message compiler needs to be built and used. This option
you do that. permits that.
- ``--with-benchmark``, ``--with-benchmark-source`` - ``--with-benchmark``, ``--with-benchmark-source``
Enable the building of the database backend benchmarks using the Enable the building of the database backend benchmarks using the
Google Benchmark framework. This option specifies the path to 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.) can be downloaded from https://github.com/google/benchmark.)
This support is experimental. This support is experimental.
@ -338,9 +338,10 @@ enabled, and sets the installation location to /opt/kea:
--with-pgsql=/usr/local/bin/pg_config \ --with-pgsql=/usr/local/bin/pg_config \
--prefix=/opt/kea --prefix=/opt/kea
If you have any problems with building Kea using the header-only Boost Users who 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 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): sake of this example to be located in /usr/pkg/lib), should issue these
commands:
.. code-block:: console .. code-block:: console
@ -384,7 +385,7 @@ errors.
If required, run ``ldconfig`` as root with ``/usr/local/lib`` (or with 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 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 .. code-block:: console
@ -394,7 +395,7 @@ relevant linker cache configuration file for your OS):
.. note:: .. 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: errors like the following:
:: ::
@ -406,13 +407,13 @@ relevant linker cache configuration file for your OS):
Cross-Building Cross-Building
-------------- --------------
It is possible to cross-build Kea, i.e. to create binaries in another It is possible to cross-build Kea, i.e. to create binaries in a separate
system (the ``build`` system) than the system where Kea will run system (the ``build`` system) from the one where Kea runs
(the ``host`` system). (the ``host`` system).
It is outside of the scope of common administrator operations and requires It is outside of the scope of common administrator operations and requires
some developer skills so the Developer Guide explains how to do that 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 using an x86_64 Linux system to build Kea for a Raspberry Pi box running
Raspbian: `Kea Cross-Compiling Example Raspbian: `Kea Cross-Compiling Example
<https://jenkins.isc.org/job/Kea_doc/doxygen/de/d9a/crossCompile.html>`__. <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 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. development libraries must be installed.
Build and install Kea as described in :ref:`installation`, Build and install Kea as described in :ref:`installation`,
@ -468,7 +469,7 @@ database configuration.
Building with PostgreSQL support 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 client development libraries must be installed. Client development
libraries are often packaged as "libpq". libraries are often packaged as "libpq".
@ -494,11 +495,11 @@ database configuration.
Building with CQL (Cassandra) Support 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: Cassandra project website contains useful pointers:
https://cassandra.apache.org. 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 simply install or build and install the package. Then build and install
Kea as described in :ref:`installation`. To enable the Kea as described in :ref:`installation`. To enable the
Cassandra (CQL) database code, at the "configure" step (see :ref:`configure`), enter: 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 $ ./configure [other-options] --with-cql=path-to-pkg-config
Note if ``pkg-config`` is at its standard location (and thus in the Note that 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 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 (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. as described below.
Download and compile cpp-driver from DataStax. For details regarding 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. 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 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; 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 specified in it) and change the environment variable CPP_DRIVER_PATH to
point to the directory where the cpp-driver sources are located. Make 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 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 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.: refer to the ``--prefix`` parameter passed to the configure script.:
.. code-block:: console .. 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 chown -R admin /var/log/kea-dhcp6.log
chgrp -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): (e.g. /etc/systemd/system/kea-dhcp6.service):
.. code-block:: console .. code-block:: console
@ -595,19 +596,18 @@ more information.
setcap 'cap_net_bind_service=+ep' /opt/kea/sbin/kea-dhcp6 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 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 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. :ref:`dhcp4-interface-configuration` section) and the ``cap_net_raw`` capability can be skipped.
.. note:: .. note::
An alternative approach to avoiding running Kea with root privileges assumes instructing Kea to An alternative approach to running Kea with root privileges is to configure Kea to use
use non-privileged (greater than 1024) posts and redirecting traffic. This, however, will work non-privileged ports (i.e. those greater than 1024) and redirecting traffic. Note that this
only for relayed traffic. This approach in general is considered experimental and not tested only works for relayed traffic. Furthermore, we consider it experimental and untested in
enough for deployment in production environment. Use with caution! production environments. Use it only after careful consideration.
To use this approach, configure the server to listen on other non-privileged ports (e.g. 1547
To use this approach, configure the server to listen on other non privileged port (eg: 1547
and 1548) by running the process with ``-p`` option in ``/etc/systemd/system/kea-dhcp4.service``: and 1548) by running the process with ``-p`` option in ``/etc/systemd/system/kea-dhcp4.service``:
.. code-block:: console .. 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 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 then configure port redirection with iptables and ip6tables for new ports (e.g. 1547
and 1548). Make sure you replace ens4 with your specific interface name. and 1548). Be sure to replace ens4 with the specific interface name.
.. code-block:: console .. 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 delegate prefixes to DHCP clients. These addresses and prefixes are
often referred to as "leases." Leases are typically assigned to clients often referred to as "leases." Leases are typically assigned to clients
for a finite amount of time, known as the "valid lifetime." DHCP 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 them by sending the appropriate message to the DHCP server. The DHCP
server records the time when these leases are renewed and calculates new server records the time when these leases are renewed and calculates new
expiration times for them. expiration times for them.
@ -75,11 +75,11 @@ The following list presents all configuration parameters pertaining to
processing expired leases with their default values: processing expired leases with their default values:
- ``reclaim-timer-wait-time`` - this parameter governs intervals - ``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]. next one. Specified in seconds. The default value is 10 [seconds].
- ``flush-reclaimed-timer-wait-time`` - this parameter controls how - ``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]. seconds. The default value is 25 [seconds].
- ``hold-reclaimed-time`` - this parameter governs how long the lease - ``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 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 a logger. Kea logging is implemented using the Log4Cplus library and whose
output formatting is based, conceptually, on the printf formatting from C 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`. :ref:`logging-message-format`.
Each output type (stdout, file, or syslog) has a default ``pattern`` which 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 describes the content of its log messages. This parameter can be used to
specifiy your own pattern. The pattern for each logger is governed specify a desired pattern. The pattern for each logger is governed
individually so each configured logger can have it's own pattern. Omitting individually so each configured logger can have its own pattern. Omitting
the ``pattern`` parameter or setting it to an empty string, "", will cause the ``pattern`` parameter or setting it to an empty string, "", causes
Kea to use the default pattern for that logger's output type. 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`` 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"; "%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 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 dependencies require at least version 4.9, which unfortunately means
that a new compiler has to be installed. Also, many of the Sysrepo 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. being they must be installed from sources.
Quick Sysrepo Overview Quick Sysrepo Overview

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

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