upstream/bind9
1
0
Fork 0
mirror of https://github.com/isc-projects/bind9.git synced 2026-05-28 04:34:54 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'sgoldlust/arm-tag-query-transfer' into 'main'

Browse source 
Add tags and short descriptions for query and transfer statements

See merge request isc-projects/bind9!6502
This commit is contained in:
Petr Špaček 2022-06-30 16:11:30 +00:00
commit b18fa6c7b2
3 changed files with 177 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
doc/arm/_ext/iscconf.py
View file

@ -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: ")

19
doc/arm/advanced.inc.rst
View file

@ -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 <rndc sync>`.
.. _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)

173
doc/arm/reference.rst
View file

@ -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
~~~~~~~~~~~~~~~~~~~
@ -1557,9 +1556,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 +1892,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 +2004,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
@ -2048,6 +2054,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<notify>`.
@ -2078,6 +2086,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
@ -2266,13 +2276,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
@ -2314,6 +2329,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
@ -2339,6 +2356,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
@ -2618,6 +2637,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 +2649,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
@ -2668,6 +2691,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
@ -2713,12 +2738,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; <recursion>` present, defaults to
@ -2736,7 +2761,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 +2772,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
@ -2765,10 +2792,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
@ -2782,9 +2811,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.
@ -2808,6 +2839,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``
@ -2835,6 +2868,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 +3022,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
@ -3101,6 +3138,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
@ -3120,24 +3159,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
@ -3159,6 +3206,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
@ -3170,6 +3219,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
@ -3202,6 +3253,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
@ -3209,6 +3262,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
@ -3224,6 +3279,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
@ -3244,11 +3301,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.
@ -3259,16 +3320,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
@ -3284,8 +3351,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:
@ -3342,6 +3411,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
@ -3362,6 +3433,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 +3720,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 +3804,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:
@ -3984,24 +4061,68 @@ Tuning
:option:`rndc signing -clear all zone <rndc signing>`.
.. 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
@ -6304,6 +6425,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
@ -6657,6 +6780,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