From ec30944aa4884b0c9e2c088485aadd4cfe743ed4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 2 Mar 2022 15:12:17 +0100 Subject: [PATCH 01/11] Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there. --- bin/check/named-checkconf.rst | 33 ++- bin/check/named-checkzone.rst | 81 ++++--- bin/check/named-compilezone.rst | 81 ++++--- bin/confgen/ddns-confgen.rst | 18 +- bin/confgen/rndc-confgen.rst | 33 ++- bin/confgen/tsig-keygen.rst | 6 +- bin/delv/delv.rst | 108 ++++++--- bin/dig/dig.rst | 285 ++++++++++++++-------- bin/dig/host.rst | 60 +++-- bin/dnssec/dnssec-cds.rst | 33 ++- bin/dnssec/dnssec-dsfromkey.rst | 39 ++- bin/dnssec/dnssec-importkey.rst | 30 ++- bin/dnssec/dnssec-keyfromlabel.rst | 78 ++++-- bin/dnssec/dnssec-keygen.rst | 96 +++++--- bin/dnssec/dnssec-revoke.rst | 24 +- bin/dnssec/dnssec-settime.rst | 78 ++++-- bin/dnssec/dnssec-signzone.rst | 120 ++++++--- bin/dnssec/dnssec-verify.rst | 27 ++- bin/named/named.rst | 65 +++-- bin/nsupdate/nsupdate.rst | 54 +++-- bin/rndc/rndc.rst | 158 ++++++++---- bin/tools/dnstap-read.rst | 12 +- bin/tools/mdig.rst | 156 ++++++++---- bin/tools/named-nzd2nzf.rst | 3 +- bin/tools/named-rrchecker.rst | 15 +- bin/tools/nsec3hash.rst | 15 +- doc/man/ddns-confgen.8in | 22 +- doc/man/delv.1in | 138 ++++++++--- doc/man/dig.1in | 374 +++++++++++++++++++++-------- doc/man/dnssec-cds.1in | 44 +++- doc/man/dnssec-dsfromkey.1in | 50 +++- doc/man/dnssec-importkey.1in | 36 ++- doc/man/dnssec-keyfromlabel.1in | 102 ++++++-- doc/man/dnssec-keygen.1in | 124 +++++++--- doc/man/dnssec-revoke.1in | 30 ++- doc/man/dnssec-settime.1in | 96 ++++++-- doc/man/dnssec-signzone.1in | 158 +++++++++--- doc/man/dnssec-verify.1in | 36 ++- doc/man/dnstap-read.1in | 14 +- doc/man/host.1in | 78 ++++-- doc/man/mdig.1in | 200 +++++++++++---- doc/man/named-checkconf.1in | 42 +++- doc/man/named-checkzone.1in | 106 +++++--- doc/man/named-compilezone.1in | 106 +++++--- doc/man/named-nzd2nzf.1in | 2 +- doc/man/named-rrchecker.1in | 18 +- doc/man/named.8in | 74 ++++-- doc/man/nsec3hash.1in | 18 +- doc/man/nsupdate.1in | 70 ++++-- doc/man/rndc-confgen.8in | 42 +++- doc/man/rndc.8in | 206 ++++++++++++---- doc/man/tsig-keygen.8in | 6 +- 52 files changed, 2761 insertions(+), 1139 deletions(-) diff --git a/bin/check/named-checkconf.rst b/bin/check/named-checkconf.rst index 882f818c7b..4bc2deada7 100644 --- a/bin/check/named-checkconf.rst +++ b/bin/check/named-checkconf.rst @@ -38,37 +38,46 @@ However, ``named-checkconf`` can be run on these files explicitly. Options ~~~~~~~ -``-h`` +.. option:: -h + This option prints the usage summary and exits. -``-j`` +.. option:: -j + When loading a zonefile, this option instructs ``named`` to read the journal if it exists. -``-l`` +.. option:: -l + This option lists all the configured zones. Each line of output contains the zone name, class (e.g. IN), view, and type (e.g. primary or secondary). -``-c`` +.. option:: -c + This option specifies that only the "core" configuration should be checked. This suppresses the loading of plugin modules, and causes all parameters to ``plugin`` statements to be ignored. -``-i`` +.. option:: -i + This option ignores warnings on deprecated options. -``-p`` +.. option:: -p + This option prints out the ``named.conf`` and included files in canonical form if no errors were detected. See also the ``-x`` option. -``-t directory`` +.. option:: -t directory + This option instructs ``named`` to chroot to ``directory``, so that ``include`` directives in the configuration file are processed as if run by a similarly chrooted ``named``. -``-v`` +.. option:: -v + This option prints the version of the ``named-checkconf`` program and exits. -``-x`` +.. option:: -x + 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 @@ -76,10 +85,12 @@ Options without compromising private data. This option cannot be used without ``-p``. -``-z`` +.. option:: -z + This option performs a test load of all zones of type ``primary`` found in ``named.conf``. -``filename`` +.. option:: filename + This indicates the name of the configuration file to be checked. If not specified, it defaults to |named_conf|. diff --git a/bin/check/named-checkzone.rst b/bin/check/named-checkzone.rst index b8e7c3a88d..19b1d6a4cc 100644 --- a/bin/check/named-checkzone.rst +++ b/bin/check/named-checkzone.rst @@ -34,32 +34,40 @@ configuring them into a name server. Options ~~~~~~~ -``-d`` +.. option:: -d + This option enables debugging. -``-h`` +.. option:: -h + This option prints the usage summary and exits. -``-q`` +.. option:: -q + This option sets quiet mode, which only sets an exit code to indicate successful or failed completion. -``-v`` +.. option:: -v + This option prints the version of the ``named-checkzone`` program and exits. -``-j`` +.. option:: -j + When loading a zone file, this option tells ``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. -``-J filename`` +.. option:: -J filename + When loading the zone file, this option tells ``named`` to read the journal from the given file, if it exists. This implies ``-j``. -``-c class`` +.. option:: -c class + This option specifies the class of the zone. If not specified, ``IN`` is assumed. -``-i mode`` +.. option:: -i mode + This option performs post-load zone integrity checks. Possible modes are ``full`` (the default), ``full-sibling``, ``local``, ``local-sibling``, and ``none``. @@ -85,11 +93,13 @@ Options Mode ``none`` disables the checks. -``-f format`` +.. option:: -f format + This option specifies the format of the zone file. Possible formats are ``text`` (the default), and ``raw``. -``-F format`` +.. 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 the zone contents. @@ -101,43 +111,52 @@ Options 0, the raw file can be read by any version of ``named``; if N is 1, the file can only be read by release 9.9.0 or higher. The default is 1. -``-k mode`` +.. option:: -k mode + This option performs ``check-names`` checks with the specified failure mode. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``. -``-l ttl`` +.. option:: -l ttl + 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``. -``-L serial`` +.. option:: -L serial + When compiling a zone to ``raw`` format, this option sets the "source serial" value in the header to the specified serial number. This is expected to be used primarily for testing purposes. -``-m mode`` +.. option:: -m mode + This option specifies whether MX records should be checked to see if they are addresses. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``. -``-M mode`` +.. option:: -M mode + This option checks whether a MX record refers to a CNAME. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``. -``-n mode`` +.. option:: -n mode + This option specifies whether NS records should be checked to see if they are addresses. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``. -``-o filename`` +.. option:: -o filename + This option writes the zone output to ``filename``. If ``filename`` is ``-``, then the zone output is written to standard output. -``-r mode`` +.. option:: -r mode + This option checks for records that are treated as different by DNSSEC but are semantically equal in plain DNS. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``. -``-s style`` +.. option:: -s style + This option specifies the style of the dumped zone file. Possible styles are ``full`` (the default) and ``relative``. The ``full`` format is most suitable for processing automatically by a separate script. @@ -146,38 +165,46 @@ Options the zone contents. It also does not have any meaning if the output format is not text. -``-S mode`` +.. option:: -S mode + This option checks whether an SRV record refers to a CNAME. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``. -``-t directory`` +.. option:: -t directory + This option tells ``named`` to chroot to ``directory``, so that ``include`` directives in the configuration file are processed as if run by a similarly chrooted ``named``. -``-T mode`` +.. option:: -T mode + This option checks whether Sender Policy Framework (SPF) records exist and issues a warning if an SPF-formatted TXT record is not also present. Possible modes are ``warn`` (the default) and ``ignore``. -``-w directory`` +.. option:: -w directory + This option instructs ``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``. -``-D`` +.. option:: -D + This option dumps the zone file in canonical format. -``-W mode`` +.. option:: -W mode + This option specifies whether to check for non-terminal wildcards. Non-terminal wildcards are almost always the result of a failure to understand the wildcard matching algorithm (:rfc:`4592`). Possible modes are ``warn`` (the default) and ``ignore``. -``zonename`` +.. option:: zonename + This indicates the domain name of the zone being checked. -``filename`` +.. option:: filename + This is the name of the zone file. Return Values diff --git a/bin/check/named-compilezone.rst b/bin/check/named-compilezone.rst index 1a2777c36c..b638cd92fd 100644 --- a/bin/check/named-compilezone.rst +++ b/bin/check/named-compilezone.rst @@ -36,32 +36,40 @@ strict as those specified in the ``named`` configuration file. Options ~~~~~~~ -``-d`` +.. option:: -d + This option enables debugging. -``-h`` +.. option:: -h + This option prints the usage summary and exits. -``-q`` +.. option:: -q + This option sets quiet mode, which only sets an exit code to indicate successful or failed completion. -``-v`` +.. option:: -v + This option prints the version of the ``named-checkzone`` program and exits. -``-j`` +.. option:: -j + When loading a zone file, this option tells ``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. -``-J filename`` +.. option:: -J filename + When loading the zone file, this option tells ``named`` to read the journal from the given file, if it exists. This implies ``-j``. -``-c class`` +.. option:: -c class + This option specifies the class of the zone. If not specified, ``IN`` is assumed. -``-i mode`` +.. option:: -i mode + This option performs post-load zone integrity checks. Possible modes are ``full`` (the default), ``full-sibling``, ``local``, ``local-sibling``, and ``none``. @@ -87,11 +95,13 @@ Options Mode ``none`` disables the checks. -``-f format`` +.. option:: -f format + This option specifies the format of the zone file. Possible formats are ``text`` (the default), and ``raw``. -``-F format`` +.. 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 the zone contents. @@ -103,83 +113,100 @@ Options 0, the raw file can be read by any version of ``named``; if N is 1, the file can only be read by release 9.9.0 or higher. The default is 1. -``-k mode`` +.. option:: -k mode + This option performs ``check-names`` checks with the specified failure mode. Possible modes are ``fail`` (the default), ``warn``, and ``ignore``. -``-l ttl`` +.. option:: -l ttl + 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``. -``-L serial`` +.. option:: -L serial + When compiling a zone to ``raw`` format, this option sets the "source serial" value in the header to the specified serial number. This is expected to be used primarily for testing purposes. -``-m mode`` +.. option:: -m mode + This option specifies whether MX records should be checked to see if they are addresses. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``. -``-M mode`` +.. option:: -M mode + This option checks whether a MX record refers to a CNAME. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``. -``-n mode`` +.. option:: -n mode + This option specifies whether NS records should be checked to see if they are addresses. Possible modes are ``fail`` (the default), ``warn``, and ``ignore``. -``-o filename`` +.. option:: -o filename + This option writes the zone output to ``filename``. If ``filename`` is ``-``, then the zone output is written to standard output. This is mandatory for ``named-compilezone``. -``-r mode`` +.. option:: -r mode + This option checks for records that are treated as different by DNSSEC but are semantically equal in plain DNS. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``. -``-s style`` +.. option:: -s style + This option specifies the style of the dumped zone file. Possible styles are ``full`` (the default) and ``relative``. The ``full`` format is most suitable for processing automatically by a separate script. The relative format is more human-readable and is thus suitable for editing by hand. -``-S mode`` +.. option:: -S mode + This option checks whether an SRV record refers to a CNAME. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``. -``-t directory`` +.. option:: -t directory + This option tells ``named`` to chroot to ``directory``, so that ``include`` directives in the configuration file are processed as if run by a similarly chrooted ``named``. -``-T mode`` +.. option:: -T mode + This option checks whether Sender Policy Framework (SPF) records exist and issues a warning if an SPF-formatted TXT record is not also present. Possible modes are ``warn`` (the default) and ``ignore``. -``-w directory`` +.. option:: -w directory + This option instructs ``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``. -``-D`` +.. option:: -D + This option dumps the zone file in canonical format. This is always enabled for ``named-compilezone``. -``-W mode`` +.. option:: -W mode + This option specifies whether to check for non-terminal wildcards. Non-terminal wildcards are almost always the result of a failure to understand the wildcard matching algorithm (:rfc:`4592`). Possible modes are ``warn`` (the default) and ``ignore``. -``zonename`` +.. option:: zonename + This indicates the domain name of the zone being checked. -``filename`` +.. option:: filename + This is the name of the zone file. Return Values diff --git a/bin/confgen/ddns-confgen.rst b/bin/confgen/ddns-confgen.rst index 52ae412c58..467dc82594 100644 --- a/bin/confgen/ddns-confgen.rst +++ b/bin/confgen/ddns-confgen.rst @@ -45,16 +45,19 @@ be used from a remote system. Options ~~~~~~~ -``-a algorithm`` +.. option:: -a algorithm + This option specifies the algorithm to use for the TSIG key. Available choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, and hmac-sha512. The default is hmac-sha256. Options are case-insensitive, and the "hmac-" prefix may be omitted. -``-h`` +.. option:: -h + This option prints a short summary of options and arguments. -``-k keyname`` +.. option:: -k keyname + This option specifies the key name of the DDNS authentication key. The default is ``ddns-key`` when neither the ``-s`` nor ``-z`` option is specified; otherwise, the default is ``ddns-key`` as a separate label @@ -62,12 +65,14 @@ Options The key name must have the format of a valid domain name, consisting of letters, digits, hyphens, and periods. -``-q`` +.. option:: -q + This option enables quiet mode, which prints only the key, with no explanatory text or usage examples. This is essentially identical to ``tsig-keygen``. -``-s name`` +.. 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 an update policy for the specified name using the "name" nametype. The @@ -75,7 +80,8 @@ Options cannot be used, since the name to be updated may differ from the key name. This option cannot be used with the ``-z`` option. -``-z zone`` +.. option:: -z zone + This option generates a configuration example to allow dynamic updates of a zone. The example ``named.conf`` text shows how to set an update policy for the specified zone using the "zonesub" diff --git a/bin/confgen/rndc-confgen.rst b/bin/confgen/rndc-confgen.rst index e24cbe2ac6..e689000185 100644 --- a/bin/confgen/rndc-confgen.rst +++ b/bin/confgen/rndc-confgen.rst @@ -34,7 +34,8 @@ by hand. Alternatively, it can be run with the ``-a`` option to set up a Options ~~~~~~~ -``-a`` +.. option:: -a + This option sets automatic ``rndc`` configuration, which creates a file |rndc_key| that is read by both ``rndc`` and ``named`` on startup. The ``rndc.key`` file defines a default command channel and @@ -46,46 +47,56 @@ Options remotely, run ``rndc-confgen`` without the ``-a`` option and set up ``rndc.conf`` and ``named.conf`` as directed. -``-A algorithm`` +.. option:: -A algorithm + This option specifies the algorithm to use for the TSIG key. Available choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, and hmac-sha512. The default is hmac-sha256. -``-b keysize`` +.. option:: -b keysize + This option specifies the size of the authentication key in bits. The size must be between 1 and 512 bits; the default is the hash size. -``-c keyfile`` +.. option:: -c keyfile + This option is used with the ``-a`` option to specify an alternate location for ``rndc.key``. -``-h`` +.. option:: -h + This option prints a short summary of the options and arguments to ``rndc-confgen``. -``-k keyname`` +.. option:: -k keyname + This option specifies the key name of the ``rndc`` authentication key. This must be a valid domain name. The default is ``rndc-key``. -``-p port`` +.. option:: -p port + This option specifies the command channel port where ``named`` listens for connections from ``rndc``. The default is 953. -``-q`` +.. option:: -q + This option prevets printing the written path in automatic configuration mode. -``-s address`` +.. option:: -s address + This option specifies the IP address where ``named`` listens for command-channel connections from ``rndc``. The default is the loopback address 127.0.0.1. -``-t chrootdir`` +.. option:: -t chrootdir + This option is used with the ``-a`` option to specify a directory where ``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``. -``-u user`` +.. option:: -u user + This option is used with the ``-a`` option to set the owner of the generated ``rndc.key`` file. If ``-t`` is also specified, only the file in the chroot area has its owner changed. diff --git a/bin/confgen/tsig-keygen.rst b/bin/confgen/tsig-keygen.rst index a1274079de..3ff279ac0b 100644 --- a/bin/confgen/tsig-keygen.rst +++ b/bin/confgen/tsig-keygen.rst @@ -35,13 +35,15 @@ of the generated key. If no name is specified, the default is ``tsig-key``. Options ~~~~~~~ -``-a algorithm`` +.. option:: -a algorithm + This option specifies the algorithm to use for the TSIG key. Available choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, and hmac-sha512. The default is hmac-sha256. Options are case-insensitive, and the "hmac-" prefix may be omitted. -``-h`` +.. option:: -h + This option prints a short summary of options and arguments. See Also diff --git a/bin/delv/delv.rst b/bin/delv/delv.rst index 3c1cfa38fe..6b2469b0f0 100644 --- a/bin/delv/delv.rst +++ b/bin/delv/delv.rst @@ -68,7 +68,8 @@ A typical invocation of ``delv`` looks like: where: -``server`` +.. option:: server + is the name or IP address of the name server to query. This can be an IPv4 address in dotted-decimal notation or an IPv6 address in colon-delimited notation. When the supplied ``server`` argument is a @@ -84,10 +85,12 @@ where: sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1 for IPv6). -``name`` +.. option:: name + is the domain name to be looked up. -``type`` +.. option:: type + indicates what type of query is required - ANY, A, MX, etc. ``type`` can be any valid query type. If no ``type`` argument is supplied, ``delv`` performs a lookup for an A record. @@ -95,7 +98,8 @@ where: Options ~~~~~~~ -``-a anchor-file`` +.. option:: -a anchor-file + This option specifies a file from which to read DNSSEC trust anchors. The default is |bind_keys|, which is included with BIND 9 and contains one or more trust anchors for the root zone ("."). @@ -111,27 +115,32 @@ Options revoked and rolled over, |bind_keys| must be updated to use DNSSEC validation in ``delv``. -``-b address`` +.. option:: -b address + This option sets the source IP address of the query to ``address``. This must be a valid address on one of the host's network interfaces, or ``0.0.0.0``, or ``::``. An optional source port may be specified by appending ``#`` -``-c class`` +.. option:: -c class + This option sets the query class for the requested data. Currently, only class "IN" is supported in ``delv`` and any other value is ignored. -``-d level`` +.. option:: -d level + This option sets the systemwide debug level to ``level``. The allowed range is from 0 to 99. The default is 0 (no debugging). Debugging traces from ``delv`` become more verbose as the debug level increases. See the ``+mtrace``, ``+rtrace``, and ``+vtrace`` options below for additional debugging details. -``-h`` +.. option:: -h + This option displays the ``delv`` help usage output and exits. -``-i`` +.. option:: -i + This option sets insecure mode, which disables internal DNSSEC validation. (Note, however, that this does not set the CD bit on upstream queries. If the server being queried is performing DNSSEC validation, then it does @@ -139,23 +148,27 @@ Options is necessary to examine invalid data to debug a DNSSEC problem, use ``dig +cd``.) -``-m`` +.. option:: -m + This option enables memory usage debugging. -``-p port#`` +.. option:: -p port# + This option specifies a destination port to use for queries, instead of the standard DNS port number 53. This option is used with a name server that has been configured to listen for queries on a non-standard port number. -``-q name`` +.. option:: -q name + This option sets the query name to ``name``. While the query name can be specified without using the ``-q`` option, it is sometimes necessary to disambiguate names from types or classes (for example, when looking up the name "ns", which could be misinterpreted as the type NS, or "ch", which could be misinterpreted as class CH). -``-t type`` +.. option:: -t type + This option sets the query type to ``type``, which can be any valid query type supported in BIND 9 except for zone transfer types AXFR and IXFR. As with ``-q``, this is useful to distinguish query-name types or classes @@ -165,10 +178,12 @@ Options The default query type is "A", unless the ``-x`` option is supplied to indicate a reverse lookup, in which case it is "PTR". -``-v`` +.. option:: -v + This option prints the ``delv`` version and exits. -``-x addr`` +.. option:: -x addr + This option performs a reverse lookup, mapping an address to a name. ``addr`` is an IPv4 address in dotted-decimal notation, or a colon-delimited IPv6 address. When ``-x`` is used, there is no need to provide the @@ -177,10 +192,12 @@ Options query type to PTR. IPv6 addresses are looked up using nibble format under the IP6.ARPA domain. -``-4`` +.. option:: -4 + This option forces ``delv`` to only use IPv4. -``-6`` +.. option:: -6 + This option forces ``delv`` to only use IPv6. Query Options @@ -195,7 +212,8 @@ the string ``no`` to negate the meaning of that keyword. Other keywords assign values to options like the timeout interval. They have the form ``+keyword=value``. The query options are: -``+[no]cdflag`` +.. option:: +[no]cdflag + This option controls whether to set the CD (checking disabled) bit in queries sent by ``delv``. This may be useful when troubleshooting DNSSEC problems from behind a validating resolver. A validating resolver @@ -204,15 +222,18 @@ assign values to options like the timeout interval. They have the form to return invalid responses, which ``delv`` can then validate internally and report the errors in detail. -``+[no]class`` +.. option:: +[no]class + This option controls whether to display the CLASS when printing a record. The default is to display the CLASS. -``+[no]ttl`` +.. option:: +[no]ttl + This option controls whether to display the TTL when printing a record. The default is to display the TTL. -``+[no]rtrace`` +.. option:: +[no]rtrace + This option toggles resolver fetch logging. This reports the name and type of each query sent by ``delv`` in the process of carrying out the resolution and validation process, including the original query @@ -224,7 +245,8 @@ assign values to options like the timeout interval. They have the form ``-d`` option produces the same output, but affects other logging categories as well. -``+[no]mtrace`` +.. option:: +[no]mtrace + This option toggles message logging. This produces a detailed dump of the responses received by ``delv`` in the process of carrying out the resolution and validation process. @@ -234,7 +256,8 @@ assign values to options like the timeout interval. They have the form debug level to 10 using the ``-d`` option produces the same output, but affects other logging categories as well. -``+[no]vtrace`` +.. option:: +[no]vtrace + This option toggles validation logging. This shows the internal process of the validator as it determines whether an answer is validly signed, unsigned, or invalid. @@ -244,20 +267,24 @@ assign values to options like the timeout interval. They have the form systemwide debug level to 3 using the ``-d`` option produces the same output, but affects other logging categories as well. -``+[no]short`` +.. option:: +[no]short + This option toggles between verbose and terse answers. The default is to print the answer in a verbose form. -``+[no]comments`` +.. option:: +[no]comments + This option toggles the display of comment lines in the output. The default is to print comments. -``+[no]rrcomments`` +.. option:: +[no]rrcomments + This option toggles the display of per-record comments in the output (for example, human-readable key information about DNSKEY records). The default is to print per-record comments. -``+[no]crypto`` +.. option:: +[no]crypto + This option toggles the display of cryptographic fields in DNSSEC records. The contents of these fields are unnecessary to debug most DNSSEC validation failures and removing them makes it easier to see the @@ -265,28 +292,33 @@ assign values to options like the timeout interval. They have the form they are replaced by the string ``[omitted]`` or, in the DNSKEY case, the key ID is displayed as the replacement, e.g. ``[ key id = value ]``. -``+[no]trust`` +.. option:: +[no]trust + This option controls whether to display the trust level when printing a record. The default is to display the trust level. -``+[no]split[=W]`` +.. option:: +[no]split[=W] + This option splits long hex- or base64-formatted fields in resource records into chunks of ``W`` characters (where ``W`` is rounded up to the nearest multiple of 4). ``+nosplit`` or ``+split=0`` causes fields not to be split at all. The default is 56 characters, or 44 characters when multiline mode is active. -``+[no]all`` +.. option:: +[no]all + This option sets or clears the display options ``+[no]comments``, ``+[no]rrcomments``, and ``+[no]trust`` as a group. -``+[no]multiline`` +.. option:: +[no]multiline + This option prints long records (such as RRSIG, DNSKEY, and SOA records) in a verbose multi-line format with human-readable comments. The default is to print each record on a single line, to facilitate machine parsing of the ``delv`` output. -``+[no]dnssec`` +.. option:: +[no]dnssec + This option indicates whether to display RRSIG records in the ``delv`` output. The default is to do so. Note that (unlike in ``dig``) this does *not* control whether to request DNSSEC records or to @@ -294,23 +326,27 @@ assign values to options like the timeout interval. They have the form always occurs unless suppressed by the use of ``-i`` or ``+noroot``. -``+[no]root[=ROOT]`` +.. option:: +[no]root[=ROOT] + This option indicates whether to perform conventional DNSSEC validation, and if so, specifies the name of a trust anchor. The default is to validate using a trust anchor of "." (the root zone), for which there is a built-in key. If specifying a different trust anchor, then ``-a`` must be used to specify a file containing the key. -``+[no]tcp`` +.. option:: +[no]tcp + This option controls whether to use TCP when sending queries. The default is to use UDP unless a truncated response has been received. -``+[no]unknownformat`` +.. option:: +[no]unknownformat + This option prints all RDATA in unknown RR-type presentation format (:rfc:`3597`). The default is to print RDATA for known types in the type's presentation format. -``+[no]yaml`` +.. option:: +[no]yaml + This option prints response data in YAML format. Files diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst index 6889ce6bb4..9fd5eec7ae 100644 --- a/bin/dig/dig.rst +++ b/bin/dig/dig.rst @@ -69,7 +69,8 @@ A typical invocation of ``dig`` looks like: where: -``server`` +.. option:: server + is the name or IP address of the name server to query. This can be an IPv4 address in dotted-decimal notation or an IPv6 address in colon-delimited notation. When the supplied ``server`` argument is a @@ -84,10 +85,12 @@ where: sends the query to the local host. The reply from the name server that responds is displayed. -``name`` +.. option:: name + is the name of the resource record that is to be looked up. -``type`` +.. option:: type + indicates what type of query is required - ANY, A, MX, SIG, etc. ``type`` can be any valid query type. If no ``type`` argument is supplied, ``dig`` performs a lookup for an A record. @@ -95,28 +98,34 @@ where: Options ~~~~~~~ -``-4`` +.. option:: -4 + This option indicates that only IPv4 should be used. -``-6`` +.. option:: -6 + This option indicates that only IPv6 should be used. -``-b address[#port]`` +.. option:: -b address[#port] + This option sets the source IP address of the query. The ``address`` must be a valid address on one of the host's network interfaces, or "0.0.0.0" or "::". An optional port may be specified by appending ``#port``. -``-c class`` +.. option:: -c class + This option sets the query class. The default ``class`` is IN; other classes are HS for Hesiod records or CH for Chaosnet records. -``-f file`` +.. option:: -f file + This option sets batch mode, in which ``dig`` reads a list of lookup requests to process from the given ``file``. Each line in the file should be organized in the same way it would be presented as a query to ``dig`` using the command-line interface. -``-k keyfile`` +.. 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 authentication with ``dig``, the name server that is queried needs to @@ -124,24 +133,29 @@ Options by providing appropriate ``key`` and ``server`` statements in ``named.conf``. -``-m`` +.. option:: -m + This option enables memory usage debugging. -``-p port`` +.. option:: -p port + This option sends the query to a non-standard port on the server, instead of the default port 53. This option is used to test a name server that has been configured to listen for queries on a non-standard port number. -``-q name`` +.. option:: -q name + This option specifies the domain name to query. This is useful to distinguish the ``name`` from other arguments. -``-r`` +.. option:: -r + This option indicates that options from ``${HOME}/.digrc`` should not be read. This is useful for scripts that need predictable behavior. -``-t type`` +.. option:: -t type + This option indicates the resource record type to query, which can be any valid query type. If it is a resource record type supported in BIND 9, it can be given by the type mnemonic (such as ``NS`` or ``AAAA``). The default query type is @@ -156,13 +170,16 @@ Options the number of the type. If the resource record type is not supported in BIND 9, the result is displayed as described in :rfc:`3597`. -``-u`` +.. option:: -u + This option indicates that print query times should be provided in microseconds instead of milliseconds. -``-v`` +.. option:: -v + This option prints the version number and exits. -``-x addr`` +.. option:: -x addr + This option sets simplified reverse lookups, for mapping addresses to names. The ``addr`` is an IPv4 address in dotted-decimal notation, or a colon-delimited IPv6 address. When the ``-x`` option is used, there is no @@ -172,7 +189,8 @@ Options and IN respectively. IPv6 addresses are looked up using nibble format under the IP6.ARPA domain. -``-y [hmac:]keyname:secret`` +.. option:: -y [hmac:]keyname:secret + This option signs queries using TSIG with the given authentication key. ``keyname`` is the name of the key, and ``secret`` is the base64-encoded shared secret. ``hmac`` is the name of the key algorithm; @@ -203,17 +221,21 @@ assign values to options, like the timeout interval. They have the form abbreviation is unambiguous; for example, ``+cd`` is equivalent to ``+cdflag``. The query options are: -``+[no]aaflag`` +.. option:: +[no]aaflag + This option is a synonym for ``+[no]aaonly``. -``+[no]aaonly`` +.. option:: +[no]aaonly + This option sets the ``aa`` flag in the query. -``+[no]additional`` +.. option:: +[no]additional + This option displays [or does not display] the additional section of a reply. The default is to display it. -``+[no]adflag`` +.. option:: +[no]adflag + This option sets [or does not set] the AD (authentic data) bit in the query. This requests the server to return whether all of the answer and authority sections have been validated as secure, according to the security @@ -222,44 +244,54 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to indicates that some part of the answer was insecure or not validated. This bit is set by default. -``+[no]all`` +.. option:: +[no]all + This option sets or clears all display flags. -``+[no]answer`` +.. option:: +[no]answer + This option displays [or does not display] the answer section of a reply. The default is to display it. -``+[no]authority`` +.. option:: +[no]authority + This option displays [or does not display] the authority section of a reply. The default is to display it. -``+[no]badcookie`` +.. option:: +[no]badcookie + This option retries the lookup with a new server cookie if a BADCOOKIE response is received. -``+[no]besteffort`` +.. option:: +[no]besteffort + This option attempts to display the contents of messages which are malformed. The default is to not display malformed answers. -``+bufsize[=B]`` +.. option:: +bufsize[=B] + This option sets the UDP message buffer size advertised using EDNS0 to ``B`` bytes. The maximum and minimum sizes of this buffer are 65535 and 0, respectively. ``+bufsize`` restores the default buffer size. -``+[no]cdflag`` +.. option:: +[no]cdflag + This option sets [or does not set] the CD (checking disabled) bit in the query. This requests the server to not perform DNSSEC validation of responses. -``+[no]class`` +.. option:: +[no]class + This option displays [or does not display] the CLASS when printing the record. -``+[no]cmd`` +.. option:: +[no]cmd + This option toggles the printing of the initial comment in the output, identifying the version of ``dig`` and the query options that have been applied. This option always has a global effect; it cannot be set globally and then overridden on a per-lookup basis. The default is to print this comment. -``+[no]comments`` +.. option:: +[no]comments + This option toggles the display of some comment lines in the output, with information about the packet header and OPT pseudosection, and the names of the response section. The default is to print these comments. @@ -268,7 +300,8 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to can be controlled using other command-line switches. These include ``+[no]cmd``, ``+[no]question``, ``+[no]stats``, and ``+[no]rrcomments``. -``+[no]cookie=####`` +.. option:: +[no]cookie=#### + This option sends [or does not send] a COOKIE EDNS option, with an optional value. Replaying a COOKIE from a previous response allows the server to identify a previous client. The default is ``+cookie``. @@ -276,7 +309,8 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to ``+cookie`` is also set when ``+trace`` is set to better emulate the default queries from a nameserver. -``+[no]crypto`` +.. option:: +[no]crypto + This option toggles the display of cryptographic fields in DNSSEC records. The contents of these fields are unnecessary for debugging most DNSSEC validation failures and removing them makes it easier to see the @@ -284,62 +318,75 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to they are replaced by the string ``[omitted]`` or, in the DNSKEY case, the key ID is displayed as the replacement, e.g. ``[ key id = value ]``. -``+[no]defname`` +.. option:: +[no]defname + This option, which is deprecated, is treated as a synonym for ``+[no]search``. -``+[no]dns64prefix`` +.. option:: +[no]dns64prefix + Lookup IPV4ONLY.ARPA AAAA and print any DNS64 prefixes found. -``+[no]dnssec`` +.. option:: +[no]dnssec + This option requests that DNSSEC records be sent by setting the DNSSEC OK (DO) bit in the OPT record in the additional section of the query. -``+domain=somename`` +.. option:: +domain=somename + This option sets the search list to contain the single domain ``somename``, as if specified in a ``domain`` directive in ``/etc/resolv.conf``, and enables search list processing as if the ``+search`` option were given. -``+dscp=value`` +.. option:: +dscp=value + This option sets the DSCP code point to be used when sending the query. Valid DSCP code points are in the range [0...63]. By default no code point is explicitly set. -``+[no]edns[=#]`` +.. option:: +[no]edns[=#] + This option specifies the EDNS version to query with. Valid values are 0 to 255. Setting the EDNS version causes an EDNS query to be sent. ``+noedns`` clears the remembered EDNS version. EDNS is set to 0 by default. -``+[no]ednsflags[=#]`` +.. option:: +[no]ednsflags[=#] + This option sets the must-be-zero EDNS flags bits (Z bits) to the specified value. Decimal, hex, and octal encodings are accepted. Setting a named flag (e.g., DO) is silently ignored. By default, no Z bits are set. -``+[no]ednsnegotiation`` +.. option:: +[no]ednsnegotiation + This option enables/disables EDNS version negotiation. By default, EDNS version negotiation is enabled. -``+[no]ednsopt[=code[:value]]`` +.. option:: +[no]ednsopt[=code[:value]] + This option specifies the EDNS option with code point ``code`` and an optional payload of ``value`` as a hexadecimal string. ``code`` can be either an EDNS option name (for example, ``NSID`` or ``ECS``) or an arbitrary numeric value. ``+noednsopt`` clears the EDNS options to be sent. -``+[no]expire`` +.. option:: +[no]expire + This option sends an EDNS Expire option. -``+[no]fail`` +.. option:: +[no]fail + This option indicates that ``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. -``+[no]header-only`` +.. option:: +[no]header-only + This option sends a query with a DNS header without a question section. The default is to add a question section. The query type and query name are ignored when this is set. -``+[no]https[=value]`` +.. option:: +[no]https[=value] + This option indicates whether to use DNS over HTTPS (DoH) when querying name servers. When this option is in use, the port number defaults to 443. The HTTP POST request mode is used when sending the query. @@ -348,31 +395,38 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to query URI; the default is ``/dns-query``. So, for example, ``dig @example.com +https`` will use the URI ``https://example.com/dns-query``. -``+[no]https-get[=value]`` +.. option:: +[no]https-get[=value] + Similar to ``+https``, except that the HTTP GET request mode is used when sending the query. -``+[no]https-post[=value]`` +.. option:: +[no]https-post[=value] + Same as ``+https``. -``+[no]http-plain[=value]`` +.. option:: +[no]http-plain[=value] + Similar to ``+https``, except that HTTP queries will be sent over a non-encrypted channel. When this option is in use, the port number defaults to 80 and the HTTP request mode is POST. -``+[no]http-plain-get[=value]`` +.. option:: +[no]http-plain-get[=value] + Similar to ``+http-plain``, except that the HTTP request mode is GET. -``+[no]http-plain-post[=value]`` +.. option:: +[no]http-plain-post[=value] + Same as ``+http-plain``. -``+[no]identify`` +.. option:: +[no]identify + This option shows [or does not show] the IP address and port number that supplied the answer, when the ``+short`` option is enabled. If short form answers are requested, the default is not to show the source address and port number of the server that provided the answer. -``+[no]idnin`` +.. option:: +[no]idnin + This option processes [or does not process] IDN domain names on input. This requires ``IDN SUPPORT`` to have been enabled at compile time. @@ -380,7 +434,8 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to The IDN processing on input is disabled when ``dig`` output is redirected to files, pipes, and other non-tty file descriptors. -``+[no]idnout`` +.. option:: +[no]idnout + This option converts [or does not convert] puny code on output. This requires ``IDN SUPPORT`` to have been enabled at compile time. @@ -388,24 +443,29 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to a tty. The puny code processing on output is disabled when ``dig`` output is redirected to files, pipes, and other non-tty file descriptors. -``+[no]ignore`` +.. option:: +[no]ignore + This option ignores [or does not ignore] truncation in UDP responses instead of retrying with TCP. By default, TCP retries are performed. -``+[no]keepalive`` +.. option:: +[no]keepalive + This option sends [or does not send] an EDNS Keepalive option. -``+[no]keepopen`` +.. option:: +[no]keepopen + This option keeps [or does not keep] the TCP socket open between queries, and reuses it rather than creating a new TCP socket for each lookup. The default is ``+nokeepopen``. -``+[no]multiline`` +.. option:: +[no]multiline + This option prints [or does not print] records, like the SOA records, in a verbose multi-line format with human-readable comments. The default is to print each record on a single line to facilitate machine parsing of the ``dig`` output. -``+ndots=D`` +.. option:: +ndots=D + This option sets the number of dots (``D``) that must appear in ``name`` for it to be considered absolute. The default value is that defined using the ``ndots`` statement in ``/etc/resolv.conf``, or 1 if no ``ndots`` @@ -414,24 +474,29 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to ``search`` or ``domain`` directive in ``/etc/resolv.conf`` if ``+search`` is set. -``+[no]nsid`` +.. option:: +[no]nsid + When enabled, this option includes an EDNS name server ID request when sending a query. -``+[no]nssearch`` +.. option:: +[no]nssearch + When this option is set, ``dig`` attempts to find the authoritative name servers for the zone containing the name being looked up, and display the SOA record that each name server has for the zone. Addresses of servers that did not respond are also printed. -``+[no]onesoa`` +.. option:: +[no]onesoa + When enabled, this option prints only one (starting) SOA record when performing an AXFR. The default is to print both the starting and ending SOA records. -``+[no]opcode=value`` +.. option:: +[no]opcode=value + When enabled, this option sets (restores) the DNS message opcode to the specified value. The default value is QUERY (0). -``+padding=value`` +.. option:: +padding=value + This option pads the size of the query packet using the EDNS Padding option to blocks of ``value`` bytes. For example, ``+padding=32`` causes a 48-byte query to be padded to 64 bytes. The default block size is 0, @@ -440,42 +505,51 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to mandatory. Responses to padded queries may also be padded, but only if the query uses TCP or DNS COOKIE. -``+qid=value`` +.. option:: +qid=value + This option specifies the query ID to use when sending queries. -``+[no]qr`` +.. option:: +[no]qr + This option toggles the display of the query message as it is sent. By default, the query is not printed. -``+[no]question`` +.. option:: +[no]question + This option toggles the display of the question section of a query when an answer is returned. The default is to print the question section as a comment. -``+[no]raflag`` +.. option:: +[no]raflag + This option sets [or does not set] the RA (Recursion Available) bit in the query. The default is ``+noraflag``. This bit is ignored by the server for QUERY. -``+[no]rdflag`` +.. option:: +[no]rdflag + This option is a synonym for ``+[no]recurse``. -``+[no]recurse`` +.. option:: +[no]recurse + This option toggles the setting of the RD (recursion desired) bit in the query. This bit is set by default, which means ``dig`` normally sends recursive queries. Recursion is automatically disabled when the ``+nssearch`` or ``+trace`` query option is used. -``+retry=T`` +.. option:: +retry=T + This option sets the number of times to retry UDP and TCP queries to server to ``T`` instead of the default, 2. Unlike ``+tries``, this does not include the initial query. -``+[no]rrcomments`` +.. option:: +[no]rrcomments + This option toggles the display of per-record comments in the output (for example, human-readable key information about DNSKEY records). The default is not to print record comments unless multiline mode is active. -``+[no]search`` +.. option:: +[no]search + This option uses [or does not use] the search list defined by the searchlist or domain directive in ``resolv.conf``, if any. The search list is not used by default. @@ -484,36 +558,43 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to ``+ndots``, determines whether the name is treated as relative and hence whether a search is eventually performed. -``+[no]short`` +.. option:: +[no]short + This option toggles whether a terse answer is provided. The default is to print the answer in a verbose form. This option always has a global effect; it cannot be set globally and then overridden on a per-lookup basis. -``+[no]showbadcookie`` +.. option:: +[no]showbadcookie + This option toggles whether to show the message containing the BADCOOKIE rcode before retrying the request or not. The default is to not show the messages. -``+[no]showsearch`` +.. option:: +[no]showsearch + This option performs [or does not perform] a search showing intermediate results. -``+[no]sigchase`` +.. option:: +[no]sigchase + This feature is now obsolete and has been removed; use ``delv`` instead. -``+split=W`` +.. option:: +split=W + This option splits long hex- or base64-formatted fields in resource records into chunks of ``W`` characters (where ``W`` is rounded up to the nearest multiple of 4). ``+nosplit`` or ``+split=0`` causes fields not to be split at all. The default is 56 characters, or 44 characters when multiline mode is active. -``+[no]stats`` +.. option:: +[no]stats + This option toggles the printing of statistics: when the query was made, the size of the reply, etc. The default behavior is to print the query statistics as a comment after each lookup. -``+[no]subnet=addr[/prefix-length]`` +.. option:: +[no]subnet=addr[/prefix-length] + This option sends [or does not send] an EDNS CLIENT-SUBNET option with the specified IP address or network prefix. @@ -522,30 +603,36 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to prefix-length of zero, which signals a resolver that the client's address information must *not* be used when resolving this query. -``+[no]tcflag`` +.. option:: +[no]tcflag + This option sets [or does not set] the TC (TrunCation) bit in the query. The default is ``+notcflag``. This bit is ignored by the server for QUERY. -``+[no]tcp`` +.. option:: +[no]tcp + This option indicates whether to use TCP when querying name servers. The default behavior is to use UDP unless a type ``any`` or ``ixfr=N`` query is requested, in which case the default is TCP. AXFR queries always use TCP. -``+timeout=T`` +.. option:: +timeout=T + This option sets the timeout for a query to ``T`` seconds. The default timeout is 5 seconds. An attempt to set ``T`` to less than 1 is silently set to 1. -``+[no]tls`` +.. option:: +[no]tls + This option indicates whether to use DNS over TLS (DoT) when querying name servers. When this option is in use, the port number defaults to 853. -``+[no]topdown`` +.. option:: +[no]topdown + This feature is related to ``dig +sigchase``, which is obsolete and has been removed. Use ``delv`` instead. -``+[no]trace`` +.. option:: +[no]trace + This option toggles tracing of the delegation path from the root name servers for the name being looked up. Tracing is disabled by default. When tracing is enabled, ``dig`` makes iterative queries to resolve the @@ -559,38 +646,46 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to ``+dnssec`` is also set when ``+trace`` is set, to better emulate the default queries from a name server. -``+tries=T`` +.. option:: +tries=T + This option sets the number of times to try UDP and TCP queries to server to ``T`` instead of the default, 3. If ``T`` is less than or equal to zero, the number of tries is silently rounded up to 1. -``+trusted-key=####`` +.. 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. -``+[no]ttlid`` +.. option:: +[no]ttlid + This option displays [or does not display] the TTL when printing the record. -``+[no]ttlunits`` +.. option:: +[no]ttlunits + This option displays [or does not display] the TTL in friendly human-readable time units of ``s``, ``m``, ``h``, ``d``, and ``w``, representing seconds, minutes, hours, days, and weeks. This implies ``+ttlid``. -``+[no]unknownformat`` +.. option:: +[no]unknownformat + This option prints all RDATA in unknown RR type presentation format (:rfc:`3597`). The default is to print RDATA for known types in the type's presentation format. -``+[no]vc`` +.. option:: +[no]vc + This option uses [or does not use] TCP when querying name servers. This alternate syntax to ``+[no]tcp`` is provided for backwards compatibility. The ``vc`` stands for "virtual circuit." -``+[no]yaml`` +.. option:: +[no]yaml + When enabled, this option prints the responses (and, if ``+qr`` is in use, also the outgoing queries) in a detailed YAML format. -``+[no]zflag`` +.. option:: +[no]zflag + This option sets [or does not set] the last unassigned DNS header flag in a DNS query. This flag is off by default. diff --git a/bin/dig/host.rst b/bin/dig/host.rst index 8e855c36fc..27058eba75 100644 --- a/bin/dig/host.rst +++ b/bin/dig/host.rst @@ -39,40 +39,49 @@ server or servers listed in ``/etc/resolv.conf``. Options ~~~~~~~ -``-4`` +.. option:: -4 + This option specifies that only IPv4 should be used for query transport. See also the ``-6`` option. -``-6`` +.. option:: -6 + This option specifies that only IPv6 should be used for query transport. See also the ``-4`` option. -``-a`` +.. option:: -a + The ``-a`` ("all") option is normally equivalent to ``-v -t ANY``. It also affects the behavior of the ``-l`` list zone option. -``-A`` +.. option:: -A + The ``-A`` ("almost all") option is equivalent to ``-a``, except that RRSIG, NSEC, and NSEC3 records are omitted from the output. -``-c class`` +.. option:: -c class + This option specifies the query class, which can be used to lookup HS (Hesiod) or CH (Chaosnet) class resource records. The default class is IN (Internet). -``-C`` +.. option:: -C + This option indicates that ``named`` should check consistency, meaning that ``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. -``-d`` +.. option:: -d + This option prints debugging traces, and is equivalent to the ``-v`` verbose option. -``-l`` +.. option:: -l + This option tells ``named`` to list the zone, meaning the ``host`` command performs a zone transfer of zone ``name`` and prints out the NS, PTR, and address records (A/AAAA). Together, the ``-l -a`` options print all records in the zone. -``-N ndots`` +.. option:: -N ndots + This option specifies the number of dots (``ndots``) that have to be in ``name`` for it to be considered absolute. The default value is that defined using the ``ndots`` statement in ``/etc/resolv.conf``, or 1 if no ``ndots`` statement @@ -80,10 +89,12 @@ Options and are searched for in the domains listed in the ``search`` or ``domain`` directive in ``/etc/resolv.conf``. -``-p port`` +.. option:: -p port + This option specifies the port to query on the server. The default is 53. -``-r`` +.. option:: -r + This option specifies a non-recursive query; setting this option clears the RD (recursion desired) bit in the query. This means that the name server receiving the query does not attempt to resolve ``name``. The ``-r`` @@ -91,17 +102,20 @@ Options making non-recursive queries, and expecting to receive answers to those queries that can be referrals to other name servers. -``-R number`` +.. option:: -R number + This option specifies the number of retries for UDP queries. If ``number`` is negative or zero, the number of retries is silently set to 1. The default value is 1, or the value of the ``attempts`` option in ``/etc/resolv.conf``, if set. -``-s`` +.. option:: -s + This option tells ``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. -``-t type`` +.. option:: -t type + This option specifies the query type. The ``type`` argument can be any recognized query type: CNAME, NS, SOA, TXT, DNSKEY, AXFR, etc. @@ -115,31 +129,37 @@ Options specified by appending an equals sign (=), followed by the starting serial number, e.g., ``-t IXFR=12345678``. -``-T``; ``-U`` +.. option:: -T``; ``-U + This option specifies TCP or UDP. By default, ``host`` uses UDP when making queries; the ``-T`` option makes it use a TCP connection when querying the name server. TCP is automatically selected for queries that require it, such as zone transfer (AXFR) requests. Type ``ANY`` queries default to TCP, but can be forced to use UDP initially via ``-U``. -``-m flag`` +.. option:: -m flag + This option sets memory usage debugging: the flag can be ``record``, ``usage``, or ``trace``. The ``-m`` option can be specified more than once to set multiple flags. -``-v`` +.. option:: -v + This option sets verbose output, and is equivalent to the ``-d`` debug option. Verbose output can also be enabled by setting the ``debug`` option in ``/etc/resolv.conf``. -``-V`` +.. option:: -V + This option prints the version number and exits. -``-w`` +.. option:: -w + This option sets "wait forever": the query timeout is set to the maximum possible. See also the ``-W`` option. -``-W wait`` +.. 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 less than 1, the wait interval is set to 1 second. diff --git a/bin/dnssec/dnssec-cds.rst b/bin/dnssec/dnssec-cds.rst index 3eac0b520f..df471daa46 100644 --- a/bin/dnssec/dnssec-cds.rst +++ b/bin/dnssec/dnssec-cds.rst @@ -72,7 +72,8 @@ maintain a ``dsset-`` file as well as emit an ``nsupdate`` script. Options ~~~~~~~ -``-a algorithm`` +.. option:: -a algorithm + When converting CDS records to DS records, this option specifies the acceptable digest algorithms. This option can be repeated, so that multiple digest types are allowed. If none of the CDS records @@ -87,15 +88,18 @@ Options are case-insensitive, and the hyphen may be omitted. If no algorithm is specified, the default is SHA-256 only. -``-c class`` +.. option:: -c class + This option specifies the DNS class of the zones. -``-D`` +.. option:: -D + This option generates DS records from CDNSKEY records if both CDS and CDNSKEY records are present in the child zone. By default CDS records are preferred. -``-d path`` +.. option:: -d path + This specifies the location of the parent DS records. The path can be the name of a file containing the DS records; if it is a directory, ``dnssec-cds`` looks for a ``dsset-`` file for the domain inside the directory. @@ -104,14 +108,16 @@ Options were signed earlier than the modification time of the ``dsset-`` file. This can be adjusted with the ``-s`` option. -``-f child-file`` +.. option:: -f child-file + This option specifies the file containing the child's CDS and/or CDNSKEY records, plus its DNSKEY records and the covering RRSIG records, so that they can be authenticated. The examples below describe how to generate this file. -``-iextension`` +.. option:: -iextension + This option updates the ``dsset-`` file in place, instead of writing DS records to the standard output. @@ -125,7 +131,8 @@ Options child records, provided that it is later than the file's current modification time. -``-s start-time`` +.. option:: -s start-time + This option specifies the date and time after which RRSIG records become acceptable. This can be either an absolute or a relative time. An absolute start time is indicated by a number in YYYYMMDDHHMMSS @@ -137,12 +144,14 @@ Options If no start-time is specified, the modification time of the ``dsset-`` file is used. -``-T ttl`` +.. option:: -T ttl + This option specifies a TTL to be used for new DS records. If not specified, the default is the TTL of the old DS records. If they had no explicit TTL, the new DS records also have no explicit TTL. -``-u`` +.. option:: -u + This option writes an ``nsupdate`` script to the standard output, instead of printing the new DS reords. The output is empty if no change is needed. @@ -151,10 +160,12 @@ Options original ``dsset-`` file, with the ``-T`` option, or using the ``nsupdate`` ``ttl`` command. -``-V`` +.. option:: -V + This option prints version information. -``-v level`` +.. option:: -v level + This option sets the debugging level. Level 1 is intended to be usefully verbose for general users; higher levels are intended for developers. diff --git a/bin/dnssec/dnssec-dsfromkey.rst b/bin/dnssec/dnssec-dsfromkey.rst index 6396733424..a9b010ebeb 100644 --- a/bin/dnssec/dnssec-dsfromkey.rst +++ b/bin/dnssec/dnssec-dsfromkey.rst @@ -51,13 +51,16 @@ as generated by ``dnssec-keygen`` ``-C``. Options ~~~~~~~ -``-1`` +.. option:: -1 + This option is an abbreviation for ``-a SHA1``. -``-2`` +.. option:: -2 + This option is an abbreviation for ``-a SHA-256``. -``-a algorithm`` +.. option:: -a algorithm + This option specifies a digest algorithm to use when converting DNSKEY records to DS records. This option can be repeated, so that multiple DS records are created for each DNSKEY record. @@ -66,19 +69,23 @@ Options are case-insensitive, and the hyphen may be omitted. If no algorithm is specified, the default is SHA-256. -``-A`` +.. option:: -A + This option indicates that ZSKs are to be included when generating DS records. Without this option, only keys which have the KSK flag set are converted to DS records and printed. This option is only useful in ``-f`` zone file mode. -``-c class`` +.. option:: -c class + This option specifies the DNS class; the default is IN. This option is only useful in ``-s`` keyset or ``-f`` zone file mode. -``-C`` +.. option:: -C + This option generates CDS records rather than DS records. -``-f file`` +.. option:: -f file + This option sets zone file mode, in which the final dnsname argument of ``dnssec-dsfromkey`` is the DNS domain name of a zone whose master file can be read from ``file``. If the zone name is the same as ``file``, then it may be @@ -90,23 +97,29 @@ Options ``dig dnskey example.com | dnssec-dsfromkey -f - example.com`` -``-h`` +.. option:: -h + This option prints usage information. -``-K directory`` +.. option:: -K directory + This option tells BIND 9 to look for key files or ``keyset-`` files in ``directory``. -``-s`` +.. option:: -s + This option enables keyset mode, in which the final dnsname argument from ``dnssec-dsfromkey`` is the DNS domain name used to locate a ``keyset-`` file. -``-T TTL`` +.. option:: -T TTL + This option specifies the TTL of the DS records. By default the TTL is omitted. -``-v level`` +.. option:: -v level + This option sets the debugging level. -``-V`` +.. option:: -V + This option prints version information. Example diff --git a/bin/dnssec/dnssec-importkey.rst b/bin/dnssec/dnssec-importkey.rst index 9e58fcee78..969791e139 100644 --- a/bin/dnssec/dnssec-importkey.rst +++ b/bin/dnssec/dnssec-importkey.rst @@ -41,7 +41,8 @@ DNSKEY RRset on schedule even if the true private key is stored offline. Options ~~~~~~~ -``-f filename`` +.. option:: -f filename + This option indicates the zone file mode. Instead of a public keyfile name, the argument is the DNS domain name of a zone master file, which can be read from ``filename``. If the domain name is the same as ``filename``, then it may be @@ -50,23 +51,28 @@ Options If ``filename`` is set to ``"-"``, then the zone data is read from the standard input. -``-K directory`` +.. option:: -K directory + This option sets the directory in which the key files are to reside. -``-L ttl`` +.. option:: -L ttl + This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in place, in which case the existing TTL takes precedence. Setting the default TTL to ``0`` or ``none`` removes it from the key. -``-h`` +.. option:: -h + This option emits a usage message and exits. -``-v level`` +.. option:: -v level + This option sets the debugging level. -``-V`` +.. option:: -V + This option prints version information. Timing Options @@ -81,21 +87,25 @@ months (defined as 30 24-hour days), weeks, days, hours, or minutes, respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use ``none`` or ``never``. -``-P date/offset`` +.. option:: -P date/offset + This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it. -``-P sync date/offset`` +.. option:: -P sync date/offset + This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone. -``-D date/offset`` +.. option:: -D date/offset + This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.) -``-D sync date/offset`` +.. option:: -D sync date/offset + This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted. diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst index 35920acef4..3f635e74d1 100644 --- a/bin/dnssec/dnssec-keyfromlabel.rst +++ b/bin/dnssec/dnssec-keyfromlabel.rst @@ -37,7 +37,8 @@ match the name of the zone for which the key is being generated. Options ~~~~~~~ -``-a algorithm`` +.. option:: -a algorithm + This option selects the cryptographic algorithm. The value of ``algorithm`` must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. @@ -57,20 +58,23 @@ Options ``-S`` option, which copies the algorithm from the predecessory key. Previously, the default for newly generated keys was RSASHA1. -``-3`` +.. option:: -3 + This option uses an NSEC3-capable algorithm to generate a DNSSEC key. If this option is used with an algorithm that has both NSEC and NSEC3 versions, then the NSEC3 version is used; for example, ``dnssec-keygen -3a RSASHA1`` specifies the NSEC3RSASHA1 algorithm. -``-E engine`` +.. option:: -E engine + This option specifies the cryptographic hardware to use. When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually ``pkcs11``). -``-l label`` +.. option:: -l label + This option specifies the label for a key pair in the crypto hardware. When BIND 9 is built with OpenSSL-based PKCS#11 support, the label is @@ -78,14 +82,16 @@ Options preceded by an optional OpenSSL engine name, followed by a colon, as in ``pkcs11:keylabel``. -``-n nametype`` +.. option:: -n nametype + This option specifies the owner type of the key. The value of ``nametype`` must either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host (KEY)), USER (for a key associated with a user (KEY)), or OTHER (DNSKEY). These values are case-insensitive. -``-C`` +.. option:: -C + This option enables compatibility mode, which generates an old-style key, without any metadata. By default, ``dnssec-keyfromlabel`` includes the key's creation date in the metadata stored with the private key; other dates may @@ -93,26 +99,32 @@ Options that include this data may be incompatible with older versions of BIND; the ``-C`` option suppresses them. -``-c class`` +.. option:: -c class + This option indicates that the DNS record containing the key should have the specified class. If not specified, class IN is used. -``-f flag`` +.. option:: -f flag + This option sets the specified flag in the ``flag`` field of the KEY/DNSKEY record. The only recognized flags are KSK (Key-Signing Key) and REVOKE. -``-G`` +.. option:: -G + This option generates a key, but does not publish it or sign with it. This option is incompatible with ``-P`` and ``-A``. -``-h`` +.. option:: -h + This option prints a short summary of the options and arguments to ``dnssec-keyfromlabel``. -``-K directory`` +.. option:: -K directory + This option sets the directory in which the key files are to be written. -``-k`` +.. option:: -k + This option generates KEY records rather than DNSKEY records. ``-L`` ttl @@ -122,12 +134,14 @@ Options place, in which case the existing TTL would take precedence. Setting the default TTL to ``0`` or ``none`` removes it. -``-p protocol`` +.. option:: -p protocol + This option sets the protocol value for the key. The protocol is a number between 0 and 255. The default is 3 (DNSSEC). Other possible values for this argument are listed in :rfc:`2535` and its successors. -``-S key`` +.. option:: -S key + This option generates a key as an explicit successor to an existing key. The name, algorithm, size, and type of the key are set to match the predecessor. The activation date of the new key is set to the @@ -135,19 +149,23 @@ Options set to the activation date minus the prepublication interval, which defaults to 30 days. -``-t type`` +.. option:: -t type + This option indicates the type of the key. ``type`` must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers to the ability to authenticate data, and CONF to the ability to encrypt data. -``-v level`` +.. option:: -v level + This option sets the debugging level. -``-V`` +.. option:: -V + This option prints version information. -``-y`` +.. option:: -y + This option allows DNSSEC key files to be generated even if the key ID would collide with that of an existing key, in the event of either key being revoked. (This is only safe to enable if @@ -166,41 +184,49 @@ months (defined as 30 24-hour days), weeks, days, hours, or minutes, respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use ``none`` or ``never``. -``-P date/offset`` +.. option:: -P date/offset + This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it. If not set, and if the ``-G`` option has not been used, the default is the current date. -``-P sync date/offset`` +.. option:: -P sync date/offset + This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone. -``-A date/offset`` +.. option:: -A date/offset + This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. If not set, and if the ``-G`` option has not been used, the default is the current date. -``-R date/offset`` +.. option:: -R date/offset + This option sets the date on which the key is to be revoked. After that date, the key is flagged as revoked. It is included in the zone and is used to sign it. -``-I date/offset`` +.. option:: -I date/offset + This option sets the date on which the key is to be retired. After that date, the key is still included in the zone, but it is not used to sign it. -``-D date/offset`` +.. option:: -D date/offset + This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.) -``-D sync date/offset`` +.. option:: -D sync date/offset + This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted. -``-i interval`` +.. option:: -i interval + This option sets the prepublication interval for a key. If set, then the publication and activation dates must be separated by at least this much time. If the activation date is specified but the publication diff --git a/bin/dnssec/dnssec-keygen.rst b/bin/dnssec/dnssec-keygen.rst index db37d7e778..65f0beb09a 100644 --- a/bin/dnssec/dnssec-keygen.rst +++ b/bin/dnssec/dnssec-keygen.rst @@ -36,13 +36,15 @@ generated. Options ~~~~~~~ -``-3`` +.. option:: -3 + This option uses an NSEC3-capable algorithm to generate a DNSSEC key. If this option is used with an algorithm that has both NSEC and NSEC3 versions, then the NSEC3 version is selected; for example, ``dnssec-keygen -3a RSASHA1`` specifies the NSEC3RSASHA1 algorithm. -``-a algorithm`` +.. option:: -a algorithm + This option selects the cryptographic algorithm. For DNSSEC keys, the value of ``algorithm`` must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. For @@ -61,7 +63,8 @@ Options keys, but that feature was removed in BIND 9.13.0. Use ``tsig-keygen`` to generate TSIG keys. -``-b keysize`` +.. option:: -b keysize + This option specifies the number of bits in the key. The choice of key size depends on the algorithm used: RSA keys must be between 1024 and 4096 bits; Diffie-Hellman keys must be between 128 and 4096 bits. Elliptic @@ -72,7 +75,8 @@ Options have a default size of 1024 bits; RSA keys for use as key-signing keys (KSKs, generated with ``-f KSK``) default to 2048 bits. -``-C`` +.. option:: -C + This option enables compatibility mode, which generates an old-style key, without any timing metadata. By default, ``dnssec-keygen`` includes the key's creation date in the metadata stored with the private key; other @@ -80,44 +84,53 @@ Options etc. Keys that include this data may be incompatible with older versions of BIND; the ``-C`` option suppresses them. -``-c class`` +.. option:: -c class + This option indicates that the DNS record containing the key should have the specified class. If not specified, class IN is used. -``-d bits`` +.. option:: -d bits + This option specifies the key size in bits. For the algorithms RSASHA1, NSEC3RSASA1, RSASHA256, and RSASHA512 the key size must be between 1024 and 4096 bits; DH size is between 128 and 4096 bits. This option is ignored for algorithms ECDSAP256SHA256, ECDSAP384SHA384, ED25519, and ED448. -``-E engine`` +.. option:: -E engine + This option specifies the cryptographic hardware to use, when applicable. When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually ``pkcs11``). -``-f flag`` +.. option:: -f flag + This option sets the specified flag in the flag field of the KEY/DNSKEY record. The only recognized flags are KSK (Key-Signing Key) and REVOKE. -``-G`` +.. option:: -G + This option generates a key, but does not publish it or sign with it. This option is incompatible with ``-P`` and ``-A``. -``-g generator`` +.. option:: -g generator + This option indicates the generator to use if generating a Diffie-Hellman key. Allowed values are 2 and 5. If no generator is specified, a known prime from :rfc:`2539` is used if possible; otherwise the default is 2. -``-h`` +.. option:: -h + This option prints a short summary of the options and arguments to ``dnssec-keygen``. -``-K directory`` +.. option:: -K directory + This option sets the directory in which the key files are to be written. -``-k policy`` +.. option:: -k policy + This option creates keys for a specific ``dnssec-policy``. If a policy uses multiple keys, ``dnssec-keygen`` generates multiple keys. This also creates a ".state" file to keep track of the key state. @@ -126,7 +139,8 @@ Options it cannot be used at the same time as many of the other options that ``dnssec-keygen`` provides. -``-L ttl`` +.. option:: -L ttl + This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in @@ -135,24 +149,28 @@ Options defaults to the SOA TTL. Setting the default TTL to ``0`` or ``none`` is the same as leaving it unset. -``-l file`` +.. option:: -l file + This option provides a configuration file that contains a ``dnssec-policy`` statement (matching the policy set with ``-k``). -``-n nametype`` +.. option:: -n nametype + This option specifies the owner type of the key. The value of ``nametype`` must either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host (KEY)), USER (for a key associated with a user (KEY)), or OTHER (DNSKEY). These values are case-insensitive. The default is ZONE for DNSKEY generation. -``-p protocol`` +.. option:: -p protocol + This option sets the protocol value for the generated key, for use with ``-T KEY``. The protocol is a number between 0 and 255. The default is 3 (DNSSEC). Other possible values for this argument are listed in :rfc:`2535` and its successors. -``-q`` +.. option:: -q + This option sets quiet mode, which suppresses unnecessary output, including progress indication. Without this option, when ``dnssec-keygen`` is run interactively to generate an RSA or DSA key pair, it prints a @@ -162,7 +180,8 @@ Options round of the Miller-Rabin primality test; and a space ( ) means that the number has passed all the tests and is a satisfactory key. -``-S key`` +.. option:: -S key + This option creates a new key which is an explicit successor to an existing key. The name, algorithm, size, and type of the key are set to match the existing key. The activation date of the new key is set to @@ -170,26 +189,31 @@ Options set to the activation date minus the prepublication interval, which defaults to 30 days. -``-s strength`` +.. option:: -s strength + This option specifies the strength value of the key. The strength is a number between 0 and 15, and currently has no defined purpose in DNSSEC. -``-T rrtype`` +.. option:: -T rrtype + This option specifies the resource record type to use for the key. ``rrtype`` must be either DNSKEY or KEY. The default is DNSKEY when using a DNSSEC algorithm, but it can be overridden to KEY for use with SIG(0). -``-t type`` +.. option:: -t type + This option indicates the type of the key for use with ``-T KEY``. ``type`` must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers to the ability to authenticate data, and CONF to the ability to encrypt data. -``-V`` +.. option:: -V + This option prints version information. -``-v level`` +.. option:: -v level + This option sets the debugging level. Timing Options @@ -204,43 +228,51 @@ months (defined as 30 24-hour days), weeks, days, hours, or minutes, respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use ``none`` or ``never``. -``-P date/offset`` +.. option:: -P date/offset + This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it. If not set, and if the ``-G`` option has not been used, the default is the current date. -``-P sync date/offset`` +.. option:: -P sync date/offset + This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone. -``-A date/offset`` +.. option:: -A date/offset + This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. If not set, and if the ``-G`` option has not been used, the default is the current date. If set, and ``-P`` is not set, the publication date is set to the activation date minus the prepublication interval. -``-R date/offset`` +.. option:: -R date/offset + This option sets the date on which the key is to be revoked. After that date, the key is flagged as revoked. It is included in the zone and is used to sign it. -``-I date/offset`` +.. option:: -I date/offset + This option sets the date on which the key is to be retired. After that date, the key is still included in the zone, but it is not used to sign it. -``-D date/offset`` +.. option:: -D date/offset + This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.) -``-D sync date/offset`` +.. option:: -D sync date/offset + This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted. -``-i interval`` +.. option:: -i interval + This option sets the prepublication interval for a key. If set, then the publication and activation dates must be separated by at least this much time. If the activation date is specified but the publication diff --git a/bin/dnssec/dnssec-revoke.rst b/bin/dnssec/dnssec-revoke.rst index d7027a96d5..0d748f5b0a 100644 --- a/bin/dnssec/dnssec-revoke.rst +++ b/bin/dnssec/dnssec-revoke.rst @@ -31,34 +31,42 @@ containing the now-revoked key. Options ~~~~~~~ -``-h`` +.. option:: -h + This option emits a usage message and exits. -``-K directory`` +.. option:: -K directory + This option sets the directory in which the key files are to reside. -``-r`` +.. option:: -r + This option indicates to remove the original keyset files after writing the new keyset files. -``-v level`` +.. option:: -v level + This option sets the debugging level. -``-V`` +.. option:: -V + This option prints version information. -``-E engine`` +.. option:: -E engine + This option specifies the cryptographic hardware to use, when applicable. When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually ``pkcs11``). -``-f`` +.. option:: -f + This option indicates a forced overwrite and causes ``dnssec-revoke`` to write the new key pair, even if a file already exists matching the algorithm and key ID of the revoked key. -``-R`` +.. option:: -R + This option prints the key tag of the key with the REVOKE bit set, but does not revoke the key. diff --git a/bin/dnssec/dnssec-settime.rst b/bin/dnssec/dnssec-settime.rst index 46975035ea..e21e57acae 100644 --- a/bin/dnssec/dnssec-settime.rst +++ b/bin/dnssec/dnssec-settime.rst @@ -59,7 +59,8 @@ purposes. Options ~~~~~~~ -``-f`` +.. option:: -f + This option forces an update of an old-format key with no metadata fields. Without this option, ``dnssec-settime`` fails when attempting to update a legacy key. With this option, the key is recreated in the new @@ -68,10 +69,12 @@ Options specified, then the key's publication and activation dates are also set to the present time. -``-K directory`` +.. option:: -K directory + This option sets the directory in which the key files are to reside. -``-L ttl`` +.. option:: -L ttl + This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in @@ -80,16 +83,20 @@ Options defaults to the SOA TTL. Setting the default TTL to ``0`` or ``none`` removes it from the key. -``-h`` +.. option:: -h + This option emits a usage message and exits. -``-V`` +.. option:: -V + This option prints version information. -``-v level`` +.. option:: -v level + This option sets the debugging level. -``-E engine`` +.. option:: -E engine + This option specifies the cryptographic hardware to use, when applicable. When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL @@ -108,47 +115,57 @@ months (defined as 30 24-hour days), weeks, days, hours, or minutes, respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use ``none`` or ``never``. -``-P date/offset`` +.. option:: -P date/offset + This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it. -``-P ds date/offset`` +.. option:: -P ds date/offset + This option sets the date on which DS records that match this key have been seen in the parent zone. -``-P sync date/offset`` +.. option:: -P sync date/offset + This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone. -``-A date/offset`` +.. option:: -A date/offset + This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. -``-R date/offset`` +.. option:: -R date/offset + This option sets the date on which the key is to be revoked. After that date, the key is flagged as revoked. It is included in the zone and is used to sign it. -``-I date/offset`` +.. option:: -I date/offset + This option sets the date on which the key is to be retired. After that date, the key is still included in the zone, but it is not used to sign it. -``-D date/offset`` +.. option:: -D date/offset + This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.) -``-D ds date/offset`` +.. option:: -D ds date/offset + This option sets the date on which the DS records that match this key have been seen removed from the parent zone. -``-D sync date/offset`` +.. option:: -D sync date/offset + This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted. -``-S predecessor key`` +.. option:: -S predecessor key + This option selects a key for which the key being modified is an explicit successor. The name, algorithm, size, and type of the predecessor key must exactly match those of the key being modified. The activation @@ -156,7 +173,8 @@ explicitly prevent a date from being set, use ``none`` or ``never``. predecessor. The publication date is set to the activation date minus the prepublication interval, which defaults to 30 days. -``-i interval`` +.. option:: -i interval + This option sets the prepublication interval for a key. If set, then the publication and activation dates must be separated by at least this much time. If the activation date is specified but the publication @@ -183,22 +201,28 @@ purpose, but should never be used in production. Known key states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE. -``-s`` +.. option:: -s + This option indicates that when setting key timing data, the state file should also be updated. -``-g state`` +.. option:: -g state + This option sets the goal state for this key. Must be HIDDEN or OMNIPRESENT. -``-d state date/offset`` +.. option:: -d state date/offset + This option sets the DS state for this key as of the specified date, offset from the current date. -``-k state date/offset`` +.. option:: -k state date/offset + This option sets the DNSKEY state for this key as of the specified date, offset from the current date. -``-r state date/offset`` +.. option:: -r state date/offset + This option sets the RRSIG (KSK) state for this key as of the specified date, offset from the current date. -``-z state date/offset`` +.. option:: -z state date/offset + This option sets the RRSIG (ZSK) state for this key as of the specified date, offset from the current date. Printing Options @@ -207,10 +231,12 @@ Printing Options ``dnssec-settime`` can also be used to print the timing metadata associated with a key. -``-u`` +.. option:: -u + This option indicates that times should be printed in Unix epoch format. -``-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all`` +.. option:: -p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all + This option prints a specific metadata value or set of metadata values. The ``-p`` option may be followed by one or more of the following letters or strings to indicate which value or values to print: ``C`` for the diff --git a/bin/dnssec/dnssec-signzone.rst b/bin/dnssec/dnssec-signzone.rst index 4dbf25a84e..4288acd496 100644 --- a/bin/dnssec/dnssec-signzone.rst +++ b/bin/dnssec/dnssec-signzone.rst @@ -33,21 +33,26 @@ file for each child zone. Options ~~~~~~~ -``-a`` +.. option:: -a + This option verifies all generated signatures. -``-c class`` +.. option:: -c class + This option specifies the DNS class of the zone. -``-C`` +.. option:: -C + This option sets compatibility mode, in which a ``keyset-zonename`` file is generated in addition to ``dsset-zonename`` when signing a zone, for use by older versions of ``dnssec-signzone``. -``-d directory`` +.. option:: -d directory + This option indicates the directory where BIND 9 should look for ``dsset-`` or ``keyset-`` files. -``-D`` +.. option:: -D + This option indicates that only those record types automatically managed by ``dnssec-signzone``, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output. If smart signing (``-S``) is used, DNSKEY records are also included. @@ -55,7 +60,8 @@ Options ``$INCLUDE``. This option cannot be combined with ``-O raw`` or serial-number updating. -``-E engine`` +.. option:: -E engine + This option specifies the hardware to use for cryptographic operations, such as a secure key store used for signing, when applicable. @@ -63,19 +69,23 @@ Options engine identifier that drives the cryptographic accelerator or hardware service module (usually ``pkcs11``). -``-g`` +.. option:: -g + This option indicates that DS records for child zones should be generated from a ``dsset-`` or ``keyset-`` file. Existing DS records are removed. -``-K directory`` +.. option:: -K directory + This option specifies the directory to search for DNSSEC keys. If not specified, it defaults to the current directory. -``-k key`` +.. option:: -k key + This option tells BIND 9 to treat the specified key as a key-signing key, ignoring any key flags. This option may be specified multiple times. -``-M maxttl`` +.. option:: -M maxttl + This option sets the maximum TTL for the signed zone. Any TTL higher than ``maxttl`` in the input zone is reduced to ``maxttl`` in the output. This provides certainty as to the largest possible TTL in the signed zone, @@ -86,7 +96,8 @@ Options ``named.conf``. (Note: This option is incompatible with ``-D``, because it modifies non-DNSSEC data in the output zone.) -``-s start-time`` +.. option:: -s start-time + This option specifies the date and time when the generated RRSIG records become valid. This can be either an absolute or relative time. An absolute start time is indicated by a number in YYYYMMDDHHMMSS notation; @@ -95,7 +106,8 @@ Options time. If no ``start-time`` is specified, the current time minus 1 hour (to allow for clock skew) is used. -``-e end-time`` +.. option:: -e end-time + This option specifies the date and time when the generated RRSIG records expire. As with ``start-time``, an absolute time is indicated in YYYYMMDDHHMMSS notation. A time relative to the start time is indicated with ``+N``, @@ -104,7 +116,8 @@ Options specified, 30 days from the start time is the default. ``end-time`` must be later than ``start-time``. -``-X extended end-time`` +.. option:: -X extended end-time + This option specifies the date and time when the generated RRSIG records for the DNSKEY RRset expire. This is to be used in cases when the DNSKEY signatures need to persist longer than signatures on other records; @@ -119,20 +132,24 @@ Options as the default. (``end-time``, in turn, defaults to 30 days from the start time.) ``extended end-time`` must be later than ``start-time``. -``-f output-file`` +.. option:: -f output-file + This option indicates the name of the output file containing the signed zone. The default is to append ``.signed`` to the input filename. If ``output-file`` is set to ``-``, then the signed zone is written to the standard output, with a default output format of ``full``. -``-h`` +.. option:: -h + This option prints a short summary of the options and arguments to ``dnssec-signzone``. -``-V`` +.. option:: -V + This option prints version information. -``-i interval`` +.. option:: -i interval + This option indicates that, when a previously signed zone is passed as input, records may be re-signed. The ``interval`` option specifies the cycle interval as an offset from the current time, in seconds. If a RRSIG record expires @@ -146,14 +163,16 @@ Options days. Therefore, if any existing RRSIG records are due to expire in less than 7.5 days, they are replaced. -``-I input-format`` +.. option:: -I input-format + This option sets the format of the input zone file. Possible formats are ``text`` (the default), and ``raw``. This option is primarily intended to be used for dynamic signed zones, so that the dumped zone file in a non-text format containing updates can be signed directly. This option is not useful for non-dynamic zones. -``-j jitter`` +.. option:: -j jitter + When signing a zone with a fixed signature lifetime, all RRSIG records issued at the time of signing expire simultaneously. If the zone is incrementally signed, i.e., a previously signed zone is passed @@ -168,16 +187,19 @@ Options less congestion than if all validators need to refetch at around the same time. -``-L serial`` +.. option:: -L serial + When writing a signed zone to "raw" format, this option sets the "source serial" value in the header to the specified ``serial`` number. (This is expected to be used primarily for testing purposes.) -``-n ncpus`` +.. option:: -n ncpus + This option specifies the number of threads to use. By default, one thread is started for each detected CPU. -``-N soa-serial-format`` +.. option:: -N soa-serial-format + This option sets the SOA serial number format of the signed zone. Possible formats are ``keep`` (the default), ``increment``, ``unixtime``, and ``date``. @@ -200,11 +222,13 @@ Options than or equal to that value, in which case it is simply incremented by one. -``-o origin`` +.. option:: -o origin + This option sets the zone origin. If not specified, the name of the zone file is assumed to be the origin. -``-O output-format`` +.. option:: -O output-format + This option sets the format of the output file containing the signed zone. Possible formats are ``text`` (the default), which is the standard textual representation of the zone; ``full``, which is text output in a @@ -214,7 +238,8 @@ Options if N is 0, the raw file can be read by any version of ``named``; if N is 1, the file can be read by release 9.9.0 or higher. The default is 1. -``-P`` +.. option:: -P + This option disables post-sign verification tests. The post-sign verification tests ensure that for each algorithm in @@ -222,7 +247,8 @@ Options revoked KSK keys are self-signed, and that all records in the zone are signed by the algorithm. This option skips these tests. -``-Q`` +.. option:: -Q + This option removes signatures from keys that are no longer active. Normally, when a previously signed zone is passed as input to the @@ -234,14 +260,16 @@ Options active. This enables ZSK rollover using the procedure described in :rfc:`4641#4.2.1.1` ("Pre-Publish Key Rollover"). -``-q`` +.. option:: -q + This option enables quiet mode, which suppresses unnecessary output. Without this option, when ``dnssec-signzone`` is run it prints three pieces of information to standard output: the number of keys in use; the algorithms used to verify the zone was signed correctly and other status information; and the filename containing the signed zone. With the option that output is suppressed, leaving only the filename. -``-R`` +.. option:: -R + This option removes signatures from keys that are no longer published. This option is similar to ``-Q``, except it forces @@ -250,7 +278,8 @@ Options :rfc:`4641#4.2.1.2` ("Double Signature Zone Signing Key Rollover"). -``-S`` +.. option:: -S + This option enables smart signing, which instructs ``dnssec-signzone`` to search the key repository for keys that match the zone being signed, and to include them in the zone if appropriate. @@ -283,7 +312,8 @@ Options If the key's sync deletion date is set and is in the past, synchronization records (type CDS and/or CDNSKEY) are removed. -``-T ttl`` +.. option:: -T ttl + This option specifies a TTL to be used for new DNSKEY records imported into the zone from the key repository. If not specified, the default is the TTL value from the zone's SOA record. This option is ignored when @@ -295,40 +325,48 @@ Options conflict between TTL values in imported keys, the shortest one is used. -``-t`` +.. option:: -t + This option prints statistics at completion. -``-u`` +.. option:: -u + This option updates the NSEC/NSEC3 chain when re-signing a previously signed zone. With this option, a zone signed with NSEC can be switched to NSEC3, or a zone signed with NSEC3 can be switched to NSEC or to NSEC3 with different parameters. Without this option, ``dnssec-signzone`` retains the existing chain when re-signing. -``-v level`` +.. option:: -v level + This option sets the debugging level. -``-x`` +.. option:: -x + 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``.) -``-z`` +.. 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``.) -``-3 salt`` +.. option:: -3 salt + This option generates an NSEC3 chain with the given hex-encoded salt. A dash (-) can be used to indicate that no salt is to be used when generating the NSEC3 chain. -``-H iterations`` +.. option:: -H iterations + This option indicates that, when generating an NSEC3 chain, BIND 9 should use this many iterations. The default is 10. -``-A`` +.. option:: -A + This option indicates that, when generating an NSEC3 chain, BIND 9 should set the OPTOUT flag on all NSEC3 records and should not generate NSEC3 records for insecure delegations. @@ -336,10 +374,12 @@ Options all records. This is useful when using the ``-u`` option to modify an NSEC3 chain which previously had OPTOUT set. -``zonefile`` +.. option:: zonefile + This option sets the file containing the zone to be signed. -``key`` +.. option:: key + This option specifies which keys should be used to sign the zone. If no keys are specified, the zone is examined for DNSKEY records at the zone apex. If these records are found and there are matching private keys in diff --git a/bin/dnssec/dnssec-verify.rst b/bin/dnssec/dnssec-verify.rst index 28e6cd8b43..5d8c7c0b56 100644 --- a/bin/dnssec/dnssec-verify.rst +++ b/bin/dnssec/dnssec-verify.rst @@ -31,48 +31,57 @@ NSEC/NSEC3 chains are complete. Options ~~~~~~~ -``-c class`` +.. option:: -c class + This option specifies the DNS class of the zone. -``-E engine`` +.. option:: -E engine + This option specifies the cryptographic hardware to use, when applicable. When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually ``pkcs11``). -``-I input-format`` +.. option:: -I input-format + This option sets the format of the input zone file. Possible formats are ``text`` (the default) and ``raw``. This option is primarily intended to be used for dynamic signed zones, so that the dumped zone file in a non-text format containing updates can be verified independently. This option is not useful for non-dynamic zones. -``-o origin`` +.. option:: -o origin + This option indicates the zone origin. If not specified, the name of the zone file is assumed to be the origin. -``-v level`` +.. option:: -v level + This option sets the debugging level. -``-V`` +.. option:: -V + This option prints version information. -``-q`` +.. option:: -q + This option sets quiet mode, which suppresses output. Without this option, when ``dnssec-verify`` is run it prints to standard output the number of keys in use, the algorithms used to verify the zone was signed correctly, and other status information. With this option, all non-error output is suppressed, and only the exit code indicates success. -``-x`` +.. option:: -x + This option verifies only that the DNSKEY RRset is signed with key-signing keys. Without this flag, it is assumed that the DNSKEY RRset is signed by all active keys. When this flag is set, it is not an error if the DNSKEY RRset is not signed by zone-signing keys. This corresponds to the ``-x`` option in ``dnssec-signzone``. -``-z`` +.. option:: -z + This option indicates that the KSK flag on the keys should be ignored when determining whether the zone is correctly signed. Without this flag, it is assumed that there is a non-revoked, self-signed DNSKEY with the KSK flag set for each diff --git a/bin/named/named.rst b/bin/named/named.rst index ea440b202b..b9cd8ed503 100644 --- a/bin/named/named.rst +++ b/bin/named/named.rst @@ -35,30 +35,36 @@ listens for queries. Options ~~~~~~~ -``-4`` +.. option:: -4 + This option tells ``named`` to use only IPv4, even if the host machine is capable of IPv6. ``-4`` and ``-6`` are mutually exclusive. -``-6`` +.. option:: -6 + This option tells ``named`` to use only IPv6, even if the host machine is capable of IPv4. ``-4`` and ``-6`` are mutually exclusive. -``-c config-file`` +.. option:: -c config-file + This option tells ``named`` to use ``config-file`` as its configuration file instead of the default, |named_conf|. To ensure that the configuration file can be reloaded after the server has changed its working directory due to to a possible ``directory`` option in the configuration file, ``config-file`` should be an absolute pathname. -``-d debug-level`` +.. option:: -d debug-level + This option sets the daemon's debug level to ``debug-level``. Debugging traces from ``named`` become more verbose as the debug level increases. -``-D string`` +.. option:: -D string + This option specifies a string that is used to identify a instance of ``named`` in a process listing. The contents of ``string`` are not examined. -``-E engine-name`` +.. option:: -E engine-name + When applicable, this option specifies the hardware to use for cryptographic operations, such as a secure key store used for signing. @@ -66,16 +72,20 @@ Options engine identifier that drives the cryptographic accelerator or hardware service module (usually ``pkcs11``). -``-f`` +.. option:: -f + This option runs the server in the foreground (i.e., do not daemonize). -``-g`` +.. option:: -g + This option runs the server in the foreground and forces all logging to ``stderr``. -``-L logfile`` +.. option:: -L logfile + This option sets the log to the file ``logfile`` by default, instead of the system log. -``-M option`` +.. option:: -M option + This option sets the default memory context options. If set to ``external``, the internal memory manager is bypassed in favor of system-provided memory allocation functions. If set to ``fill``, blocks @@ -84,18 +94,21 @@ Options and is the default unless ``named`` has been compiled with developer options. -``-m flag`` +.. option:: -m flag + This option turns on memory usage debugging flags. Possible flags are ``usage``, ``trace``, ``record``, ``size``, and ``mctx``. These correspond to the ``ISC_MEM_DEBUGXXXX`` flags described in ````. -``-n #cpus`` +.. option:: -n #cpus + This option creates ``#cpus`` worker threads to take advantage of multiple CPUs. If not specified, ``named`` tries to determine the number of CPUs present and creates one thread per CPU. If it is unable to determine the number of CPUs, a single worker thread is created. -``-p value`` +.. option:: -p value + This option specifies the port(s) on which the server will listen for queries. If ``value`` is of the form ```` or ``dns=``, the server will listen for DNS queries on @@ -106,8 +119,9 @@ Options listen for HTTPS queries on ``portnum``; the default is 443. If ``value`` is of the form ``http=``, the server will listen for HTTP queries on ``portnum``; the default is 80. - -``-s`` + +.. option:: -s + This option writes memory usage statistics to ``stdout`` on exit. .. note:: @@ -115,7 +129,8 @@ Options This option is mainly of interest to BIND 9 developers and may be removed or changed in a future release. -``-S #max-socks`` +.. option:: -S #max-socks + This option is deprecated and no longer has any function. .. warning:: @@ -130,7 +145,8 @@ Options specified value, because ``named`` reserves some file descriptors for its internal use. -``-t directory`` +.. option:: -t directory + This option tells ``named`` to chroot to ``directory`` after processing the command-line arguments, but before reading the configuration file. @@ -141,7 +157,8 @@ Options most systems; the way ``chroot`` is defined allows a process with root privileges to escape a chroot jail. -``-U #listeners`` +.. option:: -U #listeners + This option tells ``named`` the number of ``#listeners`` worker threads to listen on, for incoming UDP packets on each address. If not specified, ``named`` calculates a default value based on the number of detected CPUs: 1 for 1 CPU, and the @@ -151,7 +168,8 @@ Options CPUs, then ``-U`` may be increased as high as that value, but no higher. -``-u user`` +.. option:: -u user + This option sets the setuid to ``user`` after completing privileged operations, such as creating sockets that listen on privileged ports. @@ -165,13 +183,16 @@ Options previous kernels did not allow privileges to be retained after ``setuid``. -``-v`` +.. option:: -v + This option reports the version number and exits. -``-V`` +.. option:: -V + This option reports the version number and build options, and exits. -``-X lock-file`` +.. option:: -X lock-file + This option acquires a lock on the specified file at runtime; this helps to prevent duplicate ``named`` instances from running simultaneously. Use of this option overrides the ``lock-file`` option in diff --git a/bin/nsupdate/nsupdate.rst b/bin/nsupdate/nsupdate.rst index 64865a53f8..1bd4cdedc8 100644 --- a/bin/nsupdate/nsupdate.rst +++ b/bin/nsupdate/nsupdate.rst @@ -63,26 +63,33 @@ used by Windows 2000 can be switched on with the ``-o`` flag. Options ~~~~~~~ -``-4`` +.. option:: -4 + This option sets use of IPv4 only. -``-6`` +.. option:: -6 + This option sets use of IPv6 only. -``-C`` +.. option:: -C + Overrides the default `resolv.conf` file. This is only intended for testing. -``-d`` +.. option:: -d + This option sets debug mode, which provides tracing information about the update requests that are made and the replies received from the name server. -``-D`` +.. option:: -D + This option sets extra debug mode. -``-i`` +.. option:: -i + This option forces interactive mode, even when standard input is not a terminal. -``-k keyfile`` +.. 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``; @@ -93,7 +100,8 @@ Options key used to authenticate Dynamic DNS update requests. In this case, the key specified is not an HMAC-MD5 key. -``-l`` +.. option:: -l + This option sets local-host only mode, which sets the server address to localhost (disabling the ``server`` so that the server address cannot be overridden). Connections to the local server use a TSIG key @@ -102,26 +110,32 @@ Options ``update-policy`` to ``local``. The location of this key file can be overridden with the ``-k`` option. -``-L level`` +.. option:: -L level + This option sets the logging debug level. If zero, logging is disabled. -``-p port`` +.. option:: -p port + This option sets the port to use for connections to a name server. The default is 53. -``-P`` +.. option:: -P + This option prints the list of private BIND-specific resource record types whose format is understood by ``nsupdate``. See also the ``-T`` option. -``-r udpretries`` +.. option:: -r udpretries + This option sets the number of UDP retries. The default is 3. If zero, only one update request is made. -``-t timeout`` +.. option:: -t timeout + This option sets the maximum time an update request can take before it is aborted. The default is 300 seconds. If zero, the timeout is disabled. -``-T`` +.. option:: -T + This option prints the list of IANA standard resource record types whose format is understood by ``nsupdate``. ``nsupdate`` exits after the lists are printed. The ``-T`` option can be combined with the ``-P`` @@ -132,21 +146,25 @@ Options present, is parsed using the UNKNOWN rdata format, ( ). -``-u udptimeout`` +.. option:: -u udptimeout + This option sets the UDP retry interval. The default is 3 seconds. If zero, the interval is computed from the timeout interval and number of UDP retries. -``-v`` +.. option:: -v + This option specifies that TCP should be used even for small update requests. By default, ``nsupdate`` uses UDP to send update requests to the name server unless they are too large to fit in a UDP request, in which case TCP is used. TCP may be preferable when a batch of update requests is made. -``-V`` +.. option:: -V + This option prints the version number and exits. -``-y [hmac:]keyname:secret`` +.. option:: -y [hmac:]keyname:secret + This option sets the literal TSIG authentication key. ``keyname`` is the name of the key, and ``secret`` is the base64 encoded shared secret. ``hmac`` is the name of the key algorithm; valid choices are ``hmac-md5``, diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst index fbc836a5c2..0f76030534 100644 --- a/bin/rndc/rndc.rst +++ b/bin/rndc/rndc.rst @@ -46,51 +46,62 @@ server and decide what algorithm and key it should use. Options ~~~~~~~ -``-4`` +.. option:: -4 + This option indicates use of IPv4 only. -``-6`` +.. option:: -6 + This option indicates use of IPv6 only. -``-b source-address`` +.. option:: -b source-address + This option indicates ``source-address`` as the source address for the connection to the server. Multiple instances are permitted, to allow setting of both the IPv4 and IPv6 source addresses. -``-c config-file`` +.. option:: -c config-file + This option indicates ``config-file`` as the configuration file instead of the default, |rndc_conf|. -``-k key-file`` +.. option:: -k key-file + This option indicates ``key-file`` as the key file instead of the default, |rndc_key|. The key in |rndc_key| is used to authenticate commands sent to the server if the config-file does not exist. -``-s server`` +.. option:: -s server + ``server`` is the name or address of the server which matches a server statement in the configuration file for ``rndc``. If no server is supplied on the command line, the host named by the default-server clause in the options statement of the ``rndc`` configuration file is used. -``-p port`` +.. option:: -p port + This option instructs BIND 9 to send commands to TCP port ``port`` instead of its default control channel port, 953. -``-q`` +.. option:: -q + This option sets quiet mode, where message text returned by the server is not printed unless there is an error. -``-r`` +.. option:: -r + This option instructs ``rndc`` to print the result code returned by ``named`` after executing the requested command (e.g., ISC_R_SUCCESS, ISC_R_FAILURE, etc.). -``-V`` +.. option:: -V + This option enables verbose logging. -``-y key_id`` +.. 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, ``rndc`` first looks for a key clause in the server statement of @@ -108,7 +119,8 @@ without arguments. Currently supported commands are: -``addzone`` *zone* [*class* [*view*]] *configuration* +.. option:: addzone zone [class [view]] configuration + 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 @@ -133,7 +145,8 @@ Currently supported commands are: See also ``rndc delzone`` and ``rndc modzone``. -``delzone`` [**-clean**] *zone* [*class* [*view*]] +.. option:: delzone [-clean] zone [class [view]] + This command deletes a zone while the server is running. If the ``-clean`` argument is specified, the zone's master file (and @@ -151,7 +164,8 @@ Currently supported commands are: See also ``rndc addzone`` and ``rndc modzone``. -``dnssec`` ( **-status** | **-rollover** **-key** id [**-alg** *algorithm*] [**-when** *time*] | **-checkds** [**-key** *id* [**-alg** *algorithm*]] [**-when** *time*] ( *published* | *withdrawn* )) *zone* [*class* [*view*]] +.. option:: dnssec (-status | -rollover -key id [-alg algorithm] [-when time] | -checkds [-key id [-alg algorithm]] [-when time] published | withdraw)) zone [class [view]] + This command allows you to interact with the "dnssec-policy" of a given zone. @@ -170,7 +184,8 @@ Currently supported commands are: select the correct algorithm). The time that the DS has been published or withdrawn is set to now, unless otherwise specified with the argument ``-when time``. -``dnstap`` ( **-reopen** | **-roll** [*number*] ) +.. 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 truncate and re-open it. ``rndc dnstap -roll`` causes the output file @@ -179,25 +194,30 @@ Currently supported commands are: output file is moved to ".1", and so on. If ``number`` is specified, then the number of backup log files is limited to that number. -``dumpdb`` [**-all** | **-cache** | **-zones** | **-adb** | **-bad** | **-expired** | **-fail**] [*view ...*] +.. option:: dumpdb [-all | -cache | -zones | -adb | -bad | -expired | -fail] [view ...] + This command dumps the server's caches (default) and/or zones to the dump file for the specified views. If no view is specified, all views are dumped. (See the ``dump-file`` option in the BIND 9 Administrator Reference Manual.) -``flush`` +.. option:: flush + This command flushes the server's cache. -``flushname`` *name* [*view*] +.. option:: flushname name [view] + This command flushes the given name from the view's DNS cache and, if applicable, from the view's nameserver address database, bad server cache, and SERVFAIL cache. -``flushtree`` *name* [*view*] +.. option:: flushtree name [view] + This command flushes the given name, and all of its subdomains, from the view's DNS cache, address database, bad server cache, and SERVFAIL cache. -``freeze`` [*zone* [*class* [*view*]]] +.. option:: freeze [zone [class [view]]] + This command suspends updates to a dynamic zone. If no zone is specified, then all zones are suspended. This allows manual edits to be made to a zone normally updated by dynamic update, and causes changes in the @@ -206,7 +226,8 @@ Currently supported commands are: See also ``rndc thaw``. -``halt`` [**-p**] +.. option:: halt [-p] + 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 @@ -216,7 +237,8 @@ Currently supported commands are: See also ``rndc stop``. -``loadkeys`` [*zone* [*class* [*view*]]] +.. option:: loadkeys [zone [class [view]]] + This command fetches all DNSSEC keys for the given zone from the key directory. If they are within their publication period, they are merged into the zone's DNSKEY RRset. Unlike ``rndc sign``, however, the zone is not @@ -228,7 +250,8 @@ Currently supported commands are: zone to be configured to allow dynamic DNS. (See "Dynamic Update Policies" in the Administrator Reference Manual for more details.) -``managed-keys`` (*status* | *refresh* | *sync* | *destroy*) [*class* [*view*]] +.. option:: managed-keys (status | refresh | sync | destroy) [class [view]] + This command inspects and controls the "managed-keys" database which handles :rfc:`5011` DNSSEC trust anchor maintenance. If a view is specified, these commands are applied to that view; otherwise, they are applied to all @@ -266,7 +289,8 @@ Currently supported commands are: keys in the event of a trust anchor rollover, or as a brute-force repair for key maintenance problems. -``modzone`` *zone* [*class* [*view*]] *configuration* +.. option:: modzone zone [class [view]] configuration + This command modifies the configuration of a zone while the server is running. This command requires the ``allow-new-zones`` option to be set to ``yes``. As with ``addzone``, the configuration string specified on the @@ -284,15 +308,18 @@ Currently supported commands are: See also ``rndc addzone`` and ``rndc delzone``. -``notify`` *zone* [*class* [*view*]] +.. option:: notify zone [class [view]] + This command resends NOTIFY messages for the zone. -``notrace`` +.. option:: notrace + This command sets the server's debugging level to 0. See also ``rndc trace``. -``nta`` [( **-class** *class* | **-dump** | **-force** | **-remove** | **-lifetime** *duration*)] *domain* [*view*] +.. option:: nta [(-class class | -dump | -force | -remove | -lifetime duration)] domain [view] + 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 @@ -343,7 +370,8 @@ Currently supported commands are: view name that begins with a hyphen, use a double-hyphen (--) on the command line to indicate the end of options. -``querylog`` [(*on* | *off*)] +.. option:: querylog [(on | off)] + This command enables or disables query logging. For backward compatibility, this command can also be used without an argument to toggle query logging on and off. @@ -353,13 +381,15 @@ Currently supported commands are: of ``named.conf``, or by specifying ``querylog yes;`` in the ``options`` section of ``named.conf``. -``reconfig`` +.. option:: reconfig + This command reloads the configuration file and loads new zones, but does not reload existing zone files even if they have changed. This is faster than a full ``reload`` when there is a large number of zones, because it avoids the need to examine the modification times of the zone files. -``recursing`` +.. option:: recursing + This command dumps the list of queries ``named`` is currently recursing on, and the list of domains to which iterative queries are currently being sent. @@ -379,16 +409,20 @@ Currently supported commands are: and the next time a fetch is sent to that domain, it is recreated with the counters set to zero). -``refresh`` *zone* [*class* [*view*]] +.. option:: refresh zone [class [view]] + This command schedules zone maintenance for the given zone. -``reload`` +.. option:: reload + This command reloads the configuration file and zones. -``reload`` *zone* [*class* [*view*]] +.. option:: reload zone [class [view]] + This command reloads the given zone. -``retransfer`` *zone* [*class* [*view*]] +.. option:: retransfer zone [class [view]] + This command retransfers the given secondary zone from the primary server. If the zone is configured to use ``inline-signing``, the signed @@ -396,12 +430,14 @@ Currently supported commands are: unsigned version is complete, the signed version is regenerated with new signatures. -``scan`` +.. option:: scan + This command scans the list of available network interfaces for changes, without performing a full ``reconfig`` or waiting for the ``interface-interval`` timer. -``secroots`` [**-**] [*view* ...] +.. option:: secroots [-] [view ...] + This command dumps the security roots (i.e., trust anchors configured via ``trust-anchors``, or the ``managed-keys`` or ``trusted-keys`` statements [both deprecated], or ``dnssec-validation auto``) and negative trust anchors @@ -418,7 +454,8 @@ Currently supported commands are: See also ``rndc managed-keys``. -``serve-stale`` (**on** | **off** | **reset** | **status**) [*class* [*view*]] +.. 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``. @@ -430,12 +467,14 @@ Currently supported commands are: answers is currently enabled or disabled. It also reports the values of ``stale-answer-ttl`` and ``max-stale-ttl``. -``showzone`` *zone* [*class* [*view*]] +.. option:: showzone zone [class [view]] + This command prints the configuration of a running zone. See also ``rndc zonestatus``. -``sign`` *zone* [*class* [*view*]] +.. option:: sign zone [class [view]] + This command fetches all DNSSEC keys for the given zone from the key directory (see the ``key-directory`` option in the BIND 9 Administrator Reference Manual). If they are within their publication period, they are merged into @@ -450,7 +489,8 @@ Currently supported commands are: See also ``rndc loadkeys``. -``signing`` [(**-list** | **-clear** *keyid/algorithm* | **-clear** *all* | **-nsec3param** ( *parameters* | none ) | **-serial** *value* ) *zone* [*class* [*view*]] +.. option:: signing [(-list | -clear keyid/algorithm | -clear all | -nsec3param (parameters | none) | -serial value) zone [class [view]] + This command lists, edits, or removes the DNSSEC signing-state records for the specified zone. The status of ongoing DNSSEC operations, such as signing or generating NSEC3 chains, is stored in the zone in the form @@ -495,17 +535,20 @@ Currently supported commands are: is rejected. The primary use of this parameter is to set the serial number on inline signed zones. -``stats`` +.. option:: stats + This command writes server statistics to the statistics file. (See the ``statistics-file`` option in the BIND 9 Administrator Reference Manual.) -``status`` +.. option:: status + This command displays the status of the server. Note that the number of zones includes the internal ``bind/CH`` zone and the default ``./IN`` hint zone, if there is no explicit root zone configured. -``stop`` **-p** +.. option:: 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 ``-p`` is specified, ``named(8)`'s process ID is returned. @@ -514,12 +557,14 @@ Currently supported commands are: See also ``rndc halt``. -``sync`` **-clean** [*zone* [*class* [*view*]]] +.. option:: sync -clean [zone [class [view]]] + This command syncs changes in the journal file for a dynamic zone to the master file. If the "-clean" option is specified, the journal file is also removed. If no zone is specified, then all zones are synced. -``tcp-timeouts`` [*initial* *idle* *keepalive* *advertised*] +.. option:: tcp-timeouts [initial idle keepalive advertised] + When called without arguments, this command displays the current values of the ``tcp-initial-timeout``, ``tcp-idle-timeout``, ``tcp-keepalive-timeout``, and ``tcp-advertised-timeout`` options. @@ -528,7 +573,8 @@ Currently supported commands are: denial-of-service (DoS) attack. See the descriptions of these options in the BIND 9 Administrator Reference Manual for details of their use. -``thaw`` [*zone* [*class* [*view*]]] +.. option:: thaw [zone [class [view]]] + This command enables updates to a frozen dynamic zone. If no zone is specified, then all frozen zones are enabled. This causes the server to reload the zone from disk, and re-enables dynamic updates after the load has @@ -540,31 +586,37 @@ Currently supported commands are: See also ``rndc freeze``. -``trace`` +.. option:: trace + This command increments the server's debugging level by one. -``trace`` *level* +.. option:: trace level + This command sets the server's debugging level to an explicit value. See also ``rndc notrace``. -``tsig-delete`` *keyname* [*view*] +.. option:: tsig-delete keyname [view] + This command deletes a given TKEY-negotiated key from the server. This does not apply to statically configured TSIG keys. -``tsig-list`` +.. 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 dynamic TKEY-negotiated keys. -``validation`` (**on** | **off** | **status**) [*view* ...]`` +.. option:: validation (on | off | status) [view ...] + This command enables, disables, or checks the current status of DNSSEC validation. By default, validation is enabled. The cache is flushed when validation is turned on or off to avoid using data that might differ between states. -``zonestatus`` *zone* [*class* [*view*]] +.. option:: zonestatus zone [class [view]] + This command displays the current status of the given zone, including the master file name and any include files from which it was loaded, when it was most recently loaded, the current serial number, the number of nodes, @@ -574,7 +626,7 @@ Currently supported commands are: See also ``rndc showzone``. -``rndc`` commands that specify zone names, such as ``reload``, +``rndc`` commands that specify zone names, such as ``reload`` ``retransfer``, or ``zonestatus``, can be ambiguous when applied to zones of type ``redirect``. Redirect zones are always called ``.``, and can be confused with zones of type ``hint`` or with secondary copies of the root diff --git a/bin/tools/dnstap-read.rst b/bin/tools/dnstap-read.rst index 104c05f2e6..dc04f4ec1c 100644 --- a/bin/tools/dnstap-read.rst +++ b/bin/tools/dnstap-read.rst @@ -32,18 +32,22 @@ longer and more detailed YAML format is used. Options ~~~~~~~ -``-m`` +.. option:: -m + This option indicates trace memory allocations, and is used for debugging memory leaks. -``-p`` +.. option:: -p + This option prints the text form of the DNS message that was encapsulated in the ``dnstap`` frame, after printing the ``dnstap`` data. -``-x`` +.. option:: -x + This option prints a hex dump of the wire form of the DNS message that was encapsulated in the ``dnstap`` frame, after printing the ``dnstap`` data. -``-y`` +.. option:: -y + This option prints ``dnstap`` data in a detailed YAML format. See Also diff --git a/bin/tools/mdig.rst b/bin/tools/mdig.rst index 50aa588637..eb6fbdb459 100644 --- a/bin/tools/mdig.rst +++ b/bin/tools/mdig.rst @@ -60,39 +60,47 @@ assign values to options like the timeout interval. They have the form Anywhere Options ~~~~~~~~~~~~~~~~ -``-f`` +.. option:: -f + This option makes ``mdig`` operate in batch mode by reading a list of lookup requests to process from the file ``filename``. The file contains a number of queries, one per line. Each entry in the file should be organized in the same way they would be presented as queries to ``mdig`` using the command-line interface. -``-h`` +.. option:: -h + This option causes ``mdig`` to print detailed help information, with the full list of options, and exit. -``-v`` +.. option:: -v + This option causes ``mdig`` to print the version number and exit. Global Options ~~~~~~~~~~~~~~ -``-4`` +.. option:: -4 + This option forces ``mdig`` to only use IPv4 query transport. -``-6`` +.. option:: -6 + This option forces ``mdig`` to only use IPv6 query transport. -``-b address`` +.. option:: -b address + This option sets the source IP address of the query to ``address``. This must be a valid address on one of the host's network interfaces or "0.0.0.0" or "::". An optional port may be specified by appending "#" -``-m`` +.. option:: -m + This option enables memory usage debugging. -``-p port#`` +.. option:: -p port# + This option is used when a non-standard port number is to be queried. ``port#`` is the port number that ``mdig`` sends its queries to, instead of the standard DNS port number 53. This option is @@ -101,39 +109,49 @@ Global Options The global query options are: -``+[no]additional`` +.. option:: +[no]additional + This option displays [or does not display] the additional section of a reply. The default is to display it. -``+[no]all`` +.. option:: +[no]all + This option sets or clears all display flags. -``+[no]answer`` +.. option:: +[no]answer + This option displays [or does not display] the answer section of a reply. The default is to display it. -``+[no]authority`` +.. option:: +[no]authority + This option displays [or does not display] the authority section of a reply. The default is to display it. -``+[no]besteffort`` +.. option:: +[no]besteffort + This option attempts to display [or does not display] the contents of messages which are malformed. The default is to not display malformed answers. -``+burst`` +.. option:: +burst + This option delays queries until the start of the next second. -``+[no]cl`` +.. option:: +[no]cl + This option displays [or does not display] the CLASS when printing the record. -``+[no]comments`` +.. option:: +[no]comments + This option toggles the display of comment lines in the output. The default is to print comments. -``+[no]continue`` +.. option:: +[no]continue + This option toggles continuation on errors (e.g. timeouts). -``+[no]crypto`` +.. option:: +[no]crypto + This option toggles the display of cryptographic fields in DNSSEC records. The contents of these fields are unnecessary to debug most DNSSEC validation failures and removing them makes it easier to see the @@ -141,50 +159,60 @@ The global query options are: they are replaced by the string "[omitted]"; in the DNSKEY case, the key ID is displayed as the replacement, e.g., ``[ key id = value ]``. -``+dscp[=value]`` +.. option:: +dscp[=value] + This option sets the DSCP code point to be used when sending the query. Valid DSCP code points are in the range [0...63]. By default no code point is explicitly set. -``+[no]multiline`` +.. option:: +[no]multiline + This option toggles printing of records, like the SOA records, in a verbose multi-line format with human-readable comments. The default is to print each record on a single line, to facilitate machine parsing of the ``mdig`` output. -``+[no]question`` +.. option:: +[no]question + This option prints [or does not print] the question section of a query when an answer is returned. The default is to print the question section as a comment. -``+[no]rrcomments`` +.. option:: +[no]rrcomments + This option toggles the display of per-record comments in the output (for example, human-readable key information about DNSKEY records). The default is not to print record comments unless multiline mode is active. -``+[no]short`` +.. option:: +[no]short + This option provides [or does not provide] a terse answer. The default is to print the answer in a verbose form. -``+split=W`` +.. option:: +split=W + This option splits long hex- or base64-formatted fields in resource records into chunks of ``W`` characters (where ``W`` is rounded up to the nearest multiple of 4). ``+nosplit`` or ``+split=0`` causes fields not to be split. The default is 56 characters, or 44 characters when multiline mode is active. -``+[no]tcp`` +.. option:: +[no]tcp + This option uses [or does not use] TCP when querying name servers. The default behavior is to use UDP. -``+[no]ttlid`` +.. option:: +[no]ttlid + This option displays [or does not display] the TTL when printing the record. -``+[no]ttlunits`` +.. option:: +[no]ttlunits + This option displays [or does not display] the TTL in friendly human-readable time units of "s", "m", "h", "d", and "w", representing seconds, minutes, hours, days, and weeks. This implies +ttlid. -``+[no]vc`` +.. option:: +[no]vc + This option uses [or does not use] TCP when querying name servers. This alternate syntax to ``+[no]tcp`` is provided for backwards compatibility. The ``vc`` stands for "virtual circuit". @@ -192,18 +220,21 @@ The global query options are: Local Options ~~~~~~~~~~~~~ -``-c class`` +.. option:: -c class + This option sets the query class to ``class``. It can be any valid query class which is supported in BIND 9. The default query class is "IN". -``-t type`` +.. option:: -t type + This option sets the query type to ``type``. It can be any valid query type which is supported in BIND 9. The default query type is "A", unless the ``-x`` option is supplied to indicate a reverse lookup with the "PTR" query type. -``-x addr`` +.. option:: -x addr + Reverse lookups - mapping addresses to names - are simplified by this option. ``addr`` is an IPv4 address in dotted-decimal notation, or a colon-delimited IPv6 address. ``mdig`` automatically @@ -214,13 +245,16 @@ Local Options The local query options are: -``+[no]aaflag`` +.. option:: +[no]aaflag + This is a synonym for ``+[no]aaonly``. -``+[no]aaonly`` +.. option:: +[no]aaonly + This sets the ``aa`` flag in the query. -``+[no]adflag`` +.. option:: +[no]adflag + This sets [or does not set] the AD (authentic data) bit in the query. This requests the server to return whether all of the answer and authority sections have all been validated as secure, according to the security @@ -229,59 +263,71 @@ The local query options are: indicates that some part of the answer was insecure or not validated. This bit is set by default. -``+bufsize=B`` +.. option:: +bufsize=B + This sets the UDP message buffer size advertised using EDNS0 to ``B`` bytes. The maximum and minimum sizes of this buffer are 65535 and 0 respectively. Values outside this range are rounded up or down appropriately. Values other than zero cause a EDNS query to be sent. -``+[no]cdflag`` +.. option:: +[no]cdflag + This sets [or does not set] the CD (checking disabled) bit in the query. This requests the server to not perform DNSSEC validation of responses. -``+[no]cookie=####`` +.. option:: +[no]cookie=#### + This sends [or does not send] a COOKIE EDNS option, with an optional value. Replaying a COOKIE from a previous response allows the server to identify a previous client. The default is ``+nocookie``. -``+[no]dnssec`` +.. option:: +[no]dnssec + This requests that DNSSEC records be sent by setting the DNSSEC OK (DO) bit in the OPT record in the additional section of the query. -``+[no]edns[=#]`` +.. option:: +[no]edns[=#] + This specifies [or does not specify] the EDNS version to query with. Valid values are 0 to 255. Setting the EDNS version causes an EDNS query to be sent. ``+noedns`` clears the remembered EDNS version. EDNS is set to 0 by default. -``+[no]ednsflags[=#]`` +.. option:: +[no]ednsflags[=#] + This sets the must-be-zero EDNS flag bits (Z bits) to the specified value. Decimal, hex, and octal encodings are accepted. Setting a named flag (e.g. DO) is silently ignored. By default, no Z bits are set. -``+[no]ednsopt[=code[:value]]`` +.. option:: +[no]ednsopt[=code[:value]] + This specifies [or does not specify] an EDNS option with code point ``code`` and an optional payload of ``value`` as a hexadecimal string. ``+noednsopt`` clears the EDNS options to be sent. -``+[no]expire`` +.. option:: +[no]expire + This toggles sending of an EDNS Expire option. -``+[no]nsid`` +.. option:: +[no]nsid + This toggles inclusion of an EDNS name server ID request when sending a query. -``+[no]recurse`` +.. option:: +[no]recurse + This toggles the setting of the RD (recursion desired) bit in the query. This bit is set by default, which means ``mdig`` normally sends recursive queries. -``+retry=T`` +.. option:: +retry=T + This sets the number of times to retry UDP queries to server to ``T`` instead of the default, 2. Unlike ``+tries``, this does not include the initial query. -``+[no]subnet=addr[/prefix-length]`` +.. option:: +[no]subnet=addr[/prefix-length] + This sends [or does not send] an EDNS Client Subnet option with the specified IP address or network prefix. @@ -290,29 +336,35 @@ The local query options are: prefix-length of zero, which signals a resolver that the client's address information must *not* be used when resolving this query. -``+timeout=T`` +.. option:: +timeout=T + This sets the timeout for a query to ``T`` seconds. The default timeout is 5 seconds for UDP transport and 10 for TCP. An attempt to set ``T`` to less than 1 results in a query timeout of 1 second being applied. -``+tries=T`` +.. option:: +tries=T + This sets the number of times to try UDP queries to server to ``T`` instead of the default, 3. If ``T`` is less than or equal to zero, the number of tries is silently rounded up to 1. -``+udptimeout=T`` +.. option:: +udptimeout=T + This sets the timeout between UDP query retries to ``T``. -``+[no]unknownformat`` +.. option:: +[no]unknownformat + This prints [or does not print] all RDATA in unknown RR-type presentation format (see :rfc:`3597`). The default is to print RDATA for known types in the type's presentation format. -``+[no]yaml`` +.. option:: +[no]yaml + This toggles printing of the responses in a detailed YAML format. -``+[no]zflag`` +.. option:: +[no]zflag + This sets [or does not set] the last unassigned DNS header flag in a DNS query. This flag is off by default. diff --git a/bin/tools/named-nzd2nzf.rst b/bin/tools/named-nzd2nzf.rst index d20fc369b1..634cc85561 100644 --- a/bin/tools/named-nzd2nzf.rst +++ b/bin/tools/named-nzd2nzf.rst @@ -33,7 +33,8 @@ version of BIND to an older version. Arguments ~~~~~~~~~ -``filename`` +.. option:: filename + This is the name of the ``.nzd`` file whose contents should be printed. See Also diff --git a/bin/tools/named-rrchecker.rst b/bin/tools/named-rrchecker.rst index 191f229319..7ea9c39de8 100644 --- a/bin/tools/named-rrchecker.rst +++ b/bin/tools/named-rrchecker.rst @@ -30,22 +30,27 @@ input and checks whether it is syntactically correct. Options ~~~~~~~ -``-h`` +.. option:: -h + This option prints out the help menu. -``-o origin`` +.. option:: -o origin + This option specifies the origin to be used when interpreting the record. -``-p`` +.. option:: -p + This option prints out the resulting record in canonical form. If there is no canonical form defined, the record is printed in unknown record format. -``-u`` +.. option:: -u + This option prints out the resulting record in unknown record form. -``-C``, ``-T``, and ``-P`` +.. option:: -C, -T, -P + These options print out the known class, standard type, and private type mnemonics, respectively. diff --git a/bin/tools/nsec3hash.rst b/bin/tools/nsec3hash.rst index 9b174cee34..9facfc773e 100644 --- a/bin/tools/nsec3hash.rst +++ b/bin/tools/nsec3hash.rst @@ -39,22 +39,27 @@ into a command line to confirm the correctness of an NSEC3 hash. Arguments ~~~~~~~~~ -``salt`` +.. option:: salt + This is the salt provided to the hash algorithm. -``algorithm`` +.. option:: algorithm + This is a number indicating the hash algorithm. Currently the only supported hash algorithm for NSEC3 is SHA-1, which is indicated by the number 1; consequently "1" is the only useful value for this argument. -``flags`` +.. option:: flags + This is provided for compatibility with NSEC3 record presentation format, but is ignored since the flags do not affect the hash. -``iterations`` +.. option:: iterations + This is the number of additional times the hash should be performed. -``domain`` +.. option:: domain + This is the domain name to be hashed. See Also diff --git a/doc/man/ddns-confgen.8in b/doc/man/ddns-confgen.8in index 47261ab8c8..3088aca7d1 100644 --- a/doc/man/ddns-confgen.8in +++ b/doc/man/ddns-confgen.8in @@ -54,37 +54,47 @@ be used from a remote system. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-a algorithm\fP +.B \-a algorithm This option specifies the algorithm to use for the TSIG key. Available choices are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, and hmac\-sha512. The default is hmac\-sha256. Options are case\-insensitive, and the "hmac\-" prefix may be omitted. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints a short summary of options and arguments. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k keyname\fP +.B \-k keyname This option specifies the key name of the DDNS authentication key. The default is \fBddns\-key\fP when neither the \fB\-s\fP nor \fB\-z\fP option is specified; otherwise, the default is \fBddns\-key\fP as a separate label followed by the argument of the option, e.g., \fBddns\-key.example.com.\fP The key name must have the format of a valid domain name, consisting of letters, digits, hyphens, and periods. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-q\fP +.B \-q This option enables quiet mode, which prints only the key, with no explanatory text or usage examples. This is essentially identical to \fBtsig\-keygen\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s name\fP +.B \-s name This option generates a configuration example to allow dynamic updates of a single hostname. The example \fBnamed.conf\fP text shows how to set an update policy for the specified name using the "name" nametype. The default key name is \fBddns\-key.name\fP\&. Note that the "self" nametype cannot be used, since the name to be updated may differ from the key name. This option cannot be used with the \fB\-z\fP option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-z zone\fP +.B \-z zone This option generates a configuration example to allow dynamic updates of a zone. The example \fBnamed.conf\fP text shows how to set an update policy for the specified zone using the "zonesub" diff --git a/doc/man/delv.1in b/doc/man/delv.1in index 08e095d04c..407d07cca2 100644 --- a/doc/man/delv.1in +++ b/doc/man/delv.1in @@ -84,7 +84,7 @@ delv @server name type where: .INDENT 0.0 .TP -.B \fBserver\fP +.B server is the name or IP address of the name server to query. This can be an IPv4 address in dotted\-decimal notation or an IPv6 address in colon\-delimited notation. When the supplied \fBserver\fP argument is a @@ -99,11 +99,15 @@ options is in use, then only addresses for the corresponding transport are tried. If no usable addresses are found, \fBdelv\fP sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1 for IPv6). +.UNINDENT +.INDENT 0.0 .TP -.B \fBname\fP +.B name is the domain name to be looked up. +.UNINDENT +.INDENT 0.0 .TP -.B \fBtype\fP +.B type indicates what type of query is required \- ANY, A, MX, etc. \fBtype\fP can be any valid query type. If no \fBtype\fP argument is supplied, \fBdelv\fP performs a lookup for an A record. @@ -111,7 +115,7 @@ supplied, \fBdelv\fP performs a lookup for an A record. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-a anchor\-file\fP +.B \-a anchor\-file This option specifies a file from which to read DNSSEC trust anchors. The default is \fB@sysconfdir@/bind.keys\fP, which is included with BIND 9 and contains one or more trust anchors for the root zone ("."). @@ -126,52 +130,70 @@ supported. \fBdelv\fP does not consult the managed\-keys database maintained by \fBnamed\fP, which means that if either of the keys in \fB@sysconfdir@/bind.keys\fP is revoked and rolled over, \fB@sysconfdir@/bind.keys\fP must be updated to use DNSSEC validation in \fBdelv\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-b address\fP +.B \-b address This option sets the source IP address of the query to \fBaddress\fP\&. This must be a valid address on one of the host\(aqs network interfaces, or \fB0.0.0.0\fP, or \fB::\fP\&. An optional source port may be specified by appending \fB#\fP +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option sets the query class for the requested data. Currently, only class "IN" is supported in \fBdelv\fP and any other value is ignored. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-d level\fP +.B \-d level This option sets the systemwide debug level to \fBlevel\fP\&. The allowed range is from 0 to 99. The default is 0 (no debugging). Debugging traces from \fBdelv\fP become more verbose as the debug level increases. See the \fB+mtrace\fP, \fB+rtrace\fP, and \fB+vtrace\fP options below for additional debugging details. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option displays the \fBdelv\fP help usage output and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-i\fP +.B \-i This option sets insecure mode, which disables internal DNSSEC validation. (Note, however, that this does not set the CD bit on upstream queries. If the server being queried is performing DNSSEC validation, then it does not return invalid data; this can cause \fBdelv\fP to time out. When it is necessary to examine invalid data to debug a DNSSEC problem, use \fBdig +cd\fP\&.) +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-m\fP +.B \-m This option enables memory usage debugging. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p port#\fP +.B \-p port# This option specifies a destination port to use for queries, instead of the standard DNS port number 53. This option is used with a name server that has been configured to listen for queries on a non\-standard port number. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-q name\fP +.B \-q name This option sets the query name to \fBname\fP\&. While the query name can be specified without using the \fB\-q\fP option, it is sometimes necessary to disambiguate names from types or classes (for example, when looking up the name "ns", which could be misinterpreted as the type NS, or "ch", which could be misinterpreted as class CH). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t type\fP +.B \-t type This option sets the query type to \fBtype\fP, which can be any valid query type supported in BIND 9 except for zone transfer types AXFR and IXFR. As with \fB\-q\fP, this is useful to distinguish query\-name types or classes @@ -180,11 +202,15 @@ names from types. .sp The default query type is "A", unless the \fB\-x\fP option is supplied to indicate a reverse lookup, in which case it is "PTR". +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v\fP +.B \-v This option prints the \fBdelv\fP version and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-x addr\fP +.B \-x addr This option performs a reverse lookup, mapping an address to a name. \fBaddr\fP is an IPv4 address in dotted\-decimal notation, or a colon\-delimited IPv6 address. When \fB\-x\fP is used, there is no need to provide the @@ -192,11 +218,15 @@ IPv6 address. When \fB\-x\fP is used, there is no need to provide the lookup for a name like \fB11.12.13.10.in\-addr.arpa\fP and sets the query type to PTR. IPv6 addresses are looked up using nibble format under the IP6.ARPA domain. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-4\fP +.B \-4 This option forces \fBdelv\fP to only use IPv4. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-6\fP +.B \-6 This option forces \fBdelv\fP to only use IPv6. .UNINDENT .SH QUERY OPTIONS @@ -211,7 +241,7 @@ assign values to options like the timeout interval. They have the form \fB+keyword=value\fP\&. The query options are: .INDENT 0.0 .TP -.B \fB+[no]cdflag\fP +.B +[no]cdflag This option controls whether to set the CD (checking disabled) bit in queries sent by \fBdelv\fP\&. This may be useful when troubleshooting DNSSEC problems from behind a validating resolver. A validating resolver @@ -219,16 +249,22 @@ blocks invalid responses, making it difficult to retrieve them for analysis. Setting the CD flag on queries causes the resolver to return invalid responses, which \fBdelv\fP can then validate internally and report the errors in detail. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]class\fP +.B +[no]class This option controls whether to display the CLASS when printing a record. The default is to display the CLASS. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ttl\fP +.B +[no]ttl This option controls whether to display the TTL when printing a record. The default is to display the TTL. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]rtrace\fP +.B +[no]rtrace This option toggles resolver fetch logging. This reports the name and type of each query sent by \fBdelv\fP in the process of carrying out the resolution and validation process, including the original query @@ -239,8 +275,10 @@ This is equivalent to setting the debug level to 1 in the "resolver" logging category. Setting the systemwide debug level to 1 using the \fB\-d\fP option produces the same output, but affects other logging categories as well. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]mtrace\fP +.B +[no]mtrace This option toggles message logging. This produces a detailed dump of the responses received by \fBdelv\fP in the process of carrying out the resolution and validation process. @@ -249,8 +287,10 @@ This is equivalent to setting the debug level to 10 for the "packets" module of the "resolver" logging category. Setting the systemwide debug level to 10 using the \fB\-d\fP option produces the same output, but affects other logging categories as well. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]vtrace\fP +.B +[no]vtrace This option toggles validation logging. This shows the internal process of the validator as it determines whether an answer is validly signed, unsigned, or invalid. @@ -259,74 +299,100 @@ This is equivalent to setting the debug level to 3 for the "validator" module of the "dnssec" logging category. Setting the systemwide debug level to 3 using the \fB\-d\fP option produces the same output, but affects other logging categories as well. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]short\fP +.B +[no]short This option toggles between verbose and terse answers. The default is to print the answer in a verbose form. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]comments\fP +.B +[no]comments This option toggles the display of comment lines in the output. The default is to print comments. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]rrcomments\fP +.B +[no]rrcomments This option toggles the display of per\-record comments in the output (for example, human\-readable key information about DNSKEY records). The default is to print per\-record comments. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]crypto\fP +.B +[no]crypto This option toggles the display of cryptographic fields in DNSSEC records. The contents of these fields are unnecessary to debug most DNSSEC validation failures and removing them makes it easier to see the common failures. The default is to display the fields. When omitted, they are replaced by the string \fB[omitted]\fP or, in the DNSKEY case, the key ID is displayed as the replacement, e.g. \fB[ key id = value ]\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]trust\fP +.B +[no]trust This option controls whether to display the trust level when printing a record. The default is to display the trust level. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]split[=W]\fP +.B +[no]split[=W] This option splits long hex\- or base64\-formatted fields in resource records into chunks of \fBW\fP characters (where \fBW\fP is rounded up to the nearest multiple of 4). \fB+nosplit\fP or \fB+split=0\fP causes fields not to be split at all. The default is 56 characters, or 44 characters when multiline mode is active. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]all\fP +.B +[no]all This option sets or clears the display options \fB+[no]comments\fP, \fB+[no]rrcomments\fP, and \fB+[no]trust\fP as a group. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]multiline\fP +.B +[no]multiline This option prints long records (such as RRSIG, DNSKEY, and SOA records) in a verbose multi\-line format with human\-readable comments. The default is to print each record on a single line, to facilitate machine parsing of the \fBdelv\fP output. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]dnssec\fP +.B +[no]dnssec This option indicates whether to display RRSIG records in the \fBdelv\fP output. The default is to do so. Note that (unlike in \fBdig\fP) this does \fInot\fP 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 \fB\-i\fP or \fB+noroot\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]root[=ROOT]\fP +.B +[no]root[=ROOT] This option indicates whether to perform conventional DNSSEC validation, and if so, specifies the name of a trust anchor. The default is to validate using a trust anchor of "." (the root zone), for which there is a built\-in key. If specifying a different trust anchor, then \fB\-a\fP must be used to specify a file containing the key. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]tcp\fP +.B +[no]tcp This option controls whether to use TCP when sending queries. The default is to use UDP unless a truncated response has been received. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]unknownformat\fP +.B +[no]unknownformat This option prints all RDATA in unknown RR\-type presentation format (\fI\%RFC 3597\fP). The default is to print RDATA for known types in the type\(aqs presentation format. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]yaml\fP +.B +[no]yaml This option prints response data in YAML format. .UNINDENT .SH FILES diff --git a/doc/man/dig.1in b/doc/man/dig.1in index ab8f59dddd..61c97248a3 100644 --- a/doc/man/dig.1in +++ b/doc/man/dig.1in @@ -86,7 +86,7 @@ dig @server name type where: .INDENT 0.0 .TP -.B \fBserver\fP +.B server is the name or IP address of the name server to query. This can be an IPv4 address in dotted\-decimal notation or an IPv6 address in colon\-delimited notation. When the supplied \fBserver\fP argument is a @@ -100,11 +100,15 @@ options are in use, then only addresses for the corresponding transport are tried. If no usable addresses are found, \fBdig\fP sends the query to the local host. The reply from the name server that responds is displayed. +.UNINDENT +.INDENT 0.0 .TP -.B \fBname\fP +.B name is the name of the resource record that is to be looked up. +.UNINDENT +.INDENT 0.0 .TP -.B \fBtype\fP +.B type indicates what type of query is required \- ANY, A, MX, SIG, etc. \fBtype\fP can be any valid query type. If no \fBtype\fP argument is supplied, \fBdig\fP performs a lookup for an A record. @@ -112,53 +116,73 @@ supplied, \fBdig\fP performs a lookup for an A record. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-4\fP +.B \-4 This option indicates that only IPv4 should be used. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-6\fP +.B \-6 This option indicates that only IPv6 should be used. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-b address[#port]\fP +.B \-b address[#port] This option sets the source IP address of the query. The \fBaddress\fP must be a valid address on one of the host\(aqs network interfaces, or "0.0.0.0" or "::". An optional port may be specified by appending \fB#port\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option sets the query class. The default \fBclass\fP is IN; other classes are HS for Hesiod records or CH for Chaosnet records. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-f file\fP +.B \-f file This option sets batch mode, in which \fBdig\fP reads a list of lookup requests to process from the given \fBfile\fP\&. Each line in the file should be organized in the same way it would be presented as a query to \fBdig\fP using the command\-line interface. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k keyfile\fP +.B \-k keyfile This option tells \fBnamed\fP to sign queries using TSIG using a key read from the given file. Key files can be generated using \fBtsig\-keygen\fP\&. When using TSIG authentication with \fBdig\fP, 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 \fBkey\fP and \fBserver\fP statements in \fBnamed.conf\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-m\fP +.B \-m This option enables memory usage debugging. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p port\fP +.B \-p port This option sends the query to a non\-standard port on the server, instead of the default port 53. This option is used to test a name server that has been configured to listen for queries on a non\-standard port number. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-q name\fP +.B \-q name This option specifies the domain name to query. This is useful to distinguish the \fBname\fP from other arguments. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-r\fP +.B \-r This option indicates that options from \fB${HOME}/.digrc\fP should not be read. This is useful for scripts that need predictable behavior. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t type\fP +.B \-t type This option indicates the resource record type to query, which can be any valid query type. If it is a resource record type supported in BIND 9, it can be given by the type mnemonic (such as \fBNS\fP or \fBAAAA\fP). The default query type is @@ -172,14 +196,20 @@ SOA record was \fBN\fP\&. All resource record types can be expressed as \fBTYPEnn\fP, where \fBnn\fP is the number of the type. If the resource record type is not supported in BIND 9, the result is displayed as described in \fI\%RFC 3597\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-u\fP +.B \-u This option indicates that print query times should be provided in microseconds instead of milliseconds. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v\fP +.B \-v This option prints the version number and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-x addr\fP +.B \-x addr This option sets simplified reverse lookups, for mapping addresses to names. The \fBaddr\fP is an IPv4 address in dotted\-decimal notation, or a colon\-delimited IPv6 address. When the \fB\-x\fP option is used, there is no @@ -188,8 +218,10 @@ need to provide the \fBname\fP, \fBclass\fP, and \fBtype\fP arguments. \fB94.2.0.192.in\-addr.arpa\fP and sets the query type and class to PTR and IN respectively. IPv6 addresses are looked up using nibble format under the IP6.ARPA domain. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-y [hmac:]keyname:secret\fP +.B \-y [hmac:]keyname:secret This option signs queries using TSIG with the given authentication key. \fBkeyname\fP is the name of the key, and \fBsecret\fP is the base64\-encoded shared secret. \fBhmac\fP is the name of the key algorithm; @@ -225,17 +257,23 @@ abbreviation is unambiguous; for example, \fB+cd\fP is equivalent to \fB+cdflag\fP\&. The query options are: .INDENT 0.0 .TP -.B \fB+[no]aaflag\fP +.B +[no]aaflag This option is a synonym for \fB+[no]aaonly\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]aaonly\fP +.B +[no]aaonly This option sets the \fBaa\fP flag in the query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]additional\fP +.B +[no]additional This option displays [or does not display] the additional section of a reply. The default is to display it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]adflag\fP +.B +[no]adflag This option sets [or does not set] the AD (authentic data) bit in the query. This requests the server to return whether all of the answer and authority sections have been validated as secure, according to the security @@ -243,45 +281,65 @@ policy of the server. \fBAD=1\fP indicates that all records have been validated as secure and the answer is not from a OPT\-OUT range. \fBAD=0\fP indicates that some part of the answer was insecure or not validated. This bit is set by default. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]all\fP +.B +[no]all This option sets or clears all display flags. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]answer\fP +.B +[no]answer This option displays [or does not display] the answer section of a reply. The default is to display it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]authority\fP +.B +[no]authority This option displays [or does not display] the authority section of a reply. The default is to display it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]badcookie\fP +.B +[no]badcookie This option retries the lookup with a new server cookie if a BADCOOKIE response is received. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]besteffort\fP +.B +[no]besteffort This option attempts to display the contents of messages which are malformed. The default is to not display malformed answers. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+bufsize[=B]\fP +.B +bufsize[=B] This option sets the UDP message buffer size advertised using EDNS0 to \fBB\fP bytes. The maximum and minimum sizes of this buffer are 65535 and 0, respectively. \fB+bufsize\fP restores the default buffer size. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]cdflag\fP +.B +[no]cdflag This option sets [or does not set] the CD (checking disabled) bit in the query. This requests the server to not perform DNSSEC validation of responses. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]class\fP +.B +[no]class This option displays [or does not display] the CLASS when printing the record. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]cmd\fP +.B +[no]cmd This option toggles the printing of the initial comment in the output, identifying the version of \fBdig\fP and the query options that have been applied. This option always has a global effect; it cannot be set globally and then overridden on a per\-lookup basis. The default is to print this comment. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]comments\fP +.B +[no]comments This option toggles the display of some comment lines in the output, with information about the packet header and OPT pseudosection, and the names of the response section. The default is to print these comments. @@ -289,79 +347,109 @@ the response section. The default is to print these comments. Other types of comments in the output are not affected by this option, but can be controlled using other command\-line switches. These include \fB+[no]cmd\fP, \fB+[no]question\fP, \fB+[no]stats\fP, and \fB+[no]rrcomments\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]cookie=####\fP +.B +[no]cookie=#### This option sends [or does not send] a COOKIE EDNS option, with an optional value. Replaying a COOKIE from a previous response allows the server to identify a previous client. The default is \fB+cookie\fP\&. .sp \fB+cookie\fP is also set when \fB+trace\fP is set to better emulate the default queries from a nameserver. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]crypto\fP +.B +[no]crypto This option toggles the display of cryptographic fields in DNSSEC records. The contents of these fields are unnecessary for debugging most DNSSEC validation failures and removing them makes it easier to see the common failures. The default is to display the fields. When omitted, they are replaced by the string \fB[omitted]\fP or, in the DNSKEY case, the key ID is displayed as the replacement, e.g. \fB[ key id = value ]\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]defname\fP +.B +[no]defname This option, which is deprecated, is treated as a synonym for \fB+[no]search\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]dns64prefix\fP +.B +[no]dns64prefix Lookup IPV4ONLY.ARPA AAAA and print any DNS64 prefixes found. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]dnssec\fP +.B +[no]dnssec This option requests that DNSSEC records be sent by setting the DNSSEC OK (DO) bit in the OPT record in the additional section of the query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+domain=somename\fP +.B +domain=somename This option sets the search list to contain the single domain \fBsomename\fP, as if specified in a \fBdomain\fP directive in \fB/etc/resolv.conf\fP, and enables search list processing as if the \fB+search\fP option were given. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+dscp=value\fP +.B +dscp=value This option sets the DSCP code point to be used when sending the query. Valid DSCP code points are in the range [0...63]. By default no code point is explicitly set. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]edns[=#]\fP +.B +[no]edns[=#] This option specifies the EDNS version to query with. Valid values are 0 to 255. Setting the EDNS version causes an EDNS query to be sent. \fB+noedns\fP clears the remembered EDNS version. EDNS is set to 0 by default. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ednsflags[=#]\fP +.B +[no]ednsflags[=#] This option sets the must\-be\-zero EDNS flags bits (Z bits) to the specified value. Decimal, hex, and octal encodings are accepted. Setting a named flag (e.g., DO) is silently ignored. By default, no Z bits are set. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ednsnegotiation\fP +.B +[no]ednsnegotiation This option enables/disables EDNS version negotiation. By default, EDNS version negotiation is enabled. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ednsopt[=code[:value]]\fP +.B +[no]ednsopt[=code[:value]] This option specifies the EDNS option with code point \fBcode\fP and an optional payload of \fBvalue\fP as a hexadecimal string. \fBcode\fP can be either an EDNS option name (for example, \fBNSID\fP or \fBECS\fP) or an arbitrary numeric value. \fB+noednsopt\fP clears the EDNS options to be sent. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]expire\fP +.B +[no]expire This option sends an EDNS Expire option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]fail\fP +.B +[no]fail This option indicates that \fBnamed\fP 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. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]header\-only\fP +.B +[no]header\-only This option sends a query with a DNS header without a question section. The default is to add a question section. The query type and query name are ignored when this is set. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]https[=value]\fP +.B +[no]https[=value] This option indicates whether to use DNS over HTTPS (DoH) when querying name servers. When this option is in use, the port number defaults to 443. The HTTP POST request mode is used when sending the query. @@ -369,65 +457,91 @@ The HTTP POST request mode is used when sending the query. If \fBvalue\fP is specified, it will be used as the HTTP endpoint in the query URI; the default is \fB/dns\-query\fP\&. So, for example, \fBdig @example.com +https\fP will use the URI \fBhttps://example.com/dns\-query\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]https\-get[=value]\fP +.B +[no]https\-get[=value] Similar to \fB+https\fP, except that the HTTP GET request mode is used when sending the query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]https\-post[=value]\fP +.B +[no]https\-post[=value] Same as \fB+https\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]http\-plain[=value]\fP +.B +[no]http\-plain[=value] Similar to \fB+https\fP, except that HTTP queries will be sent over a non\-encrypted channel. When this option is in use, the port number defaults to 80 and the HTTP request mode is POST. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]http\-plain\-get[=value]\fP +.B +[no]http\-plain\-get[=value] Similar to \fB+http\-plain\fP, except that the HTTP request mode is GET. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]http\-plain\-post[=value]\fP +.B +[no]http\-plain\-post[=value] Same as \fB+http\-plain\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]identify\fP +.B +[no]identify This option shows [or does not show] the IP address and port number that supplied the answer, when the \fB+short\fP option is enabled. If short form answers are requested, the default is not to show the source address and port number of the server that provided the answer. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]idnin\fP +.B +[no]idnin This option processes [or does not process] IDN domain names on input. This requires \fBIDN SUPPORT\fP to have been enabled at compile time. .sp The default is to process IDN input when standard output is a tty. The IDN processing on input is disabled when \fBdig\fP output is redirected to files, pipes, and other non\-tty file descriptors. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]idnout\fP +.B +[no]idnout This option converts [or does not convert] puny code on output. This requires \fBIDN SUPPORT\fP to have been enabled at compile time. .sp The default is to process puny code on output when standard output is a tty. The puny code processing on output is disabled when \fBdig\fP output is redirected to files, pipes, and other non\-tty file descriptors. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ignore\fP +.B +[no]ignore This option ignores [or does not ignore] truncation in UDP responses instead of retrying with TCP. By default, TCP retries are performed. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]keepalive\fP +.B +[no]keepalive This option sends [or does not send] an EDNS Keepalive option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]keepopen\fP +.B +[no]keepopen This option keeps [or does not keep] the TCP socket open between queries, and reuses it rather than creating a new TCP socket for each lookup. The default is \fB+nokeepopen\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]multiline\fP +.B +[no]multiline This option prints [or does not print] records, like the SOA records, in a verbose multi\-line format with human\-readable comments. The default is to print each record on a single line to facilitate machine parsing of the \fBdig\fP output. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+ndots=D\fP +.B +ndots=D This option sets the number of dots (\fBD\fP) that must appear in \fBname\fP for it to be considered absolute. The default value is that defined using the \fBndots\fP statement in \fB/etc/resolv.conf\fP, or 1 if no \fBndots\fP @@ -435,25 +549,35 @@ statement is present. Names with fewer dots are interpreted as relative names, and are searched for in the domains listed in the \fBsearch\fP or \fBdomain\fP directive in \fB/etc/resolv.conf\fP if \fB+search\fP is set. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]nsid\fP +.B +[no]nsid When enabled, this option includes an EDNS name server ID request when sending a query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]nssearch\fP +.B +[no]nssearch When this option is set, \fBdig\fP attempts to find the authoritative name servers for the zone containing the name being looked up, and display the SOA record that each name server has for the zone. Addresses of servers that did not respond are also printed. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]onesoa\fP +.B +[no]onesoa When enabled, this option prints only one (starting) SOA record when performing an AXFR. The default is to print both the starting and ending SOA records. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]opcode=value\fP +.B +[no]opcode=value When enabled, this option sets (restores) the DNS message opcode to the specified value. The default value is QUERY (0). +.UNINDENT +.INDENT 0.0 .TP -.B \fB+padding=value\fP +.B +padding=value This option pads the size of the query packet using the EDNS Padding option to blocks of \fBvalue\fP bytes. For example, \fB+padding=32\fP causes a 48\-byte query to be padded to 64 bytes. The default block size is 0, @@ -461,43 +585,61 @@ which disables padding; the maximum is 512. Values are ordinarily expected to be powers of two, such as 128; however, this is not mandatory. Responses to padded queries may also be padded, but only if the query uses TCP or DNS COOKIE. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+qid=value\fP +.B +qid=value This option specifies the query ID to use when sending queries. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]qr\fP +.B +[no]qr This option toggles the display of the query message as it is sent. By default, the query is not printed. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]question\fP +.B +[no]question This option toggles the display of the question section of a query when an answer is returned. The default is to print the question section as a comment. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]raflag\fP +.B +[no]raflag This option sets [or does not set] the RA (Recursion Available) bit in the query. The default is \fB+noraflag\fP\&. This bit is ignored by the server for QUERY. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]rdflag\fP +.B +[no]rdflag This option is a synonym for \fB+[no]recurse\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]recurse\fP +.B +[no]recurse This option toggles the setting of the RD (recursion desired) bit in the query. This bit is set by default, which means \fBdig\fP normally sends recursive queries. Recursion is automatically disabled when the \fB+nssearch\fP or \fB+trace\fP query option is used. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+retry=T\fP +.B +retry=T This option sets the number of times to retry UDP and TCP queries to server to \fBT\fP instead of the default, 2. Unlike \fB+tries\fP, this does not include the initial query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]rrcomments\fP +.B +[no]rrcomments This option toggles the display of per\-record comments in the output (for example, human\-readable key information about DNSKEY records). The default is not to print record comments unless multiline mode is active. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]search\fP +.B +[no]search This option uses [or does not use] the search list defined by the searchlist or domain directive in \fBresolv.conf\fP, if any. The search list is not used by default. @@ -505,37 +647,51 @@ default. \fBndots\fP from \fBresolv.conf\fP (default 1), which may be overridden by \fB+ndots\fP, determines whether the name is treated as relative and hence whether a search is eventually performed. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]short\fP +.B +[no]short This option toggles whether a terse answer is provided. The default is to print the answer in a verbose form. This option always has a global effect; it cannot be set globally and then overridden on a per\-lookup basis. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]showbadcookie\fP +.B +[no]showbadcookie This option toggles whether to show the message containing the BADCOOKIE rcode before retrying the request or not. The default is to not show the messages. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]showsearch\fP +.B +[no]showsearch This option performs [or does not perform] a search showing intermediate results. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]sigchase\fP +.B +[no]sigchase This feature is now obsolete and has been removed; use \fBdelv\fP instead. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+split=W\fP +.B +split=W This option splits long hex\- or base64\-formatted fields in resource records into chunks of \fBW\fP characters (where \fBW\fP is rounded up to the nearest multiple of 4). \fB+nosplit\fP or \fB+split=0\fP causes fields not to be split at all. The default is 56 characters, or 44 characters when multiline mode is active. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]stats\fP +.B +[no]stats This option toggles the printing of statistics: when the query was made, the size of the reply, etc. The default behavior is to print the query statistics as a comment after each lookup. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]subnet=addr[/prefix\-length]\fP +.B +[no]subnet=addr[/prefix\-length] This option sends [or does not send] an EDNS CLIENT\-SUBNET option with the specified IP address or network prefix. .sp @@ -543,31 +699,43 @@ address or network prefix. sends an EDNS CLIENT\-SUBNET option with an empty address and a source prefix\-length of zero, which signals a resolver that the client\(aqs address information must \fInot\fP be used when resolving this query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]tcflag\fP +.B +[no]tcflag This option sets [or does not set] the TC (TrunCation) bit in the query. The default is \fB+notcflag\fP\&. This bit is ignored by the server for QUERY. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]tcp\fP +.B +[no]tcp This option indicates whether to use TCP when querying name servers. The default behavior is to use UDP unless a type \fBany\fP or \fBixfr=N\fP query is requested, in which case the default is TCP. AXFR queries always use TCP. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+timeout=T\fP +.B +timeout=T This option sets the timeout for a query to \fBT\fP seconds. The default timeout is 5 seconds. An attempt to set \fBT\fP to less than 1 is silently set to 1. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]tls\fP +.B +[no]tls This option indicates whether to use DNS over TLS (DoT) when querying name servers. When this option is in use, the port number defaults to 853. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]topdown\fP +.B +[no]topdown This feature is related to \fBdig +sigchase\fP, which is obsolete and has been removed. Use \fBdelv\fP instead. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]trace\fP +.B +[no]trace This option toggles tracing of the delegation path from the root name servers for the name being looked up. Tracing is disabled by default. When tracing is enabled, \fBdig\fP makes iterative queries to resolve the @@ -580,39 +748,55 @@ the root zone name servers. .sp \fB+dnssec\fP is also set when \fB+trace\fP is set, to better emulate the default queries from a name server. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+tries=T\fP +.B +tries=T This option sets the number of times to try UDP and TCP queries to server to \fBT\fP instead of the default, 3. If \fBT\fP is less than or equal to zero, the number of tries is silently rounded up to 1. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+trusted\-key=####\fP +.B +trusted\-key=#### This option formerly specified trusted keys for use with \fBdig +sigchase\fP\&. This feature is now obsolete and has been removed; use \fBdelv\fP instead. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ttlid\fP +.B +[no]ttlid This option displays [or does not display] the TTL when printing the record. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ttlunits\fP +.B +[no]ttlunits This option displays [or does not display] the TTL in friendly human\-readable time units of \fBs\fP, \fBm\fP, \fBh\fP, \fBd\fP, and \fBw\fP, representing seconds, minutes, hours, days, and weeks. This implies \fB+ttlid\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]unknownformat\fP +.B +[no]unknownformat This option prints all RDATA in unknown RR type presentation format (\fI\%RFC 3597\fP). The default is to print RDATA for known types in the type\(aqs presentation format. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]vc\fP +.B +[no]vc This option uses [or does not use] TCP when querying name servers. This alternate syntax to \fB+[no]tcp\fP is provided for backwards compatibility. The \fBvc\fP stands for "virtual circuit." +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]yaml\fP +.B +[no]yaml When enabled, this option prints the responses (and, if \fB+qr\fP is in use, also the outgoing queries) in a detailed YAML format. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]zflag\fP +.B +[no]zflag This option sets [or does not set] the last unassigned DNS header flag in a DNS query. This flag is off by default. .UNINDENT diff --git a/doc/man/dnssec-cds.1in b/doc/man/dnssec-cds.1in index a7b097f182..a06a8fffdd 100644 --- a/doc/man/dnssec-cds.1in +++ b/doc/man/dnssec-cds.1in @@ -85,7 +85,7 @@ maintain a \fBdsset\-\fP file as well as emit an \fBnsupdate\fP script. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-a algorithm\fP +.B \-a algorithm When converting CDS records to DS records, this option specifies the acceptable digest algorithms. This option can be repeated, so that multiple digest types are allowed. If none of the CDS records @@ -99,16 +99,22 @@ are created for each CDNSKEY records. The algorithm must be one of SHA\-1, SHA\-256, or SHA\-384. These values are case\-insensitive, and the hyphen may be omitted. If no algorithm is specified, the default is SHA\-256 only. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option specifies the DNS class of the zones. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D\fP +.B \-D This option generates DS records from CDNSKEY records if both CDS and CDNSKEY records are present in the child zone. By default CDS records are preferred. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-d path\fP +.B \-d path This specifies the location of the parent DS records. The path can be the name of a file containing the DS records; if it is a directory, \fBdnssec\-cds\fP looks for a \fBdsset\-\fP file for the domain inside the directory. @@ -116,15 +122,19 @@ looks for a \fBdsset\-\fP file for the domain inside the directory. To protect against replay attacks, child records are rejected if they were signed earlier than the modification time of the \fBdsset\-\fP file. This can be adjusted with the \fB\-s\fP option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-f child\-file\fP +.B \-f child\-file This option specifies the file containing the child\(aqs CDS and/or CDNSKEY records, plus its DNSKEY records and the covering RRSIG records, so that they can be authenticated. .sp The examples below describe how to generate this file. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-iextension\fP +.B \-iextension This option updates the \fBdsset\-\fP file in place, instead of writing DS records to the standard output. .sp @@ -137,8 +147,10 @@ To protect against replay attacks, the modification time of the \fBdsset\-\fP file is set to match the signature inception time of the child records, provided that it is later than the file\(aqs current modification time. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s start\-time\fP +.B \-s start\-time This option specifies the date and time after which RRSIG records become acceptable. This can be either an absolute or a relative time. An absolute start time is indicated by a number in YYYYMMDDHHMMSS @@ -149,13 +161,17 @@ current time is indicated with \fBnow+N\fP\&. .sp If no start\-time is specified, the modification time of the \fBdsset\-\fP file is used. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-T ttl\fP +.B \-T ttl This option specifies a TTL to be used for new DS records. If not specified, the default is the TTL of the old DS records. If they had no explicit TTL, the new DS records also have no explicit TTL. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-u\fP +.B \-u This option writes an \fBnsupdate\fP script to the standard output, instead of printing the new DS reords. The output is empty if no change is needed. @@ -163,13 +179,19 @@ needed. Note: The TTL of new records needs to be specified: it can be done in the original \fBdsset\-\fP file, with the \fB\-T\fP option, or using the \fBnsupdate\fP \fBttl\fP command. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints version information. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v level\fP +.B \-v level This option sets the debugging level. Level 1 is intended to be usefully verbose for general users; higher levels are intended for developers. +.UNINDENT +.INDENT 0.0 .TP .B \fBdomain\fP This indicates the name of the delegation point/child zone apex. diff --git a/doc/man/dnssec-dsfromkey.1in b/doc/man/dnssec-dsfromkey.1in index 2394f75a1b..12668866c9 100644 --- a/doc/man/dnssec-dsfromkey.1in +++ b/doc/man/dnssec-dsfromkey.1in @@ -61,13 +61,17 @@ as generated by \fBdnssec\-keygen\fP \fB\-C\fP\&. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-1\fP +.B \-1 This option is an abbreviation for \fB\-a SHA1\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-2\fP +.B \-2 This option is an abbreviation for \fB\-a SHA\-256\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-a algorithm\fP +.B \-a algorithm This option specifies a digest algorithm to use when converting DNSKEY records to DS records. This option can be repeated, so that multiple DS records are created for each DNSKEY record. @@ -75,20 +79,28 @@ are created for each DNSKEY record. The algorithm must be one of SHA\-1, SHA\-256, or SHA\-384. These values are case\-insensitive, and the hyphen may be omitted. If no algorithm is specified, the default is SHA\-256. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-A\fP +.B \-A This option indicates that ZSKs are to be included when generating DS records. Without this option, only keys which have the KSK flag set are converted to DS records and printed. This option is only useful in \fB\-f\fP zone file mode. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option specifies the DNS class; the default is IN. This option is only useful in \fB\-s\fP keyset or \fB\-f\fP zone file mode. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-C\fP +.B \-C This option generates CDS records rather than DS records. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-f file\fP +.B \-f file This option sets zone file mode, in which the final dnsname argument of \fBdnssec\-dsfromkey\fP is the DNS domain name of a zone whose master file can be read from \fBfile\fP\&. If the zone name is the same as \fBfile\fP, then it may be @@ -99,24 +111,36 @@ input. This makes it possible to use the output of the \fBdig\fP command as input, as in: .sp \fBdig dnskey example.com | dnssec\-dsfromkey \-f \- example.com\fP +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints usage information. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-K directory\fP +.B \-K directory This option tells BIND 9 to look for key files or \fBkeyset\-\fP files in \fBdirectory\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s\fP +.B \-s This option enables keyset mode, in which the final dnsname argument from \fBdnssec\-dsfromkey\fP is the DNS domain name used to locate a \fBkeyset\-\fP file. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-T TTL\fP +.B \-T TTL This option specifies the TTL of the DS records. By default the TTL is omitted. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v level\fP +.B \-v level This option sets the debugging level. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints version information. .UNINDENT .SH EXAMPLE diff --git a/doc/man/dnssec-importkey.1in b/doc/man/dnssec-importkey.1in index 22d85f36d8..29ddda79ee 100644 --- a/doc/man/dnssec-importkey.1in +++ b/doc/man/dnssec-importkey.1in @@ -51,7 +51,7 @@ DNSKEY RRset on schedule even if the true private key is stored offline. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-f filename\fP +.B \-f filename This option indicates the zone file mode. Instead of a public keyfile name, the argument is the DNS domain name of a zone master file, which can be read from \fBfilename\fP\&. If the domain name is the same as \fBfilename\fP, then it may be @@ -59,24 +59,34 @@ omitted. .sp If \fBfilename\fP is set to \fB"\-"\fP, then the zone data is read from the standard input. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-K directory\fP +.B \-K directory This option sets the directory in which the key files are to reside. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-L ttl\fP +.B \-L ttl This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in place, in which case the existing TTL takes precedence. Setting the default TTL to \fB0\fP or \fBnone\fP removes it from the key. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option emits a usage message and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v level\fP +.B \-v level This option sets the debugging level. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints version information. .UNINDENT .SH TIMING OPTIONS @@ -91,21 +101,27 @@ respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&. .INDENT 0.0 .TP -.B \fB\-P date/offset\fP +.B \-P date/offset This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-P sync date/offset\fP +.B \-P sync date/offset This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D date/offset\fP +.B \-D date/offset This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.) +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D sync date/offset\fP +.B \-D sync date/offset This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted. .UNINDENT diff --git a/doc/man/dnssec-keyfromlabel.1in b/doc/man/dnssec-keyfromlabel.1in index 22ad8cec0c..cc9aab63e0 100644 --- a/doc/man/dnssec-keyfromlabel.1in +++ b/doc/man/dnssec-keyfromlabel.1in @@ -47,7 +47,7 @@ match the name of the zone for which the key is being generated. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-a algorithm\fP +.B \-a algorithm This option selects the cryptographic algorithm. The value of \fBalgorithm\fP must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. @@ -66,64 +66,88 @@ option, then NSEC3RSASHA1 is used instead. Since BIND 9.12.0, this option is mandatory except when using the \fB\-S\fP option, which copies the algorithm from the predecessory key. Previously, the default for newly generated keys was RSASHA1. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-3\fP +.B \-3 This option uses an NSEC3\-capable algorithm to generate a DNSSEC key. If this option is used with an algorithm that has both NSEC and NSEC3 versions, then the NSEC3 version is used; for example, \fBdnssec\-keygen \-3a RSASHA1\fP specifies the NSEC3RSASHA1 algorithm. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-E engine\fP +.B \-E engine This option specifies the cryptographic hardware to use. .sp When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-l label\fP +.B \-l label This option specifies the label for a key pair in the crypto hardware. .sp When BIND 9 is built with OpenSSL\-based PKCS#11 support, the label is an arbitrary string that identifies a particular key. It may be preceded by an optional OpenSSL engine name, followed by a colon, as in \fBpkcs11:keylabel\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-n nametype\fP +.B \-n nametype This option specifies the owner type of the key. The value of \fBnametype\fP must either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host (KEY)), USER (for a key associated with a user (KEY)), or OTHER (DNSKEY). These values are case\-insensitive. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-C\fP +.B \-C This option enables compatibility mode, which generates an old\-style key, without any metadata. By default, \fBdnssec\-keyfromlabel\fP includes the key\(aqs creation date in the metadata stored with the private key; other dates may be set there as well, including publication date, activation date, etc. Keys that include this data may be incompatible with older versions of BIND; the \fB\-C\fP option suppresses them. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option indicates that the DNS record containing the key should have the specified class. If not specified, class IN is used. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-f flag\fP +.B \-f flag This option sets the specified flag in the \fBflag\fP field of the KEY/DNSKEY record. The only recognized flags are KSK (Key\-Signing Key) and REVOKE. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-G\fP +.B \-G This option generates a key, but does not publish it or sign with it. This option is incompatible with \fB\-P\fP and \fB\-A\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints a short summary of the options and arguments to \fBdnssec\-keyfromlabel\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-K directory\fP +.B \-K directory This option sets the directory in which the key files are to be written. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k\fP +.B \-k This option generates KEY records rather than DNSKEY records. +.UNINDENT +.INDENT 0.0 .TP .B \fB\-L\fP ttl This option sets the default TTL to use for this key when it is converted into a @@ -131,33 +155,45 @@ DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in place, in which case the existing TTL would take precedence. Setting the default TTL to \fB0\fP or \fBnone\fP removes it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p protocol\fP +.B \-p protocol This option sets the protocol value for the key. The protocol is a number between 0 and 255. The default is 3 (DNSSEC). Other possible values for this argument are listed in \fI\%RFC 2535\fP and its successors. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-S key\fP +.B \-S key This option generates a key as an explicit successor to an existing key. The name, algorithm, size, and type of the key are set to match the predecessor. The activation date of the new key is set to the inactivation date of the existing one. The publication date is set to the activation date minus the prepublication interval, which defaults to 30 days. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t type\fP +.B \-t type This option indicates the type of the key. \fBtype\fP must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers to the ability to authenticate data, and CONF to the ability to encrypt data. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v level\fP +.B \-v level This option sets the debugging level. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints version information. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-y\fP +.B \-y This option allows DNSSEC key files to be generated even if the key ID would collide with that of an existing key, in the event of either key being revoked. (This is only safe to enable if @@ -176,41 +212,55 @@ respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&. .INDENT 0.0 .TP -.B \fB\-P date/offset\fP +.B \-P date/offset This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it. If not set, and if the \fB\-G\fP option has not been used, the default is the current date. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-P sync date/offset\fP +.B \-P sync date/offset This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-A date/offset\fP +.B \-A date/offset This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. If not set, and if the \fB\-G\fP option has not been used, the default is the current date. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-R date/offset\fP +.B \-R date/offset This option sets the date on which the key is to be revoked. After that date, the key is flagged as revoked. It is included in the zone and is used to sign it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-I date/offset\fP +.B \-I date/offset This option sets the date on which the key is to be retired. After that date, the key is still included in the zone, but it is not used to sign it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D date/offset\fP +.B \-D date/offset This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.) +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D sync date/offset\fP +.B \-D sync date/offset This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-i interval\fP +.B \-i interval This option sets the prepublication interval for a key. If set, then the publication and activation dates must be separated by at least this much time. If the activation date is specified but the publication diff --git a/doc/man/dnssec-keygen.1in b/doc/man/dnssec-keygen.1in index 5b96ab25bd..55f1e9a987 100644 --- a/doc/man/dnssec-keygen.1in +++ b/doc/man/dnssec-keygen.1in @@ -46,13 +46,15 @@ generated. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-3\fP +.B \-3 This option uses an NSEC3\-capable algorithm to generate a DNSSEC key. If this option is used with an algorithm that has both NSEC and NSEC3 versions, then the NSEC3 version is selected; for example, \fBdnssec\-keygen \-3a RSASHA1\fP specifies the NSEC3RSASHA1 algorithm. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-a algorithm\fP +.B \-a algorithm This option selects the cryptographic algorithm. For DNSSEC keys, the value of \fBalgorithm\fP must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. For @@ -70,8 +72,10 @@ option, which copies the algorithm from the predecessor key. In prior releases, HMAC algorithms could be generated for use as TSIG keys, but that feature was removed in BIND 9.13.0. Use \fBtsig\-keygen\fP to generate TSIG keys. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-b keysize\fP +.B \-b keysize This option specifies the number of bits in the key. The choice of key size depends on the algorithm used: RSA keys must be between 1024 and 4096 bits; Diffie\-Hellman keys must be between 128 and 4096 bits. Elliptic @@ -81,53 +85,73 @@ If the key size is not specified, some algorithms have pre\-defined defaults. For example, RSA keys for use as DNSSEC zone\-signing keys have a default size of 1024 bits; RSA keys for use as key\-signing keys (KSKs, generated with \fB\-f KSK\fP) default to 2048 bits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-C\fP +.B \-C This option enables compatibility mode, which generates an old\-style key, without any timing metadata. By default, \fBdnssec\-keygen\fP includes the key\(aqs creation date in the metadata stored with the private key; other dates may be set there as well, including publication date, activation date, etc. Keys that include this data may be incompatible with older versions of BIND; the \fB\-C\fP option suppresses them. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option indicates that the DNS record containing the key should have the specified class. If not specified, class IN is used. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-d bits\fP +.B \-d bits This option specifies the key size in bits. For the algorithms RSASHA1, NSEC3RSASA1, RSASHA256, and RSASHA512 the key size must be between 1024 and 4096 bits; DH size is between 128 and 4096 bits. This option is ignored for algorithms ECDSAP256SHA256, ECDSAP384SHA384, ED25519, and ED448. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-E engine\fP +.B \-E engine This option specifies the cryptographic hardware to use, when applicable. .sp When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-f flag\fP +.B \-f flag This option sets the specified flag in the flag field of the KEY/DNSKEY record. The only recognized flags are KSK (Key\-Signing Key) and REVOKE. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-G\fP +.B \-G This option generates a key, but does not publish it or sign with it. This option is incompatible with \fB\-P\fP and \fB\-A\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-g generator\fP +.B \-g generator This option indicates the generator to use if generating a Diffie\-Hellman key. Allowed values are 2 and 5. If no generator is specified, a known prime from \fI\%RFC 2539\fP is used if possible; otherwise the default is 2. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints a short summary of the options and arguments to \fBdnssec\-keygen\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-K directory\fP +.B \-K directory This option sets the directory in which the key files are to be written. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k policy\fP +.B \-k policy This option creates keys for a specific \fBdnssec\-policy\fP\&. If a policy uses multiple keys, \fBdnssec\-keygen\fP generates multiple keys. This also creates a ".state" file to keep track of the key state. @@ -135,8 +159,10 @@ creates a ".state" file to keep track of the key state. This option creates keys according to the \fBdnssec\-policy\fP configuration, hence it cannot be used at the same time as many of the other options that \fBdnssec\-keygen\fP provides. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-L ttl\fP +.B \-L ttl This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in @@ -144,25 +170,33 @@ place, in which case the existing TTL takes precedence. If this value is not set and there is no existing DNSKEY RRset, the TTL defaults to the SOA TTL. Setting the default TTL to \fB0\fP or \fBnone\fP is the same as leaving it unset. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-l file\fP +.B \-l file This option provides a configuration file that contains a \fBdnssec\-policy\fP statement (matching the policy set with \fB\-k\fP). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-n nametype\fP +.B \-n nametype This option specifies the owner type of the key. The value of \fBnametype\fP must either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY (for a key associated with a host (KEY)), USER (for a key associated with a user (KEY)), or OTHER (DNSKEY). These values are case\-insensitive. The default is ZONE for DNSKEY generation. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p protocol\fP +.B \-p protocol This option sets the protocol value for the generated key, for use with \fB\-T KEY\fP\&. The protocol is a number between 0 and 255. The default is 3 (DNSSEC). Other possible values for this argument are listed in \fI\%RFC 2535\fP and its successors. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-q\fP +.B \-q This option sets quiet mode, which suppresses unnecessary output, including progress indication. Without this option, when \fBdnssec\-keygen\fP is run interactively to generate an RSA or DSA key pair, it prints a @@ -171,35 +205,47 @@ generation. A \fB\&.\fP indicates that a random number has been found which passed an initial sieve test; \fB+\fP means a number has passed a single round of the Miller\-Rabin primality test; and a space ( ) means that the number has passed all the tests and is a satisfactory key. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-S key\fP +.B \-S key This option creates a new key which is an explicit successor to an existing key. The name, algorithm, size, and type of the key are set to match the existing key. The activation date of the new key is set to the inactivation date of the existing one. The publication date is set to the activation date minus the prepublication interval, which defaults to 30 days. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s strength\fP +.B \-s strength This option specifies the strength value of the key. The strength is a number between 0 and 15, and currently has no defined purpose in DNSSEC. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-T rrtype\fP +.B \-T rrtype This option specifies the resource record type to use for the key. \fBrrtype\fP must be either DNSKEY or KEY. The default is DNSKEY when using a DNSSEC algorithm, but it can be overridden to KEY for use with SIG(0). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t type\fP +.B \-t type This option indicates the type of the key for use with \fB\-T KEY\fP\&. \fBtype\fP must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers to the ability to authenticate data, and CONF to the ability to encrypt data. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints version information. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v level\fP +.B \-v level This option sets the debugging level. .UNINDENT .SH TIMING OPTIONS @@ -214,43 +260,57 @@ respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&. .INDENT 0.0 .TP -.B \fB\-P date/offset\fP +.B \-P date/offset This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it. If not set, and if the \fB\-G\fP option has not been used, the default is the current date. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-P sync date/offset\fP +.B \-P sync date/offset This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-A date/offset\fP +.B \-A date/offset This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. If not set, and if the \fB\-G\fP option has not been used, the default is the current date. If set, and \fB\-P\fP is not set, the publication date is set to the activation date minus the prepublication interval. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-R date/offset\fP +.B \-R date/offset This option sets the date on which the key is to be revoked. After that date, the key is flagged as revoked. It is included in the zone and is used to sign it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-I date/offset\fP +.B \-I date/offset This option sets the date on which the key is to be retired. After that date, the key is still included in the zone, but it is not used to sign it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D date/offset\fP +.B \-D date/offset This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.) +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D sync date/offset\fP +.B \-D sync date/offset This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-i interval\fP +.B \-i interval This option sets the prepublication interval for a key. If set, then the publication and activation dates must be separated by at least this much time. If the activation date is specified but the publication diff --git a/doc/man/dnssec-revoke.1in b/doc/man/dnssec-revoke.1in index e4910734c9..65bf06a4e0 100644 --- a/doc/man/dnssec-revoke.1in +++ b/doc/man/dnssec-revoke.1in @@ -41,34 +41,48 @@ containing the now\-revoked key. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option emits a usage message and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-K directory\fP +.B \-K directory This option sets the directory in which the key files are to reside. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-r\fP +.B \-r This option indicates to remove the original keyset files after writing the new keyset files. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v level\fP +.B \-v level This option sets the debugging level. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints version information. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-E engine\fP +.B \-E engine This option specifies the cryptographic hardware to use, when applicable. .sp When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-f\fP +.B \-f This option indicates a forced overwrite and causes \fBdnssec\-revoke\fP to write the new key pair, even if a file already exists matching the algorithm and key ID of the revoked key. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-R\fP +.B \-R This option prints the key tag of the key with the REVOKE bit set, but does not revoke the key. .UNINDENT diff --git a/doc/man/dnssec-settime.1in b/doc/man/dnssec-settime.1in index af92c1a9c1..c396220d87 100644 --- a/doc/man/dnssec-settime.1in +++ b/doc/man/dnssec-settime.1in @@ -69,7 +69,7 @@ purposes. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-f\fP +.B \-f This option forces an update of an old\-format key with no metadata fields. Without this option, \fBdnssec\-settime\fP fails when attempting to update a legacy key. With this option, the key is recreated in the new @@ -77,11 +77,15 @@ format, but with the original key data retained. The key\(aqs creation date is set to the present time. If no other values are specified, then the key\(aqs publication and activation dates are also set to the present time. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-K directory\fP +.B \-K directory This option sets the directory in which the key files are to reside. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-L ttl\fP +.B \-L ttl This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in @@ -89,17 +93,25 @@ place, in which case the existing TTL takes precedence. If this value is not set and there is no existing DNSKEY RRset, the TTL defaults to the SOA TTL. Setting the default TTL to \fB0\fP or \fBnone\fP removes it from the key. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option emits a usage message and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints version information. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v level\fP +.B \-v level This option sets the debugging level. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-E engine\fP +.B \-E engine This option specifies the cryptographic hardware to use, when applicable. .sp When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL @@ -118,55 +130,75 @@ respectively. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&. .INDENT 0.0 .TP -.B \fB\-P date/offset\fP +.B \-P date/offset This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used to sign it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-P ds date/offset\fP +.B \-P ds date/offset This option sets the date on which DS records that match this key have been seen in the parent zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-P sync date/offset\fP +.B \-P sync date/offset This option sets the date on which CDS and CDNSKEY records that match this key are to be published to the zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-A date/offset\fP +.B \-A date/offset This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-R date/offset\fP +.B \-R date/offset This option sets the date on which the key is to be revoked. After that date, the key is flagged as revoked. It is included in the zone and is used to sign it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-I date/offset\fP +.B \-I date/offset This option sets the date on which the key is to be retired. After that date, the key is still included in the zone, but it is not used to sign it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D date/offset\fP +.B \-D date/offset This option sets the date on which the key is to be deleted. After that date, the key is no longer included in the zone. (However, it may remain in the key repository.) +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D ds date/offset\fP +.B \-D ds date/offset This option sets the date on which the DS records that match this key have been seen removed from the parent zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D sync date/offset\fP +.B \-D sync date/offset This option sets the date on which the CDS and CDNSKEY records that match this key are to be deleted. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-S predecessor key\fP +.B \-S predecessor key This option selects a key for which the key being modified is an explicit successor. The name, algorithm, size, and type of the predecessor key must exactly match those of the key being modified. The activation date of the successor key is set to the inactivation date of the predecessor. The publication date is set to the activation date minus the prepublication interval, which defaults to 30 days. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-i interval\fP +.B \-i interval This option sets the prepublication interval for a key. If set, then the publication and activation dates must be separated by at least this much time. If the activation date is specified but the publication @@ -193,22 +225,32 @@ purpose, but should never be used in production. Known key states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE. .INDENT 0.0 .TP -.B \fB\-s\fP +.B \-s This option indicates that when setting key timing data, the state file should also be updated. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-g state\fP +.B \-g state This option sets the goal state for this key. Must be HIDDEN or OMNIPRESENT. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-d state date/offset\fP +.B \-d state date/offset This option sets the DS state for this key as of the specified date, offset from the current date. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k state date/offset\fP +.B \-k state date/offset This option sets the DNSKEY state for this key as of the specified date, offset from the current date. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-r state date/offset\fP +.B \-r state date/offset This option sets the RRSIG (KSK) state for this key as of the specified date, offset from the current date. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-z state date/offset\fP +.B \-z state date/offset This option sets the RRSIG (ZSK) state for this key as of the specified date, offset from the current date. .UNINDENT .SH PRINTING OPTIONS @@ -217,10 +259,12 @@ This option sets the RRSIG (ZSK) state for this key as of the specified date, of associated with a key. .INDENT 0.0 .TP -.B \fB\-u\fP +.B \-u This option indicates that times should be printed in Unix epoch format. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all\fP +.B \-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all This option prints a specific metadata value or set of metadata values. The \fB\-p\fP option may be followed by one or more of the following letters or strings to indicate which value or values to print: \fBC\fP for the diff --git a/doc/man/dnssec-signzone.1in b/doc/man/dnssec-signzone.1in index a04e31a7fe..759efd5feb 100644 --- a/doc/man/dnssec-signzone.1in +++ b/doc/man/dnssec-signzone.1in @@ -43,49 +43,67 @@ file for each child zone. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-a\fP +.B \-a This option verifies all generated signatures. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option specifies the DNS class of the zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-C\fP +.B \-C This option sets compatibility mode, in which a \fBkeyset\-zonename\fP file is generated in addition to \fBdsset\-zonename\fP when signing a zone, for use by older versions of \fBdnssec\-signzone\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-d directory\fP +.B \-d directory This option indicates the directory where BIND 9 should look for \fBdsset\-\fP or \fBkeyset\-\fP files. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D\fP +.B \-D This option indicates that only those record types automatically managed by \fBdnssec\-signzone\fP, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output. If smart signing (\fB\-S\fP) is used, DNSKEY records are also included. The resulting file can be included in the original zone file with \fB$INCLUDE\fP\&. This option cannot be combined with \fB\-O raw\fP or serial\-number updating. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-E engine\fP +.B \-E engine This option specifies the hardware to use for cryptographic operations, such as a secure key store used for signing, when applicable. .sp When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-g\fP +.B \-g This option indicates that DS records for child zones should be generated from a \fBdsset\-\fP or \fBkeyset\-\fP file. Existing DS records are removed. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-K directory\fP +.B \-K directory This option specifies the directory to search for DNSSEC keys. If not specified, it defaults to the current directory. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k key\fP +.B \-k key This option tells BIND 9 to treat the specified key as a key\-signing key, ignoring any key flags. This option may be specified multiple times. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-M maxttl\fP +.B \-M maxttl This option sets the maximum TTL for the signed zone. Any TTL higher than \fBmaxttl\fP in the input zone is reduced to \fBmaxttl\fP in the output. This provides certainty as to the largest possible TTL in the signed zone, @@ -95,8 +113,10 @@ expire from resolver caches. Zones that are signed with this option should be configured to use a matching \fBmax\-zone\-ttl\fP in \fBnamed.conf\fP\&. (Note: This option is incompatible with \fB\-D\fP, because it modifies non\-DNSSEC data in the output zone.) +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s start\-time\fP +.B \-s start\-time This option specifies the date and time when the generated RRSIG records become valid. This can be either an absolute or relative time. An absolute start time is indicated by a number in YYYYMMDDHHMMSS notation; @@ -104,8 +124,10 @@ start time is indicated by a number in YYYYMMDDHHMMSS notation; start time is indicated by \fB+N\fP, which is N seconds from the current time. If no \fBstart\-time\fP is specified, the current time minus 1 hour (to allow for clock skew) is used. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-e end\-time\fP +.B \-e end\-time This option specifies the date and time when the generated RRSIG records expire. As with \fBstart\-time\fP, an absolute time is indicated in YYYYMMDDHHMMSS notation. A time relative to the start time is indicated with \fB+N\fP, @@ -113,8 +135,10 @@ which is N seconds from the start time. A time relative to the current time is indicated with \fBnow+N\fP\&. If no \fBend\-time\fP is specified, 30 days from the start time is the default. \fBend\-time\fP must be later than \fBstart\-time\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-X extended end\-time\fP +.B \-X extended end\-time This option specifies the date and time when the generated RRSIG records for the DNSKEY RRset expire. This is to be used in cases when the DNSKEY signatures need to persist longer than signatures on other records; @@ -128,21 +152,29 @@ relative to the current time is indicated with \fBnow+N\fP\&. If no \fBextended end\-time\fP is specified, the value of \fBend\-time\fP is used as the default. (\fBend\-time\fP, in turn, defaults to 30 days from the start time.) \fBextended end\-time\fP must be later than \fBstart\-time\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-f output\-file\fP +.B \-f output\-file This option indicates the name of the output file containing the signed zone. The default is to append \fB\&.signed\fP to the input filename. If \fBoutput\-file\fP is set to \fB\-\fP, then the signed zone is written to the standard output, with a default output format of \fBfull\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints a short summary of the options and arguments to \fBdnssec\-signzone\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints version information. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-i interval\fP +.B \-i interval This option indicates that, when a previously signed zone is passed as input, records may be re\-signed. The \fBinterval\fP option specifies the cycle interval as an offset from the current time, in seconds. If a RRSIG record expires @@ -155,15 +187,19 @@ the signature end and start times. So if neither \fBend\-time\fP nor signatures that are valid for 30 days, with a cycle interval of 7.5 days. Therefore, if any existing RRSIG records are due to expire in less than 7.5 days, they are replaced. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-I input\-format\fP +.B \-I input\-format This option sets the format of the input zone file. Possible formats are \fBtext\fP (the default), and \fBraw\fP\&. This option is primarily intended to be used for dynamic signed zones, so that the dumped zone file in a non\-text format containing updates can be signed directly. This option is not useful for non\-dynamic zones. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-j jitter\fP +.B \-j jitter When signing a zone with a fixed signature lifetime, all RRSIG records issued at the time of signing expire simultaneously. If the zone is incrementally signed, i.e., a previously signed zone is passed @@ -177,17 +213,23 @@ servers by spreading out cache expiration, i.e., if large numbers of RRSIGs do not expire at the same time from all caches, there is less congestion than if all validators need to refetch at around the same time. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-L serial\fP +.B \-L serial When writing a signed zone to "raw" format, this option sets the "source serial" value in the header to the specified \fBserial\fP number. (This is expected to be used primarily for testing purposes.) +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-n ncpus\fP +.B \-n ncpus This option specifies the number of threads to use. By default, one thread is started for each detected CPU. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-N soa\-serial\-format\fP +.B \-N soa\-serial\-format This option sets the SOA serial number format of the signed zone. Possible formats are \fBkeep\fP (the default), \fBincrement\fP, \fBunixtime\fP, and \fBdate\fP\&. @@ -211,12 +253,16 @@ YYYYMMDDNN format, unless the serial number is already greater than or equal to that value, in which case it is simply incremented by one. .UNINDENT +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-o origin\fP +.B \-o origin This option sets the zone origin. If not specified, the name of the zone file is assumed to be the origin. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-O output\-format\fP +.B \-O output\-format This option sets the format of the output file containing the signed zone. Possible formats are \fBtext\fP (the default), which is the standard textual representation of the zone; \fBfull\fP, which is text output in a @@ -225,16 +271,20 @@ format suitable for processing by external scripts; and \fBraw\fP and \fBnamed\fP\&. \fBraw=N\fP specifies the format version of the raw zone file: if N is 0, the raw file can be read by any version of \fBnamed\fP; if N is 1, the file can be read by release 9.9.0 or higher. The default is 1. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-P\fP +.B \-P This option disables post\-sign verification tests. .sp The post\-sign verification tests ensure that for each algorithm in use there is at least one non\-revoked self\-signed KSK key, that all revoked KSK keys are self\-signed, and that all records in the zone are signed by the algorithm. This option skips these tests. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-Q\fP +.B \-Q This option removes signatures from keys that are no longer active. .sp Normally, when a previously signed zone is passed as input to the @@ -245,15 +295,19 @@ with cached copies of the old DNSKEY RRset. The \fB\-Q\fP option forces \fBdnssec\-signzone\fP to remove signatures from keys that are no longer active. This enables ZSK rollover using the procedure described in \fI\%RFC 4641#4.2.1.1\fP ("Pre\-Publish Key Rollover"). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-q\fP +.B \-q This option enables quiet mode, which suppresses unnecessary output. Without this option, when \fBdnssec\-signzone\fP is run it prints three pieces of information to standard output: the number of keys in use; the algorithms used to verify the zone was signed correctly and other status information; and the filename containing the signed zone. With the option that output is suppressed, leaving only the filename. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-R\fP +.B \-R This option removes signatures from keys that are no longer published. .sp This option is similar to \fB\-Q\fP, except it forces @@ -261,8 +315,10 @@ This option is similar to \fB\-Q\fP, except it forces published. This enables ZSK rollover using the procedure described in \fI\%RFC 4641#4.2.1.2\fP ("Double Signature Zone Signing Key Rollover"). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-S\fP +.B \-S This option enables smart signing, which instructs \fBdnssec\-signzone\fP to search the key repository for keys that match the zone being signed, and to include them in the zone if appropriate. @@ -297,8 +353,10 @@ If the key\(aqs sync deletion date is set and is in the past, synchronization records (type CDS and/or CDNSKEY) are removed. .UNINDENT .UNINDENT +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-T ttl\fP +.B \-T ttl This option specifies a TTL to be used for new DNSKEY records imported into the zone from the key repository. If not specified, the default is the TTL value from the zone\(aqs SOA record. This option is ignored when @@ -309,52 +367,72 @@ records\(aq TTL values are set to match them, or if any of the imported DNSKEY records had a default TTL value. In the event of a conflict between TTL values in imported keys, the shortest one is used. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t\fP +.B \-t This option prints statistics at completion. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-u\fP +.B \-u This option updates the NSEC/NSEC3 chain when re\-signing a previously signed zone. With this option, a zone signed with NSEC can be switched to NSEC3, or a zone signed with NSEC3 can be switched to NSEC or to NSEC3 with different parameters. Without this option, \fBdnssec\-signzone\fP retains the existing chain when re\-signing. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v level\fP +.B \-v level This option sets the debugging level. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-x\fP +.B \-x 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 \fBdnssec\-dnskey\-kskonly yes;\fP zone option in \fBnamed\fP\&.) +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-z\fP +.B \-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 \fBupdate\-check\-ksk no;\fP zone option in \fBnamed\fP\&.) +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-3 salt\fP +.B \-3 salt This option generates an NSEC3 chain with the given hex\-encoded salt. A dash (\-) can be used to indicate that no salt is to be used when generating the NSEC3 chain. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-H iterations\fP +.B \-H iterations This option indicates that, when generating an NSEC3 chain, BIND 9 should use this many iterations. The default is 10. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-A\fP +.B \-A This option indicates that, when generating an NSEC3 chain, BIND 9 should set the OPTOUT flag on all NSEC3 records and should not generate NSEC3 records for insecure delegations. .sp Using this option twice (i.e., \fB\-AA\fP) turns the OPTOUT flag off for all records. This is useful when using the \fB\-u\fP option to modify an NSEC3 chain which previously had OPTOUT set. +.UNINDENT +.INDENT 0.0 .TP -.B \fBzonefile\fP +.B zonefile This option sets the file containing the zone to be signed. +.UNINDENT +.INDENT 0.0 .TP -.B \fBkey\fP +.B key This option specifies which keys should be used to sign the zone. If no keys are specified, the zone is examined for DNSKEY records at the zone apex. If these records are found and there are matching private keys in diff --git a/doc/man/dnssec-verify.1in b/doc/man/dnssec-verify.1in index 8ab9e81057..09392181d1 100644 --- a/doc/man/dnssec-verify.1in +++ b/doc/man/dnssec-verify.1in @@ -41,48 +41,64 @@ NSEC/NSEC3 chains are complete. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option specifies the DNS class of the zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-E engine\fP +.B \-E engine This option specifies the cryptographic hardware to use, when applicable. .sp When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-I input\-format\fP +.B \-I input\-format This option sets the format of the input zone file. Possible formats are \fBtext\fP (the default) and \fBraw\fP\&. This option is primarily intended to be used for dynamic signed zones, so that the dumped zone file in a non\-text format containing updates can be verified independently. This option is not useful for non\-dynamic zones. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-o origin\fP +.B \-o origin This option indicates the zone origin. If not specified, the name of the zone file is assumed to be the origin. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v level\fP +.B \-v level This option sets the debugging level. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints version information. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-q\fP +.B \-q This option sets quiet mode, which suppresses output. Without this option, when \fBdnssec\-verify\fP is run it prints to standard output the number of keys in use, the algorithms used to verify the zone was signed correctly, and other status information. With this option, all non\-error output is suppressed, and only the exit code indicates success. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-x\fP +.B \-x This option verifies only that the DNSKEY RRset is signed with key\-signing keys. Without this flag, it is assumed that the DNSKEY RRset is signed by all active keys. When this flag is set, it is not an error if the DNSKEY RRset is not signed by zone\-signing keys. This corresponds to the \fB\-x\fP option in \fBdnssec\-signzone\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-z\fP +.B \-z This option indicates that the KSK flag on the keys should be ignored when determining whether the zone is correctly signed. Without this flag, it is assumed that there is a non\-revoked, self\-signed DNSKEY with the KSK flag set for each @@ -95,6 +111,8 @@ the KSK flag state, and that other RRsets be signed by a non\-revoked key for the same algorithm that includes the self\-signed key; the same key may be used for both purposes. This corresponds to the \fB\-z\fP option in \fBdnssec\-signzone\fP\&. +.UNINDENT +.INDENT 0.0 .TP .B \fBzonefile\fP This option indicates the file containing the zone to be signed. diff --git a/doc/man/dnstap-read.1in b/doc/man/dnstap-read.1in index 420c94b4b8..da8d01c250 100644 --- a/doc/man/dnstap-read.1in +++ b/doc/man/dnstap-read.1in @@ -42,18 +42,24 @@ longer and more detailed YAML format is used. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-m\fP +.B \-m This option indicates trace memory allocations, and is used for debugging memory leaks. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p\fP +.B \-p This option prints the text form of the DNS message that was encapsulated in the \fBdnstap\fP frame, after printing the \fBdnstap\fP data. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-x\fP +.B \-x This option prints a hex dump of the wire form of the DNS message that was encapsulated in the \fBdnstap\fP frame, after printing the \fBdnstap\fP data. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-y\fP +.B \-y This option prints \fBdnstap\fP data in a detailed YAML format. .UNINDENT .SH SEE ALSO diff --git a/doc/man/host.1in b/doc/man/host.1in index 824b0cf9c4..4eaae39073 100644 --- a/doc/man/host.1in +++ b/doc/man/host.1in @@ -49,69 +49,95 @@ server or servers listed in \fB/etc/resolv.conf\fP\&. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-4\fP +.B \-4 This option specifies that only IPv4 should be used for query transport. See also the \fB\-6\fP option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-6\fP +.B \-6 This option specifies that only IPv6 should be used for query transport. See also the \fB\-4\fP option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-a\fP +.B \-a The \fB\-a\fP ("all") option is normally equivalent to \fB\-v \-t ANY\fP\&. It also affects the behavior of the \fB\-l\fP list zone option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-A\fP +.B \-A The \fB\-A\fP ("almost all") option is equivalent to \fB\-a\fP, except that RRSIG, NSEC, and NSEC3 records are omitted from the output. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option specifies the query class, which can be used to lookup HS (Hesiod) or CH (Chaosnet) class resource records. The default class is IN (Internet). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-C\fP +.B \-C This option indicates that \fBnamed\fP should check consistency, meaning that \fBhost\fP queries the SOA records for zone \fBname\fP 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. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-d\fP +.B \-d This option prints debugging traces, and is equivalent to the \fB\-v\fP verbose option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-l\fP +.B \-l This option tells \fBnamed\fP to list the zone, meaning the \fBhost\fP command performs a zone transfer of zone \fBname\fP and prints out the NS, PTR, and address records (A/AAAA). .sp Together, the \fB\-l \-a\fP options print all records in the zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-N ndots\fP +.B \-N ndots This option specifies the number of dots (\fBndots\fP) that have to be in \fBname\fP for it to be considered absolute. The default value is that defined using the \fBndots\fP statement in \fB/etc/resolv.conf\fP, or 1 if no \fBndots\fP statement is present. Names with fewer dots are interpreted as relative names, and are searched for in the domains listed in the \fBsearch\fP or \fBdomain\fP directive in \fB/etc/resolv.conf\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p port\fP +.B \-p port This option specifies the port to query on the server. The default is 53. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-r\fP +.B \-r This option specifies a non\-recursive query; setting this option clears the RD (recursion desired) bit in the query. This means that the name server receiving the query does not attempt to resolve \fBname\fP\&. The \fB\-r\fP option enables \fBhost\fP to mimic the behavior of a name server by making non\-recursive queries, and expecting to receive answers to those queries that can be referrals to other name servers. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-R number\fP +.B \-R number This option specifies the number of retries for UDP queries. If \fBnumber\fP is negative or zero, the number of retries is silently set to 1. The default value is 1, or the value of the \fBattempts\fP option in \fB/etc/resolv.conf\fP, if set. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s\fP +.B \-s This option tells \fBnamed\fP \fInot\fP 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. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t type\fP +.B \-t type This option specifies the query type. The \fBtype\fP argument can be any recognized query type: CNAME, NS, SOA, TXT, DNSKEY, AXFR, etc. .sp @@ -124,32 +150,44 @@ colon\-delimited IPv6 address, \fBhost\fP queries for PTR records. If a query type of IXFR is chosen, the starting serial number can be specified by appending an equals sign (=), followed by the starting serial number, e.g., \fB\-t IXFR=12345678\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-T\fP; \fB\-U\fP +.B \-T\(ga\(ga; \(ga\(ga\-U This option specifies TCP or UDP. By default, \fBhost\fP uses UDP when making queries; the \fB\-T\fP option makes it use a TCP connection when querying the name server. TCP is automatically selected for queries that require it, such as zone transfer (AXFR) requests. Type \fBANY\fP queries default to TCP, but can be forced to use UDP initially via \fB\-U\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-m flag\fP +.B \-m flag This option sets memory usage debugging: the flag can be \fBrecord\fP, \fBusage\fP, or \fBtrace\fP\&. The \fB\-m\fP option can be specified more than once to set multiple flags. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v\fP +.B \-v This option sets verbose output, and is equivalent to the \fB\-d\fP debug option. Verbose output can also be enabled by setting the \fBdebug\fP option in \fB/etc/resolv.conf\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints the version number and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-w\fP +.B \-w This option sets "wait forever": the query timeout is set to the maximum possible. See also the \fB\-W\fP option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-W wait\fP +.B \-W wait This options sets the length of the wait timeout, indicating that \fBnamed\fP should wait for up to \fBwait\fP seconds for a reply. If \fBwait\fP is less than 1, the wait interval is set to 1 second. .sp diff --git a/doc/man/mdig.1in b/doc/man/mdig.1in index d4c9a4e2e1..60d09faea4 100644 --- a/doc/man/mdig.1in +++ b/doc/man/mdig.1in @@ -70,39 +70,51 @@ assign values to options like the timeout interval. They have the form .SH ANYWHERE OPTIONS .INDENT 0.0 .TP -.B \fB\-f\fP +.B \-f This option makes \fBmdig\fP operate in batch mode by reading a list of lookup requests to process from the file \fBfilename\fP\&. The file contains a number of queries, one per line. Each entry in the file should be organized in the same way they would be presented as queries to \fBmdig\fP using the command\-line interface. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option causes \fBmdig\fP to print detailed help information, with the full list of options, and exit. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v\fP +.B \-v This option causes \fBmdig\fP to print the version number and exit. .UNINDENT .SH GLOBAL OPTIONS .INDENT 0.0 .TP -.B \fB\-4\fP +.B \-4 This option forces \fBmdig\fP to only use IPv4 query transport. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-6\fP +.B \-6 This option forces \fBmdig\fP to only use IPv6 query transport. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-b address\fP +.B \-b address This option sets the source IP address of the query to \fBaddress\fP\&. This must be a valid address on one of the host\(aqs network interfaces or "0.0.0.0" or "::". An optional port may be specified by appending "#" +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-m\fP +.B \-m This option enables memory usage debugging. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p port#\fP +.B \-p port# This option is used when a non\-standard port number is to be queried. \fBport#\fP is the port number that \fBmdig\fP sends its queries to, instead of the standard DNS port number 53. This option is @@ -113,90 +125,128 @@ queries on a non\-standard port number. The global query options are: .INDENT 0.0 .TP -.B \fB+[no]additional\fP +.B +[no]additional This option displays [or does not display] the additional section of a reply. The default is to display it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]all\fP +.B +[no]all This option sets or clears all display flags. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]answer\fP +.B +[no]answer This option displays [or does not display] the answer section of a reply. The default is to display it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]authority\fP +.B +[no]authority This option displays [or does not display] the authority section of a reply. The default is to display it. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]besteffort\fP +.B +[no]besteffort This option attempts to display [or does not display] the contents of messages which are malformed. The default is to not display malformed answers. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+burst\fP +.B +burst This option delays queries until the start of the next second. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]cl\fP +.B +[no]cl This option displays [or does not display] the CLASS when printing the record. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]comments\fP +.B +[no]comments This option toggles the display of comment lines in the output. The default is to print comments. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]continue\fP +.B +[no]continue This option toggles continuation on errors (e.g. timeouts). +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]crypto\fP +.B +[no]crypto This option toggles the display of cryptographic fields in DNSSEC records. The contents of these fields are unnecessary to debug most DNSSEC validation failures and removing them makes it easier to see the common failures. The default is to display the fields. When omitted, they are replaced by the string "[omitted]"; in the DNSKEY case, the key ID is displayed as the replacement, e.g., \fB[ key id = value ]\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+dscp[=value]\fP +.B +dscp[=value] This option sets the DSCP code point to be used when sending the query. Valid DSCP code points are in the range [0...63]. By default no code point is explicitly set. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]multiline\fP +.B +[no]multiline This option toggles printing of records, like the SOA records, in a verbose multi\-line format with human\-readable comments. The default is to print each record on a single line, to facilitate machine parsing of the \fBmdig\fP output. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]question\fP +.B +[no]question This option prints [or does not print] the question section of a query when an answer is returned. The default is to print the question section as a comment. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]rrcomments\fP +.B +[no]rrcomments This option toggles the display of per\-record comments in the output (for example, human\-readable key information about DNSKEY records). The default is not to print record comments unless multiline mode is active. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]short\fP +.B +[no]short This option provides [or does not provide] a terse answer. The default is to print the answer in a verbose form. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+split=W\fP +.B +split=W This option splits long hex\- or base64\-formatted fields in resource records into chunks of \fBW\fP characters (where \fBW\fP is rounded up to the nearest multiple of 4). \fB+nosplit\fP or \fB+split=0\fP causes fields not to be split. The default is 56 characters, or 44 characters when multiline mode is active. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]tcp\fP +.B +[no]tcp This option uses [or does not use] TCP when querying name servers. The default behavior is to use UDP. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ttlid\fP +.B +[no]ttlid This option displays [or does not display] the TTL when printing the record. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ttlunits\fP +.B +[no]ttlunits This option displays [or does not display] the TTL in friendly human\-readable time units of "s", "m", "h", "d", and "w", representing seconds, minutes, hours, days, and weeks. This implies +ttlid. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]vc\fP +.B +[no]vc This option uses [or does not use] TCP when querying name servers. This alternate syntax to \fB+[no]tcp\fP is provided for backwards compatibility. The \fBvc\fP stands for "virtual circuit". @@ -204,18 +254,22 @@ syntax to \fB+[no]tcp\fP is provided for backwards compatibility. The .SH LOCAL OPTIONS .INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option sets the query class to \fBclass\fP\&. It can be any valid query class which is supported in BIND 9. The default query class is "IN". +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t type\fP +.B \-t type This option sets the query type to \fBtype\fP\&. It can be any valid query type which is supported in BIND 9. The default query type is "A", unless the \fB\-x\fP option is supplied to indicate a reverse lookup with the "PTR" query type. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-x addr\fP +.B \-x addr Reverse lookups \- mapping addresses to names \- are simplified by this option. \fBaddr\fP is an IPv4 address in dotted\-decimal notation, or a colon\-delimited IPv6 address. \fBmdig\fP automatically @@ -228,13 +282,17 @@ domain. The local query options are: .INDENT 0.0 .TP -.B \fB+[no]aaflag\fP +.B +[no]aaflag This is a synonym for \fB+[no]aaonly\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]aaonly\fP +.B +[no]aaonly This sets the \fBaa\fP flag in the query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]adflag\fP +.B +[no]adflag This sets [or does not set] the AD (authentic data) bit in the query. This requests the server to return whether all of the answer and authority sections have all been validated as secure, according to the security @@ -242,91 +300,129 @@ policy of the server. AD=1 indicates that all records have been validated as secure and the answer is not from a OPT\-OUT range. AD=0 indicates that some part of the answer was insecure or not validated. This bit is set by default. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+bufsize=B\fP +.B +bufsize=B This sets the UDP message buffer size advertised using EDNS0 to \fBB\fP bytes. The maximum and minimum sizes of this buffer are 65535 and 0 respectively. Values outside this range are rounded up or down appropriately. Values other than zero cause a EDNS query to be sent. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]cdflag\fP +.B +[no]cdflag This sets [or does not set] the CD (checking disabled) bit in the query. This requests the server to not perform DNSSEC validation of responses. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]cookie=####\fP +.B +[no]cookie=#### This sends [or does not send] a COOKIE EDNS option, with an optional value. Replaying a COOKIE from a previous response allows the server to identify a previous client. The default is \fB+nocookie\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]dnssec\fP +.B +[no]dnssec This requests that DNSSEC records be sent by setting the DNSSEC OK (DO) bit in the OPT record in the additional section of the query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]edns[=#]\fP +.B +[no]edns[=#] This specifies [or does not specify] the EDNS version to query with. Valid values are 0 to 255. Setting the EDNS version causes an EDNS query to be sent. \fB+noedns\fP clears the remembered EDNS version. EDNS is set to 0 by default. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ednsflags[=#]\fP +.B +[no]ednsflags[=#] This sets the must\-be\-zero EDNS flag bits (Z bits) to the specified value. Decimal, hex, and octal encodings are accepted. Setting a named flag (e.g. DO) is silently ignored. By default, no Z bits are set. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]ednsopt[=code[:value]]\fP +.B +[no]ednsopt[=code[:value]] This specifies [or does not specify] an EDNS option with code point \fBcode\fP and an optional payload of \fBvalue\fP as a hexadecimal string. \fB+noednsopt\fP clears the EDNS options to be sent. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]expire\fP +.B +[no]expire This toggles sending of an EDNS Expire option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]nsid\fP +.B +[no]nsid This toggles inclusion of an EDNS name server ID request when sending a query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]recurse\fP +.B +[no]recurse This toggles the setting of the RD (recursion desired) bit in the query. This bit is set by default, which means \fBmdig\fP normally sends recursive queries. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+retry=T\fP +.B +retry=T This sets the number of times to retry UDP queries to server to \fBT\fP instead of the default, 2. Unlike \fB+tries\fP, this does not include the initial query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]subnet=addr[/prefix\-length]\fP +.B +[no]subnet=addr[/prefix\-length] This sends [or does not send] an EDNS Client Subnet option with the specified IP address or network prefix. +.UNINDENT +.INDENT 0.0 .TP .B \fBmdig +subnet=0.0.0.0/0\fP, or simply \fBmdig +subnet=0\fP This sends an EDNS client\-subnet option with an empty address and a source prefix\-length of zero, which signals a resolver that the client\(aqs address information must \fInot\fP be used when resolving this query. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+timeout=T\fP +.B +timeout=T This sets the timeout for a query to \fBT\fP seconds. The default timeout is 5 seconds for UDP transport and 10 for TCP. An attempt to set \fBT\fP to less than 1 results in a query timeout of 1 second being applied. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+tries=T\fP +.B +tries=T This sets the number of times to try UDP queries to server to \fBT\fP instead of the default, 3. If \fBT\fP is less than or equal to zero, the number of tries is silently rounded up to 1. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+udptimeout=T\fP +.B +udptimeout=T This sets the timeout between UDP query retries to \fBT\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]unknownformat\fP +.B +[no]unknownformat This prints [or does not print] all RDATA in unknown RR\-type presentation format (see \fI\%RFC 3597\fP). The default is to print RDATA for known types in the type\(aqs presentation format. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]yaml\fP +.B +[no]yaml This toggles printing of the responses in a detailed YAML format. +.UNINDENT +.INDENT 0.0 .TP -.B \fB+[no]zflag\fP +.B +[no]zflag This sets [or does not set] the last unassigned DNS header flag in a DNS query. This flag is off by default. .UNINDENT diff --git a/doc/man/named-checkconf.1in b/doc/man/named-checkconf.1in index 5ff53d45e8..b094851243 100644 --- a/doc/man/named-checkconf.1in +++ b/doc/man/named-checkconf.1in @@ -48,48 +48,68 @@ However, \fBnamed\-checkconf\fP can be run on these files explicitly. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints the usage summary and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-j\fP +.B \-j When loading a zonefile, this option instructs \fBnamed\fP to read the journal if it exists. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-l\fP +.B \-l This option lists all the configured zones. Each line of output contains the zone name, class (e.g. IN), view, and type (e.g. primary or secondary). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c\fP +.B \-c This option specifies that only the "core" configuration should be checked. This suppresses the loading of plugin modules, and causes all parameters to \fBplugin\fP statements to be ignored. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-i\fP +.B \-i This option ignores warnings on deprecated options. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p\fP +.B \-p This option prints out the \fBnamed.conf\fP and included files in canonical form if no errors were detected. See also the \fB\-x\fP option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t directory\fP +.B \-t directory This option instructs \fBnamed\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the configuration file are processed as if run by a similarly chrooted \fBnamed\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v\fP +.B \-v This option prints the version of the \fBnamed\-checkconf\fP program and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-x\fP +.B \-x When printing the configuration files in canonical form, this option obscures shared secrets by replacing them with strings of question marks (\fB?\fP). This allows the contents of \fBnamed.conf\fP and related files to be shared \- for example, when submitting bug reports \- without compromising private data. This option cannot be used without \fB\-p\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-z\fP +.B \-z This option performs a test load of all zones of type \fBprimary\fP found in \fBnamed.conf\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fBfilename\fP +.B filename This indicates the name of the configuration file to be checked. If not specified, it defaults to \fB@sysconfdir@/named.conf\fP\&. .UNINDENT diff --git a/doc/man/named-checkzone.1in b/doc/man/named-checkzone.1in index c7ed4bf1dd..06a3411382 100644 --- a/doc/man/named-checkzone.1in +++ b/doc/man/named-checkzone.1in @@ -42,32 +42,46 @@ configuring them into a name server. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-d\fP +.B \-d This option enables debugging. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints the usage summary and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-q\fP +.B \-q This option sets quiet mode, which only sets an exit code to indicate successful or failed completion. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v\fP +.B \-v This option prints the version of the \fBnamed\-checkzone\fP program and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-j\fP +.B \-j When loading a zone file, this option tells \fBnamed\fP to read the journal if it exists. The journal file name is assumed to be the zone file name with the string \fB\&.jnl\fP appended. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-J filename\fP +.B \-J filename When loading the zone file, this option tells \fBnamed\fP to read the journal from the given file, if it exists. This implies \fB\-j\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option specifies the class of the zone. If not specified, \fBIN\fP is assumed. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-i mode\fP +.B \-i mode This option performs post\-load zone integrity checks. Possible modes are \fBfull\fP (the default), \fBfull\-sibling\fP, \fBlocal\fP, \fBlocal\-sibling\fP, and \fBnone\fP\&. @@ -92,12 +106,16 @@ checks, but are otherwise the same as \fBfull\fP and \fBlocal\fP, respectively. .sp Mode \fBnone\fP disables the checks. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-f format\fP +.B \-f format This option specifies the format of the zone file. Possible formats are \fBtext\fP (the default), and \fBraw\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-F format\fP +.B \-F format This option specifies the format of the output file specified. For \fBnamed\-checkzone\fP, this does not have any effect unless it dumps the zone contents. @@ -108,44 +126,62 @@ store the zone in a binary format for rapid loading by \fBnamed\fP\&. \fBraw=N\fP specifies the format version of the raw zone file: if \fBN\fP is 0, the raw file can be read by any version of \fBnamed\fP; if N is 1, the file can only be read by release 9.9.0 or higher. The default is 1. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k mode\fP +.B \-k mode This option performs \fBcheck\-names\fP checks with the specified failure mode. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-l ttl\fP +.B \-l ttl 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 \fBmax\-zone\-ttl\fP option in \fBnamed.conf\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-L serial\fP +.B \-L serial When compiling a zone to \fBraw\fP format, this option sets the "source serial" value in the header to the specified serial number. This is expected to be used primarily for testing purposes. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-m mode\fP +.B \-m mode This option specifies whether MX records should be checked to see if they are addresses. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-M mode\fP +.B \-M mode This option checks whether a MX record refers to a CNAME. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-n mode\fP +.B \-n mode This option specifies whether NS records should be checked to see if they are addresses. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-o filename\fP +.B \-o filename This option writes the zone output to \fBfilename\fP\&. If \fBfilename\fP is \fB\-\fP, then the zone output is written to standard output. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-r mode\fP +.B \-r mode This option checks for records that are treated as different by DNSSEC but are semantically equal in plain DNS. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s style\fP +.B \-s style This option specifies the style of the dumped zone file. Possible styles are \fBfull\fP (the default) and \fBrelative\fP\&. The \fBfull\fP format is most suitable for processing automatically by a separate script. @@ -153,39 +189,55 @@ The relative format is more human\-readable and is thus suitable for editing by hand. This does not have any effect unless it dumps the zone contents. It also does not have any meaning if the output format is not text. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-S mode\fP +.B \-S mode This option checks whether an SRV record refers to a CNAME. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t directory\fP +.B \-t directory This option tells \fBnamed\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the configuration file are processed as if run by a similarly chrooted \fBnamed\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-T mode\fP +.B \-T mode This option checks whether Sender Policy Framework (SPF) records exist and issues a warning if an SPF\-formatted TXT record is not also present. Possible modes are \fBwarn\fP (the default) and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-w directory\fP +.B \-w directory This option instructs \fBnamed\fP to chdir to \fBdirectory\fP, so that relative filenames in master file \fB$INCLUDE\fP directives work. This is similar to the directory clause in \fBnamed.conf\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D\fP +.B \-D This option dumps the zone file in canonical format. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-W mode\fP +.B \-W mode This option specifies whether to check for non\-terminal wildcards. Non\-terminal wildcards are almost always the result of a failure to understand the wildcard matching algorithm (\fI\%RFC 4592\fP). Possible modes are \fBwarn\fP (the default) and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fBzonename\fP +.B zonename This indicates the domain name of the zone being checked. +.UNINDENT +.INDENT 0.0 .TP -.B \fBfilename\fP +.B filename This is the name of the zone file. .UNINDENT .SH RETURN VALUES diff --git a/doc/man/named-compilezone.1in b/doc/man/named-compilezone.1in index 7635bd07ad..96741bfc0f 100644 --- a/doc/man/named-compilezone.1in +++ b/doc/man/named-compilezone.1in @@ -44,32 +44,46 @@ strict as those specified in the \fBnamed\fP configuration file. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-d\fP +.B \-d This option enables debugging. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints the usage summary and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-q\fP +.B \-q This option sets quiet mode, which only sets an exit code to indicate successful or failed completion. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v\fP +.B \-v This option prints the version of the \fBnamed\-checkzone\fP program and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-j\fP +.B \-j When loading a zone file, this option tells \fBnamed\fP to read the journal if it exists. The journal file name is assumed to be the zone file name with the string \fB\&.jnl\fP appended. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-J filename\fP +.B \-J filename When loading the zone file, this option tells \fBnamed\fP to read the journal from the given file, if it exists. This implies \fB\-j\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c class\fP +.B \-c class This option specifies the class of the zone. If not specified, \fBIN\fP is assumed. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-i mode\fP +.B \-i mode This option performs post\-load zone integrity checks. Possible modes are \fBfull\fP (the default), \fBfull\-sibling\fP, \fBlocal\fP, \fBlocal\-sibling\fP, and \fBnone\fP\&. @@ -94,12 +108,16 @@ checks, but are otherwise the same as \fBfull\fP and \fBlocal\fP, respectively. .sp Mode \fBnone\fP disables the checks. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-f format\fP +.B \-f format This option specifies the format of the zone file. Possible formats are \fBtext\fP (the default), and \fBraw\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-F format\fP +.B \-F format This option specifies the format of the output file specified. For \fBnamed\-checkzone\fP, this does not have any effect unless it dumps the zone contents. @@ -110,84 +128,118 @@ store the zone in a binary format for rapid loading by \fBnamed\fP\&. \fBraw=N\fP specifies the format version of the raw zone file: if \fBN\fP is 0, the raw file can be read by any version of \fBnamed\fP; if N is 1, the file can only be read by release 9.9.0 or higher. The default is 1. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k mode\fP +.B \-k mode This option performs \fBcheck\-names\fP checks with the specified failure mode. Possible modes are \fBfail\fP (the default), \fBwarn\fP, and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-l ttl\fP +.B \-l ttl 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 \fBmax\-zone\-ttl\fP option in \fBnamed.conf\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-L serial\fP +.B \-L serial When compiling a zone to \fBraw\fP format, this option sets the "source serial" value in the header to the specified serial number. This is expected to be used primarily for testing purposes. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-m mode\fP +.B \-m mode This option specifies whether MX records should be checked to see if they are addresses. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-M mode\fP +.B \-M mode This option checks whether a MX record refers to a CNAME. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-n mode\fP +.B \-n mode This option specifies whether NS records should be checked to see if they are addresses. Possible modes are \fBfail\fP (the default), \fBwarn\fP, and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-o filename\fP +.B \-o filename This option writes the zone output to \fBfilename\fP\&. If \fBfilename\fP is \fB\-\fP, then the zone output is written to standard output. This is mandatory for \fBnamed\-compilezone\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-r mode\fP +.B \-r mode This option checks for records that are treated as different by DNSSEC but are semantically equal in plain DNS. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s style\fP +.B \-s style This option specifies the style of the dumped zone file. Possible styles are \fBfull\fP (the default) and \fBrelative\fP\&. The \fBfull\fP format is most suitable for processing automatically by a separate script. The relative format is more human\-readable and is thus suitable for editing by hand. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-S mode\fP +.B \-S mode This option checks whether an SRV record refers to a CNAME. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t directory\fP +.B \-t directory This option tells \fBnamed\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the configuration file are processed as if run by a similarly chrooted \fBnamed\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-T mode\fP +.B \-T mode This option checks whether Sender Policy Framework (SPF) records exist and issues a warning if an SPF\-formatted TXT record is not also present. Possible modes are \fBwarn\fP (the default) and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-w directory\fP +.B \-w directory This option instructs \fBnamed\fP to chdir to \fBdirectory\fP, so that relative filenames in master file \fB$INCLUDE\fP directives work. This is similar to the directory clause in \fBnamed.conf\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D\fP +.B \-D This option dumps the zone file in canonical format. This is always enabled for \fBnamed\-compilezone\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-W mode\fP +.B \-W mode This option specifies whether to check for non\-terminal wildcards. Non\-terminal wildcards are almost always the result of a failure to understand the wildcard matching algorithm (\fI\%RFC 4592\fP). Possible modes are \fBwarn\fP (the default) and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fBzonename\fP +.B zonename This indicates the domain name of the zone being checked. +.UNINDENT +.INDENT 0.0 .TP -.B \fBfilename\fP +.B filename This is the name of the zone file. .UNINDENT .SH RETURN VALUES diff --git a/doc/man/named-nzd2nzf.1in b/doc/man/named-nzd2nzf.1in index 4c537aa932..fee8beec73 100644 --- a/doc/man/named-nzd2nzf.1in +++ b/doc/man/named-nzd2nzf.1in @@ -43,7 +43,7 @@ version of BIND to an older version. .SH ARGUMENTS .INDENT 0.0 .TP -.B \fBfilename\fP +.B filename This is the name of the \fB\&.nzd\fP file whose contents should be printed. .UNINDENT .SH SEE ALSO diff --git a/doc/man/named-rrchecker.1in b/doc/man/named-rrchecker.1in index 26609b0d21..d51b24734f 100644 --- a/doc/man/named-rrchecker.1in +++ b/doc/man/named-rrchecker.1in @@ -40,22 +40,30 @@ input and checks whether it is syntactically correct. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints out the help menu. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-o origin\fP +.B \-o origin This option specifies the origin to be used when interpreting the record. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p\fP +.B \-p This option prints out the resulting record in canonical form. If there is no canonical form defined, the record is printed in unknown record format. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-u\fP +.B \-u This option prints out the resulting record in unknown record form. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-C\fP, \fB\-T\fP, and \fB\-P\fP +.B \-C, \-T, \-P These options print out the known class, standard type, and private type mnemonics, respectively. .UNINDENT diff --git a/doc/man/named.8in b/doc/man/named.8in index 34ef4c4081..e200fc37c7 100644 --- a/doc/man/named.8in +++ b/doc/man/named.8in @@ -45,47 +45,65 @@ listens for queries. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-4\fP +.B \-4 This option tells \fBnamed\fP to use only IPv4, even if the host machine is capable of IPv6. \fB\-4\fP and \fB\-6\fP are mutually exclusive. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-6\fP +.B \-6 This option tells \fBnamed\fP to use only IPv6, even if the host machine is capable of IPv4. \fB\-4\fP and \fB\-6\fP are mutually exclusive. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c config\-file\fP +.B \-c config\-file This option tells \fBnamed\fP to use \fBconfig\-file\fP as its configuration file instead of the default, \fB@sysconfdir@/named.conf\fP\&. To ensure that the configuration file can be reloaded after the server has changed its working directory due to to a possible \fBdirectory\fP option in the configuration file, \fBconfig\-file\fP should be an absolute pathname. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-d debug\-level\fP +.B \-d debug\-level This option sets the daemon\(aqs debug level to \fBdebug\-level\fP\&. Debugging traces from \fBnamed\fP become more verbose as the debug level increases. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D string\fP +.B \-D string This option specifies a string that is used to identify a instance of \fBnamed\fP in a process listing. The contents of \fBstring\fP are not examined. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-E engine\-name\fP +.B \-E engine\-name When applicable, this option specifies the hardware to use for cryptographic operations, such as a secure key store used for signing. .sp When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-f\fP +.B \-f This option runs the server in the foreground (i.e., do not daemonize). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-g\fP +.B \-g This option runs the server in the foreground and forces all logging to \fBstderr\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-L logfile\fP +.B \-L logfile This option sets the log to the file \fBlogfile\fP by default, instead of the system log. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-M option\fP +.B \-M option This option sets the default memory context options. If set to \fBexternal\fP, the internal memory manager is bypassed in favor of system\-provided memory allocation functions. If set to \fBfill\fP, blocks @@ -93,19 +111,25 @@ of memory are filled with tag values when allocated or freed, to assist debugging of memory problems. \fBnofill\fP disables this behavior, and is the default unless \fBnamed\fP has been compiled with developer options. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-m flag\fP +.B \-m flag This option turns on memory usage debugging flags. Possible flags are \fBusage\fP, \fBtrace\fP, \fBrecord\fP, \fBsize\fP, and \fBmctx\fP\&. These correspond to the \fBISC_MEM_DEBUGXXXX\fP flags described in \fB\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-n #cpus\fP +.B \-n #cpus This option creates \fB#cpus\fP worker threads to take advantage of multiple CPUs. If not specified, \fBnamed\fP tries to determine the number of CPUs present and creates one thread per CPU. If it is unable to determine the number of CPUs, a single worker thread is created. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p value\fP +.B \-p value This option specifies the port(s) on which the server will listen for queries. If \fBvalue\fP is of the form \fB\fP or \fBdns=\fP, the server will listen for DNS queries on @@ -116,8 +140,10 @@ If \fBvalue\fP is of the form \fBhttps=\fP, the server will listen for HTTPS queries on \fBportnum\fP; the default is 443. If \fBvalue\fP is of the form \fBhttp=\fP, the server will listen for HTTP queries on \fBportnum\fP; the default is 80. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s\fP +.B \-s This option writes memory usage statistics to \fBstdout\fP on exit. .UNINDENT .sp @@ -130,7 +156,7 @@ removed or changed in a future release. .UNINDENT .INDENT 0.0 .TP -.B \fB\-S #max\-socks\fP +.B \-S #max\-socks This option is deprecated and no longer has any function. .UNINDENT .sp @@ -150,7 +176,7 @@ for its internal use. .UNINDENT .INDENT 0.0 .TP -.B \fB\-t directory\fP +.B \-t directory This option tells \fBnamed\fP to chroot to \fBdirectory\fP after processing the command\-line arguments, but before reading the configuration file. .UNINDENT @@ -166,7 +192,7 @@ with root privileges to escape a chroot jail. .UNINDENT .INDENT 0.0 .TP -.B \fB\-U #listeners\fP +.B \-U #listeners This option tells \fBnamed\fP the number of \fB#listeners\fP worker threads to listen on, for incoming UDP packets on each address. If not specified, \fBnamed\fP calculates a default value based on the number of detected CPUs: 1 for 1 CPU, and the @@ -175,8 +201,10 @@ This cannot be increased to a value higher than the number of CPUs. If \fB\-n\fP has been set to a higher value than the number of detected CPUs, then \fB\-U\fP may be increased as high as that value, but no higher. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-u user\fP +.B \-u user This option sets the setuid to \fBuser\fP after completing privileged operations, such as creating sockets that listen on privileged ports. .UNINDENT @@ -195,13 +223,17 @@ previous kernels did not allow privileges to be retained after .UNINDENT .INDENT 0.0 .TP -.B \fB\-v\fP +.B \-v This option reports the version number and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option reports the version number and build options, and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-X lock\-file\fP +.B \-X lock\-file This option acquires a lock on the specified file at runtime; this helps to prevent duplicate \fBnamed\fP instances from running simultaneously. Use of this option overrides the \fBlock\-file\fP option in diff --git a/doc/man/nsec3hash.1in b/doc/man/nsec3hash.1in index 3090300f6e..e0ac570c1f 100644 --- a/doc/man/nsec3hash.1in +++ b/doc/man/nsec3hash.1in @@ -49,22 +49,30 @@ into a command line to confirm the correctness of an NSEC3 hash. .SH ARGUMENTS .INDENT 0.0 .TP -.B \fBsalt\fP +.B salt This is the salt provided to the hash algorithm. +.UNINDENT +.INDENT 0.0 .TP -.B \fBalgorithm\fP +.B algorithm This is a number indicating the hash algorithm. Currently the only supported hash algorithm for NSEC3 is SHA\-1, which is indicated by the number 1; consequently "1" is the only useful value for this argument. +.UNINDENT +.INDENT 0.0 .TP -.B \fBflags\fP +.B flags This is provided for compatibility with NSEC3 record presentation format, but is ignored since the flags do not affect the hash. +.UNINDENT +.INDENT 0.0 .TP -.B \fBiterations\fP +.B iterations This is the number of additional times the hash should be performed. +.UNINDENT +.INDENT 0.0 .TP -.B \fBdomain\fP +.B domain This is the domain name to be hashed. .UNINDENT .SH SEE ALSO diff --git a/doc/man/nsupdate.1in b/doc/man/nsupdate.1in index b4840b36b3..3a3d1c281b 100644 --- a/doc/man/nsupdate.1in +++ b/doc/man/nsupdate.1in @@ -73,26 +73,38 @@ used by Windows 2000 can be switched on with the \fB\-o\fP flag. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-4\fP +.B \-4 This option sets use of IPv4 only. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-6\fP +.B \-6 This option sets use of IPv6 only. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-C\fP +.B \-C Overrides the default \fIresolv.conf\fP file. This is only intended for testing. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-d\fP +.B \-d This option sets debug mode, which provides tracing information about the update requests that are made and the replies received from the name server. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-D\fP +.B \-D This option sets extra debug mode. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-i\fP +.B \-i This option forces interactive mode, even when standard input is not a terminal. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k keyfile\fP +.B \-k keyfile This option indicates the file containing the TSIG authentication key. Keyfiles may be in two formats: a single file containing a \fBnamed.conf\fP\-format \fBkey\fP statement, which may be generated automatically by \fBddns\-confgen\fP; @@ -102,8 +114,10 @@ or a pair of files whose names are of the format \fBdnssec\-keygen\fP\&. The \fB\-k\fP 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. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-l\fP +.B \-l This option sets local\-host only mode, which sets the server address to localhost (disabling the \fBserver\fP so that the server address cannot be overridden). Connections to the local server use a TSIG key @@ -111,27 +125,39 @@ found in \fB@runstatedir@/session.key\fP, which is automatically generated by \fBnamed\fP if any local \fBprimary\fP zone has set \fBupdate\-policy\fP to \fBlocal\fP\&. The location of this key file can be overridden with the \fB\-k\fP option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-L level\fP +.B \-L level This option sets the logging debug level. If zero, logging is disabled. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p port\fP +.B \-p port This option sets the port to use for connections to a name server. The default is 53. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-P\fP +.B \-P This option prints the list of private BIND\-specific resource record types whose format is understood by \fBnsupdate\fP\&. See also the \fB\-T\fP option. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-r udpretries\fP +.B \-r udpretries This option sets the number of UDP retries. The default is 3. If zero, only one update request is made. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t timeout\fP +.B \-t timeout This option sets the maximum time an update request can take before it is aborted. The default is 300 seconds. If zero, the timeout is disabled. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-T\fP +.B \-T This option prints the list of IANA standard resource record types whose format is understood by \fBnsupdate\fP\&. \fBnsupdate\fP exits after the lists are printed. The \fB\-T\fP option can be combined with the \fB\-P\fP @@ -141,22 +167,30 @@ Other types can be entered using \fBTYPEXXXXX\fP where \fBXXXXX\fP is the decimal value of the type with no leading zeros. The rdata, if present, is parsed using the UNKNOWN rdata format, ( ). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-u udptimeout\fP +.B \-u udptimeout This option sets the UDP retry interval. The default is 3 seconds. If zero, the interval is computed from the timeout interval and number of UDP retries. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-v\fP +.B \-v This option specifies that TCP should be used even for small update requests. By default, \fBnsupdate\fP uses UDP to send update requests to the name server unless they are too large to fit in a UDP request, in which case TCP is used. TCP may be preferable when a batch of update requests is made. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option prints the version number and exits. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-y [hmac:]keyname:secret\fP +.B \-y [hmac:]keyname:secret This option sets the literal TSIG authentication key. \fBkeyname\fP is the name of the key, and \fBsecret\fP is the base64 encoded shared secret. \fBhmac\fP is the name of the key algorithm; valid choices are \fBhmac\-md5\fP, diff --git a/doc/man/rndc-confgen.8in b/doc/man/rndc-confgen.8in index fa3158722a..6abc3951bd 100644 --- a/doc/man/rndc-confgen.8in +++ b/doc/man/rndc-confgen.8in @@ -44,7 +44,7 @@ by hand. Alternatively, it can be run with the \fB\-a\fP option to set up a .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-a\fP +.B \-a This option sets automatic \fBrndc\fP configuration, which creates a file \fB@sysconfdir@/rndc.key\fP that is read by both \fBrndc\fP and \fBnamed\fP on startup. The \fBrndc.key\fP file defines a default command channel and @@ -55,47 +55,67 @@ If a more elaborate configuration than that generated by \fBrndc\-confgen \-a\fP is required, for example if rndc is to be used remotely, run \fBrndc\-confgen\fP without the \fB\-a\fP option and set up \fBrndc.conf\fP and \fBnamed.conf\fP as directed. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-A algorithm\fP +.B \-A algorithm This option specifies the algorithm to use for the TSIG key. Available choices are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, and hmac\-sha512. The default is hmac\-sha256. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-b keysize\fP +.B \-b keysize This option specifies the size of the authentication key in bits. The size must be between 1 and 512 bits; the default is the hash size. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c keyfile\fP +.B \-c keyfile This option is used with the \fB\-a\fP option to specify an alternate location for \fBrndc.key\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints a short summary of the options and arguments to \fBrndc\-confgen\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k keyname\fP +.B \-k keyname This option specifies the key name of the \fBrndc\fP authentication key. This must be a valid domain name. The default is \fBrndc\-key\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p port\fP +.B \-p port This option specifies the command channel port where \fBnamed\fP listens for connections from \fBrndc\fP\&. The default is 953. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-q\fP +.B \-q This option prevets printing the written path in automatic configuration mode. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s address\fP +.B \-s address This option specifies the IP address where \fBnamed\fP listens for command\-channel connections from \fBrndc\fP\&. The default is the loopback address 127.0.0.1. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-t chrootdir\fP +.B \-t chrootdir This option is used with the \fB\-a\fP option to specify a directory where \fBnamed\fP runs chrooted. An additional copy of the \fBrndc.key\fP is written relative to this directory, so that it is found by the chrooted \fBnamed\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-u user\fP +.B \-u user This option is used with the \fB\-a\fP option to set the owner of the generated \fBrndc.key\fP file. If \fB\-t\fP is also specified, only the file in the chroot area has its owner changed. diff --git a/doc/man/rndc.8in b/doc/man/rndc.8in index 3b1d5d2f25..bc6534c2c1 100644 --- a/doc/man/rndc.8in +++ b/doc/man/rndc.8in @@ -56,51 +56,71 @@ server and decide what algorithm and key it should use. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-4\fP +.B \-4 This option indicates use of IPv4 only. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-6\fP +.B \-6 This option indicates use of IPv6 only. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-b source\-address\fP +.B \-b source\-address This option indicates \fBsource\-address\fP as the source address for the connection to the server. Multiple instances are permitted, to allow setting of both the IPv4 and IPv6 source addresses. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-c config\-file\fP +.B \-c config\-file This option indicates \fBconfig\-file\fP as the configuration file instead of the default, \fB@sysconfdir@/rndc.conf\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-k key\-file\fP +.B \-k key\-file This option indicates \fBkey\-file\fP as the key file instead of the default, \fB@sysconfdir@/rndc.key\fP\&. The key in \fB@sysconfdir@/rndc.key\fP is used to authenticate commands sent to the server if the config\-file does not exist. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-s server\fP +.B \-s server \fBserver\fP is the name or address of the server which matches a server statement in the configuration file for \fBrndc\fP\&. If no server is supplied on the command line, the host named by the default\-server clause in the options statement of the \fBrndc\fP configuration file is used. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-p port\fP +.B \-p port This option instructs BIND 9 to send commands to TCP port \fBport\fP instead of its default control channel port, 953. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-q\fP +.B \-q This option sets quiet mode, where message text returned by the server is not printed unless there is an error. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-r\fP +.B \-r This option instructs \fBrndc\fP to print the result code returned by \fBnamed\fP after executing the requested command (e.g., ISC_R_SUCCESS, ISC_R_FAILURE, etc.). +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-V\fP +.B \-V This option enables verbose logging. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-y key_id\fP +.B \-y key_id This option indicates use of the key \fBkey_id\fP from the configuration file. For control message validation to succeed, \fBkey_id\fP must be known by \fBnamed\fP with the same algorithm and secret string. If no \fBkey_id\fP is specified, \fBrndc\fP first looks for a key clause in the server statement of @@ -118,7 +138,7 @@ without arguments. Currently supported commands are: .INDENT 0.0 .TP -.B \fBaddzone\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] \fIconfiguration\fP +.B addzone zone [class [view]] configuration This command adds a zone while the server is running. This command requires the \fBallow\-new\-zones\fP option to be set to \fByes\fP\&. The configuration string specified on the command line is the zone configuration text @@ -142,8 +162,10 @@ the default view: text.) .sp See also \fBrndc delzone\fP and \fBrndc modzone\fP\&. +.UNINDENT +.INDENT 0.0 .TP -\fBdelzone\fP [\fB\-clean\fP] \fIzone\fP [\fIclass\fP [\fIview\fP]] +.B delzone [\-clean] zone [class [view]] This command deletes a zone while the server is running. .sp If the \fB\-clean\fP argument is specified, the zone\(aqs master file (and @@ -160,8 +182,10 @@ recreated. To remove it permanently, it must also be removed from \fBnamed.conf\fP\&. .sp See also \fBrndc addzone\fP and \fBrndc modzone\fP\&. +.UNINDENT +.INDENT 0.0 .TP -\fBdnssec\fP ( \fB\-status\fP | \fB\-rollover\fP \fB\-key\fP id [\fB\-alg\fP \fIalgorithm\fP] [\fB\-when\fP \fItime\fP] | \fB\-checkds\fP [\fB\-key\fP \fIid\fP [\fB\-alg\fP \fIalgorithm\fP]] [\fB\-when\fP \fItime\fP] ( \fIpublished\fP | \fIwithdrawn\fP )) \fIzone\fP [\fIclass\fP [\fIview\fP]] +.B dnssec (\-status | \-rollover \-key id [\-alg algorithm] [\-when time] | \-checkds [\-key id [\-alg algorithm]] [\-when time] published | withdraw)) zone [class [view]] This command allows you to interact with the "dnssec\-policy" of a given zone. .sp @@ -179,8 +203,10 @@ is only one key acting as a KSK in the zone, assume the DS of that key (if there are multiple keys with the same tag, use \fB\-alg algorithm\fP to select the correct algorithm). The time that the DS has been published or withdrawn is set to now, unless otherwise specified with the argument \fB\-when time\fP\&. +.UNINDENT +.INDENT 0.0 .TP -\fBdnstap\fP ( \fB\-reopen\fP | \fB\-roll\fP [\fInumber\fP] ) +.B dnstap (\-reopen | \-roll [number]) This command closes and re\-opens DNSTAP output files. \fBrndc dnstap \-reopen\fP allows the output file to be renamed externally, so that \fBnamed\fP can truncate and re\-open it. \fBrndc dnstap \-roll\fP causes the output file @@ -188,26 +214,36 @@ to be rolled automatically, similar to log files. The most recent output file has ".0" appended to its name; the previous most recent output file is moved to ".1", and so on. If \fBnumber\fP is specified, then the number of backup log files is limited to that number. +.UNINDENT +.INDENT 0.0 .TP -\fBdumpdb\fP [\fB\-all\fP | \fB\-cache\fP | \fB\-zones\fP | \fB\-adb\fP | \fB\-bad\fP | \fB\-expired\fP | \fB\-fail\fP] [\fIview ...\fP] +.B dumpdb [\-all | \-cache | \-zones | \-adb | \-bad | \-expired | \-fail] [view ...] This command dumps the server\(aqs caches (default) and/or zones to the dump file for the specified views. If no view is specified, all views are dumped. (See the \fBdump\-file\fP option in the BIND 9 Administrator Reference Manual.) +.UNINDENT +.INDENT 0.0 .TP -.B \fBflush\fP +.B flush This command flushes the server\(aqs cache. +.UNINDENT +.INDENT 0.0 .TP -.B \fBflushname\fP \fIname\fP [\fIview\fP] +.B flushname name [view] This command flushes the given name from the view\(aqs DNS cache and, if applicable, from the view\(aqs nameserver address database, bad server cache, and SERVFAIL cache. +.UNINDENT +.INDENT 0.0 .TP -.B \fBflushtree\fP \fIname\fP [\fIview\fP] +.B flushtree name [view] This command flushes the given name, and all of its subdomains, from the view\(aqs DNS cache, address database, bad server cache, and SERVFAIL cache. +.UNINDENT +.INDENT 0.0 .TP -.B \fBfreeze\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]] +.B freeze [zone [class [view]]] This command suspends updates to a dynamic zone. If no zone is specified, then all zones are suspended. This allows manual edits to be made to a zone normally updated by dynamic update, and causes changes in the @@ -215,8 +251,10 @@ journal file to be synced into the master file. All dynamic update attempts are refused while the zone is frozen. .sp See also \fBrndc thaw\fP\&. +.UNINDENT +.INDENT 0.0 .TP -\fBhalt\fP [\fB\-p\fP] +.B halt [\-p] 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 @@ -225,8 +263,10 @@ an external process to determine when \fBnamed\fP has completed halting. .sp See also \fBrndc stop\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fBloadkeys\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]] +.B loadkeys [zone [class [view]]] This command fetches all DNSSEC keys for the given zone from the key directory. If they are within their publication period, they are merged into the zone\(aqs DNSKEY RRset. Unlike \fBrndc sign\fP, however, the zone is not @@ -237,8 +277,10 @@ This command requires that the zone be configured with a \fBdnssec\-policy\fP, o that the \fBauto\-dnssec\fP zone option be set to \fBmaintain\fP, and also requires the zone to be configured to allow dynamic DNS. (See "Dynamic Update Policies" in the Administrator Reference Manual for more details.) +.UNINDENT +.INDENT 0.0 .TP -.B \fBmanaged\-keys\fP (\fIstatus\fP | \fIrefresh\fP | \fIsync\fP | \fIdestroy\fP) [\fIclass\fP [\fIview\fP]] +.B managed\-keys (status | refresh | sync | destroy) [class [view]] This command inspects and controls the "managed\-keys" database which handles \fI\%RFC 5011\fP DNSSEC trust anchor maintenance. If a view is specified, these commands are applied to that view; otherwise, they are applied to all @@ -277,8 +319,10 @@ also be used, for example, to jumpstart the acquisition of new keys in the event of a trust anchor rollover, or as a brute\-force repair for key maintenance problems. .UNINDENT +.UNINDENT +.INDENT 0.0 .TP -.B \fBmodzone\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] \fIconfiguration\fP +.B modzone zone [class [view]] configuration This command modifies the configuration of a zone while the server is running. This command requires the \fBallow\-new\-zones\fP option to be set to \fByes\fP\&. As with \fBaddzone\fP, the configuration string specified on the @@ -295,16 +339,22 @@ make the changes permanent, it must also be modified in \fBnamed.conf\fP\&. .sp See also \fBrndc addzone\fP and \fBrndc delzone\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fBnotify\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +.B notify zone [class [view]] This command resends NOTIFY messages for the zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fBnotrace\fP +.B notrace This command sets the server\(aqs debugging level to 0. .sp See also \fBrndc trace\fP\&. +.UNINDENT +.INDENT 0.0 .TP -\fBnta\fP [( \fB\-class\fP \fIclass\fP | \fB\-dump\fP | \fB\-force\fP | \fB\-remove\fP | \fB\-lifetime\fP \fIduration\fP)] \fIdomain\fP [\fIview\fP] +.B nta [(\-class class | \-dump | \-force | \-remove | \-lifetime duration)] domain [view] This command sets a DNSSEC negative trust anchor (NTA) for \fBdomain\fP, with a lifetime of \fBduration\fP\&. The default lifetime is configured in \fBnamed.conf\fP via the \fBnta\-lifetime\fP option, and defaults to one @@ -354,8 +404,10 @@ All of these options can be shortened, i.e., to \fB\-l\fP, \fB\-r\fP, Unrecognized options are treated as errors. To refer to a domain or view name that begins with a hyphen, use a double\-hyphen (\-\-) on the command line to indicate the end of options. +.UNINDENT +.INDENT 0.0 .TP -.B \fBquerylog\fP [(\fIon\fP | \fIoff\fP)] +.B querylog [(on | off)] This command enables or disables query logging. For backward compatibility, this command can also be used without an argument to toggle query logging on and off. @@ -364,14 +416,18 @@ Query logging can also be enabled by explicitly directing the \fBqueries\fP \fBcategory\fP to a \fBchannel\fP in the \fBlogging\fP section of \fBnamed.conf\fP, or by specifying \fBquerylog yes;\fP in the \fBoptions\fP section of \fBnamed.conf\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fBreconfig\fP +.B reconfig This command reloads the configuration file and loads new zones, but does not reload existing zone files even if they have changed. This is faster than a full \fBreload\fP when there is a large number of zones, because it avoids the need to examine the modification times of the zone files. +.UNINDENT +.INDENT 0.0 .TP -.B \fBrecursing\fP +.B recursing This command dumps the list of queries \fBnamed\fP is currently recursing on, and the list of domains to which iterative queries are currently being sent. @@ -390,30 +446,42 @@ cumulative over time; whenever the number of active fetches for a domain drops to zero, the counter for that domain is deleted, and the next time a fetch is sent to that domain, it is recreated with the counters set to zero). +.UNINDENT +.INDENT 0.0 .TP -.B \fBrefresh\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +.B refresh zone [class [view]] This command schedules zone maintenance for the given zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fBreload\fP +.B reload This command reloads the configuration file and zones. +.UNINDENT +.INDENT 0.0 .TP -.B \fBreload\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +.B reload zone [class [view]] This command reloads the given zone. +.UNINDENT +.INDENT 0.0 .TP -.B \fBretransfer\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +.B retransfer zone [class [view]] This command retransfers the given secondary zone from the primary server. .sp If the zone is configured to use \fBinline\-signing\fP, the signed version of the zone is discarded; after the retransfer of the unsigned version is complete, the signed version is regenerated with new signatures. +.UNINDENT +.INDENT 0.0 .TP -.B \fBscan\fP +.B scan This command scans the list of available network interfaces for changes, without performing a full \fBreconfig\fP or waiting for the \fBinterface\-interval\fP timer. +.UNINDENT +.INDENT 0.0 .TP -\fBsecroots\fP [\fB\-\fP] [\fIview\fP ...] +.B secroots [\-] [view ...] This command dumps the security roots (i.e., trust anchors configured via \fBtrust\-anchors\fP, or the \fBmanaged\-keys\fP or \fBtrusted\-keys\fP statements [both deprecated], or \fBdnssec\-validation auto\fP) and negative trust anchors @@ -429,8 +497,10 @@ Otherwise, it is written to the secroots dump file, which defaults to option in \fBnamed.conf\fP\&. .sp See also \fBrndc managed\-keys\fP\&. +.UNINDENT +.INDENT 0.0 .TP -\fBserve\-stale\fP (\fBon\fP | \fBoff\fP | \fBreset\fP | \fBstatus\fP) [\fIclass\fP [\fIview\fP]] +.B 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 \fBnamed.conf\fP\&. .sp @@ -441,13 +511,17 @@ serve\-stale reset\fP restores the setting as configured in \fBnamed.conf\fP\&. \fBrndc serve\-stale status\fP reports whether caching and serving of stale answers is currently enabled or disabled. It also reports the values of \fBstale\-answer\-ttl\fP and \fBmax\-stale\-ttl\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fBshowzone\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +.B showzone zone [class [view]] This command prints the configuration of a running zone. .sp See also \fBrndc zonestatus\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fBsign\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +.B sign zone [class [view]] This command fetches all DNSSEC keys for the given zone from the key directory (see the \fBkey\-directory\fP option in the BIND 9 Administrator Reference Manual). If they are within their publication period, they are merged into @@ -461,8 +535,10 @@ and also requires the zone to be configured to allow dynamic DNS. (See details.) .sp See also \fBrndc loadkeys\fP\&. +.UNINDENT +.INDENT 0.0 .TP -\fBsigning\fP [(\fB\-list\fP | \fB\-clear\fP \fIkeyid/algorithm\fP | \fB\-clear\fP \fIall\fP | \fB\-nsec3param\fP ( \fIparameters\fP | none ) | \fB\-serial\fP \fIvalue\fP ) \fIzone\fP [\fIclass\fP [\fIview\fP]] +.B signing [(\-list | \-clear keyid/algorithm | \-clear all | \-nsec3param (parameters | none) | \-serial value) zone [class [view]] This command lists, edits, or removes the DNSSEC signing\-state records for the specified zone. The status of ongoing DNSSEC operations, such as signing or generating NSEC3 chains, is stored in the zone in the form @@ -506,18 +582,24 @@ replaces it with NSEC. \fBvalue\fP\&. If the value would cause the serial number to go backwards, it is rejected. The primary use of this parameter is to set the serial number on inline signed zones. +.UNINDENT +.INDENT 0.0 .TP -.B \fBstats\fP +.B stats This command writes server statistics to the statistics file. (See the \fBstatistics\-file\fP option in the BIND 9 Administrator Reference Manual.) +.UNINDENT +.INDENT 0.0 .TP -.B \fBstatus\fP +.B status This command displays the status of the server. Note that the number of zones includes the internal \fBbind/CH\fP zone and the default \fB\&./IN\fP hint zone, if there is no explicit root zone configured. +.UNINDENT +.INDENT 0.0 .TP -\fBstop\fP \fB\-p\fP +.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. @@ -525,13 +607,17 @@ This allows an external process to determine when \(ga\(ganamed\fP has completed stopping. .sp See also \fBrndc halt\fP\&. +.UNINDENT +.INDENT 0.0 .TP -\fBsync\fP \fB\-clean\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]] +.B sync \-clean [zone [class [view]]] This command syncs changes in the journal file for a dynamic zone to the master file. If the "\-clean" option is specified, the journal file is also removed. If no zone is specified, then all zones are synced. +.UNINDENT +.INDENT 0.0 .TP -.B \fBtcp\-timeouts\fP [\fIinitial\fP \fIidle\fP \fIkeepalive\fP \fIadvertised\fP] +.B tcp\-timeouts [initial idle keepalive advertised] When called without arguments, this command displays the current values of the \fBtcp\-initial\-timeout\fP, \fBtcp\-idle\-timeout\fP, \fBtcp\-keepalive\-timeout\fP, and \fBtcp\-advertised\-timeout\fP options. @@ -539,8 +625,10 @@ When called with arguments, these values are updated. This allows an administrator to make rapid adjustments when under a denial\-of\-service (DoS) attack. See the descriptions of these options in the BIND 9 Administrator Reference Manual for details of their use. +.UNINDENT +.INDENT 0.0 .TP -.B \fBthaw\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]] +.B thaw [zone [class [view]]] This command enables updates to a frozen dynamic zone. If no zone is specified, then all frozen zones are enabled. This causes the server to reload the zone from disk, and re\-enables dynamic updates after the load has @@ -551,32 +639,44 @@ changes in the zone. Otherwise, if the zone has changed, any existing journal file is removed. .sp See also \fBrndc freeze\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fBtrace\fP +.B trace This command increments the server\(aqs debugging level by one. +.UNINDENT +.INDENT 0.0 .TP -.B \fBtrace\fP \fIlevel\fP +.B trace level This command sets the server\(aqs debugging level to an explicit value. .sp See also \fBrndc notrace\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \fBtsig\-delete\fP \fIkeyname\fP [\fIview\fP] +.B tsig\-delete keyname [view] This command deletes a given TKEY\-negotiated key from the server. This does not apply to statically configured TSIG keys. +.UNINDENT +.INDENT 0.0 .TP -.B \fBtsig\-list\fP +.B tsig\-list This command lists the names of all TSIG keys currently configured for use by \fBnamed\fP in each view. The list includes both statically configured keys and dynamic TKEY\-negotiated keys. +.UNINDENT +.INDENT 0.0 .TP -\fBvalidation\fP (\fBon\fP | \fBoff\fP | \fBstatus\fP) [\fIview\fP ...]\(ga\(ga +.B validation (on | off | status) [view ...] This command enables, disables, or checks the current status of DNSSEC validation. By default, validation is enabled. .sp The cache is flushed when validation is turned on or off to avoid using data that might differ between states. +.UNINDENT +.INDENT 0.0 .TP -.B \fBzonestatus\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +.B zonestatus zone [class [view]] This command displays the current status of the given zone, including the master file name and any include files from which it was loaded, when it was most recently loaded, the current serial number, the number of nodes, @@ -587,7 +687,7 @@ signing, and the scheduled refresh or expiry times for the zone. See also \fBrndc showzone\fP\&. .UNINDENT .sp -\fBrndc\fP commands that specify zone names, such as \fBreload\fP, +\fBrndc\fP commands that specify zone names, such as \fBreload\fP \fBretransfer\fP, or \fBzonestatus\fP, can be ambiguous when applied to zones of type \fBredirect\fP\&. Redirect zones are always called \fB\&.\fP, and can be confused with zones of type \fBhint\fP or with secondary copies of the root diff --git a/doc/man/tsig-keygen.8in b/doc/man/tsig-keygen.8in index 868cc41d6f..b2424663e3 100644 --- a/doc/man/tsig-keygen.8in +++ b/doc/man/tsig-keygen.8in @@ -44,13 +44,15 @@ of the generated key. If no name is specified, the default is \fBtsig\-key\fP\&. .SH OPTIONS .INDENT 0.0 .TP -.B \fB\-a algorithm\fP +.B \-a algorithm This option specifies the algorithm to use for the TSIG key. Available choices are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, and hmac\-sha512. The default is hmac\-sha256. Options are case\-insensitive, and the "hmac\-" prefix may be omitted. +.UNINDENT +.INDENT 0.0 .TP -.B \fB\-h\fP +.B \-h This option prints a short summary of options and arguments. .UNINDENT .SH SEE ALSO From 8537878c01307bf1aa9532b68697a0b021f08e76 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 2 Mar 2022 16:36:34 +0100 Subject: [PATCH 02/11] Add semantic markup for program names into manual pages It allows to cross-reference options in man pages from other documents using :option:`named -g` syntax. --- bin/check/named-checkconf.rst | 1 + bin/check/named-checkzone.rst | 1 + bin/check/named-compilezone.rst | 1 + bin/confgen/ddns-confgen.rst | 1 + bin/confgen/rndc-confgen.rst | 1 + bin/confgen/tsig-keygen.rst | 1 + bin/delv/delv.rst | 1 + bin/dig/dig.rst | 1 + bin/dig/host.rst | 1 + bin/dig/nslookup.rst | 1 + bin/dnssec/dnssec-cds.rst | 1 + bin/dnssec/dnssec-dsfromkey.rst | 1 + bin/dnssec/dnssec-importkey.rst | 1 + bin/dnssec/dnssec-keyfromlabel.rst | 1 + bin/dnssec/dnssec-keygen.rst | 1 + bin/dnssec/dnssec-revoke.rst | 1 + bin/dnssec/dnssec-settime.rst | 1 + bin/dnssec/dnssec-signzone.rst | 1 + bin/dnssec/dnssec-verify.rst | 1 + bin/named/named.rst | 1 + bin/nsupdate/nsupdate.rst | 3 +-- bin/rndc/rndc.conf.rst | 1 + bin/rndc/rndc.rst | 1 + bin/tools/arpaname.rst | 1 + bin/tools/dnstap-read.rst | 1 + bin/tools/mdig.rst | 1 + bin/tools/named-journalprint.rst | 1 + bin/tools/named-nzd2nzf.rst | 1 + bin/tools/named-rrchecker.rst | 1 + bin/tools/nsec3hash.rst | 1 + 30 files changed, 30 insertions(+), 2 deletions(-) diff --git a/bin/check/named-checkconf.rst b/bin/check/named-checkconf.rst index 4bc2deada7..2073db84e7 100644 --- a/bin/check/named-checkconf.rst +++ b/bin/check/named-checkconf.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: named-checkconf .. _man_named-checkconf: named-checkconf - named configuration file syntax checking tool diff --git a/bin/check/named-checkzone.rst b/bin/check/named-checkzone.rst index 19b1d6a4cc..5102f8675b 100644 --- a/bin/check/named-checkzone.rst +++ b/bin/check/named-checkzone.rst @@ -13,6 +13,7 @@ .. BEWARE: Do not forget to edit also named-compilezone.rst! +.. program:: named-checkzone .. _man_named-checkzone: named-checkzone - zone file validation tool diff --git a/bin/check/named-compilezone.rst b/bin/check/named-compilezone.rst index b638cd92fd..82dcb2bcff 100644 --- a/bin/check/named-compilezone.rst +++ b/bin/check/named-compilezone.rst @@ -13,6 +13,7 @@ .. BEWARE: Do not forget to edit also named-checkzone.rst! +.. program:: named-compilezone .. _man_named-compilezone: named-compilezone - zone file converting tool diff --git a/bin/confgen/ddns-confgen.rst b/bin/confgen/ddns-confgen.rst index 467dc82594..719628bc83 100644 --- a/bin/confgen/ddns-confgen.rst +++ b/bin/confgen/ddns-confgen.rst @@ -13,6 +13,7 @@ .. BEWARE: Do not forget to edit also tsig-keygen.rst! +.. program:: ddns-confgen .. _man_ddns-confgen: ddns-confgen - TSIG key generation tool diff --git a/bin/confgen/rndc-confgen.rst b/bin/confgen/rndc-confgen.rst index e689000185..eab7201c29 100644 --- a/bin/confgen/rndc-confgen.rst +++ b/bin/confgen/rndc-confgen.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: rndc-confgen .. _man_rndc-confgen: rndc-confgen - rndc key generation tool diff --git a/bin/confgen/tsig-keygen.rst b/bin/confgen/tsig-keygen.rst index 3ff279ac0b..65582e2f08 100644 --- a/bin/confgen/tsig-keygen.rst +++ b/bin/confgen/tsig-keygen.rst @@ -13,6 +13,7 @@ .. BEWARE: Do not forget to edit also ddns-confgen.rst! +.. program:: tsig-keygen .. _man_tsig-keygen: tsig-keygen - TSIG key generation tool diff --git a/bin/delv/delv.rst b/bin/delv/delv.rst index 6b2469b0f0..2e1669a78d 100644 --- a/bin/delv/delv.rst +++ b/bin/delv/delv.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: delv .. _man_delv: delv - DNS lookup and validation utility diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst index 9fd5eec7ae..26d75046fa 100644 --- a/bin/dig/dig.rst +++ b/bin/dig/dig.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dig .. _man_dig: dig - DNS lookup utility diff --git a/bin/dig/host.rst b/bin/dig/host.rst index 27058eba75..033c9214f3 100644 --- a/bin/dig/host.rst +++ b/bin/dig/host.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: host .. _man_host: host - DNS lookup utility diff --git a/bin/dig/nslookup.rst b/bin/dig/nslookup.rst index 2d1e123828..04cebd6a17 100644 --- a/bin/dig/nslookup.rst +++ b/bin/dig/nslookup.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: nslookup .. _man_nslookup: nslookup - query Internet name servers interactively diff --git a/bin/dnssec/dnssec-cds.rst b/bin/dnssec/dnssec-cds.rst index df471daa46..f7d36fc514 100644 --- a/bin/dnssec/dnssec-cds.rst +++ b/bin/dnssec/dnssec-cds.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dnssec-cds .. _man_dnssec-cds: dnssec-cds - change DS records for a child zone based on CDS/CDNSKEY diff --git a/bin/dnssec/dnssec-dsfromkey.rst b/bin/dnssec/dnssec-dsfromkey.rst index a9b010ebeb..8f29a05343 100644 --- a/bin/dnssec/dnssec-dsfromkey.rst +++ b/bin/dnssec/dnssec-dsfromkey.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dnssec-dsfromkey .. _man_dnssec-dsfromkey: dnssec-dsfromkey - DNSSEC DS RR generation tool diff --git a/bin/dnssec/dnssec-importkey.rst b/bin/dnssec/dnssec-importkey.rst index 969791e139..093ca31eb3 100644 --- a/bin/dnssec/dnssec-importkey.rst +++ b/bin/dnssec/dnssec-importkey.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dnssec-importkey .. _man_dnssec-importkey: dnssec-importkey - import DNSKEY records from external systems so they can be managed diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst index 3f635e74d1..668929f665 100644 --- a/bin/dnssec/dnssec-keyfromlabel.rst +++ b/bin/dnssec/dnssec-keyfromlabel.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dnssec-keyfromlabel .. _man_dnssec-keyfromlabel: dnssec-keyfromlabel - DNSSEC key generation tool diff --git a/bin/dnssec/dnssec-keygen.rst b/bin/dnssec/dnssec-keygen.rst index 65f0beb09a..536f6a67e6 100644 --- a/bin/dnssec/dnssec-keygen.rst +++ b/bin/dnssec/dnssec-keygen.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dnssec-keygen .. _man_dnssec-keygen: dnssec-keygen: DNSSEC key generation tool diff --git a/bin/dnssec/dnssec-revoke.rst b/bin/dnssec/dnssec-revoke.rst index 0d748f5b0a..ef41812ee8 100644 --- a/bin/dnssec/dnssec-revoke.rst +++ b/bin/dnssec/dnssec-revoke.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dnssec-revoke .. _man_dnssec-revoke: dnssec-revoke - set the REVOKED bit on a DNSSEC key diff --git a/bin/dnssec/dnssec-settime.rst b/bin/dnssec/dnssec-settime.rst index e21e57acae..f6a04f317a 100644 --- a/bin/dnssec/dnssec-settime.rst +++ b/bin/dnssec/dnssec-settime.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dnssec-settime .. _man_dnssec-settime: dnssec-settime: set the key timing metadata for a DNSSEC key diff --git a/bin/dnssec/dnssec-signzone.rst b/bin/dnssec/dnssec-signzone.rst index 4288acd496..6675f3d076 100644 --- a/bin/dnssec/dnssec-signzone.rst +++ b/bin/dnssec/dnssec-signzone.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dnssec-signzone .. _man_dnssec-signzone: dnssec-signzone - DNSSEC zone signing tool diff --git a/bin/dnssec/dnssec-verify.rst b/bin/dnssec/dnssec-verify.rst index 5d8c7c0b56..c0806c6d6d 100644 --- a/bin/dnssec/dnssec-verify.rst +++ b/bin/dnssec/dnssec-verify.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dnssec-verify .. _man_dnssec-verify: dnssec-verify - DNSSEC zone verification tool diff --git a/bin/named/named.rst b/bin/named/named.rst index b9cd8ed503..43a04e2193 100644 --- a/bin/named/named.rst +++ b/bin/named/named.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: named .. _man_named: named - Internet domain name server diff --git a/bin/nsupdate/nsupdate.rst b/bin/nsupdate/nsupdate.rst index 1bd4cdedc8..7c033f8501 100644 --- a/bin/nsupdate/nsupdate.rst +++ b/bin/nsupdate/nsupdate.rst @@ -9,8 +9,7 @@ .. See the COPYRIGHT file distributed with this work for additional .. information regarding copyright ownership. -.. highlight: console - +.. program:: nsupdate .. _man_nsupdate: nsupdate - dynamic DNS update utility diff --git a/bin/rndc/rndc.conf.rst b/bin/rndc/rndc.conf.rst index b02e780351..0824f71bcf 100644 --- a/bin/rndc/rndc.conf.rst +++ b/bin/rndc/rndc.conf.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: rndc.conf .. _man_rndc.conf: rndc.conf - rndc configuration file diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst index 0f76030534..5b92f72478 100644 --- a/bin/rndc/rndc.rst +++ b/bin/rndc/rndc.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: rndc .. _man_rndc: rndc - name server control utility diff --git a/bin/tools/arpaname.rst b/bin/tools/arpaname.rst index c932f6e33f..ffe711f732 100644 --- a/bin/tools/arpaname.rst +++ b/bin/tools/arpaname.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: arpaname .. _man_arpaname: arpaname - translate IP addresses to the corresponding ARPA names diff --git a/bin/tools/dnstap-read.rst b/bin/tools/dnstap-read.rst index dc04f4ec1c..af726f3fee 100644 --- a/bin/tools/dnstap-read.rst +++ b/bin/tools/dnstap-read.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: dnstap-read .. _man_dnstap-read: dnstap-read - print dnstap data in human-readable form diff --git a/bin/tools/mdig.rst b/bin/tools/mdig.rst index eb6fbdb459..fab3ee1f76 100644 --- a/bin/tools/mdig.rst +++ b/bin/tools/mdig.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: mdig .. _man_mdig: mdig - DNS pipelined lookup utility diff --git a/bin/tools/named-journalprint.rst b/bin/tools/named-journalprint.rst index 1b9b057bd7..2fb08f5cac 100644 --- a/bin/tools/named-journalprint.rst +++ b/bin/tools/named-journalprint.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: named-journalprint .. _man_named-journalprint: named-journalprint - print zone journal in human-readable form diff --git a/bin/tools/named-nzd2nzf.rst b/bin/tools/named-nzd2nzf.rst index 634cc85561..2562d1c116 100644 --- a/bin/tools/named-nzd2nzf.rst +++ b/bin/tools/named-nzd2nzf.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: named-nzd2nzf .. _man_named-nzd2nzf: named-nzd2nzf - convert an NZD database to NZF text format diff --git a/bin/tools/named-rrchecker.rst b/bin/tools/named-rrchecker.rst index 7ea9c39de8..84ab388093 100644 --- a/bin/tools/named-rrchecker.rst +++ b/bin/tools/named-rrchecker.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: named-rrchecker .. _man_named-rrchecker: named-rrchecker - syntax checker for individual DNS resource records diff --git a/bin/tools/nsec3hash.rst b/bin/tools/nsec3hash.rst index 9facfc773e..58550e1b25 100644 --- a/bin/tools/nsec3hash.rst +++ b/bin/tools/nsec3hash.rst @@ -11,6 +11,7 @@ .. highlight: console +.. program:: nsec3hash .. _man_nsec3hash: nsec3hash - generate NSEC3 hash From 5f0ee7c303f6d22ea8eaf9d4822f84bf20755658 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 3 Mar 2022 10:07:10 +0100 Subject: [PATCH 03/11] Fix rndc command in release notes for 9.17.12 rndc checkds does not exist, it should have been rndc dnssec Related: #2488, !4813 --- doc/notes/notes-9.17.12.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/notes/notes-9.17.12.rst b/doc/notes/notes-9.17.12.rst index 47ed9019d7..6035d1aafd 100644 --- a/doc/notes/notes-9.17.12.rst +++ b/doc/notes/notes-9.17.12.rst @@ -79,7 +79,7 @@ Bug Fixes - Zones using KASP could not be thawed after they were frozen using ``rndc freeze``. This has been fixed. :gl:`#2523` -- After ``rndc checkds -checkds`` or ``rndc dnssec -rollover`` is used, +- After ``rndc dnssec -checkds`` or ``rndc dnssec -rollover`` is used, ``named`` now immediately attempts to reconfigure zone keys. This change prevents unnecessary key rollover delays. :gl:`#2488` From a85df3ff9c55e8798fcc31e175d2037e8d7e5cf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 2 Mar 2022 16:54:31 +0100 Subject: [PATCH 04/11] Add hyperlinks from program options to definition in man pages Side-effect of hyperlinking is that typos in program and option names are now detected by Sphinx. Candidate -options were detected using: find -name *.rst | xargs grep '``-[^`]' and then modified from ``-o`` to :option:`-o` using regex s/``\(-[^`]\+\)``/:option:`\1`/ + manual modifications where necessary. Non-hyphenated options were detected by looking at context around program names: find bin -name *.rst | xargs -I{} -n1 basename {} .rst | sort -u and grepping for program name with trailing whitespace. Stand-alone program names like ``named`` are not hyperlinked in this commit. --- bin/check/named-checkconf.rst | 4 +- bin/check/named-checkzone.rst | 2 +- bin/check/named-compilezone.rst | 2 +- bin/confgen/ddns-confgen.rst | 10 +-- bin/confgen/rndc-confgen.rst | 14 +-- bin/delv/delv.rst | 20 ++--- bin/dig/dig.rst | 18 ++-- bin/dig/host.rst | 34 +++---- bin/dnssec/dnssec-cds.rst | 20 ++--- bin/dnssec/dnssec-dsfromkey.rst | 20 ++--- bin/dnssec/dnssec-importkey.rst | 2 +- bin/dnssec/dnssec-keyfromlabel.rst | 19 ++-- bin/dnssec/dnssec-keygen.rst | 26 +++--- bin/dnssec/dnssec-settime.rst | 20 ++--- bin/dnssec/dnssec-signzone.rst | 22 ++--- bin/dnssec/dnssec-verify.rst | 7 +- bin/named/named.rst | 16 ++-- bin/nsupdate/nsupdate.rst | 31 ++++--- bin/rndc/rndc.conf.rst | 2 +- bin/rndc/rndc.rst | 36 ++++---- bin/tools/dnstap-read.rst | 2 +- bin/tools/mdig.rst | 2 +- bin/tools/named-nzd2nzf.rst | 2 +- doc/arm/advanced.rst | 24 ++--- doc/arm/catz.rst | 12 +-- doc/arm/configuration.rst | 10 +-- doc/arm/dnssec.rst | 12 +-- doc/arm/managed-keys.rst | 2 +- doc/arm/pkcs11.rst | 2 +- doc/arm/reference.rst | 104 +++++++++++----------- doc/arm/security.rst | 4 +- doc/arm/troubleshooting.rst | 2 +- doc/dnssec-guide/advanced-discussions.rst | 10 +-- doc/dnssec-guide/getting-started.rst | 6 +- doc/dnssec-guide/recipes.rst | 12 +-- doc/dnssec-guide/signing.rst | 4 +- doc/dnssec-guide/validation.rst | 2 +- doc/man/ddns-confgen.8in | 8 +- doc/man/delv.1in | 20 ++--- doc/man/dig.1in | 18 ++-- doc/man/dnssec-cds.1in | 18 ++-- doc/man/dnssec-dsfromkey.1in | 20 ++--- doc/man/dnssec-importkey.1in | 2 +- doc/man/dnssec-keyfromlabel.1in | 18 ++-- doc/man/dnssec-keygen.1in | 24 ++--- doc/man/dnssec-settime.1in | 20 ++--- doc/man/dnssec-signzone.1in | 25 +++--- doc/man/dnssec-verify.1in | 6 +- doc/man/dnstap-read.1in | 2 +- doc/man/host.1in | 34 +++---- doc/man/mdig.1in | 2 +- doc/man/named-checkconf.1in | 4 +- doc/man/named-checkzone.1in | 2 +- doc/man/named-compilezone.1in | 2 +- doc/man/named.8in | 16 ++-- doc/man/nsupdate.1in | 33 ++++--- doc/man/rndc-confgen.8in | 12 +-- doc/man/rndc.8in | 36 ++++---- doc/notes/notes-9.17.0.rst | 2 +- doc/notes/notes-9.17.11.rst | 2 +- doc/notes/notes-9.17.12.rst | 4 +- doc/notes/notes-9.17.13.rst | 4 +- doc/notes/notes-9.17.18.rst | 2 +- doc/notes/notes-9.17.2.rst | 8 +- doc/notes/notes-9.17.20.rst | 2 +- doc/notes/notes-9.17.21.rst | 4 +- doc/notes/notes-9.17.3.rst | 6 +- doc/notes/notes-9.17.4.rst | 2 +- doc/notes/notes-9.17.5.rst | 2 +- doc/notes/notes-9.17.6.rst | 4 +- 70 files changed, 464 insertions(+), 437 deletions(-) diff --git a/bin/check/named-checkconf.rst b/bin/check/named-checkconf.rst index 2073db84e7..99b15d41df 100644 --- a/bin/check/named-checkconf.rst +++ b/bin/check/named-checkconf.rst @@ -65,7 +65,7 @@ Options .. option:: -p This option prints out the ``named.conf`` and included files in canonical form if - no errors were detected. See also the ``-x`` option. + no errors were detected. See also the :option:`-x` option. .. option:: -t directory @@ -84,7 +84,7 @@ Options (``?``). This allows the contents of ``named.conf`` and related files to be shared - for example, when submitting bug reports - without compromising private data. This option cannot be used without - ``-p``. + :option:`-p`. .. option:: -z diff --git a/bin/check/named-checkzone.rst b/bin/check/named-checkzone.rst index 5102f8675b..25b9585a95 100644 --- a/bin/check/named-checkzone.rst +++ b/bin/check/named-checkzone.rst @@ -61,7 +61,7 @@ Options .. option:: -J filename When loading the zone file, this option tells ``named`` to read the journal from the given file, if - it exists. This implies ``-j``. + it exists. This implies :option:`-j`. .. option:: -c class diff --git a/bin/check/named-compilezone.rst b/bin/check/named-compilezone.rst index 82dcb2bcff..8d947c7407 100644 --- a/bin/check/named-compilezone.rst +++ b/bin/check/named-compilezone.rst @@ -63,7 +63,7 @@ Options .. option:: -J filename When loading the zone file, this option tells ``named`` to read the journal from the given file, if - it exists. This implies ``-j``. + it exists. This implies :option:`-j`. .. option:: -c class diff --git a/bin/confgen/ddns-confgen.rst b/bin/confgen/ddns-confgen.rst index 719628bc83..2a290bcc57 100644 --- a/bin/confgen/ddns-confgen.rst +++ b/bin/confgen/ddns-confgen.rst @@ -30,7 +30,7 @@ Description The resulting keys can be used, for example, to secure dynamic DNS updates to a zone, or for the ``rndc`` command channel. -The key name can specified using ``-k`` parameter and defaults to ``ddns-key``. +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, including an example ``update-policy`` statement. @@ -38,7 +38,7 @@ including an example ``update-policy`` statement. command-channel security.) Note that ``named`` itself can configure a local DDNS key for use with -``nsupdate -l``; it does this when a zone is configured with +:option:`nsupdate -l`; it does this when a zone is configured with ``update-policy local;``. ``ddns-confgen`` is only needed when a more elaborate configuration is required: for instance, if ``nsupdate`` is to be used from a remote system. @@ -60,7 +60,7 @@ Options .. option:: -k keyname This option specifies the key name of the DDNS authentication key. The - default is ``ddns-key`` when neither the ``-s`` nor ``-z`` option is + default is ``ddns-key`` when neither the :option:`-s` nor :option:`-z` option is specified; otherwise, the default is ``ddns-key`` as a separate label followed by the argument of the option, e.g., ``ddns-key.example.com.`` The key name must have the format of a valid domain name, consisting of @@ -79,7 +79,7 @@ Options 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 - name. This option cannot be used with the ``-z`` option. + name. This option cannot be used with the :option:`-z` option. .. option:: -z zone @@ -87,7 +87,7 @@ Options dynamic updates of a zone. The example ``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 ``-s`` option. + This option cannot be used with the :option:`-s` option. See Also ~~~~~~~~ diff --git a/bin/confgen/rndc-confgen.rst b/bin/confgen/rndc-confgen.rst index eab7201c29..5a5925fe77 100644 --- a/bin/confgen/rndc-confgen.rst +++ b/bin/confgen/rndc-confgen.rst @@ -28,7 +28,7 @@ Description ``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`` -by hand. Alternatively, it can be run with the ``-a`` option to set up a +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 ``controls`` statement altogether. @@ -44,8 +44,8 @@ Options the local host with no further configuration. If a more elaborate configuration than that generated by - ``rndc-confgen -a`` is required, for example if rndc is to be used - remotely, run ``rndc-confgen`` without the ``-a`` option + :option:`rndc-confgen -a` is required, for example if rndc is to be used + remotely, run ``rndc-confgen`` without the :option:`-a` option and set up ``rndc.conf`` and ``named.conf`` as directed. .. option:: -A algorithm @@ -61,7 +61,7 @@ Options .. option:: -c keyfile - This option is used with the ``-a`` option to specify an alternate location for + This option is used with the :option:`-a` option to specify an alternate location for ``rndc.key``. .. option:: -h @@ -91,15 +91,15 @@ Options .. option:: -t chrootdir - This option is used with the ``-a`` option to specify a directory where ``named`` + This option is used with the :option:`-a` option to specify a directory where ``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``. .. option:: -u user - This option is used with the ``-a`` option to set the owner of the generated ``rndc.key`` file. - If ``-t`` is also specified, only the file in the chroot + This option is used with the :option:`-a` option to set the owner of the generated ``rndc.key`` file. + If :option:`-t` is also specified, only the file in the chroot area has its owner changed. Examples diff --git a/bin/delv/delv.rst b/bin/delv/delv.rst index 2e1669a78d..466bf5eb70 100644 --- a/bin/delv/delv.rst +++ b/bin/delv/delv.rst @@ -80,7 +80,7 @@ where: If no ``server`` argument is provided, ``delv`` consults ``/etc/resolv.conf``; if an address is found there, it queries the - name server at that address. If either of the ``-4`` or ``-6`` + name server at that address. If either of the :option:`-4` or :option:`-6` options is in use, then only addresses for the corresponding transport are tried. If no usable addresses are found, ``delv`` sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1 @@ -163,7 +163,7 @@ Options .. option:: -q name This option sets the query name to ``name``. While the query name can be - specified without using the ``-q`` option, it is sometimes necessary to + specified without using the :option:`-q` option, it is sometimes necessary to disambiguate names from types or classes (for example, when looking up the name "ns", which could be misinterpreted as the type NS, or "ch", which could be misinterpreted as class CH). @@ -172,11 +172,11 @@ Options This option sets the query type to ``type``, which can be any valid query type supported in BIND 9 except for zone transfer types AXFR and IXFR. As - with ``-q``, this is useful to distinguish query-name types or classes + with :option:`-q`, this is useful to distinguish query-name types or classes when they are ambiguous. It is sometimes necessary to disambiguate names from types. - The default query type is "A", unless the ``-x`` option is supplied + The default query type is "A", unless the :option:`-x` option is supplied to indicate a reverse lookup, in which case it is "PTR". .. option:: -v @@ -187,7 +187,7 @@ Options This option performs a reverse lookup, mapping an address to a name. ``addr`` is an IPv4 address in dotted-decimal notation, or a colon-delimited - IPv6 address. When ``-x`` is used, there is no need to provide the + IPv6 address. When :option:`-x` is used, there is no need to provide the ``name`` or ``type`` arguments; ``delv`` automatically performs a lookup for a name like ``11.12.13.10.in-addr.arpa`` and sets the query type to PTR. IPv6 addresses are looked up using nibble format @@ -243,7 +243,7 @@ assign values to options like the timeout interval. They have the form This is equivalent to setting the debug level to 1 in the "resolver" logging category. Setting the systemwide debug level to 1 using the - ``-d`` option produces the same output, but affects other + :option:`-d` option produces the same output, but affects other logging categories as well. .. option:: +[no]mtrace @@ -254,7 +254,7 @@ assign values to options like the timeout interval. They have the form This is equivalent to setting the debug level to 10 for the "packets" module of the "resolver" logging category. Setting the systemwide - debug level to 10 using the ``-d`` option produces the same + debug level to 10 using the :option:`-d` option produces the same output, but affects other logging categories as well. .. option:: +[no]vtrace @@ -265,7 +265,7 @@ assign values to options like the timeout interval. They have the form This is equivalent to setting the debug level to 3 for the "validator" module of the "dnssec" logging category. Setting the - systemwide debug level to 3 using the ``-d`` option produces the + systemwide debug level to 3 using the :option:`-d` option produces the same output, but affects other logging categories as well. .. option:: +[no]short @@ -324,7 +324,7 @@ assign values to options like the timeout interval. They have the form The default is to do so. Note that (unlike in ``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 ``-i`` or + always occurs unless suppressed by the use of :option:`-i` or ``+noroot``. .. option:: +[no]root[=ROOT] @@ -332,7 +332,7 @@ assign values to options like the timeout interval. They have the form This option indicates whether to perform conventional DNSSEC validation, and if so, specifies the name of a trust anchor. The default is to validate using a trust anchor of "." (the root zone), for which there is a built-in key. If - specifying a different trust anchor, then ``-a`` must be used to specify a + specifying a different trust anchor, then :option:`-a` must be used to specify a file containing the key. .. option:: +[no]tcp diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst index 26d75046fa..b4f4295e0a 100644 --- a/bin/dig/dig.rst +++ b/bin/dig/dig.rst @@ -51,12 +51,12 @@ performs an NS query for "." (the root). It is possible to set per-user defaults for ``dig`` via ``${HOME}/.digrc``. This file is read and any options in it are applied -before the command-line arguments. The ``-r`` option disables this +before the command-line arguments. The :option:`-r` option disables this feature, for scripts that need predictable behavior. The IN and CH class names overlap with the IN and CH top-level domain -names. Either use the ``-t`` and ``-c`` options to specify the type and -class, use the ``-q`` to specify the domain name, or use "IN." and +names. Either use the :option:`-t` and :option:`-c` options to specify the type and +class, use the :option:`-q` to specify the domain name, or use "IN." and "CH." when looking up these top-level domains. Simple Usage @@ -80,7 +80,7 @@ where: If no ``server`` argument is provided, ``dig`` consults ``/etc/resolv.conf``; if an address is found there, it queries the - name server at that address. If either of the ``-4`` or ``-6`` + name server at that address. If either of the :option:`-4` or :option:`-6` options are in use, then only addresses for the corresponding transport are tried. If no usable addresses are found, ``dig`` sends the query to the local host. The reply from the name server @@ -160,7 +160,7 @@ Options This option indicates the resource record type to query, which can be any valid query type. If it is a resource record type supported in BIND 9, it can be given by the type mnemonic (such as ``NS`` or ``AAAA``). The default query type is - ``A``, unless the ``-x`` option is supplied to indicate a reverse + ``A``, unless the :option:`-x` option is supplied to indicate a reverse lookup. A zone transfer can be requested by specifying a type of AXFR. When an incremental zone transfer (IXFR) is required, set the ``type`` to ``ixfr=N``. The incremental zone transfer contains @@ -183,7 +183,7 @@ Options This option sets simplified reverse lookups, for mapping addresses to names. The ``addr`` is an IPv4 address in dotted-decimal notation, or a - colon-delimited IPv6 address. When the ``-x`` option is used, there is no + colon-delimited IPv6 address. When the :option:`-x` option is used, there is no need to provide the ``name``, ``class``, and ``type`` arguments. ``dig`` automatically performs a lookup for a name like ``94.2.0.192.in-addr.arpa`` and sets the query type and class to PTR @@ -200,8 +200,8 @@ Options not specified, the default is ``hmac-md5``; if MD5 was disabled, the default is ``hmac-sha256``. -.. note:: Only the ``-k`` option should be used, rather than the ``-y`` option, - because with ``-y`` the shared secret is supplied as a command-line +.. note:: Only the :option:`-k` option should be used, rather than the :option:`-y` option, + because with :option:`-y` the shared secret is supplied as a command-line argument in clear text. This may be visible in the output from ``ps1`` or in a history file maintained by the user's shell. @@ -694,7 +694,7 @@ Multiple Queries ~~~~~~~~~~~~~~~~ The BIND 9 implementation of ``dig`` supports specifying multiple -queries on the command line (in addition to supporting the ``-f`` batch +queries on the command line (in addition to supporting the :option:`-f` batch file option). Each of those queries can be supplied with its own set of flags, options, and query options. diff --git a/bin/dig/host.rst b/bin/dig/host.rst index 033c9214f3..55ca5baec9 100644 --- a/bin/dig/host.rst +++ b/bin/dig/host.rst @@ -42,20 +42,20 @@ Options .. option:: -4 - This option specifies that only IPv4 should be used for query transport. See also the ``-6`` option. + This option specifies that only IPv4 should be used for query transport. See also the :option:`-6` option. .. option:: -6 - This option specifies that only IPv6 should be used for query transport. See also the ``-4`` option. + This option specifies that only IPv6 should be used for query transport. See also the :option:`-4` option. .. option:: -a - The ``-a`` ("all") option is normally equivalent to ``-v -t ANY``. It - also affects the behavior of the ``-l`` list zone option. + The :option:`-a` ("all") option is normally equivalent to :option:`-v` :option:`-t ANY <-t>`. It + also affects the behavior of the :option:`-l` list zone option. .. option:: -A - The ``-A`` ("almost all") option is equivalent to ``-a``, except that RRSIG, + The :option:`-A` ("almost all") option is equivalent to :option:`-a`, except that RRSIG, NSEC, and NSEC3 records are omitted from the output. .. option:: -c class @@ -72,14 +72,14 @@ Options .. option:: -d - This option prints debugging traces, and is equivalent to the ``-v`` verbose option. + This option prints debugging traces, and is equivalent to the :option:`-v` verbose option. .. option:: -l This option tells ``named`` to list the zone, meaning the ``host`` command performs a zone transfer of zone ``name`` and prints out the NS, PTR, and address records (A/AAAA). - Together, the ``-l -a`` options print all records in the zone. + Together, the :option:`-l` :option:`-a` options print all records in the zone. .. option:: -N ndots @@ -98,7 +98,7 @@ Options This option specifies a non-recursive query; setting this option clears the RD (recursion desired) bit in the query. This means that the name server - receiving the query does not attempt to resolve ``name``. The ``-r`` + receiving the query does not attempt to resolve ``name``. The :option:`-r` option enables ``host`` to mimic the behavior of a name server by making non-recursive queries, and expecting to receive answers to those queries that can be referrals to other name servers. @@ -122,31 +122,31 @@ Options When no query type is specified, ``host`` automatically selects an appropriate query type. By default, it looks for A, AAAA, and MX - records. If the ``-C`` option is given, queries are made for SOA + records. If the :option:`-C` option is given, queries are made for SOA records. If ``name`` is a dotted-decimal IPv4 address or colon-delimited IPv6 address, ``host`` queries for PTR records. If a query type of IXFR is chosen, the starting serial number can be specified by appending an equals sign (=), followed by the starting serial - number, e.g., ``-t IXFR=12345678``. + number, e.g., :option:`-t IXFR=12345678 <-t>`. -.. option:: -T``; ``-U +.. option:: -T, -U This option specifies TCP or UDP. By default, ``host`` uses UDP when making queries; the - ``-T`` option makes it use a TCP connection when querying the name + :option:`-T` option makes it use a TCP connection when querying the name server. TCP is automatically selected for queries that require it, such as zone transfer (AXFR) requests. Type ``ANY`` queries default - to TCP, but can be forced to use UDP initially via ``-U``. + to TCP, but can be forced to use UDP initially via :option:`-U`. .. option:: -m flag This option sets memory usage debugging: the flag can be ``record``, ``usage``, or - ``trace``. The ``-m`` option can be specified more than once to set + ``trace``. The :option:`-m` option can be specified more than once to set multiple flags. .. option:: -v - This option sets verbose output, and is equivalent to the ``-d`` debug option. Verbose output + This option sets verbose output, and is equivalent to the :option:`-d` debug option. Verbose output can also be enabled by setting the ``debug`` option in ``/etc/resolv.conf``. @@ -157,7 +157,7 @@ Options .. option:: -w This option sets "wait forever": the query timeout is set to the maximum possible. See - also the ``-W`` option. + also the :option:`-W` option. .. option:: -W wait @@ -168,7 +168,7 @@ Options seconds for TCP connections. These defaults can be overridden by the ``timeout`` option in ``/etc/resolv.conf``. - See also the ``-w`` option. + See also the :option:`-w` option. IDN Support ~~~~~~~~~~~ diff --git a/bin/dnssec/dnssec-cds.rst b/bin/dnssec/dnssec-cds.rst index f7d36fc514..31cfbb3b40 100644 --- a/bin/dnssec/dnssec-cds.rst +++ b/bin/dnssec/dnssec-cds.rst @@ -33,9 +33,9 @@ its key-signing keys (KSKs); by polling periodically with ``dnssec-cds``, the parent can keep the DS records up-to-date and enable automatic rolling of KSKs. -Two input files are required. The ``-f child-file`` option specifies a +Two input files are required. The :option:`-f child-file <-f>` option specifies a file containing the child's CDS and/or CDNSKEY records, plus RRSIG and -DNSKEY records so that they can be authenticated. The ``-d path`` option +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 @@ -49,7 +49,7 @@ is typically the pre-existing KSK. For protection against replay attacks, the signatures on the child records must not be older than they were on a previous run of ``dnssec-cds``. Their age is obtained from the modification time of the -``dsset-`` file, or from the ``-s`` option. +``dsset-`` file, or from the :option:`-s` option. To protect against breaking the delegation, ``dnssec-cds`` ensures that the DNSKEY RRset can be verified by every key algorithm in the new DS @@ -57,7 +57,7 @@ RRset, and that the same set of keys are covered by every DS digest type. By default, replacement DS records are written to the standard output; -with the ``-i`` option the input file is overwritten in place. The +with the :option:`-i` option the input file is overwritten in place. The replacement DS records are the same as the existing records, when no change is required. The output can be empty if the CDS/CDNSKEY records specify that the child zone wants to be insecure. @@ -66,8 +66,8 @@ specify that the child zone wants to be insecure. Be careful not to delete the DS records when ``dnssec-cds`` fails! -Alternatively, ``dnssec-cds -u`` writes an ``nsupdate`` script to the -standard output. The ``-u`` and ``-i`` options can be used together to +Alternatively, :option`dnssec-cds -u` writes an ``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. Options @@ -107,7 +107,7 @@ Options To protect against replay attacks, child records are rejected if they were signed earlier than the modification time of the ``dsset-`` - file. This can be adjusted with the ``-s`` option. + file. This can be adjusted with the :option:`-s` option. .. option:: -f child-file @@ -117,12 +117,12 @@ Options The examples below describe how to generate this file. -.. option:: -iextension +.. option:: -i extension This option updates the ``dsset-`` file in place, instead of writing DS records to the standard output. - There must be no space between the ``-i`` and the extension. If + There must be no space between the :option:`-i` and the extension. If no extension is provided, the old ``dsset-`` is discarded. If an extension is present, a backup of the old ``dsset-`` file is kept with the extension appended to its filename. @@ -158,7 +158,7 @@ Options needed. Note: The TTL of new records needs to be specified: it can be done in the - original ``dsset-`` file, with the ``-T`` option, or using the + original ``dsset-`` file, with the :option:`-T` option, or using the ``nsupdate`` ``ttl`` command. .. option:: -V diff --git a/bin/dnssec/dnssec-dsfromkey.rst b/bin/dnssec/dnssec-dsfromkey.rst index 8f29a05343..ca8d54a632 100644 --- a/bin/dnssec/dnssec-dsfromkey.rst +++ b/bin/dnssec/dnssec-dsfromkey.rst @@ -32,10 +32,10 @@ Description ~~~~~~~~~~~ The ``dnssec-dsfromkey`` command outputs DS (Delegation Signer) resource records -(RRs), or CDS (Child DS) RRs with the ``-C`` option. +(RRs), or CDS (Child DS) RRs with the :option:`-C` option. By default, only KSKs are converted (keys with flags = 257). The -``-A`` option includes ZSKs (flags = 256). Revoked keys are never +:option:`-A` option includes ZSKs (flags = 256). Revoked keys are never included. The input keys can be specified in a number of ways: @@ -43,22 +43,22 @@ The input keys can be specified in a number of ways: By default, ``dnssec-dsfromkey`` reads a key file named in the format ``Knnnn.+aaa+iiiii.key``, as generated by ``dnssec-keygen``. -With the ``-f file`` option, ``dnssec-dsfromkey`` reads keys from a zone +With the :option:`-f file <-f>` option, ``dnssec-dsfromkey`` reads keys from a zone file or partial zone file (which can contain just the DNSKEY records). -With the ``-s`` option, ``dnssec-dsfromkey`` reads a ``keyset-`` file, -as generated by ``dnssec-keygen`` ``-C``. +With the :option:`-s` option, ``dnssec-dsfromkey`` reads a ``keyset-`` file, +as generated by ``dnssec-keygen`` :option:`-C`. Options ~~~~~~~ .. option:: -1 - This option is an abbreviation for ``-a SHA1``. + This option is an abbreviation for :option:`-a SHA1 <-a>`. .. option:: -2 - This option is an abbreviation for ``-a SHA-256``. + This option is an abbreviation for :option:`-a SHA-256 <-a>`. .. option:: -a algorithm @@ -74,12 +74,12 @@ Options This option indicates that ZSKs are to be included when generating DS records. Without this option, only keys which have the KSK flag set are converted to DS records and - printed. This option is only useful in ``-f`` zone file mode. + printed. This option is only useful in :option:`-f` zone file mode. .. option:: -c class - This option specifies the DNS class; the default is IN. This option is only useful in ``-s`` keyset - or ``-f`` zone file mode. + This option specifies the DNS class; the default is IN. This option is only useful in :option:`-s` keyset + or :option:`-f` zone file mode. .. option:: -C diff --git a/bin/dnssec/dnssec-importkey.rst b/bin/dnssec/dnssec-importkey.rst index 093ca31eb3..e22f06f032 100644 --- a/bin/dnssec/dnssec-importkey.rst +++ b/bin/dnssec/dnssec-importkey.rst @@ -35,7 +35,7 @@ input, in which case both .key and .private files are generated. The newly created .private file does *not* contain private key data, and cannot be used for signing. However, having a .private file makes it -possible to set publication (``-P``) and deletion (``-D``) times for the +possible to set publication (:option:`-P`) and deletion (:option:`-D`) times for the key, which means the public key can be added to and removed from the DNSKEY RRset on schedule even if the true private key is stored offline. diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst index 668929f665..98d94876b4 100644 --- a/bin/dnssec/dnssec-keyfromlabel.rst +++ b/bin/dnssec/dnssec-keyfromlabel.rst @@ -45,18 +45,18 @@ Options ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. If no algorithm is specified, RSASHA1 is used by default - unless the ``-3`` option is specified, in which case NSEC3RSASHA1 - is used instead. (If ``-3`` is used and an algorithm is + unless the :option:`-3` option is specified, in which case NSEC3RSASHA1 + is used instead. (If :option:`-3` is used and an algorithm is specified, that algorithm is checked for compatibility with NSEC3.) These values are case-insensitive. In some cases, abbreviations are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for - ECDSAP384SHA384. If RSASHA1 is specified along with the ``-3`` + ECDSAP384SHA384. If RSASHA1 is specified along with the :option:`-3` option, then NSEC3RSASHA1 is used instead. Since BIND 9.12.0, this option is mandatory except when using the - ``-S`` option, which copies the algorithm from the predecessory key. + :option:`-S` option, which copies the algorithm from the predecessory key. Previously, the default for newly generated keys was RSASHA1. .. option:: -3 @@ -98,7 +98,7 @@ Options date in the metadata stored with the private key; other dates may be set there as well, including publication date, activation date, etc. Keys that include this data may be incompatible with older versions of - BIND; the ``-C`` option suppresses them. + BIND; the :option:`-C` option suppresses them. .. option:: -c class @@ -113,7 +113,7 @@ Options .. option:: -G This option generates a key, but does not publish it or sign with it. This option is - incompatible with ``-P`` and ``-A``. + incompatible with :option:`-P` and :option:`-A`. .. option:: -h @@ -128,7 +128,8 @@ Options This option generates KEY records rather than DNSKEY records. -``-L`` ttl +.. option:: -L ttl + This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in @@ -189,7 +190,7 @@ explicitly prevent a date from being set, use ``none`` or ``never``. This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used - to sign it. If not set, and if the ``-G`` option has not been used, the + to sign it. If not set, and if the :option:`-G` option has not been used, the default is the current date. .. option:: -P sync date/offset @@ -201,7 +202,7 @@ explicitly prevent a date from being set, use ``none`` or ``never``. This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. If not set, - and if the ``-G`` option has not been used, the default is the current date. + and if the :option:`-G` option has not been used, the default is the current date. .. option:: -R date/offset diff --git a/bin/dnssec/dnssec-keygen.rst b/bin/dnssec/dnssec-keygen.rst index 536f6a67e6..78358294d5 100644 --- a/bin/dnssec/dnssec-keygen.rst +++ b/bin/dnssec/dnssec-keygen.rst @@ -50,14 +50,14 @@ Options ``algorithm`` must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. For TKEY, the value must be DH (Diffie-Hellman); specifying this value - automatically sets the ``-T KEY`` option as well. + automatically sets the :option:`-T KEY <-T>` option as well. These values are case-insensitive. In some cases, abbreviations are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for - ECDSAP384SHA384. If RSASHA1 is specified along with the ``-3`` + ECDSAP384SHA384. If RSASHA1 is specified along with the :option:`-3` option, NSEC3RSASHA1 is used instead. - This parameter *must* be specified except when using the ``-S`` + This parameter *must* be specified except when using the :option:`-S` option, which copies the algorithm from the predecessor key. In prior releases, HMAC algorithms could be generated for use as TSIG @@ -74,7 +74,7 @@ Options If the key size is not specified, some algorithms have pre-defined defaults. For example, RSA keys for use as DNSSEC zone-signing keys have a default size of 1024 bits; RSA keys for use as key-signing - keys (KSKs, generated with ``-f KSK``) default to 2048 bits. + keys (KSKs, generated with :option:`-f KSK <-f>`) default to 2048 bits. .. option:: -C @@ -83,7 +83,7 @@ Options creation date in the metadata stored with the private key; other dates may be set there as well, including publication date, activation date, etc. Keys that include this data may be incompatible with older - versions of BIND; the ``-C`` option suppresses them. + versions of BIND; the :option:`-C` option suppresses them. .. option:: -c class @@ -113,7 +113,7 @@ Options .. option:: -G This option generates a key, but does not publish it or sign with it. This option is - incompatible with ``-P`` and ``-A``. + incompatible with :option:`-P` and :option:`-A`. .. option:: -g generator @@ -153,7 +153,7 @@ Options .. option:: -l file This option provides a configuration file that contains a ``dnssec-policy`` statement - (matching the policy set with ``-k``). + (matching the policy set with :option:`-k`). .. option:: -n nametype @@ -166,7 +166,7 @@ Options .. option:: -p protocol This option sets the protocol value for the generated key, for use with - ``-T KEY``. The protocol is a number between 0 and 255. The default + :option:`-T KEY <-T>`. The protocol is a number between 0 and 255. The default is 3 (DNSSEC). Other possible values for this argument are listed in :rfc:`2535` and its successors. @@ -204,7 +204,7 @@ Options .. option:: -t type - This option indicates the type of the key for use with ``-T KEY``. ``type`` + This option indicates the type of the key for use with :option:`-T KEY <-T>`. ``type`` must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers to the ability to authenticate data, and CONF to the ability to encrypt data. @@ -233,7 +233,7 @@ explicitly prevent a date from being set, use ``none`` or ``never``. This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used - to sign it. If not set, and if the ``-G`` option has not been used, the + to sign it. If not set, and if the :option:`-G` option has not been used, the default is the current date. .. option:: -P sync date/offset @@ -245,8 +245,8 @@ explicitly prevent a date from being set, use ``none`` or ``never``. This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. If not set, - and if the ``-G`` option has not been used, the default is the current date. If set, - and ``-P`` is not set, the publication date is set to the + and if the :option:`-G` option has not been used, the default is the current date. If set, + and :option:`-P` is not set, the publication date is set to the activation date minus the prepublication interval. .. option:: -R date/offset @@ -309,7 +309,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 ``dnssec-signzone -S``, DNSKEY records are +signed by ``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 f6a04f317a..7ddaeb6b35 100644 --- a/bin/dnssec/dnssec-settime.rst +++ b/bin/dnssec/dnssec-settime.rst @@ -26,10 +26,10 @@ Description ~~~~~~~~~~~ ``dnssec-settime`` reads a DNSSEC private key file and sets the key -timing metadata as specified by the ``-P``, ``-A``, ``-R``, ``-I``, and -``-D`` options. The metadata can then be used by ``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. +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 +to be published, whether it should be used for signing a zone, etc. If none of these options is set on the command line, ``dnssec-settime`` simply prints the key timing metadata already stored @@ -45,12 +45,12 @@ the key file. The private file's permissions are always set to be inaccessible to anyone other than the owner (mode 0600). When working with state files, it is possible to update the timing metadata in -those files as well with ``-s``. With this option, it is also possible to update key -states with ``-d`` (DS), ``-k`` (DNSKEY), ``-r`` (RRSIG of KSK), or ``-z`` -(RRSIG of ZSK). Allowed states are HIDDEN, RUMOURED, OMNIPRESENT, and -UNRETENTIVE. +those files as well with :option:`-s`. With this option, it is also possible +to update key states with :option:`-d` (DS), :option:`-k` (DNSKEY), :option:`-r` +(RRSIG of KSK), or :option:`-z` (RRSIG of ZSK). Allowed states are HIDDEN, +RUMOURED, OMNIPRESENT, and UNRETENTIVE. -The goal state of the key can also be set with ``-g``. This should be either +The goal state of the key can also be set with :option:`-g`. This should be either HIDDEN or OMNIPRESENT, representing whether the key should be removed from the zone or published. @@ -239,7 +239,7 @@ associated with a key. .. option:: -p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all This option prints a specific metadata value or set of metadata values. - The ``-p`` option may be followed by one or more of the following letters or + The :option:`-p` option may be followed by one or more of the following letters or strings to indicate which value or values to print: ``C`` for the creation date, ``P`` for the publication date, ``Pds` for the DS publication date, ``Psync`` for the CDS and CDNSKEY publication date, ``A`` for the diff --git a/bin/dnssec/dnssec-signzone.rst b/bin/dnssec/dnssec-signzone.rst index 6675f3d076..8f1518e708 100644 --- a/bin/dnssec/dnssec-signzone.rst +++ b/bin/dnssec/dnssec-signzone.rst @@ -56,9 +56,9 @@ Options This option indicates that only those record types automatically managed by ``dnssec-signzone``, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output. - If smart signing (``-S``) is used, DNSKEY records are also included. + If smart signing (:option:`-S`) is used, DNSKEY records are also included. The resulting file can be included in the original zone file with - ``$INCLUDE``. This option cannot be combined with ``-O raw`` + ``$INCLUDE``. This option cannot be combined with :option:`-O raw <-O>` or serial-number updating. .. option:: -E engine @@ -94,7 +94,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 ``-D``, + ``named.conf``. (Note: This option is incompatible with :option:`-D`, because it modifies non-DNSSEC data in the output zone.) .. option:: -s start-time @@ -256,7 +256,7 @@ Options signer, and a DNSKEY record has been removed and replaced with a new one, signatures from the old key that are still within their validity period are retained. This allows the zone to continue to validate - with cached copies of the old DNSKEY RRset. The ``-Q`` option forces + with cached copies of the old DNSKEY RRset. The :option:`-Q` option forces ``dnssec-signzone`` to remove signatures from keys that are no longer active. This enables ZSK rollover using the procedure described in :rfc:`4641#4.2.1.1` ("Pre-Publish Key Rollover"). @@ -273,7 +273,7 @@ Options This option removes signatures from keys that are no longer published. - This option is similar to ``-Q``, except it forces + This option is similar to :option:`-Q`, except it forces ``dnssec-signzone`` to remove signatures from keys that are no longer published. This enables ZSK rollover using the procedure described in :rfc:`4641#4.2.1.2` ("Double Signature Zone Signing Key @@ -318,7 +318,7 @@ Options This option specifies a TTL to be used for new DNSKEY records imported into the zone from the key repository. If not specified, the default is the TTL value from the zone's SOA record. This option is ignored when - signing without ``-S``, since DNSKEY records are not imported from + signing without :option:`-S`, since DNSKEY records are not imported from the key repository in that case. It is also ignored if there are any pre-existing DNSKEY records at the zone apex, in which case new records' TTL values are set to match them, or if any of the @@ -371,8 +371,10 @@ Options This option indicates that, when generating an NSEC3 chain, BIND 9 should set the OPTOUT flag on all NSEC3 records and should not generate NSEC3 records for insecure delegations. - Using this option twice (i.e., ``-AA``) turns the OPTOUT flag off for - all records. This is useful when using the ``-u`` option to modify an +.. option:: -AA + + This option turns the OPTOUT flag off for + all records. This is useful when using the :option:`-u` option to modify an NSEC3 chain which previously had OPTOUT set. .. option:: zonefile @@ -391,10 +393,10 @@ Example The following command signs the ``example.com`` zone with the ECDSAP256SHA256 key generated by ``dnssec-keygen`` -(Kexample.com.+013+17247). Because the ``-S`` option is not being used, +(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 -DS records can be imported from them (``-g``). +DS records can be imported from them (:option:`-g`). :: diff --git a/bin/dnssec/dnssec-verify.rst b/bin/dnssec/dnssec-verify.rst index c0806c6d6d..ae97feefb0 100644 --- a/bin/dnssec/dnssec-verify.rst +++ b/bin/dnssec/dnssec-verify.rst @@ -79,7 +79,7 @@ Options Without this flag, it is assumed that the DNSKEY RRset is signed by all active keys. When this flag is set, it is not an error if the DNSKEY RRset is not signed by zone-signing keys. This corresponds - to the ``-x`` option in ``dnssec-signzone``. + to the :option:`-x option in dnssec-signzone `. .. option:: -z @@ -94,9 +94,10 @@ Options the KSK flag state, and that other RRsets be signed by a non-revoked key for the same algorithm that includes the self-signed key; the same key may be used for both purposes. This corresponds to - the ``-z`` option in ``dnssec-signzone``. + the :option:`-z option in dnssec-signzone `. + +.. option:: zonefile -``zonefile`` This option indicates the file containing the zone to be signed. See Also diff --git a/bin/named/named.rst b/bin/named/named.rst index 43a04e2193..072cb48761 100644 --- a/bin/named/named.rst +++ b/bin/named/named.rst @@ -38,13 +38,13 @@ Options .. option:: -4 - This option tells ``named`` to use only IPv4, even if the host machine is capable of IPv6. ``-4`` and - ``-6`` are mutually exclusive. + This option tells ``named`` to use only IPv4, even if the host machine is capable of IPv6. :option:`-4` and + :option:`-6` are mutually exclusive. .. option:: -6 - This option tells ``named`` to use only IPv6, even if the host machine is capable of IPv4. ``-4`` and - ``-6`` are mutually exclusive. + This option tells ``named`` to use only IPv6, even if the host machine is capable of IPv4. :option:`-4` and + :option:`-6` are mutually exclusive. .. option:: -c config-file @@ -153,7 +153,7 @@ Options .. warning:: - This option should be used in conjunction with the ``-u`` option, + This option should be used in conjunction with the :option:`-u` option, as chrooting a process running as root doesn't enhance security on most systems; the way ``chroot`` is defined allows a process with root privileges to escape a chroot jail. @@ -165,8 +165,8 @@ Options value based on the number of detected CPUs: 1 for 1 CPU, and the number of detected CPUs minus one for machines with more than 1 CPU. This cannot be increased to a value higher than the number of CPUs. - If ``-n`` has been set to a higher value than the number of detected - CPUs, then ``-U`` may be increased as high as that value, but no + If :option:`-n` has been set to a higher value than the number of detected + CPUs, then :option:`-U` may be increased as high as that value, but no higher. .. option:: -u user @@ -179,7 +179,7 @@ Options On Linux, ``named`` uses the kernel's capability mechanism to drop all root privileges except the ability to ``bind`` to a privileged port and set process resource limits. Unfortunately, - this means that the ``-u`` option only works when ``named`` is run + this means that the :option:`-u` option only works when ``named`` is run on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or later, since previous kernels did not allow privileges to be retained after ``setuid``. diff --git a/bin/nsupdate/nsupdate.rst b/bin/nsupdate/nsupdate.rst index 7c033f8501..35c05f1905 100644 --- a/bin/nsupdate/nsupdate.rst +++ b/bin/nsupdate/nsupdate.rst @@ -49,15 +49,15 @@ 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 -configuration fragments. ``nsupdate`` uses the ``-y`` or ``-k`` options +configuration fragments. ``nsupdate`` uses the :option:`-y` or :option:`-k` options to provide the TSIG shared secret; these options are mutually exclusive. SIG(0) uses public key cryptography. To use a SIG(0) key, the public key must be stored in a KEY record in a zone served by the name server. GSS-TSIG uses Kerberos credentials. Standard GSS-TSIG mode is switched -on with the ``-g`` flag. A non-standards-compliant variant of GSS-TSIG -used by Windows 2000 can be switched on with the ``-o`` flag. +on with the :option:`-g` flag. A non-standards-compliant variant of GSS-TSIG +used by Windows 2000 can be switched on with the :option:`-o` flag. Options ~~~~~~~ @@ -83,6 +83,10 @@ Options This option sets extra debug mode. +.. option:: -g + + This option enables standard GSS-TSIG mode. + .. option:: -i This option forces interactive mode, even when standard input is not a terminal. @@ -95,7 +99,7 @@ Options 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 ``-k`` option can also be used to specify a SIG(0) + ``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. @@ -107,12 +111,17 @@ Options found in |session_key|, which is automatically generated by ``named`` if any local ``primary`` zone has set ``update-policy`` to ``local``. The location of this key file can be - overridden with the ``-k`` option. + overridden with the :option:`-k` option. .. option:: -L level This option sets the logging debug level. If zero, logging is disabled. +.. option:: -o + + This option enables a non-standards-compliant variant of GSS-TSIG + used by Windows 2000. + .. option:: -p port This option sets the port to use for connections to a name server. The default is @@ -121,7 +130,7 @@ Options .. option:: -P This option prints the list of private BIND-specific resource record types whose - format is understood by ``nsupdate``. See also the ``-T`` option. + format is understood by ``nsupdate``. See also the :option:`-T` option. .. option:: -r udpretries @@ -137,7 +146,7 @@ Options This option prints the list of IANA standard resource record types whose format is understood by ``nsupdate``. ``nsupdate`` exits after the lists - are printed. The ``-T`` option can be combined with the ``-P`` + are printed. The :option:`-T` option can be combined with the :option:`-P` option. Other types can be entered using ``TYPEXXXXX`` where ``XXXXX`` is the @@ -171,7 +180,7 @@ Options ``hmac-sha512``. If ``hmac`` is not specified, the default is ``hmac-md5``, or if MD5 was disabled, ``hmac-sha256``. - NOTE: Use of the ``-y`` option is discouraged because the shared + NOTE: Use of the :option:`-y` option is discouraged because the shared secret is supplied as a command-line argument in clear text. This may be visible in the output from ps1 or in a history file maintained by the user's shell. @@ -231,15 +240,15 @@ The command formats and their meanings are as follows: ``keyname``-``secret`` pair. If ``hmac`` is specified, it sets the signing algorithm in use. The default is ``hmac-md5``; if MD5 was disabled, the default is ``hmac-sha256``. The ``key`` command overrides any key - specified on the command line via ``-y`` or ``-k``. + specified on the command line via :option:`-y` or :option:`-k`. ``gsstsig`` This command uses GSS-TSIG to sign the updates. This is equivalent to specifying - ``-g`` on the command line. + :option:`-g` on the command line. ``oldgsstsig`` This command uses the Windows 2000 version of GSS-TSIG to sign the updates. This is - equivalent to specifying ``-o`` on the command line. + equivalent to specifying :option:`-o` on the command line. ``realm [realm_name]`` When using GSS-TSIG, this command specifies the use of ``realm_name`` rather than the default realm diff --git a/bin/rndc/rndc.conf.rst b/bin/rndc/rndc.conf.rst index 0824f71bcf..4b239eafc5 100644 --- a/bin/rndc/rndc.conf.rst +++ b/bin/rndc/rndc.conf.rst @@ -127,7 +127,7 @@ 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 ``rndc -s testserver`` is used, then ``rndc`` connects to the server +If :option:`rndc -s testserver ` is used, then ``rndc`` connects to the server on localhost port 5353 using the key "testkey". To generate a random secret with ``rndc-confgen``: diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst index 5b92f72478..276d02e99a 100644 --- a/bin/rndc/rndc.rst +++ b/bin/rndc/rndc.rst @@ -144,7 +144,7 @@ Currently supported commands are: (Note the brackets around and semi-colon after the zone configuration text.) - See also ``rndc delzone`` and ``rndc modzone``. + See also :option:`rndc delzone` and :option:`rndc modzone`. .. option:: delzone [-clean] zone [class [view]] @@ -163,7 +163,7 @@ Currently supported commands are: recreated. To remove it permanently, it must also be removed from ``named.conf``. - See also ``rndc addzone`` and ``rndc modzone``. + See also :option:`rndc addzone` and :option:`rndc modzone`. .. option:: dnssec (-status | -rollover -key id [-alg algorithm] [-when time] | -checkds [-key id [-alg algorithm]] [-when time] published | withdraw)) zone [class [view]] @@ -225,7 +225,7 @@ Currently supported commands are: journal file to be synced into the master file. All dynamic update attempts are refused while the zone is frozen. - See also ``rndc thaw``. + See also :option:`rndc thaw`. .. option:: halt [-p] @@ -236,13 +236,13 @@ Currently supported commands are: an external process to determine when ``named`` has completed halting. - See also ``rndc stop``. + See also :option:`rndc stop`. .. option:: loadkeys [zone [class [view]]] This command fetches all DNSSEC keys for the given zone from the key directory. If they are within their publication period, they are merged into the - zone's DNSKEY RRset. Unlike ``rndc sign``, however, the zone is not + zone's DNSKEY RRset. Unlike :option:`rndc sign`, however, the zone is not immediately re-signed by the new keys, but is allowed to incrementally re-sign over time. @@ -282,7 +282,7 @@ Currently supported commands are: restarted or reconfigured, and all existing key maintenance states are deleted. - Running ``rndc reconfig`` or restarting ``named`` immediately + Running :option:`rndc reconfig` or restarting ``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 @@ -298,7 +298,7 @@ Currently supported commands are: command line is the zone configuration text that would ordinarily be placed in ``named.conf``. - If the zone was originally added via ``rndc addzone``, the + 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 @@ -307,7 +307,7 @@ Currently supported commands are: make the changes permanent, it must also be modified in ``named.conf``. - See also ``rndc addzone`` and ``rndc delzone``. + See also :option:`rndc addzone` and :option:`rndc delzone`. .. option:: notify zone [class [view]] @@ -317,7 +317,7 @@ Currently supported commands are: This command sets the server's debugging level to 0. - See also ``rndc trace``. + See also :option:`rndc trace`. .. option:: nta [(-class class | -dump | -force | -remove | -lifetime duration)] domain [view] @@ -453,7 +453,7 @@ Currently supported commands are: ``named.secroots``, but can be overridden via the ``secroots-file`` option in ``named.conf``. - See also ``rndc managed-keys``. + See also :option:`rndc managed-keys`. .. option:: serve-stale (on | off | reset | status) [class [view]] @@ -472,7 +472,7 @@ Currently supported commands are: This command prints the configuration of a running zone. - See also ``rndc zonestatus``. + See also :option:`rndc zonestatus`. .. option:: sign zone [class [view]] @@ -488,7 +488,7 @@ Currently supported commands are: "Dynamic Update Policies" in the BIND 9 Administrator Reference Manual for more details.) - See also ``rndc loadkeys``. + See also :option:`rndc loadkeys`. .. option:: signing [(-list | -clear keyid/algorithm | -clear all | -nsec3param (parameters | none) | -serial value) zone [class [view]] @@ -556,7 +556,7 @@ Currently supported commands are: This allows an external process to determine when ``named`` has completed stopping. - See also ``rndc halt``. + See also :option:`rndc halt`. .. option:: sync -clean [zone [class [view]]] @@ -585,7 +585,7 @@ Currently supported commands are: changes in the zone. Otherwise, if the zone has changed, any existing journal file is removed. - See also ``rndc freeze``. + See also :option:`rndc freeze`. .. option:: trace @@ -595,7 +595,7 @@ Currently supported commands are: This command sets the server's debugging level to an explicit value. - See also ``rndc notrace``. + See also :option:`rndc notrace`. .. option:: tsig-delete keyname [view] @@ -625,10 +625,10 @@ Currently supported commands are: signed, whether it uses automatic DNSSEC key management or inline signing, and the scheduled refresh or expiry times for the zone. - See also ``rndc showzone``. + See also :option:`rndc showzone`. -``rndc`` commands that specify zone names, such as ``reload`` -``retransfer``, or ``zonestatus``, can be ambiguous when applied to zones +``rndc`` commands that specify zone names, such as :option:`reload` +:option:`retransfer`, or :option:`zonestatus`, can be ambiguous when applied to zones of type ``redirect``. Redirect zones are always called ``.``, and can be confused with zones of type ``hint`` or with secondary copies of the root zone. To specify a redirect zone, use the special zone name diff --git a/bin/tools/dnstap-read.rst b/bin/tools/dnstap-read.rst index af726f3fee..107162beea 100644 --- a/bin/tools/dnstap-read.rst +++ b/bin/tools/dnstap-read.rst @@ -27,7 +27,7 @@ Description ``dnstap-read`` reads ``dnstap`` data from a specified file and prints it in a human-readable format. By default, ``dnstap`` data is printed in -a short summary format, but if the ``-y`` option is specified, a +a short summary format, but if the :option:`-y` option is specified, a longer and more detailed YAML format is used. Options diff --git a/bin/tools/mdig.rst b/bin/tools/mdig.rst index fab3ee1f76..3bf85f2991 100644 --- a/bin/tools/mdig.rst +++ b/bin/tools/mdig.rst @@ -231,7 +231,7 @@ Local Options This option sets the query type to ``type``. It can be any valid query type which is supported in BIND 9. The default query type is "A", - unless the ``-x`` option is supplied to indicate a reverse lookup with + unless the :option:`-x` option is supplied to indicate a reverse lookup with the "PTR" query type. .. option:: -x addr diff --git a/bin/tools/named-nzd2nzf.rst b/bin/tools/named-nzd2nzf.rst index 2562d1c116..aaffc73966 100644 --- a/bin/tools/named-nzd2nzf.rst +++ b/bin/tools/named-nzd2nzf.rst @@ -27,7 +27,7 @@ Description ``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 ``rndc addzone``. It can also be +zones that were added to ``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 eeb807af00..dbdf5bde23 100644 --- a/doc/arm/advanced.rst +++ b/doc/arm/advanced.rst @@ -96,19 +96,19 @@ The zone files of dynamic zones cannot normally be edited by hand because they are not guaranteed to contain the most recent dynamic changes; those are only in the journal file. The only way to ensure that the zone file of a dynamic zone is up-to-date is to run -``rndc stop``. +:option:`rndc stop`. To make changes to a dynamic zone manually, follow these steps: first, disable dynamic updates to the zone using -``rndc freeze zone``. This updates the zone file with the +:option:`rndc freeze zone `. This updates the zone file with the changes stored in its ``.jnl`` file. Then, edit the zone file. Finally, run -``rndc thaw zone`` to reload the changed zone and re-enable dynamic +:option:`rndc thaw zone ` to reload the changed zone and re-enable dynamic updates. -``rndc sync zone`` updates the zone file with changes from the +:option:`rndc sync zone ` updates the zone file with changes from the journal file without stopping dynamic updates; this may be useful for viewing the current zone state. To remove the ``.jnl`` file after -updating the zone file, use ``rndc sync -clean``. +updating the zone file, use :option:`rndc sync -clean `. .. _incremental_zone_transfers: @@ -389,8 +389,8 @@ configuration syntax and the process of creating TSIG keys. the tools included with BIND support it for sending messages to ``named``: - * :ref:`man_nsupdate` supports TSIG via the ``-k``, ``-l``, and ``-y`` command-line options, or via the ``key`` command when running interactively. - * :ref:`man_dig` supports TSIG via the ``-k`` and ``-y`` command-line options. + * :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. Generating a Shared Key ~~~~~~~~~~~~~~~~~~~~~~~ @@ -446,7 +446,7 @@ the signature. If the signature is valid, the response is signed using the same key. TSIG keys that are known to a server can be listed using the command -``rndc tsig-list``. +:option:`rndc tsig-list`. Instructing the Server to Use a Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -545,10 +545,10 @@ exchange. The shared secret can then be used to sign subsequent transactions between the two servers. TSIG keys known by the server, including TKEY-negotiated keys, can be -listed using ``rndc tsig-list``. +listed using :option:`rndc tsig-list`. TKEY-negotiated keys can be deleted from a server using -``rndc tsig-delete``. This can also be done via the TKEY protocol +:option:`rndc tsig-delete`. This can also be done via the TKEY protocol itself, by sending an authenticated TKEY query specifying the "key deletion" mode. @@ -645,8 +645,8 @@ The ``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`` -records for the zone, as well as ``DS`` for the child zones if ``-g`` -is specified. If ``-g`` is not specified, then DS RRsets for the +records for the zone, as well as ``DS`` for the child zones if :option:`-g ` +is specified. If :option:`-g ` is not specified, then DS RRsets for the secure child zones need to be added manually. By default, all zone keys which have an available private key are used diff --git a/doc/arm/catz.rst b/doc/arm/catz.rst index f28d435a20..a49a13ff80 100644 --- a/doc/arm/catz.rst +++ b/doc/arm/catz.rst @@ -35,7 +35,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 -be added using ``rndc addzone``. In environments with a large number of +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 configuration on all the secondary servers can be significant. @@ -56,11 +56,11 @@ 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 - ``rndc addzone``. + :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 - ``rndc reload``, or by updating the zone using ``nsupdate``. + :option:`rndc reload`, or by updating the zone using ``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 @@ -79,7 +79,7 @@ update, notices that the member zone has been removed, stops serving the zone, and removes it from its list of configured zones. However, removing the member zone from the primary server must be done by editing the configuration file or running -``rndc delzone``. +:option:`rndc delzone`. Configuring Catalog Zones ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -137,8 +137,8 @@ specified in any order. Catalog zones are defined on a per-view basis. Configuring a non-empty ``catalog-zones`` statement in a view automatically turns on -``allow-new-zones`` for that view. This means that ``rndc addzone`` -and ``rndc delzone`` also work in any view that supports catalog +``allow-new-zones`` for that view. This means that :option:`rndc addzone` +and :option:`rndc delzone` also work in any view that supports catalog zones. Catalog Zone Format diff --git a/doc/arm/configuration.rst b/doc/arm/configuration.rst index 27d23c3fd4..183862b73e 100644 --- a/doc/arm/configuration.rst +++ b/doc/arm/configuration.rst @@ -218,10 +218,10 @@ server. shared secret, and there is no way to provide that secret other than with a configuration file. The default location for the ``rndc`` configuration file is |rndc_conf|, but an alternate location - can be specified with the ``-c`` option. If the configuration file is + can be specified with the :option:`-c ` option. If the configuration file is not found, ``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 ``rndc-confgen -a`` as + ``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 @@ -233,7 +233,7 @@ server. The ``options`` statement has three clauses: ``default-server``, ``default-key``, and ``default-port``. ``default-server`` takes a host name or address argument and represents the server that is - contacted if no ``-s`` option is provided on the command line. + 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 @@ -275,7 +275,7 @@ server. This file, if installed as |rndc_conf|, allows the command: - ``$ rndc reload`` + :option:`rndc reload` to connect to 127.0.0.1 port 953 and causes the name server to reload, if a name server on the local machine is running with the following @@ -293,7 +293,7 @@ server. Running the ``rndc-confgen`` program conveniently creates an ``rndc.conf`` file, and also displays the corresponding ``controls`` statement needed to add to ``named.conf``. - Alternatively, it is possible to run ``rndc-confgen -a`` to set up an + Alternatively, it is possible to run :option:`rndc-confgen -a` to set up an ``rndc.key`` file and not modify ``named.conf`` at all. Signals diff --git a/doc/arm/dnssec.rst b/doc/arm/dnssec.rst index d3f5324682..d182f67deb 100644 --- a/doc/arm/dnssec.rst +++ b/doc/arm/dnssec.rst @@ -105,7 +105,7 @@ To enable automatic signing, set a ``dnssec-policy`` or add the With ``auto-dnssec allow``, ``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 -``rndc sign ``. +:option:`rndc sign zonename `. ``auto-dnssec maintain`` includes the above functionality, but also automatically adjusts the zone's DNSKEY records on a schedule according to @@ -123,17 +123,17 @@ 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 -``rndc loadkeys`` command forces ``named`` to check for key updates immediately. +:option:`rndc loadkeys` command forces ``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 -``rndc sign`` or ``rndc loadkeys`` command. Those commands can still be +:option:`rndc sign` or :option:`rndc loadkeys` command. Those commands can still be used when there are unscheduled key changes. When new keys are added to a zone, the TTL is set to match that of any existing DNSKEY RRset. If there is no existing DNSKEY RRset, the TTL is set to the TTL specified when the key was created (using the -``dnssec-keygen -L`` option), if any, or to the SOA TTL. +:option:`dnssec-keygen -L` option), if any, or to the SOA TTL. To sign the zone using NSEC3 instead of NSEC, submit an NSEC3PARAM record via dynamic update prior to the scheduled publication @@ -240,7 +240,7 @@ Converting From NSEC to NSEC3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add a ``nsec3param`` option to your ``dnssec-policy`` and -run ``rndc reconfig``. +run :option:`rndc reconfig`. Or use ``nsupdate`` to add an NSEC3PARAM record. @@ -251,7 +251,7 @@ Converting From NSEC3 to NSEC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To do this, remove the ``nsec3param`` option from the ``dnssec-policy`` and -run ``rndc reconfig``. +run :option:`rndc reconfig`. Or use ``nsupdate`` to remove all NSEC3PARAM records with a zero flag field. The NSEC chain is generated before the NSEC3 chain diff --git a/doc/arm/managed-keys.rst b/doc/arm/managed-keys.rst index d50dbdb39e..d24601eb04 100644 --- a/doc/arm/managed-keys.rst +++ b/doc/arm/managed-keys.rst @@ -47,7 +47,7 @@ has completed, the active KSK can be revoked, and the zone can be 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 exists with a publication date in the past, but an activation date which is -unset or in the future, ``dnssec-signzone -S`` includes the +unset or in the future, :option:`dnssec-signzone -S` includes the DNSKEY record in the zone but does not sign with it: :: diff --git a/doc/arm/pkcs11.rst b/doc/arm/pkcs11.rst index 07a59dafbc..c90f776c09 100644 --- a/doc/arm/pkcs11.rst +++ b/doc/arm/pkcs11.rst @@ -231,7 +231,7 @@ Running ``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 -E command line option. +the name of the OpenSSL engine using the :option:`-E ` command line option. :: diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index b6aadb86ce..02888ec3e4 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -405,7 +405,7 @@ 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 to load the command channel key from the file |rndc_key|. -To create an ``rndc.key`` file, run ``rndc-confgen -a``. +To create an ``rndc.key`` file, run :option:`rndc-confgen -a`. To disable the command channel, use an empty ``controls`` statement: ``controls { };``. @@ -495,7 +495,7 @@ logging configuration is: category unmatched { null; }; }; -If ``named`` is started with the ``-L`` option, it logs to the specified +If ``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: @@ -509,7 +509,7 @@ configuration is: The logging configuration is only established when the entire configuration file has been parsed. When the server starts up, all logging messages regarding syntax errors in the configuration file go to -the default channels, or to standard error if the ``-g`` option was +the default channels, or to standard error if the :option:`-g ` option was specified. .. _channel: @@ -608,8 +608,8 @@ 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 ``-d`` flag followed by a -positive integer, or by running ``rndc trace``. The global debug level +by starting the ``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; higher debug levels give more detailed output. Channels that specify a @@ -652,7 +652,7 @@ 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 ``-L`` option, then a fifth +logging, as follows. If ``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`. @@ -699,12 +699,12 @@ The ``default_debug`` channel has the special property that it only 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 ``-u`` command-line option is used, the +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 - and still running as root - is discarded. To capture this -output, run the server with the ``-L`` option to specify a -default logfile, or the ``-g`` option to log to standard error which can +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 be redirected to a file. Once a channel is defined, it cannot be redefined. The @@ -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 ``-L`` option, the default category +If ``named`` is started with the :option:`-L ` option, the default category is: :: @@ -1098,7 +1098,7 @@ default is used. ``dnstap-output`` can only be set globally in ``options``. Currently, it can only be set once while ``named`` is running; once set, it - cannot be changed by ``rndc reload`` or ``rndc reconfig``. + cannot be changed by :option:`rndc reload` or :option:`rndc reconfig`. ``dnstap-identity`` This specifies an ``identity`` string to send in ``dnstap`` messages. If @@ -1129,7 +1129,7 @@ default is used. When ``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 ``rndc addzone``. Note that this is not the NZD + zones added using :option:`rndc addzone`. Note that this is not the NZD database file size, but the largest size that the database may grow to. @@ -1171,7 +1171,7 @@ default is used. ``new-zones-directory`` This specifies the directory in which to store the configuration - parameters for zones added via ``rndc addzone``. By default, this is + 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. @@ -1224,7 +1224,7 @@ default is used. ``dump-file`` This is the pathname of the file the server dumps the database to, when - instructed to do so with ``rndc dumpdb``. If not specified, the + instructed to do so with :option:`rndc dumpdb`. If not specified, the default is ``named_dump.db``. ``memstatistics-file`` @@ -1239,7 +1239,7 @@ default is used. ``none``. Specifying ``lock-file none`` disables the use of a lock file. - ``lock-file`` is ignored if ``named`` was run using the ``-X`` + ``lock-file`` is ignored if ``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 when the server is first started. @@ -1255,12 +1255,12 @@ default is used. ``recursing-file`` This is the pathname of the file where the server dumps the queries that are - currently recursing, when instructed to do so with ``rndc recursing``. + currently recursing, when instructed to do so with :option:`rndc recursing`. If not specified, the default is ``named.recursing``. ``statistics-file`` This is the pathname of the file the server appends statistics to, when - instructed to do so using ``rndc stats``. If not specified, the + instructed to do so using :option:`rndc stats`. If not specified, the default is ``named.stats`` in the server's current directory. The format of the file is described in :ref:`statsfile`. @@ -1271,7 +1271,7 @@ default is used. ``secroots-file`` This is the pathname of the file the server dumps security roots to, when - instructed to do so with ``rndc secroots``. If not specified, the + instructed to do so with :option:`rndc secroots`. If not specified, the default is ``named.secroots``. ``session-keyfile`` @@ -1519,7 +1519,7 @@ default is used. ``nta-lifetime`` This specifies the default lifetime, in seconds, for - negative trust anchors added via ``rndc nta``. + negative trust anchors added via :option:`rndc nta`. A negative trust anchor selectively disables DNSSEC validation for zones that are known to be failing because of misconfiguration, rather @@ -1537,7 +1537,7 @@ default is used. ``nta-recheck`` This specifies how often to check whether negative trust anchors added via - ``rndc nta`` are still necessary. + :option:`rndc nta` are still necessary. A negative trust anchor is normally used when a domain has stopped validating due to operator error; it temporarily disables DNSSEC @@ -1548,7 +1548,7 @@ default is used. negative trust anchor is allowed to expire early. Validity checks can be disabled for an individual NTA by using - ``rndc nta -f``, or for all NTAs by setting ``nta-recheck`` to zero. + :option:`rndc nta -f `, or for all NTAs by setting ``nta-recheck`` to zero. For convenience, TTL-style time-unit suffixes can be used to specify the NTA recheck interval in seconds, minutes, or hours. It also accepts ISO 8601 @@ -1579,7 +1579,7 @@ default is used. For stale answers to be returned, they must be enabled, either in the configuration file using ``stale-answer-enable`` or via - ``rndc serve-stale on``. + :option:`rndc serve-stale on `. ``serial-update-method`` Zones configured for dynamic DNS may use this option to set the @@ -1611,7 +1611,7 @@ default is used. counters). These statistics may be accessed via the ``statistics-channel`` or - using ``rndc stats``, which dumps them to the file listed in the + using :option:`rndc stats`, which dumps them to the file listed in the ``statistics-file``. See also :ref:`statsfile`. For backward compatibility with earlier versions of BIND 9, the @@ -1637,7 +1637,7 @@ Boolean Options support the routing sockets for this feature to work. ``allow-new-zones`` - If ``yes``, then zones can be added at runtime via ``rndc addzone``. + If ``yes``, then zones can be added at runtime via :option:`rndc addzone`. The default is ``no``. Newly added zones' configuration parameters are stored so that they @@ -1652,7 +1652,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 - :ref:`man_rndc` for further details about ``rndc addzone``. + :ref:`man_rndc` for further details about :option:`rndc addzone`. ``auth-nxdomain`` If ``yes``, then the ``AA`` bit is always set on NXDOMAIN responses, @@ -1661,8 +1661,8 @@ Boolean Options ``memstatistics`` This writes memory statistics to the file specified by - ``memstatistics-file`` at exit. The default is ``no`` unless ``-m - record`` is specified on the command line, in which case it is ``yes``. + ``memstatistics-file`` at exit. The default is ``no`` unless :option:`-m + record ` is specified on the command line, in which case it is ``yes``. ``dialup`` If ``yes``, then the server treats all zones as if they are doing @@ -1885,12 +1885,12 @@ Boolean Options also enabled. The default is not to return stale answers. Stale answers can also be enabled or disabled at runtime via - ``rndc serve-stale on`` or ``rndc serve-stale off``; these override - the configured setting. ``rndc serve-stale reset`` restores the + :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 - re-enabled with ``rndc serve-stale on``, or the server must be + re-enabled with :option:`rndc serve-stale on `, or the server must be restarted. Information about stale answers is logged under the ``serve-stale`` @@ -2045,19 +2045,19 @@ Boolean Options settings: ``auto-dnssec allow;`` permits keys to be updated and the zone fully - re-signed whenever the user issues the command ``rndc sign zonename``. + re-signed whenever the user issues the command :option:`rndc sign zonename `. ``auto-dnssec maintain;`` includes the above, but also 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 ``rndc sign zonename`` + :ref:`man_dnssec-settime`). The command :option:`rndc sign zonename ` causes ``named`` to load keys from the key repository and sign the - zone with all keys that are active. ``rndc loadkeys zonename`` + zone with all keys that are active. :option:`rndc loadkeys zonename ` causes ``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 - periodically, regardless of whether ``rndc loadkeys`` is used. The + periodically, regardless of whether :option:`rndc loadkeys` is used. The recheck interval is defined by ``dnssec-loadkeys-interval``. ``auto-dnssec off;`` does not allow for DNSSEC key management. @@ -2131,7 +2131,7 @@ Boolean Options ``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 ``rndc querylog off``. + on``, or deactivated with :option:`rndc querylog off `. ``check-names`` This option is used to restrict the character set and syntax of @@ -2219,7 +2219,7 @@ Boolean Options the KSK bit set) are only used to sign the DNSKEY RRset at the zone apex. However, if this option is set to ``no``, then the KSK bit is ignored; KSKs are treated as if they were ZSKs and are used to sign - the entire zone. This is similar to the ``dnssec-signzone -z`` + the entire zone. This is similar to the :option:`dnssec-signzone -z` command-line option. When this option is set to ``yes``, there must be at least two active @@ -2234,7 +2234,7 @@ Boolean Options used to sign the DNSKEY, CDNSKEY, and CDS RRsets at the zone apex. Zone-signing keys (keys without the KSK bit set) are used to sign the remainder of the zone, but not the DNSKEY RRset. This is similar - to the ``dnssec-signzone -x`` command-line option. + to the :option:`dnssec-signzone -x` command-line option. The default is ``yes``. If ``update-check-ksk`` is set to ``no``, this option is ignored. @@ -2317,7 +2317,7 @@ on the host machine. able to resolve the name using only the transport it has. If the machine is dual-stacked, the ``dual-stack-servers`` parameter has no effect unless access to a transport has been disabled on the command - line (e.g., ``named -4``). + line (e.g., :option:`named -4`). .. _access_control: @@ -3025,7 +3025,7 @@ system. default is zero. The current list of active fetches can be dumped by running - ``rndc recursing``. The list includes the number of active fetches + :option:`rndc recursing`. The list includes the number of active fetches for each domain and the number of queries that have been passed (allowed) or dropped (spilled) as a result of the ``fetches-per-zone`` limit. (Note: these counters are not cumulative over time; @@ -3145,7 +3145,7 @@ system. minimum are adjusted with a logged warning. (Note: this value must be greater than the expected round-trip delay time; otherwise, no client will ever have enough time to submit a message.) This value - can be updated at runtime by using ``rndc tcp-timeouts``. + can be updated at runtime by using :option:`rndc tcp-timeouts`. ``tcp-idle-timeout`` This sets the amount of time (in units of 100 milliseconds) that the server waits on @@ -3155,7 +3155,7 @@ system. second). Values above the maximum or below the minimum are adjusted with a logged warning. See ``tcp-keepalive-timeout`` for clients using the EDNS TCP keepalive option. This value can be - updated at runtime by using ``rndc tcp-timeouts``. + updated at runtime by using :option:`rndc tcp-timeouts`. ``tcp-keepalive-timeout`` This sets the amount of time (in units of 100 milliseconds) that the server waits on @@ -3166,7 +3166,7 @@ system. adjusted with a logged warning. This value may be greater than ``tcp-idle-timeout`` because clients using the EDNS TCP keepalive option are expected to use TCP connections for more than one message. - This value can be updated at runtime by using ``rndc tcp-timeouts``. + This value can be updated at runtime by using :option:`rndc tcp-timeouts`. ``tcp-advertised-timeout`` This sets the timeout value (in units of 100 milliseconds) that the server sends @@ -3176,7 +3176,7 @@ system. and the minimum is 0, which signals that the clients must close TCP connections immediately. Ordinarily this should be set to the same value as ``tcp-keepalive-timeout``. This value can be updated at - runtime by using ``rndc tcp-timeouts``. + runtime by using :option:`rndc tcp-timeouts`. .. _intervals: @@ -3461,7 +3461,7 @@ Tuning For stale answers to be returned, the retaining of them in cache must be enabled via the configuration option ``stale-cache-enable``, and returning cached answers must be enabled, either in the configuration file using the - ``stale-answer-enable`` option or by calling ``rndc serve-stale on``. + ``stale-answer-enable`` option or by calling :option:`rndc serve-stale on `. When ``stale-cache-enable`` is set to ``no``, setting the ``max-stale-ttl`` has no effect, the value of ``max-cache-ttl`` will be ``0`` in such case. @@ -3529,12 +3529,12 @@ Tuning Signing-state records are used internally by ``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 ``rndc signing -list zone``. Once ``named`` has + using the command :option:`rndc signing -list zone `. Once ``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 ``rndc signing -clear keyid/algorithm zone``. To clear all of + running :option:`rndc signing -clear keyid/algorithm zone `. To clear all of the completed signing-state records for a zone, use - ``rndc signing -clear all zone``. + :option:`rndc signing -clear all zone `. ``min-refresh-time``; ``max-refresh-time``; ``min-retry-time``; ``max-retry-time`` These options control the server's behavior on refreshing a zone @@ -4953,7 +4953,7 @@ has been validated and proven secure. The resolver attempts DNSSEC validation on all DNS data in subdomains of configured trust anchors. Validation below specified names can be -temporarily disabled by using ``rndc nta``, or permanently disabled with +temporarily disabled by using :option:`rndc nta`, or permanently disabled with the ``validate-except`` option. All keys listed in ``trust-anchors``, and their corresponding zones, are @@ -5621,7 +5621,7 @@ or ``delegation-only``. The zone data is maintained in the form of NS and (if necessary) glue A or AAAA RRs internally, which can be seen by dumping zone databases with - ``rndc dumpdb -all``. The configured RRs are considered local configuration + :option:`rndc dumpdb -all `. The configured RRs are considered local configuration parameters rather than public data. Non-recursive queries (i.e., those with the RD bit off) to a static-stub zone are therefore prohibited and are responded to with REFUSED. @@ -5675,9 +5675,9 @@ or ``delegation-only``. Because redirect zones are not referenced directly by name, they are not kept in the zone lookup table with normal primary and secondary zones. To reload - a redirect zone, use ``rndc reload -redirect``; to retransfer a - redirect zone configured as a secondary, use ``rndc retransfer -redirect``. - When using ``rndc reload`` without specifying a zone name, redirect + a redirect zone, use :option:`rndc reload -redirect `; to retransfer a + redirect zone configured as a secondary, use :option:`rndc retransfer -redirect `. + When using :option:`rndc reload` without specifying a zone name, redirect zones are reloaded along with other zones. ``delegation-only`` diff --git a/doc/arm/security.rst b/doc/arm/security.rst index c17643ba8c..eafcccc90a 100644 --- a/doc/arm/security.rst +++ b/doc/arm/security.rst @@ -152,12 +152,12 @@ 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 ``-t`` option for +(using the ``chroot()`` function) by specifying the :option:`-t ` option for ``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 -the daemon as an unprivileged user (``-u`` user). We suggest running +the daemon as an unprivileged user (:option:`-u ` user). We suggest running as an unprivileged user when using the ``chroot`` feature. Here is an example command line to load BIND in a ``chroot`` sandbox, diff --git a/doc/arm/troubleshooting.rst b/doc/arm/troubleshooting.rst index 1bd5f9890c..cc52acdcfd 100644 --- a/doc/arm/troubleshooting.rst +++ b/doc/arm/troubleshooting.rst @@ -75,7 +75,7 @@ Inspecting Encrypted DNS Traffic This feature requires support from the cryptographic library that BIND 9 is built against. For OpenSSL, version 1.1.1 or newer is - required (use ``named -V`` to check). + required (use :option:`named -V` to check). By definition, TLS-encrypted traffic (e.g. DNS over TLS, DNS over HTTPS) is opaque to packet sniffers, which makes debugging problems with diff --git a/doc/dnssec-guide/advanced-discussions.rst b/doc/dnssec-guide/advanced-discussions.rst index 8cdd094bfc..a828743e44 100644 --- a/doc/dnssec-guide/advanced-discussions.rst +++ b/doc/dnssec-guide/advanced-discussions.rst @@ -885,7 +885,7 @@ care to set appropriate ownership and permissions on the keys. If the ``auto-dnssec`` zone option is set to ``maintain``, ``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 -``rndc loadkeys`` command. Otherwise, for primary zones, you can use +:option:`rndc loadkeys` command. Otherwise, for primary zones, you can use ``nsupdate`` to add the new DNSKEYs to the zone; this causes ``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. @@ -909,9 +909,9 @@ 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`` utility to set the *Delete* date on all keys to any time in the past. -(See the ``dnssec-settime -D `` option.) +(See the :option:`dnssec-settime -D date/offset ` option.) -After adjusting the timing metadata, the ``rndc loadkeys`` command +After adjusting the timing metadata, the :option:`rndc loadkeys` command causes ``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 @@ -935,8 +935,8 @@ environment. 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 ``rndc freeze`` before editing the zone file, and -``rndc thaw`` when you have finished editing, or you can use the +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: :: diff --git a/doc/dnssec-guide/getting-started.rst b/doc/dnssec-guide/getting-started.rst index 7329a1fee4..bd1abbffd7 100644 --- a/doc/dnssec-guide/getting-started.rst +++ b/doc/dnssec-guide/getting-started.rst @@ -27,7 +27,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, -use the ``-v`` switch as shown below: +use the :option:`-v ` switch as shown below: :: @@ -47,10 +47,10 @@ DNSSEC Support in BIND All versions of BIND 9 since BIND 9.7 can support DNSSEC, as currently deployed in the global DNS, so the BIND software you are running most -likely already supports DNSSEC. Run the command ``named -V`` +likely already supports DNSSEC. Run the command :option:`named -V` to see what flags it was built with. If it was built with OpenSSL (``--with-openssl``), then it supports DNSSEC. Below is an example -of the output from running ``named -V``: +of the output from running :option:`named -V`: :: diff --git a/doc/dnssec-guide/recipes.rst b/doc/dnssec-guide/recipes.rst index ccb6bb5b7f..d332e6461e 100644 --- a/doc/dnssec-guide/recipes.rst +++ b/doc/dnssec-guide/recipes.rst @@ -234,8 +234,8 @@ 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 (``-I``) date of January 1, -2021, and a deletion (``-D``) date of February 1, 2021, for the current ZSK +The second, ``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 @@ -487,8 +487,8 @@ 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 (``-I``) date of January 1, -2021, and a deletion (``-D``) date of February 1, 2021 for the current KSK +The second, ``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 @@ -1095,14 +1095,14 @@ Change your ``dnssec-policy`` line to indicate you want to revert to unsigned: dnssec-policy "insecure"; }; -Then use ``rndc reload`` to reload the zone. +Then use :option:`rndc reload` to reload the zone. The "insecure" policy is a built-in policy (like "default"). It will make sure 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 -``rndc dnssec -checkds -key withdrawn example.com`` to tell ``named`` that +:option:`rndc dnssec -checkds -key id withdrawn example.com ` to tell ``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 diff --git a/doc/dnssec-guide/signing.rst b/doc/dnssec-guide/signing.rst index 6aa3617264..5e8b41f4c6 100644 --- a/doc/dnssec-guide/signing.rst +++ b/doc/dnssec-guide/signing.rst @@ -78,7 +78,7 @@ for most situations. We cover the creation of a custom policy in default values. When the configuration file is updated, tell ``named`` to -reload the configuration file by running ``rndc reconfig``: +reload the configuration file by running :option:`rndc reconfig`: :: @@ -1599,7 +1599,7 @@ of the zone, which looks something like this: file "db/example.com.signed.db"; }; -Once the ``rndc reconfig`` command is issued, BIND serves a signed +Once the :option:`rndc reconfig` command is issued, BIND serves a signed zone. The file ``dsset-example.com`` (created by ``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 diff --git a/doc/dnssec-guide/validation.rst b/doc/dnssec-guide/validation.rst index 2083bc16a7..ffb277e71e 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 ``rndc reconfig``, and your recursive server is +Restart ``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 diff --git a/doc/man/ddns-confgen.8in b/doc/man/ddns-confgen.8in index 3088aca7d1..0549db6389 100644 --- a/doc/man/ddns-confgen.8in +++ b/doc/man/ddns-confgen.8in @@ -39,7 +39,7 @@ ddns-confgen \- ddns key generation tool The resulting keys can be used, for example, to secure dynamic DNS updates to a zone, or for the \fBrndc\fP command channel. .sp -The key name can specified using \fB\-k\fP parameter and defaults to \fBddns\-key\fP\&. +The key name can specified using \fI\%\-k\fP parameter and defaults to \fBddns\-key\fP\&. The generated key is accompanied by configuration text and instructions that can be used with \fBnsupdate\fP and \fBnamed\fP when setting up dynamic DNS, including an example \fBupdate\-policy\fP statement. @@ -69,7 +69,7 @@ This option prints a short summary of options and arguments. .TP .B \-k keyname This option specifies the key name of the DDNS authentication key. The -default is \fBddns\-key\fP when neither the \fB\-s\fP nor \fB\-z\fP option is +default is \fBddns\-key\fP when neither the \fI\%\-s\fP nor \fI\%\-z\fP option is specified; otherwise, the default is \fBddns\-key\fP as a separate label followed by the argument of the option, e.g., \fBddns\-key.example.com.\fP The key name must have the format of a valid domain name, consisting of @@ -90,7 +90,7 @@ of a single hostname. The example \fBnamed.conf\fP text shows how to set an update policy for the specified name using the "name" nametype. The default key name is \fBddns\-key.name\fP\&. Note that the "self" nametype cannot be used, since the name to be updated may differ from the key -name. This option cannot be used with the \fB\-z\fP option. +name. This option cannot be used with the \fI\%\-z\fP option. .UNINDENT .INDENT 0.0 .TP @@ -99,7 +99,7 @@ This option generates a configuration example to allow dynamic updates of a zone. The example \fBnamed.conf\fP 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 \fB\-s\fP option. +This option cannot be used with the \fI\%\-s\fP option. .UNINDENT .SH SEE ALSO .sp diff --git a/doc/man/delv.1in b/doc/man/delv.1in index 407d07cca2..cc662b9d23 100644 --- a/doc/man/delv.1in +++ b/doc/man/delv.1in @@ -94,7 +94,7 @@ DNSSEC). .sp If no \fBserver\fP argument is provided, \fBdelv\fP consults \fB/etc/resolv.conf\fP; if an address is found there, it queries the -name server at that address. If either of the \fB\-4\fP or \fB\-6\fP +name server at that address. If either of the \fI\%\-4\fP or \fI\%\-6\fP options is in use, then only addresses for the corresponding transport are tried. If no usable addresses are found, \fBdelv\fP sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1 @@ -186,7 +186,7 @@ non\-standard port number. .TP .B \-q name This option sets the query name to \fBname\fP\&. While the query name can be -specified without using the \fB\-q\fP option, it is sometimes necessary to +specified without using the \fI\%\-q\fP option, it is sometimes necessary to disambiguate names from types or classes (for example, when looking up the name "ns", which could be misinterpreted as the type NS, or "ch", which could be misinterpreted as class CH). @@ -196,11 +196,11 @@ up the name "ns", which could be misinterpreted as the type NS, or .B \-t type This option sets the query type to \fBtype\fP, which can be any valid query type supported in BIND 9 except for zone transfer types AXFR and IXFR. As -with \fB\-q\fP, this is useful to distinguish query\-name types or classes +with \fI\%\-q\fP, this is useful to distinguish query\-name types or classes when they are ambiguous. It is sometimes necessary to disambiguate names from types. .sp -The default query type is "A", unless the \fB\-x\fP option is supplied +The default query type is "A", unless the \fI\%\-x\fP option is supplied to indicate a reverse lookup, in which case it is "PTR". .UNINDENT .INDENT 0.0 @@ -213,7 +213,7 @@ This option prints the \fBdelv\fP version and exits. .B \-x addr This option performs a reverse lookup, mapping an address to a name. \fBaddr\fP is an IPv4 address in dotted\-decimal notation, or a colon\-delimited -IPv6 address. When \fB\-x\fP is used, there is no need to provide the +IPv6 address. When \fI\%\-x\fP is used, there is no need to provide the \fBname\fP or \fBtype\fP arguments; \fBdelv\fP automatically performs a lookup for a name like \fB11.12.13.10.in\-addr.arpa\fP and sets the query type to PTR. IPv6 addresses are looked up using nibble format @@ -273,7 +273,7 @@ of trust for DNSSEC validation. .sp This is equivalent to setting the debug level to 1 in the "resolver" logging category. Setting the systemwide debug level to 1 using the -\fB\-d\fP option produces the same output, but affects other +\fI\%\-d\fP option produces the same output, but affects other logging categories as well. .UNINDENT .INDENT 0.0 @@ -285,7 +285,7 @@ resolution and validation process. .sp This is equivalent to setting the debug level to 10 for the "packets" module of the "resolver" logging category. Setting the systemwide -debug level to 10 using the \fB\-d\fP option produces the same +debug level to 10 using the \fI\%\-d\fP option produces the same output, but affects other logging categories as well. .UNINDENT .INDENT 0.0 @@ -297,7 +297,7 @@ unsigned, or invalid. .sp This is equivalent to setting the debug level to 3 for the "validator" module of the "dnssec" logging category. Setting the -systemwide debug level to 3 using the \fB\-d\fP option produces the +systemwide debug level to 3 using the \fI\%\-d\fP option produces the same output, but affects other logging categories as well. .UNINDENT .INDENT 0.0 @@ -365,7 +365,7 @@ This option indicates whether to display RRSIG records in the \fBdelv\fP output. The default is to do so. Note that (unlike in \fBdig\fP) this does \fInot\fP 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 \fB\-i\fP or +always occurs unless suppressed by the use of \fI\%\-i\fP or \fB+noroot\fP\&. .UNINDENT .INDENT 0.0 @@ -374,7 +374,7 @@ always occurs unless suppressed by the use of \fB\-i\fP or This option indicates whether to perform conventional DNSSEC validation, and if so, specifies the name of a trust anchor. The default is to validate using a trust anchor of "." (the root zone), for which there is a built\-in key. If -specifying a different trust anchor, then \fB\-a\fP must be used to specify a +specifying a different trust anchor, then \fI\%\-a\fP must be used to specify a file containing the key. .UNINDENT .INDENT 0.0 diff --git a/doc/man/dig.1in b/doc/man/dig.1in index 61c97248a3..7181d1c84b 100644 --- a/doc/man/dig.1in +++ b/doc/man/dig.1in @@ -62,12 +62,12 @@ performs an NS query for "." (the root). .sp It is possible to set per\-user defaults for \fBdig\fP via \fB${HOME}/.digrc\fP\&. This file is read and any options in it are applied -before the command\-line arguments. The \fB\-r\fP option disables this +before the command\-line arguments. The \fI\%\-r\fP option disables this feature, for scripts that need predictable behavior. .sp The IN and CH class names overlap with the IN and CH top\-level domain -names. Either use the \fB\-t\fP and \fB\-c\fP options to specify the type and -class, use the \fB\-q\fP to specify the domain name, or use "IN." and +names. Either use the \fI\%\-t\fP and \fI\%\-c\fP options to specify the type and +class, use the \fI\%\-q\fP to specify the domain name, or use "IN." and "CH." when looking up these top\-level domains. .SH SIMPLE USAGE .sp @@ -95,7 +95,7 @@ server. .sp If no \fBserver\fP argument is provided, \fBdig\fP consults \fB/etc/resolv.conf\fP; if an address is found there, it queries the -name server at that address. If either of the \fB\-4\fP or \fB\-6\fP +name server at that address. If either of the \fI\%\-4\fP or \fI\%\-6\fP options are in use, then only addresses for the corresponding transport are tried. If no usable addresses are found, \fBdig\fP sends the query to the local host. The reply from the name server @@ -186,7 +186,7 @@ scripts that need predictable behavior. This option indicates the resource record type to query, which can be any valid query type. If it is a resource record type supported in BIND 9, it can be given by the type mnemonic (such as \fBNS\fP or \fBAAAA\fP). The default query type is -\fBA\fP, unless the \fB\-x\fP option is supplied to indicate a reverse +\fBA\fP, unless the \fI\%\-x\fP option is supplied to indicate a reverse lookup. A zone transfer can be requested by specifying a type of AXFR. When an incremental zone transfer (IXFR) is required, set the \fBtype\fP to \fBixfr=N\fP\&. The incremental zone transfer contains @@ -212,7 +212,7 @@ This option prints the version number and exits. .B \-x addr This option sets simplified reverse lookups, for mapping addresses to names. The \fBaddr\fP is an IPv4 address in dotted\-decimal notation, or a -colon\-delimited IPv6 address. When the \fB\-x\fP option is used, there is no +colon\-delimited IPv6 address. When the \fI\%\-x\fP option is used, there is no need to provide the \fBname\fP, \fBclass\fP, and \fBtype\fP arguments. \fBdig\fP automatically performs a lookup for a name like \fB94.2.0.192.in\-addr.arpa\fP and sets the query type and class to PTR @@ -234,8 +234,8 @@ not specified, the default is \fBhmac\-md5\fP; if MD5 was disabled, the default \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -Only the \fB\-k\fP option should be used, rather than the \fB\-y\fP option, -because with \fB\-y\fP the shared secret is supplied as a command\-line +Only the \fI\%\-k\fP option should be used, rather than the \fI\%\-y\fP option, +because with \fI\%\-y\fP the shared secret is supplied as a command\-line argument in clear text. This may be visible in the output from \fBps1\fP or in a history file maintained by the user\(aqs shell. .UNINDENT @@ -803,7 +803,7 @@ This flag is off by default. .SH MULTIPLE QUERIES .sp The BIND 9 implementation of \fBdig\fP supports specifying multiple -queries on the command line (in addition to supporting the \fB\-f\fP batch +queries on the command line (in addition to supporting the \fI\%\-f\fP batch file option). Each of those queries can be supplied with its own set of flags, options, and query options. .sp diff --git a/doc/man/dnssec-cds.1in b/doc/man/dnssec-cds.1in index a06a8fffdd..9bc561f69d 100644 --- a/doc/man/dnssec-cds.1in +++ b/doc/man/dnssec-cds.1in @@ -43,9 +43,9 @@ its key\-signing keys (KSKs); by polling periodically with \fBdnssec\-cds\fP, th parent can keep the DS records up\-to\-date and enable automatic rolling of KSKs. .sp -Two input files are required. The \fB\-f child\-file\fP option specifies a +Two input files are required. The \fI\%\-f child\-file\fP option specifies a file containing the child\(aqs CDS and/or CDNSKEY records, plus RRSIG and -DNSKEY records so that they can be authenticated. The \fB\-d path\fP option +DNSKEY records so that they can be authenticated. The \fI\%\-d path\fP option specifies the location of a file containing the current DS records. For example, this could be a \fBdsset\-\fP file generated by \fBdnssec\-signzone\fP, or the output of \fBdnssec\-dsfromkey\fP, or the @@ -59,7 +59,7 @@ is typically the pre\-existing KSK. For protection against replay attacks, the signatures on the child records must not be older than they were on a previous run of \fBdnssec\-cds\fP\&. Their age is obtained from the modification time of the -\fBdsset\-\fP file, or from the \fB\-s\fP option. +\fBdsset\-\fP file, or from the \fI\%\-s\fP option. .sp To protect against breaking the delegation, \fBdnssec\-cds\fP ensures that the DNSKEY RRset can be verified by every key algorithm in the new DS @@ -67,7 +67,7 @@ RRset, and that the same set of keys are covered by every DS digest type. .sp By default, replacement DS records are written to the standard output; -with the \fB\-i\fP option the input file is overwritten in place. The +with the \fI\%\-i\fP option the input file is overwritten in place. The replacement DS records are the same as the existing records, when no change is required. The output can be empty if the CDS/CDNSKEY records specify that the child zone wants to be insecure. @@ -80,7 +80,7 @@ Be careful not to delete the DS records when \fBdnssec\-cds\fP fails! .UNINDENT .sp Alternatively, \fBdnssec\-cds \-u\fP writes an \fBnsupdate\fP script to the -standard output. The \fB\-u\fP and \fB\-i\fP options can be used together to +standard output. The \fI\%\-u\fP and \fI\%\-i\fP options can be used together to maintain a \fBdsset\-\fP file as well as emit an \fBnsupdate\fP script. .SH OPTIONS .INDENT 0.0 @@ -121,7 +121,7 @@ looks for a \fBdsset\-\fP file for the domain inside the directory. .sp To protect against replay attacks, child records are rejected if they were signed earlier than the modification time of the \fBdsset\-\fP -file. This can be adjusted with the \fB\-s\fP option. +file. This can be adjusted with the \fI\%\-s\fP option. .UNINDENT .INDENT 0.0 .TP @@ -134,11 +134,11 @@ The examples below describe how to generate this file. .UNINDENT .INDENT 0.0 .TP -.B \-iextension +.B \-i extension This option updates the \fBdsset\-\fP file in place, instead of writing DS records to the standard output. .sp -There must be no space between the \fB\-i\fP and the extension. If +There must be no space between the \fI\%\-i\fP and the extension. If no extension is provided, the old \fBdsset\-\fP is discarded. If an extension is present, a backup of the old \fBdsset\-\fP file is kept with the extension appended to its filename. @@ -177,7 +177,7 @@ printing the new DS reords. The output is empty if no change is needed. .sp Note: The TTL of new records needs to be specified: it can be done in the -original \fBdsset\-\fP file, with the \fB\-T\fP option, or using the +original \fBdsset\-\fP file, with the \fI\%\-T\fP option, or using the \fBnsupdate\fP \fBttl\fP command. .UNINDENT .INDENT 0.0 diff --git a/doc/man/dnssec-dsfromkey.1in b/doc/man/dnssec-dsfromkey.1in index 12668866c9..8ec700a523 100644 --- a/doc/man/dnssec-dsfromkey.1in +++ b/doc/man/dnssec-dsfromkey.1in @@ -42,10 +42,10 @@ dnssec-dsfromkey \- DNSSEC DS RR generation tool .SH DESCRIPTION .sp The \fBdnssec\-dsfromkey\fP command outputs DS (Delegation Signer) resource records -(RRs), or CDS (Child DS) RRs with the \fB\-C\fP option. +(RRs), or CDS (Child DS) RRs with the \fI\%\-C\fP option. .sp By default, only KSKs are converted (keys with flags = 257). The -\fB\-A\fP option includes ZSKs (flags = 256). Revoked keys are never +\fI\%\-A\fP option includes ZSKs (flags = 256). Revoked keys are never included. .sp The input keys can be specified in a number of ways: @@ -53,21 +53,21 @@ The input keys can be specified in a number of ways: By default, \fBdnssec\-dsfromkey\fP reads a key file named in the format \fBKnnnn.+aaa+iiiii.key\fP, as generated by \fBdnssec\-keygen\fP\&. .sp -With the \fB\-f file\fP option, \fBdnssec\-dsfromkey\fP reads keys from a zone +With the \fI\%\-f file\fP option, \fBdnssec\-dsfromkey\fP reads keys from a zone file or partial zone file (which can contain just the DNSKEY records). .sp -With the \fB\-s\fP option, \fBdnssec\-dsfromkey\fP reads a \fBkeyset\-\fP file, -as generated by \fBdnssec\-keygen\fP \fB\-C\fP\&. +With the \fI\%\-s\fP option, \fBdnssec\-dsfromkey\fP reads a \fBkeyset\-\fP file, +as generated by \fBdnssec\-keygen\fP \fI\%\-C\fP\&. .SH OPTIONS .INDENT 0.0 .TP .B \-1 -This option is an abbreviation for \fB\-a SHA1\fP\&. +This option is an abbreviation for \fI\%\-a SHA1\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-2 -This option is an abbreviation for \fB\-a SHA\-256\fP\&. +This option is an abbreviation for \fI\%\-a SHA\-256\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -85,13 +85,13 @@ is specified, the default is SHA\-256. .B \-A This option indicates that ZSKs are to be included when generating DS records. Without this option, only keys which have the KSK flag set are converted to DS records and -printed. This option is only useful in \fB\-f\fP zone file mode. +printed. This option is only useful in \fI\%\-f\fP zone file mode. .UNINDENT .INDENT 0.0 .TP .B \-c class -This option specifies the DNS class; the default is IN. This option is only useful in \fB\-s\fP keyset -or \fB\-f\fP zone file mode. +This option specifies the DNS class; the default is IN. This option is only useful in \fI\%\-s\fP keyset +or \fI\%\-f\fP zone file mode. .UNINDENT .INDENT 0.0 .TP diff --git a/doc/man/dnssec-importkey.1in b/doc/man/dnssec-importkey.1in index 29ddda79ee..3c38ccf998 100644 --- a/doc/man/dnssec-importkey.1in +++ b/doc/man/dnssec-importkey.1in @@ -45,7 +45,7 @@ input, in which case both .key and .private files are generated. .sp The newly created .private file does \fInot\fP contain private key data, and cannot be used for signing. However, having a .private file makes it -possible to set publication (\fB\-P\fP) and deletion (\fB\-D\fP) times for the +possible to set publication (\fI\%\-P\fP) and deletion (\fI\%\-D\fP) times for the key, which means the public key can be added to and removed from the DNSKEY RRset on schedule even if the true private key is stored offline. .SH OPTIONS diff --git a/doc/man/dnssec-keyfromlabel.1in b/doc/man/dnssec-keyfromlabel.1in index cc9aab63e0..63dfd774ab 100644 --- a/doc/man/dnssec-keyfromlabel.1in +++ b/doc/man/dnssec-keyfromlabel.1in @@ -53,18 +53,18 @@ be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. .sp If no algorithm is specified, RSASHA1 is used by default -unless the \fB\-3\fP option is specified, in which case NSEC3RSASHA1 -is used instead. (If \fB\-3\fP is used and an algorithm is +unless the \fI\%\-3\fP option is specified, in which case NSEC3RSASHA1 +is used instead. (If \fI\%\-3\fP is used and an algorithm is specified, that algorithm is checked for compatibility with NSEC3.) .sp These values are case\-insensitive. In some cases, abbreviations are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for -ECDSAP384SHA384. If RSASHA1 is specified along with the \fB\-3\fP +ECDSAP384SHA384. If RSASHA1 is specified along with the \fI\%\-3\fP option, then NSEC3RSASHA1 is used instead. .sp Since BIND 9.12.0, this option is mandatory except when using the -\fB\-S\fP option, which copies the algorithm from the predecessory key. +\fI\%\-S\fP option, which copies the algorithm from the predecessory key. Previously, the default for newly generated keys was RSASHA1. .UNINDENT .INDENT 0.0 @@ -111,7 +111,7 @@ By default, \fBdnssec\-keyfromlabel\fP includes the key\(aqs creation date in the metadata stored with the private key; other dates may be set there as well, including publication date, activation date, etc. Keys that include this data may be incompatible with older versions of -BIND; the \fB\-C\fP option suppresses them. +BIND; the \fI\%\-C\fP option suppresses them. .UNINDENT .INDENT 0.0 .TP @@ -129,7 +129,7 @@ The only recognized flags are KSK (Key\-Signing Key) and REVOKE. .TP .B \-G This option generates a key, but does not publish it or sign with it. This option is -incompatible with \fB\-P\fP and \fB\-A\fP\&. +incompatible with \fI\%\-P\fP and \fI\%\-A\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -149,7 +149,7 @@ This option generates KEY records rather than DNSKEY records. .UNINDENT .INDENT 0.0 .TP -.B \fB\-L\fP ttl +.B \-L ttl This option sets the default TTL to use for this key when it is converted into a DNSKEY RR. This is the TTL used when the key is imported into a zone, unless there was already a DNSKEY RRset in @@ -215,7 +215,7 @@ explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&. .B \-P date/offset This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used -to sign it. If not set, and if the \fB\-G\fP option has not been used, the +to sign it. If not set, and if the \fI\%\-G\fP option has not been used, the default is the current date. .UNINDENT .INDENT 0.0 @@ -229,7 +229,7 @@ are to be published to the zone. .B \-A date/offset This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. If not set, -and if the \fB\-G\fP option has not been used, the default is the current date. +and if the \fI\%\-G\fP option has not been used, the default is the current date. .UNINDENT .INDENT 0.0 .TP diff --git a/doc/man/dnssec-keygen.1in b/doc/man/dnssec-keygen.1in index 55f1e9a987..f9fccee924 100644 --- a/doc/man/dnssec-keygen.1in +++ b/doc/man/dnssec-keygen.1in @@ -59,14 +59,14 @@ This option selects the cryptographic algorithm. For DNSSEC keys, the value of \fBalgorithm\fP must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. For TKEY, the value must be DH (Diffie\-Hellman); specifying this value -automatically sets the \fB\-T KEY\fP option as well. +automatically sets the \fI\%\-T KEY\fP option as well. .sp These values are case\-insensitive. In some cases, abbreviations are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for -ECDSAP384SHA384. If RSASHA1 is specified along with the \fB\-3\fP +ECDSAP384SHA384. If RSASHA1 is specified along with the \fI\%\-3\fP option, NSEC3RSASHA1 is used instead. .sp -This parameter \fImust\fP be specified except when using the \fB\-S\fP +This parameter \fImust\fP be specified except when using the \fI\%\-S\fP option, which copies the algorithm from the predecessor key. .sp In prior releases, HMAC algorithms could be generated for use as TSIG @@ -84,7 +84,7 @@ curve algorithms do not need this parameter. If the key size is not specified, some algorithms have pre\-defined defaults. For example, RSA keys for use as DNSSEC zone\-signing keys have a default size of 1024 bits; RSA keys for use as key\-signing -keys (KSKs, generated with \fB\-f KSK\fP) default to 2048 bits. +keys (KSKs, generated with \fI\%\-f KSK\fP) default to 2048 bits. .UNINDENT .INDENT 0.0 .TP @@ -94,7 +94,7 @@ metadata. By default, \fBdnssec\-keygen\fP includes the key\(aqs creation date in the metadata stored with the private key; other dates may be set there as well, including publication date, activation date, etc. Keys that include this data may be incompatible with older -versions of BIND; the \fB\-C\fP option suppresses them. +versions of BIND; the \fI\%\-C\fP option suppresses them. .UNINDENT .INDENT 0.0 .TP @@ -129,7 +129,7 @@ The only recognized flags are KSK (Key\-Signing Key) and REVOKE. .TP .B \-G This option generates a key, but does not publish it or sign with it. This option is -incompatible with \fB\-P\fP and \fB\-A\fP\&. +incompatible with \fI\%\-P\fP and \fI\%\-A\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -175,7 +175,7 @@ is the same as leaving it unset. .TP .B \-l file This option provides a configuration file that contains a \fBdnssec\-policy\fP statement -(matching the policy set with \fB\-k\fP). +(matching the policy set with \fI\%\-k\fP). .UNINDENT .INDENT 0.0 .TP @@ -190,7 +190,7 @@ case\-insensitive. The default is ZONE for DNSKEY generation. .TP .B \-p protocol This option sets the protocol value for the generated key, for use with -\fB\-T KEY\fP\&. The protocol is a number between 0 and 255. The default +\fI\%\-T KEY\fP\&. The protocol is a number between 0 and 255. The default is 3 (DNSSEC). Other possible values for this argument are listed in \fI\%RFC 2535\fP and its successors. .UNINDENT @@ -233,7 +233,7 @@ SIG(0). .INDENT 0.0 .TP .B \-t type -This option indicates the type of the key for use with \fB\-T KEY\fP\&. \fBtype\fP +This option indicates the type of the key for use with \fI\%\-T KEY\fP\&. \fBtype\fP must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers to the ability to authenticate data, and CONF to the ability to encrypt data. @@ -263,7 +263,7 @@ explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&. .B \-P date/offset This option sets the date on which a key is to be published to the zone. After that date, the key is included in the zone but is not used -to sign it. If not set, and if the \fB\-G\fP option has not been used, the +to sign it. If not set, and if the \fI\%\-G\fP option has not been used, the default is the current date. .UNINDENT .INDENT 0.0 @@ -277,8 +277,8 @@ are to be published to the zone. .B \-A date/offset This option sets the date on which the key is to be activated. After that date, the key is included in the zone and used to sign it. If not set, -and if the \fB\-G\fP option has not been used, the default is the current date. If set, -and \fB\-P\fP is not set, the publication date is set to the +and if the \fI\%\-G\fP option has not been used, the default is the current date. If set, +and \fI\%\-P\fP is not set, the publication date is set to the activation date minus the prepublication interval. .UNINDENT .INDENT 0.0 diff --git a/doc/man/dnssec-settime.1in b/doc/man/dnssec-settime.1in index c396220d87..498bcd3b22 100644 --- a/doc/man/dnssec-settime.1in +++ b/doc/man/dnssec-settime.1in @@ -36,10 +36,10 @@ dnssec-settime \- set the key timing metadata for a DNSSEC key .SH DESCRIPTION .sp \fBdnssec\-settime\fP reads a DNSSEC private key file and sets the key -timing metadata as specified by the \fB\-P\fP, \fB\-A\fP, \fB\-R\fP, \fB\-I\fP, and -\fB\-D\fP options. The metadata can then be used by \fBdnssec\-signzone\fP or -other signing software to determine when a key is to be published, -whether it should be used for signing a zone, etc. +timing metadata as specified by the \fI\%\-P\fP, \fI\%\-A\fP, \fI\%\-R\fP, +\fI\%\-I\fP, and \fI\%\-D\fP options. The metadata can then be used by +\fBdnssec\-signzone\fP or other signing software to determine when a key is +to be published, whether it should be used for signing a zone, etc. .sp If none of these options is set on the command line, \fBdnssec\-settime\fP simply prints the key timing metadata already stored @@ -55,12 +55,12 @@ the key file. The private file\(aqs permissions are always set to be inaccessible to anyone other than the owner (mode 0600). .sp When working with state files, it is possible to update the timing metadata in -those files as well with \fB\-s\fP\&. With this option, it is also possible to update key -states with \fB\-d\fP (DS), \fB\-k\fP (DNSKEY), \fB\-r\fP (RRSIG of KSK), or \fB\-z\fP -(RRSIG of ZSK). Allowed states are HIDDEN, RUMOURED, OMNIPRESENT, and -UNRETENTIVE. +those files as well with \fI\%\-s\fP\&. With this option, it is also possible +to update key states with \fI\%\-d\fP (DS), \fI\%\-k\fP (DNSKEY), \fI\%\-r\fP +(RRSIG of KSK), or \fI\%\-z\fP (RRSIG of ZSK). Allowed states are HIDDEN, +RUMOURED, OMNIPRESENT, and UNRETENTIVE. .sp -The goal state of the key can also be set with \fB\-g\fP\&. This should be either +The goal state of the key can also be set with \fI\%\-g\fP\&. This should be either HIDDEN or OMNIPRESENT, representing whether the key should be removed from the zone or published. .sp @@ -266,7 +266,7 @@ This option indicates that times should be printed in Unix epoch format. .TP .B \-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all This option prints a specific metadata value or set of metadata values. -The \fB\-p\fP option may be followed by one or more of the following letters or +The \fI\%\-p\fP option may be followed by one or more of the following letters or strings to indicate which value or values to print: \fBC\fP for the creation date, \fBP\fP for the publication date, \fBPds\(ga for the DS publication date, \(ga\(gaPsync\fP for the CDS and CDNSKEY publication date, \fBA\fP for the diff --git a/doc/man/dnssec-signzone.1in b/doc/man/dnssec-signzone.1in index 759efd5feb..f59f6b2aac 100644 --- a/doc/man/dnssec-signzone.1in +++ b/doc/man/dnssec-signzone.1in @@ -68,9 +68,9 @@ This option indicates the directory where BIND 9 should look for \fBdsset\-\fP o .B \-D This option indicates that only those record types automatically managed by \fBdnssec\-signzone\fP, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output. -If smart signing (\fB\-S\fP) is used, DNSKEY records are also included. +If smart signing (\fI\%\-S\fP) is used, DNSKEY records are also included. The resulting file can be included in the original zone file with -\fB$INCLUDE\fP\&. This option cannot be combined with \fB\-O raw\fP +\fB$INCLUDE\fP\&. This option cannot be combined with \fI\%\-O raw\fP or serial\-number updating. .UNINDENT .INDENT 0.0 @@ -111,7 +111,7 @@ which is useful to know when rolling keys. The maxttl is the longest 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 \fBmax\-zone\-ttl\fP in -\fBnamed.conf\fP\&. (Note: This option is incompatible with \fB\-D\fP, +\fBnamed.conf\fP\&. (Note: This option is incompatible with \fI\%\-D\fP, because it modifies non\-DNSSEC data in the output zone.) .UNINDENT .INDENT 0.0 @@ -291,7 +291,7 @@ Normally, when a previously signed zone is passed as input to the signer, and a DNSKEY record has been removed and replaced with a new one, signatures from the old key that are still within their validity period are retained. This allows the zone to continue to validate -with cached copies of the old DNSKEY RRset. The \fB\-Q\fP option forces +with cached copies of the old DNSKEY RRset. The \fI\%\-Q\fP option forces \fBdnssec\-signzone\fP to remove signatures from keys that are no longer active. This enables ZSK rollover using the procedure described in \fI\%RFC 4641#4.2.1.1\fP ("Pre\-Publish Key Rollover"). @@ -310,7 +310,7 @@ zone. With the option that output is suppressed, leaving only the filename. .B \-R This option removes signatures from keys that are no longer published. .sp -This option is similar to \fB\-Q\fP, except it forces +This option is similar to \fI\%\-Q\fP, except it forces \fBdnssec\-signzone\fP to remove signatures from keys that are no longer published. This enables ZSK rollover using the procedure described in \fI\%RFC 4641#4.2.1.2\fP ("Double Signature Zone Signing Key @@ -360,7 +360,7 @@ synchronization records (type CDS and/or CDNSKEY) are removed. This option specifies a TTL to be used for new DNSKEY records imported into the zone from the key repository. If not specified, the default is the TTL value from the zone\(aqs SOA record. This option is ignored when -signing without \fB\-S\fP, since DNSKEY records are not imported from +signing without \fI\%\-S\fP, since DNSKEY records are not imported from the key repository in that case. It is also ignored if there are any pre\-existing DNSKEY records at the zone apex, in which case new records\(aq TTL values are set to match them, or if any of the @@ -420,9 +420,12 @@ is 10. .B \-A This option indicates that, when generating an NSEC3 chain, BIND 9 should set the OPTOUT flag on all NSEC3 records and should not generate NSEC3 records for insecure delegations. -.sp -Using this option twice (i.e., \fB\-AA\fP) turns the OPTOUT flag off for -all records. This is useful when using the \fB\-u\fP option to modify an +.UNINDENT +.INDENT 0.0 +.TP +.B \-AA +This option turns the OPTOUT flag off for +all records. This is useful when using the \fI\%\-u\fP option to modify an NSEC3 chain which previously had OPTOUT set. .UNINDENT .INDENT 0.0 @@ -442,10 +445,10 @@ the current directory, they are used for signing. .sp The following command signs the \fBexample.com\fP zone with the ECDSAP256SHA256 key generated by \fBdnssec\-keygen\fP -(Kexample.com.+013+17247). Because the \fB\-S\fP option is not being used, +(Kexample.com.+013+17247). Because the \fI\%\-S\fP option is not being used, the zone\(aqs keys must be in the master file (\fBdb.example.com\fP). This invocation looks for \fBdsset\fP files in the current directory, so that -DS records can be imported from them (\fB\-g\fP). +DS records can be imported from them (\fI\%\-g\fP). .INDENT 0.0 .INDENT 3.5 .sp diff --git a/doc/man/dnssec-verify.1in b/doc/man/dnssec-verify.1in index 09392181d1..ad6930df4e 100644 --- a/doc/man/dnssec-verify.1in +++ b/doc/man/dnssec-verify.1in @@ -94,7 +94,7 @@ This option verifies only that the DNSKEY RRset is signed with key\-signing keys Without this flag, it is assumed that the DNSKEY RRset is signed by all active keys. When this flag is set, it is not an error if the DNSKEY RRset is not signed by zone\-signing keys. This corresponds -to the \fB\-x\fP option in \fBdnssec\-signzone\fP\&. +to the \fB\-x option in dnssec\-signzone\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -110,11 +110,11 @@ be at least one non\-revoked, self\-signed DNSKEY, regardless of the KSK flag state, and that other RRsets be signed by a non\-revoked key for the same algorithm that includes the self\-signed key; the same key may be used for both purposes. This corresponds to -the \fB\-z\fP option in \fBdnssec\-signzone\fP\&. +the \fB\-z option in dnssec\-signzone\fP\&. .UNINDENT .INDENT 0.0 .TP -.B \fBzonefile\fP +.B zonefile This option indicates the file containing the zone to be signed. .UNINDENT .SH SEE ALSO diff --git a/doc/man/dnstap-read.1in b/doc/man/dnstap-read.1in index da8d01c250..8b09290419 100644 --- a/doc/man/dnstap-read.1in +++ b/doc/man/dnstap-read.1in @@ -37,7 +37,7 @@ dnstap-read \- print dnstap data in human-readable form .sp \fBdnstap\-read\fP reads \fBdnstap\fP data from a specified file and prints it in a human\-readable format. By default, \fBdnstap\fP data is printed in -a short summary format, but if the \fB\-y\fP option is specified, a +a short summary format, but if the \fI\%\-y\fP option is specified, a longer and more detailed YAML format is used. .SH OPTIONS .INDENT 0.0 diff --git a/doc/man/host.1in b/doc/man/host.1in index 4eaae39073..4e54442347 100644 --- a/doc/man/host.1in +++ b/doc/man/host.1in @@ -50,23 +50,23 @@ server or servers listed in \fB/etc/resolv.conf\fP\&. .INDENT 0.0 .TP .B \-4 -This option specifies that only IPv4 should be used for query transport. See also the \fB\-6\fP option. +This option specifies that only IPv4 should be used for query transport. See also the \fI\%\-6\fP option. .UNINDENT .INDENT 0.0 .TP .B \-6 -This option specifies that only IPv6 should be used for query transport. See also the \fB\-4\fP option. +This option specifies that only IPv6 should be used for query transport. See also the \fI\%\-4\fP option. .UNINDENT .INDENT 0.0 .TP .B \-a -The \fB\-a\fP ("all") option is normally equivalent to \fB\-v \-t ANY\fP\&. It -also affects the behavior of the \fB\-l\fP list zone option. +The \fI\%\-a\fP ("all") option is normally equivalent to \fI\%\-v\fP \fI\%\-t ANY\fP\&. It +also affects the behavior of the \fI\%\-l\fP list zone option. .UNINDENT .INDENT 0.0 .TP .B \-A -The \fB\-A\fP ("almost all") option is equivalent to \fB\-a\fP, except that RRSIG, +The \fI\%\-A\fP ("almost all") option is equivalent to \fI\%\-a\fP, except that RRSIG, NSEC, and NSEC3 records are omitted from the output. .UNINDENT .INDENT 0.0 @@ -86,7 +86,7 @@ found for the zone. .INDENT 0.0 .TP .B \-d -This option prints debugging traces, and is equivalent to the \fB\-v\fP verbose option. +This option prints debugging traces, and is equivalent to the \fI\%\-v\fP verbose option. .UNINDENT .INDENT 0.0 .TP @@ -94,7 +94,7 @@ This option prints debugging traces, and is equivalent to the \fB\-v\fP verbose This option tells \fBnamed\fP to list the zone, meaning the \fBhost\fP command performs a zone transfer of zone \fBname\fP and prints out the NS, PTR, and address records (A/AAAA). .sp -Together, the \fB\-l \-a\fP options print all records in the zone. +Together, the \fI\%\-l\fP \fI\%\-a\fP options print all records in the zone. .UNINDENT .INDENT 0.0 .TP @@ -116,7 +116,7 @@ This option specifies the port to query on the server. The default is 53. .B \-r This option specifies a non\-recursive query; setting this option clears the RD (recursion desired) bit in the query. This means that the name server -receiving the query does not attempt to resolve \fBname\fP\&. The \fB\-r\fP +receiving the query does not attempt to resolve \fBname\fP\&. The \fI\%\-r\fP option enables \fBhost\fP to mimic the behavior of a name server by making non\-recursive queries, and expecting to receive answers to those queries that can be referrals to other name servers. @@ -143,34 +143,34 @@ CNAME, NS, SOA, TXT, DNSKEY, AXFR, etc. .sp When no query type is specified, \fBhost\fP automatically selects an appropriate query type. By default, it looks for A, AAAA, and MX -records. If the \fB\-C\fP option is given, queries are made for SOA +records. If the \fI\%\-C\fP option is given, queries are made for SOA records. If \fBname\fP is a dotted\-decimal IPv4 address or colon\-delimited IPv6 address, \fBhost\fP queries for PTR records. .sp If a query type of IXFR is chosen, the starting serial number can be specified by appending an equals sign (=), followed by the starting serial -number, e.g., \fB\-t IXFR=12345678\fP\&. +number, e.g., \fI\%\-t IXFR=12345678\fP\&. .UNINDENT .INDENT 0.0 .TP -.B \-T\(ga\(ga; \(ga\(ga\-U +.B \-T, \-U This option specifies TCP or UDP. By default, \fBhost\fP uses UDP when making queries; the -\fB\-T\fP option makes it use a TCP connection when querying the name +\fI\%\-T\fP option makes it use a TCP connection when querying the name server. TCP is automatically selected for queries that require it, such as zone transfer (AXFR) requests. Type \fBANY\fP queries default -to TCP, but can be forced to use UDP initially via \fB\-U\fP\&. +to TCP, but can be forced to use UDP initially via \fI\%\-U\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-m flag This option sets memory usage debugging: the flag can be \fBrecord\fP, \fBusage\fP, or -\fBtrace\fP\&. The \fB\-m\fP option can be specified more than once to set +\fBtrace\fP\&. The \fI\%\-m\fP option can be specified more than once to set multiple flags. .UNINDENT .INDENT 0.0 .TP .B \-v -This option sets verbose output, and is equivalent to the \fB\-d\fP debug option. Verbose output +This option sets verbose output, and is equivalent to the \fI\%\-d\fP debug option. Verbose output can also be enabled by setting the \fBdebug\fP option in \fB/etc/resolv.conf\fP\&. .UNINDENT @@ -183,7 +183,7 @@ This option prints the version number and exits. .TP .B \-w This option sets "wait forever": the query timeout is set to the maximum possible. See -also the \fB\-W\fP option. +also the \fI\%\-W\fP option. .UNINDENT .INDENT 0.0 .TP @@ -195,7 +195,7 @@ By default, \fBhost\fP waits for 5 seconds for UDP responses and 10 seconds for TCP connections. These defaults can be overridden by the \fBtimeout\fP option in \fB/etc/resolv.conf\fP\&. .sp -See also the \fB\-w\fP option. +See also the \fI\%\-w\fP option. .UNINDENT .SH IDN SUPPORT .sp diff --git a/doc/man/mdig.1in b/doc/man/mdig.1in index 60d09faea4..5794844555 100644 --- a/doc/man/mdig.1in +++ b/doc/man/mdig.1in @@ -264,7 +264,7 @@ query class which is supported in BIND 9. The default query class is .B \-t type This option sets the query type to \fBtype\fP\&. It can be any valid query type which is supported in BIND 9. The default query type is "A", -unless the \fB\-x\fP option is supplied to indicate a reverse lookup with +unless the \fI\%\-x\fP option is supplied to indicate a reverse lookup with the "PTR" query type. .UNINDENT .INDENT 0.0 diff --git a/doc/man/named-checkconf.1in b/doc/man/named-checkconf.1in index b094851243..7e90403438 100644 --- a/doc/man/named-checkconf.1in +++ b/doc/man/named-checkconf.1in @@ -78,7 +78,7 @@ This option ignores warnings on deprecated options. .TP .B \-p This option prints out the \fBnamed.conf\fP and included files in canonical form if -no errors were detected. See also the \fB\-x\fP option. +no errors were detected. See also the \fI\%\-x\fP option. .UNINDENT .INDENT 0.0 .TP @@ -100,7 +100,7 @@ shared secrets by replacing them with strings of question marks (\fB?\fP). This allows the contents of \fBnamed.conf\fP and related files to be shared \- for example, when submitting bug reports \- without compromising private data. This option cannot be used without -\fB\-p\fP\&. +\fI\%\-p\fP\&. .UNINDENT .INDENT 0.0 .TP diff --git a/doc/man/named-checkzone.1in b/doc/man/named-checkzone.1in index 06a3411382..0cd75f13ed 100644 --- a/doc/man/named-checkzone.1in +++ b/doc/man/named-checkzone.1in @@ -72,7 +72,7 @@ string \fB\&.jnl\fP appended. .TP .B \-J filename When loading the zone file, this option tells \fBnamed\fP to read the journal from the given file, if -it exists. This implies \fB\-j\fP\&. +it exists. This implies \fI\%\-j\fP\&. .UNINDENT .INDENT 0.0 .TP diff --git a/doc/man/named-compilezone.1in b/doc/man/named-compilezone.1in index 96741bfc0f..8ae678cf5c 100644 --- a/doc/man/named-compilezone.1in +++ b/doc/man/named-compilezone.1in @@ -74,7 +74,7 @@ string \fB\&.jnl\fP appended. .TP .B \-J filename When loading the zone file, this option tells \fBnamed\fP to read the journal from the given file, if -it exists. This implies \fB\-j\fP\&. +it exists. This implies \fI\%\-j\fP\&. .UNINDENT .INDENT 0.0 .TP diff --git a/doc/man/named.8in b/doc/man/named.8in index e200fc37c7..7395e3c866 100644 --- a/doc/man/named.8in +++ b/doc/man/named.8in @@ -46,14 +46,14 @@ listens for queries. .INDENT 0.0 .TP .B \-4 -This option tells \fBnamed\fP to use only IPv4, even if the host machine is capable of IPv6. \fB\-4\fP and -\fB\-6\fP are mutually exclusive. +This option tells \fBnamed\fP to use only IPv4, even if the host machine is capable of IPv6. \fI\%\-4\fP and +\fI\%\-6\fP are mutually exclusive. .UNINDENT .INDENT 0.0 .TP .B \-6 -This option tells \fBnamed\fP to use only IPv6, even if the host machine is capable of IPv4. \fB\-4\fP and -\fB\-6\fP are mutually exclusive. +This option tells \fBnamed\fP to use only IPv6, even if the host machine is capable of IPv4. \fI\%\-4\fP and +\fI\%\-6\fP are mutually exclusive. .UNINDENT .INDENT 0.0 .TP @@ -184,7 +184,7 @@ before reading the configuration file. \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 -This option should be used in conjunction with the \fB\-u\fP option, +This option should be used in conjunction with the \fI\%\-u\fP option, as chrooting a process running as root doesn\(aqt enhance security on most systems; the way \fBchroot\fP is defined allows a process with root privileges to escape a chroot jail. @@ -198,8 +198,8 @@ each address. If not specified, \fBnamed\fP calculates a default value based on the number of detected CPUs: 1 for 1 CPU, and the number of detected CPUs minus one for machines with more than 1 CPU. This cannot be increased to a value higher than the number of CPUs. -If \fB\-n\fP has been set to a higher value than the number of detected -CPUs, then \fB\-U\fP may be increased as high as that value, but no +If \fI\%\-n\fP has been set to a higher value than the number of detected +CPUs, then \fI\%\-U\fP may be increased as high as that value, but no higher. .UNINDENT .INDENT 0.0 @@ -215,7 +215,7 @@ creating sockets that listen on privileged ports. On Linux, \fBnamed\fP uses the kernel\(aqs capability mechanism to drop all root privileges except the ability to \fBbind\fP to a privileged port and set process resource limits. Unfortunately, -this means that the \fB\-u\fP option only works when \fBnamed\fP is run +this means that the \fI\%\-u\fP option only works when \fBnamed\fP is run on kernel 2.2.18 or later, or kernel 2.3.99\-pre3 or later, since previous kernels did not allow privileges to be retained after \fBsetuid\fP\&. diff --git a/doc/man/nsupdate.1in b/doc/man/nsupdate.1in index 3a3d1c281b..7e3a7ea8fd 100644 --- a/doc/man/nsupdate.1in +++ b/doc/man/nsupdate.1in @@ -61,15 +61,15 @@ statements are added to \fB@sysconfdir@/named.conf\fP 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. \fBddns\-confgen\fP can generate suitable -configuration fragments. \fBnsupdate\fP uses the \fB\-y\fP or \fB\-k\fP options +configuration fragments. \fBnsupdate\fP uses the \fI\%\-y\fP or \fI\%\-k\fP options to provide the TSIG shared secret; these options are mutually exclusive. .sp SIG(0) uses public key cryptography. To use a SIG(0) key, the public key must be stored in a KEY record in a zone served by the name server. .sp GSS\-TSIG uses Kerberos credentials. Standard GSS\-TSIG mode is switched -on with the \fB\-g\fP flag. A non\-standards\-compliant variant of GSS\-TSIG -used by Windows 2000 can be switched on with the \fB\-o\fP flag. +on with the \fI\%\-g\fP flag. A non\-standards\-compliant variant of GSS\-TSIG +used by Windows 2000 can be switched on with the \fI\%\-o\fP flag. .SH OPTIONS .INDENT 0.0 .TP @@ -99,6 +99,11 @@ This option sets extra debug mode. .UNINDENT .INDENT 0.0 .TP +.B \-g +This option enables standard GSS\-TSIG mode. +.UNINDENT +.INDENT 0.0 +.TP .B \-i This option forces interactive mode, even when standard input is not a terminal. .UNINDENT @@ -111,7 +116,7 @@ statement, which may be generated automatically by \fBddns\-confgen\fP; or a pair of files whose names are of the format \fBK{name}.+157.+{random}.key\fP and \fBK{name}.+157.+{random}.private\fP, which can be generated by -\fBdnssec\-keygen\fP\&. The \fB\-k\fP option can also be used to specify a SIG(0) +\fBdnssec\-keygen\fP\&. The \fI\%\-k\fP 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. .UNINDENT @@ -124,7 +129,7 @@ overridden). Connections to the local server use a TSIG key found in \fB@runstatedir@/session.key\fP, which is automatically generated by \fBnamed\fP if any local \fBprimary\fP zone has set \fBupdate\-policy\fP to \fBlocal\fP\&. The location of this key file can be -overridden with the \fB\-k\fP option. +overridden with the \fI\%\-k\fP option. .UNINDENT .INDENT 0.0 .TP @@ -133,6 +138,12 @@ This option sets the logging debug level. If zero, logging is disabled. .UNINDENT .INDENT 0.0 .TP +.B \-o +This option enables a non\-standards\-compliant variant of GSS\-TSIG +used by Windows 2000. +.UNINDENT +.INDENT 0.0 +.TP .B \-p port This option sets the port to use for connections to a name server. The default is 53. @@ -141,7 +152,7 @@ This option sets the port to use for connections to a name server. The default i .TP .B \-P This option prints the list of private BIND\-specific resource record types whose -format is understood by \fBnsupdate\fP\&. See also the \fB\-T\fP option. +format is understood by \fBnsupdate\fP\&. See also the \fI\%\-T\fP option. .UNINDENT .INDENT 0.0 .TP @@ -160,7 +171,7 @@ default is 300 seconds. If zero, the timeout is disabled. .B \-T This option prints the list of IANA standard resource record types whose format is understood by \fBnsupdate\fP\&. \fBnsupdate\fP exits after the lists -are printed. The \fB\-T\fP option can be combined with the \fB\-P\fP +are printed. The \fI\%\-T\fP option can be combined with the \fI\%\-P\fP option. .sp Other types can be entered using \fBTYPEXXXXX\fP where \fBXXXXX\fP is the @@ -198,7 +209,7 @@ name of the key algorithm; valid choices are \fBhmac\-md5\fP, \fBhmac\-sha512\fP\&. If \fBhmac\fP is not specified, the default is \fBhmac\-md5\fP, or if MD5 was disabled, \fBhmac\-sha256\fP\&. .sp -NOTE: Use of the \fB\-y\fP option is discouraged because the shared +NOTE: Use of the \fI\%\-y\fP option is discouraged because the shared secret is supplied as a command\-line argument in clear text. This may be visible in the output from ps1 or in a history file maintained by the user\(aqs shell. @@ -258,15 +269,15 @@ This command specifies that all updates are to be TSIG\-signed using the \fBkeyname\fP\-\fBsecret\fP pair. If \fBhmac\fP is specified, it sets the signing algorithm in use. The default is \fBhmac\-md5\fP; if MD5 was disabled, the default is \fBhmac\-sha256\fP\&. The \fBkey\fP command overrides any key -specified on the command line via \fB\-y\fP or \fB\-k\fP\&. +specified on the command line via \fI\%\-y\fP or \fI\%\-k\fP\&. .TP .B \fBgsstsig\fP This command uses GSS\-TSIG to sign the updates. This is equivalent to specifying -\fB\-g\fP on the command line. +\fI\%\-g\fP on the command line. .TP .B \fBoldgsstsig\fP This command uses the Windows 2000 version of GSS\-TSIG to sign the updates. This is -equivalent to specifying \fB\-o\fP on the command line. +equivalent to specifying \fI\%\-o\fP on the command line. .TP .B \fBrealm [realm_name]\fP When using GSS\-TSIG, this command specifies the use of \fBrealm_name\fP rather than the default realm diff --git a/doc/man/rndc-confgen.8in b/doc/man/rndc-confgen.8in index 6abc3951bd..b937044f58 100644 --- a/doc/man/rndc-confgen.8in +++ b/doc/man/rndc-confgen.8in @@ -38,7 +38,7 @@ rndc-confgen \- rndc key generation tool \fBrndc\-confgen\fP generates configuration files for \fBrndc\fP\&. It can be used as a convenient alternative to writing the \fBrndc.conf\fP file and the corresponding \fBcontrols\fP and \fBkey\fP statements in \fBnamed.conf\fP -by hand. Alternatively, it can be run with the \fB\-a\fP option to set up a +by hand. Alternatively, it can be run with the \fI\%\-a\fP option to set up a \fBrndc.key\fP file and avoid the need for a \fBrndc.conf\fP file and a \fBcontrols\fP statement altogether. .SH OPTIONS @@ -53,7 +53,7 @@ the local host with no further configuration. .sp If a more elaborate configuration than that generated by \fBrndc\-confgen \-a\fP is required, for example if rndc is to be used -remotely, run \fBrndc\-confgen\fP without the \fB\-a\fP option +remotely, run \fBrndc\-confgen\fP without the \fI\%\-a\fP option and set up \fBrndc.conf\fP and \fBnamed.conf\fP as directed. .UNINDENT .INDENT 0.0 @@ -72,7 +72,7 @@ This option specifies the size of the authentication key in bits. The size must .INDENT 0.0 .TP .B \-c keyfile -This option is used with the \fB\-a\fP option to specify an alternate location for +This option is used with the \fI\%\-a\fP option to specify an alternate location for \fBrndc.key\fP\&. .UNINDENT .INDENT 0.0 @@ -108,7 +108,7 @@ connections from \fBrndc\fP\&. The default is the loopback address .INDENT 0.0 .TP .B \-t chrootdir -This option is used with the \fB\-a\fP option to specify a directory where \fBnamed\fP +This option is used with the \fI\%\-a\fP option to specify a directory where \fBnamed\fP runs chrooted. An additional copy of the \fBrndc.key\fP is written relative to this directory, so that it is found by the chrooted \fBnamed\fP\&. @@ -116,8 +116,8 @@ chrooted \fBnamed\fP\&. .INDENT 0.0 .TP .B \-u user -This option is used with the \fB\-a\fP option to set the owner of the generated \fBrndc.key\fP file. -If \fB\-t\fP is also specified, only the file in the chroot +This option is used with the \fI\%\-a\fP option to set the owner of the generated \fBrndc.key\fP file. +If \fI\%\-t\fP is also specified, only the file in the chroot area has its owner changed. .UNINDENT .SH EXAMPLES diff --git a/doc/man/rndc.8in b/doc/man/rndc.8in index bc6534c2c1..ebded5438d 100644 --- a/doc/man/rndc.8in +++ b/doc/man/rndc.8in @@ -161,7 +161,7 @@ the default view: (Note the brackets around and semi\-colon after the zone configuration text.) .sp -See also \fBrndc delzone\fP and \fBrndc modzone\fP\&. +See also \fI\%rndc delzone\fP and \fI\%rndc modzone\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -181,7 +181,7 @@ when the server is restarted or reconfigured, the zone is recreated. To remove it permanently, it must also be removed from \fBnamed.conf\fP\&. .sp -See also \fBrndc addzone\fP and \fBrndc modzone\fP\&. +See also \fI\%rndc addzone\fP and \fI\%rndc modzone\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -250,7 +250,7 @@ normally updated by dynamic update, and causes changes in the journal file to be synced into the master file. All dynamic update attempts are refused while the zone is frozen. .sp -See also \fBrndc thaw\fP\&. +See also \fI\%rndc thaw\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -262,14 +262,14 @@ forward from the journal files when the server is restarted. If an external process to determine when \fBnamed\fP has completed halting. .sp -See also \fBrndc stop\fP\&. +See also \fI\%rndc stop\fP\&. .UNINDENT .INDENT 0.0 .TP .B loadkeys [zone [class [view]]] This command fetches all DNSSEC keys for the given zone from the key directory. If they are within their publication period, they are merged into the -zone\(aqs DNSKEY RRset. Unlike \fBrndc sign\fP, however, the zone is not +zone\(aqs DNSKEY RRset. Unlike \fI\%rndc sign\fP, however, the zone is not immediately re\-signed by the new keys, but is allowed to incrementally re\-sign over time. .sp @@ -311,7 +311,7 @@ However, key maintenance operations cease until \fBnamed\fP is restarted or reconfigured, and all existing key maintenance states are deleted. .sp -Running \fBrndc reconfig\fP or restarting \fBnamed\fP immediately +Running \fI\%rndc reconfig\fP or restarting \fBnamed\fP 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 @@ -329,7 +329,7 @@ As with \fBaddzone\fP, the configuration string specified on the command line is the zone configuration text that would ordinarily be placed in \fBnamed.conf\fP\&. .sp -If the zone was originally added via \fBrndc addzone\fP, the +If the zone was originally added via \fI\%rndc addzone\fP, 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 \fBnamed.conf\fP, then that original @@ -338,7 +338,7 @@ reconfigured, the zone reverts to its original configuration. To make the changes permanent, it must also be modified in \fBnamed.conf\fP\&. .sp -See also \fBrndc addzone\fP and \fBrndc delzone\fP\&. +See also \fI\%rndc addzone\fP and \fI\%rndc delzone\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -350,7 +350,7 @@ This command resends NOTIFY messages for the zone. .B notrace This command sets the server\(aqs debugging level to 0. .sp -See also \fBrndc trace\fP\&. +See also \fI\%rndc trace\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -496,7 +496,7 @@ Otherwise, it is written to the secroots dump file, which defaults to \fBnamed.secroots\fP, but can be overridden via the \fBsecroots\-file\fP option in \fBnamed.conf\fP\&. .sp -See also \fBrndc managed\-keys\fP\&. +See also \fI\%rndc managed\-keys\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -517,7 +517,7 @@ answers is currently enabled or disabled. It also reports the values of .B showzone zone [class [view]] This command prints the configuration of a running zone. .sp -See also \fBrndc zonestatus\fP\&. +See also \fI\%rndc zonestatus\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -534,7 +534,7 @@ and also requires the zone to be configured to allow dynamic DNS. (See "Dynamic Update Policies" in the BIND 9 Administrator Reference Manual for more details.) .sp -See also \fBrndc loadkeys\fP\&. +See also \fI\%rndc loadkeys\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -606,7 +606,7 @@ 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 completed stopping. .sp -See also \fBrndc halt\fP\&. +See also \fI\%rndc halt\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -638,7 +638,7 @@ option is in use, the journal file is updated to reflect changes in the zone. Otherwise, if the zone has changed, any existing journal file is removed. .sp -See also \fBrndc freeze\fP\&. +See also \fI\%rndc freeze\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -650,7 +650,7 @@ This command increments the server\(aqs debugging level by one. .B trace level This command sets the server\(aqs debugging level to an explicit value. .sp -See also \fBrndc notrace\fP\&. +See also \fI\%rndc notrace\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -684,11 +684,11 @@ whether the zone supports dynamic updates, whether the zone is DNSSEC signed, whether it uses automatic DNSSEC key management or inline signing, and the scheduled refresh or expiry times for the zone. .sp -See also \fBrndc showzone\fP\&. +See also \fI\%rndc showzone\fP\&. .UNINDENT .sp -\fBrndc\fP commands that specify zone names, such as \fBreload\fP -\fBretransfer\fP, or \fBzonestatus\fP, can be ambiguous when applied to zones +\fBrndc\fP commands that specify zone names, such as \fI\%reload\fP +\fI\%retransfer\fP, or \fI\%zonestatus\fP, can be ambiguous when applied to zones of type \fBredirect\fP\&. Redirect zones are always called \fB\&.\fP, and can be confused with zones of type \fBhint\fP or with secondary copies of the root zone. To specify a redirect zone, use the special zone name diff --git a/doc/notes/notes-9.17.0.rst b/doc/notes/notes-9.17.0.rst index 8a8c67250c..2949f2bc82 100644 --- a/doc/notes/notes-9.17.0.rst +++ b/doc/notes/notes-9.17.0.rst @@ -63,7 +63,7 @@ Feature Changes .. _bug: https://sourceware.org/bugzilla/show_bug.cgi?id=23844 -- The ``rndc nta -dump`` and ``rndc secroots`` commands now both +- The :option:`rndc nta -dump ` and :option:`rndc secroots` commands now both include ``validate-except`` entries when listing negative trust anchors. These are indicated by the keyword ``permanent`` in place of the expiry date. :gl:`#1532` diff --git a/doc/notes/notes-9.17.11.rst b/doc/notes/notes-9.17.11.rst index 3afe0f500d..b0c4311d6f 100644 --- a/doc/notes/notes-9.17.11.rst +++ b/doc/notes/notes-9.17.11.rst @@ -50,7 +50,7 @@ Bug Fixes Note that journals created by the current version of ``named`` are not usable by versions prior to 9.16.12. Before downgrading to a prior release, users are advised to ensure that all dynamic zones have been - synchronized using ``rndc sync -clean``. + synchronized using :option:`rndc sync -clean `. A journal file's format can be changed manually by running ``named-journalprint -d`` (downgrade) or ``named-journalprint -u`` diff --git a/doc/notes/notes-9.17.12.rst b/doc/notes/notes-9.17.12.rst index 6035d1aafd..56985b9205 100644 --- a/doc/notes/notes-9.17.12.rst +++ b/doc/notes/notes-9.17.12.rst @@ -77,9 +77,9 @@ Bug Fixes :gl:`#2517` - Zones using KASP could not be thawed after they were frozen using - ``rndc freeze``. This has been fixed. :gl:`#2523` + :option:`rndc freeze`. This has been fixed. :gl:`#2523` -- After ``rndc dnssec -checkds`` or ``rndc dnssec -rollover`` is used, +- After :option:`rndc dnssec -checkds ` or :option:`rndc dnssec -rollover ` is used, ``named`` now immediately attempts to reconfigure zone keys. This change prevents unnecessary key rollover delays. :gl:`#2488` diff --git a/doc/notes/notes-9.17.13.rst b/doc/notes/notes-9.17.13.rst index 6bf1a83a01..8f8adb1965 100644 --- a/doc/notes/notes-9.17.13.rst +++ b/doc/notes/notes-9.17.13.rst @@ -61,8 +61,8 @@ Bug Fixes ``stale-cache-enable`` was set to ``yes``. This has been fixed. :gl:`#389` :gl:`#2289` -- A deadlock could occur when multiple ``rndc addzone``, ``rndc - delzone``, and/or ``rndc modzone`` commands were invoked +- A deadlock could occur when multiple :option:`rndc addzone`, :option:`rndc + delzone`, and/or :option:`rndc modzone` commands were invoked simultaneously for different zones. This has been fixed. :gl:`#2626` - ``inline-signing`` was incorrectly described as being inherited from diff --git a/doc/notes/notes-9.17.18.rst b/doc/notes/notes-9.17.18.rst index f93461d29d..81e2c3dc57 100644 --- a/doc/notes/notes-9.17.18.rst +++ b/doc/notes/notes-9.17.18.rst @@ -63,6 +63,6 @@ Bug Fixes a Combined Signing Key (CSK). :gl:`#2857` - When a dynamic zone was made available in another view using the - ``in-view`` statement, running ``rndc freeze`` always reported an + ``in-view`` statement, running :option:`rndc freeze` always reported an ``already frozen`` error even though the zone was successfully frozen. This has been fixed. :gl:`#2844` diff --git a/doc/notes/notes-9.17.2.rst b/doc/notes/notes-9.17.2.rst index 04df00bf9f..9640106b8d 100644 --- a/doc/notes/notes-9.17.2.rst +++ b/doc/notes/notes-9.17.2.rst @@ -100,8 +100,8 @@ Feature Changes in cache as a potential mitigation mechanism, should there be a problem with one or more domains. Note that cache content retention is independent of whether stale answers are used in response to - client queries (``stale-answer-enable yes|no`` and ``rndc serve-stale - on|off``). Serving of stale answers when the authoritative servers + client queries (``stale-answer-enable yes|no`` and :option:`rndc serve-stale + on|off `). Serving of stale answers when the authoritative servers are not responding must be explicitly enabled, whereas the retention of expired cache content takes place automatically on all versions of BIND 9 that have this feature available. :gl:`#1877` @@ -195,13 +195,13 @@ Bug Fixes of the current active key (the predecessor) was not changed and thus never removed from the zone. :gl:`#1846` -- When ``named-checkconf -z`` was run, it would sometimes incorrectly +- When :option:`named-checkconf -z` was run, it would sometimes incorrectly set its exit code. It reflected the status of the last view found; if zone-loading errors were found in earlier configured views but not in the last one, the exit code indicated success. Thanks to Graham Clinch. :gl:`#1807` -- ``named-checkconf -p`` could include spurious text in +- :option:`named-checkconf -p` could include spurious text in ``server-addresses`` statements due to an uninitialized DSCP value. This has been fixed. :gl:`#1812` diff --git a/doc/notes/notes-9.17.20.rst b/doc/notes/notes-9.17.20.rst index bbe329080c..59c460a29b 100644 --- a/doc/notes/notes-9.17.20.rst +++ b/doc/notes/notes-9.17.20.rst @@ -55,7 +55,7 @@ Feature Changes a steady response rate on a loaded resolver while these internal data structures are resized. :gl:`#2941` -- The output of ``rndc serve-stale status`` has been clarified. It now +- The output of :option:`rndc serve-stale status ` has been clarified. It now explicitly reports whether retention of stale data in the cache is enabled (``stale-cache-enable``), and whether returning such data in responses is enabled (``stale-answer-enable``). :gl:`#2742` diff --git a/doc/notes/notes-9.17.21.rst b/doc/notes/notes-9.17.21.rst index 206478bb43..47ab63959f 100644 --- a/doc/notes/notes-9.17.21.rst +++ b/doc/notes/notes-9.17.21.rst @@ -59,8 +59,8 @@ Bug Fixes ~~~~~~~~~ - Removing a configured ``catalog-zone`` clause from the configuration, - running ``rndc reconfig``, then bringing back the removed - ``catalog-zone`` clause and running ``rndc reconfig`` again caused + running :option:`rndc reconfig`, then bringing back the removed + ``catalog-zone`` clause and running :option:`rndc reconfig` again caused ``named`` to crash. This has been fixed. :gl:`#1608` - The resolver could hang on shutdown due to dispatch resources not diff --git a/doc/notes/notes-9.17.3.rst b/doc/notes/notes-9.17.3.rst index 1e1a818e00..b4e200dc28 100644 --- a/doc/notes/notes-9.17.3.rst +++ b/doc/notes/notes-9.17.3.rst @@ -15,7 +15,7 @@ Notes for BIND 9.17.3 New Features ~~~~~~~~~~~~ -- New ``rndc`` command ``rndc dnssec -status`` shows the current DNSSEC +- New ``rndc`` command :option:`rndc dnssec -status ` shows the current DNSSEC policy and keys in use, the key states, and rollover status. :gl:`#1612` @@ -68,8 +68,8 @@ Bug Fixes for ``check-names``, were not processed correctly and were being ignored. :gl:`#1949` -- ``rndc dnstap -roll `` did not limit the number of saved files - to ````. :gl:`!3728` +- :option:`rndc dnstap -roll value ` did not limit the number of saved files + to ``value``. :gl:`!3728` - The validator could fail to accept a properly signed RRset if an unsupported algorithm appeared earlier in the DNSKEY RRset than a diff --git a/doc/notes/notes-9.17.4.rst b/doc/notes/notes-9.17.4.rst index 3d793a4c71..4598f3dff2 100644 --- a/doc/notes/notes-9.17.4.rst +++ b/doc/notes/notes-9.17.4.rst @@ -125,5 +125,5 @@ Bug Fixes cases when it should have been calculated in days. This has been fixed. (Thanks to Tony Finch.) :gl:`!3735` -- LMDB locking code was revised to make ``rndc reconfig`` work properly +- LMDB locking code was revised to make :option:`rndc reconfig` work properly on FreeBSD and with LMDB >= 0.9.26. :gl:`#1976` diff --git a/doc/notes/notes-9.17.5.rst b/doc/notes/notes-9.17.5.rst index 297201e6d6..fb038c6f4d 100644 --- a/doc/notes/notes-9.17.5.rst +++ b/doc/notes/notes-9.17.5.rst @@ -15,7 +15,7 @@ Notes for BIND 9.17.5 New Features ~~~~~~~~~~~~ -- Add a new ``rndc`` command, ``rndc dnssec -checkds``, which signals to +- Add a new ``rndc`` command, :option:`rndc dnssec -checkds `, which signals to ``named`` that a DS record for a given zone or key has been published or withdrawn from the parent. This command replaces the time-based ``parent-registration-delay`` configuration option. :gl:`#1613` diff --git a/doc/notes/notes-9.17.6.rst b/doc/notes/notes-9.17.6.rst index 2ae912ec6b..900f4cccfc 100644 --- a/doc/notes/notes-9.17.6.rst +++ b/doc/notes/notes-9.17.6.rst @@ -15,10 +15,10 @@ Notes for BIND 9.17.6 New Features ~~~~~~~~~~~~ -- Add a new ``rndc`` command, ``rndc dnssec -rollover``, which triggers +- Add a new ``rndc`` command, :option:`rndc dnssec -rollover `, which triggers a manual rollover for a specific key. :gl:`#1749` -- Add a new ``rndc`` command, ``rndc dumpdb -expired``, which dumps the +- Add a new ``rndc`` command, :option:`rndc dumpdb -expired `, which dumps the cache database, including expired RRsets that are awaiting cleanup, to the ``dump-file`` for diagnostic purposes. :gl:`#1870` From ccc637835595380e9931703cb15e963b4fb31da3 Mon Sep 17 00:00:00 2001 From: Tony Finch Date: Thu, 3 Mar 2022 15:02:10 +0000 Subject: [PATCH 05/11] More man page option hyperlinks The dig man page wanted -h option hyperlink and anchor, and there were a couple of missing cross-references in the rndc man page. --- bin/dig/dig.rst | 6 +++++- bin/rndc/rndc.rst | 4 ++-- doc/man/dig.1in | 7 ++++++- doc/man/dnssec-cds.1in | 2 +- doc/man/rndc-confgen.8in | 2 +- doc/man/rndc.8in | 4 ++-- 6 files changed, 17 insertions(+), 8 deletions(-) diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst index b4f4295e0a..c2b51b1512 100644 --- a/bin/dig/dig.rst +++ b/bin/dig/dig.rst @@ -38,7 +38,7 @@ than ``dig``. Although ``dig`` is normally used with command-line arguments, it also has a batch mode of operation for reading lookup requests from a file. A brief summary of its command-line arguments and options is printed when -the ``-h`` option is given. The BIND 9 +the :option:`-h` option is given. The BIND 9 implementation of ``dig`` allows multiple lookups to be issued from the command line. @@ -125,6 +125,10 @@ Options same way it would be presented as a query to ``dig`` using the command-line interface. +.. option:: -h + + Print a usage summary. + .. option:: -k keyfile This option tells ``named`` to sign queries using TSIG using a key read from the given file. Key diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst index 276d02e99a..ec96bf963e 100644 --- a/bin/rndc/rndc.rst +++ b/bin/rndc/rndc.rst @@ -386,7 +386,7 @@ Currently supported commands are: This command reloads the configuration file and loads new zones, but does not reload existing zone files even if they have changed. This is faster than a - full ``reload`` when there is a large number of zones, because it + full :option:`rndc reload` when there is a large number of zones, because it avoids the need to examine the modification times of the zone files. .. option:: recursing @@ -434,7 +434,7 @@ Currently supported commands are: .. option:: scan This command scans the list of available network interfaces for changes, without - performing a full ``reconfig`` or waiting for the + performing a full :option:`rndc reconfig` or waiting for the ``interface-interval`` timer. .. option:: secroots [-] [view ...] diff --git a/doc/man/dig.1in b/doc/man/dig.1in index 7181d1c84b..670c72e9b5 100644 --- a/doc/man/dig.1in +++ b/doc/man/dig.1in @@ -49,7 +49,7 @@ than \fBdig\fP\&. Although \fBdig\fP is normally used with command\-line arguments, it also has a batch mode of operation for reading lookup requests from a file. A brief summary of its command\-line arguments and options is printed when -the \fB\-h\fP option is given. The BIND 9 +the \fI\%\-h\fP option is given. The BIND 9 implementation of \fBdig\fP allows multiple lookups to be issued from the command line. .sp @@ -147,6 +147,11 @@ command\-line interface. .UNINDENT .INDENT 0.0 .TP +.B \-h +Print a usage summary. +.UNINDENT +.INDENT 0.0 +.TP .B \-k keyfile This option tells \fBnamed\fP to sign queries using TSIG using a key read from the given file. Key files can be generated using \fBtsig\-keygen\fP\&. When using TSIG diff --git a/doc/man/dnssec-cds.1in b/doc/man/dnssec-cds.1in index 9bc561f69d..215fce457a 100644 --- a/doc/man/dnssec-cds.1in +++ b/doc/man/dnssec-cds.1in @@ -79,7 +79,7 @@ Be careful not to delete the DS records when \fBdnssec\-cds\fP fails! .UNINDENT .UNINDENT .sp -Alternatively, \fBdnssec\-cds \-u\fP writes an \fBnsupdate\fP script to the +Alternatively, :option\(gadnssec\-cds \-u\(ga writes an \fBnsupdate\fP script to the standard output. The \fI\%\-u\fP and \fI\%\-i\fP options can be used together to maintain a \fBdsset\-\fP file as well as emit an \fBnsupdate\fP script. .SH OPTIONS diff --git a/doc/man/rndc-confgen.8in b/doc/man/rndc-confgen.8in index b937044f58..9433875a43 100644 --- a/doc/man/rndc-confgen.8in +++ b/doc/man/rndc-confgen.8in @@ -52,7 +52,7 @@ authentication key allowing \fBrndc\fP to communicate with \fBnamed\fP on the local host with no further configuration. .sp If a more elaborate configuration than that generated by -\fBrndc\-confgen \-a\fP is required, for example if rndc is to be used +\fI\%rndc\-confgen \-a\fP is required, for example if rndc is to be used remotely, run \fBrndc\-confgen\fP without the \fI\%\-a\fP option and set up \fBrndc.conf\fP and \fBnamed.conf\fP as directed. .UNINDENT diff --git a/doc/man/rndc.8in b/doc/man/rndc.8in index ebded5438d..d94b544c7e 100644 --- a/doc/man/rndc.8in +++ b/doc/man/rndc.8in @@ -422,7 +422,7 @@ of \fBnamed.conf\fP, or by specifying \fBquerylog yes;\fP in the .B reconfig This command reloads the configuration file and loads new zones, but does not reload existing zone files even if they have changed. This is faster than a -full \fBreload\fP when there is a large number of zones, because it +full \fI\%rndc reload\fP when there is a large number of zones, because it avoids the need to examine the modification times of the zone files. .UNINDENT .INDENT 0.0 @@ -476,7 +476,7 @@ with new signatures. .TP .B scan This command scans the list of available network interfaces for changes, without -performing a full \fBreconfig\fP or waiting for the +performing a full \fI\%rndc reconfig\fP or waiting for the \fBinterface\-interval\fP timer. .UNINDENT .INDENT 0.0 From 7e7a946d4446e6a91fb994a8c2456289e8bf6e42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 3 Mar 2022 15:32:35 +0100 Subject: [PATCH 06/11] Introduce new Sphinx role iscman for ISC manual pages The new directive and role "iscman" allow to tag & reference man pages in our source tree. Essentially it is just namespacing for ISC man pages, but it comes with couple benefits. Differences from .. _man_program label we formerly used: - Does not expand :ref:`man_program` into full text of the page header. - Generates index entry with category "manual page". - Rendering style is closer to ubiquitous to the one produced by ``named`` syntax. Differences from Sphinx built-in :manpage: role: - Supports all builders with support for cross-references. - Generates internal links (unlike :manpage: which generates external URLs). - Checks that target exists withing our source tree. --- bin/check/named-checkconf.rst | 1 + bin/check/named-checkzone.rst | 1 + bin/check/named-compilezone.rst | 1 + bin/confgen/ddns-confgen.rst | 1 + bin/confgen/rndc-confgen.rst | 1 + bin/confgen/tsig-keygen.rst | 1 + bin/delv/delv.rst | 1 + bin/dig/dig.rst | 1 + bin/dig/host.rst | 1 + bin/dig/nslookup.rst | 1 + bin/dnssec/dnssec-cds.rst | 1 + bin/dnssec/dnssec-dsfromkey.rst | 1 + bin/dnssec/dnssec-importkey.rst | 1 + bin/dnssec/dnssec-keyfromlabel.rst | 1 + bin/dnssec/dnssec-keygen.rst | 1 + bin/dnssec/dnssec-revoke.rst | 1 + bin/dnssec/dnssec-settime.rst | 1 + bin/dnssec/dnssec-signzone.rst | 1 + bin/dnssec/dnssec-verify.rst | 1 + bin/named/named.conf.rst | 2 ++ bin/named/named.rst | 1 + bin/nsupdate/nsupdate.rst | 1 + bin/plugins/filter-a.rst | 1 + bin/plugins/filter-aaaa.rst | 1 + bin/rndc/rndc.conf.rst | 1 + bin/rndc/rndc.rst | 1 + bin/tools/arpaname.rst | 1 + bin/tools/dnstap-read.rst | 1 + bin/tools/mdig.rst | 1 + bin/tools/named-journalprint.rst | 1 + bin/tools/named-nzd2nzf.rst | 1 + bin/tools/named-rrchecker.rst | 1 + bin/tools/nsec3hash.rst | 1 + doc/arm/conf.py | 3 ++- doc/man/conf.py | 3 +++ 35 files changed, 39 insertions(+), 1 deletion(-) diff --git a/bin/check/named-checkconf.rst b/bin/check/named-checkconf.rst index 99b15d41df..e79debb20f 100644 --- a/bin/check/named-checkconf.rst +++ b/bin/check/named-checkconf.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: named-checkconf .. program:: named-checkconf .. _man_named-checkconf: diff --git a/bin/check/named-checkzone.rst b/bin/check/named-checkzone.rst index 25b9585a95..a28b970b1e 100644 --- a/bin/check/named-checkzone.rst +++ b/bin/check/named-checkzone.rst @@ -13,6 +13,7 @@ .. BEWARE: Do not forget to edit also named-compilezone.rst! +.. iscman:: named-checkzone .. program:: named-checkzone .. _man_named-checkzone: diff --git a/bin/check/named-compilezone.rst b/bin/check/named-compilezone.rst index 8d947c7407..6e10bbe2d0 100644 --- a/bin/check/named-compilezone.rst +++ b/bin/check/named-compilezone.rst @@ -13,6 +13,7 @@ .. BEWARE: Do not forget to edit also named-checkzone.rst! +.. iscman:: named-compilezone .. program:: named-compilezone .. _man_named-compilezone: diff --git a/bin/confgen/ddns-confgen.rst b/bin/confgen/ddns-confgen.rst index 2a290bcc57..7585e8c06f 100644 --- a/bin/confgen/ddns-confgen.rst +++ b/bin/confgen/ddns-confgen.rst @@ -13,6 +13,7 @@ .. BEWARE: Do not forget to edit also tsig-keygen.rst! +.. iscman:: ddns-confgen .. program:: ddns-confgen .. _man_ddns-confgen: diff --git a/bin/confgen/rndc-confgen.rst b/bin/confgen/rndc-confgen.rst index 5a5925fe77..7b165cb332 100644 --- a/bin/confgen/rndc-confgen.rst +++ b/bin/confgen/rndc-confgen.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: rndc-confgen .. program:: rndc-confgen .. _man_rndc-confgen: diff --git a/bin/confgen/tsig-keygen.rst b/bin/confgen/tsig-keygen.rst index 65582e2f08..4c7e8875ad 100644 --- a/bin/confgen/tsig-keygen.rst +++ b/bin/confgen/tsig-keygen.rst @@ -13,6 +13,7 @@ .. BEWARE: Do not forget to edit also ddns-confgen.rst! +.. iscman:: tsig-keygen .. program:: tsig-keygen .. _man_tsig-keygen: diff --git a/bin/delv/delv.rst b/bin/delv/delv.rst index 466bf5eb70..cb32f9bb5f 100644 --- a/bin/delv/delv.rst +++ b/bin/delv/delv.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: delv .. program:: delv .. _man_delv: diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst index c2b51b1512..bcd9167332 100644 --- a/bin/dig/dig.rst +++ b/bin/dig/dig.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dig .. program:: dig .. _man_dig: diff --git a/bin/dig/host.rst b/bin/dig/host.rst index 55ca5baec9..4299c874dc 100644 --- a/bin/dig/host.rst +++ b/bin/dig/host.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: host .. program:: host .. _man_host: diff --git a/bin/dig/nslookup.rst b/bin/dig/nslookup.rst index 04cebd6a17..08350194ca 100644 --- a/bin/dig/nslookup.rst +++ b/bin/dig/nslookup.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: nslookup .. program:: nslookup .. _man_nslookup: diff --git a/bin/dnssec/dnssec-cds.rst b/bin/dnssec/dnssec-cds.rst index 31cfbb3b40..3eb5384449 100644 --- a/bin/dnssec/dnssec-cds.rst +++ b/bin/dnssec/dnssec-cds.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dnssec-cds .. program:: dnssec-cds .. _man_dnssec-cds: diff --git a/bin/dnssec/dnssec-dsfromkey.rst b/bin/dnssec/dnssec-dsfromkey.rst index ca8d54a632..3d5cae2ddc 100644 --- a/bin/dnssec/dnssec-dsfromkey.rst +++ b/bin/dnssec/dnssec-dsfromkey.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dnssec-dsfromkey .. program:: dnssec-dsfromkey .. _man_dnssec-dsfromkey: diff --git a/bin/dnssec/dnssec-importkey.rst b/bin/dnssec/dnssec-importkey.rst index e22f06f032..5c939a9fe3 100644 --- a/bin/dnssec/dnssec-importkey.rst +++ b/bin/dnssec/dnssec-importkey.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dnssec-importkey .. program:: dnssec-importkey .. _man_dnssec-importkey: diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst index 98d94876b4..87d3e37c94 100644 --- a/bin/dnssec/dnssec-keyfromlabel.rst +++ b/bin/dnssec/dnssec-keyfromlabel.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dnssec-keyfromlabel .. program:: dnssec-keyfromlabel .. _man_dnssec-keyfromlabel: diff --git a/bin/dnssec/dnssec-keygen.rst b/bin/dnssec/dnssec-keygen.rst index 78358294d5..40c54e3fb0 100644 --- a/bin/dnssec/dnssec-keygen.rst +++ b/bin/dnssec/dnssec-keygen.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dnssec-keygen .. program:: dnssec-keygen .. _man_dnssec-keygen: diff --git a/bin/dnssec/dnssec-revoke.rst b/bin/dnssec/dnssec-revoke.rst index ef41812ee8..f8f4c99ca2 100644 --- a/bin/dnssec/dnssec-revoke.rst +++ b/bin/dnssec/dnssec-revoke.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dnssec-revoke .. program:: dnssec-revoke .. _man_dnssec-revoke: diff --git a/bin/dnssec/dnssec-settime.rst b/bin/dnssec/dnssec-settime.rst index 7ddaeb6b35..56b973ac3e 100644 --- a/bin/dnssec/dnssec-settime.rst +++ b/bin/dnssec/dnssec-settime.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dnssec-settime .. program:: dnssec-settime .. _man_dnssec-settime: diff --git a/bin/dnssec/dnssec-signzone.rst b/bin/dnssec/dnssec-signzone.rst index 8f1518e708..3ca6944f06 100644 --- a/bin/dnssec/dnssec-signzone.rst +++ b/bin/dnssec/dnssec-signzone.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dnssec-signzone .. program:: dnssec-signzone .. _man_dnssec-signzone: diff --git a/bin/dnssec/dnssec-verify.rst b/bin/dnssec/dnssec-verify.rst index ae97feefb0..1b4c3316e1 100644 --- a/bin/dnssec/dnssec-verify.rst +++ b/bin/dnssec/dnssec-verify.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dnssec-verify .. program:: dnssec-verify .. _man_dnssec-verify: diff --git a/bin/named/named.conf.rst b/bin/named/named.conf.rst index 86d92aff9f..4cb543ded8 100644 --- a/bin/named/named.conf.rst +++ b/bin/named/named.conf.rst @@ -11,6 +11,8 @@ .. highlight: console +.. iscman:: named.conf + named.conf - configuration file for **named** --------------------------------------------- diff --git a/bin/named/named.rst b/bin/named/named.rst index 072cb48761..8e7b334a6f 100644 --- a/bin/named/named.rst +++ b/bin/named/named.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: named .. program:: named .. _man_named: diff --git a/bin/nsupdate/nsupdate.rst b/bin/nsupdate/nsupdate.rst index 35c05f1905..dbefcd7521 100644 --- a/bin/nsupdate/nsupdate.rst +++ b/bin/nsupdate/nsupdate.rst @@ -9,6 +9,7 @@ .. See the COPYRIGHT file distributed with this work for additional .. information regarding copyright ownership. +.. iscman:: nsupdate .. program:: nsupdate .. _man_nsupdate: diff --git a/bin/plugins/filter-a.rst b/bin/plugins/filter-a.rst index 31802120f3..4650d6dca7 100644 --- a/bin/plugins/filter-a.rst +++ b/bin/plugins/filter-a.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: filter-a .. _man_filter-a: filter-a.so - filter A in DNS responses when AAAA is present diff --git a/bin/plugins/filter-aaaa.rst b/bin/plugins/filter-aaaa.rst index 8b63f5729b..d2ec514947 100644 --- a/bin/plugins/filter-aaaa.rst +++ b/bin/plugins/filter-aaaa.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: filter-aaaa .. _man_filter-aaaa: filter-aaaa.so - filter AAAA in DNS responses when A is present diff --git a/bin/rndc/rndc.conf.rst b/bin/rndc/rndc.conf.rst index 4b239eafc5..26ef20c12a 100644 --- a/bin/rndc/rndc.conf.rst +++ b/bin/rndc/rndc.conf.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: rndc.conf .. program:: rndc.conf .. _man_rndc.conf: diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst index ec96bf963e..21c80eb316 100644 --- a/bin/rndc/rndc.rst +++ b/bin/rndc/rndc.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: rndc .. program:: rndc .. _man_rndc: diff --git a/bin/tools/arpaname.rst b/bin/tools/arpaname.rst index ffe711f732..5ccd4e3264 100644 --- a/bin/tools/arpaname.rst +++ b/bin/tools/arpaname.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: arpaname .. program:: arpaname .. _man_arpaname: diff --git a/bin/tools/dnstap-read.rst b/bin/tools/dnstap-read.rst index 107162beea..db34606add 100644 --- a/bin/tools/dnstap-read.rst +++ b/bin/tools/dnstap-read.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dnstap-read .. program:: dnstap-read .. _man_dnstap-read: diff --git a/bin/tools/mdig.rst b/bin/tools/mdig.rst index 3bf85f2991..b56e318b62 100644 --- a/bin/tools/mdig.rst +++ b/bin/tools/mdig.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: mdig .. program:: mdig .. _man_mdig: diff --git a/bin/tools/named-journalprint.rst b/bin/tools/named-journalprint.rst index 2fb08f5cac..2d9caab89f 100644 --- a/bin/tools/named-journalprint.rst +++ b/bin/tools/named-journalprint.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: named-journalprint .. program:: named-journalprint .. _man_named-journalprint: diff --git a/bin/tools/named-nzd2nzf.rst b/bin/tools/named-nzd2nzf.rst index aaffc73966..be2c5ee2ea 100644 --- a/bin/tools/named-nzd2nzf.rst +++ b/bin/tools/named-nzd2nzf.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: named-nzd2nzf .. program:: named-nzd2nzf .. _man_named-nzd2nzf: diff --git a/bin/tools/named-rrchecker.rst b/bin/tools/named-rrchecker.rst index 84ab388093..4ff3b27fa9 100644 --- a/bin/tools/named-rrchecker.rst +++ b/bin/tools/named-rrchecker.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: named-rrchecker .. program:: named-rrchecker .. _man_named-rrchecker: diff --git a/bin/tools/nsec3hash.rst b/bin/tools/nsec3hash.rst index 58550e1b25..2429e317d0 100644 --- a/bin/tools/nsec3hash.rst +++ b/bin/tools/nsec3hash.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: nsec3hash .. program:: nsec3hash .. _man_nsec3hash: diff --git a/doc/arm/conf.py b/doc/arm/conf.py index 4c3640fae3..947138f535 100644 --- a/doc/arm/conf.py +++ b/doc/arm/conf.py @@ -81,8 +81,9 @@ class GitLabRefRole(ReferenceRole): raise ValueError -def setup(_): +def setup(app): roles.register_local_role('gl', GitLabRefRole(GITLAB_BASE_URL)) + app.add_crossref_type('iscman', 'iscman', 'pair: %s; manual page') # # Configuration file for the Sphinx documentation builder. diff --git a/doc/man/conf.py b/doc/man/conf.py index 929155c07b..dd472411dd 100644 --- a/doc/man/conf.py +++ b/doc/man/conf.py @@ -116,3 +116,6 @@ rst_epilog = """ .. |named_pid| replace: ``@runstatedir@/named.pid`` .. |session_key| replace: ``@runstatedir@/session.key`` """ + +def setup(app): + app.add_crossref_type('iscman', 'iscman', 'pair: %s; manual page') From c7085be211992a253861c6c39969047d1abdac5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 3 Mar 2022 16:00:43 +0100 Subject: [PATCH 07/11] Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1" --- bin/check/named-checkconf.rst | 12 +++--- bin/check/named-checkzone.rst | 10 ++--- bin/check/named-compilezone.rst | 8 ++-- bin/confgen/ddns-confgen.rst | 4 +- bin/confgen/rndc-confgen.rst | 8 ++-- bin/confgen/tsig-keygen.rst | 2 +- bin/delv/delv.rst | 60 +++++++++++++-------------- bin/dig/dig.rst | 66 +++++++++++++++--------------- bin/dig/host.rst | 28 ++++++------- bin/dig/nslookup.rst | 14 +++---- bin/dnssec/dnssec-cds.rst | 28 ++++++------- bin/dnssec/dnssec-dsfromkey.rst | 12 +++--- bin/dnssec/dnssec-importkey.rst | 2 +- bin/dnssec/dnssec-keyfromlabel.rst | 10 ++--- bin/dnssec/dnssec-keygen.rst | 18 ++++---- bin/dnssec/dnssec-revoke.rst | 4 +- bin/dnssec/dnssec-settime.rst | 8 ++-- bin/dnssec/dnssec-signzone.rst | 22 +++++----- bin/dnssec/dnssec-verify.rst | 4 +- bin/named/named.rst | 40 +++++++++--------- bin/nsupdate/nsupdate.rst | 28 ++++++------- bin/rndc/rndc.conf.rst | 8 ++-- bin/rndc/rndc.rst | 24 +++++------ bin/tools/arpaname.rst | 2 +- bin/tools/dnstap-read.rst | 2 +- bin/tools/mdig.rst | 28 ++++++------- bin/tools/named-journalprint.rst | 4 +- bin/tools/named-nzd2nzf.rst | 2 +- bin/tools/named-rrchecker.rst | 2 +- bin/tools/nsec3hash.rst | 2 +- 30 files changed, 231 insertions(+), 231 deletions(-) diff --git a/bin/check/named-checkconf.rst b/bin/check/named-checkconf.rst index e79debb20f..5c5a84beef 100644 --- a/bin/check/named-checkconf.rst +++ b/bin/check/named-checkconf.rst @@ -26,16 +26,16 @@ Synopsis Description ~~~~~~~~~~~ -``named-checkconf`` checks the syntax, but not the semantics, of a +: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 errors. If no file is specified, |named_conf| is read by default. Note: files that ``named`` reads in separate parser contexts, such as ``rndc.key`` and ``bind.keys``, are not automatically read by -``named-checkconf``. Configuration errors in these files may cause -``named`` to fail to run, even if ``named-checkconf`` was successful. -However, ``named-checkconf`` can be run on these files explicitly. +:program:`named-checkconf`. Configuration errors in these files may cause +``named`` to fail to run, even if :program:`named-checkconf` was successful. +However, :program:`named-checkconf` can be run on these files explicitly. Options ~~~~~~~ @@ -76,7 +76,7 @@ Options .. option:: -v - This option prints the version of the ``named-checkconf`` program and exits. + This option prints the version of the :program:`named-checkconf` program and exits. .. option:: -x @@ -99,7 +99,7 @@ Options Return Values ~~~~~~~~~~~~~ -``named-checkconf`` returns an exit status of 1 if errors were detected +:program:`named-checkconf` returns an exit status of 1 if errors were detected and 0 otherwise. See Also diff --git a/bin/check/named-checkzone.rst b/bin/check/named-checkzone.rst index a28b970b1e..147234029d 100644 --- a/bin/check/named-checkzone.rst +++ b/bin/check/named-checkzone.rst @@ -28,9 +28,9 @@ Synopsis Description ~~~~~~~~~~~ -``named-checkzone`` checks the syntax and integrity of a zone file. It +: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 -makes ``named-checkzone`` useful for checking zone files before +makes :program:`named-checkzone` useful for checking zone files before configuring them into a name server. Options @@ -51,7 +51,7 @@ Options .. option:: -v - This option prints the version of the ``named-checkzone`` program and exits. + This option prints the version of the :program:`named-checkzone` program and exits. .. option:: -j @@ -103,7 +103,7 @@ 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 + :program:`named-checkzone`, this does not have any effect unless it dumps the zone contents. Possible formats are ``text`` (the default), which is the standard @@ -212,7 +212,7 @@ Options Return Values ~~~~~~~~~~~~~ -``named-checkzone`` returns an exit status of 1 if errors were detected +:program:`named-checkzone` returns an exit status of 1 if errors were detected and 0 otherwise. See Also diff --git a/bin/check/named-compilezone.rst b/bin/check/named-compilezone.rst index 6e10bbe2d0..bd936d3b5b 100644 --- a/bin/check/named-compilezone.rst +++ b/bin/check/named-compilezone.rst @@ -28,7 +28,7 @@ Synopsis Description ~~~~~~~~~~~ -``named-compilezone`` checks the syntax and integrity of a zone file, +: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``. @@ -152,7 +152,7 @@ Options .. option:: -o filename This option writes the zone output to ``filename``. If ``filename`` is ``-``, then - the zone output is written to standard output. This is mandatory for ``named-compilezone``. + the zone output is written to standard output. This is mandatory for :program:`named-compilezone`. .. option:: -r mode @@ -194,7 +194,7 @@ Options .. option:: -D This option dumps the zone file in canonical format. This is always enabled for - ``named-compilezone``. + :program:`named-compilezone`. .. option:: -W mode @@ -214,7 +214,7 @@ Options Return Values ~~~~~~~~~~~~~ -``named-compilezone`` returns an exit status of 1 if errors were detected +:program:`named-compilezone` returns an exit status of 1 if errors were detected and 0 otherwise. See Also diff --git a/bin/confgen/ddns-confgen.rst b/bin/confgen/ddns-confgen.rst index 7585e8c06f..bed8437c63 100644 --- a/bin/confgen/ddns-confgen.rst +++ b/bin/confgen/ddns-confgen.rst @@ -27,7 +27,7 @@ Synopsis Description ~~~~~~~~~~~ -``ddns-confgen`` is an utility that generates keys for use in TSIG signing. +: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. @@ -40,7 +40,7 @@ command-channel security.) Note that ``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;``. ``ddns-confgen`` is only needed when a more +``update-policy local;``. :program:`ddns-confgen` is only needed when a more elaborate configuration is required: for instance, if ``nsupdate`` is to be used from a remote system. diff --git a/bin/confgen/rndc-confgen.rst b/bin/confgen/rndc-confgen.rst index 7b165cb332..41f857c01c 100644 --- a/bin/confgen/rndc-confgen.rst +++ b/bin/confgen/rndc-confgen.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``rndc-confgen`` generates configuration files for ``rndc``. It can be +: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`` by hand. Alternatively, it can be run with the :option:`-a` option to set up a @@ -46,7 +46,7 @@ Options 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 ``rndc-confgen`` without the :option:`-a` option + remotely, run :program:`rndc-confgen` without the :option:`-a` option and set up ``rndc.conf`` and ``named.conf`` as directed. .. option:: -A algorithm @@ -68,7 +68,7 @@ Options .. option:: -h This option prints a short summary of the options and arguments to - ``rndc-confgen``. + :program:`rndc-confgen`. .. option:: -k keyname @@ -113,7 +113,7 @@ To allow ``rndc`` to be used with no manual configuration, run: To print a sample ``rndc.conf`` file and the corresponding ``controls`` and ``key`` statements to be manually inserted into ``named.conf``, run: -``rndc-confgen`` +:program:`rndc-confgen` See Also ~~~~~~~~ diff --git a/bin/confgen/tsig-keygen.rst b/bin/confgen/tsig-keygen.rst index 4c7e8875ad..311dcfbb4c 100644 --- a/bin/confgen/tsig-keygen.rst +++ b/bin/confgen/tsig-keygen.rst @@ -27,7 +27,7 @@ Synopsis Description ~~~~~~~~~~~ -``tsig-keygen`` is an utility that generates keys for use in TSIG signing. +: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. diff --git a/bin/delv/delv.rst b/bin/delv/delv.rst index cb32f9bb5f..e444825978 100644 --- a/bin/delv/delv.rst +++ b/bin/delv/delv.rst @@ -32,10 +32,10 @@ Synopsis Description ~~~~~~~~~~~ -``delv`` is a tool for sending DNS queries and validating the results, +:program:`delv` is a tool for sending DNS queries and validating the results, using the same internal resolver and validator logic as ``named``. -``delv`` sends to a specified name server all queries needed to +:program:`delv` sends to a specified name server all queries needed to fetch and validate the requested data; this includes the original requested query, subsequent queries to follow CNAME or DNAME chains, queries for DNSKEY, and DS records to establish a chain of trust for @@ -44,25 +44,25 @@ simulates the behavior of a name server configured for DNSSEC validating and forwarding. By default, responses are validated using the built-in DNSSEC trust anchor -for the root zone ("."). Records returned by ``delv`` are either fully +for the root zone ("."). Records returned by :program:`delv` are either fully validated or were not signed. If validation fails, an explanation of the failure is included in the output; the validation process can be traced -in detail. Because ``delv`` does not rely on an external server to carry +in detail. Because :program:`delv` does not rely on an external server to carry out validation, it can be used to check the validity of DNS responses in environments where local name servers may not be trustworthy. -Unless it is told to query a specific name server, ``delv`` tries +Unless it is told to query a specific name server, :program:`delv` tries each of the servers listed in ``/etc/resolv.conf``. If no usable server -addresses are found, ``delv`` sends queries to the localhost +addresses are found, :program:`delv` sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1 for IPv6). -When no command-line arguments or options are given, ``delv`` +When no command-line arguments or options are given, :program:`delv` performs an NS query for "." (the root zone). Simple Usage ~~~~~~~~~~~~ -A typical invocation of ``delv`` looks like: +A typical invocation of :program:`delv` looks like: :: @@ -75,15 +75,15 @@ where: is the name or IP address of the name server to query. This can be an IPv4 address in dotted-decimal notation or an IPv6 address in colon-delimited notation. When the supplied ``server`` argument is a - hostname, ``delv`` resolves that name before querying that name + hostname, :program:`delv` resolves that name before querying that name server (note, however, that this initial lookup is *not* validated by DNSSEC). - If no ``server`` argument is provided, ``delv`` consults + If no ``server`` argument is provided, :program:`delv` consults ``/etc/resolv.conf``; if an address is found there, it queries the name server at that address. If either of the :option:`-4` or :option:`-6` options is in use, then only addresses for the corresponding - transport are tried. If no usable addresses are found, ``delv`` + transport are tried. If no usable addresses are found, :program:`delv` sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1 for IPv6). @@ -95,7 +95,7 @@ where: indicates what type of query is required - ANY, A, MX, etc. ``type`` can be any valid query type. If no ``type`` argument is - supplied, ``delv`` performs a lookup for an A record. + supplied, :program:`delv` performs a lookup for an A record. Options ~~~~~~~ @@ -109,13 +109,13 @@ Options Keys that do not match the root zone name are ignored. An alternate key name can be specified using the ``+root=NAME`` options. - Note: When reading the trust anchor file, ``delv`` treats ``trust-anchors``, + Note: When reading the trust anchor file, :program:`delv` treats ``trust-anchors``, ``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. ``delv`` does not consult the managed-keys database maintained by + 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 revoked and rolled over, |bind_keys| must be updated to - use DNSSEC validation in ``delv``. + use DNSSEC validation in :program:`delv`. .. option:: -b address @@ -127,26 +127,26 @@ Options .. option:: -c class This option sets the query class for the requested data. Currently, only class - "IN" is supported in ``delv`` and any other value is ignored. + "IN" is supported in :program:`delv` and any other value is ignored. .. option:: -d level This option sets the systemwide debug level to ``level``. The allowed range is from 0 to 99. The default is 0 (no debugging). Debugging traces from - ``delv`` become more verbose as the debug level increases. See the + :program:`delv` become more verbose as the debug level increases. See the ``+mtrace``, ``+rtrace``, and ``+vtrace`` options below for additional debugging details. .. option:: -h - This option displays the ``delv`` help usage output and exits. + This option displays the :program:`delv` help usage output and exits. .. option:: -i This option sets insecure mode, which disables internal DNSSEC validation. (Note, however, that this does not set the CD bit on upstream queries. If the server being queried is performing DNSSEC validation, then it does - not return invalid data; this can cause ``delv`` to time out. When it + not return invalid data; this can cause :program:`delv` to time out. When it is necessary to examine invalid data to debug a DNSSEC problem, use ``dig +cd``.) @@ -182,30 +182,30 @@ Options .. option:: -v - This option prints the ``delv`` version and exits. + This option prints the :program:`delv` version and exits. .. option:: -x addr This option performs a reverse lookup, mapping an address to a name. ``addr`` is an IPv4 address in dotted-decimal notation, or a colon-delimited IPv6 address. When :option:`-x` is used, there is no need to provide the - ``name`` or ``type`` arguments; ``delv`` automatically performs a + ``name`` or ``type`` arguments; :program:`delv` automatically performs a lookup for a name like ``11.12.13.10.in-addr.arpa`` and sets the query type to PTR. IPv6 addresses are looked up using nibble format under the IP6.ARPA domain. .. option:: -4 - This option forces ``delv`` to only use IPv4. + This option forces :program:`delv` to only use IPv4. .. option:: -6 - This option forces ``delv`` to only use IPv6. + This option forces :program:`delv` to only use IPv6. Query Options ~~~~~~~~~~~~~ -``delv`` provides a number of query options which affect the way results +:program:`delv` provides a number of query options which affect the way results are displayed, and in some cases the way lookups are performed. Each query option is identified by a keyword preceded by a plus sign @@ -217,11 +217,11 @@ assign values to options like the timeout interval. They have the form .. option:: +[no]cdflag This option controls whether to set the CD (checking disabled) bit in queries - sent by ``delv``. This may be useful when troubleshooting DNSSEC + sent by :program:`delv`. This may be useful when troubleshooting DNSSEC problems from behind a validating resolver. A validating resolver blocks invalid responses, making it difficult to retrieve them for analysis. Setting the CD flag on queries causes the resolver - to return invalid responses, which ``delv`` can then validate + to return invalid responses, which :program:`delv` can then validate internally and report the errors in detail. .. option:: +[no]class @@ -237,7 +237,7 @@ assign values to options like the timeout interval. They have the form .. option:: +[no]rtrace This option toggles resolver fetch logging. This reports the name and type of each - query sent by ``delv`` in the process of carrying out the resolution + query sent by :program:`delv` in the process of carrying out the resolution and validation process, including the original query and all subsequent queries to follow CNAMEs and to establish a chain of trust for DNSSEC validation. @@ -250,7 +250,7 @@ assign values to options like the timeout interval. They have the form .. option:: +[no]mtrace This option toggles message logging. This produces a detailed dump of the - responses received by ``delv`` in the process of carrying out the + responses received by :program:`delv` in the process of carrying out the resolution and validation process. This is equivalent to setting the debug level to 10 for the "packets" @@ -317,11 +317,11 @@ assign values to options like the timeout interval. They have the form This option prints long records (such as RRSIG, DNSKEY, and SOA records) in a verbose multi-line format with human-readable comments. The default is to print each record on a single line, to facilitate machine - parsing of the ``delv`` output. + parsing of the :program:`delv` output. .. option:: +[no]dnssec - This option indicates whether to display RRSIG records in the ``delv`` output. + 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 *not* control whether to request DNSSEC records or to validate them. DNSSEC records are always requested, and validation diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst index bcd9167332..b6461819d8 100644 --- a/bin/dig/dig.rst +++ b/bin/dig/dig.rst @@ -29,28 +29,28 @@ Synopsis Description ~~~~~~~~~~~ -``dig`` is a flexible tool for interrogating DNS name servers. It +:program:`dig` is a flexible tool for interrogating DNS name servers. It performs DNS lookups and displays the answers that are returned from the -name server(s) that were queried. Most DNS administrators use ``dig`` to +name server(s) that were queried. Most DNS administrators use :program:`dig` to troubleshoot DNS problems because of its flexibility, ease of use, and clarity of output. Other lookup tools tend to have less functionality -than ``dig``. +than :program:`dig`. -Although ``dig`` is normally used with command-line arguments, it also +Although :program:`dig` is normally used with command-line arguments, it also has a batch mode of operation for reading lookup requests from a file. A brief summary of its command-line arguments and options is printed when the :option:`-h` option is given. The BIND 9 -implementation of ``dig`` allows multiple lookups to be issued from the +implementation of :program:`dig` allows multiple lookups to be issued from the command line. -Unless it is told to query a specific name server, ``dig`` tries each +Unless it is told to query a specific name server, :program:`dig` tries each of the servers listed in ``/etc/resolv.conf``. If no usable server -addresses are found, ``dig`` sends the query to the local host. +addresses are found, :program:`dig` sends the query to the local host. -When no command-line arguments or options are given, ``dig`` +When no command-line arguments or options are given, :program:`dig` performs an NS query for "." (the root). -It is possible to set per-user defaults for ``dig`` via +It is possible to set per-user defaults for :program:`dig` via ``${HOME}/.digrc``. This file is read and any options in it are applied before the command-line arguments. The :option:`-r` option disables this feature, for scripts that need predictable behavior. @@ -63,7 +63,7 @@ class, use the :option:`-q` to specify the domain name, or use "IN." and Simple Usage ~~~~~~~~~~~~ -A typical invocation of ``dig`` looks like: +A typical invocation of :program:`dig` looks like: :: @@ -76,14 +76,14 @@ where: is the name or IP address of the name server to query. This can be an IPv4 address in dotted-decimal notation or an IPv6 address in colon-delimited notation. When the supplied ``server`` argument is a - hostname, ``dig`` resolves that name before querying that name + hostname, :program:`dig` resolves that name before querying that name server. - If no ``server`` argument is provided, ``dig`` consults + If no ``server`` argument is provided, :program:`dig` consults ``/etc/resolv.conf``; if an address is found there, it queries the name server at that address. If either of the :option:`-4` or :option:`-6` options are in use, then only addresses for the corresponding - transport are tried. If no usable addresses are found, ``dig`` + transport are tried. If no usable addresses are found, :program:`dig` sends the query to the local host. The reply from the name server that responds is displayed. @@ -95,7 +95,7 @@ where: indicates what type of query is required - ANY, A, MX, SIG, etc. ``type`` can be any valid query type. If no ``type`` argument is - supplied, ``dig`` performs a lookup for an A record. + supplied, :program:`dig` performs a lookup for an A record. Options ~~~~~~~ @@ -121,9 +121,9 @@ Options .. option:: -f file - This option sets batch mode, in which ``dig`` reads a list of lookup requests to process from + This option sets batch mode, in which :program:`dig` reads a list of lookup requests to process from the given ``file``. Each line in the file should be organized in the - same way it would be presented as a query to ``dig`` using the + same way it would be presented as a query to :program:`dig` using the command-line interface. .. option:: -h @@ -134,7 +134,7 @@ Options 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 - authentication with ``dig``, the name server that is queried needs to + 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``. @@ -190,7 +190,7 @@ Options ``addr`` is an IPv4 address in dotted-decimal notation, or a colon-delimited IPv6 address. When the :option:`-x` option is used, there is no need to provide the ``name``, ``class``, and ``type`` arguments. - ``dig`` automatically performs a lookup for a name like + :program:`dig` automatically performs a lookup for a name like ``94.2.0.192.in-addr.arpa`` and sets the query type and class to PTR and IN respectively. IPv6 addresses are looked up using nibble format under the IP6.ARPA domain. @@ -213,7 +213,7 @@ Options Query Options ~~~~~~~~~~~~~ -``dig`` provides a number of query options which affect the way in which +:program:`dig` provides a number of query options which affect the way in which lookups are made and the results displayed. Some of these set or reset flag bits in the query header, some determine which sections of the answer get printed, and others determine the timeout and retry @@ -292,7 +292,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to .. option:: +[no]cmd This option toggles the printing of the initial comment in the output, identifying the - version of ``dig`` and the query options that have been applied. This option + version of :program:`dig` and the query options that have been applied. This option always has a global effect; it cannot be set globally and then overridden on a per-lookup basis. The default is to print this comment. @@ -437,7 +437,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to ``IDN SUPPORT`` to have been enabled at compile time. The default is to process IDN input when standard output is a tty. - The IDN processing on input is disabled when ``dig`` output is redirected + The IDN processing on input is disabled when :program:`dig` output is redirected to files, pipes, and other non-tty file descriptors. .. option:: +[no]idnout @@ -446,7 +446,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to ``IDN SUPPORT`` to have been enabled at compile time. The default is to process puny code on output when standard output is - a tty. The puny code processing on output is disabled when ``dig`` output + a tty. The puny code processing on output is disabled when :program:`dig` output is redirected to files, pipes, and other non-tty file descriptors. .. option:: +[no]ignore @@ -468,7 +468,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to This option prints [or does not print] records, like the SOA records, in a verbose multi-line format with human-readable comments. The default is to print each record on - a single line to facilitate machine parsing of the ``dig`` output. + a single line to facilitate machine parsing of the :program:`dig` output. .. option:: +ndots=D @@ -486,7 +486,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to .. option:: +[no]nssearch - When this option is set, ``dig`` attempts to find the authoritative + When this option is set, :program:`dig` attempts to find the authoritative name servers for the zone containing the name being looked up, and display the SOA record that each name server has for the zone. Addresses of servers that did not respond are also printed. @@ -538,7 +538,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to .. option:: +[no]recurse This option toggles the setting of the RD (recursion desired) bit in the query. - This bit is set by default, which means ``dig`` normally sends + This bit is set by default, which means :program:`dig` normally sends recursive queries. Recursion is automatically disabled when the ``+nssearch`` or ``+trace`` query option is used. @@ -641,7 +641,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to This option toggles tracing of the delegation path from the root name servers for the name being looked up. Tracing is disabled by default. When - tracing is enabled, ``dig`` makes iterative queries to resolve the + tracing is enabled, :program:`dig` makes iterative queries to resolve the name being looked up. It follows referrals from the root servers, showing the answer from each server that was used to resolve the lookup. @@ -698,7 +698,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to Multiple Queries ~~~~~~~~~~~~~~~~ -The BIND 9 implementation of ``dig`` supports specifying multiple +The BIND 9 implementation of :program:`dig` supports specifying multiple queries on the command line (in addition to supporting the :option:`-f` batch file option). Each of those queries can be supplied with its own set of flags, options, and query options. @@ -720,19 +720,19 @@ query options. For example: dig +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr -shows how ``dig`` can be used from the command line to make three +shows how :program:`dig` can be used from the command line to make three lookups: an ANY query for ``www.isc.org``, a reverse lookup of 127.0.0.1, and a query for the NS records of ``isc.org``. A global query option of -``+qr`` is applied, so that ``dig`` shows the initial query it made for +``+qr`` is applied, so that :program:`dig` shows the initial query it made for each lookup. The final query has a local query option of ``+noqr`` which -means that ``dig`` does not print the initial query when it looks up the +means that :program:`dig` does not print the initial query when it looks up the NS records for ``isc.org``. IDN Support ~~~~~~~~~~~ -If ``dig`` has been built with IDN (internationalized domain name) -support, it can accept and display non-ASCII domain names. ``dig`` +If :program:`dig` has been built with IDN (internationalized domain name) +support, it can accept and display non-ASCII domain names. :program:`dig` appropriately converts character encoding of a domain name before sending a request to a DNS server or displaying a reply from the server. To turn off IDN support, use the parameters @@ -742,7 +742,7 @@ variable. Return Codes ~~~~~~~~~~~~ -``dig`` return codes are: +:program:`dig` return codes are: ``0`` DNS response received, including NXDOMAIN status diff --git a/bin/dig/host.rst b/bin/dig/host.rst index 4299c874dc..fd0445887d 100644 --- a/bin/dig/host.rst +++ b/bin/dig/host.rst @@ -26,16 +26,16 @@ Synopsis Description ~~~~~~~~~~~ -``host`` is a simple utility for performing DNS lookups. It is normally +:program:`host` is a simple utility for performing DNS lookups. It is normally used to convert names to IP addresses and vice versa. When no arguments -or options are given, ``host`` prints a short summary of its +or options are given, :program:`host` prints a short summary of its command-line arguments and options. ``name`` is the domain name that is to be looked up. It can also be a dotted-decimal IPv4 address or a colon-delimited IPv6 address, in which -case ``host`` by default performs a reverse lookup for that address. +case :program:`host` by default performs a reverse lookup for that address. ``server`` is an optional argument which is either the name or IP -address of the name server that ``host`` should query instead of the +address of the name server that :program:`host` should query instead of the server or servers listed in ``/etc/resolv.conf``. Options @@ -66,7 +66,7 @@ Options .. option:: -C - This option indicates that ``named`` should check consistency, meaning that ``host`` queries the SOA records for zone + This option indicates that ``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 ``host`` command performs a zone transfer of zone + This option tells ``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. @@ -100,7 +100,7 @@ Options This option specifies a non-recursive query; setting this option clears the RD (recursion desired) bit in the query. This means that the name server receiving the query does not attempt to resolve ``name``. The :option:`-r` - option enables ``host`` to mimic the behavior of a name server by + option enables :program:`host` to mimic the behavior of a name server by making non-recursive queries, and expecting to receive answers to those queries that can be referrals to other name servers. @@ -121,11 +121,11 @@ Options This option specifies the query type. The ``type`` argument can be any recognized query type: CNAME, NS, SOA, TXT, DNSKEY, AXFR, etc. - When no query type is specified, ``host`` automatically selects an + When no query type is specified, :program:`host` automatically selects an appropriate query type. By default, it looks for A, AAAA, and MX records. If the :option:`-C` option is given, queries are made for SOA records. If ``name`` is a dotted-decimal IPv4 address or - colon-delimited IPv6 address, ``host`` queries for PTR records. + colon-delimited IPv6 address, :program:`host` queries for PTR records. If a query type of IXFR is chosen, the starting serial number can be specified by appending an equals sign (=), followed by the starting serial @@ -133,7 +133,7 @@ Options .. option:: -T, -U - This option specifies TCP or UDP. By default, ``host`` uses UDP when making queries; the + This option specifies TCP or UDP. By default, :program:`host` uses UDP when making queries; the :option:`-T` option makes it use a TCP connection when querying the name server. TCP is automatically selected for queries that require it, such as zone transfer (AXFR) requests. Type ``ANY`` queries default @@ -165,7 +165,7 @@ Options 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 less than 1, the wait interval is set to 1 second. - By default, ``host`` waits for 5 seconds for UDP responses and 10 + By default, :program:`host` waits for 5 seconds for UDP responses and 10 seconds for TCP connections. These defaults can be overridden by the ``timeout`` option in ``/etc/resolv.conf``. @@ -174,13 +174,13 @@ Options IDN Support ~~~~~~~~~~~ -If ``host`` has been built with IDN (internationalized domain name) -support, it can accept and display non-ASCII domain names. ``host`` +If :program:`host` has been built with IDN (internationalized domain name) +support, it can accept and display non-ASCII domain names. :program:`host` appropriately converts character encoding of a domain name before sending a request to a DNS server or displaying a reply from the server. To turn off IDN support, define the ``IDN_DISABLE`` environment variable. IDN support is disabled if the variable is set -when ``host`` runs. +when :program:`host` runs. Files ~~~~~ diff --git a/bin/dig/nslookup.rst b/bin/dig/nslookup.rst index 08350194ca..d885a24400 100644 --- a/bin/dig/nslookup.rst +++ b/bin/dig/nslookup.rst @@ -26,8 +26,8 @@ Synopsis Description ~~~~~~~~~~~ -``nslookup`` is a program to query Internet domain name servers. -``nslookup`` has two modes: interactive and non-interactive. Interactive +:program:`nslookup` is a program to query Internet domain name servers. +:program:`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 prints just the name and requested @@ -56,7 +56,7 @@ seconds, type: nslookup -query=hinfo -timeout=10 -The ``-version`` option causes ``nslookup`` to print the version number +The ``-version`` option causes :program:`nslookup` to print the version number and immediately exit. Interactive Commands @@ -183,19 +183,19 @@ Interactive Commands Return Values ~~~~~~~~~~~~~ -``nslookup`` returns with an exit status of 1 if any query failed, and 0 +:program:`nslookup` returns with an exit status of 1 if any query failed, and 0 otherwise. IDN Support ~~~~~~~~~~~ -If ``nslookup`` has been built with IDN (internationalized domain name) -support, it can accept and display non-ASCII domain names. ``nslookup`` +If :program:`nslookup` has been built with IDN (internationalized domain name) +support, it can accept and display non-ASCII domain names. :program:`nslookup` appropriately converts character encoding of a domain name before sending a request to a DNS server or displaying a reply from the server. To turn off IDN support, define the ``IDN_DISABLE`` environment variable. IDN support is disabled if the variable is set -when ``nslookup`` runs, or when the standard output is not a tty. +when :program:`nslookup` runs, or when the standard output is not a tty. Files ~~~~~ diff --git a/bin/dnssec/dnssec-cds.rst b/bin/dnssec/dnssec-cds.rst index 3eb5384449..d041db6bec 100644 --- a/bin/dnssec/dnssec-cds.rst +++ b/bin/dnssec/dnssec-cds.rst @@ -26,11 +26,11 @@ Synopsis Description ~~~~~~~~~~~ -The ``dnssec-cds`` command changes DS records at a delegation point +The :program:`dnssec-cds` command changes DS records at a delegation point based on CDS or CDNSKEY records published in the child zone. If both CDS and CDNSKEY records are present in the child zone, the CDS is preferred. This enables a child zone to inform its parent of upcoming changes to -its key-signing keys (KSKs); by polling periodically with ``dnssec-cds``, the +its key-signing keys (KSKs); by polling periodically with :program:`dnssec-cds`, the parent can keep the DS records up-to-date and enable automatic rolling of KSKs. @@ -40,19 +40,19 @@ DNSKEY records so that they can be authenticated. The :option:`-d path <-d>` opt 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 -output of a previous run of ``dnssec-cds``. +output of a previous run of :program:`dnssec-cds`. -The ``dnssec-cds`` command uses special DNSSEC validation logic +The :program:`dnssec-cds` command uses special DNSSEC validation logic specified by :rfc:`7344`. It requires that the CDS and/or CDNSKEY records be validly signed by a key represented in the existing DS records. This is typically the pre-existing KSK. For protection against replay attacks, the signatures on the child records must not be older than they were on a previous run of -``dnssec-cds``. Their age is obtained from the modification time of the +:program:`dnssec-cds`. Their age is obtained from the modification time of the ``dsset-`` file, or from the :option:`-s` option. -To protect against breaking the delegation, ``dnssec-cds`` ensures that +To protect against breaking the delegation, :program:`dnssec-cds` ensures that the DNSKEY RRset can be verified by every key algorithm in the new DS RRset, and that the same set of keys are covered by every DS digest type. @@ -65,7 +65,7 @@ specify that the child zone wants to be insecure. .. warning:: - Be careful not to delete the DS records when ``dnssec-cds`` fails! + Be careful not to delete the DS records when :program:`dnssec-cds` fails! Alternatively, :option`dnssec-cds -u` writes an ``nsupdate`` script to the standard output. The :option:`-u` and :option:`-i` options can be used together to @@ -79,7 +79,7 @@ Options When converting CDS records to DS records, this option specifies the acceptable digest algorithms. This option can be repeated, so that multiple digest types are allowed. If none of the CDS records - use an acceptable digest type, ``dnssec-cds`` will try to use CDNSKEY + use an acceptable digest type, :program:`dnssec-cds` will try to use CDNSKEY records instead; if there are no CDNSKEY records, it reports an error. When converting CDNSKEY records to DS records, this option specifies the @@ -103,7 +103,7 @@ Options .. option:: -d path This specifies the location of the parent DS records. The path can be the name of a file - containing the DS records; if it is a directory, ``dnssec-cds`` + containing the DS records; if it is a directory, :program:`dnssec-cds` looks for a ``dsset-`` file for the domain inside the directory. To protect against replay attacks, child records are rejected if they @@ -177,7 +177,7 @@ Options Exit Status ~~~~~~~~~~~ -The ``dnssec-cds`` command exits 0 on success, or non-zero if an error +The :program:`dnssec-cds` command exits 0 on success, or non-zero if an error occurred. If successful, the DS records may or may not need to be @@ -187,11 +187,11 @@ Examples ~~~~~~~~ Before running ``dnssec-signzone``, ensure that the delegations -are up-to-date by running ``dnssec-cds`` on every ``dsset-`` file. +are up-to-date by running :program:`dnssec-cds` on every ``dsset-`` file. -To fetch the child records required by ``dnssec-cds``, invoke +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 -``dnssec-cds`` performs all the necessary checking. +:program:`dnssec-cds` performs all the necessary checking. :: @@ -203,7 +203,7 @@ To fetch the child records required by ``dnssec-cds``, invoke done When the parent zone is automatically signed by ``named``, -``dnssec-cds`` can be used with ``nsupdate`` to maintain a delegation as follows. +:program:`dnssec-cds` can be used with ``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 3d5cae2ddc..9548b540d8 100644 --- a/bin/dnssec/dnssec-dsfromkey.rst +++ b/bin/dnssec/dnssec-dsfromkey.rst @@ -32,7 +32,7 @@ Synopsis Description ~~~~~~~~~~~ -The ``dnssec-dsfromkey`` command outputs DS (Delegation Signer) resource records +The :program:`dnssec-dsfromkey` command outputs DS (Delegation Signer) resource records (RRs), or CDS (Child DS) RRs with the :option:`-C` option. By default, only KSKs are converted (keys with flags = 257). The @@ -41,13 +41,13 @@ included. The input keys can be specified in a number of ways: -By default, ``dnssec-dsfromkey`` reads a key file named in the format +By default, :program:`dnssec-dsfromkey` reads a key file named in the format ``Knnnn.+aaa+iiiii.key``, as generated by ``dnssec-keygen``. -With the :option:`-f file <-f>` option, ``dnssec-dsfromkey`` reads keys from a zone +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, ``dnssec-dsfromkey`` reads a ``keyset-`` file, +With the :option:`-s` option, :program:`dnssec-dsfromkey` reads a ``keyset-`` file, as generated by ``dnssec-keygen`` :option:`-C`. Options @@ -88,7 +88,7 @@ Options .. option:: -f file - This option sets zone file mode, in which the final dnsname argument of ``dnssec-dsfromkey`` is the + This option sets zone file mode, in which the final dnsname argument of :program:`dnssec-dsfromkey` is the DNS domain name of a zone whose master file can be read from ``file``. If the zone name is the same as ``file``, then it may be omitted. @@ -109,7 +109,7 @@ Options .. option:: -s - This option enables keyset mode, in which the final dnsname argument from ``dnssec-dsfromkey`` is the DNS + This option enables keyset mode, in which the final dnsname argument from :program:`dnssec-dsfromkey` is the DNS domain name used to locate a ``keyset-`` file. .. option:: -T TTL diff --git a/bin/dnssec/dnssec-importkey.rst b/bin/dnssec/dnssec-importkey.rst index 5c939a9fe3..8dd0f09c3f 100644 --- a/bin/dnssec/dnssec-importkey.rst +++ b/bin/dnssec/dnssec-importkey.rst @@ -28,7 +28,7 @@ Synopsis Description ~~~~~~~~~~~ -``dnssec-importkey`` reads a public DNSKEY record and generates a pair +:program:`dnssec-importkey` reads a public DNSKEY record and generates a pair of .key/.private files. The DNSKEY record may be read from an existing .key file, in which case a corresponding .private file is generated, or it may be read from any other file or from the standard diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst index 87d3e37c94..da0eb4f835 100644 --- a/bin/dnssec/dnssec-keyfromlabel.rst +++ b/bin/dnssec/dnssec-keyfromlabel.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``dnssec-keyfromlabel`` generates a pair of key files that reference a +: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 @@ -95,7 +95,7 @@ Options .. option:: -C This option enables compatibility mode, which generates an old-style key, without any metadata. - By default, ``dnssec-keyfromlabel`` includes the key's creation + By default, :program:`dnssec-keyfromlabel` includes the key's creation date in the metadata stored with the private key; other dates may be set there as well, including publication date, activation date, etc. Keys that include this data may be incompatible with older versions of @@ -119,7 +119,7 @@ Options .. option:: -h This option prints a short summary of the options and arguments to - ``dnssec-keyfromlabel``. + :program:`dnssec-keyfromlabel`. .. option:: -K directory @@ -250,7 +250,7 @@ explicitly prevent a date from being set, use ``none`` or ``never``. Generated Key Files ~~~~~~~~~~~~~~~~~~~ -When ``dnssec-keyfromlabel`` completes successfully, it prints a string +When :program:`dnssec-keyfromlabel` completes successfully, it prints a string of the form ``Knnnn.+aaa+iiiii`` to the standard output. This is an identification string for the key files it has generated. @@ -260,7 +260,7 @@ identification string for the key files it has generated. - ``iiiii`` is the key identifier (or footprint). -``dnssec-keyfromlabel`` creates two files, with names based on the +:program:`dnssec-keyfromlabel` creates two files, with names based on the printed string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and ``Knnnn.+aaa+iiiii.private`` contains the private key. diff --git a/bin/dnssec/dnssec-keygen.rst b/bin/dnssec/dnssec-keygen.rst index 40c54e3fb0..d1a1299419 100644 --- a/bin/dnssec/dnssec-keygen.rst +++ b/bin/dnssec/dnssec-keygen.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``dnssec-keygen`` generates keys for DNSSEC (Secure DNS), as defined in +:program:`dnssec-keygen` generates keys for DNSSEC (Secure DNS), as defined in :rfc:`2535` and :rfc:`4034`. It can also generate keys for use with TSIG (Transaction Signatures) as defined in :rfc:`2845`, or TKEY (Transaction Key) as defined in :rfc:`2930`. @@ -80,7 +80,7 @@ Options .. option:: -C This option enables compatibility mode, which generates an old-style key, without any timing - metadata. By default, ``dnssec-keygen`` includes the key's + metadata. By default, :program:`dnssec-keygen` includes the key's creation date in the metadata stored with the private key; other dates may be set there as well, including publication date, activation date, etc. Keys that include this data may be incompatible with older @@ -125,7 +125,7 @@ Options .. option:: -h This option prints a short summary of the options and arguments to - ``dnssec-keygen``. + :program:`dnssec-keygen`. .. option:: -K directory @@ -134,12 +134,12 @@ Options .. option:: -k policy This option creates keys for a specific ``dnssec-policy``. If a policy uses multiple keys, - ``dnssec-keygen`` generates multiple keys. This also + :program:`dnssec-keygen` generates multiple keys. This also creates a ".state" file to keep track of the key state. This option creates keys according to the ``dnssec-policy`` configuration, hence it cannot be used at the same time as many of the other options that - ``dnssec-keygen`` provides. + :program:`dnssec-keygen` provides. .. option:: -L ttl @@ -174,7 +174,7 @@ Options .. option:: -q This option sets quiet mode, which suppresses unnecessary output, including progress - indication. Without this option, when ``dnssec-keygen`` is run + indication. Without this option, when :program:`dnssec-keygen` is run interactively to generate an RSA or DSA key pair, it prints a string of symbols to ``stderr`` indicating the progress of the key generation. A ``.`` indicates that a random number has been found which @@ -295,7 +295,7 @@ explicitly prevent a date from being set, use ``none`` or ``never``. Generated Keys ~~~~~~~~~~~~~~ -When ``dnssec-keygen`` completes successfully, it prints a string of the +When :program:`dnssec-keygen` completes successfully, it prints a string of the form ``Knnnn.+aaa+iiiii`` to the standard output. This is an identification string for the key it has generated. @@ -305,7 +305,7 @@ identification string for the key it has generated. - ``iiiii`` is the key identifier (or footprint). -``dnssec-keygen`` creates two files, with names based on the printed +:program:`dnssec-keygen` creates two files, with names based on the printed string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and ``Knnnn.+aaa+iiiii.private`` contains the private key. @@ -329,7 +329,7 @@ The command prints a string of the form: ``Kexample.com.+013+26160`` -In this example, ``dnssec-keygen`` creates the files +In this example, :program:`dnssec-keygen` creates the files ``Kexample.com.+013+26160.key`` and ``Kexample.com.+013+26160.private``. To generate a matching key-signing key, issue the command: diff --git a/bin/dnssec/dnssec-revoke.rst b/bin/dnssec/dnssec-revoke.rst index f8f4c99ca2..53aa8a9d0d 100644 --- a/bin/dnssec/dnssec-revoke.rst +++ b/bin/dnssec/dnssec-revoke.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``dnssec-revoke`` reads a DNSSEC key file, sets the REVOKED bit on the +:program:`dnssec-revoke` reads a DNSSEC key file, sets the REVOKED bit on the key as defined in :rfc:`5011`, and creates a new pair of key files containing the now-revoked key. @@ -63,7 +63,7 @@ Options .. option:: -f - This option indicates a forced overwrite and causes ``dnssec-revoke`` to write the new key pair, + This option indicates a forced overwrite and causes :program:`dnssec-revoke` to write the new key pair, even if a file already exists matching the algorithm and key ID of the revoked key. diff --git a/bin/dnssec/dnssec-settime.rst b/bin/dnssec/dnssec-settime.rst index 56b973ac3e..c1bd65681e 100644 --- a/bin/dnssec/dnssec-settime.rst +++ b/bin/dnssec/dnssec-settime.rst @@ -26,14 +26,14 @@ Synopsis Description ~~~~~~~~~~~ -``dnssec-settime`` reads a DNSSEC private key file and sets the key +: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 to be published, whether it should be used for signing a zone, etc. If none of these options is set on the command line, -``dnssec-settime`` simply prints the key timing metadata already stored +:program:`dnssec-settime` simply prints the key timing metadata already stored in the key. When key metadata fields are changed, both files of a key pair @@ -64,7 +64,7 @@ Options .. option:: -f This option forces an update of an old-format key with no metadata fields. Without - this option, ``dnssec-settime`` fails when attempting to update a + this option, :program:`dnssec-settime` fails when attempting to update a legacy key. With this option, the key is recreated in the new format, but with the original key data retained. The key's creation date is set to the present time. If no other values are @@ -230,7 +230,7 @@ Known key states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE. Printing Options ~~~~~~~~~~~~~~~~ -``dnssec-settime`` can also be used to print the timing metadata +:program:`dnssec-settime` can also be used to print the timing metadata associated with a key. .. option:: -u diff --git a/bin/dnssec/dnssec-signzone.rst b/bin/dnssec/dnssec-signzone.rst index 3ca6944f06..61d03e2041 100644 --- a/bin/dnssec/dnssec-signzone.rst +++ b/bin/dnssec/dnssec-signzone.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``dnssec-signzone`` signs a zone; it generates NSEC and RRSIG records +:program:`dnssec-signzone` signs a zone; it generates NSEC and RRSIG records and produces a signed version of the zone. The security status of delegations from the signed zone (that is, whether the child zones are secure) is determined by the presence or absence of a ``keyset`` @@ -47,7 +47,7 @@ Options This option sets compatibility mode, in which a ``keyset-zonename`` file is generated in addition to ``dsset-zonename`` when signing a zone, for use by older versions - of ``dnssec-signzone``. + of :program:`dnssec-signzone`. .. option:: -d directory @@ -56,7 +56,7 @@ Options .. option:: -D This option indicates that only those record types automatically managed by - ``dnssec-signzone``, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output. + :program:`dnssec-signzone`, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output. If smart signing (:option:`-S`) is used, DNSKEY records are also included. The resulting file can be included in the original zone file with ``$INCLUDE``. This option cannot be combined with :option:`-O raw <-O>` @@ -144,7 +144,7 @@ Options .. option:: -h This option prints a short summary of the options and arguments to - ``dnssec-signzone``. + :program:`dnssec-signzone`. .. option:: -V @@ -160,7 +160,7 @@ Options The default cycle interval is one quarter of the difference between the signature end and start times. So if neither ``end-time`` nor - ``start-time`` is specified, ``dnssec-signzone`` generates + ``start-time`` is specified, :program:`dnssec-signzone` generates signatures that are valid for 30 days, with a cycle interval of 7.5 days. Therefore, if any existing RRSIG records are due to expire in less than 7.5 days, they are replaced. @@ -258,14 +258,14 @@ Options one, signatures from the old key that are still within their validity period are retained. This allows the zone to continue to validate with cached copies of the old DNSKEY RRset. The :option:`-Q` option forces - ``dnssec-signzone`` to remove signatures from keys that are no longer + :program:`dnssec-signzone` to remove signatures from keys that are no longer active. This enables ZSK rollover using the procedure described in :rfc:`4641#4.2.1.1` ("Pre-Publish Key Rollover"). .. option:: -q This option enables quiet mode, which suppresses unnecessary output. Without this option, when - ``dnssec-signzone`` is run it prints three pieces of information to standard output: the number of + :program:`dnssec-signzone` is run it prints three pieces of information to standard output: the number of keys in use; the algorithms used to verify the zone was signed correctly and other status information; and the filename containing the signed zone. With the option that output is suppressed, leaving only the filename. @@ -275,14 +275,14 @@ Options This option removes signatures from keys that are no longer published. This option is similar to :option:`-Q`, except it forces - ``dnssec-signzone`` to remove signatures from keys that are no longer + :program:`dnssec-signzone` to remove signatures from keys that are no longer published. This enables ZSK rollover using the procedure described in :rfc:`4641#4.2.1.2` ("Double Signature Zone Signing Key Rollover"). .. option:: -S - This option enables smart signing, which instructs ``dnssec-signzone`` to search the key + This option enables smart signing, which instructs :program:`dnssec-signzone` to search the key repository for keys that match the zone being signed, and to include them in the zone if appropriate. @@ -336,7 +336,7 @@ Options This option updates the NSEC/NSEC3 chain when re-signing a previously signed zone. With this option, a zone signed with NSEC can be switched to NSEC3, or a zone signed with NSEC3 can be switched to NSEC or to NSEC3 with - different parameters. Without this option, ``dnssec-signzone`` + different parameters. Without this option, :program:`dnssec-signzone` retains the existing chain when re-signing. .. option:: -v level @@ -406,7 +406,7 @@ DS records can be imported from them (:option:`-g`). db.example.com.signed % -In the above example, ``dnssec-signzone`` creates the file +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. diff --git a/bin/dnssec/dnssec-verify.rst b/bin/dnssec/dnssec-verify.rst index 1b4c3316e1..cba858612d 100644 --- a/bin/dnssec/dnssec-verify.rst +++ b/bin/dnssec/dnssec-verify.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``dnssec-verify`` verifies that a zone is fully signed for each +:program:`dnssec-verify` verifies that a zone is fully signed for each algorithm found in the DNSKEY RRset for the zone, and that the NSEC/NSEC3 chains are complete. @@ -68,7 +68,7 @@ Options .. option:: -q - This option sets quiet mode, which suppresses output. Without this option, when ``dnssec-verify`` + This option sets quiet mode, which suppresses output. Without this option, when :program:`dnssec-verify` is run it prints to standard output the number of keys in use, the algorithms used to verify the zone was signed correctly, and other status information. With this option, all non-error output is suppressed, and only the exit diff --git a/bin/named/named.rst b/bin/named/named.rst index 8e7b334a6f..d9befaf0e4 100644 --- a/bin/named/named.rst +++ b/bin/named/named.rst @@ -26,11 +26,11 @@ Synopsis Description ~~~~~~~~~~~ -``named`` is a Domain Name System (DNS) server, part of the BIND 9 +:program:`named` is a Domain Name System (DNS) server, part of the BIND 9 distribution from ISC. For more information on the DNS, see :rfc:`1033`, :rfc:`1034`, and :rfc:`1035`. -When invoked without arguments, ``named`` reads the default +When invoked without arguments, :program:`named` reads the default configuration file |named_conf|, reads any initial data, and listens for queries. @@ -39,17 +39,17 @@ Options .. option:: -4 - This option tells ``named`` to use only IPv4, even if the host machine is capable of IPv6. :option:`-4` and + This option tells :program:`named` to use only IPv4, even if the host machine is capable of IPv6. :option:`-4` and :option:`-6` are mutually exclusive. .. option:: -6 - This option tells ``named`` to use only IPv6, even if the host machine is capable of IPv4. :option:`-4` and + This option tells :program:`named` to use only IPv6, even if the host machine is capable of IPv4. :option:`-4` and :option:`-6` are mutually exclusive. .. option:: -c config-file - This option tells ``named`` to use ``config-file`` as its configuration file instead of the default, + This option tells :program:`named` to use ``config-file`` as its configuration file instead of the default, |named_conf|. To ensure that the configuration file can be reloaded after the server has changed its working directory due to to a possible ``directory`` option in the configuration file, @@ -58,11 +58,11 @@ Options .. option:: -d debug-level This option sets the daemon's debug level to ``debug-level``. Debugging traces from - ``named`` become more verbose as the debug level increases. + :program:`named` become more verbose as the debug level increases. .. option:: -D string - This option specifies a string that is used to identify a instance of ``named`` + This option specifies a string that is used to identify a instance of :program:`named` in a process listing. The contents of ``string`` are not examined. .. option:: -E engine-name @@ -93,7 +93,7 @@ Options system-provided memory allocation functions. If set to ``fill``, blocks of memory are filled with tag values when allocated or freed, to assist debugging of memory problems. ``nofill`` disables this behavior, - and is the default unless ``named`` has been compiled with developer + and is the default unless :program:`named` has been compiled with developer options. .. option:: -m flag @@ -105,7 +105,7 @@ Options .. option:: -n #cpus This option creates ``#cpus`` worker threads to take advantage of multiple CPUs. If - not specified, ``named`` tries to determine the number of CPUs + not specified, :program:`named` tries to determine the number of CPUs present and creates one thread per CPU. If it is unable to determine the number of CPUs, a single worker thread is created. @@ -144,12 +144,12 @@ Options exhaustion of file descriptors and the operational environment is known to support the specified number of sockets. Note also that the actual maximum number is normally slightly fewer than the - specified value, because ``named`` reserves some file descriptors + specified value, because :program:`named` reserves some file descriptors for its internal use. .. option:: -t directory - This option tells ``named`` to chroot to ``directory`` after processing the command-line arguments, but + This option tells :program:`named` to chroot to ``directory`` after processing the command-line arguments, but before reading the configuration file. .. warning:: @@ -161,8 +161,8 @@ Options .. option:: -U #listeners - This option tells ``named`` the number of ``#listeners`` worker threads to listen on, for incoming UDP packets on - each address. If not specified, ``named`` calculates a default + This option tells :program:`named` the number of ``#listeners`` worker threads to listen on, for incoming UDP packets on + each address. If not specified, :program:`named` calculates a default value based on the number of detected CPUs: 1 for 1 CPU, and the number of detected CPUs minus one for machines with more than 1 CPU. This cannot be increased to a value higher than the number of CPUs. @@ -177,10 +177,10 @@ Options .. note:: - On Linux, ``named`` uses the kernel's capability mechanism to drop + On Linux, :program:`named` uses the kernel's capability mechanism to drop all root privileges except the ability to ``bind`` to a privileged port and set process resource limits. Unfortunately, - this means that the :option:`-u` option only works when ``named`` is run + this means that the :option:`-u` option only works when :program:`named` is run on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or later, since previous kernels did not allow privileges to be retained after ``setuid``. @@ -196,7 +196,7 @@ Options .. option:: -X lock-file This option acquires a lock on the specified file at runtime; this helps to - prevent duplicate ``named`` instances from running simultaneously. + 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. @@ -217,14 +217,14 @@ The result of sending any other signals to the server is undefined. Configuration ~~~~~~~~~~~~~ -The ``named`` configuration file is too complex to describe in detail +The :program:`named` configuration file is too complex to describe in detail here. A complete description is provided in the BIND 9 Administrator Reference Manual. -``named`` inherits the ``umask`` (file creation mode mask) from the -parent process. If files created by ``named``, such as journal files, +:program:`named` inherits the ``umask`` (file creation mode mask) from the +parent process. If files created by :program:`named`, such as journal files, need to have custom permissions, the ``umask`` should be set explicitly -in the script used to start the ``named`` process. +in the script used to start the :program:`named` process. Files ~~~~~ diff --git a/bin/nsupdate/nsupdate.rst b/bin/nsupdate/nsupdate.rst index dbefcd7521..1ea4595bf0 100644 --- a/bin/nsupdate/nsupdate.rst +++ b/bin/nsupdate/nsupdate.rst @@ -24,18 +24,18 @@ Synopsis Description ~~~~~~~~~~~ -``nsupdate`` is used to submit Dynamic DNS Update requests, as defined in +:program:`nsupdate` is used to submit Dynamic DNS Update requests, as defined in :rfc:`2136`, to a name server. This allows resource records to be added or removed from a zone without manually editing the zone file. A single update request can contain requests to add or remove more than one resource record. -Zones that are under dynamic control via ``nsupdate`` or a DHCP server +Zones that are under dynamic control via :program:`nsupdate` or a DHCP server should not be edited by hand. Manual edits could conflict with dynamic updates and cause data to be lost. The resource records that are dynamically added or removed with -``nsupdate`` must be in the same zone. Requests are sent to the +:program:`nsupdate` must be in the same zone. Requests are sent to the zone's primary server, which is identified by the MNAME field of the zone's SOA record. @@ -44,13 +44,13 @@ updates. These use the TSIG resource record type described in :rfc:`2845`, the SIG(0) record described in :rfc:`2535` and :rfc:`2931`, or GSS-TSIG as described in :rfc:`3645`. -TSIG relies on a shared secret that should only be known to ``nsupdate`` +TSIG relies on a shared secret that should only be known to :program:`nsupdate` 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 -configuration fragments. ``nsupdate`` uses the :option:`-y` or :option:`-k` options +configuration fragments. :program:`nsupdate` uses the :option:`-y` or :option:`-k` options to provide the TSIG shared secret; these options are mutually exclusive. SIG(0) uses public key cryptography. To use a SIG(0) key, the public key @@ -131,7 +131,7 @@ Options .. option:: -P This option prints the list of private BIND-specific resource record types whose - format is understood by ``nsupdate``. See also the :option:`-T` option. + format is understood by :program:`nsupdate`. See also the :option:`-T` option. .. option:: -r udpretries @@ -146,7 +146,7 @@ Options .. option:: -T This option prints the list of IANA standard resource record types whose format is - understood by ``nsupdate``. ``nsupdate`` exits after the lists + understood by :program:`nsupdate`. :program:`nsupdate` exits after the lists are printed. The :option:`-T` option can be combined with the :option:`-P` option. @@ -163,7 +163,7 @@ Options .. option:: -v - This option specifies that TCP should be used even for small update requests. By default, ``nsupdate`` uses + This option specifies that TCP should be used even for small update requests. By default, :program:`nsupdate` uses UDP to send update requests to the name server unless they are too large to fit in a UDP request, in which case TCP is used. TCP may be preferable when a batch of update requests is made. @@ -189,7 +189,7 @@ Options Input Format ~~~~~~~~~~~~ -``nsupdate`` reads input from ``filename`` or standard input. Each +:program:`nsupdate` reads input from ``filename`` or standard input. Each command is supplied on exactly one line of input. Some commands are for administrative purposes; others are either update instructions or prerequisite checks on the contents of the zone. These checks set @@ -209,7 +209,7 @@ The command formats and their meanings are as follows: ``server servername port`` This command sends all dynamic update requests to the name server ``servername``. - When no server statement is provided, ``nsupdate`` sends updates + When no server statement is provided, :program:`nsupdate` sends updates to the primary server of the correct zone. The MNAME field of that zone's SOA record identify the primary server for that zone. ``port`` is the port number on ``servername`` where the dynamic @@ -218,14 +218,14 @@ The command formats and their meanings are as follows: ``local address port`` This command sends all dynamic update requests using the local ``address``. When - no local statement is provided, ``nsupdate`` sends updates using + no local statement is provided, :program:`nsupdate` sends updates using an address and port chosen by the system. ``port`` can also be used to force requests to come from a specific port. If no port number is specified, the system assigns one. ``zone zonename`` This command specifies that all updates are to be made to the zone ``zonename``. - If no ``zone`` statement is provided, ``nsupdate`` attempts to + If no ``zone`` statement is provided, :program:`nsupdate` attempts to determine the correct zone to update based on the rest of the input. ``class classname`` @@ -323,7 +323,7 @@ Lines beginning with a semicolon (;) are comments and are ignored. Examples ~~~~~~~~ -The examples below show how ``nsupdate`` can be used to insert and +The examples below show how :program:`nsupdate` can be used to insert and delete resource records from the ``example.com`` zone. Notice that the input in each example contains a trailing blank line, so that a group of commands is sent as one dynamic update request to the primary name @@ -381,5 +381,5 @@ Bugs ~~~~ The TSIG key is redundantly stored in two separate files. This is a -consequence of ``nsupdate`` using the DST library for its cryptographic +consequence of :program:`nsupdate` using the DST library for its cryptographic operations, and may change in future releases. diff --git a/bin/rndc/rndc.conf.rst b/bin/rndc/rndc.conf.rst index 26ef20c12a..1555bb62b5 100644 --- a/bin/rndc/rndc.conf.rst +++ b/bin/rndc/rndc.conf.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``rndc.conf`` is the configuration file for ``rndc``, the BIND 9 name +:program:`rndc.conf` is the configuration file for ``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 semi-colon. Clauses in the statements are also semi-colon terminated. @@ -38,7 +38,7 @@ C++ style: // to end of line Unix style: # to end of line -``rndc.conf`` is much simpler than ``named.conf``. The file uses three +:program:`rndc.conf` is much simpler than ``named.conf``. The file uses three statements: an options statement, a server statement, and a key statement. @@ -135,7 +135,7 @@ To generate a random secret with ``rndc-confgen``: ``rndc-confgen`` -A complete ``rndc.conf`` file, including the randomly generated key, +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. @@ -147,7 +147,7 @@ Name Server Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~ The name server must be configured to accept rndc connections and to -recognize the key specified in the ``rndc.conf`` file, using the +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 the BIND 9 Administrator Reference Manual for details. diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst index 21c80eb316..247ddc3a1b 100644 --- a/bin/rndc/rndc.rst +++ b/bin/rndc/rndc.rst @@ -26,15 +26,15 @@ Synopsis Description ~~~~~~~~~~~ -``rndc`` controls the operation of a name server; it supersedes the -``ndc`` utility. If ``rndc`` is +:program:`rndc` controls the operation of a name server; it supersedes the +``ndc`` utility. If :program:`rndc` is invoked with no command line options or arguments, it prints a short summary of the supported commands and the available options and their arguments. -``rndc`` communicates with the name server over a TCP connection, +:program:`rndc` communicates with the name server over a TCP connection, sending commands authenticated with digital signatures. In the current -versions of ``rndc`` and ``named``, the only supported authentication +versions of :program:`rndc` and ``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 @@ -42,7 +42,7 @@ authentication for the command request and the name server's response. All commands sent over the channel must be signed by a key_id known to the server. -``rndc`` reads a configuration file to determine how to contact the name +:program:`rndc` reads a configuration file to determine how to contact the name server and decide what algorithm and key it should use. Options @@ -77,9 +77,9 @@ Options .. option:: -s server ``server`` is the name or address of the server which matches a server - statement in the configuration file for ``rndc``. If no server is + statement in the configuration file for :program:`rndc`. If no server is supplied on the command line, the host named by the default-server - clause in the options statement of the ``rndc`` configuration file + clause in the options statement of the :program:`rndc` configuration file is used. .. option:: -p port @@ -94,7 +94,7 @@ Options .. option:: -r - This option instructs ``rndc`` to print the result code returned by ``named`` + This option instructs :program:`rndc` to print the result code returned by ``named`` after executing the requested command (e.g., ISC_R_SUCCESS, ISC_R_FAILURE, etc.). @@ -106,7 +106,7 @@ Options 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, - ``rndc`` first looks for a key clause in the server statement of + :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 the configuration file contains shared secrets which are used to send @@ -116,7 +116,7 @@ Options Commands ~~~~~~~~ -A list of commands supported by ``rndc`` can be seen by running ``rndc`` +A list of commands supported by :program:`rndc` can be seen by running :program:`rndc` without arguments. Currently supported commands are: @@ -449,7 +449,7 @@ Currently supported commands are: yet been updated by a successful key refresh query). If the first argument is ``-``, then the output is returned via the - ``rndc`` response channel and printed to the standard output. + :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``. @@ -628,7 +628,7 @@ Currently supported commands are: See also :option:`rndc showzone`. -``rndc`` commands that specify zone names, such as :option:`reload` +:program:`rndc` commands that specify zone names, such as :option:`reload` :option:`retransfer`, or :option:`zonestatus`, can be ambiguous when applied to zones of type ``redirect``. Redirect zones are always called ``.``, and can be confused with zones of type ``hint`` or with secondary copies of the root diff --git a/bin/tools/arpaname.rst b/bin/tools/arpaname.rst index 5ccd4e3264..00ed8977f7 100644 --- a/bin/tools/arpaname.rst +++ b/bin/tools/arpaname.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``arpaname`` translates IP addresses (IPv4 and IPv6) to the +:program:`arpaname` translates IP addresses (IPv4 and IPv6) to the corresponding IN-ADDR.ARPA or IP6.ARPA names. See Also diff --git a/bin/tools/dnstap-read.rst b/bin/tools/dnstap-read.rst index db34606add..49dceab433 100644 --- a/bin/tools/dnstap-read.rst +++ b/bin/tools/dnstap-read.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``dnstap-read`` reads ``dnstap`` data from a specified file and prints +:program:`dnstap-read` reads ``dnstap`` data from a specified file and prints it in a human-readable format. By default, ``dnstap`` data is printed in a short summary format, but if the :option:`-y` option is specified, a longer and more detailed YAML format is used. diff --git a/bin/tools/mdig.rst b/bin/tools/mdig.rst index b56e318b62..fcd0f4d9b6 100644 --- a/bin/tools/mdig.rst +++ b/bin/tools/mdig.rst @@ -30,12 +30,12 @@ Synopsis Description ~~~~~~~~~~~ -``mdig`` is a multiple/pipelined query version of ``dig``: instead of +:program:`mdig` is a multiple/pipelined query version of ``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. -``mdig`` options are a subset of the ``dig`` options, and are divided +:program:`mdig` options are a subset of the ``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. @@ -45,9 +45,9 @@ address of the name server to query. (Unlike ``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, -``mdig`` resolves that name before querying the name server. +:program:`mdig` resolves that name before querying the name server. -``mdig`` provides a number of query options which affect the way in +:program:`mdig` provides a number of query options which affect the way in which lookups are made and the results displayed. Some of these set or reset flag bits in the query header, some determine which sections of the answer get printed, and others determine the timeout and retry @@ -64,31 +64,31 @@ Anywhere Options .. option:: -f - This option makes ``mdig`` operate in batch mode by reading a list + This option makes :program:`mdig` operate in batch mode by reading a list of lookup requests to process from the file ``filename``. The file contains a number of queries, one per line. Each entry in the file should be organized in the same way they would be presented as queries - to ``mdig`` using the command-line interface. + to :program:`mdig` using the command-line interface. .. option:: -h - This option causes ``mdig`` to print detailed help information, with the full list + This option causes :program:`mdig` to print detailed help information, with the full list of options, and exit. .. option:: -v - This option causes ``mdig`` to print the version number and exit. + This option causes :program:`mdig` to print the version number and exit. Global Options ~~~~~~~~~~~~~~ .. option:: -4 - This option forces ``mdig`` to only use IPv4 query transport. + This option forces :program:`mdig` to only use IPv4 query transport. .. option:: -6 - This option forces ``mdig`` to only use IPv6 query transport. + This option forces :program:`mdig` to only use IPv6 query transport. .. option:: -b address @@ -104,7 +104,7 @@ Global Options .. option:: -p port# This option is used when a non-standard port number is to be - queried. ``port#`` is the port number that ``mdig`` sends its + queried. ``port#`` is the port number that :program:`mdig` sends its queries to, instead of the standard DNS port number 53. This option is used to test a name server that has been configured to listen for queries on a non-standard port number. @@ -171,7 +171,7 @@ The global query options are: This option toggles printing of records, like the SOA records, in a verbose multi-line format with human-readable comments. The default is to print each record on - a single line, to facilitate machine parsing of the ``mdig`` output. + a single line, to facilitate machine parsing of the :program:`mdig` output. .. option:: +[no]question @@ -239,7 +239,7 @@ Local Options Reverse lookups - mapping addresses to names - are simplified by this option. ``addr`` is an IPv4 address in dotted-decimal - notation, or a colon-delimited IPv6 address. ``mdig`` automatically + notation, or a colon-delimited IPv6 address. :program:`mdig` automatically performs a lookup for a query name like ``11.12.13.10.in-addr.arpa`` and sets the query type and class to PTR and IN respectively. By default, IPv6 addresses are looked up using nibble format under the IP6.ARPA @@ -319,7 +319,7 @@ The local query options are: .. option:: +[no]recurse This toggles the setting of the RD (recursion desired) bit in the query. - This bit is set by default, which means ``mdig`` normally sends + This bit is set by default, which means :program:`mdig` normally sends recursive queries. .. option:: +retry=T diff --git a/bin/tools/named-journalprint.rst b/bin/tools/named-journalprint.rst index 2d9caab89f..c7c33e1b8f 100644 --- a/bin/tools/named-journalprint.rst +++ b/bin/tools/named-journalprint.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``named-journalprint`` scans the contents of a zone journal file, +:program:`named-journalprint` scans the contents of a zone journal file, printing it in a human-readable form, or, optionally, converting it to a different journal file format. @@ -38,7 +38,7 @@ shutdown or crash. By default, the name of the journal file is formed by appending the extension ``.jnl`` to the name of the corresponding zone file. -``named-journalprint`` converts the contents of a given journal file +:program:`named-journalprint` converts the contents of a given journal file into a human-readable text format. Each line begins with ``add`` or ``del``, to indicate whether the record was added or deleted, and continues with the resource record in master-file format. diff --git a/bin/tools/named-nzd2nzf.rst b/bin/tools/named-nzd2nzf.rst index be2c5ee2ea..2e0bede966 100644 --- a/bin/tools/named-nzd2nzf.rst +++ b/bin/tools/named-nzd2nzf.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``named-nzd2nzf`` converts an NZD database to NZF format and prints it +: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 used to restore the old file format when rolling back from a newer diff --git a/bin/tools/named-rrchecker.rst b/bin/tools/named-rrchecker.rst index 4ff3b27fa9..6b736c249c 100644 --- a/bin/tools/named-rrchecker.rst +++ b/bin/tools/named-rrchecker.rst @@ -26,7 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -``named-rrchecker`` reads a individual DNS resource record from standard +:program:`named-rrchecker` reads a individual DNS resource record from standard input and checks whether it is syntactically correct. Options diff --git a/bin/tools/nsec3hash.rst b/bin/tools/nsec3hash.rst index 2429e317d0..43a8d64ced 100644 --- a/bin/tools/nsec3hash.rst +++ b/bin/tools/nsec3hash.rst @@ -28,7 +28,7 @@ Synopsis Description ~~~~~~~~~~~ -``nsec3hash`` generates an NSEC3 hash based on a set of NSEC3 +:program:`nsec3hash` generates an NSEC3 hash based on a set of NSEC3 parameters. This can be used to check the validity of NSEC3 records in a signed zone. From 53a5776025862492c8067a0918c5ec38970f546c 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 08/11] 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. --- 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-9.17.0.rst | 2 +- doc/notes/notes-9.17.1.rst | 2 +- doc/notes/notes-9.17.10.rst | 24 +- doc/notes/notes-9.17.11.rst | 20 +- doc/notes/notes-9.17.12.rst | 16 +- doc/notes/notes-9.17.13.rst | 10 +- doc/notes/notes-9.17.15.rst | 2 +- doc/notes/notes-9.17.16.rst | 6 +- doc/notes/notes-9.17.17.rst | 12 +- doc/notes/notes-9.17.18.rst | 14 +- doc/notes/notes-9.17.19.rst | 16 +- doc/notes/notes-9.17.2.rst | 22 +- doc/notes/notes-9.17.20.rst | 4 +- doc/notes/notes-9.17.21.rst | 6 +- doc/notes/notes-9.17.22.rst | 10 +- doc/notes/notes-9.17.3.rst | 12 +- doc/notes/notes-9.17.4.rst | 12 +- doc/notes/notes-9.17.5.rst | 14 +- doc/notes/notes-9.17.6.rst | 12 +- doc/notes/notes-9.17.7.rst | 16 +- doc/notes/notes-9.17.8.rst | 10 +- doc/notes/notes-9.17.9.rst | 10 +- doc/notes/notes-current.rst | 10 +- 75 files changed, 720 insertions(+), 720 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 4cb543ded8..aeda5c9490 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 a243511907..a52056ca0b 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 02888ec3e4..8179d3a368 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. @@ -2465,7 +2465,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. @@ -2487,7 +2487,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 @@ -2531,16 +2531,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 @@ -2625,9 +2625,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: :: @@ -2647,15 +2647,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 @@ -2875,11 +2875,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 @@ -2982,13 +2982,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 @@ -3094,7 +3094,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: @@ -3126,7 +3126,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`` @@ -3344,7 +3344,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`` @@ -3475,10 +3475,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. @@ -3526,10 +3526,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 @@ -3564,7 +3564,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 @@ -3572,7 +3572,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 @@ -3586,7 +3586,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. @@ -3608,15 +3608,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 @@ -3667,7 +3667,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 @@ -3681,7 +3681,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`` @@ -3756,7 +3756,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``. @@ -3765,7 +3765,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 @@ -4089,7 +4089,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 @@ -4110,7 +4110,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 @@ -4249,7 +4249,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 @@ -4266,7 +4266,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 @@ -4519,12 +4519,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. @@ -4559,7 +4559,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 @@ -4608,13 +4608,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 @@ -4632,10 +4632,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. @@ -4700,7 +4700,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. @@ -4740,11 +4740,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 @@ -4787,11 +4787,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: @@ -4874,7 +4874,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. @@ -4891,9 +4891,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: @@ -4961,7 +4961,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. @@ -5007,9 +5007,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. @@ -5019,7 +5019,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 @@ -5028,9 +5028,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``. @@ -5038,14 +5038,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. @@ -5063,19 +5063,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: @@ -5108,7 +5108,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. @@ -5134,7 +5134,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. @@ -5205,7 +5205,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 @@ -5264,7 +5264,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`` @@ -5520,7 +5520,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 @@ -5536,7 +5536,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: :: @@ -5555,7 +5555,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 @@ -5596,7 +5596,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 @@ -5902,7 +5902,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 @@ -6023,10 +6023,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, @@ -6043,7 +6043,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 @@ -6207,7 +6207,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.) @@ -6568,7 +6568,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. @@ -6693,14 +6693,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 4a8290ade7..539346834e 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-9.17.0.rst b/doc/notes/notes-9.17.0.rst index 2949f2bc82..c33d22caa2 100644 --- a/doc/notes/notes-9.17.0.rst +++ b/doc/notes/notes-9.17.0.rst @@ -30,7 +30,7 @@ New Features - When a secondary server receives a large incremental zone transfer (IXFR), it can have a negative impact on query performance while the incremental changes are applied to the zone. To address this, - ``named`` can now limit the size of IXFR responses it sends in + :iscman:`named` can now limit the size of IXFR responses it sends in response to zone transfer requests. If an IXFR response would be larger than an AXFR of the entire zone, it will send an AXFR response instead. diff --git a/doc/notes/notes-9.17.1.rst b/doc/notes/notes-9.17.1.rst index db21d737de..7a7aa9cb10 100644 --- a/doc/notes/notes-9.17.1.rst +++ b/doc/notes/notes-9.17.1.rst @@ -54,7 +54,7 @@ Bug Fixes ~~~~~~~~~ - When an RPZ policy zone was updated via zone transfer and a large - number of records was deleted, ``named`` could become nonresponsive + number of records was deleted, :iscman:`named` could become nonresponsive for a short period while deleted names were removed from the RPZ summary database. This database cleanup is now done incrementally over a longer period of time, reducing such delays. :gl:`#1447` diff --git a/doc/notes/notes-9.17.10.rst b/doc/notes/notes-9.17.10.rst index 84695e5be5..6ffa6ee321 100644 --- a/doc/notes/notes-9.17.10.rst +++ b/doc/notes/notes-9.17.10.rst @@ -15,26 +15,26 @@ Notes for BIND 9.17.10 New Features ~~~~~~~~~~~~ -- Support for DNS-over-HTTPS (DoH) was added to ``named``. Because of +- Support for DNS-over-HTTPS (DoH) was added to :iscman:`named`. Because of this, the ``nghttp2`` HTTP/2 library is now required for building the development branch of BIND 9. Both TLS-encrypted and unencrypted HTTP/2 connections are supported (the latter may be used to offload encryption to other software). Note that there is no client-side support for HTTPS as yet; this will - be added to ``dig`` in a future release. :gl:`#1144` + be added to :iscman:`dig` in a future release. :gl:`#1144` -- ``named`` now supports XFR-over-TLS (XoT) for incoming as well as +- :iscman:`named` now supports XFR-over-TLS (XoT) for incoming as well as outgoing zone transfers. Addresses in a ``primaries`` list can now be accompanied by an optional ``tls`` keyword, followed by either the name of a previously configured ``tls`` statement or ``ephemeral``. :gl:`#2392` - A new option, ``stale-answer-client-timeout``, has been added to - improve ``named``'s behavior with respect to serving stale data. The - option defines the amount of time ``named`` waits before attempting to + improve :iscman:`named`'s behavior with respect to serving stale data. The + option defines the amount of time :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, attempting to refresh + found, :iscman:`named` continues the ongoing fetches, attempting to refresh the RRset in cache until the ``resolver-query-timeout`` interval is reached. @@ -57,7 +57,7 @@ Removed Features failure: ``acache-cleaning-interval``, ``acache-enable``, ``additional-from-auth``, ``additional-from-cache``, ``allow-v6-synthesis``, ``cleaning-interval``, ``dnssec-enable``, - ``dnssec-lookaside``, ``filter-aaaa``, ``filter-aaaa-on-v4``, + ``dnssec-lookaside``, :iscman:`filter-aaaa`, ``filter-aaaa-on-v4``, ``filter-aaaa-on-v6``, ``geoip-use-ecs``, ``lwres``, ``max-acache-size``, ``nosit-udp-size``, ``queryport-pool-ports``, ``queryport-pool-updateinterval``, ``request-sit``, ``sit-secret``, @@ -66,11 +66,11 @@ Removed Features Feature Changes ~~~~~~~~~~~~~~~ -- When serve-stale is enabled and stale data is available, ``named`` now +- When serve-stale is enabled and stale data is available, :iscman:`named` now returns stale answers upon encountering any unexpected error in the query resolution process. This may happen, for example, if the ``fetches-per-server`` or ``fetches-per-zone`` limits are reached. In - this case, ``named`` attempts to answer DNS requests with stale data, + this case, :iscman:`named` attempts to answer DNS requests with stale data, but does not start the ``stale-refresh-time`` window. :gl:`#2434` - The default value of ``max-stale-ttl`` has been changed from 12 hours @@ -93,10 +93,10 @@ Feature Changes Bug Fixes ~~~~~~~~~ -- ``named`` failed to start when its configuration included a zone with +- :iscman:`named` failed to start when its configuration included a zone with a non-builtin ``allow-update`` ACL attached. :gl:`#2413` -- Previously, ``dnssec-keyfromlabel`` crashed when operating on an ECDSA +- Previously, :iscman:`dnssec-keyfromlabel` crashed when operating on an ECDSA key. This has been fixed. :gl:`#2178` - KASP incorrectly set signature validity to the value of the DNSKEY @@ -115,5 +115,5 @@ Bug Fixes (Equation (2)). :gl:`#2375` - Performance of the DNSSEC verification code (used by - ``dnssec-signzone``, ``dnssec-verify``, and mirror zones) has been + :iscman:`dnssec-signzone`, :iscman:`dnssec-verify`, and mirror zones) has been improved. :gl:`#2073` diff --git a/doc/notes/notes-9.17.11.rst b/doc/notes/notes-9.17.11.rst index b0c4311d6f..502f893e70 100644 --- a/doc/notes/notes-9.17.11.rst +++ b/doc/notes/notes-9.17.11.rst @@ -15,7 +15,7 @@ Notes for BIND 9.17.11 New Features ~~~~~~~~~~~~ -- ``dig`` has been extended to support DNS-over-HTTPS (DoH) queries, +- :iscman:`dig` has been extended to support DNS-over-HTTPS (DoH) queries, using ``dig +https`` and related options. :gl:`#1641` - A new ``purge-keys`` option has been added to ``dnssec-policy``. It @@ -35,33 +35,33 @@ Feature Changes - ``http default`` can now be specified in ``listen-on`` and ``listen-on-v6`` statements to use the default HTTP endpoint of ``/dns-query``. It is no longer necessary to include an ``http`` - statement in ``named.conf`` unless overriding this value. :gl:`#2472` + statement in :iscman:`named.conf` unless overriding this value. :gl:`#2472` Bug Fixes ~~~~~~~~~ -- Zone journal (``.jnl``) files created by versions of ``named`` prior +- Zone journal (``.jnl``) files created by versions of :iscman:`named` prior to 9.16.12 were no longer compatible; this could cause problems when upgrading if journal files were not synchronized first. This has been corrected: older journal files can now be read when starting up. When an old-style journal file is detected, it is updated to the new format immediately after loading. - Note that journals created by the current version of ``named`` are not + Note that journals created by the current version of :iscman:`named` are not usable by versions prior to 9.16.12. Before downgrading to a prior release, users are advised to ensure that all dynamic zones have been synchronized using :option:`rndc sync -clean `. A journal file's format can be changed manually by running ``named-journalprint -d`` (downgrade) or ``named-journalprint -u`` - (upgrade). Note that this *must not* be done while ``named`` is + (upgrade). Note that this *must not* be done while :iscman:`named` is running. :gl:`#2505` -- ``named`` crashed when it was allowed to serve stale answers and +- :iscman:`named` crashed when it was allowed to serve stale answers and ``stale-answer-client-timeout`` was triggered without any (stale) data available in the cache to answer the query. :gl:`#2503` -- If an outgoing packet exceeded ``max-udp-size``, ``named`` dropped it +- If an outgoing packet exceeded ``max-udp-size``, :iscman:`named` dropped it instead of sending back a proper response. To prevent this problem, the ``IP_DONTFRAG`` option is no longer set on UDP sockets, which has been happening since BIND 9.17.6. :gl:`#2466` @@ -70,7 +70,7 @@ Bug Fixes using ``dnssec-policy`` with ``nsec3param``. This has been fixed. :gl:`#2498` -- A memory leak occurred when ``named`` was reconfigured after adding an +- A memory leak occurred when :iscman:`named` was reconfigured after adding an inline-signed zone with ``auto-dnssec maintain`` enabled. This has been fixed. :gl:`#2041` @@ -79,9 +79,9 @@ Bug Fixes such a record was loaded. :gl:`#2499` - If an invalid key name (e.g. ``a..b``) was specified in a - ``primaries`` list in ``named.conf``, the wrong size was passed to + ``primaries`` list in :iscman:`named.conf`, the wrong size was passed to ``isc_mem_put()``, which resulted in the returned memory being put on - the wrong free list and prevented ``named`` from starting up. This has + the wrong free list and prevented :iscman:`named` from starting up. This has been fixed. :gl:`#2460` - ``libtool`` was inadvertently introduced as a build-time requirement diff --git a/doc/notes/notes-9.17.12.rst b/doc/notes/notes-9.17.12.rst index 56985b9205..fbbf0e63ff 100644 --- a/doc/notes/notes-9.17.12.rst +++ b/doc/notes/notes-9.17.12.rst @@ -16,12 +16,12 @@ Security Fixes ~~~~~~~~~~~~~~ - A malformed incoming IXFR transfer could trigger an assertion failure - in ``named``, causing it to quit abnormally. (CVE-2021-25214) + in :iscman:`named`, causing it to quit abnormally. (CVE-2021-25214) ISC would like to thank Greg Kuechle of SaskTel for bringing this vulnerability to our attention. :gl:`#2467` -- ``named`` crashed when a DNAME record placed in the ANSWER section +- :iscman:`named` crashed when a DNAME record placed in the ANSWER section during DNAME chasing turned out to be the final answer to a client query. (CVE-2021-25215) @@ -56,7 +56,7 @@ Bug Fixes has been fixed. :gl:`#2583` - When ``stale-answer-client-timeout`` was set to a positive value and - recursion for a client query completed when ``named`` was about to + recursion for a client query completed when :iscman:`named` was about to look for a stale answer, an assertion could fail in ``query_respond()``, resulting in a crash. This has been fixed. :gl:`#2594` @@ -64,15 +64,15 @@ Bug Fixes - After upgrading to the previous release, journal files for trust anchor databases (e.g. ``managed-keys.bind.jnl``) could be left in a corrupt state. (Other zone journal files were not affected.) This has - been fixed. If a corrupt journal file is detected, ``named`` can now + been fixed. If a corrupt journal file is detected, :iscman:`named` can now recover from it. :gl:`#2600` -- When sending queries over TCP, ``dig`` now properly handles ``+tries=1 +- When sending queries over TCP, :iscman:`dig` now properly handles ``+tries=1 +retry=0`` by not retrying the connection when the remote server closes the connection prematurely. :gl:`#2490` - CDS/CDNSKEY DELETE records are now removed when a zone transitions - from a secure to an insecure state. ``named-checkzone`` also no longer + from a secure to an insecure state. :iscman:`named-checkzone` also no longer reports an error when such records are found in an unsigned zone. :gl:`#2517` @@ -80,8 +80,8 @@ Bug Fixes :option:`rndc freeze`. This has been fixed. :gl:`#2523` - After :option:`rndc dnssec -checkds ` or :option:`rndc dnssec -rollover ` is used, - ``named`` now immediately attempts to reconfigure zone keys. This + :iscman:`named` now immediately attempts to reconfigure zone keys. This change prevents unnecessary key rollover delays. :gl:`#2488` -- ``named`` crashed after skipping a primary server while transferring a +- :iscman:`named` crashed after skipping a primary server while transferring a zone over TLS. This has been fixed. :gl:`#2562` diff --git a/doc/notes/notes-9.17.13.rst b/doc/notes/notes-9.17.13.rst index 8f8adb1965..1f9e946941 100644 --- a/doc/notes/notes-9.17.13.rst +++ b/doc/notes/notes-9.17.13.rst @@ -21,7 +21,7 @@ Feature Changes - The maximum supported number of NSEC3 iterations that can be configured for a zone has been reduced to 150. :gl:`#2642` -- After the network manager was introduced to ``named`` to handle +- After the network manager was introduced to :iscman:`named` to handle incoming traffic, it was discovered that recursive performance had degraded compared to previous BIND 9 versions. This has now been fixed by processing internal tasks inside network manager worker @@ -54,7 +54,7 @@ Bug Fixes itself was preserved. :gl:`#2623` - It was possible for corrupt journal files generated by an earlier - version of ``named`` to cause problems after an upgrade. This has been + version of :iscman:`named` to cause problems after an upgrade. This has been fixed. :gl:`#2670` - TTL values in cache dumps were reported incorrectly when @@ -67,15 +67,15 @@ Bug Fixes - ``inline-signing`` was incorrectly described as being inherited from the ``options``/``view`` levels and was incorrectly accepted at those - levels without effect. This has been fixed; ``named.conf`` files with + levels without effect. This has been fixed; :iscman:`named.conf` files with ``inline-signing`` at those levels no longer load. :gl:`#2536` -- ``named`` and ``named-checkconf`` did not report an error when +- :iscman:`named` and :iscman:`named-checkconf` did not report an error when multiple zones with the ``dnssec-policy`` option set were using the same zone file. This has been fixed. :gl:`#2603` - If ``dnssec-policy`` was active and a private key file was temporarily - offline during a rekey event, ``named`` could incorrectly introduce + offline during a rekey event, :iscman:`named` could incorrectly introduce replacement keys and break a signed zone. This has been fixed. :gl:`#2596` diff --git a/doc/notes/notes-9.17.15.rst b/doc/notes/notes-9.17.15.rst index 15a618b6bc..92ae3a6054 100644 --- a/doc/notes/notes-9.17.15.rst +++ b/doc/notes/notes-9.17.15.rst @@ -15,7 +15,7 @@ Notes for BIND 9.17.15 Bug Fixes ~~~~~~~~~ -- When preparing DNS responses, ``named`` could replace the letters +- When preparing DNS responses, :iscman:`named` could replace the letters ``W`` (uppercase) and ``w`` (lowercase) with ``\000``. This has been fixed. :gl:`#2779` diff --git a/doc/notes/notes-9.17.16.rst b/doc/notes/notes-9.17.16.rst index 3fdadf3315..0b9f288a19 100644 --- a/doc/notes/notes-9.17.16.rst +++ b/doc/notes/notes-9.17.16.rst @@ -17,7 +17,7 @@ Security Fixes - Sending DNS messages with the OPCODE field set to anything other than QUERY (0) via DNS-over-TLS (DoT) or DNS-over-HTTPS (DoH) channels - triggered an assertion failure in ``named``. This has been fixed. + triggered an assertion failure in :iscman:`named`. This has been fixed. ISC would like to thank Ville Heikkila of Synopsys Cybersecurity Research Center for bringing this vulnerability to our attention. @@ -55,12 +55,12 @@ Bug Fixes database of managed keys from subsequently being read back. This has been fixed. :gl:`#2686` -- Signed, insecure delegation responses prepared by ``named`` either +- Signed, insecure delegation responses prepared by :iscman:`named` either lacked the necessary NSEC records or contained duplicate NSEC records when both wildcard expansion and CNAME chaining were required to prepare the response. This has been fixed. :gl:`#2759` -- If ``nsupdate`` sends an SOA request and receives a REFUSED response, +- If :iscman:`nsupdate` sends an SOA request and receives a REFUSED response, it now fails over to the next available server. :gl:`#2758` - A bug that caused the NSEC3 salt to be changed on every restart for diff --git a/doc/notes/notes-9.17.17.rst b/doc/notes/notes-9.17.17.rst index b707df5d7e..881d72c11a 100644 --- a/doc/notes/notes-9.17.17.rst +++ b/doc/notes/notes-9.17.17.rst @@ -15,11 +15,11 @@ Notes for BIND 9.17.17 Security Fixes ~~~~~~~~~~~~~~ -- Fixed an assertion failure that occurred in ``named`` when it +- Fixed an assertion failure that occurred in :iscman:`named` when it attempted to send a UDP packet that exceeded the MTU size, if Response Rate Limiting (RRL) was enabled. (CVE-2021-25218) :gl:`#2856` -- ``named`` failed to check the opcode of responses when performing zone +- :iscman:`named` failed to check the opcode of responses when performing zone refreshes, stub zone updates, and UPDATE forwarding. This could lead to an assertion failure under certain conditions and has been addressed by rejecting responses whose opcode does not match the @@ -43,7 +43,7 @@ New Features Feature Changes ~~~~~~~~~~~~~~~ -- Previously, ``named`` accepted FORMERR responses both with and without +- Previously, :iscman:`named` accepted FORMERR responses both with and without an OPT record, as an indication that a given server did not support EDNS. To implement full compliance with :rfc:`6891`, only FORMERR responses without an OPT record are now accepted. This intentionally @@ -58,10 +58,10 @@ Feature Changes enabled by default. :gl:`#2433` - Testing revealed that setting the thread affinity for various types of - ``named`` threads led to inconsistent recursive performance, as + :iscman:`named` threads led to inconsistent recursive performance, as sometimes multiple sets of threads competed over a single resource. - Due to the above, ``named`` no longer sets thread affinity. This + Due to the above, :iscman:`named` no longer sets thread affinity. This causes a slight dip of around 5% in authoritative performance, but recursive performance is now consistently improved. :gl:`#2822` @@ -74,6 +74,6 @@ Feature Changes Bug Fixes ~~~~~~~~~ -- Authentication of ``rndc`` messages could fail if a ``controls`` +- Authentication of :iscman:`rndc` messages could fail if a ``controls`` statement was configured with multiple key algorithms for the same listener. This has been fixed. :gl:`#2756` diff --git a/doc/notes/notes-9.17.18.rst b/doc/notes/notes-9.17.18.rst index 81e2c3dc57..23705137b0 100644 --- a/doc/notes/notes-9.17.18.rst +++ b/doc/notes/notes-9.17.18.rst @@ -20,18 +20,18 @@ New Features Feature Changes ~~~~~~~~~~~~~~~ -- When ``dnssec-signzone`` signs a zone using a successor key whose +- When :iscman:`dnssec-signzone` signs a zone using a successor key whose predecessor is still published, it now only refreshes signatures for RRsets which have an invalid signature, an expired signature, or a signature which expires within the provided cycle interval. This - allows ``dnssec-signzone`` to gradually replace signatures in a zone + allows :iscman:`dnssec-signzone` to gradually replace signatures in a zone whose ZSK is being rolled over (similarly to what ``auto-dnssec maintain;`` does). :gl:`#1551` -- ``dnssec-cds`` now only generates SHA-2 DS records by default and +- :iscman:`dnssec-cds` now only generates SHA-2 DS records by default and avoids copying deprecated SHA-1 records from a child zone to its delegation in the parent. If the child zone does not publish SHA-2 CDS - records, ``dnssec-cds`` will generate them from the CDNSKEY records. + records, :iscman:`dnssec-cds` will generate them from the CDNSKEY records. The ``-a algorithm`` option now affects the process of generating DS digest records from both CDS and CDNSKEY records. Thanks to Tony Finch. :gl:`#2871` @@ -45,16 +45,16 @@ Bug Fixes - A recent change to the internal memory structure of zone databases inadvertently neglected to update the MAPAPI value for zone files in - ``map`` format. This caused version 9.17.17 of ``named`` to attempt to + ``map`` format. This caused version 9.17.17 of :iscman:`named` to attempt to load files into memory that were no longer compatible, triggering an assertion failure on startup. The MAPAPI value has now been updated, - so ``named`` rejects outdated files when encountering them. + so :iscman:`named` rejects outdated files when encountering them. :gl:`#2872` - Zone files in ``map`` format whose size exceeded 2 GB failed to load. This has been fixed. :gl:`#2878` -- Stale data in the cache could cause ``named`` to send non-minimized +- Stale data in the cache could cause :iscman:`named` to send non-minimized queries despite QNAME minimization being enabled. This has been fixed. :gl:`#2665` diff --git a/doc/notes/notes-9.17.19.rst b/doc/notes/notes-9.17.19.rst index 25006ffca4..e59c5d8dc7 100644 --- a/doc/notes/notes-9.17.19.rst +++ b/doc/notes/notes-9.17.19.rst @@ -15,7 +15,7 @@ Notes for BIND 9.17.19 Security Fixes ~~~~~~~~~~~~~~ -- The ``lame-ttl`` option controls how long ``named`` caches certain +- The ``lame-ttl`` option controls how long :iscman:`named` caches certain types of broken responses from authoritative servers (see the `security advisory `_ for details). This caching mechanism could be abused by an attacker to @@ -65,12 +65,12 @@ Removed Features which is part of the `OpenSC`_ project. :gl:`#2691` - Old-style Dynamically Loadable Zones (DLZ) drivers that had to be - enabled in ``named`` at build time have been removed. New-style DLZ + enabled in :iscman:`named` at build time have been removed. New-style DLZ modules should be used as a replacement. :gl:`#2814` - Support for the ``map`` zone file format (``masterfile-format map;``) has been removed. Users relying on the ``map`` format are advised to - convert their zones to the ``raw`` format with ``named-compilezone`` + convert their zones to the ``raw`` format with :iscman:`named-compilezone` and change the configuration appropriately prior to upgrading BIND 9. :gl:`#2882` @@ -80,10 +80,10 @@ Feature Changes ~~~~~~~~~~~~~~~ - The network manager API is now used for sending all outgoing DNS - queries and requests from ``named`` and related tools, including - ``delv``, ``mdig``, and ``nsupdate``. :gl:`#2401` + queries and requests from :iscman:`named` and related tools, including + :iscman:`delv`, :iscman:`mdig`, and :iscman:`nsupdate`. :gl:`#2401` -- ``named`` and ``named-checkconf`` now exit with an error when a single +- :iscman:`named` and :iscman:`named-checkconf` now exit with an error when a single port configured for ``query-source``, ``transfer-source``, ``notify-source``, ``parental-source``, and/or their respective IPv6 counterparts clashes with a global listening port. This configuration @@ -91,7 +91,7 @@ Feature Changes until now (even though sending UDP messages such as NOTIFY failed). :gl:`#2888` -- ``named`` and ``named-checkconf`` now issue a warning when there is a +- :iscman:`named` and :iscman:`named-checkconf` now issue a warning when there is a single port configured for ``query-source``, ``transfer-source``, ``notify-source``, ``parental-source``, and/or for their respective IPv6 counterparts. :gl:`#2888` @@ -110,7 +110,7 @@ Bug Fixes again. :gl:`#2911` - When new IP addresses were set up by the operating system during - ``named`` startup, it could fail to listen for TCP connections on the + :iscman:`named` startup, it could fail to listen for TCP connections on the newly added interfaces. :gl:`#2852` - Under specific circumstances, zone transfers over TCP and TLS could be diff --git a/doc/notes/notes-9.17.2.rst b/doc/notes/notes-9.17.2.rst index 9640106b8d..81874ff333 100644 --- a/doc/notes/notes-9.17.2.rst +++ b/doc/notes/notes-9.17.2.rst @@ -68,7 +68,7 @@ New Features Docs`_. Release notes are no longer available as a separate document accompanying a release. :gl:`#83` -- ``named`` and ``named-checkzone`` now reject master zones that have a +- :iscman:`named` and :iscman:`named-checkzone` now reject master zones that have a DS RRset at the zone apex. Attempts to add DS records at the zone apex via UPDATE will be logged but otherwise ignored. DS records belong in the parent zone, not at the zone apex. :gl:`#1798` @@ -78,7 +78,7 @@ New Features particular type that can be added to a domain name via dynamic update. :gl:`#1657` -- ``dig`` and other tools can now print the Extended DNS Error (EDE) +- :iscman:`dig` and other tools can now print the Extended DNS Error (EDE) option when it appears in a request or a response. :gl:`#1835` - ``dig +qid=`` allows the user to specify a particular query ID @@ -96,7 +96,7 @@ Feature Changes ~~~~~~~~~~~~~~~ - The default value of ``max-stale-ttl`` has changed from 1 week to 12 - hours. This option controls how long ``named`` retains expired RRsets + hours. This option controls how long :iscman:`named` retains expired RRsets in cache as a potential mitigation mechanism, should there be a problem with one or more domains. Note that cache content retention is independent of whether stale answers are used in response to @@ -109,8 +109,8 @@ Feature Changes .. warning:: This change may be significant for administrators who expect that stale cache content will be automatically retained for up to 1 - week. Add option ``max-stale-ttl 1w;`` to ``named.conf`` to keep - the previous behavior of ``named``. + week. Add option ``max-stale-ttl 1w;`` to :iscman:`named.conf` to keep + the previous behavior of :iscman:`named`. - BIND 9 no longer sets receive/send buffer sizes for UDP sockets, relying on system defaults instead. :gl:`#1713` @@ -119,8 +119,8 @@ Feature Changes BIND 9 rwlock implementation. :gl:`#1753` - BIND 9 binaries which are neither daemons nor administrative programs - were moved to ``$bindir``. Only ``ddns-confgen``, ``named``, - ``rndc``, ``rndc-confgen``, and ``tsig-confgen`` were left in + were moved to ``$bindir``. Only :iscman:`ddns-confgen`, :iscman:`named`, + :iscman:`rndc`, :iscman:`rndc-confgen`, and ``tsig-confgen`` were left in ``$sbindir``. :gl:`#1724` - ``listen-on-v6 { any; }`` creates a separate socket for each @@ -160,12 +160,12 @@ Bug Fixes processing step that was causing this delay has now been removed. :gl:`#1834` -- ``named`` could crash with an assertion failure if the name of a +- :iscman:`named` could crash with an assertion failure if the name of a database node was looked up while the database was being modified. :gl:`#1857` - When running on a system with support for Linux capabilities, - ``named`` drops root privileges very soon after system startup. This + :iscman:`named` drops root privileges very soon after system startup. This was causing a spurious log message, ``unable to set effective uid to 0: Operation not permitted``, which has now been silenced. :gl:`#1042` :gl:`#1090` @@ -173,7 +173,7 @@ Bug Fixes - A possible deadlock in ``lib/isc/unix/socket.c`` was fixed. :gl:`#1859` -- Previously, ``named`` did not destroy some mutexes and conditional +- Previously, :iscman:`named` did not destroy some mutexes and conditional variables in netmgr code, which caused a memory leak on FreeBSD. This has been fixed. :gl:`#1893` @@ -205,7 +205,7 @@ Bug Fixes ``server-addresses`` statements due to an uninitialized DSCP value. This has been fixed. :gl:`#1812` -- When built without LMDB support, ``named`` failed to restart after a +- When built without LMDB support, :iscman:`named` failed to restart after a zone with a double quote (") in its name was added with ``rndc addzone``. Thanks to Alberto Fernández. :gl:`#1695` diff --git a/doc/notes/notes-9.17.20.rst b/doc/notes/notes-9.17.20.rst index 59c460a29b..6771d66898 100644 --- a/doc/notes/notes-9.17.20.rst +++ b/doc/notes/notes-9.17.20.rst @@ -62,7 +62,7 @@ Feature Changes - The `UseSTD3ASCIIRules`_ flag is now set for libidn2 function calls. This enables additional validation rules for IDN domains and hostnames - in ``dig``. :gl:`#1610` + in :iscman:`dig`. :gl:`#1610` .. _UseSTD3ASCIIRules: http://www.unicode.org/reports/tr46/#UseSTD3ASCIIRules @@ -70,7 +70,7 @@ Bug Fixes ~~~~~~~~~ - Reloading a catalog zone which referenced a missing/deleted member - zone triggered a runtime check failure, causing ``named`` to exit + zone triggered a runtime check failure, causing :iscman:`named` to exit prematurely. This has been fixed. :gl:`#2308` - Some lame delegations could trigger a dependency loop, in which a diff --git a/doc/notes/notes-9.17.21.rst b/doc/notes/notes-9.17.21.rst index 47ab63959f..a70eb2806c 100644 --- a/doc/notes/notes-9.17.21.rst +++ b/doc/notes/notes-9.17.21.rst @@ -36,7 +36,7 @@ Feature Changes - The `UseSTD3ASCIIRules`_ flag is now disabled again for libidn2 function calls. Applying additional validation rules for domain names - in ``dig`` (a change introduced in the previous BIND 9 release) caused + in :iscman:`dig` (a change introduced in the previous BIND 9 release) caused characters which are disallowed in hostnames (e.g. underscore ``_``, wildcard ``*``) to be silently stripped. That change was reverted. :gl:`#1610` @@ -50,7 +50,7 @@ Feature Changes following triggering events: ``socket is not connected``, ``quota reached``, and ``soft quota reached``. :gl:`#2700` -- ``dnssec-dsfromkey`` no longer generates DS records from revoked keys. +- :iscman:`dnssec-dsfromkey` no longer generates DS records from revoked keys. :gl:`#853` .. _UseSTD3ASCIIRules: http://www.unicode.org/reports/tr46/#UseSTD3ASCIIRules @@ -61,7 +61,7 @@ Bug Fixes - Removing a configured ``catalog-zone`` clause from the configuration, running :option:`rndc reconfig`, then bringing back the removed ``catalog-zone`` clause and running :option:`rndc reconfig` again caused - ``named`` to crash. This has been fixed. :gl:`#1608` + :iscman:`named` to crash. This has been fixed. :gl:`#1608` - The resolver could hang on shutdown due to dispatch resources not being cleaned up when a TCP connection was reset, or due to dependency diff --git a/doc/notes/notes-9.17.22.rst b/doc/notes/notes-9.17.22.rst index feb6763ef4..9298600880 100644 --- a/doc/notes/notes-9.17.22.rst +++ b/doc/notes/notes-9.17.22.rst @@ -15,17 +15,17 @@ Notes for BIND 9.17.22 New Features ~~~~~~~~~~~~ -- ``named`` now logs TLS pre-master secrets for debugging purposes when +- :iscman:`named` now logs TLS pre-master secrets for debugging purposes when the ``SSLKEYLOGFILE`` environment variable is set. This enables troubleshooting issues with encrypted DNS traffic. :gl:`#2723` Feature Changes ~~~~~~~~~~~~~~~ -- Overall memory use by ``named`` has been optimized and reduced, +- Overall memory use by :iscman:`named` has been optimized and reduced, especially on systems with many CPU cores. :gl:`#2398` :gl:`#3048` -- ``named`` formerly generated an ephemeral key and certificate for the +- :iscman:`named` formerly generated an ephemeral key and certificate for the ``tls ephemeral`` configuration using the RSA algorithm with 4096-bit keys. This has been changed to the ECDSA P-256 algorithm. :gl:`#2264` @@ -44,6 +44,6 @@ Bug Fixes - Under certain circumstances, the signed version of an inline-signed zone could be dumped to disk without the serial number of the unsigned version of the zone. This prevented resynchronization of the zone - contents after ``named`` restarted, if the unsigned zone file was - modified while ``named`` was not running. This has been fixed. + contents after :iscman:`named` restarted, if the unsigned zone file was + modified while :iscman:`named` was not running. This has been fixed. :gl:`#3071` diff --git a/doc/notes/notes-9.17.3.rst b/doc/notes/notes-9.17.3.rst index b4e200dc28..1ecd164a6d 100644 --- a/doc/notes/notes-9.17.3.rst +++ b/doc/notes/notes-9.17.3.rst @@ -15,7 +15,7 @@ Notes for BIND 9.17.3 New Features ~~~~~~~~~~~~ -- New ``rndc`` command :option:`rndc dnssec -status ` shows the current DNSSEC +- New :iscman:`rndc` command :option:`rndc dnssec -status ` shows the current DNSSEC policy and keys in use, the key states, and rollover status. :gl:`#1612` @@ -34,7 +34,7 @@ Feature Changes - As part of an ongoing effort to use :rfc:`8499` terminology, ``primaries`` can now be used as a synonym for ``masters`` in - ``named.conf``. Similarly, ``notify primary-only`` can now be used as + :iscman:`named.conf`. Similarly, ``notify primary-only`` can now be used as a synonym for ``notify master-only``. The output of ``rndc zonestatus`` now uses ``primary`` and ``secondary`` terminology. :gl:`#1948` @@ -43,21 +43,21 @@ Bug Fixes ~~~~~~~~~ - A race condition could occur if a TCP socket connection was closed - while ``named`` was waiting for a recursive response. The attempt to + while :iscman:`named` was waiting for a recursive response. The attempt to send a response over the closing connection triggered an assertion failure in the function ``isc__nm_tcpdns_send()``. :gl:`#1937` -- A race condition could occur when ``named`` attempted to use a UDP +- A race condition could occur when :iscman:`named` attempted to use a UDP interface that was shutting down. This triggered an assertion failure in ``uv__udp_finish_close()``. :gl:`#1938` - Fix assertion failure when server was under load and root zone had not yet been loaded. :gl:`#1862` -- ``named`` could crash when cleaning dead nodes in ``lib/dns/rbtdb.c`` +- :iscman:`named` could crash when cleaning dead nodes in ``lib/dns/rbtdb.c`` that were being reused. :gl:`#1968` -- ``named`` crashed on shutdown when a new ``rndc`` connection was +- :iscman:`named` crashed on shutdown when a new :iscman:`rndc` connection was received during shutdown. This has been fixed. :gl:`#1747` - The DS RRset returned by ``dns_keynode_dsset()`` was used in a diff --git a/doc/notes/notes-9.17.4.rst b/doc/notes/notes-9.17.4.rst index 4598f3dff2..4e511c3aff 100644 --- a/doc/notes/notes-9.17.4.rst +++ b/doc/notes/notes-9.17.4.rst @@ -21,7 +21,7 @@ Security Fixes ISC would like to thank Emanuel Almeida of Cisco Systems, Inc. for bringing this vulnerability to our attention. :gl:`#1996` -- ``named`` could crash after failing an assertion check in certain +- :iscman:`named` could crash after failing an assertion check in certain query resolution scenarios where QNAME minimization and forwarding were both enabled. To prevent such crashes, QNAME minimization is now always disabled for a given query resolution process, if forwarders @@ -61,12 +61,12 @@ New Features - A new configuration option ``stale-cache-enable`` has been introduced to enable or disable keeping stale answers in cache. :gl:`#1712` -- ``rndc`` has been updated to use the new BIND network manager API. +- :iscman:`rndc` has been updated to use the new BIND network manager API. This change had the side effect of altering the TCP timeout for RNDC connections from 60 seconds to the ``tcp-idle-timeout`` value, which defaults to 30 seconds. Also, because the network manager currently has no support for UNIX-domain sockets, those cannot now be used - with ``rndc``. This will be addressed in a future release, either by + with :iscman:`rndc`. This will be addressed in a future release, either by restoring UNIX-domain socket support or by formally declaring them to be obsolete in the control channel. :gl:`#1759` @@ -97,14 +97,14 @@ Bug Fixes ``response-policy`` statement. This has been fixed. :gl:`#1619` - The IPv6 Duplicate Address Detection (DAD) mechanism could - inadvertently prevent ``named`` from binding to new IPv6 interfaces, + inadvertently prevent :iscman:`named` from binding to new IPv6 interfaces, by causing multiple route socket messages to be sent for each IPv6 - address. ``named`` monitors for new interfaces to ``bind()`` to when + address. :iscman:`named` monitors for new interfaces to ``bind()`` to when it is configured to listen on ``any`` or on a specific range of addresses. New IPv6 interfaces can be in a "tentative" state before they are fully available for use. When DAD is in use, two messages are emitted by the route socket: one when the interface first appears and - then a second one when it is fully "up." An attempt by ``named`` to + then a second one when it is fully "up." An attempt by :iscman:`named` to ``bind()`` to the new interface prematurely would fail, causing it thereafter to ignore that address/interface. The problem was worked around by setting the ``IP_FREEBIND`` option on the socket and trying diff --git a/doc/notes/notes-9.17.5.rst b/doc/notes/notes-9.17.5.rst index fb038c6f4d..e7164e0de0 100644 --- a/doc/notes/notes-9.17.5.rst +++ b/doc/notes/notes-9.17.5.rst @@ -15,12 +15,12 @@ Notes for BIND 9.17.5 New Features ~~~~~~~~~~~~ -- Add a new ``rndc`` command, :option:`rndc dnssec -checkds `, which signals to - ``named`` that a DS record for a given zone or key has been published +- Add a new :iscman:`rndc` command, :option:`rndc dnssec -checkds `, which signals to + :iscman:`named` that a DS record for a given zone or key has been published or withdrawn from the parent. This command replaces the time-based ``parent-registration-delay`` configuration option. :gl:`#1613` -- Log when ``named`` adds a CDS/CDNSKEY to the zone. :gl:`#1748` +- Log when :iscman:`named` adds a CDS/CDNSKEY to the zone. :gl:`#1748` Removed Features ~~~~~~~~~~~~~~~~ @@ -47,7 +47,7 @@ Feature Changes Bug Fixes ~~~~~~~~~ -- In rare circumstances, ``named`` would exit with an assertion failure +- In rare circumstances, :iscman:`named` would exit with an assertion failure when the number of nodes stored in the red-black tree exceeded the maximum allowed size of the internal hash table. :gl:`#2104` @@ -56,13 +56,13 @@ Bug Fixes resulted in a generic protocol error being returned instead of a more specific error code. :gl:`#1928` -- With query name minimization enabled, ``named`` failed to resolve +- With query name minimization enabled, :iscman:`named` failed to resolve ``ip6.arpa.`` names that had extra labels to the left of the IPv6 - part. For example, when ``named`` attempted query name minimization on + part. For example, when :iscman:`named` attempted query name minimization on a name like ``A.B.1.2.3.4.(...).ip6.arpa.``, it stopped at the leftmost IPv6 label, i.e. ``1.2.3.4.(...).ip6.arpa.``, without considering the extra labels (``A.B``). That caused a query loop when - resolving the name: if ``named`` received NXDOMAIN answers, then the + resolving the name: if :iscman:`named` received NXDOMAIN answers, then the same query was repeatedly sent until the number of queries sent reached the value of the ``max-recursion-queries`` configuration option. :gl:`#1847` diff --git a/doc/notes/notes-9.17.6.rst b/doc/notes/notes-9.17.6.rst index 900f4cccfc..fe6857f648 100644 --- a/doc/notes/notes-9.17.6.rst +++ b/doc/notes/notes-9.17.6.rst @@ -15,10 +15,10 @@ Notes for BIND 9.17.6 New Features ~~~~~~~~~~~~ -- Add a new ``rndc`` command, :option:`rndc dnssec -rollover `, which triggers +- Add a new :iscman:`rndc` command, :option:`rndc dnssec -rollover `, which triggers a manual rollover for a specific key. :gl:`#1749` -- Add a new ``rndc`` command, :option:`rndc dumpdb -expired `, which dumps the +- Add a new :iscman:`rndc` command, :option:`rndc dumpdb -expired `, which dumps the cache database, including expired RRsets that are awaiting cleanup, to the ``dump-file`` for diagnostic purposes. :gl:`#1870` @@ -34,7 +34,7 @@ Feature Changes - DNS Flag Day 2020: The default EDNS buffer size has been changed from 4096 to 1232 bytes, the EDNS buffer size probing has been removed, and - ``named`` now sets the DF (Don't Fragment) flag on outgoing UDP + :iscman:`named` now sets the DF (Don't Fragment) flag on outgoing UDP packets. According to measurements done by multiple parties, this should not cause any operational problems as most of the Internet "core" is able to cope with IP message sizes between 1400-1500 bytes; @@ -48,15 +48,15 @@ Feature Changes Bug Fixes ~~~~~~~~~ -- ``named`` reported an invalid memory size when running in an +- :iscman:`named` reported an invalid memory size when running in an environment that did not properly report the number of available memory pages and/or the size of each memory page. :gl:`#2166` -- With multiple forwarders configured, ``named`` could fail the +- With multiple forwarders configured, :iscman:`named` could fail the ``REQUIRE(msg->state == (-1))`` assertion in ``lib/dns/message.c``, causing it to crash. This has been fixed. :gl:`#2124` -- ``named`` erroneously performed continuous key rollovers for KASP +- :iscman:`named` erroneously performed continuous key rollovers for KASP policies that used algorithm Ed25519 or Ed448 due to a mismatch between created key size and expected key size. :gl:`#2171` diff --git a/doc/notes/notes-9.17.7.rst b/doc/notes/notes-9.17.7.rst index 47c8b1498f..d0f156ab17 100644 --- a/doc/notes/notes-9.17.7.rst +++ b/doc/notes/notes-9.17.7.rst @@ -15,9 +15,9 @@ Notes for BIND 9.17.7 New Features ~~~~~~~~~~~~ -- Support for DNS over TLS (DoT) has been added: the ``dig`` tool is now - able to send DoT queries (``+tls`` option) and ``named`` can handle - DoT queries (``listen-on tls ...`` option). ``named`` can use either a +- Support for DNS over TLS (DoT) has been added: the :iscman:`dig` tool is now + able to send DoT queries (``+tls`` option) and :iscman:`named` can handle + DoT queries (``listen-on tls ...`` option). :iscman:`named` can use either a certificate provided by the user or an ephemeral certificate generated automatically upon startup. :gl:`#1840` @@ -29,26 +29,26 @@ New Features Feature Changes ~~~~~~~~~~~~~~~ -- The ``dig``, ``host``, and ``nslookup`` tools have been converted to +- The :iscman:`dig`, :iscman:`host`, and :iscman:`nslookup` tools have been converted to use the new network manager API rather than the older ISC socket API. As a side effect of this change, the ``dig +unexpected`` option no longer works. This could previously be used to diagnose broken servers or network configurations by listening for replies from servers other than the one that was queried. With the new API, such answers are - filtered before they ever reach ``dig``, so the option has been + filtered before they ever reach :iscman:`dig`, so the option has been removed. :gl:`#2140` -- The network manager API is now used by ``named`` to send zone transfer +- The network manager API is now used by :iscman:`named` to send zone transfer requests. :gl:`#2016` Bug Fixes ~~~~~~~~~ -- ``named`` could crash with an assertion failure if a TCP connection +- :iscman:`named` could crash with an assertion failure if a TCP connection were closed while a request was still being processed. :gl:`#2227` -- ``named`` acting as a resolver could incorrectly treat signed zones +- :iscman:`named` acting as a resolver could incorrectly treat signed zones with no DS record at the parent as bogus. Such zones should be treated as insecure. This has been fixed. :gl:`#2236` diff --git a/doc/notes/notes-9.17.8.rst b/doc/notes/notes-9.17.8.rst index 2102c635c3..92f57498f8 100644 --- a/doc/notes/notes-9.17.8.rst +++ b/doc/notes/notes-9.17.8.rst @@ -20,11 +20,11 @@ New Features NSEC3 salt collisions are automatically prevented during resalting. :gl:`#1620` -- ``dig`` output now includes the transport protocol used (UDP, TCP, or +- :iscman:`dig` output now includes the transport protocol used (UDP, TCP, or TLS). :gl:`#1816` -- ``dig`` can now report the DNS64 prefixes in use (``+dns64prefix``). - This is useful when the host on which ``dig`` is run is behind an +- :iscman:`dig` can now report the DNS64 prefixes in use (``+dns64prefix``). + This is useful when the host on which :iscman:`dig` is run is behind an IPv6-only link, using DNS64/NAT64 or 464XLAT for IPv4aaS (IPv4 as a Service). :gl:`#1154` @@ -37,11 +37,11 @@ Feature Changes - Earlier releases of BIND versions 9.16 and newer required the operating system to support load-balanced sockets in order for - ``named`` to be able to achieve high performance (by distributing + :iscman:`named` to be able to achieve high performance (by distributing incoming queries among multiple threads). However, the only operating systems currently known to support load-balanced sockets are Linux and FreeBSD 12, which means both UDP and TCP performance were limited to a - single thread on other systems. As of BIND 9.17.8, ``named`` attempts + single thread on other systems. As of BIND 9.17.8, :iscman:`named` attempts to distribute incoming queries among multiple threads on systems which lack support for load-balanced sockets (except Windows). :gl:`#2137` diff --git a/doc/notes/notes-9.17.9.rst b/doc/notes/notes-9.17.9.rst index 04459adcd4..db9f53584d 100644 --- a/doc/notes/notes-9.17.9.rst +++ b/doc/notes/notes-9.17.9.rst @@ -27,10 +27,10 @@ Feature Changes described in :rfc:`8078`. :gl:`#1750` - When using the ``unixtime`` or ``date`` method to update the SOA - serial number, ``named`` and ``dnssec-signzone`` silently fell back to + serial number, :iscman:`named` and :iscman:`dnssec-signzone` silently fell back to the ``increment`` method to prevent the new serial number from being smaller than the old serial number (using serial number arithmetics). - ``dnssec-signzone`` now prints a warning message, and ``named`` logs a + :iscman:`dnssec-signzone` now prints a warning message, and :iscman:`named` logs a warning, when such a fallback happens. :gl:`#2058` Bug Fixes @@ -40,16 +40,16 @@ Bug Fixes the same time, resulting in an unpredictable but low-probability assertion failure in ``free_rbtdb()``. This has been fixed. :gl:`#2317` -- ``named`` no longer attempts to assign threads to CPUs outside the CPU +- :iscman:`named` no longer attempts to assign threads to CPUs outside the CPU affinity set. Thanks to Ole Bjørn Hessen. :gl:`#2245` -- When reconfiguring ``named``, removing ``auto-dnssec`` did not turn +- When reconfiguring :iscman:`named`, removing ``auto-dnssec`` did not turn off DNSSEC maintenance. This has been fixed. :gl:`#2341` - The report of intermittent BIND assertion failures triggered in ``lib/dns/resolver.c:dns_name_issubdomain()`` has now been closed without further action. Our initial response to this was to add - diagnostic logging instead of terminating ``named``, anticipating that + diagnostic logging instead of terminating :iscman:`named`, anticipating that we would receive further useful troubleshooting input. This workaround first appeared in BIND releases 9.17.5 and 9.16.7. However, since those releases were published, there have been no new reports of diff --git a/doc/notes/notes-current.rst b/doc/notes/notes-current.rst index fd41ed5c2f..a66b6eb57d 100644 --- a/doc/notes/notes-current.rst +++ b/doc/notes/notes-current.rst @@ -25,7 +25,7 @@ Known Issues New Features ~~~~~~~~~~~~ -- ``dnssec-verify`` and ``dnssec-signzone`` now accept a ``-J`` option to +- :iscman:`dnssec-verify` and :iscman:`dnssec-signzone` now accept a ``-J`` option to specify a journal file to read when loading the zone to be verified or signed. :gl:`#2486` @@ -33,11 +33,11 @@ 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` - The ``keep-order-response`` option has been declared obsolete and the - functionality has been removed. ``named`` expects DNS clients to be + functionality has been removed. :iscman:`named` expects DNS clients to be fully compliant with :rfc:`7766`. :gl:`#3140` Feature Changes @@ -59,7 +59,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` @@ -74,7 +74,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 From 420a71df57812b5bfa359882ab592d383be59576 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 3 Mar 2022 22:27:26 +0100 Subject: [PATCH 09/11] Remove reference to ndc utility from BIND 8 --- bin/rndc/rndc.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst index 65b6af3ef3..c241d7ec48 100644 --- a/bin/rndc/rndc.rst +++ b/bin/rndc/rndc.rst @@ -26,8 +26,7 @@ Synopsis Description ~~~~~~~~~~~ -:program:`rndc` controls the operation of a name server; it supersedes the -``ndc`` utility. If :program:`rndc` is +:program:`rndc` controls the operation of a name server. If :program:`rndc` is invoked with no command line options or arguments, it prints a short summary of the supported commands and the available options and their arguments. @@ -648,5 +647,5 @@ See Also ~~~~~~~~ :manpage:`rndc.conf(5)`, :manpage:`rndc-confgen(8)`, -:manpage:`named(8)`, :manpage:`named.conf(5)`, :manpage:`ndc(8)`, BIND 9 Administrator +:manpage:`named(8)`, :manpage:`named.conf(5)`, BIND 9 Administrator Reference Manual. From 1d4d008fc98ce819e07d27c6a3072cf9e474a47e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Fri, 4 Mar 2022 13:10:25 +0100 Subject: [PATCH 10/11] Add internal hyperlinks to See Also section of manual pages Replace :manpage: with :iscman: to generate internal hyperlinks. That way reader can use links even when offline, and jumps to man pages for the same version. Formerly HTML version of man pages did not have links in See Also section because :manpage: role in Sphinx can generate only external hyperlinks - and we do not have that enabled. Enabling the Sphinx :manpage: linking could reliably create hyperlinks only to external URLs, but that would take users to another version of docs. Generated by: find bin -name '*.rst' | xargs sed -i -e 's/:manpage:`\([^(]\+\)(\([0-9]\))`/:iscman:`\1(\2) <\1>`/g' + hand-edit to revert change for mmencode reference which is not provided in our source tree. --- bin/check/named-checkconf.rst | 2 +- bin/check/named-checkzone.rst | 4 ++-- bin/check/named-compilezone.rst | 4 ++-- bin/confgen/ddns-confgen.rst | 2 +- bin/confgen/rndc-confgen.rst | 2 +- bin/confgen/tsig-keygen.rst | 2 +- bin/delv/delv.rst | 2 +- bin/dig/dig.rst | 2 +- bin/dig/host.rst | 2 +- bin/dig/nslookup.rst | 2 +- bin/dnssec/dnssec-cds.rst | 2 +- bin/dnssec/dnssec-dsfromkey.rst | 2 +- bin/dnssec/dnssec-importkey.rst | 2 +- bin/dnssec/dnssec-keyfromlabel.rst | 2 +- bin/dnssec/dnssec-keygen.rst | 2 +- bin/dnssec/dnssec-revoke.rst | 2 +- bin/dnssec/dnssec-settime.rst | 2 +- bin/dnssec/dnssec-signzone.rst | 2 +- bin/dnssec/dnssec-verify.rst | 2 +- bin/named/named.conf.rst | 2 +- bin/named/named.rst | 2 +- bin/nsupdate/nsupdate.rst | 2 +- bin/rndc/rndc.conf.rst | 2 +- bin/rndc/rndc.rst | 4 ++-- bin/tools/dnstap-read.rst | 2 +- bin/tools/mdig.rst | 2 +- bin/tools/named-journalprint.rst | 2 +- bin/tools/named-rrchecker.rst | 2 +- doc/man/named-checkzone.1in | 4 ++-- doc/man/named-compilezone.1in | 4 ++-- doc/man/rndc.8in | 5 ++--- 31 files changed, 37 insertions(+), 38 deletions(-) diff --git a/bin/check/named-checkconf.rst b/bin/check/named-checkconf.rst index a09e8149fe..b3065a512a 100644 --- a/bin/check/named-checkconf.rst +++ b/bin/check/named-checkconf.rst @@ -105,4 +105,4 @@ and 0 otherwise. See Also ~~~~~~~~ -:manpage:`named(8)`, :manpage:`named-checkzone(8)`, BIND 9 Administrator Reference Manual. +:iscman:`named(8) `, :iscman:`named-checkzone(8) `, BIND 9 Administrator Reference Manual. diff --git a/bin/check/named-checkzone.rst b/bin/check/named-checkzone.rst index 232d2734c0..563752f476 100644 --- a/bin/check/named-checkzone.rst +++ b/bin/check/named-checkzone.rst @@ -218,5 +218,5 @@ and 0 otherwise. See Also ~~~~~~~~ -:manpage:`named(8)`, :manpage:`named-checkconf(8)`, :manpage:`named-compilezone(8)`, -:rfc:`1035`, BIND 9 Administrator Reference Manual. +:iscman:`named(8) `, :iscman:`named-checkconf(8) `, :iscman:`named-compilezone(8) `, :rfc:`1035`, BIND 9 Administrator Reference +Manual. diff --git a/bin/check/named-compilezone.rst b/bin/check/named-compilezone.rst index be719150ca..fa47f154c2 100644 --- a/bin/check/named-compilezone.rst +++ b/bin/check/named-compilezone.rst @@ -220,5 +220,5 @@ and 0 otherwise. See Also ~~~~~~~~ -:manpage:`named(8)`, :manpage:`named-checkconf(8)`, :manpage:`named-checkzone(8)`, -:rfc:`1035`, BIND 9 Administrator Reference Manual. +:iscman:`named(8) `, :iscman:`named-checkconf(8) `, :iscman:`named-checkzone(8) `, `:rfc:`1035`, +BIND 9 Administrator Reference Manual. diff --git a/bin/confgen/ddns-confgen.rst b/bin/confgen/ddns-confgen.rst index f4daccc065..9dd9d5ef5f 100644 --- a/bin/confgen/ddns-confgen.rst +++ b/bin/confgen/ddns-confgen.rst @@ -93,4 +93,4 @@ Options See Also ~~~~~~~~ -:manpage:`nsupdate(1)`, :manpage:`named.conf(5)`, :manpage:`named(8)`, BIND 9 Administrator Reference Manual. +:iscman:`nsupdate(1) `, :iscman:`named.conf(5) `, :iscman:`named(8) `, BIND 9 Administrator Reference Manual. diff --git a/bin/confgen/rndc-confgen.rst b/bin/confgen/rndc-confgen.rst index c32db065a2..0a91489c48 100644 --- a/bin/confgen/rndc-confgen.rst +++ b/bin/confgen/rndc-confgen.rst @@ -118,4 +118,4 @@ To print a sample :iscman:`rndc.conf` file and the corresponding ``controls`` an See Also ~~~~~~~~ -:manpage:`rndc(8)`, :manpage:`rndc.conf(5)`, :manpage:`named(8)`, BIND 9 Administrator Reference Manual. +:iscman:`rndc(8) `, :iscman:`rndc.conf(5) `, :iscman:`named(8) `, BIND 9 Administrator Reference Manual. diff --git a/bin/confgen/tsig-keygen.rst b/bin/confgen/tsig-keygen.rst index 4580ceb3e6..7420bede43 100644 --- a/bin/confgen/tsig-keygen.rst +++ b/bin/confgen/tsig-keygen.rst @@ -51,4 +51,4 @@ Options See Also ~~~~~~~~ -:manpage:`nsupdate(1)`, :manpage:`named.conf(5)`, :manpage:`named(8)`, BIND 9 Administrator Reference Manual. +:iscman:`nsupdate(1) `, :iscman:`named.conf(5) `, :iscman:`named(8) `, BIND 9 Administrator Reference Manual. diff --git a/bin/delv/delv.rst b/bin/delv/delv.rst index f78ef4115d..3d06448563 100644 --- a/bin/delv/delv.rst +++ b/bin/delv/delv.rst @@ -361,4 +361,4 @@ Files See Also ~~~~~~~~ -:manpage:`dig(1)`, :manpage:`named(8)`, :rfc:`4034`, :rfc:`4035`, :rfc:`4431`, :rfc:`5074`, :rfc:`5155`. +:iscman:`dig(1) `, :iscman:`named(8) `, :rfc:`4034`, :rfc:`4035`, :rfc:`4431`, :rfc:`5074`, :rfc:`5155`. diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst index cbfdf857f4..07505b18dc 100644 --- a/bin/dig/dig.rst +++ b/bin/dig/dig.rst @@ -769,7 +769,7 @@ Files See Also ~~~~~~~~ -:manpage:`delv(1)`, :manpage:`host(1)`, :manpage:`named(8)`, :manpage:`dnssec-keygen(8)`, :rfc:`1035`. +:iscman:`delv(1) `, :iscman:`host(1) `, :iscman:`named(8) `, :iscman:`dnssec-keygen(8) `, :rfc:`1035`. Bugs ~~~~ diff --git a/bin/dig/host.rst b/bin/dig/host.rst index bbc565253e..2647d36a73 100644 --- a/bin/dig/host.rst +++ b/bin/dig/host.rst @@ -190,4 +190,4 @@ Files See Also ~~~~~~~~ -:manpage:`dig(1)`, :manpage:`named(8)`. +:iscman:`dig(1) `, :iscman:`named(8) `. diff --git a/bin/dig/nslookup.rst b/bin/dig/nslookup.rst index 0462112ab4..2b92aa761b 100644 --- a/bin/dig/nslookup.rst +++ b/bin/dig/nslookup.rst @@ -205,4 +205,4 @@ Files See Also ~~~~~~~~ -:manpage:`dig(1)`, :manpage:`host(1)`, :manpage:`named(8)`. +:iscman:`dig(1) `, :iscman:`host(1) `, :iscman:`named(8) `. diff --git a/bin/dnssec/dnssec-cds.rst b/bin/dnssec/dnssec-cds.rst index 69b652db09..09960e91d3 100644 --- a/bin/dnssec/dnssec-cds.rst +++ b/bin/dnssec/dnssec-cds.rst @@ -217,5 +217,5 @@ protection time. See Also ~~~~~~~~ -:manpage:`dig(1)`, :manpage:`dnssec-settime(8)`, :manpage:`dnssec-signzone(8)`, :manpage:`nsupdate(1)`, BIND 9 Administrator +:iscman:`dig(1) `, :iscman:`dnssec-settime(8) `, :iscman:`dnssec-signzone(8) `, :iscman:`nsupdate(1) `, BIND 9 Administrator Reference Manual, :rfc:`7344`. diff --git a/bin/dnssec/dnssec-dsfromkey.rst b/bin/dnssec/dnssec-dsfromkey.rst index 2819b028f3..9ca025a319 100644 --- a/bin/dnssec/dnssec-dsfromkey.rst +++ b/bin/dnssec/dnssec-dsfromkey.rst @@ -154,6 +154,6 @@ A keyfile error may return "file not found," even if the file exists. See Also ~~~~~~~~ -:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual, +:iscman:`dnssec-keygen(8) `, :iscman:`dnssec-signzone(8) `, BIND 9 Administrator Reference Manual, :rfc:`3658` (DS RRs), :rfc:`4509` (SHA-256 for DS RRs), :rfc:`6605` (SHA-384 for DS RRs), :rfc:`7344` (CDS and CDNSKEY RRs). diff --git a/bin/dnssec/dnssec-importkey.rst b/bin/dnssec/dnssec-importkey.rst index 73f011f615..b8b70d13fd 100644 --- a/bin/dnssec/dnssec-importkey.rst +++ b/bin/dnssec/dnssec-importkey.rst @@ -121,5 +121,5 @@ or the full file name ``Knnnn.+aaa+iiiii.key``, as generated by See Also ~~~~~~~~ -:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual, +:iscman:`dnssec-keygen(8) `, :iscman:`dnssec-signzone(8) `, BIND 9 Administrator Reference Manual, :rfc:`5011`. diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst index bbb26f1584..c5d79ea612 100644 --- a/bin/dnssec/dnssec-keyfromlabel.rst +++ b/bin/dnssec/dnssec-keyfromlabel.rst @@ -273,5 +273,5 @@ security reasons, this file does not have general read permission. See Also ~~~~~~~~ -:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual, +:iscman:`dnssec-keygen(8) `, :iscman:`dnssec-signzone(8) `, BIND 9 Administrator Reference Manual, :rfc:`4034`, :rfc:`7512`. diff --git a/bin/dnssec/dnssec-keygen.rst b/bin/dnssec/dnssec-keygen.rst index 12b240bcc3..700149ffc8 100644 --- a/bin/dnssec/dnssec-keygen.rst +++ b/bin/dnssec/dnssec-keygen.rst @@ -339,5 +339,5 @@ To generate a matching key-signing key, issue the command: See Also ~~~~~~~~ -:manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual, :rfc:`2539`, +:iscman:`dnssec-signzone(8) `, BIND 9 Administrator Reference Manual, :rfc:`2539`, :rfc:`2845`, :rfc:`4034`. diff --git a/bin/dnssec/dnssec-revoke.rst b/bin/dnssec/dnssec-revoke.rst index 53aa8a9d0d..052865fb7c 100644 --- a/bin/dnssec/dnssec-revoke.rst +++ b/bin/dnssec/dnssec-revoke.rst @@ -75,4 +75,4 @@ Options See Also ~~~~~~~~ -:manpage:`dnssec-keygen(8)`, BIND 9 Administrator Reference Manual, :rfc:`5011`. +:iscman:`dnssec-keygen(8) `, BIND 9 Administrator Reference Manual, :rfc:`5011`. diff --git a/bin/dnssec/dnssec-settime.rst b/bin/dnssec/dnssec-settime.rst index 1f87049d70..a71712ca04 100644 --- a/bin/dnssec/dnssec-settime.rst +++ b/bin/dnssec/dnssec-settime.rst @@ -252,5 +252,5 @@ associated with a key. See Also ~~~~~~~~ -:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual, +:iscman:`dnssec-keygen(8) `, :iscman:`dnssec-signzone(8) `, BIND 9 Administrator Reference Manual, :rfc:`5011`. diff --git a/bin/dnssec/dnssec-signzone.rst b/bin/dnssec/dnssec-signzone.rst index df84f98515..244fc64d61 100644 --- a/bin/dnssec/dnssec-signzone.rst +++ b/bin/dnssec/dnssec-signzone.rst @@ -423,5 +423,5 @@ The private keys are assumed to be in the current directory. See Also ~~~~~~~~ -:manpage:`dnssec-keygen(8)`, BIND 9 Administrator Reference Manual, :rfc:`4033`, +:iscman:`dnssec-keygen(8) `, BIND 9 Administrator Reference Manual, :rfc:`4033`, :rfc:`4641`. diff --git a/bin/dnssec/dnssec-verify.rst b/bin/dnssec/dnssec-verify.rst index cba858612d..870089482b 100644 --- a/bin/dnssec/dnssec-verify.rst +++ b/bin/dnssec/dnssec-verify.rst @@ -104,4 +104,4 @@ Options See Also ~~~~~~~~ -:manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual, :rfc:`4033`. +:iscman:`dnssec-signzone(8) `, BIND 9 Administrator Reference Manual, :rfc:`4033`. diff --git a/bin/named/named.conf.rst b/bin/named/named.conf.rst index aeda5c9490..3ce51e38ad 100644 --- a/bin/named/named.conf.rst +++ b/bin/named/named.conf.rst @@ -904,5 +904,5 @@ Files See Also ~~~~~~~~ -:manpage:`named(8)`, :manpage:`named-checkconf(8)`, :manpage:`rndc(8)`, :manpage:`rndc-confgen(8)`, :manpage:`tsig-keygen(8)`, BIND 9 Administrator Reference Manual. +:iscman:`named(8) `, :iscman:`named-checkconf(8) `, :iscman:`rndc(8) `, :iscman:`rndc-confgen(8) `, :iscman:`tsig-keygen(8) `, BIND 9 Administrator Reference Manual. diff --git a/bin/named/named.rst b/bin/named/named.rst index f3557b01e4..21a82c4dbd 100644 --- a/bin/named/named.rst +++ b/bin/named/named.rst @@ -238,4 +238,4 @@ Files See Also ~~~~~~~~ -:rfc:`1033`, :rfc:`1034`, :rfc:`1035`, :manpage:`named-checkconf(8)`, :manpage:`named-checkzone(8)`, :manpage:`rndc(8)`, :manpage:`named.conf(5)`, BIND 9 Administrator Reference Manual. +:rfc:`1033`, :rfc:`1034`, :rfc:`1035`, :iscman:`named-checkconf(8) `, :iscman:`named-checkzone(8) `, :iscman:`rndc(8) `, :iscman:`named.conf(5) `, BIND 9 Administrator Reference Manual. diff --git a/bin/nsupdate/nsupdate.rst b/bin/nsupdate/nsupdate.rst index 05fe3e4fe0..3d9425a5cb 100644 --- a/bin/nsupdate/nsupdate.rst +++ b/bin/nsupdate/nsupdate.rst @@ -375,7 +375,7 @@ See Also ~~~~~~~~ :rfc:`2136`, :rfc:`3007`, :rfc:`2104`, :rfc:`2845`, :rfc:`1034`, :rfc:`2535`, :rfc:`2931`, -:manpage:`named(8)`, :manpage:`dnssec-keygen(8)`, :manpage:`tsig-keygen(8)`. +:iscman:`named(8) `, :iscman:`dnssec-keygen(8) `, :iscman:`tsig-keygen(8) `. Bugs ~~~~ diff --git a/bin/rndc/rndc.conf.rst b/bin/rndc/rndc.conf.rst index 7a63998e39..20e6bc97a4 100644 --- a/bin/rndc/rndc.conf.rst +++ b/bin/rndc/rndc.conf.rst @@ -155,4 +155,4 @@ details. See Also ~~~~~~~~ -:manpage:`rndc(8)`, :manpage:`rndc-confgen(8)`, :manpage:`mmencode(1)`, BIND 9 Administrator Reference Manual. +:iscman:`rndc(8) `, :iscman:`rndc-confgen(8) `, :manpage:`mmencode(1)`, BIND 9 Administrator Reference Manual. diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst index c241d7ec48..c5f2b29281 100644 --- a/bin/rndc/rndc.rst +++ b/bin/rndc/rndc.rst @@ -646,6 +646,6 @@ Several error messages could be clearer. See Also ~~~~~~~~ -:manpage:`rndc.conf(5)`, :manpage:`rndc-confgen(8)`, -:manpage:`named(8)`, :manpage:`named.conf(5)`, BIND 9 Administrator +:iscman:`rndc.conf(5) `, :iscman:`rndc-confgen(8) `, +:iscman:`named(8) `, :iscman:`named.conf(5) `, BIND 9 Administrator Reference Manual. diff --git a/bin/tools/dnstap-read.rst b/bin/tools/dnstap-read.rst index 49dceab433..a5956825fc 100644 --- a/bin/tools/dnstap-read.rst +++ b/bin/tools/dnstap-read.rst @@ -55,4 +55,4 @@ Options See Also ~~~~~~~~ -:manpage:`named(8)`, :manpage:`rndc(8)`, BIND 9 Administrator Reference Manual. +:iscman:`named(8) `, :iscman:`rndc(8) `, BIND 9 Administrator Reference Manual. diff --git a/bin/tools/mdig.rst b/bin/tools/mdig.rst index ec9487bbfd..a3e1c056bc 100644 --- a/bin/tools/mdig.rst +++ b/bin/tools/mdig.rst @@ -373,4 +373,4 @@ The local query options are: See Also ~~~~~~~~ -:manpage:`dig(1)`, :rfc:`1035`. +:iscman:`dig(1) `, :rfc:`1035`. diff --git a/bin/tools/named-journalprint.rst b/bin/tools/named-journalprint.rst index 73cd69a233..9d56801864 100644 --- a/bin/tools/named-journalprint.rst +++ b/bin/tools/named-journalprint.rst @@ -63,4 +63,4 @@ bug in that release.) Note that these options *must not* be used while See Also ~~~~~~~~ -:manpage:`named(8)`, :manpage:`nsupdate(1)`, BIND 9 Administrator Reference Manual. +:iscman:`named(8) `, :iscman:`nsupdate(1) `, BIND 9 Administrator Reference Manual. diff --git a/bin/tools/named-rrchecker.rst b/bin/tools/named-rrchecker.rst index 6b736c249c..28da236b72 100644 --- a/bin/tools/named-rrchecker.rst +++ b/bin/tools/named-rrchecker.rst @@ -59,4 +59,4 @@ Options See Also ~~~~~~~~ -:rfc:`1034`, :rfc:`1035`, :manpage:`named(8)`. +:rfc:`1034`, :rfc:`1035`, :iscman:`named(8) `. diff --git a/doc/man/named-checkzone.1in b/doc/man/named-checkzone.1in index 0cd75f13ed..4290c4760c 100644 --- a/doc/man/named-checkzone.1in +++ b/doc/man/named-checkzone.1in @@ -246,8 +246,8 @@ This is the name of the zone file. and 0 otherwise. .SH SEE ALSO .sp -\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-compilezone(8)\fP, -\fI\%RFC 1035\fP, BIND 9 Administrator Reference Manual. +\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-compilezone(8)\fP, \fI\%RFC 1035\fP, BIND 9 Administrator Reference +Manual. .SH AUTHOR Internet Systems Consortium .SH COPYRIGHT diff --git a/doc/man/named-compilezone.1in b/doc/man/named-compilezone.1in index 8ae678cf5c..16872ec748 100644 --- a/doc/man/named-compilezone.1in +++ b/doc/man/named-compilezone.1in @@ -248,8 +248,8 @@ This is the name of the zone file. and 0 otherwise. .SH SEE ALSO .sp -\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-checkzone(8)\fP, -\fI\%RFC 1035\fP, BIND 9 Administrator Reference Manual. +\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-checkzone(8)\fP, \fI:rfc:\(ga1035\fP, +BIND 9 Administrator Reference Manual. .SH AUTHOR Internet Systems Consortium .SH COPYRIGHT diff --git a/doc/man/rndc.8in b/doc/man/rndc.8in index f23f8f06a6..619840268c 100644 --- a/doc/man/rndc.8in +++ b/doc/man/rndc.8in @@ -35,8 +35,7 @@ rndc \- name server control utility \fBrndc\fP [\fB\-b\fP source\-address] [\fB\-c\fP config\-file] [\fB\-k\fP key\-file] [\fB\-s\fP server] [\fB\-p\fP port] [\fB\-q\fP] [\fB\-r\fP] [\fB\-V\fP] [\fB\-y\fP key_id] [[\fB\-4\fP] | [\fB\-6\fP]] {command} .SH DESCRIPTION .sp -\fBrndc\fP controls the operation of a name server; it supersedes the -\fBndc\fP utility. If \fBrndc\fP is +\fBrndc\fP controls the operation of a name server. If \fBrndc\fP is invoked with no command line options or arguments, it prints a short summary of the supported commands and the available options and their arguments. @@ -703,7 +702,7 @@ Several error messages could be clearer. .SH SEE ALSO .sp \fBrndc.conf(5)\fP, \fBrndc\-confgen(8)\fP, -\fBnamed(8)\fP, \fBnamed.conf(5)\fP, \fBndc(8)\fP, BIND 9 Administrator +\fBnamed(8)\fP, \fBnamed.conf(5)\fP, BIND 9 Administrator Reference Manual. .SH AUTHOR Internet Systems Consortium From ad5b0402c9de3177b7da012aefff6a9df5536b14 Mon Sep 17 00:00:00 2001 From: Tony Finch Date: Thu, 10 Mar 2022 16:52:12 +0000 Subject: [PATCH 11/11] Regenerate the named.conf manual with hyperlinks The named.conf grammar is exported to the manual via doc/misc/rst-options.pl which is the ultimate source for the non-grammar parts of the man page. --- bin/named/named.conf.rst | 8 ++++---- doc/man/named.conf.5in | 8 ++++---- doc/misc/rst-options.pl | 12 +++++++----- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/bin/named/named.conf.rst b/bin/named/named.conf.rst index 3ce51e38ad..6fc7d8175c 100644 --- a/bin/named/named.conf.rst +++ b/bin/named/named.conf.rst @@ -24,10 +24,10 @@ Synopsis Description ~~~~~~~~~~~ -: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: +:file:`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: C style: /\* \*/ diff --git a/doc/man/named.conf.5in b/doc/man/named.conf.5in index 539346834e..ec2c6b47f6 100644 --- a/doc/man/named.conf.5in +++ b/doc/man/named.conf.5in @@ -35,10 +35,10 @@ named.conf \- configuration file for **named** \fBnamed.conf\fP .SH DESCRIPTION .sp -\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: +\fBnamed.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: .sp C style: /* */ .INDENT 0.0 diff --git a/doc/misc/rst-options.pl b/doc/misc/rst-options.pl index 7526ea4f4c..79a934dbcc 100644 --- a/doc/misc/rst-options.pl +++ b/doc/misc/rst-options.pl @@ -43,6 +43,8 @@ END print <`, :iscman:`named-checkconf(8) `, :iscman:`rndc(8) `, :iscman:`rndc-confgen(8) `, :iscman:`tsig-keygen(8) `, BIND 9 Administrator Reference Manual. END