diff --git a/doc/arm/advanced.inc.rst b/doc/arm/advanced.inc.rst index 3d70ebc6d1..73202eb171 100644 --- a/doc/arm/advanced.inc.rst +++ b/doc/arm/advanced.inc.rst @@ -126,7 +126,7 @@ supported only if the option :any:`ixfr-from-differences` is set to When acting as a secondary server, BIND 9 attempts to use IXFR unless it is explicitly disabled. For more information about disabling IXFR, see the -description of the :any:`request-ixfr` clause of the ``server`` statement. +description of the :any:`request-ixfr` clause of the :namedconf:ref:`server` statement. When a secondary server receives a zone via AXFR, it creates a new copy of the zone database and then swaps it into place; during the loading process, queries diff --git a/doc/arm/catz.inc.rst b/doc/arm/catz.inc.rst index 2b50ed3237..0c87bfc811 100644 --- a/doc/arm/catz.inc.rst +++ b/doc/arm/catz.inc.rst @@ -47,7 +47,7 @@ removes, or reconfigures member zones based on the data received. To use a catalog zone, it must first be set up as a normal zone on both the primary and secondary servers that are configured to use it. It -must also be added to a :any:`catalog-zones` list in the ``options`` or +must also be added to a :any:`catalog-zones` list in the :namedconf:ref:`options` or :any:`view` statement in :iscman:`named.conf`. This is comparable to the way a policy zone is configured as a normal zone and also listed in a :any:`response-policy` statement. @@ -86,7 +86,7 @@ Configuring Catalog Zones .. namedconf:statement:: catalog-zones Catalog zones are configured with a :any:`catalog-zones` statement in the -``options`` or :any:`view` section of :iscman:`named.conf`. For example: +:namedconf:ref:`options` or :any:`view` section of :iscman:`named.conf`. For example: :: diff --git a/doc/arm/dns-ops.inc.rst b/doc/arm/dns-ops.inc.rst index 32d06788a4..a9ad9f955b 100644 --- a/doc/arm/dns-ops.inc.rst +++ b/doc/arm/dns-ops.inc.rst @@ -110,10 +110,10 @@ server. described in :ref:`controls_statement_definition_and_usage`. The format of the configuration file is similar to that of - :iscman:`named.conf`, but is limited to only four statements: the ``options``, - ``key``, ``server``, and ``include`` statements. These statements are + :iscman:`named.conf`, but is limited to only three blocks: the :rndcconf:ref:`options`, + :rndcconf:ref:`key`, :rndcconf:ref:`server`, and the :ref:`include_grammar`. These blocks are what associate the secret keys to the servers with which they are - meant to be shared. The order of statements is not significant. + meant to be shared. The order of blocks is not significant. .. rndcconf:statement:: options @@ -126,13 +126,13 @@ server. .. rndcconf:statement:: default-key :any:`default-key` takes the name of a key as its argument, as defined - by a ``key`` statement. + by a :rndcconf:ref:`key` block. .. rndcconf:statement:: default-port :any:`default-port` specifies the port to which :iscman:`rndc` should connect if no port is given on the command line or in - a ``server`` statement. + a :rndcconf:ref:`server` block. .. rndcconf:statement:: default-source-address .. rndcconf:statement:: default-source-address-v6 @@ -144,17 +144,17 @@ server. .. rndcconf:statement:: key - The ``key`` statement defines a key to be used by :iscman:`rndc` when - authenticating with :iscman:`named`. Its syntax is identical to the ``key`` - statement in :iscman:`named.conf`. The keyword ``key`` is followed by a key + The :rndcconf:ref:`key` block defines a key to be used by :iscman:`rndc` when + authenticating with :iscman:`named`. Its syntax is identical to the :namedconf:ref:`key` + statement in :iscman:`named.conf`. The keyword :rndcconf:ref:`key` is followed by a key name, which must be a valid domain name, though it need not actually be hierarchical; thus, a string like ``rndc_key`` is a valid name. - The ``key`` statement has two clauses: ``algorithm`` and ``secret``. + The :rndcconf:ref:`key` block has two statements: :rndcconf:ref:`algorithm` and :rndcconf:ref:`secret`. .. rndcconf:statement:: algorithm While the configuration parser accepts any string as the argument - to ``algorithm``, currently only the strings ``hmac-md5``, + to :rndcconf:ref:`algorithm`, currently only the strings ``hmac-md5``, ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, and ``hmac-sha512`` have any meaning. @@ -165,7 +165,7 @@ server. .. rndcconf:statement:: server - The ``server`` statement specifies connection parameters for a given server. + The :rndcconf:ref:`server` block specifies connection parameters for a given server. The server can be specified as a host name or address. .. rndcconf:statement:: addresses @@ -217,7 +217,7 @@ server. allow { localhost; } keys { rndc_key; }; }; - and it has an identical key statement for ``rndc_key``. + and it has an identical key block for ``rndc_key``. Running the :iscman:`rndc-confgen` program conveniently creates an :iscman:`rndc.conf` file, and also displays the corresponding diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 8a604af014..cdcdd700b5 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -387,7 +387,7 @@ The following blocks are supported: :any:`dnssec-policy` Describes a DNSSEC key and signing policy for zones. See :ref:`dnssec_policy_grammar` for details. - ``key`` + :namedconf:ref:`key` Specifies key information for use in authentication and authorization using TSIG. :any:`logging` @@ -396,7 +396,7 @@ The following blocks are supported: ``masters`` Synonym for :any:`primaries`. - ``options`` + :namedconf:ref:`options` Controls global server configuration options and sets defaults for other statements. :any:`parental-agents` @@ -407,7 +407,7 @@ The following blocks are supported: :any:`primaries` Defines a named list of servers for inclusion in stub and secondary zones' :any:`primaries` or :any:`also-notify` lists. (Note: this is a synonym for the original keyword ``masters``, which can still be used, but is no longer the preferred terminology.) - ``server`` + :namedconf:ref:`server` Sets certain configuration options on a per-server basis. :any:`statistics-channels` @@ -436,7 +436,7 @@ The following blocks are supported: :any:`zone` Defines a zone. -The :any:`logging` and ``options`` statements may only occur once per +The :any:`logging` and :namedconf:ref:`options` statements may only occur once per configuration. :any:`acl` Block Grammar @@ -560,7 +560,7 @@ statements can be used in all views. Keys intended for use in a must be defined at the top level. The :term:`server_key`, also known as the key name, is a domain name that uniquely -identifies the key. It can be used in a ``server`` statement to cause +identifies the key. It can be used in a :namedconf:ref:`server` statement to cause requests sent to that server to be signed with this key, or in address match lists to verify that incoming requests have been signed with a key matching this name, algorithm, and secret. @@ -1261,7 +1261,7 @@ default is used. default is to allow :any:`dnstap` log files to grow to any size without rolling. - :any:`dnstap-output` can only be set globally in ``options``. Currently, + :any:`dnstap-output` can only be set globally in :namedconf:ref:`options`. Currently, it can only be set once while :iscman:`named` is running; once set, it cannot be changed by :option:`rndc reload` or :option:`rndc reconfig`. @@ -2726,7 +2726,7 @@ for details on how to specify IP address lists. server. This is only applicable for secondary zones (i.e., :any:`type secondary` or ``slave``). - If this option is set in :any:`view` or ``options``, it is globally + If this option is set in :any:`view` or :namedconf:ref:`options`, it is globally applied to all secondary zones. If set in the :any:`zone` statement, the global value is overridden. @@ -2831,7 +2831,7 @@ for details on how to specify IP address lists. insecure; see :ref:`dynamic_update_security` for details. In general, this option should only be set at the :any:`zone` level. - While a default value can be set at the ``options`` or :any:`view` level + While a default value can be set at the :namedconf:ref:`options` or :any:`view` level and inherited by zones, this could lead to some zones unintentionally allowing updates. @@ -2857,7 +2857,7 @@ for details on how to specify IP address lists. IP-address-based access control; see :ref:`dynamic_update_security` for more details. In general this option should only be set at the :any:`zone` level. - While a default value can be set at the ``options`` or :any:`view` level + While a default value can be set at the :namedconf:ref:`options` or :any:`view` level and inherited by zones, this can lead to some zones unintentionally forwarding updates. @@ -2872,7 +2872,7 @@ for details on how to specify IP address lists. This specifies which hosts are allowed to receive zone transfers from the server. :any:`allow-transfer` may also be specified in the :any:`zone` statement, in which case it overrides the :any:`allow-transfer` - statement set in ``options`` or :any:`view`. If not specified, the + statement set in :namedconf:ref:`options` or :any:`view`. If not specified, the default is to allow transfers to all hosts. The transport level limitations can also be specified. In particular, @@ -3311,7 +3311,7 @@ options apply to zone transfers. ``2``. Increasing :any:`transfers-per-ns` may speed up the convergence of secondary zones, but it also may increase the load on the remote name server. :any:`transfers-per-ns` may be overridden on a per-server basis - by using the :any:`transfers` phrase of the ``server`` statement. + by using the :any:`transfers` phrase of the :namedconf:ref:`server` statement. .. namedconf:statement:: transfer-source :tags: transfer @@ -3900,9 +3900,9 @@ RRset Ordering given RRset, the default order for that RRset is ``none``. Note that if multiple :any:`rrset-order` statements are present in the - configuration file (at both the ``options`` and :any:`view` levels), they + configuration file (at both the :namedconf:ref:`options` and :any:`view` levels), they are *not* combined; instead, the more-specific one (:any:`view`) replaces - the less-specific one (``options``). + the less-specific one (:namedconf:ref:`options`). If multiple rules within a single :any:`rrset-order` statement match a given RRset, the first matching rule is applied. @@ -4229,7 +4229,7 @@ Tuning and ``raw``. Zone files in binary formats should be generated with the same check level as that specified in the :iscman:`named` configuration file. - When configured in ``options``, this statement sets the + When configured in :namedconf:ref:`options`, this statement sets the :any:`masterfile-format` for all zones, but it can be overridden on a per-zone or per-view basis by including a :any:`masterfile-format` statement within the :any:`zone` or :any:`view` block in the configuration @@ -5013,7 +5013,7 @@ Response Rate Limiting .. namedconf:statement:: rate-limit Excessive, almost-identical UDP *responses* can be controlled by - configuring a :any:`rate-limit` clause in an ``options`` or :any:`view` + configuring a :any:`rate-limit` clause in an :namedconf:ref:`options` or :any:`view` statement. This mechanism keeps authoritative BIND 9 from being used to amplify reflection denial-of-service (DoS) attacks. Short BADCOOKIE errors or truncated (TC=1) responses can be sent to provide rate-limited responses to @@ -5247,16 +5247,16 @@ redirect zone is tried first. ``server`` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``server`` statement defines characteristics to be associated with a +The :namedconf:ref:`server` statement defines characteristics to be associated with a remote name server. If a prefix length is specified, then a range of servers is covered. Only the most specific server clause applies, regardless of the order in :iscman:`named.conf`. -The ``server`` statement can occur at the top level of the configuration +The :rndcconf:ref:`server` statement can occur at the top level of the configuration file or inside a :any:`view` statement. If a :any:`view` statement contains -one or more ``server`` statements, only those apply to the view and any -top-level ones are ignored. If a view contains no ``server`` statements, -any top-level ``server`` statements are used as defaults. +one or more :namedconf:ref:`server` statements, only those apply to the view and any +top-level ones are ignored. If a view contains no :namedconf:ref:`server` statements, +any top-level :namedconf:ref:`server` statements are used as defaults. .. namedconf:statement:: bogus @@ -5635,7 +5635,7 @@ The following options can be specified in an :any:`http` statement: HTTP/2 streams over an HTTP/2 connection. Any of the options above could be omitted. In such a case, a global value -specified in the ``options`` statement is used +specified in the :namedconf:ref:`options` statement is used (see :any:`http-listener-clients`, :any:`http-streams-per-connection`. For example, the following configuration enables DNS-over-HTTPS queries on @@ -6137,12 +6137,12 @@ clients that match the :any:`view`. By defining a zone of the same name in multiple views, different zone data can be given to different clients: for example, "internal" and "external" clients in a split DNS setup. -Many of the options given in the ``options`` statement can also be used +Many of the options given in the :namedconf:ref:`options` statement can also be used within a :any:`view` statement, and then apply only when resolving queries with that view. When no view-specific value is given, the value in the -``options`` statement is used as a default. Also, zone options can have +:namedconf:ref:`options` statement is used as a default. Also, zone options can have default values specified in the :any:`view` statement; these view-specific -defaults take precedence over those in the ``options`` statement. +defaults take precedence over those in the :namedconf:ref:`options` statement. Views are class-specific. If no class is given, class IN is assumed. Note that all non-IN views must contain a hint zone, since only the IN @@ -6151,7 +6151,7 @@ class has compiled-in default hints. If there are no :any:`view` statements in the config file, a default view that matches any client is automatically created in class IN. Any :any:`zone` statements specified on the top level of the configuration file -are considered to be part of this default view, and the ``options`` +are considered to be part of this default view, and the :namedconf:ref:`options` statement applies to the default view. If any explicit :any:`view` statements are present, all :any:`zone` statements must occur inside :any:`view` statements. @@ -6307,7 +6307,7 @@ Zone Types When configuring NOTIFY for a mirror zone, only ``notify no;`` and ``notify explicit;`` can be used at the zone level; any other :namedconf:ref:`notify` setting at the zone level is a configuration error. Using - any other :namedconf:ref:`notify` setting at the ``options`` or :any:`view` level + any other :namedconf:ref:`notify` setting at the :namedconf:ref:`options` or :any:`view` level causes that setting to be overridden with ``notify explicit;`` for the mirror zone. The global default for the :namedconf:ref:`notify` option is ``yes``, so mirror zones are by default configured with ``notify @@ -6384,7 +6384,7 @@ Zone Types :any:`forwarders` statement, which applies to queries within the domain given by the zone name. If no :any:`forwarders` statement is present, or an empty list for :any:`forwarders` is given, then no forwarding is done - for the domain, canceling the effects of any forwarders in the ``options`` + for the domain, canceling the effects of any forwarders in the :namedconf:ref:`options` statement. Thus, to use this type of zone to change the behavior of the global :any:`forward` option (that is, "forward first" to, then "forward only", or vice versa), but use the same servers as set diff --git a/doc/arm/troubleshooting.inc.rst b/doc/arm/troubleshooting.inc.rst index 556e1b48f6..0390ce606b 100644 --- a/doc/arm/troubleshooting.inc.rst +++ b/doc/arm/troubleshooting.inc.rst @@ -47,10 +47,10 @@ was implemented in BIND as of release 9.14.0. As a result, some domains may be non-resolvable without manual intervention. In these cases, resolution can be restored by adding -``server`` clauses for the offending servers, or by specifying ``edns no`` or +:namedconf:ref:`server` clauses for the offending servers, or by specifying ``edns no`` or ``send-cookie no``, depending on the specific noncompliance. -To determine which ``server`` clause to use, run the following commands +To determine which :namedconf:ref:`server` clause to use, run the following commands to send queries to the authoritative servers for the broken domain: :: diff --git a/doc/arm/tsig.inc.rst b/doc/arm/tsig.inc.rst index 1f3b587e3b..6840692c68 100644 --- a/doc/arm/tsig.inc.rst +++ b/doc/arm/tsig.inc.rst @@ -103,7 +103,7 @@ are signed using the specified key. Keys may also be specified in the :any:`also-notify` statement of a primary or secondary zone, causing NOTIFY messages to be signed using the specified key. -Keys can also be specified in a ``server`` directive. Adding the +Keys can also be specified in a :namedconf:ref:`server` directive. Adding the following on ``host1``, if the IP address of ``host2`` is 10.1.2.3, would cause *all* requests from ``host1`` to ``host2``, including normal DNS queries, to be signed using the ``host1-host2.`` key: diff --git a/doc/dnssec-guide/signing.rst b/doc/dnssec-guide/signing.rst index 9469d1dbea..826ea4ae75 100644 --- a/doc/dnssec-guide/signing.rst +++ b/doc/dnssec-guide/signing.rst @@ -92,7 +92,7 @@ other BIND configuration options, its scope depends on where it is placed. In the example above, we placed it in a :any:`zone` clause, so it applied only to the zone in question. If we had placed it in a :any:`view` clause, it would have applied to all zones in the view; and if we had placed it in -the ``options`` clause, it would have applied to all zones served by +the :namedconf:ref:`options` clause, it would have applied to all zones served by this instance of BIND. .. _signing_verification: @@ -144,7 +144,7 @@ simulate what a validating resolver will check, by telling First, we need to make a copy of the key created by BIND. This is in the directory you set with the :any:`directory` statement in -your configuration file's ``options`` clause, and is named something +your configuration file's :namedconf:ref:`options` clause, and is named something like ``Kexample.com.+013.10376.key``: :: @@ -813,7 +813,7 @@ during the process. Having defined a new policy called "standard", we now need to tell :iscman:`named` to use it. We do this by adding a ``dnssec-policy standard;`` statement to the configuration file. Like many other configuration -statements, it can be placed in the ``options`` statement (thus applying +statements, it can be placed in the :namedconf:ref:`options` statement (thus applying to all zones on the server), a :any:`view` statement (applying to all zones in the view), or a :any:`zone` statement (applying only to that zone). In this example, we'll add it to the :any:`zone` statement: diff --git a/doc/dnssec-guide/validation.rst b/doc/dnssec-guide/validation.rst index fa71497c47..0600d7707c 100644 --- a/doc/dnssec-guide/validation.rst +++ b/doc/dnssec-guide/validation.rst @@ -40,7 +40,7 @@ described in :ref:`how_to_test_recursive_server`. In earlier versions of BIND, including 9.11-ESV, DNSSEC validation must be explicitly enabled. To do this, you only need to -add one line to the ``options`` section of your configuration file: +add one line to the :namedconf:ref:`options` section of your configuration file: :: @@ -280,7 +280,7 @@ name fails: ;; MSG SIZE rcvd: 78 On the other hand, if DNSSEC validation is disabled (by adding the -statement ``dnssec-validation no;`` to the ``options`` clause in the +statement ``dnssec-validation no;`` to the :namedconf:ref:`options` clause in the configuration file), the lookup succeeds: ::