From 51d5195263f8faf48d99f76ed9c6a35148d01bc3 Mon Sep 17 00:00:00 2001 From: Andrei Pavel Date: Wed, 15 Dec 2021 18:16:09 +0200 Subject: [PATCH] [#2142] Remove references to outdated Kea versions --- doc/sphinx/arm/dhcp4-srv.rst | 8 ++++---- doc/sphinx/arm/dhcp6-srv.rst | 30 +++++++++++++++--------------- doc/sphinx/arm/hooks-ha.rst | 18 ++++++++++-------- doc/sphinx/arm/hooks-radius.rst | 2 +- doc/sphinx/arm/hooks.rst | 12 ++++++------ doc/sphinx/arm/quickstart.rst | 2 +- 6 files changed, 37 insertions(+), 35 deletions(-) diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index 2798c0a371..8b4814df05 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -2064,7 +2064,7 @@ Such an option can be defined by putting the following entry in the configuratio ... } -The ``"false"`` value of the ``array`` parameter determines that the +The ``false`` value of the ``array`` parameter determines that the option does NOT comprise an array of ``uint32`` values but is, instead, a single value. Two other parameters have been left blank: ``record-types`` and ``encapsulate``. The former specifies the @@ -2078,7 +2078,7 @@ configuration statement only defines the format of an option and does not set its value(s). The ``name``, ``code``, and ``type`` parameters are required; all others -are optional. The ``array`` default value is ``"false"``. The +are optional. The ``array`` default value is ``false``. The ``record-types`` and ``encapsulate`` default values are blank (``""``). The default ``space`` is ``dhcp4``. @@ -2528,7 +2528,7 @@ By default, Kea sends back only those options that are requested by a client, unless there are protocol rules that tell the DHCP server to always send an option. This approach works nicely in most cases and avoids problems with clients -refusing responses with options they don't understand. However, +refusing responses with options they do not understand. However, the situation with vendor options is more complex, as they are not requested the same way as other options, are not well-documented in official RFCs, or vary by vendor. @@ -6578,7 +6578,7 @@ The DHCPv4 server supports the following statistics: This section describes DHCPv4-specific statistics. For a general overview and usage of statistics, see :ref:`stats`. -The DHCPv4 server provides two global parameters to control default sample +The DHCPv4 server provides two global parameters to control the default sample limits of statistics: - ``statistic-default-sample-count`` - determines the default maximum diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index f4673a8c7f..705d593cf7 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -1846,7 +1846,7 @@ in the configuration file: ... } -The ``"false"`` value of the ``array`` parameter determines that the option +The ``false`` value of the ``array`` parameter determines that the option does NOT comprise an array of ``uint32`` values but is, instead, a single value. Two other parameters have been left blank: ``record-types`` and ``encapsulate``. The former specifies the comma-separated list of option @@ -1860,7 +1860,7 @@ configuration statement only defines the format of an option and does not set its value(s). The ``name``, ``code``, and ``type`` parameters are required; all -others are optional. The ``array`` default value is ``"false"``. The +others are optional. The ``array`` default value is ``false``. The ``record-types`` and ``encapsulate`` default values are blank (``""``). The default ``space`` is ``dhcp6``. @@ -2648,7 +2648,7 @@ shared network, subnet, or pool. There are two parameters which are used to limit the scope of the class by instructing the server to evaluate test expressions when required. -The first one is the per-class ``only-if-required`` flag, which is "false" +The first one is the per-class ``only-if-required`` flag, which is ``false`` by default. When it is set to ``true``, the test expression of the class is not evaluated at the reception of the incoming packet but later, and only if the class evaluation is required. @@ -2842,13 +2842,13 @@ The second parameter added in Kea 1.9.1 is ``ddns-use-conflict-resolution``. The value of this parameter is passed by ``kea-dhcp6`` to D2 with each DNS update request. When ``true`` (the default value), D2 employs conflict resolution, as described in `RFC 4703 `__, when -attempting to fulfill the update request. When "false", D2 simply attempts +attempting to fulfill the update request. When ``false``, D2 simply attempts to update the DNS entries per the request, regardless of whether they conflict with existing entries owned by other DHCPv6 clients. .. note:: - Setting ``ddns-use-conflict-resolution`` to "false" disables the overwrite + Setting ``ddns-use-conflict-resolution`` to ``false`` disables the overwrite safeguards that the rules of conflict resolution (from `RFC 4703 `__) are intended to prevent. This means that existing entries for an FQDN or an @@ -2897,7 +2897,7 @@ control this communication: - ``enable-updates`` - Enables connectivity to ``kea-dhcp-ddns`` such that DDNS updates can be constructed and sent. It must be ``true`` for NCRs to be generated and sent to D2. - It defaults to "false". + It defaults to ``false``. - ``server-ip`` - This is the IP address on which D2 listens for requests. The default is the local loopback interface at address 127.0.0.1. @@ -3099,11 +3099,11 @@ parameter, which provides the following modes of behavior: .. note:: In early versions of Kea, this parameter was a boolean and - permitted only values of ``true`` and "false". + permitted only values of ``true`` and ``false``. Boolean values have been deprecated and are no longer accepted. Administrators currently using booleans must replace them with the desired mode name. A value of ``true`` maps to ``when-present``, while - "false" maps to ``never``. + ``false`` maps to ``never``. For example, to instruct ``kea-dhcp6`` to always generate the FQDN for a client, set the parameter ``ddns-replace-client-name`` to ``always`` as @@ -3408,7 +3408,7 @@ additional information must be stored with each lease. Because the amount of information stored for each lease has ramifications in terms of performance and system resource consumption, storage of this additional information is configurable through the ``store-extended-info`` parameter. -It defaults to "false" and may be set at the global, shared-network, and +It defaults to ``false`` and may be set at the global, shared-network, and subnet levels. :: @@ -3464,7 +3464,7 @@ threads. These settings can be found under the ``multi-threading`` structure and represented by: - ``enable-multi-threading`` - use multiple threads to process packets in - parallel. The default is "false". + parallel. The default is ``false``. - ``thread-pool-size`` - specify the number of threads to process packets in parallel. It may be set to 0 (auto-detect), or any positive number explicitly sets @@ -4007,7 +4007,7 @@ reserved class has been also assigned. 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. + ``only-if-required`` parameter set to ``false`` have been evaluated. This means that these classes must not depend on the statically assigned classes from the host reservations. If such a dependency is needed, the ``only-if-required`` must @@ -4653,7 +4653,7 @@ enabled with the ``ip-reservations-unique`` global parameter. ``ip-reservations-unique`` is a boolean parameter that defaults to ``true``, which forbids the specification of more than one reservation -for the same lease in a given subnet. Setting this parameter to "false" +for the same lease in a given subnet. Setting this parameter to ``false`` allows such reservations to be created both in the Kea configuration file and in the host database backend, via the ``host-cmds`` hook library. @@ -4661,7 +4661,7 @@ This setting is currently supported by the most popular host database backends, i.e. MySQL and PostgreSQL. It is not supported for Cassandra, Host Cache (see :ref:`hooks-host-cache`), or the RADIUS backend (see :ref:`hooks-radius`). An attempt to set ``ip-reservations-unique`` -to "false" when any of these three backends is in use yields a +to ``false`` when any of these three backends is in use yields a configuration error. .. note:: @@ -4722,7 +4722,7 @@ for the same IP address or delegated prefix. Currently the Kea server does not verify whether multiple reservations for the same IP address and/or delegated prefix exist in MySQL and/or PostgreSQL) host databases when ``ip-reservations-unique`` - is updated from ``true`` to "false". This may cause issues with + is updated from ``true`` to ``false``. This may cause issues with lease allocations. The administrator must ensure that there is at most one reservation for each IP address and/or delegated prefix within each subnet, prior to the configuration update. @@ -6503,7 +6503,7 @@ The DHCPv6 server supports the following statistics: This section describes DHCPv6-specific statistics. For a general overview and usage of statistics, see :ref:`stats`. -The DHCPv6 server provides two global parameters to control default sample +The DHCPv6 server provides two global parameters to control the default sample limits of statistics: - ``statistic-default-sample-count`` - determines the default maximum diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst index 6d6c8f00b8..27041ba491 100644 --- a/doc/sphinx/arm/hooks-ha.rst +++ b/doc/sphinx/arm/hooks-ha.rst @@ -108,11 +108,11 @@ There is no limit on the number of backup servers in the HA setup; however, the presence of backup servers may increase the latency of DHCP responses, because not only do active servers send lease updates to each other, but also to the backup servers. The active -servers don't expect acknowledgments from the backup servers +servers do not expect acknowledgments from the backup servers before responding to the DHCP clients, so the overhead of sending lease updates to the backup servers is minimized. -The last supported configuration, ``passive-backup``, there is only one active +In the last supported configuration, ``passive-backup``, there is only one active server and typically one or more backup servers. A passive-backup configuration with no backup servers is also accepted, but it is no different than running a single server with no HA function at all. @@ -179,7 +179,7 @@ clocks and restart the servers. .. note:: - It is possible to restart the servers one at a time, in no particular oder. + It is possible to restart the servers one at a time, in no particular order. The clocks must be in sync before restarting the servers. .. note:: @@ -1600,11 +1600,13 @@ and four threads for the client. .. note:: It is essential to configure the ports correctly. One common mistake - is to configure CA to listen on port 8000 and also configure dedicated listeners on port - 1. In such a configuration, the DHCP server will fail to bind sockets, but the communication - will still work via CA, albeit slowly. Make sure your dedicated listeners use a different port - (8001 is a suggested alternative). If you misconfigure ports or use the ports used by CA, the - performance bottlenecks caused by the single-threaded nature of CA and the sequential nature of + is to configure CA to listen on port 8000 and also configure dedicated listeners on port 8000. + In such a configuration, the communication will still work over CA, + but it will be slow and the DHCP server will fail to bind sockets. + Administrators should ensure that dedicated listeners use a different + port (8001 is a suggested alternative); if ports are misconfigured + or the ports dedicated to CA are used, the performance bottlenecks + caused by the single-threaded nature of CA and the sequential nature of the UNIX socket that connects CA to DHCP servers will nullify any performance gains offered by HA+MT. .. _ha-parked-packet-limit: diff --git a/doc/sphinx/arm/hooks-radius.rst b/doc/sphinx/arm/hooks-radius.rst index 95eeacb162..49d8e3e9bf 100644 --- a/doc/sphinx/arm/hooks-radius.rst +++ b/doc/sphinx/arm/hooks-radius.rst @@ -51,7 +51,7 @@ on CentOS 7.0. Other systems may differ slightly. .. note:: ISC provides Kea software and hooks in convenient-to-use - native Alpine, deb and RPM packages. This includes the RADIUS hook and the required patched version + native Alpine, deb, and RPM packages. This includes the RADIUS hook and the required patched version of the FreeRADIUS client library. The software compilation for RADIUS is complicated; unless there are specific reasons to compile it, administrators should seriously consider using native packages. diff --git a/doc/sphinx/arm/hooks.rst b/doc/sphinx/arm/hooks.rst index 10a9af74fb..936dba2a17 100644 --- a/doc/sphinx/arm/hooks.rst +++ b/doc/sphinx/arm/hooks.rst @@ -1846,21 +1846,21 @@ contract. Currently, the following commands are supported: -- ``reservation-add``, which adds a new host reservation +- ``reservation-add``, which adds a new host reservation. - ``reservation-get``, which returns an existing reservation if specified - criteria are matched + criteria are matched. -- ``reservation-get-all``, which returns all reservations in a specified subnet +- ``reservation-get-all``, which returns all reservations in a specified subnet. - ``reservation-get-page``, a variant of ``reservation-get-all`` that returns - reservations by pages, either all or in a specified subnet + reservations by pages, either all or in a specified subnet. - ``reservation-get-by-hostname``, which returns all reservations with a - specified hostname and optionally in a subnet + specified hostname and optionally in a subnet. - ``reservation-get-by-id``, which returns all reservations with a specified - identifier since Kea version 1.9.0 + identifier (since Kea version 1.9.0). - ``reservation-del``, which attempts to delete a reservation matching specified criteria. diff --git a/doc/sphinx/arm/quickstart.rst b/doc/sphinx/arm/quickstart.rst index 40465351bd..7433535204 100644 --- a/doc/sphinx/arm/quickstart.rst +++ b/doc/sphinx/arm/quickstart.rst @@ -51,7 +51,7 @@ Quick Start Guide Using tarball Quick Start Guide Using Native Packages ======================================= -ISC provides native Alpine, deb and RPM packages, which make Kea installation +ISC provides native Alpine, deb, and RPM packages, which make Kea installation much easier. Unless specific compilation options are desired, it is usually easier to install Kea using native packages.