Merge pull request #13416 from jsoref/doc-dnssec

Minor doc tweaks

docs/changelog/pre-4.0.rst

@@ -263,7 +263,7 @@ lot of improvements and bug fixes and tremendously increases compliance.
 We want to explicitly thank Kees Monshouwer for digging up all the
 DNSSEC improvements and porting them back to this release.
 
-When upgrading, please run "pdnssec rectify-all-zones" and trigger an
+When upgrading, please run ``pdnssec rectify-all-zones`` and trigger an
 AXFR for all DNSSEC zones to make sure you benefit from all the
 compliance improvements present in this version.
 
@@ -1010,7 +1010,7 @@ Changes since 3.3
 -  `commit a7aa9be <https://github.com/PowerDNS/pdns/commit/a7aa9be>`__:
    Replace hardcoded make with variable
 -  `commit e4fe901 <https://github.com/PowerDNS/pdns/commit/e4fe901>`__:
-   make sure to run PKG\_PROG\_PKG\_CONFIG before the first PKG\_\*
+   make sure to run ``PKG_PROG_PKG_CONFIG`` before the first ``PKG_*``
    usage
 -  `commit 29bf169 <https://github.com/PowerDNS/pdns/commit/29bf169>`__:
    fix hmac-md5 TSIG key lookup
@@ -1103,7 +1103,7 @@ catering to their needs beyond the specifications.
 **Warning**: Version 3.3 of the PowerDNS Authoritative Server is a major
 upgrade if you are coming from 2.9.x. There are also some important
 changes if you are coming from 3.0, 3.1 or 3.2. Please refer to the
-`Upgrade documentation <authoritative/upgrading.md>`__ for important
+`Upgrade documentation <../upgrading.rst>`__ for important
 information on correct and stable operation, as well as notes on
 performance and memory use.
 
@@ -2179,7 +2179,7 @@ Changes between RC1 and RC2
 -  We imported the TinyDNS backend by Ruben d'Arco. Code mostly in
    `commit
    2559 <http://wiki.powerdns.com/projects/trac/changeset/2559>`__. See
-   `TinyDNS Backend <authoritative/backend-tinydns.md>`__.
+   `TinyDNS Backend <../backends/tinydns.rst>`__.
 -  Overriding C(XX)FLAGS is easier now. Problem pointed out by Jose
    Arthur Benetasso Villanova and others, fix suggested by Sten Spans.
    Patch in `commit
@@ -2748,13 +2748,10 @@ important protocol is among the easiest to use available. In addition,
 all important algorithms are supported.
 
 Complete detail can be found in `Serving authoritative DNSSEC
-data <authoritative/dnssec.md>`__. The goal of 'PowerDNSSEC' is to allow
-existing PowerDNS installations to start serving DNSSEC with as little
-hassle as possible, while maintaining performance and achieving high
-levels of security.
-
-Tutorials and examples of how to use DNSSEC in PowerDNS can be found
-linked from http://powerdnssec.org.
+data <../dnssec/intro.rst>`__. The goal of PowerDNS's DNSSEC support
+is to allow existing PowerDNS installations to start serving DNSSEC with
+as little hassle as possible, while maintaining performance and
+achieving high levels of security.
 
 PowerDNS Authoritative Server 3.0 development has been made possible by
 the financial and moral support of
@@ -2764,7 +2761,6 @@ the financial and moral support of
    DNS <http://www.ipcom.at/en/dns/rcodezero_anycast/>`__, a subsidiary
    of NIC.AT, the Austrian registry
 -  `SIDN, the Dutch registry <http://www.sidn.nl/>`__
--  .. (awaiting details) ..
 
 This release has received exceptional levels of community support, and
 we'd like to thank the following people in addition to those mentioned
@@ -4187,7 +4183,7 @@ job, and to let us know the results.
 
 Additionally, the bind2backend is almost ready to replace the stock bind
 backend. If you run with Bind zones, you are cordially invited to
-substitute 'launch=bind2' for 'launch=bind'. This will happen
+substitute ``launch=bind2`` for ``launch=bind``. This will happen
 automatically in 2.9.19!
 
 In other news, the entire Wikipedia constellation now runs on PowerDNS
