Converting from docbook to sphinx: fixing links, editing grammar and style as needed

doc/guide/admin.rst

@@ -124,7 +124,7 @@ backend may be essential for the success of your deployment.
    |               |                |                |               |              |
    +---------------+----------------+----------------+---------------+--------------+
 
-memfile
+Memfile
 -------
 
 The memfile backend is able to store lease information, but cannot
@@ -538,7 +538,7 @@ Year 2038 Issue
 The lease expiration time is stored in the SQL database for each lease
 as a timestamp value. Kea developers observed that the MySQL database
 doesn't accept timestamps beyond 2147483647 seconds (the maximum signed
-32-bit number) from the beginning of the Unix epoch (00:00:00 on 1
+32-bit number) from the beginning of the UNIX epoch (00:00:00 on 1
 January 1970). Some versions of PostgreSQL do accept greater values, but
 the value is altered when it is read back. For this reason, the lease
 database backends put a restriction on the maximum timestamp to be

doc/guide/classify.rst

@@ -26,7 +26,7 @@ client class to receive common options.
 An incoming packet can be associated with a client class in several
 ways:
 
--  Implicitly, using a vendor class option or another builtin condition.
+-  Implicitly, using a vendor class option or another built-in condition.
 
 -  Using an expression which evaluates to true.
 
@@ -49,7 +49,7 @@ The classification process is conducted in several steps:
 2.  Vendor class options are processed.
 
 3.  Classes with matching expressions and not marked for later evaluation ("on
-    request" or depending on the KNOWN/UNKNOWN builtin classes)
+    request" or depending on the KNOWN/UNKNOWN built-in classes)
     are processed in the order they are defined in the
     configuration; the boolean expression is evaluated and, if it
     returns true ("match"), the incoming packet is associated with the
@@ -74,7 +74,7 @@ The classification process is conducted in several steps:
     packet is assigned to the UNKNOWN class.
 
 7.  Classes with matching expressions - directly, or indirectly using the
-    KNOWN/UNKNOWN builtin classes and not marked for later evaluation ("on
+    KNOWN/UNKNOWN built-in classes and not marked for later evaluation ("on
     request") - are processed in the order they are defined
     in the configuration; the boolean expression is evaluated and, if it
     returns true ("match"), the incoming packet is associated with the
@@ -128,10 +128,10 @@ value is obtained is unspecified.
 
 .. _classification-using-vendor:
 
-Builtin Client Classes
+Built-in Client Classes
 ======================
 
-Some classes are builtin, so they do not need to be defined. The main
+Some classes are built-in, so they do not need to be defined. The main
 example uses Vendor Class information: the server checks whether an
 incoming DHCPv4 packet includes the vendor class identifier option (60)
 or an incoming DHCPv6 packet includes the vendor class option (16). If
@@ -150,13 +150,13 @@ be found in :ref:`high-availability-library`.
 
 Other examples are the ALL class, which all incoming packets belong to,
 and the KNOWN class, assigned when host reservations exist for a
-particular client. By convention, builtin classes' names begin with all
+particular client. By convention, built-in classes' names begin with all
 capital letters.
 
-Currently recognized builtin class names are ALL, KNOWN and UNKNOWN, and the
+Currently recognized built-in class names are ALL, KNOWN and UNKNOWN, and the
 prefixes VENDOR_CLASS_, HA_, AFTER_, and EXTERNAL_. Although the AFTER\_
 prefix is a provision for an as-yet-unwritten hook, the EXTERNAL\_
-prefix can be freely used; builtin classes are implicitly defined so
+prefix can be freely used; built-in classes are implicitly defined so
 they never raise warnings if they do not appear in the configuration.
 
 .. _classification-using-expressions:
@@ -186,7 +186,7 @@ in the operator returning an empty string.
 
 Dependencies between classes are also checked. For instance, forward
 dependencies are rejected when the configuration is parsed; an
-expression can only depend on already-defined classes (including builtin
+expression can only depend on already-defined classes (including built-in
 classes) which are evaluated in a previous or the same evaluation phase.
 This does not apply to the KNOWN or UNKNOWN classes.
 
@@ -339,7 +339,7 @@ Notes:
 -  "member('foobar')" checks whether the packet belongs to the client
    class "foobar". To avoid dependency loops, the configuration file
    parser verifies whether client classes were already defined or are
-   builtin, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the
+   built-in, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the
    to-come "after" hook) and "EXTERNAL_" or equal to "ALL", "KNOWN",
    "UNKNOWN", etc.
 

doc/guide/dhcp4-srv.rst

@@ -280,12 +280,12 @@ information in a CSV file rather than a database. As well as requiring
 less administration, an advantage of using a file for storage is that it
 eliminates a dependency on third-party database software.
 
-The configuration of the file backend (Memfile) is controlled through
+The configuration of the file backend (memfile) is controlled through
 the Dhcp4/lease-database parameters. The ``type`` parameter is mandatory
 and it specifies which storage for leases the server should use. The
 value of ``"memfile"`` indicates that the file should be used as the
 storage. The following list gives additional optional parameters that
-can be used to configure the Memfile backend.
+can be used to configure the memfile backend.
 
 -  ``persist``: controls whether the new leases and updates to existing
    leases are written to the file. It is strongly recommended that the
@@ -310,7 +310,7 @@ can be used to configure the Memfile backend.
    value of the ``lfc-interval`` is ``3600``. A value of 0 disables the
    LFC.
 
-An example configuration of the Memfile backend is presented below:
+An example configuration of the memfile backend is presented below:
 
 ::
 
@@ -3944,7 +3944,7 @@ which belong to them.
    }
 
 Static class assignments, as shown above, can be used in conjunction
-with classification, using expressions. The "KNOWN" or "UNKNOWN" builtin
+with classification, using expressions. The "KNOWN" or "UNKNOWN" built-in
 class is added to the packet and any class depending on it (directly or
 indirectly) and not only-if-required is evaluated.
 

doc/guide/dhcp6-srv.rst

@@ -266,12 +266,12 @@ information in a CSV file rather than a database. As well as requiring
 less administration, an advantage of using a file for storage is that it
 eliminates a dependency on third-party database software.
 
-The configuration of the file backend (Memfile) is controlled through
+The configuration of the file backend (memfile) is controlled through
 the Dhcp6/lease-database parameters. The ``type`` parameter is mandatory
 and it specifies which storage for leases the server should use. The
 value of ``"memfile"`` indicates that the file should be used as the
 storage. The following list gives additional optional parameters that
-can be used to configure the Memfile backend.
+can be used to configure the memfile backend.
 
 -  ``persist``: controls whether the new leases and updates to existing
    leases are written to the file. It is strongly recommended that the
@@ -296,7 +296,7 @@ can be used to configure the Memfile backend.
    default value of the ``lfc-interval`` is ``3600``. A value of 0
    disables the LFC.
 
-An example configuration of the Memfile backend is presented below:
+An example configuration of the memfile backend is presented below:
 
 ::
 
@@ -3433,7 +3433,7 @@ which belong to them.
     }
 
 Static class assignments, as shown above, can be used in conjunction
-with classification, using expressions. The "KNOWN" or "UNKNOWN" builtin
+with classification, using expressions. The "KNOWN" or "UNKNOWN" built-in
 class is added to the packet and any class depending on it (directly or
 indirectly) and not only-if-required is evaluated.
 
@@ -4411,7 +4411,7 @@ configuration:
 
 This very simple configuration provides DNS server information to
 all clients in the network, regardless of their location. Note the
-specification of the Memfile lease database; this is needed as Kea
+specification of the memfile lease database; this is needed as Kea
 requires a lease database to be specified even if it is not used.
 
 .. _dhcp6-rfc7550:

doc/guide/hooks-cb-cmds.rst

@@ -3,22 +3,22 @@
 cb_cmds: Configuration Backend Commands
 =======================================
 
-This section describes the ``cb_cmds`` hooks library which is used to
+This section describes the ``cb_cmds`` hooks library, which is used to
 manage Kea servers' configurations in the Configuration Backends. This
-library must be used in conjuction with the available CB hooks libraries
+library must be used in conjunction with the available CB hooks libraries
-implementing the common APIs to create, read, update and delete (CRUD)
+implementing the common APIs to create, read, update, and delete (CRUD)
 the configuration information in the respective databases. For example:
 the ``mysql_cb`` hooks library, released in Kea 1.6.0, implements this
 API for MySQL. In order to manage the configuration information in the
-MySQL database both ``mysql_cb`` and ``cb_cmds`` libraries must be
+MySQL database, both the ``mysql_cb`` and ``cb_cmds`` libraries must be
 loaded by the server used for the configuration management.
 
-The ``cb_cmds`` library is only available to ISC customers with a
+The ``cb_cmds`` library is only available to ISC customers with a paid
 support contract.
 
    **Note**
 
-   This library may only be loaded by the ``kea-dhcp4`` or the
+   This library may only be loaded by the ``kea-dhcp4`` or
    ``kea-dhcp6`` process.
 
 Commands Structure
@@ -26,23 +26,23 @@ Commands Structure
 
 There are 5 types of commands supported by this library:
 
--  ``del`` - delete selected object from the database, e.g.
+-  ``del`` - delete the selected object from the database, e.g.
-   ``remote-global-parameter4-del``
+   ``remote-global-parameter4-del``.
 
--  ``get`` - fetch selected object from the database, e.g.
+-  ``get`` - fetch the selected object from the database, e.g.
-   ``remote-subnet4-get``,
+   ``remote-subnet4-get``.
 
 -  ``get-all`` - fetch all objects of the particular type from the
-   database, e.g. ``remote-option-def4-get-all``,
+   database, e.g. ``remote-option-def4-get-all``.
 
 -  ``list`` - list all objects of the particular type in the database,
    e.g. ``remote-network4-list``; this class of commands returns brief
-   information about each object comparing to the output of ``get-all``,
+   information about each object comparing to the output of ``get-all``.
 
 -  ``set`` - creates or replaces an object of the given type in the
-   database, e.g. ``remote-option4-global-set`` .
+   database, e.g. ``remote-option4-global-set``.
 
-All types of commands accept optional ``remote`` map which selects the
+All types of commands accept an optional ``remote`` map which selects the
 database instance to which the command refers. For example:
 
 ::
@@ -59,21 +59,21 @@ database instance to which the command refers. For example:
    }
 
 selects the MySQL database, running on host 192.0.2.33 and port 3302, to
