diff --git a/doc/arm/config-intro.inc.rst b/doc/arm/config-intro.inc.rst index 7efea14026..d041eccf5f 100644 --- a/doc/arm/config-intro.inc.rst +++ b/doc/arm/config-intro.inc.rst @@ -79,7 +79,7 @@ as required by the user. }; The :any:`logging` and :namedconf:ref:`options` blocks -and :ref:`category`, :any:`channel`, +and :any:`category`, :any:`channel`, :any:`directory`, :any:`file`, and :any:`severity` statements are all described further in the appropriate sections of this ARM. diff --git a/doc/arm/config-resolve.inc.rst b/doc/arm/config-resolve.inc.rst index d299622f84..fcfa97e20d 100644 --- a/doc/arm/config-resolve.inc.rst +++ b/doc/arm/config-resolve.inc.rst @@ -563,4 +563,4 @@ and discard the rest. For more detail on ordering responses, refer to the :ref:`rrset-order` statement in the -:ref:`options` block. +:namedconf:ref:`options` block. diff --git a/doc/arm/dns-ops.inc.rst b/doc/arm/dns-ops.inc.rst index a9ad9f955b..38effae7e0 100644 --- a/doc/arm/dns-ops.inc.rst +++ b/doc/arm/dns-ops.inc.rst @@ -107,7 +107,7 @@ server. not found, :iscman:`rndc` also looks in |rndc_key| (or whatever ``sysconfdir`` was defined when the BIND build was configured). The ``rndc.key`` file is generated by running :option:`rndc-confgen -a` as - described in :ref:`controls_statement_definition_and_usage`. + described in :any:`controls`. The format of the configuration file is similar to that of :iscman:`named.conf`, but is limited to only three blocks: the :rndcconf:ref:`options`, diff --git a/doc/arm/dnssec.inc.rst b/doc/arm/dnssec.inc.rst index 9adec06c94..c48bab1dda 100644 --- a/doc/arm/dnssec.inc.rst +++ b/doc/arm/dnssec.inc.rst @@ -112,7 +112,7 @@ that are about to expire and managing :ref:`key_rollovers`. .. note:: :any:`dnssec-policy` needs write access to the zone. Please see - :ref:`dnssec_policy` for more details about implications for zone storage. + :any:`dnssec-policy` for more details about implications for zone storage. The default policy creates one key that is used to sign the complete zone, and uses ``NSEC`` to enable authenticated denial of existence (a secure way @@ -150,7 +150,7 @@ Also: using zero extra iterations and no salt. NSEC3 opt-out is disabled, meaning insecure delegations also get an NSEC3 record. -For more information about KASP configuration see :ref:`dnssec_policy_grammar`. +For more information about KASP configuration see :any:`dnssec-policy`. The :ref:`dnssec_advanced_discussions` section in the DNSSEC Guide discusses the various policy settings and may be useful for determining values for specific diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index d03c309e29..ff36672cc4 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -385,7 +385,7 @@ The following blocks are supported: Declares control channels to be used by the :iscman:`rndc` utility. :any:`dnssec-policy` - Describes a DNSSEC key and signing policy for zones. See :ref:`dnssec_policy_grammar` for details. + Describes a DNSSEC key and signing policy for zones. See :any:`dnssec-policy` for details. :namedconf:ref:`key` Specifies key information for use in authentication and authorization using TSIG. @@ -463,16 +463,12 @@ The following ACLs are built-in: ``localnets`` Matches any host on an IPv4 or IPv6 network for which the system has an interface. When addresses are added or removed, the ``localnets`` ACL element is updated to reflect the changes. Some systems do not provide a way to determine the prefix lengths of local IPv6 addresses; in such cases, ``localnets`` only matches the local IPv6 addresses, just like ``localhost``. -.. _controls_grammar: - :any:`controls` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: controls :tags: server :short: Specifies control channels to be used to manage the name server. -.. _controls_statement_definition_and_usage: - :any:`controls` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -543,27 +539,22 @@ To disable the command channel, use an empty :any:`controls` statement: ``controls { };``. -.. _key_grammar: - ``key`` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: key :tags: security :short: Defines a shared secret key for use with :ref:`tsig` or the command channel. -.. _key_statement: - ``key`` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``key`` statement defines a shared secret key for use with TSIG (see -:ref:`tsig`) or the command channel (see :ref:`controls_statement_definition_and_usage`). +:ref:`tsig`) or the command channel (see :any:`controls`). The ``key`` statement can occur at the top level of the configuration file or inside a :any:`view` statement. Keys defined in top-level ``key`` statements can be used in all views. Keys intended for use in a -:any:`controls` statement (see :ref:`controls_statement_definition_and_usage`) -must be defined at the top level. +:any:`controls` statement 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 :namedconf:ref:`server` statement to cause @@ -589,16 +580,12 @@ matching this name, algorithm, and secret. The ``secret_string`` is the secret to be used by the algorithm, and is treated as a Base64-encoded string. -.. _logging_grammar: - :any:`logging` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: logging :tags: logging :short: Configures logging options for the name server. -.. _logging_statement: - :any:`logging` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -815,7 +802,7 @@ Here is an example where all three ``print-`` options are on: There are four predefined channels that are used for :iscman:`named`'s default logging, as follows. If :iscman:`named` is started with the :option:`-L ` option, then a fifth channel, ``default_logfile``, is added. How they are used is described in -:ref:`the_category_phrase`. +:any:`category`. :: @@ -872,8 +859,6 @@ Once a channel is defined, it cannot be redefined. The built-in channels cannot be altered directly, but the default logging can be modified by pointing categories at defined channels. -.. _the_category_phrase: - The :any:`category` Phrase ^^^^^^^^^^^^^^^^^^^^^^^^^^ There are many categories, so desired logs can be sent anywhere @@ -1015,16 +1000,12 @@ At ``debug`` level 4 or higher, the detailed context information logged at ``debug`` level 2 is logged for errors other than SERVFAIL and for negative responses such as NXDOMAIN. -.. _parental_agents_grammar: - :any:`parental-agents` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: parental-agents :tags: zone :short: Defines a list of delegation agents to be used by primary and secondary zones. -.. _parental_agents_statement: - :any:`parental-agents` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1033,16 +1014,12 @@ used by multiple primary and secondary zones. A parental agent is the entity that is allowed to change a zone's delegation information (defined in :rfc:`7344`). -.. _primaries_grammar: - :any:`primaries` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: primaries :tags: zone :short: Defines one or more primary servers for a zone. -.. _primaries_statement: - :any:`primaries` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1068,8 +1045,6 @@ where ``tls-configuration-name`` refers to a previously defined observers but does not protect from man-in-the-middle attacks on zone transfers. -.. _options_grammar: - ``options`` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: options @@ -2924,7 +2899,7 @@ Forwarding can also be configured on a per-domain basis, allowing for the global forwarding options to be overridden in a variety of ways. Particular domains can be set to use different forwarders, or have a different ``forward only/first`` behavior, or not forward at all; see -:ref:`zone_statement_grammar`. +:any:`zone`. .. _dual_stack: @@ -4028,8 +4003,6 @@ Periodic Task Intervals gone away. For convenience, TTL-style time-unit suffixes may be used to specify the value. It also accepts ISO 8601 duration formats. -.. _the_sortlist_statement: - The :any:`sortlist` Statement ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -4134,7 +4107,7 @@ RRset Ordering The :any:`rrset-order` statement permits configuration of the ordering of the records in a multiple-record response. See also: - :ref:`the_sortlist_statement`. + :any:`sortlist`. Each rule in an :any:`rrset-order` statement is defined as follows: @@ -4691,7 +4664,7 @@ Built-in Server Information Zones The server provides some helpful diagnostic information through a number of built-in zones under the pseudo-top-level-domain ``bind`` in the ``CHAOS`` class. These zones are part of a built-in view -(see :ref:`view_statement_grammar`) of class ``CHAOS``, which is +(see :any:`view`) of class ``CHAOS``, which is separate from the default view of class ``IN``. Most global configuration options (:any:`allow-query`, etc.) apply to this view, but some are locally overridden: :namedconf:ref:`notify`, :any:`recursion`, and @@ -5643,7 +5616,7 @@ NXDOMAIN Redirection :iscman:`named` supports NXDOMAIN redirection via two methods: -- Redirect zone (:ref:`zone_statement_grammar`) +- :any:`Redirect zone ` - Redirect namespace With either method, when :iscman:`named` gets an NXDOMAIN response it examines a @@ -5670,16 +5643,12 @@ zone; there are no delegations. If both a redirect zone and a redirect namespace are configured, the redirect zone is tried first. -.. _server_statement_grammar: - ``server`` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: server :tags: server :short: Defines characteristics to be associated with a remote name server. -.. _server_statement_definition_and_usage: - ``server`` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -5803,16 +5772,12 @@ and :namedconf:ref:`options` blocks: - :namedconf:ref:`transfer-source` -.. _statschannels: - :any:`statistics-channels` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: statistics-channels :tags: logging :short: Specifies the communication channels to be used by system administrators to access statistics information on the name server. -.. _statistics_channels: - :any:`statistics-channels` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -6294,16 +6259,12 @@ that is used to initialize the key-maintenance process is stored in can be found, the initializing key is also compiled directly into :iscman:`named`. -.. _dnssec_policy_grammar: - :any:`dnssec-policy` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: dnssec-policy :tags: dnssec :short: Defines a key and signing policy (KASP) for zones. -.. _dnssec_policy: - :any:`dnssec-policy` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -6628,8 +6589,6 @@ with the ``initial-key`` keyword. The :any:`trusted-keys` statement has been deprecated in favor of :any:`trust-anchors` with the ``static-key`` keyword. -.. _view_statement_grammar: - :any:`view` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: view @@ -6646,8 +6605,6 @@ The :any:`trusted-keys` statement has been deprecated in favor of [ zone_statement ; ... ] } ; -.. _view_statement: - :any:`view` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -6746,8 +6703,6 @@ Here is an example of a typical split DNS setup implemented using }; }; -.. _zone_statement_grammar: - :any:`zone` Block Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. namedconf:statement:: zone @@ -6756,8 +6711,6 @@ Here is an example of a typical split DNS setup implemented using :suppress_grammar: -.. _zone_statement: - :any:`zone` Block Definition and Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -6865,7 +6818,7 @@ Zone Types Mirroring a zone other than root requires an explicit list of primary servers to be provided using the :any:`primaries` option (see - :ref:`primaries_grammar` for details), and a key-signing key (KSK) + :any:`primaries` for details), and a key-signing key (KSK) for the specified zone to be explicitly configured as a trust anchor (see :any:`trust-anchors`). @@ -7810,7 +7763,7 @@ There are currently two user interfaces to get access to the statistics. One is in plain-text format, dumped to the file specified by the :any:`statistics-file` configuration option; the other is remotely accessible via a statistics channel when the :any:`statistics-channels` -statement is specified in the configuration file (see :ref:`statschannels`.) +statement is specified in the configuration file. .. _statsfile: diff --git a/doc/arm/troubleshooting.inc.rst b/doc/arm/troubleshooting.inc.rst index 0390ce606b..a395357051 100644 --- a/doc/arm/troubleshooting.inc.rst +++ b/doc/arm/troubleshooting.inc.rst @@ -85,12 +85,11 @@ to make :iscman:`named` prepare such a file, set the ``SSLKEYLOGFILE`` environment variable to either: - the string ``config`` (``SSLKEYLOGFILE=config``); this requires - defining a :any:`logging` :ref:`channel ` which will + defining a :any:`logging` :any:`channel` which will handle messages belonging to the ``sslkeylog`` category, - the path to the key file to write (``SSLKEYLOGFILE=/path/to/file``); - this is equivalent to the following :any:`logging` :ref:`stanza - `: + this is equivalent to the following :any:`logging` configuration: :: diff --git a/doc/arm/zones.inc.rst b/doc/arm/zones.inc.rst index 60289fe272..1807029cac 100644 --- a/doc/arm/zones.inc.rst +++ b/doc/arm/zones.inc.rst @@ -29,7 +29,7 @@ of RRs in a set is not significant and need not be preserved by name servers, resolvers, or other parts of the DNS. However, sorting of multiple RRs is permitted for optimization purposes: for example, to specify that a particular nearby server be tried first. See -:ref:`the_sortlist_statement` and :ref:`rrset_ordering`. +:any:`sortlist` and :ref:`rrset_ordering`. The components of a Resource Record are: