Converting from docbook to sphinx: fixing links, making content/grammar corrections as needed

doc/guide/admin.rst

@@ -28,11 +28,11 @@ PostgreSQL.
 Backend versions are specified in a major.minor format. The minor number
 is increased when there are backwards-compatible changes introduced; for
 example, the addition of a new index. It is desirable but not mandatory
-to apply such a change; you can run an older backend version if you want
+to apply such a change; running an older backend version is possible.
-to. (Although, in the example given, running without the new index may
+(Although, in the example given, running without the new index may
 introduce a performance penalty.) On the other hand, the
 major number is increased when an incompatible change is introduced; for
-example, an extra column is added to a table. If you try to run Kea on a
+example, an extra column is added to a table. If Kea is run on a
 backend that is too old (as signified by a mismatched backend major
 version number), Kea will refuse to run; administrative action will be
 required to upgrade the backend.
@@ -80,7 +80,7 @@ supported types are:
 
 -  ``cql`` — Information is stored in an Apache Cassandra database.
 
-Additional parameters may be needed, depending on your setup and
+Additional parameters may be needed, depending on the setup and
 specific operation: username, password, and database name or the
 directory where specific files are located. See the appropriate manual
 page for details (``man 8 kea-admin``).
@@ -93,7 +93,7 @@ Supported Backends
 The following table presents the capabilities of available backends.
 Please refer to the specific sections dedicated to each backend to
 better understand their capabilities and limitations. Choosing the right
-backend may be essential for the success of your deployment.
+backend may be essential for the success of the deployment.
 
 .. table:: List of available backends
 
@@ -152,9 +152,8 @@ newer versions of Kea, it can also be used for downgrading should the
 need arise. When upgrading, any values not present in the original lease
 files will be assigned appropriate default values. When downgrading, any
 data present in the files but not in the server's schema will be
-dropped. If you wish to convert the files manually prior to starting the
+dropped. To convert the files manually prior to starting the
-servers, you may do so by running the LFC process yourself. See
+servers, run the LFC process. See :ref:`kea-lfc` for more information.
-:ref:`kea-lfc` for more information.
 
 .. _mysql-database:
 
@@ -164,17 +163,17 @@ MySQL
 MySQL is able to store leases, host reservations, options defined on a
 per-host basis, and a subset of the server configuration parameters
 (serving as a configuration backend). This section can be safely ignored
-if you choose to store the data in other backends.
+if the data will be stored in other backends.
 
 .. _mysql-database-create:
 
 First-Time Creation of the MySQL Database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you are setting the MySQL database for the first time, you need to
+When setting up the MySQL database for the first time, the
-create the database area within MySQL and set up the MySQL user ID under
+database area must be created within MySQL, and the MySQL user ID under
-which Kea will access the database. This needs to be done manually;
+which Kea will access the database must be set up. This needs to be done manually,
-``kea-admin`` cannot do this for you.
+rather than via ``kea-admin``.
 
 To create the database:
 
@@ -192,7 +191,7 @@ To create the database:
 
       mysql> CREATE DATABASE database-name;
 
-   (database-name is the name you have chosen for the database.)
+   (database-name is the name chosen for the database.)
 
 3. Create the user under which Kea will access the database (and give it
    a password), then grant it access to the database tables:
@@ -202,12 +201,12 @@ To create the database:
       mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password';
       mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost';
 
-   (user-name and password are the user ID and password you are using to
+   (user-name and password are the user ID and password being used to
    allow Kea access to the MySQL instance. All apostrophes in the
    command lines above are required.)
 
-4. At this point, you may elect to create the database tables.
+4. At this point, administrators may elect to create the database tables.
-   (Alternatively, you can exit MySQL and create the tables using the
+   (Alternatively, the tables can be created by exiting MySQL and using the
    ``kea-admin`` tool, as explained below.) To do this:
 
    ::
@@ -215,7 +214,7 @@ To create the database:
       mysql> CONNECT database-name;
       mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql
 
-   (path-to-kea is the location where you installed Kea.)
+   (path-to-kea is the location where Kea is installed.)
 
 5. Exit MySQL:
 
@@ -225,17 +224,17 @@ To create the database:
       Bye
       $
 
-If you elected not to create the tables in Step 4, you can do so now by
+If the tables were not created in Step 4, run the ``kea-admin`` tool
-running the ``kea-admin`` tool:
+to create them now:
 
 ::
 
    $ kea-admin lease-init mysql -u database-user -p database-password -n database-name
 
-Do not do this if you did create the tables in Step 4. ``kea-admin``
+Do not do this if the tables were created in Step 4. ``kea-admin``
 implements rudimentary checks; it will refuse to initialize a database
-that contains any existing tables. If you want to start from scratch,
+that contains any existing tables. To start from scratch,
-you must remove all data manually. (This process is a manual operation
+all must be removed data manually. (This process is a manual operation
 on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.)
 
 .. _mysql-upgrade:
@@ -273,8 +272,8 @@ PostgreSQL
 ----------
 
 PostgreSQL is able to store leases, host reservations, and options
-defined on a per-host basis. This step can be safely ignored if you are
+defined on a per-host basis. This step can be safely ignored if
-using other database backends.
+other database backends will be used.
 
 .. _pgsql-database-create:
 
@@ -300,7 +299,7 @@ which the servers will access it. A number of steps are required:
       CREATE DATABASE
       postgres=#
 
-   (database-name is the name you have chosen for the database.)
+   (database-name is the name chosen for the database.)
 
 3. Create the user under which Kea will access the database (and give it
    a password), then grant it access to the database:
@@ -321,13 +320,13 @@ which the servers will access it. A number of steps are required:
       Bye
       $
 
-5. At this point you are ready to create the database tables. This can
+5. At this point, create the database tables either
-   be done using the ``kea-admin`` tool as explained in the next section
+   using the ``kea-admin`` tool, as explained in the next section
    (recommended), or manually. To create the tables manually, enter the
-   following command. Note that PostgreSQL will prompt you to enter the
+   following command. Note that PostgreSQL will prompt the administrator to enter the
-   new user's password you specified in Step 3. When the command
+   new user's password that was specified in Step 3. When the command
-   completes, you will be returned to the shell prompt. You should see
+   completes, Kea will return to the shell prompt. The
-   output similar to the following:
+   output should be similar to the following:
 
    ::
 
@@ -350,19 +349,19 @@ which the servers will access it. A number of steps are required:
       COMMIT
       $
 
-   (path-to-kea is the location where you installed Kea.)
+   (path-to-kea is the location where Kea is installed.)
 
-   If instead you encounter an error like:
+   If instead an error is encountered, such as:
 
    ::
 
       psql: FATAL:  no pg_hba.conf entry for host "[local]", user "user-name", database "database-name", SSL off
 
-   ... you will need to alter the PostgreSQL configuration. Kea uses
+   ... the PostgreSQL configuration will need to be altered. Kea uses
    password authentication when connecting to the database and must have
    the appropriate entries added to PostgreSQL's pg_hba.conf file. This
-   file is normally located in the primary data directory for your
+   file is normally located in the primary data directory for the
-   PostgreSQL server. The precise path may vary depending on your
+   PostgreSQL server. The precise path may vary depending on the
    operating system and version, but the default location for PostgreSQL
    9.3 on Centos 6.5 is: ``/var/lib/pgsql/9.3/data/pg_hba.conf``.
 
@@ -378,25 +377,25 @@ which the servers will access it. A number of steps are required:
 
    These edits are primarily intended as a starting point, and are not a
    definitive reference on PostgreSQL administration or database
-   security. Please consult your PostgreSQL user manual before making
+   security. Please consult the PostgreSQL user manual before making
-   these changes, as they may expose other databases that you run. It
+   these changes, as they may expose other databases that are running. It
    may be necessary to restart PostgreSQL in order for the changes to
    take effect.
 
 Initialize the PostgreSQL Database Using kea-admin
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you elected not to create the tables manually, you can do so now by
+If the tables were not created manually, do so now by
 running the ``kea-admin`` tool:
 
 ::
 
    $ kea-admin lease-init pgsql -u database-user -p database-password -n database-name
 
-Do not do this if you already created the tables manually. ``kea-admin``
+Do not do this if the tables were already created manually. ``kea-admin``
 implements rudimentary checks; it will refuse to initialize a database
-that contains any existing tables. If you want to start from scratch,
+that contains any existing tables. To start from scratch,
-you must remove all data manually. (This process is a manual operation
+all data must be removed manually. (This process is a manual operation
 on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.)
 
 .. _pgsql-upgrade:
@@ -431,18 +430,18 @@ development was contributed by Deutsche Telekom. The Cassandra backend
 is able to store leases, host reservations, and options defined on a
 per-host basis.
 
-Cassandra must be properly set up if you want Kea to store information
+Cassandra must be properly set up if Kea is to store information
-in it. This section can be safely ignored if you choose to store the
+in it. This section can be safely ignored if the
-data in other backends.
+data will be stored in other backends.
 
 .. _cql-database-create:
 
 First-Time Creation of the Cassandra Database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you are setting up the Cassandra database for the first time, you
+When setting up the Cassandra database for the first time,
-need to create the keyspace area within it. This needs to be done
+the keyspace area within it must be created. This needs to be done
-manually; ``kea-admin`` cannot do this for you.
+manually; it cannot be performed by ``kea-admin``.
 
 To create the database:
 
@@ -465,29 +464,29 @@ To create the database:
 
       cql> CREATE KEYSPACE keyspace-name WITH replication = {'class' : 'SimpleStrategy','replication_factor' : 1};
 
-   (keyspace-name is the name you have chosen for the keyspace)
+   (keyspace-name is the name chosen for the keyspace.)
 
-4. At this point, you may elect to create the database tables.
+4. At this point, the database tables can be created.
-   (Alternatively, you can exit Cassandra and create the tables using
+   (It is also possible to exit Cassandra and create the tables using
    the ``kea-admin`` tool, as explained below.) To do this:
 
    ::
 
       cqslh -k keyspace-name -f path-to-kea/share/kea/scripts/cql/dhcpdb_create.cql
 
-   (path-to-kea is the location where you installed Kea)
+   (path-to-kea is the location where Kea is installed.)
 
-If you elected not to create the tables in Step 4, you can do so now by
+If the tables were not created in Step 4, do so now by
 running the ``kea-admin`` tool:
 
 ::
 
    $ kea-admin lease-init cql -n database-name
 
-Do not do this if you did create the tables in Step 4. ``kea-admin``
+Do not do this if the tables were created in Step 4. ``kea-admin``
 implements rudimentary checks; it will refuse to initialize a database
-that contains any existing tables. If you want to start from scratch,
+that contains any existing tables. To start from scratch,
-you must remove all data manually. (This process is a manual operation
+all data must be removed manually. (This process is a manual operation
 on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.)
 
 .. _cql-upgrade:

doc/guide/agent.rst

@@ -6,8 +6,8 @@ The Kea Control Agent
 
 .. _agent-overview:
 
-Overview
+Overview of the Kea Control Agent
-========
+=================================
 
 The Kea Control Agent (CA) is a daemon which exposes a RESTful control
 interface for managing Kea servers. The daemon can receive control
@@ -132,7 +132,7 @@ configuration itself.
 
 Hooks libraries can be loaded by the Control Agent in the same way as
 they are loaded by the DHCPv4 and DHCPv6 servers. The CA currently
-supports one hook point - 'control_command_receive' - which makes it
+supports one hook point - "control_command_receive" - which makes it
 possible to delegate processing of some commands to the hooks library.
 The ``hooks-libraries`` list contains the list of hooks libraries that
 should be loaded by the CA, along with their configuration information
@@ -193,12 +193,12 @@ server enables authentication of the clients using certificates.
    #   openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \
    #           -CAkey ca.key -set_serial 01 -out kea-client.crt
    #
-   #   Note that the 'common name' value used when generating the client
+   #   Note that the "common name" value used when generating the client
    #   and the server certificates must differ from the value used
    #   for the CA certificate.
    #
    #   The client certificate must be deployed on the client system.
-   #   In order to test the proxy configuration with 'curl' run a
+   #   In order to test the proxy configuration with "curl", run a
    #   command similar to the following:
    #
    #   curl -k --key kea-client.key --cert kea-client.crt -X POST \

doc/guide/classify.rst

@@ -129,20 +129,20 @@ value is obtained is unspecified.
 .. _classification-using-vendor:
 
 Built-in Client Classes
-======================
+=======================
 
 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
-it does, the content of that option is prepended with "VENDOR_CLASS_"
+it does, the content of that option is prepended with "VENDOR_CLASS\_"
 and the result is interpreted as a class. For example, modern cable
 modems send this option with value "docsis3.0", so the packet belongs to
 class "VENDOR_CLASS_docsis3.0".
 
-The "HA_" prefix is used by the High Availability hooks library to
+The "HA\_" prefix is used by the High Availability hooks library to
 designate certain servers to process DHCP packets as a result of load
-balancing. The class name is constructed by prepending the "HA_" prefix
+balancing. The class name is constructed by prepending the "HA\_" prefix
 to the name of the server which should process the DHCP packet. This
 server uses an appropriate pool or subnet to allocate IP addresses
 (and/or prefixes), based on the assigned client classes. The details can
@@ -154,7 +154,7 @@ particular client. By convention, built-in classes' names begin with all
 capital letters.
 
 Currently recognized built-in class names are ALL, KNOWN and UNKNOWN, and the
-prefixes VENDOR_CLASS_, HA_, AFTER_, and EXTERNAL_. Although the AFTER\_
+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; built-in classes are implicitly defined so
 they never raise warnings if they do not appear in the configuration.
@@ -339,8 +339,8 @@ 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
-   built-in, 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",
+   to-come "after" hook) and "EXTERNAL\_" or equal to "ALL", "KNOWN",
    "UNKNOWN", etc.
 
    "known" and "unknown" are shorthand for "member('KNOWN')" and "not
@@ -523,7 +523,7 @@ digits separated by the separator, e.g ':', '-', '' (empty separator).
    the expressions are overly complex, the time taken to execute them
    may impact the performance of the server. Administrators who need complex or
    time-consuming expressions should consider writing a
-   `hook <#hooks-libraries>`__ to perform the necessary work.
+   :ref:`hook <hooks-libraries>` to perform the necessary work.
 
 .. _classification-configuring:
 
@@ -816,7 +816,7 @@ expression would be complex or time-consuming to write, and could be
 better or more easily written as code. Once the hook has added the proper class name
 to the packet, the rest of the classification system will work as expected
 in choosing a subnet and selecting options. For a description of hooks,
-see :ref:`hooks-libraries>`__; for information on configuring classes,
+see :ref:`hooks-libraries`; for information on configuring classes,
 see :ref:`classification-configuring` and :ref:`classification-subnets`.
 
 Debugging Expressions
@@ -833,7 +833,7 @@ The specific loggers are "kea-dhcp4.eval" and "kea-dhcp6.eval".
 To understand the logging statements, it is essential to understand a bit
 about how expressions are evaluated; for a more complete description,
 refer to the design document at
-https://gitlab.isc.org/isc-projects/kea/wikis/design%20documents. In
+https://gitlab.isc.org/isc-projects/kea/wikis/designs/Design-documents. In
 brief, there are two structures used during the evaluation of an
 expression: a list of tokens which represent the expressions, and a value
 stack which represents the values being manipulated.

doc/guide/config.rst

@@ -28,7 +28,7 @@ JSON Syntax
 -----------
 
 Configuration files for the DHCPv4, DHCPv6, DDNS, Control Agent, and
-Netconf modules are defined in an extended JSON format. Basic JSON is
+NETCONF modules are defined in an extended JSON format. Basic JSON is
 defined in `RFC 7159 <https://tools.ietf.org/html/rfc7159>`__ and `ECMA
 404 <https://www.ecma-international.org/publications/standards/Ecma-404.htm>`__.
 In particular, the only boolean values allowed are true or false (all

doc/guide/ctrl-channel.rst

@@ -12,28 +12,28 @@ traffic is not handled. Another risk is that if the new configuration is
 invalid for any reason, the server may refuse to start, which will
 further extend the downtime period until the issue is resolved.
 
-To avoid such problems, the DHCPv4, DHCPv6 and D2 servers in Kea include
+To avoid such problems, the DHCPv4, DHCPv6, and D2 servers in Kea include
 support for a mechanism that allows online reconfiguration without
 requiring server shutdown. Both servers can be instructed to open
 control sockets, which is a communications channel. The server is able
 to receive commands on that channel, act on them, and report back
 status.
 
-The DHCPv4, DHCPv6 and D2 servers receive commands over the UNIX domain
+The DHCPv4, DHCPv6, and D2 servers receive commands over the UNIX domain
-sockets. The details how to configure these sockets, see
+sockets. For details on how to configure these sockets, see
-`??? <#dhcp4-ctrl-channel>`__ and `??? <#dhcp6-ctrl-channel>`__. While
+:ref:`dhcp4-ctrl-channel` and :ref:`dhcp6-ctrl-channel`. While
-it is possible to control the servers directly using unix domain sockets
+it is possible to control the servers directly using UNIX domain sockets,
-it requires that the controlling client be running on the same machine
+that requires that the controlling client be running on the same machine
 as the server. SSH is usually used to connect remotely to the controlled
 machine.
 
 Network administrators usually prefer using some form of a RESTful API
 to control the servers, rather than using UNIX domain sockets directly.
-Therefore, Kea includes a component called Control Agent (or CA), which
+Therefore, Kea includes a component called the Control Agent (or CA), which
 exposes a RESTful API to the controlling clients and can forward
 commands to the respective Kea services over the UNIX domain sockets.
-The CA configuration has been described in
+The CA configuration is described in
-`??? <#agent-configuration>`__.
+:ref:`agent-configuration`.
 
 The HTTP requests received by the CA contain the control commands
 encapsulated within HTTP requests. Simply speaking, the CA is
@@ -48,7 +48,7 @@ will assume that the control command is targeted at the CA itself and
 will try to handle it on its own.
 
 Control connections over both HTTP and UNIX domain sockets are guarded
-with timeouts. The default timeout value is set to 10s and is not
+with timeouts. The default timeout value is set to 10 seconds and is not
 configurable.
 
 .. _ctrl-channel-syntax:
@@ -92,8 +92,8 @@ following structure:
        }
 
 ``command`` is the name of the command to execute and is mandatory.
-``arguments`` is a map of parameters required to carry out the given
+``arguments`` is a map of the parameters required to carry out the given
-command. The exact content and format of the map is command-specific.
+command. The exact content and format of the map are command-specific.
 
 ``service`` is a list of the servers at which the control command is
 targeted. In the example above, the control command is targeted at the
@@ -118,7 +118,7 @@ If the command received by the CA does not include a ``service``
 parameter or this list is empty, the CA simply processes this message on
 its own. For example, a ``config-get`` command which includes no service
 parameter returns the Control Agent's own configuration. The
-``config-get`` with a service value "dhcp4" is forwarded to the DHCPv4
+``config-get`` command with a service value "dhcp4" is forwarded to the DHCPv4
 server and returns the DHCPv4 server's configuration.
 
 The following list shows the mapping of the values carried within the
@@ -167,7 +167,7 @@ that depends on the specific command.
 
    **Note**
 
-   When sending commands via Control Agent, it is possible to specify
+   When sending commands via the Control Agent, it is possible to specify
    multiple services at which the command is targeted. CA forwards this
    command to each service individually. Thus, the CA response to the
    controlling client contains an array of individual responses.
@@ -180,7 +180,7 @@ Using the Control Channel
 The easiest way to start interacting with the control API is to use
 common UNIX/Linux tools such as ``socat`` and ``curl``.
 
-In order to control the given Kea service via UNIX domain socket, use
+In order to control the given Kea service via a UNIX domain socket, use
 ``socat`` in interactive mode as follows:
 
 ::
@@ -188,7 +188,7 @@ In order to control the given Kea service via UNIX domain socket, use
    $ socat UNIX:/path/to/the/kea/socket -
 
 or in batch mode, include the "ignoreeof" option as shown below to
-ensure socat waits long enough for the server to respond:
+ensure ``socat`` waits long enough for the server to respond:
 
 ::
 
@@ -202,10 +202,11 @@ the specific server directly and bypasses the Control Agent.
 
 It is also easy to open a UNIX socket programmatically. An example of a
 simple client written in C is available in the Kea Developer's Guide, in
-the Control Channel Overview chapter, in the Using Control Channel
+the Control Channel Overview chapter, in the
+`Using Control Channel <https://jenkins.isc.org/job/Kea_doc/doxygen/d2/d96/ctrlSocket.html#ctrlSocketClient>`__
 section.
 
-To use Kea's RESTful API with ``curl``, you may use the following:
+To use Kea's RESTful API with ``curl``, use the following:
 
 ::
 
@@ -221,10 +222,10 @@ Commands Supported by Both the DHCPv4 and DHCPv6 Servers
 
 .. _command-build-report:
 
-build-report
+The build-report Command
-------------
+------------------------
 
-The *build-report* command returns on the control channel what the
+The ``build-report`` command returns on the control channel what the
 command line ``-W`` argument displays, i.e. the embedded content of the
 ``config.report`` file. This command does not take any parameters.
 
@@ -236,14 +237,14 @@ command line ``-W`` argument displays, i.e. the embedded content of the
 
 .. _command-config-get:
 
-config-get
+The config-get Command
-----------
+----------------------
 
-The *config-get* command retrieves the current configuration used by the
+The ``config-get`` command retrieves the current configuration used by the
 server. This command does not take any parameters. The configuration
 returned is roughly equal to the configuration that was loaded using the
--c command line option during server start-up or later set using
+-c command line option during server start-up or later set using the
-config-set command. However, there may be certain differences, as
+``config-set`` command. However, there may be certain differences, as
 comments are not retained. If the original configuration used file
 inclusion, the returned configuration will include all parameters from
 all the included files.
@@ -263,23 +264,23 @@ An example command invocation looks like this:
 
 .. _command-config-reload:
 
-config-reload
+The config-reload Command
--------------
+-------------------------
 
-The *config-reload* command instructs Kea to load again the
+The ``config-reload`` command instructs Kea to load again the
 configuration file that was used previously. This operation is useful if
 the configuration file has been changed by some external source; for
 example, a sysadmin can tweak the configuration file and use this
 command to force Kea pick up the changes.
 
-Caution should be taken when mixing this with config-set commands. Kea
+Caution should be taken when mixing this with ``config-set`` commands. Kea
 remembers the location of the configuration file it was started with,
-and this configuration can be significantly changed using config-set
+and this configuration can be significantly changed using the ``config-set``
-command. When config-reload is issued after config-set, Kea will attempt
+command. When ``config-reload`` is issued after ``config-set``, Kea will attempt
 to reload its original configuration from the file, possibly losing all
-changes introduced using config-set or other commands.
+changes introduced using ``config-set`` or other commands.
 
-*config-reload* does not take any parameters. An example command
+``config-reload`` does not take any parameters. An example command
 invocation looks like this:
 
 ::
@@ -290,14 +291,14 @@ invocation looks like this:
 
 .. _command-config-test:
 
-config-test
+The config-test Command
------------
+-----------------------
 
-The *config-test* command instructs the server to check whether the new
+The ``config-test`` command instructs the server to check whether the new
 configuration supplied in the command's arguments can be loaded. The
 supplied configuration is expected to be the full configuration for the
 target server, along with an optional Logger configuration. As for the
-``-t`` command, some sanity checks are not performed so it is possible a
+``-t`` command, some sanity checks are not performed, so it is possible a
 configuration which successfully passes this command will still fail in
 the ``config-set`` command or at launch time. The structure of the
 command is as follows:
@@ -340,12 +341,12 @@ outcome:
 
 .. _command-config-write:
 
-config-write
+The config-write Command
-------------
+------------------------
 
-The *config-write* command instructs the Kea server to write its current
+The ``config-write`` command instructs the Kea server to write its current
-configuration to a file on disk. It takes one optional argument called
+configuration to a file on disk. It takes one optional argument, called
-*filename* that specifies the name of the file to write the
+"filename", that specifies the name of the file to write the
 configuration to. If not specified, the name used when starting Kea
 (passed as a -c argument) will be used. If a relative path is specified,
 Kea will write its files only in the directory it is running.
@@ -363,10 +364,10 @@ An example command invocation looks like this:
 
 .. _command-leases-reclaim:
 
-leases-reclaim
+The leases-reclaim Command
---------------
+--------------------------
 
-The *leases-reclaim* command instructs the server to reclaim all expired
+The ``leases-reclaim`` command instructs the server to reclaim all expired
 leases immediately. The command has the following JSON syntax:
 
 ::
@@ -378,23 +379,23 @@ leases immediately. The command has the following JSON syntax:
        }
    }
 
-The *remove* boolean parameter is mandatory and indicates whether the
+The ``remove`` boolean parameter is mandatory and indicates whether the
 reclaimed leases should be removed from the lease database (if true), or
-left in the *expired-reclaimed* state (if false). The latter facilitates
+left in the "expired-reclaimed" state (if false). The latter facilitates
 lease affinity, i.e. the ability to re-assign an expired lease to the
-same client which used this lease before. See `??? <#lease-affinity>`__
+same client that used this lease before. See :ref:`lease-affinity`
-for the details. Also, see `??? <#lease-reclamation>`__ for general
+for the details. Also, see :ref:`lease-reclamation` for general
-information about the processing of expired leases (leases reclamation).
+information about the processing of expired leases (lease reclamation).
 
 .. _command-libreload:
 
-libreload
+The libreload Command
----------
+---------------------
 
-The *libreload* command first unloads and then loads all currently
+The ``libreload`` command first unloads and then loads all currently
-loaded hook libraries. This is primarily intended to allow one or more
+loaded hooks libraries. This is primarily intended to allow one or more
-hook libraries to be replaced with newer versions without requiring Kea
+hooks libraries to be replaced with newer versions without requiring Kea
-servers to be reconfigured or restarted. Note that the hook libraries
+servers to be reconfigured or restarted. Note that the hooks libraries
 are passed the same parameter values (if any) that were passed when they
 originally loaded.
 
@@ -410,10 +411,10 @@ or 1, indicating failure.
 
 .. _command-list-commands:
 
-list-commands
+The list-commands Command
--------------
+-------------------------
 
-The *list-commands* command retrieves a list of all commands supported
+The ``list-commands`` command retrieves a list of all commands supported
 by the server. It does not take any arguments. An example command may
 look like this:
 
@@ -430,10 +431,10 @@ command.
 
 .. _command-config-set:
 
-config-set
+The config-set Command
-----------
+----------------------
 
-The *config-set* command instructs the server to replace its current
+The ``config-set`` command instructs the server to replace its current
 configuration with the new configuration supplied in the command's
 arguments. The supplied configuration is expected to be the full
 configuration for the target server, along with an optional Logger
@@ -483,10 +484,10 @@ string, "text", describing the outcome:
 
 .. _command-shutdown:
 
-shutdown
+The shutdown Command
---------
+--------------------
 
-The *shutdown* command instructs the server to initiate its shutdown
+The ``shutdown`` command instructs the server to initiate its shutdown
 procedure. It is the equivalent of sending a SIGTERM signal to the
 process. This command does not take any arguments. An example command
 may look like this:
@@ -502,18 +503,18 @@ been initiated.
 
 .. _command-dhcp-disable:
 
-dhcp-disable
+The dhcp-disable Command
-------------
+------------------------
 
-The *dhcp-disable* command globally disables the DHCP service. The
+The ``dhcp-disable`` command globally disables the DHCP service. The
 server continues to operate, but it drops all received DHCP messages.
 This command is useful when the server's maintenance requires that the
 server temporarily stop allocating new leases and renew existing leases.
 It is also useful in failover-like configurations during a
 synchronization of the lease databases at startup, or recovery after a
-failure. The optional parameter *max-period* specifies the time in
+failure. The optional parameter "max-period" specifies the time in
 seconds after which the DHCP service should be automatically re-enabled,
-if the *dhcp-enable* command is not sent before this time elapses.
+if the ``dhcp-enable`` command is not sent before this time elapses.
 
 ::
 
@@ -526,10 +527,10 @@ if the *dhcp-enable* command is not sent before this time elapses.
 
 .. _command-dhcp-enable:
 
-dhcp-enable
+The dhcp-enable Command
------------
+-----------------------
 
-The *dhcp-enable* command globally enables the DHCP service.
+The ``dhcp-enable`` command globally enables the DHCP service.
 
 ::
 
@@ -539,10 +540,10 @@ The *dhcp-enable* command globally enables the DHCP service.
 
 .. _command-version-get:
 
-version-get
+The version-get Command
------------
+-----------------------
 
-The *version-get* command returns extended information about the Kea
+The ``version-get`` command returns extended information about the Kea
 version. It is the same information available via the ``-V``
 command-line argument. This command does not take any parameters.
 
@@ -552,8 +553,8 @@ command-line argument. This command does not take any parameters.
        "command": "version-get"
    }
 
-Commands Supported by D2 Server
+Commands Supported by the D2 Server
-===============================
+===================================
 
 The D2 server supports only a subset of DHCPv4 / DHCPv6 server commands:
 
@@ -577,11 +578,10 @@ The D2 server supports only a subset of DHCPv4 / DHCPv6 server commands:
 
 .. _agent-commands:
 
-Commands Supported by Control Agent
+Commands Supported by the Control Agent
-===================================
+=======================================
 
-The following commands listed in `Commands Supported by Both the DHCPv4
+The following commands listed in :ref:`commands-common` are also supported by the
-and DHCPv6 Servers <#commands-common>`__ are also supported by the
 Control Agent, i.e. when the ``service`` parameter is blank, the
 commands are handled by the CA and they relate to the CA process itself:
 

doc/guide/dhcp4-srv.rst

@@ -717,8 +717,8 @@ For additional Cassandra-specific parameters, see
 
 .. _read-only-database-configuration4:
 
-Using Read-Only Databases for Host Reservations
+Using Read-Only Databases for Host Reservations with DHCPv4
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In some deployments the database user whose name is specified in the
 database backend configuration may not have write privileges to the
@@ -2062,7 +2062,7 @@ The definition used to decode a VSI option is:
 
 2. If none, the global definition;
 
-3. If none, the last-resort definition described in the next section
+3. If none, the last-resort definition described in the next section,
    :ref:`dhcp4-vendor-opts` (backward-compatible with previous Kea versions).
 
 ..

doc/guide/dhcp6-srv.rst

@@ -663,8 +663,8 @@ For additional Cassandra-specific parameters, see
 
 .. _read-only-database-configuration6:
 
-Using Read-Only Databases for Host Reservations
+Using Read-Only Databases for Host Reservations with DHCPv6
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In some deployments the database user whose name is specified in the
 database backend configuration may not have write privileges to the
@@ -2378,7 +2378,7 @@ servers set to 2001:db8:0::1 and 2001:db8:2::1.
    }
 
 This example shows a configuration using an automatically generated
-"VENDOR_CLASS_" class. The administrator of the network has decided that
+"VENDOR_CLASS\_" class. The administrator of the network has decided that
 addresses in the range 2001:db8:1::1 to 2001:db8:1::ffff are to be
 managed by the DHCP6 server and that only clients belonging to the
 eRouter1.0 client class are allowed to use that pool.

doc/guide/hammer.rst

@@ -52,7 +52,7 @@ or in VirtualBox. To list of supported systems, use the
    freebsd:
      - 11.2: virtualbox
      - 12.0: virtualbox
-       
+
 
 It is also possible to run the build locally, in the current system (if the OS
 is supported).
@@ -108,7 +108,7 @@ using SSH, invoke:
    ./hammer.py ssh -p virtualbox -s freebsd -r 12.0
 
 It is possible to speed up subsequent Hammer builds. To achieve this
-Hammer employs :ref:`ccache <https://ccache.samba.org/>`. During
+Hammer employs `ccache <https://ccache.samba.org/>`__. During
 compilation, ccache stores objects in a shared folder. In subsequent runs,
 instead of doing an actual compilation, ccache returns the stored earlier
 objects. The cache with these objects for reuse needs to be stored outside of VM
@@ -119,7 +119,7 @@ operating system.
 ::
 
          ./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache
-       
+
 
 ..
 

doc/guide/hooks-ha.rst

@@ -957,7 +957,7 @@ the Kea source at: ``src/lib/config/timeouts.h``.
 Pausing 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

doc/guide/hooks-host-cache.rst

@@ -4,8 +4,8 @@ host_cache: Caching Host Reservations
 =====================================
 
 Some database backends, such as RADIUS, are considered slow and may take
-a long time to respond. Since Kea in general is synchronous, the backend
+a long time to respond. Since Kea in general is synchronous, backend
-performance directly affects the DHCP performance. To minimize the
+performance directly affects DHCP performance. To minimize the
 impact and improve performance, the Host Cache library provides a way to
 cache information from the database locally. This includes negative
 caching, i.e. the ability to remember that there is no client
@@ -13,19 +13,19 @@ information in the database.
 
    **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.
 
-In principle, this hook library can be used with any backend that may
+In principle, this hooks library can be used with any backend that may
-introduce performance degradation (MySQL, PostgreSQL, Cassandra,
+introduce performance degradation (MySQL, PostgreSQL, Cassandra, or
 RADIUS). Host Cache must be loaded for the RADIUS accounting mechanism
 to work.
 
-The Host Cache hook library is currently very simple. It takes only one
+The Host Cache hooks library is currently very simple. It takes only one
-optional parameter ("maximum") that defines the maximum number of hosts
+optional parameter ("maximum"), which defines the maximum number of hosts
 to be cached. If not specified, the default value of 0 is used, which
-means there is no limit. The hook library can be loaded the same way as
+means there is no limit. This hooks library can be loaded the same way as
-any other hook library; for example, this configuration could be used:
+any other hooks library; for example, this configuration could be used:
 
 ::
 
@@ -46,15 +46,15 @@ any other hook library; for example, this configuration could be used:
 
 Once loaded, the Host Cache hook library provides a number of new
 commands which can be used either over the control channel (see
-`??? <#ctrl-channel-client>`__) or the REST API (see
+:ref:`ctrl-channel-client`) or the RESTful API (see
-`??? <#agent-overview>`__). An example REST API client is described in
+:ref:`agent-overview`). An example RESTful API client is described in
-`??? <#shell-overview>`__. The following sections describe the commands
+:ref:`shell-overview`. The following sections describe the commands
 available.
 
 .. _command-cache-flush:
 
-cache-flush Command
+The cache-flush Command
--------------------
+-----------------------
 
 This command allows removal of a specified number of cached host
 entries. It takes one parameter, which defines the number of hosts to be
@@ -67,14 +67,14 @@ removed. An example usage looks as follows:
        "arguments": 1000
    }
 
-This command will remove 1000 hosts. If you want to delete all cached
+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.
 
 .. _command-cache-clear:
 
-cache-clear Command
+The cache-clear Command
--------------------
+-----------------------
 
 This command allows removal of all cached host entries. An example usage
 looks as follows:
@@ -85,13 +85,13 @@ looks as follows:
        "command": "cache-clear"
    }
 