-fetch the list of subnets from. All parameters in the ``remote`` are
+fetch the list of subnets from. All parameters in the ``remote`` argument are
-optional. The ``port`` parameter can be only specified in conjuction
+optional. The ``port`` parameter can be only specified in conjunction
-with the ``host``. If no parameters in the ``remote`` parameter are to
+with the ``host``. If no options in the ``remote`` parameter are to
 be specified, the parameter should be omitted. In this case, the server
 will use the first backend listed in the ``config-control`` map within
 the configuration of the server receiving the command.
 
    **Note**
 
-   In the Kea 1.6.0 release, it is possible to configure the Kea server
+   As of the Kea 1.6.0 release, it is possible to configure the Kea server
    to use only one configuration backend. Strictly speaking, it is
-   possible to point Kea server to at most one MySQL database using the
+   possible to point the Kea server to at most one MySQL database using the
    ``config-control`` parameter. That's why, in this release, the
-   ``remote`` parameter may be omitted in the commands because the
+   ``remote`` parameter may be omitted in the commands, because the
-   cb_cmds hooks library will use by default the sole backend.
+   cb_cmds hooks library will use the sole backend by default.
 
 .. _cb-cmds-dhcp:
 
@@ -83,23 +83,23 @@ Control Commands for DHCP Servers
 This section describes and gives some examples of the control commands
 implemented by the ``cb_cmds`` hooks library, to manage the
 configuration information of the DHCPv4 and DHCPv6 servers. Many of the
-commands are almost identical between DHCPv4 and DHCPv6, i.e. only
+commands are almost identical between DHCPv4 and DHCPv6; they only
-differ by the command name. Other commands slightly differ by the
+differ by the command name. Other commands differ slightly by the
-structure of the inserted data, e.g. the structure of the IPv4 subnet
+structure of the inserted data; for example, the structure of the IPv4 subnet
-information is different than the structure of the IPv6 subnet.
+information is different than that of the IPv6 subnet.
-Nevertheless, they still share the structure of the command arguments
+Nevertheless, they still share the structure of their command arguments
 and thus it makes sense to describe them together.
 
-In the following sections, various commands are described and the usage
+In the following sections, various commands are described and some usage
 examples are provided. In the sections jointly describing the DHCPv4 and
-DHCPv6 variants of the particular command we sometimes use the following
+DHCPv6 variants of the particular command, we sometimes use the following
-notation - the ``remote-subnet[46]-set`` is the wildcard name for the
+notation: the ``remote-subnet[46]-set`` is the wildcard name for the
 two commands: ``remote-subnet4-set`` and ``remote-subnet6-set``.
 
 In addition, whenever the text in the subsequent sections refers to a
 DHCP command or DHCP parameter, it refers to both DHCPv4 and DHCPv6
 variants. The text specific to the particular server type refers to them
-as: DHCPv4 command, DHCPv4 parameter, DHCPv6 command, DHCPv6 parameter
+as: DHCPv4 command, DHCPv4 parameter, DHCPv6 command, DHCPv6 parameter,
 etc.
 
 .. _cb-cmds-metadata:
@@ -108,13 +108,13 @@ Metadata
 ~~~~~~~~
 
 The typical response to the ``get`` or ``list`` command includes a list
-of returned objects (e.g. subnets) and each such object contains the
+of returned objects (e.g. subnets), and each such object contains the
-``metadata`` map with some database specific information describing this
+``metadata`` map with some database-specific information describing this
 object. In other words, the metadata contains any information about the
-fetched object which may be useful for the administrator, but is not the
+fetched object which may be useful for the administrator, but which is not
 part of the object specification from the DHCP server standpoint. In the
 Kea 1.6.0 release, the metadata is limited to the ``server-tag``, which
-describescthe association of the object with the particular server or
+describes the association of the object with a particular server or
 all servers. The server tag is always set to ``all`` in the Kea 1.6.0
 beta release.
 
@@ -141,19 +141,19 @@ command, which includes the metadata:
 
 
 Client implementations must not assume that the metadata contains only
-the ``server-tag`` parameter. In the future releases this map will be
+the ``server-tag`` parameter. In future releases, this map will be
 extended with additional information, e.g. object modification time, log
-message created during the last modification etc.
+message created during the last modification, etc.
 
 .. _command-remote-global-parameter4-del:
 
-remote-global-parameter4-del, remote-global-parameter6-del commands
+The remote-global-parameter4-del, remote-global-parameter6-del Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This command is used to delete a global DHCP parameter from the
+These commands are used to delete a global DHCP parameter from the
-configuration database. When the parameter is deleted from the database
+configuration database. When the parameter is deleted from the database,
 the server will use the value specified in the configuration file for
-this parameter or a default value if the parameter is not specified in
+this parameter, or a default value if the parameter is not specified in
 the configuration file.
 
 The following command attempts to delete the DHCPv4 ``renew-timer``
@@ -174,8 +174,8 @@ parameter from the database:
 
 .. _command-remote-global-parameter4-get:
 
-remote-global-parameter4-get, remote-global-parameter6-get commands
+The remote-global-parameter4-get, remote-global-parameter6-get Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to fetch a scalar global DHCP parameter from the
 configuration database.
@@ -197,10 +197,10 @@ parameter:
 
 
 The returned value has one of the four scalar types: string, integer,
-real or boolean. Non scalar global configuration parameters, such as map
+real, or boolean. Non-scalar global configuration parameters, such as map
 or list, are not returned by this command.
 
-In case of the example above the string value is returned, e.g.:
+In the case of the example above, the string value is returned, e.g.:
 
 ::
 
