upstream/bind9
1
0
Fork 0
mirror of https://github.com/isc-projects/bind9.git synced 2026-05-24 02:59:43 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Hyperlink program names to their manual pages

Browse source 
Use the new role :iscman: to replace all occurences or ``binary``
with :iscman:`binary`, creating a hyperlink to the manual page.

Generated using:
    find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs
    for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done

Additional hand-edits were done mainly around filter-aaaa and
filter-a which are program names and and option names at the
same time. Couple more edits was neede to fix .rst syntax broken by
automatic replacement.

(cherry picked from commit 53a5776025)
This commit is contained in:
Petr Špaček 2022-03-03 22:17:04 +01:00
parent 52a20d646d
commit 07044325eb
No known key found for this signature in database
GPG key ID: ABD587CDF06581AE
53 changed files with 592 additions and 592 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
bin/check/named-checkconf.rst
View file

@ -27,14 +27,14 @@ Description
~~~~~~~~~~~
:program:`named-checkconf` checks the syntax, but not the semantics, of a
``named`` configuration file. The file, along with all files included by it, is parsed and checked for syntax
:iscman:`named` configuration file. The file, along with all files included by it, is parsed and checked for syntax
errors. If no file is specified,
|named_conf| is read by default.
Note: files that ``named`` reads in separate parser contexts, such as
Note: files that :iscman:`named` reads in separate parser contexts, such as
``rndc.key`` and ``bind.keys``, are not automatically read by
:program:`named-checkconf`. Configuration errors in these files may cause
``named`` to fail to run, even if :program:`named-checkconf` was successful.
:iscman:`named` to fail to run, even if :program:`named-checkconf` was successful.
However, :program:`named-checkconf` can be run on these files explicitly.
Options
@ -46,7 +46,7 @@ Options
.. option:: -j
When loading a zonefile, this option instructs ``named`` to read the journal if it exists.
When loading a zonefile, this option instructs :iscman:`named` to read the journal if it exists.
.. option:: -l
@ -65,14 +65,14 @@ Options
.. option:: -p
This option prints out the ``named.conf`` and included files in canonical form if
This option prints out the :iscman:`named.conf` and included files in canonical form if
no errors were detected. See also the :option:`-x` option.
.. option:: -t directory
This option instructs ``named`` to chroot to ``directory``, so that ``include`` directives in the
This option instructs :iscman:`named` to chroot to ``directory``, so that ``include`` directives in the
configuration file are processed as if run by a similarly chrooted
``named``.
:iscman:`named`.
.. option:: -v
@ -82,14 +82,14 @@ Options
When printing the configuration files in canonical form, this option obscures
shared secrets by replacing them with strings of question marks
(``?``). This allows the contents of ``named.conf`` and related files
(``?``). This allows the contents of :iscman:`named.conf` and related files
to be shared - for example, when submitting bug reports -
without compromising private data. This option cannot be used without
:option:`-p`.
.. option:: -z
This option performs a test load of all zones of type ``primary`` found in ``named.conf``.
This option performs a test load of all zones of type ``primary`` found in :iscman:`named.conf`.
.. option:: filename

20
bin/check/named-checkzone.rst
View file

@ -29,7 +29,7 @@ Description
~~~~~~~~~~~
:program:`named-checkzone` checks the syntax and integrity of a zone file. It
performs the same checks as ``named`` does when loading a zone. This
performs the same checks as :iscman:`named` does when loading a zone. This
makes :program:`named-checkzone` useful for checking zone files before
configuring them into a name server.
@ -55,13 +55,13 @@ Options
.. option:: -j
When loading a zone file, this option tells ``named`` to read the journal if it exists. The journal
When loading a zone file, this option tells :iscman:`named` to read the journal if it exists. The journal
file name is assumed to be the zone file name with the
string ``.jnl`` appended.
.. option:: -J filename
When loading the zone file, this option tells ``named`` to read the journal from the given file, if
When loading the zone file, this option tells :iscman:`named` to read the journal from the given file, if
it exists. This implies :option:`-j`.
.. option:: -c class
@ -108,9 +108,9 @@ Options
Possible formats are ``text`` (the default), which is the standard
textual representation of the zone, and ``raw`` and ``raw=N``, which
store the zone in a binary format for rapid loading by ``named``.
store the zone in a binary format for rapid loading by :iscman:`named`.
``raw=N`` specifies the format version of the raw zone file: if ``N`` is
0, the raw file can be read by any version of ``named``; if N is 1, the
0, the raw file can be read by any version of :iscman:`named`; if N is 1, the
file can only be read by release 9.9.0 or higher. The default is 1.
.. option:: -k mode
@ -122,7 +122,7 @@ Options
This option sets a maximum permissible TTL for the input file. Any record with a
TTL higher than this value causes the zone to be rejected. This
is similar to using the ``max-zone-ttl`` option in ``named.conf``.
is similar to using the ``max-zone-ttl`` option in :iscman:`named.conf`.
.. option:: -L serial
@ -174,9 +174,9 @@ Options
.. option:: -t directory
This option tells ``named`` to chroot to ``directory``, so that ``include`` directives in the
This option tells :iscman:`named` to chroot to ``directory``, so that ``include`` directives in the
configuration file are processed as if run by a similarly chrooted
``named``.
:iscman:`named`.
.. option:: -T mode
@ -186,9 +186,9 @@ Options
.. option:: -w directory
This option instructs ``named`` to chdir to ``directory``, so that relative filenames in master file
This option instructs :iscman:`named` to chdir to ``directory``, so that relative filenames in master file
``$INCLUDE`` directives work. This is similar to the directory clause in
``named.conf``.
:iscman:`named.conf`.
.. option:: -D

26
bin/check/named-compilezone.rst
View file

@ -31,9 +31,9 @@ Description
:program:`named-compilezone` checks the syntax and integrity of a zone file,
and dumps the zone contents to a specified file in a specified format.
It applies strict check levels by default, since the
dump output is used as an actual zone file loaded by ``named``.
dump output is used as an actual zone file loaded by :iscman:`named`.
When manually specified otherwise, the check levels must at least be as
strict as those specified in the ``named`` configuration file.
strict as those specified in the :iscman:`named` configuration file.
Options
~~~~~~~
@ -53,17 +53,17 @@ Options
.. option:: -v
This option prints the version of the ``named-checkzone`` program and exits.
This option prints the version of the :iscman:`named-checkzone` program and exits.
.. option:: -j
When loading a zone file, this option tells ``named`` to read the journal if it exists. The journal
When loading a zone file, this option tells :iscman:`named` to read the journal if it exists. The journal
file name is assumed to be the zone file name with the
string ``.jnl`` appended.
.. option:: -J filename
When loading the zone file, this option tells ``named`` to read the journal from the given file, if
When loading the zone file, this option tells :iscman:`named` to read the journal from the given file, if
it exists. This implies :option:`-j`.
.. option:: -c class
@ -105,14 +105,14 @@ Options
.. option:: -F format
This option specifies the format of the output file specified. For
``named-checkzone``, this does not have any effect unless it dumps
:iscman:`named-checkzone`, this does not have any effect unless it dumps
the zone contents.
Possible formats are ``text`` (the default), which is the standard
textual representation of the zone, and ``raw`` and ``raw=N``, which
store the zone in a binary format for rapid loading by ``named``.
store the zone in a binary format for rapid loading by :iscman:`named`.
``raw=N`` specifies the format version of the raw zone file: if ``N`` is
0, the raw file can be read by any version of ``named``; if N is 1, the
0, the raw file can be read by any version of :iscman:`named`; if N is 1, the
file can only be read by release 9.9.0 or higher. The default is 1.
.. option:: -k mode
@ -124,7 +124,7 @@ Options
This option sets a maximum permissible TTL for the input file. Any record with a
TTL higher than this value causes the zone to be rejected. This
is similar to using the ``max-zone-ttl`` option in ``named.conf``.
is similar to using the ``max-zone-ttl`` option in :iscman:`named.conf`.
.. option:: -L serial
@ -175,9 +175,9 @@ Options
.. option:: -t directory
This option tells ``named`` to chroot to ``directory``, so that ``include`` directives in the
This option tells :iscman:`named` to chroot to ``directory``, so that ``include`` directives in the
configuration file are processed as if run by a similarly chrooted
``named``.
:iscman:`named`.
.. option:: -T mode
@ -187,9 +187,9 @@ Options
.. option:: -w directory
This option instructs ``named`` to chdir to ``directory``, so that relative filenames in master file
This option instructs :iscman:`named` to chdir to ``directory``, so that relative filenames in master file
``$INCLUDE`` directives work. This is similar to the directory clause in
``named.conf``.
:iscman:`named.conf`.
.. option:: -D

16
bin/confgen/ddns-confgen.rst
View file