-This command will remove all hosts. If you want to delete only a certain
+This command will remove all hosts. To delete only a certain
 number of cached hosts, please use cache-flush instead.
 
 .. _command-cache-size:
 
-cache-size Command
+The cache-size Command
-------------------
+----------------------
 
 This command returns the number of host entries. An example usage looks
 as follows:
@@ -104,8 +104,8 @@ as follows:
 
 .. _command-cache-write:
 
-cache-write Command
+The cache-write Command
--------------------
+-----------------------
 
 In general, the cache content is considered a runtime state and the
 server can be shut down or restarted as usual; the cache will then be
@@ -114,8 +114,8 @@ useful to store the contents of the cache. One such case is RADIUS,
 where the cached hosts also retain additional cached RADIUS attributes;
 there is no easy way to obtain this information again, because renewing
 clients send their packet to the DHCP server directly. Another use case
-is when you want to restart the server and for performance reasons you
+is when an administrator wants to restart the server and, for performance reasons,
-want it to start with a hot (populated) cache.
+wants it to start with a hot (populated) cache.
 
 This command allows writing the contents of the in-memory cache to a
 file on disk. It takes one parameter, which defines the filename. An
@@ -134,8 +134,8 @@ processed by any other tool that is able to understand JSON format.
 
 .. _command-cache-load:
 
