Additional edits, Sphinx formatting

doc/guide/classify.rst

@@ -98,7 +98,7 @@ The classification process is conducted in several steps:
 
 ..
 
- .. note::
+.. note::
 
    Client classes in Kea follow the order in which they are specified in
    the configuration (vs. alphabetical order). Required classes follow
@@ -120,7 +120,7 @@ the client requested. As the NTP server was defined twice, the server
 chooses only one of the values for the reply; the class from which the
 value is obtained is unspecified.
 
- .. note::
+.. note::
 
    Care should be taken with client classification, as it is easy for
    clients that do not meet any class criteria to be denied service
@@ -413,7 +413,7 @@ Notes:
    than one appear. For the vendor.enterprise and vendor-class.enterprise
    expressions, the value from the first instance is returned. Please
    submit a feature request on the
-   `Kea GitLab site <https://gitlab.isc.org/isc-projects/kea>`__ if you need
+   `Kea GitLab site <https://gitlab.isc.org/isc-projects/kea>`__ to request
    support for multiple instances.
 
 .. table:: List of Classification Expressions
@@ -517,7 +517,7 @@ digits separated by the separator, e.g ':', '-', '' (empty separator).
 
 ..
 
- .. note::
+.. note::
 
    The expression for each class is executed on each packet received. If
    the expressions are overly complex, the time taken to execute them
@@ -543,7 +543,7 @@ The option data is a list which defines any options that should be
 assigned to members of this class.
 
 The option definition is for DHCPv4 option 43
-(:ref:`dhcp4-vendor-opts` and DHCPv4 private options
+(:ref:`dhcp4-vendor-opts`) and DHCPv4 private options
 (:ref:`dhcp4-private-opts`).
 
 Usually the test expression is evaluated before subnet selection, but in
@@ -889,17 +889,17 @@ The logging might then resemble this:
 
 ::
 
-          2016-05-19 13:35:04.163 DEBUG [kea.eval/44478] EVAL_DEBUG_OPTION Pushing option 61 with value 0x666F6F626172
+      2016-05-19 13:35:04.163 DEBUG [kea.eval/44478] EVAL_DEBUG_OPTION Pushing option 61 with value 0x666F6F626172
-          2016-05-19 13:35:04.164 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '0'
+      2016-05-19 13:35:04.164 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '0'
-          2016-05-19 13:35:04.165 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '3'
+      2016-05-19 13:35:04.165 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '3'
-          2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0, string 0x666F6F626172 pushing result 0x666F6F
+      2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0, string 0x666F6F626172 pushing result 0x666F6F
-          2016-05-19 13:35:04.167 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string 'foo'
+      2016-05-19 13:35:04.167 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string 'foo'
-          2016-05-19 13:35:04.168 DEBUG [kea.eval/44478] EVAL_DEBUG_EQUAL Popping 0x666F6F and 0x666F6F pushing result 'true'
+      2016-05-19 13:35:04.168 DEBUG [kea.eval/44478] EVAL_DEBUG_EQUAL Popping 0x666F6F and 0x666F6F pushing result 'true'
 
 
 ..
 
- .. note::
+.. note::
 
    The debug logging may be quite verbose if there are a number of
    expressions to evaluate; that is intended as an aid in helping

doc/guide/congestion-handling.rst

@@ -4,7 +4,7 @@
 Congestion Handling in DHCPv4 and DHCPv6
 ****************************************
 
-.. _congeston-handling-background:
+.. _congestion-handling-background:
 
 What is Congestion?
 ===================
@@ -39,7 +39,7 @@ that were no longer relevant, or worse, were redundant. In other words,
 the packets waiting in the FIFO socket buffers became increasingly
 stale.
 
-.. _congeston-handling-solution:
+.. _congestion-handling-solution:
 
 Configuring Congestion Handling
 ===============================
@@ -70,7 +70,8 @@ queue is implemented as a plug-in, which can replaced by a custom queue
 implementation via a hook library. This should make it straightforward
 for interested parties to experiment with their own solutions.
 (Developers can refer to isc::dhcp::PacketQueue and
-isc::dhcp::PacketQueueMgr, described in the Kea Developer's Guide).
+isc::dhcp::PacketQueueMgr, described in the
+`Kea Developer's Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/index.html>`__.)
 
 Packet queue behavior is configured in both kea-dhcp4 and kea-dhcp6
 servers through an optional, top-level, configuration element,

doc/guide/ddns.rst

@@ -141,7 +141,7 @@ Upon startup, the module will load its configuration and begin listening
 for NCRs based on that configuration.
 
 During startup, the server will attempt to create a PID file of the form:
-[localstatedir]/[conf name].kea-dhcp-ddns.pid where:
+[**localstatedir**]/[**conf name**].kea-dhcp-ddns.pid where:
 
 -  ``localstatedir`` - is the value as passed into the build configure
    script; it defaults to "/usr/local/var". Note that this value may be
@@ -560,7 +560,7 @@ This section describes how to add Reverse DDNS Domains; repeat these
 steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain has
 the following parameters:
 
--  ``name`` - the fully qualified reverse zone that this DDNS Domain can
+-  ``name`` - the fully qualified reverse zone that this DDNS domain can
    update. This is the value used during reverse matching, which will
    compare it with a reversed version of the request's lease address.
    The zone name should follow the appropriate standards; for example,

doc/guide/dhcp6-srv.rst

@@ -58,7 +58,7 @@ configuration file. Since the DHCPv6 server opens privileged ports, it
 requires root access. This daemon must be run as root.
 
 During startup, the server will attempt to create a PID file of the
-form: localstatedir]/[conf name].kea-dhcp6.pid where:
+form: [**localstatedir**]/[**conf name**].kea-dhcp6.pid where:
 
 -  ``localstatedir``: The value as passed into the build configure
    script; it defaults to "/usr/local/var". Note that this value may be
