Add 'inline-signing yes;' to configuration examples to have working
copy paste configurations.
(cherry picked from commit b13a0c8836d2d8bc5b4de1cdfcdb2057c0bb9d93)
This change was made in !6403, but the appropriate documentation
changes were not applied to the ARM.
(cherry picked from commit 7231383e4cc57caac36d03055e8627b12aa4b91a)
Make documentation building successful even on RHEL9 sphinx 3.4.3. It
does not like case-insensitive matching of terms, so provide lowercase
text description with Uppercase word reference.
(cherry picked from commit bc6c6b1184)
Add more text about the importance of properly securing the statistics
channel and what is and what is not considered a security vulnerability.
(cherry-picked from commit 6869c98d36)
The "max-zone-ttl" option should now be configured as part of
dnssec-policy. Use of this option in zone/view/options will be ignored
in any zone that also has dnssec-policy configured.
Mostly deduplicating and linking information across the ARM.
Generally people should not touch it unless they what they are doing, so
let's try to discourage them a bit.
(cherry picked from commit bffa3063f0)
This is essentially a backport of !6296.
Replace DNSSEC chapter with version from the main branch, commit
901b6425d2.
There were structural changes to the ARM in the main branch, and
replacing the whole file with a new version is an order of magniture
easier than attempting to cherry-pick individual changes which should, in
the end, produce the same file under a different name.
File names in the main branch and v9_16 are now in sync (for the DNSSEC
chapter).
Fixes: #3320
Make clear that inline-signing stores DNSSEC records in a signed
version of the zone, using the zone's filename plus ".signed" extension.
Tell that dynamic zones store updates in the zone's filename.
DNSSEC records for dynamic zones also go in the zone's filename, unless
inline-signing is enabled.
Then, dnssec-policy assumes inline-signing, but only if the zone is
not dynamic.
(cherry picked from commit 8860f6b4ff)
After enormous amount of bikesheding about colors we decided to override
ReadTheDocs default style for literals (``literal`` in the RST markup).
Justification:
- The default RTD "light red literal on white background" is hard to
read. https://webaim.org/resources/contrastchecker/ reports that text
colored as rgb(231, 76, 60) on white background has insufficient
contrast.
- The ARM has enormous amount of literals all over the place and thus
one sentence can contain several black/red/black color changes. This
is distracting. As a consequence, the ARM looks like a Geronimo
Stilton book.
What we experimented with as replacements for red:
- Green - way too distracting
- Blue - too similar to "usual clickable link"
- Violet - too Geronimo Stilton style
- Brown - better but still distracting
After all the bikesheding we settled on black, i.e. the same as all
"normal" text. I.e. the color is now the same and literals are denoted
by monospaced font and a box around the literal. This has best contrast
and is way less distracting than it used to be.
This lead to a new problem: Internal references to "term definitions"
defined using directives like .. option:: were rendered almost the same
as literals:
- References: monospaced + box + bold + clickable
- Literals: monospaced + box To distinguish these two we added black
dotted underline to clickable references.
I hereby declare the bikeshed painted.
(cherry picked from commit 833af31e7b)
RTD style default never wraps <th> and <td> elements and that just does
not work for real sentences or any other long lines.
We can reconsider styling some tables separately, but at the moment we
do not have use for tables with long but unwrappable lines so it's
easier to allow wrapping globally.
(cherry picked from commit a5dd98ac1b)
Remove the line "This address must appear in the secondary server’s
parental-agents zone clause". This line is a copy paste error from
notify-source.
Rewrap.
(cherry picked from commit 313f606692)
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)
Older versions do not have "override" parameter in add_role_to_domain()
function signature. Luckily the override is _not_ required when
overidding the built-in standard domain roles for the first time, so we
just drop the paramter.
Tested with Sphinx 1.6.7 (does not have override) and Sphinx 4.5.0
(does have override).
Fixes: #3294
Related: !6086
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)
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)
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)