-cache-load Command
+The cache-load Command
-------------------
+----------------------
 
 See the previous section for a discussion of use cases where it may be
 useful to write and load contents of the host cache to disk.
@@ -157,8 +157,8 @@ processed by any other tool that is able to understand JSON format.
 
 .. _command-cache-get:
 
-cache-get Command
+The cache-get Command
------------------
+---------------------
 
 This command is similar to cache-write, but instead of writing the cache
 contents to disk, it returns the contents to whoever sent the command.
@@ -178,8 +178,8 @@ may be large.
 
 .. _command-cache-get-by-id:
 
-cache-get-by-id Command
+The cache-get-by-id Command
------------------------
+---------------------------
 
 This command is similar to cache-get, but instead of returning the whole
 content it returns only the entries matching the given identifier.
@@ -201,14 +201,14 @@ address.
 
 .. _command-cache-insert:
 
-cache-insert Command
+The cache-insert Command
---------------------
+------------------------
 
 This command may be used to manually insert a host into the cache; there
-are very few use cases when this command could be useful. This command
+are very few use cases when this command might be useful. This command
 expects its arguments to follow the usual syntax for specifying host
-reservations (see `??? <#host-reservation-v4>`__ or
+reservations (see :ref:`host-reservation-v4` or
-`??? <#host-reservation-v6>`__), with one difference: the subnet-id
+:ref:`host-reservation-v6`), with one difference: the subnet-id
 value must be specified explicitly.
 
 An example command that will insert an IPv4 host into the host cache
@@ -262,15 +262,15 @@ looks as follows:
 
 .. _command-cache-remove:
 
-cache-remove Command
+The cache-remove Command
---------------------
+------------------------
 
 Sometimes it is useful to remove a single entry from the host cache. A
 good use case is a situation where the device is up, Kea has already
 provided configuration, and the host entry is in cache. As a result of
-administrative action (e.g. customer hasn't paid their bills or has
+administrative action (e.g. the customer hasn't paid their bills or has
 perhaps been upgraded to better service), the information in the backend
-(e.g. MySQL or RADIUS) is being updated. However, since cache is in use,
+(e.g. MySQL or RADIUS) is being updated. However, since the cache is in use,
 Kea does not notice the change as the cached values are used. The
 cache-remove command can solve this problem by removing a cached entry
 after administrative changes.

doc/guide/hooks-radius.rst

@@ -20,7 +20,7 @@ intends to fulfill.
    This library may only be loaded by the ``kea-dhcp4`` or the
    ``kea-dhcp6`` process.
 
-The major feature of the hook library is the ability to use RADIUS
+The major feature of this hooks library is the ability to use RADIUS
 authorization. When a DHCP packet is received, the Kea server sends an
 Access-Request to the RADIUS server and waits for a response. The server
 then sends back either an Access-Accept with specific client attributes,
@@ -32,10 +32,10 @@ effectively means RADIUS can act as an address-reservation database.
 
 The second case supported is the ability to assign clients to specific
 pools based on a RADIUS response. In this case, the RADIUS server sends
-back an Access-Accept with Framed-Pool (IPv4) or Framed-IPv6-Pool
+back an Access-Accept with a Framed-Pool (IPv4) or Framed-IPv6-Pool
 (IPv6). In both cases, Kea interprets those attributes as client
 classes. With the addition of the ability to limit access to pools to
-specific classes (see `??? <#classification-pools>`__), RADIUS can be
+specific classes (see :ref:`classification-pools`), RADIUS can be
 used to force the client to be assigned a dynamic address from a
 specific pool. Furthermore, the same mechanism can be used to control
 what kind of options the client will get if there are DHCP options
@@ -51,7 +51,7 @@ on CentOS 7.0. Other systems may differ slightly.
 
 STEP 1: Install dependencies
 
-Several tools are needed to build dependencies and Kea itself. The
+Several tools are needed to build the dependencies and Kea itself. The
 following commands should install them:
 
 ::
@@ -59,11 +59,11 @@ following commands should install them:
    $ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
    $ sudo yum install gcc-g++ openssl-devel log4cplus-devel wget git
 
-STEP 2: FreeRADIUS installation
+STEP 2: Install FreeRADIUS
 
-The Kea RADIUS hook library uses the FreeRADIUS client library to
+The Kea RADIUS hooks library uses the FreeRADIUS client library to
 conduct RADIUS communication. Unfortunately, the standard 1.1.7 release
-available from the project website http://freeradius.org/sub_projects/
+available from the project website https://freeradius.org/sub_projects/
 has several serious deficiencies; ISC engineers observed a segmentation
 fault during testing. Also, the base version of the library does not
 offer asynchronous transmissions, which are essential for effective
@@ -83,11 +83,11 @@ version, please use the following steps:
    $ make
    $ sudo make install
 
-You may pass additional parameters to the configure script, if you need
+Additional parameters may be passed to the configure script, if needed.
-to. Once installed, the FreeRADIUS client will be installed in
+Once installed, the FreeRADIUS client will be installed in
 /usr/local. This is the default path where Kea will be looking for it.
-You may install it in a different directory; if you choose to do so,
+It can be installed in a different directory; if so,
-make sure you add that path to the configure script when compiling Kea.
+make sure to add that path to the configure script when compiling Kea.
 
 STEP 3: Install recent BOOST version
 
@@ -159,10 +159,10 @@ Once this is done, verify that the Kea sources look similar to this:
    drwxr-xr-x  10 thomson  staff     340 Apr 26 19:04 src
    drwxr-xr-x  14 thomson  staff     476 Apr 26 19:04 tools
 
-The makefiles must be regenerated using autoreconf.
+The makefiles must be regenerated using ``autoreconf``.
 
 The next step is to configure Kea, and there are several essential steps
-necessary here. Running autoreconf -if is necessary to compile the
+necessary here. Running ``autoreconf -if`` is necessary to compile the
 premium package that contains RADIUS. Also, the --with-freeradius option
 is necessary to tell Kea where the FreeRADIUS client sources can be
 found. Also, since the non-standard Boost is used, the path to it must
@@ -268,7 +268,7 @@ the following:
      Kea-shell:              no
      Perfdhcp:               no
 
-Please make sure that your compilation has the following:
+Please make sure that the compilation includes the following:
 
 -  RADIUS listed in Included Hooks;
 -  FreeRADIUS client directories printed and pointing to the right
@@ -276,9 +276,9 @@ Please make sure that your compilation has the following:
 -  Boost version at least 1.65.1. The versions available in CentOS 7
    (1.48 and and 1.53) are too old.
 
-Once your configuration is complete, compile Kea using make. If your
+Once the configuration is complete, compile Kea using make. If the
-system has more than one core, it is recommended that you use the "-j N"
+system has more than one core, using the "-j N"
-option to speed up the build.
+option is recommended to speed up the build.
 
 ::
 
@@ -291,7 +291,7 @@ RADIUS Hook Configuration
 -------------------------
 
 The RADIUS hook is a library that has to be loaded by either DHCPv4 or
-DHCPv6 Kea servers. Unlike some other available hook libraries, this one
+DHCPv6 Kea servers. Unlike some other available hooks libraries, this one
 takes many parameters. For example, this configuration could be used:
 
 ::
@@ -320,28 +320,28 @@ takes many parameters. For example, this configuration could be used:
          }
      } ]
 
-RADIUS is a complicated environment. As such, it's not really possible
+RADIUS is a complicated environment. As such, it is not feasible
-to provide a default configuration that would work out of the box.
+to provide a default configuration that works for everyone.
 However, we do have one example that showcases some of the more common
-features. Please see doc/examples/kea4/hooks-radius.json in your Kea
+features. Please see doc/examples/kea4/hooks-radius.json in the Kea
 sources.
 
 The RADIUS hook library supports the following global configuration
 flags, which correspond to FreeRADIUS client library options:
 
--  ``bindaddr`` (default "*") specifies the address to be used by the
+-  ``bindaddr`` (default "*") - specifies the address to be used by the
-   hook library in communication with RADIUS servers. The "*" special
+   hooks library in communication with RADIUS servers. The "*" special
    value tells the kernel to choose the address.
 
--  ``canonical-mac-address`` (default false) specifies whether MAC
+-  ``canonical-mac-address`` (default false) - specifies whether MAC
    addresses in attributes follow the canonical RADIUS format (lowercase
    pairs of hexadecimal digits separated by '-').
 
--  ``client-id-pop0`` (default false), used with flex-id, removes the
+-  ``client-id-pop0`` (default false) - used with flex-id, removes the
    leading zero (or pair of zeroes in DHCPv6) type in client-id (aka
    duid in DHCPv6). Implied by client-id-printable.
 
--  ``client-id-printable`` (default false) checks whether the
+-  ``client-id-printable`` (default false) - checks whether the
    client-id/duid content is printable and uses it as is instead of in
    hexadecimal. Implies client-id-pop0 and extract-duid as 0 and 255 are
    not printable.
@@ -353,42 +353,42 @@ flags, which correspond to FreeRADIUS client library options:
    use locks or atomics, it is recommended that you do not use this
    feature when running in this mode.
 
--  ``dictionary`` (default set by configure at build time) is the
+-  ``dictionary`` (default set by configure at build time) - is the
    attribute and value dictionary. Note that it is a critical parameter.
 
--  ``extract-duid`` (default true) extracts the embedded duid from an
+-  ``extract-duid`` (default true) - extracts the embedded duid from an
    RFC 4361-compliant DHCPv4 client-id. Implied by client-id-printable.
 
--  ``identifier-type4`` (default client-id) specifies the identifier
+-  ``identifier-type4`` (default client-id) - specifies the identifier
    type to build the User-Name attribute. It should be the same as the
    host identifier, and when the flex-id hook library is used the
    replace-client-id must be set to true; client-id will be used with
    client-id-pop0.
 
--  ``identifier-type6`` (default duid) specifies the identifier type to
+-  ``identifier-type6`` (default duid) - specifies the identifier type to
    build the User-Name attribute. It should be the same as the host
    identifier, and when the flex-id hook library is used the
    replace-client-id must be set to true; duid will be used with
    client-id-pop0.
 
--  ``realm`` (default "") is the default realm.
+-  ``realm`` (default "") - is the default realm.
 
--  ``reselect-subnet-address`` (default false) uses the Kea reserved
+-  ``reselect-subnet-address`` (default false) - uses the Kea reserved
    address/RADIUS Framed-IP-Address or Framed-IPv6-Address to reselect
    subnets where the address is not in the subnet range.
 
--  ``reselect-subnet-pool`` (default false) uses the Kea
+-  ``reselect-subnet-pool`` (default false) - uses the Kea
    client-class/RADIUS Frame-Pool to reselect subnets where no available
    pool can be found.
 
--  ``retries`` (default 3) is the number of retries before trying the
+-  ``retries`` (default 3) - is the number of retries before trying the
    next server. Note that it is not supported for asynchronous
    communication.
 
--  ``session-history`` (default "") is the name of the file providing
+-  ``session-history`` (default "") - is the name of the file providing
    persistent storage for accounting session history.
 
--  ``timeout`` (default 10) is the number of seconds during which a
+-  ``timeout`` (default 10) - is the number of seconds during which a
    response is awaited.
 
 When ``reselect-subnet-pool`` or ``reselect-subnet-address`` is set to
@@ -398,54 +398,54 @@ does not match, another subnet is selected among matching subnets.
 
 Two services are supported:
 
--  ``access`` - the authentication service
+-  ``access`` - the authentication service.
 
--  ``accounting`` - the accounting service
+-  ``accounting`` - the accounting service.
 
 Configuration of services is divided into two parts:
 
--  servers that define RADIUS servers the library is expected to
+-  Servers that define RADIUS servers that the library is expected to
    contact. Each server may have the following items specified:
 
-   -  ``name``, which specifies the IP address of the server (it is
+   -  ``name`` - specifies the IP address of the server (it is
       possible to use a name which will be resolved, but it is not
       recommended).
 
-   -  ``port`` (default RADIUS authentication or accounting service),
+   -  ``port`` (default RADIUS authentication or accounting service) -
-      which specifies the UDP port of the server. Note that the
+      specifies the UDP port of the server. Note that the
       FreeRADIUS client library by default uses ports 1812
       (authorization) and 1813 (accounting). Some server implementations
-      use 1645 (authorization) and 1646 (accounting). You may use the
+      use 1645 (authorization) and 1646 (accounting). The
-      "port" parameter to adjust as needed.
+      "port" parameter may be used to adjust as needed.
 
-   -  ``secret``, which authenticates messages.
+   -  ``secret`` - authenticates messages.
 
    There may be up to eight servers. Note that when no server is
    specified, the service is disabled.
 
--  attributes which define additional information that the Kea server
+-  Attributes which define additional information that the Kea server
    will send to a RADIUS server. The parameter must be identified either
    by a name or type. Its value can be specified in one of three
    possible ways: data (which defines a plain text value), raw (which
    defines the value in hex), or expr (which defines an expression,
    which will be evaluated for each incoming packet independently).
 
-   -  ``name`` of the attribute.
+   -  ``name`` - the name of the attribute.
 
-   -  ``type`` of the attribute. Either the type or the name must be
+   -  ``type`` - the type of the attribute. Either the type or the name must be
       provided, and the attribute must be defined in the dictionary.
 
-   -  ``data`` is the first of three ways to specify the attribute
+   -  ``data`` - the first of three ways to specify the attribute
       content. The data entry is parsed by the FreeRADIUS library, so
       values defined in the dictionary of the attribute may be used.
 
-   -  ``raw`` is the second of three ways to specify the attribute
+   -  ``raw`` - the second of three ways to specify the attribute
       content; it specifies the content in hexadecimal. Note that it
       does not work with integer-content attributes (date, integer, and
       IPv4 address); a string-content attribute (string, IPv6 address,
       and IPv6 prefix) is required.
 
-   -  ``expr`` is the last way to specify the attribute content. It
+   -  ``expr`` - the last way to specify the attribute content. It
       specifies an evaluation expression which must return a not-empty
       string when evaluated with the DHCP query packet. Currently this
       is restricted to the access service.
@@ -485,7 +485,7 @@ following snippet could be used:
                "data": "mysecretpassword"
            },
            {
-               // It's also possible to specify an attribute using its type,
+               // It is also possible to specify an attribute using its type,
                // rather than a name. 77 is Connect-Info. The value is specified
                // using hex. Again, this is a static value. It will be sent the
                // same for every packet and to every server.
@@ -519,8 +519,8 @@ following snippet could be used:
 
    }
 
