This commit updates the reference manual with short descriptions of
different TLS authentication modes, as mentioned in the RFC 9103,
Section 9.3 (Opportunistic TLS, Strict TLS, Mutual TLS), and mentions
how these authentication modes can be achieved via BIND's
configuration file.
This commit adds support for Strict/Mutual TLS into BIND. It does so
by implementing the backing code for 'hostname' and 'ca-file' options
of the 'tls' statement. The commit also updates the documentation
accordingly.
This seems to be most appropriate way to ensure consistency between
release tarballs and public presentation on ReadTheDocs.
Previous attempt with removing docutils constraint, which relied on pip
depedency solver to pick the same packages as in CI was flawed. RTD
installs a bit different set of packages so it was inherently
unreliable.
As a result RTD pulled in sphinx-rtd-theme==0.4.3 while CI
had 1.0.0, and this inconsistency caused Table of Contents in Release
Notes to render incorrectly. Previous solution was to downgrade
docutils to < 0.17, but I think we should rather pin exact versions.
For the long history of messing with versions read also
isc-projects/bind9@2a8eda0084isc-projects/images@d4435b97beisc-projects/bind9@6a2daddf5b
(cherry picked from commit 6088ba3837)
Currently our CI images we use to build docs (which subsequently get
into release tarballs) are using docutils 0.17.1, which is latest version
which fulfills Sphinx 4.5.0 requirement for docutils < 0.18.
The old requirement for docutils < 0.17 was causing discrepancy between
the way we build release artifacts and the docs on ReadTheDocs.org which
uses doc/arm/requirements.txt from our repo.
Remove the limit for RDT with hope that it will pull latest permissible
version of docutils.
For the long history of messing with docutils version read also
isc-projects/images@d4435b97beisc-projects/bind9@6a2daddf5b
(cherry picked from commit 2a8eda0084)
Catalog zones change of ownership is special mechanism to facilitate
controlled migration of a member zone from one catalog to another.
It is implemented using catalog zones property named "coo" and is
documented in DNS catalog zones draft version 5 document.
Implement the feature using a new hash table in the catalog zone
structure, which holds the added "coo" properties for the catalog zone
(containing the target catalog zone's name), and the key for the hash
table being the member zone's name for which the "coo" property is being
created.
Change some log messages to have consistent zone name quoting types.
Update the ARM with change of ownership documentation and usage
examples.
Add tests which check newly the added features.
(cherry picked from commit bb837db4ee)
According to DNS catalog zones draft version 5 document, catalog
zone custom properties must be placed under the "ext" label.
Make necessary changes to support the new custom properties syntax in
catalog zones with version "2" of the schema.
Change the default catalog zones schema version from "1" to "2" in
ARM to prepare for the new features and changes which come starting
from this commit in order to support the latest DNS catalog zones draft
document.
Make some restructuring in ARM and rename the term catalog zone "option"
to "custom property" to better reflect the terms used in the draft.
Change the version of 'catalog1.zone.' catalog zone in the "catz" system
test to "2", and leave the version of 'catalog2.zone.' catalog zone at
version "1" to test both versions.
Add tests to check that the new syntax works only with the new schema
version, and that the old syntax works only with the legacy schema
version catalog zones.
(cherry picked from commit cedfebc64a)
After some back and forth, it was decidede to match the configuration
option with unbound ("so-reuseport"), PowerDNS ("reuseport") and/or
nginx ("reuseport").
(cherry picked from commit 7e71c4d0cc)
Previously, the option to enable kernel load balancing of the sockets
was always enabled when supported by the operating system (SO_REUSEPORT
on Linux and SO_REUSEPORT_LB on FreeBSD).
It was reported that in scenarios where the networking threads are also
responsible for processing long-running tasks (like RPZ processing, CATZ
processing or large zone transfers), this could lead to intermitten
brownouts for some clients, because the thread assigned by the operating
system might be busy. In such scenarious, the overall performance would
be better served by threads competing over the sockets because the idle
threads can pick up the incoming traffic.
Add new configuration option (`load-balance-sockets`) to allow enabling
or disabling the load balancing of the sockets.
(cherry picked from commit 85c6e797aa)
While backporting !5934 I noticed a copy&paste mistake in TSIG
chapter of the ARM.
The incorrect reference was introduced by "Add hyperlinks from
program options to definition in man pages" commit but it is not
worth creating separate MR for that when the backport is not merged
yet.
Use the new role :iscman: to replace all occurences or ``binary``
with :iscman:`binary`, creating a hyperlink to the manual page.
Generated using:
find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs
for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done
Additional hand-edits were done mainly around filter-aaaa and
filter-a which are program names and and option names at the
same time. Couple more edits was neede to fix .rst syntax broken by
automatic replacement.
(cherry picked from commit 53a5776025)
The new directive and role "iscman" allow to tag & reference man pages in
our source tree. Essentially it is just namespacing for ISC man pages,
but it comes with couple benefits.
Differences from .. _man_program label we formerly used:
- Does not expand :ref:`man_program` into full text of the page header.
- Generates index entry with category "manual page".
- Rendering style is closer to ubiquitous to the one produced
by ``named`` syntax.
Differences from Sphinx built-in :manpage: role:
- Supports all builders with support for cross-references.
- Generates internal links (unlike :manpage: which generates external
URLs).
- Checks that target exists withing our source tree.
(cherry picked from commit 7e7a946d44)
Side-effect of hyperlinking is that typos in program and option names
are now detected by Sphinx.
Candidate -options were detected using:
find -name *.rst | xargs grep '``-[^`]'
and then modified from ``-o`` to :option:`-o` using regex
s/``\(-[^`]\+\)``/:option:`\1`/
+ manual modifications where necessary.
Non-hyphenated options were detected by looking at context around
program names:
find bin -name *.rst | xargs -I{} -n1 basename {} .rst | sort -u
and grepping for program name with trailing whitespace.
Stand-alone program names like ``named`` are not hyperlinked in this
commit.
(cherry picked from commit a85df3ff9c)
Remove outdated command references from ARM section
3.3.1. Tools for Use With the Name Server Daemon
and replace them with links to man pages.
Fixes: #2799
(cherry picked from commit 2d2d87a615)
Both utilities were included as one man page, but this caused a problem:
Sphinx directive .. include was used twice on the same file, which
prevented us from using labels (or anything with unique identifier) in
the man pages. This effectivelly prevented linking to them.
Splitting man pages allows us to solve the linking problems and also
clearly make text easier to follow because it does not mention two tools
at the same time.
This change causes duplication of text, but given the frequecy of changes
to these tools I think it is acceptable. I've considered deduplication
using smaller .rst snippets which get included into both man pages,
but it would require more sed scripting to handle defaults etc. and
I think it would be way too complex solution for this problem.
Related: #2799
(cherry picked from commit 9992f7808c)
Both utilities were included as one man page, but this caused a problem:
Sphinx directive .. include was used twice on the same file, which
prevented us from using labels (or anything with unique identifier) in
the man pages. This effectivelly prevented linking to them.
Splitting man pages allows us to solve the linking problems and also
clearly make text easier to follow because it does not mention two tools
at the same time.
This change causes duplication of text, but given the frequecy of changes
to these tools I think it is acceptable.
Related: #2799
(cherry picked from commit 2e42414522)
we now document zone type as either "primary" or "secondary",
omitting the old terms (though they are still accepted).
(cherry picked from commit 0bde07261b)
Add a note to the DNSSEC guide and to the ARM reference that A ZSK/KSK
pair used for signing your zone should have the same algorithm.
This commit also updates the 'dnssec-policy/keys' example to use the
slightly more modern 'rsasha256' algorithm.
(cherry picked from commit 7365400610)
For users it's not really important if a RFC is Internet Standard,
Proposed Standard, or Experimental. RFCs are now regrouped by
"Protocol", Best Current Practice, and "catch all" category FYI.
(cherry picked from commit 7fd61f9403)
In 2022, IPv6 is not anything unusual, and it was really odd
to have it in a separate section next to a huge list of RFCs.
Fixes: #1918
(cherry picked from commit 2774b497a6)
There is little point of listing all of the obsolete RFCs. I think it is
more likely confuse people than to do anything useful.
(cherry picked from commit 9437ea08e1)
Replace the hard-coded paths for various BIND 9 files (configuration,
pid, etc.) in the man pages and ARM with compile-time values using the
sphinx-build replace system.
This is more complicated, because the restructured text specification
doesn't allow |substitions| inside ``code-blocks``, so for each specific
file we had to create own substition which is sub-optimal, but it is
only way how to do this without adding Sphinx extension.
(cherry picked from commit b42681c4e9)
The "directory" configuration options affects the configuration listed
after the directive but not before which may affect ``include``
directive with relative file paths.
(cherry picked from commit 00ba6967b1)
Formerly parental-agents grammar was an exception and it did not
auto-generate itself from source code. From now on it is generated using
the same mechanism as other grammars.
For consistency with rest of the system, I've also renamed the grammar
file and the link anchors from "parentals" to "parental-agents".
Technically this is fixup for commit
0311705d4b.
Related: !5234
(cherry picked from commit 34a3b35b08)
In the RPZ documentation, there's a mistake where it states that the
default behavior will be disabled by setting `qname-wait-recurse yes;`
while in fact it's opposite `qname-wait-recurse no;`.
This affects only the RST documentation.
(cherry picked from commit 1e711dcccb)
The keyfromlabel system ECDSA tests sometimes fail. When this happens
the ZSK and KSK key id values differ by 1, which is an indication that
the same key is used for both DNSKEY records.
When the private key is retrieved with 'ENGINE_load_private_key()', the
public key is already set. But sometimes that key differs from the key
which was retrieved with 'ENGINE_load_public_key()'.
The libp11 source code uses id to find the key and without IDs all the
keys are "equal", so it is returning the first key in the array of the
enumerated keys instead of the matching key. In our test we didn't use
'--id', just '--label'. With this change, the system test should no
longer fail intermittently.
Note this is only an issue for ECDSA keys, not RSA keys.
(cherry picked from commit 0af8bbd49b)
We started with compilation of _all_ 9.17.z notes into one file:
$ ls *.17*.rst | sort -V | xargs cat > notes-9.18.0.rst
Then removed removed duplicate extra copyright headers:
$ grep -v '^\.\. [^_]' notes-9.18.0.rst > notes-9.18.0.rst.copy
$ grep -v '^\.\.$' notes-9.18.0.rst.copy > notes-9.18.0.rst
$ vim notes-9.17.0.rst notes-9.18.0.rst
Next step was to find notes referencing the changes which were
backported to 9.16.25 and remove these. Duplicites were checked
by diffing corresponding texts in 9.16 and 9.17, and it revealed that
some backports were either partial, or code was backported but the
release note was lost in 9.16 branch. In that case we did not
re-introduce the relnote and considered it also duplicate.
Most notable cases of "missing in 9.16 relnote but in fact fixed"
were notes for CVE-2020-8616 and CVE-2020-8617.
These were accidentally omitted from 9.16 release docs, and we are going
to fix it in separate MR !5722.
Further removals include:
- Security issue #2787: The bug was introduced & fixed in 9.17.z,
so there is no need to tell about it to people upgrading to 9.18.0.
- Bugfix !3135: Backported but with unclear reference in relnotes.
- Bugfix !3137: Backported but with unclear reference in relnotes.
- Bugfix #2460: Introduced & fixed in 9.17.z.
- Bugfix #2504: The bug was introduced & fixed in 9.17.z.
- Bugfix #2562: Introduced & fixed in 9.17.z.
- Bugfix #2917: Introduced & fixed in 9.17.z
- Bugfix #3040: Introduced & fixed in 9.17.z.
- Bugfix #3062: Introduced & fixed in 9.17.z.
- Change #4: Introduced & "finished" in 9.17.z.
- Change #1610: Introduced & reverted in 9.17.z.
- Change #1958: No user visible impact.
- Change #2016: No user visible impact.
- Change #2022: No user visible impact.
- Change #2264: Affects a feature introduced only to 9.17 branch.
- Change #2401: No user visible impact.
- Known issue about libuv: Got fixed later in the cycle.
- Known issue about port clash: It is now config error.
Then tweaking started to clarify meaning of various notes to people
upgrading from 9.16.
While doing so, bugfix #2927 was omited because the change just makes
9.18 SERVFAIL faster than 9.16, so even though it is technically bugfix
it is so minor that it is not worth bragging about in release notes.
TLS/DoT/DoH features were summarized from many independent
notes into one giant note per feature.
All notes were rearranged according to their "perceived priority".
There were three RFCs listed in list of "RFCs we implement" but missing
in the ARM.
Command to compare lists in the two documents:
diff <(grep -o '^ RFC[0-9]\+' doc/misc/rfc-compliance | sed -e 's/[^0-9]//g' | sort -n) <(grep '^:rfc:`' doc/arm/general.rst | sed -e 's/^.*`\([0-9]*\)`.*$/\1/' | sort -n)
