From 07044325eb09e482af47fe4e8c75af3c46bf63bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 3 Mar 2022 22:17:04 +0100 Subject: [PATCH] Hyperlink program names to their manual pages Use the new role :iscman: to replace all occurences or ``binary`` with :iscman:`binary`, creating a hyperlink to the manual page. Generated using: find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done Additional hand-edits were done mainly around filter-aaaa and filter-a which are program names and and option names at the same time. Couple more edits was neede to fix .rst syntax broken by automatic replacement. (cherry picked from commit 53a5776025862492c8067a0918c5ec38970f546c) --- bin/check/named-checkconf.rst | 18 +- bin/check/named-checkzone.rst | 20 +- bin/check/named-compilezone.rst | 26 +- bin/confgen/ddns-confgen.rst | 16 +- bin/confgen/rndc-confgen.rst | 36 +- bin/confgen/tsig-keygen.rst | 2 +- bin/delv/delv.rst | 6 +- bin/dig/dig.rst | 14 +- bin/dig/host.rst | 8 +- bin/dig/nslookup.rst | 6 +- bin/dnssec/dnssec-cds.rst | 18 +- bin/dnssec/dnssec-dsfromkey.rst | 8 +- bin/dnssec/dnssec-importkey.rst | 2 +- bin/dnssec/dnssec-keyfromlabel.rst | 2 +- bin/dnssec/dnssec-keygen.rst | 4 +- bin/dnssec/dnssec-settime.rst | 2 +- bin/dnssec/dnssec-signzone.rst | 14 +- bin/named/named.conf.rst | 2 +- bin/named/named.rst | 4 +- bin/nsupdate/nsupdate.rst | 14 +- bin/plugins/filter-a.rst | 4 +- bin/plugins/filter-aaaa.rst | 8 +- bin/rndc/rndc.conf.rst | 24 +- bin/rndc/rndc.rst | 64 ++-- bin/tools/mdig.rst | 6 +- bin/tools/named-journalprint.rst | 8 +- bin/tools/named-nzd2nzf.rst | 2 +- doc/arm/advanced.rst | 50 +-- doc/arm/build.rst | 10 +- doc/arm/catz.rst | 12 +- doc/arm/configuration.rst | 76 ++--- doc/arm/dlz.rst | 6 +- doc/arm/dnssec.rst | 48 +-- doc/arm/dyndb.rst | 2 +- doc/arm/general.rst | 6 +- doc/arm/introduction.rst | 10 +- doc/arm/logging-categories.rst | 6 +- doc/arm/managed-keys.rst | 8 +- doc/arm/pkcs11.rst | 14 +- doc/arm/plugins.rst | 18 +- doc/arm/reference.rst | 314 +++++++++--------- doc/arm/security.rst | 10 +- doc/arm/troubleshooting.rst | 6 +- doc/dnssec-guide/advanced-discussions.rst | 30 +- doc/dnssec-guide/commonly-asked-questions.rst | 4 +- doc/dnssec-guide/getting-started.rst | 2 +- doc/dnssec-guide/recipes.rst | 46 +-- doc/dnssec-guide/signing.rst | 104 +++--- doc/dnssec-guide/troubleshooting.rst | 24 +- doc/dnssec-guide/validation.rst | 28 +- doc/man/named.conf.5in | 2 +- doc/man/rndc.8in | 4 +- doc/notes/notes-current.rst | 6 +- 53 files changed, 592 insertions(+), 592 deletions(-) diff --git a/bin/check/named-checkconf.rst b/bin/check/named-checkconf.rst index 5c5a84beef..a09e8149fe 100644 --- a/bin/check/named-checkconf.rst +++ b/bin/check/named-checkconf.rst @@ -27,14 +27,14 @@ Description ~~~~~~~~~~~ :program:`named-checkconf` checks the syntax, but not the semantics, of a -``named`` configuration file. The file, along with all files included by it, is parsed and checked for syntax +:iscman:`named` configuration file. The file, along with all files included by it, is parsed and checked for syntax errors. If no file is specified, |named_conf| is read by default. -Note: files that ``named`` reads in separate parser contexts, such as +Note: files that :iscman:`named` reads in separate parser contexts, such as ``rndc.key`` and ``bind.keys``, are not automatically read by :program:`named-checkconf`. Configuration errors in these files may cause -``named`` to fail to run, even if :program:`named-checkconf` was successful. +:iscman:`named` to fail to run, even if :program:`named-checkconf` was successful. However, :program:`named-checkconf` can be run on these files explicitly. Options @@ -46,7 +46,7 @@ Options .. option:: -j - When loading a zonefile, this option instructs ``named`` to read the journal if it exists. + When loading a zonefile, this option instructs :iscman:`named` to read the journal if it exists. .. option:: -l @@ -65,14 +65,14 @@ Options .. option:: -p - This option prints out the ``named.conf`` and included files in canonical form if + This option prints out the :iscman:`named.conf` and included files in canonical form if no errors were detected. See also the :option:`-x` option. .. option:: -t directory - This option instructs ``named`` to chroot to ``directory``, so that ``include`` directives in the + This option instructs :iscman:`named` to chroot to ``directory``, so that ``include`` directives in the configuration file are processed as if run by a similarly chrooted - ``named``. + :iscman:`named`. .. option:: -v @@ -82,14 +82,14 @@ Options When printing the configuration files in canonical form, this option obscures shared secrets by replacing them with strings of question marks - (``?``). This allows the contents of ``named.conf`` and related files + (``?``). This allows the contents of :iscman:`named.conf` and related files to be shared - for example, when submitting bug reports - without compromising private data. This option cannot be used without :option:`-p`. .. option:: -z - This option performs a test load of all zones of type ``primary`` found in ``named.conf``. + This option performs a test load of all zones of type ``primary`` found in :iscman:`named.conf`. .. option:: filename diff --git a/bin/check/named-checkzone.rst b/bin/check/named-checkzone.rst index 147234029d..232d2734c0 100644 --- a/bin/check/named-checkzone.rst +++ b/bin/check/named-checkzone.rst @@ -29,7 +29,7 @@ Description ~~~~~~~~~~~ :program:`named-checkzone` checks the syntax and integrity of a zone file. It -performs the same checks as ``named`` does when loading a zone. This +performs the same checks as :iscman:`named` does when loading a zone. This makes :program:`named-checkzone` useful for checking zone files before configuring them into a name server. @@ -55,13 +55,13 @@ Options .. option:: -j - When loading a zone file, this option tells ``named`` to read the journal if it exists. The journal + When loading a zone file, this option tells :iscman:`named` to read the journal if it exists. The journal file name is assumed to be the zone file name with the string ``.jnl`` appended. .. option:: -J filename - When loading the zone file, this option tells ``named`` to read the journal from the given file, if + When loading the zone file, this option tells :iscman:`named` to read the journal from the given file, if it exists. This implies :option:`-j`. .. option:: -c class @@ -108,9 +108,9 @@ Options Possible formats are ``text`` (the default), which is the standard textual representation of the zone, and ``raw`` and ``raw=N``, which - store the zone in a binary format for rapid loading by ``named``. + store the zone in a binary format for rapid loading by :iscman:`named`. ``raw=N`` specifies the format version of the raw zone file: if ``N`` is - 0, the raw file can be read by any version of ``named``; if N is 1, the + 0, the raw file can be read by any version of :iscman:`named`; if N is 1, the file can only be read by release 9.9.0 or higher. The default is 1. .. option:: -k mode @@ -122,7 +122,7 @@ Options This option sets a maximum permissible TTL for the input file. Any record with a TTL higher than this value causes the zone to be rejected. This - is similar to using the ``max-zone-ttl`` option in ``named.conf``. + is similar to using the ``max-zone-ttl`` option in :iscman:`named.conf`. .. option:: -L serial @@ -174,9 +174,9 @@ Options .. option:: -t directory - This option tells ``named`` to chroot to ``directory``, so that ``include`` directives in the + This option tells :iscman:`named` to chroot to ``directory``, so that ``include`` directives in the configuration file are processed as if run by a similarly chrooted - ``named``. + :iscman:`named`. .. option:: -T mode @@ -186,9 +186,9 @@ Options .. option:: -w directory - This option instructs ``named`` to chdir to ``directory``, so that relative filenames in master file + This option instructs :iscman:`named` to chdir to ``directory``, so that relative filenames in master file ``$INCLUDE`` directives work. This is similar to the directory clause in - ``named.conf``. + :iscman:`named.conf`. .. option:: -D diff --git a/bin/check/named-compilezone.rst b/bin/check/named-compilezone.rst index bd936d3b5b..be719150ca 100644 --- a/bin/check/named-compilezone.rst +++ b/bin/check/named-compilezone.rst @@ -31,9 +31,9 @@ Description :program:`named-compilezone` checks the syntax and integrity of a zone file, and dumps the zone contents to a specified file in a specified format. It applies strict check levels by default, since the -dump output is used as an actual zone file loaded by ``named``. +dump output is used as an actual zone file loaded by :iscman:`named`. When manually specified otherwise, the check levels must at least be as -strict as those specified in the ``named`` configuration file. +strict as those specified in the :iscman:`named` configuration file. Options ~~~~~~~ @@ -53,17 +53,17 @@ Options .. option:: -v - This option prints the version of the ``named-checkzone`` program and exits. + This option prints the version of the :iscman:`named-checkzone` program and exits. .. option:: -j - When loading a zone file, this option tells ``named`` to read the journal if it exists. The journal + When loading a zone file, this option tells :iscman:`named` to read the journal if it exists. The journal file name is assumed to be the zone file name with the string ``.jnl`` appended. .. option:: -J filename - When loading the zone file, this option tells ``named`` to read the journal from the given file, if + When loading the zone file, this option tells :iscman:`named` to read the journal from the given file, if it exists. This implies :option:`-j`. .. option:: -c class @@ -105,14 +105,14 @@ Options .. option:: -F format This option specifies the format of the output file specified. For - ``named-checkzone``, this does not have any effect unless it dumps + :iscman:`named-checkzone`, this does not have any effect unless it dumps the zone contents. Possible formats are ``text`` (the default), which is the standard textual representation of the zone, and ``raw`` and ``raw=N``, which - store the zone in a binary format for rapid loading by ``named``. + store the zone in a binary format for rapid loading by :iscman:`named`. ``raw=N`` specifies the format version of the raw zone file: if ``N`` is - 0, the raw file can be read by any version of ``named``; if N is 1, the + 0, the raw file can be read by any version of :iscman:`named`; if N is 1, the file can only be read by release 9.9.0 or higher. The default is 1. .. option:: -k mode @@ -124,7 +124,7 @@ Options This option sets a maximum permissible TTL for the input file. Any record with a TTL higher than this value causes the zone to be rejected. This - is similar to using the ``max-zone-ttl`` option in ``named.conf``. + is similar to using the ``max-zone-ttl`` option in :iscman:`named.conf`. .. option:: -L serial @@ -175,9 +175,9 @@ Options .. option:: -t directory - This option tells ``named`` to chroot to ``directory``, so that ``include`` directives in the + This option tells :iscman:`named` to chroot to ``directory``, so that ``include`` directives in the configuration file are processed as if run by a similarly chrooted - ``named``. + :iscman:`named`. .. option:: -T mode @@ -187,9 +187,9 @@ Options .. option:: -w directory - This option instructs ``named`` to chdir to ``directory``, so that relative filenames in master file + This option instructs :iscman:`named` to chdir to ``directory``, so that relative filenames in master file ``$INCLUDE`` directives work. This is similar to the directory clause in - ``named.conf``. + :iscman:`named.conf`. .. option:: -D diff --git a/bin/confgen/ddns-confgen.rst b/bin/confgen/ddns-confgen.rst index bed8437c63..f4daccc065 100644 --- a/bin/confgen/ddns-confgen.rst +++ b/bin/confgen/ddns-confgen.rst @@ -29,19 +29,19 @@ Description :program:`ddns-confgen` is an utility that generates keys for use in TSIG signing. The resulting keys can be used, for example, to secure dynamic DNS updates -to a zone, or for the ``rndc`` command channel. +to a zone, or for the :iscman:`rndc` command channel. The key name can specified using :option:`-k` parameter and defaults to ``ddns-key``. The generated key is accompanied by configuration text and instructions that -can be used with ``nsupdate`` and ``named`` when setting up dynamic DNS, +can be used with :iscman:`nsupdate` and :iscman:`named` when setting up dynamic DNS, including an example ``update-policy`` statement. -(This usage is similar to the ``rndc-confgen`` command for setting up +(This usage is similar to the :iscman:`rndc-confgen` command for setting up command-channel security.) -Note that ``named`` itself can configure a local DDNS key for use with +Note that :iscman:`named` itself can configure a local DDNS key for use with :option:`nsupdate -l`; it does this when a zone is configured with ``update-policy local;``. :program:`ddns-confgen` is only needed when a more -elaborate configuration is required: for instance, if ``nsupdate`` is to +elaborate configuration is required: for instance, if :iscman:`nsupdate` is to be used from a remote system. Options @@ -71,12 +71,12 @@ Options This option enables quiet mode, which prints only the key, with no explanatory text or usage examples. This is essentially identical to - ``tsig-keygen``. + :iscman:`tsig-keygen`. .. option:: -s name This option generates a configuration example to allow dynamic updates - of a single hostname. The example ``named.conf`` text shows how to set + of a single hostname. The example :iscman:`named.conf` text shows how to set an update policy for the specified name using the "name" nametype. The default key name is ``ddns-key.name``. Note that the "self" nametype cannot be used, since the name to be updated may differ from the key @@ -85,7 +85,7 @@ Options .. option:: -z zone This option generates a configuration example to allow - dynamic updates of a zone. The example ``named.conf`` text shows how + dynamic updates of a zone. The example :iscman:`named.conf` text shows how to set an update policy for the specified zone using the "zonesub" nametype, allowing updates to all subdomain names within that zone. This option cannot be used with the :option:`-s` option. diff --git a/bin/confgen/rndc-confgen.rst b/bin/confgen/rndc-confgen.rst index 41f857c01c..c32db065a2 100644 --- a/bin/confgen/rndc-confgen.rst +++ b/bin/confgen/rndc-confgen.rst @@ -26,11 +26,11 @@ Synopsis Description ~~~~~~~~~~~ -:program:`rndc-confgen` generates configuration files for ``rndc``. It can be -used as a convenient alternative to writing the ``rndc.conf`` file and -the corresponding ``controls`` and ``key`` statements in ``named.conf`` +:program:`rndc-confgen` generates configuration files for :iscman:`rndc`. It can be +used as a convenient alternative to writing the :iscman:`rndc.conf` file and +the corresponding ``controls`` and ``key`` statements in :iscman:`named.conf` by hand. Alternatively, it can be run with the :option:`-a` option to set up a -``rndc.key`` file and avoid the need for a ``rndc.conf`` file and a +``rndc.key`` file and avoid the need for a :iscman:`rndc.conf` file and a ``controls`` statement altogether. Options @@ -38,16 +38,16 @@ Options .. option:: -a - This option sets automatic ``rndc`` configuration, which creates a file - |rndc_key| that is read by both ``rndc`` and ``named`` on startup. + This option sets automatic :iscman:`rndc` configuration, which creates a file + |rndc_key| that is read by both :iscman:`rndc` and :iscman:`named` on startup. The ``rndc.key`` file defines a default command channel and - authentication key allowing ``rndc`` to communicate with ``named`` on + authentication key allowing :iscman:`rndc` to communicate with :iscman:`named` on the local host with no further configuration. If a more elaborate configuration than that generated by :option:`rndc-confgen -a` is required, for example if rndc is to be used remotely, run :program:`rndc-confgen` without the :option:`-a` option - and set up ``rndc.conf`` and ``named.conf`` as directed. + and set up :iscman:`rndc.conf` and :iscman:`named.conf` as directed. .. option:: -A algorithm @@ -72,13 +72,13 @@ Options .. option:: -k keyname - This option specifies the key name of the ``rndc`` authentication key. This must be a + This option specifies the key name of the :iscman:`rndc` authentication key. This must be a valid domain name. The default is ``rndc-key``. .. option:: -p port - This option specifies the command channel port where ``named`` listens for - connections from ``rndc``. The default is 953. + This option specifies the command channel port where :iscman:`named` listens for + connections from :iscman:`rndc`. The default is 953. .. option:: -q @@ -86,16 +86,16 @@ Options .. option:: -s address - This option specifies the IP address where ``named`` listens for command-channel - connections from ``rndc``. The default is the loopback address + This option specifies the IP address where :iscman:`named` listens for command-channel + connections from :iscman:`rndc`. The default is the loopback address 127.0.0.1. .. option:: -t chrootdir - This option is used with the :option:`-a` option to specify a directory where ``named`` + This option is used with the :option:`-a` option to specify a directory where :iscman:`named` runs chrooted. An additional copy of the ``rndc.key`` is written relative to this directory, so that it is found by the - chrooted ``named``. + chrooted :iscman:`named`. .. option:: -u user @@ -106,12 +106,12 @@ Options Examples ~~~~~~~~ -To allow ``rndc`` to be used with no manual configuration, run: +To allow :iscman:`rndc` to be used with no manual configuration, run: ``rndc-confgen -a`` -To print a sample ``rndc.conf`` file and the corresponding ``controls`` and -``key`` statements to be manually inserted into ``named.conf``, run: +To print a sample :iscman:`rndc.conf` file and the corresponding ``controls`` and +``key`` statements to be manually inserted into :iscman:`named.conf`, run: :program:`rndc-confgen` diff --git a/bin/confgen/tsig-keygen.rst b/bin/confgen/tsig-keygen.rst index 311dcfbb4c..4580ceb3e6 100644 --- a/bin/confgen/tsig-keygen.rst +++ b/bin/confgen/tsig-keygen.rst @@ -29,7 +29,7 @@ Description :program:`tsig-keygen` is an utility that generates keys for use in TSIG signing. The resulting keys can be used, for example, to secure dynamic DNS updates -to a zone, or for the ``rndc`` command channel. +to a zone, or for the :iscman:`rndc` command channel. A domain name can be specified on the command line to be used as the name of the generated key. If no name is specified, the default is ``tsig-key``. diff --git a/bin/delv/delv.rst b/bin/delv/delv.rst index e444825978..f78ef4115d 100644 --- a/bin/delv/delv.rst +++ b/bin/delv/delv.rst @@ -33,7 +33,7 @@ Description ~~~~~~~~~~~ :program:`delv` is a tool for sending DNS queries and validating the results, -using the same internal resolver and validator logic as ``named``. +using the same internal resolver and validator logic as :iscman:`named`. :program:`delv` sends to a specified name server all queries needed to fetch and validate the requested data; this includes the original @@ -113,7 +113,7 @@ Options ``initial-key``, and ``static-key`` identically. That is, for a managed key, it is the *initial* key that is trusted; :rfc:`5011` key management is not supported. :program:`delv` does not consult the managed-keys database maintained by - ``named``, which means that if either of the keys in |bind_keys| is + :iscman:`named`, which means that if either of the keys in |bind_keys| is revoked and rolled over, |bind_keys| must be updated to use DNSSEC validation in :program:`delv`. @@ -322,7 +322,7 @@ assign values to options like the timeout interval. They have the form .. option:: +[no]dnssec This option indicates whether to display RRSIG records in the :program:`delv` output. - The default is to do so. Note that (unlike in ``dig``) this does + The default is to do so. Note that (unlike in :iscman:`dig`) this does *not* control whether to request DNSSEC records or to validate them. DNSSEC records are always requested, and validation always occurs unless suppressed by the use of :option:`-i` or diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst index b6461819d8..cbfdf857f4 100644 --- a/bin/dig/dig.rst +++ b/bin/dig/dig.rst @@ -132,12 +132,12 @@ Options .. option:: -k keyfile - This option tells ``named`` to sign queries using TSIG using a key read from the given file. Key - files can be generated using ``tsig-keygen``. When using TSIG + This option tells :iscman:`named` to sign queries using TSIG using a key read from the given file. Key + files can be generated using :iscman:`tsig-keygen`. When using TSIG authentication with :program:`dig`, the name server that is queried needs to know the key and algorithm that is being used. In BIND, this is done by providing appropriate ``key`` and ``server`` statements in - ``named.conf``. + :iscman:`named.conf`. .. option:: -m @@ -381,7 +381,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to .. option:: +[no]fail - This option indicates that ``named`` should try [or not try] the next server if a SERVFAIL is received. The default is + This option indicates that :iscman:`named` should try [or not try] the next server if a SERVFAIL is received. The default is to not try the next server, which is the reverse of normal stub resolver behavior. @@ -582,7 +582,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to .. option:: +[no]sigchase - This feature is now obsolete and has been removed; use ``delv`` + This feature is now obsolete and has been removed; use :iscman:`delv` instead. .. option:: +split=W @@ -635,7 +635,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to .. option:: +[no]topdown This feature is related to ``dig +sigchase``, which is obsolete and - has been removed. Use ``delv`` instead. + has been removed. Use :iscman:`delv` instead. .. option:: +[no]trace @@ -661,7 +661,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to .. option:: +trusted-key=#### This option formerly specified trusted keys for use with ``dig +sigchase``. This - feature is now obsolete and has been removed; use ``delv`` instead. + feature is now obsolete and has been removed; use :iscman:`delv` instead. .. option:: +[no]ttlid diff --git a/bin/dig/host.rst b/bin/dig/host.rst index fd0445887d..bbc565253e 100644 --- a/bin/dig/host.rst +++ b/bin/dig/host.rst @@ -66,7 +66,7 @@ Options .. option:: -C - This option indicates that ``named`` should check consistency, meaning that :program:`host` queries the SOA records for zone + This option indicates that :iscman:`named` should check consistency, meaning that :program:`host` queries the SOA records for zone ``name`` from all the listed authoritative name servers for that zone. The list of name servers is defined by the NS records that are found for the zone. @@ -77,7 +77,7 @@ Options .. option:: -l - This option tells ``named`` to list the zone, meaning the :program:`host` command performs a zone transfer of zone + This option tells :iscman:`named` to list the zone, meaning the :program:`host` command performs a zone transfer of zone ``name`` and prints out the NS, PTR, and address records (A/AAAA). Together, the :option:`-l` :option:`-a` options print all records in the zone. @@ -112,7 +112,7 @@ Options .. option:: -s - This option tells ``named`` *not* to send the query to the next nameserver if any server responds + This option tells :iscman:`named` *not* to send the query to the next nameserver if any server responds with a SERVFAIL response, which is the reverse of normal stub resolver behavior. @@ -162,7 +162,7 @@ Options .. option:: -W wait - This options sets the length of the wait timeout, indicating that ``named`` should wait for up to ``wait`` seconds for a reply. If ``wait`` is + This options sets the length of the wait timeout, indicating that :iscman:`named` should wait for up to ``wait`` seconds for a reply. If ``wait`` is less than 1, the wait interval is set to 1 second. By default, :program:`host` waits for 5 seconds for UDP responses and 10 diff --git a/bin/dig/nslookup.rst b/bin/dig/nslookup.rst index d885a24400..0462112ab4 100644 --- a/bin/dig/nslookup.rst +++ b/bin/dig/nslookup.rst @@ -63,9 +63,9 @@ Interactive Commands ~~~~~~~~~~~~~~~~~~~~ ``host [server]`` - This command looks up information for ``host`` using the current default server or - using ``server``, if specified. If ``host`` is an Internet address and the - query type is A or PTR, the name of the host is returned. If ``host`` is + This command looks up information for :iscman:`host` using the current default server or + using ``server``, if specified. If :iscman:`host` is an Internet address and the + query type is A or PTR, the name of the host is returned. If :iscman:`host` is a name and does not have a trailing period (``.``), the search list is used to qualify the name. diff --git a/bin/dnssec/dnssec-cds.rst b/bin/dnssec/dnssec-cds.rst index d041db6bec..69b652db09 100644 --- a/bin/dnssec/dnssec-cds.rst +++ b/bin/dnssec/dnssec-cds.rst @@ -39,7 +39,7 @@ file containing the child's CDS and/or CDNSKEY records, plus RRSIG and DNSKEY records so that they can be authenticated. The :option:`-d path <-d>` option specifies the location of a file containing the current DS records. For example, this could be a ``dsset-`` file generated by -``dnssec-signzone``, or the output of ``dnssec-dsfromkey``, or the +:iscman:`dnssec-signzone`, or the output of :iscman:`dnssec-dsfromkey`, or the output of a previous run of :program:`dnssec-cds`. The :program:`dnssec-cds` command uses special DNSSEC validation logic @@ -67,9 +67,9 @@ specify that the child zone wants to be insecure. Be careful not to delete the DS records when :program:`dnssec-cds` fails! -Alternatively, :option`dnssec-cds -u` writes an ``nsupdate`` script to the +Alternatively, :option`dnssec-cds -u` writes an :iscman:`nsupdate` script to the standard output. The :option:`-u` and :option:`-i` options can be used together to -maintain a ``dsset-`` file as well as emit an ``nsupdate`` script. +maintain a ``dsset-`` file as well as emit an :iscman:`nsupdate` script. Options ~~~~~~~ @@ -154,13 +154,13 @@ Options .. option:: -u - This option writes an ``nsupdate`` script to the standard output, instead of + This option writes an :iscman:`nsupdate` script to the standard output, instead of printing the new DS reords. The output is empty if no change is needed. Note: The TTL of new records needs to be specified: it can be done in the original ``dsset-`` file, with the :option:`-T` option, or using the - ``nsupdate`` ``ttl`` command. + :iscman:`nsupdate` ``ttl`` command. .. option:: -V @@ -186,11 +186,11 @@ changed. Examples ~~~~~~~~ -Before running ``dnssec-signzone``, ensure that the delegations +Before running :iscman:`dnssec-signzone`, ensure that the delegations are up-to-date by running :program:`dnssec-cds` on every ``dsset-`` file. To fetch the child records required by :program:`dnssec-cds`, invoke -``dig`` as in the script below. It is acceptable if the ``dig`` fails, since +:iscman:`dig` as in the script below. It is acceptable if the :iscman:`dig` fails, since :program:`dnssec-cds` performs all the necessary checking. :: @@ -202,8 +202,8 @@ To fetch the child records required by :program:`dnssec-cds`, invoke dnssec-cds -i -f /dev/stdin -d $f $d done -When the parent zone is automatically signed by ``named``, -:program:`dnssec-cds` can be used with ``nsupdate`` to maintain a delegation as follows. +When the parent zone is automatically signed by :iscman:`named`, +:program:`dnssec-cds` can be used with :iscman:`nsupdate` to maintain a delegation as follows. The ``dsset-`` file allows the script to avoid having to fetch and validate the parent DS records, and it maintains the replay attack protection time. diff --git a/bin/dnssec/dnssec-dsfromkey.rst b/bin/dnssec/dnssec-dsfromkey.rst index 9548b540d8..2819b028f3 100644 --- a/bin/dnssec/dnssec-dsfromkey.rst +++ b/bin/dnssec/dnssec-dsfromkey.rst @@ -42,13 +42,13 @@ included. The input keys can be specified in a number of ways: By default, :program:`dnssec-dsfromkey` reads a key file named in the format -``Knnnn.+aaa+iiiii.key``, as generated by ``dnssec-keygen``. +``Knnnn.+aaa+iiiii.key``, as generated by :iscman:`dnssec-keygen`. With the :option:`-f file <-f>` option, :program:`dnssec-dsfromkey` reads keys from a zone file or partial zone file (which can contain just the DNSKEY records). With the :option:`-s` option, :program:`dnssec-dsfromkey` reads a ``keyset-`` file, -as generated by ``dnssec-keygen`` :option:`-C`. +as generated by :iscman:`dnssec-keygen` :option:`-C`. Options ~~~~~~~ @@ -94,7 +94,7 @@ Options omitted. If ``file`` is ``-``, then the zone data is read from the standard - input. This makes it possible to use the output of the ``dig`` + input. This makes it possible to use the output of the :iscman:`dig` command as input, as in: ``dig dnskey example.com | dnssec-dsfromkey -f - example.com`` @@ -141,7 +141,7 @@ Files The keyfile can be designated by the key identification ``Knnnn.+aaa+iiiii`` or the full file name ``Knnnn.+aaa+iiiii.key``, as -generated by ``dnssec-keygen``. +generated by :iscman:`dnssec-keygen`. The keyset file name is built from the ``directory``, the string ``keyset-``, and the ``dnsname``. diff --git a/bin/dnssec/dnssec-importkey.rst b/bin/dnssec/dnssec-importkey.rst index 8dd0f09c3f..73f011f615 100644 --- a/bin/dnssec/dnssec-importkey.rst +++ b/bin/dnssec/dnssec-importkey.rst @@ -116,7 +116,7 @@ Files A keyfile can be designed by the key identification ``Knnnn.+aaa+iiiii`` or the full file name ``Knnnn.+aaa+iiiii.key``, as generated by -``dnssec-keygen``. +:iscman:`dnssec-keygen`. See Also ~~~~~~~~ diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst index da0eb4f835..bbb26f1584 100644 --- a/bin/dnssec/dnssec-keyfromlabel.rst +++ b/bin/dnssec/dnssec-keyfromlabel.rst @@ -29,7 +29,7 @@ Description :program:`dnssec-keyfromlabel` generates a pair of key files that reference a key object stored in a cryptographic hardware service module (HSM). The private key file can be used for DNSSEC signing of zone data as if it -were a conventional signing key created by ``dnssec-keygen``, but the +were a conventional signing key created by :iscman:`dnssec-keygen`, but the key material is stored within the HSM and the actual signing takes place there. diff --git a/bin/dnssec/dnssec-keygen.rst b/bin/dnssec/dnssec-keygen.rst index d1a1299419..12b240bcc3 100644 --- a/bin/dnssec/dnssec-keygen.rst +++ b/bin/dnssec/dnssec-keygen.rst @@ -63,7 +63,7 @@ Options In prior releases, HMAC algorithms could be generated for use as TSIG keys, but that feature was removed in BIND 9.13.0. Use - ``tsig-keygen`` to generate TSIG keys. + :iscman:`tsig-keygen` to generate TSIG keys. .. option:: -b keysize @@ -310,7 +310,7 @@ string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and ``Knnnn.+aaa+iiiii.private`` contains the private key. The ``.key`` file contains a DNSKEY or KEY record. When a zone is being -signed by ``named`` or :option:`dnssec-signzone -S`, DNSKEY records are +signed by :iscman:`named` or :option:`dnssec-signzone -S`, DNSKEY records are included automatically. In other cases, the ``.key`` file can be inserted into a zone file manually or with an ``$INCLUDE`` statement. diff --git a/bin/dnssec/dnssec-settime.rst b/bin/dnssec/dnssec-settime.rst index c1bd65681e..1f87049d70 100644 --- a/bin/dnssec/dnssec-settime.rst +++ b/bin/dnssec/dnssec-settime.rst @@ -29,7 +29,7 @@ Description :program:`dnssec-settime` reads a DNSSEC private key file and sets the key timing metadata as specified by the :option:`-P`, :option:`-A`, :option:`-R`, :option:`-I`, and :option:`-D` options. The metadata can then be used by -``dnssec-signzone`` or other signing software to determine when a key is +:iscman:`dnssec-signzone` or other signing software to determine when a key is to be published, whether it should be used for signing a zone, etc. If none of these options is set on the command line, diff --git a/bin/dnssec/dnssec-signzone.rst b/bin/dnssec/dnssec-signzone.rst index 61d03e2041..df84f98515 100644 --- a/bin/dnssec/dnssec-signzone.rst +++ b/bin/dnssec/dnssec-signzone.rst @@ -95,7 +95,7 @@ Options possible time before signatures that have been retrieved by resolvers expire from resolver caches. Zones that are signed with this option should be configured to use a matching ``max-zone-ttl`` in - ``named.conf``. (Note: This option is incompatible with :option:`-D`, + :iscman:`named.conf`. (Note: This option is incompatible with :option:`-D`, because it modifies non-DNSSEC data in the output zone.) .. option:: -s start-time @@ -236,8 +236,8 @@ Options textual representation of the zone; ``full``, which is text output in a format suitable for processing by external scripts; and ``raw`` and ``raw=N``, which store the zone in binary formats for rapid loading by - ``named``. ``raw=N`` specifies the format version of the raw zone file: - if N is 0, the raw file can be read by any version of ``named``; if N is + :iscman:`named`. ``raw=N`` specifies the format version of the raw zone file: + if N is 0, the raw file can be read by any version of :iscman:`named`; if N is 1, the file can be read by release 9.9.0 or higher. The default is 1. .. option:: -P @@ -347,14 +347,14 @@ Options This option indicates that BIND 9 should only sign the DNSKEY, CDNSKEY, and CDS RRsets with key-signing keys, and should omit signatures from zone-signing keys. (This is similar to the - ``dnssec-dnskey-kskonly yes;`` zone option in ``named``.) + ``dnssec-dnskey-kskonly yes;`` zone option in :iscman:`named`.) .. option:: -z This option indicates that BIND 9 should ignore the KSK flag on keys when determining what to sign. This causes KSK-flagged keys to sign all records, not just the DNSKEY RRset. (This is similar to the ``update-check-ksk no;`` zone option in - ``named``.) + :iscman:`named`.) .. option:: -3 salt @@ -393,7 +393,7 @@ Example ~~~~~~~ The following command signs the ``example.com`` zone with the -ECDSAP256SHA256 key generated by ``dnssec-keygen`` +ECDSAP256SHA256 key generated by :iscman:`dnssec-keygen` (Kexample.com.+013+17247). Because the :option:`-S` option is not being used, the zone's keys must be in the master file (``db.example.com``). This invocation looks for ``dsset`` files in the current directory, so that @@ -408,7 +408,7 @@ DS records can be imported from them (:option:`-g`). In the above example, :program:`dnssec-signzone` creates the file ``db.example.com.signed``. This file should be referenced in a zone -statement in the ``named.conf`` file. +statement in the :iscman:`named.conf` file. This example re-signs a previously signed zone with default parameters. The private keys are assumed to be in the current directory. diff --git a/bin/named/named.conf.rst b/bin/named/named.conf.rst index 75a24b6a31..75881596cc 100644 --- a/bin/named/named.conf.rst +++ b/bin/named/named.conf.rst @@ -24,7 +24,7 @@ Synopsis Description ~~~~~~~~~~~ -``named.conf`` is the configuration file for ``named``. Statements are +:iscman:`named.conf` is the configuration file for :iscman:`named`. Statements are enclosed in braces and terminated with a semi-colon. Clauses in the statements are also semi-colon terminated. The usual comment styles are supported: diff --git a/bin/named/named.rst b/bin/named/named.rst index d9befaf0e4..f3557b01e4 100644 --- a/bin/named/named.rst +++ b/bin/named/named.rst @@ -198,13 +198,13 @@ Options This option acquires a lock on the specified file at runtime; this helps to prevent duplicate :program:`named` instances from running simultaneously. Use of this option overrides the ``lock-file`` option in - ``named.conf``. If set to ``none``, the lock file check is disabled. + :iscman:`named.conf`. If set to ``none``, the lock file check is disabled. Signals ~~~~~~~ In routine operation, signals should not be used to control the -nameserver; ``rndc`` should be used instead. +nameserver; :iscman:`rndc` should be used instead. SIGHUP This signal forces a reload of the server. diff --git a/bin/nsupdate/nsupdate.rst b/bin/nsupdate/nsupdate.rst index 1ea4595bf0..05fe3e4fe0 100644 --- a/bin/nsupdate/nsupdate.rst +++ b/bin/nsupdate/nsupdate.rst @@ -49,7 +49,7 @@ and the name server. For instance, suitable ``key`` and ``server`` statements are added to |named_conf| so that the name server can associate the appropriate secret key and algorithm with the IP address of the client application that is using TSIG -authentication. ``ddns-confgen`` can generate suitable +authentication. :iscman:`ddns-confgen` can generate suitable configuration fragments. :program:`nsupdate` uses the :option:`-y` or :option:`-k` options to provide the TSIG shared secret; these options are mutually exclusive. @@ -95,12 +95,12 @@ Options .. option:: -k keyfile This option indicates the file containing the TSIG authentication key. Keyfiles may be in - two formats: a single file containing a ``named.conf``-format ``key`` - statement, which may be generated automatically by ``ddns-confgen``; + two formats: a single file containing a :iscman:`named.conf`-format ``key`` + statement, which may be generated automatically by :iscman:`ddns-confgen`; or a pair of files whose names are of the format ``K{name}.+157.+{random}.key`` and ``K{name}.+157.+{random}.private``, which can be generated by - ``dnssec-keygen``. The :option:`-k` option can also be used to specify a SIG(0) + :iscman:`dnssec-keygen`. The :option:`-k` option can also be used to specify a SIG(0) key used to authenticate Dynamic DNS update requests. In this case, the key specified is not an HMAC-MD5 key. @@ -110,7 +110,7 @@ Options (disabling the ``server`` so that the server address cannot be overridden). Connections to the local server use a TSIG key found in |session_key|, which is automatically - generated by ``named`` if any local ``primary`` zone has set + generated by :iscman:`named` if any local ``primary`` zone has set ``update-policy`` to ``local``. The location of this key file can be overridden with the :option:`-k` option. @@ -366,10 +366,10 @@ Files Sets the default TSIG key for use in local-only mode ``K{name}.+157.+{random}.key`` - Base-64 encoding of the HMAC-MD5 key created by ``dnssec-keygen``. + Base-64 encoding of the HMAC-MD5 key created by :iscman:`dnssec-keygen`. ``K{name}.+157.+{random}.private`` - Base-64 encoding of the HMAC-MD5 key created by ``dnssec-keygen``. + Base-64 encoding of the HMAC-MD5 key created by :iscman:`dnssec-keygen`. See Also ~~~~~~~~ diff --git a/bin/plugins/filter-a.rst b/bin/plugins/filter-a.rst index 4650d6dca7..16b3deea80 100644 --- a/bin/plugins/filter-a.rst +++ b/bin/plugins/filter-a.rst @@ -25,8 +25,8 @@ Synopsis Description ~~~~~~~~~~~ -``filter-a.so`` is a query plugin module for ``named``, enabling -``named`` to omit some IPv4 addresses when responding to clients. +:program:`filter-a.so` is a query plugin module for :iscman:`named`, enabling +:iscman:`named` to omit some IPv4 addresses when responding to clients. For example: diff --git a/bin/plugins/filter-aaaa.rst b/bin/plugins/filter-aaaa.rst index d2ec514947..8cd7556915 100644 --- a/bin/plugins/filter-aaaa.rst +++ b/bin/plugins/filter-aaaa.rst @@ -25,13 +25,13 @@ Synopsis Description ~~~~~~~~~~~ -``filter-aaaa.so`` is a query plugin module for ``named``, enabling -``named`` to omit some IPv6 addresses when responding to clients. +:program:`filter-aaaa.so` is a query plugin module for :iscman:`named`, enabling +:iscman:`named` to omit some IPv6 addresses when responding to clients. -Until BIND 9.12, this feature was implemented natively in ``named`` and +Until BIND 9.12, this feature was implemented natively in :iscman:`named` and enabled with the ``filter-aaaa`` ACL and the ``filter-aaaa-on-v4`` and ``filter-aaaa-on-v6`` options. These options are now deprecated in -``named.conf`` but can be passed as parameters to the +:iscman:`named.conf` but can be passed as parameters to the ``filter-aaaa.so`` plugin, for example: :: diff --git a/bin/rndc/rndc.conf.rst b/bin/rndc/rndc.conf.rst index 1555bb62b5..7a63998e39 100644 --- a/bin/rndc/rndc.conf.rst +++ b/bin/rndc/rndc.conf.rst @@ -26,9 +26,9 @@ Synopsis Description ~~~~~~~~~~~ -:program:`rndc.conf` is the configuration file for ``rndc``, the BIND 9 name +:program:`rndc.conf` is the configuration file for :iscman:`rndc`, the BIND 9 name server control utility. This file has a similar structure and syntax to -``named.conf``. Statements are enclosed in braces and terminated with a +:iscman:`named.conf`. Statements are enclosed in braces and terminated with a semi-colon. Clauses in the statements are also semi-colon terminated. The usual comment styles are supported: @@ -38,13 +38,13 @@ C++ style: // to end of line Unix style: # to end of line -:program:`rndc.conf` is much simpler than ``named.conf``. The file uses three +:program:`rndc.conf` is much simpler than :iscman:`named.conf`. The file uses three statements: an options statement, a server statement, and a key statement. The ``options`` statement contains five clauses. The ``default-server`` clause is followed by the name or address of a name server. This host -is used when no name server is given as an argument to ``rndc``. +is used when no name server is given as an argument to :iscman:`rndc`. The ``default-key`` clause is followed by the name of a key, which is identified by a ``key`` statement. If no ``keyid`` is provided on the rndc command line, and no ``key`` clause is found in a matching @@ -69,14 +69,14 @@ IPv4 and IPv6 source address, respectively. The ``key`` statement begins with an identifying string, the name of the key. The statement has two clauses. ``algorithm`` identifies the -authentication algorithm for ``rndc`` to use; currently only HMAC-MD5 +authentication algorithm for :iscman:`rndc` to use; currently only HMAC-MD5 (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (default), HMAC-SHA384, and HMAC-SHA512 are supported. This is followed by a secret clause which contains the base-64 encoding of the algorithm's authentication key. The base-64 string is enclosed in double quotes. There are two common ways to generate the base-64 string for the secret. -The BIND 9 program ``rndc-confgen`` can be used to generate a random +The BIND 9 program :iscman:`rndc-confgen` can be used to generate a random key, or the ``mmencode`` program, also known as ``mimencode``, can be used to generate a base-64 string from known input. ``mmencode`` does not ship with BIND 9 but is available on many systems. See the Example @@ -120,7 +120,7 @@ Example }; -In the above example, ``rndc`` by default uses the server at +In the above example, :iscman:`rndc` by default uses the server at localhost (127.0.0.1) and the key called "samplekey". Commands to the localhost server use the "samplekey" key, which must also be defined in the server's configuration file with the same name and secret. The @@ -128,16 +128,16 @@ key statement indicates that "samplekey" uses the HMAC-SHA256 algorithm and its secret clause contains the base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes. -If :option:`rndc -s testserver ` is used, then ``rndc`` connects to the server +If :option:`rndc -s testserver ` is used, then :iscman:`rndc` connects to the server on localhost port 5353 using the key "testkey". -To generate a random secret with ``rndc-confgen``: +To generate a random secret with :iscman:`rndc-confgen`: -``rndc-confgen`` +:iscman:`rndc-confgen` A complete :program:`rndc.conf` file, including the randomly generated key, is written to the standard output. Commented-out ``key`` and -``controls`` statements for ``named.conf`` are also printed. +``controls`` statements for :iscman:`named.conf` are also printed. To generate a base-64 secret with ``mmencode``: @@ -148,7 +148,7 @@ Name Server Configuration The name server must be configured to accept rndc connections and to recognize the key specified in the :program:`rndc.conf` file, using the -controls statement in ``named.conf``. See the sections on the +controls statement in :iscman:`named.conf`. See the sections on the ``controls`` statement in the BIND 9 Administrator Reference Manual for details. diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst index 247ddc3a1b..65b6af3ef3 100644 --- a/bin/rndc/rndc.rst +++ b/bin/rndc/rndc.rst @@ -34,7 +34,7 @@ arguments. :program:`rndc` communicates with the name server over a TCP connection, sending commands authenticated with digital signatures. In the current -versions of :program:`rndc` and ``named``, the only supported authentication +versions of :program:`rndc` and :iscman:`named`, the only supported authentication algorithms are HMAC-MD5 (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (default), HMAC-SHA384, and HMAC-SHA512. They use a shared secret on each end of the connection, which provides TSIG-style @@ -94,7 +94,7 @@ Options .. option:: -r - This option instructs :program:`rndc` to print the result code returned by ``named`` + This option instructs :program:`rndc` to print the result code returned by :iscman:`named` after executing the requested command (e.g., ISC_R_SUCCESS, ISC_R_FAILURE, etc.). @@ -105,7 +105,7 @@ Options .. option:: -y key_id This option indicates use of the key ``key_id`` from the configuration file. For control message validation to succeed, ``key_id`` must be known - by ``named`` with the same algorithm and secret string. If no ``key_id`` is specified, + by :iscman:`named` with the same algorithm and secret string. If no ``key_id`` is specified, :program:`rndc` first looks for a key clause in the server statement of the server being used, or if no server statement is present for that host, then in the default-key clause of the options statement. Note that @@ -126,14 +126,14 @@ Currently supported commands are: This command adds a zone while the server is running. This command requires the ``allow-new-zones`` option to be set to ``yes``. The configuration string specified on the command line is the zone configuration text - that would ordinarily be placed in ``named.conf``. + that would ordinarily be placed in :iscman:`named.conf`. The configuration is saved in a file called ``viewname.nzf`` (or, if - ``named`` is compiled with liblmdb, an LMDB database file called + :iscman:`named` is compiled with liblmdb, an LMDB database file called ``viewname.nzd``). ``viewname`` is the name of the view, unless the view name contains characters that are incompatible with use as a file name, in which case a cryptographic hash of the view name is used - instead. When ``named`` is restarted, the file is loaded into + instead. When :iscman:`named` is restarted, the file is loaded into the view configuration so that zones that were added can persist after a restart. @@ -159,10 +159,10 @@ Currently supported commands are: If the zone was originally added via ``rndc addzone``, then it is removed permanently. However, if it was originally configured in - ``named.conf``, then that original configuration remains in place; + :iscman:`named.conf`, then that original configuration remains in place; when the server is restarted or reconfigured, the zone is recreated. To remove it permanently, it must also be removed from - ``named.conf``. + :iscman:`named.conf`. See also :option:`rndc addzone` and :option:`rndc modzone`. @@ -177,7 +177,7 @@ Currently supported commands are: ``rndc dnssec -rollover`` allows you to schedule key rollover for a specific key (overriding the original key lifetime). - ``rndc dnssec -checkds`` will let ``named`` know that the DS for the given + ``rndc dnssec -checkds`` will let :iscman:`named` know that the DS for the given key has been seen published into or withdrawn from the parent. This is required in order to complete a KSK rollover. If the ``-key id`` argument is specified, look for the key with the given identifier, otherwise if there @@ -189,7 +189,7 @@ Currently supported commands are: .. option:: dnstap (-reopen | -roll [number]) This command closes and re-opens DNSTAP output files. ``rndc dnstap -reopen`` allows - the output file to be renamed externally, so that ``named`` can + the output file to be renamed externally, so that :iscman:`named` can truncate and re-open it. ``rndc dnstap -roll`` causes the output file to be rolled automatically, similar to log files. The most recent output file has ".0" appended to its name; the previous most recent @@ -233,8 +233,8 @@ Currently supported commands are: This command stops the server immediately. Recent changes made through dynamic update or IXFR are not saved to the master files, but are rolled forward from the journal files when the server is restarted. If - ``-p`` is specified, ``named``'s process ID is returned. This allows - an external process to determine when ``named`` has completed + ``-p`` is specified, :iscman:`named`'s process ID is returned. This allows + an external process to determine when :iscman:`named` has completed halting. See also :option:`rndc stop`. @@ -279,11 +279,11 @@ Currently supported commands are: Existing keys that are already trusted are not deleted from memory; DNSSEC validation can continue after this command is used. - However, key maintenance operations cease until ``named`` is + However, key maintenance operations cease until :iscman:`named` is restarted or reconfigured, and all existing key maintenance states are deleted. - Running :option:`rndc reconfig` or restarting ``named`` immediately + Running :option:`rndc reconfig` or restarting :iscman:`named` immediately after this command causes key maintenance to be reinitialized from scratch, just as if the server were being started for the first time. This is primarily intended for testing, but it may @@ -297,16 +297,16 @@ Currently supported commands are: command requires the ``allow-new-zones`` option to be set to ``yes``. As with ``addzone``, the configuration string specified on the command line is the zone configuration text that would ordinarily be - placed in ``named.conf``. + placed in :iscman:`named.conf`. If the zone was originally added via :option:`rndc addzone`, the configuration changes are recorded permanently and are still in effect after the server is restarted or reconfigured. However, if - it was originally configured in ``named.conf``, then that original + it was originally configured in :iscman:`named.conf`, then that original configuration remains in place; when the server is restarted or reconfigured, the zone reverts to its original configuration. To make the changes permanent, it must also be modified in - ``named.conf``. + :iscman:`named.conf`. See also :option:`rndc addzone` and :option:`rndc delzone`. @@ -324,18 +324,18 @@ Currently supported commands are: This command sets a DNSSEC negative trust anchor (NTA) for ``domain``, with a lifetime of ``duration``. The default lifetime is configured in - ``named.conf`` via the ``nta-lifetime`` option, and defaults to one + :iscman:`named.conf` via the ``nta-lifetime`` option, and defaults to one hour. The lifetime cannot exceed one week. A negative trust anchor selectively disables DNSSEC validation for zones that are known to be failing because of misconfiguration rather than an attack. When data to be validated is at or below an active - NTA (and above any other configured trust anchors), ``named`` + NTA (and above any other configured trust anchors), :iscman:`named` aborts the DNSSEC validation process and treats the data as insecure rather than bogus. This continues until the NTA's lifetime has elapsed. - NTAs persist across restarts of the ``named`` server. The NTAs for a + NTAs persist across restarts of the :iscman:`named` server. The NTAs for a view are saved in a file called ``name.nta``, where ``name`` is the name of the view; if it contains characters that are incompatible with use as a file name, a cryptographic hash is generated from the name of @@ -353,7 +353,7 @@ Currently supported commands are: of existing NTAs is printed. Note that this may include NTAs that are expired but have not yet been cleaned up. - Normally, ``named`` periodically tests to see whether data below + Normally, :iscman:`named` periodically tests to see whether data below an NTA can now be validated (see the ``nta-recheck`` option in the Administrator Reference Manual for details). If data can be validated, then the NTA is regarded as no longer necessary and is @@ -380,8 +380,8 @@ Currently supported commands are: Query logging can also be enabled by explicitly directing the ``queries`` ``category`` to a ``channel`` in the ``logging`` section - of ``named.conf``, or by specifying ``querylog yes;`` in the - ``options`` section of ``named.conf``. + of :iscman:`named.conf`, or by specifying ``querylog yes;`` in the + ``options`` section of :iscman:`named.conf`. .. option:: reconfig @@ -392,7 +392,7 @@ Currently supported commands are: .. option:: recursing - This command dumps the list of queries ``named`` is currently + This command dumps the list of queries :iscman:`named` is currently recursing on, and the list of domains to which iterative queries are currently being sent. @@ -452,18 +452,18 @@ Currently supported commands are: :program:`rndc` response channel and printed to the standard output. Otherwise, it is written to the secroots dump file, which defaults to ``named.secroots``, but can be overridden via the ``secroots-file`` - option in ``named.conf``. + option in :iscman:`named.conf`. See also :option:`rndc managed-keys`. .. option:: serve-stale (on | off | reset | status) [class [view]] This command enables, disables, resets, or reports the current status of - the serving of stale answers as configured in ``named.conf``. + the serving of stale answers as configured in :iscman:`named.conf`. If serving of stale answers is disabled by ``rndc-serve-stale off``, then it - remains disabled even if ``named`` is reloaded or reconfigured. ``rndc - serve-stale reset`` restores the setting as configured in ``named.conf``. + remains disabled even if :iscman:`named` is reloaded or reconfigured. ``rndc + serve-stale reset`` restores the setting as configured in :iscman:`named.conf`. ``rndc serve-stale status`` reports whether caching and serving of stale answers is currently enabled or disabled. It also reports the values of @@ -520,7 +520,7 @@ Currently supported commands are: chain should be set. ``iterations`` defines the number of additional times to apply the algorithm when generating an NSEC3 hash. The ``salt`` is a string of data expressed in hexadecimal, a hyphen (`-') if no salt is to be - used, or the keyword ``auto``, which causes ``named`` to generate a + used, or the keyword ``auto``, which causes :iscman:`named` to generate a random 64-bit salt. So, for example, to create an NSEC3 chain using the SHA-1 hash @@ -553,8 +553,8 @@ Currently supported commands are: This command stops the server, making sure any recent changes made through dynamic update or IXFR are first saved to the master files of the updated - zones. If ``-p`` is specified, ``named(8)`'s process ID is returned. - This allows an external process to determine when ``named`` has + zones. If ``-p`` is specified, :iscman:`named`'s process ID is returned. + This allows an external process to determine when :iscman:`named` has completed stopping. See also :option:`rndc halt`. @@ -606,7 +606,7 @@ Currently supported commands are: .. option:: tsig-list This command lists the names of all TSIG keys currently configured for use by - ``named`` in each view. The list includes both statically configured keys and + :iscman:`named` in each view. The list includes both statically configured keys and dynamic TKEY-negotiated keys. .. option:: validation (on | off | status) [view ...] diff --git a/bin/tools/mdig.rst b/bin/tools/mdig.rst index fcd0f4d9b6..ec9487bbfd 100644 --- a/bin/tools/mdig.rst +++ b/bin/tools/mdig.rst @@ -30,18 +30,18 @@ Synopsis Description ~~~~~~~~~~~ -:program:`mdig` is a multiple/pipelined query version of ``dig``: instead of +:program:`mdig` is a multiple/pipelined query version of :iscman:`dig`: instead of waiting for a response after sending each query, it begins by sending all queries. Responses are displayed in the order in which they are received, not in the order the corresponding queries were sent. -:program:`mdig` options are a subset of the ``dig`` options, and are divided +:program:`mdig` options are a subset of the :iscman:`dig` options, and are divided into "anywhere options," which can occur anywhere, "global options," which must occur before the query name (or they are ignored with a warning), and "local options," which apply to the next query on the command line. The ``@server`` option is a mandatory global option. It is the name or IP -address of the name server to query. (Unlike ``dig``, this value is not +address of the name server to query. (Unlike :iscman:`dig`, this value is not retrieved from ``/etc/resolv.conf``.) It can be an IPv4 address in dotted-decimal notation, an IPv6 address in colon-delimited notation, or a hostname. When the supplied ``server`` argument is a hostname, diff --git a/bin/tools/named-journalprint.rst b/bin/tools/named-journalprint.rst index c7c33e1b8f..73cd69a233 100644 --- a/bin/tools/named-journalprint.rst +++ b/bin/tools/named-journalprint.rst @@ -30,8 +30,8 @@ Description printing it in a human-readable form, or, optionally, converting it to a different journal file format. -Journal files are automatically created by ``named`` when changes are -made to dynamic zones (e.g., by ``nsupdate``). They record each addition +Journal files are automatically created by :iscman:`named` when changes are +made to dynamic zones (e.g., by :iscman:`nsupdate`). They record each addition or deletion of a resource record, in binary format, allowing the changes to be re-applied to the zone when the server is restarted after a shutdown or crash. By default, the name of the journal file is formed by @@ -45,7 +45,7 @@ the resource record in master-file format. The ``-c`` (compact) option provides a mechanism to reduce the size of a journal by removing (most/all) transactions prior to the specified -serial number. Note: this option *must not* be used while ``named`` is +serial number. Note: this option *must not* be used while :iscman:`named` is running, and can cause data loss if the zone file has not been updated to contain the data being removed from the journal. Use with extreme caution. @@ -58,7 +58,7 @@ replaced. ``-d`` writes out the journal in the format used by versions of BIND up to 9.16.11; ``-u`` writes it out in the format used by versions since 9.16.13. (9.16.12 is omitted due to a journal-formatting bug in that release.) Note that these options *must not* be used while -``named`` is running. +:iscman:`named` is running. See Also ~~~~~~~~ diff --git a/bin/tools/named-nzd2nzf.rst b/bin/tools/named-nzd2nzf.rst index 2e0bede966..9711f8dd7d 100644 --- a/bin/tools/named-nzd2nzf.rst +++ b/bin/tools/named-nzd2nzf.rst @@ -28,7 +28,7 @@ Description :program:`named-nzd2nzf` converts an NZD database to NZF format and prints it to standard output. This can be used to review the configuration of -zones that were added to ``named`` via :option:`rndc addzone`. It can also be +zones that were added to :iscman:`named` via :option:`rndc addzone`. It can also be used to restore the old file format when rolling back from a newer version of BIND to an older version. diff --git a/doc/arm/advanced.rst b/doc/arm/advanced.rst index dbdf5bde23..178d2d22af 100644 --- a/doc/arm/advanced.rst +++ b/doc/arm/advanced.rst @@ -31,9 +31,9 @@ The ``NOTIFY`` protocol is specified in :rfc:`1996`. .. note:: - As a secondary zone can also be a primary to other secondaries, ``named``, by + As a secondary zone can also be a primary to other secondaries, :iscman:`named`, by default, sends ``NOTIFY`` messages for every zone it loads. - Specifying ``notify primary-only;`` causes ``named`` to only send + Specifying ``notify primary-only;`` causes :iscman:`named` to only send ``NOTIFY`` for primary zones that it loads. .. _dynamic_update: @@ -50,7 +50,7 @@ Dynamic update is enabled by including an ``allow-update`` or an If the zone's ``update-policy`` is set to ``local``, updates to the zone are permitted for the key ``local-ddns``, which is generated by -``named`` at startup. See :ref:`dynamic_update_policies` for more details. +:iscman:`named` at startup. See :ref:`dynamic_update_policies` for more details. Dynamic updates using Kerberos-signed requests can be made using the TKEY/GSS protocol, either by setting the ``tkey-gssapi-keytab`` option @@ -385,9 +385,9 @@ a secondary server. This section is a guide to setting up TSIG in BIND. It describes the configuration syntax and the process of creating TSIG keys. -``named`` supports TSIG for server-to-server communication, and some of +:iscman:`named` supports TSIG for server-to-server communication, and some of the tools included with BIND support it for sending messages to -``named``: +:iscman:`named`: * :ref:`man_nsupdate` supports TSIG via the :option:`-k `, :option:`-l `, and :option:`-y ` command-line options, or via the ``key`` command when running interactively. * :ref:`man_dig` supports TSIG via the :option:`-k ` and :option:`-y ` command-line options. @@ -395,9 +395,9 @@ the tools included with BIND support it for sending messages to Generating a Shared Key ~~~~~~~~~~~~~~~~~~~~~~~ -TSIG keys can be generated using the ``tsig-keygen`` command; the output +TSIG keys can be generated using the :iscman:`tsig-keygen` command; the output of the command is a ``key`` directive suitable for inclusion in -``named.conf``. The key name, algorithm, and size can be specified by +:iscman:`named.conf`. The key name, algorithm, and size can be specified by command-line parameters; the defaults are "tsig-key", HMAC-SHA256, and 256 bits, respectively. @@ -415,15 +415,15 @@ server to another is beyond the scope of the DNS. A secure transport mechanism should be used: secure FTP, SSL, ssh, telephone, encrypted email, etc.) -``tsig-keygen`` can also be run as ``ddns-confgen``, in which case its +:iscman:`tsig-keygen` can also be run as :iscman:`ddns-confgen`, in which case its output includes additional configuration text for setting up dynamic DNS -in ``named``. See :ref:`man_ddns-confgen` for details. +in :iscman:`named`. See :ref:`man_ddns-confgen` for details. Loading a New Key ~~~~~~~~~~~~~~~~~ For a key shared between servers called ``host1`` and ``host2``, the -following could be added to each server's ``named.conf`` file: +following could be added to each server's :iscman:`named.conf` file: :: @@ -432,14 +432,14 @@ following could be added to each server's ``named.conf`` file: secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY="; }; -(This is the same key generated above using ``tsig-keygen``.) +(This is the same key generated above using :iscman:`tsig-keygen`.) Since this text contains a secret, it is recommended that either -``named.conf`` not be world-readable, or that the ``key`` directive be +:iscman:`named.conf` not be world-readable, or that the ``key`` directive be stored in a file which is not world-readable and which is included in -``named.conf`` via the ``include`` directive. +:iscman:`named.conf` via the ``include`` directive. -Once a key has been added to ``named.conf`` and the server has been +Once a key has been added to :iscman:`named.conf` and the server has been restarted or reconfigured, the server can recognize the key. If the server receives a message signed by the key, it is able to verify the signature. If the signature is valid, the response is signed @@ -568,7 +568,7 @@ to recursively fetch or validate the key. SIG(0) signing of multiple-message TCP streams is not supported. The only tool shipped with BIND 9 that generates SIG(0) signed messages -is ``nsupdate``. +is :iscman:`nsupdate`. .. _DNSSEC: @@ -602,7 +602,7 @@ another zone above this one in the DNS tree. Generating Keys ~~~~~~~~~~~~~~~ -The ``dnssec-keygen`` program is used to generate keys. +The :iscman:`dnssec-keygen` program is used to generate keys. A secure zone must contain one or more zone keys. The zone keys sign all other records in the zone, as well as the zone keys of any @@ -629,9 +629,9 @@ key (in the ``.key`` file) is used for signature verification. To generate another key with the same properties but with a different key tag, repeat the above command. -The ``dnssec-keyfromlabel`` program is used to get a key pair from a +The :iscman:`dnssec-keyfromlabel` program is used to get a key pair from a crypto hardware device and build the key files. Its usage is similar to -``dnssec-keygen``. +:iscman:`dnssec-keygen`. The public keys should be inserted into the zone file by including the ``.key`` files using ``$INCLUDE`` statements. @@ -641,7 +641,7 @@ The public keys should be inserted into the zone file by including the Signing the Zone ~~~~~~~~~~~~~~~~ -The ``dnssec-signzone`` program is used to sign a zone. +The :iscman:`dnssec-signzone` program is used to sign a zone. Any ``keyset`` files corresponding to secure sub-zones should be present. The zone signer generates ``NSEC``, ``NSEC3``, and ``RRSIG`` @@ -656,9 +656,9 @@ it is in a file called ``zone.child.example``: ``dnssec-signzone -o child.example zone.child.example`` One output file is produced: ``zone.child.example.signed``. This file -should be referenced by ``named.conf`` as the input file for the zone. +should be referenced by :iscman:`named.conf` as the input file for the zone. -``dnssec-signzone`` also produces keyset and dsset files. These are used +:iscman:`dnssec-signzone` also produces keyset and dsset files. These are used to provide the parent zone administrators with the ``DNSKEYs`` (or their corresponding ``DS`` records) that are the secure entry point to the zone. @@ -667,7 +667,7 @@ corresponding ``DS`` records) that are the secure entry point to the zone. Configuring Servers for DNSSEC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To enable ``named`` to validate answers received from other servers, the +To enable :iscman:`named` to validate answers received from other servers, the ``dnssec-validation`` option must be set to either ``yes`` or ``auto``. When ``dnssec-validation`` is set to ``auto``, a trust anchor for the @@ -676,7 +676,7 @@ as part of BIND and is kept up to date using :rfc:`5011` key management. When ``dnssec-validation`` is set to ``yes``, DNSSEC validation only occurs if at least one trust anchor has been explicitly configured -in ``named.conf``, using a ``trust-anchors`` statement (or the +in :iscman:`named.conf`, using a ``trust-anchors`` statement (or the ``managed-keys`` and ``trusted-keys`` statements, both deprecated). When ``dnssec-validation`` is set to ``no``, DNSSEC validation does not @@ -692,7 +692,7 @@ with the keyword ``static-key`` or ``static-ds`` are loaded directly into the table of trust anchors, and can only be changed by altering the configuration. Keys configured with ``initial-key`` or ``initial-ds`` are used to initialize :rfc:`5011` trust anchor maintenance, and are kept up-to-date -automatically after the first time ``named`` runs. +automatically after the first time :iscman:`named` runs. ``trust-anchors`` is described in more detail later in this document. @@ -704,7 +704,7 @@ After DNSSEC is established, a typical DNSSEC configuration looks something like the following. It has one or more public keys for the root, which allows answers from outside the organization to be validated. It also has several keys for parts of the namespace that the -organization controls. These are here to ensure that ``named`` is immune +organization controls. These are here to ensure that :iscman:`named` is immune to compromised security in the DNSSEC components of parent zones. :: diff --git a/doc/arm/build.rst b/doc/arm/build.rst index 01538e4f0a..9ea1cd307d 100644 --- a/doc/arm/build.rst +++ b/doc/arm/build.rst @@ -118,12 +118,12 @@ For DNSTAP packet logging, ``libfstrm`` (https://developers.google.com/protocol-buffers) must be installed, and BIND must be configured with ``--enable-dnstap``. -To support internationalized domain names in ``dig``, ``libidn2`` +To support internationalized domain names in :iscman:`dig`, ``libidn2`` (https://www.gnu.org/software/libidn/#libidn2) must be installed. If the library is installed in a nonstandard location, specify the prefix using ``--with-libidn2=/prefix`` or adjust ``PKG_CONFIG_PATH``. -For line editing in ``nsupdate`` and ``nslookup``, either the +For line editing in :iscman:`nsupdate` and :iscman:`nslookup`, either the ``readline`` (https://tiswww.case.edu/php/chet/readline/rltop.html) or the ``libedit`` library (https://www.thrysoee.dk/editline/) must be installed. If these are installed at a nonstandard location, adjust @@ -152,19 +152,19 @@ specifying ``--enable-fixed-rrset`` or ``--disable-fixed-rrset`` on the ``configure`` command line. By default, fixed RRset-order is disabled to reduce memory footprint. -The ``--enable-querytrace`` option causes ``named`` to log every step +The ``--enable-querytrace`` option causes :iscman:`named` to log every step while processing every query. The ``--enable-singletrace`` option turns on the same verbose tracing, but allows an individual query to be separately traced by setting its query ID to 0. These options should only be enabled when debugging, because they have a significant negative impact on query performance. -``make install`` installs ``named`` and the various BIND 9 libraries. By +``make install`` installs :iscman:`named` and the various BIND 9 libraries. By default, installation is into /usr/local, but this can be changed with the ``--prefix`` option when running ``configure``. The option ``--sysconfdir`` can be specified to set the directory where -configuration files such as ``named.conf`` go by default; +configuration files such as :iscman:`named.conf` go by default; ``--localstatedir`` can be used to set the default parent directory of ``run/named.pid``. ``--sysconfdir`` defaults to ``$prefix/etc`` and ``--localstatedir`` defaults to ``$prefix/var``. diff --git a/doc/arm/catz.rst b/doc/arm/catz.rst index a49a13ff80..18af8cc6ea 100644 --- a/doc/arm/catz.rst +++ b/doc/arm/catz.rst @@ -34,7 +34,7 @@ Principle of Operation ~~~~~~~~~~~~~~~~~~~~~~ Normally, if a zone is to be served by a secondary server, the -``named.conf`` file on the server must list the zone, or the zone must +:iscman:`named.conf` file on the server must list the zone, or the zone must be added using :option:`rndc addzone`. In environments with a large number of secondary servers, and/or where the zones being served are changing frequently, the overhead involved in maintaining consistent zone @@ -48,19 +48,19 @@ 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 ``catalog-zones`` list in the ``options`` or -``view`` statement in ``named.conf``. This is comparable to the way a +``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 ``response-policy`` statement. To use the catalog zone feature to serve a new member zone: - Set up the member zone to be served on the primary as normal. This - can be done by editing ``named.conf`` or by running + can be done by editing :iscman:`named.conf` or by running :option:`rndc addzone`. - Add an entry to the catalog zone for the new member zone. This can be done by editing the catalog zone's zone file and running - :option:`rndc reload`, or by updating the zone using ``nsupdate``. + :option:`rndc reload`, or by updating the zone using :iscman:`nsupdate`. The change to the catalog zone is propagated from the primary to all secondaries using the normal AXFR/IXFR mechanism. When the secondary receives the @@ -85,7 +85,7 @@ Configuring Catalog Zones ~~~~~~~~~~~~~~~~~~~~~~~~~ Catalog zones are configured with a ``catalog-zones`` statement in the -``options`` or ``view`` section of ``named.conf``. For example: +``options`` or ``view`` section of :iscman:`named.conf`. For example: :: @@ -211,7 +211,7 @@ BIND currently supports the following options: These options are the equivalents of ``allow-query`` and - ``allow-transfer`` in a zone declaration in the ``named.conf`` + ``allow-transfer`` in a zone declaration in the :iscman:`named.conf` configuration file. The ACL is processed in order; if there is no match to any rule, the default policy is to deny access. For the syntax of the APL RR, see :rfc:`3123`. diff --git a/doc/arm/configuration.rst b/doc/arm/configuration.rst index 183862b73e..6ef62e2b38 100644 --- a/doc/arm/configuration.rst +++ b/doc/arm/configuration.rst @@ -145,12 +145,12 @@ controlling and debugging the name server daemon. Diagnostic Tools ^^^^^^^^^^^^^^^^ -The ``dig``, ``host``, and ``nslookup`` programs are all command-line +The :iscman:`dig`, :iscman:`host`, and :iscman:`nslookup` programs are all command-line tools for manually querying name servers. They differ in style and output format. -``dig`` - ``dig`` is the most versatile and complete of these lookup tools. It +:iscman:`dig` + :iscman:`dig` is the most versatile and complete of these lookup tools. It has two modes: simple interactive mode for a single query, and batch mode, which executes a query for each in a list of several query lines. All query options are accessible from the command line. @@ -158,23 +158,23 @@ output format. For more information and a list of available commands and options, see :ref:`man_dig`. -``host`` - The ``host`` utility emphasizes simplicity and ease of use. By +:iscman:`host` + The :iscman:`host` utility emphasizes simplicity and ease of use. By default, it converts between host names and Internet addresses, but its functionality can be extended with the use of options. For more information and a list of available commands and options, see :ref:`man_host`. -``nslookup`` - ``nslookup`` has two modes: interactive and non-interactive. +:iscman:`nslookup` + :iscman:`nslookup` has two modes: interactive and non-interactive. Interactive mode allows the user to query name servers for information about various hosts and domains, or to print a list of hosts in a domain. Non-interactive mode is used to print just the name and requested information for a host or domain. Due to its arcane user interface and frequently inconsistent - behavior, we do not recommend the use of ``nslookup``. Use ``dig`` + behavior, we do not recommend the use of :iscman:`nslookup`. Use :iscman:`dig` instead. .. _admin_tools: @@ -185,47 +185,47 @@ Administrative Tools Administrative tools play an integral part in the management of a server. -``named-checkconf`` - The ``named-checkconf`` program checks the syntax of a ``named.conf`` +:iscman:`named-checkconf` + The :iscman:`named-checkconf` program checks the syntax of a :iscman:`named.conf` file. For more information and a list of available commands and options, see :ref:`man_named-checkconf`. -``named-checkzone`` - The ``named-checkzone`` program checks a zone file for syntax and +:iscman:`named-checkzone` + The :iscman:`named-checkzone` program checks a zone file for syntax and consistency. For more information and a list of available commands and options, see :ref:`man_named-checkzone`. -``named-compilezone`` - This tool is similar to ``named-checkzone`` but it always dumps the zone content +:iscman:`named-compilezone` + This tool is similar to :iscman:`named-checkzone` but it always dumps the zone content to a specified file (typically in a different format). For more information and a list of available commands and options, see :ref:`man_named-compilezone`. -``rndc`` - The remote name daemon control (``rndc``) program allows the system +:iscman:`rndc` + The remote name daemon control (:iscman:`rndc`) program allows the system administrator to control the operation of a name server. - See :ref:`man_rndc` for details of the available ``rndc`` + See :ref:`man_rndc` for details of the available :iscman:`rndc` commands. - ``rndc`` requires a configuration file, since all communication with + :iscman:`rndc` requires a configuration file, since all communication with the server is authenticated with digital signatures that rely on a shared secret, and there is no way to provide that secret other than - with a configuration file. The default location for the ``rndc`` + with a configuration file. The default location for the :iscman:`rndc` configuration file is |rndc_conf|, but an alternate location can be specified with the :option:`-c ` option. If the configuration file is - not found, ``rndc`` also looks in |rndc_key| (or whatever + 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`. The format of the configuration file is similar to that of - ``named.conf``, but is limited to only four statements: the ``options``, + :iscman:`named.conf`, but is limited to only four statements: the ``options``, ``key``, ``server``, and ``include`` statements. These statements are what associate the secret keys to the servers with which they are meant to be shared. The order of statements is not significant. @@ -236,12 +236,12 @@ server. contacted if no :option:`-s ` option is provided on the command line. ``default-key`` takes the name of a key as its argument, as defined by a ``key`` statement. ``default-port`` specifies the port to which - ``rndc`` should connect if no port is given on the command line or in + :iscman:`rndc` should connect if no port is given on the command line or in a ``server`` statement. - The ``key`` statement defines a key to be used by ``rndc`` when - authenticating with ``named``. Its syntax is identical to the ``key`` - statement in ``named.conf``. The keyword ``key`` is followed by a 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 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``. @@ -256,7 +256,7 @@ server. name or address. The ``server`` statement has two clauses: ``key`` and ``port``. The ``key`` clause specifies the name of the key to be used when communicating with this server, and the ``port`` clause can - be used to specify the port ``rndc`` should connect to on the server. + be used to specify the port :iscman:`rndc` should connect to on the server. A sample minimal configuration file is as follows: @@ -290,11 +290,11 @@ server. and it has an identical key statement for ``rndc_key``. - Running the ``rndc-confgen`` program conveniently creates an - ``rndc.conf`` file, and also displays the corresponding - ``controls`` statement needed to add to ``named.conf``. + Running the :iscman:`rndc-confgen` program conveniently creates an + :iscman:`rndc.conf` file, and also displays the corresponding + ``controls`` statement needed to add to :iscman:`named.conf`. Alternatively, it is possible to run :option:`rndc-confgen -a` to set up an - ``rndc.key`` file and not modify ``named.conf`` at all. + ``rndc.key`` file and not modify :iscman:`named.conf` at all. Signals ~~~~~~~ @@ -303,13 +303,13 @@ Certain Unix signals cause the name server to take specific actions, as described in the following table. These signals can be sent using the ``kill`` command. -+--------------+-------------------------------------------------------+ -| ``SIGHUP`` | Causes the server to read ``named.conf`` and reload | -| | the database. | -+--------------+-------------------------------------------------------+ -| ``SIGTERM`` | Causes the server to clean up and exit. | -+--------------+-------------------------------------------------------+ -| ``SIGINT`` | Causes the server to clean up and exit. | -+--------------+-------------------------------------------------------+ ++--------------+-------------------------------------------------------------+ +| ``SIGHUP`` | Causes the server to read :iscman:`named.conf` and reload | +| | the database. | ++--------------+-------------------------------------------------------------+ +| ``SIGTERM`` | Causes the server to clean up and exit. | ++--------------+-------------------------------------------------------------+ +| ``SIGINT`` | Causes the server to clean up and exit. | ++--------------+-------------------------------------------------------------+ .. include:: plugins.rst diff --git a/doc/arm/dlz.rst b/doc/arm/dlz.rst index 31daed009e..f24e0e8f29 100644 --- a/doc/arm/dlz.rst +++ b/doc/arm/dlz.rst @@ -20,8 +20,8 @@ no required format or schema. DLZ modules exist for several different database backends, including MySQL and LDAP, and can be written for any other. -The DLZ module provides data to ``named`` in text -format, which is then converted to DNS wire format by ``named``. This +The DLZ module provides data to :iscman:`named` in text +format, which is then converted to DNS wire format by :iscman:`named`. This conversion, and the lack of any internal caching, places significant limits on the query performance of DLZ modules. Consequently, DLZ is not recommended for use on high-volume servers. However, it can be used in a @@ -33,7 +33,7 @@ database. Configuring DLZ ~~~~~~~~~~~~~~~ -A DLZ database is configured with a ``dlz`` statement in ``named.conf``: +A DLZ database is configured with a ``dlz`` statement in :iscman:`named.conf`: :: diff --git a/doc/arm/dnssec.rst b/doc/arm/dnssec.rst index d182f67deb..a90e8cacfa 100644 --- a/doc/arm/dnssec.rst +++ b/doc/arm/dnssec.rst @@ -21,12 +21,12 @@ A zone can be changed from insecure to secure in three ways: using a dynamic DNS update, via the ``auto-dnssec`` zone option, or by setting a DNSSEC policy for the zone with ``dnssec-policy``. -For any method, ``named`` must be configured so that it can see +For any method, :iscman:`named` must be configured so that it can see the ``K*`` files which contain the public and private parts of the keys that are used to sign the zone. These files are generated -by ``dnssec-keygen``, or created when needed by ``named`` if +by :iscman:`dnssec-keygen`, or created when needed by :iscman:`named` if ``dnssec-policy`` is used. Keys should be placed in the -key-directory, as specified in ``named.conf``: +key-directory, as specified in :iscman:`named.conf`: :: @@ -68,7 +68,7 @@ To insert the keys via dynamic update: > send While the update request completes almost immediately, the zone is -not completely signed until ``named`` has had time to "walk" the zone +not completely signed until :iscman:`named` has had time to "walk" the zone and generate the NSEC and RRSIG records. The NSEC record at the apex is added last, to signal that there is a complete NSEC chain. @@ -87,7 +87,7 @@ NSEC3PARAM record. > send Again, this update request completes almost immediately; however, -the record does not show up until ``named`` has had a chance to +the record does not show up until :iscman:`named` has had a chance to build/remove the relevant chain. A private type record is created to record the state of the operation (see below for more details), and is removed once the operation completes. @@ -99,10 +99,10 @@ Fully Automatic Zone Signing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To enable automatic signing, set a ``dnssec-policy`` or add the -``auto-dnssec`` option to the zone statement in ``named.conf``. +``auto-dnssec`` option to the zone statement in :iscman:`named.conf`. ``auto-dnssec`` has two possible arguments: ``allow`` or ``maintain``. -With ``auto-dnssec allow``, ``named`` can search the key directory for +With ``auto-dnssec allow``, :iscman:`named` can search the key directory for keys matching the zone, insert them into the zone, and use them to sign the zone. It does so only when it receives an :option:`rndc sign zonename `. @@ -115,15 +115,15 @@ the keys' timing metadata. (See :ref:`man_dnssec-keygen` and ``dnssec-policy`` is similar to ``auto-dnssec maintain``, but ``dnssec-policy`` also automatically creates new keys when necessary. In addition, any configuration related to DNSSEC signing is retrieved from the -policy, ignoring existing DNSSEC ``named.conf`` options. +policy, ignoring existing DNSSEC :iscman:`named.conf` options. -``named`` periodically searches the key directory for keys matching +:iscman:`named` periodically searches the key directory for keys matching the zone; if the keys' metadata indicates that any change should be made to the zone - such as adding, removing, or revoking a key - then that action is carried out. By default, the key directory is checked for changes every 60 minutes; this period can be adjusted with ``dnssec-loadkeys-interval``, up to a maximum of 24 hours. The -:option:`rndc loadkeys` command forces ``named`` to check for key updates immediately. +:option:`rndc loadkeys` command forces :iscman:`named` to check for key updates immediately. If keys are present in the key directory the first time the zone is loaded, the zone is signed immediately, without waiting for an @@ -196,8 +196,8 @@ Dynamic DNS Update Method ~~~~~~~~~~~~~~~~~~~~~~~~~ To perform key rollovers via a dynamic update, the ``K*`` -files for the new keys must be added so that ``named`` can find them. -The new DNSKEY RRs can then be added via dynamic update. ``named`` then causes the +files for the new keys must be added so that :iscman:`named` can find them. +The new DNSKEY RRs can then be added via dynamic update. :iscman:`named` then causes the zone to be signed with the new keys; when the signing is complete, the private type records are updated so that the last octet is non-zero. @@ -211,15 +211,15 @@ ensures that all clients are able to verify at least one signature when the old DNSKEY is removed. The old DNSKEY can be removed via UPDATE, taking care to specify the -correct key. ``named`` cleans out any signatures generated by the +correct key. :iscman:`named` cleans out any signatures generated by the old key after the update completes. Automatic Key Rollovers ~~~~~~~~~~~~~~~~~~~~~~~ -When a new key reaches its activation date (as set by ``dnssec-keygen`` -or ``dnssec-settime``), and if the ``auto-dnssec`` zone option is set to -``maintain``, ``named`` automatically carries out the key rollover. +When a new key reaches its activation date (as set by :iscman:`dnssec-keygen` +or :iscman:`dnssec-settime`), and if the ``auto-dnssec`` zone option is set to +``maintain``, :iscman:`named` automatically carries out the key rollover. If the key's algorithm has not previously been used to sign the zone, then the zone is fully signed as quickly as possible. However, if the new key replaces an existing key of the same algorithm, the @@ -242,7 +242,7 @@ Converting From NSEC to NSEC3 Add a ``nsec3param`` option to your ``dnssec-policy`` and run :option:`rndc reconfig`. -Or use ``nsupdate`` to add an NSEC3PARAM record. +Or use :iscman:`nsupdate` to add an NSEC3PARAM record. In both cases, the NSEC3 chain is generated and the NSEC3PARAM record is added before the NSEC chain is destroyed. @@ -253,7 +253,7 @@ Converting From NSEC3 to NSEC To do this, remove the ``nsec3param`` option from the ``dnssec-policy`` and run :option:`rndc reconfig`. -Or use ``nsupdate`` to remove all NSEC3PARAM records with a +Or use :iscman:`nsupdate` to remove all NSEC3PARAM records with a zero flag field. The NSEC chain is generated before the NSEC3 chain is removed. @@ -261,12 +261,12 @@ Converting From Secure to Insecure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To convert a signed zone to unsigned using dynamic DNS, delete all the -DNSKEY records from the zone apex using ``nsupdate``. All signatures, +DNSKEY records from the zone apex using :iscman:`nsupdate`. All signatures, NSEC or NSEC3 chains, and associated NSEC3PARAM records are removed automatically. This takes place after the update request completes. This requires the ``dnssec-secure-to-insecure`` option to be set to -``yes`` in ``named.conf``. +``yes`` in :iscman:`named.conf`. In addition, if the ``auto-dnssec maintain`` zone statement is used, it should be removed or changed to ``allow`` instead; otherwise it will re-sign. @@ -274,7 +274,7 @@ should be removed or changed to ``allow`` instead; otherwise it will re-sign. Periodic Re-signing ~~~~~~~~~~~~~~~~~~~ -In any secure zone which supports dynamic updates, ``named`` +In any secure zone which supports dynamic updates, :iscman:`named` periodically re-signs RRsets which have not been re-signed as a result of some update action. The signature lifetimes are adjusted to spread the re-sign load over time rather than all at once. @@ -282,9 +282,9 @@ spread the re-sign load over time rather than all at once. NSEC3 and OPTOUT ~~~~~~~~~~~~~~~~ -``named`` only supports creating new NSEC3 chains where all the NSEC3 -records in the zone have the same OPTOUT state. ``named`` supports +:iscman:`named` only supports creating new NSEC3 chains where all the NSEC3 +records in the zone have the same OPTOUT state. :iscman:`named` supports UPDATES to zones where the NSEC3 records in the chain have mixed OPTOUT -state. ``named`` does not support changing the OPTOUT state of an +state. :iscman:`named` does not support changing the OPTOUT state of an individual NSEC3 record; if the OPTOUT state of an individual NSEC3 needs to be changed, the entire chain must be changed. diff --git a/doc/arm/dyndb.rst b/doc/arm/dyndb.rst index c6d7026f72..8d2c5ba759 100644 --- a/doc/arm/dyndb.rst +++ b/doc/arm/dyndb.rst @@ -35,7 +35,7 @@ Configuring DynDB ~~~~~~~~~~~~~~~~~ A DynDB database is configured with a ``dyndb`` statement in -``named.conf``: +:iscman:`named.conf`: :: diff --git a/doc/arm/general.rst b/doc/arm/general.rst index c1808886be..5b65f6ac9d 100644 --- a/doc/arm/general.rst +++ b/doc/arm/general.rst @@ -394,10 +394,10 @@ Notes .. [#rfc4955] BIND 9 interoperates with correctly designed experiments. -.. [#rfc5452] ``named`` only uses ports to extend the ID space; addresses are not +.. [#rfc5452] :iscman:`named` only uses ports to extend the ID space; addresses are not used. -.. [#rfc6147] Section 5.5 does not match reality. ``named`` uses the presence +.. [#rfc6147] Section 5.5 does not match reality. :iscman:`named` uses the presence of DO=1 to detect if validation may be occurring. CD has no bearing on whether validation occurs. @@ -417,7 +417,7 @@ Notes .. [#rfc7344] Updating of parent zones is not yet implemented. -.. [#rfc7830] ``named`` does not currently encrypt DNS requests, so the PAD option +.. [#rfc7830] :iscman:`named` does not currently encrypt DNS requests, so the PAD option is accepted but not returned in responses. .. [#rfc3363] Section 4 is ignored. diff --git a/doc/arm/introduction.rst b/doc/arm/introduction.rst index 1f7be6c42a..fc80fb8119 100644 --- a/doc/arm/introduction.rst +++ b/doc/arm/introduction.rst @@ -95,7 +95,7 @@ applications. Clients look up information in the DNS by calling a *resolver* library, which sends queries to one or more *name servers* and interprets the responses. The BIND 9 software distribution contains a name server, -``named``, and a set of associated tools. +:iscman:`named`, and a set of associated tools. .. _domain_names: @@ -155,7 +155,7 @@ and we suggest reading :rfc:`1033`, :rfc:`1034`, and :rfc:`1035` to gain a compl understanding of this difficult and subtle topic. Though BIND 9 is called a "domain name server," it deals primarily in -terms of zones. The ``primary`` and ``secondary`` declarations in the ``named.conf`` +terms of zones. The ``primary`` and ``secondary`` declarations in the :iscman:`named.conf` file specify zones, not domains. When BIND asks some other site if it is willing to be a secondary server for a *domain*, it is actually asking for secondary service for some collection of *zones*. @@ -172,7 +172,7 @@ servers, on different networks. Responses from authoritative servers have the "authoritative answer" (AA) bit set in the response packets. This makes them easy to identify -when debugging DNS configurations using tools like ``dig`` (:ref:`diagnostic_tools`). +when debugging DNS configurations using tools like :iscman:`dig` (:ref:`diagnostic_tools`). .. _primary_master: @@ -282,8 +282,8 @@ send queries first to a custom server for RBL processing before forwarding them to the wider Internet. There may be one or more forwarders in a given setup. The order in which -the forwarders are listed in ``named.conf`` does not determine the -sequence in which they are queried; rather, ``named`` uses the response +the forwarders are listed in :iscman:`named.conf` does not determine the +sequence in which they are queried; rather, :iscman:`named` uses the response times from previous queries to select the server that is likely to respond the most quickly. A server that has not yet been queried is given an initial small random response time to ensure that it is tried diff --git a/doc/arm/logging-categories.rst b/doc/arm/logging-categories.rst index d0d276100a..145c54fd43 100644 --- a/doc/arm/logging-categories.rst +++ b/doc/arm/logging-categories.rst @@ -41,7 +41,7 @@ Note: the log message can also be due to packet loss. Before reporting servers for non-:rfc:`1034` compliance they should be re-tested to determine the nature of the non-compliance. This testing should prevent or reduce the number of false-positive reports. - Note: eventually ``named`` will have to stop treating such timeouts as due to :rfc:`1034` non-compliance and start treating it as plain packet loss. Falsely classifying packet loss as due to :rfc:`1034` non-compliance impacts DNSSEC validation, which requires EDNS for the DNSSEC records to be returned. + Note: eventually :iscman:`named` will have to stop treating such timeouts as due to :rfc:`1034` non-compliance and start treating it as plain packet loss. Falsely classifying packet loss as due to :rfc:`1034` non-compliance impacts DNSSEC validation, which requires EDNS for the DNSSEC records to be returned. ``general`` A catch-all for many things that still are not classified into categories. @@ -102,10 +102,10 @@ TLS pre-master secrets (for debugging purposes). ``trust-anchor-telemetry`` - Trust-anchor-telemetry requests received by ``named``. + Trust-anchor-telemetry requests received by :iscman:`named`. ``unmatched`` - Messages that ``named`` was unable to determine the class of, or for which there was no matching ``view``. A one-line summary is also logged to the ``client`` category. This category is best sent to a file or stderr; by default it is sent to the ``null`` channel. + Messages that :iscman:`named` was unable to determine the class of, or for which there was no matching ``view``. A one-line summary is also logged to the ``client`` category. This category is best sent to a file or stderr; by default it is sent to the ``null`` channel. ``update`` Dynamic updates. diff --git a/doc/arm/managed-keys.rst b/doc/arm/managed-keys.rst index d24601eb04..41ea724c04 100644 --- a/doc/arm/managed-keys.rst +++ b/doc/arm/managed-keys.rst @@ -15,7 +15,7 @@ Dynamic Trust Anchor Management ------------------------------- BIND is able to maintain DNSSEC trust anchors using :rfc:`5011` key -management. This feature allows ``named`` to keep track of changes to +management. This feature allows :iscman:`named` to keep track of changes to critical DNSSEC keys without any need for the operator to make changes to configuration files. @@ -45,7 +45,7 @@ has completed, the active KSK can be revoked, and the zone can be "rolled over" to the newly accepted key. The easiest way to place a stand-by key in a zone is to use the "smart -signing" features of ``dnssec-keygen`` and ``dnssec-signzone``. If a key +signing" features of :iscman:`dnssec-keygen` and :iscman:`dnssec-signzone`. If a key exists with a publication date in the past, but an activation date which is unset or in the future, :option:`dnssec-signzone -S` includes the DNSKEY record in the zone but does not sign with it: @@ -55,7 +55,7 @@ DNSKEY record in the zone but does not sign with it: $ dnssec-keygen -K keys -f KSK -P now -A now+2y example.net $ dnssec-signzone -S -K keys example.net -To revoke a key, use the command ``dnssec-revoke``. This +To revoke a key, use the command :iscman:`dnssec-revoke`. This adds the REVOKED bit to the key flags and regenerates the ``K*.key`` and ``K*.private`` files. @@ -77,7 +77,7 @@ wrapping around at 65535. So, for example, the key If two keys have IDs exactly 128 apart and one is revoked, the two key IDs will collide, causing several problems. To prevent this, -``dnssec-keygen`` does not generate a new key if another key +:iscman:`dnssec-keygen` does not generate a new key if another key which may collide is present. This checking only occurs if the new keys are written to the same directory that holds all other keys in use for that zone. diff --git a/doc/arm/pkcs11.rst b/doc/arm/pkcs11.rst index c90f776c09..0dcc664ccf 100644 --- a/doc/arm/pkcs11.rst +++ b/doc/arm/pkcs11.rst @@ -153,7 +153,7 @@ Remember that each key should have unique label and we are going to use that label to reference the private key. Convert the RSA keys stored in the HSM into a format that BIND 9 understands. -The ``dnssec-keyfromlabel`` tool from BIND 9 can link the raw keys stored in the +The :iscman:`dnssec-keyfromlabel` tool from BIND 9 can link the raw keys stored in the HSM with the ``K++`` files. You'll need to provide the OpenSSL engine name (``pkcs11``), the algorithm (``RSASHA256``) and the PKCS#11 label that specify the token (we asume that it has been initialized as bind9), the @@ -216,7 +216,7 @@ Specifying the Engine on the Command Line ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When using OpenSSL-based PKCS#11, the "engine" to be used by OpenSSL can be -specified in ``named`` and all of the BIND ``dnssec-*`` tools by using the ``-E +specified in :iscman:`named` and all of the BIND ``dnssec-*`` tools by using the ``-E `` command line option. Specifying the engine is generally not necessary unless a different OpenSSL engine is used. @@ -227,8 +227,8 @@ provide the name of the OpenSSL engine using the -E command line option. dnssec-signzone -E pkcs11 -S -o example.net example.net -Running ``named`` With Automatic Zone Re-signing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Running :iscman:`named` With Automatic Zone Re-signing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The zone can also be signed automatically by named. Again, we need to provide the name of the OpenSSL engine using the :option:`-E ` command line option. @@ -248,14 +248,14 @@ and the logs should have lines like: DNSKEY example.net/RSASHA256/42231 (ZSK) is now published DNSKEY example.net/RSA256SHA256/42231 (ZSK) is now active -For ``named`` to dynamically re-sign zones using HSM keys, -and/or to sign new records inserted via nsupdate, ``named`` must +For :iscman:`named` to dynamically re-sign zones using HSM keys, +and/or to sign new records inserted via nsupdate, :iscman:`named` must have access to the HSM PIN. In OpenSSL-based PKCS#11, this is accomplished by placing the PIN into the ``openssl.cnf`` file (in the above examples, ``/opt/pkcs11/usr/ssl/openssl.cnf``). The location of the openssl.cnf file can be overridden by setting the -``OPENSSL_CONF`` environment variable before running ``named``. +``OPENSSL_CONF`` environment variable before running :iscman:`named`. Here is a sample ``openssl.cnf``: diff --git a/doc/arm/plugins.rst b/doc/arm/plugins.rst index 1939ac7fef..09b79439e6 100644 --- a/doc/arm/plugins.rst +++ b/doc/arm/plugins.rst @@ -14,7 +14,7 @@ Plugins ------- -Plugins are a mechanism to extend the functionality of ``named`` using +Plugins are a mechanism to extend the functionality of :iscman:`named` using dynamically loadable libraries. By using plugins, core server functionality can be kept simple for the majority of users; more complex code implementing optional features need only be installed by users that @@ -25,17 +25,17 @@ more plugins are added. Currently, only "query plugins" are supported; these modify the name server query logic. Other plugin types may be added in the future. -The only plugin currently included in BIND is ``filter-aaaa.so``, which +The only plugin currently included in BIND is :iscman:`filter-aaaa.so `, which replaces the ``filter-aaaa`` feature that previously existed natively as -part of ``named``. The code for this feature has been removed from -``named`` and can no longer be configured using standard ``named.conf`` -syntax, but linking in the ``filter-aaaa.so`` plugin provides identical +part of :iscman:`named`. The code for this feature has been removed from +:iscman:`named` and can no longer be configured using standard :iscman:`named.conf` +syntax, but linking in the :iscman:`filter-aaaa.so ` plugin provides identical functionality. Configuring Plugins ~~~~~~~~~~~~~~~~~~~ -A plugin is configured with the ``plugin`` statement in ``named.conf``: +A plugin is configured with the ``plugin`` statement in :iscman:`named.conf`: :: @@ -61,7 +61,7 @@ Each plugin implements four functions: - ``plugin_register`` to allocate memory, configure a plugin instance, and attach to hook points within - ``named`` + :iscman:`named` , - ``plugin_destroy`` to tear down the plugin instance and free memory, @@ -71,9 +71,9 @@ Each plugin implements four functions: - ``plugin_check`` to test syntactic correctness of the plugin parameters. -At various locations within the ``named`` source code, there are "hook +At various locations within the :iscman:`named` source code, there are "hook points" at which a plugin may register itself. When a hook point is -reached while ``named`` is running, it is checked to see whether any +reached while :iscman:`named` is running, it is checked to see whether any plugins have registered themselves there; if so, the associated "hook action" - a function within the plugin library - is called. Hook actions may examine the runtime state and make changes: for example, diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index a5b6cc0c5a..9a98de4b00 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -261,7 +261,7 @@ The following statements are supported: Defines a named IP address matching list, for access control and other uses. ``controls`` - Declares control channels to be used by the ``rndc`` utility. + Declares control channels to be used by the :iscman:`rndc` utility. ``dnssec-policy`` Describes a DNSSEC key and signing policy for zones. See :ref:`dnssec-policy Grammar ` for details. @@ -291,7 +291,7 @@ The following statements are supported: Sets certain configuration options on a per-server basis. ``statistics-channels`` - Declares communication channels to get access to ``named`` statistics. + Declares communication channels to get access to :iscman:`named` statistics. ``tls`` Specifies configuration information for a TLS connection, including a ``key-file``, ``cert-file``, ``dhparam-file``, ``ciphers``, ``protocols``, ``prefer-server-ciphers``, and ``session-tickets``. @@ -361,7 +361,7 @@ The following ACLs are built-in: The ``controls`` statement declares control channels to be used by system administrators to manage the operation of the name server. These -control channels are used by the ``rndc`` utility to send commands to +control channels are used by the :iscman:`rndc` utility to send commands to and retrieve non-DNS results from a name server. An ``inet`` control channel is a TCP socket listening at the specified @@ -369,7 +369,7 @@ An ``inet`` control channel is a TCP socket listening at the specified address. An ``ip_addr`` of ``*`` (asterisk) is interpreted as the IPv4 wildcard address; connections are accepted on any of the system's IPv4 addresses. To listen on the IPv6 wildcard address, use an -``ip_addr`` of ``::``. If ``rndc`` is only used on the local host, +``ip_addr`` of ``::``. If :iscman:`rndc` is only used on the local host, using the loopback address (``127.0.0.1`` or ``::1``) is recommended for maximum security. @@ -392,7 +392,7 @@ The primary authorization mechanism of the command channel is the ``key_list``, which contains a list of ``key_id``s. Each ``key_id`` in the ``key_list`` is authorized to execute commands over the control channel. See :ref:`admin_tools` for information about -configuring keys in ``rndc``. +configuring keys in :iscman:`rndc`. If the ``read-only`` clause is enabled, the control channel is limited to the following set of read-only commands: ``nta -dump``, ``null``, @@ -400,10 +400,10 @@ to the following set of read-only commands: ``nta -dump``, ``null``, ``read-only`` is not enabled and the control channel allows read-write access. -If no ``controls`` statement is present, ``named`` sets up a default +If no ``controls`` statement is present, :iscman:`named` sets up a default control channel listening on the loopback address 127.0.0.1 and its IPv6 counterpart, ::1. In this case, and also when the ``controls`` statement -is present but does not have a ``keys`` clause, ``named`` attempts +is present but does not have a ``keys`` clause, :iscman:`named` attempts to load the command channel key from the file |rndc_key|. To create an ``rndc.key`` file, run :option:`rndc-confgen -a`. @@ -459,7 +459,7 @@ match lists to verify that incoming requests have been signed with a key matching this name, algorithm, and secret. The ``algorithm_id`` is a string that specifies a security/authentication -algorithm. The ``named`` server supports ``hmac-md5``, ``hmac-sha1``, +algorithm. The :iscman:`named` server supports ``hmac-md5``, ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, and ``hmac-sha512`` TSIG authentication. Truncated hashes are supported by appending the minimum number of required bits preceded by a dash, e.g., @@ -495,7 +495,7 @@ logging configuration is: category unmatched { null; }; }; -If ``named`` is started with the :option:`-L ` option, it logs to the specified +If :iscman:`named` is started with the :option:`-L ` option, it logs to the specified file at startup, instead of using syslog. In this case the logging configuration is: @@ -525,7 +525,7 @@ whether messages selected for the channel go to a file, go to a particular syslog facility, go to the standard error stream, or are discarded. The definition can optionally also limit the message severity level that is accepted by the channel (the default is ``info``), and whether to include a -``named``-generated time stamp, the category name, and/or the severity level +:iscman:`named`-generated time stamp, the category name, and/or the severity level (the default is not to include any). The ``null`` destination clause causes all messages sent to the channel @@ -540,7 +540,7 @@ many backup versions of the file are saved each time this happens (``suffix``). The ``size`` option is used to limit log file growth. If the file ever -exceeds the specified size, then ``named`` stops writing to the file +exceeds the specified size, then :iscman:`named` stops writing to the file unless it has a ``versions`` option associated with it. If backup versions are kept, the files are rolled as described below. If there is no ``versions`` option, no more data is written to the log until @@ -597,7 +597,7 @@ also determine what eventually passes through. For example, defining a channel facility and severity as ``daemon`` and ``debug``, but only logging ``daemon.warning`` via ``syslog.conf``, causes messages of severity ``info`` and ``notice`` to be dropped. If the situation were -reversed, with ``named`` writing messages of only ``warning`` or higher, +reversed, with :iscman:`named` writing messages of only ``warning`` or higher, then ``syslogd`` would print all messages it received from the channel. The ``stderr`` destination clause directs the channel to the server's @@ -608,7 +608,7 @@ configuration, for example. The server can supply extensive debugging information when it is in debugging mode. If the server's global debug level is greater than zero, debugging mode is active. The global debug level is set either -by starting the ``named`` server with the :option:`-d ` flag followed by a +by starting the :iscman:`named` server with the :option:`-d ` flag followed by a positive integer, or by running :option:`rndc trace`. The global debug level can be set to zero, and debugging mode turned off, by running ``rndc notrace``. All debugging messages in the server have a debug level; @@ -651,8 +651,8 @@ order: time, category, severity. Here is an example where all three If ``buffered`` has been turned on, the output to files is not flushed after each log entry. By default all log messages are flushed. -There are four predefined channels that are used for ``named``'s default -logging, as follows. If ``named`` is started with the :option:`-L ` option, then a fifth +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`. @@ -700,8 +700,8 @@ produces output when the server's debug level is non-zero. It normally writes to a file called ``named.run`` in the server's working directory. For security reasons, when the :option:`-u ` command-line option is used, the -``named.run`` file is created only after ``named`` has changed to the -new UID, and any debug output generated while ``named`` is starting - +``named.run`` file is created only after :iscman:`named` has changed to the +new UID, and any debug output generated while :iscman:`named` is starting - and still running as root - is discarded. To capture this output, run the server with the :option:`-L ` option to specify a default logfile, or the :option:`-g ` option to log to standard error which can @@ -726,7 +726,7 @@ default category is specified, the following "default default" is used: category default { default_syslog; default_debug; }; -If ``named`` is started with the :option:`-L ` option, the default category +If :iscman:`named` is started with the :option:`-L ` option, the default category is: :: @@ -902,7 +902,7 @@ where ``tls-configuration-name`` refers to a previously defined ``options`` Statement Grammar ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is the grammar of the ``options`` statement in the ``named.conf`` +This is the grammar of the ``options`` statement in the :iscman:`named.conf` file: .. include:: ../misc/options.grammar.rst @@ -930,7 +930,7 @@ default is used. statements, in which case it overrides the global ``attach-cache`` option. - The ``cache_name`` specifies the cache to be shared. When the ``named`` + The ``cache_name`` specifies the cache to be shared. When the :iscman:`named` server configures views which are supposed to share a cache, it creates a cache with the specified name for the first view of these sharing views. The rest of the views simply refer to the @@ -985,7 +985,7 @@ default is used. the working directory defaults to ``"."``, the directory from which the server was started. The directory specified should be an absolute path, and *must* be writable by the effective user ID of the - ``named`` process. + :iscman:`named` process. The option takes effect only at the time that the configuration option is parsed; if other files are being included before or after specifying the @@ -1028,13 +1028,13 @@ default is used. resolver query; }; - Logged ``dnstap`` messages can be parsed using the ``dnstap-read`` + Logged ``dnstap`` messages can be parsed using the :iscman:`dnstap-read` utility (see :ref:`man_dnstap-read` for details). For more information on ``dnstap``, see http://dnstap.info. The fstrm library has a number of tunables that are exposed in - ``named.conf``, and can be modified if necessary to improve + :iscman:`named.conf`, and can be modified if necessary to improve performance or prevent loss of data. These are: - ``fstrm-set-buffer-hint``: The threshold number of bytes to @@ -1097,7 +1097,7 @@ default is used. rolling. ``dnstap-output`` can only be set globally in ``options``. Currently, - it can only be set once while ``named`` is running; once set, it + 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`. ``dnstap-identity`` @@ -1111,7 +1111,7 @@ default is used. ``none``, no version string is sent. ``geoip-directory`` - When ``named`` is compiled using the MaxMind GeoIP2 geolocation API, this + When :iscman:`named` is compiled using the MaxMind GeoIP2 geolocation API, this specifies the directory containing GeoIP database files. By default, the option is set based on the prefix used to build the ``libmaxminddb`` module; for example, if the library is installed in ``/usr/local/lib``, then the @@ -1126,7 +1126,7 @@ default is used. ``bind.keys``, ``rndc.key``, or ``session.key``.) ``lmdb-mapsize`` - When ``named`` is built with liblmdb, this option sets a maximum size + When :iscman:`named` is built with liblmdb, this option sets a maximum size for the memory map of the new-zone database (NZD) in LMDB database format. This database is used to store configuration information for zones added using :option:`rndc addzone`. Note that this is not the NZD @@ -1134,8 +1134,8 @@ default is used. to. Because the database file is memory-mapped, its size is limited by - the address space of the ``named`` process. The default of 32 megabytes - was chosen to be usable with 32-bit ``named`` builds. The largest + the address space of the :iscman:`named` process. The default of 32 megabytes + was chosen to be usable with 32-bit :iscman:`named` builds. The largest permitted value is 1 terabyte. Given typical zone configurations without elaborate ACLs, a 32 MB NZD file ought to be able to hold configurations of about 100,000 zones. @@ -1145,9 +1145,9 @@ default is used. keys (i.e., those configured using the ``initial-key`` or ``initial-ds`` keywords in a ``trust-anchors`` statement). By default, this is the working directory. The directory *must* be writable by the effective user ID of the - ``named`` process. + :iscman:`named` process. - If ``named`` is not configured to use views, managed keys for + If :iscman:`named` is not configured to use views, managed keys for the server are tracked in a single file called ``managed-keys.bind``. Otherwise, managed keys are tracked in separate files, one file per view; each file name is the view @@ -1162,7 +1162,7 @@ default is used. ``max-ixfr-ratio`` This sets the size threshold (expressed as a percentage of the size - of the full zone) beyond which ``named`` chooses to use an AXFR + of the full zone) beyond which :iscman:`named` chooses to use an AXFR response rather than IXFR when answering zone transfer requests. See :ref:`incremental_zone_transfers`. @@ -1174,7 +1174,7 @@ default is used. parameters for zones added via :option:`rndc addzone`. By default, this is the working directory. If set to a relative path, it is relative to the working directory. The directory *must* be writable by the - effective user ID of the ``named`` process. + effective user ID of the :iscman:`named` process. ``qname-minimization`` This option controls QNAME minimization behavior in the BIND @@ -1232,16 +1232,16 @@ default is used. on exit. If not specified, the default is ``named.memstats``. ``lock-file`` - This is the pathname of a file on which ``named`` attempts to acquire a + This is the pathname of a file on which :iscman:`named` attempts to acquire a file lock when starting for the first time; if unsuccessful, the server terminates, under the assumption that another server is already running. If not specified, the default is ``none``. Specifying ``lock-file none`` disables the use of a lock file. - ``lock-file`` is ignored if ``named`` was run using the :option:`-X ` + ``lock-file`` is ignored if :iscman:`named` was run using the :option:`-X ` option, which overrides it. Changes to ``lock-file`` are ignored if - ``named`` is being reloaded or reconfigured; it is only effective + :iscman:`named` is being reloaded or reconfigured; it is only effective when the server is first started. ``pid-file`` @@ -1266,7 +1266,7 @@ default is used. ``bindkeys-file`` This is the pathname of a file to override the built-in trusted keys provided - by ``named``. See the discussion of ``dnssec-validation`` for + by :iscman:`named`. See the discussion of ``dnssec-validation`` for details. If not specified, the default is |bind_keys|. ``secroots-file`` @@ -1276,7 +1276,7 @@ default is used. ``session-keyfile`` This is the pathname of the file into which to write a TSIG session key - generated by ``named`` for use by ``nsupdate -l``. If not specified, + generated by :iscman:`named` for use by ``nsupdate -l``. If not specified, the default is |session_key|. (See :ref:`dynamic_update_policies`, and in particular the discussion of the ``update-policy`` statement's ``local`` option, for more information about this feature.) @@ -1413,14 +1413,14 @@ default is used. ``dnssec-must-be-secure`` This specifies hierarchies which must be or may not be secure (signed and - validated). If ``yes``, then ``named`` only accepts answers if + validated). If ``yes``, then :iscman:`named` only accepts answers if they are secure. If ``no``, then normal DNSSEC validation applies, allowing insecure answers to be accepted. The specified domain must be defined as a trust anchor, for instance in a ``trust-anchors`` statement, or ``dnssec-validation auto`` must be active. ``dns64`` - This directive instructs ``named`` to return mapped IPv4 addresses to + This directive instructs :iscman:`named` to return mapped IPv4 addresses to AAAA queries when there are no AAAA records. It is intended to be used in conjunction with a NAT64. Each ``dns64`` defines one DNS64 prefix. Multiple DNS64 prefixes can be defined. @@ -1501,19 +1501,19 @@ default is used. ``dnssec-update-mode`` If this option is set to its default value of ``maintain`` in a zone of type ``primary`` which is DNSSEC-signed and configured to allow - dynamic updates (see :ref:`dynamic_update_policies`), and if ``named`` has access - to the private signing key(s) for the zone, then ``named`` + dynamic updates (see :ref:`dynamic_update_policies`), and if :iscman:`named` has access + to the private signing key(s) for the zone, then :iscman:`named` automatically signs all new or changed records and maintains signatures for the zone by regenerating RRSIG records whenever they approach their expiration date. - If the option is changed to ``no-resign``, then ``named`` signs + If the option is changed to ``no-resign``, then :iscman:`named` signs all new or changed records, but scheduled maintenance of signatures is disabled. - With either of these settings, ``named`` rejects updates to a + With either of these settings, :iscman:`named` rejects updates to a DNSSEC-signed zone when the signing keys are inactive or unavailable - to ``named``. (A planned third option, ``external``, will disable all + to :iscman:`named`. (A planned third option, ``external``, will disable all automatic signing and allow DNSSEC data to be submitted into a zone via dynamic update; this is not yet implemented.) @@ -1524,10 +1524,10 @@ default is used. A negative trust anchor selectively disables DNSSEC validation for zones that are known to be failing because of misconfiguration, rather than an attack. When data to be validated is at or below an active - NTA (and above any other configured trust anchors), ``named`` + NTA (and above any other configured trust anchors), :iscman:`named` aborts the DNSSEC validation process and treats the data as insecure rather than bogus. This continues until the NTA's lifetime has - elapsed. NTAs persist across ``named`` restarts. + elapsed. NTAs persist across :iscman:`named` restarts. For convenience, TTL-style time-unit suffixes can be used to specify the NTA lifetime in seconds, minutes, or hours. It also accepts ISO 8601 duration @@ -1542,7 +1542,7 @@ default is used. A negative trust anchor is normally used when a domain has stopped validating due to operator error; it temporarily disables DNSSEC validation for that domain. In the interest of ensuring that DNSSEC - validation is turned back on as soon as possible, ``named`` + validation is turned back on as soon as possible, :iscman:`named` periodically sends a query to the domain, ignoring negative trust anchors, to find out whether it can now be validated. If so, the negative trust anchor is allowed to expire early. @@ -1643,7 +1643,7 @@ Boolean Options Newly added zones' configuration parameters are stored so that they can persist after the server is restarted. The configuration information is saved in a file called ``viewname.nzf`` (or, if - ``named`` is compiled with liblmdb, in an LMDB database file called + :iscman:`named` is compiled with liblmdb, in an LMDB database file called ``viewname.nzd``). "viewname" is the name of the view, unless the view name contains characters that are incompatible with use as a file name, in which case a cryptographic hash of the view name is used @@ -1651,7 +1651,7 @@ Boolean Options Configurations for zones added at runtime are stored either in a new-zone file (NZF) or a new-zone database (NZD), depending on - whether ``named`` was linked with liblmdb at compile time. See + whether :iscman:`named` was linked with liblmdb at compile time. See :ref:`man_rndc` for further details about :option:`rndc addzone`. ``auth-nxdomain`` @@ -1856,7 +1856,7 @@ Boolean Options at the global options level, not per-view. ``answer-cookie no`` is intended as a temporary measure, for use when - ``named`` shares an IP address with other servers that do not yet + :iscman:`named` shares an IP address with other servers that do not yet support DNS COOKIE. A mismatch between servers on the same address is not expected to cause operational problems, but the option to disable COOKIE responses so that all servers have the same behavior is @@ -1887,9 +1887,9 @@ Boolean Options Stale answers can also be enabled or disabled at runtime via :option:`rndc serve-stale on ` or :option:`rndc serve-stale off `; these override the configured setting. :option:`rndc serve-stale reset ` restores the - setting to the one specified in ``named.conf``. Note that if stale - answers have been disabled by ``rndc``, they cannot be - re-enabled by reloading or reconfiguring ``named``; they must be + setting to the one specified in :iscman:`named.conf`. Note that if stale + answers have been disabled by :iscman:`rndc`, they cannot be + re-enabled by reloading or reconfiguring :iscman:`named`; they must be re-enabled with :option:`rndc serve-stale on `, or the server must be restarted. @@ -1897,9 +1897,9 @@ Boolean Options log category. ``stale-answer-client-timeout`` - This option defines the amount of time (in milliseconds) that ``named`` + This option defines the amount of time (in milliseconds) that :iscman:`named` waits before attempting to answer the query with a stale RRset from cache. - If a stale answer is found, ``named`` continues the ongoing fetches, + If a stale answer is found, :iscman:`named` continues the ongoing fetches, attempting to refresh the RRset in cache until the ``resolver-query-timeout`` interval is reached. @@ -1918,7 +1918,7 @@ Boolean Options ``stale-refresh-time`` If the name servers for a given zone are not answering, this sets the time - window for which ``named`` will promptly return "stale" cached answers for + window for which :iscman:`named` will promptly return "stale" cached answers for that RRSet being requested before a new attempt in contacting the servers is made. For convenience, TTL-style time-unit suffixes may be used to specify the value. It also accepts ISO 8601 duration formats. @@ -1926,7 +1926,7 @@ Boolean Options The default ``stale-refresh-time`` is 30 seconds, as :rfc:`8767` recommends that attempts to refresh to be done no more frequently than every 30 seconds. A value of zero disables the feature, meaning that normal - resolution will take place first, if that fails only then ``named`` will + resolution will take place first, if that fails only then :iscman:`named` will return "stale" cached answers. ``nocookie-udp-size`` @@ -1949,7 +1949,7 @@ Boolean Options or "aes". If there are multiple secrets specified, the first one listed in - ``named.conf`` is used to generate new server cookies. The others + :iscman:`named.conf` is used to generate new server cookies. The others are only used to verify returned cookies. ``response-padding`` @@ -1973,7 +1973,7 @@ Boolean Options of two (for instance, 128), but this is not mandatory. ``trust-anchor-telemetry`` - This causes ``named`` to send specially formed queries once per day to + This causes :iscman:`named` to send specially formed queries once per day to domains for which trust anchors have been configured via, e.g., ``trust-anchors`` or ``dnssec-validation auto``. @@ -2006,7 +2006,7 @@ Boolean Options operating systems that causes IPv4 TCP connections, such as zone transfers, to be accepted on an IPv6 socket using mapped addresses. This caused address-match lists designed for IPv4 to fail to match. - However, ``named`` now solves this problem internally. The use of + However, :iscman:`named` now solves this problem internally. The use of this option is discouraged. ``ixfr-from-differences`` @@ -2035,8 +2035,8 @@ Boolean Options ``multi-master`` This should be set when there are multiple primary servers for a zone and the - addresses refer to different machines. If ``yes``, ``named`` does not - log when the serial number on the primary is less than what ``named`` + addresses refer to different machines. If ``yes``, :iscman:`named` does not + log when the serial number on the primary is less than what :iscman:`named` currently has. The default is ``no``. ``auto-dnssec`` @@ -2051,9 +2051,9 @@ Boolean Options automatically adjusts the zone's DNSSEC keys on a schedule, according to the keys' timing metadata (see :ref:`man_dnssec-keygen` and :ref:`man_dnssec-settime`). The command :option:`rndc sign zonename ` - causes ``named`` to load keys from the key repository and sign the + causes :iscman:`named` to load keys from the key repository and sign the zone with all keys that are active. :option:`rndc loadkeys zonename ` - causes ``named`` to load keys from the key repository and schedule + causes :iscman:`named` to load keys from the key repository and schedule key maintenance events to occur in the future, but it does not sign the full zone immediately. Note: once keys have been loaded for a zone the first time, the repository is searched for changes @@ -2069,7 +2069,7 @@ Boolean Options .. _dnssec-validation-option: ``dnssec-validation`` - This option enables DNSSEC validation in ``named``. + This option enables DNSSEC validation in :iscman:`named`. If set to ``auto``, DNSSEC validation is enabled and a default trust anchor for the DNS root zone is used. @@ -2086,18 +2086,18 @@ Boolean Options ``yes``. The default root trust anchor is stored in the file ``bind.keys``. - ``named`` loads that key at startup if ``dnssec-validation`` is + :iscman:`named` loads that key at startup if ``dnssec-validation`` is set to ``auto``. A copy of the file is installed along with BIND 9, and is current as of the release date. If the root key expires, a new copy of ``bind.keys`` can be downloaded from https://www.isc.org/bind-keys. (To prevent problems if ``bind.keys`` is not found, the current trust - anchor is also compiled in ``named``. Relying on this is not - recommended, however, as it requires ``named`` to be recompiled with + anchor is also compiled in :iscman:`named`. Relying on this is not + recommended, however, as it requires :iscman:`named` to be recompiled with a new key when the root key expires.) - .. note:: ``named`` loads *only* the root key from ``bind.keys``. The file + .. note:: :iscman:`named` loads *only* the root key from ``bind.keys``. The file cannot be used to store keys for other zones. The root key in ``bind.keys`` is ignored if ``dnssec-validation auto`` is not in use. @@ -2119,7 +2119,7 @@ Boolean Options ``dnssec-accept-expired`` This accepts expired signatures when verifying DNSSEC signatures. The - default is ``no``. Setting this option to ``yes`` leaves ``named`` + default is ``no``. Setting this option to ``yes`` leaves :iscman:`named` vulnerable to replay attacks. ``querylog`` @@ -2128,7 +2128,7 @@ Boolean Options cost to performance which may be significant on heavily loaded servers. The ``querylog`` option specifies whether query logging should be active when - ``named`` first starts. If ``querylog`` is not specified, then query logging + :iscman:`named` first starts. If ``querylog`` is not specified, then query logging is determined by the presence of the logging category ``queries``. Query logging can also be activated at runtime using the command ``rndc querylog on``, or deactivated with :option:`rndc querylog off `. @@ -2172,9 +2172,9 @@ Boolean Options that MX and SRV records refer to address (A or AAAA) records and that glue address records exist for delegated zones. For MX and SRV records, only in-zone hostnames are checked (for out-of-zone hostnames, - use ``named-checkzone``). For NS records, only names below top-of-zone + use :iscman:`named-checkzone`). For NS records, only names below top-of-zone are checked (for out-of-zone names and glue consistency checks, use - ``named-checkzone``). The default is ``yes``. + :iscman:`named-checkzone`). The default is ``yes``. The use of the SPF record to publish Sender Policy Framework is deprecated, as the migration from using TXT records to SPF records was @@ -2257,7 +2257,7 @@ Boolean Options Note that if a zone has been configured with ``auto-dnssec maintain`` and the private keys remain accessible in the key repository, - the zone will be automatically signed again the next time ``named`` + the zone will be automatically signed again the next time :iscman:`named` is started. ``synth-from-dnssec`` @@ -2393,7 +2393,7 @@ for details on how to specify IP address lists. ``allow-recursion-on`` is not set, then ``allow-query-cache-on`` is used if set; otherwise, the default is to allow recursive queries on all addresses. Any client permitted to send recursive queries can - send them to any address on which ``named`` is listening. Note: both + send them to any address on which :iscman:`named` is listening. Note: both ``allow-recursion`` and ``allow-recursion-on`` must be satisfied before recursion is allowed; a client that is blocked by one cannot be allowed by the other. @@ -2471,7 +2471,7 @@ for details on how to specify IP address lists. ``no-case-compress`` This specifies a list of addresses which require responses to use - case-insensitive compression. This ACL can be used when ``named`` + case-insensitive compression. This ACL can be used when :iscman:`named` needs to work with clients that do not comply with the requirement in :rfc:`1034` to use case-insensitive name comparisons when checking for matching domain names. @@ -2493,7 +2493,7 @@ for details on how to specify IP address lists. Case-insensitive compression is *always* used in AXFR and IXFR responses, regardless of whether the client matches this ACL. - There are circumstances in which ``named`` does not preserve the case + There are circumstances in which :iscman:`named` does not preserve the case of owner names of records: if a zone file defines records of different types with the same name, but the capitalization of the name is different (e.g., "www.example.com/A" and @@ -2537,16 +2537,16 @@ The server listens on all interfaces allowed by the address match list. If no ``listen-on-v6`` is specified, the default is to listen for standard DNS queries on port 53 of all IPv6 interfaces. -If a TLS configuration is specified, ``named`` will listen for DNS-over-TLS +If a TLS configuration is specified, :iscman:`named` will listen for DNS-over-TLS (DoT) connections, using the key and certificate specified in the referenced ``tls`` statement. If the name ``ephemeral`` is used, an ephemeral key and certificate created for the currently running -``named`` process will be used. +:iscman:`named` process will be used. -If an HTTP configuration is specified, ``named`` will listen for +If an HTTP configuration is specified, :iscman:`named` will listen for DNS-over-HTTPS (DoH) connections using the HTTP endpoint specified in the referenced ``http`` statement. If the name ``default`` is used, then -``named`` will listen for connections at the default endpoint, +:iscman:`named` will listen for connections at the default endpoint, ``/dns-query``. Use of an ``http`` specification requires ``tls`` to be specified @@ -2631,9 +2631,9 @@ are: query-source-v6 address * port *; If ``use-v4-udp-ports`` or ``use-v6-udp-ports`` is unspecified, -``named`` checks whether the operating system provides a programming +:iscman:`named` checks whether the operating system provides a programming interface to retrieve the system's default range for ephemeral ports. If -such an interface is available, ``named`` uses the corresponding +such an interface is available, :iscman:`named` uses the corresponding system default range; otherwise, it uses its own defaults: :: @@ -2653,15 +2653,15 @@ options are: desirable size depends on several parameters, but we generally recommend it contain at least 16384 ports (14 bits of entropy). Note also that the system's default range when used may be too small for this purpose, and - that the range may even be changed while ``named`` is running; the new - range is automatically applied when ``named`` is reloaded. Explicit + that the range may even be changed while :iscman:`named` is running; the new + range is automatically applied when :iscman:`named` is reloaded. Explicit configuration of ``use-v4-udp-ports`` and ``use-v6-udp-ports`` is encouraged, so that the ranges are sufficiently large and are reasonably independent from the ranges used by other applications. -.. note:: The operational configuration where ``named`` runs may prohibit +.. note:: The operational configuration where :iscman:`named` runs may prohibit the use of some ports. For example, Unix systems do not allow - ``named``, if run without root privilege, to use ports less than 1024. + :iscman:`named`, if run without root privilege, to use ports less than 1024. If such ports are included in the specified (or detected) set of query ports, the corresponding query attempts will fail, resulting in resolution failures or delay. It is therefore important to configure the @@ -2881,11 +2881,11 @@ determined. For example, with the following configuration: use-v6-udp-ports { range 32768 65535; }; avoid-v6-udp-ports { 40000; range 50000 60000; }; -UDP ports of IPv6 messages sent from ``named`` are in one of the +UDP ports of IPv6 messages sent from :iscman:`named` are in one of the following ranges: 32768 to 39999, 40001 to 49999, and 60001 to 65535. ``avoid-v4-udp-ports`` and ``avoid-v6-udp-ports`` can be used to prevent -``named`` from choosing as its random source port a port that is blocked +:iscman:`named` from choosing as its random source port a port that is blocked by a firewall or a port that is used by other applications; if a query went out with a source port blocked by a firewall, the answer would not pass through the firewall and the name server would have to query @@ -2988,13 +2988,13 @@ system. ``clients-per-query``; ``max-clients-per-query`` These set the initial value (minimum) and maximum number of recursive simultaneous clients for any given query () that - the server accepts before dropping additional clients. ``named`` + the server accepts before dropping additional clients. :iscman:`named` attempts to self-tune this value and changes are logged. The default values are 10 and 100. This value should reflect how many queries come in for a given name in the time it takes to resolve that name. If the number of queries - exceeds this value, ``named`` assumes that it is dealing with a + exceeds this value, :iscman:`named` assumes that it is dealing with a non-responsive zone and drops additional queries. If it gets a response after dropping queries, it raises the estimate. The estimate is then lowered in 20 minutes if it has remained @@ -3100,7 +3100,7 @@ system. :ref:`attach-cache ` option is used). When the amount of data in a cache database reaches the configured - limit, ``named`` starts purging non-expired records (following an + limit, :iscman:`named` starts purging non-expired records (following an LRU-based strategy). The default size limit for each individual cache is: @@ -3132,7 +3132,7 @@ system. On systems where detection of the amount of physical memory is not supported, percentage-based values fall back to ``unlimited``. Note that the amount of physical memory available is only detected on - startup, so ``named`` does not adjust the cache size limits if the + startup, so :iscman:`named` does not adjust the cache size limits if the amount of physical memory is changed at runtime. ``tcp-listen-queue`` @@ -3350,7 +3350,7 @@ The legal values for ```` are: long as the database is not modified. The default RRset order used depends on whether any ``rrset-order`` -statements are present in the configuration file used by ``named``: +statements are present in the configuration file used by :iscman:`named`: - If no ``rrset-order`` statement is present in the configuration file, the implicit default is to return all records in ``random`` @@ -3481,10 +3481,10 @@ Tuning ``sig-validity-interval`` this specifies the upper bound of the number of days that RRSIGs - generated by ``named`` are valid; the default is ``30`` days, + generated by :iscman:`named` are valid; the default is ``30`` days, with a maximum of 3660 days (10 years). The optional second value specifies the minimum bound on those RRSIGs and also determines - how long before expiry ``named`` starts regenerating those RRSIGs. + how long before expiry :iscman:`named` starts regenerating those RRSIGs. The default value for the lower bound is 1/4 of the upper bound; it is expressed in days if the upper bound is greater than 7, and hours if it is less than or equal to 7 days. @@ -3532,10 +3532,10 @@ Tuning This parameter may be removed in a future version, once there is a standard type. - Signing-state records are used internally by ``named`` to track + Signing-state records are used internally by :iscman:`named` to track the current state of a zone-signing process, i.e., whether it is still active or has been completed. The records can be inspected - using the command :option:`rndc signing -list zone `. Once ``named`` has + using the command :option:`rndc signing -list zone `. Once :iscman:`named` has finished signing a zone with a particular key, the signing-state record associated with that key can be removed from the zone by running :option:`rndc signing -clear keyid/algorithm zone `. To clear all of @@ -3570,7 +3570,7 @@ Tuning fragmented packets and/or block UDP DNS packets that are greater than 512 bytes. - When ``named`` first queries a remote server, it advertises a UDP + When :iscman:`named` first queries a remote server, it advertises a UDP buffer size of 1232. Query timeouts observed for any given server affect the buffer size @@ -3578,7 +3578,7 @@ Tuning dropping patterns, the query is retried over TCP. Per-server EDNS statistics are only retained in memory for the lifetime of a given server's ADB entry. - The ``named`` now sets the DON'T FRAGMENT flag on outgoing UDP packets. + The :iscman:`named` now sets the DON'T FRAGMENT flag on outgoing UDP packets. According to the measurements done by multiple parties this should not be causing any operational problems as most of the Internet "core" is able to cope with IP message sizes between 1400-1500 bytes, the 1232 size was picked @@ -3592,7 +3592,7 @@ Tuning the above rules. ``max-udp-size`` - This sets the maximum EDNS UDP message size that ``named`` sends, in bytes. + This sets the maximum EDNS UDP message size that :iscman:`named` sends, in bytes. Valid values are 512 to 4096; values outside this range are silently adjusted to the nearest value within it. The default value is 1232. @@ -3614,15 +3614,15 @@ Tuning for details). The default value is ``text``, which is the standard textual representation, except for secondary zones, in which the default value is ``raw``. Files in formats other than ``text`` are typically - expected to be generated by the ``named-compilezone`` tool, or dumped by - ``named``. + expected to be generated by the :iscman:`named-compilezone` tool, or dumped by + :iscman:`named`. Note that when a zone file in a format other than ``text`` is loaded, - ``named`` may omit some of the checks which are performed for a file in + :iscman:`named` may omit some of the checks which are performed for a file in ``text`` format. For example, ``check-names`` only applies when loading zones in ``text`` format, and ``max-zone-ttl`` only applies to ``text`` and ``raw``. Zone files in binary formats should be generated with the - same check level as that specified in the ``named`` configuration file. + same check level as that specified in the :iscman:`named` configuration file. When configured in ``options``, this statement sets the ``masterfile-format`` for all zones, but it can be overridden on a @@ -3673,7 +3673,7 @@ Tuning ``prefetch`` When a query is received for cached data which is to expire shortly, - ``named`` can refresh the data from the authoritative server + :iscman:`named` can refresh the data from the authoritative server immediately, ensuring that the cache always has an answer available. ``prefetch`` specifies the "trigger" TTL value at which prefetch @@ -3687,7 +3687,7 @@ Tuning An optional second argument specifies the "eligibility" TTL: the smallest *original* TTL value that is accepted for a record to be eligible for prefetching. The eligibility TTL must be at least six - seconds longer than the trigger TTL; if not, ``named`` + seconds longer than the trigger TTL; if not, :iscman:`named` silently adjusts it upward. The default eligibility TTL is ``9``. ``v6-bias`` @@ -3762,7 +3762,7 @@ that matches all clients. type ``TXT`` and class ``CHAOS``. The primary purpose of such queries is to identify which of a group of anycast servers is actually answering the queries. Specifying ``server-id none;`` disables processing of - the queries. Specifying ``server-id hostname;`` causes ``named`` + the queries. Specifying ``server-id hostname;`` causes :iscman:`named` to use the hostname as found by the ``gethostname()`` function. The default ``server-id`` is ``none``. @@ -3771,7 +3771,7 @@ that matches all clients. Built-in Empty Zones ^^^^^^^^^^^^^^^^^^^^ -The ``named`` server has some built-in empty zones, for SOA and NS records +The :iscman:`named` server has some built-in empty zones, for SOA and NS records only. These are for zones that should normally be answered locally and for which queries should not be sent to the Internet's root servers. The official servers that cover these namespaces return NXDOMAIN responses @@ -4095,7 +4095,7 @@ Five policy triggers can be encoded in RPZ records. ``nsdname-enable`` phrase turns NSDNAME triggers off or on for a single policy zone or for all zones. - If authoritative name servers for the query name are not yet known, ``named`` + If authoritative name servers for the query name are not yet known, :iscman:`named` recursively looks up the authoritative servers for the query name before applying an RPZ-NSDNAME rule, which can cause a processing delay. To speed up processing at the cost of precision, the ``nsdname-wait-recurse`` option can @@ -4116,7 +4116,7 @@ Five policy triggers can be encoded in RPZ records. exclude top-level domains. The ``nsip-enable`` phrase turns NSIP triggers off or on for a single policy zone or for all zones. - If a name server's IP address is not yet known, ``named`` + If a name server's IP address is not yet known, :iscman:`named` recursively looks up the IP address before applying an RPZ-NSIP rule, which can cause a processing delay. To speed up processing at the cost of precision, the ``nsip-wait-recurse`` option can be used; when set @@ -4255,7 +4255,7 @@ such as SERVFAIL to appear to be rewritten, since no recursion is being done to discover problems at the authoritative server. The ``dnsrps-enable yes`` option turns on the DNS Response Policy Service -(DNSRPS) interface, if it has been compiled in ``named`` using +(DNSRPS) interface, if it has been compiled in :iscman:`named` using ``configure --enable-dnsrps``. The ``dnsrps-options`` block provides additional RPZ configuration @@ -4272,7 +4272,7 @@ DNSRPS provider from Farsight Security takes options such as ``dnsrpzd-conf``, ``dnsrpzd-sock``, and ``dnzrpzd-args`` (for details of these options, see the ``librpz`` documentation). Other RPZ configuration settings could be included in ``dnsrps-options`` as well, -but if ``named`` were switched back to traditional RPZ by setting +but if :iscman:`named` were switched back to traditional RPZ by setting ``dnsrps-enable`` to "no", those options would be ignored. The TTL of a record modified by RPZ policies is set from the TTL of the @@ -4525,12 +4525,12 @@ included in ``RateSlipped`` and ``RespTruncated``. NXDOMAIN Redirection ^^^^^^^^^^^^^^^^^^^^ -``named`` supports NXDOMAIN redirection via two methods: +:iscman:`named` supports NXDOMAIN redirection via two methods: - Redirect zone (:ref:`zone_statement_grammar`) - Redirect namespace -With either method, when ``named`` gets an NXDOMAIN response it examines a +With either method, when :iscman:`named` gets an NXDOMAIN response it examines a separate namespace to see if the NXDOMAIN response should be replaced with an alternative response. @@ -4565,7 +4565,7 @@ redirect zone is tried first. The ``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 ``named.conf``. +regardless of the order in :iscman:`named.conf`. The ``server`` statement can occur at the top level of the configuration file or inside a ``view`` statement. If a ``view`` statement contains @@ -4614,13 +4614,13 @@ use EDNS when communicating with the remote server. The default is ``yes``. The ``edns-udp-size`` option sets the EDNS UDP size that is advertised -by ``named`` when querying the remote server. Valid values are 512 to +by :iscman:`named` when querying the remote server. Valid values are 512 to 4096 bytes; values outside this range are silently adjusted to the nearest value within it. This option is useful when advertising a different value to this server than the value advertised globally: for example, when there is a firewall at the remote site that is blocking large replies. Note: currently, this sets a single UDP size -for all packets sent to the server; ``named`` does not deviate from this +for all packets sent to the server; :iscman:`named` does not deviate from this value. This differs from the behavior of ``edns-udp-size`` in ``options`` or ``view`` statements, where it specifies a maximum value. The ``server`` statement behavior may be brought into conformance with @@ -4638,10 +4638,10 @@ values are silently adjusted. This option is not needed until higher EDNS versions than 0 are in use. The ``max-udp-size`` option sets the maximum EDNS UDP message size -``named`` sends. Valid values are 512 to 4096 bytes; values outside +:iscman:`named` sends. Valid values are 512 to 4096 bytes; values outside this range are silently adjusted. This option is useful when there is a firewall that is blocking large replies from -``named``. +:iscman:`named`. The ``padding`` option adds EDNS Padding options to outgoing messages, increasing the packet size to a multiple of the specified block size. @@ -4706,7 +4706,7 @@ an NSID EDNS option to requests sent to the server. This overrides The ``send-cookie`` clause determines whether the local server adds a COOKIE EDNS option to requests sent to the server. This overrides -``send-cookie`` set at the view or option level. The ``named`` server +``send-cookie`` set at the view or option level. The :iscman:`named` server may determine that COOKIE is not supported by the remote server and not add a COOKIE EDNS option to requests. @@ -4746,11 +4746,11 @@ If no port is specified, port 80 is used for HTTP channels. The asterisk Attempts to open a statistics channel are restricted by the optional ``allow`` clause. Connections to the statistics channel are permitted based on the ``address_match_list``. If no ``allow`` clause is -present, ``named`` accepts connection attempts from any address; since +present, :iscman:`named` accepts connection attempts from any address; since the statistics may contain sensitive internal information, it is highly recommended to restrict the source of connection requests appropriately. -If no ``statistics-channels`` statement is present, ``named`` does not +If no ``statistics-channels`` statement is present, :iscman:`named` does not open any communication channels. The statistics are available in various formats and views, depending on @@ -4793,11 +4793,11 @@ statistics), and http://127.0.0.1:8888/json/v1/traffic (traffic sizes). The ``tls`` statement is used to configure a TLS connection; this configuration can then be referenced by a ``listen-on`` or ``listen-on-v6`` -statement to cause ``named`` to listen for incoming requests via TLS, +statement to cause :iscman:`named` to listen for incoming requests via TLS, or in the ``primaries`` statement for a zone of type ``secondary`` to cause zone transfer requests to be sent via TLS. -``tls`` can only be set at the top level of ``named.conf``. +``tls`` can only be set at the top level of :iscman:`named.conf`. The following options can be specified in a ``tls`` statement: @@ -4880,7 +4880,7 @@ the remote virtual machine or server might be not). These files do not contain any sensitive data and can be shared if required. There are two built-in TLS connection configurations: ``ephemeral``, -uses a temporary key and certificate created for the current ``named`` +uses a temporary key and certificate created for the current :iscman:`named` session only, and ``none``, which can be used when setting up an HTTP listener with no encryption. @@ -4897,9 +4897,9 @@ listener with no encryption. The ``http`` statement is used to configure HTTP endpoints on which to listen for DNS-over-HTTPS (DoH) queries. This configuration can then be referenced by a ``listen-on`` or ``listen-on-v6`` statement to -cause ``named`` to listen for incoming requests over HTTPS. +cause :iscman:`named` to listen for incoming requests over HTTPS. -``http`` can only be set at the top level of ``named.conf``. +``http`` can only be set at the top level of :iscman:`named.conf`. The following options can be specified in an ``http`` statement: @@ -4967,7 +4967,7 @@ deemed to exist regardless of what parent zones say. Only keys configured as trust anchors are used to validate the DNSKEY RRset for the corresponding name. The parent's DS RRset is not used. -``trust-anchors`` may be set at the top level of ``named.conf`` or within +``trust-anchors`` may be set at the top level of :iscman:`named.conf` or within a view. If it is set in both places, the configurations are additive; keys defined at the top level are inherited by all views, but keys defined in a view are only used within that view. @@ -5013,9 +5013,9 @@ the new key. If, however, the trust anchor had been configured using ``initial-key`` or ``initial-ds`` instead, the zone owner could add a "stand-by" key to -the zone in advance. ``named`` would store +the zone in advance. :iscman:`named` would store the stand-by key, and when the original key was revoked, -``named`` would be able to transition smoothly +:iscman:`named` would be able to transition smoothly to the new key. It would also recognize that the old key had been revoked and cease using that key to validate answers, minimizing the damage that the compromised key could do. @@ -5025,7 +5025,7 @@ up-to-date. Whereas ``static-key`` and ``static-ds`` trust anchors continue to be trusted until they are removed from -``named.conf``, an +:iscman:`named.conf`, an ``initial-key`` or ``initial-ds`` is only trusted *once*: for as long as it takes to load the managed key database and start the @@ -5034,9 +5034,9 @@ takes to load the managed key database and start the It is not possible to mix static with initial trust anchors for the same domain name. -The first time ``named`` runs with an +The first time :iscman:`named` runs with an ``initial-key`` or ``initial-ds`` -configured in ``named.conf``, it fetches the +configured in :iscman:`named.conf`, it fetches the DNSKEY RRset directly from the zone apex, and validates it using the trust anchor specified in ``trust-anchors``. @@ -5044,14 +5044,14 @@ If the DNSKEY RRset is validly signed by a key matching the trust anchor, then it is used as the basis for a new managed-keys database. -From that point on, whenever ``named`` runs, it sees the ``initial-key`` or ``initial-ds`` +From that point on, whenever :iscman:`named` runs, it sees the ``initial-key`` or ``initial-ds`` listed in ``trust-anchors``, checks to make sure :rfc:`5011` key maintenance has already been initialized for the specified domain, and if so, simply moves on. The key specified in the ``trust-anchors`` statement is not used to validate answers; it is superseded by the key or keys stored in the managed-keys database. -The next time ``named`` runs after an ``initial-key`` or ``initial-ds`` has been *removed* +The next time :iscman:`named` runs after an ``initial-key`` or ``initial-ds`` has been *removed* from the ``trust-anchors`` statement (or changed to a ``static-key`` or ``static-ds``), the corresponding zone is removed from the managed-keys database, and :rfc:`5011` key maintenance is no longer used for that domain. @@ -5069,19 +5069,19 @@ When the key database is changed, the zone is updated. As with any other dynamic zone, changes are written into a journal file, e.g., ``managed-keys.bind.jnl`` or ``internal.mkeys.jnl``. Changes are committed to the primary file as soon as possible afterward, -usually within 30 seconds. Whenever ``named`` is using +usually within 30 seconds. Whenever :iscman:`named` is using automatic key maintenance, the zone file and journal file can be expected to exist in the working directory. (For this reason, among others, the working directory should be always be writable by -``named``.) +:iscman:`named`.) -If the ``dnssec-validation`` option is set to ``auto``, ``named`` +If the ``dnssec-validation`` option is set to ``auto``, :iscman:`named` automatically initializes an ``initial-key`` for the root zone. The key that is used to initialize the key-maintenance process is stored in ``bind.keys``; the location of this file can be overridden with the ``bindkeys-file`` option. As a fallback in the event no ``bind.keys`` can be found, the initializing key is also compiled directly into -``named``. +:iscman:`named`. .. _dnssec_policy_grammar: @@ -5114,7 +5114,7 @@ specifying the name of the policy that should be used. Key rollover timing is computed for each key according to the key lifetime defined in the KASP. The lifetime may be modified by zone TTLs and propagation delays, to prevent validation failures. When a key -reaches the end of its lifetime, ``named`` generates and publishes a new +reaches the end of its lifetime, :iscman:`named` generates and publishes a new key automatically, then deactivates the old key and activates the new one; finally, the old key is retired according to a computed schedule. @@ -5140,7 +5140,7 @@ tree, in the file ``doc/misc/dnssec-policy.default.conf``.) ``default``. If a ``dnssec-policy`` statement is modified and the server restarted or -reconfigured, ``named`` attempts to change the policy smoothly from the +reconfigured, :iscman:`named` attempts to change the policy smoothly from the old one to the new. For example, if the key algorithm is changed, then a new key is generated with the new algorithm, and the old algorithm is retired when the existing key's lifetime ends. @@ -5211,7 +5211,7 @@ The following options can be specified in a ``dnssec-policy`` statement: ``purge-keys`` This is the time after when DNSSEC keys that have been deleted from the zone can be removed from disk. If a key still determined to have - presence (for example in some resolver cache), ``named`` will not + presence (for example in some resolver cache), :iscman:`named` will not remove the key files. The default is ``P90D`` (90 days). Set this option to ``0`` to never @@ -5270,7 +5270,7 @@ The following options can be specified in a ``dnssec-policy`` statement: The default is to use NSEC. The ``iterations``, ``optout`` and ``salt-length`` parts are optional, but if not set, the values in the example above are the default NSEC3 parameters. Note that you don't - specify a specific salt string, ``named`` will create a salt for you + specify a specific salt string, :iscman:`named` will create a salt for you of the provided salt length. ``zone-propagation-delay`` @@ -5526,7 +5526,7 @@ or ``delegation-only``. data is subject to DNSSEC validation before being used in answers. Validation is applied to the entire zone during the zone transfer process, and again when the zone file is loaded from disk upon - restarting ``named``. If validation of a new version of a mirror zone + restarting :iscman:`named`. If validation of a new version of a mirror zone fails, a retransfer is scheduled; in the meantime, the most recent correctly validated version of that zone is used until it either expires or a newer version validates correctly. If no usable zone @@ -5542,7 +5542,7 @@ or ``delegation-only``. Mirror zones are intended to be used to set up a fast local copy of the root zone (see :rfc:`8806`). A default list of primary servers - for the IANA root zone is built into ``named``, so its mirroring can + for the IANA root zone is built into :iscman:`named`, so its mirroring can be enabled using the following configuration: :: @@ -5561,7 +5561,7 @@ or ``delegation-only``. relevant zone (or view). Other, more efficient zone verification methods may be added in the future. - To make mirror zone contents persist between ``named`` restarts, use + To make mirror zone contents persist between :iscman:`named` restarts, use the :ref:`file ` option. Mirroring a zone other than root requires an explicit list of primary @@ -5602,7 +5602,7 @@ or ``delegation-only``. Stub zones can be used to eliminate the need for a glue NS record in a parent zone, at the expense of maintaining a stub zone entry and a set of name - server addresses in ``named.conf``. This usage is not recommended for + server addresses in :iscman:`named.conf`. This usage is not recommended for new configurations, and BIND 9 supports it only in a limited way. If a BIND 9 primary, serving a parent zone, has child stub zones configured, all the secondary servers for the parent zone also need to @@ -5908,7 +5908,7 @@ Zone Options ``server-names`` This option is only meaningful for static-stub zones. This is a list of domain names of name servers that act as authoritative servers of the static-stub - zone. These names are resolved to IP addresses when ``named`` + zone. These names are resolved to IP addresses when :iscman:`named` needs to send queries to these servers. For this supplemental resolution to be successful, these names must not be a subdomain of the origin name of the static-stub zone. That is, when "example.net" is the @@ -6029,10 +6029,10 @@ configuration error to specify both ``allow-update`` and ``update-policy`` at the same time. A pre-defined ``update-policy`` rule can be switched on with the command -``update-policy local;``. ``named`` automatically +``update-policy local;``. :iscman:`named` automatically generates a TSIG session key when starting and stores it in a file; this key can then be used by local clients to update the zone while -``named`` is running. By default, the session key is stored in the file +:iscman:`named` is running. By default, the session key is stored in the file |session_key|, the key name is "local-ddns", and the key algorithm is HMAC-SHA256. These values are configurable with the ``session-keyfile``, ``session-keyname``, and ``session-keyalg`` options, @@ -6049,7 +6049,7 @@ name is "local-ddns", this policy is equivalent to: with the additional restriction that only clients connecting from the local system are permitted to send updates. -Note that only one session key is generated by ``named``; all zones +Note that only one session key is generated by :iscman:`named`; all zones configured to use ``update-policy local`` accept the same key. The command ``nsupdate -l`` implements this feature, sending requests to @@ -6213,7 +6213,7 @@ The ruletype field has 20 values: ``name``, ``subdomain``, ``zonesub``, It is theoretically possible to spoof these TCP sessions. ``external`` - This rule allows ``named`` to defer the decision of whether to allow a given update to an external daemon. + This rule allows :iscman:`named` to defer the decision of whether to allow a given update to an external daemon. The method of communicating with the daemon is specified in the ``identity`` field, the format of which is "``local:``\ path", where "path" is the location of a Unix-domain socket. (Currently, "local" is the only supported mechanism.) @@ -6574,7 +6574,7 @@ Syntax: ``$INCLUDE`` filename [origin] [comment] This reads and processes the file ``filename`` as if it were included in the file at this point. The ``filename`` can be an absolute path, or a relative -path. In the latter case it is read from ``named``'s working directory. If +path. In the latter case it is read from :iscman:`named`'s working directory. If ``origin`` is specified, the file is processed with ``$ORIGIN`` set to that value; otherwise, the current ``$ORIGIN`` is used. @@ -6699,14 +6699,14 @@ similar to that used in zone transfers. Since it does not require parsing text, load time is significantly reduced. For a primary server, a zone file in ``raw`` format is expected -to be generated from a text zone file by the ``named-compilezone`` command. +to be generated from a text zone file by the :iscman:`named-compilezone` command. For a secondary server or a dynamic zone, the zone file is automatically -generated when ``named`` dumps the zone contents after zone transfer or +generated when :iscman:`named` dumps the zone contents after zone transfer or when applying prior updates, if one of these formats is specified by the ``masterfile-format`` option. If a zone file in ``raw`` format needs manual modification, it first must -be converted to ``text`` format by the ``named-compilezone`` command, +be converted to ``text`` format by the :iscman:`named-compilezone` command, then converted back after editing. For example: :: diff --git a/doc/arm/security.rst b/doc/arm/security.rst index eafcccc90a..b00d79af63 100644 --- a/doc/arm/security.rst +++ b/doc/arm/security.rst @@ -153,7 +153,7 @@ matches when *both* conditions are true. On Unix servers, it is possible to run BIND in a *chrooted* environment (using the ``chroot()`` function) by specifying the :option:`-t ` option for -``named``. This can help improve system security by placing BIND in a +:iscman:`named`. This can help improve system security by placing BIND in a "sandbox," which limits the damage done if a server is compromised. Another useful feature in the Unix version of BIND is the ability to run @@ -161,7 +161,7 @@ the daemon as an unprivileged user (:option:`-u ` user). We suggest ru as an unprivileged user when using the ``chroot`` feature. Here is an example command line to load BIND in a ``chroot`` sandbox, -``/var/named``, and to run ``named`` ``setuid`` to user 202: +``/var/named``, and to run :iscman:`named` ``setuid`` to user 202: ``/usr/local/sbin/named -u 202 -t /var/named`` @@ -178,7 +178,7 @@ the values of options like ``directory`` and ``pid-file`` must be adjusted to account for this. Unlike with earlier versions of BIND, -``named`` does *not* typically need to be compiled statically, nor do shared libraries need to be installed under the new +:iscman:`named` does *not* typically need to be compiled statically, nor do shared libraries need to be installed under the new root. However, depending on the operating system, it may be necessary to set up locations such as ``/dev/zero``, ``/dev/random``, ``/dev/log``, and ``/etc/localtime``. @@ -188,14 +188,14 @@ up locations such as ``/dev/zero``, ``/dev/random``, ``/dev/log``, and Using the ``setuid`` Function ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Prior to running the ``named`` daemon, use the ``touch`` utility (to +Prior to running the :iscman:`named` daemon, use the ``touch`` utility (to change file access and modification times) or the ``chown`` utility (to set the user id and/or group id) on files where BIND should write. .. note:: - If the ``named`` daemon is running as an unprivileged user, it + If the :iscman:`named` daemon is running as an unprivileged user, it cannot bind to new restricted ports if the server is reloaded. diff --git a/doc/arm/troubleshooting.rst b/doc/arm/troubleshooting.rst index cc52acdcfd..9b86fca1c4 100644 --- a/doc/arm/troubleshooting.rst +++ b/doc/arm/troubleshooting.rst @@ -81,7 +81,7 @@ By definition, TLS-encrypted traffic (e.g. DNS over TLS, DNS over HTTPS) is opaque to packet sniffers, which makes debugging problems with encrypted DNS close to impossible. However, Wireshark_ offers a solution_ to this problem by being able to read key log files. In order -to make ``named`` prepare such a file, set the ``SSLKEYLOGFILE`` +to make :iscman:`named` prepare such a file, set the ``SSLKEYLOGFILE`` environment variable to either: - the string ``config`` (``SSLKEYLOGFILE=config``); this requires @@ -110,13 +110,13 @@ environment variable to either: unusable. When the ``SSLKEYLOGFILE`` environment variable is set, each TLS -connection established by ``named`` (both incoming and outgoing) causes +connection established by :iscman:`named` (both incoming and outgoing) causes about 1 kilobyte of data to be written to the key log file. .. warning:: Due to the limitations of the current logging code in BIND 9, - enabling TLS pre-master secret logging adversely affects ``named`` + enabling TLS pre-master secret logging adversely affects :iscman:`named` performance. .. _Wireshark: https://www.wireshark.org/ diff --git a/doc/dnssec-guide/advanced-discussions.rst b/doc/dnssec-guide/advanced-discussions.rst index a828743e44..1dc9d9a519 100644 --- a/doc/dnssec-guide/advanced-discussions.rst +++ b/doc/dnssec-guide/advanced-discussions.rst @@ -273,7 +273,7 @@ salt. Let's look at how each one can be configured: security versus resources. - *Salt*: The salt cannot be configured explicitly, but you can provide - a salt length and ``named`` generates a random salt of the given length. + a salt length and :iscman:`named` generates a random salt of the given length. We learn more about salt in :ref:`advanced_discussions_nsec3_salt`. If you want to use these NSEC3 parameters for a zone, you can add the @@ -866,8 +866,8 @@ roll over DNSKEYs to a new algorithm, e.g., from RSASHA1 (algorithm 5 or care to avoid breaking DNSSEC validation. If you are managing DNSSEC by using the ``dnssec-policy`` configuration, -``named`` handles the rollover for you. Simply change the algorithm -for the relevant keys, and ``named`` uses the new algorithm when the +:iscman:`named` handles the rollover for you. Simply change the algorithm +for the relevant keys, and :iscman:`named` uses the new algorithm when the key is next rolled. It performs a smooth transition to the new algorithm, ensuring that the zone remains valid throughout rollover. @@ -875,20 +875,20 @@ If you are using other methods to sign the zone, the administrator needs to do m with other key rollovers, when the zone is a primary zone, an algorithm rollover can be accomplished using dynamic updates or automatic key rollovers. For secondary zones, only automatic key rollovers are -possible, but the ``dnssec-settime`` utility can be used to control the +possible, but the :iscman:`dnssec-settime` utility can be used to control the timing. In any case, the first step is to put DNSKEYs in place using the new algorithm. You must generate the ``K*`` files for the new algorithm and put -them in the zone's key directory, where ``named`` can access them. Take +them in the zone's key directory, where :iscman:`named` can access them. Take care to set appropriate ownership and permissions on the keys. If the -``auto-dnssec`` zone option is set to ``maintain``, ``named`` +``auto-dnssec`` zone option is set to ``maintain``, :iscman:`named` automatically signs the zone with the new keys, based on their timing metadata when the ``dnssec-loadkeys-interval`` elapses or when you issue the :option:`rndc loadkeys` command. Otherwise, for primary zones, you can use -``nsupdate`` to add the new DNSKEYs to the zone; this causes ``named`` +:iscman:`nsupdate` to add the new DNSKEYs to the zone; this causes :iscman:`named` to use them to sign the zone. For secondary zones, e.g., on a -"bump in the wire" signing server, ``nsupdate`` cannot be used. +"bump in the wire" signing server, :iscman:`nsupdate` cannot be used. Once the zone has been signed by the new DNSKEYs (and you have waited for at least one TTL period), you must inform the parent zone and any trust @@ -904,17 +904,17 @@ repositories. You must then allow another maximum TTL interval to elapse so that the old DS records disappear from all resolver caches. The next step is to remove the DNSKEYs using the old algorithm from your -zone. Again this can be accomplished using ``nsupdate`` to delete the +zone. Again this can be accomplished using :iscman:`nsupdate` to delete the old DNSKEYs (for primary zones only) or by automatic key rollover when ``auto-dnssec`` is set to ``maintain``. You can cause the automatic key -rollover to take place immediately by using the ``dnssec-settime`` +rollover to take place immediately by using the :iscman:`dnssec-settime` utility to set the *Delete* date on all keys to any time in the past. (See the :option:`dnssec-settime -D date/offset ` option.) After adjusting the timing metadata, the :option:`rndc loadkeys` command -causes ``named`` to remove the DNSKEYs and +causes :iscman:`named` to remove the DNSKEYs and RRSIGs for the old algorithm from the zone. Note also that with the -``nsupdate`` method, removing the DNSKEYs also causes ``named`` to +:iscman:`nsupdate` method, removing the DNSKEYs also causes :iscman:`named` to remove the associated RRSIGs automatically. Once you have verified that the old DNSKEYs and RRSIGs have been removed @@ -937,7 +937,7 @@ When you have both DNSSEC and dynamic updates in your environment, updating zone data works the same way as with traditional (insecure) DNS: you can use :option:`rndc freeze` before editing the zone file, and :option:`rndc thaw` when you have finished editing, or you can use the -command ``nsupdate`` to add, edit, or remove records like this: +command :iscman:`nsupdate` to add, edit, or remove records like this: :: @@ -947,10 +947,10 @@ command ``nsupdate`` to add, edit, or remove records like this: > send > quit -The examples provided in this guide make ``named`` automatically +The examples provided in this guide make :iscman:`named` automatically re-sign the zone whenever its content has changed. If you decide to sign your own zone file manually, you need to remember to execute the -``dnssec-signzone`` command whenever your zone file has been updated. +:iscman:`dnssec-signzone` command whenever your zone file has been updated. As far as system resources and performance are concerned, be mindful that with a DNSSEC zone that changes frequently, every time the zone diff --git a/doc/dnssec-guide/commonly-asked-questions.rst b/doc/dnssec-guide/commonly-asked-questions.rst index 05a971074f..e06224f65b 100644 --- a/doc/dnssec-guide/commonly-asked-questions.rst +++ b/doc/dnssec-guide/commonly-asked-questions.rst @@ -147,7 +147,7 @@ Can I use the same key for multiple zones? specific key rollover requirements) get their own key pairs, while other, more "generic" zones can use a single key pair for easier management. Note that at present (mid-2020), fully automatic signing (using the ``dnssec-policy`` - clause in your ``named`` configuration file) does not support reuse of keys + clause in your :iscman:`named` configuration file) does not support reuse of keys except when the same zone appears in multiple views (see next question). To use the same key for multiple zones, sign your zones using semi-automatic signing. Each zone wishing to use the key @@ -164,6 +164,6 @@ How do I sign the different instances of a zone that appears in multiple views? Will there be any problems if I change the DNSSEC policy for a zone? If you are using fully automatic signing, no. Just change the parameters in the - ``dnssec-policy`` statement and reload the configuration file. ``named`` + ``dnssec-policy`` statement and reload the configuration file. :iscman:`named` makes a smooth transition to the new policy, ensuring that your zone remains valid at all times. diff --git a/doc/dnssec-guide/getting-started.rst b/doc/dnssec-guide/getting-started.rst index bd1abbffd7..bab31d288f 100644 --- a/doc/dnssec-guide/getting-started.rst +++ b/doc/dnssec-guide/getting-started.rst @@ -26,7 +26,7 @@ BIND Version Most configuration examples given in this document require BIND version 9.16.0 or newer (although many do work with all versions of BIND -later than 9.9). To check the version of ``named`` you have installed, +later than 9.9). To check the version of :iscman:`named` you have installed, use the :option:`-v ` switch as shown below: :: diff --git a/doc/dnssec-guide/recipes.rst b/doc/dnssec-guide/recipes.rst index d332e6461e..8f19e819d0 100644 --- a/doc/dnssec-guide/recipes.rst +++ b/doc/dnssec-guide/recipes.rst @@ -54,7 +54,7 @@ on them. Using the method described in :ref:`easy_start_guide_for_authoritative_servers`, we just need to add a ``dnssec-policy`` statement to the relevant zone clause. This is -what the ``named.conf`` zone statement looks like on the primary server, 192.168.1.1: +what the :iscman:`named.conf` zone statement looks like on the primary server, 192.168.1.1: :: @@ -72,7 +72,7 @@ custom policy, define the policy in the configuration file and select it in the zone statement (as described in :ref:`signing_custom_policy`). -On the secondary servers, ``named.conf`` does not need to be updated, +On the secondary servers, :iscman:`named.conf` does not need to be updated, and it looks like this: :: @@ -132,7 +132,7 @@ the parent zone. This server is configured as secondary to the hidden primary 192.168.1.1 to receive the unsigned data; then, using keys accessible to this middle box, to sign data on the fly; and finally, to send out the signed data via zone transfer to the other three DNS secondaries. Its -``named.conf`` zone statement looks like this: +:iscman:`named.conf` zone statement looks like this: :: @@ -151,7 +151,7 @@ and use a custom policy.) Finally, on the three secondary servers, the configuration should be updated to receive a zone transfer from 192.168.1.5 (the middle box) instead of -from 192.168.1.1 (the hidden primary). If using BIND, the ``named.conf`` file looks +from 192.168.1.1 (the hidden primary). If using BIND, the :iscman:`named.conf` file looks like this: :: @@ -172,7 +172,7 @@ section is not really relevant to you. In the policy statement, you set how long you want your keys to be valid for, the time taken for information to propagate through your zone, the time it takes for your parent zone to register a new DS record, etc., and that's more -or less it. ``named`` implements everything for you automatically, apart from +or less it. :iscman:`named` implements everything for you automatically, apart from uploading the new DS records to your parent zone - which is covered in :ref:`signing_easy_start_upload_to_parent_zone`. (Some screenshots from a session where a KSK is uploaded to the parent zone @@ -234,17 +234,17 @@ The first command gets us into the key directory ``/etc/bind/keys/example.com/``, where keys for ``example.com`` are stored. -The second, ``dnssec-settime``, sets an inactive (:option:`-I `) date of January 1, +The second, :iscman:`dnssec-settime`, sets an inactive (:option:`-I `) date of January 1, 2021, and a deletion (:option:`-D `) date of February 1, 2021, for the current ZSK (``Kexample.com.+008+17694``). -The third command, ``dnssec-keygen``, creates a successor key, using +The third command, :iscman:`dnssec-keygen`, creates a successor key, using the exact same parameters (algorithms, key sizes, etc.) as the current ZSK. The new ZSK created in our example is ``Kexample.com.+008+51623``. -Make sure the successor keys are readable by ``named``. +Make sure the successor keys are readable by :iscman:`named`. -``named``'s logging messages indicate when the next +:iscman:`named`'s logging messages indicate when the next key checking event is scheduled to occur, the frequency of which can be controlled by ``dnssec-loadkeys-interval``. The log message looks like this: @@ -376,9 +376,9 @@ One Month After ZSK Rollover Again, technically there is nothing you need to do on this day, but it doesn't hurt to verify that the old ZSK (17694) is now completely -gone from your zone. ``named`` will not touch +gone from your zone. :iscman:`named` will not touch ``Kexample.com.+008+17694.private`` and ``Kexample.com.+008+17694.key`` -on your file system. Running the same ``dig`` command for DNSKEY should +on your file system. Running the same :iscman:`dig` command for DNSKEY should suffice: :: @@ -487,21 +487,21 @@ The first command gets us into the key directory ``/etc/bind/keys/example.com/``, where keys for ``example.com`` are stored. -The second, ``dnssec-settime``, sets an inactive (:option:`-I `) date of January 1, +The second, :iscman:`dnssec-settime`, sets an inactive (:option:`-I `) date of January 1, 2021, and a deletion (:option:`-D `) date of February 1, 2021 for the current KSK (``Kexample.com.+007+24848``). -The third command, ``dnssec-keygen``, creates a successor key, using +The third command, :iscman:`dnssec-keygen`, creates a successor key, using the exact same parameters (algorithms, key sizes, etc.) as the current KSK. The new key pair created in our example is ``Kexample.com.+007+23550``. -The fourth and final command, ``dnssec-dsfromkey``, creates a DS record +The fourth and final command, :iscman:`dnssec-dsfromkey`, creates a DS record from the new KSK (23550), using SHA-1 as the digest type. Again, in practice most people generate two DS records for both supported digest types (SHA-1 and SHA-256), but for our example here we are only using one to keep the output small and hopefully clearer. -Make sure the successor keys are readable by ``named``. +Make sure the successor keys are readable by :iscman:`named`. The ``syslog`` message indicates when the next key checking event is. The log message looks like this: @@ -691,7 +691,7 @@ One Month After KSK Rollover ++++++++++++++++++++++++++++ While the removal of the old DNSKEY from the zone should be automated by -``named``, the removal of the DS record is manual. You should make sure +:iscman:`named`, the removal of the DS record is manual. You should make sure the old DNSKEY record is gone from your zone first, by querying for the DNSKEY records of the zone; this time we expect not to see the key with an ID of 24828: @@ -778,7 +778,7 @@ Migrating from NSEC to NSEC3 This recipe describes how to transition from using NSEC to NSEC3, as described in :ref:`advanced_discussions_proof_of_nonexistence`. This recipe -assumes that the zones are already signed, and that ``named`` is configured +assumes that the zones are already signed, and that :iscman:`named` is configured according to the steps described in :ref:`easy_start_guide_for_authoritative_servers`. @@ -804,7 +804,7 @@ DNSSEC policy, using 10 iterations, no opt-out, and a random string that is nsec3param iterations 10 optout no salt-length 16; }; -Then reconfigure the server with ``rndc``. You can tell that it worked if you +Then reconfigure the server with :iscman:`rndc`. You can tell that it worked if you see the following debug log messages: :: @@ -873,7 +873,7 @@ The ``dnssec-policy`` currently has no easy way to re-salt using the same salt length, so to change your NSEC3 salt you need to change the ``salt-length`` value and reconfigure your server. You should see the following messages in the log, assuming your old salt was -"1234567890ABCDEF" and ``named`` created "FEDCBA09" (salt length 8) +"1234567890ABCDEF" and :iscman:`named` created "FEDCBA09" (salt length 8) as the new salt: :: @@ -1000,7 +1000,7 @@ To undo NSEC3 opt-out, change the configuration again: .. note:: NSEC3 hashes the plain text domain name, and we can compute our own - hashes using the tool ``nsec3hash``. For example, to compute the + hashes using the tool :iscman:`nsec3hash`. For example, to compute the hashed name for ``www.example.com`` using the parameters we listed above, we can execute this command: @@ -1073,7 +1073,7 @@ have cached information. After you are certain that all cached information has expired (usually this means one TTL interval has passed), you may reconfigure your zone. -Here is what ``named.conf`` looks like when it is signed: +Here is what :iscman:`named.conf` looks like when it is signed: :: @@ -1102,7 +1102,7 @@ the zone is still DNSSEC maintained, to allow for a graceful transition to unsigned. When the DS records have been removed from the parent zone, use -:option:`rndc dnssec -checkds -key id withdrawn example.com ` to tell ``named`` that +:option:`rndc dnssec -checkds -key id withdrawn example.com ` to tell :iscman:`named` that the DS is removed, and the remaining DNSSEC records will be removed in a timely manner. Or if you have parental agents configured, the DNSSEC records will be automatically removed after BIND has seen that the parental agents no longer @@ -1112,6 +1112,6 @@ After a while, your zone is reverted back to the traditional, insecure DNS format. You can verify by checking that all DNSKEY and RRSIG records have been removed from the zone. -You can then remove the ``dnssec-policy`` line from your ``named.conf`` and +You can then remove the ``dnssec-policy`` line from your :iscman:`named.conf` and reload the zone. The zone will now no longer be subject to any DNSSEC maintenance. diff --git a/doc/dnssec-guide/signing.rst b/doc/dnssec-guide/signing.rst index 5e8b41f4c6..9dd058b7e4 100644 --- a/doc/dnssec-guide/signing.rst +++ b/doc/dnssec-guide/signing.rst @@ -77,7 +77,7 @@ for most situations. We cover the creation of a custom policy in :ref:`signing_custom_policy`, but for the moment we are accepting the default values. -When the configuration file is updated, tell ``named`` to +When the configuration file is updated, tell :iscman:`named` to reload the configuration file by running :option:`rndc reconfig`: :: @@ -116,7 +116,7 @@ in the published zone. The log file shows messages such as these: It then starts signing the zone. How long this process takes depends on the size of the zone, the speed of the server, and how much activity is -taking place. We can check what is happening by using ``rndc``, +taking place. We can check what is happening by using :iscman:`rndc`, entering the command: :: @@ -138,9 +138,9 @@ and when it is finished: When the second message appears, the zone is signed. Before moving on to the next step of coordinating with the parent zone, -let's make sure everything looks good using ``delv``. We want to +let's make sure everything looks good using :iscman:`delv`. We want to simulate what a validating resolver will check, by telling -``delv`` to use a specific trust anchor. +:iscman:`delv` to use a specific trust anchor. First, we need to make a copy of the key created by BIND. This is in the directory you set with the ``directory`` statement in @@ -171,7 +171,7 @@ it looks like this: example.com. static-key 257 3 13 "6saiq99qDB...dqp+o0dw=="; }; -Now we can run the ``delv`` command and instruct it to use this +Now we can run the :iscman:`delv` command and instruct it to use this trusted-key file to validate the answer it receives from the authoritative name server 192.168.1.13: @@ -241,7 +241,7 @@ correct format for their system. example.com. 3600 IN DNSKEY 257 3 13 6saiq99qDB...dqp+o0dw== The DS record format may be generated from the DNSKEY using the -``dnssec-dsfromkey`` tool, which is covered in +:iscman:`dnssec-dsfromkey` tool, which is covered in :ref:`parent_ds_record_format`. For more details and examples on how to work with your parent zone, please see :ref:`working_with_parent_zone`. @@ -257,7 +257,7 @@ and published your DS record. Your zone is now officially DNSSEC-enabled. What happens next? That is basically it - BIND takes care of everything else. As for updating your zone file, you can continue to update it the same way as prior to signing your -zone; the normal work flow of editing a zone file and using the ``rndc`` +zone; the normal work flow of editing a zone file and using the :iscman:`rndc` command to reload the zone still works as usual, and although you are editing the unsigned version of the zone, BIND generates the signed version automatically. @@ -471,7 +471,7 @@ least one corresponding signature, known as an RRSIG. oq4yBQumOhO5WX61LjA17l1DuLWcd/ASwlUZWFGCYQ== ) The serial number was automatically incremented from the old, unsigned -version. ``named`` keeps track of the serial number of the signed version of +version. :iscman:`named` keeps track of the serial number of the signed version of the zone independently of the unsigned version. If the unsigned zone is updated with a new serial number that is higher than the one in the signed copy, then the signed copy is increased to match it; @@ -482,7 +482,7 @@ otherwise, the two are kept separate. Examine the Zone File ^^^^^^^^^^^^^^^^^^^^^ -Our original zone file ``example.com.db`` remains untouched, and ``named`` has +Our original zone file ``example.com.db`` remains untouched, and :iscman:`named` has generated three additional files automatically for us (shown below). The signed DNS data is stored in ``example.com.db.signed`` and in the associated journal file. @@ -495,14 +495,14 @@ associated journal file. A quick description of each of the files: -- ``.jbk``: a transient file used by ``named`` +- ``.jbk``: a transient file used by :iscman:`named` - ``.signed``: the signed version of the zone in raw format - ``.signed.jnl``: a journal file for the signed version of the zone These files are stored in raw (binary) format for faster loading. To -reveal the human-readable version, use ``named-compilezone`` +reveal the human-readable version, use :iscman:`named-compilezone` as shown below. In the example below, we run the command on the raw format zone ``example.com.db.signed`` to produce a text version of the zone ``example.com.text``: @@ -662,7 +662,7 @@ Check with your parent zone to see which format they require. But how can you get each of the formats from your existing data? -When ``named`` turned on automatic +When :iscman:`named` turned on automatic DNSSEC maintenance, essentially the first thing it did was to create the DNSSEC keys and put them in the directory you specified in the configuration file. If you look in that directory, you will see three @@ -755,7 +755,7 @@ keys. The following is an example of such a clause: The policy has multiple parts: - The name must be specified. As each zone can use a different policy, - ``named`` needs to be able to distinguish between policies. This is + :iscman:`named` needs to be able to distinguish between policies. This is done by giving each policy a name, such as ``standard`` in the above example. @@ -811,7 +811,7 @@ is to have a quick key roll but have users get validation failures during the process. Having defined a new policy called "standard", we now need to tell -``named`` to use it. We do this by adding a ``dnssec-policy standard;`` +: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 to all zones on the server), a ``view`` statement (applying to all zones @@ -826,13 +826,13 @@ this example, we'll add it to the ``zone`` statement: ... }; -Finally, tell ``named`` to use the new policy: +Finally, tell :iscman:`named` to use the new policy: :: # rndc reconfig -... and that's it. ``named`` now applies the "standard" policy to +... and that's it. :iscman:`named` now applies the "standard" policy to your zone. .. _signing_maintenance_tasks: @@ -918,7 +918,7 @@ includes the DS record identifying the key that is being rolled. If one or both don't have the DS included yet the rollover is paused, and the check for DS presence is retried after an hour. The same applies for DS withdrawal. -Alternatively, you can use the ``rndc`` tool to tell ``named`` that the DS +Alternatively, you can use the :iscman:`rndc` tool to tell :iscman:`named` that the DS record has been published or withdrawn. For example: :: @@ -928,8 +928,8 @@ record has been published or withdrawn. For example: If your parent zone doesn't support CDS/CDNSKEY, you will have to supply the DNSKEY or DS record to the parent zone manually when a new KSK appears in your zone, presumably using the same mechanism you used to upload the -records for the first time. Again, you need to use the ``rndc`` tool -to tell ``named`` that the DS record has been published. +records for the first time. Again, you need to use the :iscman:`rndc` tool +to tell :iscman:`named` that the DS record has been published. .. [#] For security reasons, a parent zone that supports CDS/CDNSKEY may require @@ -966,18 +966,18 @@ Manual "Manual" signing was the first method to be introduced into BIND and its name describes it perfectly: the user needs to do everything. In the more-automated methods, you load an unsigned zone file into - ``named``, which takes care of signing it. With manual signing, you - have to provide a signed zone for ``named`` to serve. + :iscman:`named`, which takes care of signing it. With manual signing, you + have to provide a signed zone for :iscman:`named` to serve. In practice, this means creating an unsigned zone file as usual, then - using the BIND-provided tools ``dnssec-keygen`` to create the keys - and ``dnssec-signzone`` to sign the zone. The signed zone is stored + using the BIND-provided tools :iscman:`dnssec-keygen` to create the keys + and :iscman:`dnssec-signzone` to sign the zone. The signed zone is stored in another file and is the one you tell BIND to load. To update the zone (for example, to add a resource record), you update the - unsigned zone, re-sign it, and tell ``named`` to load the updated + unsigned zone, re-sign it, and tell :iscman:`named` to load the updated signed copy. The same goes for refreshing signatures or rolling keys; the user is responsible for providing the signed zone served by - ``named``. (In the case of rolling keys, you are also responsible for + :iscman:`named`. (In the case of rolling keys, you are also responsible for ensuring that the keys are added and removed at the correct times.) Why would you want to sign your zone this way? You probably @@ -987,7 +987,7 @@ Manual Semi-Automatic The first step in DNSSEC automation came with BIND 9.7, when the - ``auto-dnssec`` option was added. This causes ``named`` to + ``auto-dnssec`` option was added. This causes :iscman:`named` to periodically search the directory holding the key files (see :ref:`generate_keys` for a description) and to use the information in them to both add and remove keys and sign the @@ -995,10 +995,10 @@ Semi-Automatic Use of ``auto-dnssec`` alone requires that the zone be dynamic, something not suitable for a number of situations, so BIND 9.9 added the - ``inline-signing`` option. With this, ``named`` essentially keeps the + ``inline-signing`` option. With this, :iscman:`named` essentially keeps the signed and unsigned copies of the zone separate. The signed zone is created from the unsigned one using the key information; when the - unsigned zone is updated and the zone reloaded, ``named`` detects the + unsigned zone is updated and the zone reloaded, :iscman:`named` detects the changes and updates the signed copy of the zone. This mode of signing has been termed "semi-automatic" in this @@ -1021,7 +1021,7 @@ Fully Automatic with ``dnssec-keymgr`` (probably via ``cron``). It reads a DNSSEC policy from its configuration file and reads timing information from the DNSSEC key files. With this information it creates new key files with timing - information in them consistent with the policy. ``named`` is run as + information in them consistent with the policy. :iscman:`named` is run as usual, picking up the timing information in the key files to determine when to add and remove keys, and when to sign with them. @@ -1053,7 +1053,7 @@ Semi-Automatic Signing As noted above, the term semi-automatic signing has been used in this document to indicate the mode of signing enabled by the ``auto-dnssec`` -and ``inline-signing`` keywords. ``named`` signs the zone without any +and ``inline-signing`` keywords. :iscman:`named` signs the zone without any manual intervention, based purely on the timing information in the DNSSEC key files. The files, however, must be created manually. @@ -1122,7 +1122,7 @@ This command generates four key files in ``/etc/bind/keys``: The two files ending in ``.key`` are the public keys. These contain the DNSKEY resource records that appear in the zone. The two files ending in ``.private`` are the private keys, and contain the information -that ``named`` actually uses to sign the zone. +that :iscman:`named` actually uses to sign the zone. Of the two pairs, one is the zone-signing key (ZSK), and one is the key-signing key (KSK). We can tell which is which by looking at the file @@ -1160,7 +1160,7 @@ DNSKEY resource record. In our example, 8 means the algorithm RSASHA256. Finally, the "keyid" is essentially a hash of the key itself. -Make sure these files are readable by ``named`` and make sure that the +Make sure these files are readable by :iscman:`named` and make sure that the ``.private`` files are not readable by anyone else. Refer to :ref:`system_entropy` for information on how to @@ -1172,13 +1172,13 @@ Setting Key Timing Information You may remember that in the above description of this method, we said that time information related to rolling keys is stored in the key -files. This is placed there by ``dnssec-keygen`` when the file is -created, and it can be modified using ``dnssec-settime``. By default, +files. This is placed there by :iscman:`dnssec-keygen` when the file is +created, and it can be modified using :iscman:`dnssec-settime`. By default, only a limited amount of timing information is included in the file, as illustrated in the examples in the previous section. All the dates are the same, and are the date and time that -``dnssec-keygen`` created the key. We can use ``dnssec-settime`` to +:iscman:`dnssec-keygen` created the key. We can use :iscman:`dnssec-settime` to modify the dates [#]_. For example, to publish this key in the zone on 1 July 2020, use it to sign records for a year starting on 15 July 2020, and remove it from the zone at the end of July 2021, we @@ -1217,12 +1217,12 @@ one affects the signing of your zone: copy of the new key in their cache before there are any resource records signed with it. By default, if not specified at creation time, this is set to the current time, meaning the key is - published as soon as ``named`` picks it up. + published as soon as :iscman:`named` picks it up. 3. *Activate*: This sets the date on which the key is to be activated. After that date, resource records are signed with the key. By default, if not specified during creation time, this is set to the current - time, meaning the key is used to sign data as soon as ``named`` + time, meaning the key is used to sign data as soon as :iscman:`named` picks it up. 4. *Revoke:* This sets the date on which the key is to be revoked. After that @@ -1277,7 +1277,7 @@ Sometime later it is activated and is used to sign resource records. After a specified period, BIND stops using it to sign records, and at some other specified later time it is removed from the zone. -Finally, we should note that the ``dnssec-keygen`` command supports the +Finally, we should note that the :iscman:`dnssec-keygen` command supports the same set of switches so we could have set the dates when we created the key. @@ -1288,7 +1288,7 @@ Reconfiguring BIND Having created the keys with the appropriate timing information, the next step is to turn on DNSSEC signing. Below is a very simple -``named.conf``; in our example environment, this file is +:iscman:`named.conf`; in our example environment, this file is ``/etc/bind/named.conf``. :: @@ -1306,7 +1306,7 @@ next step is to turn on DNSSEC signing. Below is a very simple inline-signing yes; }; -Once the configuration file is updated, tell ``named`` to +Once the configuration file is updated, tell :iscman:`named` to reload: :: @@ -1366,7 +1366,7 @@ Fully Automatic Signing With ``dnssec-keymgr`` information for existing keys with the defined policy, and adjusts it if necessary. It also creates additional keys as required. -``dnssec-keymgr`` is completely separate from ``named``. As we will see, +``dnssec-keymgr`` is completely separate from :iscman:`named`. As we will see, the policy states a coverage period; ``dnssec-keymgr`` generates enough key files to handle all rollovers in that period. However, it is a good idea to schedule it to run on a regular basis; that way there is @@ -1407,7 +1407,7 @@ example of such a file: keyttl 300; }; -As can be seen, the syntax is similar to that of the ``named`` +As can be seen, the syntax is similar to that of the :iscman:`named` configuration file. In the example above, we define a DNSSEC policy called "standard". Keys @@ -1417,7 +1417,7 @@ and placed in the directory ``/etc/bind``. KSKs have a key size of zone 30 days before it becomes active, and is retained in the zone for 30 days after it is rolled. ZSKs have a key size of 2048 bits and roll every 90 days; like the KSKs, the are added to the zone 30 days before -they are used for signing, and retained for 30 days after ``named`` +they are used for signing, and retained for 30 days after :iscman:`named` ceases signing with them. The policy is applied to two zones, ``example.com`` and ``example.net``. @@ -1425,11 +1425,11 @@ The policy is applied unaltered to the former, but for the latter the setting for the DNSKEY TTL has been overridden and set to 300 seconds. To apply the policy, we need to run ``dnssec-keymgr``. Since this does -not read the ``named`` configuration file, it relies on the presence of +not read the :iscman:`named` configuration file, it relies on the presence of at least one key file for a zone to tell it that the zone is DNSSEC-enabled. If a key file does not already exist, we first need to create one for each zone. We can do that either by running -``dnssec-keygen`` to create a key file for each zone [#]_, or by +:iscman:`dnssec-keygen` to create a key file for each zone [#]_, or by specifying the zones in question on the command line. Here, we do the latter: @@ -1525,12 +1525,12 @@ Fully Automatic Signing With ``dnssec-policy`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The latest development in DNSSEC key management appeared with BIND 9.16, -and is the full integration of key management into ``named``. Managing +and is the full integration of key management into :iscman:`named`. Managing the signing process and rolling of these keys has been described in :ref:`easy_start_guide_for_authoritative_servers` and is not repeated here. A few points are worth noting, though: -- The ``dnssec-policy`` statement in the ``named`` configuration file +- The ``dnssec-policy`` statement in the :iscman:`named` configuration file describes all aspects of the DNSSEC policy, including the signing. With ``dnssec-keymgr``, this is split between two configuration files and two programs. @@ -1561,7 +1561,7 @@ be useful for test purposes, so we cover it briefly here. The first step is to create the keys as described in :ref:`generate_keys`. Then, edit the zone file to make sure the proper DNSKEY entries are included in your zone file. Finally, use the -command ``dnssec-signzone``: +command :iscman:`dnssec-signzone`: :: @@ -1589,7 +1589,7 @@ has three parameters: the unsigned zone name also generates a plain text file ``/etc/bind/db/example.com.signed.db``, which you can verify for correctness. -Finally, you'll need to update ``named.conf`` to load the signed version +Finally, you'll need to update :iscman:`named.conf` to load the signed version of the zone, which looks something like this: :: @@ -1600,7 +1600,7 @@ of the zone, which looks something like this: }; Once the :option:`rndc reconfig` command is issued, BIND serves a signed -zone. The file ``dsset-example.com`` (created by ``dnssec-signzone`` +zone. The file ``dsset-example.com`` (created by :iscman:`dnssec-signzone` when it signed the ``example.com`` zone) contains the DS record for the zone's KSK. You will need to pass that to the administrator of the parent zone, to be placed in the zone. @@ -1613,9 +1613,9 @@ appropriate times. .. [#] The dates can also be modified using an editor, but that is likely to - be more error-prone than using ``dnssec-settime``. + be more error-prone than using :iscman:`dnssec-settime`. .. [#] Only one key file - for either a KSK or ZSK - is needed to signal the - presence of the zone. ``dnssec-keygen`` creates files of both + presence of the zone. :iscman:`dnssec-keygen` creates files of both types as needed. diff --git a/doc/dnssec-guide/troubleshooting.rst b/doc/dnssec-guide/troubleshooting.rst index e0909d952a..b865a06f26 100644 --- a/doc/dnssec-guide/troubleshooting.rst +++ b/doc/dnssec-guide/troubleshooting.rst @@ -100,7 +100,7 @@ Visible DNSSEC Validation Symptoms After determining the query path, it is necessary to determine whether the problem is actually related to DNSSEC -validation. You can use the ``+cd`` flag in ``dig`` to disable +validation. You can use the ``+cd`` flag in :iscman:`dig` to disable validation, as described in :ref:`how_do_i_know_validation_problem`. @@ -132,7 +132,7 @@ server at 192.168.1.7: ;; WHEN: Wed Mar 18 15:12:49 GMT 2020 ;; MSG SIZE rcvd: 72 -With ``delv``, a "resolution failed" message is output instead: +With :iscman:`delv`, a "resolution failed" message is output instead: :: @@ -320,7 +320,7 @@ Next, we query for the DNSKEY and RRSIG of ``example.net`` to see if there's anything wrong. Since we are having trouble validating, we can use the ``+cd`` option to temporarily disable checking and return results, even though they do not pass the validation tests. The -``+multiline`` option tells ``dig`` to print the type, algorithm type, +``+multiline`` option tells :iscman:`dig` to print the type, algorithm type, and key id for DNSKEY records. Again, some long strings are shortened for ease of display: @@ -404,7 +404,7 @@ Unable to Load Keys ^^^^^^^^^^^^^^^^^^^ This is a simple yet common issue. If the key files are present but -unreadable by ``named`` for some reason, the ``syslog`` returns clear error +unreadable by :iscman:`named` for some reason, the ``syslog`` returns clear error messages, as shown below: :: @@ -435,7 +435,7 @@ reload`` with the key files missing from the key directory: named[32516]: zone example.com/IN (signed): next key event: 27-Nov-2014 20:07:09.292 This happens to look exactly the same as if the keys were present and -readable, and appears to indicate that ``named`` loaded the keys and signed the zone. It +readable, and appears to indicate that :iscman:`named` loaded the keys and signed the zone. It even generates the internal (raw) files: :: @@ -444,7 +444,7 @@ even generates the internal (raw) files: # ls example.com.db example.com.db.jbk example.com.db.signed -If ``named`` really loaded the keys and signed the zone, you should see +If :iscman:`named` really loaded the keys and signed the zone, you should see the following files: :: @@ -462,7 +462,7 @@ Invalid Trust Anchors ^^^^^^^^^^^^^^^^^^^^^ In most cases, you never need to explicitly configure trust -anchors. ``named`` supplies the current root trust anchor and, +anchors. :iscman:`named` supplies the current root trust anchor and, with the default setting of ``dnssec-validation``, updates it on the infrequent occasions when it is changed. @@ -509,7 +509,7 @@ shows an example of querying a recursive server 10.53.0.3: ;; QUESTION SECTION: ;www.example.org. IN A -``delv`` shows a similar result: +:iscman:`delv` shows a similar result: :: @@ -540,7 +540,7 @@ BIND 9.11 introduced Negative Trust Anchors (NTAs) as a means to *temporarily* disable DNSSEC validation for a zone when you know that the zone's DNSSEC is misconfigured. -NTAs are added using the ``rndc`` command, e.g.: +NTAs are added using the :iscman:`rndc` command, e.g.: :: @@ -549,7 +549,7 @@ NTAs are added using the ``rndc`` command, e.g.: The list of currently configured NTAs can also be examined using -``rndc``, e.g.: +:iscman:`rndc`, e.g.: :: @@ -561,7 +561,7 @@ The default lifetime of an NTA is one hour, although by default, BIND polls the zone every five minutes to see if the zone correctly validates, at which point the NTA automatically expires. Both the default lifetime and the polling interval may be configured via -``named.conf``, and the lifetime can be overridden on a per-zone basis +:iscman:`named.conf`, and the lifetime can be overridden on a per-zone basis using the ``-lifetime duration`` parameter to ``rndc nta``. Both timer values have a permitted maximum value of one week. @@ -570,7 +570,7 @@ values have a permitted maximum value of one week. NSEC3 Troubleshooting ~~~~~~~~~~~~~~~~~~~~~ -BIND includes a tool called ``nsec3hash`` that runs through the same +BIND includes a tool called :iscman:`nsec3hash` that runs through the same steps as a validating resolver, to generate the correct hashed name based on NSEC3PARAM parameters. The command takes the following parameters in order: salt, algorithm, iterations, and domain. For diff --git a/doc/dnssec-guide/validation.rst b/doc/dnssec-guide/validation.rst index ffb277e71e..d02b359d52 100644 --- a/doc/dnssec-guide/validation.rst +++ b/doc/dnssec-guide/validation.rst @@ -50,7 +50,7 @@ add one line to the ``options`` section of your configuration file: ... }; -Restart ``named`` or run :option:`rndc reconfig`, and your recursive server is +Restart :iscman:`named` or run :option:`rndc reconfig`, and your recursive server is now happily validating each DNS response. If this does not work for you, and you have already verified DNSSEC support as described in :ref:`dnssec_support_in_bind`, you may have some other @@ -120,28 +120,28 @@ confirm that it is in fact validating DNS responses. .. _using_dig_to_verify: -Using ``dig`` to Verify -^^^^^^^^^^^^^^^^^^^^^^^ +Using :iscman:`dig` to Verify +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Web-based DNSSEC-verification tools often employ JavaScript. If you don't trust the JavaScript magic that the web-based tools rely on, you can take matters into your own hands and use a command-line DNS tool to check your validating resolver yourself. -While ``nslookup`` is popular, partly because it comes pre-installed on -most systems, it is not DNSSEC-aware. ``dig``, on the other hand, fully +While :iscman:`nslookup` is popular, partly because it comes pre-installed on +most systems, it is not DNSSEC-aware. :iscman:`dig`, on the other hand, fully supports the DNSSEC standard and comes as a part of BIND. If you do not -have ``dig`` already installed on your system, install it by downloading +have :iscman:`dig` already installed on your system, install it by downloading it from ISC's `website `__. ISC provides pre-compiled Windows versions on its website. -``dig`` is a flexible tool for interrogating DNS name servers. It +:iscman:`dig` is a flexible tool for interrogating DNS name servers. It performs DNS lookups and displays the answers that are returned from the name servers that were queried. Most seasoned DNS administrators use -``dig`` to troubleshoot DNS problems because of its flexibility, ease of +:iscman:`dig` to troubleshoot DNS problems because of its flexibility, ease of use, and clarity of output. -The example below shows how to use ``dig`` to query the name server 10.53.0.1 +The example below shows how to use :iscman:`dig` to query the name server 10.53.0.1 for the A record for ``ftp.isc.org`` when DNSSEC validation is enabled (i.e. the default). The address 10.53.0.1 is only used as an example; replace it with the actual address or host name of your @@ -202,7 +202,7 @@ file, i.e.: }; If the server is restarted (to ensure a clean cache) and the same -``dig`` command executed, the result is very similar: +:iscman:`dig` command executed, the result is very similar: :: @@ -234,7 +234,7 @@ If the server is restarted (to ensure a clean cache) and the same ;; MSG SIZE rcvd: 187 However, this time there is no ``ad`` flag in the header. Although -``dig`` is still returning the DNSSEC-related resource records, it is +:iscman:`dig` is still returning the DNSSEC-related resource records, it is not checking them, and thus cannot vouch for the authenticity of the answer. If you do carry out this test, remember to re-enable DNSSEC validation (by removing the ``dnssec-validation no;`` line from the configuration @@ -324,7 +324,7 @@ How Do I Know I Have a Validation Problem? Since all DNSSEC validation failures result in a general ``SERVFAIL`` message, how do we know if it was really a validation error? -Fortunately, there is a flag in ``dig``, (``+cd``, for "checking +Fortunately, there is a flag in :iscman:`dig`, (``+cd``, for "checking disabled") which tells the server to disable DNSSEC validation. If you receive a ``SERVFAIL`` message, re-run the query a second time and set the ``+cd`` flag. If the query succeeds with ``+cd``, but @@ -769,8 +769,8 @@ EDNS on DNS Servers For many years, BIND has had EDNS enabled by default, and the UDP packet size is set to a maximum of 4096 bytes. The DNS administrator should not need to perform any reconfiguration. You can -use ``dig`` to verify that your server supports EDNS and see the UDP packet -size it allows with this ``dig`` command: +use :iscman:`dig` to verify that your server supports EDNS and see the UDP packet +size it allows with this :iscman:`dig` command: :: diff --git a/doc/man/named.conf.5in b/doc/man/named.conf.5in index 4769bc11cb..564cea7ae8 100644 --- a/doc/man/named.conf.5in +++ b/doc/man/named.conf.5in @@ -35,7 +35,7 @@ named.conf \- configuration file for **named** \fBnamed.conf\fP .SH DESCRIPTION .sp -\fBnamed.conf\fP is the configuration file for \fBnamed\fP\&. Statements are +\fI\%named.conf\fP is the configuration file for \fBnamed\fP\&. Statements are enclosed in braces and terminated with a semi\-colon. Clauses in the statements are also semi\-colon terminated. The usual comment styles are supported: diff --git a/doc/man/rndc.8in b/doc/man/rndc.8in index d94b544c7e..f23f8f06a6 100644 --- a/doc/man/rndc.8in +++ b/doc/man/rndc.8in @@ -602,8 +602,8 @@ there is no explicit root zone configured. .B stop \-p This command stops the server, making sure any recent changes made through dynamic update or IXFR are first saved to the master files of the updated -zones. If \fB\-p\fP is specified, \fBnamed(8)\(ga\(aqs process ID is returned. -This allows an external process to determine when \(ga\(ganamed\fP has +zones. If \fB\-p\fP is specified, \fBnamed\fP\(aqs process ID is returned. +This allows an external process to determine when \fBnamed\fP has completed stopping. .sp See also \fI\%rndc halt\fP\&. diff --git a/doc/notes/notes-current.rst b/doc/notes/notes-current.rst index 85047bd2f1..02e5c0d13f 100644 --- a/doc/notes/notes-current.rst +++ b/doc/notes/notes-current.rst @@ -31,7 +31,7 @@ Removed Features ~~~~~~~~~~~~~~~~ - The IPv6 sockets are now explicitly restricted to sending and receiving IPv6 - packets only. This renders the ``dig`` option ``+mapped`` non-functioning and + packets only. This renders the :iscman:`dig` option ``+mapped`` non-functioning and thus the option has been removed. :gl:`#3093` Feature Changes @@ -53,7 +53,7 @@ Feature Changes Bug Fixes ~~~~~~~~~ -- With libuv >= 1.37.0, the recvmmsg support would not be enabled in ``named`` +- With libuv >= 1.37.0, the recvmmsg support would not be enabled in :iscman:`named` reducing the maximum query-response performance. The recvmmsg support would be used only in libuv 1.35.0 and 1.36.0. This has been fixed. :gl:`#3095` @@ -68,7 +68,7 @@ Bug Fixes change in the previous release. This has been fixed. :gl:`#3111` - An error in the processing of the ``blackhole`` ACL could cause some DNS - requests sent by ``named`` to fail - for example, zone transfer requests + requests sent by :iscman:`named` to fail - for example, zone transfer requests and SOA refresh queries - if the destination address or prefix was specifically excluded from the ACL using ``!``, or if the ACL was set to ``none``. ``blackhole`` worked correctly when it was left unset, or