-For the RADIUS hook library to operate properly in DHCPv4, it is
+For the RADIUS hooks library to operate properly in DHCPv4,
-necessary to also load the Host Cache hook library. The reason for this
+the Host Cache hooks library must also be loaded. The reason for this
 is somewhat complex. In a typical deployment, the DHCP clients send
 their packets via DHCP relay which inserts certain Relay Agent
 Information options, such as circuit-id or remote-id. The values of
@@ -528,16 +528,16 @@ those options are then used by the Kea DHCP server to formulate the
 necessary attributes in the Access-Request message sent to the RADIUS
 server. However, once the DHCP client gets its address, it then renews
 by sending packets directly to the DHCP server. As a result, the relays
-are not able to insert their RAI options and the DHCP server can't send
+are not able to insert their RAI options, and the DHCP server cannot send
 the Access-Request queries to the RADIUS server by using just the
 information from incoming packets. Kea needs to keep the information
 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 `??? <#user-context>`__ for details about user
+reservations. (See :ref:`user-context` for details about user
 context). 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 you do not want RADIUS communication for messages
+is mandatory, unless administrators do not want RADIUS communication for messages
 other than Discover and the first Request from each client.

doc/guide/hooks-stat-cmds.rst

@@ -19,68 +19,68 @@ for retrieving these statistics.
 
    **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 commands currently provided by this library are:
 
--  ``stat-lease4-get`` - fetches DHCPv4 lease statistics
+-  ``stat-lease4-get`` - fetches DHCPv4 lease statistics.
 
--  ``stat-lease6-get`` - fetches DHCPv6 lease statistics
+-  ``stat-lease6-get`` - fetches DHCPv6 lease statistics.
 
-The Stat commands library is part of the open source code and is
+The stat 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 directly to the servers
-via either the control channel (see `??? <#ctrl-channel>`__) or the
+via either the control channel (see :ref:`ctrl-channel`) or the
-Control Agent (see `??? <#kea-ctrl-agent>`__).
+Control Agent (see :ref:`kea-ctrl-agent`).
 
-This library may be loaded by both kea-dhcp4 and kea-dhcp6 servers. It
+This library may be loaded by both the kea-dhcp4 and kea-dhcp6 servers. It
 is loaded in the same way as other libraries and currently has no
 parameters:
 
 ::
 
-   "Dhcp6": { 
+   "Dhcp6": {
        "hooks-libraries": [
            {
                "library": "/path/libdhcp_stat_cmds.so"
            }
            ...
-       ] 
+       ]
    }
 
 In a deployment with multiple Kea DHCP servers sharing a common lease
-storage, it may be loaded by any or all of the servers. However, one
+storage, this hooks library may be loaded by any or all of the servers. However, one
 thing to keep in mind is that a server's response to a
-stat-lease{4/6}-get command will only contain data for subnets known to
+stat-lease[46]-get command will only contain data for subnets known to
 that server. In other words, if a subnet does not appear in a server's
 configuration, Kea will not retrieve statistics for it.
 
 .. _command-stat-lease4-get:
 
-stat-lease4-get, stat-lease6-get Commands
+The stat-lease4-get, stat-lease6-get Commands
------------------------------------------
+---------------------------------------------
 
 The ``stat-lease4-get`` and ``stat-lease6-get`` commands fetch lease
 statistics for a range of known subnets. The range of subnets is
 determined through the use of optional command input parameters:
 
--  ``subnet-id`` - The ID of the subnet for which lease statistics
+-  ``subnet-id`` - the ID of the subnet for which lease statistics
    should be fetched. Use this to get statistics for a single subnet. If
    the subnet does not exist, the command result code is 3 (i.e.
    CONTROL_RESULT_EMPTY).
 
--  ``subnet-range`` - A pair of subnet IDs which describe an inclusive
+-  ``subnet-range`` - a pair of subnet IDs which describe an inclusive
    range of subnets for which statistics should be retrieved. The range
-   may include one or more IDs that correspond to no subnet: in this
+   may include one or more IDs that correspond to no subnet; in this
    case, the command will only output lease statistics for those that
    exist. However, if the range does not include any known subnets, the
    command result code is 3 (i.e. CONTROL_RESULT_EMPTY).
 
-   -  ``first-subnet-id`` - The ID of the first subnet in the range.
+   -  ``first-subnet-id`` - the ID of the first subnet in the range.
 
-   -  ``last-subnet-id`` - The ID of the last subnet in the range.
+   -  ``last-subnet-id`` - the ID of the last subnet in the range.
 
 The use of subnet-id and subnet-range are mutually exclusive. If no
 parameters are given, the result will contain data for all known
@@ -130,10 +130,10 @@ The response to either command will contain three elements:
 
    -  ``0`` - the command was successful;
 
-   -  ``1`` - an error occurred, an explanation will be the "text"
+   -  ``1`` - an error occurred, and an explanation will be the "text"
-      element;
+      element; or
 
-   -  ``2`` - the fetch found no matching data
+   -  ``2`` - the fetch found no matching data.
 
 -  ``text`` - an explanation of the command outcome. When the command
    succeeds it will contain the command name along with the number of
@@ -143,48 +143,48 @@ The response to either command will contain three elements:
    the element "result-set", which is patterned after SQL statement
    responses:
 
-   -  ``columns`` - a list of text column labels The columns returned
+   -  ``columns`` - a list of text column labels. The columns returned
       for DHCPv4 are:
 
-      -  ``subnet-id`` - ID of the subnet.
+      -  ``subnet-id`` - the ID of the subnet.
 
-      -  ``total-addresses`` - total number of addresses available for
+      -  ``total-addresses`` - the total number of addresses available for
          DHCPv4 management in the subnet. In other words, this is the
          sum of all addresses in all the configured pools in the subnet.
 
-      -  ``assigned-addresses`` - number of addresses in the subnet that
+      -  ``assigned-addresses`` - the number of addresses in the subnet that
          are currently assigned to a client.
 
-      -  ``declined-addresses`` - number of addresses in the subnet that
+      -  ``declined-addresses`` - the number of addresses in the subnet that
          are currently declined and are thus unavailable for assignment.
 
    -  The columns returned for DHCPv6 are:
 
-      -  ``subnet-id`` - ID of the subnet.
+      -  ``subnet-id`` - the ID of the subnet.
 
-      -  ``total-nas`` - number of NA addresses available for DHCPv6
+      -  ``total-nas`` - the number of NA addresses available for DHCPv6
          management in the subnet. In other words, this is the sum of
-         all the NA addresses in the all configured NA pools in the
+         all the NA addresses in all the configured NA pools in the
          subnet.
 
-      -  ``assigned-nas`` - number of NA addresses in a the subnet that
+      -  ``assigned-nas`` - the number of NA addresses in the subnet that
          are currently assigned to a client.
 
-      -  ``declined-nas`` - number of NA addresses that are currently
+      -  ``declined-nas`` - the number of NA addresses that are currently
          declined and are thus unavailable for assignment.
 
-      -  ``total-pds`` - total number of prefixes available of DHCPv6
+      -  ``total-pds`` - the total number of prefixes available of DHCPv6
          management in the subnet. In other words, this is the sum of
          all prefixes in all the configured prefix pools in the subnet.
 
-      -  ``assigned-pds`` - number of prefixes in the subnet that are
+      -  ``assigned-pds`` - the number of prefixes in the subnet that are
          currently assigned to a client.
 
    -  ``rows`` - a list of rows, one per subnet ID. Each row contains a
       data value corresponding to and in the same order as each column
       listed in "columns" for a given subnet.
 
-   -  ``timestamp`` - textual date and time the data was fetched,
+   -  ``timestamp`` - the textual date and time the data were fetched,
       expressed as GMT.
 
 The response to a DHCPv4 command might look as follows:

doc/guide/hooks.rst

@@ -61,7 +61,7 @@ refer to :ref:`installation` for a general overview of the installation process.
 
 ISC provides several additional premium hooks in the form of packages, which
 follow a similar installation procedure but with several additional steps.
-For your convenience, the premium hooks installation procedure is described in this section.
+For our users' convenience, the premium hooks installation procedure is described in this section.
 
 1. Download the package; detailed instructions are provided separately on how
 to get it. The package will be a file with a name similar to
@@ -80,7 +80,7 @@ Unpack this tarball:
    $ tar zxvf kea-KEAVERSION.tar.gz
 
 This will unpack the tarball into the kea-KEAVERSION subdirectory of
-your current working directory.
+the current working directory.
 
 3. Unpack the Kea premium tarball into the directory into which Kea was
 unpacked. Once Kea KEAVERSION has been unpacked into a kea-KEAVERSION
@@ -97,9 +97,9 @@ directory named "premium". Regardless of the name of the package, the
 directory will always be called "premium", although its contents will vary
 depending on the premium package.
 
-4. Run autoreconf tools. This step is necessary to update Kea's build
+4. Run ``autoreconf`` tools. This step is necessary to update Kea's build
 script to include the additional directory. If this tool is not already
-available on the system, install the automake and autoconf
+available on the system, install the ``automake`` and ``autoconf``
 tools. To generate the configure script, please use:
 
 ::
@@ -920,17 +920,15 @@ can be achieved by using the following configuration:
        ]
    }
 
-  **Note**
+Note that care should be taken when adjusting the expression. If the expression
+changes, then all the ``flex-id`` values may change, possibly rendering
+all reservations based on ``flex-id`` unusable until they are manually updated.
+It is strongly recommended that administrators start with the expression and a
+handful of reservations, and then adjust the expression as needed. Once
+the expression is confirmed to do what is desired of it, host reservations
+can be deployed on a broader scale.
 
-  Care should be taken when adjusting the expression. If the expression
+``flex-id`` values in host reservations can be specified in two ways. First,
-  changes, then all the ``flex-id`` values may change, possibly rendering
-  all reservations based on ``flex-id`` unusable until they are manually updated.
-  It is strongly recommended that administrators start with the expression and a
-  handful of reservations, and then adjust the expression as needed. Once
-  the expression is confirmed to do what is desired of it, host reservations
-  can be deployed on a broader scale.
-
-flex-id values in host reservations can be specified in two ways. First,
 they can be expressed as a hex string, e.g. bar string can be represented
 as 626174. Alternatively, it can be expressed as a quoted value (using
 double and single quotes), e.g. "'bar'". The former is more convenient
@@ -1235,8 +1233,8 @@ Example failure:
 As ``reservation-add`` is expected to store the host, the hosts-databases
 parameter must be specified in the configuration and databases must not
 run in read-only mode. In future versions of Kea, it will be possible to
-modify the reservations read from a configuration file. Please contact
+modify the reservations read from a configuration file. Interested parties are
-ISC if you are interested in this functionality.
+encouraged to contact ISC for more information on developing this functionality.
 
 .. _command-reservation-get:
 
@@ -1388,12 +1386,12 @@ may be disruptive. Use with caution. For larger deployments, please
 consider using ``reservation-get-page`` instead (see
 :ref:`command-reservation-get-page`).
 
-For a reference, see :ref:`ref-reservation-get-all`.
+For a reference, see :ref:`command-reservation-get-all`.
 
 .. _command-reservation-get-page:
 
-reservation-get-page command
+The reservation-get-page command
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``reservation-get-page`` can be used to query the host database and
 retrieve all reservations in a specified subnet by pages. This command
@@ -1517,8 +1515,6 @@ 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`.
 
-For a reference, see :ref:`ref-reservation-get-page`.
-
    **Note**
 
    Currently ``reservation-get-page`` is not supported by the Cassandra
@@ -2519,35 +2515,35 @@ both the command and the response.
 
 .. _user-context:
 
-User contexts
+User Contexts
 =============
 
-Hook libraries can have their own configuration parameters. That is
+Hooks libraries can have their own configuration parameters, which is
 convenient if the parameter applies to the whole library. However,
-sometimes it is very useful if certain configuration entities are
+sometimes it is very useful to extend certain configuration entities
-extended with additional configuration data. This is where the concept
+with additional configuration data. This is where the concept
-of user contexts comes in. A sysadmin can define an arbitrary set of
+of user contexts comes in. A system administrator can define an arbitrary set of
-data and attach it to Kea structures, as long as the data is specified
+data and attach it to Kea structures, as long as the data are specified
-as JSON map. In particular, it is possible to define fields that are
+as a JSON map. In particular, it is possible to define fields that are
-integers, strings, boolean, lists and maps. It is possible to define
+integers, strings, boolean, lists, or maps. It is possible to define
 nested structures of arbitrary complexity. Kea does not use that data on
-its own, simply stores and makes it available for the hook libraries.
+its own; it simply stores it and makes it available for the hooks libraries.
 
 Another use case for user contexts may be storing comments and other
 information that will be retained by Kea. Regular comments are discarded
-when configuration is loaded, but user contexts are retained. This is
+when the configuration is loaded, but user contexts are retained. This is
-useful if you want your comments to survive config-set, config-get
+useful if administrators want their comments to survive config-set or config-get
-operations for example.
+operations, for example.
 
 If user context is supported in a given context, the parser translates
 "comment" entries into user context with a "comment" entry. The pretty
 print of a configuration does the opposite operation and puts "comment"
-entries at the beginning of maps as it seems to be the common usage.
+entries at the beginning of maps, as that seems to be the common usage.
 
 As of Kea 1.3, the structures that allow user contexts are pools of all
 types (addresses and prefixes) and subnets. Kea 1.4 extended user
 context support to the global scope, interfaces config, shared networks,
 subnets, client classes, option datas and definitions, host
 reservations, control socket, dhcp ddns, loggers and server id. These
-are supported in both DHCPv4 and DHCPv6 at the exception of server id
+are supported in both DHCPv4 and DHCPv6, with the exception of server id
 which is DHCPv6 only.

doc/guide/intro.rst

@@ -74,7 +74,7 @@ software separately. (For the build requirements, also see :ref:`build-requireme
    kea-netconf agent. This Kea module is built optionally and requires
    Sysrepo software when used. Building Kea with NETCONF support
    requires many dependencies to be installed, which are described in
-   more detail in :ref: `netconf-install`.
+   more detail in :ref:`netconf-install`.
 
 .. _kea_software:
 
@@ -110,7 +110,7 @@ The following software is included with Kea:
 -  ``kea-ctrl-agent`` — Kea Control Agent (CA) is a daemon that exposes
    a RESTful control interface for managing Kea servers.
 
--  ``kea-netconf`` - Kea-netconf is an agent that provides a
+-  ``kea-netconf`` - kea-netconf is an agent that provides a
    YANG/NETCONF interface for the Kea environment.
 
 -  ``kea-shell`` — This simple text client uses the REST interface to

doc/guide/keactrl.rst

@@ -248,8 +248,8 @@ take effect. This limitation will be removed in a future release.
    NETCONF is an optional feature that is disabled by default and can be
    enabled during compilation. If Kea was compiled without NETCONF
    support, keactrl will do its best to not bother the user with
-   information about it. The netconf entries will still be present in
+   information about it. The NETCONF entries will still be present in
-   the keactrl.conf file, but netconf status will not be shown and other
+   the keactrl.conf file, but NETCONF status will not be shown and other
    commands will ignore it.
 
    **Note**

doc/guide/lease-expiration.rst

@@ -39,6 +39,8 @@ Although all configuration examples in this section are provided for the
 DHCPv4 server, the same parameters may be used for DHCPv6 server
 configuration.
 
+.. _lease-reclamation:
+
 Lease Reclamation
 =================
 

doc/guide/logging.rst

@@ -9,15 +9,15 @@ Logging Configuration
 
 During its operation Kea may produce many messages. They differ in
 severity (some are more important than others) and source (different
-components (e.g. hooks) produce different messages). It is useful to
+components, like hooks, produce different messages). It is useful to
-understand which log messages are critical and which are not, and
+understand which log messages are critical and which are not, and to
-configure your logging appropriately. For example, debug-level messages
+configure logging appropriately. For example, debug-level messages
 can be safely ignored in a typical deployment. They are, however, very
 useful when debugging a problem.
 
 The logging system in Kea is configured through the loggers entry in the
 server section of your configuration file. In previous Kea releases this
