Resolve "Editorial review of the ARM prior to 2.6 release"

Author: suzgold

doc/sphinx/arm/admin.rst

@@ -48,11 +48,11 @@ upgrade, and dump lease data to a text file.
 ``backend``. Additional, non-mandatory options may be specified. The
 currently supported commands are:
 
--  ``db-init`` — initializes a new database schema. This is useful
-   during a new Kea installation. The database is initialized to the
-   latest version supported by the version of the software being installed.
-   Called automatically on startup or reconfiguration of Kea DHCP servers if
-   required.
+-  ``db-init`` — initializes a new database schema, which is useful
+   during a new Kea installation. The new database is updated to
+   match the Kea version being installed. :iscman:`kea-admin` is
+   automatically invoked with this command if a missing schema is
+   detected during startup or reconfiguration of Kea DHCP servers.
 
 -  ``db-version`` — reports the database backend version number. This
    is not necessarily equal to the Kea version number, as each backend

doc/sphinx/arm/classify.rst

@@ -503,12 +503,12 @@ Notes:
    +-----------------------+-------------------------+-----------------------+
    | Lcase                 | lcase('LoWeR')          | Converts the value of |
    |                       |                         | a string expression   |
-   |                       |                         | to lower case e.g.    |
+   |                       |                         | to lower case, e.g.   |
    |                       |                         | 'lower'               |
    +-----------------------+-------------------------+-----------------------+
    | Ucase                 | ucase('uPpEr')          | Converts the value of |
    |                       |                         | a string expression   |
-   |                       |                         | to upper case e.g.    |
+   |                       |                         | to upper case, e.g.   |
    |                       |                         | 'UPPER'               |
    +-----------------------+-------------------------+-----------------------+
    | Split                 | split('foo.bar', '.', 2)| Return the second     |
@@ -759,11 +759,11 @@ domain name servers.
        ...
    }
 
-The next example shows a client class being defined for use by the DHCPv6
-server. In it the class named "Client_enterprise" is defined. It is
+The next example shows a client class named "Client_enterprise" being defined
+for use by the DHCPv6 server. It is
 comprised of all clients whose client identifiers start with the given
-hex string (which would indicate a DUID based on an enterprise ID of
-``0x0002AABBCCDD``). Members of this class will be given 2001:db8:0::1 and
+hex string, which would indicate a DUID based on an enterprise ID of
+``0x0002AABBCCDD``. Members of this class will be given 2001:db8:0::1 and
 2001:db8:2::1 as their domain name servers.
 
 ::
@@ -1138,17 +1138,17 @@ Client classes in Kea follow the order in which they are specified in the
 configuration (vs. alphabetical order). Required classes follow the order in
 which they are required.
 
-When determining which client-class information (comprising of
-options, lease lifetimes or DHCPv4 field values) that is part of class
-definitions, to include in the response, the server examines the union of
+When determining which client-class information (comprised of
+options, lease lifetimes, or DHCPv4 field values) is part of the class
+definitions to be included in the response, the server examines the union of
 options from all of the assigned classes. If two or more classes include the
 same class information, the value from the first assigned class is used.
-``ALL`` is always the first class, hence the class with the highest
+``ALL`` is always the first class, i.e. the class with the highest
 priority, and matching required classes are last, so they have the
 lowest priority.
 
-Optons defined in classes override any global options, and in turn will be
-overridden by options defined for an individual subnet, shared network, pool or
+Options defined in classes override any global options, and in turn are
+overridden by options defined for an individual subnet, shared network, pool, or
 reservation.
 
 On the other hand, lease lifetimes and DHCPv4 field values defined at class

doc/sphinx/arm/config-backend.rst

@@ -12,21 +12,21 @@ Kea Configuration Backend (CB or config backend) gives Kea servers the ability
 to manage and fetch their configuration from one or more databases. In
 this documentation, the term "Configuration Backend" may also refer to
 the particular Kea module providing support to manage and fetch the
-configuration information from the particular database type.  For
+configuration information from the particular database type. For
 example, the MySQL Configuration Backend is the logic implemented within
 :ischooklib:`libdhcp_mysql_cb.so`, which provides a complete set of functions to
 manage and fetch the configuration information from the MySQL database.
 The PostgreSQL Configuration Backend is the logic implemented within
 :ischooklib:`libdhcp_pgsql_cb.so`, which provides a complete set of functions to
 manage and fetch the configuration information from the PostgreSQL database.
