diff options
author | Suzanne Goldlust <sgoldlust@isc.org> | 2020-11-14 01:00:37 +0100 |
---|---|---|
committer | Tomek Mrugalski <tomek@isc.org> | 2020-11-20 11:32:22 +0100 |
commit | 76b25d1836e64c14377f180f7103dd61b7513b06 (patch) | |
tree | b49c0f1ee5e0b6c9ec11c6b80a34225f177ce18f /doc | |
parent | Fix typos (diff) | |
download | kea-76b25d1836e64c14377f180f7103dd61b7513b06.tar.xz kea-76b25d1836e64c14377f180f7103dd61b7513b06.zip |
Fix typos, and other text corrections
Mostly minor text fixups, with a few edits for clarity
Diffstat (limited to 'doc')
-rw-r--r-- | doc/devel/congestion-handling.dox | 2 | ||||
-rw-r--r-- | doc/sphinx/arm/admin.rst | 41 | ||||
-rw-r--r-- | doc/sphinx/arm/config.rst | 44 | ||||
-rw-r--r-- | doc/sphinx/arm/congestion-handling.rst | 2 | ||||
-rw-r--r-- | doc/sphinx/arm/ctrl-channel.rst | 8 | ||||
-rw-r--r-- | doc/sphinx/arm/database-connectivity.rst | 36 | ||||
-rw-r--r-- | doc/sphinx/arm/ddns.rst | 2 | ||||
-rw-r--r-- | doc/sphinx/arm/dhcp4-srv.rst | 119 | ||||
-rw-r--r-- | doc/sphinx/arm/dhcp6-srv.rst | 106 | ||||
-rw-r--r-- | doc/sphinx/arm/hooks-cb-cmds.rst | 16 | ||||
-rw-r--r-- | doc/sphinx/arm/hooks-ha.rst | 56 | ||||
-rw-r--r-- | doc/sphinx/arm/hooks-lease-cmds.rst | 26 | ||||
-rw-r--r-- | doc/sphinx/arm/hooks-lease-query.rst | 20 | ||||
-rw-r--r-- | doc/sphinx/arm/hooks-radius.rst | 8 | ||||
-rw-r--r-- | doc/sphinx/arm/hooks.rst | 16 | ||||
-rw-r--r-- | doc/sphinx/arm/install.rst | 116 | ||||
-rw-r--r-- | doc/sphinx/arm/lease-expiration.rst | 6 | ||||
-rw-r--r-- | doc/sphinx/arm/logging.rst | 10 | ||||
-rw-r--r-- | doc/sphinx/arm/netconf.rst | 2 | ||||
-rw-r--r-- | doc/sphinx/arm/quickstart.rst | 2 | ||||
-rw-r--r-- | doc/sphinx/arm/shell.rst | 2 | ||||
-rw-r--r-- | doc/sphinx/arm/stork.rst | 71 |
22 files changed, 356 insertions, 355 deletions
diff --git a/doc/devel/congestion-handling.dox b/doc/devel/congestion-handling.dox index e5e44fe815..c5ba638419 100644 --- a/doc/devel/congestion-handling.dox +++ b/doc/devel/congestion-handling.dox @@ -52,7 +52,7 @@ The default packet queue implementation for both Kea DHCPv4 and DHCPv6 servers is a simple ring buffer. Once it reaches capacity, new packets get added to the back of queue by discarding packets from the front of queue. Rather than always discarding the newest packets, we now always discard the oldest -packets. The capacity of the buffer, (i.e the maximum number of packets the +packets. The capacity of the buffer (i.e. the maximum number of packets the buffer can contain) is configurable. @section custom-implementations Custom Packet Queues diff --git a/doc/sphinx/arm/admin.rst b/doc/sphinx/arm/admin.rst index 48c897cbb0..f58e718cf6 100644 --- a/doc/sphinx/arm/admin.rst +++ b/doc/sphinx/arm/admin.rst @@ -9,7 +9,7 @@ Kea Database Administration Databases and Database Version Numbers ====================================== -Kea may be configured to use a database as a storage for leases or as a +Kea may be configured to use a database as storage for leases or as a source of servers' configurations and host reservations (i.e. static assignments of addresses, prefixes, options, etc.). Kea updates introduce changes to the database schemas to faciliate new @@ -213,7 +213,7 @@ To create the database: 4. Create the database. - You'll need to exit mysql client + Exit the MySQL client .. code-block:: mysql @@ -226,12 +226,13 @@ To create the database: $ kea-admin db-init mysql -u database-user -p database-password -n database-name - While it is possible to create the database from within mysql client, we recommend you - use the kea-admin tool as it performs some necessary validations to ensure Kea can + While it is possible to create the database from within the MySQL client, we recommend + using the kea-admin tool as it performs some necessary validations to ensure Kea can access the database at runtime. Among those checks is that the schema does not contain any pre-existing tables. If there are any pre-existing tables they must be removed - manaully. An additional check examines the user's ability to create functions and - triggers. If you encounter the following error: + manually. An additional check examines the user's ability to create functions and + triggers. The following error indicates that the user does not have the necessary + permissions to create functions or triggers: .. code-block:: console @@ -241,23 +242,22 @@ To create the database: mysql: [Warning] Using a password on the command line interface can be insecure. ERROR/kea-admin: Create failed, the user, keatest, has insufficient privileges. - Then user does not have the necessary permissions to create functions or triggers. - The simplest way around this is to set the global MySQL variable, log_bin_trust_function_creators to 1 - via mysql client. Note you must do this as a user with SUPER privileges: + The simplest way around this is to set the global MySQL variable, log_bin_trust_function_creators, to 1 + via the MySQL client. Note this must be done as a user with SUPER privileges: .. code-block:: mysql mysql> set @@global.log_bin_trust_function_creators = 1; Query OK, 0 rows affected (0.00 sec) - If you choose to create the database with mysql directly, you may do as as follows: + To create the database with MySQL directly, use these steps: .. code-block:: mysql mysql> CONNECT database-name; mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql - (path-to-kea is the location where Kea is installed.) + (where "path-to-kea" is the location where Kea is installed.) The database may also be dropped manually as follows: @@ -266,10 +266,10 @@ To create the database: mysql> CONNECT database-name; mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_drop.mysql - (path-to-kea is the location where Kea is installed.) + (where "path-to-kea" is the location where Kea is installed.) .. warning:: - Dropping the database will result in the unrecoverable loss of any data it contains. + Dropping the database results in the unrecoverable loss of any data it contains. 5. Exit MySQL: @@ -323,10 +323,9 @@ earlier version. To perform an upgrade, issue the following command: .. note:: - To search host reservations by hostname it is critical the collation of - the hostname column in the host table to be case-insensitive. Fortunately - the default collation in MySQL is case-insensitive. You can verify this - on your MySQL installation by: + To search host reservations by hostname it is critical that the collation of + the hostname column in the host table be case-insensitive. Fortunately, that + is the default in MySQL, but it can be verified via this command: .. code-block:: mysql @@ -337,7 +336,7 @@ earlier version. To perform an upgrade, issue the following command: | utf8_general_ci | +-----------------+ - According to the naming of collations when the name finishes by ``_ci`` + According to naming convention, when the name ends in ``_ci``, the collation is case-insensitive. .. _mysql-performance: @@ -345,8 +344,8 @@ earlier version. To perform an upgrade, issue the following command: Simple MySQL tweak to gain performance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Changing MySQL internal value ``innodb_flush_log_at_trx_commit`` from default value -``1`` to ``2`` can result with huge gain in Kea performance. It can be set per session for testing: +Changing the MySQL internal value ``innodb_flush_log_at_trx_commit`` from the default value +``1`` to ``2`` can result in a huge gain in Kea performance. It can be set per session for testing: .. code-block:: mysql @@ -361,7 +360,7 @@ or permanently in ``/etc/mysql/my.cnf``: innodb_flush_log_at_trx_commit=2 Be aware that changing this value can result with problems during data recovery -after crash, we strongly recommend to check `MySQL documentation <https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_flush_log_at_trx_commit>`__. +after a crash, so we strongly recommend checking the `MySQL documentation <https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_flush_log_at_trx_commit>`__. .. _pgsql-database: diff --git a/doc/sphinx/arm/config.rst b/doc/sphinx/arm/config.rst index 5804855682..affd9e4838 100644 --- a/doc/sphinx/arm/config.rst +++ b/doc/sphinx/arm/config.rst @@ -125,18 +125,18 @@ locations where extra parameters may appear are denoted by an ellipsis Comments and User Context ------------------------- -You can specify shell, C or C++ style comments in the JSON configuration file if -you use the file locally. This is convenient and works in simple cases where -your configuration is kept statically using local file. However, since comments -are not part of JSON syntax, most JSON tools will detect them as -errors. Another problem with them is once Kea loads its configuration, the -shell, C and C++ style comments are ignored. If you use commands such as -`config-get` or `config-write`, those comments will be lost. An example of such +Shell, C, or C++ style comments are all permitted in the JSON configuration file if +the file is used locally. This is convenient and works in simple cases where +the configuration is kept statically using a local file. However, since comments +are not part of JSON syntax, most JSON tools detect them as +errors. Another problem with them is that once Kea loads its configuration, the +shell, C, and C++ style comments are ignored. If commands such as +`config-get` or `config-write` are used, those comments are lost. An example of such comments has been presented in the previous section. -Historically, to address the problem Kea code allowed to put `comment` strings +Historically, to address the problem, Kea code allowed the use of `comment` strings as valid JSON entities. This had the benefit of being retained through various -operations (such as `config-get`) or allowed processing by JSON tools. An +operations (such as `config-get`), or allowing processing by JSON tools. An example JSON comment looks like this: :: @@ -149,18 +149,18 @@ example JSON comment looks like this: }] } -However, users complained that the comment is only a single line and it's not -possible to add any other information in more structured form. One specific +However, the facts that the comment could only be a single line, and that it was not +possible to add any other information in a more structured form, were frustrating. One specific example was a request to add floor levels and building numbers to subnets. This was one of the reasons why the concept of user context has been introduced. It allows adding arbitrary JSON structure to most Kea configuration structures. It has a number of benefits compared to earlier approaches. First, it is fully compatible with JSON tools and Kea commands. Second, it allows storing simple -comment strings if you want to, but it can store much more complex data, such as -multiple lines (as string array), extra typed data (such as floor numbers being -actual numbers) and more. Third, the data is exposed to hooks, so it's possible -to develop third party hooks that take advantage of that extra information. An -example user context would look like this: +comment strings, but it can also store much more complex data, such as +multiple lines (as a string array), extra typed data (such as floor numbers being +actual numbers), and more. Third, the data is exposed to hooks, so it is possible +to develop third-party hooks that take advantage of that extra information. An +example user context looks like this: :: @@ -188,12 +188,12 @@ JSON comments, but converts them to user context on the fly. The comments entries in user-context were converted back to JSON comments to keep backward compatibility, but that conversion went away in version 1.7.9. -The is one side effect, however. If your configuration uses the old JSON -comment, the `config-get` command will return a slightly modified -configuration. Don't be surprised if you call `config-set` followed by a -`config-get` and receive a slightly different structure. If this bothers you, -the best way to avoid this problem is simply abandon JSON comments and start -using user-context. +The is one side effect, however. If the configuration uses the old JSON +comment, the `config-get` command returns a slightly modified +configuration. It is not uncommon for a call for `config-set` followed by a +`config-get` to receive a slightly different structure. +The best way to avoid this problem is simply to abandon JSON comments and +use user context. For a discussion about user context used in hooks, see :ref:`user-context-hooks`. diff --git a/doc/sphinx/arm/congestion-handling.rst b/doc/sphinx/arm/congestion-handling.rst index fb3b553e46..1b4f350653 100644 --- a/doc/sphinx/arm/congestion-handling.rst +++ b/doc/sphinx/arm/congestion-handling.rst @@ -58,7 +58,7 @@ The default packet queue implementation for both kea-dhcp4 and kea-dhcp6 is a simple ring buffer. Once it reaches capacity, new packets get added to the back of the queue by discarding packets from the front of the queue. Rather than always discarding the newest packets, Kea now always -discards the oldest packets. The capacity of the buffer, i.e the maximum +discards the oldest packets. The capacity of the buffer, i.e. the maximum number of packets the buffer can contain, is configurable. A reasonable starting point would be to match the capacity to the number of leases per second a specific installation of Kea can handle. Please note that this diff --git a/doc/sphinx/arm/ctrl-channel.rst b/doc/sphinx/arm/ctrl-channel.rst index 0bb9417b8e..adcc8fdb8f 100644 --- a/doc/sphinx/arm/ctrl-channel.rst +++ b/doc/sphinx/arm/ctrl-channel.rst @@ -520,7 +520,7 @@ been initiated. The optional parameter, "exit-value", specifies the numeric value with which the server process will exit to the system. The default value is zero. -The DDNS deamon supports an extra parameter "type" which controls the way +The DDNS daemon supports an extra parameter "type" which controls the way the process cleans up on exit. The supported shutdown types are: - "normal" - Stops the queue manager and finishes all current transactions @@ -619,15 +619,15 @@ The ``status-get`` command returns server's runtime information: The ``high-availability`` information is returned only when the command is sent to the DHCP servers being in the HA setup. This parameter is never returned when the ``status-get`` command is sent to the -Control Agent or DDNS deamon. +Control Agent or DDNS daemon. The ``thread-pool-size`` and ``packet-queue-size`` parameters are returned only when the command is sent to DHCP servers with multi-threading enabled. These two parameters and ``multi-threading-enabled`` are never returned when the -``status-get`` command is sent to the Control Agent or DDNS deamon. +``status-get`` command is sent to the Control Agent or DDNS daemon. To learn more about the HA status information returned by the -``status-get`` command please refer to the the :ref:`command-ha-status-get` +``status-get`` command please refer to the :ref:`command-ha-status-get` section. diff --git a/doc/sphinx/arm/database-connectivity.rst b/doc/sphinx/arm/database-connectivity.rst index e93c80843c..5b63588638 100644 --- a/doc/sphinx/arm/database-connectivity.rst +++ b/doc/sphinx/arm/database-connectivity.rst @@ -4,31 +4,31 @@ Database Connectivity ********************* Kea servers (kea-dhcp4 and kea-dhcp6) can be configured to use a variety of -database back ends for leases, hosts and configuration. All of them may be +database backends for leases, hosts, and configuration. All of them may be configured to support automatic recovery when connectivity is lost (see ``max-reconnect-tries`` and ``reconnect-wait-time``). It is important to understand how and when automatic recovery comes into play. -Automatic recovery, when configured, only operates after a successful start up -or reconfiguration during which connectivity to all back ends has been +Automatic recovery, when configured, only operates after a successful startup +or reconfiguration during which connectivity to all backends has been successfully established. -During server start up the inability to connect to any of the configured back -ends is always considered fatal. A fatal error will be logged and the server -will exit. This is done based on the idea that configuration should be valid -at start up. Exiting to the operating system allows nanny scripts to detect +During server startup, the inability to connect to any of the configured +backends is always considered fatal. A fatal error is logged and the server +exits, based on the idea that the configuration should be valid +at startup. Exiting to the operating system allows nanny scripts to detect the problem. -During dynamic reconfiguration, all back ends are disconnected and then -reconnected using the new configuration. If connectivity to any of the -back ends cannot be established, the server will log a fatal error but remain -up. It will be able to process commands but will not serve clients. This +During dynamic reconfiguration, all backends are disconnected and then +reconnected using the new configuration. If connectivity to any of the +backends cannot be established, the server logs a fatal error but remains +up. It is able to process commands but does not serve clients. This allows the configuration to be corrected via command, if required. -During normal operations, if connectivity to any of the back ends is lost and -automatic recovery for that back end is enabled, the server will disconnect -from all back ends, and then attempt to reconnect them. During the recovery -process the server will cease serving clients but continue to respond to -commands. If connectivity to all back ends is restored the server will -return to normal operations. If connectivity cannot be restored after -``max-reconnect-tries``, the server will issue a fatal error and exit. +During normal operations, if connectivity to any of the backends is lost and +automatic recovery for that backend is enabled, the server disconnects +from all backends and then attempts to reconnect. During the recovery +process, the server ceases to serve clients but continues to respond to +commands. If connectivity to all backends is restored, the server +returns to normal operations. If connectivity cannot be restored after +``max-reconnect-tries``, the server issues a fatal error and exits. diff --git a/doc/sphinx/arm/ddns.rst b/doc/sphinx/arm/ddns.rst index 36c93dcf60..155e363659 100644 --- a/doc/sphinx/arm/ddns.rst +++ b/doc/sphinx/arm/ddns.rst @@ -84,7 +84,7 @@ Dual-Stack Environments `RFC 4703, section 5.2, <https://tools.ietf.org/html/rfc4703#section-5.2>`__ describes issues that may arise with dual-stack clients. These are clients that -wish to have have both IPv4 and IPv6 mappings for the same FQDN. For +wish to have both IPv4 and IPv6 mappings for the same FQDN. For this to work properly, the clients are required to embed their IPv6 DUID within their IPv4 client identifier option, as described in `RFC 4703 <https://tools.ietf.org/html/rfc4361>`__. In this way, DNS updates diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index dc1ae57252..3bb61c596d 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -732,9 +732,9 @@ entry, as in: For additional Cassandra-specific parameters, see :ref:`cassandra-database-configuration4`. -If the same host is configured both in-file and in-database, Kea won't warn of -the duplicate like it would if you specified them both in the same data source. -Instead the host configured in-file will have priority over the one configured +If the same host is configured both in-file and in-database, Kea does not issue a warning, +as it would if both were specified in the same data source. +Instead, the host configured in-file has priority over the one configured in-database. .. _read-only-database-configuration4: @@ -2229,14 +2229,14 @@ The definition used to decode a VSI option is: sub-option code 0 and 255 mean PAD and END respectively according to `RFC 2132 <https://tools.ietf.org/html/rfc2132>`_. In other words, the sub-option code values of 0 and 255 are reserved. Kea does, however, - allow you to define sub-option codes from 0 to 255. If you define - sub-options with codes 0 and/or 255, bytes with that value will - no longer be treated as a PAD or an END, but as the sub-option code + allow users to define sub-option codes from 0 to 255. If + sub-options with codes 0 and/or 255 are defined, bytes with that value are + no longer treated as a PAD or an END, but as the sub-option code when parsing a VSI option in an incoming query. - Option 43 input processing (aka unpacking) is deferred so that it - happens after classification. This means you cannot classify clients - using option 43 suboptions. The definition used to unpack option 43 + Option 43 input processing (also called unpacking) is deferred so that it + happens after classification. This means clients cannot be classified + using option 43 suboptions. The definition used to unpack option 43 is determined as follows: - If defined at the global scope this definition is used @@ -2247,12 +2247,12 @@ The definition used to decode a VSI option is: definition only says the sub-option space is "vendor-encapsulated-options-space" - The output definition selection is a bit simpler: + The output definition selection is a bit simpler: - If the packet belongs to a client class which defines the option 43 use this definition - If defined at the global scope use this definition - - Otherwise use the built-in last resot definition. + - Otherwise use the built-in last-resort definition. Note as they use a specific/per vendor option space the sub-options are defined at the global scope. @@ -2999,19 +2999,19 @@ The default configuration would appear as follows: ... } -As of Kea 1.7.1, there are two parameters which determine if kea-dhcp4 -can generate DDNS requests to D2. The existing, ``dhcp-ddns:enable-updates`` -parameter which now only controls whether kea-dhcp4 connects to D2. -And the new behavioral parameter, ``ddns-send-updates``, which determines -if DDNS updates are enabled at a given level (i.e global, shared-network, -or subnet). The following table shows how the two parameters function +As of Kea 1.7.1, there are two parameters which determine whether kea-dhcp4 +can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates`` +parameter, which now only controls whether kea-dhcp4 connects to D2; +and the new behavioral parameter, ``ddns-send-updates``, which determines +whether DDNS updates are enabled at a given level (i.e. global, shared-network, +or subnet). The following table shows how the two parameters function together: .. table:: Enabling and Disabling DDNS Updates +-----------------+--------------------+-------------------------------+ | dhcp-ddns: | Global | Outcome | - | enable-updates | ddns-send-udpates | | + | enable-updates | ddns-send-updates | | +=================+====================+===============================+ | false (default) | false | no updates at any scope | +-----------------+--------------------+-------------------------------+ @@ -3026,12 +3026,12 @@ together: | | | false for ddns-enable-updates | +-----------------+--------------------+-------------------------------+ -Kea 1.9.1 adds two new parameters. The first new parameter is ``ddns-update-on-renew``. -Normally, when leases are renewed the server will only update DNS if the DNS +Kea 1.9.1 adds two new parameters. The first new parameter is ``ddns-update-on-renew``. +Normally, when leases are renewed the server only updates DNS if the DNS information for the lease (e.g. FQDN, DNS update direction flags) has changed. Setting ``ddns-update-on-renew`` to true instructs the server to always update the DNS information when a lease is renewed even if its DNS information has not -changed. This allows Kea to "self-heal" in the event it was previously unable +changed. This allows Kea to "self-heal" in the event it was previously unable to add DNS entries or they were somehow lost by the DNS server. .. note:: @@ -3072,7 +3072,7 @@ conflict with existing entries owned by other DHCP4 clients. FQDN while new entries for Client-B will still be added. Disabling conflict resolution should be done only after careful review of - your specific use cases. The best way to avoid unwanted DNS entries is to + specific use cases. The best way to avoid unwanted DNS entries is to always ensure leases changes are processed through Kea, whether they are released, expire, or are deleted via the lease-del4 command, prior to reassigning either FQDNs or IP addresses. Doing so will cause kea-dhcp4 @@ -3328,9 +3328,9 @@ its value, simply set it to the desired string: } The suffix used when generating an FQDN, or when qualifying a partial -name, is specified by the ``ddns-qualifying-suffix`` parameter. It is -strongly recommended that you supply a value for qualifying prefix when -DDNS updates are enabled. For obvious reasons, we cannot supply a +name, is specified by the ``ddns-qualifying-suffix`` parameter. It is +strongly recommended that the user supply a value for the qualifying prefix when +DDNS updates are enabled. For obvious reasons, we cannot supply a meaningful default. :: @@ -3341,7 +3341,7 @@ meaningful default. ... } -When generating a name, kea-dhcp4 will construct the name in the format: +When generating a name, kea-dhcp4 constructs the name in the format: [**ddns-generated-prefix**]-[**address-text**].[**ddns-qualifying-suffix**]. @@ -3366,12 +3366,12 @@ and '-'. This may be accomplished with the following two parameters: - ``hostname-char-set`` - a regular expression describing the invalid character set. This can be any valid, regular expression using POSIX - extended expression syntax. Embedded nuls (0x00) will always be + extended expression syntax. Embedded nulls (0x00) are always considered an invalid character to be replaced (or omitted). - ``hostname-char-replacement`` - a string of zero or more characters - with which to replace each invalid character in the host name. An empty - string and will cause invalid characters to be OMITTED rather than replaced. + with which to replace each invalid character in the host name. An empty + string causes invalid characters to be OMITTED rather than replaced. .. note:: @@ -3380,10 +3380,10 @@ and '-'. This may be accomplished with the following two parameters: - "hostname-char-set": "[^A-Za-z0-9.-]", - "hostname-char-replacement": "" - This enables sanitizing and will omit any character that is not - a letter,digit, hyphen, dot or nul. + This enables sanitizing and omits any character that is not + a letter, digit, hyphen, dot, or null. -The following configuration will replace anything other than a letter, +The following configuration replaces anything other than a letter, digit, hyphen, or dot with the letter 'x': :: @@ -3433,11 +3433,11 @@ qualifying suffix (if one is defined and needed). .. note:: - Since the 1.6.0 Kea release it is possible to specify hostname-char-set + Since the 1.6.0 Kea release, it is possible to specify hostname-char-set and/or hostname-char-replacement at the global scope. This allows - to sanitize host names without requiring a dhcp-ddns entry. When + sanitizing host names without requiring a dhcp-ddns entry. When a hostname-char parameter is defined at the global scope and - in a dhcp-ddns entry the second (local) value is used. + in a dhcp-ddns entry, the second (local) value is used. .. _dhcp4-next-server: @@ -3862,8 +3862,8 @@ be retained on the lease. The lease's user-context will look something like thi .. note:: It is possible that other hook libraries are already making use of user-context. Enabling store-extended-info should not interfere with any other user-context - content so long as it does not also use an element labled "ISC". In other - words, user-context is intended to be a flexible container serving mulitple + content so long as it does not also use an element labeled "ISC". In other + words, user-context is intended to be a flexible container serving multiple purposes. As long as no other purpose also writes an "ISC" element to user-context there should not be a conflict. @@ -3906,10 +3906,10 @@ Multi-threading settings in different backends Both kea-dhcp4 and kea-dhcp6 are tested internally to determine which settings gave the best performance. Although this section describes our results, those are just recommendations and are very dependent on the particular hardware that was used -for testing. We strongly advice to run your own performance tests. +for testing. We strongly advise that administrators run their own performance tests. -Full report of Kea 1.7 performance results can be found `here <https://jenkins.isc.org/job/kea-1.7/job/performance/KeaPerformanceReport/>`_. -This include hardware description, test scenario descriptions and +A full report of Kea 1.7 performance results can be found `here <https://jenkins.isc.org/job/kea-1.7/job/performance/KeaPerformanceReport/>`_. +This includes hardware descriptions, test scenario descriptions, and current results. After enabling multi-threading, the number of threads is set by ``thread-pool-size`` @@ -3951,8 +3951,9 @@ IPv6 connectivity is available and they can shut down their IPv4 stack. The new should disable its stack for. The value is expressed in seconds. The RFC mentions V6ONLY_WAIT timer. This is implemented in Kea by setting the value of -v6-only-preferred option. This follows the usual practice of setting options. You can specify the -option value on pool, subnet, shared network, global levels or even specify it in host reservations. +v6-only-preferred option. This follows the usual practice of setting options. The +option value can be specified on pool, subnet, shared network, or global levels, or even +via host reservations. Note there is no special processing involved. This follows the standard Kea option processing regime. The option will not be sent back, unless the client explicitly requests it. For example, to @@ -4401,7 +4402,7 @@ to them. } ] } -In some cases the host reservations can be used in conjuction with client +In some cases the host reservations can be used in conjunction with client classes specified within the Kea configuration. In particular, when a host reservation exists for a client within a given subnet, the "KNOWN" built-in class is assigned to the client. Conversely, when there is no @@ -4427,7 +4428,7 @@ evaluation of the class after the lease has been allocated and thus the reserved class has been also assigned. .. note:: - Be aware that the classes specified in non global host reservations + Be aware that the classes specified in non-global host reservations are assigned to the processed packet after all classes with the ``only-if-required`` parameter set to ``false`` have been evaluated. This has an implication that these classes must not depend on the @@ -4539,8 +4540,8 @@ The ``reservation-mode`` parameter can be specified at: ``.Dhcp4["shared-networks"][].subnet4[]["reservation-mode"]`` (highest priority: overrides all others) -For deciding what ``"reservation-mode"`` to choose, you may refer to the -following decision diagram: +To decide which ``"reservation-mode"`` to choose, the +following decision diagram may be useful: :: @@ -5125,24 +5126,24 @@ It is possible to control the ``ip-reservations-unique`` via the the currently used backends (backends do not support the new setting), the new setting is ignored and the warning log message is output. The backends continue to use the default setting, i.e. expecting that -IP reservations are unique within each subnet. In order to allow -creating non unique IP reservations the administrator must remove -the backends which lack support for it from the configuration file. +IP reservations are unique within each subnet. To allow the +creation of non-unique IP reservations, the administrator must remove +the backends which lack support for them from the configuration file. -The administrators must be careful when they have been using multiple -reservations for the same IP address and later decided to return to +Administrators must be careful when they have been using multiple +reservations for the same IP address and later decide to return to the default mode in which this is no longer allowed. The administrators must make sure that at most one reservation for the given IP address exists within a subnet prior to switching back to the default mode. If such duplicates are left in the configuration file, the server -will report a configuration error. Leaving such reservations in the host +reports a configuration error. Leaving such reservations in the host databases does not cause configuration errors but may lead to lease -allocation errors during the server operation when it unexpectedly +allocation errors during the server's operation, when it unexpectedly finds multiple reservations for the same IP address. .. note:: - Currently the server does not verify if multiple reservations for + Currently the server does not verify whether multiple reservations for the same IP address exist in the host databases (MySQL and/or PostgreSQL) when ``ip-reservations-unique`` is updated from ``true`` to ``false``. This may cause issues with lease allocations. @@ -6385,14 +6386,14 @@ Beginning with Kea 1.7.7 the DHCPv4 server provides two global parameters to control statistics default sample limits: - ``statistic-default-sample-count`` - determines the default maximum - number of samples which will be kept. The special value of zero - means to use a default maximum age. + number of samples which are kept. The special value of zero + indicates that a default maximum age should be used. - ``statistic-default-sample-age`` - determines the default maximum - age in seconds of samples which will be kept. + age in seconds of samples which are kept. -For instance to reduce the statistic keeping overhead you can set -the default maximum sample count to 1 so only one sample will be kept by: +For instance, to reduce the statistic keeping overhead, set +the default maximum sample count to 1 so only one sample is kept: :: diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index f908f29171..208b6bf265 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -670,9 +670,9 @@ entry, as in: For additional Cassandra-specific parameters, see :ref:`cassandra-database-configuration4`. -If the same host is configured both in-file and in-database, Kea won't warn of -the duplicate like it would if you specified them both in the same data source. -Instead the host configured in-file will have priority over the one configured +If the same host is configured both in-file and in-database, Kea does not issue a warning, +as it would if both were specified in the same data source. +Instead, the host configured in-file has priority over the one configured in-database. .. _read-only-database-configuration6: @@ -2717,18 +2717,18 @@ The default configuration and values would appear as follows: } As of Kea 1.7.1, there are two parameters which determine if kea-dhcp6 -can generate DDNS requests to D2. The existing, ``dhcp-ddns:enable-updates`` -parameter which now only controls whether kea-dhcp6 connects to D2. -And the new behavioral parameter, ``ddns-send-updates``, which determines -if DDNS updates are enabled at a given level (i.e global, shared-network, -or subnet). The following table shows how the two parameters function +can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates`` +parameter, which now only controls whether kea-dhcp6 connects to D2; +and the new behavioral parameter, ``ddns-send-updates``, which determines +whether DDNS updates are enabled at a given level (i.e. global, shared-network, +or subnet). The following table shows how the two parameters function together: .. table:: Enabling and Disabling DDNS Updates +-----------------+--------------------+-------------------------------+ | dhcp-ddns: | Global | Outcome | - | enable-updates | ddns-send-udpates | | + | enable-updates | ddns-send-updates | | +=================+====================+===============================+ | false (default) | false | no updates at any scope | +-----------------+--------------------+-------------------------------+ @@ -2790,10 +2790,10 @@ conflict with existing entries owned by other DHCP6 clients. FQDN while new entries for Client-B will still be added. Disabling conflict resolution should be done only after careful review of - your specific use cases. The best way to avoid unwanted DNS entries is to + specific use cases. The best way to avoid unwanted DNS entries is to always ensure leases changes are processed through Kea, whether they are released, expire, or are deleted via the lease-del6 command, prior to - reassigning either FQDNs or IP addresses. Doing so will cause kea-dhcp6 + reassigning either FQDNs or IP addresses. Doing so causes kea-dhcp6 to generate DNS removal requests to D2. @@ -3027,7 +3027,7 @@ follows: "Dhcp6": { ... - "ddsn-replace-client-name": "always", + "ddns-replace-client-name": "always", ... } @@ -3056,14 +3056,14 @@ are enabled. To set its value simply set it to the desired string: ... } -When qualifying a partial name, kea-dhcp6 will construct the name in the +When qualifying a partial name, kea-dhcp6 constructs the name in the format: [**candidate-name**].[**ddns-qualifying-suffix**]. where **candidate-name** is the partial name supplied in the DHCPREQUEST. For example, if the FQDN domain name value is "some-computer" and the -``ddsn-qualifying-suffix`` "example.com", the generated FQDN is: +``ddns-qualifying-suffix`` "example.com", the generated FQDN is: **some-computer.example.com.** @@ -3093,12 +3093,12 @@ accomplished with the following two parameters: - ``hostname-char-set`` - a regular expression describing the invalid character set. This can be any valid, regular expression using POSIX - extended expression syntax. Embedded nuls (0x00) will always be + extended expression syntax. Embedded nulls (0x00) are always considered an invalid character to be replaced (or omitted). - ``hostname-char-replacement`` - a string of zero or more characters with which to replace each invalid character in the host name. An empty - string and will cause invalid characters to be OMITTED rather than replaced. + string causes invalid characters to be OMITTED rather than replaced. .. note:: @@ -3107,10 +3107,10 @@ accomplished with the following two parameters: - "hostname-char-set": "[^A-Za-z0-9.-]", - "hostname-char-replacement": "" - This enables sanitizing and will omit any character that is not - a letter,digit, hyphen, dot or nul. + This enables sanitizing and omits any character that is not + a letter, digit, hyphen, dot, or null. -The following configuration will replace anything other than a letter, +The following configuration replaces anything other than a letter, digit, hyphen, or dot with the letter 'x': :: @@ -3156,11 +3156,11 @@ qualifying suffix (if one is defined and needed). .. note:: - Since the 1.6.0 Kea release it is possible to specify hostname-char-set + Since the 1.6.0 Kea release, it is possible to specify hostname-char-set and/or hostname-char-replacement at the global scope. This allows - to sanitize host names without requiring a dhcp-ddns entry. When + sanitizing of host names without requiring a dhcp-ddns entry. When a hostname-char parameter is defined at the global scope and - in a dhcp-ddns entry the second (local) value is used. + in a dhcp-ddns entry, the second (local) value is used. .. _dhcp6-dhcp4o6-config: @@ -3371,16 +3371,16 @@ pretty-printed for clarity): information within Kea. .. note:: - It is possible that other hook libraries are already making use of - user-context. Enabling store-extended-info should not interfere with - any other user-context content so long as it does not also use an element - labled "ISC". In other words, user-context is intended to be a flexible - container serving mulitple purposes. As long as no other purpose also + It is possible that other hook libraries are already using + user-context. Enabling store-extended-info should not interfere with + any other user-context content, as long as it does not also use an element + labeled "ISC". In other words, user-context is intended to be a flexible + container serving multiple purposes. As long as no other purpose also writes an "ISC" element to user-context there should not be a conflict. .. _dhcp6-multi-threading-settings: -Multi-threading settings +Multi-Threading Settings ------------------------ The Kea server can be configured to process packets in parallel using multiple @@ -3411,16 +3411,16 @@ An example configuration that sets these parameter looks as follows: ... } -Multi-threading settings in different backends +Multi-Threading Settings in Different Backends ---------------------------------------------- Both kea-dhcp4 and kea-dhcp6 are tested internally to determine which settings -gave the best performance. Although this section describes our results, those are just +give the best performance. Although this section describes our results, they are merely recommendations and are very dependent on the particular hardware that was used -for testing. We strongly advice to run your own performance tests. +for testing. We strongly advise that administrators run their own performance tests. -Full report of Kea 1.7 performance results can be found `here <https://jenkins.isc.org/job/kea-1.7/job/performance/KeaPerformanceReport/>`_. -This includes hardware description, test scenario descriptions and +A full report of Kea 1.7 performance results can be found `here <https://jenkins.isc.org/job/kea-1.7/job/performance/KeaPerformanceReport/>`_. +This includes hardware descriptions, test scenario descriptions, and current results. After enabling multi-threading, the number of threads is set by ``thread-pool-size`` @@ -3846,7 +3846,7 @@ to them. } ] } -In some cases the host reservations can be used in conjuction with client +In some cases the host reservations can be used in conjunction with client classes specified within the Kea configuration. In particular, when a host reservation exists for a client within a given subnet, the "KNOWN" built-in class is assigned to the client. Conversely, when there is no @@ -3872,7 +3872,7 @@ evaluation of the class after the lease has been allocated and thus the reserved class has been also assigned. .. note:: - Be aware that the classes specified in non global host reservations + Be aware that the classes specified in non-global host reservations are assigned to the processed packet after all classes with the ``only-if-required`` parameter set to ``false`` have been evaluated. This has an implication that these classes must not depend on the @@ -3984,8 +3984,8 @@ The ``reservation-mode`` parameter can be specified at: ``.Dhcp6["shared-networks"][].subnet6[]["reservation-mode"]`` (highest priority: overrides all others) -For deciding what ``"reservation-mode"`` to choose, you may refer to the -following decision diagram: +To decide which ``"reservation-mode"`` to choose, the +following decision diagram may be useful: :: @@ -4557,25 +4557,25 @@ It is possible to control the ``ip-reservations-unique`` via the the currently used backends (backends do not support the new setting), the new setting is ignored and the warning log message is output. The backends continue to use the default setting, i.e. expecting that -IP reservations are unique within each subnet. In order to allow -creating non unique IP reservations the administrator must remove +IP reservations are unique within each subnet. To allow the +creation of non-unique IP reservations, the administrator must remove the backends which lack support for it from the configuration file. -The administrators must be careful when they have been using multiple +Administrators must be careful when they have been using multiple reservations for the same IP address and/or delegated prefix and later -decided to return to the default mode in which this is no longer allowed. +decide to return to the default mode in which this is no longer allowed. The administrators must make sure that at most one reservation for the given IP address or delegated prefix exists within a subnet prior to switching back to the default mode. If such duplicates are left in -the configuration file, the server will report a configuration error. +the configuration file, the server reports a configuration error. Leaving such reservations in the host databases does not cause configuration errors but may lead to lease allocation errors during -the server operation when it unexpectedly finds multiple reservations +the server operation, when it unexpectedly finds multiple reservations for the same IP address or delegated prefix. .. note:: - Currently the server does not verify if multiple reservations for + Currently the server does not verify whether multiple reservations for the same IP address and/or delegated prefix exist in the host databases (MySQL and/or PostgreSQL) when ``ip-reservations-unique`` is updated from ``true`` to ``false``. This may cause issues with @@ -4932,7 +4932,7 @@ host reservation in this subnet or simply the initially selected subnet has no more addresses available. Therefore, it is strongly recommended to always specify subnet selectors (interface or a relay address) at shared network level if the subnets belong to a shared network, as it is rarely useful to -specify them at the subnet level and it may lead to the configurtion errors +specify them at the subnet level and it may lead to the configuration errors described above. Client Classification in Shared Networks @@ -5459,7 +5459,7 @@ Using a Specific Relay Agent for a Subnet ========================================= The DHCPv6 server follows the same principles as the DHCPv4 server to -select a subnet for the client with noticable differences mainly for +select a subnet for the client, with noticeable differences mainly for relays. .. note:: @@ -5729,7 +5729,7 @@ default, the following syntax can be used: The parameter is expressed in seconds, so the example above will instruct the server to recycle declined leases after one hour. -There are several statistics and hook points associated with the Decline +There are several statistics and hook points associated with the decline handling procedure. The lease6_decline hook is triggered after the incoming DHCPDECLINE message has been sanitized and the server is about to decline the lease. The declined-addresses statistic is increased @@ -6371,18 +6371,18 @@ The DHCPv6 server supports the following statistics: This section describes DHCPv6-specific statistics. For a general overview and usage of statistics, see :ref:`stats`. -Beginning with Kea 1.7.7 the DHCPv6 server provides two global +Beginning with Kea 1.7.7, the DHCPv6 server provides two global parameters to control statistics default sample limits: - ``statistic-default-sample-count`` - determines the default maximum - number of samples which will be kept. The special value of zero - means to use a default maximum age. + number of samples which are kept. The special value of zero + indicates that a default maximum age should be used. - ``statistic-default-sample-age`` - determines the default maximum - age in seconds of samples which will be kept. + age in seconds of samples which are kept. -For instance to reduce the statistic keeping overhead you can set -the default maximum sample count to 1 so only one sample will be kept by: +For instance, to reduce the statistic keeping overhead, set +the default maximum sample count to 1 so that only one sample is kept: :: diff --git a/doc/sphinx/arm/hooks-cb-cmds.rst b/doc/sphinx/arm/hooks-cb-cmds.rst index 8d6cb315ff..d3d80e9bf8 100644 --- a/doc/sphinx/arm/hooks-cb-cmds.rst +++ b/doc/sphinx/arm/hooks-cb-cmds.rst @@ -335,9 +335,9 @@ database: } } -The server tag must be unique accross all servers in the database. When the +The server tag must be unique across all servers in the database. When the server information under the given server tag already exists, it is replaced -with the new information. The specified server tag is case insensitive. The +with the new information. The specified server tag is case-insensitive, and the maximum length of the server tag is 256 characters. The following keywords are reserved and must not be used as server tags: "all" and "any". @@ -1366,12 +1366,12 @@ belong. The `server-tags` parameter must not be specified for this command. The remote-option6-pd-pool-set Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This command creates a new prefix delefation pool specific DHCPv6 option or +This command creates a new prefix delegation pool-specific DHCPv6 option or replaces an existing option in the database. The structure of the option information is the same as in the Kea configuration file (see :ref:`dhcp4-std-options` and :ref:`dhcp6-std-options`). The option information is carried in the `options` list. Another list, `pd-pools`, contains a map with the prefix -delegation pool prefix and the prefix length identifying the pool. If such +delegation pool prefix and the prefix length identifying the pool. If such an option already exists for the prefix delegation pool, it is replaced with the new instance. @@ -1518,7 +1518,7 @@ option is deleted. The following command attempts to delete an option having the option code 5 in the top-level option space from the subnet -having an identifer of 123. +having an identifier of 123. :: @@ -1727,10 +1727,10 @@ be used by the "server1" and "server2": } } -The `server-tags` parameter is mandatory and it contains one or -more server tags. It may contain the keyword "all" to fetchg the subnets +The `server-tags` parameter is mandatory and contains one or +more server tags. It may contain the keyword "all", to fetch the subnets associated with all servers. When the `server-tags` list -contains the `null` value the returned response contains a list +contains the `null` value, the returned response contains a list of unassigned subnets, i.e. the subnets which are associated with no servers. For example: diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst index 6663acc990..8d862a1061 100644 --- a/doc/sphinx/arm/hooks-ha.rst +++ b/doc/sphinx/arm/hooks-ha.rst @@ -238,12 +238,12 @@ The following is the list of all possible server states: - ``partner-in-maintenance`` - an active server transitions to this state after receiving a ``ha-maintenance-start`` command from the administrator. The server in this state becomes responsible - for responding to all DHCP requests. The server sends - ``ha-maintenance-notify`` command to the partner which is supposed - to enter the ``in-maintenance`` state. If that is the case, the server + for responding to all DHCP requests. The server sends a + ``ha-maintenance-notify`` command to the partner, which should + enter the ``in-maintenance`` state. The server remaining in the ``partner-in-maintenance`` state keeps sending lease - updates to the partner until it finds that the parter stops - responding to those lease updates, heartbeats or any other commands. + updates to the partner until it finds that the partner has stopped + responding to those lease updates, heartbeats, or any other commands. In this case, the server in the ``partner-in-maintenance`` state transitions to the ``partner-down`` state and keeps responding to the queries, but no longer sends lease updates. @@ -259,7 +259,7 @@ The following is the list of all possible server states: is still provisioned. This default configuration can be changed by setting the ``wait-backup-ack`` configuration parameter to ``true``, in which case the primary server always waits for the acknowledgements - and drops the DHCP query if sending any of the correponding lease + and drops the DHCP query if sending any of the corresponding lease updates fails. This improves lease database consistency between the primary and the secondary. However, if a communication failure between the active server and any of the backups occurs, it effectively causes @@ -565,7 +565,7 @@ low a value for the ``max-unacked-clients`` parameter may result in a transition to the ``partner-down`` state even though the partner is still operating. On the other hand, selecting too high a value may result in never transitioning to the ``partner-down`` state if the DHCP -traffic in the network is very low (e.g. at nighttime), because the number +traffic in the network is very low (e.g. at night), because the number of distinct clients trying to communicate with the server could be lower than the ``max-unacked-clients`` setting. @@ -879,16 +879,16 @@ mode, thus they are not specified here. For example: ``heartbeat-delay``, should not be specified in the passive-backup mode. The ``wait-backup-ack`` is a boolean parameter not present in previous examples. It defaults to ``false`` and must not be modified in the load-balancing and hot-standby modes. In the passive-backup -mode this parameter can be set to ``true`` which causes the primary server to expect +mode this parameter can be set to ``true``, which causes the primary server to expect acknowledgments to the lease updates from the backup servers prior to responding -to the DHCP client. It ensures that the lease was propagated to all servers before -the client is given the lease, but it poses a risk of loosing a DHCP service if +to the DHCP client. It ensures that the lease has propagated to all servers before +the client is given the lease, but it poses a risk of losing a DHCP service if there is a communication problem with one of the backup servers. This setting -also increases the latency of the DHCP response because of the time that the +also increases the latency of the DHCP response, because of the time that the primary spends waiting for the acknowledgements. We recommend that the -``wait-backup-ack`` is left at its default value if the DHCP service reliability +``wait-backup-ack`` setting be left at its default value, if the DHCP service reliability is more important than consistency of the lease information between the -primary and the backups and in all cases when the DHCP service latency should +primary and the backups, and in all cases when the DHCP service latency should be minimal. .. _ha-sharing-lease-info: @@ -1305,16 +1305,16 @@ the servers while the other one continues to respond to the DHCP queries. When the upgraded server is back online, the upgrade can be performed for the second server. The typical problem reported for the earlier versions of the High Availability hooks library was that the administrator did not -have a direct control over the state of the DHCP server. Shutting down -one of the servers for maintenance didn't necessarily cause the other -server to start reponding to all DHCP queries because the failure +have direct control over the state of the DHCP server. Shutting down +one of the servers for maintenance did not necessarily cause the other +server to start responding to all DHCP queries, because the failure detection algorithm described in :ref:`ha-scope-transition` requires that -the partner does not respond for a configured period of time and, +the partner not respond for a configured period of time and, depending on the configuration, may also require that a number of DHCP -requests are not responded for a configured period of time. The -maintenance procedure, however, requires that the administrator is able -to instruct one of the servers to instantly start serving all DHCP clients -and the other server to instantly stop serving any DHCP clients so as it +requests are not responded to for a configured period of time. The +maintenance procedure, however, requires that the administrator be able +to instruct one of the servers to instantly start serving all DHCP clients, +and the other server to instantly stop serving any DHCP clients, so it can be safely shut down. The maintenance feature of the High Availability hooks library addresses @@ -1597,15 +1597,15 @@ to the failing server allows for detecting the failure. The status-get Command ------------------------ -The ``status-get`` is the general purpose command supported by several Kea deamons, +``status-get`` is a general-purpose command supported by several Kea daemons, not only DHCP servers. However, when sent to the DHCP server with HA enabled, it -can be used to get insight into the details of the HA specific status information -of the servers being in the HA configuration. Not only does the response contain -the status information of the server receiving this command but also the -information about its partner, if this information is available. +can be used to get insight into the details of the HA-specific status information +of the servers used in the HA configuration. Not only does the response contain +the status information of the server receiving this command, but also the +information about its partner if it is available. -The following is the example response to the ``status-get`` command including -the HA status of two load balancing servers: +The following is an example response to the ``status-get`` command, including +the HA status of two load-balancing servers: :: diff --git a/doc/sphinx/arm/hooks-lease-cmds.rst b/doc/sphinx/arm/hooks-lease-cmds.rst index cb5c38deb4..52b04643ae 100644 --- a/doc/sphinx/arm/hooks-lease-cmds.rst +++ b/doc/sphinx/arm/hooks-lease-cmds.rst @@ -280,17 +280,17 @@ The lease6-bulk-apply Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``lease6-bulk-apply`` was implemented to address -the performance penalty in the High Availability when a single DHCPv6 -transaction resulted in multiple lease updates sent to the partner if +the performance penalty in the High-Availability mode when a single DHCPv6 +transaction resulted in multiple lease updates sent to the partner, if multiple address and/or prefix leases were allocated. Consider the case when a DHCPv6 client requests the assignment of two IPv6 addresses and two IPv6 -prefixes. That may result in allocation of 4 leases. In addition, the -DHCPv6 may assign different address than requested by the client during -the renew or rebind and delete the leases previously used by this client. -The are 6 of lease changes sent between the HA partners is in this case. -Sending these updates in individual commands, e.g. ``lease6-update`` -is highly inefficient and produces unnecessary delays in communication -between the HA partners and in sending the response to the DHCPv6 client. +prefixes: that may result in allocation of 4 leases. In addition, +DHCPv6 may assign a different address than the one requested by the client during +the renew or rebind stage, and delete the leases previously used by this client. +There are six lease changes sent between the HA partners in this case. +Sending these updates in individual commands, e.g. via ``lease6-update``, +is highly inefficient and produces unnecessary delays in communication, +both between the HA partners and in sending the response to the DHCPv6 client. The ``lease6-bulk-apply`` command deals with this problem by aggregating all lease changes in a single command. Both @@ -299,7 +299,7 @@ The receiving server iterates over the deleted leases and deletes them from its lease database. Next, it iterates over the new/updated leases and adds them to the database or updates them if they already exist. -Even though the High Avialability is the major application for +Even though High Availability is the major application for this command, it can be freely used in all cases when it is desired to send multiple lease changes in a single command. @@ -342,10 +342,10 @@ or update two other leases in the database: } If any of the leases is malformed, no leases changes are applied -to the lease database. If the leases are well formed but there is a +to the lease database. If the leases are well-formed but there is a failure to apply any of the lease changes to the database, the command -will continue to be processed for other leases. All the leases for which -the command was unable to apply the changes in the database will be +continues to be processed for other leases. All the leases for which +the command was unable to apply the changes in the database are listed in the response. For example: :: diff --git a/doc/sphinx/arm/hooks-lease-query.rst b/doc/sphinx/arm/hooks-lease-query.rst index cd8e5a9415..774009c801 100644 --- a/doc/sphinx/arm/hooks-lease-query.rst +++ b/doc/sphinx/arm/hooks-lease-query.rst @@ -86,19 +86,19 @@ In addition, one or more of the following options will be included: +------------------------------+-------+-----------------------------------------------+ | Option | Code | Content | +==============================+=======+===============================================+ - | dhcp-client-identifier | 61 | copied from the lease (if one) | + | dhcp-client-identifier | 61 | copied from the lease (if appropriate) | +------------------------------+-------+-----------------------------------------------+ - | client-last-transaction-time | 91 | amount of time that has elapsed since the | - | | | lease's client-last-transaction-time (CLTT) | - | | | This value will also be used by the server to | - | | | adjust life time and timer values. | + | client-last-transaction-time | 91 | the amount of time that has elapsed since the | + | | | lease's client-last-transaction-time (CLTT). | + | | | This value is also used by the server to | + | | | adjust lifetime and timer values. | +------------------------------+-------+-----------------------------------------------+ - | dhcp-lease-time | 51 | lease's life time reduced by CLTT | + | dhcp-lease-time | 51 | lease's lifetime reduced by CLTT | +------------------------------+-------+-----------------------------------------------+ | dhcp-renewal-time | 58 | as controlled by kea-dhcp4 configuration and | | | | then reduced by CLTT | +------------------------------+-------+-----------------------------------------------+ - | dhcp-rebind-time | 59 | as dictacted by kea-dhcp4 configuration and | + | dhcp-rebind-time | 59 | as dictated by kea-dhcp4 configuration and | | | | then reduced by CLTT | +------------------------------+-------+-----------------------------------------------+ | dhcp-agent-options | 82 | if stored on the lease. (See | @@ -288,9 +288,9 @@ The client-data option will encapsulate the following options: | | | - preferred life time reduced by CLTT | +------------------------------+-------+-----------------------------------------------+ -If the lease with the most recent CLTT value (Client Last -Transmission Time) has relay information in it's user-context (see -:ref:`store-extended-info-v6`), then an OPTION_LQ_RELAY_DATA option will be +If the lease with the most recent client-last-transaction-time (CLTT) +value has relay information in its user-context (see +:ref:`store-extended-info-v6`), then an OPTION_LQ_RELAY_DATA option is added to the reply (see `RFC 5007, Section 4.1.2.4 <https://tools.ietf.org/html/rfc5007#section-4.1.2.4>`__). diff --git a/doc/sphinx/arm/hooks-radius.rst b/doc/sphinx/arm/hooks-radius.rst index 86bf274e57..25951fca28 100644 --- a/doc/sphinx/arm/hooks-radius.rst +++ b/doc/sphinx/arm/hooks-radius.rst @@ -111,7 +111,7 @@ To download and compile Boost 1.65, please use the following commands: .. code-block:: console $ wget -nd https://dl.bintray.com/boostorg/release/1.65.1/source/boost_1_65_1.tar.gz - $ tar zxvf boost_1_65_1.tar.gz + $ tar -zxvf boost_1_65_1.tar.gz $ cd boost_1_65_1/ $ ./bootstrap.sh $ ./b2 --without-python @@ -137,7 +137,7 @@ Choice 2: get a tarball and extract it .. parsed-literal:: - $ tar zxvf kea-|release|.tar.gz + $ tar -zxvf kea-|release|.tar.gz The next step is to extract the premium Kea package that contains the RADIUS repository into the Kea sources. After the tarball is extracted, @@ -146,7 +146,7 @@ the Kea sources should have a premium/ subdirectory. .. parsed-literal:: $ cd kea - $ tar zxvf ../kea-premium-radius-|release|.tar.gz + $ tar -zxvf ../kea-premium-radius-|release|.tar.gz Once this is done, verify that the Kea sources look similar to this: @@ -283,7 +283,7 @@ Please make sure that the compilation includes the following: - FreeRADIUS client directories printed and pointing to the right directories; - Boost version at least 1.65.1. The versions available in CentOS 7 - (1.48 and and 1.53) are too old. + (1.48 and 1.53) are too old. Once the configuration is complete, compile Kea using make. If the system has more than one core, using the "-j N" diff --git a/doc/sphinx/arm/hooks.rst b/doc/sphinx/arm/hooks.rst index c612be89c8..007665922d 100644 --- a/doc/sphinx/arm/hooks.rst +++ b/doc/sphinx/arm/hooks.rst @@ -86,7 +86,7 @@ Unpack this tarball: .. parsed-literal:: - $ tar zxvf kea-|release|.tar.gz + $ tar -zxvf kea-|release|.tar.gz This will unpack the tarball into the kea-|release| subdirectory of the current working directory. @@ -99,7 +99,7 @@ steps will unpack the premium tarball into the correct location: .. parsed-literal:: $ cd kea-|release| - $ tar xvf ../kea-premium-|release|.tar.gz + $ tar -xvf ../kea-premium-|release|.tar.gz Note that unpacking the Kea premium package will put the files into a directory named "premium". Regardless of the name of the package, the @@ -390,7 +390,7 @@ loaded by the correct process per the table below. | | |load balancing and is sometimes referred to as | | | |active-active. Each server can handle selected group of | | | |clients in this network or all clients, if it detects that | - | | |its partner has became unavailable. It is also possible to | + | | |its partner has become unavailable. It is also possible to | | | |designate one server to serve all DHCP clients, and leave | | | |another server as "standby". This mode is called hot standby| | | |and is sometimes referenced to as active-passive. This | @@ -406,7 +406,7 @@ loaded by the correct process per the table below. | | |for Kea DHCP servers. | +-----------------+---------------+------------------------------------------------------------+ | Statistics | Kea sources |The Statistics Commands library provides additional | - | Commands | (since 1.4) |commmands for retrieving accurate DHCP lease statistics for | + | Commands | (since 1.4) |commands for retrieving accurate DHCP lease statistics for | | | |Kea DHCP servers that share the same lease database. This | | | |setup is common in deployments where DHCP service redundancy| | | |is required and a shared lease database is used to avoid | @@ -2977,8 +2977,8 @@ entries at the beginning of maps, but this was withdrawn in 1.7.9. As of Kea 1.3, the structures that allow user contexts are pools of all types (addresses and prefixes) and subnets. Kea 1.4 extended user -context support to the global scope, interfaces config, shared networks, -subnets, client classes, option datas and definitions, host -reservations, control socket, dhcp ddns, loggers and server id. These -are supported in both DHCPv4 and DHCPv6, with the exception of server id +context support to the global scope, interfaces configuration, shared networks, +subnets, client classes, option data and definitions, host +reservations, control socket, dhcp ddns, loggers and server ID. These +are supported in both DHCPv4 and DHCPv6, with the exception of server ID which is DHCPv6 only. diff --git a/doc/sphinx/arm/install.rst b/doc/sphinx/arm/install.rst index 474e8a7f09..6a5fd5904c 100644 --- a/doc/sphinx/arm/install.rst +++ b/doc/sphinx/arm/install.rst @@ -7,13 +7,13 @@ Installation Packages ======== -Starting with Kea 1.6.0, ISC now publishes native RPM, deb and APK -packages along with the tarballs with the source code. The packages +Starting with Kea 1.6.0, ISC now publishes native RPM, deb, and APK +packages, along with the tarballs with the source code. The packages are available on `Cloudsmith <https://cloudsmith.io/~isc/repos/>`_ at -https://cloudsmith.io/~isc/repos. You can download the native packages -and install them using the system available in your distribution (such -as dpkg or rpm). Also, you can add the Kea repository to your system, -which will make it easier to install updates. For details, please +https://cloudsmith.io/~isc/repos. The native packages can be downloaded +and installed using the system available in a specific distribution (such +as dpkg or rpm). The Kea repository can also be added to the system, +making it easier to install updates. For details, please go to https://cloudsmith.io/~isc/repos, choose the repository of interest and then click the ``Set Me Up`` button for detailed instructions. @@ -63,9 +63,9 @@ various development include headers and program development tools. .. note:: Some operating systems have split their distribution packages into a - run-time and a development package. You will need to install the + run-time and a development package. The development package versions, which include header files and - libraries, to build Kea from the source code. + libraries, must be installed to build Kea from the source code. Building from source code requires the following software installed on the system: @@ -137,7 +137,7 @@ Although Kea may be available in pre-compiled, ready-to-use packages from operating system vendors, it is open source software written in C++. As such, it is freely available in source code form from ISC as a downloadable tar file. The source code can also be obtained from the Kea -Gitlab repository at https://gitlab.isc.org/isc-projects/kea. This +GitLab repository at https://gitlab.isc.org/isc-projects/kea. This section describes how to build Kea from the source code. Download Tar File @@ -146,7 +146,7 @@ Download Tar File The Kea release tarballs may be downloaded from: https://downloads.isc.org/isc/kea/ . -Retrieve from Git +Retrieve From Git ----------------- Downloading this "bleeding edge" code is recommended only for developers @@ -176,13 +176,13 @@ files. They can be created by running ``autoreconf`` with the ``--install`` switch. This will run ``autoconf``, ``aclocal``, ``libtoolize``, ``autoheader``, ``automake``, and related commands. -Write access to the Kea repository is only granted to ISC staff. If you -are a developer planning to contribute to Kea, please check our +Write access to the Kea repository is only granted to ISC staff. +Developers planning to contribute to Kea, should check our `Contributor's Guide <https://gitlab.isc.org/isc-projects/kea/blob/master/contributors-guide.md>`__. The `Kea Developer's Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/>`__ contains more -information about the process, as well as describes the requirements for +information about the process, and describes the requirements for contributed code to be accepted by ISC. .. _configure: @@ -255,11 +255,11 @@ options. Some commonly used options are: This option requires subscription-only RADIUS hook. - ``--with-freeradius-dictionary`` - Specifies a non-standard location for a FreeRADIUS dictionary file. That + Specify a non-standard location for a FreeRADIUS dictionary file. That file contains list of supported RADIUS attributes. Available in subscriber only version. This option requires subscription-only RADIUS hook. -If you don't see the RADIUS options, make sure you have RADIUS hook sources in +If the RADIUS options are not available, ensure that the RADIUS hook sources are in the ``premium`` directory and rerun ``autoreconf -i``. .. note:: @@ -267,15 +267,15 @@ the ``premium`` directory and rerun ``autoreconf -i``. The ``--runstatedir`` in the installation directories is particular. There are three cases: - - You use autoconf 2.70 or greater which supports this, but this autoconf + - The system uses autoconf 2.70 or greater which supports this, but this autoconf version has not been released yet. - - You use autoconf 2.69 patched to add support of this. In this case and the - previous simply use when needed the``--runstatedir`` configure parameter. + - The system uses autoconf 2.69 patched to add this support. In this case and the + previous, simply use the ``--runstatedir`` configure parameter when needed. - There is no support (the configure parameter is not recognized and configure directly raises an error). For autoconf 2.69 the ``runstatedir`` environment - variable is supported so simply remove the ``--`` before ``runstatedir`` + variable is supported, so simply remove the ``--`` before ``runstatedir`` in the configure script call, e.g.: ``./configure runstatedir=/opt/run ...`` .. @@ -292,14 +292,14 @@ developers, or people who want to extend Kea code or send patches: - ``--with-gtest``, ``--with-gtest-source`` Enable the building of the C++ Unit Tests using the Google Test framework. This option specifies the path to the gtest source. (If - the framework is not installed on your system, it can be downloaded + the framework is not installed on the system, it can be downloaded from https://github.com/google/googletest.) - ``--enable-generate-docs`` Enable the rebuilding Kea documentation. ISC publishes Kea - documentation for each release; however, in some cases you may want - to rebuild it. For example, if you want to change something in the - docs, or want to generate new ones from git sources that are not + documentation for each release; however, in some cases it may be + desirable to rebuild it: for example, to change something in the + docs, or to generate new ones from git sources that are not released yet. - ``--enable-generate-parser`` @@ -307,23 +307,23 @@ developers, or people who want to extend Kea code or send patches: and bison (.yy files). Kea sources have C++/h files generated out from them. By default Kea does not use flex or bison to avoid requiring installation of unnecessary dependencies for users. - However, if you change anything in the parses (such as adding a new - parameter), you will need to use flex and bison to regenerate - parsers. This option lets you do that. + However, anything in the parses is changed (such as adding a new + parameter), flex and bison are required to regenerate + parsers. This option permits that. - ``--enable-generate-messages`` Enable the regeneration of messages files from their messages source files, e.g. regenerate xxx_messages.h and xxx_messages.cc from xxx_messages.mes using the Kea message compiler. By default Kea is built using these .h and .cc files from the distribution. However, if - you change anything in a .mes file (such as adding a new message), you - will need to build and use the Kea message compiler. This option lets - you do that. + anything in a .mes file is changed (such as adding a new message), + the Kea message compiler needs to be built and used. This option + permits that. - ``--with-benchmark``, ``--with-benchmark-source`` Enable the building of the database backend benchmarks using the Google Benchmark framework. This option specifies the path to the - gtest source. (If the framework is not installed on your system, it + gtest source. (If the framework is not installed on the system, it can be downloaded from https://github.com/google/benchmark.) This support is experimental. @@ -338,9 +338,10 @@ enabled, and sets the installation location to /opt/kea: --with-pgsql=/usr/local/bin/pg_config \ --prefix=/opt/kea -If you have any problems with building Kea using the header-only Boost -code, or you'd like to use the Boost system library (assumed for the -sake of this example to be located in /usr/pkg/lib): +Users who have any problems with building Kea using the header-only Boost +code, or who would like to use the Boost system library (assumed for the +sake of this example to be located in /usr/pkg/lib), should issue these +commands: .. code-block:: console @@ -384,7 +385,7 @@ errors. If required, run ``ldconfig`` as root with ``/usr/local/lib`` (or with prefix/lib if configured with --prefix) in ``/etc/ld.so.conf`` (or the -relevant linker cache configuration file for your OS): +relevant linker cache configuration file for the OS): .. code-block:: console @@ -394,7 +395,7 @@ relevant linker cache configuration file for your OS): .. note:: - If you do not run ``ldconfig`` where it is required, you may see + If ``ldconfig`` is not run where required, users may see errors like the following: :: @@ -406,13 +407,13 @@ relevant linker cache configuration file for your OS): Cross-Building -------------- -It is possible to cross-build Kea, i.e. to create binaries in another -system (the ``build`` system) than the system where Kea will run +It is possible to cross-build Kea, i.e. to create binaries in a separate +system (the ``build`` system) from the one where Kea runs (the ``host`` system). It is outside of the scope of common administrator operations and requires -some developer skills so the Developer Guide explains how to do that -using a x86_64 Linux system to build Kea for a Raspberry Pi box running +some developer skills, so the Developer Guide explains how to do that +using an x86_64 Linux system to build Kea for a Raspberry Pi box running Raspbian: `Kea Cross-Compiling Example <https://jenkins.isc.org/job/Kea_doc/doxygen/de/d9a/crossCompile.html>`__. @@ -442,7 +443,7 @@ optional backends and the creation of the lease database. Building with MySQL Support --------------------------- -Install MySQL according to the instructions for your system. The client +Install MySQL according to the instructions for the system. The client development libraries must be installed. Build and install Kea as described in :ref:`installation`, @@ -468,7 +469,7 @@ database configuration. Building with PostgreSQL support -------------------------------- -Install PostgreSQL according to the instructions for your system. The +Install PostgreSQL according to the instructions for the system. The client development libraries must be installed. Client development libraries are often packaged as "libpq". @@ -494,11 +495,11 @@ database configuration. Building with CQL (Cassandra) Support ------------------------------------- -Install Cassandra according to the instructions for your system. The +Install Cassandra according to the instructions for the system. The Cassandra project website contains useful pointers: https://cassandra.apache.org. -If you have a cpp-driver package available as binary or as source, +If a cpp-driver package is available as binary or as source, simply install or build and install the package. Then build and install Kea as described in :ref:`installation`. To enable the Cassandra (CQL) database code, at the "configure" step (see :ref:`configure`), enter: @@ -507,10 +508,10 @@ Cassandra (CQL) database code, at the "configure" step (see :ref:`configure`), e $ ./configure [other-options] --with-cql=path-to-pkg-config -Note if ``pkg-config`` is at its standard location (and thus in the -shell path) you do not need to supply its path. If it does not work +Note that if ``pkg-config`` is at its standard location (and thus in the +shell path), the path does not need to be specified. If it does not work (e.g. no pkg-config, package not available in pkg-config with the -cassandra name), you can still use the ``cql_config`` script in tools/ +cassandra name), the ``cql_config`` script in tools/ can still be used as described below. Download and compile cpp-driver from DataStax. For details regarding @@ -533,7 +534,7 @@ but, until that is complete, intermediate steps need to be conducted. A cql_config script is present in the tools/ directory of the Kea sources. Before using it, please create a cql_config_defines.sh file in the same directory (there is an example available in cql_config_define.sh.sample; -you may copy it over to cql_config_defines.sh and edit the path +copy it over to cql_config_defines.sh and edit the path specified in it) and change the environment variable CPP_DRIVER_PATH to point to the directory where the cpp-driver sources are located. Make sure that appropriate access rights are set on this file. It should be @@ -565,7 +566,7 @@ First, a regular user account must be created: useradd admin -Then, change the binaries ownership and group to new user. Note your path may be different. Please +Then, change the binaries ownership and group to new user. Note that the specific path may be different. Please refer to the ``--prefix`` parameter passed to the configure script.: .. code-block:: console @@ -577,7 +578,7 @@ refer to the ``--prefix`` parameter passed to the configure script.: chown -R admin /var/log/kea-dhcp6.log chgrp -R admin /var/log/kea-dhcp6.log -Assuming you are using systemd, you also should modify its service file +If using systemd, modify its service file (e.g. /etc/systemd/system/kea-dhcp6.service): .. code-block:: console @@ -595,19 +596,18 @@ more information. setcap 'cap_net_bind_service=+ep' /opt/kea/sbin/kea-dhcp6 After this step is complete, the admin user should be able to run Kea. Note that DHCPv4 server by -default opens raw sockets. If your network is only using relayed traffic, you can instruct Kea to +default opens raw sockets. If the network is only using relayed traffic, Kea can be instructed to use regular UDP sockets (refer to ``dhcp-socket-type`` parameter in the :ref:`dhcp4-interface-configuration` section) and the ``cap_net_raw`` capability can be skipped. .. note:: - An alternative approach to avoiding running Kea with root privileges assumes instructing Kea to - use non-privileged (greater than 1024) posts and redirecting traffic. This, however, will work - only for relayed traffic. This approach in general is considered experimental and not tested - enough for deployment in production environment. Use with caution! + An alternative approach to running Kea with root privileges is to configure Kea to use + non-privileged ports (i.e. those greater than 1024) and redirecting traffic. Note that this + only works for relayed traffic. Furthermore, we consider it experimental and untested in + production environments. Use it only after careful consideration. - -To use this approach, configure the server to listen on other non privileged port (eg: 1547 +To use this approach, configure the server to listen on other non-privileged ports (e.g. 1547 and 1548) by running the process with ``-p`` option in ``/etc/systemd/system/kea-dhcp4.service``: .. code-block:: console @@ -620,8 +620,8 @@ and ``/etc/systemd/system/kea-dhcp4.service``: ExecStart=/opt/kea/sbin/kea-dhcp6 -d -c /etc/kea/kea-dhcp6.conf -p 1547 -and then configure port redirection with iptables and ip6tables for new ports (eg: 1547 -and 1548). Make sure you replace ens4 with your specific interface name. +and then configure port redirection with iptables and ip6tables for new ports (e.g. 1547 +and 1548). Be sure to replace ens4 with the specific interface name. .. code-block:: console diff --git a/doc/sphinx/arm/lease-expiration.rst b/doc/sphinx/arm/lease-expiration.rst index 0ae7bdafff..e823953f55 100644 --- a/doc/sphinx/arm/lease-expiration.rst +++ b/doc/sphinx/arm/lease-expiration.rst @@ -8,7 +8,7 @@ The primary role of the DHCP server is to assign addresses and/or delegate prefixes to DHCP clients. These addresses and prefixes are often referred to as "leases." Leases are typically assigned to clients for a finite amount of time, known as the "valid lifetime." DHCP clients -who wish to continue using their assigned leases will periodically renew +who wish to continue using their assigned leases periodically renew them by sending the appropriate message to the DHCP server. The DHCP server records the time when these leases are renewed and calculates new expiration times for them. @@ -75,11 +75,11 @@ The following list presents all configuration parameters pertaining to processing expired leases with their default values: - ``reclaim-timer-wait-time`` - this parameter governs intervals - between the completion of the previous reclaimation cycle and the start of the + between the completion of the previous reclamation cycle and the start of the next one. Specified in seconds. The default value is 10 [seconds]. - ``flush-reclaimed-timer-wait-time`` - this parameter controls how - often the server initiates the lease reclaimation procedure. Expressed in + often the server initiates the lease reclamation procedure. Expressed in seconds. The default value is 25 [seconds]. - ``hold-reclaimed-time`` - this parameter governs how long the lease diff --git a/doc/sphinx/arm/logging.rst b/doc/sphinx/arm/logging.rst index ca0ccb00cb..0d0c8dbfec 100644 --- a/doc/sphinx/arm/logging.rst +++ b/doc/sphinx/arm/logging.rst @@ -598,14 +598,14 @@ The pattern (string) Option This option can be used to specify the layout pattern of log messages for a logger. Kea logging is implemented using the Log4Cplus library and whose output formatting is based, conceptually, on the printf formatting from C -and is discussed in detail in the the next section +and is discussed in detail in the next section :ref:`logging-message-format`. Each output type (stdout, file, or syslog) has a default ``pattern`` which describes the content of its log messages. This parameter can be used to -specifiy your own pattern. The pattern for each logger is governed -individually so each configured logger can have it's own pattern. Omitting -the ``pattern`` parameter or setting it to an empty string, "", will cause +specify a desired pattern. The pattern for each logger is governed +individually so each configured logger can have its own pattern. Omitting +the ``pattern`` parameter or setting it to an empty string, "", causes Kea to use the default pattern for that logger's output type. In addition to the log text itself, the default patterns used for ``stdout`` @@ -644,7 +644,7 @@ below: "%D{%Y-%m-%d %H:%M:%S.%q} %-5p [%c/%i.%t] %m\n"; -and a typical log produced by this pattern would look somethng like this: +and a typical log produced by this pattern looks something like this: :: diff --git a/doc/sphinx/arm/netconf.rst b/doc/sphinx/arm/netconf.rst index ae350df855..eda508446c 100644 --- a/doc/sphinx/arm/netconf.rst +++ b/doc/sphinx/arm/netconf.rst @@ -50,7 +50,7 @@ For detailed installation instructions, see the `CentOS installation notes page CentOS 7.5's gcc compiler (version 4.8.5) is very old. Some Sysrepo dependencies require at least version 4.9, which unfortunately means that a new compiler has to be installed. Also, many of the Sysrepo -dependencies are not avalable in CentOS as packages, so for the time +dependencies are not available in CentOS as packages, so for the time being they must be installed from sources. Quick Sysrepo Overview diff --git a/doc/sphinx/arm/quickstart.rst b/doc/sphinx/arm/quickstart.rst index b646a9e897..0edc7f816f 100644 --- a/doc/sphinx/arm/quickstart.rst +++ b/doc/sphinx/arm/quickstart.rst @@ -24,7 +24,7 @@ Quick Start Guide for using tarball .. parsed-literal:: - $ tar xvzf kea-|release|.tar.gz + $ tar -xvzf kea-|release|.tar.gz 4. Go into the source directory and run the configure script: diff --git a/doc/sphinx/arm/shell.rst b/doc/sphinx/arm/shell.rst index 5871079766..5cb99ba2be 100644 --- a/doc/sphinx/arm/shell.rst +++ b/doc/sphinx/arm/shell.rst @@ -113,7 +113,7 @@ servers, the default empty path in the URL is not enough, so the $ kea-shell --host 192.0.2.1 --port 8001 --path kea ... -The Kea shell requires Python to to be installed on the system. It has been +The Kea shell requires Python to be installed on the system. It has been tested with Python 2.7 and various versions of Python 3, up to 3.5. Since not every Kea deployment uses this feature and there are deployments that do not have Python, the Kea shell is not enabled by diff --git a/doc/sphinx/arm/stork.rst b/doc/sphinx/arm/stork.rst index 58a642ede9..77b8950eee 100644 --- a/doc/sphinx/arm/stork.rst +++ b/doc/sphinx/arm/stork.rst @@ -1,49 +1,50 @@ .. _stork: ************************* -Monitoring Kea with Stork +Monitoring Kea With Stork ************************* -It is usually desired to monitor running Kea services. Kea exposes many sources of informations: -configuration files, API, statistics, logs, open database content and more. It may be sometimes -overwhelming to keep up. ISC started the Stork project to address this problem for both Kea -and BIND 9. Stork can address a variety of scenarios: - -- you can use Stork as a dashboard. It provides you with an insight into what exactly is going - on with your servers. In particular, it can provide up to date details regarding pool - utilization in your subnets and shared networks, can monitor state of your HA pair (and - provide extra insight in case of failover and recovery events), lets you list, filter and - search for specific host reservations and more. For this capability, you need to deploy - a single Stork server and one Stork agent on each machine you want to monitor. - -- you can use Stork agent to integrate Kea with Prometheus and Grafana. Once you deploy a Stork - agent, it starts acting as Prometheus exporter. If you deploy Prometheus in your network, you - will be able to visualize statistics as time-series using Grafana. - -- you can do both of the above. If you have Grafana deployed in your network, you can let Stork - know its location. In this configuration, Stork will let you inspect the current status and - will provide a customized link to Grafana to see how a given property behaved over time. - -Stork is available in source code, but also as native Deb and RPM packages, which makes it easy -to install on most popular systems. For more details, please see -`Stork ARM <https://stork.readthedocs.io>`_ or `Stork project page <https://gitlab.isc.org/isc-projects/stork>`_. -The former has a nice collection of screenshots that is frequently updated. It will let you quickly -formulate a first impression of what is currently available. Stork is being rapidly developed with -monthly release. Please check back frequently. +Most administrators want to be able to monitor any Kea services that are running. Kea offers so many +pieces of information - configuration files, API, statistics, logs, open database content, and more - +that it may sometimes +be overwhelming to keep up. ISC's Stork project is intended to address this problem for both Kea +and BIND 9. Stork is useful in a variety of scenarios: + +- Stork can be used as a dashboard. It provides insight into what exactly is happening + on the servers. In particular, it allows users to: see up-to-date details regarding pool + utilization in subnets and shared networks; monitor the state of the HA pair (and + provide extra insight in case of failover and recovery events); list, filter, and + search for specific host reservations; and more. Only + a single Stork server needs to be deployed, and one Stork agent on each machine to be monitored. + +- The Stork agent can integrate Kea with Prometheus and Grafana. Once the Stork + agent is active on the server, it serves as a Prometheus exporter. Users who have deployed + Prometheus in their networks can visualize statistics as time series using Grafana. + +- Stork can act as both a dashboard and an integrator for Prometheus/Grafana. Once Stork + is linked to where Grafana is deployed on the network, users can inspect the current status and + visit a customized link to Grafana to see how a given property behaves over time. + +Stork is available as source code, but also as native deb and RPM packages, which makes it easy +to install on most popular systems. For more details, please see the +`Stork ARM <https://stork.readthedocs.io>`_ or the `Stork project page <https://gitlab.isc.org/isc-projects/stork>`_. +The former has a nice collection of screenshots that is frequently updated, to give users +an impression of what is currently available. Stork is in the midst of full development with +monthly releases, so please check back frequently. .. _grafana: .. _prometheus: -Kea statistics in Grafana +Kea Statistics in Grafana ========================= -The ISC Stork project provides an agent, that can be deployed along side Kea and BIND 9. It will -expose Kea statistics in a format that's acceptable by Prometheus. -One of the major benefits of Prometheus is that it turns repeated one time observation into time series, -which lets you monitor how certain behaviors change over time. It is easy to use other tools -to visualize data available in Prometheus. The most common approach is to use +The ISC Stork project provides an agent that can be deployed alongside Kea and BIND 9. It +exposes Kea statistics in a format that is accepted by Prometheus. +One of the major benefits of Prometheus is that it turns repeated one-time observations into time series, +which lets users monitor how certain behaviors change over time. It is easy to use other tools +to visualize data available in Prometheus; the most common approach is to use Grafana to provide visual dashboards. The Stork project provides dashboard definitions for Kea and BIND 9 that can be imported into Grafana very easily. -You can learn more about Prometheus and Grafana on their websites: `Prometheus homepage <https://prometheus.io/>`_ -and `Grafana homepage <https://grafana.com/>`_. +Learn more about Prometheus and Grafana on their websites: `Prometheus <https://prometheus.io/>`_ +and `Grafana <https://grafana.com/>`_. |