-entry was in an independent Logging section, this is still supported for
+entry was in an independent Logging section; this is still supported for
 backward compatibility.
 
 Loggers
@@ -31,7 +31,7 @@ messages pertaining to different logical functions of the component. For
 example, the DHCPv4 server uses one logger for messages about packet
 reception and transmission, another logger for messages related to lease
 allocation, and so on. Some of the libraries used by the Kea server,
-e.g. libdhcpsrv, use their own loggers.
+such as libdhcpsrv, use their own loggers.
 
 Users implementing hooks libraries (code attached to the server at
 runtime) are responsible for creating the loggers used by those
@@ -43,15 +43,14 @@ loggers used by Kea. Whenever it makes sense, a hooks library can use
 multiple loggers to log messages pertaining to different logical parts
 of the library.
 
-In the server section of a configuration file you can specify the
+In the server section of a configuration file the
 configuration for zero or more loggers (including loggers used by the
-proprietary hooks libraries). If there are no loggers specified, the
+proprietary hooks libraries) can be specified. If there are no loggers specified, the
 code will use default values; these cause Kea to log messages of INFO
 severity or greater to standard output. There is a small time window
 after Kea has been started but before it has read its configuration;
 logging in this short period can be controlled using environment
-variables. For details, see `Logging During Kea
+variables. For details, see :ref:`logging-during-startup`.
-Startup <#logging-during-startup>`__.
 
 The three main elements of a logger configuration are: ``name`` (the
 component that is generating the messages), ``severity`` (what to log),
@@ -59,16 +58,16 @@ and ``output_commands`` (where to log). There is also a ``debuglevel``
 element, which is only relevant if debug-level logging has been
 selected.
 
-name (string)
+The name (string) Logger
-~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 Each logger in the system has a name: that of the component binary file
-using it to log messages. For instance, if you want to configure logging
+using it to log messages. For instance, to configure logging
-for the DHCPv4 server, you add an entry for a logger named “kea-dhcp4”.
+for the DHCPv4 server, add an entry for a logger named “kea-dhcp4”.
 This configuration will then be used by the loggers in the DHCPv4
-server, and all the libraries used by it (unless a library defines its
+server and all the libraries used by it, unless a library defines its
 own logger and there is a specific logger configuration that applies to
-that logger).
+that logger.
 
 When tracking down an issue with the server's operation, use of DEBUG
 logging is required to obtain the verbose output needed for problem
@@ -85,10 +84,10 @@ required minimum.
 The loggers are associated with a particular library or binary of Kea.
 However, each library or binary may (and usually does) include multiple
 loggers. For example, the DHCPv4 server binary contains separate loggers
-for packet parsing, for dropped packets, for callouts, etc.
+for packet parsing, dropped packets, callouts, etc.
 
 The loggers form a hierarchy. For each program in Kea, there is a "root"