-From herein, the term "database" is used to refer to either a MySQL or
+From here on, the term "database" is used to refer to either a MySQL or
 PostgreSQL database.
 
 In small deployments, e.g. those comprising a single DHCP server
 instance with limited and infrequently changing number of subnets, it
 may be impractical to use the CB as a configuration repository because
 it requires additional third-party software to be installed and
-configured - in particular the database server, client and libraries.
+configured - in particular the database server, client, and libraries.
 Once the number of DHCP servers and/or the number of managed subnets in the
 network grows, the usefulness of the CB becomes obvious.
 
@@ -56,7 +56,7 @@ entire configuration to the new server when a common database is used.
 Using the database as a configuration repository for Kea servers also
 brings other benefits, such as:
 
--  the ability to use database specific tools to access the configuration
+-  the ability to use database-specific tools to access the configuration
    information;
 
 -  the ability to create customized statistics based on the information
@@ -163,13 +163,13 @@ in two independent configuration sources.
 CB Components
 -------------
 
-To use a MySQL configuration backend you must compile
-:ischooklib:`libdhcp_mysql_cb.so` and configure the DHCP servers to load it.
+To use a MySQL configuration backend, :ischooklib:`libdhcp_mysql_cb.so`
+must be compiled and the DHCP servers must be configured to load it.
 It is compiled when the ``--with-mysql`` configuration switch is used during the Kea build.
 The MySQL C client libraries must be installed, as explained in :ref:`dhcp-install-configure`.
 
-To use a PostgreSQL configuration backend you must compile :ischooklib:`libdhcp_pgsql_cb.so`
-and configure the DHCP servers to load it.  It is compiled when
+To use a PostgreSQL configuration backend, :ischooklib:`libdhcp_pgsql_cb.so` must
+be compiled and the DHCP servers must be configured to load it. It is compiled when
 the ``--with-pgsql`` configuration switch is used during the Kea build. The PostgreSQL
 C client libraries must be installed, as explained in :ref:`dhcp-install-configure`.
 
@@ -183,8 +183,8 @@ C client libraries must be installed, as explained in :ref:`dhcp-install-configu
 servers' configuration information within the database. This library can
 be attached to both DHCPv4 and DHCPv6 server instances. While it is
 possible to manage the configuration information without :ischooklib:`libdhcp_cb_cmds.so`
-with commonly available tools, such as MySQL Workbench or
-the command-line MySQL client, or by directly working with the database;
+using commonly available tools, such as MySQL Workbench or
+the command-line MySQL client, or by directly working with the database,
 these avenues are neither recommended nor supported.
 
 The DHCPv4 and DHCPv6 server-specific configurations of the CB, as well as
@@ -220,7 +220,7 @@ servers in the database.
 Commands which contain the logical server `all` are applied to all servers
 connecting to the database. The `all` server cannot be
 deleted or modified, and it is not returned among other servers
-as a result of the :isccmd:`remote-server4-get-all`, :isccmd:`remote-server6-get-all` commands.
+as a result of the :isccmd:`remote-server4-get-all` and :isccmd:`remote-server6-get-all` commands.
 
 In most cases, there are no server tags defined in the configuration
 database; all connecting servers get the same configuration
@@ -242,7 +242,7 @@ servers.
 
 To differentiate between different Kea server configurations, a
 list of the server tags used by the servers must be stored in the
-database. For the DHCPv4 and DHCPv6 servers, it can be done using the
+database. For the DHCPv4 and DHCPv6 servers, this can be done using the
 :isccmd:`remote-server4-set` and :isccmd:`remote-server6-set` commands. The
 server tags can then be used to associate the configuration information with
 the servers. However, it is important to note that some DHCP

doc/sphinx/arm/config.rst

@@ -174,17 +174,17 @@ syntax and its top-level element is a map (i.e. the data must be enclosed in
 curly brackets). However, some hook libraries may expect specific formatting;
 please consult the specific hook library documentation for details.
 
-In a sense the user-context mechanism has superseded the JSON comment
-capabilities; ISC encourages administrators to use user-context instead of
-the older mechanisms. To promote this way of storing comments, Kea compared
-converts JSON comments to user-context on the fly.
+The user-context mechanism has superseded the JSON comment
+capabilities; ISC encourages administrators to use user context instead of
+the older mechanisms. To promote this way of storing comments, Kea
+converts JSON comments to user context on the fly.
 
 However, if the configuration uses the old JSON
-comment, the :isccmd:`config-get` command returns a slightly modified
-configuration. It is not uncommon for a call for :isccmd:`config-set` followed by a
+comment method, the :isccmd:`config-get` command returns a slightly modified
+configuration. It is not uncommon for a call for :isccmd:`config-set` followed by
 :isccmd:`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.