@@ -278,22 +278,22 @@ Finally, the boolean value:
 
 .. _command-remote-global-parameter4-get-all:
 
-remote-global-parameter4-get-all, remote-global-parameter6-get-all commands
+The remote-global-parameter4-get-all, remote-global-parameter6-get-all Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to fetch all global DHCP parameters from the
 database. They include no arguments besides the optional ``remote`` map.
 
 .. _command-remote-global-parameter4-set:
 
-remote-global-parameter4-set
+The remote-global-parameter4-set Command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This command is used to create scalar global DHCP parameters in the
 database. If any of the parameters already exists, its value is replaced
 as a result of this command. It is possible to set multiple parameters
-within a single command, each having one of the four types: a string,
+within a single command, each having one of the four types: string,
-integer, real and boolean. For example:
+integer, real, and boolean. For example:
 
 ::
 
@@ -315,22 +315,22 @@ integer, real and boolean. For example:
 
 An error is returned if any of the parameters is not supported by the
 DHCP server or its type does not match. Care should be taken when
-multiple parameters are specified in a single command because it is
+multiple parameters are specified in a single command, because it is
 possible that only some of the parameters are stored successfully and
-some fail. If an error occurred when processing this command, it is
+some fail. If an error occurs when processing this command, it is
 recommended to use ``remote-global-parameter[46]-get-all`` to check
 which of the parameters have been stored/updated successfully and which
-failed.
+have failed.
 
 .. _command-remote-network4-del:
 
-remote-network4-del, remote-network6-del commands
+The remote-network4-del, remote-network6-del Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to delete an IPv4 or IPv6 shared network from
 the database. The optional parameter ``subnets-action`` determines
 whether the subnets belonging to the deleted shared network should also
-be deleted or preserved. The ``subnets-action`` defaults to ``keep``,
+be deleted or preserved. The ``subnets-action`` parameter defaults to ``keep``,
 which preserves the subnets. If it is set to ``delete``, the subnets are
 deleted along with the shared network.
 
@@ -354,20 +354,20 @@ The following command:
    }
 
 
-deletes the "level3" IPv6 shared network. The subnets are preserved but
+deletes the "level3" IPv6 shared network. The subnets are preserved, but
 they are disassociated from the deleted shared network and become
 global. This behavior corresponds to the behavior of the
-``network[46]-del`` commands with respect to the ``subnets-action``.
+``network[46]-del`` commands with respect to the ``subnets-action`` parameter.
 
 .. _command-remote-network4-get:
 
-remote-network4-get, remote-network6-get commands
+The remote-network4-get, remote-network6-get Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These commands are used to retrieve the information about an IPv4 or
+These commands are used to retrieve information about an IPv4 or
 IPv6 shared network. The optional parameter ``subnets-include`` denotes
 whether the subnets belonging to the shared network should also be
-returned. This parameter defaults to ``no`` in which case the subnets
+returned. This parameter defaults to ``no``, in which case the subnets
 are not returned. If this parameter is set to ``full``, the subnets are
 returned together with the shared network.
 
@@ -394,13 +394,13 @@ with the full information about the subnets belonging to it:
 
 .. _command-remote-network4-list:
 
-remote-network4-list, remote-network6-list commands
+The remote-network4-list, remote-network6-list Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to list all IPv4 or IPv6 shared networks in the
 particular database. The returned information about each shared network
-merely contains the shared network name and the metadata. In order to
+merely contains the shared network name and the metadata. To
-fetch the detailed information about the selected shared network, use
+fetch detailed information about the selected shared network, use
 the ``remote-network[46]-get`` command.
 
 The ``remote-network[46]-list`` takes no argument except the optional
@@ -408,20 +408,20 @@ The ``remote-network[46]-list`` takes no argument except the optional
 
 .. _command-remote-network4-set:
 
-remote-network4-set
+The remote-network4-set, remote-network6-set Commands
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These commands creates new or replaces an existing IPv4 or IPv6 shared
+These commands create a new or replace an existing IPv4 or IPv6 shared
 network in the database. The structure of the shared network information
 is the same as in the Kea configuration file (see
-`??? <#shared-network4>`__ and `??? <#shared-network6>`__ for details),
+:ref:`shared-network4` and :ref:`shared-network6` for details),
-except that it is not allowed to specify subnets along with the shared
+except that specifying subnets along with the shared
-network information. Including the ``subnet4`` or ``subnet6`` parameter
+network information is not allowed. Including the ``subnet4`` or ``subnet6`` parameter
 within the shared network information will result in an error.
 
-These commands are intended to be used for managing the shared network
+These commands are intended to be used for managing the shared
-specific information and DHCP options. In order to associate and
+network-specific information and DHCP options. In order to associate and
-disassociate the subnets with the shared networks the
+disassociate the subnets with the shared networks, the
 ``remote-subnet[46]-set`` commands should be used.
 
 The following command adds the IPv6 shared network "level3" to the
@@ -449,8 +449,8 @@ database:
    }
 
 
-This command includes the ``interface`` parameter which sets the shared
+This command includes the ``interface`` parameter, which sets the shared
-network level interface name. Remaining shared network level parameters,
+network-level interface name. Any remaining shared network-level parameters,
 which are not specified with the command, will be marked as
 "unspecified" in the database. The DHCP server will use the global
 values for unspecified parameters or, if the global values are not
@@ -458,18 +458,18 @@ specified, the default values will be used.
 
    **Note**
 
-   Same as for other "set" commands, this command replaces the entire
+   As with other "set" commands, this command replaces all the
-   information about the given shared network in the database if the
+   information about the given shared network in the database, if the
    shared network already exists. Therefore, when sending this command,
    make sure to always include all parameters that must be specified for
-   the updated shared network instance. Any unspecified parameter will
+   the updated shared-network instance. Any unspecified parameter will
    be marked unspecified in the database, even if its value was present
    prior to sending the command.
 
 .. _command-remote-option-def4-del:
 
-remote-option-def4-del, remote-option-def6-del commands
+The remote-option-def4-del, remote-option-def6-del Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to delete a DHCP option definition from the
 database. The option definition is identified by an option code and
@@ -495,17 +495,17 @@ option space. For example:
 
 deletes the definition of the option having the code of 1 and belonging
 to the option space "isc". The default option spaces are "dhcp4" and
-"dhcp6" for the DHCPv4 and DHCPv6 top level options respectively.
+"dhcp6" for the DHCPv4 and DHCPv6 top-level options, respectively.
 
 .. _command-remote-option-def4-get:
 
-remote-option-def4-get, remote-option-def6-get commands
+The remote-option-def4-get, remote-option-def6-get Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to fetch a specified DHCP option definition from
 the database. The option definition is identified by the option code and
 option space. The default option spaces are "dhcp4" and "dhcp6" for the
-DHCPv4 and DHCPv6 top level options respectively.
+DHCPv4 and DHCPv6 top-level options, respectively.
 
 The following command retrieves a DHCPv4 option definition having the
 code of 1 and belonging to option space "isc":
@@ -530,23 +530,23 @@ code of 1 and belonging to option space "isc":
 
 .. _command-remote-option-def4-get-all:
 
-remote-option-def4-get-all, remote-option-def6-get-all commands
+The remote-option-def4-get-all, remote-option-def6-get-all Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to fetch all DHCP option definitions from the
-database. It takes no arguments except the optional ``remote`` map.
+database. They take no arguments except the optional ``remote`` map.
 
 .. _command-remote-option-def4-set:
 
-remote-option-def4-set, remote-option-def6-set commands
+The remote-option-def4-set, remote-option-def6-set Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands create a new DHCP option definition or replace an
 existing option definition in the database. The structure of the option
 definition information is the same as in the Kea configuration file (see
-`??? <#dhcp4-custom-options>`__ and `??? <#dhcp6-custom-options>`__).
+:ref:`dhcp4-custom-options` and :ref:`dhcp6-custom-options`).
-The following command creates the DHCPv4 option definition in the top
+The following command creates the DHCPv4 option definition in the
-level "dhcp4" option space:
+top-level "dhcp4" option space:
 
 ::
 
