diff --git a/doc/arm/build.inc.rst b/doc/arm/build.inc.rst index e9b18bbdf5..10dd3eaddd 100644 --- a/doc/arm/build.inc.rst +++ b/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 -recommended. On older systems, an updated ``libuv`` package needs to be -installed from sources such as EPEL, PPA, or other native sources. The other +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 +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 diff --git a/doc/arm/catz.inc.rst b/doc/arm/catz.inc.rst index c22a6ff078..14121f6ee2 100644 --- a/doc/arm/catz.inc.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/arm/intro-security.inc.rst b/doc/arm/intro-security.inc.rst index 87db9701da..2137a29bc3 100644 --- a/doc/arm/intro-security.inc.rst +++ b/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`. +``named.conf`` :ref:`statements, TSIG cryptographic methods, or TLS`. 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 ` 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. diff --git a/doc/arm/pkcs11.inc.rst b/doc/arm/pkcs11.inc.rst index 2cf848a59d..47a3298cb2 100644 --- a/doc/arm/pkcs11.inc.rst +++ b/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 -your convenience: +`provider-pkcs11.7`_ manual page, but a sample working configuration is included +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 -have a BIND 9 installed, either from a package, or from the sources, and the +HSM keys can now be created and used. We are assuming that +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=/``, f.e.: +NOTE: a PIN stored on disk can be used by specifying ``pin-source=/``, 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, -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 -this is when creating ECDSA keys, you should specify a unique ID: +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 +a key it returns the first key, rather than the matching key. To work around +this when creating ECDSA keys, specify a unique ID: :: diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 4519d20944..294276f046 100644 --- a/doc/arm/reference.rst +++ b/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 - ``tcp-idle-timeout``, the ``max-transfer-idle-in`` will close the - inbound zone transfer if there was no complete AXFR or no complete - IXFR chunk. The ``tcp-idle-timeout`` will close the connection if - there's no progress on the TCP level. + .. note:: Inbound zone transfers are also affected by + ``tcp-idle-timeout``; ``max-transfer-idle-in`` closes the + inbound zone transfer if there is no complete AXFR or no complete + IXFR chunk. ``tcp-idle-timeout`` closes the connection if + 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 - 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 + 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 + 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 - 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 + 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 + 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 - lower or equal TTL value is encountered during query processing, it is + of the current query takes place; when a cache record with an + 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 -authentification of the transmission channel. That might be enough in +certificates; they provide encryption of the traffic but no +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` - (maximum) and :any:`signatures-validity` minus :any:`signatures-jitter` - (minimum). The default jitter is 12 hours and the configured value must - be lower than :any:`signatures-validity` and + newly generated signature is in the range between :any:`signatures-validity` + (maximum) and :any:`signatures-validity`, minus :any:`signatures-jitter` + (minimum). The default jitter is 12 hours, and the configured value must + 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. diff --git a/doc/arm/security.inc.rst b/doc/arm/security.inc.rst index 878fa379fe..45c22d29de 100644 --- a/doc/arm/security.inc.rst +++ b/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 -can potentically cause crashes, incorrect data handling, or corruption. +operation, etc. Unauthorized, unexpected, or incorrect writes to any of the following listed objects +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`