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`