@ -29,19 +29,19 @@ Description
:program:`ddns-confgen` is an utility that generates keys for use in TSIG signing.
The resulting keys can be used, for example, to secure dynamic DNS updates
to a zone, or for the ``rndc`` command channel.
to a zone, or for the :iscman:`rndc` command channel.
The key name can specified using :option:`-k` parameter and defaults to ``ddns-key``.
The generated key is accompanied by configuration text and instructions that
can be used with ``nsupdate`` and ``named`` when setting up dynamic DNS,
can be used with :iscman:`nsupdate` and :iscman:`named` when setting up dynamic DNS,
including an example ``update-policy`` statement.
(This usage is similar to the ``rndc-confgen`` command for setting up
(This usage is similar to the :iscman:`rndc-confgen` command for setting up
command-channel security.)
Note that ``named`` itself can configure a local DDNS key for use with
Note that :iscman:`named` itself can configure a local DDNS key for use with
:option:`nsupdate -l`; it does this when a zone is configured with
``update-policy local;``. :program:`ddns-confgen` is only needed when a more
elaborate configuration is required: for instance, if ``nsupdate`` is to
elaborate configuration is required: for instance, if :iscman:`nsupdate` is to
be used from a remote system.
Options
@ -71,12 +71,12 @@ Options
This option enables quiet mode, which prints only the key, with no
explanatory text or usage examples. This is essentially identical to
``tsig-keygen``.
:iscman:`tsig-keygen`.
.. option:: -s name
This option generates a configuration example to allow dynamic updates
of a single hostname. The example ``named.conf`` text shows how to set
of a single hostname. The example :iscman:`named.conf` text shows how to set
an update policy for the specified name using the "name" nametype. The
default key name is ``ddns-key.name``. Note that the "self" nametype
cannot be used, since the name to be updated may differ from the key
@ -85,7 +85,7 @@ Options
.. option:: -z zone
This option generates a configuration example to allow
dynamic updates of a zone. The example ``named.conf`` text shows how
dynamic updates of a zone. The example :iscman:`named.conf` text shows how
to set an update policy for the specified zone using the "zonesub"
nametype, allowing updates to all subdomain names within that zone.
This option cannot be used with the :option:`-s` option.

36
bin/confgen/rndc-confgen.rst
View file

@ -26,11 +26,11 @@ Synopsis
Description
~~~~~~~~~~~
:program:`rndc-confgen` generates configuration files for ``rndc``. It can be
used as a convenient alternative to writing the ``rndc.conf`` file and
the corresponding ``controls`` and ``key`` statements in ``named.conf``
:program:`rndc-confgen` generates configuration files for :iscman:`rndc`. It can be
used as a convenient alternative to writing the :iscman:`rndc.conf` file and
the corresponding ``controls`` and ``key`` statements in :iscman:`named.conf`
by hand. Alternatively, it can be run with the :option:`-a` option to set up a
``rndc.key`` file and avoid the need for a ``rndc.conf`` file and a
``rndc.key`` file and avoid the need for a :iscman:`rndc.conf` file and a
``controls`` statement altogether.
Options
@ -38,16 +38,16 @@ Options
.. option:: -a
This option sets automatic ``rndc`` configuration, which creates a file
|rndc_key| that is read by both ``rndc`` and ``named`` on startup.
This option sets automatic :iscman:`rndc` configuration, which creates a file
|rndc_key| that is read by both :iscman:`rndc` and :iscman:`named` on startup.
The ``rndc.key`` file defines a default command channel and
authentication key allowing ``rndc`` to communicate with ``named`` on
authentication key allowing :iscman:`rndc` to communicate with :iscman:`named` on
the local host with no further configuration.
If a more elaborate configuration than that generated by
:option:`rndc-confgen -a` is required, for example if rndc is to be used
remotely, run :program:`rndc-confgen` without the :option:`-a` option
and set up ``rndc.conf`` and ``named.conf`` as directed.
and set up :iscman:`rndc.conf` and :iscman:`named.conf` as directed.
.. option:: -A algorithm
@ -72,13 +72,13 @@ Options
.. option:: -k keyname
This option specifies the key name of the ``rndc`` authentication key. This must be a
This option specifies the key name of the :iscman:`rndc` authentication key. This must be a
valid domain name. The default is ``rndc-key``.
.. option:: -p port
This option specifies the command channel port where ``named`` listens for
connections from ``rndc``. The default is 953.
This option specifies the command channel port where :iscman:`named` listens for
connections from :iscman:`rndc`. The default is 953.
.. option:: -q
@ -86,16 +86,16 @@ Options
.. option:: -s address
This option specifies the IP address where ``named`` listens for command-channel
connections from ``rndc``. The default is the loopback address
This option specifies the IP address where :iscman:`named` listens for command-channel
connections from :iscman:`rndc`. The default is the loopback address
127.0.0.1.
.. option:: -t chrootdir
This option is used with the :option:`-a` option to specify a directory where ``named``
This option is used with the :option:`-a` option to specify a directory where :iscman:`named`
runs chrooted. An additional copy of the ``rndc.key`` is
written relative to this directory, so that it is found by the
chrooted ``named``.
chrooted :iscman:`named`.
.. option:: -u user
@ -106,12 +106,12 @@ Options
Examples
~~~~~~~~
To allow ``rndc`` to be used with no manual configuration, run:
To allow :iscman:`rndc` to be used with no manual configuration, run:
``rndc-confgen -a``
To print a sample ``rndc.conf`` file and the corresponding ``controls`` and
``key`` statements to be manually inserted into ``named.conf``, run:
To print a sample :iscman:`rndc.conf` file and the corresponding ``controls`` and
``key`` statements to be manually inserted into :iscman:`named.conf`, run:
:program:`rndc-confgen`

2
bin/confgen/tsig-keygen.rst
View file

@ -29,7 +29,7 @@ Description
:program:`tsig-keygen` is an utility that generates keys for use in TSIG signing.
The resulting keys can be used, for example, to secure dynamic DNS updates
to a zone, or for the ``rndc`` command channel.
to a zone, or for the :iscman:`rndc` command channel.
A domain name can be specified on the command line to be used as the name
of the generated key. If no name is specified, the default is ``tsig-key``.

6
bin/delv/delv.rst
View file

@ -33,7 +33,7 @@ Description
~~~~~~~~~~~
:program:`delv` is a tool for sending DNS queries and validating the results,
using the same internal resolver and validator logic as ``named``.
using the same internal resolver and validator logic as :iscman:`named`.
:program:`delv` sends to a specified name server all queries needed to
fetch and validate the requested data; this includes the original
@ -113,7 +113,7 @@ Options
``initial-key``, and ``static-key`` identically. That is, for a managed key,
it is the *initial* key that is trusted; :rfc:`5011` key management is not
supported. :program:`delv` does not consult the managed-keys database maintained by
``named``, which means that if either of the keys in |bind_keys| is
:iscman:`named`, which means that if either of the keys in |bind_keys| is
revoked and rolled over, |bind_keys| must be updated to
use DNSSEC validation in :program:`delv`.
@ -322,7 +322,7 @@ assign values to options like the timeout interval. They have the form
.. option:: +[no]dnssec
This option indicates whether to display RRSIG records in the :program:`delv` output.
The default is to do so. Note that (unlike in ``dig``) this does
The default is to do so. Note that (unlike in :iscman:`dig`) this does
*not* control whether to request DNSSEC records or to
validate them. DNSSEC records are always requested, and validation
always occurs unless suppressed by the use of :option:`-i` or

14
bin/dig/dig.rst
View file

@ -132,12 +132,12 @@ Options
.. option:: -k keyfile
This option tells ``named`` to sign queries using TSIG using a key read from the given file. Key
files can be generated using ``tsig-keygen``. When using TSIG
This option tells :iscman:`named` to sign queries using TSIG using a key read from the given file. Key
files can be generated using :iscman:`tsig-keygen`. When using TSIG
authentication with :program:`dig`, the name server that is queried needs to
know the key and algorithm that is being used. In BIND, this is done
by providing appropriate ``key`` and ``server`` statements in
``named.conf``.
:iscman:`named.conf`.
.. option:: -m
@ -381,7 +381,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
.. option:: +[no]fail
This option indicates that ``named`` should try [or not try] the next server if a SERVFAIL is received. The default is
This option indicates that :iscman:`named` should try [or not try] the next server if a SERVFAIL is received. The default is
to not try the next server, which is the reverse of normal stub
resolver behavior.
@ -582,7 +582,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
.. option:: +[no]sigchase
This feature is now obsolete and has been removed; use ``delv``
This feature is now obsolete and has been removed; use :iscman:`delv`
instead.
.. option:: +split=W
@ -635,7 +635,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
.. option:: +[no]topdown
This feature is related to ``dig +sigchase``, which is obsolete and
has been removed. Use ``delv`` instead.
has been removed. Use :iscman:`delv` instead.
.. option:: +[no]trace
@ -661,7 +661,7 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
.. option:: +trusted-key=####
This option formerly specified trusted keys for use with ``dig +sigchase``. This
feature is now obsolete and has been removed; use ``delv`` instead.
feature is now obsolete and has been removed; use :iscman:`delv` instead.
.. option:: +[no]ttlid

8
bin/dig/host.rst
View file

@ -66,7 +66,7 @@ Options
.. option:: -C
This option indicates that ``named`` should check consistency, meaning that :program:`host` queries the SOA records for zone
This option indicates that :iscman:`named` should check consistency, meaning that :program:`host` queries the SOA records for zone
``name`` from all the listed authoritative name servers for that
zone. The list of name servers is defined by the NS records that are
found for the zone.
@ -77,7 +77,7 @@ Options
.. option:: -l
This option tells ``named`` to list the zone, meaning the :program:`host` command performs a zone transfer of zone
This option tells :iscman:`named` to list the zone, meaning the :program:`host` command performs a zone transfer of zone
``name`` and prints out the NS, PTR, and address records (A/AAAA).
Together, the :option:`-l` :option:`-a` options print all records in the zone.
@ -112,7 +112,7 @@ Options
.. option:: -s
This option tells ``named`` *not* to send the query to the next nameserver if any server responds
This option tells :iscman:`named` *not* to send the query to the next nameserver if any server responds
with a SERVFAIL response, which is the reverse of normal stub
resolver behavior.
@ -162,7 +162,7 @@ Options
.. option:: -W wait
This options sets the length of the wait timeout, indicating that ``named`` should wait for up to ``wait`` seconds for a reply. If ``wait`` is
This options sets the length of the wait timeout, indicating that :iscman:`named` should wait for up to ``wait`` seconds for a reply. If ``wait`` is
less than 1, the wait interval is set to 1 second.
By default, :program:`host` waits for 5 seconds for UDP responses and 10

6
bin/dig/nslookup.rst
View file

@ -63,9 +63,9 @@ Interactive Commands
~~~~~~~~~~~~~~~~~~~~
``host [server]``
This command looks up information for ``host`` using the current default server or
using ``server``, if specified. If ``host`` is an Internet address and the
query type is A or PTR, the name of the host is returned. If ``host`` is
This command looks up information for :iscman:`host` using the current default server or
using ``server``, if specified. If :iscman:`host` is an Internet address and the
query type is A or PTR, the name of the host is returned. If :iscman:`host` is
a name and does not have a trailing period (``.``), the search list is used
to qualify the name.

18
bin/dnssec/dnssec-cds.rst
View file

@ -39,7 +39,7 @@ file containing the child's CDS and/or CDNSKEY records, plus RRSIG and
DNSKEY records so that they can be authenticated. The :option:`-d path <-d>` option
specifies the location of a file containing the current DS records. For
example, this could be a ``dsset-`` file generated by
``dnssec-signzone``, or the output of ``dnssec-dsfromkey``, or the
:iscman:`dnssec-signzone`, or the output of :iscman:`dnssec-dsfromkey`, or the
output of a previous run of :program:`dnssec-cds`.
The :program:`dnssec-cds` command uses special DNSSEC validation logic
@ -67,9 +67,9 @@ specify that the child zone wants to be insecure.
Be careful not to delete the DS records when :program:`dnssec-cds` fails!
Alternatively, :option`dnssec-cds -u` writes an ``nsupdate`` script to the
Alternatively, :option`dnssec-cds -u` writes an :iscman:`nsupdate` script to the
standard output. The :option:`-u` and :option:`-i` options can be used together to
maintain a ``dsset-`` file as well as emit an ``nsupdate`` script.
maintain a ``dsset-`` file as well as emit an :iscman:`nsupdate` script.
Options
~~~~~~~
@ -154,13 +154,13 @@ Options
.. option:: -u
This option writes an ``nsupdate`` script to the standard output, instead of
This option writes an :iscman:`nsupdate` script to the standard output, instead of
printing the new DS reords. The output is empty if no change is
needed.
Note: The TTL of new records needs to be specified: it can be done in the
original ``dsset-`` file, with the :option:`-T` option, or using the
``nsupdate`` ``ttl`` command.
:iscman:`nsupdate` ``ttl`` command.
.. option:: -V
@ -186,11 +186,11 @@ changed.
Examples
~~~~~~~~
Before running ``dnssec-signzone``, ensure that the delegations
Before running :iscman:`dnssec-signzone`, ensure that the delegations
are up-to-date by running :program:`dnssec-cds` on every ``dsset-`` file.
To fetch the child records required by :program:`dnssec-cds`, invoke
``dig`` as in the script below. It is acceptable if the ``dig`` fails, since
:iscman:`dig` as in the script below. It is acceptable if the :iscman:`dig` fails, since
:program:`dnssec-cds` performs all the necessary checking.
::
@ -202,8 +202,8 @@ To fetch the child records required by :program:`dnssec-cds`, invoke
dnssec-cds -i -f /dev/stdin -d $f $d
done
When the parent zone is automatically signed by ``named``,
:program:`dnssec-cds` can be used with ``nsupdate`` to maintain a delegation as follows.
When the parent zone is automatically signed by :iscman:`named`,
:program:`dnssec-cds` can be used with :iscman:`nsupdate` to maintain a delegation as follows.
The ``dsset-`` file allows the script to avoid having to fetch and
validate the parent DS records, and it maintains the replay attack
protection time.

8
bin/dnssec/dnssec-dsfromkey.rst
View file

@ -42,13 +42,13 @@ included.
The input keys can be specified in a number of ways:
By default, :program:`dnssec-dsfromkey` reads a key file named in the format
``Knnnn.+aaa+iiiii.key``, as generated by ``dnssec-keygen``.
``Knnnn.+aaa+iiiii.key``, as generated by :iscman:`dnssec-keygen`.
With the :option:`-f file <-f>` option, :program:`dnssec-dsfromkey` reads keys from a zone
file or partial zone file (which can contain just the DNSKEY records).
With the :option:`-s` option, :program:`dnssec-dsfromkey` reads a ``keyset-`` file,
as generated by ``dnssec-keygen`` :option:`-C`.
as generated by :iscman:`dnssec-keygen` :option:`-C`.
Options
~~~~~~~
@ -94,7 +94,7 @@ Options
omitted.
If ``file`` is ``-``, then the zone data is read from the standard
input. This makes it possible to use the output of the ``dig``
input. This makes it possible to use the output of the :iscman:`dig`
command as input, as in:
``dig dnskey example.com | dnssec-dsfromkey -f - example.com``
@ -141,7 +141,7 @@ Files
The keyfile can be designated by the key identification
``Knnnn.+aaa+iiiii`` or the full file name ``Knnnn.+aaa+iiiii.key``, as
generated by ``dnssec-keygen``.
generated by :iscman:`dnssec-keygen`.
The keyset file name is built from the ``directory``, the string
``keyset-``, and the ``dnsname``.

2
bin/dnssec/dnssec-importkey.rst
View file

@ -116,7 +116,7 @@ Files
A keyfile can be designed by the key identification ``Knnnn.+aaa+iiiii``
or the full file name ``Knnnn.+aaa+iiiii.key``, as generated by
``dnssec-keygen``.
:iscman:`dnssec-keygen`.
See Also
~~~~~~~~

2
bin/dnssec/dnssec-keyfromlabel.rst
View file

@ -29,7 +29,7 @@ Description
:program:`dnssec-keyfromlabel` generates a pair of key files that reference a
key object stored in a cryptographic hardware service module (HSM). The
private key file can be used for DNSSEC signing of zone data as if it
were a conventional signing key created by ``dnssec-keygen``, but the
were a conventional signing key created by :iscman:`dnssec-keygen`, but the
key material is stored within the HSM and the actual signing takes
place there.

4
bin/dnssec/dnssec-keygen.rst
View file

@ -63,7 +63,7 @@ Options
In prior releases, HMAC algorithms could be generated for use as TSIG
keys, but that feature was removed in BIND 9.13.0. Use
``tsig-keygen`` to generate TSIG keys.
:iscman:`tsig-keygen` to generate TSIG keys.
.. option:: -b keysize
@ -310,7 +310,7 @@ string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and
``Knnnn.+aaa+iiiii.private`` contains the private key.
The ``.key`` file contains a DNSKEY or KEY record. When a zone is being
signed by ``named`` or :option:`dnssec-signzone -S`, DNSKEY records are
signed by :iscman:`named` or :option:`dnssec-signzone -S`, DNSKEY records are
included automatically. In other cases, the ``.key`` file can be
inserted into a zone file manually or with an ``$INCLUDE`` statement.

2
bin/dnssec/dnssec-settime.rst
View file

@ -29,7 +29,7 @@ Description
:program:`dnssec-settime` reads a DNSSEC private key file and sets the key
timing metadata as specified by the :option:`-P`, :option:`-A`, :option:`-R`,
:option:`-I`, and :option:`-D` options. The metadata can then be used by
``dnssec-signzone`` or other signing software to determine when a key is
:iscman:`dnssec-signzone` or other signing software to determine when a key is
to be published, whether it should be used for signing a zone, etc.
If none of these options is set on the command line,

14
bin/dnssec/dnssec-signzone.rst
View file

@ -95,7 +95,7 @@ Options
possible time before signatures that have been retrieved by resolvers
expire from resolver caches. Zones that are signed with this
option should be configured to use a matching ``max-zone-ttl`` in
``named.conf``. (Note: This option is incompatible with :option:`-D`,
:iscman:`named.conf`. (Note: This option is incompatible with :option:`-D`,
because it modifies non-DNSSEC data in the output zone.)
.. option:: -s start-time
@ -236,8 +236,8 @@ Options
textual representation of the zone; ``full``, which is text output in a
format suitable for processing by external scripts; and ``raw`` and
``raw=N``, which store the zone in binary formats for rapid loading by
``named``. ``raw=N`` specifies the format version of the raw zone file:
if N is 0, the raw file can be read by any version of ``named``; if N is
:iscman:`named`. ``raw=N`` specifies the format version of the raw zone file:
if N is 0, the raw file can be read by any version of :iscman:`named`; if N is
1, the file can be read by release 9.9.0 or higher. The default is 1.
.. option:: -P
@ -347,14 +347,14 @@ Options
This option indicates that BIND 9 should only sign the DNSKEY, CDNSKEY, and CDS RRsets with key-signing keys,
and should omit signatures from zone-signing keys. (This is similar to the
``dnssec-dnskey-kskonly yes;`` zone option in ``named``.)
``dnssec-dnskey-kskonly yes;`` zone option in :iscman:`named`.)
.. option:: -z
This option indicates that BIND 9 should ignore the KSK flag on keys when determining what to sign. This causes
KSK-flagged keys to sign all records, not just the DNSKEY RRset.
(This is similar to the ``update-check-ksk no;`` zone option in
``named``.)
:iscman:`named`.)
.. option:: -3 salt
@ -393,7 +393,7 @@ Example
~~~~~~~
The following command signs the ``example.com`` zone with the
ECDSAP256SHA256 key generated by ``dnssec-keygen``
ECDSAP256SHA256 key generated by :iscman:`dnssec-keygen`
(Kexample.com.+013+17247). Because the :option:`-S` option is not being used,
the zone's keys must be in the master file (``db.example.com``). This
invocation looks for ``dsset`` files in the current directory, so that
@ -408,7 +408,7 @@ DS records can be imported from them (:option:`-g`).
In the above example, :program:`dnssec-signzone` creates the file
``db.example.com.signed``. This file should be referenced in a zone
statement in the ``named.conf`` file.
statement in the :iscman:`named.conf` file.
This example re-signs a previously signed zone with default parameters.
The private keys are assumed to be in the current directory.

2
bin/named/named.conf.rst
View file

@ -24,7 +24,7 @@ Synopsis
Description
~~~~~~~~~~~
``named.conf`` is the configuration file for ``named``. Statements are
:iscman:`named.conf` is the configuration file for :iscman:`named`. Statements are
enclosed in braces and terminated with a semi-colon. Clauses in the
statements are also semi-colon terminated. The usual comment styles are
supported:

4
bin/named/named.rst
View file

@ -198,13 +198,13 @@ Options
This option acquires a lock on the specified file at runtime; this helps to
prevent duplicate :program:`named` instances from running simultaneously.
Use of this option overrides the ``lock-file`` option in
``named.conf``. If set to ``none``, the lock file check is disabled.
:iscman:`named.conf`. If set to ``none``, the lock file check is disabled.
Signals
~~~~~~~
In routine operation, signals should not be used to control the
nameserver; ``rndc`` should be used instead.
nameserver; :iscman:`rndc` should be used instead.
SIGHUP
This signal forces a reload of the server.

14
bin/nsupdate/nsupdate.rst
View file

@ -49,7 +49,7 @@ and the name server. For instance, suitable ``key`` and ``server``
statements are added to |named_conf| so that the name server
can associate the appropriate secret key and algorithm with the IP
address of the client application that is using TSIG
authentication. ``ddns-confgen`` can generate suitable
authentication. :iscman:`ddns-confgen` can generate suitable
configuration fragments. :program:`nsupdate` uses the :option:`-y` or :option:`-k` options
to provide the TSIG shared secret; these options are mutually exclusive.
@ -95,12 +95,12 @@ Options
.. option:: -k keyfile
This option indicates the file containing the TSIG authentication key. Keyfiles may be in
two formats: a single file containing a ``named.conf``-format ``key``
statement, which may be generated automatically by ``ddns-confgen``;
two formats: a single file containing a :iscman:`named.conf`-format ``key``
statement, which may be generated automatically by :iscman:`ddns-confgen`;
or a pair of files whose names are of the format
``K{name}.+157.+{random}.key`` and
``K{name}.+157.+{random}.private``, which can be generated by
``dnssec-keygen``. The :option:`-k` option can also be used to specify a SIG(0)
:iscman:`dnssec-keygen`. The :option:`-k` option can also be used to specify a SIG(0)
key used to authenticate Dynamic DNS update requests. In this case,
the key specified is not an HMAC-MD5 key.
@ -110,7 +110,7 @@ Options
(disabling the ``server`` so that the server address cannot be
overridden). Connections to the local server use a TSIG key
found in |session_key|, which is automatically
generated by ``named`` if any local ``primary`` zone has set
generated by :iscman:`named` if any local ``primary`` zone has set
``update-policy`` to ``local``. The location of this key file can be
overridden with the :option:`-k` option.
@ -366,10 +366,10 @@ Files
Sets the default TSIG key for use in local-only mode
``K{name}.+157.+{random}.key``
Base-64 encoding of the HMAC-MD5 key created by ``dnssec-keygen``.
Base-64 encoding of the HMAC-MD5 key created by :iscman:`dnssec-keygen`.
``K{name}.+157.+{random}.private``
Base-64 encoding of the HMAC-MD5 key created by ``dnssec-keygen``.
Base-64 encoding of the HMAC-MD5 key created by :iscman:`dnssec-keygen`.
See Also
~~~~~~~~

4
bin/plugins/filter-a.rst
View file

@ -25,8 +25,8 @@ Synopsis
Description
~~~~~~~~~~~
``filter-a.so`` is a query plugin module for ``named``, enabling
``named`` to omit some IPv4 addresses when responding to clients.
:program:`filter-a.so` is a query plugin module for :iscman:`named`, enabling
:iscman:`named` to omit some IPv4 addresses when responding to clients.
For example:

8
bin/plugins/filter-aaaa.rst
View file

@ -25,13 +25,13 @@ Synopsis
Description
~~~~~~~~~~~
``filter-aaaa.so`` is a query plugin module for ``named``, enabling
``named`` to omit some IPv6 addresses when responding to clients.
:program:`filter-aaaa.so` is a query plugin module for :iscman:`named`, enabling
:iscman:`named` to omit some IPv6 addresses when responding to clients.
Until BIND 9.12, this feature was implemented natively in ``named`` and
Until BIND 9.12, this feature was implemented natively in :iscman:`named` and
enabled with the ``filter-aaaa`` ACL and the ``filter-aaaa-on-v4`` and
``filter-aaaa-on-v6`` options. These options are now deprecated in
``named.conf`` but can be passed as parameters to the
:iscman:`named.conf` but can be passed as parameters to the
``filter-aaaa.so`` plugin, for example:
::

