Tweak and reword release notes

doc/notes/notes-9.21.7.rst

@@ -17,44 +17,47 @@ New Features
 
 - Add support for EDE 20 (Not Authoritative)
 
-  Support was added for EDE codes 20 (Not Authoritative) when client
+  Support was added for EDE codes 20 (Not Authoritative) when the client
   requests recursion (RD) but the server has recursion disabled.
 
-  RFC 8914 mention EDE 20 should also be returned if the client doesn't
+  :rfc:`8914` indicates that EDE 20 should also be returned if the
-  have the RD bit set (and recursion is needed) but it doesn't apply for
+  client does not have the RD bit set (and recursion is needed), but it
-  BIND as BIND would try to resolve from the "deepest" referral in
+  does not apply for BIND; BIND would try to resolve from the "deepest"
-  AUTHORITY section. For example, if the client asks for "www.isc.org/A"
+  referral in the AUTHORITY section. For example, if the client asks for
-  but the server only knows the root domain, it will return NOERROR but
+  ``www.isc.org/A`` but the server only knows the root domain, it will
-  no answer for "www.isc.og/A", just the list of other servers to ask.
+  return NOERROR but no answer for ``www.isc.org/A``, just the list of
-  :gl:`#1836`
+  other servers to ask. :gl:`#1836`
 
 - Add support for EDE 7 and EDE 8.
 
   Support was added for EDE codes 7 (Signature Expired) and 8 (Signature
-  Not Yet Valid) which might occur during DNSSEC validation. :gl:`#2715`
+  Not Yet Valid), which might occur during DNSSEC validation.
+  :gl:`#2715`
 
 - Add support for EDNS ZONEVERSION option.
 
-  `dig` and `named` can now make requests with an EDNS `ZONEVERSION`
+  :iscman:`dig` and :iscman:`named` can now make requests with an EDNS
-  option present.
+  ZONEVERSION option present.
 
-  Two new `named.conf` options have been added: `request-zoneversion`
+  Two new :iscman:`named.conf` options have been added:
-  and `provide-zoneversion`.  `request-zoneversion` is `off` by default.
+  :any:`request-zoneversion` and :any:`provide-zoneversion`.
-  `provide-zoneversion` is `on` by default. :gl:`#4767`
+  :any:`request-zoneversion` is ``off`` by default.
+  :any:`provide-zoneversion` is ``on`` by default. :gl:`#4767`
 
-- Dig can now display the received BADVERS message during negotiation.
+- :iscman:`dig` can now display the received BADVERS message during
+  negotiation.
 
-  Dig +showbadvers now displays the received BADVERS message and
+  :option:`dig +showbadvers` now displays the received BADVERS message
-  continues the EDNS version negotiation.  Previously to see the BADVERS
+  and continues the EDNS version negotiation.  Previously, to see the
-  message +noednsneg had to be specified which terminated the EDNS
+  BADVERS message :option:`dig +noednsnegotiation` had to be specified,
-  negotiation.  Additionally the specified EDNS value (+edns=value) is
+  which terminated the EDNS negotiation.  Additionally, the specified
-  now used when making all the initial queries with +trace. i.e EDNS
+  EDNS value (``+edns=value``) is now used when making all the initial
-  version negotiation will be performed with each server when performing
+  queries with :option:`dig +trace`, i.e. EDNS version negotiation is
-  the trace. :gl:`#5234`
+  performed with each server when performing the trace. :gl:`#5234`
 
-- Add an rndc command to reset some statistics counters.
+- Add an :iscman:`rndc` command to reset some statistics counters.
 
-  The new ``reset-stats`` command for ``rndc`` allows some statistics
+  The new :option:`rndc reset-stats` command allows some statistics
   counters to be reset during runtime. At the moment only two
   "high-water" counters are supported, so the ability to reset them
   after the initial peaks during the server's "warm-up" phase may be
@@ -72,22 +75,28 @@ Removed Features
 - Implement the systemd notification protocol manually to remove
   dependency on libsystemd.
 
