Review and update ARM documentation

Minor edits and fixes for the documentation added from 2022 through
9.18.

(cherry picked from commit b6e4b512dd02d0cbd8dc7f90784ad3ddba21d270)

doc/arm/build.inc.rst

@@ -62,9 +62,9 @@ To build BIND 9, the following packages must be installed:
 - ``perl``
 - ``pkg-config`` / ``pkgconfig`` / ``pkgconf``
 
-BIND 9.20 requires ``libuv`` 1.37.0 or higher, using ``libuv`` >= 1.40.0 is
+BIND 9.20 requires ``libuv`` 1.37.0 or higher; using ``libuv`` >= 1.40.0 is
-recommended. On older systems, an updated ``libuv`` package needs to be
+recommended. On older systems an updated ``libuv`` package needs to be
-installed from sources such as EPEL, PPA, or other native sources. The other
+installed from sources, such as EPEL, PPA, or other native sources. The other
 option is to build and install ``libuv`` from source.
 
 OpenSSL 1.1.1 or newer is required. If the OpenSSL library is installed

doc/arm/catz.inc.rst

@@ -25,7 +25,7 @@ changes are immediately put into effect. Because the catalog zone is a
 normal DNS zone, these configuration changes can be propagated using the
 standard AXFR/IXFR zone transfer mechanism.
 
-Catalog zones' format and behavior are specified as :rfc:`9432`.
+The format and behavior of catalog zones are specified in :rfc:`9432`.
 
 Principle of Operation
 ~~~~~~~~~~~~~~~~~~~~~~

doc/arm/intro-security.inc.rst

@@ -54,7 +54,7 @@ therefore, depend on the site's security policy.
 
 3. Zone transfer from a **primary** to one or more **secondary** authoritative name servers across a
 public network carries risk. The zone transfer may be secured using
-``named.conf`` :ref:`statements, TSIG cryptographic methods or TLS<sec_file_transfer>`.
+``named.conf`` :ref:`statements, TSIG cryptographic methods, or TLS<sec_file_transfer>`.
 Clearly, if the secondary authoritative name server(s) all lie within a network entirely
 under the user's control, the security threat may be regarded as non-existent. Any implementation requirements
 again depend on the site's security policy.
@@ -72,5 +72,5 @@ or full-service resolver to completely answer user queries. Stub resolvers on th
 typically have a caching capability to increase performance. At this time there are no standard stub resolvers or proxy
 DNS tools that implement DNSSEC. BIND 9 may be configured to provide such capability on supported Linux or Unix platforms.
 :ref:`DNS over TLS <dns_over_tls>` may be configured to verify the integrity of the data between the stub resolver and