@@ -4263,7 +4259,7 @@ Improvements
 Recursor improvements and fixes.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-See `Recursion <authoritative/recursion.md>`__ for details. The changes
+See `Recursion <../guides/recursion.rst>`__ for details. The changes
 below mean that all of the caveats listed for the recursor have now been
 addressed.
 
@@ -4502,7 +4498,7 @@ Improvements
 -  PostgreSQL now only depends on the C API and not on the deprecated
    C++ one
 -  PowerDNS can now fully overrule external zones when doing recursion.
-   See `Recursion <authoritative/recursion.md>`__.
+   See `Recursion <../guides/recursion.rst>`__.
 
 Version 2.9.13
 --------------
@@ -4853,7 +4849,7 @@ However, this turns out to not be that bad at all. The recursor can now
 be restarted without having to restart the rest of the nameserver, for
 example. Cooperation between the both halves of PowerDNS is also almost
 seamless. As a result, 'non-lazy recursion' has been dropped. See
-`Recursion <authoritative/recursion.md>`__ for more details.
+`Recursion <../guides/recursion.rst>`__ for more details.
 
 Furthermore, the recursor only works on Linux, Windows and Solaris (not
 entirely). FreeBSD does not support the required functions. If you know
@@ -4945,7 +4941,7 @@ From this, it is apparent that far more people are interested in
 PowerDNS than yet know about it. So spread the word!
 
 In other news, we now have a security page at
-`Security <security/index.md>`__. Furthermore, Maurice Nonnekes
+`Security <../security.rst>`__. Furthermore, Maurice Nonnekes
 contributed an OpenBSD port! See `his
 page <http://www.codeninja.nl/openbsd/powerdns/>`__ for more details!
 
@@ -5069,9 +5065,9 @@ instructions. Without instructions, the right things also happen, but
 the operator is in charge.
 
 For more about all this coolness, see
-`“pdns\_control” <authoritative/running.md#pdnscontrol>`__ and
+`“pdns\_control” <running.rst#pdnscontrol>`__ and
 `“pdns\_control
-commands” <authoritative/backend-bind.md#bind-control-commands>`__.
+commands” <backends/bind.rst#bind-control-commands>`__.
 
 **Warning**: Again some changes in compilation instructions. The hybrid
 pgmysql backend has been split up into 'gmysql' and 'gpgsql', sharing a
@@ -5423,7 +5419,7 @@ release fixing a huge memory leak in the new Query Cache.
 
 Developers: this version needs the new pdns-2.5.1 development kit,
 available on http://downloads.powerdns.com/releases/dev. See also
-`Backend writers' guide <appendix/backend-writers-guide.md>`__.
+`Backend writers' guide <../appendices/backend-writers-guide.rst>`__.
 
 And some small changes
 
@@ -5480,7 +5476,7 @@ New features
    The webserver also displays the efficiency of the new Query Cache.
 
    The old Packet Cache is still there (and useful) but see
-   `Authoritative Server Performance <authoritative/performance.md>`__
+   `Authoritative Server Performance <../performance.rst>`__
    for more details.
 
 -  There is now the ability to shut off some logging at a very early
@@ -5538,7 +5534,7 @@ Version 2.4
 
 Developers: this version is compatible with the pdns-2.1 development
 kit, available on http://downloads.powerdns.com/releases/dev. See also
-`*Backend writers' guide* <appendix/backend-writers-guide.md>`__.
+`*Backend writers' guide* <../appendices/backend-writers-guide.rst>`__.
 
 This version fixes some stability issues with malformed or malcrafted
 packets. An upgrade is advised. Furthermore, there are interesting new
@@ -5585,7 +5581,7 @@ Version 2.3
 
 Developers: this version is compatible with the pdns-2.1 development
 kit, available on http://downloads.powerdns.com/releases/dev. See also