-- Remove unnecessary options in dnssec-keygen and dnssec-keyfromlabel.
+- Remove unnecessary options in :iscman:`dnssec-keygen` and
+  :iscman:`dnssec-keyfromlabel`.
 
-  The `dnssec-keygen` utility (and `dnssec-keyfromlabel`, which was
+  The :iscman:`dnssec-keygen` utility (and
-  derived from it) had several options dating to the time when keys in
+  :iscman:`dnssec-keyfromlabel`, which was derived from it) had several
-  DNS were still experimental and not fully specified, and when
+  options dating to the time when keys in DNS were still experimental
-  `dnssec-keygen` had the additional function of generating TSIG keys,
+  and not fully specified, and when :iscman:`dnssec-keygen` had the
-  which are now generated by `tsig-keygen`. These options are no longer
+  additional function of generating TSIG keys, which are now generated
-  necessary in the modern DNSSEC environment, and have been removed.
+  by :iscman:`tsig-keygen`. These options are no longer necessary in the
+  modern DNSSEC environment, and have been removed.
 
-  The removed options are: - `-t` (key type), which formerly set flags
+  The removed options are:
-  to disable confidentiality or authentication support in a key; these
+
-  are no longer used. - `-n` (name type), which is now always set to
+  - ``-t`` (key type), which formerly set flags to disable
-  "ZONE" for DNSKEY and "HOST" for KEY. - `-p` (protocol), which is now
+    confidentiality or authentication support in a key; these are no
-  always set to 3 (DNSSEC); no other value has ever been defined. - `-s`
+    longer used.
-  (signatory field), which was never fully defined. - `-d` (digest
+  - ``-n`` (name type), which is now always set to "ZONE" for DNSKEY and
-  bits), which is meaningful only for TSIG keys.
+    "HOST" for KEY.
+  - ``-p`` (protocol), which is now always set to 3 (DNSSEC); no other
+    value has ever been defined.
+  - ``-s`` (signatory field), which was never fully defined.
+  - ``-d`` (digest bits), which is meaningful only for TSIG keys.
 
 Feature Changes
 ~~~~~~~~~~~~~~~
@@ -102,9 +111,9 @@ Feature Changes
 
 - Improve the LRU cache-expiration mechanism.
 
-  Improve the LRU cache-expiration mechanism to a SIEVE-LRU based
+  The LRU cache-expiration mechanism has been improved to a
-  mechanism that triggers when the cache is close to the
+  SIEVE-LRU-based mechanism that triggers when the cache is close to the
-  `max-cache-size` limit.  This improves the recursive server
+  :any:`max-cache-size` limit.  This improves the recursive server's
   performance.
 
 Bug Fixes
@@ -112,69 +121,74 @@ Bug Fixes
 
 - QNAME minimization could leak the query type.
 
-  When performing QNAME minimization, `named` now sends an NS query for
+  When performing QNAME minimization, :iscman:`named` now sends an NS
-  the original query name, before sending the final query. This prevents
+  query for the original query name, before sending the final query.
-  the parent zone from learning the original query type, in the event
+  This prevents the parent zone from learning the original query type,
-  that the query name is a delegation point.
+  in the event that the query name is a delegation point.
 
-  For example, when looking up an address record for `example.com`, NS
+  For example, when looking up an address record for ``example.com``, NS
-  queries are now sent to the servers for both `com` and `example.com`,
+  queries are now sent to the servers for both ``com`` and
-  before the address query is sent to the servers for `example.com`.
+  ``example.com``, before the address query is sent to the servers for
-  Previously, an address query would have been sent to the servers for
+  ``example.com``. Previously, an address query would have been sent to
-  `com`. :gl:`#4805`
+  the servers for ``com``. :gl:`#4805`
 
 - Stop caching lack of EDNS support.
 
-  `named` could falsely learn that a server doesn't support EDNS when  a
+  :iscman:`named` could falsely learn that a server did not support EDNS
-  spoofed response was received; that subsequently prevented DNSSEC
+  when a spoofed response was received; that subsequently prevented
-  lookups from being made.  This has been fixed. :gl:`#3949` :gl:`#5066`
+  DNSSEC lookups from being made.  This has been fixed. :gl:`#3949`
+  :gl:`#5066`
 