@@ -573,8 +573,8 @@ level "dhcp4" option space:
 
 .. _command-remote-option4-global-del:
 
-remote-option4-global-del, remote-option6-global-del commands
+The remote-option4-global-del, remote-option6-global-del Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to delete a global DHCP option from the
 database. The option is identified by an option code and option space.
@@ -598,18 +598,18 @@ For example:
    }
 
 
-The "dhcp4" is the top level option space where the standard DHCPv4
+The "dhcp4" is the top-level option space where the standard DHCPv4
 options belong.
 
 .. _command-remote-option4-global-get:
 
-remote-option4-global-get, remote-option6-global-get commands
+The remote-option4-global-get, remote-option6-global-get Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to fetch a global DHCP option from the database.
-The option is identified by the code and option space. The top level
+The option is identified by the code and option space. The top-level
 option spaces where DHCP standard options belong are called "dhcp4" and
-"dhcp6" for the DHCPv4 and DHCPv6 servers respectively.
+"dhcp6" for the DHCPv4 and DHCPv6 servers, respectively.
 
 The following command retrieves the IPv6 "DNS Servers" (code 23) option:
 
@@ -633,22 +633,22 @@ The following command retrieves the IPv6 "DNS Servers" (code 23) option:
 
 .. _command-remote-option4-global-get-all:
 
-remote-option4-global-get-all, remote-option6-global-get-all commands
+The remote-option4-global-get-all, remote-option6-global-get-all Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to fetch all global DHCP options from the
-configuration database. It takes no arguments except the optional
+configuration database. They take no arguments except the optional
 ``remote`` map.
 
 .. _command-remote-option4-global-set:
 
-remote-option4-global-set, remote-option6-global-set command
+The remote-option4-global-set, remote-option6-global-set Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands create a new global DHCP option or replace an existing
 option in the database. The structure of the option information is the
-same as in the Kea configuration file (see `??? <#dhcp4-std-options>`__
+same as in the Kea configuration file (see :ref:`dhcp4-std-options`
-and see `??? <#dhcp4-std-options>`__). For example:
+and :ref:`dhcp4-std-options`). For example:
 
 ::
 
@@ -670,7 +670,7 @@ and see `??? <#dhcp4-std-options>`__). For example:
 
 Note that specifying an option name instead of the option code only
 works reliably for the standard DHCP options. When specifying a value
-for the user defined DHCP option, the option code should be specified
+for the user-defined DHCP option, the option code should be specified
 instead of the name. For example:
 
 ::
@@ -691,12 +691,12 @@ instead of the name. For example:
 
 .. _command-remote-subnet4-del-by-id:
 
-remote-subnet4-del-by-id, remote-subnet6-del-by-id command
+The remote-subnet4-del-by-id, remote-subnet6-del-by-id Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is the first variant of the commands used to delete an IPv4 or IPv6
-subnet from the database. It uses subnet ID to identify the subnet. For
+subnet from the database. It uses the subnet ID to identify the subnet. For
-example, in order to delete the IPv4 subnet with ID of 5:
+example, to delete the IPv4 subnet with an ID of 5:
 
 ::
 
@@ -717,8 +717,8 @@ example, in order to delete the IPv4 subnet with ID of 5:
 
 .. _command-remote-subnet4-del-by-prefix:
 
-remote-subnet4-del-by-prefix, remote-subnet6-del-by-prefix commands
+The remote-subnet4-del-by-prefix, remote-subnet6-del-by-prefix Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is the second variant of the commands used to delete an IPv4 or
 IPv6 subnet from the database. It uses the subnet prefix to identify the
@@ -743,8 +743,8 @@ subnet. For example:
 
 .. _command-remote-subnet4-get-by-id:
 
-remote-subnet4-get-by-id, remote-subnet6-get-by-id commands
+The remote-subnet4-get-by-id, remote-subnet6-get-by-id Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is the first variant of the commands used to fetch an IPv4 or IPv6
 subnet from the database. It uses a subnet ID to identify the subnet.
@@ -769,8 +769,8 @@ For example:
 
 .. _command-remote-subnet4-get-by-prefix:
 
-remote-subnet4-get-by-prefix, remote-subnet6-get-by-prefix command
+The remote-subnet4-get-by-prefix, remote-subnet6-get-by-prefix Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is the second variant of the commands used to fetch an IPv4 or IPv6
 subnet from the database. It uses a subnet prefix to identify the
@@ -795,31 +795,31 @@ subnet. For example:
 
 .. _command-remote-subnet4-list:
 
-remote-subnet4-list, remote-subnet6-list commands
+The remote-subnet4-list, remote-subnet6-list Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to list all IPv4 or IPv6 subnets from the
-database. It takes no parameters except the optional ``remote`` map. The
+database. They take no parameters except the optional ``remote`` map. The
 returned information about each subnet is limited to subnet identifier,
-prefix and associated shared network name. In order to retrieve full
+prefix, and associated shared network name. To retrieve full
-information about the selected subnet use the
+information about the selected subnet, use the
-``remote-subnet[46]-get-by-id`` or ``remote-subnet[46]-get-by-prefix``.
+``remote-subnet[46]-get-by-id`` or ``remote-subnet[46]-get-by-prefix`` command.
 
 .. _command-remote-subnet4-set:
 
-remote-subnet4-set, remote-subnet6-set commands
+The remote-subnet4-set, remote-subnet6-set Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These commands are used to create a new IPv4 or IPv6 subnet or replace
 an existing subnet in the database. Setting the subnet also associates
 or disassociates the subnet with a shared network.
 
 The structure of the subnet information is similar to the structure used
-in the configuration file (see `??? <#dhcp4-configuration>`__ and
+in the configuration file (see :ref:`dhcp4-configuration` and
-`??? <#dhcp6-configuration>`__). The subnet information conveyed in the
+:ref:`dhcp6-configuration`). The subnet information conveyed in the
-``remote-subnet[46]-set`` must include additional parameter
+``remote-subnet[46]-set`` command must include the additional parameter
-``shared-network-name`` which denotes whether the subnet belongs to a
+``shared-network-name``, which denotes whether the subnet belongs to a
-shared network or not.
+shared network.
 
 Consider the following example:
 
@@ -847,12 +847,12 @@ Consider the following example:
    }
 
 
-It creates the subnet and associates the subnet with the "level3" shared
+It creates the subnet and associates it with the "level3" shared
-network. The "level3" must be created with the ``remote-network4-set``
+network. The "level3" shared network must be created with the ``remote-network4-set``
-prior to creating the subnet.
+command prior to creating the subnet.
 
-If the created subnet must be global (not associated with any shared
+If the created subnet must be global - that is, not associated with any shared
-network), the ``shared-network-name`` must be explicitly set to
+network - the ``shared-network-name`` must be explicitly set to
 ``null``:
 
 ::
@@ -877,14 +877,14 @@ network), the ``shared-network-name`` must be explicitly set to
 
 
 The subnet created in the previous example is replaced with the new
-subnet having the same parameters but it becomes global.
+subnet having the same parameters, but it becomes global.
 
 The ``shared-network-name`` parameter is mandatory for the
 ``remote-subnet4-set`` command.
 
    **Note**
 
-   Same as for other "set" commands, this command replaces the entire
+   As with other "set" commands, this command replaces all the
    information about the particular subnet in the database, if the
    subnet information is already present. Therefore, when sending this
    command, make sure to always include all parameters that must be

doc/guide/hooks-class-cmds.rst

@@ -11,20 +11,20 @@ list client classes configured for a given server.
 
    **Note**
 
-   This library may only be loaded by the ``kea-dhcp4`` or the
+   This library may only be loaded by the ``kea-dhcp4`` or
    ``kea-dhcp6`` process.
 
-The Class Commands hooks library is available to premium Kea customers
+The Class Commands hooks library is currently available only to ISC
-only.
+customers with a paid support contract.
 
 .. _command-class-add:
 
