All statements now use .. namedconf:statement:: or
.. rndcconf:statement:: syntax provided by our Sphinx extension.
This has several consequences:
- It changes how statement headings are rendered
- Statements are indexed and show up as separate items in doc
search results (in the HTML version)
- Statements can be linked to using either :any:`statement` or
:namedconf:ref:`statement` syntax (not used in this commit)
- Statements can be categorized and printed using ..
namedconf:statatementlist:: syntax (not used in this commit)
(cherry picked from commit e5b7022dcb)
To give a hint to users that get an error that the key lifetime is
shorter than the time it takes to do a rollover.
(cherry picked from commit c47735b86b)
Warn users that server-side IP addresses are not stored in dnstap
captures of resolver traffic unless "query-source(-v6)" is explicitly
set, explaining why it is so.
(cherry picked from commit 366f7a938b)
The two procedures were essentially the same, but each instance was
missing some details from the other. They are now combined into one text
in the DNSSEC Guide and linked from DNSSEC chapter.
(cherry picked from commit 7d25027898)
Private Type Records are not specific to manually signing, so it is
better to move it to the end of the "Zone Signing" section shared by all
three methods.
(cherry picked from commit 5ba618fd28)
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)
Let's make more automated methods more prominent:
- KASP first
- dynamic updates second
- command-line tools only as last resort
(cherry picked from commit 28a533322b)
The goal is simplicity. Copy&paste to do the right thing, or read
referenced material and make up your mind if you need specialities.
NSEC discussion is already present in the DNSSEC guide so I merged
KASP examples with example for NSEC3 and removed NSEC text from the
DNSSEC chapter.
(cherry picked from commit 744763f8f2)
I've attempted to drop most of DNSSEC-specific jargon from the intro
paragraph, and to convince readers to read on.
(cherry picked from commit 0dc9c33149)
Use best practice values in examples that follow new guidance from
draft-ietf-dnsop-nsec3-guidance:
; SHA-1, no extra iterations, empty salt:
;
bcp.example. IN NSEC3PARAM 1 0 0 -
(cherry picked from commit 93601d8325)
Move this section up so that DNSSEC signing topics are grouped together
(and not split by the DNSSEC Validation chapter).
(cherry picked from commit 7824c5c967)
Restructure the section about dynamic zones and automatic signing:
- Focus on dynamic zones with 'auto-dnssec allow;'.
- Add a section about multi-signer models.
- Move NSEC3 related topics into one section.
- Remove any text that does not concern dynamic zones (mostly duplicate
text anyway).
(cherry picked from commit be54c08d2b)
Move bits from the "DNSSEC, Dynamic Zones, and Automatic Signing"
about denial of existence to a separate section below the "Key and
Signing Policy" section.
Add a brief introduction about denial of existence to this section.
(cherry picked from commit 71490a5a2d)
Restructure the first part of the DNSSEC chapter that deals with zone
signing. Put dnssec-policy first. Mention Key and Signing Policy.
Only then talk about the DNSSEC tools.
(cherry picked from commit a1c95e8e7c)
DNSSEC-bis is an uncommon term. Other servers are typically resolvers
and they usually are configured with the root key.
(cherry picked from commit fb24454c58)
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)
Introduce a new syntax:
.. namedconf:statementlist::
:filter_tags: acl, resolver
The resulting table contains only items tagged as acl OR resolver.
(cherry picked from commit 33931c97fa)
It turns out it is easier to regenerate Sphinx-mandated structure in
get_objects than to maintain two separate data structures. I should have
realized that before.
(cherry picked from commit 2f2aa1d21c)
New directive .. statementlist:: generates table of statements in a
the given domain (named.conf or rndc.conf). The table contains link to
definition, short description, and also list of tags.
Short description and tags have to be provided by user using optional
parameters. E.g.:
.. statement:: max-cache-size
:tags: resolver, cache
:short: Short description
.. statementlist:: is currently not parametrized.
This modification is based on Sphinx "tutorial" extension "TODO".
The main trick is to use placeholder node for .. statementlist:: and
replace it with table at later stage, when all source files were
processed and all cross-references can be resolved.
Beware, some details in Sphinx docs are not up-to-date, it's better
to read Sphinx and docutil sources.
(cherry picked from commit 976aef030a)
New and currently unused values can be provided using this syntax:
.. statement:: max-cache-size
:tags: resolver, cache
:short: Short description
The domain stores them in its internal structures for further use.
(cherry picked from commit b12606cebe)
The extension provides a "Sphinx domain factory". Each new Sphinx domain
defines a namespace for configuration statements so named.conf and
rndc.conf do not clash. Currently the Sphinx domains are instantiated
twice and resuling domains are named "namedconf" and "rndcconf".
This commit adds a single new directive:
.. statement:: max-cache-size
It is namespaced like this:
.. namedconf:statement:: max-cache-size
This directive generates a new anchor for configuration statement and it
can be referenced like :any:`max-cache-size` (if the identifier is
unique), or more specific :namedconf:ref:`max-cache-size`.
It is based on Sphinx "tutorial" extension "recipe".
Beware, some details in Sphinx docs are not up-to-date, it's better
to read Sphinx and docutil sources.
(cherry picked from commit a23fa7edc9)
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)
Ron AitchisonandPetr Špaček
Matthijs Mekking
Michał Kępień
Suzanne GoldlustandMatthijs Mekking
Michal Nowak
Tom Krizek