All footnotes need to have unique name and be referenced

With Sphinx 8.1.0, footnotes can't stand on their own and have to be
referenced from somewhere, otherwise build fails, e.g.:

    doc/dnssec-guide/signing.rst:1470: WARNING: Footnote [#] is not referenced. [ref.footnote]

(cherry picked from commit bdf8859e2d)
This commit is contained in:
Michal Nowak
2024-10-17 19:49:17 +02:00
parent 653b200151
commit be23cd6af0
5 changed files with 40 additions and 38 deletions

View File

@@ -1009,13 +1009,14 @@ Below are a few challenges and disadvantages that DNSSEC faces.
6. *Not enough people are using it today*: While it's estimated (as of
mid-2020) that roughly 30% of the global Internet DNS traffic is
validating [#]_ , that doesn't mean that many of the DNS zones are
actually signed. What this means is, even if your company's zone is
signed today, fewer than 30% of the Internet's servers are taking
advantage of this extra security. It gets worse: with less than 1.5%
of the ``com.`` domains signed, even if your DNSSEC validation is enabled today,
it's not likely to buy you or your users a whole lot more protection
until these popular domain names decide to sign their zones.
validating, [#apnic_validating_stats]_ that doesn't mean that many of
the DNS zones are actually signed. What this means is, even if your
company's zone is signed today, fewer than 30% of the Internet's
servers are taking advantage of this extra security. It gets worse:
with less than 1.5% of the ``com.`` domains signed, even if your
DNSSEC validation is enabled today, it's not likely to buy you or
your users a whole lot more protection until these popular domain
names decide to sign their zones.
The last point may have more impact than you realize. Consider this:
HTTP and HTTPS make up the majority of traffic on the Internet. While you may have
@@ -1030,6 +1031,6 @@ CNAME to ``foo.random-cloud-provider.com``. As long as
fully validate everything when they visit your web page and could be
redirected elsewhere by a cache poisoning attack.
.. [#]
.. [#apnic_validating_stats]
Based on APNIC statistics at
`<https://stats.labs.apnic.net/dnssec/XA>`__

View File

@@ -346,7 +346,7 @@ want to consider deploying DNSSEC:
implementing DNSSEC, if your organization is subject to compliance
standards that mandate it. For example, the US government set a
deadline in 2008 to have all ``.gov`` subdomains signed by
December 2009 [#]_. So if you operate a subdomain in ``.gov``, you
December 2009. [#omb_memo]_ So if you operate a subdomain in ``.gov``, you
must implement DNSSEC to be compliant. ICANN also requires
that all new top-level domains support DNSSEC.
@@ -369,7 +369,7 @@ want to consider deploying DNSSEC:
infrastructure. To take a peek at these next-generation DNS features,
check out :ref:`introduction_to_dane`.
.. [#]
.. [#omb_memo]
The Office of Management and Budget (OMB) for the US government
published `a memo in
2008 <https://georgewbush-whitehouse.archives.gov/omb/memoranda/fy2008/m08-23.pdf>`__,

View File

@@ -560,7 +560,8 @@ since this new KSK is not active yet. You can do it
immediately after the new DS record has been generated on December 1,
or you can wait until the next day after you have verified that the
new DNSKEY record is added to the zone. Below are some screenshots from
GoDaddy's web-based interface, used to add a new DS record [#]_.
GoDaddy's web-based interface, used to add a new DS record.
[#godaddy_iface_note]_
1. After logging in, click the green "Launch" button next to the domain
name you want to manage.
@@ -761,7 +762,7 @@ Congratulations, the KSK rollover is complete! As for the actual key
files (ending in ``.key`` and ``.private``), they may be deleted at this
point, but they do not have to be.
.. [#]
.. [#godaddy_iface_note]
The screenshots were taken from GoDaddy's interface at the time the
original version of this guide was published (2015). It may have
changed since then.

View File

@@ -439,8 +439,9 @@ Look for Signatures in Your Zone
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Another way to see if your zone data is signed is to check for the
presence of a signature. With DNSSEC, every record [#]_ now comes with at
least one corresponding signature, known as an RRSIG.
presence of a signature. With DNSSEC, every record
[#every_record_signed]_ now comes with at least one corresponding
signature, known as an RRSIG.
::
@@ -552,7 +553,7 @@ containing the information we uploaded in
;; ANSWER SECTION:
example.com. 61179 IN DS 10376 13 2 B92E22CAE0B41430EC38D3F7EDF1183C3A94F4D4748569250C15EE33B8312EF0
.. [#]
.. [#every_record_signed]
Well, almost every record: NS records and glue records for
delegations do not have RRSIG records. If there are
no delegations, then every record in your zone is
@@ -885,7 +886,7 @@ Working with the Parent Zone (2)
Once the zone is signed, the only required manual tasks are
to monitor KSK or CSK key rolls and pass the new DS record to the
parent zone. However, if the parent can process CDS or CDNSKEY records,
you may not even have to do that [#]_.
you may not even have to do that. [#parent_zone_security_considerations]_
When the time approaches for the roll of a KSK or CSK, BIND adds a
CDS and a CDNSKEY record for the key in question to the apex of the
@@ -939,7 +940,7 @@ your zone, presumably using the same mechanism you used to upload the
records for the first time. Again, you need to use the :iscman:`rndc` tool
to tell :iscman:`named` that the DS record has been published.
.. [#]
.. [#parent_zone_security_considerations]
For security reasons, a parent zone that supports CDS/CDNSKEY may require
the DS record to be manually uploaded when we first sign the zone.
Until our zone is signed, the parent cannot be sure that a CDS or CDNSKEY
@@ -1038,8 +1039,9 @@ ending in ``.private`` are the private keys, and contain the information
that :iscman:`named` actually uses to sign the zone.
Of the two pairs, one is the zone-signing key (ZSK), and one is the
key-signing key (KSK). We can tell which is which by looking at the file
contents (the actual keys are shortened here for ease of display):
key-signing key (KSK). [#signal_zone_presence]_ We can tell which is
which by looking at the file contents (the actual keys are shortened
here for ease of display):
.. code-block:: console
@@ -1089,11 +1091,13 @@ information in the key files, you can implement any DNSSEC policy you want for
your zones.
All the dates are the same, and are the date and time that
:iscman:`dnssec-keygen` created the key. We can use :iscman:`dnssec-settime` to
modify the dates [#]_. For example, to publish this key in
the zone on 1 July 2020, use it to sign records for a year starting on
15 July 2020, and remove it from the zone at the end of July 2021, we
can use the following command:
:iscman:`dnssec-keygen` created the key. We can use
:iscman:`dnssec-settime` to modify the dates. The dates can also be
modified using an editor, but that is likely to be more error-prone than
using :iscman:`dnssec-settime`. For example, to publish this key in the
zone on 1 July 2020, use it to sign records for a year starting on 15
July 2020, and remove it from the zone at the end of July 2021, we can
use the following command:
.. code-block:: console
@@ -1193,11 +1197,7 @@ Finally, we should note that the :iscman:`dnssec-keygen` command supports the
same set of switches so we could have set the dates
when we created the key.
.. [#]
The dates can also be modified using an editor, but that is likely to
be more error-prone than using :iscman:`dnssec-settime`.
.. [#]
.. [#signal_zone_presence]
Only one key file - for either a KSK or ZSK - is needed to signal the
presence of the zone. :iscman:`dnssec-keygen` creates files of both
types as needed.

View File

@@ -76,13 +76,13 @@ not loading; or the web browser returning an error message indicating
that the page cannot be displayed. For example, if root name
servers were misconfigured with the wrong information about ``.org``, it
could cause all validation for ``.org`` domains to fail. To end
users, it would appear that all ``.org`` web
sites were out of service [#]_. Should you encounter DNSSEC-related problems, don't be
tempted to disable validation; there is almost certainly a solution that
leaves validation enabled. A basic troubleshooting guide can be found in
:ref:`dnssec_troubleshooting`.
users, it would appear that all ``.org`` web sites were out of service.
[#wrong_root_addr]_ Should you encounter DNSSEC-related problems, don't
be tempted to disable validation; there is almost certainly a solution
that leaves validation enabled. A basic troubleshooting guide can be
found in :ref:`dnssec_troubleshooting`.
.. [#]
.. [#wrong_root_addr]
Of course, something like this could happen for reasons other than
DNSSEC: for example, the root publishing the wrong addresses for the
``.org`` nameservers.
@@ -400,7 +400,7 @@ Let's discuss the difference between *yes* and *auto*. If set to
using the :any:`trust-anchors` statement (with either the ``static-key`` or
``static-ds`` modifier) in the configuration file; if set to
*auto* (the default, and as shown in the example), then no further
action should be required as BIND includes a copy [#]_ of the root key.
action should be required as BIND includes a copy [#root_zone_key_update]_ of the root key.
When set to *auto*, BIND automatically keeps the keys (also known as
trust anchors, discussed in :ref:`trust_anchors_description`)
up-to-date without intervention from the DNS administrator.
@@ -646,7 +646,7 @@ If you followed the recommendation in
:ref:`easy_start_guide_for_recursive_servers`, by setting
:any:`dnssec-validation` to *auto*, there is nothing left to do.
BIND already includes a copy of the root key, and automatically updates it
when the root key changes. [#]_ It looks something like this:
when the root key changes. [#root_zone_key_update]_ It looks something like this:
::
@@ -715,7 +715,7 @@ the top-level domains have been signed, including all the largest ones.
Unless you have a particular need to manage keys yourself, it is best to
use the BIND defaults and let the software manage the root key.
.. [#]
.. [#root_zone_key_update]
The root zone was signed in July 2010 and, as at the time of this writing
(mid-2020), the key has been changed once, in October 2018. The intention going
forward is to roll the key once every five years.