24
bin/rndc/rndc.conf.rst
View file

@ -26,9 +26,9 @@ Synopsis
Description
~~~~~~~~~~~
:program:`rndc.conf` is the configuration file for ``rndc``, the BIND 9 name
:program:`rndc.conf` is the configuration file for :iscman:`rndc`, the BIND 9 name
server control utility. This file has a similar structure and syntax to
``named.conf``. Statements are enclosed in braces and terminated with a
:iscman:`named.conf`. Statements are enclosed in braces and terminated with a
semi-colon. Clauses in the statements are also semi-colon terminated.
The usual comment styles are supported:
@ -38,13 +38,13 @@ C++ style: // to end of line
Unix style: # to end of line
:program:`rndc.conf` is much simpler than ``named.conf``. The file uses three
:program:`rndc.conf` is much simpler than :iscman:`named.conf`. The file uses three
statements: an options statement, a server statement, and a key
statement.
The ``options`` statement contains five clauses. The ``default-server``
clause is followed by the name or address of a name server. This host
is used when no name server is given as an argument to ``rndc``.
is used when no name server is given as an argument to :iscman:`rndc`.
The ``default-key`` clause is followed by the name of a key, which is
identified by a ``key`` statement. If no ``keyid`` is provided on the
rndc command line, and no ``key`` clause is found in a matching
@ -69,14 +69,14 @@ IPv4 and IPv6 source address, respectively.
The ``key`` statement begins with an identifying string, the name of the
key. The statement has two clauses. ``algorithm`` identifies the
authentication algorithm for ``rndc`` to use; currently only HMAC-MD5
authentication algorithm for :iscman:`rndc` to use; currently only HMAC-MD5
(for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (default),
HMAC-SHA384, and HMAC-SHA512 are supported. This is followed by a secret
clause which contains the base-64 encoding of the algorithm's
authentication key. The base-64 string is enclosed in double quotes.
There are two common ways to generate the base-64 string for the secret.
The BIND 9 program ``rndc-confgen`` can be used to generate a random
The BIND 9 program :iscman:`rndc-confgen` can be used to generate a random
key, or the ``mmencode`` program, also known as ``mimencode``, can be
used to generate a base-64 string from known input. ``mmencode`` does
not ship with BIND 9 but is available on many systems. See the Example
@ -120,7 +120,7 @@ Example
};
In the above example, ``rndc`` by default uses the server at
In the above example, :iscman:`rndc` by default uses the server at
localhost (127.0.0.1) and the key called "samplekey". Commands to the
localhost server use the "samplekey" key, which must also be defined
in the server's configuration file with the same name and secret. The
@ -128,16 +128,16 @@ key statement indicates that "samplekey" uses the HMAC-SHA256 algorithm
and its secret clause contains the base-64 encoding of the HMAC-SHA256
secret enclosed in double quotes.
If :option:`rndc -s testserver <rndc -s>` is used, then ``rndc`` connects to the server
If :option:`rndc -s testserver <rndc -s>` is used, then :iscman:`rndc` connects to the server
on localhost port 5353 using the key "testkey".
To generate a random secret with ``rndc-confgen``:
To generate a random secret with :iscman:`rndc-confgen`:
``rndc-confgen``
:iscman:`rndc-confgen`
A complete :program:`rndc.conf` file, including the randomly generated key,
is written to the standard output. Commented-out ``key`` and
``controls`` statements for ``named.conf`` are also printed.
``controls`` statements for :iscman:`named.conf` are also printed.
To generate a base-64 secret with ``mmencode``:
@ -148,7 +148,7 @@ Name Server Configuration
The name server must be configured to accept rndc connections and to
recognize the key specified in the :program:`rndc.conf` file, using the
controls statement in ``named.conf``. See the sections on the
controls statement in :iscman:`named.conf`. See the sections on the
``controls`` statement in the BIND 9 Administrator Reference Manual for
details.

64
bin/rndc/rndc.rst
View file