-area (or full-service) resolver. However, unless the resolver and the Authoritative Name Server implements DNSSEC, end-to-end integrity (from
+area (or full-service) resolver. However, unless the resolver and the authoritative name server implements DNSSEC, end-to-end integrity (from
 authoritative name server to stub resolver) cannot be guaranteed.

doc/arm/pkcs11.inc.rst

@@ -84,8 +84,8 @@ Configuring pkcs11-provider
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The canonical documentation for configuring pkcs11-provider is in the
-`provider-pkcs11.7`_ manual page, but here's copy of working configuration for
+`provider-pkcs11.7`_ manual page, but a sample working configuration is included
-your convenience:
+here for the user's convenience:
 
 .. _`provider-pkcs11.7`: https://github.com/latchset/pkcs11-provider/blob/main/docs/provider-pkcs11.7.md
 
@@ -143,8 +143,8 @@ Add following lines at the bottom of the file:
 Key Generation
 ^^^^^^^^^^^^^^
 
-HSM keys can now be created and used.  We are going to assume that you already
+HSM keys can now be created and used.  We are assuming that
-have a BIND 9 installed, either from a package, or from the sources, and the
+BIND 9 is already installed, either from a package or from the sources, and the
 tools are readily available in the ``$PATH``.
 
 A zone that is configured with ``dnssec-policy`` can generate keys through
@@ -188,7 +188,7 @@ and ZSK:
 
    dnssec-keyfromlabel -a RSASHA256 -l "pkcs11:token=bind9;object=example.net-zsk;pin-value=0000" example.net
 
-NOTE: you can use PIN stored on disk, by specifying ``pin-source=<path_to>/<file>``, f.e.:
+NOTE: a PIN stored on disk can be used by specifying ``pin-source=<path_to>/<file>``, e.g:
 
 ::
 
@@ -200,7 +200,7 @@ and then use in the label specification:
 
    pin-source=/opt/bind9/etc/pin.txt
 
-Confirm that you have one KSK and one ZSK present in the current directory:
+Confirm that there is one KSK and one ZSK present in the current directory:
 
 ::
 
@@ -215,10 +215,10 @@ The output should look like this (the second number will be different):
    Kexample.net.+008+42231.key
    Kexample.net.+008+42231.private
 
-A note on generating ECDSA keys: there is a bug in libp11 when looking up a key,
+A note on generating ECDSA keys: there is a bug in libp11 when looking up a key.
-that function compares keys only on their ID, not the label. So when looking up
+That function compares keys only on their ID, not the label, so when looking up
-a key it returns the first key, rather than the matching key. The workaround for
+a key it returns the first key, rather than the matching key. To work around
-this is when creating ECDSA keys, you should specify a unique ID:
+this when creating ECDSA keys, specify a unique ID:
 
 ::
 

doc/arm/reference.rst

@@ -315,7 +315,7 @@ file documentation:
         A quoted string which is used as a DNS name; for example: ``my.test.domain``.
 
     ``duration``
-        A duration in BIND 9 can be written in three ways: as single number
+        A duration in BIND 9 can be written in three ways: as a single number
         representing seconds, as a string of numbers with TTL-style
         time-unit suffixes, or in ISO 6801 duration format.
 
@@ -1062,7 +1062,7 @@ responses such as NXDOMAIN.
 
 :any:`parental-agents` lists allow for a common set of parental agents to be
 easily used by multiple primary and secondary zones. A "parental agent" is a
-trusted DNS server that is queried to check if DS records for a given zones
+trusted DNS server that is queried to check whether DS records for a given zones
 are up-to-date.
 
 :any:`primaries` Block Grammar
@@ -2042,7 +2042,7 @@ Boolean Options
    :tags: server
    :short: Controls whether BIND 9 responds to root key sentinel probes.
 
-   If ``yes``, respond to root key sentinel probes as described in
+   If ``yes``, the server responds to root key sentinel probes as described in
    :rfc:`8509`:. The default is ``yes``.
 
 .. namedconf:statement:: reuseport
@@ -3325,7 +3325,7 @@ Query Address
    :short: Specifies the range(s) of ports to be excluded from use as sources for UDP/IPv6 messages.
 
    These statements, which are deprecated and will be removed in a future
-   release, specific ranges of port numbers to exclude from those specified
+   release, indicate ranges of port numbers to exclude from those specified
    in the :any:`avoid-v4-udp-ports` and :any:`avoid-v6-udp-ports`
    options, respectively.
 
@@ -3429,11 +3429,11 @@ options apply to zone transfers.
    terminated. The default is 60 minutes (1 hour). The maximum value
    is 28 days (40320 minutes).
 
-   .. note:: The inbound zone transfers are also affected by
+   .. note:: Inbound zone transfers are also affected by
-             ``tcp-idle-timeout``, the ``max-transfer-idle-in`` will close the
+             ``tcp-idle-timeout``; ``max-transfer-idle-in`` closes the
-             inbound zone transfer if there was no complete AXFR or no complete
+             inbound zone transfer if there is no complete AXFR or no complete
-             IXFR chunk. The ``tcp-idle-timeout`` will close the connection if
+             IXFR chunk. ``tcp-idle-timeout`` closes the connection if
-             there's no progress on the TCP level.
+             there is no progress on the TCP level.
 
 .. namedconf:statement:: max-transfer-time-out
    :tags: transfer
@@ -3641,7 +3641,7 @@ system.
 
 .. namedconf:statement:: max-records-per-type
    :tags: server
-   :short: Sets the maximum number of records that can be stored in an RRset
+   :short: Sets the maximum number of records that can be stored in an RRset.
 
    This sets the maximum number of resource records that can be stored
    in an RRset in a database. When configured in :namedconf:ref:`options`
@@ -3649,14 +3649,14 @@ system.
    the default value for zone databases, which can be overridden by setting
    it at the :namedconf:ref:`zone` level.
 
-   If set to a positive value, any attempt to cache or to add to a zone
+   If set to a positive value, any attempt to cache, or to add to a zone
-   an RRset with more than the specified number of records will result in
+   an RRset with more than the specified number of records, will result in
-   a failure.  If set to 0, there is no cap on RRset size.  The default is
+   a failure. If set to 0, there is no cap on RRset size. The default is
    100.
 
 .. namedconf:statement:: max-types-per-name
    :tags: server
-   :short: Sets the maximum number of RR types that can be stored for an owner name
+   :short: Sets the maximum number of RR types that can be stored for an owner name.
 
    This sets the maximum number of resource record types that can be stored
    for a single owner name in a database. When configured in
@@ -3676,7 +3676,7 @@ system.
 
    In a cache, if :any:`max-types-per-name` is set to a positive number, an
    attempt to add a new resource record set to a name that already has the
-   specified number of types will temporarily succeed so that the query can
+   specified number of types will temporarily succeed, so that the query can
    be answered. However, the newly added RRset will immediately be purged.
 
    Certain high-priority types, including SOA, CNAME, DNSKEY, and their
@@ -3899,7 +3899,7 @@ system.
 
    .. note::
 
-       :any:`max-cache-size` does not work reliably for the maximum
+       :any:`max-cache-size` does not work reliably for a maximum
        amount of memory of 100 MB or lower.
 
    Upon startup and reconfiguration, caches with a limited size
@@ -3983,7 +3983,7 @@ system.
    :short: Specifies the maximum number of concurrent DNS UPDATE messages that can be processed by the server.
 
    This is the maximum number of simultaneous DNS UPDATE messages that
-   the server will accept for updating local authoritiative zones or
+   the server will accept, for updating local authoritative zones or
    forwarding to a primary server. The default is ``100``.
 
 .. namedconf:statement:: sig0checks-quota
@@ -4459,13 +4459,13 @@ Tuning
    dropping patterns, the query is retried over TCP.  Per-server EDNS statistics
    are only retained in memory for the lifetime of a given server's ADB entry.
 
-   According to the measurements done by multiple parties the default value
+   According to measurements taken by multiple parties, the default value
-   should not be causing the fragmentation as most of the Internet "core" is able to
+   should not be causing the fragmentation. As most of the Internet "core" is able to
-   cope with IP message sizes between 1400-1500 bytes, the 1232 size was picked
+   cope with IP message sizes between 1400-1500 bytes, the 1232 size was chosen
    as a conservative minimal number that could be changed by the DNS operator to
-   a estimated path MTU minus the estimated header space. In practice, the
+   a estimated path MTU, minus the estimated header space. In practice, the
    smallest MTU witnessed in the operational DNS community is 1500 octets, the
-   Ethernet maximum payload size, so a a useful default for maximum DNS/UDP
+   Ethernet maximum payload size, so a useful default for the maximum DNS/UDP
    payload size on **reliable** networks would be 1432.
 
    Any server-specific :any:`edns-udp-size` setting has precedence over all
@@ -4593,8 +4593,8 @@ Tuning
    immediately, ensuring that the cache always has an answer available.
 
    :any:`prefetch` specifies the "trigger" TTL value at which prefetch
-   of the current query takes place; when a cache record with a
+   of the current query takes place; when a cache record with an
-   lower or equal TTL value is encountered during query processing, it is
+   equal or lower TTL value is encountered during query processing, it is
    refreshed. Valid trigger TTL values are 1 to 10 seconds. Values
    larger than 10 seconds are silently reduced to 10. Setting a
    trigger TTL to zero causes prefetch to be disabled. The default
@@ -6019,8 +6019,8 @@ The main motivation behind having the ``ephemeral`` configuration is
 to aid in testing, as trusted certificate authorities do not issue the
 certificates associated with this configuration. Thus, these
 certificates will never be trusted by any clients that verify TLS
-certificates. They provide encryption of the traffic but no
+certificates; they provide encryption of the traffic but no
-authentification of the transmission channel. That might be enough in
+authentication of the transmission channel. That might be enough in
 the case of deployment in a controlled environment.
 
 It should be noted that on reconfiguration, the ``ephemeral`` TLS key
@@ -6028,9 +6028,9 @@ and the certificate are recreated, and all TLS certificates and keys,
 as well as associated data, are reloaded from the disk. In that case,
 listening sockets associated with TLS remain intact.
 
-Please keep in mind that doing reconfiguration can cause a short
+Please keep in mind that performing a reconfiguration can cause a short
 interruption in BIND's ability to process inbound client packets. The
-length of interruption is environment and configuration-specific. A
+length of interruption is environment- and configuration-specific. A
 good example of when reconfiguration is necessary is when TLS keys and
 certificates are updated on the disk.
 
@@ -6542,14 +6542,14 @@ The following options can be specified in a :any:`dnssec-policy` statement:
 
 .. namedconf:statement:: signatures-jitter
    :tags: dnssec
-   :short: Specifies a range for signatures expirations.
+   :short: Specifies a range for signature expirations.
 
     To prevent all signatures from expiring at the same moment, BIND 9 may
     vary the validity interval of individual signatures. The validity of a
-    newly generated signatures is in range between :any:`signatures-validity`
+    newly generated signature is in the range between :any:`signatures-validity`
-    (maximum) and :any:`signatures-validity` minus :any:`signatures-jitter`
+    (maximum) and :any:`signatures-validity`, minus :any:`signatures-jitter`
-    (minimum). The default jitter is 12 hours and the configured value must
+    (minimum). The default jitter is 12 hours, and the configured value must
-    be lower than :any:`signatures-validity` and
+    be lower than both :any:`signatures-validity` and
     :any:`signatures-validity-dnskey`.
 
 .. namedconf:statement:: signatures-refresh
@@ -8326,40 +8326,40 @@ Resolver Statistics Counters
     This indicates the number of active fetches.
 
 ``BucketSize``
-    This indicates the number the resolver's internal buckets (a static number).
+    This indicates the number of the resolver's internal buckets (a static number).
 
 ``REFUSED``
     This indicates the number of REFUSED responses received.
 
 ``ClientCookieOut``
-    This indicates the number of COOKIE sent with client cookie only.
+    This indicates the number of COOKIE messages sent to an authoritative server with only a client cookie.
 
 ``ServerCookieOut``
-    This indicates the number of COOKIE sent with client and server cookie.
+    This indicates the number of COOKIE messages sent to an authoritative server with both a client and a cached server cookie.
 
 ``CookieIn``
-    This indicates the number of COOKIE replies received.
+    This indicates the number of COOKIE replies received from an authoritative server.
 
 ``CookieClientOk``
-    This indicates the number of COOKIE client ok.
+    This indicates the number of correctly formed COOKIE client responses received.
 
 ``BadEDNSVersion``
     This indicates the number of bad EDNS version replies received.
 
 ``BadCookieRcode``
-    This indicates the number of bad cookie rcode replies received.
+    This indicates the number of BADCOOKIE response codes received from an authoritative server.
 
 ``ZoneQuota``
-    This indicates the number of queries spilled due to zone quota.
+    This indicates the number of queries spilled for exceeding the :any:`fetches-per-zone` quota.
 
 ``ServerQuota``
-    This indicates the number of queries spilled due to server quota.
+    This indicates the number of queries spilled for exceeding the :any:`fetches-per-server` quota.
 
 ``ClientQuota``
-    This indicates the number of queries spilled due to clients per query quota.
+    This indicates the number of queries spilled for exceeding the :any:`clients-per-query` quota.
 
 ``NextItem``
-    This indicates the number of waits for next item, when an invalid response is received.
+    This indicates the number of times the server waited for the next item after receiving an invalid response.
 
 ``Priming``
     This indicates the number of priming fetches performed by the resolver.

doc/arm/security.inc.rst

@@ -22,12 +22,12 @@ section, cannot be the basis for CVE assignment or special security-sensitive
 handling of issues.
 
 Unauthorized access can potentially disclose sensitive data, slow down server
-operation, etc. Unauthorized, unexpected, or incorrect writes to listed objects
+operation, etc. Unauthorized, unexpected, or incorrect writes to any of the following listed objects
-can potentically cause crashes, incorrect data handling, or corruption.
+can potentially cause crashes, incorrect data handling, or corruption:
 
 - All files stored on disk - including zone files, configuration files, key
   files, temporary files, etc.
-- Clients communicating via :any:`controls` socket using configured keys
+- Clients communicating via the :any:`controls` socket using configured keys
 - Access to :any:`statistics-channels` from untrusted clients
 - Sockets used for :any:`update-policy` type `external`