-class-add Command
+The class-add Command
------------------
+---------------------
 
 The ``class-add`` command adds a new client class to the DHCP server
 configuration. This class is appended at the end of the list of classes
-used by the server and may depend on any of the already configured
+used by the server and may depend on any of the already-configured
 client classes.
 
 The following example demonstrates how to add a new client class to the
@@ -61,12 +61,12 @@ Here is the response to the ``class-add`` command in our example:
 
 .. _command-class-update:
 
-class-update Command
+The class-update Command
---------------------
+------------------------
 
 The ``class-update`` command updates an existing client class in the
 DHCP server configuration. If the client class with the given name
-doesn't exist, the server returns the result code of 3, which means that
+does not exist, the server returns the result code of 3, which means that
 the server configuration is not modified and the client class does not
 exist. The ``class-add`` command must be used instead to create the new
 client class.
@@ -110,10 +110,10 @@ the new name will be added at the end of the list of configured classes.
 
 .. _command-class-del:
 
-class-del Command
+The class-del Command
------------------
+---------------------
 
-The ``class-del`` is used to remove a particular class from the server
+The ``class-del`` command is used to remove a particular class from the server
 configuration. The class to be removed is identified by name. The class
 is not removed if there are other classes depending on it; to remove
 such a class, the dependent classes must be removed first.
@@ -145,8 +145,8 @@ If the class doesn't exist, the result of 3 is returned.
 
 .. _command-class-list:
 
-class-list Command
+The class-list Command
-------------------
+----------------------
 
 ``class-list`` is used to retrieve a list of all client classes. This
 command includes no arguments:
@@ -183,8 +183,8 @@ merely class names. To retrieve full class information, the
 
 .. _command-class-get:
 
-class-get Command
+The class-get Command
------------------
+---------------------
 
 ``class-get`` is used to retrieve detailed information about a specified
 class. The command structure is very simple:

doc/guide/hooks-ha.rst

@@ -11,7 +11,7 @@ but is now part of the open source Kea, available to all users.
 
    **Note**
 
-   This library may only be loaded by the ``kea-dhcp4`` or the
+   This library may only be loaded by the ``kea-dhcp4`` or
    ``kea-dhcp6`` process.
 
 High Availability (HA) of the DHCP service is provided by running
@@ -44,13 +44,13 @@ Supported Configurations
 ------------------------
 
 The Kea HA hook library supports two configurations, also known as HA
-modes: load balancing and hot standby. In the load-balancing mode, two
+modes: load-balancing and hot-standby. In the load-balancing mode, two
 servers respond to DHCP requests. The load-balancing function is
 implemented as described in `RFC
-3074 <http://tools.ietf.org/html/rfc3074>`__, with each server
+3074 <https://tools.ietf.org/html/rfc3074>`__, with each server
 responding to half the received DHCP queries. When one of the servers
 allocates a lease for a client, it notifies the partner server over the
-control channel (RESTful API), so the partner can save the lease
+control channel (the RESTful API), so the partner can save the lease
 information in its own database. If the communication with the partner
 is unsuccessful, the DHCP query is dropped and the response is not
 returned to the DHCP client. If the lease update is successful, the
@@ -70,7 +70,7 @@ the primary server to complete the lease database synchronization before
 it starts the synchronization.
 
 In the hot-standby configuration, one of the servers is also designated
-as "primary" and the second as "secondary". However, during normal
+as "primary" and the second as "secondary." However, during normal
 operation, the primary server is the only one that responds to DHCP
 requests. The secondary or standby server receives lease updates from
 the primary over the control channel; however, it does not respond to
@@ -79,13 +79,13 @@ until the secondary considers the primary to be offline. If the
 secondary server detects the failure of the primary, it starts
 responding to all DHCP queries.
 
-In the configurations described above, the primary, secondary, and
+In the configurations described above, the primary and secondary/standby
-standby are referred to as "active" servers, because they receive lease
+are referred to as "active" servers, because they receive lease
 updates and can automatically react to the partner's failures by
 responding to the DHCP queries which would normally be handled by the
 partner. The HA hook library supports another server type/role: backup
-server. The use of a backup server is optional. They can be used in both
+server. The use of a backup server is optional, and can be implemented in both
-load balancing and hot standby setup, in addition to the active servers.
+load-balancing and hot-standby setup, in addition to the active servers.
 There is no limit on the number of backup servers in the HA setup;
 however, the presence of backup servers increases the latency of DHCP
 responses, because not only do active servers send lease updates to each
@@ -97,7 +97,7 @@ Clocks on Active Servers
 Synchronized clocks are essential for the HA setup to operate reliably.
 The servers share lease information via lease updates and during
 synchronization of the databases. The lease information includes the
-time when the lease has been allocated and when it expires. Some clock
+time when the lease was allocated and when it expires. Some clock
 skew between the servers participating in the HA setup usually exists;
 this is acceptable as long as the clock skew is relatively low, compared
 to the lease lifetimes. However, if the clock skew becomes too high, the
@@ -115,7 +115,7 @@ partner and receiving this response by the server which sent the
 heartbeat command. If the clock skew exceeds 30 seconds, a warning log
 message is issued. The administrator may correct this problem by
 synchronizing the clocks (e.g. using NTP); the servers should notice the
-clock skew correction and stop issuing the warning
+clock skew correction and stop issuing the warning.
 
 If the clock skew is not corrected and exceeds 60 seconds, the HA
 service on each of the servers is terminated, i.e. the state machine
@@ -135,10 +135,10 @@ state of the server can be retrieved by its peers using the
 ``ha-heartbeat`` command sent over the RESTful API. If the partner
 server doesn't respond to the ``ha-heartbeat`` command within the
 specified amount of time, the communication is considered interrupted
-and the server may (depending on the configuration) use additional
+and the server may, depending on the configuration, use additional
 measures (described later in this document) to verify that the partner
 is still operating. If it finds that the partner is not operating, the
-server transitions to the ``partner-down`` state to handle the entire
+server transitions to the ``partner-down`` state to handle all the
 DHCP traffic directed to the system.
 
 In this case, the surviving server continues to send the
@@ -181,7 +181,7 @@ The following is the list of all possible server states:
    leases from the active partner and update the local lease database.
    When in this state, the server issues the ``dhcp-disable`` command to
    disable the DHCP service of the partner from which the leases are
-   fetched. The DHCP service is disabled for the maximum time of 60
+   fetched. The DHCP service is disabled for a maximum time of 60
    seconds, after which it is automatically re-enabled, in case the
    syncing partner was unable to re-enable the service. If the
    synchronization is completed, the syncing server issues the
@@ -204,8 +204,8 @@ The following is the list of all possible server states:
    exchanged and the heartbeats are not sent. Once a server has entered
    the "terminated" state, it will remain in this state until it is
    restarted. The administrator must correct the issue which caused this
-   situation prior to restarting the server (e.g. synchronize clocks).
+   situation prior to restarting the server (e.g. synchronize the clocks);
-   Otherwise, the server will return to the "terminated" state once it
+   otherwise, the server will return to the "terminated" state once it
    finds that the issue persists.
 
 -  ``waiting`` - each started server instance enters this state. The
@@ -271,12 +271,12 @@ the scopes can be found below.
 
 The DHCP service scopes require some explanation. The HA configuration
 must specify a unique name for each server within the HA setup. This
-document uses the following convention within provided examples:
+document uses the following convention within the provided examples:
 ``server1`` for a primary server, ``server2`` for the secondary or
 standby server, and ``server3`` for the backup server. In real life any
 names can be used as long as they remain unique.
 
-In the load-balancing mode there are two scopes named after the active
+In the load-balancing mode there are two scopes specified for the active
 servers: ``HA_server1`` and ``HA_server2``. The DHCP queries
 load-balanced to ``server1`` belong to the ``HA_server1`` scope and the
 queries load-balanced to ``server2`` belong to the ``HA_server2`` scope.