+use user context.
 
 Kea supports user contexts at the following levels: global scope,
 interfaces configuration, shared networks,

doc/sphinx/arm/ctrl-channel.rst

@@ -352,9 +352,9 @@ returned is roughly equal to the configuration that was loaded using the
 :isccmd:`config-set` command. However, there may be certain differences, as
 comments are not retained. If the original configuration used file
 inclusion, the returned configuration includes all parameters from
-all included files. Starting with 2.4.0, the successful response also
-contains a SHA-256 digest that can be used to easily determine if a
-configuration has changed or not.
+all included files. In Kea 2.4.0 and later, the successful response also
+contains a SHA-256 digest that can be used to easily determine whether a
+configuration has changed.
 
 .. warning::
 
@@ -400,9 +400,9 @@ And the server's response:
         }
     }
 
-Starting with 2.4.0, also ``config-set`` and ``config-get`` return the SHA-256 hash
-of the new or current configuration. This may be used to later determine if a configuration
-has changed or not.
+In Kea 2.4.0 and later, ``config-set`` and ``config-get`` also return the SHA-256 hash
+of the new or current configuration. This may be used to determine whether a configuration
+has changed.
 
 .. isccmd:: config-reload
 .. _command-config-reload:
@@ -414,9 +414,9 @@ The :isccmd:`config-reload` command instructs Kea to load again the
 configuration file that was used previously. This operation is useful if
 the configuration file has been changed by some external source; for
 example, a system administrator can tweak the configuration file and use this
-command to force Kea pick up the changes.
+command to force Kea to pick up the changes.
 
-Caution should be taken when mixing this with the :isccmd:`config-set` command. Kea
+Care should be taken when using this in conjunction with the :isccmd:`config-set` command. Kea
 remembers the location of the configuration file it was started with,
 and this configuration can be significantly changed using the :isccmd:`config-set`
 command. When :isccmd:`config-reload` is issued after :isccmd:`config-set`, Kea attempts
@@ -550,7 +550,7 @@ loaded hook libraries. This is primarily intended to allow one or more
 hook libraries to be replaced with newer versions, without requiring Kea
 servers to be reconfigured or restarted. The hook libraries
 are passed the same parameter values (if any) that were passed when they
-originally loaded.
+were originally loaded.
 
 ::
 
@@ -643,9 +643,9 @@ string, ``text``, describing the outcome:
 
        {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }
 
-Starting with 2.4.0, the successful response from a DHCPv4, DHCPv6, or DHCP-DDNS daemons
-also contain a SHA-256 digest of the newly set configuration. The digest can be used to easily
-determine if a configuration has changed or not.
+In Kea 2.4.0 and later, the successful response from a DHCPv4, DHCPv6, or DHCP-DDNS daemon
+also contains a SHA-256 digest of the newly set configuration. The digest can be used to easily
+determine whether a configuration has changed.
 
 .. isccmd:: shutdown
 .. _command-shutdown:
@@ -654,7 +654,7 @@ The ``shutdown`` Command
 ------------------------
 
 The :isccmd:`shutdown` command instructs the server to initiate its shutdown
-procedure. It is the equivalent of sending a ``SIGTERM`` signal to the
+procedure; it is the equivalent of sending a ``SIGTERM`` signal to the
 process. This command does not take any arguments. An example command
 may look like this:
 
@@ -714,24 +714,24 @@ if the :isccmd:`dhcp-enable` command is not sent before this time elapses.
 Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
 command source. A server administrator should typically omit this parameter
 because the default value "user" indicates that the administrator sent the
-command. In Kea 2.5.5 thru 2.5.7 this parameter was also used in communication
+command. In Kea 2.5.5 through 2.5.7, this parameter was also used in communication
 between the HA partners to specify the identifier of an HA service sending the command