@@ -571,7 +571,7 @@ be set to "mysql" or "postgresql".
 
 Next, the name of the database to hold the reservations must be set;
 this is the name used when the lease database was created (see
-`:ref:`supported-databases` for instructions on how to set up the
+:ref:`supported-databases` for instructions on how to set up the
 desired database type):
 
 ::
@@ -1782,10 +1782,10 @@ last field is an array, i.e. it can contain more than one value, as in:
        ...
    }
 
-The new option content is one IPv6 address followed by one or more 16-
+The new option content is one IPv6 address followed by one or more 16-bit
-bit unsigned integers.
+unsigned integers.
 
- .. note::
+.. note::
 
    In general, boolean values are specified as ``true`` or ``false``,
    without quotes. Some specific boolean parameters may accept also
@@ -2082,7 +2082,7 @@ Calculation of the values is controlled by the following three parameters:
 
 ..
 
- .. note::
+.. note::
 
    In the event that both explicit values are specified and
    calculate-tee-times is true, the server will use the explicit values.
@@ -2332,7 +2332,7 @@ class list for the packet. The second specifies an expression that is
 evaluated for each packet. If the result is "true", the packet is a
 member of the class.
 
- .. note::
+.. note::
 
    Care should be taken with client classification, as it is easy for
    clients that do not meet class criteria to be denied all service.
@@ -2614,7 +2614,7 @@ will generate NCRs and the configuration parameters that can be used to
 influence this decision. It assumes that the ``enable-updates``
 parameter is true.
 
- .. note::
+.. note::
 
    Currently the interface between kea-dhcp6 and D2 only supports
    requests which update DNS entries for a single IP address. If a lease
@@ -2753,7 +2753,7 @@ parameter, which provides the following modes of behavior:
 
 ..
 
- .. note::
+.. note::
 
    Note that in early versions of Kea, this parameter was a boolean and
    permitted only values of ``true`` and ``false``.
@@ -2808,25 +2808,25 @@ are enabled. To set its value simply set it to the desired string:
 When qualifying a partial name, kea-dhcp6 will construct the name in the
 format:
 
-[candidate-name].[qualifying-suffix].
+[**candidate-name**].[**qualifying-suffix**].
 
-where candidate-name is the partial name supplied in the DHCPREQUEST.
+where **candidate-name** is the partial name supplied in the DHCPREQUEST.
 For example, if the FQDN domain name value is "some-computer" and the
 qualifying-suffix "example.com", the generated FQDN is:
 
-some-computer.example.com.
+**some-computer.example.com.**
 
 When generating the entire name, kea-dhcp6 will construct the name in
 the format:
 
-[generated-prefix]-[address-text].[qualifying-suffix].
+[**generated-prefix**]-[**address-text**].[**qualifying-suffix**].
 
-where address-text is simply the lease IP address converted to a
+where **address-text** is simply the lease IP address converted to a
 hyphenated string. For example, if the lease address is 3001:1::70E, the
 qualifying suffix "example.com", and the default value is used for
 ``generated-prefix``, the generated FQDN is:
 
-myhost-3001-1--70E.example.com.
+**myhost-3001-1--70E.example.com.**
 
 .. _host-name-sanitization:
 
@@ -2870,7 +2870,7 @@ Thus, a client-supplied value of "myhost-$[123.org" would become
 name supplied by the client, and it is performed before applying a
 qualifying suffix (if one is defined and needed).
 
- .. note::
+.. note::
 
    The following are some considerations to keep in mind:
    Name sanitizing is meant to catch the more common cases of invalid
@@ -2909,7 +2909,7 @@ cooperating DHCPv4 and DHCPv6 servers. This section is about the
 configuration of the DHCPv6 side (the DHCPv4 side is described in
 :ref:`dhcp4-dhcp4o6-config`).
 
- .. note::
+.. note::
 
    DHCPv4-over-DHCPv6 support is experimental and the details of the
    inter-process communication may change; both the DHCPv4 and DHCPv6
@@ -2980,7 +2980,7 @@ The following configuration was used during some tests:
 
 ..
 
- .. note::
+.. note::
 
    Relayed DHCPv4-QUERY DHCPv6 messages are not supported.
 
@@ -3195,10 +3195,10 @@ global reservations defined. Typically, such reservations would be used
 to reserve hostnames for clients which may move from one subnet to
 another.
 
- .. note::
+.. note::
 
    Global reservations, while useful in certain circumstances, have aspects
-   that must be given due consideration when using them, please see
+   that must be given due consideration. Please see
    :ref:`reservation6-conflict` for more details.
 
 .. _reservation6-conflict:
@@ -3250,7 +3250,7 @@ conflict with existing leases. Another recommendation is to use
 out-of-pool reservations. If the reserved address does not belong to a
 pool, there is no way that other clients can get it.
 
- .. note::
+.. note::
 
    The conflict-resolution mechanism does not work for global
    reservations. Although the global address reservations feature may be useful
@@ -3437,7 +3437,7 @@ 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.
 
- .. note::
+.. note::
 
    To force the evaluation of a class expression after the
    host reservation lookup, for instance because of a dependency on
@@ -3459,7 +3459,7 @@ The `Kea wiki
 provides some examples of how to conduct common host reservations
 operations.
 
- .. note::
+.. note::
 
    In Kea, the maximum length of an option specified per-host is
    arbitrarily set to 4096 bytes.
@@ -3723,7 +3723,7 @@ before the pools in the first subnet get exhausted; this sometimes occurs
 when the client provides a hint that belongs to another subnet, or the client has
 reservations in a subnet other than the default.
 
- .. note::
+.. note::
 
    Deployments should not assume that Kea waits until it has allocated
    all the addresses from the first subnet in a shared network before
@@ -4168,7 +4168,7 @@ When a new DUID type is selected, the server generates its value and
 replaces any existing DUID in the file. The server then uses the new
 server identifier in all future interactions with the clients.
 
- .. note::
+.. note::
 
    If the new server identifier is created after some clients have
    obtained their leases, the clients using the old identifier are not
@@ -4512,7 +4512,7 @@ selects that subnet for a relay with address 3000::1.
 If "relay" is specified, the "ip-addresses" parameter within it is
 mandatory.
 
- .. note::
+.. note::
 
    The current version of Kea uses the "ip-addresses" parameter, which
    supports specifying a list of addresses.
@@ -4758,7 +4758,7 @@ back to the available pool.
 Statistics in the DHCPv6 Server
 ===============================
 
- .. note::
+.. note::
 
    This section describes DHCPv6-specific statistics. For a general
    overview and usage of statistics, see :ref:`stats`.
@@ -5499,7 +5499,7 @@ The following standards are currently supported:
 -  *Dynamic Host Configuration Protocol for IPv6 (DHCPv6)*, `RFC
    8415 <https://tools.ietf.org/html/rfc8415>`__: New DHCPv6 protocol
    specification which obsoletes RFC 3315, RFC 3633, RFC 3736, RFC 4242,
-   RFC 7083, RFC 7283, and RFC 7550
+   RFC 7083, RFC 7283, and RFC 7550.
 
 .. _dhcp6-limit:
 

doc/guide/hooks-class-cmds.rst

@@ -141,7 +141,7 @@ the specified client class has been found:
        "text": "Class 'ipxe_efi_x64' deleted."
    }
 