@@ -452,9 +452,9 @@ behavior with respect to HA:
    it is greater than the duration of multiple ``heartbeat-delay``
    values. When the server detects that communication is interrupted, it
    may transition to the ``partner-down`` state (when
-   ``max-unacked-clients`` is 0) or trigger the failure- detection
+   ``max-unacked-clients`` is 0) or trigger the failure-detection
    procedure using the values of the two parameters below. The default
-   value of this parameter is 60000.
+   value of this parameter is 60000 ms.
 
 -  ``max-ack-delay`` - is one of the parameters controlling partner
    failure-detection. When communication with the partner is
@@ -485,7 +485,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. nighttime), because the number
+traffic in the network is very low (e.g. at nighttime), because the number
 of distinct clients trying to communicate with the server could be lower
 than the ``max-unacked-clients`` setting.
 
@@ -544,7 +544,7 @@ received DHCP queries. In many cases, HA will be needed in deployments
 which already use some other client classification.
 
 Suppose there is a system which classifies devices into two groups:
-phones and laptops, based on some classification criteria specified in
+phones and laptops, based on some classification criteria specified in the
 Kea configuration file. Both types of devices are allocated leases from
 different address pools. Introducing HA in the load-balancing mode
 results in a further split of each of those pools, as each server
@@ -561,7 +561,7 @@ the existing pools to be split between ``HA_server1`` and
 -  laptops_server2
 
 The corresponding server configuration using advanced classification
-(and ``member`` expression) is provided below. For brevity's sake, the
+(and the ``member`` expression) is provided below. For brevity's sake, the
 HA hook library configuration has been removed from this example.
 
 ::
@@ -657,14 +657,14 @@ pools: two pools dedicated to server1 and two to server2. Each server
 can assign leases to both phones and laptops. Both groups of devices are
 assigned addresses from different pools. The ``HA_server1`` and
 ``HA_server2`` classes are built-in (see
-`??? <#classification-using-vendor>`__) and do not need to be declared.
+:ref:`classification-using-vendor`) and do not need to be declared.
 They are assigned dynamically by the HA hook library as a result of the
 load-balancing algorithm. ``phones_*`` and ``laptop_*`` evaluate to
 "true" when the query belongs to a given combination of other classes,
 e.g. ``HA_server1`` and ``phones``. The pool is selected accordingly as
 a result of such an evaluation.
 
-Consult `??? <#classify>`__ for details on how to use the ``member``
+Consult :ref:`classify` for details on how to use the ``member``
 expression and class dependencies.
 
 .. _ha-hot-standby-config:
@@ -750,8 +750,7 @@ hot-standby configuration:
    }
 
 This configuration is very similar to the load-balancing configuration
-described in `Load-Balancing
+described in :ref:`ha-load-balancing-config`, with a few notable
-Configuration <#ha-load-balancing-config>`__, with a few notable
 differences.
 
 The ``mode`` is now set to ``hot-standby``, in which only one server
@@ -789,7 +788,7 @@ In some cases, though, it is desirable to disable lease updates and/or
 database synchronization between the active servers, if the exchange of
 information about the allocated leases is performed using some other
 mechanism. Kea supports various database types that can be used to store
-leases, including MySQL, Postgres, and Cassandra. Those databases
+leases, including MySQL, PostgreSQL, and Cassandra. Those databases
 include built-in solutions for data replication which are often used by
 Kea administrators to provide redundancy.
 
@@ -859,11 +858,11 @@ Controlling Lease-Page Size Limit
 
 An HA-enabled server initiates synchronization of the lease database
 after downtime or upon receiving the ``ha-sync`` command. The server
-uses commands described in `??? <#lease-get-page-cmds>`__ to fetch
+uses commands described in :ref:`lease-get-page-cmds` to fetch
 leases from its partner server (lease queries). The size of the results
 page (the maximum number of leases to be returned in a single response
-to one of these commands) can be controlled via HA hooks library
+to one of these commands) can be controlled via configuration of the HA hooks
-configuration. Increasing the page size decreases the number of lease
+library. Increasing the page size decreases the number of lease
 queries sent to the partner server, but it causes the partner server to
 generate larger responses, which lengthens transmission time as well as
 increases memory and CPU utilization on both servers. Decreasing the
@@ -885,8 +884,7 @@ lease-database synchronization after a server failure may be a
 time-consuming operation. The synchronizing server must gather all
 leases from its partner, which yields a large response over the RESTful
 interface. The server receives leases using the paging mechanism
-described in `Controlling Lease-Page Size
+described in :ref:`ha-syncing-page-limit`. Before the page of leases is fetched,
-Limit <#ha-syncing-page-limit>`__. Before the page of leases is fetched,
 the synchronizing server sends a ``dhcp-disable`` command to disable the
 DHCP service on the partner server. If the service is already disabled,
 this command will reset the timeout for the DHCP service being disabled.
@@ -897,7 +895,7 @@ service. The connection of the synchronizing server with its partner is
 also protected by the timeout. If the synchronization of a single page
 of leases takes longer than the specified time, the synchronizing server
 terminates the connection and the synchronization fails. Both timeout
-values are controlled by a single configuration parameter:
+values are controlled by a single configuration parameter,
 ``sync-timeout``. The following configuration snippet demonstrates how
 to modify the timeout for automatic re-enabling of the DHCP service on
 the partner server and how to increase the timeout for fetching a single
@@ -960,7 +958,7 @@ Pausing HA State Machine
 ------------------------
 
 The high-availability state machine includes many different states
-described in detail in `Server States <#ha-server-states>`__. The server
+described in detail in :ref:`ha-server-states`. The server
 enters each state when certain conditions are met, most often taking
 into account the partner server's state. In some states the server
 performs specific actions, e.g. synchronization of the lease database in
@@ -970,7 +968,7 @@ configured mode of operation in the ``load-balancing`` and
 
 By default, transitions between the states are performed automatically
 and the server administrator has no direct control when the transitions
-take place; in most cases, the administrator doesn't need such control.
+take place; in most cases, the administrator does not need such control.
 In some situations, however, the administrator may want to "pause" the
 HA state machine in a selected state to perform some additional
 administrative actions before the server transitions to the next state.
@@ -981,7 +979,7 @@ enters the ``syncing`` state by querying the partner server for leases,
 but it is possible that the partner was also experiencing a failure and
 lacks lease information. In this case, it may be required to reconstruct
 lease databases on both servers from some external source, e.g. a backup
-server. If the lease database is to be reconstructed via RESTful API,
+server. If the lease database is to be reconstructed via the RESTful API,
 the servers should be started in the initial, i.e. ``waiting``, state
 and remain in this state while leases are being added. In particular,
 the servers should not attempt to synchronize their lease databases nor
@@ -1041,14 +1039,13 @@ following configuration causes the HA state machine to pause in the
 The ``pause`` parameter value ``once`` denotes that the state machine
 should be paused upon the first transition to the ``waiting`` state;
 later transitions to this state will not cause the state machine to
-pause. Two other supported values of the ``pause`` parameter are:
+pause. Two other supported values of the ``pause`` parameter are
 ``always`` and ``never``. The latter is the default value for each
 state, which instructs the server never to pause the state machine.
 
 In order to "unpause" the state machine, the ``ha-continue`` command
 must be sent to the paused server. This command does not take any
-arguments. See `Control Commands for High
+arguments. See :ref:`ha-control-commands` for details about commands
-Availability <#ha-control-commands>`__ for details about commands
 specific to the HA hooks library.
 
 It is possible to configure the state machine to pause in more than one
@@ -1108,7 +1105,7 @@ This configuration instructs the server to pause the state machine every
 time it transitions to the ``ready`` state and upon the first transition
 to the ``partner-down`` state.
 
-Refer to `Server States <#ha-server-states>`__ for a complete list of
+Refer to :ref:`ha-server-states` for a complete list of
 server states. The state machine can be paused in any of the supported
 states; however, it is not practical for the ``backup`` and
 ``terminated`` states because the server never transitions out of these
@@ -1138,9 +1135,9 @@ states anyway.
 Control Agent Configuration
 ---------------------------
 