-- Fix resolver statistics counters for timed out responses.
+- Fix resolver statistics counters for timed-out responses.
 
   When query responses timed out, the resolver could incorrectly
-  increase the regular responses counters, even if no response was
+  increase the regular response counters, even if no response was
   received. This has been fixed. :gl:`#5193`
 
-- Nested DNS validation could cause assertion failure.
+- Nested DNS validation could cause an assertion failure.
 
   When multiple nested DNS validations were destroyed out of order, the
   EDE context could be freed before all EDE codes were copied, which
   could cause an assertion failure. This has been fixed. :gl:`#5213`
 
-- Ensure max-clients-per-query is at least clients-per-query.
+- Ensure :any:`max-clients-per-query` is at least
+  :any:`clients-per-query`.
 
-  If the `max-clients-per-query` option is set to a lower value than
+  If the :any:`max-clients-per-query` option is set to a lower value
-  `clients-per-query`, the value is adjusted to match
+  than :any:`clients-per-query`, the value is adjusted to match
-  `clients-per-query`. :gl:`#5224`
+  :any:`clients-per-query`. :gl:`#5224`
 
 - Fix write after free in validator code.
 
   Raw integer pointers were being used for the validator's nvalidations
-  and nfails values but the memory holding them could be freed before
+  and nfails values, but the memory holding them could be freed while
-  they ceased to be used.  Use reference counted counters instead.
+  they were still being used. Reference counted counters are now used
-  :gl:`#5239`
+  instead. :gl:`#5239`
 
 - Don't enforce NOAUTH/NOCONF flags in DNSKEYs.
 
-  All DNSKEY keys are able to authenticate. The `DNS_KEYTYPE_NOAUTH`
+  All DNSKEY keys are able to authenticate. The ``DNS_KEYTYPE_NOAUTH``
-  (and `DNS_KEYTYPE_NOCONF`) flags were defined for the KEY rdata type,
+  (and ``DNS_KEYTYPE_NOCONF``) flags were defined for the KEY rdata
-  and are not applicable to DNSKEY. Previously, however, because the
+  type, and are not applicable to DNSKEY. Previously, however, because
-  DNSKEY implementation was built on top of KEY, the `_NOAUTH` flag
+  the DNSKEY implementation was built on top of KEY, the ``_NOAUTH``
-  prevented authentication in DNSKEYs as well. This has been corrected.
+  flag prevented authentication in DNSKEYs as well. This has been
-  :gl:`#5240`
+  corrected. :gl:`#5240`
 
 - Fix several small DNSSEC timing issues.
 
-  The following small issues related to `dnssec-policy` have been fixed:
+  The following small issues related to :any:`dnssec-policy` have been
-  - In some cases the key manager inside BIND 9 could run every hour,
+  fixed:
-  while it could have run less often. - While `CDS` and `CDNSKEY`
+
-  records will be removed correctly from the zone when the corresponding
+  - In some cases the key manager inside BIND 9 would run every hour,
-  `DS` record needs to be updated, the expected timing metadata when
+    while in other cases it would run less often.
-  this will happen was never set. - There were a couple of cases where
+  - While ``CDS`` and ``CDNSKEY`` records will be removed correctly from
-  the safety intervals are added inappropriately, delaying key rollovers
+    the zone when the corresponding ``DS`` record needs to be updated,
-  longer than necessary. - If you have identical `keys` in your
+    the expected timing metadata for when this should happen was never
-  `dnssec-policy`, they may be retired inappropriately. Note that having
+    set.
-  keys with identical properties is discouraged in all cases.
+  - There were a couple of cases where the safety intervals were added
+    inappropriately, delaying key rollovers longer than necessary.
+  - Identical keys in a :any:`dnssec-policy` may have been
+    retired inappropriately. Note that having `keys` with identical
+    properties is discouraged in all cases.
+
   :gl:`#5242`
-
-