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)
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)
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)
For consistency with rest of the system, the grammar file and
the link anchors were renamed from "parentals" to "parental-agents".
Technically this is fixup for commit
90ef2b9c81.
Related: !5239
(reimplementation of 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)
This commit partially removes extra RFCs which are not listed in
file doc/misc/rfc-compliance.
Most of the removed RFCs are either outright obsolete, irrelevant,
or not implemented. Rationale:
- 974 - obsolete
- 1033 - ops info, hardly followed today
- 1464 - ops info
- 1591 - policy
- 1537 - obsolete
- 1713 - obsolete
- 1794 - notimp
- 2010 - ops info
- 2052 - obsolete
- 2065 - obsolete
- 2137 - obsolete
- 2168 - obsolete
- 2240 - obsolete
- 2345 - not dns
- 2352 - not dns
- 2540 - notimp
- 2825 - notimp, info, obsolete
- 2826 - notimp
- 2929 - obsolete
- 3071 - policy
- 3090 - obsolete
- 3258 - notimp
- 6594 - iana, SSHFP
- 7216 - not dns
- 8482 - notimp
- 8490 - notimp
Probably most notable RFCs removed are:
- 8482 for special ANY handling
- 8490 for Stateful Operations
As far as I can tell BIND does not implement those.
(cherry-picked from commit 8c82b0f2d0)
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)
(cherry-picked from commit b1af79acc7)
Supported Platforms section is now really only about platforms and not
libraries. Libraries were moved to the Building BIND section.
We now have section for required libraries, and second with optional
features. Wordy explanations were taken verbatim from the original
README.md.
(cherry-picked from commit 2c81fa9013)
Converted using pandoc 2.14.2-14 on Arch Linux:
$ pandoc --shift-heading-level-by=-1 -f markdown -t rst README.md > doc/arm/build.rst
Plus hand-edit to remove sections other than Building BIND 9, remove
misindentation in section headers, and add a standard copyright header.