-If the class doesn't exist, the result of 3 is returned.
+If the class does not exist, the result of 3 is returned.
 
 .. _command-class-list:
 

doc/guide/hooks-ha.rst

@@ -9,7 +9,7 @@ of the DHCP service in the event of an outage of one of the servers.
 This library was previously only available to ISC's paid subscribers,
 but is now part of the open source Kea, available to all users.
 
- .. note::
+.. note::
 
    This library may only be loaded by the ``kea-dhcp4`` or
    ``kea-dhcp6`` process.
@@ -223,7 +223,7 @@ The following is the list of all possible server states:
 
 ..
 
- .. note::
+.. note::
 
    Currently, restarting the HA service from the ``terminated`` state
    requires restarting the DHCP server or reloading its configuration.
@@ -295,7 +295,8 @@ in normal operation serves no scopes.
 The scope names can be used to associate pools, subnets, and networks
 with certain servers, so only these servers can allocate addresses or
 prefixes from those pools, subnets, or networks. This is done via the
-client classification mechanism (see below).
+client classification mechanism (see :ref:`ha-load-balancing-advanced-config`
+for more details).
 
 .. _ha-scope-transition:
 
@@ -394,13 +395,13 @@ with the only difference that ``this-server-name`` should be set to
        }]
    }
 