-logger, named after the program (e.g. the root logger for kea-dhcp (the
+logger, named after the program (e.g. the root logger for kea-dhcp, the
 DHCPv4 server) is named kea-dhcp4. All other loggers are children of
 this logger and are named accordingly, e.g. the allocation engine in the
 DHCPv4 server logs messages using a logger called
@@ -101,9 +100,9 @@ configuration file and so applies to all loggers. If an entry is made
 for a given logger, any attributes specified override those of the root
 logger, whereas any not specified are inherited from it.
 
-To illustrate this, suppose you are using the DHCPv4 server with the
+To illustrate this, suppose we are using the DHCPv4 server with the
 root logger “kea-dhcp4” logging at the INFO level. In order to enable
-DEBUG verbosity for DHCPv4 packet drops, you must create a configuration
+DEBUG verbosity for DHCPv4 packet drops, we must create a configuration
 entry for the logger called “kea-dhcp4.bad-packets” and specify severity
 DEBUG for this logger. All other configuration parameters may be omitted
 for this logger if the logger should use the default values specified in
@@ -121,348 +120,347 @@ will be logged according to the configuration set by the second entry.
 Currently defined loggers are defined in the following table. The
 "Software Package" column of this table specifies whether the particular
 loggers belong to the core Kea code (open source Kea binaries and
-libraries), or hook libraries (open source or premium).
+libraries), or hooks libraries (open source or premium).
 
-.. table:: List of loggers supported by Kea servers and hooks libraries
+.. table:: List of Loggers Supported by Kea Servers and Hooks Libraries Shipped With Kea and Premium Packages
-shipped with Kea and premium packages
 
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | Logger Name           | Software Package      | Description           |
+   | Logger Name                      | Software Package       | Description           |
-   +=======================+=======================+=======================+
+   +==================================+========================+=======================+
-   | ``kea-ctrl-agent``    | core                  | The root logger for   |
+   | ``kea-ctrl-agent``               | core                   | The root logger for   |
-   |                       |                       | the Control Agent     |
+   |                                  |                        | the Control Agent     |
-   |                       |                       | exposing the RESTful  |
+   |                                  |                        | exposing the RESTful  |
-   |                       |                       | control API. All      |
+   |                                  |                        | control API. All      |
-   |                       |                       | components used by    |
+   |                                  |                        | components used by    |
-   |                       |                       | the Control Agent     |
+   |                                  |                        | the Control Agent     |
-   |                       |                       | inherit the settings  |
+   |                                  |                        | inherit the settings  |
-   |                       |                       | from this logger.     |
+   |                                  |                        | from this logger.     |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-ctrl-agent.http | core                  | A logger which        |
+   | ``kea-ctrl-agent.http``          | core                   | A logger which        |
-   | ``                    |                       | outputs log messages  |
+   |                                  |                        | outputs log messages  |
-   |                       |                       | related to receiving, |
+   |                                  |                        | related to receiving, |
-   |                       |                       | parsing, and sending  |
+   |                                  |                        | parsing, and sending  |
-   |                       |                       | HTTP messages.        |
+   |                                  |                        | HTTP messages.        |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4``         | core                  | The root logger for   |
+   | ``kea-dhcp4``                    | core                   | The root logger for   |
-   |                       |                       | the DHCPv4 server.    |
+   |                                  |                        | the DHCPv4 server.    |
-   |                       |                       | All components used   |
+   |                                  |                        | All components used   |
-   |                       |                       | by the DHCPv4 server  |
+   |                                  |                        | by the DHCPv4 server  |
-   |                       |                       | inherit the settings  |
+   |                                  |                        | inherit the settings  |
-   |                       |                       | from this logger.     |
+   |                                  |                        | from this logger.     |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp6``         | core                  | The root logger for   |
+   | ``kea-dhcp6``                    | core                   | The root logger for   |
-   |                       |                       | the DHCPv6 server.    |
+   |                                  |                        | the DHCPv6 server.    |
-   |                       |                       | All components used   |
+   |                                  |                        | All components used   |
-   |                       |                       | by the DHCPv6 server  |
+   |                                  |                        | by the DHCPv6 server  |
-   |                       |                       | inherit the settings  |
+   |                                  |                        | inherit the settings  |
-   |                       |                       | from this logger.     |
+   |                                  |                        | from this logger.     |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.alloc-eng | core                  | Used by the lease     |
+   | ``kea-dhcp4.alloc-engine``,      | core                   | Used by the lease     |
-   | ine``,                |                       | allocation engine,    |
+   | ``kea-dhcp6.alloc-engine``       |                        | allocation engine,    |
-   | ``kea-dhcp6.alloc-eng |                       | which is responsible  |
+   |                                  |                        | which is responsible  |
-   | ine``                 |                       | for managing leases   |
+   |                                  |                        | for managing leases   |
-   |                       |                       | in the lease          |
+   |                                  |                        | in the lease          |
-   |                       |                       | database, i.e.        |
+   |                                  |                        | database, i.e.        |
-   |                       |                       | creating, modifying,  |
+   |                                  |                        | creating, modifying,  |
-   |                       |                       | and removing DHCP     |
+   |                                  |                        | and removing DHCP     |
-   |                       |                       | leases as a result of |
+   |                                  |                        | leases as a result of |
-   |                       |                       | processing messages   |
+   |                                  |                        | processing messages   |
-   |                       |                       | from the clients.     |
+   |                                  |                        | from clients.         |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.bad-packe | core                  | Used by the DHCP      |
+   | ``kea-dhcp4.bad-packets``,       | core                   | Used by the DHCP      |
-   | ts``,                 |                       | servers for logging   |
+   | ``kea-dhcp6.bad-packets``        |                        | servers for logging   |
-   | ``kea-dhcp6.bad-packe |                       | inbound client        |
+   |                                  |                        | inbound client        |
-   | ts``                  |                       | packets that were     |
+   |                                  |                        | packets that were     |
-   |                       |                       | dropped or to which   |
+   |                                  |                        | dropped or to which   |
-   |                       |                       | the server responded  |
+   |                                  |                        | the server responded  |
-   |                       |                       | with a DHCPNAK. It    |
+   |                                  |                        | with a DHCPNAK. It    |
-   |                       |                       | allows administrators |
+   |                                  |                        | allows administrators |
-   |                       |                       | to configure a        |
+   |                                  |                        | to configure a        |
-   |                       |                       | separate log output   |
+   |                                  |                        | separate log output   |
-   |                       |                       | that contains only    |
+   |                                  |                        | that contains only    |
-   |                       |                       | packet drop and       |
+   |                                  |                        | packet drop and       |
-   |                       |                       | reject entries.       |
+   |                                  |                        | reject entries.       |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.callouts` | core                  | Used to log messages  |
+   | ``kea-dhcp4.callouts``,          | core                   | Used to log messages  |
-   | `,                    |                       | pertaining to the     |
+   | ``kea-dhcp6.callouts``           |                        | pertaining to the     |
-   | ``kea-dhcp6.callouts` |                       | callouts registration |
+   |                                  |                        | callouts registration |
-   | `                     |                       | and execution for the |
+   |                                  |                        | and execution for the |
-   |                       |                       | particular hook       |
+   |                                  |                        | particular hook       |
-   |                       |                       | point.                |
+   |                                  |                        | point.                |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.commands` | core                  | Used to log messages  |
+   | ``kea-dhcp4.commands``,          | core                   | Used to log messages  |
-   | `,                    |                       | relating to the       |
+   | ``kea-dhcp6.commands``           |                        | relating to the       |
-   | ``kea-dhcp6.commands` |                       | handling of commands  |
+   |                                  |                        | handling of commands  |
-   | `                     |                       | received by the DHCP  |
+   |                                  |                        | received by the DHCP  |
-   |                       |                       | server over the       |
+   |                                  |                        | server over the       |
-   |                       |                       | command channel.      |
+   |                                  |                        | command channel.      |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.database` | core                  | Used to log messages  |
+   | ``kea-dhcp4.database``,          | core                   | Used to log messages  |
-   | `,                    |                       | relating to general   |
+   | ``kea-dhcp6.database``           |                        | relating to general   |
-   | ``kea-dhcp6.database` |                       | operations on the     |
+   |                                  |                        | operations on the     |
-   | `                     |                       | relational databases  |
+   |                                  |                        | relational databases  |
-   |                       |                       | and Cassandra.        |
+   |                                  |                        | and Cassandra.        |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.ddns``,   | core                  | Used by the DHCP      |
+   | ``kea-dhcp4.ddns``,              | core                   | Used by the DHCP      |
-   | ``kea-dhcp6.ddns``    |                       | server to log         |
+   | ``kea-dhcp6.ddns``               |                        | server to log         |
-   |                       |                       | messages related to   |
+   |                                  |                        | messages related to   |
-   |                       |                       | the Client FQDN and   |
+   |                                  |                        | Client FQDN and       |
-   |                       |                       | Hostname option       |
+   |                                  |                        | Hostname option       |
-   |                       |                       | processing. It also   |
+   |                                  |                        | processing. It also   |
-   |                       |                       | includes log messages |
+   |                                  |                        | includes log messages |
-   |                       |                       | related to the        |
+   |                                  |                        | related to the        |
-   |                       |                       | relevant DNS updates. |
+   |                                  |                        | relevant DNS updates. |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.dhcp4``   | core                  | Used by the DHCPv4    |
+   | ``kea-dhcp4.dhcp4``              | core                   | Used by the DHCPv4    |
-   |                       |                       | server daemon to log  |
+   |                                  |                        | server daemon to log  |
-   |                       |                       | basic operations.     |
+   |                                  |                        | basic operations.     |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.dhcpsrv`` | core                  | The base loggers for  |
+   | ``kea-dhcp4.dhcpsrv``,           | core                   | The base loggers for  |
-   | ,                     |                       | the libkea-dhcpsrv    |
+   | ``kea-dhcp6.dhcpsrv``            |                        | the libkea-dhcpsrv    |
-   | ``kea-dhcp6.dhcpsrv`` |                       | library.              |
+   |                                  |                        | library.              |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.eval``,   | core                  | Used to log messages  |
+   | ``kea-dhcp4.eval``,              | core                   | Used to log messages  |
-   | ``kea-dhcp6.eval``    |                       | relating to the       |
+   | ``kea-dhcp6.eval``               |                        | relating to the       |
-   |                       |                       | client classification |
+   |                                  |                        | client classification |
-   |                       |                       | expression evaluation |
+   |                                  |                        | expression evaluation |
-   |                       |                       | code.                 |
+   |                                  |                        | code.                 |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.host-cach | libdhcp_host_cache    | This logger is used   |
+   | ``kea-dhcp4.host-cache-hooks``,  | libdhcp_host_cache     | This logger is used   |
-   | e-hooks``,            | premium hook library  | to log messages       |
+   | ``kea-dhcp6.host-cache-hooks``   | premium hook library   | to log messages       |
-   | ``kea-dhcp6.host-cach |                       | related to the        |
+   |                                  |                        | related to the        |
-   | e-hooks``             |                       | operation of the Host |
+   |                                  |                        | operation of the Host |
-   |                       |                       | Cache Hook Library.   |
+   |                                  |                        | Cache hooks library.  |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.flex-id-h | libdhcp_flex_id       | This logger is used   |
+   | ``kea-dhcp4.flex-id-hooks``,     | libdhcp_flex_id        | This logger is used   |
-   | ooks``,               | premium hook library  | to log messages       |
+   | ``kea-dhcp6.flex-id-hooks``      | premium hook library   | to log messages       |
-   | ``kea-dhcp6.flex-id-h |                       | related to the        |
+   |                                  |                        | related to the        |
-   | ooks``                |                       | operation of the      |
+   |                                  |                        | operation of the      |
-   |                       |                       | Flexible Identifiers  |
+   |                                  |                        | Flexible Identifiers  |
-   |                       |                       | Hook Library.         |
+   |                                  |                        | hooks library.        |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.ha-hooks` | libdhcp_ha hook       | This logger is used   |
+   | ``kea-dhcp4.ha-hooks``,          | libdhcp_ha hook        | This logger is used   |
-   | `,                    | library               | to log messages       |
+   | ``kea-dhcp6.ha-hooks``           | library                | to log messages       |
-   | ``kea-dhcp6.ha-hooks` |                       | related to the        |
+   |                                  |                        | related to the        |
-   | `                     |                       | operation of the High |
+   |                                  |                        | operation of the High |
-   |                       |                       | Availability Hook     |
+   |                                  |                        | Availability hooks    |
-   |                       |                       | Library.              |
+   |                                  |                        | library.              |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.hooks``,  | core                  | Used to log messages  |
+   | ``kea-dhcp4.hooks``,             | core                   | Used to log messages  |
-   | ``kea-dhcp6.hooks``   |                       | related to the        |
+   | ``kea-dhcp6.hooks``              |                        | related to the        |
-   |                       |                       | management of hooks   |
+   |                                  |                        | management of hooks   |
-   |                       |                       | libraries, e.g.       |
+   |                                  |                        | libraries, e.g.       |
-   |                       |                       | registration and      |
+   |                                  |                        | registration and      |
-   |                       |                       | deregistration of the |
+   |                                  |                        | deregistration of the |
-   |                       |                       | libraries, and to the |
+   |                                  |                        | libraries, and to the |
-   |                       |                       | initialization of the |
+   |                                  |                        | initialization of the |
-   |                       |                       | callouts execution    |
+   |                                  |                        | callouts execution    |
-   |                       |                       | for various hook      |
+   |                                  |                        | for various hook      |
-   |                       |                       | points within the     |
+   |                                  |                        | points within the     |
-   |                       |                       | DHCP server.          |
+   |                                  |                        | DHCP server.          |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.host-cmds | libdhcp_host_cmds     | This logger is used   |
+   | ``kea-dhcp4.host-cmds-hooks``,   | libdhcp_host_cmds      | This logger is used   |
-   | -hooks``,             | premium hook library  | to log messages       |
+   | ``kea-dhcp6.host-cmds-hooks``    | premium hook library   | to log messages       |
-   | ``kea-dhcp6.host-cmds |                       | related to the        |
+   |                                  |                        | related to the        |
-   | -hooks``              |                       | operation of the Host |
+   |                                  |                        | operation of the Host |
-   |                       |                       | Cmds hooks library.   |
+   |                                  |                        | Commands hooks        |
-   |                       |                       | In general, these     |
+   |                                  |                        | library. In general,  |
-   |                       |                       | will pertain to the   |
+   |                                  |                        | these will pertain to |
-   |                       |                       | loading and unloading |
+   |                                  |                        | the loading and       |
-   |                       |                       | of the library and    |
+   |                                  |                        | unloading of the      |
-   |                       |                       | the execution of      |
+   |                                  |                        | library and the       |
-   |                       |                       | commands by the       |
+   |                                  |                        | execution of commands |
-   |                       |                       | library.              |
+   |                                  |                        | by the library.       |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.hosts``,  | core                  | Used within the       |
+   | ``kea-dhcp4.hosts``,             | core                   | Used within the       |
-   | ``kea-dhcp6.hosts``   |                       | libdhcpsrv, it logs   |
+   | ``kea-dhcp6.hosts``              |                        | libdhcpsrv, it logs   |
-   |                       |                       | messages related to   |
+   |                                  |                        | messages related to   |
-   |                       |                       | the management of the |
+   |                                  |                        | the management of     |
-   |                       |                       | DHCP host             |
+   |                                  |                        | DHCP host             |
-   |                       |                       | reservations, i.e.    |
+   |                                  |                        | reservations, i.e.    |
-   |                       |                       | retrieval of the      |
+   |                                  |                        | retrieving            |
-   |                       |                       | reservations and      |
+   |                                  |                        | reservations and      |
-   |                       |                       | adding new            |
+   |                                  |                        | adding new            |
-   |                       |                       | reservations.         |
+   |                                  |                        | reservations.         |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.lease-cmd | libdhcp_lease_cmds    | This logger is used   |
+   | ``kea-dhcp4.lease-cmds-hooks``,  | libdhcp_lease_cmds     | This logger is used   |
-   | s-hooks``,            | hook library          | to log messages       |
+   | ``kea-dhcp6.lease-cmds-hooks``   | hook library           | to log messages       |
-   | ``kea-dhcp6.lease-cmd |                       | related to the        |
+   |                                  |                        | related to the        |
-   | s-hooks``             |                       | operation of the      |
+   |                                  |                        | operation of the      |
-   |                       |                       | Lease Cmds hooks      |
+   |                                  |                        | Lease Commands hooks  |
-   |                       |                       | library. In general,  |
+   |                                  |                        | library. In general,  |
-   |                       |                       | these will pertain to |
+   |                                  |                        | these will pertain to |
-   |                       |                       | the loading and       |
+   |                                  |                        | the loading and       |
-   |                       |                       | unloading of the      |
+   |                                  |                        | unloading of the      |
-   |                       |                       | library and the       |
+   |                                  |                        | library and the       |
-   |                       |                       | execution of commands |
+   |                                  |                        | execution of commands |
-   |                       |                       | by the library.       |
+   |                                  |                        | by the library.       |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.leases``, | core                  | Used by the DHCP      |
+   | ``kea-dhcp4.leases``,            | core                   | Used by the DHCP      |
-   | ``kea-dhcp6.leases``  |                       | server to log         |
+   | ``kea-dhcp6.leases``             |                        | server to log         |
-   |                       |                       | messages related to   |
+   |                                  |                        | messages related to   |
-   |                       |                       | lease allocation. The |
+   |                                  |                        | lease allocation. The |
-   |                       |                       | messages include      |
+   |                                  |                        | messages include      |
-   |                       |                       | detailed information  |
+   |                                  |                        | detailed information  |
-   |                       |                       | about the allocated   |
+   |                                  |                        | about the allocated   |
-   |                       |                       | or offered leases,    |
+   |                                  |                        | or offered leases,    |
-   |                       |                       | errors during the     |
+   |                                  |                        | errors during the     |
-   |                       |                       | lease allocation,     |
+   |                                  |                        | lease allocation,     |
-   |                       |                       | etc.                  |
+   |                                  |                        | etc.                  |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.legal-log | libdhcp_legal_log     | This logger is used   |
+   | ``kea-dhcp4.legal-log-hooks``,   | libdhcp_legal_log      | This logger is used   |
-   | -hooks``,             | premium hook library  | to log messages       |
+   | ``kea-dhcp6.legal-log-hooks``    | premium hook library   | to log messages       |
-   | ``kea-dhcp6.legal-log |                       | related to the        |
+   |                                  |                        | related to the        |
-   | -hooks``              |                       | operation of the      |
+   |                                  |                        | operation of the      |
-   |                       |                       | Forensic Logging      |
+   |                                  |                        | Forensic Logging      |
-   |                       |                       | Hooks Library.        |
+   |                                  |                        | hooks library.        |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.options`` | core                  | Used by the DHCP      |
+   | ``kea-dhcp4.options``,           | core                   | Used by the DHCP      |
-   | ,                     |                       | server to log         |
+   | ``kea-dhcp4.options``            |                        | server to log         |
-   | ``kea-dhcp4.options`` |                       | messages related to   |
+   |                                  |                        | messages related to   |
-   |                       |                       | the processing of     |
+   |                                  |                        | the processing of     |
-   |                       |                       | options in the DHCP   |
+   |                                  |                        | options in the DHCP   |
-   |                       |                       | messages, i.e.        |
+   |                                  |                        | messages, i.e.        |
-   |                       |                       | parsing options,      |
+   |                                  |                        | parsing options,      |
-   |                       |                       | encoding options into |
+   |                                  |                        | encoding options into |
-   |                       |                       | on-wire format, and   |
+   |                                  |                        | on-wire format, and   |
-   |                       |                       | packet classification |
+   |                                  |                        | packet classification |
-   |                       |                       | using options         |
+   |                                  |                        | using options         |
-   |                       |                       | contained in the      |
+   |                                  |                        | contained in the      |
-   |                       |                       | received packets.     |
+   |                                  |                        | received packets.     |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.packets`` | core                  | This logger is mostly |
+   | ``kea-dhcp4.packets``,           | core                   | This logger is mostly |
-   | ,                     |                       | used to log messages  |
+   | ``kea-dhcp6.packets``            |                        | used to log messages  |
-   | ``kea-dhcp6.packets`` |                       | related to            |
+   |                                  |                        | related to            |
-   |                       |                       | transmission of the   |
+   |                                  |                        | transmission of the   |
-   |                       |                       | DHCP packets, i.e.    |
+   |                                  |                        | DHCP packets, i.e.    |
-   |                       |                       | packet reception and  |
+   |                                  |                        | packet reception and  |
-   |                       |                       | the sending of a      |
+   |                                  |                        | the sending of a      |
-   |                       |                       | response. Such        |
+   |                                  |                        | response. Such        |
-   |                       |                       | messages include      |
+   |                                  |                        | messages include      |
-   |                       |                       | information about the |
+   |                                  |                        | information about the |
-   |                       |                       | source and            |
+   |                                  |                        | source and            |
-   |                       |                       | destination IP        |
+   |                                  |                        | destination IP        |
-   |                       |                       | addresses and         |
+   |                                  |                        | addresses and         |
-   |                       |                       | interfaces used to    |
+   |                                  |                        | interfaces used to    |
-   |                       |                       | transmit packets. The |
+   |                                  |                        | transmit packets. The |
-   |                       |                       | logger is also used   |
+   |                                  |                        | logger is also used   |
-   |                       |                       | to log messages       |
+   |                                  |                        | to log messages       |
-   |                       |                       | related to subnet     |
+   |                                  |                        | related to subnet     |
-   |                       |                       | selection, as this    |
+   |                                  |                        | selection, as this    |
-   |                       |                       | selection is usually  |
+   |                                  |                        | selection is usually  |
-   |                       |                       | based on the IP       |
+   |                                  |                        | based on the IP       |
-   |                       |                       | addresses, relay      |
+   |                                  |                        | addresses, relay      |
-   |                       |                       | addresses, and/or     |
+   |                                  |                        | addresses, and/or     |
-   |                       |                       | interface names,      |
+   |                                  |                        | interface names,      |
-   |                       |                       | which can be          |
+   |                                  |                        | which can be          |
-   |                       |                       | retrieved from the    |
+   |                                  |                        | retrieved from the    |
-   |                       |                       | received packet even  |
+   |                                  |                        | received packet even  |
-   |                       |                       | before the DHCP       |
+   |                                  |                        | before the DHCP       |
-   |                       |                       | message carried in    |
+   |                                  |                        | message carried in    |
-   |                       |                       | the packet is parsed. |
+   |                                  |                        | the packet is parsed. |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.radius-ho | libdhcp_radius        | This logger is used   |
+   | ``kea-dhcp4.radius-hooks``,      | libdhcp_radius         | This logger is used   |
-   | oks``,                | premium hook library  | to log messages       |
+   | ``kea-dhcp6.radius-hooks``       | premium hook library   | to log messages       |
-   | ``kea-dhcp6.radius-ho |                       | related to the        |
+   |                                  |                        | related to the        |
-   | oks``                 |                       | operation of the      |
+   |                                  |                        | operation of the      |
-   |                       |                       | Radius Hook Library.  |
+   |                                  |                        | RADIUS hooks library. |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.stat-cmds | libdhcp_stat_cmds     | This logger is used   |
+   | ``kea-dhcp4.stat-cmds-hooks``,   | libdhcp_stat_cmds      | This logger is used   |
-   | -hooks``,             | hook library          | to log messages       |
+   | ``kea-dhcp6.stat-cmds-hooks``    | hook library           | to log messages       |
-   | ``kea-dhcp6.stat-cmds |                       | related to the        |
+   |                                  |                        | related to the        |
-   | -hooks``              |                       | operation of the      |
+   |                                  |                        | operation of the      |
-   |                       |                       | Statistics Commands   |
+   |                                  |                        | Statistics Commands   |
-   |                       |                       | hooks library. In     |
+   |                                  |                        | hooks library. In     |
-   |                       |                       | general, these will   |
+   |                                  |                        | general, these will   |
-   |                       |                       | pertain to loading    |
+   |                                  |                        | pertain to loading    |
-   |                       |                       | and unloading the     |
+   |                                  |                        | and unloading the     |
-   |                       |                       | library and the       |
+   |                                  |                        | library and the       |
-   |                       |                       | execution of commands |
+   |                                  |                        | execution of commands |
-   |                       |                       | by the library.       |
+   |                                  |                        | by the library.       |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.subnet-cm | libdhcp_subnet_cmds   | This logger is used   |
+   | ``kea-dhcp4.subnet-cmds-hooks``, | libdhcp_subnet_cmds    | This logger is used   |
-   | ds-hooks``,           | hook library          | to log messages       |
+   | ``kea-dhcp6.subnet-cmds-hooks``  | hook library           | to log messages       |
-   | ``kea-dhcp6.subnet-cm |                       | related to the        |
+   |                                  |                        | related to the        |
-   | ds-hooks``            |                       | operation of the      |
+   |                                  |                        | operation of the      |
-   |                       |                       | Subnet Commands hooks |
+   |                                  |                        | Subnet Commands hooks |
-   |                       |                       | library. In general,  |
+   |                                  |                        | library. In general,  |
-   |                       |                       | these will pertain to |
+   |                                  |                        | these will pertain to |
-   |                       |                       | loading and unloading |
+   |                                  |                        | loading and unloading |
-   |                       |                       | the library and the   |
+   |                                  |                        | the library and the   |
-   |                       |                       | execution of commands |
+   |                                  |                        | execution of commands |
-   |                       |                       | by the library.       |
+   |                                  |                        | by the library.       |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp4.mysql-cb- | libdhcp_mysql_cb_hook | This logger is used   |
+   | ``kea-dhcp4.mysql-cb-hooks``,    | libdhcp_mysql_cb_hooks | This logger is used   |
-   | hooks``,              | s                     | to log messages       |
+   | ``kea-dhcp6.mysql-cb-hooks``     | hook library           | to log messages       |
-   | ``kea-dhcp6.mysql-cb- | hook library          | related to the        |
+   |                                  |                        | related to the        |
-   | hooks``               |                       | operation of the      |
+   |                                  |                        | operation of the      |
-   |                       |                       | MySQL Configuration   |
+   |                                  |                        | MySQL Configuration   |
-   |                       |                       | Backend hooks         |
+   |                                  |                        | Backend hooks         |
-   |                       |                       | library.              |
+   |                                  |                        | library.              |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp-ddns``     | core                  | The root logger for   |
+   | ``kea-dhcp-ddns``                | core                   | The root logger for   |
-   |                       |                       | the kea-dhcp-ddns     |
+   |                                  |                        | the kea-dhcp-ddns     |
-   |                       |                       | daemon. All           |
+   |                                  |                        | daemon. All           |
-   |                       |                       | components used by    |
+   |                                  |                        | components used by    |
-   |                       |                       | this daemon inherit   |
+   |                                  |                        | this daemon inherit   |
-   |                       |                       | the settings from     |
+   |                                  |                        | the settings from     |
-   |                       |                       | this logger unless    |
+   |                                  |                        | this logger unless    |
-   |                       |                       | there are             |
+   |                                  |                        | there are             |
-   |                       |                       | configurations for    |
+   |                                  |                        | configurations for    |
-   |                       |                       | more specialized      |
+   |                                  |                        | more specialized      |
-   |                       |                       | loggers..             |
+   |                                  |                        | loggers.              |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp-ddns.dctl` | core                  | The logger used by    |
+   | ``kea-dhcp-ddns.dctl``           | core                   | The logger used by    |
-   | `                     |                       | the kea-dhcp-ddns     |
+   |                                  |                        | the kea-dhcp-ddns     |
-   |                       |                       | daemon for logging    |
+   |                                  |                        | daemon for logging    |
-   |                       |                       | basic information     |
+   |                                  |                        | basic information     |
-   |                       |                       | about the process,    |
+   |                                  |                        | about the process,    |
-   |                       |                       | received signals, and |
+   |                                  |                        | received signals, and |
-   |                       |                       | triggered             |
+   |                                  |                        | triggered             |
-   |                       |                       | reconfigurations.     |
+   |                                  |                        | reconfigurations.     |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp-ddns.dhcpd | core                  | The logger used by    |
+   | ``kea-dhcp-ddns.dhcpddns``       | core                   | The logger used by    |
-   | dns``                 |                       | the kea-dhcp-ddns     |
+   |                                  |                        | the kea-dhcp-ddns     |
-   |                       |                       | daemon for logging    |
+   |                                  |                        | daemon for logging    |
-   |                       |                       | events related to     |
+   |                                  |                        | events related to     |
-   |                       |                       | DDNS operations.      |
+   |                                  |                        | DDNS operations.      |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp-ddns.dhcp- | core                  | Used by the           |
+   | ``kea-dhcp-ddns.dhcp-to-d2``     | core                   | Used by the           |
-   | to-d2``               |                       | kea-dhcp-ddns daemon  |
+   |                                  |                        | kea-dhcp-ddns daemon  |
-   |                       |                       | for logging           |
+   |                                  |                        | for logging           |
-   |                       |                       | information about     |
+   |                                  |                        | information about     |
-   |                       |                       | events dealing with   |
+   |                                  |                        | events dealing with   |
-   |                       |                       | receiving messages    |
+   |                                  |                        | receiving messages    |
-   |                       |                       | from the DHCP servers |
+   |                                  |                        | from the DHCP servers |
-   |                       |                       | and adding them to    |
+   |                                  |                        | and adding them to    |
-   |                       |                       | the queue for         |
+   |                                  |                        | the queue for         |
-   |                       |                       | processing.           |
+   |                                  |                        | processing.           |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-dhcp-ddns.d2-to | core                  | Used by the           |
+   | ``kea-dhcp-ddns.d2-to-dns``      | core                   | Used by the           |
-   | -dns``                |                       | kea-dhcp-ddns daemon  |
+   |                                  |                        | kea-dhcp-ddns daemon  |
-   |                       |                       | for logging           |
+   |                                  |                        | for logging           |
-   |                       |                       | information about     |
+   |                                  |                        | information about     |
-   |                       |                       | events dealing with   |
+   |                                  |                        | events dealing with   |
-   |                       |                       | sending and receiving |
+   |                                  |                        | sending and receiving |
-   |                       |                       | messages with the DNS |
+   |                                  |                        | messages to and from  |
-   |                       |                       | servers.              |
+   |                                  |                        | the DNS servers.      |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
-   | ``kea-netconf``       | core                  | The root logger for   |
+   | ``kea-netconf``                  | core                   | The root logger for   |
-   |                       |                       | the Netconf agent.    |
+   |                                  |                        | the NETCONF agent.    |
-   |                       |                       | All components used   |
+   |                                  |                        | All components used   |
-   |                       |                       | by Netconf inherit    |
+   |                                  |                        | by NETCONF inherit    |
-   |                       |                       | the settings from     |
+   |                                  |                        | the settings from     |
-   |                       |                       | this logger if there  |
+   |                                  |                        | this logger if there  |
-   |                       |                       | is no specialized     |
+   |                                  |                        | is no specialized     |
-   |                       |                       | logger provided.      |
+   |                                  |                        | logger provided.      |
-   +-----------------------+-----------------------+-----------------------+
+   +----------------------------------+------------------------+-----------------------+
 
 Note that user-defined hook libraries should not use any of the loggers
 mentioned above, but should instead define new loggers with names that
-correspond to the libraries using them. Suppose that the user created
+correspond to the libraries using them. Suppose that a user created
-the library called “libdhcp-packet-capture” to dump packets received and
+a library called “libdhcp-packet-capture” to dump packets received and
-transmitted by the server to the file. An appropriate name for the
+transmitted by the server to a file. An appropriate name for the
 logger could be ``kea-dhcp4.packet-capture-hooks``. (Note that the hook
 library implementer only specifies the second part of this name, i.e.
 “packet-capture”. The first part is a root-logger name and is prepended
@@ -472,11 +470,11 @@ from the root logger, something that can be overridden by an entry in
 the configuration file.
 
 The easiest way to find a logger name is to configure all logging to go
-to a single destination and look for specific logger names. See `Logging
+to a single destination and look there for specific logger names. See
-Message Format <#logging-message-format>`__ for details.
+:ref:`logging-message-format` for details.
 
-severity (string)
+The severity (string) Logger
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This specifies the category of messages logged. Each message is logged
 with an associated severity, which may be one of the following (in
@@ -504,56 +502,56 @@ logger are inhibited.
 
    **Note**
 
-   The keactrl tool, described in `??? <#keactrl>`__, can be configured
+   The ``keactrl`` tool, described in :ref:`keactrl`, can be configured
    to start the servers in verbose mode. If this is the case, the
    settings of the logging severity in the configuration file will have
-   no effect, i.e. the servers will use a logging severity of DEBUG
+   no effect; the servers will use a logging severity of DEBUG
    regardless of the logging settings specified in the configuration
-   file. If you need to control severity via the configuration file,
+   file. To control severity via the configuration file,
    please make sure that the ``kea_verbose`` value is set to "no" within
-   the keactrl configuration.
+   the ``keactrl`` configuration.
 
-debuglevel (integer)
+The debuglevel (integer) Logger
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When a logger's severity is set to DEBUG, this value specifies what
 level of debug messages should be printed. It ranges from 0 (least
 verbose) to 99 (most verbose). If severity for the logger is not DEBUG,
 this value is ignored.
 
-output_options (list)
+The output_options (list) Logger
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Each logger can have zero or more ``output_options``. These specify
 where log messages are sent and are explained in detail below.
 
-output (string)
+The output (string) Option
-^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This value determines the type of output. There are several special
 values allowed here: ``stdout`` (messages are printed on standard
 output), ``stderr`` (messages are printed on stderr), ``syslog``
-(messages are logged to syslog using default name), ``syslog:name``
+(messages are logged to syslog using the default name), ``syslog:name``
-(messages are logged to syslog using specified name). Any other value is
+(messages are logged to syslog using a specified name). Any other value is
 interpreted as a filename to which messages should be written.
 
-flush (true of false)
+The flush (true of false) Option
-^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Flush buffers after each log message. Doing this will reduce performance
 but will ensure that if the program terminates abnormally, all messages
 up to the point of termination are output. The default is "true".
 
-maxsize (integer)
+The maxsize (integer) Option
-^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Only relevant when the destination is a file. This is the maximum size
+This option is only relevant when the destination is a file; this is the maximum size
 in bytes that a log file may reach. When the maximum size is reached,
 the file is renamed and a new file opened. For example, a ".1" is
-appended to the name — if a ".1" file exists, it is renamed ".2", etc.
+appended to the name; if a ".1" file exists, it is renamed ".2", etc.
 This is referred to as rotation.
 
-The default value is 10240000 (10MB). The smallest value that may be
+The default value is 10240000 (10MB). The smallest value that can be
 specified without disabling rotation is 204800. Any value less than
 this, including 0, disables rotation.
 
@@ -561,18 +559,18 @@ this, including 0, disables rotation.
 
    Due to a limitation of the underlying logging library (log4cplus),
    rolling over the log files (from ".1" to ".2", etc) may show odd
-   results; there can be multiple small files at the timing of roll
+   results; there can be multiple small files at the timing of rollover.
-   over. This can happen when multiple processes try to roll over the
+   This can happen when multiple processes try to roll over the
    files simultaneously. Version 1.1.0 of log4cplus solved this problem,
    so if this version or later of log4cplus is used to build Kea, the
    issue should not occur. Even for older versions, it is normally
    expected to happen rarely unless the log messages are produced very
    frequently by multiple different processes.
 
-maxver (integer)
+The maxver (integer) Option
-^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Only relevant when the destination is a file and rotation is enabled
+This option is only relevant when the destination is a file and rotation is enabled
 (i.e. maxsize is large enough). This is the maximum number of rotated
 versions that will be kept. Once that number of files has been reached,
 the oldest file, "log-name.maxver", will be discarded each time the log
@@ -582,7 +580,7 @@ maxver rotated files. The minimum and default value is 1.
 Example Logger Configurations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In this example we want to set the Server logging to write to the
+In this example we want to set the server logging to write to the
 console using standard output.
 
 ::
@@ -602,7 +600,7 @@ console using standard output.
    }
 
 In this second example, we want to store debug log messages in a file
-that is at most 2MB and keep up to 8 copies of old logfiles. Once the
+that is at most 2MB and keep up to eight copies of old logfiles. Once the
 logfile grows to 2MB, it will be renamed and a new file will be created.
 
 ::
@@ -625,6 +623,8 @@ logfile grows to 2MB, it will be renamed and a new file will be created.
       ]
    }
 