-`Backend writers' guide <appendix/backend-writers-guide.md>`__
+`Backend writers' guide <../appendices/backend-writers-guide.rst>`__
 
 This release adds the Generic MySQL backend which allows full
 master/slave semantics with MySQL and InnoDB tables (or other tables
@@ -5627,7 +5623,7 @@ Version 2.2
 
 Developers: this version is compatible with the pdns-2.1 development
 kit, available on http://downloads.powerdns.com/releases/dev. See also
-`Backend writers' guide <appendix/backend-writers-guide.md>`__
+`Backend writers' guide <../appendices/backend-writers-guide.rst>`__
 
 Again a big release. PowerDNS is seeing some larger deployments in more
 demanding environments and these are helping shake out remaining issues,
@@ -5668,12 +5664,12 @@ New features
 -  **pdns\_control purge** can now also purge based on suffix, allowing
    operators to purge an entire domain from the packet cache instead of
    only specific records. See also
-   `pdns\_control <authoritative/running.md#pdnscontrol>`__ Thanks to
+   `pdns\_control <running.rst#pdnscontrol>`__ Thanks to
    Mike Benoit for this suggestion.
 -  **soa-serial-offset** for installations with small SOA serial numbers
    wishing to register .DE domains with DENIC which demands six-figure
    SOA serial numbers. See also `Chapter 21, *Index of all Authoritative
-   Server settings* <authoritative/settings.md>`__.
+   Server settings* <../settings.rst>`__.
 
 Version 2.1
 -----------
@@ -5724,7 +5720,7 @@ Unexpected behaviour
    with user expectations. If a recursive question can be answered
    entirely from local data, it is. To restore old behaviour, disable
    **lazy-recursion**. Also see
-   `Recursion <authoritative/recursion.md>`__.
+   `Recursion <../guides/recursion.rst>`__.
 
 Features
 ^^^^^^^^
@@ -5737,13 +5733,13 @@ Features
 -  Zone2sql now accepts ^^transactions to wrap zones in a transaction
    for PostgreSQL and Oracle output. This is a major speedup and also
    makes for better isolation of inserts. See
-   `Zone2sql <authoritative/migration.md#zone2sql>`__.
+   `Zone2sql <migration.rst#zone2sql>`__.
 -  **pdns\_control** now has the ability to purge the PowerDNS cache or
    parts of it. This enables operators to raise the TTL of the Packet
    Cache to huge values and only to invalidate the cache when changes
    are made. See also `Authoritative Server
-   Performance <authoritative/performance.md>`__ and
-   `pdns\_control <authoritative/running.md#pdnscontrol>`__.
+   Performance <../performance.rst>`__ and
+   `pdns\_control <../running.rst#pdnscontrol>`__.
 
 Version 2.0.1
 -------------
@@ -5929,15 +5925,15 @@ Features
 ^^^^^^^^
 
 -  pdns\_control (see
-   `pdns\_control <authoritative/running.md#pdnscontrol>`__) now opens
+   `pdns\_control <running.rst#pdnscontrol>`__) now opens
    the local end of its socket in ``/tmp`` instead of next to the remote
    socket (by default ``/var/run``). This eases the way for allowing
    non-root access to pdns\_control. When running chrooted (see
    `Chapter 7, *Security settings &
-   considerations* <common/security.md>`__), the local socket again
+   considerations* <../security.rst>`__), the local socket again
    moves back to ``/var/run``.
 -  pdns\_control now has a 'version' command. See `Section 1.1,
-   “pdns\_control” <authoritative/running.md#pdnscontrol>`__.
+   “pdns\_control” <../running.rst#pdnscontrol>`__.
 
 Version 1.99.11 Prerelease
 --------------------------
@@ -6049,7 +6045,7 @@ Features
    `Supermaster automatic provisioning of
    slaves <authoritative/modes-of-operation.md#supermaster>`__.
 -  Recursing backend can now live on a non-standard (!=53) port. See
-   `Recursion <authoritative/recursion.md>`__.
+   `Recursion <../guides/recursion.rst>`__.
 -  Slave zone retrieval is now queued instead of immediate, which scales
    better and is more resilient to temporary failures.
 -  **max-queue-length** parameter. If this many packets are queued for
@@ -6097,17 +6093,17 @@ Bugs fixed
 Feature enhancements
 ^^^^^^^^^^^^^^^^^^^^
 
--  Recursing backend. See `Recursion <authoritative/recursion.md>`__.
+-  Recursing backend. See `Recursion <../guides/recursion.rst>`__.
    Allows recursive and authoritative DNS on the same IP address.