-`??? <#kea-ctrl-agent>`__ describes in detail the Kea daemon, which
+:ref:`kea-ctrl-agent` describes in detail the Kea daemon, which
-provides a RESTful interface to control Kea servers. The same
+provides a RESTful interface to control the Kea servers. The same
-functionality is used by the High Availability hook library to establish
+functionality is used by the High Availability hooks library to establish
 communication between the HA peers. Therefore, the HA library requires
 that the Control Agent (CA) be started for each DHCP instance within the
 HA setup. If the Control Agent is not started, the peers will not be
@@ -1186,18 +1183,18 @@ trigger lease-database synchronization on demand. It may also be useful
 to manually set the HA scopes that are being served.
 
 Note that the backup server can sometimes be used to handle DHCP traffic
-if both active servers are down. The backup servers do not perform
+if both active servers are down. The backup server does not perform
-failover function automatically. Thus, in order to use the backup server
+failover function automatically; thus, in order to use the backup server
 to respond to DHCP queries, the server administrator must enable this
 function manually.
 
-The following sections describe commands supported by the HA hook
+The following sections describe commands supported by the HA hooks
 library which are available for the administrator.
 
 .. _command-ha-sync:
 
-ha-sync Command
+The ha-sync Command
-~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~
 
 The ``ha-sync`` command instructs the server to synchronize its local
 lease database with the selected peer. The server fetches all leases
@@ -1207,7 +1204,7 @@ do not exist in the local database. All leases that are not returned by
 the peer but are in the local database are preserved. The database
 synchronization is unidirectional; only the database on the server to
 which the command has been sent is updated. In order to synchronize the
-peer's database a separate ``ha-sync`` has to be issued to that peer.
+peer's database a separate ``ha-sync`` command must be issued to that peer.
 
 Database synchronization may be triggered for both active and backup
 server types. The ``ha-sync`` command has the following structure
@@ -1229,13 +1226,13 @@ of the server from which it will be fetching leases, by sending the
 ``dhcp-disable`` command to that server. The ``max-period`` parameter
 specifies the maximum duration (in seconds) for which the DHCP service
 should be disabled. If the DHCP service is successfully disabled, the
-synchronizing server will fetch leases from the remote server by issuing
+synchronizing server fetches leases from the remote server by issuing
-one or more ``lease4-get-page`` commands. When the lease- database
+one or more ``lease4-get-page`` commands. When the lease-database
 synchronization is complete, the synchronizing server sends the
 ``dhcp-enable`` command to the peer to re-enable its DHCP service.
 
 The ``max-period`` value should be sufficiently long to guarantee that
-it doesn't elapse before the synchronization is completed. Otherwise,
+it does not elapse before the synchronization is completed. Otherwise,
 the DHCP server will automatically enable its DHCP function while the
 synchronization is still in progress. If the DHCP server subsequently
 allocates any leases during the synchronization, those new (or updated)
@@ -1244,13 +1241,12 @@ database inconsistencies.
 
 .. _command-ha-scopes:
 
-ha-scopes Command
+The ha-scopes Command
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~
 
 This command allows modification of the HA scopes that the server is
-serving. Consult `Load-Balancing
+serving. Consult :ref:`ha-load-balancing-config` and
-Configuration <#ha-load-balancing-config>`__ and `Hot-Standby
+:ref:`ha-hot-standby-config` to learn what scopes are
-Configuration <#ha-hot-standby-config>`__ to learn what scopes are
 available for different HA modes of operation. The ``ha-scopes`` command
 has the following structure (DHCPv4 server case):
 
@@ -1264,8 +1260,8 @@ has the following structure (DHCPv4 server case):
        }
    }
 
-This command configures the server to handle traffic from both
+This command configures the server to handle traffic from both the
-``HA_server1`` and ``HA_server2`` scopes. In order to disable all scopes
+``HA_server1`` and ``HA_server2`` scopes. To disable all scopes
 specify an empty list:
 
 ::
@@ -1280,12 +1276,11 @@ specify an empty list:
 
 .. _command-ha-continue:
 
-ha-continue Command
+The ha-continue Command
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~
 
 This command is used to resume the operation of the paused HA state
-machine, as described in `Pausing HA State
+machine, as described in :ref:`ha-pause-state-machine`. It takes no arguments, so the
-Machine <#ha-pause-state-machine>`__. It takes no arguments, so the
 command structure is as simple as:
 
 ::

doc/guide/hooks-lease-cmds.rst

@@ -5,12 +5,12 @@ lease_cmds: Lease Commands
 
 This section describes the hook library with commands used to manage
 leases. Kea provides a way to store lease information in several
-backends (memfile, MySQL, PostgreSQL and Cassandra), and this library
+backends (memfile, MySQL, PostgreSQL, and Cassandra), and this library
-provides a interface that can manipulate leases in a unified, safe way.
+provides an interface that can manipulate leases in a unified, safe way.
 In particular, it allows things previously impossible: lease
 manipulation in memfile while Kea is running, sanity check changes,
 lease existence checks, and removal of all leases belonging to a
-specific subnet. It can also catch more obscure errors, like an attempt
+specific subnet. The hook library can also catch more obscure errors, like an attempt
 to add a lease with a subnet-id that does not exist in the
 configuration, or configuring a lease to use an address that is outside
 of the subnet to which it is supposed to belong. The library also
@@ -25,57 +25,57 @@ leases.
 There are many use cases where an administrative command may be useful;
 for example, during migration between servers or different vendors, when
 a certain network is being retired, or when a device has been
-disconnected and the sysadmin knows for sure that it will not be coming
+disconnected and the system administrator knows that it will not be coming
 back. The "get" queries may be useful for automating certain management
 and monitoring tasks. They can also act as preparatory steps for lease
 updates and removals.
 
 This library provides the following commands:
 
--  ``lease4-add`` - adds a new IPv4 lease;
+-  ``lease4-add`` - adds a new IPv4 lease.
 
--  ``lease6-add`` - adds a new IPv6 lease;
+-  ``lease6-add`` - adds a new IPv6 lease.
 
 -  ``lease4-get`` - checks whether an IPv4 lease with the specified
-   parameters exists and returns it if it does;
+   parameters exists and returns it if it does.
 
 -  ``lease6-get`` - checks whether an IPv6 lease with the specified
-   parameters exists and returns it if it does;
+   parameters exists and returns it if it does.
 
 -  ``lease4-get-all`` - returns all IPv4 leases or all IPv4 leases for
-   the specified subnets;
+   the specified subnets.
 
 -  ``lease6-get-all`` - returns all IPv6 leases or all IPv6 leases for
-   the specified subnets;
+   the specified subnets.
 
 -  ``lease4-get-page`` - returns a set ("page") of leases from the list
    of all IPv4 leases in the database. By iterating through the pages it
-   is possible to retrieve all the leases;
+   is possible to retrieve all the leases.
 
 -  ``lease6-get-page`` - returns a set ("page") of leases from the list
    of all IPv6 leases in the database. By iterating through the pages it
-   is possible to retrieve all the leases;
+   is possible to retrieve all the leases.
 
--  ``lease4-del`` - deletes an IPv4 lease with the specified parameters;
+-  ``lease4-del`` - deletes an IPv4 lease with the specified parameters.
 
--  ``lease6-del`` - deletes an IPv6 lease with the specified parameters;
+-  ``lease6-del`` - deletes an IPv6 lease with the specified parameters.
 
--  ``lease4-update`` - updates an IPv4 lease;
+-  ``lease4-update`` - updates an IPv4 lease.
 
--  ``lease6-update`` - updates an IPv6 lease;
+-  ``lease6-update`` - updates an IPv6 lease.
 
 -  ``lease4-wipe`` - removes all leases from a specific IPv4 subnet or
-   from all subnets;
+   from all subnets.
 
 -  ``lease6-wipe`` - removes all leases from a specific IPv6 subnet or
-   from all subnets;
+   from all subnets.
 
 The lease commands library is part of the open source code and is
 available to every Kea user.
 