-in a numeric format. However, due to the compatibility issues with the older
-Kea versions that did not properly parse the numeric values, it was necessary
+in a numeric format. However, due to compatibility issues with older
+Kea versions that did not properly parse numeric values, it was necessary
 to introduce the new parameter, ``origin-id``, in Kea 2.5.8.
 
 It holds a numeric value representing the origin of the command. The same value
 can still be passed using the ``origin`` parameter, but it can cause the
-aforementioned compatibility issues between the HA partners running different
-Kea versions. Therefore, new Kea versions favor using ``origin-id`` in communication
-between the HA partners. The ``origin`` parameter can still be used, but the
-``origin-id`` takes precedence. Overall, it is recommended that both parameters be
-omitted from the user commands.
+aforementioned compatibility issues between HA partners running different
+Kea versions; if both are used, ``origin-id`` takes precedence. New Kea versions
+favor using ``origin-id`` in communication between the HA partners, but
+overall, it is recommended that both parameters be
+omitted and the default value used.
 
 The following codes represent the supported origins in numeric format:
 
- -  ``1`` - a user command, same as specifying ``"origin": "user"``,
- -  ``2000``, ``2001``, ``2002`` etc. - origins specified by HA partners where
+ -  ``1`` - a user command; the same as specifying ``"origin": "user"``.
+ -  ``2000``, ``2001``, ``2002``, etc. - origins specified by HA partners where
     the increments above ``2000`` are distinct HA service identifiers used when
     the partners have many relationships.
 
@@ -748,7 +748,7 @@ In the following example:
        }
    }
 
-the effective origin will be ``2002`` which indicates it is an HA partner
+the effective origin is ``2002``, which indicates it is an HA partner
 sending the command for the service with ID of ``2``. The ``origin``
 parameter will be ignored in this case.
 
@@ -763,24 +763,23 @@ The :isccmd:`dhcp-enable` command globally enables the DHCP service.
 Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
 command source. A server administrator should typically omit this parameter
 because the default value "user" indicates that the administrator sent the
-command. In Kea 2.5.5 thru 2.5.7 this parameter was also used in communication
+command. In Kea 2.5.5 through 2.5.7, this parameter was also used in communication
 between the HA partners to specify the identifier of an HA service sending the command
-in a numeric format. However, due to the compatibility issues with the older
-Kea versions that did not properly parse the numeric values, it was necessary
+in a numeric format. However, due to compatibility issues with older
+Kea versions that did not properly parse numeric values, it was necessary
 to introduce the new parameter, ``origin-id``, in Kea 2.5.8.
 
 It holds a numeric value representing the origin of the command. The same value
 can still be passed using the ``origin`` parameter, but it can cause the
-aforementioned compatibility issues between the HA partners running different
-Kea versions. Therefore, new Kea versions favor using ``origin-id`` in communication
-between the HA partners. The ``origin`` parameter can still be used, but the
-``origin-id`` takes precedence. Overall, it is recommended that both parameters be
-omitted from the user commands.
+aforementioned compatibility issues between HA partners running different
+Kea versions.; if both are used, ``origin-id`` takes precedence. New Kea versions
+favor using ``origin-id`` in communication between the HA partners, but
+overall, it is recommended that both
 
 The following codes represent the supported origins in numeric format:
 
- -  ``1`` - a user command, same as specifying ``"origin": "user"``,
- -  ``2000``, ``2001``, ``2002`` etc. - origins specified by HA partners where
+ -  ``1`` - a user command; the same as specifying ``"origin": "user"``.
+ -  ``2000``, ``2001``, ``2002``, etc. - origins specified by HA partners where
     the increments above ``2000`` are distinct HA service identifiers used when
     the partners have many relationships.
 
@@ -796,7 +795,7 @@ In the following example:
        }
    }
 
-the effective origin will be ``2002`` which indicates it is an HA partner
+the effective origin is ``2002``, which indicates it is an HA partner
 sending the command for the service with ID of ``2``. The ``origin``
 parameter will be ignored in this case.
 
@@ -880,7 +879,7 @@ The ``version-get`` Command
 ---------------------------
 
 The :isccmd:`version-get` command returns extended information about the Kea
-version. It is the same information available via the ``-V``
+version; it is the same information available via the ``-V``
 command-line argument. This command does not take any parameters.
 
 ::