--  `NAPTR support <types.md#naptr>`__, which is especially useful for
+-  `NAPTR support <appendices/types.rst#naptr>`__, which is especially useful for
    the ENUM/E.164 community.
 -  Zone transfers can now be allowed per `netmask instead of only per IP
-   address <authoritative/settings.md#allow-axfr-ips>`__.
+   address <../settings.rst#allow-axfr-ips>`__.
 -  Preliminary support for slave operation included. Only for the
    adventurous right now! See `Slave
-   operation <authoritative/modes-of-operation.md>`__
+   operation <../modes-of-operation.rst>`__
 -  All record types now documented, see `Supported record types and
-   their storage <types.md>`__.
+   their storage <../appendices/types.rst>`__.
 
 Known bugs
 ^^^^^^^^^^

docs/dnssec/advice.rst

@@ -4,7 +4,7 @@ DNSSEC advice & precautions
 DNSSEC is a major change in the way DNS works. Furthermore, there is a
 bewildering array of settings that can be configured.
 
-It is well possible to configure DNSSEC in such a way that your domain
+It is easy to (mis)configure DNSSEC in such a way that your domain
 will not operate reliably, or even, at all. We advise operators to stick
 to the keying defaults of ``pdnsutil secure-zone``.
 

docs/dnssec/intro.rst

@@ -4,9 +4,9 @@ A brief introduction to DNSSEC
 DNSSEC is a complicated subject, but it is not required to know all the
 ins and outs of this protocol to be able to use PowerDNS. In this
 section, we explain the core concepts that are needed to operate a
-PowerDNSSEC installation.
+PowerDNS installation with DNSSEC.
 
-Zone material is enhanced with signatures using 'keys'. Such a signature
+Zone material is enhanced with signatures using ``keys``. Such a signature
 (called an RRSIG) is a cryptographic guarantee that the data served is
 the original data. DNSSEC keys are asymmetric (RSA, DSA, ECSDA or GOST),
 the public part is published in DNS and is called a DNSKEY record, and
@@ -24,29 +24,29 @@ Once the parent zone has the DS, and the zone is signed with the DNSSEC
 key, we are done in theory.
 
 However, for a variety of reasons, most DNSSEC operations run with
-another layer of keys. The so called 'Key Signing Key' is sent to the
+another layer of keys. The so called ``Key Signing Key`` is sent to the
 parent zone, and this Key Signing Key is used to sign a new set of keys
 called the Zone Signing Keys.
 
 This setup allows us to change our keys without having to tell the zone
 operator about it.
 
-A final challenge is how to DNSSEC sign the answer 'no such domain'. In
-the language of DNS, the way to say 'there is no such domain' (NXDOMAIN)
+A final challenge is how to DNSSEC sign the answer *no such domain*. In
+the language of DNS, the way to say *there is no such domain* (``NXDOMAIN``)
 or there is no such record type is to send an empty answer. Such empty
 answers are universal, and can't be signed.
 
-In DNSSEC parlance we therefore sign a record that says 'there are no
-domains between A.powerdnssec.org and C.powerdnssec.org'. This securely
-tells the world that B.powerdnssec.org does not exist. This solution is
-called NSEC, and is simple but has downsides - it also tells the world
+In DNSSEC parlance we therefore sign a record that says *there are no
+domains between* ``A.powerdnssec.org`` *and* ``C.powerdnssec.org``. This securely
+tells the world that ``B.powerdnssec.org`` does not exist. This solution is
+called ``NSEC``, and is simple but has downsides - it also tells the world
 exactly which records DO exist.
 
 So alternatively, we can say that if a certain mathematical operation
-(an 'iterated salted hash') is performed on a question, that no valid
+(an *iterated salted hash*) is performed on a question, that no valid
 answers exist that have as outcome of this operation an answer between
-two very large numbers. This leads to the same 'proof of non-existence'.
-This solution is called NSEC3.
+two very large numbers. This leads to the same *proof of non-existence*.
+This solution is called ``NSEC3``.
 
-A PowerDNS zone can either be operated in NSEC or in one of two NSEC3
-modes ('inclusive' and 'narrow').
+A PowerDNS zone can either be operated in ``NSEC`` or in one of two ``NSEC3``
+modes (``inclusive`` and ``narrow``).