+.. _logging-message-format:
+
 Logging Message Format
 ----------------------
 
@@ -658,15 +658,14 @@ INFO
    process generating the message (in this case, ``kea-dhcp4``) and the
    component within the program from which the message originated
    (``dhcpsrv``, which is the name of the common library used by DHCP
-   server implementations). The number after the slash is a process id
+   server implementations). The number after the slash is a process ID
-   (pid).
+   (PID).
 
 DHCPSRV_MEMFILE_DB
    The message identification. Every message in Kea has a unique
-   identification, which can be used as an index into the `Kea Messages
+   identification, which can be used as an index to the `Kea Messages
-   Manual <kea-messages.html>`__
+   Manual <https://jenkins.isc.org/job/Kea_doc/messages/kea-messages.html>`__,
-   (https://jenkins.isc.org/job/Kea_doc/messages/kea-messages.html) from
+   where more information can be obtained.
-   which more information can be obtained.
 
 opening memory file lease database: type=memfile universe=4
    A brief description. Within this text, information relating to the
@@ -680,7 +679,7 @@ Logging During Kea Startup
 --------------------------
 
 The logging configuration is specified in the configuration file.
-However, when Kea starts, the file is not read until partway into the
+However, when Kea starts, the configuration file is not read until partway into the
 initialization process. Prior to that, the logging settings are set to
 default values, although it is possible to modify some aspects of the
 settings by means of environment variables. Note that in the absence of
@@ -693,14 +692,14 @@ of logging during startup:
 
 KEA_LOCKFILE_DIR
    Specifies a directory where the logging system should create its lock
-   file. If not specified, it is prefix/var/run/kea, where prefix
+   file. If not specified, it is prefix/var/run/kea, where "prefix"
    defaults to /usr/local. This variable must not end with a slash.
-   There is one special value: "none", which instructs Kea to not create
+   There is one special value: "none", which instructs Kea not to create
    a lock file at all. This may cause issues if several processes log to
    the same file.
 
 KEA_LOGGER_DESTINATION
-   Specifies logging output. There are several special values.
+   Specifies logging output. There are several special values:
 
    stdout
       Log to standard output.

doc/guide/netconf.rst

@@ -38,20 +38,16 @@ packages, the installation procedure is much simpler on Ubuntu.
 Installing NETCONF on Ubuntu 18.04
 ----------------------------------
 
-For detailed installation instructions see the `
+For detailed installation instructions, see the `Ubuntu installation notes page <https://gitlab.isc.org/isc-projects/kea/wikis/docs/ubuntu-installation-notes>`__.
-        Ubuntu installation notes page <
-        Ubuntu installation notes page>`__.
 
 .. _netconf-centos-install:
 
 Installing NETCONF on CentOS 7.5
 --------------------------------
 
-For detailed installation instructions see the `
+For detailed installation instructions, see the `CentOS installation notes page <https://gitlab.isc.org/isc-projects/kea/wikis/docs/centos-installation-notes>`__.
-        CentOS installation notes page <
-        CentOS installation notes page>`__.
 
-CentOS 7.5's gcc compiler (version 4.8.5) is very old. Some sysrepo
+CentOS 7.5's gcc compiler (version 4.8.5) is very old. Some Sysrepo
 dependencies require at least version 4.9, which unfortunately means
 that a new compiler has to be installed. Also, many of the Sysrepo
 dependencies are not avalable in CentOS as packages, so for the time
@@ -61,10 +57,8 @@ Quick Sysrepo Overview
 ======================
 
 This section offers a rather brief overview of a subset of available
-functions in Sysrepo. For more complete information, see the Sysrepo
+functions in Sysrepo. For more complete information, see the `Sysrepo
-homepage. You may also want to take a look at the `
+homepage <https://www.sysrepo.org>`__.
-    notes made during a series of IETF Hackathons <
-    notes made during a series of IETF Hackathons>`__.
 
 In YANG, configurations and state data are described in the YANG syntax
 in module files named: ``"module-name"``\ ``[@"revision"]``.yang
@@ -73,7 +67,7 @@ The revision part is optional and has YYYY-MM-DD format. An alternate
 XML syntax YIN is defined but less user-friendly. Top-level modules are
 named in Kea models (a short version of schema models).
 
-List currently installed YANG modules:
+To list the currently installed YANG modules:
 
 ::
 
@@ -106,7 +100,7 @@ model, a similar initiative in the past for DHCPv4 failed. Therefore,
 Kea uses its own dedicated models for DHCPv4 and DHCPv6 but partially
 supports the IETF model for DHCPv6. Those three models have extra
 modules as dependencies. The dependency modules are also provided in
-``src/share/yang/modules`` in sources and ``share/kea/yang/modules``
+``src/share/yang/modules`` in sources and in ``share/kea/yang/modules``
 after installation.
 
 To install modules from sources, do the following:
@@ -120,7 +114,7 @@ To install modules from sources, do the following:
    ...
 
 Note that the first -s parameter specifies the location of the YANG
-schema repository; you can check it with sysrepoctl -l. This is a
+schema repository; it can be verified with sysrepoctl -l. This is a
 parameter that is configured during Sysrepo compilation and is detected
 by the Kea configuration under the SYSREPO_REPO name.
 
@@ -151,8 +145,8 @@ The installation should look similar to the following:
    Notifying sysrepo about the change...
    Install operation completed successfully.
 
-You can confirm whether the models are imported correctly by using
+It is possible to confirm whether the models are imported correctly by using
-sysrepoctl -l
+sysrepoctl -l:
 
 ::
 
@@ -188,7 +182,7 @@ by:
 If the module is used (i.e. imported) by other modules, it can be
 uninstalled only after those modules have finished using it.
 Installation and uninstallation must be done in dependency order and
-reverse dependency order accordingly.
+reverse-dependency order accordingly.
 
 .. _netconf-models:
 
@@ -197,7 +191,7 @@ Supported YANG Models
 
 The only currently supported models are ``kea-dhcp4-server`` and
 ``kea-dhcp6-server``. There is partial support for
-``ietf-dhcpv6-server``, but the primary focus of testing was on Kea DHCP
+``ietf-dhcpv6-server``, but the primary focus of testing has been on Kea DHCP
 servers. Several other models (``kea-dhcp-ddns`` and ``kea-ctrl-agent``)
 are currently not supported.
 
@@ -215,9 +209,9 @@ The NETCONF agent follows this algorithm:
    sessions with the startup and running datastores.
 
 -  Check that used (not essential) and required (essential) modules are
-   installed in the sysrepo repository at the right revision. If an
+   installed in the Sysrepo repository at the right revision. If an
-   essential module, i.e. a module where the configuration schema for a
+   essential module - that is, a module where the configuration schema for a
-   managed server is defined, is not installed, raise a fatal error.
+   managed server is defined - is not installed, raise a fatal error.
 
 -  For each managed server, get the YANG configuration from the startup
    datastore, translate it to JSON, and load it onto the server being
@@ -234,27 +228,27 @@ The NETCONF agent follows this algorithm:
 Configuration
 =============
 
-The behavior described in `Using the NETCONF Agent <#using-netconf>`__
+The behavior described in :ref:`using-netconf`
 is controlled by a few configuration flags, which can be set in the
 global scope or in a specific managed-server scope. In the second case,
 the value defined in the managed-server scope takes precedence. These
 flags are:
 
--  The ``boot-update`` controls the initial configuration phase; when
+-  ``boot-update`` - controls the initial configuration phase; when
    true (the default), the initial configuration retrieved from the
    classic Kea server JSON configuration file is loaded first, and then
    the startup YANG model is loaded. This setting lets administrators
    define a control socket in the local JSON file and then download the
    configuration from YANG. When set to false, this phase is skipped.
 
--  The ``subscribe-changes`` command controls the module change
+-  ``subscribe-changes`` - controls the module change
    subscription; when true (the default), a module change callback is
    subscribed, but when false the phase is skipped and running
    configuration updates are disabled. When set to true, the running
    datastore is used to subscribe for changes.
 
--  The ``validate-changes`` command controls how Kea monitors changes in
+-  ``validate-changes`` - controls how Kea monitors changes in
-   the Sysrepo configuration. Sysrepo offers two stages where Kea could
+   the Sysrepo configuration. Sysrepo offers two stages where Kea can
    interact: validation and application. At the validation (or
    SR_EV_VERIFY event, in the Sysrepo naming convention) stage, Kea
    retrieves the newly committed configuration and verifies it. If the
@@ -284,14 +278,14 @@ making them manageable. For instance, for the DHCPv4 server:
 Note the alternative to boot with full configurations does not allow
 easy tracking of changes or synchronization between the JSON and YANG
 configuration sources; therefore, that setup is not really compatible
-with the YANG / NETCONF configuration management paradigm, where
+with the YANG/NETCONF configuration management paradigm, where
 everything should be performed in YANG.
 
 With module change subscriptions enabled, the kea-netconf daemon will
 monitor any configuration changes as they appear in the Sysrepo. Such
 changes can be done using the ``sysrepocfg`` tool or remotely using any
 NETCONF client. For details, please see the Sysrepo documentation or
-`Step-by-Step NETCONF Agent Operation Example <#operation-example>`__.
+:ref:`operation-example`.
 Those tools can be used to modify YANG configurations in the running
 datastore. Note that committed configurations are only updated in the
 running datastore; to keep them between server reboots they must be
@@ -302,7 +296,7 @@ true) and the running configuration has changed (e.g. using
 ``sysrepocfg`` or any NETCONF client), the callback validates the
 modified configuration (if ``validate-changes`` was not set to false)
 and runs a second time to apply the new configuration. If the validation
-fails, the callback is still called again but with an ABORT (vs APPLY)
+fails, the callback is still called again but with an ABORT (vs. APPLY)
 event with rollback changes.
 
 The returned code of the callback on an APPLY event is ignored, as it is
@@ -311,18 +305,18 @@ too late to refuse a bad configuration.
 There are four ways in which a modified YANG configuration could
 possibly be incorrect:
 
-1. It can be non-compliant with the schema, e.g. unknown entry, missing
+1. It can be non-compliant with the schema, e.g. an unknown entry, missing a
-   mandatory entry, value with a bad type, or not matching a constraint.
+   mandatory entry, a value with a bad type, or not matching a constraint.
 
-2. It can fail to be translated from YANG to JSON, e.g. invalid user
+2. It can fail to be translated from YANG to JSON, e.g. an invalid user
    context.
 
-3. It can fail Kea server sanity checks, e.g. out-of-subnet-pool range
+3. It can fail Kea server sanity checks, e.g. an out-of-subnet-pool range
-   or unsupported database type.
+   or an unsupported database type.
 
-4. The syntax is correct and passes server sanity checks but the
+4. The syntax may be correct and pass server sanity checks but the
    configuration fails to run, e.g. the configuration specifies database