-All commands use JSON syntax and can be issued either using control
+All commands use JSON syntax and can be issued either using the control
-channel (see `??? <#ctrl-channel>`__) or Control Agent (see
+channel (see :ref:`ctrl-channel`) or Control Agent (see
-`??? <#kea-ctrl-agent>`__).
+:ref:`kea-ctrl-agent`).
 
 The library can be loaded in the same way as other hook libraries, and
 it does not take any parameters. It supports both DHCPv4 and DHCPv6
@@ -94,8 +94,8 @@ servers.
 
 .. _command-lease4-add:
 
-lease4-add, lease6-add Commands
+The lease4-add, lease6-add Commands
--------------------------------
+-----------------------------------
 
 The ``lease4-add`` and ``lease6-add`` commands allow for the creation of
 a new lease. Typically Kea creates a lease when it first sees a new
@@ -141,7 +141,7 @@ subnet. For example:
 ``lease6-add`` can also be used to add leases for IPv6 prefixes. In this
 case there are three additional parameters that must be specified:
 subnet-id, type (set to value of "IA_PD"), and prefix length. The actual
-prefix is set using ip-address field. Note that Kea cannot guess
+prefix is set using the ip-address field. Note that Kea cannot guess
 subnet-id values for prefixes; they must be specified explicitly. For
 example, to configure a lease for prefix 2001:db8:abcd::/48, the
 following command can be used:
@@ -160,19 +160,19 @@ following command can be used:
        }
    }
 
-The commands can take a number of additional optional parameters:
+The commands can take several additional optional parameters:
 
 -  ``valid-lft`` - specifies the lifetime of the lease, expressed in
    seconds. If not specified, the value configured in the subnet related
    to the specified subnet-id is used.
 
 -  ``expire`` - creates a timestamp of the lease expiration time,
-   expressed in unix format (seconds since 1 Jan 1970). If not
+   expressed in UNIX format (seconds since 1 Jan 1970). If not
    specified, the default value is now + the lease lifetime (the value
    of valid-lft).
 
 -  ``fqdn-fwd`` - specifies whether the lease should be marked as if a
-   forward DNS update were conducted. Note this only affects the the
+   forward DNS update were conducted. Note this only affects the
    data stored in the lease database, and no DNS update will be
    performed. If configured, a DNS update to remove the A or AAAA
    records will be conducted when the lease is removed due to expiration
@@ -228,8 +228,8 @@ Here is an example of a more complex lease addition:
        }
    }
 
-The command returns a status that indicates either a success (result 0)
+The command returns a status that indicates either success (result 0)
-or a failure (result 1). A failed command always includes a text
+or failure (result 1). A failed command always includes a text
 parameter that explains the cause of failure. For example:
 
 ::
@@ -244,14 +244,14 @@ Example failure:
 
 .. _command-lease4-get:
 
-lease4-get, lease6-get Commands
+The lease4-get, lease6-get Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``lease4-get`` or ``lease6-get`` can be used to query the lease database
 and retrieve existing leases. There are two types of parameters the
 ``lease4-get`` command supports: (address) or (subnet-id,
 identifier-type, identifier). There are also two types for
-``lease6-get``: (address,type) or (subnet-id, identifier-type,
+``lease6-get``: (address, type) or (subnet-id, identifier-type,
 identifier, IAID, type). The first type of query is used when the
 address (either IPv4 or IPv6) is known, but the details of the lease are
 not; one common use case of this type of query is to find out whether a
@@ -359,8 +359,8 @@ An example result returned when the host was found:
 
 .. _command-lease4-get-all:
 
-lease4-get-all, lease6-get-all Commands
+The lease4-get-all, lease6-get-all Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``lease4-get-all`` and ``lease6-get-all`` are used to retrieve all IPv4
 or IPv6 leases, or all leases for the specified set of subnets. All
@@ -373,7 +373,7 @@ command, as in the following example:
        "command": "lease4-get-all"
    }
 
-If the arguments are provided, it is expected that they contain the
+If arguments are provided, it is expected that they contain the
 "subnets" parameter, which is a list of subnet identifiers for which the
 leases should be returned. For example, in order to retrieve all IPv6
 leases belonging to the subnets with identifiers 1, 2, 3, and 4:
@@ -444,8 +444,8 @@ following format:
 
 .. _lease-get-page-cmds:
 
-lease4-get-page, lease6-get-page Commands
+The lease4-get-page, lease6-get-page Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``lease4-get-all`` and ``lease6-get-all`` commands may result in
 very large responses; generating such a response may consume CPU
@@ -567,11 +567,11 @@ leases were found.
 
 .. _command-lease4-del:
 
-lease4-del, lease6-del Commands
+The lease4-del, lease6-del Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``leaseX-del`` can be used to delete a lease from the lease database.
-There are two types of parameters this command supports, similar to
+There are two types of parameters this command supports, similar to the
 leaseX-get commands: (address) for both v4 and v6, (subnet-id,
 identifier-type, identifier) for v4, and (subnet-id, identifier-type,
 identifier, type, IAID) for v6. The first type of query is used when the
@@ -579,7 +579,7 @@ address (either IPv4 or IPv6) is known, but the details of the lease are
 not. One common use case is where an administrator wants a specified
 address to no longer be used. The second form of the command uses
 identifiers. For maximum flexibility, this interface uses identifiers as
-a pair of values: type and the actual identifier. The currently
+a pair of values: the type and the actual identifier. The currently
 supported identifiers are "hw-address" (IPv4 only), "client-id" (IPv4
 only), and "duid" (IPv6 only).
 
@@ -614,8 +614,8 @@ properly, but the object (a lease in this case) has not been found.
 
 .. _command-lease4-update:
 
-lease4-update, lease6-update Commands
+The lease4-update, lease6-update Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``lease4-update`` and ``lease6-update`` commands can be used to
 update existing leases. Since all lease database backends are indexed by
@@ -629,8 +629,8 @@ subnet-selection procedure. If specified, however, its value must match
 the existing subnet.
 
 The optional boolean parameter "force-create" specifies whether the
-lease should be created if it doesn't exist in the database. It defaults
+lease should be created if it does not exist in the database. It defaults
-to false, which indicates that the lease is not created if it doesn't
+to false, which indicates that the lease is not created if it does not
 exist. In such a case, an error is returned as a result of trying to
 update a non-existing lease. If the "force-create" parameter is set to
 true and the updated lease does not exist, the new lease is created as a
@@ -669,13 +669,13 @@ An example of a command to update an IPv6 lease is:
 
 .. _command-lease4-wipe:
 
-lease4-wipe, lease6-wipe Commands
+The lease4-wipe, lease6-wipe Commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``lease4-wipe`` and ``lease6-wipe`` are designed to remove all leases
 associated with a given subnet. This administrative task is expected to
 be used when an existing subnet is being retired. Note that the leases
-are not properly expired: no DNS updates are carried out, no log
+are not properly expired; no DNS updates are carried out, no log
 messages are created, and hooks are not called for the leases being
 removed.
 

doc/guide/install.rst

@@ -1,3 +1,5 @@
+.. _installation:
+
 ************
 Installation
 ************
@@ -365,9 +367,9 @@ DHCP Database Installation and Configuration
 Kea stores its leases in a lease database. The software has been written
 in a way that makes it possible to choose which database product should
 be used to store the lease information. Kea supports four
-database backends: MySQL, PostgreSQL, Cassandra, and Memfile. To limit
+database backends: MySQL, PostgreSQL, Cassandra, and memfile. To limit
 external dependencies, MySQL, PostgreSQL, and Cassandra support are
-disabled by default and only Memfile is available. Support for the
+disabled by default and only memfile is available. Support for the
 optional external database backend must be explicitly included when Kea
 is built. This section covers the building of Kea with one of the
 optional backends and the creation of the lease database.

doc/guide/kea-guide.rst

@@ -14,7 +14,7 @@ Kea, can be found in ISC's `Knowledgebase <https://kb.isc.org/docs/kea-administr
 
 .. toctree::
    :numbered:
-   :maxdepth: 3
+   :maxdepth: 5
 
    intro
    quickstart