upstream/bind9
1
0
Fork 0
mirror of https://github.com/isc-projects/bind9.git synced 2026-05-28 04:34:54 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

chg: doc: Review BIND ARM (9.18 updates)

Browse source 
Closes #4832

Merge branch '4832-bind-arm-review-from-2022-through-9-18' into 'bind-9.18'

See merge request isc-projects/bind9!9375
This commit is contained in:
Nicki Křížek 2024-09-11 13:55:49 +00:00
commit f6cc09779a
6 changed files with 71 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
doc/arm/build.inc.rst
View file

@ -60,11 +60,11 @@ To build BIND 9, the following packages must be installed:
- ``perl``
- ``pkg-config`` / ``pkgconfig`` / ``pkgconf``
BIND 9.18 requires ``libuv`` 1.0.0 or higher, using ``libuv`` >= 1.40.0
BIND 9.18 requires ``libuv`` 1.0.0 or higher; using ``libuv`` >= 1.40.0
is recommended. Compiling or running with ``libuv`` 1.35.0 or 1.36.0 is
not supported, as this could lead to an assertion failure in the UDP
receive code. On older systems, an updated ``libuv`` package needs to be
installed from sources such as EPEL, PPA, or other native sources. The
receive code. 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.0.2e or newer is required. If the OpenSSL library is installed

2
doc/arm/catz.inc.rst
View file

@ -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
~~~~~~~~~~~~~~~~~~~~~~

4
doc/arm/intro-security.inc.rst
View file

@ -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.

28
doc/arm/pkcs11.inc.rst
View file

@ -86,8 +86,8 @@ Using the HSM
^^^^^^^^^^^^^
The canonical documentation for configuring engine_pkcs11 is in the
`libp11/README.md`_, but here's copy of working configuration for
your convenience:
`libp11/README.md`_ file, but a sample working configuration is included
here for the user's convenience:
.. _`libp11/README.md`: https://github.com/OpenSC/libp11/blob/master/README.md#pkcs-11-module-configuration
@ -134,8 +134,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``.
For generating the keys, we are going to use ``pkcs11-tool`` available from the
@ -154,11 +154,11 @@ label to reference the private key.
Convert the RSA keys stored in the HSM into a format that BIND 9 understands.
The :iscman:`dnssec-keyfromlabel` tool from BIND 9 can link the raw keys stored in the
HSM with the ``K<zone>+<alg>+<id>`` files. You'll need to provide the OpenSSL
HSM with the ``K<zone>+<alg>+<id>`` files. The OpenSSL
engine name (``pkcs11``), the algorithm (``RSASHA256``) and the PKCS#11 label
that specify the token (we asume that it has been initialized as bind9), the
name of the PKCS#11 object (called label when generating the keys using
``pkcs11-tool``) and the HSM PIN.
that specify the token (we assume that it has been initialized as ``bind9``), the
name of the PKCS#11 object (called "label" when generating the keys using
``pkcs11-tool``), and the HSM PIN must all be provided.
Convert the KSK:
@ -172,7 +172,7 @@ and ZSK:
dnssec-keyfromlabel -E pkcs11 -a RSASHA256 -l "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:
::
@ -184,7 +184,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:
::
@ -199,10 +199,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:
::

96
doc/arm/reference.rst
View file

@ -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.
@ -1028,7 +1028,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
@ -1064,9 +1064,9 @@ where ``tls-configuration-name`` refers to a previously defined
.. warning::
Please note that this version of BIND 9 does not support dynamic updates
forwarding (see :any:`allow-update-forwarding`) in conjuction with zone
transfers over TLS (XoT), that is when the :any:`tls` keyword is used with
Please note that this version of BIND 9 does not support dynamic update
forwarding (see :any:`allow-update-forwarding`) in conjunction with zone
transfers over TLS (XoT). This includes when the :any:`tls` keyword is used with
:any:`primaries`, e.g. ``primaries { 192.0.2.1 tls tls-configuration-name; };``.
``options`` Block Grammar
@ -2146,7 +2146,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
@ -3376,7 +3376,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.
@ -3480,11 +3480,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
@ -3696,8 +3696,8 @@ amount. ``default`` uses the limit that was in force when the server was
started. See the description of :term:`size`.
The following options are deprecated in favor of setting the operating system
resource limits from the operating system and/or process supervisor, should not
be used, and will be rendered non-operational in a future release.
resource limits from the operating system and/or process supervisor. They should not
be used and will be rendered non-operational in a future release.
.. namedconf:statement:: coresize
@ -3770,7 +3770,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`
@ -3778,14 +3778,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
@ -3805,7 +3805,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
@ -4009,7 +4009,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
@ -4093,7 +4093,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``.
.. _intervals:
@ -4601,13 +4601,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
@ -4735,8 +4735,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
@ -6111,8 +6111,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
@ -6120,9 +6120,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.
@ -6571,14 +6571,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
@ -8225,40 +8225,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.

6
doc/arm/security.inc.rst
View file

@ -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`