-   credentials, but the database refuses connection.
+   credentials but the database refuses the connection.
 
 The first case is handled by Sysrepo. The second and third cases are
 handled by kea-netconf in the validation phase (if not disabled by
@@ -337,29 +331,30 @@ agent).
 
 Each managed server entry contains optionally:
 
--  ``boot-update``, ``subscribe-changes``, and ``validate-changes``
+-  ``boot-update``, ``subscribe-changes``, and ``validate-changes`` -
    control flags.
 
--  ``model`` specifies the YANG model / module name. For each service,
+-  ``model`` - specifies the YANG model / module name. For each service,
    the default is the corresponding Kea YANG model, e.g. for ``"dhcp4"``
    it is ``"kea-dhcp4-server"``.
 
--  ``control-socket`` specifies the control socket for managing the
+-  ``control-socket`` - specifies the control socket for managing the
    service configuration.
 
 A control socket is specified by:
 
--  ``socket-type``: the socket type is either ``stdout`` (the default;
+-  ``socket-type`` - the socket type is either ``stdout``, ``unix``, or ``http``.
+   ``stdout`` is the default;
    it is not really a socket, but it allows ``kea-netconf`` to run in
-   debugging mode where everything is printed on stdout. Can be also
+   debugging mode where everything is printed on stdout, and it can also be
-   useful to redirect commands easily.), ``unix`` (standard direct
+   used to redirect commands easily. ``unix`` is the standard direct
-   server control channel, which uses UNIX sockets), and ``http`` (using
+   server control channel, which uses UNIX sockets, and ``http`` uses
-   a control agent, which accepts HTTP connections).
+   a control agent, which accepts HTTP connections.
 
--  ``socket-name``: the local socket name for the ``unix`` socket type
+-  ``socket-name`` - the local socket name for the ``unix`` socket type
    (default empty string).
 
--  ``socket-url``: the HTTP URL for the ``http`` socket type (default
+-  ``socket-url`` - the HTTP URL for the ``http`` socket type (default
    ``http://127.0.0.1:8000/``).
 
 User contexts can store arbitrary data as long as they are in valid JSON
@@ -374,14 +369,14 @@ servers or agents; however, currently no hook points are defined. The
 should be loaded by kea-netconf, along with their configuration
 information specified with ``parameters``.
 
-Please consult `??? <#logging>`__ for the details on how to configure
+Please consult :ref:`logging` for details on how to configure
 logging. The NETCONF agent's root logger's name is ``kea-netconf``, as
 given in the example above.
 
 .. _netconf-example:
 
-kea-netconf Configuration Example
+A kea-netconf Configuration Example
-=================================
+===================================
 
 The following example demonstrates the basic NETCONF configuration. More
 examples are available in the ``doc/examples/netconf`` directory in the
@@ -395,7 +390,7 @@ Kea sources.
        "Netconf":
        {
            // Control flags can be defined in the global scope or
-           // in a managed server scope. Precedence are:
+           // in a managed server scope. Precedences are:
            // - use the default value (true)
            // - use the global value
            // - use the local value.
@@ -409,7 +404,7 @@ Kea sources.
            // "stdout" which outputs the configuration on the standard output,
            // "unix" which uses the local control channel supported by the
            // "dhcp4" and "dhcp6" servers ("d2" support is not yet available),
-           // and "http" which uses the Control agent "ca" to manage itself or
+           // and "http" which uses the Control Agent "ca" to manage itself or
            // to forward commands to "dhcp4" or "dhcp6".
            "managed-servers":
            {
@@ -448,7 +443,7 @@ Kea sources.
                    }
                },
 
-               // Of course the Control Agent (nicknamed CA) supports HTTP.
+               // Of course the Control Agent (CA) supports HTTP.
                "ca":
                {
                    "model": "kea-ctrl-agent",
@@ -478,7 +473,7 @@ Kea sources.
                }
            ],
 
-           // Similar to other Kea components, Netconf also uses logging.
+           // Similar to other Kea components, NETCONF also uses logging.
            "loggers": [
                {
                    "name": "kea-netconf",
@@ -540,8 +535,8 @@ kea-netconf accepts the following command-line switches:
 
 .. _operation-example:
 
-Step-by-Step NETCONF Agent Operation Example
+A Step-by-Step NETCONF Agent Operation Example
-============================================
+==============================================
 
    **Note**
 
@@ -639,7 +634,7 @@ The following is the example ``netconf.json`` configuration for
        }
    }
 
-Note that in production you should not need to log at the DEBUG level.
+Note that in production there should not be a need to log at the DEBUG level.
 
 The Kea NETCONF agent is launched by:
 
@@ -730,7 +725,7 @@ configuration file:
      </control-socket>
    </config>
 
-is directly rejected by ``sysrepocfg``:
+It is directly rejected by ``sysrepocfg``:
 
 ::
 
@@ -788,7 +783,7 @@ server and fails to validate as in this ``BAD-config.xml`` file:
 In the last case, the misconfiguration is detected too late and the
 change must be reverted in Sysrepo, e.g. using the startup datastore as
 a backup. For this reason, please use the ``sysrepocfg`` ``--permanent``
-/ ``-p`` option (or a similar feature of NETCONF clients) with care.
+/ ``-p`` option (or any similar feature of NETCONF clients) with care.
 
 .. _operation-example-2pools:
 
@@ -956,6 +951,5 @@ Finally, any of the previous examples can be replayed using
 
     # sysrepocfg -d running -f xml -e vi kea-dhcp6-server
 
-or, of course, using a NETCONF client like ``netopeer2-cli`` from the `
+or, of course, using a NETCONF client like ``netopeer2-cli`` from the
-        Netopeer2 <
+`Netopeer2 <https://github.com/CESNET/Netopeer2>`__ NETCONF Toolset.
-        Netopeer2>`__ NETCONF Toolset.

doc/guide/quickstart.rst

@@ -6,7 +6,7 @@ Quick Start
 
 This section describes the basic steps needed to get Kea up and running.
 For further details, full customizations, and troubleshooting, see the
-respective chapters in the Kea Administrator Reference Manual (ARM).
+respective chapters elsewhere in this Kea Administrator Reference Manual (ARM).
 
 .. _quick-start:
 
@@ -98,7 +98,7 @@ Quick Start Guide for DHCPv4 and DHCPv6 Services
 
 For instructions specific to your system, please read the
 `system-specific notes <https://kb.isc.org/docs/installing-kea>`__,
-available in the `Kea section of ISC's
+available in the Kea section of `ISC's
 Knowledgebase <https://kb.isc.org/docs>`__.
 
 The details of ``keactrl`` script usage can be found in

doc/guide/shell.rst

@@ -6,20 +6,20 @@ The Kea Shell
 
 .. _shell-overview:
 
-Overview
+Overview of the Kea Shell
-========
+=========================
 
 Kea 1.2.0 introduced the Control Agent (CA, see
-`??? <#kea-ctrl-agent>`__), which provides a RESTful control interface
+:ref:`kea-ctrl-agent`), which provides a RESTful control interface
 over HTTP. That API is typically expected to be used by various IPAMs
 and similar management systems. Nevertheless, there may be cases when an
-administrator wants to send a command to the CA directly. The Kea shell
+administrator wants to send a command to the CA directly, and the Kea shell
 provides a way to do this. It is a simple command-line,
 scripting-friendly, text client that is able to connect to the CA, send
 it commands with parameters, retrieve the responses, and display them.
 
 As the primary purpose of the Kea shell is as a tool in a scripting
-environment, it is not interactive. However, with simple tricks it can
+environment, it is not interactive. However, following simple guidelines it can
 be run manually.
 
 Shell Usage
@@ -55,9 +55,9 @@ where:
 
 Other switches are:
 
--  ``-h`` prints a help message.
+-  ``-h`` - prints a help message.
 
--  ``-v`` prints the software version.
+-  ``-v`` - prints the software version.
 
 Once started, the shell reads parameters for the command from standard
 input, which are expected to be in JSON format. When all have been read,
@@ -65,10 +65,9 @@ the shell establishes a connection with the CA using HTTP, sends the
 command, and awaits a response. Once that is received, it is displayed
 on standard output.
 
-For a list of available commands, see `??? <#ctrl-channel>`__;
+For a list of available commands, see :ref:`ctrl-channel`;
-additional commands may be provided by hook libraries. If you are unsure
+additional commands may be provided by hooks libraries. For a list of
-which commands are supported, use the ``list-commands`` command. It will
+all supported commands from the CA, use the ``list-commands`` command.
-instruct the CA to return a list of all supported commands.
 
 The following shows a simple example of usage:
 
@@ -86,7 +85,7 @@ returned for the service named ``dhcp4``.
 
 It is envisaged that the Kea shell will be most frequently used in
 scripts; the next example shows a simple scripted execution. It sends
-the command "config-write" to the CA (the ``--service`` parameter hasn't
+the command "config-write" to the CA (the ``--service`` parameter has not
 been used), along with the parameters specified in param.json. The
 result will be stored in result.json.
 
@@ -105,7 +104,7 @@ servers, the default empty path in the URL is not enough, so the
 
    $ kea-shell --host 192.0.2.1 --port 8001 --path kea ...
 
-Kea shell requires Python to to be installed on the system. It has been
+The Kea shell requires Python to to be installed on the system. It has been
 tested with Python 2.7 and various versions of Python 3, up to 3.5.
 Since not every Kea deployment uses this feature and there are
 deployments that do not have Python, the Kea shell is not enabled by
@@ -115,6 +114,6 @@ during the installation of Kea.
 The Kea shell is intended to serve more as a demonstration of the
 RESTful interface's capabilities (and, perhaps, an illustration for
 people interested in integrating their management environments with Kea)
-than as a serious management client. Do not expect it to be
+than as a serious management client. It is not likely to be
-significantly expanded in the future. It is, and will remain, a simple
+significantly expanded in the future; it is, and will remain, a simple
 tool.

doc/guide/stats.rst

@@ -10,10 +10,10 @@ Statistics Overview
 Both Kea DHCP servers support statistics gathering. A working DHCP
 server encounters various events that can cause certain statistics to be
 collected. For example, a DHCPv4 server may receive a packet
-(pkt4-received statistic increases by one) that after parsing is
+(the pkt4-received statistic increases by one) that after parsing is
 identified as a DHCPDISCOVER (pkt4-discover-received). The server
 processes it and decides to send a DHCPOFFER representing its answer
-(pkt4-offer-sent and pkt4-sent statistics increase by one). Such events
+(the pkt4-offer-sent and pkt4-sent statistics increase by one). Such events
 happen frequently, so it is not uncommon for the statistics to have
 values in the high thousands. They can serve as an easy and powerful
 tool for observing a server's and a network's health. For example, if
@@ -24,7 +24,7 @@ There are four types of statistics:
 
 -  *integer* - this is the most common type. It is implemented as a
    64-bit integer (int64_t in C++), so it can hold any value between
-   -2^63 to 2^63 -1.
+   -2^63 to 2^63-1.
 
 -  *floating point* - this type is intended to store floating-point
    precision. It is implemented as a C++ double type.
@@ -38,15 +38,14 @@ There are four types of statistics:
 
 During normal operation, the DHCPv4 and DHCPv6 servers gather
 statistics. For a list of DHCPv4 and DHCPv6 statistics, see
-`??? <#dhcp4-stats>`__ and `??? <#dhcp6-stats>`__, respectively.
+:ref:`dhcp4-stats` and :ref:`dhcp6-stats`, respectively.
 
 To extract data from the statistics module, the control channel can be
-used. See `??? <#ctrl-channel>`__ for details. It is possible to
+used. See :ref:`ctrl-channel` for details. It is possible to
 retrieve a single statistic or all statistics, reset statistics (i.e.
-set to neutral value, typically zero), or even remove completely a
+set to a neutral value, typically zero), or even completely remove a
-single statistic or all statistics. See section `Commands for
+single statistic or all statistics. See the section :ref:`command-stats`
-Manipulating Statistics <#command-stats>`__ for a list of
+for a list of statistics-oriented commands.
-statistics-oriented commands.
 
 .. _stats-lifecycle:
 
@@ -55,7 +54,7 @@ Statistics Lifecycle
 
 It is useful to understand how the Statistics Manager module works. When
 the server starts operation, the manager is empty and contains no
-statistics. When ``statistic-get-all`` is executed, an empty list is
+statistics. If the ``statistic-get-all`` command is executed at that point, an empty list is
 returned. Once the server performs an operation that causes a statistic
 to change, the related statistic will be created. In general, once a
 statistic is recorded even once, it is kept in the manager until
@@ -74,8 +73,8 @@ the near future. For example, a misconfigured device in a network may
 cause clients to report duplicate addresses, so the server will report
 increasing values of pkt4-decline-received. Once the problem is found
 and the device is removed, the system administrator may want to remove
-the pkt4-decline-received statistic, so it won't be reported anymore. If
+the pkt4-decline-received statistic, so it will not be reported anymore. If
-a duplicate address is detected ever again, the server will add this
+a duplicate address is ever detected again, the server will add this
 statistic back.
 
 .. _command-stats:
@@ -84,14 +83,14 @@ Commands for Manipulating Statistics
 ====================================
 
 There are several commands defined that can be used for accessing
-(-get), resetting to zero or neutral value (-reset), or even removing a
+(-get), resetting to zero or a neutral value (-reset), or removing a
 statistic completely (-remove). The difference between reset and remove
 is somewhat subtle. The reset command sets the value of the statistic to
 zero or a neutral value, so after this operation, the statistic will
 have a value of 0 (integer), 0.0 (float), 0h0m0s0us (duration), or ""
 (string). When requested, a statistic with the values mentioned will be
 returned. ``Remove`` removes a statistic completely, so the statistic
-will not be reported anymore. Please note that the server code may add
+will no longer be reported. Please note that the server code may add
 it back if there is a reason to record it.
 
    **Note**
@@ -99,14 +98,14 @@ it back if there is a reason to record it.
    The following sections describe commands that can be sent to the
    server; the examples are not fragments of a configuration file. For
    more information on sending commands to Kea, see
-   `??? <#ctrl-channel>`__.
+   :ref:`ctrl-channel`.
 
 .. _command-statistic-get:
 
-statistic-get Command
+The statistic-get Command
----------------------
+-------------------------
 
-The *statistic-get* command retrieves a single statistic. It takes a
+The ``statistic-get`` command retrieves a single statistic. It takes a
 single-string parameter called ``name``, which specifies the statistic
 name. An example command may look like this:
 
@@ -127,10 +126,10 @@ the status code will still indicate success (0).
 
 .. _command-statistic-reset:
 
-statistic-reset Command
+The statistic-reset Command
------------------------
+---------------------------
 
-The *statistic-reset* command sets the specified statistic to its
+The ``statistic-reset`` command sets the specified statistic to its
 neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time
 duration, and "" for string type. It takes a single-string parameter
 called ``name``, which specifies the statistic name. An example command
@@ -153,10 +152,10 @@ and the text field contains the error description.
 
 .. _command-statistic-remove:
 
-statistic-remove Command
+The statistic-remove Command
-------------------------
+----------------------------
 
-The *statistic-remove* command attempts to delete a single statistic. It
+The ``statistic-remove`` command attempts to delete a single statistic. It
 takes a single-string parameter called ``name``, which specifies the
 statistic name. An example command may look like this:
 
@@ -177,10 +176,10 @@ and the text field contains the error description.
 
 .. _command-statistic-get-all:
 
-statistic-get-all Command
+The statistic-get-all Command
--------------------------
+-----------------------------
 
-The *statistic-get-all* command retrieves all statistics recorded. An
+The ``statistic-get-all`` command retrieves all statistics recorded. An
 example command may look like this:
 
 ::
@@ -196,10 +195,10 @@ when the total number of statistics is zero).
 
 .. _command-statistic-reset-all:
 
-statistic-reset-all Command
+The statistic-reset-all Command
----------------------------
+-------------------------------
 
-The *statistic-reset* command sets all statistics to their neutral
+The ``statistic-reset`` command sets all statistics to their neutral
 values: 0 for integer, 0.0 for float, 0h0m0s0us for time duration, and
 "" for string type. An example command may look like this:
 
@@ -217,10 +216,10 @@ field contains the error description.
 
 .. _command-statistic-remove-all:
 
-statistic-remove-all Command
+The statistic-remove-all Command
-----------------------------
+--------------------------------
 
-The *statistic-remove-all* command attempts to delete all statistics. An
+The ``statistic-remove-all`` command attempts to delete all statistics. An
 example command may look like this:
 
 ::
@@ -233,4 +232,4 @@ example command may look like this:
 If the removal of all statistics is successful, the server responds with
 a status of 0, indicating success, and an empty parameters field. If an
 error is encountered, the server returns a status code of 1 (error) and
-the text field will contain the error description.
+the text field contains the error description.