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-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
-only.
+The Class Commands hooks library is currently available only to ISC
+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-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
-provides a interface that can manipulate leases in a unified, safe way.
+backends (memfile, MySQL, PostgreSQL, and Cassandra), and this library
+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
-channel (see `??? <#ctrl-channel>`__) or Control Agent (see
-`??? <#kea-ctrl-agent>`__).
+All commands use JSON syntax and can be issued either using the control
+channel (see :ref:`ctrl-channel`) or Control Agent (see
+: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
@@ -83,19 +83,19 @@ servers.
 
 ::
 
-   "Dhcp6": { 
+   "Dhcp6": {
        "hooks-libraries": [
            {
                "library": "/path/libdhcp_lease_cmds.so"
            }
            ...
-       ] 
+       ]
    }
 
 .. _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)
-or a failure (result 1). A failed command always includes a text
+The command returns a status that indicates either success (result 0)
+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
-to false, which indicates that the lease is not created if it doesn't
+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 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

+.. _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