@ -34,7 +34,7 @@ arguments.
:program:`rndc` communicates with the name server over a TCP connection,
sending commands authenticated with digital signatures. In the current
versions of :program:`rndc` and ``named``, the only supported authentication
versions of :program:`rndc` and :iscman:`named`, the only supported authentication
algorithms are HMAC-MD5 (for compatibility), HMAC-SHA1, HMAC-SHA224,
HMAC-SHA256 (default), HMAC-SHA384, and HMAC-SHA512. They use a shared
secret on each end of the connection, which provides TSIG-style
@ -94,7 +94,7 @@ Options
.. option:: -r
This option instructs :program:`rndc` to print the result code returned by ``named``
This option instructs :program:`rndc` to print the result code returned by :iscman:`named`
after executing the requested command (e.g., ISC_R_SUCCESS,
ISC_R_FAILURE, etc.).
@ -105,7 +105,7 @@ Options
.. option:: -y key_id
This option indicates use of the key ``key_id`` from the configuration file. For control message validation to succeed, ``key_id`` must be known
by ``named`` with the same algorithm and secret string. If no ``key_id`` is specified,
by :iscman:`named` with the same algorithm and secret string. If no ``key_id`` is specified,
:program:`rndc` first looks for a key clause in the server statement of
the server being used, or if no server statement is present for that
host, then in the default-key clause of the options statement. Note that
@ -126,14 +126,14 @@ Currently supported commands are:
This command adds a zone while the server is running. This command requires the
``allow-new-zones`` option to be set to ``yes``. The configuration
string specified on the command line is the zone configuration text
that would ordinarily be placed in ``named.conf``.
that would ordinarily be placed in :iscman:`named.conf`.
The configuration is saved in a file called ``viewname.nzf`` (or, if
``named`` is compiled with liblmdb, an LMDB database file called
:iscman:`named` is compiled with liblmdb, an LMDB database file called
``viewname.nzd``). ``viewname`` is the name of the view, unless the view
name contains characters that are incompatible with use as a file
name, in which case a cryptographic hash of the view name is used
instead. When ``named`` is restarted, the file is loaded into
instead. When :iscman:`named` is restarted, the file is loaded into
the view configuration so that zones that were added can persist
after a restart.
@ -159,10 +159,10 @@ Currently supported commands are:
If the zone was originally added via ``rndc addzone``, then it is
removed permanently. However, if it was originally configured in
``named.conf``, then that original configuration remains in place;
:iscman:`named.conf`, then that original configuration remains in place;
when the server is restarted or reconfigured, the zone is
recreated. To remove it permanently, it must also be removed from
``named.conf``.
:iscman:`named.conf`.
See also :option:`rndc addzone` and :option:`rndc modzone`.
@ -177,7 +177,7 @@ Currently supported commands are:
``rndc dnssec -rollover`` allows you to schedule key rollover for a
specific key (overriding the original key lifetime).
``rndc dnssec -checkds`` will let ``named`` know that the DS for the given
``rndc dnssec -checkds`` will let :iscman:`named` know that the DS for the given
key has been seen published into or withdrawn from the parent. This is
required in order to complete a KSK rollover. If the ``-key id`` argument
is specified, look for the key with the given identifier, otherwise if there
@ -189,7 +189,7 @@ Currently supported commands are:
.. option:: dnstap (-reopen | -roll [number])
This command closes and re-opens DNSTAP output files. ``rndc dnstap -reopen`` allows
the output file to be renamed externally, so that ``named`` can
the output file to be renamed externally, so that :iscman:`named` can
truncate and re-open it. ``rndc dnstap -roll`` causes the output file
to be rolled automatically, similar to log files. The most recent
output file has ".0" appended to its name; the previous most recent
@ -233,8 +233,8 @@ Currently supported commands are:
This command stops the server immediately. Recent changes made through dynamic
update or IXFR are not saved to the master files, but are rolled
forward from the journal files when the server is restarted. If
``-p`` is specified, ``named``'s process ID is returned. This allows
an external process to determine when ``named`` has completed
``-p`` is specified, :iscman:`named`'s process ID is returned. This allows
an external process to determine when :iscman:`named` has completed
halting.
See also :option:`rndc stop`.
@ -279,11 +279,11 @@ Currently supported commands are:
Existing keys that are already trusted are not deleted from
memory; DNSSEC validation can continue after this command is used.
However, key maintenance operations cease until ``named`` is
However, key maintenance operations cease until :iscman:`named` is
restarted or reconfigured, and all existing key maintenance states
are deleted.
Running :option:`rndc reconfig` or restarting ``named`` immediately
Running :option:`rndc reconfig` or restarting :iscman:`named` immediately
after this command causes key maintenance to be reinitialized
from scratch, just as if the server were being started for the
first time. This is primarily intended for testing, but it may
@ -297,16 +297,16 @@ Currently supported commands are:
command requires the ``allow-new-zones`` option to be set to ``yes``.
As with ``addzone``, the configuration string specified on the
command line is the zone configuration text that would ordinarily be
placed in ``named.conf``.
placed in :iscman:`named.conf`.
If the zone was originally added via :option:`rndc addzone`, the
configuration changes are recorded permanently and are still
in effect after the server is restarted or reconfigured. However, if
it was originally configured in ``named.conf``, then that original
it was originally configured in :iscman:`named.conf`, then that original
configuration remains in place; when the server is restarted or
reconfigured, the zone reverts to its original configuration. To
make the changes permanent, it must also be modified in
``named.conf``.
:iscman:`named.conf`.
See also :option:`rndc addzone` and :option:`rndc delzone`.
@ -324,18 +324,18 @@ Currently supported commands are:
This command sets a DNSSEC negative trust anchor (NTA) for ``domain``, with a
lifetime of ``duration``. The default lifetime is configured in
``named.conf`` via the ``nta-lifetime`` option, and defaults to one
:iscman:`named.conf` via the ``nta-lifetime`` option, and defaults to one
hour. The lifetime cannot exceed one week.
A negative trust anchor selectively disables DNSSEC validation for
zones that are known to be failing because of misconfiguration rather
than an attack. When data to be validated is at or below an active
NTA (and above any other configured trust anchors), ``named``
NTA (and above any other configured trust anchors), :iscman:`named`
aborts the DNSSEC validation process and treats the data as insecure
rather than bogus. This continues until the NTA's lifetime has
elapsed.
NTAs persist across restarts of the ``named`` server. The NTAs for a
NTAs persist across restarts of the :iscman:`named` server. The NTAs for a
view are saved in a file called ``name.nta``, where ``name`` is the name
of the view; if it contains characters that are incompatible with
use as a file name, a cryptographic hash is generated from the name of
@ -353,7 +353,7 @@ Currently supported commands are:
of existing NTAs is printed. Note that this may include NTAs that are
expired but have not yet been cleaned up.
Normally, ``named`` periodically tests to see whether data below
Normally, :iscman:`named` periodically tests to see whether data below
an NTA can now be validated (see the ``nta-recheck`` option in the
Administrator Reference Manual for details). If data can be
validated, then the NTA is regarded as no longer necessary and is
@ -380,8 +380,8 @@ Currently supported commands are:
Query logging can also be enabled by explicitly directing the
``queries`` ``category`` to a ``channel`` in the ``logging`` section
of ``named.conf``, or by specifying ``querylog yes;`` in the
``options`` section of ``named.conf``.
of :iscman:`named.conf`, or by specifying ``querylog yes;`` in the
``options`` section of :iscman:`named.conf`.
.. option:: reconfig
@ -392,7 +392,7 @@ Currently supported commands are:
.. option:: recursing
This command dumps the list of queries ``named`` is currently
This command dumps the list of queries :iscman:`named` is currently
recursing on, and the list of domains to which iterative queries
are currently being sent.
@ -452,18 +452,18 @@ Currently supported commands are:
:program:`rndc` response channel and printed to the standard output.
Otherwise, it is written to the secroots dump file, which defaults to
``named.secroots``, but can be overridden via the ``secroots-file``
option in ``named.conf``.
option in :iscman:`named.conf`.
See also :option:`rndc managed-keys`.
.. option:: serve-stale (on | off | reset | status) [class [view]]
This command enables, disables, resets, or reports the current status of
the serving of stale answers as configured in ``named.conf``.
the serving of stale answers as configured in :iscman:`named.conf`.
If serving of stale answers is disabled by ``rndc-serve-stale off``, then it
remains disabled even if ``named`` is reloaded or reconfigured. ``rndc
serve-stale reset`` restores the setting as configured in ``named.conf``.
remains disabled even if :iscman:`named` is reloaded or reconfigured. ``rndc
serve-stale reset`` restores the setting as configured in :iscman:`named.conf`.
``rndc serve-stale status`` reports whether caching and serving of stale
answers is currently enabled or disabled. It also reports the values of
@ -520,7 +520,7 @@ Currently supported commands are:
chain should be set. ``iterations`` defines the number of additional times to apply
the algorithm when generating an NSEC3 hash. The ``salt`` is a string
of data expressed in hexadecimal, a hyphen (`-') if no salt is to be
used, or the keyword ``auto``, which causes ``named`` to generate a
used, or the keyword ``auto``, which causes :iscman:`named` to generate a
random 64-bit salt.
So, for example, to create an NSEC3 chain using the SHA-1 hash
@ -553,8 +553,8 @@ Currently supported commands are:
This command stops the server, making sure any recent changes made through dynamic
update or IXFR are first saved to the master files of the updated
zones. If ``-p`` is specified, ``named(8)`'s process ID is returned.
This allows an external process to determine when ``named`` has
zones. If ``-p`` is specified, :iscman:`named`'s process ID is returned.
This allows an external process to determine when :iscman:`named` has
completed stopping.
See also :option:`rndc halt`.
@ -606,7 +606,7 @@ Currently supported commands are:
.. option:: tsig-list
This command lists the names of all TSIG keys currently configured for use by
``named`` in each view. The list includes both statically configured keys and
:iscman:`named` in each view. The list includes both statically configured keys and
dynamic TKEY-negotiated keys.
.. option:: validation (on | off | status) [view ...]

6
bin/tools/mdig.rst
View file

@ -30,18 +30,18 @@ Synopsis
Description
~~~~~~~~~~~
:program:`mdig` is a multiple/pipelined query version of ``dig``: instead of
:program:`mdig` is a multiple/pipelined query version of :iscman:`dig`: instead of
waiting for a response after sending each query, it begins by sending
all queries. Responses are displayed in the order in which they are
received, not in the order the corresponding queries were sent.
:program:`mdig` options are a subset of the ``dig`` options, and are divided
:program:`mdig` options are a subset of the :iscman:`dig` options, and are divided
into "anywhere options," which can occur anywhere, "global options," which
must occur before the query name (or they are ignored with a warning),
and "local options," which apply to the next query on the command line.
The ``@server`` option is a mandatory global option. It is the name or IP
address of the name server to query. (Unlike ``dig``, this value is not
address of the name server to query. (Unlike :iscman:`dig`, this value is not
retrieved from ``/etc/resolv.conf``.) It can be an IPv4 address in
dotted-decimal notation, an IPv6 address in colon-delimited notation, or
a hostname. When the supplied ``server`` argument is a hostname,

8
bin/tools/named-journalprint.rst
View file

@ -30,8 +30,8 @@ Description
printing it in a human-readable form, or, optionally, converting it
to a different journal file format.
Journal files are automatically created by ``named`` when changes are
made to dynamic zones (e.g., by ``nsupdate``). They record each addition
Journal files are automatically created by :iscman:`named` when changes are
made to dynamic zones (e.g., by :iscman:`nsupdate`). They record each addition
or deletion of a resource record, in binary format, allowing the changes
to be re-applied to the zone when the server is restarted after a
shutdown or crash. By default, the name of the journal file is formed by
@ -45,7 +45,7 @@ the resource record in master-file format.
The ``-c`` (compact) option provides a mechanism to reduce the size of
a journal by removing (most/all) transactions prior to the specified
serial number. Note: this option *must not* be used while ``named`` is
serial number. Note: this option *must not* be used while :iscman:`named` is
running, and can cause data loss if the zone file has not been updated
to contain the data being removed from the journal. Use with extreme caution.
@ -58,7 +58,7 @@ replaced. ``-d`` writes out the journal in the format used by
versions of BIND up to 9.16.11; ``-u`` writes it out in the format used
by versions since 9.16.13. (9.16.12 is omitted due to a journal-formatting
bug in that release.) Note that these options *must not* be used while
``named`` is running.
:iscman:`named` is running.
See Also
~~~~~~~~

2
bin/tools/named-nzd2nzf.rst
View file

@ -28,7 +28,7 @@ Description
:program:`named-nzd2nzf` converts an NZD database to NZF format and prints it
to standard output. This can be used to review the configuration of
zones that were added to ``named`` via :option:`rndc addzone`. It can also be
zones that were added to :iscman:`named` via :option:`rndc addzone`. It can also be
used to restore the old file format when rolling back from a newer
version of BIND to an older version.

50
doc/arm/advanced.rst
View file

@ -31,9 +31,9 @@ The ``NOTIFY`` protocol is specified in :rfc:`1996`.
.. note::
As a secondary zone can also be a primary to other secondaries, ``named``, by
As a secondary zone can also be a primary to other secondaries, :iscman:`named`, by
default, sends ``NOTIFY`` messages for every zone it loads.
Specifying ``notify primary-only;`` causes ``named`` to only send
Specifying ``notify primary-only;`` causes :iscman:`named` to only send
``NOTIFY`` for primary zones that it loads.
.. _dynamic_update:
@ -50,7 +50,7 @@ Dynamic update is enabled by including an ``allow-update`` or an
If the zone's ``update-policy`` is set to ``local``, updates to the zone
are permitted for the key ``local-ddns``, which is generated by
``named`` at startup. See :ref:`dynamic_update_policies` for more details.
:iscman:`named` at startup. See :ref:`dynamic_update_policies` for more details.
Dynamic updates using Kerberos-signed requests can be made using the
TKEY/GSS protocol, either by setting the ``tkey-gssapi-keytab`` option
@ -385,9 +385,9 @@ a secondary server.
This section is a guide to setting up TSIG in BIND. It describes the
configuration syntax and the process of creating TSIG keys.
``named`` supports TSIG for server-to-server communication, and some of
:iscman:`named` supports TSIG for server-to-server communication, and some of
the tools included with BIND support it for sending messages to
``named``:
:iscman:`named`:
* :ref:`man_nsupdate` supports TSIG via the :option:`-k <nsupdate -k>`, :option:`-l <nsupdate -l>`, and :option:`-y <nsupdate -y>` command-line options, or via the ``key`` command when running interactively.
* :ref:`man_dig` supports TSIG via the :option:`-k <nsupdate -k>` and :option:`-y <nsupdate -y>` command-line options.
@ -395,9 +395,9 @@ the tools included with BIND support it for sending messages to
Generating a Shared Key
~~~~~~~~~~~~~~~~~~~~~~~
TSIG keys can be generated using the ``tsig-keygen`` command; the output
TSIG keys can be generated using the :iscman:`tsig-keygen` command; the output
of the command is a ``key`` directive suitable for inclusion in
``named.conf``. The key name, algorithm, and size can be specified by
:iscman:`named.conf`. The key name, algorithm, and size can be specified by
command-line parameters; the defaults are "tsig-key", HMAC-SHA256, and
256 bits, respectively.
@ -415,15 +415,15 @@ server to another is beyond the scope of the DNS. A secure transport
mechanism should be used: secure FTP, SSL, ssh, telephone, encrypted
email, etc.)
``tsig-keygen`` can also be run as ``ddns-confgen``, in which case its
:iscman:`tsig-keygen` can also be run as :iscman:`ddns-confgen`, in which case its
output includes additional configuration text for setting up dynamic DNS
in ``named``. See :ref:`man_ddns-confgen` for details.
in :iscman:`named`. See :ref:`man_ddns-confgen` for details.
Loading a New Key
~~~~~~~~~~~~~~~~~
For a key shared between servers called ``host1`` and ``host2``, the
following could be added to each server's ``named.conf`` file:
following could be added to each server's :iscman:`named.conf` file:
::
@ -432,14 +432,14 @@ following could be added to each server's ``named.conf`` file:
secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY=";
};
(This is the same key generated above using ``tsig-keygen``.)
(This is the same key generated above using :iscman:`tsig-keygen`.)
Since this text contains a secret, it is recommended that either
``named.conf`` not be world-readable, or that the ``key`` directive be
:iscman:`named.conf` not be world-readable, or that the ``key`` directive be
stored in a file which is not world-readable and which is included in
``named.conf`` via the ``include`` directive.
:iscman:`named.conf` via the ``include`` directive.
Once a key has been added to ``named.conf`` and the server has been
Once a key has been added to :iscman:`named.conf` and the server has been
restarted or reconfigured, the server can recognize the key. If the
server receives a message signed by the key, it is able to verify
the signature. If the signature is valid, the response is signed
@ -568,7 +568,7 @@ to recursively fetch or validate the key.
SIG(0) signing of multiple-message TCP streams is not supported.
The only tool shipped with BIND 9 that generates SIG(0) signed messages
is ``nsupdate``.
is :iscman:`nsupdate`.
.. _DNSSEC:
@ -602,7 +602,7 @@ another zone above this one in the DNS tree.
Generating Keys
~~~~~~~~~~~~~~~
The ``dnssec-keygen`` program is used to generate keys.
The :iscman:`dnssec-keygen` program is used to generate keys.
A secure zone must contain one or more zone keys. The zone keys
sign all other records in the zone, as well as the zone keys of any
@ -629,9 +629,9 @@ key (in the ``.key`` file) is used for signature verification.
To generate another key with the same properties but with a different
key tag, repeat the above command.
The ``dnssec-keyfromlabel`` program is used to get a key pair from a
The :iscman:`dnssec-keyfromlabel` program is used to get a key pair from a
crypto hardware device and build the key files. Its usage is similar to
``dnssec-keygen``.
:iscman:`dnssec-keygen`.
The public keys should be inserted into the zone file by including the
``.key`` files using ``$INCLUDE`` statements.
@ -641,7 +641,7 @@ The public keys should be inserted into the zone file by including the
Signing the Zone
~~~~~~~~~~~~~~~~
The ``dnssec-signzone`` program is used to sign a zone.
The :iscman:`dnssec-signzone` program is used to sign a zone.
Any ``keyset`` files corresponding to secure sub-zones should be
present. The zone signer generates ``NSEC``, ``NSEC3``, and ``RRSIG``
@ -656,9 +656,9 @@ it is in a file called ``zone.child.example``:
``dnssec-signzone -o child.example zone.child.example``
One output file is produced: ``zone.child.example.signed``. This file
should be referenced by ``named.conf`` as the input file for the zone.
should be referenced by :iscman:`named.conf` as the input file for the zone.
``dnssec-signzone`` also produces keyset and dsset files. These are used
:iscman:`dnssec-signzone` also produces keyset and dsset files. These are used
to provide the parent zone administrators with the ``DNSKEYs`` (or their
corresponding ``DS`` records) that are the secure entry point to the zone.
@ -667,7 +667,7 @@ corresponding ``DS`` records) that are the secure entry point to the zone.
Configuring Servers for DNSSEC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable ``named`` to validate answers received from other servers, the
To enable :iscman:`named` to validate answers received from other servers, the
``dnssec-validation`` option must be set to either ``yes`` or ``auto``.
When ``dnssec-validation`` is set to ``auto``, a trust anchor for the
@ -676,7 +676,7 @@ as part of BIND and is kept up to date using :rfc:`5011` key management.
When ``dnssec-validation`` is set to ``yes``, DNSSEC validation
only occurs if at least one trust anchor has been explicitly configured
in ``named.conf``, using a ``trust-anchors`` statement (or the
in :iscman:`named.conf`, using a ``trust-anchors`` statement (or the
``managed-keys`` and ``trusted-keys`` statements, both deprecated).
When ``dnssec-validation`` is set to ``no``, DNSSEC validation does not
@ -692,7 +692,7 @@ with the keyword ``static-key`` or ``static-ds`` are loaded directly into the
table of trust anchors, and can only be changed by altering the
configuration. Keys configured with ``initial-key`` or ``initial-ds`` are used
to initialize :rfc:`5011` trust anchor maintenance, and are kept up-to-date
automatically after the first time ``named`` runs.
automatically after the first time :iscman:`named` runs.
``trust-anchors`` is described in more detail later in this document.
@ -704,7 +704,7 @@ After DNSSEC is established, a typical DNSSEC configuration looks
something like the following. It has one or more public keys for the
root, which allows answers from outside the organization to be validated.
It also has several keys for parts of the namespace that the
organization controls. These are here to ensure that ``named`` is immune
organization controls. These are here to ensure that :iscman:`named` is immune
to compromised security in the DNSSEC components of parent zones.
::

10
doc/arm/build.rst
View file

@ -118,12 +118,12 @@ For DNSTAP packet logging, ``libfstrm``
(https://developers.google.com/protocol-buffers) must be installed, and
BIND must be configured with ``--enable-dnstap``.
To support internationalized domain names in ``dig``, ``libidn2``
To support internationalized domain names in :iscman:`dig`, ``libidn2``
(https://www.gnu.org/software/libidn/#libidn2) must be installed. If the
library is installed in a nonstandard location, specify the prefix using
``--with-libidn2=/prefix`` or adjust ``PKG_CONFIG_PATH``.
For line editing in ``nsupdate`` and ``nslookup``, either the
For line editing in :iscman:`nsupdate` and :iscman:`nslookup`, either the
``readline`` (https://tiswww.case.edu/php/chet/readline/rltop.html) or
the ``libedit`` library (https://www.thrysoee.dk/editline/) must be
installed. If these are installed at a nonstandard location, adjust
@ -152,19 +152,19 @@ specifying ``--enable-fixed-rrset`` or ``--disable-fixed-rrset`` on the
``configure`` command line. By default, fixed RRset-order is disabled to
reduce memory footprint.
The ``--enable-querytrace`` option causes ``named`` to log every step
The ``--enable-querytrace`` option causes :iscman:`named` to log every step
while processing every query. The ``--enable-singletrace`` option turns
on the same verbose tracing, but allows an individual query to be
separately traced by setting its query ID to 0. These options should
only be enabled when debugging, because they have a significant negative
impact on query performance.
``make install`` installs ``named`` and the various BIND 9 libraries. By
``make install`` installs :iscman:`named` and the various BIND 9 libraries. By
default, installation is into /usr/local, but this can be changed with
the ``--prefix`` option when running ``configure``.
The option ``--sysconfdir`` can be specified to set the directory where
configuration files such as ``named.conf`` go by default;
configuration files such as :iscman:`named.conf` go by default;
``--localstatedir`` can be used to set the default parent directory of
``run/named.pid``. ``--sysconfdir`` defaults to ``$prefix/etc`` and
``--localstatedir`` defaults to ``$prefix/var``.

12
doc/arm/catz.rst
View file

@ -34,7 +34,7 @@ Principle of Operation
~~~~~~~~~~~~~~~~~~~~~~
Normally, if a zone is to be served by a secondary server, the
``named.conf`` file on the server must list the zone, or the zone must
:iscman:`named.conf` file on the server must list the zone, or the zone must
be added using :option:`rndc addzone`. In environments with a large number of
secondary servers, and/or where the zones being served are changing
frequently, the overhead involved in maintaining consistent zone
@ -48,19 +48,19 @@ removes, or reconfigures member zones based on the data received.
To use a catalog zone, it must first be set up as a normal zone on both the
primary and secondary servers that are configured to use it. It
must also be added to a ``catalog-zones`` list in the ``options`` or
``view`` statement in ``named.conf``. This is comparable to the way a
``view`` statement in :iscman:`named.conf`. This is comparable to the way a
policy zone is configured as a normal zone and also listed in a
``response-policy`` statement.
To use the catalog zone feature to serve a new member zone:
- Set up the member zone to be served on the primary as normal. This
can be done by editing ``named.conf`` or by running
can be done by editing :iscman:`named.conf` or by running
:option:`rndc addzone`.
- Add an entry to the catalog zone for the new member zone. This can
be done by editing the catalog zone's zone file and running
:option:`rndc reload`, or by updating the zone using ``nsupdate``.
:option:`rndc reload`, or by updating the zone using :iscman:`nsupdate`.
The change to the catalog zone is propagated from the primary to all
secondaries using the normal AXFR/IXFR mechanism. When the secondary receives the
@ -85,7 +85,7 @@ Configuring Catalog Zones
~~~~~~~~~~~~~~~~~~~~~~~~~
Catalog zones are configured with a ``catalog-zones`` statement in the
``options`` or ``view`` section of ``named.conf``. For example:
``options`` or ``view`` section of :iscman:`named.conf`. For example:
::
@ -211,7 +211,7 @@ BIND currently supports the following options:
These options are the equivalents of ``allow-query`` and
``allow-transfer`` in a zone declaration in the ``named.conf``
``allow-transfer`` in a zone declaration in the :iscman:`named.conf`
configuration file. The ACL is processed in order; if there is no
match to any rule, the default policy is to deny access. For the
syntax of the APL RR, see :rfc:`3123`.

76
doc/arm/configuration.rst
View file

@ -145,12 +145,12 @@ controlling and debugging the name server daemon.
Diagnostic Tools
^^^^^^^^^^^^^^^^
The ``dig``, ``host``, and ``nslookup`` programs are all command-line
The :iscman:`dig`, :iscman:`host`, and :iscman:`nslookup` programs are all command-line
tools for manually querying name servers. They differ in style and
output format.
``dig``
``dig`` is the most versatile and complete of these lookup tools. It
:iscman:`dig`
:iscman:`dig` is the most versatile and complete of these lookup tools. It
has two modes: simple interactive mode for a single query, and batch
mode, which executes a query for each in a list of several query
lines. All query options are accessible from the command line.
@ -158,23 +158,23 @@ output format.
For more information and a list of available commands and options,
see :ref:`man_dig`.
``host``
The ``host`` utility emphasizes simplicity and ease of use. By
:iscman:`host`
The :iscman:`host` utility emphasizes simplicity and ease of use. By
default, it converts between host names and Internet addresses, but
its functionality can be extended with the use of options.
For more information and a list of available commands and options,
see :ref:`man_host`.
``nslookup``
``nslookup`` has two modes: interactive and non-interactive.
:iscman:`nslookup`
:iscman:`nslookup` has two modes: interactive and non-interactive.
Interactive mode allows the user to query name servers for
information about various hosts and domains, or to print a list of
hosts in a domain. Non-interactive mode is used to print just the
name and requested information for a host or domain.
Due to its arcane user interface and frequently inconsistent
behavior, we do not recommend the use of ``nslookup``. Use ``dig``
behavior, we do not recommend the use of :iscman:`nslookup`. Use :iscman:`dig`
instead.
.. _admin_tools:
@ -185,47 +185,47 @@ Administrative Tools
Administrative tools play an integral part in the management of a
server.
``named-checkconf``
The ``named-checkconf`` program checks the syntax of a ``named.conf``
:iscman:`named-checkconf`
The :iscman:`named-checkconf` program checks the syntax of a :iscman:`named.conf`
file.
For more information and a list of available commands and options,
see :ref:`man_named-checkconf`.
``named-checkzone``
The ``named-checkzone`` program checks a zone file for syntax and
:iscman:`named-checkzone`
The :iscman:`named-checkzone` program checks a zone file for syntax and
consistency.
For more information and a list of available commands and options,
see :ref:`man_named-checkzone`.
``named-compilezone``
This tool is similar to ``named-checkzone`` but it always dumps the zone content
:iscman:`named-compilezone`
This tool is similar to :iscman:`named-checkzone` but it always dumps the zone content
to a specified file (typically in a different format).
For more information and a list of available commands and options,
see :ref:`man_named-compilezone`.
``rndc``
The remote name daemon control (``rndc``) program allows the system
:iscman:`rndc`
The remote name daemon control (:iscman:`rndc`) program allows the system
administrator to control the operation of a name server.
See :ref:`man_rndc` for details of the available ``rndc``
See :ref:`man_rndc` for details of the available :iscman:`rndc`
commands.
``rndc`` requires a configuration file, since all communication with
:iscman:`rndc` requires a configuration file, since all communication with
the server is authenticated with digital signatures that rely on a
shared secret, and there is no way to provide that secret other than
with a configuration file. The default location for the ``rndc``
with a configuration file. The default location for the :iscman:`rndc`
configuration file is |rndc_conf|, but an alternate location
can be specified with the :option:`-c <rndc -c>` option. If the configuration file is
not found, ``rndc`` also looks in |rndc_key| (or whatever
not found, :iscman:`rndc` also looks in |rndc_key| (or whatever
``sysconfdir`` was defined when the BIND build was configured). The
``rndc.key`` file is generated by running :option:`rndc-confgen -a` as
described in :ref:`controls_statement_definition_and_usage`.
The format of the configuration file is similar to that of
``named.conf``, but is limited to only four statements: the ``options``,
:iscman:`named.conf`, but is limited to only four statements: the ``options``,
``key``, ``server``, and ``include`` statements. These statements are
what associate the secret keys to the servers with which they are
meant to be shared. The order of statements is not significant.
@ -236,12 +236,12 @@ server.
contacted if no :option:`-s <rndc -s>` option is provided on the command line.
``default-key`` takes the name of a key as its argument, as defined
by a ``key`` statement. ``default-port`` specifies the port to which
``rndc`` should connect if no port is given on the command line or in
:iscman:`rndc` should connect if no port is given on the command line or in
a ``server`` statement.
The ``key`` statement defines a key to be used by ``rndc`` when
authenticating with ``named``. Its syntax is identical to the ``key``
statement in ``named.conf``. The keyword ``key`` is followed by a key
The ``key`` statement defines a key to be used by :iscman:`rndc` when
authenticating with :iscman:`named`. Its syntax is identical to the ``key``
statement in :iscman:`named.conf`. The keyword ``key`` is followed by a key
name, which must be a valid domain name, though it need not actually
be hierarchical; thus, a string like ``rndc_key`` is a valid name.
The ``key`` statement has two clauses: ``algorithm`` and ``secret``.
@ -256,7 +256,7 @@ server.
name or address. The ``server`` statement has two clauses: ``key``
and ``port``. The ``key`` clause specifies the name of the key to be
used when communicating with this server, and the ``port`` clause can
be used to specify the port ``rndc`` should connect to on the server.
be used to specify the port :iscman:`rndc` should connect to on the server.
A sample minimal configuration file is as follows:
@ -290,11 +290,11 @@ server.
and it has an identical key statement for ``rndc_key``.
Running the ``rndc-confgen`` program conveniently creates an
``rndc.conf`` file, and also displays the corresponding
``controls`` statement needed to add to ``named.conf``.
Running the :iscman:`rndc-confgen` program conveniently creates an
:iscman:`rndc.conf` file, and also displays the corresponding
``controls`` statement needed to add to :iscman:`named.conf`.
Alternatively, it is possible to run :option:`rndc-confgen -a` to set up an
``rndc.key`` file and not modify ``named.conf`` at all.
``rndc.key`` file and not modify :iscman:`named.conf` at all.
Signals
~~~~~~~
@ -303,13 +303,13 @@ Certain Unix signals cause the name server to take specific actions, as
described in the following table. These signals can be sent using the
``kill`` command.
+--------------+-------------------------------------------------------+
| ``SIGHUP`` | Causes the server to read ``named.conf`` and reload |
| | the database. |
+--------------+-------------------------------------------------------+
| ``SIGTERM`` | Causes the server to clean up and exit. |
+--------------+-------------------------------------------------------+
| ``SIGINT`` | Causes the server to clean up and exit. |
+--------------+-------------------------------------------------------+
+--------------+-------------------------------------------------------------+
| ``SIGHUP`` | Causes the server to read :iscman:`named.conf` and reload |
| | the database. |
+--------------+-------------------------------------------------------------+
| ``SIGTERM`` | Causes the server to clean up and exit. |
+--------------+-------------------------------------------------------------+
| ``SIGINT`` | Causes the server to clean up and exit. |
+--------------+-------------------------------------------------------------+
.. include:: plugins.rst

6
doc/arm/dlz.rst
View file

@ -20,8 +20,8 @@ no required format or schema. DLZ modules exist for several different
database backends, including MySQL and LDAP, and can be
written for any other.
The DLZ module provides data to ``named`` in text
format, which is then converted to DNS wire format by ``named``. This
The DLZ module provides data to :iscman:`named` in text
format, which is then converted to DNS wire format by :iscman:`named`. This
conversion, and the lack of any internal caching, places significant
limits on the query performance of DLZ modules. Consequently, DLZ is not
recommended for use on high-volume servers. However, it can be used in a
@ -33,7 +33,7 @@ database.
Configuring DLZ
~~~~~~~~~~~~~~~
A DLZ database is configured with a ``dlz`` statement in ``named.conf``:
A DLZ database is configured with a ``dlz`` statement in :iscman:`named.conf`:
::

48
doc/arm/dnssec.rst
View file

@ -21,12 +21,12 @@ A zone can be changed from insecure to secure in three ways: using a
dynamic DNS update, via the ``auto-dnssec`` zone option, or by setting a
DNSSEC policy for the zone with ``dnssec-policy``.
For any method, ``named`` must be configured so that it can see
For any method, :iscman:`named` must be configured so that it can see
the ``K*`` files which contain the public and private parts of the keys
that are used to sign the zone. These files are generated
by ``dnssec-keygen``, or created when needed by ``named`` if
by :iscman:`dnssec-keygen`, or created when needed by :iscman:`named` if
``dnssec-policy`` is used. Keys should be placed in the
key-directory, as specified in ``named.conf``:
key-directory, as specified in :iscman:`named.conf`:
::
@ -68,7 +68,7 @@ To insert the keys via dynamic update:
> send
While the update request completes almost immediately, the zone is
not completely signed until ``named`` has had time to "walk" the zone
not completely signed until :iscman:`named` has had time to "walk" the zone
and generate the NSEC and RRSIG records. The NSEC record at the apex
is added last, to signal that there is a complete NSEC chain.
@ -87,7 +87,7 @@ NSEC3PARAM record.
> send
Again, this update request completes almost immediately; however,
the record does not show up until ``named`` has had a chance to
the record does not show up until :iscman:`named` has had a chance to
build/remove the relevant chain. A private type record is created
to record the state of the operation (see below for more details), and
is removed once the operation completes.
@ -99,10 +99,10 @@ Fully Automatic Zone Signing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable automatic signing, set a ``dnssec-policy`` or add the
``auto-dnssec`` option to the zone statement in ``named.conf``.
``auto-dnssec`` option to the zone statement in :iscman:`named.conf`.
``auto-dnssec`` has two possible arguments: ``allow`` or ``maintain``.
With ``auto-dnssec allow``, ``named`` can search the key directory for
With ``auto-dnssec allow``, :iscman:`named` can search the key directory for
keys matching the zone, insert them into the zone, and use them to sign
the zone. It does so only when it receives an
:option:`rndc sign zonename <rndc sign>`.
@ -115,15 +115,15 @@ the keys' timing metadata. (See :ref:`man_dnssec-keygen` and
``dnssec-policy`` is similar to ``auto-dnssec maintain``, but
``dnssec-policy`` also automatically creates new keys when necessary. In
addition, any configuration related to DNSSEC signing is retrieved from the
policy, ignoring existing DNSSEC ``named.conf`` options.
policy, ignoring existing DNSSEC :iscman:`named.conf` options.
``named`` periodically searches the key directory for keys matching
:iscman:`named` periodically searches the key directory for keys matching
the zone; if the keys' metadata indicates that any change should be
made to the zone - such as adding, removing, or revoking a key - then that
action is carried out. By default, the key directory is checked for
changes every 60 minutes; this period can be adjusted with
``dnssec-loadkeys-interval``, up to a maximum of 24 hours. The
:option:`rndc loadkeys` command forces ``named`` to check for key updates immediately.
:option:`rndc loadkeys` command forces :iscman:`named` to check for key updates immediately.
If keys are present in the key directory the first time the zone is
loaded, the zone is signed immediately, without waiting for an
@ -196,8 +196,8 @@ Dynamic DNS Update Method
~~~~~~~~~~~~~~~~~~~~~~~~~
To perform key rollovers via a dynamic update, the ``K*``
files for the new keys must be added so that ``named`` can find them.
The new DNSKEY RRs can then be added via dynamic update. ``named`` then causes the
files for the new keys must be added so that :iscman:`named` can find them.
The new DNSKEY RRs can then be added via dynamic update. :iscman:`named` then causes the
zone to be signed with the new keys; when the signing is complete, the
private type records are updated so that the last octet is non-zero.
@ -211,15 +211,15 @@ ensures that all clients are able to verify at least one signature
when the old DNSKEY is removed.
The old DNSKEY can be removed via UPDATE, taking care to specify the
correct key. ``named`` cleans out any signatures generated by the
correct key. :iscman:`named` cleans out any signatures generated by the
old key after the update completes.
Automatic Key Rollovers
~~~~~~~~~~~~~~~~~~~~~~~
When a new key reaches its activation date (as set by ``dnssec-keygen``
or ``dnssec-settime``), and if the ``auto-dnssec`` zone option is set to
``maintain``, ``named`` automatically carries out the key rollover.
When a new key reaches its activation date (as set by :iscman:`dnssec-keygen`
or :iscman:`dnssec-settime`), and if the ``auto-dnssec`` zone option is set to
``maintain``, :iscman:`named` automatically carries out the key rollover.
If the key's algorithm has not previously been used to sign the zone,
then the zone is fully signed as quickly as possible. However, if
the new key replaces an existing key of the same algorithm, the
@ -242,7 +242,7 @@ Converting From NSEC to NSEC3
Add a ``nsec3param`` option to your ``dnssec-policy`` and
run :option:`rndc reconfig`.
Or use ``nsupdate`` to add an NSEC3PARAM record.
Or use :iscman:`nsupdate` to add an NSEC3PARAM record.
In both cases, the NSEC3 chain is generated and the NSEC3PARAM record is
added before the NSEC chain is destroyed.
@ -253,7 +253,7 @@ Converting From NSEC3 to NSEC
To do this, remove the ``nsec3param`` option from the ``dnssec-policy`` and
run :option:`rndc reconfig`.
Or use ``nsupdate`` to remove all NSEC3PARAM records with a
Or use :iscman:`nsupdate` to remove all NSEC3PARAM records with a
zero flag field. The NSEC chain is generated before the NSEC3 chain
is removed.
@ -261,12 +261,12 @@ Converting From Secure to Insecure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To convert a signed zone to unsigned using dynamic DNS, delete all the
DNSKEY records from the zone apex using ``nsupdate``. All signatures,
DNSKEY records from the zone apex using :iscman:`nsupdate`. All signatures,
NSEC or NSEC3 chains, and associated NSEC3PARAM records are removed
automatically. This takes place after the update request completes.
This requires the ``dnssec-secure-to-insecure`` option to be set to
``yes`` in ``named.conf``.
``yes`` in :iscman:`named.conf`.
In addition, if the ``auto-dnssec maintain`` zone statement is used, it
should be removed or changed to ``allow`` instead; otherwise it will re-sign.
@ -274,7 +274,7 @@ should be removed or changed to ``allow`` instead; otherwise it will re-sign.
Periodic Re-signing
~~~~~~~~~~~~~~~~~~~
In any secure zone which supports dynamic updates, ``named``
In any secure zone which supports dynamic updates, :iscman:`named`
periodically re-signs RRsets which have not been re-signed as a result of
some update action. The signature lifetimes are adjusted to
spread the re-sign load over time rather than all at once.
@ -282,9 +282,9 @@ spread the re-sign load over time rather than all at once.
NSEC3 and OPTOUT
~~~~~~~~~~~~~~~~
``named`` only supports creating new NSEC3 chains where all the NSEC3
records in the zone have the same OPTOUT state. ``named`` supports
:iscman:`named` only supports creating new NSEC3 chains where all the NSEC3
records in the zone have the same OPTOUT state. :iscman:`named` supports
UPDATES to zones where the NSEC3 records in the chain have mixed OPTOUT
state. ``named`` does not support changing the OPTOUT state of an
state. :iscman:`named` does not support changing the OPTOUT state of an
individual NSEC3 record; if the
OPTOUT state of an individual NSEC3 needs to be changed, the entire chain must be changed.

2
doc/arm/dyndb.rst
View file

@ -35,7 +35,7 @@ Configuring DynDB
~~~~~~~~~~~~~~~~~
A DynDB database is configured with a ``dyndb`` statement in
``named.conf``:
:iscman:`named.conf`:
::

6
doc/arm/general.rst
View file

@ -394,10 +394,10 @@ Notes
.. [#rfc4955] BIND 9 interoperates with correctly designed experiments.
.. [#rfc5452] ``named`` only uses ports to extend the ID space; addresses are not
.. [#rfc5452] :iscman:`named` only uses ports to extend the ID space; addresses are not
used.
.. [#rfc6147] Section 5.5 does not match reality. ``named`` uses the presence
.. [#rfc6147] Section 5.5 does not match reality. :iscman:`named` uses the presence
of DO=1 to detect if validation may be occurring. CD has no bearing
on whether validation occurs.
@ -417,7 +417,7 @@ Notes
.. [#rfc7344] Updating of parent zones is not yet implemented.
.. [#rfc7830] ``named`` does not currently encrypt DNS requests, so the PAD option
.. [#rfc7830] :iscman:`named` does not currently encrypt DNS requests, so the PAD option
is accepted but not returned in responses.
.. [#rfc3363] Section 4 is ignored.

10
doc/arm/introduction.rst
View file

@ -95,7 +95,7 @@ applications.
Clients look up information in the DNS by calling a *resolver* library,
which sends queries to one or more *name servers* and interprets the
responses. The BIND 9 software distribution contains a name server,
``named``, and a set of associated tools.
:iscman:`named`, and a set of associated tools.
.. _domain_names:
@ -155,7 +155,7 @@ and we suggest reading :rfc:`1033`, :rfc:`1034`, and :rfc:`1035` to gain a compl
understanding of this difficult and subtle topic.
Though BIND 9 is called a "domain name server," it deals primarily in
terms of zones. The ``primary`` and ``secondary`` declarations in the ``named.conf``
terms of zones. The ``primary`` and ``secondary`` declarations in the :iscman:`named.conf`
file specify zones, not domains. When BIND asks some other site if it is
willing to be a secondary server for a *domain*, it is actually asking
for secondary service for some collection of *zones*.
@ -172,7 +172,7 @@ servers, on different networks.
Responses from authoritative servers have the "authoritative answer"
(AA) bit set in the response packets. This makes them easy to identify
when debugging DNS configurations using tools like ``dig`` (:ref:`diagnostic_tools`).
when debugging DNS configurations using tools like :iscman:`dig` (:ref:`diagnostic_tools`).
.. _primary_master:
@ -282,8 +282,8 @@ send queries first to a custom server for RBL processing before
forwarding them to the wider Internet.
There may be one or more forwarders in a given setup. The order in which
the forwarders are listed in ``named.conf`` does not determine the
sequence in which they are queried; rather, ``named`` uses the response
the forwarders are listed in :iscman:`named.conf` does not determine the
sequence in which they are queried; rather, :iscman:`named` uses the response
times from previous queries to select the server that is likely to
respond the most quickly. A server that has not yet been queried is
given an initial small random response time to ensure that it is tried

6
doc/arm/logging-categories.rst
View file

@ -41,7 +41,7 @@
Note: the log message can also be due to packet loss. Before reporting servers for non-:rfc:`1034` compliance they should be re-tested to determine the nature of the non-compliance. This testing should prevent or reduce the number of false-positive reports.
Note: eventually ``named`` will have to stop treating such timeouts as due to :rfc:`1034` non-compliance and start treating it as plain packet loss. Falsely classifying packet loss as due to :rfc:`1034` non-compliance impacts DNSSEC validation, which requires EDNS for the DNSSEC records to be returned.
Note: eventually :iscman:`named` will have to stop treating such timeouts as due to :rfc:`1034` non-compliance and start treating it as plain packet loss. Falsely classifying packet loss as due to :rfc:`1034` non-compliance impacts DNSSEC validation, which requires EDNS for the DNSSEC records to be returned.
``general``
A catch-all for many things that still are not classified into categories.
@ -102,10 +102,10 @@
TLS pre-master secrets (for debugging purposes).
``trust-anchor-telemetry``
Trust-anchor-telemetry requests received by ``named``.
Trust-anchor-telemetry requests received by :iscman:`named`.
``unmatched``
Messages that ``named`` was unable to determine the class of, or for which there was no matching ``view``. A one-line summary is also logged to the ``client`` category. This category is best sent to a file or stderr; by default it is sent to the ``null`` channel.
Messages that :iscman:`named` was unable to determine the class of, or for which there was no matching ``view``. A one-line summary is also logged to the ``client`` category. This category is best sent to a file or stderr; by default it is sent to the ``null`` channel.
``update``
Dynamic updates.

8
doc/arm/managed-keys.rst
View file

@ -15,7 +15,7 @@ Dynamic Trust Anchor Management
-------------------------------
BIND is able to maintain DNSSEC trust anchors using :rfc:`5011` key
management. This feature allows ``named`` to keep track of changes to
management. This feature allows :iscman:`named` to keep track of changes to
critical DNSSEC keys without any need for the operator to make changes
to configuration files.
@ -45,7 +45,7 @@ has completed, the active KSK can be revoked, and the zone can be
"rolled over" to the newly accepted key.
The easiest way to place a stand-by key in a zone is to use the "smart
signing" features of ``dnssec-keygen`` and ``dnssec-signzone``. If a key
signing" features of :iscman:`dnssec-keygen` and :iscman:`dnssec-signzone`. If a key
exists with a publication date in the past, but an activation date which is
unset or in the future, :option:`dnssec-signzone -S` includes the
DNSKEY record in the zone but does not sign with it:
@ -55,7 +55,7 @@ DNSKEY record in the zone but does not sign with it:
$ dnssec-keygen -K keys -f KSK -P now -A now+2y example.net
$ dnssec-signzone -S -K keys example.net
To revoke a key, use the command ``dnssec-revoke``. This
To revoke a key, use the command :iscman:`dnssec-revoke`. This
adds the REVOKED bit to the key flags and regenerates the ``K*.key``
and ``K*.private`` files.
@ -77,7 +77,7 @@ wrapping around at 65535. So, for example, the key
If two keys have IDs exactly 128 apart and one is revoked, the two
key IDs will collide, causing several problems. To prevent this,
``dnssec-keygen`` does not generate a new key if another key
:iscman:`dnssec-keygen` does not generate a new key if another key
which may collide is present. This checking only occurs if the new keys are
written to the same directory that holds all other keys in use for that
zone.

14
doc/arm/pkcs11.rst
View file

@ -153,7 +153,7 @@ Remember that each key should have unique label and we are going to use that
label to reference the private key.
Convert the RSA keys stored in the HSM into a format that BIND 9 understands.
The ``dnssec-keyfromlabel`` tool from BIND 9 can link the raw keys stored in the
The :iscman:`dnssec-keyfromlabel` tool from BIND 9 can link the raw keys stored in the
HSM with the ``K<zone>+<alg>+<id>`` files. You'll need to provide the OpenSSL
engine name (``pkcs11``), the algorithm (``RSASHA256``) and the PKCS#11 label
that specify the token (we asume that it has been initialized as bind9), the
@ -216,7 +216,7 @@ Specifying the Engine on the Command Line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When using OpenSSL-based PKCS#11, the "engine" to be used by OpenSSL can be
specified in ``named`` and all of the BIND ``dnssec-*`` tools by using the ``-E
specified in :iscman:`named` and all of the BIND ``dnssec-*`` tools by using the ``-E
<engine>`` command line option. Specifying the engine is generally not necessary
unless a different OpenSSL engine is used.
@ -227,8 +227,8 @@ provide the name of the OpenSSL engine using the -E command line option.
dnssec-signzone -E pkcs11 -S -o example.net example.net
Running ``named`` With Automatic Zone Re-signing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Running :iscman:`named` With Automatic Zone Re-signing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The zone can also be signed automatically by named. Again, we need to provide
the name of the OpenSSL engine using the :option:`-E <named -E>` command line option.
@ -248,14 +248,14 @@ and the logs should have lines like:
DNSKEY example.net/RSASHA256/42231 (ZSK) is now published
DNSKEY example.net/RSA256SHA256/42231 (ZSK) is now active
For ``named`` to dynamically re-sign zones using HSM keys,
and/or to sign new records inserted via nsupdate, ``named`` must
For :iscman:`named` to dynamically re-sign zones using HSM keys,
and/or to sign new records inserted via nsupdate, :iscman:`named` must
have access to the HSM PIN. In OpenSSL-based PKCS#11, this is
accomplished by placing the PIN into the ``openssl.cnf`` file (in the above
examples, ``/opt/pkcs11/usr/ssl/openssl.cnf``).
The location of the openssl.cnf file can be overridden by setting the
``OPENSSL_CONF`` environment variable before running ``named``.
``OPENSSL_CONF`` environment variable before running :iscman:`named`.
Here is a sample ``openssl.cnf``:

18
doc/arm/plugins.rst
View file

@ -14,7 +14,7 @@
Plugins
-------
Plugins are a mechanism to extend the functionality of ``named`` using
Plugins are a mechanism to extend the functionality of :iscman:`named` using
dynamically loadable libraries. By using plugins, core server
functionality can be kept simple for the majority of users; more complex
code implementing optional features need only be installed by users that
@ -25,17 +25,17 @@ more plugins are added. Currently, only "query plugins" are supported;
these modify the name server query logic. Other plugin types may be
added in the future.
The only plugin currently included in BIND is ``filter-aaaa.so``, which
The only plugin currently included in BIND is :iscman:`filter-aaaa.so <filter-aaaa>`, which
replaces the ``filter-aaaa`` feature that previously existed natively as
part of ``named``. The code for this feature has been removed from
``named`` and can no longer be configured using standard ``named.conf``
syntax, but linking in the ``filter-aaaa.so`` plugin provides identical
part of :iscman:`named`. The code for this feature has been removed from
:iscman:`named` and can no longer be configured using standard :iscman:`named.conf`
syntax, but linking in the :iscman:`filter-aaaa.so <filter-aaaa>` plugin provides identical
functionality.
Configuring Plugins
~~~~~~~~~~~~~~~~~~~
A plugin is configured with the ``plugin`` statement in ``named.conf``:
A plugin is configured with the ``plugin`` statement in :iscman:`named.conf`:
::
@ -61,7 +61,7 @@ Each plugin implements four functions:
- ``plugin_register``
to allocate memory, configure a plugin instance, and attach to hook
points within
``named``
:iscman:`named`
,
- ``plugin_destroy``
to tear down the plugin instance and free memory,
@ -71,9 +71,9 @@ Each plugin implements four functions:
- ``plugin_check``
to test syntactic correctness of the plugin parameters.
At various locations within the ``named`` source code, there are "hook
At various locations within the :iscman:`named` source code, there are "hook
points" at which a plugin may register itself. When a hook point is
reached while ``named`` is running, it is checked to see whether any
reached while :iscman:`named` is running, it is checked to see whether any
plugins have registered themselves there; if so, the associated "hook
action" - a function within the plugin library - is called. Hook
actions may examine the runtime state and make changes: for example,

314
doc/arm/reference.rst
View file

File diff suppressed because it is too large Load diff

10
doc/arm/security.rst
View file

@ -153,7 +153,7 @@ matches when *both* conditions are true.
On Unix servers, it is possible to run BIND in a *chrooted* environment
(using the ``chroot()`` function) by specifying the :option:`-t <named -t>` option for
``named``. This can help improve system security by placing BIND in a
:iscman:`named`. This can help improve system security by placing BIND in a
"sandbox," which limits the damage done if a server is compromised.
Another useful feature in the Unix version of BIND is the ability to run
@ -161,7 +161,7 @@ the daemon as an unprivileged user (:option:`-u <named -u>` user). We suggest ru
as an unprivileged user when using the ``chroot`` feature.
Here is an example command line to load BIND in a ``chroot`` sandbox,
``/var/named``, and to run ``named`` ``setuid`` to user 202:
``/var/named``, and to run :iscman:`named` ``setuid`` to user 202:
``/usr/local/sbin/named -u 202 -t /var/named``
@ -178,7 +178,7 @@ the values of options like ``directory`` and ``pid-file``
must be adjusted to account for this.
Unlike with earlier versions of BIND,
``named`` does *not* typically need to be compiled statically, nor do shared libraries need to be installed under the new
:iscman:`named` does *not* typically need to be compiled statically, nor do shared libraries need to be installed under the new
root. However, depending on the operating system, it may be necessary to set
up locations such as ``/dev/zero``, ``/dev/random``, ``/dev/log``, and
``/etc/localtime``.
@ -188,14 +188,14 @@ up locations such as ``/dev/zero``, ``/dev/random``, ``/dev/log``, and
Using the ``setuid`` Function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Prior to running the ``named`` daemon, use the ``touch`` utility (to
Prior to running the :iscman:`named` daemon, use the ``touch`` utility (to
change file access and modification times) or the ``chown`` utility (to
set the user id and/or group id) on files where BIND should
write.
.. note::
If the ``named`` daemon is running as an unprivileged user, it
If the :iscman:`named` daemon is running as an unprivileged user, it
cannot bind to new restricted ports if the server is
reloaded.

6
doc/arm/troubleshooting.rst
View file

@ -81,7 +81,7 @@ By definition, TLS-encrypted traffic (e.g. DNS over TLS, DNS over HTTPS)
is opaque to packet sniffers, which makes debugging problems with
encrypted DNS close to impossible. However, Wireshark_ offers a
solution_ to this problem by being able to read key log files. In order
to make ``named`` prepare such a file, set the ``SSLKEYLOGFILE``
to make :iscman:`named` prepare such a file, set the ``SSLKEYLOGFILE``
environment variable to either:
- the string ``config`` (``SSLKEYLOGFILE=config``); this requires
@ -110,13 +110,13 @@ environment variable to either:
unusable.
When the ``SSLKEYLOGFILE`` environment variable is set, each TLS
connection established by ``named`` (both incoming and outgoing) causes
connection established by :iscman:`named` (both incoming and outgoing) causes
about 1 kilobyte of data to be written to the key log file.
.. warning::
Due to the limitations of the current logging code in BIND 9,
enabling TLS pre-master secret logging adversely affects ``named``
enabling TLS pre-master secret logging adversely affects :iscman:`named`
performance.
.. _Wireshark: https://www.wireshark.org/

30
doc/dnssec-guide/advanced-discussions.rst
View file

@ -273,7 +273,7 @@ salt. Let's look at how each one can be configured:
security versus resources.
- *Salt*: The salt cannot be configured explicitly, but you can provide
a salt length and ``named`` generates a random salt of the given length.
a salt length and :iscman:`named` generates a random salt of the given length.
We learn more about salt in :ref:`advanced_discussions_nsec3_salt`.
If you want to use these NSEC3 parameters for a zone, you can add the
@ -866,8 +866,8 @@ roll over DNSKEYs to a new algorithm, e.g., from RSASHA1 (algorithm 5 or
care to avoid breaking DNSSEC validation.
If you are managing DNSSEC by using the ``dnssec-policy`` configuration,
``named`` handles the rollover for you. Simply change the algorithm
for the relevant keys, and ``named`` uses the new algorithm when the
:iscman:`named` handles the rollover for you. Simply change the algorithm
for the relevant keys, and :iscman:`named` uses the new algorithm when the
key is next rolled. It performs a smooth transition to the new
algorithm, ensuring that the zone remains valid throughout rollover.
@ -875,20 +875,20 @@ If you are using other methods to sign the zone, the administrator needs to do m
with other key rollovers, when the zone is a primary zone, an algorithm
rollover can be accomplished using dynamic updates or automatic key
rollovers. For secondary zones, only automatic key rollovers are
possible, but the ``dnssec-settime`` utility can be used to control the
possible, but the :iscman:`dnssec-settime` utility can be used to control the
timing.
In any case, the first step is to put DNSKEYs in place using the new algorithm.
You must generate the ``K*`` files for the new algorithm and put
them in the zone's key directory, where ``named`` can access them. Take
them in the zone's key directory, where :iscman:`named` can access them. Take
care to set appropriate ownership and permissions on the keys. If the
``auto-dnssec`` zone option is set to ``maintain``, ``named``
``auto-dnssec`` zone option is set to ``maintain``, :iscman:`named`
automatically signs the zone with the new keys, based on their timing
metadata when the ``dnssec-loadkeys-interval`` elapses or when you issue the
:option:`rndc loadkeys` command. Otherwise, for primary zones, you can use
``nsupdate`` to add the new DNSKEYs to the zone; this causes ``named``
:iscman:`nsupdate` to add the new DNSKEYs to the zone; this causes :iscman:`named`
to use them to sign the zone. For secondary zones, e.g., on a
"bump in the wire" signing server, ``nsupdate`` cannot be used.
"bump in the wire" signing server, :iscman:`nsupdate` cannot be used.
Once the zone has been signed by the new DNSKEYs (and you have waited
for at least one TTL period), you must inform the parent zone and any trust
@ -904,17 +904,17 @@ repositories. You must then allow another maximum TTL interval to elapse
so that the old DS records disappear from all resolver caches.
The next step is to remove the DNSKEYs using the old algorithm from your
zone. Again this can be accomplished using ``nsupdate`` to delete the
zone. Again this can be accomplished using :iscman:`nsupdate` to delete the
old DNSKEYs (for primary zones only) or by automatic key rollover when
``auto-dnssec`` is set to ``maintain``. You can cause the automatic key
rollover to take place immediately by using the ``dnssec-settime``
rollover to take place immediately by using the :iscman:`dnssec-settime`
utility to set the *Delete* date on all keys to any time in the past.
(See the :option:`dnssec-settime -D date/offset <dnssec-settime -D>` option.)
After adjusting the timing metadata, the :option:`rndc loadkeys` command
causes ``named`` to remove the DNSKEYs and
causes :iscman:`named` to remove the DNSKEYs and
RRSIGs for the old algorithm from the zone. Note also that with the
``nsupdate`` method, removing the DNSKEYs also causes ``named`` to
:iscman:`nsupdate` method, removing the DNSKEYs also causes :iscman:`named` to
remove the associated RRSIGs automatically.
Once you have verified that the old DNSKEYs and RRSIGs have been removed
@ -937,7 +937,7 @@ When you have both DNSSEC and dynamic updates in your environment,
updating zone data works the same way as with traditional (insecure)
DNS: you can use :option:`rndc freeze` before editing the zone file, and
:option:`rndc thaw` when you have finished editing, or you can use the
command ``nsupdate`` to add, edit, or remove records like this:
command :iscman:`nsupdate` to add, edit, or remove records like this:
::
@ -947,10 +947,10 @@ command ``nsupdate`` to add, edit, or remove records like this:
> send
> quit
The examples provided in this guide make ``named`` automatically
The examples provided in this guide make :iscman:`named` automatically
re-sign the zone whenever its content has changed. If you decide to sign
your own zone file manually, you need to remember to execute the
``dnssec-signzone`` command whenever your zone file has been updated.
:iscman:`dnssec-signzone` command whenever your zone file has been updated.
As far as system resources and performance are concerned, be mindful that
with a DNSSEC zone that changes frequently, every time the zone

4
doc/dnssec-guide/commonly-asked-questions.rst
View file

@ -147,7 +147,7 @@ Can I use the same key for multiple zones?
specific key rollover requirements) get their own key pairs, while other,
more "generic" zones can use a single key pair for easier management. Note that
at present (mid-2020), fully automatic signing (using the ``dnssec-policy``
clause in your ``named`` configuration file) does not support reuse of keys
clause in your :iscman:`named` configuration file) does not support reuse of keys
except when the same zone appears in multiple views (see next question).
To use the same key for multiple zones, sign your
zones using semi-automatic signing. Each zone wishing to use the key
@ -164,6 +164,6 @@ How do I sign the different instances of a zone that appears in multiple views?
Will there be any problems if I change the DNSSEC policy for a zone?
If you are using fully automatic signing, no. Just change the parameters in the
``dnssec-policy`` statement and reload the configuration file. ``named``
``dnssec-policy`` statement and reload the configuration file. :iscman:`named`
makes a smooth transition to the new policy, ensuring that your zone
remains valid at all times.

2
doc/dnssec-guide/getting-started.rst
View file

@ -26,7 +26,7 @@ BIND Version
Most configuration examples given in this document require BIND version
9.16.0 or newer (although many do work with all versions of BIND
later than 9.9). To check the version of ``named`` you have installed,
later than 9.9). To check the version of :iscman:`named` you have installed,
use the :option:`-v <named -v>` switch as shown below:
::

46
doc/dnssec-guide/recipes.rst
View file

@ -54,7 +54,7 @@ on them.
Using the method described in
:ref:`easy_start_guide_for_authoritative_servers`, we just need to
add a ``dnssec-policy`` statement to the relevant zone clause. This is
what the ``named.conf`` zone statement looks like on the primary server, 192.168.1.1:
what the :iscman:`named.conf` zone statement looks like on the primary server, 192.168.1.1:
::
@ -72,7 +72,7 @@ custom policy, define the policy in the configuration
file and select it in the zone statement (as described in
:ref:`signing_custom_policy`).
On the secondary servers, ``named.conf`` does not need to be updated,
On the secondary servers, :iscman:`named.conf` does not need to be updated,
and it looks like this:
::
@ -132,7 +132,7 @@ the parent zone. This server is configured as secondary to the hidden
primary 192.168.1.1 to receive the unsigned data; then, using keys
accessible to this middle box, to sign data on the fly; and finally, to send out the
signed data via zone transfer to the other three DNS secondaries. Its
``named.conf`` zone statement looks like this:
:iscman:`named.conf` zone statement looks like this:
::
@ -151,7 +151,7 @@ and use a custom policy.)
Finally, on the three secondary servers, the configuration should be updated
to receive a zone transfer from 192.168.1.5 (the middle box) instead of
from 192.168.1.1 (the hidden primary). If using BIND, the ``named.conf`` file looks
from 192.168.1.1 (the hidden primary). If using BIND, the :iscman:`named.conf` file looks
like this:
::
@ -172,7 +172,7 @@ section is not really relevant to you. In the policy statement, you set how long
you want your keys to be valid for, the time
taken for information to propagate through your zone, the time it takes
for your parent zone to register a new DS record, etc., and that's more
or less it. ``named`` implements everything for you automatically, apart from
or less it. :iscman:`named` implements everything for you automatically, apart from
uploading the new DS records to your parent zone - which is covered in
:ref:`signing_easy_start_upload_to_parent_zone`. (Some
screenshots from a session where a KSK is uploaded to the parent zone
@ -234,17 +234,17 @@ The first command gets us into the key directory
``/etc/bind/keys/example.com/``, where keys for ``example.com`` are
stored.
The second, ``dnssec-settime``, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1,
The second, :iscman:`dnssec-settime`, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1,
2021, and a deletion (:option:`-D <dnssec-settime -D>`) date of February 1, 2021, for the current ZSK
(``Kexample.com.+008+17694``).
The third command, ``dnssec-keygen``, creates a successor key, using
The third command, :iscman:`dnssec-keygen`, creates a successor key, using
the exact same parameters (algorithms, key sizes, etc.) as the current
ZSK. The new ZSK created in our example is ``Kexample.com.+008+51623``.
Make sure the successor keys are readable by ``named``.
Make sure the successor keys are readable by :iscman:`named`.
``named``'s logging messages indicate when the next
:iscman:`named`'s logging messages indicate when the next
key checking event is scheduled to occur, the frequency of which can be
controlled by ``dnssec-loadkeys-interval``. The log message looks like
this:
@ -376,9 +376,9 @@ One Month After ZSK Rollover
Again, technically there is nothing you need to do on this day,
but it doesn't hurt to verify that the old ZSK (17694) is now completely
gone from your zone. ``named`` will not touch
gone from your zone. :iscman:`named` will not touch
``Kexample.com.+008+17694.private`` and ``Kexample.com.+008+17694.key``
on your file system. Running the same ``dig`` command for DNSKEY should
on your file system. Running the same :iscman:`dig` command for DNSKEY should
suffice:
::
@ -487,21 +487,21 @@ The first command gets us into the key directory
``/etc/bind/keys/example.com/``, where keys for ``example.com`` are
stored.
The second, ``dnssec-settime``, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1,
The second, :iscman:`dnssec-settime`, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1,
2021, and a deletion (:option:`-D <dnssec-settime -D>`) date of February 1, 2021 for the current KSK
(``Kexample.com.+007+24848``).
The third command, ``dnssec-keygen``, creates a successor key, using
The third command, :iscman:`dnssec-keygen`, creates a successor key, using
the exact same parameters (algorithms, key sizes, etc.) as the current
KSK. The new key pair created in our example is ``Kexample.com.+007+23550``.
The fourth and final command, ``dnssec-dsfromkey``, creates a DS record
The fourth and final command, :iscman:`dnssec-dsfromkey`, creates a DS record
from the new KSK (23550), using SHA-1 as the digest type. Again, in
practice most people generate two DS records for both supported digest
types (SHA-1 and SHA-256), but for our example here we are only using
one to keep the output small and hopefully clearer.
Make sure the successor keys are readable by ``named``.
Make sure the successor keys are readable by :iscman:`named`.
The ``syslog`` message indicates when the next key
checking event is. The log message looks like this:
@ -691,7 +691,7 @@ One Month After KSK Rollover
++++++++++++++++++++++++++++
While the removal of the old DNSKEY from the zone should be automated by
``named``, the removal of the DS record is manual. You should make sure
:iscman:`named`, the removal of the DS record is manual. You should make sure
the old DNSKEY record is gone from your zone first, by querying for the
DNSKEY records of the zone; this time we expect not to see
the key with an ID of 24828:
@ -778,7 +778,7 @@ Migrating from NSEC to NSEC3
This recipe describes how to transition from using NSEC to NSEC3, as described
in :ref:`advanced_discussions_proof_of_nonexistence`. This recipe
assumes that the zones are already signed, and that ``named`` is configured
assumes that the zones are already signed, and that :iscman:`named` is configured
according to the steps described in
:ref:`easy_start_guide_for_authoritative_servers`.
@ -804,7 +804,7 @@ DNSSEC policy, using 10 iterations, no opt-out, and a random string that is
nsec3param iterations 10 optout no salt-length 16;
};
Then reconfigure the server with ``rndc``. You can tell that it worked if you
Then reconfigure the server with :iscman:`rndc`. You can tell that it worked if you
see the following debug log messages:
::
@ -873,7 +873,7 @@ The ``dnssec-policy`` currently has no easy way to re-salt using the
same salt length, so to change your NSEC3 salt you need to change the
``salt-length`` value and reconfigure your server. You should see
the following messages in the log, assuming your old salt was
"1234567890ABCDEF" and ``named`` created "FEDCBA09" (salt length 8)
"1234567890ABCDEF" and :iscman:`named` created "FEDCBA09" (salt length 8)
as the new salt:
::
@ -1000,7 +1000,7 @@ To undo NSEC3 opt-out, change the configuration again:
.. note::
NSEC3 hashes the plain text domain name, and we can compute our own
hashes using the tool ``nsec3hash``. For example, to compute the
hashes using the tool :iscman:`nsec3hash`. For example, to compute the
hashed name for ``www.example.com`` using the parameters we listed
above, we can execute this command:
@ -1073,7 +1073,7 @@ have cached information. After you are certain that all cached
information has expired (usually this means one TTL interval has passed),
you may reconfigure your zone.
Here is what ``named.conf`` looks like when it is signed:
Here is what :iscman:`named.conf` looks like when it is signed:
::
@ -1102,7 +1102,7 @@ the zone is still DNSSEC maintained, to allow for a graceful transition to
unsigned.
When the DS records have been removed from the parent zone, use
:option:`rndc dnssec -checkds -key id withdrawn example.com <rndc dnssec>` to tell ``named`` that
:option:`rndc dnssec -checkds -key id withdrawn example.com <rndc dnssec>` to tell :iscman:`named` that
the DS is removed, and the remaining DNSSEC records will be removed in a timely
manner. Or if you have parental agents configured, the DNSSEC records will be
automatically removed after BIND has seen that the parental agents no longer
@ -1112,6 +1112,6 @@ After a while, your zone is reverted back to the traditional, insecure DNS
format. You can verify by checking that all DNSKEY and RRSIG records have been
removed from the zone.
You can then remove the ``dnssec-policy`` line from your ``named.conf`` and
You can then remove the ``dnssec-policy`` line from your :iscman:`named.conf` and
reload the zone. The zone will now no longer be subject to any DNSSEC
maintenance.

104
doc/dnssec-guide/signing.rst
View file

@ -77,7 +77,7 @@ for most situations. We cover the creation of a custom policy in
:ref:`signing_custom_policy`, but for the moment we are accepting the
default values.
When the configuration file is updated, tell ``named`` to
When the configuration file is updated, tell :iscman:`named` to
reload the configuration file by running :option:`rndc reconfig`:
::
@ -116,7 +116,7 @@ in the published zone. The log file shows messages such as these:
It then starts signing the zone. How long this process takes depends on the
size of the zone, the speed of the server, and how much activity is
taking place. We can check what is happening by using ``rndc``,
taking place. We can check what is happening by using :iscman:`rndc`,
entering the command:
::
@ -138,9 +138,9 @@ and when it is finished:
When the second message appears, the zone is signed.
Before moving on to the next step of coordinating with the parent zone,
let's make sure everything looks good using ``delv``. We want to
let's make sure everything looks good using :iscman:`delv`. We want to
simulate what a validating resolver will check, by telling
``delv`` to use a specific trust anchor.
:iscman:`delv` to use a specific trust anchor.
First, we need to make a copy of the key created by BIND. This
is in the directory you set with the ``directory`` statement in
@ -171,7 +171,7 @@ it looks like this:
example.com. static-key 257 3 13 "6saiq99qDB...dqp+o0dw==";
};
Now we can run the ``delv`` command and instruct it to use this
Now we can run the :iscman:`delv` command and instruct it to use this
trusted-key file to validate the answer it receives from the
authoritative name server 192.168.1.13:
@ -241,7 +241,7 @@ correct format for their system.
example.com. 3600 IN DNSKEY 257 3 13 6saiq99qDB...dqp+o0dw==
The DS record format may be generated from the DNSKEY using the
``dnssec-dsfromkey`` tool, which is covered in
:iscman:`dnssec-dsfromkey` tool, which is covered in
:ref:`parent_ds_record_format`. For more details and examples on how
to work with your parent zone, please see
:ref:`working_with_parent_zone`.
@ -257,7 +257,7 @@ and published your DS record. Your zone is now officially
DNSSEC-enabled. What happens next? That is basically it - BIND
takes care of everything else. As for updating your zone file, you can
continue to update it the same way as prior to signing your
zone; the normal work flow of editing a zone file and using the ``rndc``
zone; the normal work flow of editing a zone file and using the :iscman:`rndc`
command to reload the zone still works as usual, and although you are
editing the unsigned version of the zone, BIND generates the signed
version automatically.
@ -471,7 +471,7 @@ least one corresponding signature, known as an RRSIG.
oq4yBQumOhO5WX61LjA17l1DuLWcd/ASwlUZWFGCYQ== )
The serial number was automatically incremented from the old, unsigned
version. ``named`` keeps track of the serial number of the signed version of
version. :iscman:`named` keeps track of the serial number of the signed version of
the zone independently of the unsigned version. If the unsigned zone is
updated with a new serial number that is higher than the one in the
signed copy, then the signed copy is increased to match it;
@ -482,7 +482,7 @@ otherwise, the two are kept separate.
Examine the Zone File
^^^^^^^^^^^^^^^^^^^^^
Our original zone file ``example.com.db`` remains untouched, and ``named`` has
Our original zone file ``example.com.db`` remains untouched, and :iscman:`named` has
generated three additional files automatically for us (shown below). The
signed DNS data is stored in ``example.com.db.signed`` and in the
associated journal file.
@ -495,14 +495,14 @@ associated journal file.
A quick description of each of the files:
- ``.jbk``: a transient file used by ``named``
- ``.jbk``: a transient file used by :iscman:`named`
- ``.signed``: the signed version of the zone in raw format
- ``.signed.jnl``: a journal file for the signed version of the zone
These files are stored in raw (binary) format for faster loading. To
reveal the human-readable version, use ``named-compilezone``
reveal the human-readable version, use :iscman:`named-compilezone`
as shown below. In the example below, we run the command on the
raw format zone ``example.com.db.signed`` to produce a text version of
the zone ``example.com.text``:
@ -662,7 +662,7 @@ Check with your parent zone to see which format they require.
But how can you get each of the formats from your existing data?
When ``named`` turned on automatic
When :iscman:`named` turned on automatic
DNSSEC maintenance, essentially the first thing it did was to create
the DNSSEC keys and put them in the directory you specified in the
configuration file. If you look in that directory, you will see three
@ -755,7 +755,7 @@ keys. The following is an example of such a clause:
The policy has multiple parts:
- The name must be specified. As each zone can use a different policy,
``named`` needs to be able to distinguish between policies. This is
:iscman:`named` needs to be able to distinguish between policies. This is
done by giving each policy a name, such as ``standard`` in the above
example.
@ -811,7 +811,7 @@ is to have a quick key roll but have users get validation failures
during the process.
Having defined a new policy called "standard", we now need to tell
``named`` to use it. We do this by adding a ``dnssec-policy standard;``
:iscman:`named` to use it. We do this by adding a ``dnssec-policy standard;``
statement to the configuration file. Like many other configuration
statements, it can be placed in the ``options`` statement (thus applying
to all zones on the server), a ``view`` statement (applying to all zones
@ -826,13 +826,13 @@ this example, we'll add it to the ``zone`` statement:
...
};
Finally, tell ``named`` to use the new policy:
Finally, tell :iscman:`named` to use the new policy:
::
# rndc reconfig
... and that's it. ``named`` now applies the "standard" policy to
... and that's it. :iscman:`named` now applies the "standard" policy to
your zone.
.. _signing_maintenance_tasks:
@ -918,7 +918,7 @@ includes the DS record identifying the key that is being rolled. If one or
both don't have the DS included yet the rollover is paused, and the check for
DS presence is retried after an hour. The same applies for DS withdrawal.
Alternatively, you can use the ``rndc`` tool to tell ``named`` that the DS
Alternatively, you can use the :iscman:`rndc` tool to tell :iscman:`named` that the DS
record has been published or withdrawn. For example:
::
@ -928,8 +928,8 @@ record has been published or withdrawn. For example:
If your parent zone doesn't support CDS/CDNSKEY, you will have to supply
the DNSKEY or DS record to the parent zone manually when a new KSK appears in
your zone, presumably using the same mechanism you used to upload the
records for the first time. Again, you need to use the ``rndc`` tool
to tell ``named`` that the DS record has been published.
records for the first time. Again, you need to use the :iscman:`rndc` tool
to tell :iscman:`named` that the DS record has been published.
.. [#]
For security reasons, a parent zone that supports CDS/CDNSKEY may require
@ -966,18 +966,18 @@ Manual
"Manual" signing was the first method to be introduced into BIND and
its name describes it perfectly: the user needs to do everything. In the
more-automated methods, you load an unsigned zone file into
``named``, which takes care of signing it. With manual signing, you
have to provide a signed zone for ``named`` to serve.
:iscman:`named`, which takes care of signing it. With manual signing, you
have to provide a signed zone for :iscman:`named` to serve.
In practice, this means creating an unsigned zone file as usual, then
using the BIND-provided tools ``dnssec-keygen`` to create the keys
and ``dnssec-signzone`` to sign the zone. The signed zone is stored
using the BIND-provided tools :iscman:`dnssec-keygen` to create the keys
and :iscman:`dnssec-signzone` to sign the zone. The signed zone is stored
in another file and is the one you tell BIND to load. To
update the zone (for example, to add a resource record), you update the
unsigned zone, re-sign it, and tell ``named`` to load the updated
unsigned zone, re-sign it, and tell :iscman:`named` to load the updated
signed copy. The same goes for refreshing signatures or rolling keys;
the user is responsible for providing the signed zone served by
``named``. (In the case of rolling keys, you are also responsible for
:iscman:`named`. (In the case of rolling keys, you are also responsible for
ensuring that the keys are added and removed at the correct times.)
Why would you want to sign your zone this way? You probably
@ -987,7 +987,7 @@ Manual
Semi-Automatic
The first step in DNSSEC automation came with BIND 9.7, when the
``auto-dnssec`` option was added. This causes ``named`` to
``auto-dnssec`` option was added. This causes :iscman:`named` to
periodically search the directory holding the key files (see
:ref:`generate_keys` for a description) and to
use the information in them to both add and remove keys and sign the
@ -995,10 +995,10 @@ Semi-Automatic
Use of ``auto-dnssec`` alone requires that the zone be dynamic,
something not suitable for a number of situations, so BIND 9.9 added the
``inline-signing`` option. With this, ``named`` essentially keeps the
``inline-signing`` option. With this, :iscman:`named` essentially keeps the
signed and unsigned copies of the zone separate. The signed zone is
created from the unsigned one using the key information; when the
unsigned zone is updated and the zone reloaded, ``named`` detects the
unsigned zone is updated and the zone reloaded, :iscman:`named` detects the
changes and updates the signed copy of the zone.
This mode of signing has been termed "semi-automatic" in this
@ -1021,7 +1021,7 @@ Fully Automatic with ``dnssec-keymgr``
(probably via ``cron``). It reads a DNSSEC policy from its
configuration file and reads timing information from the DNSSEC key
files. With this information it creates new key files with timing
information in them consistent with the policy. ``named`` is run as
information in them consistent with the policy. :iscman:`named` is run as
usual, picking up the timing information in the key files to
determine when to add and remove keys, and when to sign with them.
@ -1053,7 +1053,7 @@ Semi-Automatic Signing
As noted above, the term semi-automatic signing has been used in this
document to indicate the mode of signing enabled by the ``auto-dnssec``
and ``inline-signing`` keywords. ``named`` signs the zone without any
and ``inline-signing`` keywords. :iscman:`named` signs the zone without any
manual intervention, based purely on the timing information in the
DNSSEC key files. The files, however, must be created manually.
@ -1122,7 +1122,7 @@ This command generates four key files in ``/etc/bind/keys``:
The two files ending in ``.key`` are the public keys. These contain the
DNSKEY resource records that appear in the zone. The two files
ending in ``.private`` are the private keys, and contain the information
that ``named`` actually uses to sign the zone.
that :iscman:`named` actually uses to sign the zone.
Of the two pairs, one is the zone-signing key (ZSK), and one is the
key-signing key (KSK). We can tell which is which by looking at the file
@ -1160,7 +1160,7 @@ DNSKEY resource record. In
our example, 8 means the algorithm RSASHA256. Finally, the "keyid" is
essentially a hash of the key itself.
Make sure these files are readable by ``named`` and make sure that the
Make sure these files are readable by :iscman:`named` and make sure that the
``.private`` files are not readable by anyone else.
Refer to :ref:`system_entropy` for information on how to
@ -1172,13 +1172,13 @@ Setting Key Timing Information
You may remember that in the above description of this method, we said
that time information related to rolling keys is stored in the key
files. This is placed there by ``dnssec-keygen`` when the file is
created, and it can be modified using ``dnssec-settime``. By default,
files. This is placed there by :iscman:`dnssec-keygen` when the file is
created, and it can be modified using :iscman:`dnssec-settime`. By default,
only a limited amount of timing information is included in the file, as
illustrated in the examples in the previous section.
All the dates are the same, and are the date and time that
``dnssec-keygen`` created the key. We can use ``dnssec-settime`` to
:iscman:`dnssec-keygen` created the key. We can use :iscman:`dnssec-settime` to
modify the dates [#]_. For example, to publish this key in
the zone on 1 July 2020, use it to sign records for a year starting on
15 July 2020, and remove it from the zone at the end of July 2021, we
@ -1217,12 +1217,12 @@ one affects the signing of your zone:
copy of the new key in their cache before there are any resource
records signed with it. By default, if not specified at creation
time, this is set to the current time, meaning the key is
published as soon as ``named`` picks it up.
published as soon as :iscman:`named` picks it up.
3. *Activate*: This sets the date on which the key is to be activated. After
that date, resource records are signed with the key. By default,
if not specified during creation time, this is set to the current
time, meaning the key is used to sign data as soon as ``named``
time, meaning the key is used to sign data as soon as :iscman:`named`
picks it up.
4. *Revoke:* This sets the date on which the key is to be revoked. After that
@ -1277,7 +1277,7 @@ Sometime later it is activated and is used to sign resource records.
After a specified period, BIND stops using it to sign records, and at some
other specified later time it is removed from the zone.
Finally, we should note that the ``dnssec-keygen`` command supports the
Finally, we should note that the :iscman:`dnssec-keygen` command supports the
same set of switches so we could have set the dates
when we created the key.
@ -1288,7 +1288,7 @@ Reconfiguring BIND
Having created the keys with the appropriate timing information, the
next step is to turn on DNSSEC signing. Below is a very simple
``named.conf``; in our example environment, this file is
:iscman:`named.conf`; in our example environment, this file is
``/etc/bind/named.conf``.
::
@ -1306,7 +1306,7 @@ next step is to turn on DNSSEC signing. Below is a very simple
inline-signing yes;
};
Once the configuration file is updated, tell ``named`` to
Once the configuration file is updated, tell :iscman:`named` to
reload:
::
@ -1366,7 +1366,7 @@ Fully Automatic Signing With ``dnssec-keymgr``
information for existing keys with the defined policy, and adjusts it if
necessary. It also creates additional keys as required.
``dnssec-keymgr`` is completely separate from ``named``. As we will see,
``dnssec-keymgr`` is completely separate from :iscman:`named`. As we will see,
the policy states a coverage period; ``dnssec-keymgr`` generates
enough key files to handle all rollovers in that period. However, it is
a good idea to schedule it to run on a regular basis; that way there is
@ -1407,7 +1407,7 @@ example of such a file:
keyttl 300;
};
As can be seen, the syntax is similar to that of the ``named``
As can be seen, the syntax is similar to that of the :iscman:`named`
configuration file.
In the example above, we define a DNSSEC policy called "standard". Keys
@ -1417,7 +1417,7 @@ and placed in the directory ``/etc/bind``. KSKs have a key size of
zone 30 days before it becomes active, and is retained in the zone for
30 days after it is rolled. ZSKs have a key size of 2048 bits and roll
every 90 days; like the KSKs, the are added to the zone 30 days before
they are used for signing, and retained for 30 days after ``named``
they are used for signing, and retained for 30 days after :iscman:`named`
ceases signing with them.
The policy is applied to two zones, ``example.com`` and ``example.net``.
@ -1425,11 +1425,11 @@ The policy is applied unaltered to the former, but for the latter the
setting for the DNSKEY TTL has been overridden and set to 300 seconds.
To apply the policy, we need to run ``dnssec-keymgr``. Since this does
not read the ``named`` configuration file, it relies on the presence of
not read the :iscman:`named` configuration file, it relies on the presence of
at least one key file for a zone to tell it that the zone is
DNSSEC-enabled. If a key file does not already exist, we first need to create
one for each zone. We can do that either by running
``dnssec-keygen`` to create a key file for each zone [#]_, or by
:iscman:`dnssec-keygen` to create a key file for each zone [#]_, or by
specifying the zones in question on the command line. Here, we do the
latter:
@ -1525,12 +1525,12 @@ Fully Automatic Signing With ``dnssec-policy``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The latest development in DNSSEC key management appeared with BIND 9.16,
and is the full integration of key management into ``named``. Managing
and is the full integration of key management into :iscman:`named`. Managing
the signing process and rolling of these keys has been described in
:ref:`easy_start_guide_for_authoritative_servers` and is not
repeated here. A few points are worth noting, though:
- The ``dnssec-policy`` statement in the ``named`` configuration file
- The ``dnssec-policy`` statement in the :iscman:`named` configuration file
describes all aspects of the DNSSEC policy, including the signing.
With ``dnssec-keymgr``, this is split between two configuration files
and two programs.
@ -1561,7 +1561,7 @@ be useful for test purposes, so we cover it briefly here.
The first step is to create the keys as described in :ref:`generate_keys`.
Then, edit the zone file to make sure
the proper DNSKEY entries are included in your zone file. Finally, use the
command ``dnssec-signzone``:
command :iscman:`dnssec-signzone`:
::
@ -1589,7 +1589,7 @@ has three parameters: the unsigned zone name
also generates a plain text file ``/etc/bind/db/example.com.signed.db``,
which you can verify for correctness.
Finally, you'll need to update ``named.conf`` to load the signed version
Finally, you'll need to update :iscman:`named.conf` to load the signed version
of the zone, which looks something like this:
::
@ -1600,7 +1600,7 @@ of the zone, which looks something like this:
};
Once the :option:`rndc reconfig` command is issued, BIND serves a signed
zone. The file ``dsset-example.com`` (created by ``dnssec-signzone``
zone. The file ``dsset-example.com`` (created by :iscman:`dnssec-signzone`
when it signed the ``example.com`` zone) contains the DS record for the
zone's KSK. You will need to pass that to the administrator of the parent
zone, to be placed in the zone.
@ -1613,9 +1613,9 @@ appropriate times.
.. [#]
The dates can also be modified using an editor, but that is likely to
be more error-prone than using ``dnssec-settime``.
be more error-prone than using :iscman:`dnssec-settime`.
.. [#]
Only one key file - for either a KSK or ZSK - is needed to signal the
presence of the zone. ``dnssec-keygen`` creates files of both
presence of the zone. :iscman:`dnssec-keygen` creates files of both
types as needed.

24
doc/dnssec-guide/troubleshooting.rst
View file

@ -100,7 +100,7 @@ Visible DNSSEC Validation Symptoms
After determining the query path, it is necessary to
determine whether the problem is actually related to DNSSEC
validation. You can use the ``+cd`` flag in ``dig`` to disable
validation. You can use the ``+cd`` flag in :iscman:`dig` to disable
validation, as described in
:ref:`how_do_i_know_validation_problem`.
@ -132,7 +132,7 @@ server at 192.168.1.7:
;; WHEN: Wed Mar 18 15:12:49 GMT 2020
;; MSG SIZE rcvd: 72
With ``delv``, a "resolution failed" message is output instead:
With :iscman:`delv`, a "resolution failed" message is output instead:
::
@ -320,7 +320,7 @@ Next, we query for the DNSKEY and RRSIG of ``example.net`` to see if
there's anything wrong. Since we are having trouble validating, we
can use the ``+cd`` option to temporarily disable checking and return
results, even though they do not pass the validation tests. The
``+multiline`` option tells ``dig`` to print the type, algorithm type,
``+multiline`` option tells :iscman:`dig` to print the type, algorithm type,
and key id for DNSKEY records. Again,
some long strings are shortened for ease of display:
@ -404,7 +404,7 @@ Unable to Load Keys
^^^^^^^^^^^^^^^^^^^
This is a simple yet common issue. If the key files are present but
unreadable by ``named`` for some reason, the ``syslog`` returns clear error
unreadable by :iscman:`named` for some reason, the ``syslog`` returns clear error
messages, as shown below:
::
@ -435,7 +435,7 @@ reload`` with the key files missing from the key directory:
named[32516]: zone example.com/IN (signed): next key event: 27-Nov-2014 20:07:09.292
This happens to look exactly the same as if the keys were present and
readable, and appears to indicate that ``named`` loaded the keys and signed the zone. It
readable, and appears to indicate that :iscman:`named` loaded the keys and signed the zone. It
even generates the internal (raw) files:
::
@ -444,7 +444,7 @@ even generates the internal (raw) files:
# ls
example.com.db example.com.db.jbk example.com.db.signed
If ``named`` really loaded the keys and signed the zone, you should see
If :iscman:`named` really loaded the keys and signed the zone, you should see
the following files:
::
@ -462,7 +462,7 @@ Invalid Trust Anchors
^^^^^^^^^^^^^^^^^^^^^
In most cases, you never need to explicitly configure trust
anchors. ``named`` supplies the current root trust anchor and,
anchors. :iscman:`named` supplies the current root trust anchor and,
with the default setting of ``dnssec-validation``, updates it on the
infrequent occasions when it is changed.
@ -509,7 +509,7 @@ shows an example of querying a recursive server 10.53.0.3:
;; QUESTION SECTION:
;www.example.org. IN A
``delv`` shows a similar result:
:iscman:`delv` shows a similar result:
::
@ -540,7 +540,7 @@ BIND 9.11 introduced Negative Trust Anchors (NTAs) as a means to
*temporarily* disable DNSSEC validation for a zone when you know that
the zone's DNSSEC is misconfigured.
NTAs are added using the ``rndc`` command, e.g.:
NTAs are added using the :iscman:`rndc` command, e.g.:
::
@ -549,7 +549,7 @@ NTAs are added using the ``rndc`` command, e.g.:
The list of currently configured NTAs can also be examined using
``rndc``, e.g.:
:iscman:`rndc`, e.g.:
::
@ -561,7 +561,7 @@ The default lifetime of an NTA is one hour, although by default, BIND
polls the zone every five minutes to see if the zone correctly
validates, at which point the NTA automatically expires. Both the
default lifetime and the polling interval may be configured via
``named.conf``, and the lifetime can be overridden on a per-zone basis
:iscman:`named.conf`, and the lifetime can be overridden on a per-zone basis
using the ``-lifetime duration`` parameter to ``rndc nta``. Both timer
values have a permitted maximum value of one week.
@ -570,7 +570,7 @@ values have a permitted maximum value of one week.
NSEC3 Troubleshooting
~~~~~~~~~~~~~~~~~~~~~
BIND includes a tool called ``nsec3hash`` that runs through the same
BIND includes a tool called :iscman:`nsec3hash` that runs through the same
steps as a validating resolver, to generate the correct hashed name
based on NSEC3PARAM parameters. The command takes the following
parameters in order: salt, algorithm, iterations, and domain. For

28
doc/dnssec-guide/validation.rst
View file

@ -50,7 +50,7 @@ add one line to the ``options`` section of your configuration file:
...
};
Restart ``named`` or run :option:`rndc reconfig`, and your recursive server is
Restart :iscman:`named` or run :option:`rndc reconfig`, and your recursive server is
now happily validating each DNS response. If this does not work for you,
and you have already verified DNSSEC support as described in
:ref:`dnssec_support_in_bind`, you may have some other
@ -120,28 +120,28 @@ confirm that it is in fact validating DNS responses.
.. _using_dig_to_verify:
Using ``dig`` to Verify
^^^^^^^^^^^^^^^^^^^^^^^
Using :iscman:`dig` to Verify
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Web-based DNSSEC-verification tools often employ JavaScript. If you don't trust the
JavaScript magic that the web-based tools rely on, you can take matters
into your own hands and use a command-line DNS tool to check your
validating resolver yourself.
While ``nslookup`` is popular, partly because it comes pre-installed on
most systems, it is not DNSSEC-aware. ``dig``, on the other hand, fully
While :iscman:`nslookup` is popular, partly because it comes pre-installed on
most systems, it is not DNSSEC-aware. :iscman:`dig`, on the other hand, fully
supports the DNSSEC standard and comes as a part of BIND. If you do not
have ``dig`` already installed on your system, install it by downloading
have :iscman:`dig` already installed on your system, install it by downloading
it from ISC's `website <https://www.isc.org/download>`__. ISC provides pre-compiled
Windows versions on its website.
``dig`` is a flexible tool for interrogating DNS name servers. It
:iscman:`dig` is a flexible tool for interrogating DNS name servers. It
performs DNS lookups and displays the answers that are returned from the
name servers that were queried. Most seasoned DNS administrators use
``dig`` to troubleshoot DNS problems because of its flexibility, ease of
:iscman:`dig` to troubleshoot DNS problems because of its flexibility, ease of
use, and clarity of output.
The example below shows how to use ``dig`` to query the name server 10.53.0.1
The example below shows how to use :iscman:`dig` to query the name server 10.53.0.1
for the A record for ``ftp.isc.org`` when DNSSEC validation is enabled
(i.e. the default). The address 10.53.0.1 is only used as an example;
replace it with the actual address or host name of your
@ -202,7 +202,7 @@ file, i.e.:
};
If the server is restarted (to ensure a clean cache) and the same
``dig`` command executed, the result is very similar:
:iscman:`dig` command executed, the result is very similar:
::
@ -234,7 +234,7 @@ If the server is restarted (to ensure a clean cache) and the same
;; MSG SIZE rcvd: 187
However, this time there is no ``ad`` flag in the header. Although
``dig`` is still returning the DNSSEC-related resource records, it is
:iscman:`dig` is still returning the DNSSEC-related resource records, it is
not checking them, and thus cannot vouch for the authenticity of the answer.
If you do carry out this test, remember to re-enable DNSSEC validation
(by removing the ``dnssec-validation no;`` line from the configuration
@ -324,7 +324,7 @@ How Do I Know I Have a Validation Problem?
Since all DNSSEC validation failures result in a general ``SERVFAIL``
message, how do we know if it was really a validation error?
Fortunately, there is a flag in ``dig``, (``+cd``, for "checking
Fortunately, there is a flag in :iscman:`dig`, (``+cd``, for "checking
disabled") which tells the server to disable DNSSEC validation. If
you receive a ``SERVFAIL`` message, re-run the query a second time
and set the ``+cd`` flag. If the query succeeds with ``+cd``, but
@ -769,8 +769,8 @@ EDNS on DNS Servers
For many years, BIND has had EDNS enabled by default,
and the UDP packet size is set to a maximum of 4096 bytes. The DNS
administrator should not need to perform any reconfiguration. You can
use ``dig`` to verify that your server supports EDNS and see the UDP packet
size it allows with this ``dig`` command:
use :iscman:`dig` to verify that your server supports EDNS and see the UDP packet
size it allows with this :iscman:`dig` command:
::

2
doc/man/named.conf.5in
View file

@ -35,7 +35,7 @@ named.conf \- configuration file for **named**
\fBnamed.conf\fP
.SH DESCRIPTION
.sp
\fBnamed.conf\fP is the configuration file for \fBnamed\fP\&. Statements are
\fI\%named.conf\fP is the configuration file for \fBnamed\fP\&. Statements are
enclosed in braces and terminated with a semi\-colon. Clauses in the
statements are also semi\-colon terminated. The usual comment styles are
supported:

4
doc/man/rndc.8in
View file

@ -602,8 +602,8 @@ there is no explicit root zone configured.
.B stop \-p
This command stops the server, making sure any recent changes made through dynamic
update or IXFR are first saved to the master files of the updated
zones. If \fB\-p\fP is specified, \fBnamed(8)\(ga\(aqs process ID is returned.
This allows an external process to determine when \(ga\(ganamed\fP has
zones. If \fB\-p\fP is specified, \fBnamed\fP\(aqs process ID is returned.
This allows an external process to determine when \fBnamed\fP has
completed stopping.
.sp
See also \fI\%rndc halt\fP\&.

6
doc/notes/notes-current.rst
View file

@ -31,7 +31,7 @@ Removed Features
~~~~~~~~~~~~~~~~
- The IPv6 sockets are now explicitly restricted to sending and receiving IPv6
packets only. This renders the ``dig`` option ``+mapped`` non-functioning and
packets only. This renders the :iscman:`dig` option ``+mapped`` non-functioning and
thus the option has been removed. :gl:`#3093`
Feature Changes
@ -53,7 +53,7 @@ Feature Changes
Bug Fixes
~~~~~~~~~
- With libuv >= 1.37.0, the recvmmsg support would not be enabled in ``named``
- With libuv >= 1.37.0, the recvmmsg support would not be enabled in :iscman:`named`
reducing the maximum query-response performance. The recvmmsg support would
be used only in libuv 1.35.0 and 1.36.0. This has been fixed. :gl:`#3095`
@ -68,7 +68,7 @@ Bug Fixes
change in the previous release. This has been fixed. :gl:`#3111`
- An error in the processing of the ``blackhole`` ACL could cause some DNS
requests sent by ``named`` to fail - for example, zone transfer requests
requests sent by :iscman:`named` to fail - for example, zone transfer requests
and SOA refresh queries - if the destination address or prefix was
specifically excluded from the ACL using ``!``, or if the ACL was set
to ``none``. ``blackhole`` worked correctly when it was left unset, or