-Two hook libraries must be loaded to enable HA:
+Two hooks libraries must be loaded to enable HA:
 ``libdhcp_lease_cmds.so`` and ``libdhcp_ha.so``. The latter implements
 the HA feature, while the former enables control commands required by HA
 to fetch and manipulate leases on the remote servers. In the example
 provided above, it is assumed that Kea libraries are installed in the
 ``/usr/lib`` directory. If Kea is not installed in the /usr directory,
-the hook libraries locations must be updated accordingly.
+the hooks libraries locations must be updated accordingly.
 
 The HA configuration is specified within the scope of ``libdhcp_ha.so``.
 Note that the top-level parameter ``high-availability`` is a list, even
@@ -803,8 +804,8 @@ less than 10000 lines.
 
 .. _ha-syncing-timeouts:
 
-Discussion About Timeouts
+Timeouts
--------------------------
+--------
 
 In deployments with a large number of clients connected to the network,
 lease-database synchronization after a server failure may be a
@@ -881,10 +882,10 @@ the Kea source at: ``src/lib/config/timeouts.h``.
 
 .. _ha-pause-state-machine:
 
-Pausing HA State Machine
+Pausing the HA State Machine
-------------------------
+----------------------------
 
-The high availability state machine includes many different states
+The high-availability state machine includes many different states
 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
@@ -1038,7 +1039,7 @@ states; however, it is not practical for the ``backup`` and
 ``terminated`` states because the server never transitions out of these
 states anyway.
 
- .. note::
+.. note::
 
    In the ``syncing`` state the server is paused before it makes an
    attempt to synchronize the lease database with a partner. To pause
@@ -1047,7 +1048,7 @@ states anyway.
 
 ..
 
- .. note::
+.. note::
 
    The state of the HA state machine depends on the state of the
    cooperating server. Therefore, it must be taken into account that

doc/guide/hooks-host-cache.rst

@@ -44,7 +44,7 @@ any other hooks library; for example, this configuration could be used:
          }
      } ]
 
-Once loaded, the Host Cache hook library provides a number of new
+Once loaded, the Host Cache hooks library provides a number of new
 commands which can be used either over the control channel (see
 :ref:`ctrl-channel-client`) or the RESTful API (see
 :ref:`agent-overview`). An example RESTful API client is described in
@@ -69,7 +69,7 @@ removed. An example usage looks as follows:
 
 This command will remove 1000 hosts. To delete all cached
 hosts, please use cache-clear instead. The hosts are stored in FIFO
-order, so the oldest entries are always removed.
+(first-in, first-out) order, so the oldest entries are always removed.
 
 .. _command-cache-clear:
 

doc/guide/hooks-radius.rst

@@ -3,7 +3,7 @@
 radius: RADIUS Server Support
 =============================
 
