From 2630cf8e76249d6971a169b0e445dadac432890e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Tue, 28 Jun 2022 17:23:19 +0200 Subject: [PATCH 1/5] Resurrect DNS NOTIFY chapter in the ARM It was accidentally removed in the heat of 25eb91d23c5a2056f36902c90dfe8ca69f6a9400. --- doc/arm/advanced.inc.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/doc/arm/advanced.inc.rst b/doc/arm/advanced.inc.rst index 0be6df020d..50347e68c2 100644 --- a/doc/arm/advanced.inc.rst +++ b/doc/arm/advanced.inc.rst @@ -88,6 +88,25 @@ journal file without stopping dynamic updates; this may be useful for viewing the current zone state. To remove the ``.jnl`` file after updating the zone file, use :option:`rndc sync -clean `. +.. _notify: + +NOTIFY +------ + +DNS NOTIFY is a mechanism that allows primary servers to notify their +secondary servers of changes to a zone's data. In response to a NOTIFY message +from a primary server, the secondary checks to see that its version of +the zone is the current version and, if not, initiates a zone transfer. + +For more information about DNS NOTIFY, see the description of the +:namedconf:ref:`notify` and :namedconf:ref`also-notify` statements. +The NOTIFY protocol is specified in :rfc:`1996`. + +.. note:: + + As a secondary zone can also be a primary to other secondaries, :iscman:`named`, by + default, sends NOTIFY messages for every zone it loads. + .. _incremental_zone_transfers: Incremental Zone Transfers (IXFR) From 7187a5cf77e52c74a782ed3ad39e0fcdc4000868 Mon Sep 17 00:00:00 2001 From: Suzanne Goldlust Date: Fri, 24 Jun 2022 17:04:20 +0000 Subject: [PATCH 2/5] Add the :tags: and :short: descriptions for the category "query" --- doc/arm/reference.rst | 39 +++++++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 01d76a3e86..f99d079d4c 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -1557,9 +1557,12 @@ default is used. .. _root-delegation-only: .. namedconf:statement:: root-delegation-only + :tags: query + :short: Turns on enforcement of delegation-only in top-level domains (TLDs) and root zones with an optional exclude list. - This turns on enforcement of delegation-only in TLDs (top-level domains) - and root zones with an optional exclude list. + This turns on enforcement of delegation-only in top-level domains (TLDs) + and root zones with an + optional exclude list. DS queries are expected to be made to and be answered by delegation-only zones. Such queries and responses are treated as an exception to @@ -1890,6 +1893,8 @@ Boolean Options :ref:`man_rndc` for further details about :option:`rndc addzone`. .. namedconf:statement:: auth-nxdomain + :tags: query + :short: Controls whether BIND, acting as a resolver, provides authoritative NXDOMAIN (domain does not exist) answers. If ``yes``, then the ``AA`` bit is always set on NXDOMAIN responses, even if the server is not actually authoritative. The default is @@ -2000,6 +2005,8 @@ Boolean Options 6.1.3.2. The default is ``yes``. .. namedconf:statement:: minimal-responses + :tags: query + :short: Controls whether the server only adds records to the authority and additional data sections when they are required (e.g. delegations, negative responses). This improves server performance. This option controls the addition of records to the authority and additional sections of responses. Such records may be included in @@ -2078,6 +2085,8 @@ Boolean Options .. _recursion: .. namedconf:statement:: recursion + :tags: query + :short: Defines whether recursion and caching are allowed. If ``yes``, and a DNS query requests recursion, then the server attempts to do all the work required to answer the query. If recursion @@ -2618,6 +2627,8 @@ authoritative and does not have the answer in its cache. .. _forward: .. namedconf:statement:: forward + :tags: query + :short: Allows or disallows fallback to recursion if forwarding has failed; it is always used in conjunction with the :any:`forwarders` statement. This option is only meaningful if the forwarders list is not empty. A value of ``first`` is the default and causes the server to query the @@ -2628,6 +2639,8 @@ authoritative and does not have the answer in its cache. .. _forwarders: .. namedconf:statement:: forwarders + :tags: query + :short: Defines one or more hosts to which queries are forwarded. This specifies a list of IP addresses to which queries are forwarded. The default is the empty list (no forwarding). Each address in the list can be @@ -2713,12 +2726,12 @@ for details on how to specify IP address lists. .. namedconf:statement:: allow-query-cache :tags: query - :short: Specifies which hosts (an IP address list) can access this servers cache and thus effectively controls recursion. + :short: Specifies which hosts (an IP address list) can access this server's cache and thus effectively controls recursion. Defines an :term:`address_match_list` of IP address(es) which are allowed to - issue queries that access the local cache - without access to the local + issue queries that access the local cache. Without access to the local cache recursive queries are effectively useless so, in effect, this - statement (or its default) controls recursive behavior. This statements's + statement (or its default) controls recursive behavior. This statement's default setting depends on: 1. If :namedconf:ref:`recursion no; ` present, defaults to @@ -2736,7 +2749,7 @@ for details on how to specify IP address lists. .. namedconf:statement:: allow-query-cache-on :tags: query - :short: Specifies which hosts (an IP address list) can access this servers cache. Used in multi-homed configurations. + :short: Specifies which hosts (an IP address list) can access this server's cache. Used on servers with multiple interfaces. This specifies which local addresses can send answers from the cache. If ``allow-query-cache-on`` is not set, then ``allow-recursion-on`` is @@ -2747,6 +2760,8 @@ for details on how to specify IP address lists. other. .. namedconf:statement:: allow-recursion + :tags: query + :short: Defines an :any:`address_match_list` of clients that are allowed to perform recursive queries. This specifies which hosts are allowed to make recursive queries through this server. BIND checks to see if the following parameters are set, in @@ -2835,6 +2850,8 @@ for details on how to specify IP address lists. authentication. .. namedconf:statement:: blackhole + :tags: query + :short: Defines an :any:`address_match_list` of hosts that the server neither responds to nor answers queries for. This specifies a list of addresses which the server does not accept queries from or use to resolve a query. Queries from these addresses are not @@ -2987,6 +3004,8 @@ Query Address .. namedconf:statement:: query-source .. namedconf:statement:: query-source-v6 + :tags: query + :short: Controls the IPv4/IPv6 address and port on which recursive queries are issued. If the server does not know the answer to a question, it queries other name servers. ``query-source`` specifies the address and port used for @@ -3362,6 +3381,8 @@ system. zero, which means the maximum is unlimited. .. namedconf:statement:: recursive-clients + :tags: query + :short: Specifies the maximum number of concurrent recursive queries the server can perform. This sets the maximum number (a "hard quota") of simultaneous recursive lookups the server performs on behalf of clients. The default is @@ -3647,6 +3668,8 @@ client's address. This only requires configuring the name servers, not all the clients. .. namedconf:statement:: sortlist + :tags: query + :short: Controls the ordering of RRs returned to the client, based on the client's IP address. The ``sortlist`` statement (see below) takes an ``address_match_list`` and interprets it in a special way. Each top-level statement in the ``sortlist`` @@ -3729,6 +3752,8 @@ RRset Ordering suboptimal choice for load balancing purposes when used on its own. .. namedconf:statement:: rrset-order + :tags: query + :short: Defines the order in which equal RRs (RRsets) are returned. The ``rrset-order`` statement permits configuration of the ordering of the records in a multiple-record response. See also: @@ -6304,6 +6329,8 @@ Zone Types zones are reloaded along with other zones. .. namedconf:statement:: type delegation-only + :tags: query + :short: Enforces the delegation-only status of infrastructure zones (COM, NET, ORG, etc.). This zone type is used to enforce the delegation-only status of infrastructure zones (e.g., COM, NET, ORG). Any answer that is received without an From 3cf976bd78dedeb89fd0e1e5f368da496e5e8de4 Mon Sep 17 00:00:00 2001 From: Suzanne Goldlust Date: Fri, 24 Jun 2022 20:00:58 +0000 Subject: [PATCH 3/5] Add the :tags: and :short: descriptions for the category "transfer" --- doc/arm/reference.rst | 133 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 116 insertions(+), 17 deletions(-) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index f99d079d4c..e6e27de1f7 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -2055,6 +2055,8 @@ Boolean Options .. _notify_st: .. namedconf:statement:: notify + :tags: transfer + :short: Controls whether ``NOTIFY`` messages are sent on zone changes. If set to ``yes`` (the default), DNS NOTIFY messages are sent when a zone the server is authoritative for changes; see :ref:`using notify`. @@ -2275,13 +2277,18 @@ Boolean Options The default is ``yes``. .. namedconf:statement:: provide-ixfr + :tags: transfer + :short: Controls whether a primary responds to an incremental zone request (IXFR) or only responds with a full zone transfer (AXFR). The ``provide-ixfr`` clause determines whether the local server, acting as primary, responds with an incremental zone transfer when the given remote server, a secondary, requests it. If set to ``yes``, incremental transfer is provided whenever possible. If set to ``no``, all transfers to the remote server are non-incremental. + .. namedconf:statement:: request-ixfr + :tags: transfer + :short: Controls whether a secondary requests an incremental zone transfer (IXFR) or a full zone transfer (AXFR). The ``request-ixfr`` statement determines whether the local server, acting as a secondary, requests incremental zone transfers from the given @@ -2323,6 +2330,8 @@ Boolean Options this option is discouraged. .. namedconf:statement:: ixfr-from-differences + :tags: transfer + :short: Controls how IXFR transfers are calculated. When ``yes`` and the server loads a new version of a primary zone from its zone file or receives a new version of a secondary file via zone @@ -2348,6 +2357,8 @@ Boolean Options ``ixfr-from-differences`` setting is ignored for that zone. .. namedconf:statement:: multi-master + :tags: transfer + :short: Controls whether serial number mismatch errors are logged. This should be set when there are multiple primary servers for a zone and the addresses refer to different machines. If ``yes``, :iscman:`named` does not @@ -2681,6 +2692,8 @@ requesting system. See :ref:`address_match_lists` for details on how to specify IP address lists. .. namedconf:statement:: allow-notify + :tags: transfer + :short: Defines an :any:`address_match_list` that is allowed to send ``NOTIFY`` messages for the zone, in addition to addresses defined in the :any:`primaries` option for the zone. This ACL specifies which hosts may send NOTIFY messages to inform this server of changes to zones for which it is acting as a secondary @@ -2780,10 +2793,12 @@ for details on how to specify IP address lists. be allowed by the other. .. namedconf:statement:: allow-update + :tags: transfer + :short: Defines an :any:`address_match_list` of hosts that are allowed to submit dynamic updates for primary zones. A simple access control list. When set in the ``zone`` statement for a primary zone, this specifies which - hosts are allowed to submit Dynamic DNS updates to that zone. The + hosts are allowed to submit dynamic DNS updates to that zone. The default is to deny updates from all hosts. Note that allowing updates based on the requestor's IP address is @@ -2797,9 +2812,11 @@ for details on how to specify IP address lists. Updates are written to the zone's filename that is set in ``file``. .. namedconf:statement:: allow-update-forwarding + :tags: transfer + :short: Defines an :any:`address_match_list` of hosts that are allowed to submit dynamic updates to a secondary server for transmission to a primary. When set in the ``zone`` statement for a secondary zone, this specifies which - hosts are allowed to submit Dynamic DNS updates and have them be + hosts are allowed to submit dynamic DNS updates and have them be forwarded to the primary. The default is ``{ none; }``, which means that no update forwarding is performed. @@ -2823,6 +2840,8 @@ for details on how to specify IP address lists. .. _allow-transfer: .. namedconf:statement:: allow-transfer + :tags: transfer + :short: Defines an :any:`address_match_list` of hosts that are allowed to transfer the zone information from this server. This specifies which hosts are allowed to receive zone transfers from the server. ``allow-transfer`` may also be specified in the ``zone`` @@ -3120,6 +3139,8 @@ options apply to zone transfers. .. _also-notify: .. namedconf:statement:: also-notify + :tags: transfer + :short: Defines one or more hosts that are sent ``NOTIFY`` messages when zone changes occur. This option defines a global list of IP addresses of name servers that are also sent NOTIFY messages whenever a fresh copy of the zone is loaded, in @@ -3139,24 +3160,32 @@ options apply to zone transfers. zone. The default is the empty list (no global notification list). .. namedconf:statement:: max-transfer-time-in + :tags: transfer + :short: Specifies the number of minutes after which inbound zone transfers are terminated. Inbound zone transfers running longer than this many minutes are terminated. The default is 120 minutes (2 hours). The maximum value is 28 days (40320 minutes). .. namedconf:statement:: max-transfer-idle-in + :tags: transfer + :short: Specifies the number of minutes after which inbound zone transfers making no progress are terminated. Inbound zone transfers making no progress in this many minutes are terminated. The default is 60 minutes (1 hour). The maximum value is 28 days (40320 minutes). .. namedconf:statement:: max-transfer-time-out + :tags: transfer + :short: Specifies the number of minutes after which outbound zone transfers are terminated. Outbound zone transfers running longer than this many minutes are terminated. The default is 120 minutes (2 hours). The maximum value is 28 days (40320 minutes). .. namedconf:statement:: max-transfer-idle-out + :tags: transfer + :short: Specifies the number of minutes after which outbound zone transfers making no progress are terminated. Outbound zone transfers making no progress in this many minutes are terminated. The default is 60 minutes (1 hour). The maximum value @@ -3178,6 +3207,8 @@ options apply to zone transfers. one per second; when set to zero, it is silently raised to one. .. namedconf:statement:: serial-query-rate + :tags: transfer + :short: Defines an upper limit on the number of queries per second issued by the server, when querying the SOA RRs used for zone transfers. Secondary servers periodically query primary servers to find out if zone serial numbers have changed. Each such query uses a minute @@ -3189,6 +3220,8 @@ options apply to zone transfers. it is silently raised to one. .. namedconf:statement:: transfer-format + :tags: transfer + :short: Controls whether multiple records can be packed into a message during zone transfers. Zone transfers can be sent using two different formats, ``one-answer`` and ``many-answers``. The ``transfer-format`` option @@ -3221,6 +3254,8 @@ options apply to zone transfers. any benefit in setting a value other than the default. .. namedconf:statement:: transfers-in + :tags: transfer + :short: Limits the number of concurrent inbound zone transfers. This is the maximum number of inbound zone transfers that can run concurrently. The default value is ``10``. Increasing @@ -3228,6 +3263,8 @@ options apply to zone transfers. also may increase the load on the local system. .. namedconf:statement:: transfers-out + :tags: transfer + :short: Limits the number of concurrent outbound zone transfers. This is the maximum number of outbound zone transfers that can run concurrently. Zone transfer requests in excess of the limit are @@ -3243,6 +3280,8 @@ options apply to zone transfers. by using the ``transfers`` phrase of the ``server`` statement. .. namedconf:statement:: transfer-source + :tags: transfer + :short: Defines which local IPv4 address(es) are bound to TCP connections used to fetch zones transferred inbound by the server. ``transfer-source`` determines which local address is bound to IPv4 TCP connections used to fetch zones transferred inbound by the @@ -3263,11 +3302,15 @@ options apply to zone transfers. .. warning:: The configured ``port`` must not be same as the listening port. .. namedconf:statement:: transfer-source-v6 + :tags: transfer + :short: Defines which local IPv6 address(es) are bound to TCP connections used to fetch zones transferred inbound by the server. This option is the same as ``transfer-source``, except zone transfers are performed using IPv6. .. namedconf:statement:: alt-transfer-source + :tags: transfer + :short: Defines alternate local IPv4 address(es) to be used by the server for inbound zone transfers, if the address(es) defined by :any:`transfer-source` fail and :any:`use-alt-transfer-source` is enabled. This indicates an alternate transfer source if the one listed in ``transfer-source`` fails and ``use-alt-transfer-source`` is set. @@ -3278,16 +3321,22 @@ options apply to zone transfers. query. .. namedconf:statement:: alt-transfer-source-v6 + :tags: transfer + :short: Defines alternate local IPv6 address(es) to be used by the server for inbound zone transfers. This indicates an alternate transfer source if the one listed in ``transfer-source-v6`` fails and ``use-alt-transfer-source`` is set. .. namedconf:statement:: use-alt-transfer-source + :tags: transfer + :short: Indicates whether :any:`alt-transfer-source` and :any:`alt-transfer-source-v6` can be used. This indicates whether the alternate transfer sources should be used. If views are specified, this defaults to ``no``; otherwise, it defaults to ``yes``. .. namedconf:statement:: notify-source + :tags: transfer + :short: Defines the IPv4 address (and optional port) to be used for outgoing ``NOTIFY`` messages. ``notify-source`` determines which local source address, and optionally UDP port, is used to send NOTIFY messages. This @@ -3303,8 +3352,10 @@ options apply to zone transfers. .. warning:: The configured ``port`` must not be same as the listening port. .. namedconf:statement:: notify-source-v6 + :tags: transfer + :short: Defines the IPv6 address (and optional port) to be used for outgoing ``NOTIFY`` messages. - This option acts like ``notify-source``, but applies to notify messages sent to IPv6 + This option acts like ``notify-source``, but applies to ``NOTIFY`` messages sent to IPv6 addresses. .. _resource_limits: @@ -3361,6 +3412,8 @@ that are enforced internally by the server rather than by the operating system. .. namedconf:statement:: max-journal-size + :tags: transfer + :short: Controls the size of journal files. This sets a maximum size for each journal file (see :ref:`journal`), expressed in bytes or, if followed by an @@ -4009,24 +4062,68 @@ Tuning :option:`rndc signing -clear all zone `. .. namedconf:statement:: min-refresh-time -.. namedconf:statement:: max-refresh-time -.. namedconf:statement:: min-retry-time -.. namedconf:statement:: max-retry-time + :tags: transfer + :short: Limits the zone refresh interval to no more often than the specified value, in seconds. - These options control the server's behavior on refreshing a zone - (querying for SOA changes) or retrying failed transfers. Usually the - SOA values for the zone are used, up to a hard-coded maximum expiry - of 24 weeks. However, these values are set by the primary, giving + This option controls the server's behavior on refreshing a zone + (querying for SOA changes). Usually, the SOA refresh values for + the zone are used; however, these values are set by the primary, giving secondary server administrators little control over their contents. - These options allow the administrator to set a minimum and maximum - refresh and retry time in seconds per-zone, per-view, or globally. - These options are valid for secondary and stub zones, and clamp the SOA - refresh and retry times to the specified values. + This option allows the administrator to set a minimum + refresh time in seconds per-zone, per-view, or globally. + This option is valid for secondary and stub zones, and clamps the SOA + refresh time to the specified value. - The following defaults apply: ``min-refresh-time`` 300 seconds, - ``max-refresh-time`` 2419200 seconds (4 weeks), ``min-retry-time`` - 500 seconds, and ``max-retry-time`` 1209600 seconds (2 weeks). + The default is 300 seconds. + +.. namedconf:statement:: max-refresh-time + :tags: transfer + :short: Limits the zone refresh interval to no less often than the specified value, in seconds. + + This option controls the server's behavior on refreshing a zone + (querying for SOA changes). Usually, the SOA refresh values for + the zone are used; however, these values are set by the primary, giving + secondary server administrators little control over their contents. + + This option allows the administrator to set a maximum + refresh time in seconds per-zone, per-view, or globally. + This option is valid for secondary and stub zones, and clamps the SOA + refresh time to the specified value. + + The default is 2419200 seconds (4 weeks). + +.. namedconf:statement:: min-retry-time + :tags: transfer + :short: Limits the zone refresh retry interval to no more often than the specified value, in seconds. + + This option controls the server's behavior on retrying failed + zone transfers. Usually, the SOA retry values for the zone are + used; however, these values are set by the primary, giving + secondary server administrators little control over their contents. + + This option allows the administrator to set a minimum + retry time in seconds per-zone, per-view, or globally. + This option is valid for secondary and stub zones, and clamps the SOA + retry time to the specified value. + + The default is 500 seconds. + +.. namedconf:statement:: max-retry-time + :tags: transfer + :short: Limits the zone refresh retry interval to no less often than the specified value, in seconds. + + This option controls the server's behavior on retrying failed + zone transfers. Usually, the SOA retry values for the zone are + used; however, these values are set by the primary, giving + secondary server administrators little control over their contents. + + This option allows the administrator to set a maximum + retry time in seconds per-zone, per-view, or globally. + This option is valid for secondary and stub zones, and clamps the SOA + retry time to the specified value. + + The default is 1209600 seconds (2 weeks). .. namedconf:statement:: edns-udp-size @@ -6684,6 +6781,8 @@ the zone's filename, unless ``inline-signing`` is enabled. in the zone file are lost when dynamic updates occur. .. namedconf:statement:: update-policy + :tags: transfer + :short: Sets fine-grained rules to allow or deny dynamic updates (DDNS), based on requester identity, updated content, etc. The ``update-policy`` clause allows more fine-grained control over which updates are allowed. It specifies a set of rules, in which each rule From 0e7ca5b5e02ee2f88a0b6b6f4f9cc64975299d84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 29 Jun 2022 10:49:43 +0200 Subject: [PATCH 4/5] Disambiguate address_match_list link anchor Let's keep just the :term: produced by grammar glossary. --- doc/arm/reference.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index e6e27de1f7..a8e03a92c4 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -194,7 +194,6 @@ only by the name server. .. _`glob expression`: https://man7.org/linux/man-pages/man7/glob.7.html .. _address_match_lists: -.. _address_match_list: Address Match Lists ~~~~~~~~~~~~~~~~~~~ From 563eb8e1b94457700221ab938e750135b13e40a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Mon, 27 Jun 2022 17:03:47 +0200 Subject: [PATCH 5/5] Accept rst syntax in .. statement:: short: text Nested rst syntax is now parsed and rendered. E.g.: .. namedconf:statement:: example :short: Use ``this`` **cool** syntax! --- doc/arm/_ext/iscconf.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/arm/_ext/iscconf.py b/doc/arm/_ext/iscconf.py index 122673839d..670dca4998 100644 --- a/doc/arm/_ext/iscconf.py +++ b/doc/arm/_ext/iscconf.py @@ -114,10 +114,18 @@ def domain_factory(domainname, domainlabel, todolist): def isc_short(self): return self.options.get("short", "") + def parse_nested_str(self, instr): + """Parse string as nested rst syntax and produce a node""" + raw = nodes.paragraph(text=instr) + parsed = nodes.paragraph() + self.state.nested_parse(raw, self.content_offset, parsed) + return parsed + def transform_content(self, contentnode: addnodes.desc_content) -> None: """autogenerate content from structured data""" if self.isc_short: - contentnode.insert(0, nodes.paragraph(text=self.isc_short)) + short_parsed = self.parse_nested_str(self.isc_short) + contentnode.insert(0, short_parsed) if self.isc_tags: tags = nodes.paragraph() tags += nodes.strong(text="Tags: ")