-The RADIUS hook library allows Kea to interact with two types of RADIUS
+The RADIUS hooks library allows Kea to interact with two types of RADIUS
 servers: access and accounting. Although the most common DHCP and RADIUS
 integration is done on the DHCP relay-agent level (DHCP clients send
 DHCP packets to DHCP relays; those relays contact the RADIUS server and
@@ -538,8 +538,8 @@ received during the initial Discover/Offer exchanges and use it again
 later when sending accounting messages.
 
 This mechanism is implemented based on user context in host
-reservations. (See :ref:`user-context` for details about user
+reservations. (See :ref:`user-context` for details.)
-context). The host cache mechanism allows the information retrieved by
+The host cache mechanism allows the information retrieved by
 RADIUS to be stored and later used for sending accounting and access
 queries to the RADIUS server. In other words, the host-cache mechanism
 is mandatory, unless administrators do not want RADIUS communication for messages

doc/guide/hooks.rst

@@ -127,7 +127,7 @@ some hooks may require their own dedicated switches, e.g. the RADIUS hook
 requires extra switches for FreeRADIUS. Please consult later sections of
 this chapter for details.
 
-6. Rebuild Kea
+6. Rebuild Kea.
 
 ::
 
@@ -209,7 +209,9 @@ configuration would be:
    parameter entry for comments, as is the case with many configuration
    scopes.
 
-.. note:
+..
+
+.. note::
 
    In all versions of Kea since 1.1.0, libraries
    are reloaded even if their lists have not changed,
@@ -238,7 +240,7 @@ Notes:
 -  An empty list has the same effect as omitting the ``hooks-libraries``
    configuration element altogether.
 
-    .. note::
+   .. note::
 
       There is one case where this is not true: if Kea is running with a
       configuration that contains a ``hooks-libraries`` item, and that
@@ -1033,7 +1035,7 @@ client-id option) is ignored.
 
 The :ref:`lease-cmds` section describes commands used to retrieve,
 update, and delete leases using various identifiers, such as "hw-address" and
-"client-id". The lease_cmds library doesn't natively support querying
+"client-id". The lease_cmds library does not natively support querying
 for leases by flexible identifier. However, when ``replace-client-id`` is
 set to "true", it makes it possible to query for leases using a value
 derived from the flexible identifier. In the DHCPv4 case, the query will
@@ -1528,7 +1530,7 @@ page is received. Its response will look like this:
 This command is more complex than ``reservation-get-all``, but lets
 users retrieve larger host reservations lists in smaller chunks. For
 small deployments with few reservations, it is easier to use
-``reservation-get-all`` (see :ref:`command-reservation-get-all`.
+``reservation-get-all`` (see :ref:`command-reservation-get-all`).
 
 .. note::
 
@@ -2085,7 +2087,7 @@ belonging to the subnet. The server may also be configured with static
 host reservations which are associated with this subnet. The current
 implementation of the ``subnet4-del`` command removes neither the leases nor
 the host reservations associated with a subnet. This is the safest approach
-because the server doesn't lose track of leases assigned to the clients
+because the server does not lose track of leases assigned to the clients
 from this subnet. However, removal of the subnet may still cause
 configuration errors and conflicts. For example: after removal of the
 subnet, the server administrator may update a new subnet with the ID
@@ -2141,7 +2143,7 @@ belonging to the subnet. The server may also be configured with static
 host reservations which are associated with this subnet. The current
 implementation of the ``subnet6-del`` command removes neither the leases nor
 the host reservations associated with a subnet. This is the safest approach
-because the server doesn't lose track of leases assigned to the clients
+because the server does not lose track of leases assigned to the clients
 from this subnet. However, removal of the subnet may still cause
 configuration errors and conflicts. For example: after removal of the
 subnet, the server administrator may add a new subnet with the ID used

doc/guide/index.rst

@@ -75,7 +75,7 @@ project: `Afilias <https://www.afilias.info/>`__,
 `Google <https://www.google.com/>`__, `RIPE
 NCC <https://www.ripe.net/>`__, `Registro.br <https://registro.br/>`__,
 `.nz Registry Services <https://nzrs.net.nz/>`__, and `Technical Center
-of Internet <https://www.tcinet.ru/>`__ .
+of Internet <https://www.tcinet.ru/>`__.
 
 .. |image0| image:: kea-logo-100x70.png
 

doc/guide/lease-expiration.rst

@@ -155,8 +155,8 @@ by the following diagram:
 
 
    |  c1  |            | c2 |            |c3|            | c4 |
-   |<---->|<---------->|<-->|<---------->|<>|<---------->|<-->|
+   |<---->|<---------->|<-->|<---------->|<>|<---------->|<-->|<--
-   ---------------------------------------------------------------->
+   ------------------------------------------------------------------>
    |      |     5s     |    |     5s     |  |     5s     |    | time
 
 This diagram shows four lease-reclamation cycles (c1 through c4) of
@@ -322,9 +322,9 @@ should consider using host reservations or leases with very long lifetimes.
 
 .. _leases-reclamation-using-command:
 
-Reclaiming Expired Leases with Command
+Reclaiming Expired Leases via Command
-======================================
+=====================================
 
-The *leases-reclaim* command can be used to trigger lease reclamation at
+The ``leases-reclaim`` command can be used to trigger lease reclamation at
 any time. Please consult the :ref:`command-leases-reclaim` section
 for details about using this command.