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

Merge branch 'pspacek/manpage-hyperlinks' into 'main'

Browse source 
Add hyperlinks to manual pages

See merge request isc-projects/bind9!5934
This commit is contained in:
Petr Špaček 2022-03-14 09:53:02 +00:00
commit 49d2a12e7c
109 changed files with 4274 additions and 2550 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: named-checkconf
.. program:: named-checkconf
.. _man_named-checkconf:
named-checkconf - named configuration file syntax checking tool
@ -24,72 +26,83 @@ Synopsis
Description
~~~~~~~~~~~
``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
:program:`named-checkconf` checks the syntax, but not the semantics, of a
: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
``named-checkconf``. Configuration errors in these files may cause
``named`` to fail to run, even if ``named-checkconf`` was successful.
However, ``named-checkconf`` can be run on these files explicitly.
:program:`named-checkconf`. Configuration errors in these files may cause
: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
~~~~~~~
``-h``
.. option:: -h
This option prints the usage summary and exits.
``-j``
When loading a zonefile, this option instructs ``named`` to read the journal if it exists.
.. option:: -j
When loading a zonefile, this option instructs :iscman:`named` to read the journal if it exists.
.. option:: -l
``-l``
This option lists all the configured zones. Each line of output contains the zone
name, class (e.g. IN), view, and type (e.g. primary or secondary).
``-c``
.. option:: -c
This option specifies that only the "core" configuration should be checked. This suppresses the loading of
plugin modules, and causes all parameters to ``plugin`` statements to
be ignored.
``-i``
.. option:: -i
This option ignores warnings on deprecated options.
``-p``
This option prints out the ``named.conf`` and included files in canonical form if
no errors were detected. See also the ``-x`` option.
.. option:: -p
``-t directory``
This option instructs ``named`` to chroot to ``directory``, so that ``include`` directives in the
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 :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`.
``-v``
This option prints the version of the ``named-checkconf`` program and exits.
.. option:: -v
This option prints the version of the :program:`named-checkconf` program and exits.
.. option:: -x
``-x``
When printing the configuration files in canonical form, this option obscures
shared secrets by replacing them with strings of question marks
(``?``). This allows the contents of ``named.conf`` and related files
(``?``). 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
``-p``.
:option:`-p`.
``-z``
This option performs a test load of all zones of type ``primary`` found in ``named.conf``.
.. option:: -z
This option performs a test load of all zones of type ``primary`` found in :iscman:`named.conf`.
.. option:: filename
``filename``
This indicates the name of the configuration file to be checked. If not specified,
it defaults to |named_conf|.
Return Values
~~~~~~~~~~~~~
``named-checkconf`` returns an exit status of 1 if errors were detected
:program:`named-checkconf` returns an exit status of 1 if errors were detected
and 0 otherwise.
See Also
~~~~~~~~
:manpage:`named(8)`, :manpage:`named-checkzone(8)`, BIND 9 Administrator Reference Manual.
:iscman:`named(8) <named>`, :iscman:`named-checkzone(8) <named-checkzone>`, BIND 9 Administrator Reference Manual.

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

@ -13,6 +13,8 @@
.. BEWARE: Do not forget to edit also named-compilezone.rst!
.. iscman:: named-checkzone
.. program:: named-checkzone
.. _man_named-checkzone:
named-checkzone - zone file validation tool
@ -26,40 +28,48 @@ Synopsis
Description
~~~~~~~~~~~
``named-checkzone`` checks the syntax and integrity of a zone file. It
performs the same checks as ``named`` does when loading a zone. This
makes ``named-checkzone`` useful for checking zone files before
:program:`named-checkzone` checks the syntax and integrity of a zone file. It
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.
Options
~~~~~~~
``-d``
.. option:: -d
This option enables debugging.
``-h``
.. option:: -h
This option prints the usage summary and exits.
``-q``
.. option:: -q
This option sets quiet mode, which only sets an exit code to indicate
successful or failed completion.
``-v``
This option prints the version of the ``named-checkzone`` program and exits.
.. option:: -v
``-j``
When loading a zone file, this option tells ``named`` to read the journal if it exists. The journal
This option prints the version of the :program:`named-checkzone` program and exits.
.. option:: -j
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.
``-J filename``
When loading the zone file, this option tells ``named`` to read the journal from the given file, if
it exists. This implies ``-j``.
.. option:: -J filename
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
``-c class``
This option specifies the class of the zone. If not specified, ``IN`` is assumed.
``-i mode``
.. option:: -i mode
This option performs post-load zone integrity checks. Possible modes are
``full`` (the default), ``full-sibling``, ``local``,
``local-sibling``, and ``none``.
@ -85,59 +95,70 @@ Options
Mode ``none`` disables the checks.
``-f format``
.. option:: -f format
This option specifies the format of the zone file. Possible formats are
``text`` (the default), and ``raw``.
``-F format``
.. option:: -F format
This option specifies the format of the output file specified. For
``named-checkzone``, this does not have any effect unless it dumps
:program:`named-checkzone`, this does not have any effect unless it dumps
the zone contents.
Possible formats are ``text`` (the default), which is the standard
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.
``-k mode``
.. option:: -k mode
This option performs ``check-names`` checks with the specified failure mode.
Possible modes are ``fail``, ``warn`` (the default), and ``ignore``.
``-l ttl``
.. option:: -l ttl
This option sets a maximum permissible TTL for the input file. Any record with a
TTL higher than this value causes the zone to be rejected. This
is similar to using the ``max-zone-ttl`` option in ``named.conf``.
is similar to using the ``max-zone-ttl`` option in :iscman:`named.conf`.
.. option:: -L serial
``-L serial``
When compiling a zone to ``raw`` format, this option sets the "source
serial" value in the header to the specified serial number. This is
expected to be used primarily for testing purposes.
``-m mode``
.. option:: -m mode
This option specifies whether MX records should be checked to see if they are
addresses. Possible modes are ``fail``, ``warn`` (the default), and
``ignore``.
``-M mode``
.. option:: -M mode
This option checks whether a MX record refers to a CNAME. Possible modes are
``fail``, ``warn`` (the default), and ``ignore``.
``-n mode``
.. option:: -n mode
This option specifies whether NS records should be checked to see if they are
addresses. Possible modes are ``fail``, ``warn`` (the default), and ``ignore``.
``-o filename``
.. option:: -o filename
This option writes the zone output to ``filename``. If ``filename`` is ``-``, then
the zone output is written to standard output.
``-r mode``
.. option:: -r mode
This option checks for records that are treated as different by DNSSEC but are
semantically equal in plain DNS. Possible modes are ``fail``,
``warn`` (the default), and ``ignore``.
``-s style``
.. option:: -s style
This option specifies the style of the dumped zone file. Possible styles are
``full`` (the default) and ``relative``. The ``full`` format is most
suitable for processing automatically by a separate script.
@ -146,48 +167,56 @@ Options
the zone contents. It also does not have any meaning if the output format
is not text.
``-S mode``
.. option:: -S mode
This option checks whether an SRV record refers to a CNAME. Possible modes are
``fail``, ``warn`` (the default), and ``ignore``.
``-t directory``
This option tells ``named`` to chroot to ``directory``, so that ``include`` directives in the
configuration file are processed as if run by a similarly chrooted
``named``.
.. option:: -t directory
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
:iscman:`named`.
.. option:: -T mode
``-T mode``
This option checks whether Sender Policy Framework (SPF) records exist and issues a
warning if an SPF-formatted TXT record is not also present. Possible
modes are ``warn`` (the default) and ``ignore``.
``-w directory``
This option instructs ``named`` to chdir to ``directory``, so that relative filenames in master file
``$INCLUDE`` directives work. This is similar to the directory clause in
``named.conf``.
.. option:: -w directory
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
:iscman:`named.conf`.
.. option:: -D
``-D``
This option dumps the zone file in canonical format.
``-W mode``
.. option:: -W mode
This option specifies whether to check for non-terminal wildcards. Non-terminal
wildcards are almost always the result of a failure to understand the
wildcard matching algorithm (:rfc:`4592`). Possible modes are ``warn``
(the default) and ``ignore``.
``zonename``
.. option:: zonename
This indicates the domain name of the zone being checked.
``filename``
.. option:: filename
This is the name of the zone file.
Return Values
~~~~~~~~~~~~~
``named-checkzone`` returns an exit status of 1 if errors were detected
:program:`named-checkzone` returns an exit status of 1 if errors were detected
and 0 otherwise.
See Also
~~~~~~~~
:manpage:`named(8)`, :manpage:`named-checkconf(8)`, :manpage:`named-compilezone(8)`,
:rfc:`1035`, BIND 9 Administrator Reference Manual.
:iscman:`named(8) <named>`, :iscman:`named-checkconf(8) <named-checkconf>`, :iscman:`named-compilezone(8) <named-compilezone>`, :rfc:`1035`, BIND 9 Administrator Reference
Manual.

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

@ -13,6 +13,8 @@
.. BEWARE: Do not forget to edit also named-checkzone.rst!
.. iscman:: named-compilezone
.. program:: named-compilezone
.. _man_named-compilezone:
named-compilezone - zone file converting tool
@ -26,42 +28,50 @@ Synopsis
Description
~~~~~~~~~~~
``named-compilezone`` checks the syntax and integrity of a zone file,
:program:`named-compilezone` checks the syntax and integrity of a zone file,
and dumps the zone contents to a specified file in a specified format.
It applies strict check levels by default, since the
dump output is used as an actual zone file loaded by ``named``.
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
~~~~~~~
``-d``
.. option:: -d
This option enables debugging.
``-h``
.. option:: -h
This option prints the usage summary and exits.
``-q``
.. option:: -q
This option sets quiet mode, which only sets an exit code to indicate
successful or failed completion.
``-v``
This option prints the version of the ``named-checkzone`` program and exits.
.. option:: -v
``-j``
When loading a zone file, this option tells ``named`` to read the journal if it exists. The journal
This option prints the version of the :iscman:`named-checkzone` program and exits.
.. option:: -j
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.
``-J filename``
When loading the zone file, this option tells ``named`` to read the journal from the given file, if
it exists. This implies ``-j``.
.. option:: -J filename
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
``-c class``
This option specifies the class of the zone. If not specified, ``IN`` is assumed.
``-i mode``
.. option:: -i mode
This option performs post-load zone integrity checks. Possible modes are
``full`` (the default), ``full-sibling``, ``local``,
``local-sibling``, and ``none``.
@ -87,109 +97,128 @@ Options
Mode ``none`` disables the checks.
``-f format``
.. option:: -f format
This option specifies the format of the zone file. Possible formats are
``text`` (the default), and ``raw``.
``-F format``
.. option:: -F format
This option specifies the format of the output file specified. For
``named-checkzone``, this does not have any effect unless it dumps
: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.
``-k mode``
.. option:: -k mode
This option performs ``check-names`` checks with the specified failure mode.
Possible modes are ``fail`` (the default), ``warn``, and ``ignore``.
``-l ttl``
.. option:: -l ttl
This option sets a maximum permissible TTL for the input file. Any record with a
TTL higher than this value causes the zone to be rejected. This
is similar to using the ``max-zone-ttl`` option in ``named.conf``.
is similar to using the ``max-zone-ttl`` option in :iscman:`named.conf`.
.. option:: -L serial
``-L serial``
When compiling a zone to ``raw`` format, this option sets the "source
serial" value in the header to the specified serial number. This is
expected to be used primarily for testing purposes.
``-m mode``
.. option:: -m mode
This option specifies whether MX records should be checked to see if they are
addresses. Possible modes are ``fail``, ``warn`` (the default), and
``ignore``.
``-M mode``
.. option:: -M mode
This option checks whether a MX record refers to a CNAME. Possible modes are
``fail``, ``warn`` (the default), and ``ignore``.
``-n mode``
.. option:: -n mode
This option specifies whether NS records should be checked to see if they are
addresses. Possible modes are ``fail`` (the default), ``warn``, and
``ignore``.
``-o filename``
This option writes the zone output to ``filename``. If ``filename`` is ``-``, then
the zone output is written to standard output. This is mandatory for ``named-compilezone``.
.. option:: -o filename
This option writes the zone output to ``filename``. If ``filename`` is ``-``, then
the zone output is written to standard output. This is mandatory for :program:`named-compilezone`.
.. option:: -r mode
``-r mode``
This option checks for records that are treated as different by DNSSEC but are
semantically equal in plain DNS. Possible modes are ``fail``,
``warn`` (the default), and ``ignore``.
``-s style``
.. option:: -s style
This option specifies the style of the dumped zone file. Possible styles are
``full`` (the default) and ``relative``. The ``full`` format is most
suitable for processing automatically by a separate script.
The relative format is more human-readable and is thus
suitable for editing by hand.
``-S mode``
.. option:: -S mode
This option checks whether an SRV record refers to a CNAME. Possible modes are
``fail``, ``warn`` (the default), and ``ignore``.
``-t directory``
This option tells ``named`` to chroot to ``directory``, so that ``include`` directives in the
configuration file are processed as if run by a similarly chrooted
``named``.
.. option:: -t directory
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
:iscman:`named`.
.. option:: -T mode
``-T mode``
This option checks whether Sender Policy Framework (SPF) records exist and issues a
warning if an SPF-formatted TXT record is not also present. Possible
modes are ``warn`` (the default) and ``ignore``.
``-w directory``
This option instructs ``named`` to chdir to ``directory``, so that relative filenames in master file
.. option:: -w directory
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
``-D``
This option dumps the zone file in canonical format. This is always enabled for
``named-compilezone``.
:program:`named-compilezone`.
.. option:: -W mode
``-W mode``
This option specifies whether to check for non-terminal wildcards. Non-terminal
wildcards are almost always the result of a failure to understand the
wildcard matching algorithm (:rfc:`4592`). Possible modes are ``warn``
(the default) and ``ignore``.
``zonename``
.. option:: zonename
This indicates the domain name of the zone being checked.
``filename``
.. option:: filename
This is the name of the zone file.
Return Values
~~~~~~~~~~~~~
``named-compilezone`` returns an exit status of 1 if errors were detected
:program:`named-compilezone` returns an exit status of 1 if errors were detected
and 0 otherwise.
See Also
~~~~~~~~
:manpage:`named(8)`, :manpage:`named-checkconf(8)`, :manpage:`named-checkzone(8)`,
:rfc:`1035`, BIND 9 Administrator Reference Manual.
:iscman:`named(8) <named>`, :iscman:`named-checkconf(8) <named-checkconf>`, :iscman:`named-checkzone(8) <named-checkzone>`, `:rfc:`1035`,
BIND 9 Administrator Reference Manual.

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

@ -13,6 +13,8 @@
.. BEWARE: Do not forget to edit also tsig-keygen.rst!
.. iscman:: ddns-confgen
.. program:: ddns-confgen
.. _man_ddns-confgen:
ddns-confgen - TSIG key generation tool
@ -25,64 +27,70 @@ Synopsis
Description
~~~~~~~~~~~
``ddns-confgen`` is an utility that generates keys for use in TSIG signing.
:program:`ddns-confgen` is an utility that generates keys for use in TSIG signing.
The resulting keys can be used, for example, to secure dynamic DNS updates
to a zone, or for the ``rndc`` command channel.
to a zone, or for the :iscman:`rndc` command channel.
The key name can specified using ``-k`` parameter and defaults to ``ddns-key``.
The key name can specified using :option:`-k` parameter and defaults to ``ddns-key``.
The generated key is accompanied by configuration text and instructions that
can be used with ``nsupdate`` and ``named`` when setting up dynamic DNS,
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
``nsupdate -l``; it does this when a zone is configured with
``update-policy local;``. ``ddns-confgen`` is only needed when a more
elaborate configuration is required: for instance, if ``nsupdate`` is to
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 :iscman:`nsupdate` is to
be used from a remote system.
Options
~~~~~~~
``-a algorithm``
.. option:: -a algorithm
This option specifies the algorithm to use for the TSIG key. Available
choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384,
and hmac-sha512. The default is hmac-sha256. Options are
case-insensitive, and the "hmac-" prefix may be omitted.
``-h``
.. option:: -h
This option prints a short summary of options and arguments.
``-k keyname``
.. option:: -k keyname
This option specifies the key name of the DDNS authentication key. The
default is ``ddns-key`` when neither the ``-s`` nor ``-z`` option is
default is ``ddns-key`` when neither the :option:`-s` nor :option:`-z` option is
specified; otherwise, the default is ``ddns-key`` as a separate label
followed by the argument of the option, e.g., ``ddns-key.example.com.``
The key name must have the format of a valid domain name, consisting of
letters, digits, hyphens, and periods.
``-q``
.. option:: -q
This option enables quiet mode, which prints only the key, with no
explanatory text or usage examples. This is essentially identical to
``tsig-keygen``.
:iscman:`tsig-keygen`.
.. option:: -s name
``-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
name. This option cannot be used with the ``-z`` option.
name. This option cannot be used with the :option:`-z` option.
.. option:: -z zone
``-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 ``-s`` option.
This option cannot be used with the :option:`-s` option.
See Also
~~~~~~~~
:manpage:`nsupdate(1)`, :manpage:`named.conf(5)`, :manpage:`named(8)`, BIND 9 Administrator Reference Manual.
:iscman:`nsupdate(1) <nsupdate>`, :iscman:`named.conf(5) <named.conf>`, :iscman:`named(8) <named>`, BIND 9 Administrator Reference Manual.

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: rndc-confgen
.. program:: rndc-confgen
.. _man_rndc-confgen:
rndc-confgen - rndc key generation tool
@ -24,85 +26,96 @@ Synopsis
Description
~~~~~~~~~~~
``rndc-confgen`` generates configuration files for ``rndc``. It can be
used as a convenient alternative to writing the ``rndc.conf`` file and
the corresponding ``controls`` and ``key`` statements in ``named.conf``
by hand. Alternatively, it can be run with the ``-a`` option to set up a
``rndc.key`` file and avoid the need for a ``rndc.conf`` file and a
: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 :iscman:`rndc.conf` file and a
``controls`` statement altogether.
Options
~~~~~~~
``-a``
This option sets automatic ``rndc`` configuration, which creates a file
|rndc_key| that is read by both ``rndc`` and ``named`` on startup.
.. option:: -a
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
``rndc-confgen -a`` is required, for example if rndc is to be used
remotely, run ``rndc-confgen`` without the ``-a`` option
and set up ``rndc.conf`` and ``named.conf`` as directed.
: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 :iscman:`rndc.conf` and :iscman:`named.conf` as directed.
.. option:: -A algorithm
``-A algorithm``
This option specifies the algorithm to use for the TSIG key. Available choices
are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, and
hmac-sha512. The default is hmac-sha256.
``-b keysize``
.. option:: -b keysize
This option specifies the size of the authentication key in bits. The size must be between
1 and 512 bits; the default is the hash size.
``-c keyfile``
This option is used with the ``-a`` option to specify an alternate location for
.. option:: -c keyfile
This option is used with the :option:`-a` option to specify an alternate location for
``rndc.key``.
``-h``
This option prints a short summary of the options and arguments to
``rndc-confgen``.
.. option:: -h
``-k keyname``
This option specifies the key name of the ``rndc`` authentication key. This must be a
This option prints a short summary of the options and arguments to
:program:`rndc-confgen`.
.. option:: -k keyname
This option specifies the key name of the :iscman:`rndc` authentication key. This must be a
valid domain name. The default is ``rndc-key``.
``-p port``
This option specifies the command channel port where ``named`` listens for
connections from ``rndc``. The default is 953.
.. option:: -p port
This option specifies the command channel port where :iscman:`named` listens for
connections from :iscman:`rndc`. The default is 953.
.. option:: -q
``-q``
This option prevets printing the written path in automatic configuration mode.
``-s address``
This option specifies the IP address where ``named`` listens for command-channel
connections from ``rndc``. The default is the loopback address
.. option:: -s 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.
``-t chrootdir``
This option is used with the ``-a`` option to specify a directory where ``named``
.. option:: -t chrootdir
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`.
``-u user``
This option is used with the ``-a`` option to set the owner of the generated ``rndc.key`` file.
If ``-t`` is also specified, only the file in the chroot
.. option:: -u user
This option is used with the :option:`-a` option to set the owner of the generated ``rndc.key`` file.
If :option:`-t` is also specified, only the file in the chroot
area has its owner changed.
Examples
~~~~~~~~
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:
``rndc-confgen``
:program:`rndc-confgen`
See Also
~~~~~~~~
:manpage:`rndc(8)`, :manpage:`rndc.conf(5)`, :manpage:`named(8)`, BIND 9 Administrator Reference Manual.
:iscman:`rndc(8) <rndc>`, :iscman:`rndc.conf(5) <rndc.conf>`, :iscman:`named(8) <named>`, BIND 9 Administrator Reference Manual.

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

@ -13,6 +13,8 @@
.. BEWARE: Do not forget to edit also ddns-confgen.rst!
.. iscman:: tsig-keygen
.. program:: tsig-keygen
.. _man_tsig-keygen:
tsig-keygen - TSIG key generation tool
@ -25,9 +27,9 @@ Synopsis
Description
~~~~~~~~~~~
``tsig-keygen`` is an utility that generates keys for use in TSIG signing.
:program:`tsig-keygen` is an utility that generates keys for use in TSIG signing.
The resulting keys can be used, for example, to secure dynamic DNS updates
to a zone, or for the ``rndc`` command channel.
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``.
@ -35,16 +37,18 @@ of the generated key. If no name is specified, the default is ``tsig-key``.
Options
~~~~~~~
``-a algorithm``
.. option:: -a algorithm
This option specifies the algorithm to use for the TSIG key. Available
choices are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384,
and hmac-sha512. The default is hmac-sha256. Options are
case-insensitive, and the "hmac-" prefix may be omitted.
``-h``
.. option:: -h
This option prints a short summary of options and arguments.
See Also
~~~~~~~~
:manpage:`nsupdate(1)`, :manpage:`named.conf(5)`, :manpage:`named(8)`, BIND 9 Administrator Reference Manual.
:iscman:`nsupdate(1) <nsupdate>`, :iscman:`named.conf(5) <named.conf>`, :iscman:`named(8) <named>`, BIND 9 Administrator Reference Manual.

200
bin/delv/delv.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: delv
.. program:: delv
.. _man_delv:
delv - DNS lookup and validation utility
@ -30,10 +32,10 @@ Synopsis
Description
~~~~~~~~~~~
``delv`` is a tool for sending DNS queries and validating the results,
using the same internal resolver and validator logic as ``named``.
:program:`delv` is a tool for sending DNS queries and validating the results,
using the same internal resolver and validator logic as :iscman:`named`.
``delv`` sends to a specified name server all queries needed to
:program:`delv` sends to a specified name server all queries needed to
fetch and validate the requested data; this includes the original
requested query, subsequent queries to follow CNAME or DNAME chains,
queries for DNSKEY, and DS records to establish a chain of trust for
@ -42,25 +44,25 @@ simulates the behavior of a name server configured for DNSSEC validating
and forwarding.
By default, responses are validated using the built-in DNSSEC trust anchor
for the root zone ("."). Records returned by ``delv`` are either fully
for the root zone ("."). Records returned by :program:`delv` are either fully
validated or were not signed. If validation fails, an explanation of the
failure is included in the output; the validation process can be traced
in detail. Because ``delv`` does not rely on an external server to carry
in detail. Because :program:`delv` does not rely on an external server to carry
out validation, it can be used to check the validity of DNS responses in
environments where local name servers may not be trustworthy.
Unless it is told to query a specific name server, ``delv`` tries
Unless it is told to query a specific name server, :program:`delv` tries
each of the servers listed in ``/etc/resolv.conf``. If no usable server
addresses are found, ``delv`` sends queries to the localhost
addresses are found, :program:`delv` sends queries to the localhost
addresses (127.0.0.1 for IPv4, ::1 for IPv6).
When no command-line arguments or options are given, ``delv``
When no command-line arguments or options are given, :program:`delv`
performs an NS query for "." (the root zone).
Simple Usage
~~~~~~~~~~~~
A typical invocation of ``delv`` looks like:
A typical invocation of :program:`delv` looks like:
::
@ -68,34 +70,38 @@ A typical invocation of ``delv`` looks like:
where:
``server``
.. option:: server
is the name or IP address of the name server to query. This can be an
IPv4 address in dotted-decimal notation or an IPv6 address in
colon-delimited notation. When the supplied ``server`` argument is a
hostname, ``delv`` resolves that name before querying that name
hostname, :program:`delv` resolves that name before querying that name
server (note, however, that this initial lookup is *not* validated by
DNSSEC).
If no ``server`` argument is provided, ``delv`` consults
If no ``server`` argument is provided, :program:`delv` consults
``/etc/resolv.conf``; if an address is found there, it queries the
name server at that address. If either of the ``-4`` or ``-6``
name server at that address. If either of the :option:`-4` or :option:`-6`
options is in use, then only addresses for the corresponding
transport are tried. If no usable addresses are found, ``delv``
transport are tried. If no usable addresses are found, :program:`delv`
sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1
for IPv6).
``name``
.. option:: name
is the domain name to be looked up.
``type``
.. option:: type
indicates what type of query is required - ANY, A, MX, etc.
``type`` can be any valid query type. If no ``type`` argument is
supplied, ``delv`` performs a lookup for an A record.
supplied, :program:`delv` performs a lookup for an A record.
Options
~~~~~~~
``-a anchor-file``
.. option:: -a anchor-file
This option specifies a file from which to read DNSSEC trust anchors. The default
is |bind_keys|, which is included with BIND 9 and contains one
or more trust anchors for the root zone (".").
@ -103,90 +109,103 @@ Options
Keys that do not match the root zone name are ignored. An alternate
key name can be specified using the ``+root=NAME`` options.
Note: When reading the trust anchor file, ``delv`` treats ``trust-anchors``,
Note: When reading the trust anchor file, :program:`delv` treats ``trust-anchors``,
``initial-key``, and ``static-key`` identically. That is, for a managed key,
it is the *initial* key that is trusted; :rfc:`5011` key management is not
supported. ``delv`` does not consult the managed-keys database maintained by
``named``, which means that if either of the keys in |bind_keys| is
supported. :program:`delv` does not consult the managed-keys database maintained by
: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 ``delv``.
use DNSSEC validation in :program:`delv`.
.. option:: -b address
``-b address``
This option sets the source IP address of the query to ``address``. This must be
a valid address on one of the host's network interfaces, or ``0.0.0.0``,
or ``::``. An optional source port may be specified by appending
``#<port>``
``-c class``
This option sets the query class for the requested data. Currently, only class
"IN" is supported in ``delv`` and any other value is ignored.
.. option:: -c class
This option sets the query class for the requested data. Currently, only class
"IN" is supported in :program:`delv` and any other value is ignored.
.. option:: -d level
``-d level``
This option sets the systemwide debug level to ``level``. The allowed range is
from 0 to 99. The default is 0 (no debugging). Debugging traces from
``delv`` become more verbose as the debug level increases. See the
:program:`delv` become more verbose as the debug level increases. See the
``+mtrace``, ``+rtrace``, and ``+vtrace`` options below for
additional debugging details.
``-h``
This option displays the ``delv`` help usage output and exits.
.. option:: -h
This option displays the :program:`delv` help usage output and exits.
.. option:: -i
``-i``
This option sets insecure mode, which disables internal DNSSEC validation. (Note,
however, that this does not set the CD bit on upstream queries. If the
server being queried is performing DNSSEC validation, then it does
not return invalid data; this can cause ``delv`` to time out. When it
not return invalid data; this can cause :program:`delv` to time out. When it
is necessary to examine invalid data to debug a DNSSEC problem, use
``dig +cd``.)
``-m``
.. option:: -m
This option enables memory usage debugging.
``-p port#``
.. option:: -p port#
This option specifies a destination port to use for queries, instead of the
standard DNS port number 53. This option is used with a name
server that has been configured to listen for queries on a
non-standard port number.
``-q name``
.. option:: -q name
This option sets the query name to ``name``. While the query name can be
specified without using the ``-q`` option, it is sometimes necessary to
specified without using the :option:`-q` option, it is sometimes necessary to
disambiguate names from types or classes (for example, when looking
up the name "ns", which could be misinterpreted as the type NS, or
"ch", which could be misinterpreted as class CH).
``-t type``
.. option:: -t type
This option sets the query type to ``type``, which can be any valid query type
supported in BIND 9 except for zone transfer types AXFR and IXFR. As
with ``-q``, this is useful to distinguish query-name types or classes
with :option:`-q`, this is useful to distinguish query-name types or classes
when they are ambiguous. It is sometimes necessary to disambiguate
names from types.
The default query type is "A", unless the ``-x`` option is supplied
The default query type is "A", unless the :option:`-x` option is supplied
to indicate a reverse lookup, in which case it is "PTR".
``-v``
This option prints the ``delv`` version and exits.
.. option:: -v
This option prints the :program:`delv` version and exits.
.. option:: -x addr
``-x addr``
This option performs a reverse lookup, mapping an address to a name. ``addr``
is an IPv4 address in dotted-decimal notation, or a colon-delimited
IPv6 address. When ``-x`` is used, there is no need to provide the
``name`` or ``type`` arguments; ``delv`` automatically performs a
IPv6 address. When :option:`-x` is used, there is no need to provide the
``name`` or ``type`` arguments; :program:`delv` automatically performs a
lookup for a name like ``11.12.13.10.in-addr.arpa`` and sets the
query type to PTR. IPv6 addresses are looked up using nibble format
under the IP6.ARPA domain.
``-4``
This option forces ``delv`` to only use IPv4.
.. option:: -4
``-6``
This option forces ``delv`` to only use IPv6.
This option forces :program:`delv` to only use IPv4.
.. option:: -6
This option forces :program:`delv` to only use IPv6.
Query Options
~~~~~~~~~~~~~
``delv`` provides a number of query options which affect the way results
:program:`delv` provides a number of query options which affect the way results
are displayed, and in some cases the way lookups are performed.
Each query option is identified by a keyword preceded by a plus sign
@ -195,69 +214,79 @@ the string ``no`` to negate the meaning of that keyword. Other keywords
assign values to options like the timeout interval. They have the form
``+keyword=value``. The query options are:
``+[no]cdflag``
.. option:: +[no]cdflag
This option controls whether to set the CD (checking disabled) bit in queries
sent by ``delv``. This may be useful when troubleshooting DNSSEC
sent by :program:`delv`. This may be useful when troubleshooting DNSSEC
problems from behind a validating resolver. A validating resolver
blocks invalid responses, making it difficult to retrieve them
for analysis. Setting the CD flag on queries causes the resolver
to return invalid responses, which ``delv`` can then validate
to return invalid responses, which :program:`delv` can then validate
internally and report the errors in detail.
``+[no]class``
.. option:: +[no]class
This option controls whether to display the CLASS when printing a record. The
default is to display the CLASS.
``+[no]ttl``
.. option:: +[no]ttl
This option controls whether to display the TTL when printing a record. The
default is to display the TTL.
``+[no]rtrace``
.. option:: +[no]rtrace
This option toggles resolver fetch logging. This reports the name and type of each
query sent by ``delv`` in the process of carrying out the resolution
query sent by :program:`delv` in the process of carrying out the resolution
and validation process, including the original query
and all subsequent queries to follow CNAMEs and to establish a chain
of trust for DNSSEC validation.
This is equivalent to setting the debug level to 1 in the "resolver"
logging category. Setting the systemwide debug level to 1 using the
``-d`` option produces the same output, but affects other
:option:`-d` option produces the same output, but affects other
logging categories as well.
``+[no]mtrace``
.. option:: +[no]mtrace
This option toggles message logging. This produces a detailed dump of the
responses received by ``delv`` in the process of carrying out the
responses received by :program:`delv` in the process of carrying out the
resolution and validation process.
This is equivalent to setting the debug level to 10 for the "packets"
module of the "resolver" logging category. Setting the systemwide
debug level to 10 using the ``-d`` option produces the same
debug level to 10 using the :option:`-d` option produces the same
output, but affects other logging categories as well.
``+[no]vtrace``
.. option:: +[no]vtrace
This option toggles validation logging. This shows the internal process of the
validator as it determines whether an answer is validly signed,
unsigned, or invalid.
This is equivalent to setting the debug level to 3 for the
"validator" module of the "dnssec" logging category. Setting the
systemwide debug level to 3 using the ``-d`` option produces the
systemwide debug level to 3 using the :option:`-d` option produces the
same output, but affects other logging categories as well.
``+[no]short``
.. option:: +[no]short
This option toggles between verbose and terse answers. The default is to print the answer in a
verbose form.
``+[no]comments``
.. option:: +[no]comments
This option toggles the display of comment lines in the output. The default is to
print comments.
``+[no]rrcomments``
.. option:: +[no]rrcomments
This option toggles the display of per-record comments in the output (for example,
human-readable key information about DNSKEY records). The default is
to print per-record comments.
``+[no]crypto``
.. option:: +[no]crypto
This option toggles the display of cryptographic fields in DNSSEC records. The
contents of these fields are unnecessary to debug most DNSSEC
validation failures and removing them makes it easier to see the
@ -265,52 +294,61 @@ assign values to options like the timeout interval. They have the form
they are replaced by the string ``[omitted]`` or, in the DNSKEY case, the
key ID is displayed as the replacement, e.g. ``[ key id = value ]``.
``+[no]trust``
.. option:: +[no]trust
This option controls whether to display the trust level when printing a record.
The default is to display the trust level.
``+[no]split[=W]``
.. option:: +[no]split[=W]
This option splits long hex- or base64-formatted fields in resource records into
chunks of ``W`` characters (where ``W`` is rounded up to the nearest
multiple of 4). ``+nosplit`` or ``+split=0`` causes fields not to be
split at all. The default is 56 characters, or 44 characters when
multiline mode is active.
``+[no]all``
.. option:: +[no]all
This option sets or clears the display options ``+[no]comments``,
``+[no]rrcomments``, and ``+[no]trust`` as a group.
``+[no]multiline``
.. option:: +[no]multiline
This option prints long records (such as RRSIG, DNSKEY, and SOA records) in a
verbose multi-line format with human-readable comments. The default
is to print each record on a single line, to facilitate machine
parsing of the ``delv`` output.
parsing of the :program:`delv` output.
``+[no]dnssec``
This option indicates whether to display RRSIG records in the ``delv`` output.
The default is to do so. Note that (unlike in ``dig``) this does
.. 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 :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 ``-i`` or
always occurs unless suppressed by the use of :option:`-i` or
``+noroot``.
``+[no]root[=ROOT]``
.. option:: +[no]root[=ROOT]
This option indicates whether to perform conventional DNSSEC validation, and if so,
specifies the name of a trust anchor. The default is to validate using a
trust anchor of "." (the root zone), for which there is a built-in key. If
specifying a different trust anchor, then ``-a`` must be used to specify a
specifying a different trust anchor, then :option:`-a` must be used to specify a
file containing the key.
``+[no]tcp``
.. option:: +[no]tcp
This option controls whether to use TCP when sending queries. The default is to
use UDP unless a truncated response has been received.
``+[no]unknownformat``
.. option:: +[no]unknownformat
This option prints all RDATA in unknown RR-type presentation format (:rfc:`3597`).
The default is to print RDATA for known types in the type's
presentation format.
``+[no]yaml``
.. option:: +[no]yaml
This option prints response data in YAML format.
Files
@ -323,4 +361,4 @@ Files
See Also
~~~~~~~~
:manpage:`dig(1)`, :manpage:`named(8)`, :rfc:`4034`, :rfc:`4035`, :rfc:`4431`, :rfc:`5074`, :rfc:`5155`.
:iscman:`dig(1) <dig>`, :iscman:`named(8) <named>`, :rfc:`4034`, :rfc:`4035`, :rfc:`4431`, :rfc:`5074`, :rfc:`5155`.

397
bin/dig/dig.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dig
.. program:: dig
.. _man_dig:
dig - DNS lookup utility
@ -27,41 +29,41 @@ Synopsis
Description
~~~~~~~~~~~
``dig`` is a flexible tool for interrogating DNS name servers. It
:program:`dig` is a flexible tool for interrogating DNS name servers. It
performs DNS lookups and displays the answers that are returned from the
name server(s) that were queried. Most DNS administrators use ``dig`` to
name server(s) that were queried. Most DNS administrators use :program:`dig` to
troubleshoot DNS problems because of its flexibility, ease of use, and
clarity of output. Other lookup tools tend to have less functionality
than ``dig``.
than :program:`dig`.
Although ``dig`` is normally used with command-line arguments, it also
Although :program:`dig` is normally used with command-line arguments, it also
has a batch mode of operation for reading lookup requests from a file. A
brief summary of its command-line arguments and options is printed when
the ``-h`` option is given. The BIND 9
implementation of ``dig`` allows multiple lookups to be issued from the
the :option:`-h` option is given. The BIND 9
implementation of :program:`dig` allows multiple lookups to be issued from the
command line.
Unless it is told to query a specific name server, ``dig`` tries each
Unless it is told to query a specific name server, :program:`dig` tries each
of the servers listed in ``/etc/resolv.conf``. If no usable server
addresses are found, ``dig`` sends the query to the local host.
addresses are found, :program:`dig` sends the query to the local host.
When no command-line arguments or options are given, ``dig``
When no command-line arguments or options are given, :program:`dig`
performs an NS query for "." (the root).
It is possible to set per-user defaults for ``dig`` via
It is possible to set per-user defaults for :program:`dig` via
``${HOME}/.digrc``. This file is read and any options in it are applied
before the command-line arguments. The ``-r`` option disables this
before the command-line arguments. The :option:`-r` option disables this
feature, for scripts that need predictable behavior.
The IN and CH class names overlap with the IN and CH top-level domain
names. Either use the ``-t`` and ``-c`` options to specify the type and
class, use the ``-q`` to specify the domain name, or use "IN." and
names. Either use the :option:`-t` and :option:`-c` options to specify the type and
class, use the :option:`-q` to specify the domain name, or use "IN." and
"CH." when looking up these top-level domains.
Simple Usage
~~~~~~~~~~~~
A typical invocation of ``dig`` looks like:
A typical invocation of :program:`dig` looks like:
::
@ -69,83 +71,101 @@ A typical invocation of ``dig`` looks like:
where:
``server``
.. option:: server
is the name or IP address of the name server to query. This can be an
IPv4 address in dotted-decimal notation or an IPv6 address in
colon-delimited notation. When the supplied ``server`` argument is a
hostname, ``dig`` resolves that name before querying that name
hostname, :program:`dig` resolves that name before querying that name
server.
If no ``server`` argument is provided, ``dig`` consults
If no ``server`` argument is provided, :program:`dig` consults
``/etc/resolv.conf``; if an address is found there, it queries the
name server at that address. If either of the ``-4`` or ``-6``
name server at that address. If either of the :option:`-4` or :option:`-6`
options are in use, then only addresses for the corresponding
transport are tried. If no usable addresses are found, ``dig``
transport are tried. If no usable addresses are found, :program:`dig`
sends the query to the local host. The reply from the name server
that responds is displayed.
``name``
.. option:: name
is the name of the resource record that is to be looked up.
``type``
.. option:: type
indicates what type of query is required - ANY, A, MX, SIG, etc.
``type`` can be any valid query type. If no ``type`` argument is
supplied, ``dig`` performs a lookup for an A record.
supplied, :program:`dig` performs a lookup for an A record.
Options
~~~~~~~
``-4``
.. option:: -4
This option indicates that only IPv4 should be used.
``-6``
.. option:: -6
This option indicates that only IPv6 should be used.
``-b address[#port]``
.. option:: -b address[#port]
This option sets the source IP address of the query. The ``address`` must be a
valid address on one of the host's network interfaces, or "0.0.0.0"
or "::". An optional port may be specified by appending ``#port``.
``-c class``
.. option:: -c class
This option sets the query class. The default ``class`` is IN; other classes are
HS for Hesiod records or CH for Chaosnet records.
``-f file``
This option sets batch mode, in which ``dig`` reads a list of lookup requests to process from
.. option:: -f file
This option sets batch mode, in which :program:`dig` reads a list of lookup requests to process from
the given ``file``. Each line in the file should be organized in the
same way it would be presented as a query to ``dig`` using the
same way it would be presented as a query to :program:`dig` using the
command-line interface.
``-k keyfile``
This option tells ``named`` to sign queries using TSIG using a key read from the given file. Key
files can be generated using ``tsig-keygen``. When using TSIG
authentication with ``dig``, the name server that is queried needs to
.. option:: -h
Print a usage summary.
.. option:: -k keyfile
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
``-m``
This option enables memory usage debugging.
``-p port``
.. option:: -p port
This option sends the query to a non-standard port on the server, instead of the
default port 53. This option is used to test a name server that
has been configured to listen for queries on a non-standard port
number.
``-q name``
.. option:: -q name
This option specifies the domain name to query. This is useful to distinguish the ``name``
from other arguments.
``-r``
.. option:: -r
This option indicates that options from ``${HOME}/.digrc`` should not be read. This is useful for
scripts that need predictable behavior.
``-t type``
.. option:: -t type
This option indicates the resource record type to query, which can be any valid query type. If
it is a resource record type supported in BIND 9, it can be given by
the type mnemonic (such as ``NS`` or ``AAAA``). The default query type is
``A``, unless the ``-x`` option is supplied to indicate a reverse
``A``, unless the :option:`-x` option is supplied to indicate a reverse
lookup. A zone transfer can be requested by specifying a type of
AXFR. When an incremental zone transfer (IXFR) is required, set the
``type`` to ``ixfr=N``. The incremental zone transfer contains
@ -156,23 +176,27 @@ Options
the number of the type. If the resource record type is not supported
in BIND 9, the result is displayed as described in :rfc:`3597`.
``-u``
.. option:: -u
This option indicates that print query times should be provided in microseconds instead of milliseconds.
``-v``
.. option:: -v
This option prints the version number and exits.
``-x addr``
.. option:: -x addr
This option sets simplified reverse lookups, for mapping addresses to names. The
``addr`` is an IPv4 address in dotted-decimal notation, or a
colon-delimited IPv6 address. When the ``-x`` option is used, there is no
colon-delimited IPv6 address. When the :option:`-x` option is used, there is no
need to provide the ``name``, ``class``, and ``type`` arguments.
``dig`` automatically performs a lookup for a name like
:program:`dig` automatically performs a lookup for a name like
``94.2.0.192.in-addr.arpa`` and sets the query type and class to PTR
and IN respectively. IPv6 addresses are looked up using nibble format
under the IP6.ARPA domain.
``-y [hmac:]keyname:secret``
.. option:: -y [hmac:]keyname:secret
This option signs queries using TSIG with the given authentication key.
``keyname`` is the name of the key, and ``secret`` is the
base64-encoded shared secret. ``hmac`` is the name of the key algorithm;
@ -181,15 +205,15 @@ Options
not specified, the default is ``hmac-md5``; if MD5 was disabled, the default is
``hmac-sha256``.
.. note:: Only the ``-k`` option should be used, rather than the ``-y`` option,
because with ``-y`` the shared secret is supplied as a command-line
.. note:: Only the :option:`-k` option should be used, rather than the :option:`-y` option,
because with :option:`-y` the shared secret is supplied as a command-line
argument in clear text. This may be visible in the output from ``ps1`` or
in a history file maintained by the user's shell.
Query Options
~~~~~~~~~~~~~
``dig`` provides a number of query options which affect the way in which
:program:`dig` provides a number of query options which affect the way in which
lookups are made and the results displayed. Some of these set or reset
flag bits in the query header, some determine which sections of the
answer get printed, and others determine the timeout and retry
@ -203,17 +227,21 @@ assign values to options, like the timeout interval. They have the form
abbreviation is unambiguous; for example, ``+cd`` is equivalent to
``+cdflag``. The query options are:
``+[no]aaflag``
.. option:: +[no]aaflag
This option is a synonym for ``+[no]aaonly``.
``+[no]aaonly``
.. option:: +[no]aaonly
This option sets the ``aa`` flag in the query.
``+[no]additional``
.. option:: +[no]additional
This option displays [or does not display] the additional section of a reply. The
default is to display it.
``+[no]adflag``
.. option:: +[no]adflag
This option sets [or does not set] the AD (authentic data) bit in the query. This
requests the server to return whether all of the answer and authority
sections have been validated as secure, according to the security
@ -222,44 +250,54 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
indicates that some part of the answer was insecure or not validated.
This bit is set by default.
``+[no]all``
.. option:: +[no]all
This option sets or clears all display flags.
``+[no]answer``
.. option:: +[no]answer
This option displays [or does not display] the answer section of a reply. The default
is to display it.
``+[no]authority``
.. option:: +[no]authority
This option displays [or does not display] the authority section of a reply. The
default is to display it.
``+[no]badcookie``
.. option:: +[no]badcookie
This option retries the lookup with a new server cookie if a BADCOOKIE response is
received.
``+[no]besteffort``
.. option:: +[no]besteffort
This option attempts to display the contents of messages which are malformed. The
default is to not display malformed answers.
``+bufsize[=B]``
.. option:: +bufsize[=B]
This option sets the UDP message buffer size advertised using EDNS0 to
``B`` bytes. The maximum and minimum sizes of this buffer are 65535 and
0, respectively. ``+bufsize`` restores the default buffer size.
``+[no]cdflag``
.. option:: +[no]cdflag
This option sets [or does not set] the CD (checking disabled) bit in the query. This
requests the server to not perform DNSSEC validation of responses.
``+[no]class``
.. option:: +[no]class
This option displays [or does not display] the CLASS when printing the record.
``+[no]cmd``
.. option:: +[no]cmd
This option toggles the printing of the initial comment in the output, identifying the
version of ``dig`` and the query options that have been applied. This option
version of :program:`dig` and the query options that have been applied. This option
always has a global effect; it cannot be set globally and then overridden on a
per-lookup basis. The default is to print this comment.
``+[no]comments``
.. option:: +[no]comments
This option toggles the display of some comment lines in the output, with
information about the packet header and OPT pseudosection, and the names of
the response section. The default is to print these comments.
@ -268,7 +306,8 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
can be controlled using other command-line switches. These include
``+[no]cmd``, ``+[no]question``, ``+[no]stats``, and ``+[no]rrcomments``.
``+[no]cookie=####``
.. option:: +[no]cookie=####
This option sends [or does not send] a COOKIE EDNS option, with an optional value. Replaying a COOKIE
from a previous response allows the server to identify a previous
client. The default is ``+cookie``.
@ -276,7 +315,8 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
``+cookie`` is also set when ``+trace`` is set to better emulate the
default queries from a nameserver.
``+[no]crypto``
.. option:: +[no]crypto
This option toggles the display of cryptographic fields in DNSSEC records. The
contents of these fields are unnecessary for debugging most DNSSEC
validation failures and removing them makes it easier to see the
@ -284,62 +324,75 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
they are replaced by the string ``[omitted]`` or, in the DNSKEY case, the
key ID is displayed as the replacement, e.g. ``[ key id = value ]``.
``+[no]defname``
.. option:: +[no]defname
This option, which is deprecated, is treated as a synonym for ``+[no]search``.
``+[no]dns64prefix``
.. option:: +[no]dns64prefix
Lookup IPV4ONLY.ARPA AAAA and print any DNS64 prefixes found.
``+[no]dnssec``
.. option:: +[no]dnssec
This option requests that DNSSEC records be sent by setting the DNSSEC OK (DO) bit in
the OPT record in the additional section of the query.
``+domain=somename``
.. option:: +domain=somename
This option sets the search list to contain the single domain ``somename``, as if
specified in a ``domain`` directive in ``/etc/resolv.conf``, and
enables search list processing as if the ``+search`` option were
given.
``+dscp=value``
.. option:: +dscp=value
This option sets the DSCP code point to be used when sending the query. Valid DSCP
code points are in the range [0...63]. By default no code point is
explicitly set.
``+[no]edns[=#]``
.. option:: +[no]edns[=#]
This option specifies the EDNS version to query with. Valid values are 0 to 255.
Setting the EDNS version causes an EDNS query to be sent.
``+noedns`` clears the remembered EDNS version. EDNS is set to 0 by
default.
``+[no]ednsflags[=#]``
.. option:: +[no]ednsflags[=#]
This option sets the must-be-zero EDNS flags bits (Z bits) to the specified value.
Decimal, hex, and octal encodings are accepted. Setting a named flag
(e.g., DO) is silently ignored. By default, no Z bits are set.
``+[no]ednsnegotiation``
.. option:: +[no]ednsnegotiation
This option enables/disables EDNS version negotiation. By default, EDNS version
negotiation is enabled.
``+[no]ednsopt[=code[:value]]``
.. option:: +[no]ednsopt[=code[:value]]
This option specifies the EDNS option with code point ``code`` and an optional payload
of ``value`` as a hexadecimal string. ``code`` can be either an EDNS
option name (for example, ``NSID`` or ``ECS``) or an arbitrary
numeric value. ``+noednsopt`` clears the EDNS options to be sent.
``+[no]expire``
.. option:: +[no]expire
This option sends an EDNS Expire option.
``+[no]fail``
This option indicates that ``named`` should try [or not try] the next server if a SERVFAIL is received. The default is
.. option:: +[no]fail
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.
``+[no]header-only``
.. option:: +[no]header-only
This option sends a query with a DNS header without a question section. The
default is to add a question section. The query type and query name
are ignored when this is set.
``+[no]https[=value]``
.. option:: +[no]https[=value]
This option indicates whether to use DNS over HTTPS (DoH) when querying
name servers. When this option is in use, the port number defaults to 443.
The HTTP POST request mode is used when sending the query.
@ -348,64 +401,77 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
query URI; the default is ``/dns-query``. So, for example, ``dig
@example.com +https`` will use the URI ``https://example.com/dns-query``.
``+[no]https-get[=value]``
.. option:: +[no]https-get[=value]
Similar to ``+https``, except that the HTTP GET request mode is used
when sending the query.
``+[no]https-post[=value]``
.. option:: +[no]https-post[=value]
Same as ``+https``.
``+[no]http-plain[=value]``
.. option:: +[no]http-plain[=value]
Similar to ``+https``, except that HTTP queries will be sent over a
non-encrypted channel. When this option is in use, the port number
defaults to 80 and the HTTP request mode is POST.
``+[no]http-plain-get[=value]``
.. option:: +[no]http-plain-get[=value]
Similar to ``+http-plain``, except that the HTTP request mode is GET.
``+[no]http-plain-post[=value]``
.. option:: +[no]http-plain-post[=value]
Same as ``+http-plain``.
``+[no]identify``
.. option:: +[no]identify
This option shows [or does not show] the IP address and port number that
supplied the answer, when the ``+short`` option is enabled. If short
form answers are requested, the default is not to show the source
address and port number of the server that provided the answer.
``+[no]idnin``
.. option:: +[no]idnin
This option processes [or does not process] IDN domain names on input. This requires
``IDN SUPPORT`` to have been enabled at compile time.
The default is to process IDN input when standard output is a tty.
The IDN processing on input is disabled when ``dig`` output is redirected
The IDN processing on input is disabled when :program:`dig` output is redirected
to files, pipes, and other non-tty file descriptors.
``+[no]idnout``
.. option:: +[no]idnout
This option converts [or does not convert] puny code on output. This requires
``IDN SUPPORT`` to have been enabled at compile time.
The default is to process puny code on output when standard output is
a tty. The puny code processing on output is disabled when ``dig`` output
a tty. The puny code processing on output is disabled when :program:`dig` output
is redirected to files, pipes, and other non-tty file descriptors.
``+[no]ignore``
.. option:: +[no]ignore
This option ignores [or does not ignore] truncation in UDP responses instead of retrying with TCP. By
default, TCP retries are performed.
``+[no]keepalive``
.. option:: +[no]keepalive
This option sends [or does not send] an EDNS Keepalive option.
``+[no]keepopen``
.. option:: +[no]keepopen
This option keeps [or does not keep] the TCP socket open between queries, and reuses it rather than
creating a new TCP socket for each lookup. The default is
``+nokeepopen``.
``+[no]multiline``
.. option:: +[no]multiline
This option prints [or does not print] records, like the SOA records, in a verbose multi-line format
with human-readable comments. The default is to print each record on
a single line to facilitate machine parsing of the ``dig`` output.
a single line to facilitate machine parsing of the :program:`dig` output.
.. option:: +ndots=D
``+ndots=D``
This option sets the number of dots (``D``) that must appear in ``name`` for
it to be considered absolute. The default value is that defined using
the ``ndots`` statement in ``/etc/resolv.conf``, or 1 if no ``ndots``
@ -414,24 +480,29 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
``search`` or ``domain`` directive in ``/etc/resolv.conf`` if
``+search`` is set.
``+[no]nsid``
.. option:: +[no]nsid
When enabled, this option includes an EDNS name server ID request when sending a query.
``+[no]nssearch``
When this option is set, ``dig`` attempts to find the authoritative
.. option:: +[no]nssearch
When this option is set, :program:`dig` attempts to find the authoritative
name servers for the zone containing the name being looked up, and
display the SOA record that each name server has for the zone.
Addresses of servers that did not respond are also printed.
``+[no]onesoa``
.. option:: +[no]onesoa
When enabled, this option prints only one (starting) SOA record when performing an AXFR. The
default is to print both the starting and ending SOA records.
``+[no]opcode=value``
.. option:: +[no]opcode=value
When enabled, this option sets (restores) the DNS message opcode to the specified value. The
default value is QUERY (0).
``+padding=value``
.. option:: +padding=value
This option pads the size of the query packet using the EDNS Padding option to
blocks of ``value`` bytes. For example, ``+padding=32`` causes a
48-byte query to be padded to 64 bytes. The default block size is 0,
@ -440,42 +511,51 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
mandatory. Responses to padded queries may also be padded, but only
if the query uses TCP or DNS COOKIE.
``+qid=value``
.. option:: +qid=value
This option specifies the query ID to use when sending queries.
``+[no]qr``
.. option:: +[no]qr
This option toggles the display of the query message as it is sent. By default, the query
is not printed.
``+[no]question``
.. option:: +[no]question
This option toggles the display of the question section of a query when an answer is
returned. The default is to print the question section as a comment.
``+[no]raflag``
.. option:: +[no]raflag
This option sets [or does not set] the RA (Recursion Available) bit in the query. The
default is ``+noraflag``. This bit is ignored by the server for
QUERY.
``+[no]rdflag``
.. option:: +[no]rdflag
This option is a synonym for ``+[no]recurse``.
``+[no]recurse``
.. option:: +[no]recurse
This option toggles the setting of the RD (recursion desired) bit in the query.
This bit is set by default, which means ``dig`` normally sends
This bit is set by default, which means :program:`dig` normally sends
recursive queries. Recursion is automatically disabled when the
``+nssearch`` or ``+trace`` query option is used.
``+retry=T``
.. option:: +retry=T
This option sets the number of times to retry UDP and TCP queries to server to ``T``
instead of the default, 2. Unlike ``+tries``, this does not include
the initial query.
``+[no]rrcomments``
.. option:: +[no]rrcomments
This option toggles the display of per-record comments in the output (for example,
human-readable key information about DNSKEY records). The default is
not to print record comments unless multiline mode is active.
``+[no]search``
.. option:: +[no]search
This option uses [or does not use] the search list defined by the searchlist or domain
directive in ``resolv.conf``, if any. The search list is not used by
default.
@ -484,36 +564,43 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
``+ndots``, determines whether the name is treated as relative
and hence whether a search is eventually performed.
``+[no]short``
.. option:: +[no]short
This option toggles whether a terse answer is provided. The default is to print the answer in a verbose
form. This option always has a global effect; it cannot be set globally and
then overridden on a per-lookup basis.
``+[no]showbadcookie``
.. option:: +[no]showbadcookie
This option toggles whether to show the message containing the
BADCOOKIE rcode before retrying the request or not. The default
is to not show the messages.
``+[no]showsearch``
.. option:: +[no]showsearch
This option performs [or does not perform] a search showing intermediate results.
``+[no]sigchase``
This feature is now obsolete and has been removed; use ``delv``
.. option:: +[no]sigchase
This feature is now obsolete and has been removed; use :iscman:`delv`
instead.
``+split=W``
.. option:: +split=W
This option splits long hex- or base64-formatted fields in resource records into
chunks of ``W`` characters (where ``W`` is rounded up to the nearest
multiple of 4). ``+nosplit`` or ``+split=0`` causes fields not to be
split at all. The default is 56 characters, or 44 characters when
multiline mode is active.
``+[no]stats``
.. option:: +[no]stats
This option toggles the printing of statistics: when the query was made, the size of the
reply, etc. The default behavior is to print the query statistics as a
comment after each lookup.
``+[no]subnet=addr[/prefix-length]``
.. option:: +[no]subnet=addr[/prefix-length]
This option sends [or does not send] an EDNS CLIENT-SUBNET option with the specified IP
address or network prefix.
@ -522,33 +609,39 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
prefix-length of zero, which signals a resolver that the client's
address information must *not* be used when resolving this query.
``+[no]tcflag``
.. option:: +[no]tcflag
This option sets [or does not set] the TC (TrunCation) bit in the query. The default is
``+notcflag``. This bit is ignored by the server for QUERY.
``+[no]tcp``
.. option:: +[no]tcp
This option indicates whether to use TCP when querying name servers.
The default behavior is to use UDP unless a type ``any`` or ``ixfr=N``
query is requested, in which case the default is TCP. AXFR queries
always use TCP.
``+timeout=T``
.. option:: +timeout=T
This option sets the timeout for a query to ``T`` seconds. The default timeout is
5 seconds. An attempt to set ``T`` to less than 1 is silently set to 1.
``+[no]tls``
.. option:: +[no]tls
This option indicates whether to use DNS over TLS (DoT) when querying
name servers. When this option is in use, the port number defaults
to 853.
``+[no]topdown``
This feature is related to ``dig +sigchase``, which is obsolete and
has been removed. Use ``delv`` instead.
.. option:: +[no]topdown
This feature is related to ``dig +sigchase``, which is obsolete and
has been removed. Use :iscman:`delv` instead.
.. option:: +[no]trace
``+[no]trace``
This option toggles tracing of the delegation path from the root name servers for
the name being looked up. Tracing is disabled by default. When
tracing is enabled, ``dig`` makes iterative queries to resolve the
tracing is enabled, :program:`dig` makes iterative queries to resolve the
name being looked up. It follows referrals from the root servers,
showing the answer from each server that was used to resolve the
lookup.
@ -559,46 +652,54 @@ abbreviation is unambiguous; for example, ``+cd`` is equivalent to
``+dnssec`` is also set when ``+trace`` is set, to better emulate the
default queries from a name server.
``+tries=T``
.. option:: +tries=T
This option sets the number of times to try UDP and TCP queries to server to ``T``
instead of the default, 3. If ``T`` is less than or equal to zero,
the number of tries is silently rounded up to 1.
``+trusted-key=####``
This option formerly specified trusted keys for use with ``dig +sigchase``. This
feature is now obsolete and has been removed; use ``delv`` instead.
.. option:: +trusted-key=####
This option formerly specified trusted keys for use with ``dig +sigchase``. This
feature is now obsolete and has been removed; use :iscman:`delv` instead.
.. option:: +[no]ttlid
``+[no]ttlid``
This option displays [or does not display] the TTL when printing the record.
``+[no]ttlunits``
.. option:: +[no]ttlunits
This option displays [or does not display] the TTL in friendly human-readable time
units of ``s``, ``m``, ``h``, ``d``, and ``w``, representing seconds, minutes,
hours, days, and weeks. This implies ``+ttlid``.
``+[no]unknownformat``
.. option:: +[no]unknownformat
This option prints all RDATA in unknown RR type presentation format (:rfc:`3597`).
The default is to print RDATA for known types in the type's
presentation format.
``+[no]vc``
.. option:: +[no]vc
This option uses [or does not use] TCP when querying name servers. This alternate
syntax to ``+[no]tcp`` is provided for backwards compatibility. The
``vc`` stands for "virtual circuit."
``+[no]yaml``
.. option:: +[no]yaml
When enabled, this option prints the responses (and, if ``+qr`` is in use, also the
outgoing queries) in a detailed YAML format.
``+[no]zflag``
.. option:: +[no]zflag
This option sets [or does not set] the last unassigned DNS header flag in a DNS query.
This flag is off by default.
Multiple Queries
~~~~~~~~~~~~~~~~
The BIND 9 implementation of ``dig`` supports specifying multiple
queries on the command line (in addition to supporting the ``-f`` batch
The BIND 9 implementation of :program:`dig` supports specifying multiple
queries on the command line (in addition to supporting the :option:`-f` batch
file option). Each of those queries can be supplied with its own set of
flags, options, and query options.
@ -619,19 +720,19 @@ query options. For example:
dig +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr
shows how ``dig`` can be used from the command line to make three
shows how :program:`dig` can be used from the command line to make three
lookups: an ANY query for ``www.isc.org``, a reverse lookup of 127.0.0.1,
and a query for the NS records of ``isc.org``. A global query option of
``+qr`` is applied, so that ``dig`` shows the initial query it made for
``+qr`` is applied, so that :program:`dig` shows the initial query it made for
each lookup. The final query has a local query option of ``+noqr`` which
means that ``dig`` does not print the initial query when it looks up the
means that :program:`dig` does not print the initial query when it looks up the
NS records for ``isc.org``.
IDN Support
~~~~~~~~~~~
If ``dig`` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. ``dig``
If :program:`dig` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. :program:`dig`
appropriately converts character encoding of a domain name before sending
a request to a DNS server or displaying a reply from the server.
To turn off IDN support, use the parameters
@ -641,7 +742,7 @@ variable.
Return Codes
~~~~~~~~~~~~
``dig`` return codes are:
:program:`dig` return codes are:
``0``
DNS response received, including NXDOMAIN status
@ -668,7 +769,7 @@ Files
See Also
~~~~~~~~
:manpage:`delv(1)`, :manpage:`host(1)`, :manpage:`named(8)`, :manpage:`dnssec-keygen(8)`, :rfc:`1035`.
:iscman:`delv(1) <delv>`, :iscman:`host(1) <host>`, :iscman:`named(8) <named>`, :iscman:`dnssec-keygen(8) <dnssec-keygen>`, :rfc:`1035`.
Bugs
~~~~

130
bin/dig/host.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: host
.. program:: host
.. _man_host:
host - DNS lookup utility
@ -24,55 +26,64 @@ Synopsis
Description
~~~~~~~~~~~
``host`` is a simple utility for performing DNS lookups. It is normally
:program:`host` is a simple utility for performing DNS lookups. It is normally
used to convert names to IP addresses and vice versa. When no arguments
or options are given, ``host`` prints a short summary of its
or options are given, :program:`host` prints a short summary of its
command-line arguments and options.
``name`` is the domain name that is to be looked up. It can also be a
dotted-decimal IPv4 address or a colon-delimited IPv6 address, in which
case ``host`` by default performs a reverse lookup for that address.
case :program:`host` by default performs a reverse lookup for that address.
``server`` is an optional argument which is either the name or IP
address of the name server that ``host`` should query instead of the
address of the name server that :program:`host` should query instead of the
server or servers listed in ``/etc/resolv.conf``.
Options
~~~~~~~
``-4``
This option specifies that only IPv4 should be used for query transport. See also the ``-6`` option.
.. option:: -4
``-6``
This option specifies that only IPv6 should be used for query transport. See also the ``-4`` option.
This option specifies that only IPv4 should be used for query transport. See also the :option:`-6` option.
``-a``
The ``-a`` ("all") option is normally equivalent to ``-v -t ANY``. It
also affects the behavior of the ``-l`` list zone option.
.. option:: -6
``-A``
The ``-A`` ("almost all") option is equivalent to ``-a``, except that RRSIG,
This option specifies that only IPv6 should be used for query transport. See also the :option:`-4` option.
.. option:: -a
The :option:`-a` ("all") option is normally equivalent to :option:`-v` :option:`-t ANY <-t>`. It
also affects the behavior of the :option:`-l` list zone option.
.. option:: -A
The :option:`-A` ("almost all") option is equivalent to :option:`-a`, except that RRSIG,
NSEC, and NSEC3 records are omitted from the output.
``-c class``
.. option:: -c class
This option specifies the query class, which can be used to lookup HS (Hesiod) or CH (Chaosnet)
class resource records. The default class is IN (Internet).
``-C``
This option indicates that ``named`` should check consistency, meaning that ``host`` queries the SOA records for zone
.. option:: -C
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.
``-d``
This option prints debugging traces, and is equivalent to the ``-v`` verbose option.
.. option:: -d
``-l``
This option tells ``named`` to list the zone, meaning the ``host`` command performs a zone transfer of zone
This option prints debugging traces, and is equivalent to the :option:`-v` verbose option.
.. option:: -l
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 ``-l -a`` options print all records in the zone.
Together, the :option:`-l` :option:`-a` options print all records in the zone.
.. option:: -N ndots
``-N ndots``
This option specifies the number of dots (``ndots``) that have to be in ``name`` for it to be
considered absolute. The default value is that defined using the
``ndots`` statement in ``/etc/resolv.conf``, or 1 if no ``ndots`` statement
@ -80,85 +91,96 @@ Options
and are searched for in the domains listed in the ``search`` or
``domain`` directive in ``/etc/resolv.conf``.
``-p port``
.. option:: -p port
This option specifies the port to query on the server. The default is 53.
``-r``
.. option:: -r
This option specifies a non-recursive query; setting this option clears the RD (recursion
desired) bit in the query. This means that the name server
receiving the query does not attempt to resolve ``name``. The ``-r``
option enables ``host`` to mimic the behavior of a name server by
receiving the query does not attempt to resolve ``name``. The :option:`-r`
option enables :program:`host` to mimic the behavior of a name server by
making non-recursive queries, and expecting to receive answers to
those queries that can be referrals to other name servers.
``-R number``
.. option:: -R number
This option specifies the number of retries for UDP queries. If ``number`` is negative or zero,
the number of retries is silently set to 1. The default value is 1, or
the value of the ``attempts`` option in ``/etc/resolv.conf``, if set.
``-s``
This option tells ``named`` *not* to send the query to the next nameserver if any server responds
.. option:: -s
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.
``-t type``
.. option:: -t type
This option specifies the query type. The ``type`` argument can be any recognized query type:
CNAME, NS, SOA, TXT, DNSKEY, AXFR, etc.
When no query type is specified, ``host`` automatically selects an
When no query type is specified, :program:`host` automatically selects an
appropriate query type. By default, it looks for A, AAAA, and MX
records. If the ``-C`` option is given, queries are made for SOA
records. If the :option:`-C` option is given, queries are made for SOA
records. If ``name`` is a dotted-decimal IPv4 address or
colon-delimited IPv6 address, ``host`` queries for PTR records.
colon-delimited IPv6 address, :program:`host` queries for PTR records.
If a query type of IXFR is chosen, the starting serial number can be
specified by appending an equals sign (=), followed by the starting serial
number, e.g., ``-t IXFR=12345678``.
number, e.g., :option:`-t IXFR=12345678 <-t>`.
``-T``; ``-U``
This option specifies TCP or UDP. By default, ``host`` uses UDP when making queries; the
``-T`` option makes it use a TCP connection when querying the name
.. option:: -T, -U
This option specifies TCP or UDP. By default, :program:`host` uses UDP when making queries; the
:option:`-T` option makes it use a TCP connection when querying the name
server. TCP is automatically selected for queries that require
it, such as zone transfer (AXFR) requests. Type ``ANY`` queries default
to TCP, but can be forced to use UDP initially via ``-U``.
to TCP, but can be forced to use UDP initially via :option:`-U`.
.. option:: -m flag
``-m flag``
This option sets memory usage debugging: the flag can be ``record``, ``usage``, or
``trace``. The ``-m`` option can be specified more than once to set
``trace``. The :option:`-m` option can be specified more than once to set
multiple flags.
``-v``
This option sets verbose output, and is equivalent to the ``-d`` debug option. Verbose output
.. option:: -v
This option sets verbose output, and is equivalent to the :option:`-d` debug option. Verbose output
can also be enabled by setting the ``debug`` option in
``/etc/resolv.conf``.
``-V``
.. option:: -V
This option prints the version number and exits.
``-w``
This option sets "wait forever": the query timeout is set to the maximum possible. See
also the ``-W`` option.
.. option:: -w
``-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 option sets "wait forever": the query timeout is set to the maximum possible. See
also the :option:`-W` option.
.. option:: -W wait
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, ``host`` waits for 5 seconds for UDP responses and 10
By default, :program:`host` waits for 5 seconds for UDP responses and 10
seconds for TCP connections. These defaults can be overridden by the
``timeout`` option in ``/etc/resolv.conf``.
See also the ``-w`` option.
See also the :option:`-w` option.
IDN Support
~~~~~~~~~~~
If ``host`` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. ``host``
If :program:`host` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. :program:`host`
appropriately converts character encoding of a domain name before sending
a request to a DNS server or displaying a reply from the server.
To turn off IDN support, define the ``IDN_DISABLE``
environment variable. IDN support is disabled if the variable is set
when ``host`` runs.
when :program:`host` runs.
Files
~~~~~
@ -168,4 +190,4 @@ Files
See Also
~~~~~~~~
:manpage:`dig(1)`, :manpage:`named(8)`.
:iscman:`dig(1) <dig>`, :iscman:`named(8) <named>`.

24
bin/dig/nslookup.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: nslookup
.. program:: nslookup
.. _man_nslookup:
nslookup - query Internet name servers interactively
@ -24,8 +26,8 @@ Synopsis
Description
~~~~~~~~~~~
``nslookup`` is a program to query Internet domain name servers.
``nslookup`` has two modes: interactive and non-interactive. Interactive
:program:`nslookup` is a program to query Internet domain name servers.
:program:`nslookup` has two modes: interactive and non-interactive. Interactive
mode allows the user to query name servers for information about various
hosts and domains or to print a list of hosts in a domain.
Non-interactive mode prints just the name and requested
@ -54,16 +56,16 @@ seconds, type:
nslookup -query=hinfo -timeout=10
The ``-version`` option causes ``nslookup`` to print the version number
The ``-version`` option causes :program:`nslookup` to print the version number
and immediately exit.
Interactive Commands
~~~~~~~~~~~~~~~~~~~~
``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.
@ -181,19 +183,19 @@ Interactive Commands
Return Values
~~~~~~~~~~~~~
``nslookup`` returns with an exit status of 1 if any query failed, and 0
:program:`nslookup` returns with an exit status of 1 if any query failed, and 0
otherwise.
IDN Support
~~~~~~~~~~~
If ``nslookup`` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. ``nslookup``
If :program:`nslookup` has been built with IDN (internationalized domain name)
support, it can accept and display non-ASCII domain names. :program:`nslookup`
appropriately converts character encoding of a domain name before sending
a request to a DNS server or displaying a reply from the server.
To turn off IDN support, define the ``IDN_DISABLE``
environment variable. IDN support is disabled if the variable is set
when ``nslookup`` runs, or when the standard output is not a tty.
when :program:`nslookup` runs, or when the standard output is not a tty.
Files
~~~~~
@ -203,4 +205,4 @@ Files
See Also
~~~~~~~~
:manpage:`dig(1)`, :manpage:`host(1)`, :manpage:`named(8)`.
:iscman:`dig(1) <dig>`, :iscman:`host(1) <host>`, :iscman:`named(8) <named>`.

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dnssec-cds
.. program:: dnssec-cds
.. _man_dnssec-cds:
dnssec-cds - change DS records for a child zone based on CDS/CDNSKEY
@ -24,59 +26,60 @@ Synopsis
Description
~~~~~~~~~~~
The ``dnssec-cds`` command changes DS records at a delegation point
The :program:`dnssec-cds` command changes DS records at a delegation point
based on CDS or CDNSKEY records published in the child zone. If both CDS
and CDNSKEY records are present in the child zone, the CDS is preferred.
This enables a child zone to inform its parent of upcoming changes to
its key-signing keys (KSKs); by polling periodically with ``dnssec-cds``, the
its key-signing keys (KSKs); by polling periodically with :program:`dnssec-cds`, the
parent can keep the DS records up-to-date and enable automatic rolling
of KSKs.
Two input files are required. The ``-f child-file`` option specifies a
Two input files are required. The :option:`-f child-file <-f>` option specifies a
file containing the child's CDS and/or CDNSKEY records, plus RRSIG and
DNSKEY records so that they can be authenticated. The ``-d path`` option
DNSKEY records so that they can be authenticated. The :option:`-d path <-d>` option
specifies the location of a file containing the current DS records. For
example, this could be a ``dsset-`` file generated by
``dnssec-signzone``, or the output of ``dnssec-dsfromkey``, or the
output of a previous run of ``dnssec-cds``.
:iscman:`dnssec-signzone`, or the output of :iscman:`dnssec-dsfromkey`, or the
output of a previous run of :program:`dnssec-cds`.
The ``dnssec-cds`` command uses special DNSSEC validation logic
The :program:`dnssec-cds` command uses special DNSSEC validation logic
specified by :rfc:`7344`. It requires that the CDS and/or CDNSKEY records
be validly signed by a key represented in the existing DS records. This
is typically the pre-existing KSK.
For protection against replay attacks, the signatures on the child
records must not be older than they were on a previous run of
``dnssec-cds``. Their age is obtained from the modification time of the
``dsset-`` file, or from the ``-s`` option.
:program:`dnssec-cds`. Their age is obtained from the modification time of the
``dsset-`` file, or from the :option:`-s` option.
To protect against breaking the delegation, ``dnssec-cds`` ensures that
To protect against breaking the delegation, :program:`dnssec-cds` ensures that
the DNSKEY RRset can be verified by every key algorithm in the new DS
RRset, and that the same set of keys are covered by every DS digest
type.
By default, replacement DS records are written to the standard output;
with the ``-i`` option the input file is overwritten in place. The
with the :option:`-i` option the input file is overwritten in place. The
replacement DS records are the same as the existing records, when no
change is required. The output can be empty if the CDS/CDNSKEY records
specify that the child zone wants to be insecure.
.. warning::
Be careful not to delete the DS records when ``dnssec-cds`` fails!
Be careful not to delete the DS records when :program:`dnssec-cds` fails!
Alternatively, ``dnssec-cds -u`` writes an ``nsupdate`` script to the
standard output. The ``-u`` and ``-i`` options can be used together to
maintain a ``dsset-`` file as well as emit an ``nsupdate`` script.
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 :iscman:`nsupdate` script.
Options
~~~~~~~
``-a algorithm``
.. option:: -a algorithm
When converting CDS records to DS records, this option specifies
the acceptable digest algorithms. This option can be repeated, so
that multiple digest types are allowed. If none of the CDS records
use an acceptable digest type, ``dnssec-cds`` will try to use CDNSKEY
use an acceptable digest type, :program:`dnssec-cds` will try to use CDNSKEY
records instead; if there are no CDNSKEY records, it reports an error.
When converting CDNSKEY records to DS records, this option specifies the
@ -87,35 +90,40 @@ Options
are case-insensitive, and the hyphen may be omitted. If no algorithm
is specified, the default is SHA-256 only.
``-c class``
.. option:: -c class
This option specifies the DNS class of the zones.
``-D``
.. option:: -D
This option generates DS records from CDNSKEY records if both CDS and CDNSKEY
records are present in the child zone. By default CDS records are
preferred.
``-d path``
.. option:: -d path
This specifies the location of the parent DS records. The path can be the name of a file
containing the DS records; if it is a directory, ``dnssec-cds``
containing the DS records; if it is a directory, :program:`dnssec-cds`
looks for a ``dsset-`` file for the domain inside the directory.
To protect against replay attacks, child records are rejected if they
were signed earlier than the modification time of the ``dsset-``
file. This can be adjusted with the ``-s`` option.
file. This can be adjusted with the :option:`-s` option.
.. option:: -f child-file
``-f child-file``
This option specifies the file containing the child's CDS and/or CDNSKEY records, plus its
DNSKEY records and the covering RRSIG records, so that they can be
authenticated.
The examples below describe how to generate this file.
``-iextension``
.. option:: -i extension
This option updates the ``dsset-`` file in place, instead of writing DS records to
the standard output.
There must be no space between the ``-i`` and the extension. If
There must be no space between the :option:`-i` and the extension. If
no extension is provided, the old ``dsset-`` is discarded. If an
extension is present, a backup of the old ``dsset-`` file is kept
with the extension appended to its filename.
@ -125,7 +133,8 @@ Options
child records, provided that it is later than the file's current
modification time.
``-s start-time``
.. option:: -s start-time
This option specifies the date and time after which RRSIG records become
acceptable. This can be either an absolute or a relative time. An
absolute start time is indicated by a number in YYYYMMDDHHMMSS
@ -137,24 +146,28 @@ Options
If no start-time is specified, the modification time of the
``dsset-`` file is used.
``-T ttl``
.. option:: -T ttl
This option specifies a TTL to be used for new DS records. If not specified, the
default is the TTL of the old DS records. If they had no explicit TTL,
the new DS records also have no explicit TTL.
``-u``
This option writes an ``nsupdate`` script to the standard output, instead of
.. option:: -u
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 ``-T`` option, or using the
``nsupdate`` ``ttl`` command.
original ``dsset-`` file, with the :option:`-T` option, or using the
:iscman:`nsupdate` ``ttl`` command.
.. option:: -V
``-V``
This option prints version information.
``-v level``
.. option:: -v level
This option sets the debugging level. Level 1 is intended to be usefully verbose
for general users; higher levels are intended for developers.
@ -164,7 +177,7 @@ Options
Exit Status
~~~~~~~~~~~
The ``dnssec-cds`` command exits 0 on success, or non-zero if an error
The :program:`dnssec-cds` command exits 0 on success, or non-zero if an error
occurred.
If successful, the DS records may or may not need to be
@ -173,12 +186,12 @@ changed.
Examples
~~~~~~~~
Before running ``dnssec-signzone``, ensure that the delegations
are up-to-date by running ``dnssec-cds`` on every ``dsset-`` file.
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 ``dnssec-cds``, invoke
``dig`` as in the script below. It is acceptable if the ``dig`` fails, since
``dnssec-cds`` performs all the necessary checking.
To fetch the child records required by :program:`dnssec-cds`, invoke
:iscman:`dig` as in the script below. It is acceptable if the :iscman:`dig` fails, since
:program:`dnssec-cds` performs all the necessary checking.
::
@ -189,8 +202,8 @@ To fetch the child records required by ``dnssec-cds``, invoke
dnssec-cds -i -f /dev/stdin -d $f $d
done
When the parent zone is automatically signed by ``named``,
``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.
@ -204,5 +217,5 @@ protection time.
See Also
~~~~~~~~
:manpage:`dig(1)`, :manpage:`dnssec-settime(8)`, :manpage:`dnssec-signzone(8)`, :manpage:`nsupdate(1)`, BIND 9 Administrator
:iscman:`dig(1) <dig>`, :iscman:`dnssec-settime(8) <dnssec-settime>`, :iscman:`dnssec-signzone(8) <dnssec-signzone>`, :iscman:`nsupdate(1) <nsupdate>`, BIND 9 Administrator
Reference Manual, :rfc:`7344`.

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dnssec-dsfromkey
.. program:: dnssec-dsfromkey
.. _man_dnssec-dsfromkey:
dnssec-dsfromkey - DNSSEC DS RR generation tool
@ -30,34 +32,37 @@ Synopsis
Description
~~~~~~~~~~~
The ``dnssec-dsfromkey`` command outputs DS (Delegation Signer) resource records
(RRs), or CDS (Child DS) RRs with the ``-C`` option.
The :program:`dnssec-dsfromkey` command outputs DS (Delegation Signer) resource records
(RRs), or CDS (Child DS) RRs with the :option:`-C` option.
By default, only KSKs are converted (keys with flags = 257). The
``-A`` option includes ZSKs (flags = 256). Revoked keys are never
:option:`-A` option includes ZSKs (flags = 256). Revoked keys are never
included.
The input keys can be specified in a number of ways:
By default, ``dnssec-dsfromkey`` reads a key file named in the format
``Knnnn.+aaa+iiiii.key``, as generated by ``dnssec-keygen``.
By default, :program:`dnssec-dsfromkey` reads a key file named in the format
``Knnnn.+aaa+iiiii.key``, as generated by :iscman:`dnssec-keygen`.
With the ``-f file`` option, ``dnssec-dsfromkey`` reads keys from a zone
With the :option:`-f file <-f>` option, :program:`dnssec-dsfromkey` reads keys from a zone
file or partial zone file (which can contain just the DNSKEY records).
With the ``-s`` option, ``dnssec-dsfromkey`` reads a ``keyset-`` file,
as generated by ``dnssec-keygen`` ``-C``.
With the :option:`-s` option, :program:`dnssec-dsfromkey` reads a ``keyset-`` file,
as generated by :iscman:`dnssec-keygen` :option:`-C`.
Options
~~~~~~~
``-1``
This option is an abbreviation for ``-a SHA1``.
.. option:: -1
``-2``
This option is an abbreviation for ``-a SHA-256``.
This option is an abbreviation for :option:`-a SHA1 <-a>`.
.. option:: -2
This option is an abbreviation for :option:`-a SHA-256 <-a>`.
.. option:: -a algorithm
``-a algorithm``
This option specifies a digest algorithm to use when converting DNSKEY records to
DS records. This option can be repeated, so that multiple DS records
are created for each DNSKEY record.
@ -66,47 +71,57 @@ Options
are case-insensitive, and the hyphen may be omitted. If no algorithm
is specified, the default is SHA-256.
``-A``
.. option:: -A
This option indicates that ZSKs are to be included when generating DS records. Without this option, only
keys which have the KSK flag set are converted to DS records and
printed. This option is only useful in ``-f`` zone file mode.
printed. This option is only useful in :option:`-f` zone file mode.
``-c class``
This option specifies the DNS class; the default is IN. This option is only useful in ``-s`` keyset
or ``-f`` zone file mode.
.. option:: -c class
This option specifies the DNS class; the default is IN. This option is only useful in :option:`-s` keyset
or :option:`-f` zone file mode.
.. option:: -C
``-C``
This option generates CDS records rather than DS records.
``-f file``
This option sets zone file mode, in which the final dnsname argument of ``dnssec-dsfromkey`` is the
.. option:: -f file
This option sets zone file mode, in which the final dnsname argument of :program:`dnssec-dsfromkey` is the
DNS domain name of a zone whose master file can be read from
``file``. If the zone name is the same as ``file``, then it may be
omitted.
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``
``-h``
.. option:: -h
This option prints usage information.
``-K directory``
.. option:: -K directory
This option tells BIND 9 to look for key files or ``keyset-`` files in ``directory``.
``-s``
This option enables keyset mode, in which the final dnsname argument from ``dnssec-dsfromkey`` is the DNS
.. option:: -s
This option enables keyset mode, in which the final dnsname argument from :program:`dnssec-dsfromkey` is the DNS
domain name used to locate a ``keyset-`` file.
``-T TTL``
.. option:: -T TTL
This option specifies the TTL of the DS records. By default the TTL is omitted.
``-v level``
.. option:: -v level
This option sets the debugging level.
``-V``
.. option:: -V
This option prints version information.
Example
@ -126,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``.
@ -139,6 +154,6 @@ A keyfile error may return "file not found," even if the file exists.
See Also
~~~~~~~~
:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual,
:iscman:`dnssec-keygen(8) <dnssec-keygen>`, :iscman:`dnssec-signzone(8) <dnssec-signzone>`, BIND 9 Administrator Reference Manual,
:rfc:`3658` (DS RRs), :rfc:`4509` (SHA-256 for DS RRs),
:rfc:`6605` (SHA-384 for DS RRs), :rfc:`7344` (CDS and CDNSKEY RRs).

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dnssec-importkey
.. program:: dnssec-importkey
.. _man_dnssec-importkey:
dnssec-importkey - import DNSKEY records from external systems so they can be managed
@ -26,7 +28,7 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-importkey`` reads a public DNSKEY record and generates a pair
:program:`dnssec-importkey` reads a public DNSKEY record and generates a pair
of .key/.private files. The DNSKEY record may be read from an
existing .key file, in which case a corresponding .private file is
generated, or it may be read from any other file or from the standard
@ -34,14 +36,15 @@ input, in which case both .key and .private files are generated.
The newly created .private file does *not* contain private key data, and
cannot be used for signing. However, having a .private file makes it
possible to set publication (``-P``) and deletion (``-D``) times for the
possible to set publication (:option:`-P`) and deletion (:option:`-D`) times for the
key, which means the public key can be added to and removed from the
DNSKEY RRset on schedule even if the true private key is stored offline.
Options
~~~~~~~
``-f filename``
.. option:: -f filename
This option indicates the zone file mode. Instead of a public keyfile name, the argument is the
DNS domain name of a zone master file, which can be read from
``filename``. If the domain name is the same as ``filename``, then it may be
@ -50,23 +53,28 @@ Options
If ``filename`` is set to ``"-"``, then the zone data is read from the
standard input.
``-K directory``
.. option:: -K directory
This option sets the directory in which the key files are to reside.
``-L ttl``
.. option:: -L ttl
This option sets the default TTL to use for this key when it is converted into a
DNSKEY RR. This is the TTL used when the key is imported into a zone,
unless there was already a DNSKEY RRset in
place, in which case the existing TTL takes precedence. Setting the default TTL to ``0`` or ``none``
removes it from the key.
``-h``
.. option:: -h
This option emits a usage message and exits.
``-v level``
.. option:: -v level
This option sets the debugging level.
``-V``
.. option:: -V
This option prints version information.
Timing Options
@ -81,21 +89,25 @@ months (defined as 30 24-hour days), weeks, days, hours, or minutes,
respectively. Without a suffix, the offset is computed in seconds. To
explicitly prevent a date from being set, use ``none`` or ``never``.
``-P date/offset``
.. option:: -P date/offset
This option sets the date on which a key is to be published to the zone. After
that date, the key is included in the zone but is not used
to sign it.
``-P sync date/offset``
.. option:: -P sync date/offset
This option sets the date on which CDS and CDNSKEY records that match this key
are to be published to the zone.
``-D date/offset``
.. option:: -D date/offset
This option sets the date on which the key is to be deleted. After that date, the
key is no longer included in the zone. (However, it may remain in the key
repository.)
``-D sync date/offset``
.. option:: -D sync date/offset
This option sets the date on which the CDS and CDNSKEY records that match this
key are to be deleted.
@ -104,10 +116,10 @@ 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
~~~~~~~~
:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual,
:iscman:`dnssec-keygen(8) <dnssec-keygen>`, :iscman:`dnssec-signzone(8) <dnssec-signzone>`, BIND 9 Administrator Reference Manual,
:rfc:`5011`.

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dnssec-keyfromlabel
.. program:: dnssec-keyfromlabel
.. _man_dnssec-keyfromlabel:
dnssec-keyfromlabel - DNSSEC key generation tool
@ -24,10 +26,10 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-keyfromlabel`` generates a pair of key files that reference a
:program:`dnssec-keyfromlabel` generates a pair of key files that reference a
key object stored in a cryptographic hardware service module (HSM). The
private key file can be used for DNSSEC signing of zone data as if it
were a conventional signing key created by ``dnssec-keygen``, but the
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.
@ -37,40 +39,44 @@ match the name of the zone for which the key is being generated.
Options
~~~~~~~
``-a algorithm``
.. option:: -a algorithm
This option selects the cryptographic algorithm. The value of ``algorithm`` must
be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512,
ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448.
If no algorithm is specified, RSASHA1 is used by default
unless the ``-3`` option is specified, in which case NSEC3RSASHA1
is used instead. (If ``-3`` is used and an algorithm is
unless the :option:`-3` option is specified, in which case NSEC3RSASHA1
is used instead. (If :option:`-3` is used and an algorithm is
specified, that algorithm is checked for compatibility with
NSEC3.)
These values are case-insensitive. In some cases, abbreviations are
supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for
ECDSAP384SHA384. If RSASHA1 is specified along with the ``-3``
ECDSAP384SHA384. If RSASHA1 is specified along with the :option:`-3`
option, then NSEC3RSASHA1 is used instead.
Since BIND 9.12.0, this option is mandatory except when using the
``-S`` option, which copies the algorithm from the predecessory key.
:option:`-S` option, which copies the algorithm from the predecessory key.
Previously, the default for newly generated keys was RSASHA1.
``-3``
.. option:: -3
This option uses an NSEC3-capable algorithm to generate a DNSSEC key. If this
option is used with an algorithm that has both NSEC and NSEC3
versions, then the NSEC3 version is used; for example,
``dnssec-keygen -3a RSASHA1`` specifies the NSEC3RSASHA1 algorithm.
``-E engine``
.. option:: -E engine
This option specifies the cryptographic hardware to use.
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
engine identifier that drives the cryptographic accelerator or
hardware service module (usually ``pkcs11``).
``-l label``
.. option:: -l label
This option specifies the label for a key pair in the crypto hardware.
When BIND 9 is built with OpenSSL-based PKCS#11 support, the label is
@ -78,56 +84,67 @@ Options
preceded by an optional OpenSSL engine name, followed by a colon, as
in ``pkcs11:keylabel``.
``-n nametype``
.. option:: -n nametype
This option specifies the owner type of the key. The value of ``nametype`` must
either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY
(for a key associated with a host (KEY)), USER (for a key associated
with a user (KEY)), or OTHER (DNSKEY). These values are
case-insensitive.
``-C``
.. option:: -C
This option enables compatibility mode, which generates an old-style key, without any metadata.
By default, ``dnssec-keyfromlabel`` includes the key's creation
By default, :program:`dnssec-keyfromlabel` includes the key's creation
date in the metadata stored with the private key; other dates may
be set there as well, including publication date, activation date, etc. Keys
that include this data may be incompatible with older versions of
BIND; the ``-C`` option suppresses them.
BIND; the :option:`-C` option suppresses them.
.. option:: -c class
``-c class``
This option indicates that the DNS record containing the key should have the
specified class. If not specified, class IN is used.
``-f flag``
.. option:: -f flag
This option sets the specified flag in the ``flag`` field of the KEY/DNSKEY record.
The only recognized flags are KSK (Key-Signing Key) and REVOKE.
``-G``
.. option:: -G
This option generates a key, but does not publish it or sign with it. This option is
incompatible with ``-P`` and ``-A``.
incompatible with :option:`-P` and :option:`-A`.
.. option:: -h
``-h``
This option prints a short summary of the options and arguments to
``dnssec-keyfromlabel``.
:program:`dnssec-keyfromlabel`.
.. option:: -K directory
``-K directory``
This option sets the directory in which the key files are to be written.
``-k``
.. option:: -k
This option generates KEY records rather than DNSKEY records.
``-L`` ttl
.. option:: -L ttl
This option sets the default TTL to use for this key when it is converted into a
DNSKEY RR. This is the TTL used when the key is imported into a zone,
unless there was already a DNSKEY RRset in
place, in which case the existing TTL would take precedence. Setting
the default TTL to ``0`` or ``none`` removes it.
``-p protocol``
.. option:: -p protocol
This option sets the protocol value for the key. The protocol is a number between
0 and 255. The default is 3 (DNSSEC). Other possible values for this
argument are listed in :rfc:`2535` and its successors.
``-S key``
.. option:: -S key
This option generates a key as an explicit successor to an existing key. The name,
algorithm, size, and type of the key are set to match the
predecessor. The activation date of the new key is set to the
@ -135,19 +152,23 @@ Options
set to the activation date minus the prepublication interval, which
defaults to 30 days.
``-t type``
.. option:: -t type
This option indicates the type of the key. ``type`` must be one of AUTHCONF,
NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers
to the ability to authenticate data, and CONF to the ability to encrypt
data.
``-v level``
.. option:: -v level
This option sets the debugging level.
``-V``
.. option:: -V
This option prints version information.
``-y``
.. option:: -y
This option allows DNSSEC key files to be generated even if the key ID would
collide with that of an existing key, in the event of either key
being revoked. (This is only safe to enable if
@ -166,41 +187,49 @@ months (defined as 30 24-hour days), weeks, days, hours, or minutes,
respectively. Without a suffix, the offset is computed in seconds. To
explicitly prevent a date from being set, use ``none`` or ``never``.
``-P date/offset``
.. option:: -P date/offset
This option sets the date on which a key is to be published to the zone. After
that date, the key is included in the zone but is not used
to sign it. If not set, and if the ``-G`` option has not been used, the
to sign it. If not set, and if the :option:`-G` option has not been used, the
default is the current date.
``-P sync date/offset``
.. option:: -P sync date/offset
This option sets the date on which CDS and CDNSKEY records that match this key
are to be published to the zone.
``-A date/offset``
.. option:: -A date/offset
This option sets the date on which the key is to be activated. After that date,
the key is included in the zone and used to sign it. If not set,
and if the ``-G`` option has not been used, the default is the current date.
and if the :option:`-G` option has not been used, the default is the current date.
.. option:: -R date/offset
``-R date/offset``
This option sets the date on which the key is to be revoked. After that date, the
key is flagged as revoked. It is included in the zone and
is used to sign it.
``-I date/offset``
.. option:: -I date/offset
This option sets the date on which the key is to be retired. After that date, the
key is still included in the zone, but it is not used to
sign it.
``-D date/offset``
.. option:: -D date/offset
This option sets the date on which the key is to be deleted. After that date, the
key is no longer included in the zone. (However, it may remain in the key
repository.)
``-D sync date/offset``
.. option:: -D sync date/offset
This option sets the date on which the CDS and CDNSKEY records that match this
key are to be deleted.
``-i interval``
.. option:: -i interval
This option sets the prepublication interval for a key. If set, then the
publication and activation dates must be separated by at least this
much time. If the activation date is specified but the publication
@ -221,7 +250,7 @@ explicitly prevent a date from being set, use ``none`` or ``never``.
Generated Key Files
~~~~~~~~~~~~~~~~~~~
When ``dnssec-keyfromlabel`` completes successfully, it prints a string
When :program:`dnssec-keyfromlabel` completes successfully, it prints a string
of the form ``Knnnn.+aaa+iiiii`` to the standard output. This is an
identification string for the key files it has generated.
@ -231,7 +260,7 @@ identification string for the key files it has generated.
- ``iiiii`` is the key identifier (or footprint).
``dnssec-keyfromlabel`` creates two files, with names based on the
:program:`dnssec-keyfromlabel` creates two files, with names based on the
printed string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and
``Knnnn.+aaa+iiiii.private`` contains the private key.
@ -244,5 +273,5 @@ security reasons, this file does not have general read permission.
See Also
~~~~~~~~
:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual,
:iscman:`dnssec-keygen(8) <dnssec-keygen>`, :iscman:`dnssec-signzone(8) <dnssec-signzone>`, BIND 9 Administrator Reference Manual,
:rfc:`4034`, :rfc:`7512`.

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dnssec-keygen
.. program:: dnssec-keygen
.. _man_dnssec-keygen:
dnssec-keygen: DNSSEC key generation tool
@ -24,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-keygen`` generates keys for DNSSEC (Secure DNS), as defined in
:program:`dnssec-keygen` generates keys for DNSSEC (Secure DNS), as defined in
:rfc:`2535` and :rfc:`4034`. It can also generate keys for use with TSIG
(Transaction Signatures) as defined in :rfc:`2845`, or TKEY (Transaction
Key) as defined in :rfc:`2930`.
@ -36,32 +38,35 @@ generated.
Options
~~~~~~~
``-3``
.. option:: -3
This option uses an NSEC3-capable algorithm to generate a DNSSEC key. If this
option is used with an algorithm that has both NSEC and NSEC3
versions, then the NSEC3 version is selected; for example,
``dnssec-keygen -3a RSASHA1`` specifies the NSEC3RSASHA1 algorithm.
``-a algorithm``
.. option:: -a algorithm
This option selects the cryptographic algorithm. For DNSSEC keys, the value of
``algorithm`` must be one of RSASHA1, NSEC3RSASHA1, RSASHA256,
RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. For
TKEY, the value must be DH (Diffie-Hellman); specifying this value
automatically sets the ``-T KEY`` option as well.
automatically sets the :option:`-T KEY <-T>` option as well.
These values are case-insensitive. In some cases, abbreviations are
supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for
ECDSAP384SHA384. If RSASHA1 is specified along with the ``-3``
ECDSAP384SHA384. If RSASHA1 is specified along with the :option:`-3`
option, NSEC3RSASHA1 is used instead.
This parameter *must* be specified except when using the ``-S``
This parameter *must* be specified except when using the :option:`-S`
option, which copies the algorithm from the predecessor key.
In prior releases, HMAC algorithms could be generated for use as TSIG
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
``-b keysize``
This option specifies the number of bits in the key. The choice of key size
depends on the algorithm used: RSA keys must be between 1024 and 4096
bits; Diffie-Hellman keys must be between 128 and 4096 bits. Elliptic
@ -70,63 +75,74 @@ Options
If the key size is not specified, some algorithms have pre-defined
defaults. For example, RSA keys for use as DNSSEC zone-signing keys
have a default size of 1024 bits; RSA keys for use as key-signing
keys (KSKs, generated with ``-f KSK``) default to 2048 bits.
keys (KSKs, generated with :option:`-f KSK <-f>`) default to 2048 bits.
.. option:: -C
``-C``
This option enables compatibility mode, which generates an old-style key, without any timing
metadata. By default, ``dnssec-keygen`` includes the key's
metadata. By default, :program:`dnssec-keygen` includes the key's
creation date in the metadata stored with the private key; other
dates may be set there as well, including publication date, activation date,
etc. Keys that include this data may be incompatible with older
versions of BIND; the ``-C`` option suppresses them.
versions of BIND; the :option:`-C` option suppresses them.
.. option:: -c class
``-c class``
This option indicates that the DNS record containing the key should have the
specified class. If not specified, class IN is used.
``-d bits``
.. option:: -d bits
This option specifies the key size in bits. For the algorithms RSASHA1, NSEC3RSASA1, RSASHA256, and
RSASHA512 the key size must be between 1024 and 4096 bits; DH size is between 128
and 4096 bits. This option is ignored for algorithms ECDSAP256SHA256,
ECDSAP384SHA384, ED25519, and ED448.
``-E engine``
.. option:: -E engine
This option specifies the cryptographic hardware to use, when applicable.
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
engine identifier that drives the cryptographic accelerator or
hardware service module (usually ``pkcs11``).
``-f flag``
.. option:: -f flag
This option sets the specified flag in the flag field of the KEY/DNSKEY record.
The only recognized flags are KSK (Key-Signing Key) and REVOKE.
``-G``
This option generates a key, but does not publish it or sign with it. This option is
incompatible with ``-P`` and ``-A``.
.. option:: -G
This option generates a key, but does not publish it or sign with it. This option is
incompatible with :option:`-P` and :option:`-A`.
.. option:: -g generator
``-g generator``
This option indicates the generator to use if generating a Diffie-Hellman key. Allowed
values are 2 and 5. If no generator is specified, a known prime from
:rfc:`2539` is used if possible; otherwise the default is 2.
``-h``
This option prints a short summary of the options and arguments to
``dnssec-keygen``.
.. option:: -h
This option prints a short summary of the options and arguments to
:program:`dnssec-keygen`.
.. option:: -K directory
``-K directory``
This option sets the directory in which the key files are to be written.
``-k policy``
.. option:: -k policy
This option creates keys for a specific ``dnssec-policy``. If a policy uses multiple keys,
``dnssec-keygen`` generates multiple keys. This also
:program:`dnssec-keygen` generates multiple keys. This also
creates a ".state" file to keep track of the key state.
This option creates keys according to the ``dnssec-policy`` configuration, hence
it cannot be used at the same time as many of the other options that
``dnssec-keygen`` provides.
:program:`dnssec-keygen` provides.
.. option:: -L ttl
``-L ttl``
This option sets the default TTL to use for this key when it is converted into a
DNSKEY RR. This is the TTL used when the key is imported into a zone,
unless there was already a DNSKEY RRset in
@ -135,26 +151,30 @@ Options
defaults to the SOA TTL. Setting the default TTL to ``0`` or ``none``
is the same as leaving it unset.
``-l file``
This option provides a configuration file that contains a ``dnssec-policy`` statement
(matching the policy set with ``-k``).
.. option:: -l file
This option provides a configuration file that contains a ``dnssec-policy`` statement
(matching the policy set with :option:`-k`).
.. option:: -n nametype
``-n nametype``
This option specifies the owner type of the key. The value of ``nametype`` must
either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY
(for a key associated with a host (KEY)), USER (for a key associated
with a user (KEY)), or OTHER (DNSKEY). These values are
case-insensitive. The default is ZONE for DNSKEY generation.
``-p protocol``
.. option:: -p protocol
This option sets the protocol value for the generated key, for use with
``-T KEY``. The protocol is a number between 0 and 255. The default
:option:`-T KEY <-T>`. The protocol is a number between 0 and 255. The default
is 3 (DNSSEC). Other possible values for this argument are listed in
:rfc:`2535` and its successors.
``-q``
.. option:: -q
This option sets quiet mode, which suppresses unnecessary output, including progress
indication. Without this option, when ``dnssec-keygen`` is run
indication. Without this option, when :program:`dnssec-keygen` is run
interactively to generate an RSA or DSA key pair, it prints a
string of symbols to ``stderr`` indicating the progress of the key
generation. A ``.`` indicates that a random number has been found which
@ -162,7 +182,8 @@ Options
round of the Miller-Rabin primality test; and a space ( ) means that the
number has passed all the tests and is a satisfactory key.
``-S key``
.. option:: -S key
This option creates a new key which is an explicit successor to an existing key.
The name, algorithm, size, and type of the key are set to match
the existing key. The activation date of the new key is set to
@ -170,26 +191,31 @@ Options
set to the activation date minus the prepublication interval,
which defaults to 30 days.
``-s strength``
.. option:: -s strength
This option specifies the strength value of the key. The strength is a number
between 0 and 15, and currently has no defined purpose in DNSSEC.
``-T rrtype``
.. option:: -T rrtype
This option specifies the resource record type to use for the key. ``rrtype``
must be either DNSKEY or KEY. The default is DNSKEY when using a
DNSSEC algorithm, but it can be overridden to KEY for use with
SIG(0).
``-t type``
This option indicates the type of the key for use with ``-T KEY``. ``type``
.. option:: -t type
This option indicates the type of the key for use with :option:`-T KEY <-T>`. ``type``
must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
is AUTHCONF. AUTH refers to the ability to authenticate data, and
CONF to the ability to encrypt data.
``-V``
.. option:: -V
This option prints version information.
``-v level``
.. option:: -v level
This option sets the debugging level.
Timing Options
@ -204,43 +230,51 @@ months (defined as 30 24-hour days), weeks, days, hours, or minutes,
respectively. Without a suffix, the offset is computed in seconds. To
explicitly prevent a date from being set, use ``none`` or ``never``.
``-P date/offset``
.. option:: -P date/offset
This option sets the date on which a key is to be published to the zone. After
that date, the key is included in the zone but is not used
to sign it. If not set, and if the ``-G`` option has not been used, the
to sign it. If not set, and if the :option:`-G` option has not been used, the
default is the current date.
``-P sync date/offset``
.. option:: -P sync date/offset
This option sets the date on which CDS and CDNSKEY records that match this key
are to be published to the zone.
``-A date/offset``
.. option:: -A date/offset
This option sets the date on which the key is to be activated. After that date,
the key is included in the zone and used to sign it. If not set,
and if the ``-G`` option has not been used, the default is the current date. If set,
and ``-P`` is not set, the publication date is set to the
and if the :option:`-G` option has not been used, the default is the current date. If set,
and :option:`-P` is not set, the publication date is set to the
activation date minus the prepublication interval.
``-R date/offset``
.. option:: -R date/offset
This option sets the date on which the key is to be revoked. After that date, the
key is flagged as revoked. It is included in the zone and
is used to sign it.
``-I date/offset``
.. option:: -I date/offset
This option sets the date on which the key is to be retired. After that date, the
key is still included in the zone, but it is not used to
sign it.
``-D date/offset``
.. option:: -D date/offset
This option sets the date on which the key is to be deleted. After that date, the
key is no longer included in the zone. (However, it may remain in the key
repository.)
``-D sync date/offset``
.. option:: -D sync date/offset
This option sets the date on which the CDS and CDNSKEY records that match this
key are to be deleted.
``-i interval``
.. option:: -i interval
This option sets the prepublication interval for a key. If set, then the
publication and activation dates must be separated by at least this
much time. If the activation date is specified but the publication
@ -261,7 +295,7 @@ explicitly prevent a date from being set, use ``none`` or ``never``.
Generated Keys
~~~~~~~~~~~~~~
When ``dnssec-keygen`` completes successfully, it prints a string of the
When :program:`dnssec-keygen` completes successfully, it prints a string of the
form ``Knnnn.+aaa+iiiii`` to the standard output. This is an
identification string for the key it has generated.
@ -271,12 +305,12 @@ identification string for the key it has generated.
- ``iiiii`` is the key identifier (or footprint).
``dnssec-keygen`` creates two files, with names based on the printed
:program:`dnssec-keygen` creates two files, with names based on the printed
string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and
``Knnnn.+aaa+iiiii.private`` contains the private key.
The ``.key`` file contains a DNSKEY or KEY record. When a zone is being
signed by ``named`` or ``dnssec-signzone -S``, DNSKEY records are
signed by :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.
@ -295,7 +329,7 @@ The command prints a string of the form:
``Kexample.com.+013+26160``
In this example, ``dnssec-keygen`` creates the files
In this example, :program:`dnssec-keygen` creates the files
``Kexample.com.+013+26160.key`` and ``Kexample.com.+013+26160.private``.
To generate a matching key-signing key, issue the command:
@ -305,5 +339,5 @@ To generate a matching key-signing key, issue the command:
See Also
~~~~~~~~
:manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual, :rfc:`2539`,
:iscman:`dnssec-signzone(8) <dnssec-signzone>`, BIND 9 Administrator Reference Manual, :rfc:`2539`,
:rfc:`2845`, :rfc:`4034`.

32
bin/dnssec/dnssec-revoke.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dnssec-revoke
.. program:: dnssec-revoke
.. _man_dnssec-revoke:
dnssec-revoke - set the REVOKED bit on a DNSSEC key
@ -24,45 +26,53 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-revoke`` reads a DNSSEC key file, sets the REVOKED bit on the
:program:`dnssec-revoke` reads a DNSSEC key file, sets the REVOKED bit on the
key as defined in :rfc:`5011`, and creates a new pair of key files
containing the now-revoked key.
Options
~~~~~~~
``-h``
.. option:: -h
This option emits a usage message and exits.
``-K directory``
.. option:: -K directory
This option sets the directory in which the key files are to reside.
``-r``
.. option:: -r
This option indicates to remove the original keyset files after writing the new keyset files.
``-v level``
.. option:: -v level
This option sets the debugging level.
``-V``
.. option:: -V
This option prints version information.
``-E engine``
.. option:: -E engine
This option specifies the cryptographic hardware to use, when applicable.
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
engine identifier that drives the cryptographic accelerator or
hardware service module (usually ``pkcs11``).
``-f``
This option indicates a forced overwrite and causes ``dnssec-revoke`` to write the new key pair,
.. option:: -f
This option indicates a forced overwrite and causes :program:`dnssec-revoke` to write the new key pair,
even if a file already exists matching the algorithm and key ID of
the revoked key.
``-R``
.. option:: -R
This option prints the key tag of the key with the REVOKE bit set, but does not
revoke the key.
See Also
~~~~~~~~
:manpage:`dnssec-keygen(8)`, BIND 9 Administrator Reference Manual, :rfc:`5011`.
:iscman:`dnssec-keygen(8) <dnssec-keygen>`, BIND 9 Administrator Reference Manual, :rfc:`5011`.

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dnssec-settime
.. program:: dnssec-settime
.. _man_dnssec-settime:
dnssec-settime: set the key timing metadata for a DNSSEC key
@ -24,14 +26,14 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-settime`` reads a DNSSEC private key file and sets the key
timing metadata as specified by the ``-P``, ``-A``, ``-R``, ``-I``, and
``-D`` options. The metadata can then be used by ``dnssec-signzone`` or
other signing software to determine when a key is to be published,
whether it should be used for signing a zone, etc.
: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
: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,
``dnssec-settime`` simply prints the key timing metadata already stored
:program:`dnssec-settime` simply prints the key timing metadata already stored
in the key.
When key metadata fields are changed, both files of a key pair
@ -44,12 +46,12 @@ the key file. The private file's permissions are always set to be
inaccessible to anyone other than the owner (mode 0600).
When working with state files, it is possible to update the timing metadata in
those files as well with ``-s``. With this option, it is also possible to update key
states with ``-d`` (DS), ``-k`` (DNSKEY), ``-r`` (RRSIG of KSK), or ``-z``
(RRSIG of ZSK). Allowed states are HIDDEN, RUMOURED, OMNIPRESENT, and
UNRETENTIVE.
those files as well with :option:`-s`. With this option, it is also possible
to update key states with :option:`-d` (DS), :option:`-k` (DNSKEY), :option:`-r`
(RRSIG of KSK), or :option:`-z` (RRSIG of ZSK). Allowed states are HIDDEN,
RUMOURED, OMNIPRESENT, and UNRETENTIVE.
The goal state of the key can also be set with ``-g``. This should be either
The goal state of the key can also be set with :option:`-g`. This should be either
HIDDEN or OMNIPRESENT, representing whether the key should be removed from the
zone or published.
@ -59,19 +61,22 @@ purposes.
Options
~~~~~~~
``-f``
.. option:: -f
This option forces an update of an old-format key with no metadata fields. Without
this option, ``dnssec-settime`` fails when attempting to update a
this option, :program:`dnssec-settime` fails when attempting to update a
legacy key. With this option, the key is recreated in the new
format, but with the original key data retained. The key's creation
date is set to the present time. If no other values are
specified, then the key's publication and activation dates are also
set to the present time.
``-K directory``
.. option:: -K directory
This option sets the directory in which the key files are to reside.
``-L ttl``
.. option:: -L ttl
This option sets the default TTL to use for this key when it is converted into a
DNSKEY RR. This is the TTL used when the key is imported into a zone,
unless there was already a DNSKEY RRset in
@ -80,16 +85,20 @@ Options
defaults to the SOA TTL. Setting the default TTL to ``0`` or ``none``
removes it from the key.
``-h``
.. option:: -h
This option emits a usage message and exits.
``-V``
.. option:: -V
This option prints version information.
``-v level``
.. option:: -v level
This option sets the debugging level.
``-E engine``
.. option:: -E engine
This option specifies the cryptographic hardware to use, when applicable.
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
@ -108,47 +117,57 @@ months (defined as 30 24-hour days), weeks, days, hours, or minutes,
respectively. Without a suffix, the offset is computed in seconds. To
explicitly prevent a date from being set, use ``none`` or ``never``.
``-P date/offset``
.. option:: -P date/offset
This option sets the date on which a key is to be published to the zone. After
that date, the key is included in the zone but is not used
to sign it.
``-P ds date/offset``
.. option:: -P ds date/offset
This option sets the date on which DS records that match this key have been
seen in the parent zone.
``-P sync date/offset``
.. option:: -P sync date/offset
This option sets the date on which CDS and CDNSKEY records that match this key
are to be published to the zone.
``-A date/offset``
.. option:: -A date/offset
This option sets the date on which the key is to be activated. After that date,
the key is included in the zone and used to sign it.
``-R date/offset``
.. option:: -R date/offset
This option sets the date on which the key is to be revoked. After that date, the
key is flagged as revoked. It is included in the zone and
is used to sign it.
``-I date/offset``
.. option:: -I date/offset
This option sets the date on which the key is to be retired. After that date, the
key is still included in the zone, but it is not used to
sign it.
``-D date/offset``
.. option:: -D date/offset
This option sets the date on which the key is to be deleted. After that date, the
key is no longer included in the zone. (However, it may remain in the key
repository.)
``-D ds date/offset``
.. option:: -D ds date/offset
This option sets the date on which the DS records that match this key have
been seen removed from the parent zone.
``-D sync date/offset``
.. option:: -D sync date/offset
This option sets the date on which the CDS and CDNSKEY records that match this
key are to be deleted.
``-S predecessor key``
.. option:: -S predecessor key
This option selects a key for which the key being modified is an explicit
successor. The name, algorithm, size, and type of the predecessor key
must exactly match those of the key being modified. The activation
@ -156,7 +175,8 @@ explicitly prevent a date from being set, use ``none`` or ``never``.
predecessor. The publication date is set to the activation date
minus the prepublication interval, which defaults to 30 days.
``-i interval``
.. option:: -i interval
This option sets the prepublication interval for a key. If set, then the
publication and activation dates must be separated by at least this
much time. If the activation date is specified but the publication
@ -183,36 +203,44 @@ purpose, but should never be used in production.
Known key states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE.
``-s``
.. option:: -s
This option indicates that when setting key timing data, the state file should also be updated.
``-g state``
.. option:: -g state
This option sets the goal state for this key. Must be HIDDEN or OMNIPRESENT.
``-d state date/offset``
.. option:: -d state date/offset
This option sets the DS state for this key as of the specified date, offset from the current date.
``-k state date/offset``
.. option:: -k state date/offset
This option sets the DNSKEY state for this key as of the specified date, offset from the current date.
``-r state date/offset``
.. option:: -r state date/offset
This option sets the RRSIG (KSK) state for this key as of the specified date, offset from the current date.
``-z state date/offset``
.. option:: -z state date/offset
This option sets the RRSIG (ZSK) state for this key as of the specified date, offset from the current date.
Printing Options
~~~~~~~~~~~~~~~~
``dnssec-settime`` can also be used to print the timing metadata
:program:`dnssec-settime` can also be used to print the timing metadata
associated with a key.
``-u``
.. option:: -u
This option indicates that times should be printed in Unix epoch format.
``-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all``
.. option:: -p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all
This option prints a specific metadata value or set of metadata values.
The ``-p`` option may be followed by one or more of the following letters or
The :option:`-p` option may be followed by one or more of the following letters or
strings to indicate which value or values to print: ``C`` for the
creation date, ``P`` for the publication date, ``Pds` for the DS publication
date, ``Psync`` for the CDS and CDNSKEY publication date, ``A`` for the
@ -224,5 +252,5 @@ associated with a key.
See Also
~~~~~~~~
:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual,
:iscman:`dnssec-keygen(8) <dnssec-keygen>`, :iscman:`dnssec-signzone(8) <dnssec-signzone>`, BIND 9 Administrator Reference Manual,
:rfc:`5011`.

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dnssec-signzone
.. program:: dnssec-signzone
.. _man_dnssec-signzone:
dnssec-signzone - DNSSEC zone signing tool
@ -24,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-signzone`` signs a zone; it generates NSEC and RRSIG records
:program:`dnssec-signzone` signs a zone; it generates NSEC and RRSIG records
and produces a signed version of the zone. The security status of
delegations from the signed zone (that is, whether the child zones are
secure) is determined by the presence or absence of a ``keyset``
@ -33,29 +35,35 @@ file for each child zone.
Options
~~~~~~~
``-a``
.. option:: -a
This option verifies all generated signatures.
``-c class``
.. option:: -c class
This option specifies the DNS class of the zone.
``-C``
.. option:: -C
This option sets compatibility mode, in which a ``keyset-zonename`` file is generated in addition
to ``dsset-zonename`` when signing a zone, for use by older versions
of ``dnssec-signzone``.
of :program:`dnssec-signzone`.
.. option:: -d directory
``-d directory``
This option indicates the directory where BIND 9 should look for ``dsset-`` or ``keyset-`` files.
``-D``
.. option:: -D
This option indicates that only those record types automatically managed by
``dnssec-signzone``, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output.
If smart signing (``-S``) is used, DNSKEY records are also included.
:program:`dnssec-signzone`, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output.
If smart signing (:option:`-S`) is used, DNSKEY records are also included.
The resulting file can be included in the original zone file with
``$INCLUDE``. This option cannot be combined with ``-O raw``
``$INCLUDE``. This option cannot be combined with :option:`-O raw <-O>`
or serial-number updating.
``-E engine``
.. option:: -E engine
This option specifies the hardware to use for cryptographic
operations, such as a secure key store used for signing, when applicable.
@ -63,19 +71,23 @@ Options
engine identifier that drives the cryptographic accelerator or
hardware service module (usually ``pkcs11``).
``-g``
.. option:: -g
This option indicates that DS records for child zones should be generated from a ``dsset-`` or ``keyset-``
file. Existing DS records are removed.
``-K directory``
.. option:: -K directory
This option specifies the directory to search for DNSSEC keys. If not
specified, it defaults to the current directory.
``-k key``
.. option:: -k key
This option tells BIND 9 to treat the specified key as a key-signing key, ignoring any key flags. This
option may be specified multiple times.
``-M maxttl``
.. option:: -M maxttl
This option sets the maximum TTL for the signed zone. Any TTL higher than ``maxttl``
in the input zone is reduced to ``maxttl`` in the output. This
provides certainty as to the largest possible TTL in the signed zone,
@ -83,10 +95,11 @@ Options
possible time before signatures that have been retrieved by resolvers
expire from resolver caches. Zones that are signed with this
option should be configured to use a matching ``max-zone-ttl`` in
``named.conf``. (Note: This option is incompatible with ``-D``,
:iscman:`named.conf`. (Note: This option is incompatible with :option:`-D`,
because it modifies non-DNSSEC data in the output zone.)
``-s start-time``
.. option:: -s start-time
This option specifies the date and time when the generated RRSIG records become
valid. This can be either an absolute or relative time. An absolute
start time is indicated by a number in YYYYMMDDHHMMSS notation;
@ -95,7 +108,8 @@ Options
time. If no ``start-time`` is specified, the current time minus 1
hour (to allow for clock skew) is used.
``-e end-time``
.. option:: -e end-time
This option specifies the date and time when the generated RRSIG records expire. As
with ``start-time``, an absolute time is indicated in YYYYMMDDHHMMSS
notation. A time relative to the start time is indicated with ``+N``,
@ -104,7 +118,8 @@ Options
specified, 30 days from the start time is the default.
``end-time`` must be later than ``start-time``.
``-X extended end-time``
.. option:: -X extended end-time
This option specifies the date and time when the generated RRSIG records for the
DNSKEY RRset expire. This is to be used in cases when the DNSKEY
signatures need to persist longer than signatures on other records;
@ -119,20 +134,24 @@ Options
as the default. (``end-time``, in turn, defaults to 30 days from the
start time.) ``extended end-time`` must be later than ``start-time``.
``-f output-file``
.. option:: -f output-file
This option indicates the name of the output file containing the signed zone. The default
is to append ``.signed`` to the input filename. If ``output-file`` is
set to ``-``, then the signed zone is written to the standard
output, with a default output format of ``full``.
``-h``
This option prints a short summary of the options and arguments to
``dnssec-signzone``.
.. option:: -h
This option prints a short summary of the options and arguments to
:program:`dnssec-signzone`.
.. option:: -V
``-V``
This option prints version information.
``-i interval``
.. option:: -i interval
This option indicates that, when a previously signed zone is passed as input, records may be
re-signed. The ``interval`` option specifies the cycle interval as an
offset from the current time, in seconds. If a RRSIG record expires
@ -141,19 +160,21 @@ Options
The default cycle interval is one quarter of the difference between
the signature end and start times. So if neither ``end-time`` nor
``start-time`` is specified, ``dnssec-signzone`` generates
``start-time`` is specified, :program:`dnssec-signzone` generates
signatures that are valid for 30 days, with a cycle interval of 7.5
days. Therefore, if any existing RRSIG records are due to expire in
less than 7.5 days, they are replaced.
``-I input-format``
.. option:: -I input-format
This option sets the format of the input zone file. Possible formats are
``text`` (the default), and ``raw``. This option is primarily
intended to be used for dynamic signed zones, so that the dumped zone
file in a non-text format containing updates can be signed directly.
This option is not useful for non-dynamic zones.
``-j jitter``
.. option:: -j jitter
When signing a zone with a fixed signature lifetime, all RRSIG
records issued at the time of signing expire simultaneously. If the
zone is incrementally signed, i.e., a previously signed zone is passed
@ -168,16 +189,19 @@ Options
less congestion than if all validators need to refetch at around the
same time.
``-L serial``
.. option:: -L serial
When writing a signed zone to "raw" format, this option sets the "source
serial" value in the header to the specified ``serial`` number. (This is
expected to be used primarily for testing purposes.)
``-n ncpus``
.. option:: -n ncpus
This option specifies the number of threads to use. By default, one thread is
started for each detected CPU.
``-N soa-serial-format``
.. option:: -N soa-serial-format
This option sets the SOA serial number format of the signed zone. Possible formats are
``keep`` (the default), ``increment``, ``unixtime``, and
``date``.
@ -200,21 +224,24 @@ Options
than or equal to that value, in which case it is simply
incremented by one.
``-o origin``
.. option:: -o origin
This option sets the zone origin. If not specified, the name of the zone file is
assumed to be the origin.
``-O output-format``
.. option:: -O output-format
This option sets the format of the output file containing the signed
zone. Possible formats are ``text`` (the default), which is the standard
textual representation of the zone; ``full``, which is text output in a
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.
``-P``
.. option:: -P
This option disables post-sign verification tests.
The post-sign verification tests ensure that for each algorithm in
@ -222,36 +249,40 @@ Options
revoked KSK keys are self-signed, and that all records in the zone
are signed by the algorithm. This option skips these tests.
``-Q``
.. option:: -Q
This option removes signatures from keys that are no longer active.
Normally, when a previously signed zone is passed as input to the
signer, and a DNSKEY record has been removed and replaced with a new
one, signatures from the old key that are still within their validity
period are retained. This allows the zone to continue to validate
with cached copies of the old DNSKEY RRset. The ``-Q`` option forces
``dnssec-signzone`` to remove signatures from keys that are no longer
with cached copies of the old DNSKEY RRset. The :option:`-Q` option forces
:program:`dnssec-signzone` to remove signatures from keys that are no longer
active. This enables ZSK rollover using the procedure described in
:rfc:`4641#4.2.1.1` ("Pre-Publish Key Rollover").
``-q``
.. option:: -q
This option enables quiet mode, which suppresses unnecessary output. Without this option, when
``dnssec-signzone`` is run it prints three pieces of information to standard output: the number of
:program:`dnssec-signzone` is run it prints three pieces of information to standard output: the number of
keys in use; the algorithms used to verify the zone was signed correctly and
other status information; and the filename containing the signed
zone. With the option that output is suppressed, leaving only the filename.
``-R``
.. option:: -R
This option removes signatures from keys that are no longer published.
This option is similar to ``-Q``, except it forces
``dnssec-signzone`` to remove signatures from keys that are no longer
This option is similar to :option:`-Q`, except it forces
:program:`dnssec-signzone` to remove signatures from keys that are no longer
published. This enables ZSK rollover using the procedure described in
:rfc:`4641#4.2.1.2` ("Double Signature Zone Signing Key
Rollover").
``-S``
This option enables smart signing, which instructs ``dnssec-signzone`` to search the key
.. option:: -S
This option enables smart signing, which instructs :program:`dnssec-signzone` to search the key
repository for keys that match the zone being signed, and to include
them in the zone if appropriate.
@ -283,11 +314,12 @@ Options
If the key's sync deletion date is set and is in the past,
synchronization records (type CDS and/or CDNSKEY) are removed.
``-T ttl``
.. option:: -T ttl
This option specifies a TTL to be used for new DNSKEY records imported into the
zone from the key repository. If not specified, the default is the
TTL value from the zone's SOA record. This option is ignored when
signing without ``-S``, since DNSKEY records are not imported from
signing without :option:`-S`, since DNSKEY records are not imported from
the key repository in that case. It is also ignored if there are any
pre-existing DNSKEY records at the zone apex, in which case new
records' TTL values are set to match them, or if any of the
@ -295,51 +327,63 @@ Options
conflict between TTL values in imported keys, the shortest one is
used.
``-t``
.. option:: -t
This option prints statistics at completion.
``-u``
.. option:: -u
This option updates the NSEC/NSEC3 chain when re-signing a previously signed zone.
With this option, a zone signed with NSEC can be switched to NSEC3,
or a zone signed with NSEC3 can be switched to NSEC or to NSEC3 with
different parameters. Without this option, ``dnssec-signzone``
different parameters. Without this option, :program:`dnssec-signzone`
retains the existing chain when re-signing.
``-v level``
.. option:: -v level
This option sets the debugging level.
``-x``
.. option:: -x
This option indicates that BIND 9 should only sign the DNSKEY, CDNSKEY, and CDS RRsets with key-signing keys,
and should omit signatures from zone-signing keys. (This is similar to the
``dnssec-dnskey-kskonly yes;`` zone option in ``named``.)
``dnssec-dnskey-kskonly yes;`` zone option in :iscman:`named`.)
.. option:: -z
``-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
``-3 salt``
This option generates an NSEC3 chain with the given hex-encoded salt. A dash
(-) can be used to indicate that no salt is to be used when
generating the NSEC3 chain.
``-H iterations``
.. option:: -H iterations
This option indicates that, when generating an NSEC3 chain, BIND 9 should use this many iterations. The default
is 10.
``-A``
.. option:: -A
This option indicates that, when generating an NSEC3 chain, BIND 9 should set the OPTOUT flag on all NSEC3
records and should not generate NSEC3 records for insecure delegations.
Using this option twice (i.e., ``-AA``) turns the OPTOUT flag off for
all records. This is useful when using the ``-u`` option to modify an
.. option:: -AA
This option turns the OPTOUT flag off for
all records. This is useful when using the :option:`-u` option to modify an
NSEC3 chain which previously had OPTOUT set.
``zonefile``
.. option:: zonefile
This option sets the file containing the zone to be signed.
``key``
.. option:: key
This option specifies which keys should be used to sign the zone. If no keys are
specified, the zone is examined for DNSKEY records at the
zone apex. If these records are found and there are matching private keys in
@ -349,11 +393,11 @@ Example
~~~~~~~
The following command signs the ``example.com`` zone with the
ECDSAP256SHA256 key generated by ``dnssec-keygen``
(Kexample.com.+013+17247). Because the ``-S`` option is not being used,
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
DS records can be imported from them (``-g``).
DS records can be imported from them (:option:`-g`).
::
@ -362,9 +406,9 @@ DS records can be imported from them (``-g``).
db.example.com.signed
%
In the above example, ``dnssec-signzone`` creates the file
In the above example, :program:`dnssec-signzone` creates the file
``db.example.com.signed``. This file should be referenced in a zone
statement in the ``named.conf`` file.
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.
@ -379,5 +423,5 @@ The private keys are assumed to be in the current directory.
See Also
~~~~~~~~
:manpage:`dnssec-keygen(8)`, BIND 9 Administrator Reference Manual, :rfc:`4033`,
:iscman:`dnssec-keygen(8) <dnssec-keygen>`, BIND 9 Administrator Reference Manual, :rfc:`4033`,
:rfc:`4641`.

42
bin/dnssec/dnssec-verify.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dnssec-verify
.. program:: dnssec-verify
.. _man_dnssec-verify:
dnssec-verify - DNSSEC zone verification tool
@ -24,55 +26,64 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-verify`` verifies that a zone is fully signed for each
:program:`dnssec-verify` verifies that a zone is fully signed for each
algorithm found in the DNSKEY RRset for the zone, and that the
NSEC/NSEC3 chains are complete.
Options
~~~~~~~
``-c class``
.. option:: -c class
This option specifies the DNS class of the zone.
``-E engine``
.. option:: -E engine
This option specifies the cryptographic hardware to use, when applicable.
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
engine identifier that drives the cryptographic accelerator or
hardware service module (usually ``pkcs11``).
``-I input-format``
.. option:: -I input-format
This option sets the format of the input zone file. Possible formats are ``text``
(the default) and ``raw``. This option is primarily intended to be used
for dynamic signed zones, so that the dumped zone file in a non-text
format containing updates can be verified independently.
This option is not useful for non-dynamic zones.
``-o origin``
.. option:: -o origin
This option indicates the zone origin. If not specified, the name of the zone file is
assumed to be the origin.
``-v level``
.. option:: -v level
This option sets the debugging level.
``-V``
.. option:: -V
This option prints version information.
``-q``
This option sets quiet mode, which suppresses output. Without this option, when ``dnssec-verify``
.. option:: -q
This option sets quiet mode, which suppresses output. Without this option, when :program:`dnssec-verify`
is run it prints to standard output the number of keys in use, the
algorithms used to verify the zone was signed correctly, and other status
information. With this option, all non-error output is suppressed, and only the exit
code indicates success.
``-x``
.. option:: -x
This option verifies only that the DNSKEY RRset is signed with key-signing keys.
Without this flag, it is assumed that the DNSKEY RRset is signed
by all active keys. When this flag is set, it is not an error if
the DNSKEY RRset is not signed by zone-signing keys. This corresponds
to the ``-x`` option in ``dnssec-signzone``.
to the :option:`-x option in dnssec-signzone <dnssec-signzone -x>`.
.. option:: -z
``-z``
This option indicates that the KSK flag on the keys should be ignored when determining whether the zone is
correctly signed. Without this flag, it is assumed that there is
a non-revoked, self-signed DNSKEY with the KSK flag set for each
@ -84,12 +95,13 @@ Options
the KSK flag state, and that other RRsets be signed by a
non-revoked key for the same algorithm that includes the self-signed
key; the same key may be used for both purposes. This corresponds to
the ``-z`` option in ``dnssec-signzone``.
the :option:`-z option in dnssec-signzone <dnssec-signzone -z>`.
.. option:: zonefile
``zonefile``
This option indicates the file containing the zone to be signed.
See Also
~~~~~~~~
:manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual, :rfc:`4033`.
:iscman:`dnssec-signzone(8) <dnssec-signzone>`, BIND 9 Administrator Reference Manual, :rfc:`4033`.

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: named.conf
named.conf - configuration file for **named**
---------------------------------------------
@ -22,10 +24,10 @@ Synopsis
Description
~~~~~~~~~~~
``named.conf`` is the configuration file for ``named``. Statements are
enclosed in braces and terminated with a semi-colon. Clauses in the
statements are also semi-colon terminated. The usual comment styles are
supported:
:file:`named.conf` is the configuration file for :iscman:`named`.
Statements are enclosed in braces and terminated with a semi-colon.
Clauses in the statements are also semi-colon terminated. The usual
comment styles are supported:
C style: /\* \*/
@ -902,5 +904,5 @@ Files
See Also
~~~~~~~~
:manpage:`named(8)`, :manpage:`named-checkconf(8)`, :manpage:`rndc(8)`, :manpage:`rndc-confgen(8)`, :manpage:`tsig-keygen(8)`, BIND 9 Administrator Reference Manual.
:iscman:`named(8) <named>`, :iscman:`named-checkconf(8) <named-checkconf>`, :iscman:`rndc(8) <rndc>`, :iscman:`rndc-confgen(8) <rndc-confgen>`, :iscman:`tsig-keygen(8) <tsig-keygen>`, BIND 9 Administrator Reference Manual.

125
bin/named/named.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: named
.. program:: named
.. _man_named:
named - Internet domain name server
@ -24,41 +26,47 @@ Synopsis
Description
~~~~~~~~~~~
``named`` is a Domain Name System (DNS) server, part of the BIND 9
:program:`named` is a Domain Name System (DNS) server, part of the BIND 9
distribution from ISC. For more information on the DNS, see :rfc:`1033`,
:rfc:`1034`, and :rfc:`1035`.
When invoked without arguments, ``named`` reads the default
When invoked without arguments, :program:`named` reads the default
configuration file |named_conf|, reads any initial data, and
listens for queries.
Options
~~~~~~~
``-4``
This option tells ``named`` to use only IPv4, even if the host machine is capable of IPv6. ``-4`` and
``-6`` are mutually exclusive.
.. option:: -4
``-6``
This option tells ``named`` to use only IPv6, even if the host machine is capable of IPv4. ``-4`` and
``-6`` are mutually exclusive.
This option tells :program:`named` to use only IPv4, even if the host machine is capable of IPv6. :option:`-4` and
:option:`-6` are mutually exclusive.
``-c config-file``
This option tells ``named`` to use ``config-file`` as its configuration file instead of the default,
.. option:: -6
This option tells :program:`named` to use only IPv6, even if the host machine is capable of IPv4. :option:`-4` and
:option:`-6` are mutually exclusive.
.. option:: -c config-file
This option tells :program:`named` to use ``config-file`` as its configuration file instead of the default,
|named_conf|. To ensure that the configuration file
can be reloaded after the server has changed its working directory
due to to a possible ``directory`` option in the configuration file,
``config-file`` should be an absolute pathname.
``-d debug-level``
This option sets the daemon's debug level to ``debug-level``. Debugging traces from
``named`` become more verbose as the debug level increases.
.. option:: -d debug-level
``-D string``
This option specifies a string that is used to identify a instance of ``named``
This option sets the daemon's debug level to ``debug-level``. Debugging traces from
:program:`named` become more verbose as the debug level increases.
.. option:: -D string
This option specifies a string that is used to identify a instance of :program:`named`
in a process listing. The contents of ``string`` are not examined.
``-E engine-name``
.. option:: -E engine-name
When applicable, this option specifies the hardware to use for cryptographic
operations, such as a secure key store used for signing.
@ -66,36 +74,43 @@ Options
engine identifier that drives the cryptographic accelerator or
hardware service module (usually ``pkcs11``).
``-f``
.. option:: -f
This option runs the server in the foreground (i.e., do not daemonize).
``-g``
.. option:: -g
This option runs the server in the foreground and forces all logging to ``stderr``.
``-L logfile``
.. option:: -L logfile
This option sets the log to the file ``logfile`` by default, instead of the system log.
``-M option``
.. option:: -M option
This option sets the default memory context options. If set to ``external``,
the internal memory manager is bypassed in favor of
system-provided memory allocation functions. If set to ``fill``, blocks
of memory are filled with tag values when allocated or freed, to
assist debugging of memory problems. ``nofill`` disables this behavior,
and is the default unless ``named`` has been compiled with developer
and is the default unless :program:`named` has been compiled with developer
options.
``-m flag``
.. option:: -m flag
This option turns on memory usage debugging flags. Possible flags are ``usage``,
``trace``, ``record``, ``size``, and ``mctx``. These correspond to the
``ISC_MEM_DEBUGXXXX`` flags described in ``<isc/mem.h>``.
``-n #cpus``
.. option:: -n #cpus
This option creates ``#cpus`` worker threads to take advantage of multiple CPUs. If
not specified, ``named`` tries to determine the number of CPUs
not specified, :program:`named` tries to determine the number of CPUs
present and creates one thread per CPU. If it is unable to determine
the number of CPUs, a single worker thread is created.
``-p value``
.. option:: -p value
This option specifies the port(s) on which the server will listen
for queries. If ``value`` is of the form ``<portnum>`` or
``dns=<portnum>``, the server will listen for DNS queries on
@ -106,8 +121,9 @@ Options
listen for HTTPS queries on ``portnum``; the default is 443.
If ``value`` is of the form ``http=<portnum>``, the server will
listen for HTTP queries on ``portnum``; the default is 80.
``-s``
.. option:: -s
This option writes memory usage statistics to ``stdout`` on exit.
.. note::
@ -115,7 +131,8 @@ Options
This option is mainly of interest to BIND 9 developers and may be
removed or changed in a future release.
``-S #max-socks``
.. option:: -S #max-socks
This option is deprecated and no longer has any function.
.. warning::
@ -127,61 +144,67 @@ Options
exhaustion of file descriptors and the operational environment is
known to support the specified number of sockets. Note also that
the actual maximum number is normally slightly fewer than the
specified value, because ``named`` reserves some file descriptors
specified value, because :program:`named` reserves some file descriptors
for its internal use.
``-t directory``
This option tells ``named`` to chroot to ``directory`` after processing the command-line arguments, but
.. option:: -t directory
This option tells :program:`named` to chroot to ``directory`` after processing the command-line arguments, but
before reading the configuration file.
.. warning::
This option should be used in conjunction with the ``-u`` option,
This option should be used in conjunction with the :option:`-u` option,
as chrooting a process running as root doesn't enhance security on
most systems; the way ``chroot`` is defined allows a process
with root privileges to escape a chroot jail.
``-U #listeners``
This option tells ``named`` the number of ``#listeners`` worker threads to listen on, for incoming UDP packets on
each address. If not specified, ``named`` calculates a default
.. option:: -U #listeners
This option tells :program:`named` the number of ``#listeners`` worker threads to listen on, for incoming UDP packets on
each address. If not specified, :program:`named` calculates a default
value based on the number of detected CPUs: 1 for 1 CPU, and the
number of detected CPUs minus one for machines with more than 1 CPU.
This cannot be increased to a value higher than the number of CPUs.
If ``-n`` has been set to a higher value than the number of detected
CPUs, then ``-U`` may be increased as high as that value, but no
If :option:`-n` has been set to a higher value than the number of detected
CPUs, then :option:`-U` may be increased as high as that value, but no
higher.
``-u user``
.. option:: -u user
This option sets the setuid to ``user`` after completing privileged operations, such as
creating sockets that listen on privileged ports.
.. note::
On Linux, ``named`` uses the kernel's capability mechanism to drop
On Linux, :program:`named` uses the kernel's capability mechanism to drop
all root privileges except the ability to ``bind`` to a
privileged port and set process resource limits. Unfortunately,
this means that the ``-u`` option only works when ``named`` is run
this means that the :option:`-u` option only works when :program:`named` is run
on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or later, since
previous kernels did not allow privileges to be retained after
``setuid``.
``-v``
.. option:: -v
This option reports the version number and exits.
``-V``
.. option:: -V
This option reports the version number and build options, and exits.
``-X lock-file``
.. option:: -X lock-file
This option acquires a lock on the specified file at runtime; this helps to
prevent duplicate ``named`` instances from running simultaneously.
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.
@ -194,14 +217,14 @@ The result of sending any other signals to the server is undefined.
Configuration
~~~~~~~~~~~~~
The ``named`` configuration file is too complex to describe in detail
The :program:`named` configuration file is too complex to describe in detail
here. A complete description is provided in the BIND 9 Administrator
Reference Manual.
``named`` inherits the ``umask`` (file creation mode mask) from the
parent process. If files created by ``named``, such as journal files,
:program:`named` inherits the ``umask`` (file creation mode mask) from the
parent process. If files created by :program:`named`, such as journal files,
need to have custom permissions, the ``umask`` should be set explicitly
in the script used to start the ``named`` process.
in the script used to start the :program:`named` process.
Files
~~~~~
@ -215,4 +238,4 @@ Files
See Also
~~~~~~~~
:rfc:`1033`, :rfc:`1034`, :rfc:`1035`, :manpage:`named-checkconf(8)`, :manpage:`named-checkzone(8)`, :manpage:`rndc(8)`, :manpage:`named.conf(5)`, BIND 9 Administrator Reference Manual.
:rfc:`1033`, :rfc:`1034`, :rfc:`1035`, :iscman:`named-checkconf(8) <named-checkconf>`, :iscman:`named-checkzone(8) <named-checkzone>`, :iscman:`rndc(8) <rndc>`, :iscman:`named.conf(5) <named.conf>`, BIND 9 Administrator Reference Manual.

129
bin/nsupdate/nsupdate.rst
View file

@ -9,8 +9,8 @@
.. See the COPYRIGHT file distributed with this work for additional
.. information regarding copyright ownership.
.. highlight: console
.. iscman:: nsupdate
.. program:: nsupdate
.. _man_nsupdate:
nsupdate - dynamic DNS update utility
@ -24,18 +24,18 @@ Synopsis
Description
~~~~~~~~~~~
``nsupdate`` is used to submit Dynamic DNS Update requests, as defined in
:program:`nsupdate` is used to submit Dynamic DNS Update requests, as defined in
:rfc:`2136`, to a name server. This allows resource records to be added or
removed from a zone without manually editing the zone file. A single
update request can contain requests to add or remove more than one
resource record.
Zones that are under dynamic control via ``nsupdate`` or a DHCP server
Zones that are under dynamic control via :program:`nsupdate` or a DHCP server
should not be edited by hand. Manual edits could conflict with dynamic
updates and cause data to be lost.
The resource records that are dynamically added or removed with
``nsupdate`` must be in the same zone. Requests are sent to the
:program:`nsupdate` must be in the same zone. Requests are sent to the
zone's primary server, which is identified by the MNAME field of the
zone's SOA record.
@ -44,87 +44,110 @@ updates. These use the TSIG resource record type described in :rfc:`2845`,
the SIG(0) record described in :rfc:`2535` and :rfc:`2931`, or GSS-TSIG as
described in :rfc:`3645`.
TSIG relies on a shared secret that should only be known to ``nsupdate``
TSIG relies on a shared secret that should only be known to :program:`nsupdate`
and the name server. For instance, suitable ``key`` and ``server``
statements are added to |named_conf| so that the name server
can associate the appropriate secret key and algorithm with the IP
address of the client application that is using TSIG
authentication. ``ddns-confgen`` can generate suitable
configuration fragments. ``nsupdate`` uses the ``-y`` or ``-k`` options
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.
SIG(0) uses public key cryptography. To use a SIG(0) key, the public key
must be stored in a KEY record in a zone served by the name server.
GSS-TSIG uses Kerberos credentials. Standard GSS-TSIG mode is switched
on with the ``-g`` flag. A non-standards-compliant variant of GSS-TSIG
used by Windows 2000 can be switched on with the ``-o`` flag.
on with the :option:`-g` flag. A non-standards-compliant variant of GSS-TSIG
used by Windows 2000 can be switched on with the :option:`-o` flag.
Options
~~~~~~~
``-4``
.. option:: -4
This option sets use of IPv4 only.
``-6``
.. option:: -6
This option sets use of IPv6 only.
``-C``
.. option:: -C
Overrides the default `resolv.conf` file. This is only intended for testing.
``-d``
.. option:: -d
This option sets debug mode, which provides tracing information about the update
requests that are made and the replies received from the name server.
``-D``
.. option:: -D
This option sets extra debug mode.
``-i``
.. option:: -g
This option enables standard GSS-TSIG mode.
.. option:: -i
This option forces interactive mode, even when standard input is not a terminal.
``-k keyfile``
.. option:: -k keyfile
This option indicates the file containing the TSIG authentication key. Keyfiles may be in
two formats: a single file containing a ``named.conf``-format ``key``
statement, which may be generated automatically by ``ddns-confgen``;
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 ``-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.
``-l``
.. option:: -l
This option sets local-host only mode, which sets the server address to localhost
(disabling the ``server`` so that the server address cannot be
overridden). Connections to the local server use a TSIG key
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 ``-k`` option.
overridden with the :option:`-k` option.
.. option:: -L level
``-L level``
This option sets the logging debug level. If zero, logging is disabled.
``-p port``
.. option:: -o
This option enables a non-standards-compliant variant of GSS-TSIG
used by Windows 2000.
.. option:: -p port
This option sets the port to use for connections to a name server. The default is
53.
``-P``
This option prints the list of private BIND-specific resource record types whose
format is understood by ``nsupdate``. See also the ``-T`` option.
.. option:: -P
This option prints the list of private BIND-specific resource record types whose
format is understood by :program:`nsupdate`. See also the :option:`-T` option.
.. option:: -r udpretries
``-r udpretries``
This option sets the number of UDP retries. The default is 3. If zero, only one update
request is made.
``-t timeout``
.. option:: -t timeout
This option sets the maximum time an update request can take before it is aborted. The
default is 300 seconds. If zero, the timeout is disabled.
``-T``
.. option:: -T
This option prints the list of IANA standard resource record types whose format is
understood by ``nsupdate``. ``nsupdate`` exits after the lists
are printed. The ``-T`` option can be combined with the ``-P``
understood by :program:`nsupdate`. :program:`nsupdate` exits after the lists
are printed. The :option:`-T` option can be combined with the :option:`-P`
option.
Other types can be entered using ``TYPEXXXXX`` where ``XXXXX`` is the
@ -132,21 +155,25 @@ Options
present, is parsed using the UNKNOWN rdata format, (<backslash>
<hash> <space> <length> <space> <hexstring>).
``-u udptimeout``
.. option:: -u udptimeout
This option sets the UDP retry interval. The default is 3 seconds. If zero, the
interval is computed from the timeout interval and number of UDP
retries.
``-v``
This option specifies that TCP should be used even for small update requests. By default, ``nsupdate`` uses
.. option:: -v
This option specifies that TCP should be used even for small update requests. By default, :program:`nsupdate` uses
UDP to send update requests to the name server unless they are too
large to fit in a UDP request, in which case TCP is used. TCP may
be preferable when a batch of update requests is made.
``-V``
.. option:: -V
This option prints the version number and exits.
``-y [hmac:]keyname:secret``
.. option:: -y [hmac:]keyname:secret
This option sets the literal TSIG authentication key. ``keyname`` is the name of the key,
and ``secret`` is the base64 encoded shared secret. ``hmac`` is the
name of the key algorithm; valid choices are ``hmac-md5``,
@ -154,7 +181,7 @@ Options
``hmac-sha512``. If ``hmac`` is not specified, the default is
``hmac-md5``, or if MD5 was disabled, ``hmac-sha256``.
NOTE: Use of the ``-y`` option is discouraged because the shared
NOTE: Use of the :option:`-y` option is discouraged because the shared
secret is supplied as a command-line argument in clear text. This may
be visible in the output from ps1 or in a history file maintained by
the user's shell.
@ -162,7 +189,7 @@ Options
Input Format
~~~~~~~~~~~~
``nsupdate`` reads input from ``filename`` or standard input. Each
:program:`nsupdate` reads input from ``filename`` or standard input. Each
command is supplied on exactly one line of input. Some commands are for
administrative purposes; others are either update instructions or
prerequisite checks on the contents of the zone. These checks set
@ -182,7 +209,7 @@ The command formats and their meanings are as follows:
``server servername port``
This command sends all dynamic update requests to the name server ``servername``.
When no server statement is provided, ``nsupdate`` sends updates
When no server statement is provided, :program:`nsupdate` sends updates
to the primary server of the correct zone. The MNAME field of that
zone's SOA record identify the primary server for that zone.
``port`` is the port number on ``servername`` where the dynamic
@ -191,14 +218,14 @@ The command formats and their meanings are as follows:
``local address port``
This command sends all dynamic update requests using the local ``address``. When
no local statement is provided, ``nsupdate`` sends updates using
no local statement is provided, :program:`nsupdate` sends updates using
an address and port chosen by the system. ``port`` can also
be used to force requests to come from a specific port. If no port number
is specified, the system assigns one.
``zone zonename``
This command specifies that all updates are to be made to the zone ``zonename``.
If no ``zone`` statement is provided, ``nsupdate`` attempts to
If no ``zone`` statement is provided, :program:`nsupdate` attempts to
determine the correct zone to update based on the rest of the input.
``class classname``
@ -214,15 +241,15 @@ The command formats and their meanings are as follows:
``keyname``-``secret`` pair. If ``hmac`` is specified, it sets
the signing algorithm in use. The default is ``hmac-md5``; if MD5
was disabled, the default is ``hmac-sha256``. The ``key`` command overrides any key
specified on the command line via ``-y`` or ``-k``.
specified on the command line via :option:`-y` or :option:`-k`.
``gsstsig``
This command uses GSS-TSIG to sign the updates. This is equivalent to specifying
``-g`` on the command line.
:option:`-g` on the command line.
``oldgsstsig``
This command uses the Windows 2000 version of GSS-TSIG to sign the updates. This is
equivalent to specifying ``-o`` on the command line.
equivalent to specifying :option:`-o` on the command line.
``realm [realm_name]``
When using GSS-TSIG, this command specifies the use of ``realm_name`` rather than the default realm
@ -296,7 +323,7 @@ Lines beginning with a semicolon (;) are comments and are ignored.
Examples
~~~~~~~~
The examples below show how ``nsupdate`` can be used to insert and
The examples below show how :program:`nsupdate` can be used to insert and
delete resource records from the ``example.com`` zone. Notice that the
input in each example contains a trailing blank line, so that a group of
commands is sent as one dynamic update request to the primary name
@ -339,20 +366,20 @@ 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
~~~~~~~~
:rfc:`2136`, :rfc:`3007`, :rfc:`2104`, :rfc:`2845`, :rfc:`1034`, :rfc:`2535`, :rfc:`2931`,
:manpage:`named(8)`, :manpage:`dnssec-keygen(8)`, :manpage:`tsig-keygen(8)`.
:iscman:`named(8) <named>`, :iscman:`dnssec-keygen(8) <dnssec-keygen>`, :iscman:`tsig-keygen(8) <tsig-keygen>`.
Bugs
~~~~
The TSIG key is redundantly stored in two separate files. This is a
consequence of ``nsupdate`` using the DST library for its cryptographic
consequence of :program:`nsupdate` using the DST library for its cryptographic
operations, and may change in future releases.

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

@ -11,6 +11,7 @@
.. highlight: console
.. iscman:: filter-a
.. _man_filter-a:
filter-a.so - filter A in DNS responses when AAAA is present
@ -24,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:

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

@ -11,6 +11,7 @@
.. highlight: console
.. iscman:: filter-aaaa
.. _man_filter-aaaa:
filter-aaaa.so - filter AAAA in DNS responses when A is present
@ -24,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:
::

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: rndc.conf
.. program:: rndc.conf
.. _man_rndc.conf:
rndc.conf - rndc configuration file
@ -24,9 +26,9 @@ Synopsis
Description
~~~~~~~~~~~
``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:
@ -36,13 +38,13 @@ C++ style: // to end of line
Unix style: # to end of line
``rndc.conf`` is much simpler than ``named.conf``. The file uses three
:program:`rndc.conf` is much simpler than :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
@ -67,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
@ -118,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
@ -126,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 ``rndc -s testserver`` 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 ``rndc.conf`` file, including the randomly generated key,
A complete :program:`rndc.conf` file, including the randomly generated key,
is written to the standard output. Commented-out ``key`` and
``controls`` statements for ``named.conf`` are also printed.
``controls`` statements for :iscman:`named.conf` are also printed.
To generate a base-64 secret with ``mmencode``:
@ -145,12 +147,12 @@ Name Server Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~
The name server must be configured to accept rndc connections and to
recognize the key specified in the ``rndc.conf`` file, using the
controls statement in ``named.conf``. See the sections on the
recognize the key specified in the :program:`rndc.conf` file, using the
controls statement in :iscman:`named.conf`. See the sections on the
``controls`` statement in the BIND 9 Administrator Reference Manual for
details.
See Also
~~~~~~~~
:manpage:`rndc(8)`, :manpage:`rndc-confgen(8)`, :manpage:`mmencode(1)`, BIND 9 Administrator Reference Manual.
:iscman:`rndc(8) <rndc>`, :iscman:`rndc-confgen(8) <rndc-confgen>`, :manpage:`mmencode(1)`, BIND 9 Administrator Reference Manual.

281
bin/rndc/rndc.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: rndc
.. program:: rndc
.. _man_rndc:
rndc - name server control utility
@ -24,15 +26,14 @@ Synopsis
Description
~~~~~~~~~~~
``rndc`` controls the operation of a name server; it supersedes the
``ndc`` utility. If ``rndc`` is
:program:`rndc` controls the operation of a name server. If :program:`rndc` is
invoked with no command line options or arguments, it prints a short
summary of the supported commands and the available options and their
arguments.
``rndc`` communicates with the name server over a TCP connection,
:program:`rndc` communicates with the name server over a TCP connection,
sending commands authenticated with digital signatures. In the current
versions of ``rndc`` and ``named``, the only supported authentication
versions of :program:`rndc` and :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
@ -40,60 +41,71 @@ authentication for the command request and the name server's response.
All commands sent over the channel must be signed by a key_id known to
the server.
``rndc`` reads a configuration file to determine how to contact the name
:program:`rndc` reads a configuration file to determine how to contact the name
server and decide what algorithm and key it should use.
Options
~~~~~~~
``-4``
.. option:: -4
This option indicates use of IPv4 only.
``-6``
.. option:: -6
This option indicates use of IPv6 only.
``-b source-address``
.. option:: -b source-address
This option indicates ``source-address`` as the source address for the connection to the
server. Multiple instances are permitted, to allow setting of both the
IPv4 and IPv6 source addresses.
``-c config-file``
.. option:: -c config-file
This option indicates ``config-file`` as the configuration file instead of the default,
|rndc_conf|.
``-k key-file``
.. option:: -k key-file
This option indicates ``key-file`` as the key file instead of the default,
|rndc_key|. The key in |rndc_key| is used to
authenticate commands sent to the server if the config-file does not
exist.
``-s server``
.. option:: -s server
``server`` is the name or address of the server which matches a server
statement in the configuration file for ``rndc``. If no server is
statement in the configuration file for :program:`rndc`. If no server is
supplied on the command line, the host named by the default-server
clause in the options statement of the ``rndc`` configuration file
clause in the options statement of the :program:`rndc` configuration file
is used.
``-p port``
.. option:: -p port
This option instructs BIND 9 to send commands to TCP port ``port`` instead of its default control
channel port, 953.
``-q``
.. option:: -q
This option sets quiet mode, where message text returned by the server is not printed
unless there is an error.
``-r``
This option instructs ``rndc`` to print the result code returned by ``named``
.. option:: -r
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.).
``-V``
.. option:: -V
This option enables verbose logging.
``-y key_id``
.. option:: -y key_id
This option indicates use of the key ``key_id`` from the configuration file. For control message validation to succeed, ``key_id`` must be known
by ``named`` with the same algorithm and secret string. If no ``key_id`` is specified,
``rndc`` first looks for a key clause in the server statement of
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
the configuration file contains shared secrets which are used to send
@ -103,23 +115,24 @@ Options
Commands
~~~~~~~~
A list of commands supported by ``rndc`` can be seen by running ``rndc``
A list of commands supported by :program:`rndc` can be seen by running :program:`rndc`
without arguments.
Currently supported commands are:
``addzone`` *zone* [*class* [*view*]] *configuration*
.. option:: addzone zone [class [view]] configuration
This command adds a zone while the server is running. This command requires the
``allow-new-zones`` option to be set to ``yes``. The configuration
string specified on the command line is the zone configuration text
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.
@ -131,9 +144,10 @@ Currently supported commands are:
(Note the brackets around and semi-colon after the zone configuration
text.)
See also ``rndc delzone`` and ``rndc modzone``.
See also :option:`rndc delzone` and :option:`rndc modzone`.
.. option:: delzone [-clean] zone [class [view]]
``delzone`` [**-clean**] *zone* [*class* [*view*]]
This command deletes a zone while the server is running.
If the ``-clean`` argument is specified, the zone's master file (and
@ -144,14 +158,15 @@ 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 ``rndc addzone`` and ``rndc modzone``.
See also :option:`rndc addzone` and :option:`rndc modzone`.
.. option:: dnssec (-status | -rollover -key id [-alg algorithm] [-when time] | -checkds [-key id [-alg algorithm]] [-when time] published | withdraw)) zone [class [view]]
``dnssec`` ( **-status** | **-rollover** **-key** id [**-alg** *algorithm*] [**-when** *time*] | **-checkds** [**-key** *id* [**-alg** *algorithm*]] [**-when** *time*] ( *published* | *withdrawn* )) *zone* [*class* [*view*]]
This command allows you to interact with the "dnssec-policy" of a given
zone.
@ -161,7 +176,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
@ -170,56 +185,64 @@ Currently supported commands are:
select the correct algorithm). The time that the DS has been published or
withdrawn is set to now, unless otherwise specified with the argument ``-when time``.
``dnstap`` ( **-reopen** | **-roll** [*number*] )
.. option:: dnstap (-reopen | -roll [number])
This command closes and re-opens DNSTAP output files. ``rndc dnstap -reopen`` allows
the output file to be renamed externally, so that ``named`` can
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
output file is moved to ".1", and so on. If ``number`` is specified, then
the number of backup log files is limited to that number.
``dumpdb`` [**-all** | **-cache** | **-zones** | **-adb** | **-bad** | **-expired** | **-fail**] [*view ...*]
.. option:: dumpdb [-all | -cache | -zones | -adb | -bad | -expired | -fail] [view ...]
This command dumps the server's caches (default) and/or zones to the dump file for
the specified views. If no view is specified, all views are dumped.
(See the ``dump-file`` option in the BIND 9 Administrator Reference
Manual.)
``flush``
.. option:: flush
This command flushes the server's cache.
``flushname`` *name* [*view*]
.. option:: flushname name [view]
This command flushes the given name from the view's DNS cache and, if applicable,
from the view's nameserver address database, bad server cache, and
SERVFAIL cache.
``flushtree`` *name* [*view*]
.. option:: flushtree name [view]
This command flushes the given name, and all of its subdomains, from the view's
DNS cache, address database, bad server cache, and SERVFAIL cache.
``freeze`` [*zone* [*class* [*view*]]]
.. option:: freeze [zone [class [view]]]
This command suspends updates to a dynamic zone. If no zone is specified, then all
zones are suspended. This allows manual edits to be made to a zone
normally updated by dynamic update, and causes changes in the
journal file to be synced into the master file. All dynamic update
attempts are refused while the zone is frozen.
See also ``rndc thaw``.
See also :option:`rndc thaw`.
.. option:: halt [-p]
``halt`` [**-p**]
This command stops the server immediately. Recent changes made through dynamic
update or IXFR are not saved to the master files, but are rolled
forward from the journal files when the server is restarted. If
``-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 ``rndc stop``.
See also :option:`rndc stop`.
.. option:: loadkeys [zone [class [view]]]
``loadkeys`` [*zone* [*class* [*view*]]]
This command fetches all DNSSEC keys for the given zone from the key directory. If
they are within their publication period, they are merged into the
zone's DNSKEY RRset. Unlike ``rndc sign``, however, the zone is not
zone's DNSKEY RRset. Unlike :option:`rndc sign`, however, the zone is not
immediately re-signed by the new keys, but is allowed to
incrementally re-sign over time.
@ -228,7 +251,8 @@ Currently supported commands are:
zone to be configured to allow dynamic DNS. (See "Dynamic Update Policies" in
the Administrator Reference Manual for more details.)
``managed-keys`` (*status* | *refresh* | *sync* | *destroy*) [*class* [*view*]]
.. option:: managed-keys (status | refresh | sync | destroy) [class [view]]
This command inspects and controls the "managed-keys" database which handles
:rfc:`5011` DNSSEC trust anchor maintenance. If a view is specified, these
commands are applied to that view; otherwise, they are applied to all
@ -254,11 +278,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 ``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
@ -266,47 +290,51 @@ Currently supported commands are:
keys in the event of a trust anchor rollover, or as a brute-force
repair for key maintenance problems.
``modzone`` *zone* [*class* [*view*]] *configuration*
.. option:: modzone zone [class [view]] configuration
This command modifies the configuration of a zone while the server is running. This
command requires the ``allow-new-zones`` option to be set to ``yes``.
As with ``addzone``, the configuration string specified on the
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 ``rndc addzone``, the
If the zone was originally added via :option:`rndc addzone`, the
configuration changes are recorded permanently and are still
in effect after the server is restarted or reconfigured. However, if
it was originally configured in ``named.conf``, then that original
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 ``rndc addzone`` and ``rndc delzone``.
See also :option:`rndc addzone` and :option:`rndc delzone`.
.. option:: notify zone [class [view]]
``notify`` *zone* [*class* [*view*]]
This command resends NOTIFY messages for the zone.
``notrace``
.. option:: notrace
This command sets the server's debugging level to 0.
See also ``rndc trace``.
See also :option:`rndc trace`.
.. option:: nta [(-class class | -dump | -force | -remove | -lifetime duration)] domain [view]
``nta`` [( **-class** *class* | **-dump** | **-force** | **-remove** | **-lifetime** *duration*)] *domain* [*view*]
This command sets a DNSSEC negative trust anchor (NTA) for ``domain``, with a
lifetime of ``duration``. The default lifetime is configured in
``named.conf`` via the ``nta-lifetime`` option, and defaults to one
: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
@ -324,7 +352,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
@ -343,24 +371,27 @@ Currently supported commands are:
view name that begins with a hyphen, use a double-hyphen (--) on the
command line to indicate the end of options.
``querylog`` [(*on* | *off*)]
.. option:: querylog [(on | off)]
This command enables or disables query logging. For backward compatibility, this
command can also be used without an argument to toggle query logging
on and off.
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
``reconfig``
This command reloads the configuration file and loads new zones, but does not reload
existing zone files even if they have changed. This is faster than a
full ``reload`` when there is a large number of zones, because it
full :option:`rndc reload` when there is a large number of zones, because it
avoids the need to examine the modification times of the zone files.
``recursing``
This command dumps the list of queries ``named`` is currently
.. option:: recursing
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.
@ -379,16 +410,20 @@ Currently supported commands are:
and the next time a fetch is sent to that domain, it is recreated
with the counters set to zero).
``refresh`` *zone* [*class* [*view*]]
.. option:: refresh zone [class [view]]
This command schedules zone maintenance for the given zone.
``reload``
.. option:: reload
This command reloads the configuration file and zones.
``reload`` *zone* [*class* [*view*]]
.. option:: reload zone [class [view]]
This command reloads the given zone.
``retransfer`` *zone* [*class* [*view*]]
.. option:: retransfer zone [class [view]]
This command retransfers the given secondary zone from the primary server.
If the zone is configured to use ``inline-signing``, the signed
@ -396,12 +431,14 @@ Currently supported commands are:
unsigned version is complete, the signed version is regenerated
with new signatures.
``scan``
.. option:: scan
This command scans the list of available network interfaces for changes, without
performing a full ``reconfig`` or waiting for the
performing a full :option:`rndc reconfig` or waiting for the
``interface-interval`` timer.
``secroots`` [**-**] [*view* ...]
.. option:: secroots [-] [view ...]
This command dumps the security roots (i.e., trust anchors configured via
``trust-anchors``, or the ``managed-keys`` or ``trusted-keys`` statements
[both deprecated], or ``dnssec-validation auto``) and negative trust anchors
@ -411,31 +448,34 @@ Currently supported commands are:
yet been updated by a successful key refresh query).
If the first argument is ``-``, then the output is returned via the
``rndc`` response channel and printed to the standard output.
:program:`rndc` response channel and printed to the standard output.
Otherwise, it is written to the secroots dump file, which defaults to
``named.secroots``, but can be overridden via the ``secroots-file``
option in ``named.conf``.
option in :iscman:`named.conf`.
See also ``rndc managed-keys``.
See also :option:`rndc managed-keys`.
.. option:: serve-stale (on | off | reset | status) [class [view]]
``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
``stale-answer-ttl`` and ``max-stale-ttl``.
``showzone`` *zone* [*class* [*view*]]
.. option:: showzone zone [class [view]]
This command prints the configuration of a running zone.
See also ``rndc zonestatus``.
See also :option:`rndc zonestatus`.
.. option:: sign zone [class [view]]
``sign`` *zone* [*class* [*view*]]
This command fetches all DNSSEC keys for the given zone from the key directory (see
the ``key-directory`` option in the BIND 9 Administrator Reference
Manual). If they are within their publication period, they are merged into
@ -448,9 +488,10 @@ Currently supported commands are:
"Dynamic Update Policies" in the BIND 9 Administrator Reference Manual for more
details.)
See also ``rndc loadkeys``.
See also :option:`rndc loadkeys`.
.. option:: signing [(-list | -clear keyid/algorithm | -clear all | -nsec3param (parameters | none) | -serial value) zone [class [view]]
``signing`` [(**-list** | **-clear** *keyid/algorithm* | **-clear** *all* | **-nsec3param** ( *parameters* | none ) | **-serial** *value* ) *zone* [*class* [*view*]]
This command lists, edits, or removes the DNSSEC signing-state records for the
specified zone. The status of ongoing DNSSEC operations, such as
signing or generating NSEC3 chains, is stored in the zone in the form
@ -478,7 +519,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
@ -495,31 +536,36 @@ Currently supported commands are:
is rejected. The primary use of this parameter is to set the serial number on inline
signed zones.
``stats``
.. option:: stats
This command writes server statistics to the statistics file. (See the
``statistics-file`` option in the BIND 9 Administrator Reference
Manual.)
``status``
.. option:: status
This command displays the status of the server. Note that the number of zones includes
the internal ``bind/CH`` zone and the default ``./IN`` hint zone, if
there is no explicit root zone configured.
``stop`` **-p**
.. option:: stop -p
This command stops the server, making sure any recent changes made through dynamic
update or IXFR are first saved to the master files of the updated
zones. If ``-p`` is specified, ``named(8)`'s process ID is returned.
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 ``rndc halt``.
See also :option:`rndc halt`.
.. option:: sync -clean [zone [class [view]]]
``sync`` **-clean** [*zone* [*class* [*view*]]]
This command syncs changes in the journal file for a dynamic zone to the master
file. If the "-clean" option is specified, the journal file is also
removed. If no zone is specified, then all zones are synced.
``tcp-timeouts`` [*initial* *idle* *keepalive* *advertised*]
.. option:: tcp-timeouts [initial idle keepalive advertised]
When called without arguments, this command displays the current values of the
``tcp-initial-timeout``, ``tcp-idle-timeout``,
``tcp-keepalive-timeout``, and ``tcp-advertised-timeout`` options.
@ -528,7 +574,8 @@ Currently supported commands are:
denial-of-service (DoS) attack. See the descriptions of these options in the BIND 9
Administrator Reference Manual for details of their use.
``thaw`` [*zone* [*class* [*view*]]]
.. option:: thaw [zone [class [view]]]
This command enables updates to a frozen dynamic zone. If no zone is specified,
then all frozen zones are enabled. This causes the server to reload
the zone from disk, and re-enables dynamic updates after the load has
@ -538,33 +585,39 @@ Currently supported commands are:
changes in the zone. Otherwise, if the zone has changed, any existing
journal file is removed.
See also ``rndc freeze``.
See also :option:`rndc freeze`.
.. option:: trace
``trace``
This command increments the server's debugging level by one.
``trace`` *level*
.. option:: trace level
This command sets the server's debugging level to an explicit value.
See also ``rndc notrace``.
See also :option:`rndc notrace`.
.. option:: tsig-delete keyname [view]
``tsig-delete`` *keyname* [*view*]
This command deletes a given TKEY-negotiated key from the server. This does not
apply to statically configured TSIG keys.
``tsig-list``
.. option:: tsig-list
This command lists the names of all TSIG keys currently configured for use by
``named`` in each view. The list includes both statically configured keys and
:iscman:`named` in each view. The list includes both statically configured keys and
dynamic TKEY-negotiated keys.
``validation`` (**on** | **off** | **status**) [*view* ...]``
.. option:: validation (on | off | status) [view ...]
This command enables, disables, or checks the current status of DNSSEC validation. By
default, validation is enabled.
The cache is flushed when validation is turned on or off to avoid using data
that might differ between states.
``zonestatus`` *zone* [*class* [*view*]]
.. option:: zonestatus zone [class [view]]
This command displays the current status of the given zone, including the master
file name and any include files from which it was loaded, when it was
most recently loaded, the current serial number, the number of nodes,
@ -572,10 +625,10 @@ Currently supported commands are:
signed, whether it uses automatic DNSSEC key management or inline
signing, and the scheduled refresh or expiry times for the zone.
See also ``rndc showzone``.
See also :option:`rndc showzone`.
``rndc`` commands that specify zone names, such as ``reload``,
``retransfer``, or ``zonestatus``, can be ambiguous when applied to zones
:program:`rndc` commands that specify zone names, such as :option:`reload`
:option:`retransfer`, or :option:`zonestatus`, can be ambiguous when applied to zones
of type ``redirect``. Redirect zones are always called ``.``, and can be
confused with zones of type ``hint`` or with secondary copies of the root
zone. To specify a redirect zone, use the special zone name
@ -593,6 +646,6 @@ Several error messages could be clearer.
See Also
~~~~~~~~
:manpage:`rndc.conf(5)`, :manpage:`rndc-confgen(8)`,
:manpage:`named(8)`, :manpage:`named.conf(5)`, :manpage:`ndc(8)`, BIND 9 Administrator
:iscman:`rndc.conf(5) <rndc.conf>`, :iscman:`rndc-confgen(8) <rndc-confgen>`,
:iscman:`named(8) <named>`, :iscman:`named.conf(5) <named.conf>`, BIND 9 Administrator
Reference Manual.

4
bin/tools/arpaname.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: arpaname
.. program:: arpaname
.. _man_arpaname:
arpaname - translate IP addresses to the corresponding ARPA names
@ -24,7 +26,7 @@ Synopsis
Description
~~~~~~~~~~~
``arpaname`` translates IP addresses (IPv4 and IPv6) to the
:program:`arpaname` translates IP addresses (IPv4 and IPv6) to the
corresponding IN-ADDR.ARPA or IP6.ARPA names.
See Also

20
bin/tools/dnstap-read.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: dnstap-read
.. program:: dnstap-read
.. _man_dnstap-read:
dnstap-read - print dnstap data in human-readable form
@ -24,29 +26,33 @@ Synopsis
Description
~~~~~~~~~~~
``dnstap-read`` reads ``dnstap`` data from a specified file and prints
:program:`dnstap-read` reads ``dnstap`` data from a specified file and prints
it in a human-readable format. By default, ``dnstap`` data is printed in
a short summary format, but if the ``-y`` option is specified, a
a short summary format, but if the :option:`-y` option is specified, a
longer and more detailed YAML format is used.
Options
~~~~~~~
``-m``
.. option:: -m
This option indicates trace memory allocations, and is used for debugging memory leaks.
``-p``
.. option:: -p
This option prints the text form of the DNS
message that was encapsulated in the ``dnstap`` frame, after printing the ``dnstap`` data.
``-x``
.. option:: -x
This option prints a hex dump of the wire form
of the DNS message that was encapsulated in the ``dnstap`` frame, after printing the ``dnstap`` data.
``-y``
.. option:: -y
This option prints ``dnstap`` data in a detailed YAML format.
See Also
~~~~~~~~
:manpage:`named(8)`, :manpage:`rndc(8)`, BIND 9 Administrator Reference Manual.
:iscman:`named(8) <named>`, :iscman:`rndc(8) <rndc>`, BIND 9 Administrator Reference Manual.

192
bin/tools/mdig.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: mdig
.. program:: mdig
.. _man_mdig:
mdig - DNS pipelined lookup utility
@ -28,24 +30,24 @@ Synopsis
Description
~~~~~~~~~~~
``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.
``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,
``mdig`` resolves that name before querying the name server.
:program:`mdig` resolves that name before querying the name server.
``mdig`` provides a number of query options which affect the way in
:program:`mdig` provides a number of query options which affect the way in
which lookups are made and the results displayed. Some of these set or
reset flag bits in the query header, some determine which sections of
the answer get printed, and others determine the timeout and retry
@ -60,80 +62,98 @@ assign values to options like the timeout interval. They have the form
Anywhere Options
~~~~~~~~~~~~~~~~
``-f``
This option makes ``mdig`` operate in batch mode by reading a list
.. option:: -f
This option makes :program:`mdig` operate in batch mode by reading a list
of lookup requests to process from the file ``filename``. The file
contains a number of queries, one per line. Each entry in the file
should be organized in the same way they would be presented as queries
to ``mdig`` using the command-line interface.
to :program:`mdig` using the command-line interface.
``-h``
This option causes ``mdig`` to print detailed help information, with the full list
.. option:: -h
This option causes :program:`mdig` to print detailed help information, with the full list
of options, and exit.
``-v``
This option causes ``mdig`` to print the version number and exit.
.. option:: -v
This option causes :program:`mdig` to print the version number and exit.
Global Options
~~~~~~~~~~~~~~
``-4``
This option forces ``mdig`` to only use IPv4 query transport.
.. option:: -4
``-6``
This option forces ``mdig`` to only use IPv6 query transport.
This option forces :program:`mdig` to only use IPv4 query transport.
.. option:: -6
This option forces :program:`mdig` to only use IPv6 query transport.
.. option:: -b address
``-b address``
This option sets the source IP address of the query to
``address``. This must be a valid address on one of the host's network
interfaces or "0.0.0.0" or "::". An optional port may be specified by
appending "#<port>"
``-m``
.. option:: -m
This option enables memory usage debugging.
``-p port#``
.. option:: -p port#
This option is used when a non-standard port number is to be
queried. ``port#`` is the port number that ``mdig`` sends its
queried. ``port#`` is the port number that :program:`mdig` sends its
queries to, instead of the standard DNS port number 53. This option is
used to test a name server that has been configured to listen for
queries on a non-standard port number.
The global query options are:
``+[no]additional``
.. option:: +[no]additional
This option displays [or does not display] the additional section of a reply. The
default is to display it.
``+[no]all``
.. option:: +[no]all
This option sets or clears all display flags.
``+[no]answer``
.. option:: +[no]answer
This option displays [or does not display] the answer section of a reply. The default
is to display it.
``+[no]authority``
.. option:: +[no]authority
This option displays [or does not display] the authority section of a reply. The
default is to display it.
``+[no]besteffort``
.. option:: +[no]besteffort
This option attempts to display [or does not display] the contents of messages which are malformed. The
default is to not display malformed answers.
``+burst``
.. option:: +burst
This option delays queries until the start of the next second.
``+[no]cl``
.. option:: +[no]cl
This option displays [or does not display] the CLASS when printing the record.
``+[no]comments``
.. option:: +[no]comments
This option toggles the display of comment lines in the output. The default is to
print comments.
``+[no]continue``
.. option:: +[no]continue
This option toggles continuation on errors (e.g. timeouts).
``+[no]crypto``
.. option:: +[no]crypto
This option toggles the display of cryptographic fields in DNSSEC records. The
contents of these fields are unnecessary to debug most DNSSEC
validation failures and removing them makes it easier to see the
@ -141,50 +161,60 @@ The global query options are:
they are replaced by the string "[omitted]"; in the DNSKEY case, the
key ID is displayed as the replacement, e.g., ``[ key id = value ]``.
``+dscp[=value]``
.. option:: +dscp[=value]
This option sets the DSCP code point to be used when sending the query. Valid DSCP
code points are in the range [0...63]. By default no code point is
explicitly set.
``+[no]multiline``
.. option:: +[no]multiline
This option toggles printing of records, like the SOA records, in a verbose multi-line format
with human-readable comments. The default is to print each record on
a single line, to facilitate machine parsing of the ``mdig`` output.
a single line, to facilitate machine parsing of the :program:`mdig` output.
.. option:: +[no]question
``+[no]question``
This option prints [or does not print] the question section of a query when an answer
is returned. The default is to print the question section as a
comment.
``+[no]rrcomments``
.. option:: +[no]rrcomments
This option toggles the display of per-record comments in the output (for example,
human-readable key information about DNSKEY records). The default is
not to print record comments unless multiline mode is active.
``+[no]short``
.. option:: +[no]short
This option provides [or does not provide] a terse answer. The default is to print the answer in a
verbose form.
``+split=W``
.. option:: +split=W
This option splits long hex- or base64-formatted fields in resource records into
chunks of ``W`` characters (where ``W`` is rounded up to the nearest
multiple of 4). ``+nosplit`` or ``+split=0`` causes fields not to be
split. The default is 56 characters, or 44 characters when
multiline mode is active.
``+[no]tcp``
.. option:: +[no]tcp
This option uses [or does not use] TCP when querying name servers. The default behavior
is to use UDP.
``+[no]ttlid``
.. option:: +[no]ttlid
This option displays [or does not display] the TTL when printing the record.
``+[no]ttlunits``
.. option:: +[no]ttlunits
This option displays [or does not display] the TTL in friendly human-readable time
units of "s", "m", "h", "d", and "w", representing seconds, minutes,
hours, days, and weeks. This implies +ttlid.
``+[no]vc``
.. option:: +[no]vc
This option uses [or does not use] TCP when querying name servers. This alternate
syntax to ``+[no]tcp`` is provided for backwards compatibility. The
``vc`` stands for "virtual circuit".
@ -192,21 +222,24 @@ The global query options are:
Local Options
~~~~~~~~~~~~~
``-c class``
.. option:: -c class
This option sets the query class to ``class``. It can be any valid
query class which is supported in BIND 9. The default query class is
"IN".
``-t type``
.. option:: -t type
This option sets the query type to ``type``. It can be any valid
query type which is supported in BIND 9. The default query type is "A",
unless the ``-x`` option is supplied to indicate a reverse lookup with
unless the :option:`-x` option is supplied to indicate a reverse lookup with
the "PTR" query type.
``-x addr``
.. option:: -x addr
Reverse lookups - mapping addresses to names - are simplified by
this option. ``addr`` is an IPv4 address in dotted-decimal
notation, or a colon-delimited IPv6 address. ``mdig`` automatically
notation, or a colon-delimited IPv6 address. :program:`mdig` automatically
performs a lookup for a query name like ``11.12.13.10.in-addr.arpa`` and
sets the query type and class to PTR and IN respectively. By default,
IPv6 addresses are looked up using nibble format under the IP6.ARPA
@ -214,13 +247,16 @@ Local Options
The local query options are:
``+[no]aaflag``
.. option:: +[no]aaflag
This is a synonym for ``+[no]aaonly``.
``+[no]aaonly``
.. option:: +[no]aaonly
This sets the ``aa`` flag in the query.
``+[no]adflag``
.. option:: +[no]adflag
This sets [or does not set] the AD (authentic data) bit in the query. This
requests the server to return whether all of the answer and authority
sections have all been validated as secure, according to the security
@ -229,59 +265,71 @@ The local query options are:
indicates that some part of the answer was insecure or not validated.
This bit is set by default.
``+bufsize=B``
.. option:: +bufsize=B
This sets the UDP message buffer size advertised using EDNS0 to ``B``
bytes. The maximum and minimum sizes of this buffer are 65535 and 0
respectively. Values outside this range are rounded up or down
appropriately. Values other than zero cause a EDNS query to be
sent.
``+[no]cdflag``
.. option:: +[no]cdflag
This sets [or does not set] the CD (checking disabled) bit in the query. This
requests the server to not perform DNSSEC validation of responses.
``+[no]cookie=####``
.. option:: +[no]cookie=####
This sends [or does not send] a COOKIE EDNS option, with an optional value. Replaying a COOKIE
from a previous response allows the server to identify a previous
client. The default is ``+nocookie``.
``+[no]dnssec``
.. option:: +[no]dnssec
This requests that DNSSEC records be sent by setting the DNSSEC OK (DO) bit in
the OPT record in the additional section of the query.
``+[no]edns[=#]``
.. option:: +[no]edns[=#]
This specifies [or does not specify] the EDNS version to query with. Valid values are 0 to 255.
Setting the EDNS version causes an EDNS query to be sent.
``+noedns`` clears the remembered EDNS version. EDNS is set to 0 by
default.
``+[no]ednsflags[=#]``
.. option:: +[no]ednsflags[=#]
This sets the must-be-zero EDNS flag bits (Z bits) to the specified value.
Decimal, hex, and octal encodings are accepted. Setting a named flag
(e.g. DO) is silently ignored. By default, no Z bits are set.
``+[no]ednsopt[=code[:value]]``
.. option:: +[no]ednsopt[=code[:value]]
This specifies [or does not specify] an EDNS option with code point ``code`` and an optional payload
of ``value`` as a hexadecimal string. ``+noednsopt`` clears the EDNS
options to be sent.
``+[no]expire``
.. option:: +[no]expire
This toggles sending of an EDNS Expire option.
``+[no]nsid``
.. option:: +[no]nsid
This toggles inclusion of an EDNS name server ID request when sending a query.
``+[no]recurse``
.. option:: +[no]recurse
This toggles the setting of the RD (recursion desired) bit in the query.
This bit is set by default, which means ``mdig`` normally sends
This bit is set by default, which means :program:`mdig` normally sends
recursive queries.
``+retry=T``
.. option:: +retry=T
This sets the number of times to retry UDP queries to server to ``T``
instead of the default, 2. Unlike ``+tries``, this does not include
the initial query.
``+[no]subnet=addr[/prefix-length]``
.. option:: +[no]subnet=addr[/prefix-length]
This sends [or does not send] an EDNS Client Subnet option with the specified IP
address or network prefix.
@ -290,33 +338,39 @@ The local query options are:
prefix-length of zero, which signals a resolver that the client's
address information must *not* be used when resolving this query.
``+timeout=T``
.. option:: +timeout=T
This sets the timeout for a query to ``T`` seconds. The default timeout is
5 seconds for UDP transport and 10 for TCP. An attempt to set ``T``
to less than 1 results in a query timeout of 1 second being
applied.
``+tries=T``
.. option:: +tries=T
This sets the number of times to try UDP queries to server to ``T``
instead of the default, 3. If ``T`` is less than or equal to zero,
the number of tries is silently rounded up to 1.
``+udptimeout=T``
.. option:: +udptimeout=T
This sets the timeout between UDP query retries to ``T``.
``+[no]unknownformat``
.. option:: +[no]unknownformat
This prints [or does not print] all RDATA in unknown RR-type presentation format (see :rfc:`3597`).
The default is to print RDATA for known types in the type's
presentation format.
``+[no]yaml``
.. option:: +[no]yaml
This toggles printing of the responses in a detailed YAML format.
``+[no]zflag``
.. option:: +[no]zflag
This sets [or does not set] the last unassigned DNS header flag in a DNS query.
This flag is off by default.
See Also
~~~~~~~~
:manpage:`dig(1)`, :rfc:`1035`.
:iscman:`dig(1) <dig>`, :rfc:`1035`.

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: named-journalprint
.. program:: named-journalprint
.. _man_named-journalprint:
named-journalprint - print zone journal in human-readable form
@ -24,26 +26,26 @@ Synopsis
Description
~~~~~~~~~~~
``named-journalprint`` scans the contents of a zone journal file,
:program:`named-journalprint` scans the contents of a zone journal file,
printing it in a human-readable form, or, optionally, converting it
to a different journal file format.
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
appending the extension ``.jnl`` to the name of the corresponding zone
file.
``named-journalprint`` converts the contents of a given journal file
:program:`named-journalprint` converts the contents of a given journal file
into a human-readable text format. Each line begins with ``add`` or ``del``,
to indicate whether the record was added or deleted, and continues with
the resource record in master-file format.
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.
@ -56,9 +58,9 @@ 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
~~~~~~~~
:manpage:`named(8)`, :manpage:`nsupdate(1)`, BIND 9 Administrator Reference Manual.
:iscman:`named(8) <named>`, :iscman:`nsupdate(1) <nsupdate>`, BIND 9 Administrator Reference Manual.

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

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: named-nzd2nzf
.. program:: named-nzd2nzf
.. _man_named-nzd2nzf:
named-nzd2nzf - convert an NZD database to NZF text format
@ -24,16 +26,17 @@ Synopsis
Description
~~~~~~~~~~~
``named-nzd2nzf`` converts an NZD database to NZF format and prints it
:program:`named-nzd2nzf` converts an NZD database to NZF format and prints it
to standard output. This can be used to review the configuration of
zones that were added to ``named`` via ``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.
Arguments
~~~~~~~~~
``filename``
.. option:: filename
This is the name of the ``.nzd`` file whose contents should be printed.
See Also

21
bin/tools/named-rrchecker.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: named-rrchecker
.. program:: named-rrchecker
.. _man_named-rrchecker:
named-rrchecker - syntax checker for individual DNS resource records
@ -24,32 +26,37 @@ Synopsis
Description
~~~~~~~~~~~
``named-rrchecker`` reads a individual DNS resource record from standard
:program:`named-rrchecker` reads a individual DNS resource record from standard
input and checks whether it is syntactically correct.
Options
~~~~~~~
``-h``
.. option:: -h
This option prints out the help menu.
``-o origin``
.. option:: -o origin
This option specifies the origin to be used when interpreting
the record.
``-p``
.. option:: -p
This option prints out the resulting record in canonical form. If there
is no canonical form defined, the record is printed in unknown
record format.
``-u``
.. option:: -u
This option prints out the resulting record in unknown record form.
``-C``, ``-T``, and ``-P``
.. option:: -C, -T, -P
These options print out the known class, standard type,
and private type mnemonics, respectively.
See Also
~~~~~~~~
:rfc:`1034`, :rfc:`1035`, :manpage:`named(8)`.
:rfc:`1034`, :rfc:`1035`, :iscman:`named(8) <named>`.

19
bin/tools/nsec3hash.rst
View file

@ -11,6 +11,8 @@
.. highlight: console
.. iscman:: nsec3hash
.. program:: nsec3hash
.. _man_nsec3hash:
nsec3hash - generate NSEC3 hash
@ -26,7 +28,7 @@ Synopsis
Description
~~~~~~~~~~~
``nsec3hash`` generates an NSEC3 hash based on a set of NSEC3
:program:`nsec3hash` generates an NSEC3 hash based on a set of NSEC3
parameters. This can be used to check the validity of NSEC3 records in a
signed zone.
@ -39,22 +41,27 @@ into a command line to confirm the correctness of an NSEC3 hash.
Arguments
~~~~~~~~~
``salt``
.. option:: salt
This is the salt provided to the hash algorithm.
``algorithm``
.. option:: algorithm
This is a number indicating the hash algorithm. Currently the only supported
hash algorithm for NSEC3 is SHA-1, which is indicated by the number
1; consequently "1" is the only useful value for this argument.
``flags``
.. option:: flags
This is provided for compatibility with NSEC3 record presentation format, but
is ignored since the flags do not affect the hash.
``iterations``
.. option:: iterations
This is the number of additional times the hash should be performed.
``domain``
.. option:: domain
This is the domain name to be hashed.
See Also

74
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
@ -96,19 +96,19 @@ The zone files of dynamic zones cannot normally be edited by hand
because they are not guaranteed to contain the most recent dynamic
changes; those are only in the journal file. The only way to ensure
that the zone file of a dynamic zone is up-to-date is to run
``rndc stop``.
:option:`rndc stop`.
To make changes to a dynamic zone manually, follow these steps:
first, disable dynamic updates to the zone using
``rndc freeze zone``. This updates the zone file with the
:option:`rndc freeze zone <rndc freeze>`. This updates the zone file with the
changes stored in its ``.jnl`` file. Then, edit the zone file. Finally, run
``rndc thaw zone`` to reload the changed zone and re-enable dynamic
:option:`rndc thaw zone <rndc thaw>` to reload the changed zone and re-enable dynamic
updates.
``rndc sync zone`` updates the zone file with changes from the
:option:`rndc sync zone <rndc sync>` updates the zone file with changes from the
journal file without stopping dynamic updates; this may be useful for
viewing the current zone state. To remove the ``.jnl`` file after
updating the zone file, use ``rndc sync -clean``.
updating the zone file, use :option:`rndc sync -clean <rndc sync>`.
.. _incremental_zone_transfers:
@ -385,19 +385,19 @@ 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 ``-k``, ``-l``, and ``-y`` command-line options, or via the ``key`` command when running interactively.
* :ref:`man_dig` supports TSIG via the ``-k`` and ``-y`` command-line options.
* :ref:`man_nsupdate` supports TSIG via the :option:`-k <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.
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,21 +432,21 @@ 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
using the same key.
TSIG keys that are known to a server can be listed using the command
``rndc tsig-list``.
:option:`rndc tsig-list`.
Instructing the Server to Use a Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -545,10 +545,10 @@ exchange. The shared secret can then be used to sign subsequent
transactions between the two servers.
TSIG keys known by the server, including TKEY-negotiated keys, can be
listed using ``rndc tsig-list``.
listed using :option:`rndc tsig-list`.
TKEY-negotiated keys can be deleted from a server using
``rndc tsig-delete``. This can also be done via the TKEY protocol
:option:`rndc tsig-delete`. This can also be done via the TKEY protocol
itself, by sending an authenticated TKEY query specifying the "key
deletion" mode.
@ -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,12 +641,12 @@ 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``
records for the zone, as well as ``DS`` for the child zones if ``-g``
is specified. If ``-g`` is not specified, then DS RRsets for the
records for the zone, as well as ``DS`` for the child zones if :option:`-g <dnssec-signzone -g>`
is specified. If :option:`-g <dnssec-signzone -g>` is not specified, then DS RRsets for the
secure child zones need to be added manually.
By default, all zone keys which have an available private key are used
@ -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``.

22
doc/arm/catz.rst
View file

@ -34,8 +34,8 @@ Principle of Operation
~~~~~~~~~~~~~~~~~~~~~~
Normally, if a zone is to be served by a secondary server, the
``named.conf`` file on the server must list the zone, or the zone must
be added using ``rndc addzone``. In environments with a large number of
: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
configuration on all the secondary servers can be significant.
@ -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
``rndc addzone``.
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
``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
@ -79,13 +79,13 @@ update, notices that the member zone has been removed, stops
serving the zone, and removes it from its list of configured zones.
However, removing the member zone from the primary server must be done
by editing the configuration file or running
``rndc delzone``.
:option:`rndc delzone`.
Configuring Catalog Zones
~~~~~~~~~~~~~~~~~~~~~~~~~
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:
::
@ -137,8 +137,8 @@ specified in any order.
Catalog zones are defined on a per-view basis. Configuring a non-empty
``catalog-zones`` statement in a view automatically turns on
``allow-new-zones`` for that view. This means that ``rndc addzone``
and ``rndc delzone`` also work in any view that supports catalog
``allow-new-zones`` for that view. This means that :option:`rndc addzone`
and :option:`rndc delzone` also work in any view that supports catalog
zones.
Catalog Zone Format
@ -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`.

3
doc/arm/conf.py
View file

@ -81,8 +81,9 @@ class GitLabRefRole(ReferenceRole):
raise ValueError
def setup(_):
def setup(app):
roles.register_local_role('gl', GitLabRefRole(GITLAB_BASE_URL))
app.add_crossref_type('iscman', 'iscman', 'pair: %s; manual page')
#
# Configuration file for the Sphinx documentation builder.

86
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 ``-c`` option. If the configuration file is
not found, ``rndc`` also looks in |rndc_key| (or whatever
can be specified with the :option:`-c <rndc -c>` option. If the configuration file is
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 ``rndc-confgen -a`` as
``rndc.key`` file is generated by running :option:`rndc-confgen -a` as
described in :ref:`controls_statement_definition_and_usage`.
The format of the configuration file is similar to that of
``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.
@ -233,15 +233,15 @@ server.
The ``options`` statement has three clauses: ``default-server``,
``default-key``, and ``default-port``. ``default-server`` takes a
host name or address argument and represents the server that is
contacted if no ``-s`` option is provided on the command line.
contacted if no :option:`-s <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:
@ -275,7 +275,7 @@ server.
This file, if installed as |rndc_conf|, allows the
command:
``$ rndc reload``
:option:`rndc reload`
to connect to 127.0.0.1 port 953 and causes the name server to reload,
if a name server on the local machine is running with the following
@ -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``.
Alternatively, it is possible to run ``rndc-confgen -a`` to set up an
``rndc.key`` file and not modify ``named.conf`` at all.
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 :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`:
::

58
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,13 +99,13 @@ 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
``rndc sign <zonename>``.
:option:`rndc sign zonename <rndc sign>`.
``auto-dnssec maintain`` includes the above functionality, but also
automatically adjusts the zone's DNSKEY records on a schedule according to
@ -115,25 +115,25 @@ 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
``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
``rndc sign`` or ``rndc loadkeys`` command. Those commands can still be
:option:`rndc sign` or :option:`rndc loadkeys` command. Those commands can still be
used when there are unscheduled key changes.
When new keys are added to a zone, the TTL is set to match that of any
existing DNSKEY RRset. If there is no existing DNSKEY RRset, the
TTL is set to the TTL specified when the key was created (using the
``dnssec-keygen -L`` option), if any, or to the SOA TTL.
:option:`dnssec-keygen -L` option), if any, or to the SOA TTL.
To sign the zone using NSEC3 instead of NSEC, submit an
NSEC3PARAM record via dynamic update prior to the scheduled publication
@ -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
@ -240,9 +240,9 @@ Converting From NSEC to NSEC3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Add a ``nsec3param`` option to your ``dnssec-policy`` and
run ``rndc reconfig``.
run :option:`rndc reconfig`.
Or use ``nsupdate`` to add an NSEC3PARAM record.
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.
@ -251,9 +251,9 @@ Converting From NSEC3 to NSEC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To do this, remove the ``nsec3param`` option from the ``dnssec-policy`` and
run ``rndc reconfig``.
run :option:`rndc reconfig`.
Or use ``nsupdate`` to remove all NSEC3PARAM records with a
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.

10
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,9 +45,9 @@ 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, ``dnssec-signzone -S`` includes the
unset or in the future, :option:`dnssec-signzone -S` includes the
DNSKEY record in the zone but does not sign with it:
::
@ -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.

16
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,11 +227,11 @@ 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 -E command line option.
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,

406
doc/arm/reference.rst
View file

File diff suppressed because it is too large Load diff

14
doc/arm/security.rst
View file

@ -152,16 +152,16 @@ matches when *both* conditions are true.
-------------------------
On Unix servers, it is possible to run BIND in a *chrooted* environment
(using the ``chroot()`` function) by specifying the ``-t`` option for
``named``. This can help improve system security by placing BIND in a
(using the ``chroot()`` function) by specifying the :option:`-t <named -t>` option for
: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
the daemon as an unprivileged user (``-u`` user). We suggest running
the daemon as an unprivileged user (:option:`-u <named -u>` user). We suggest running
as an unprivileged user when using the ``chroot`` feature.
Here is an example command line to load BIND in a ``chroot`` sandbox,
``/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.

8
doc/arm/troubleshooting.rst
View file

@ -75,13 +75,13 @@ Inspecting Encrypted DNS Traffic
This feature requires support from the cryptographic library that
BIND 9 is built against. For OpenSSL, version 1.1.1 or newer is
required (use ``named -V`` to check).
required (use :option:`named -V` to check).
By definition, TLS-encrypted traffic (e.g. DNS over TLS, DNS over HTTPS)
is opaque to packet sniffers, which makes debugging problems with
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/

40
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
``rndc loadkeys`` command. Otherwise, for primary zones, you can use
``nsupdate`` to add the new DNSKEYs to the zone; this causes ``named``
:option:`rndc loadkeys` command. Otherwise, for primary zones, you can use
: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 ``dnssec-settime -D <date/offset>`` option.)
(See the :option:`dnssec-settime -D date/offset <dnssec-settime -D>` option.)
After adjusting the timing metadata, the ``rndc loadkeys`` command
causes ``named`` to remove the DNSKEYs and
After adjusting the timing metadata, the :option:`rndc loadkeys` command
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
@ -935,9 +935,9 @@ environment.
When you have both DNSSEC and dynamic updates in your environment,
updating zone data works the same way as with traditional (insecure)
DNS: you can use ``rndc freeze`` before editing the zone file, and
``rndc thaw`` when you have finished editing, or you can use the
command ``nsupdate`` to add, edit, or remove records like this:
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 :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.

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

@ -26,8 +26,8 @@ BIND Version
Most configuration examples given in this document require BIND version
9.16.0 or newer (although many do work with all versions of BIND
later than 9.9). To check the version of ``named`` you have installed,
use the ``-v`` switch as shown below:
later than 9.9). To check the version of :iscman:`named` you have installed,
use the :option:`-v <named -v>` switch as shown below:
::
@ -47,10 +47,10 @@ DNSSEC Support in BIND
All versions of BIND 9 since BIND 9.7 can support DNSSEC, as currently
deployed in the global DNS, so the BIND software you are running most
likely already supports DNSSEC. Run the command ``named -V``
likely already supports DNSSEC. Run the command :option:`named -V`
to see what flags it was built with. If it was built with OpenSSL
(``--with-openssl``), then it supports DNSSEC. Below is an example
of the output from running ``named -V``:
of the output from running :option:`named -V`:
::

52
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 (``-I``) date of January 1,
2021, and a deletion (``-D``) date of February 1, 2021, for the current ZSK
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 (``-I``) date of January 1,
2021, and a deletion (``-D``) date of February 1, 2021 for the current KSK
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:
::
@ -1095,14 +1095,14 @@ Change your ``dnssec-policy`` line to indicate you want to revert to unsigned:
dnssec-policy "insecure";
};
Then use ``rndc reload`` to reload the zone.
Then use :option:`rndc reload` to reload the zone.
The "insecure" policy is a built-in policy (like "default"). It will make sure
the zone is still DNSSEC maintained, to allow for a graceful transition to
unsigned.
When the DS records have been removed from the parent zone, use
``rndc dnssec -checkds -key <id> withdrawn example.com`` 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.

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

@ -77,8 +77,8 @@ 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
reload the configuration file by running ``rndc reconfig``:
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:
::
@ -1599,8 +1599,8 @@ of the zone, which looks something like this:
file "db/example.com.signed.db";
};
Once the ``rndc reconfig`` command is issued, BIND serves a signed
zone. The file ``dsset-example.com`` (created by ``dnssec-signzone``
Once the :option:`rndc reconfig` command is issued, BIND serves a signed
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 ``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:
::

3
doc/man/conf.py
View file

@ -116,3 +116,6 @@ rst_epilog = """
.. |named_pid| replace: ``@runstatedir@/named.pid``
.. |session_key| replace: ``@runstatedir@/session.key``
"""
def setup(app):
app.add_crossref_type('iscman', 'iscman', 'pair: %s; manual page')

30
doc/man/ddns-confgen.8in
View file

@ -39,7 +39,7 @@ ddns-confgen \- ddns key generation tool
The resulting keys can be used, for example, to secure dynamic DNS updates
to a zone, or for the \fBrndc\fP command channel.
.sp
The key name can specified using \fB\-k\fP parameter and defaults to \fBddns\-key\fP\&.
The key name can specified using \fI\%\-k\fP parameter and defaults to \fBddns\-key\fP\&.
The generated key is accompanied by configuration text and instructions that
can be used with \fBnsupdate\fP and \fBnamed\fP when setting up dynamic DNS,
including an example \fBupdate\-policy\fP statement.
@ -54,42 +54,52 @@ be used from a remote system.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-a algorithm\fP
.B \-a algorithm
This option specifies the algorithm to use for the TSIG key. Available
choices are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384,
and hmac\-sha512. The default is hmac\-sha256. Options are
case\-insensitive, and the "hmac\-" prefix may be omitted.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints a short summary of options and arguments.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k keyname\fP
.B \-k keyname
This option specifies the key name of the DDNS authentication key. The
default is \fBddns\-key\fP when neither the \fB\-s\fP nor \fB\-z\fP option is
default is \fBddns\-key\fP when neither the \fI\%\-s\fP nor \fI\%\-z\fP option is
specified; otherwise, the default is \fBddns\-key\fP as a separate label
followed by the argument of the option, e.g., \fBddns\-key.example.com.\fP
The key name must have the format of a valid domain name, consisting of
letters, digits, hyphens, and periods.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-q\fP
.B \-q
This option enables quiet mode, which prints only the key, with no
explanatory text or usage examples. This is essentially identical to
\fBtsig\-keygen\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s name\fP
.B \-s name
This option generates a configuration example to allow dynamic updates
of a single hostname. The example \fBnamed.conf\fP text shows how to set
an update policy for the specified name using the "name" nametype. The
default key name is \fBddns\-key.name\fP\&. Note that the "self" nametype
cannot be used, since the name to be updated may differ from the key
name. This option cannot be used with the \fB\-z\fP option.
name. This option cannot be used with the \fI\%\-z\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-z zone\fP
.B \-z zone
This option generates a configuration example to allow
dynamic updates of a zone. The example \fBnamed.conf\fP text shows how
to set an update policy for the specified zone using the "zonesub"
nametype, allowing updates to all subdomain names within that zone.
This option cannot be used with the \fB\-s\fP option.
This option cannot be used with the \fI\%\-s\fP option.
.UNINDENT
.SH SEE ALSO
.sp

158
doc/man/delv.1in
View file

@ -84,7 +84,7 @@ delv @server name type
where:
.INDENT 0.0
.TP
.B \fBserver\fP
.B server
is the name or IP address of the name server to query. This can be an
IPv4 address in dotted\-decimal notation or an IPv6 address in
colon\-delimited notation. When the supplied \fBserver\fP argument is a
@ -94,16 +94,20 @@ DNSSEC).
.sp
If no \fBserver\fP argument is provided, \fBdelv\fP consults
\fB/etc/resolv.conf\fP; if an address is found there, it queries the
name server at that address. If either of the \fB\-4\fP or \fB\-6\fP
name server at that address. If either of the \fI\%\-4\fP or \fI\%\-6\fP
options is in use, then only addresses for the corresponding
transport are tried. If no usable addresses are found, \fBdelv\fP
sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1
for IPv6).
.UNINDENT
.INDENT 0.0
.TP
.B \fBname\fP
.B name
is the domain name to be looked up.
.UNINDENT
.INDENT 0.0
.TP
.B \fBtype\fP
.B type
indicates what type of query is required \- ANY, A, MX, etc.
\fBtype\fP can be any valid query type. If no \fBtype\fP argument is
supplied, \fBdelv\fP performs a lookup for an A record.
@ -111,7 +115,7 @@ supplied, \fBdelv\fP performs a lookup for an A record.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-a anchor\-file\fP
.B \-a anchor\-file
This option specifies a file from which to read DNSSEC trust anchors. The default
is \fB@sysconfdir@/bind.keys\fP, which is included with BIND 9 and contains one
or more trust anchors for the root zone (".").
@ -126,77 +130,103 @@ supported. \fBdelv\fP does not consult the managed\-keys database maintained by
\fBnamed\fP, which means that if either of the keys in \fB@sysconfdir@/bind.keys\fP is
revoked and rolled over, \fB@sysconfdir@/bind.keys\fP must be updated to
use DNSSEC validation in \fBdelv\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-b address\fP
.B \-b address
This option sets the source IP address of the query to \fBaddress\fP\&. This must be
a valid address on one of the host\(aqs network interfaces, or \fB0.0.0.0\fP,
or \fB::\fP\&. An optional source port may be specified by appending
\fB#<port>\fP
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option sets the query class for the requested data. Currently, only class
"IN" is supported in \fBdelv\fP and any other value is ignored.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-d level\fP
.B \-d level
This option sets the systemwide debug level to \fBlevel\fP\&. The allowed range is
from 0 to 99. The default is 0 (no debugging). Debugging traces from
\fBdelv\fP become more verbose as the debug level increases. See the
\fB+mtrace\fP, \fB+rtrace\fP, and \fB+vtrace\fP options below for
additional debugging details.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option displays the \fBdelv\fP help usage output and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-i\fP
.B \-i
This option sets insecure mode, which disables internal DNSSEC validation. (Note,
however, that this does not set the CD bit on upstream queries. If the
server being queried is performing DNSSEC validation, then it does
not return invalid data; this can cause \fBdelv\fP to time out. When it
is necessary to examine invalid data to debug a DNSSEC problem, use
\fBdig +cd\fP\&.)
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-m\fP
.B \-m
This option enables memory usage debugging.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p port#\fP
.B \-p port#
This option specifies a destination port to use for queries, instead of the
standard DNS port number 53. This option is used with a name
server that has been configured to listen for queries on a
non\-standard port number.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-q name\fP
.B \-q name
This option sets the query name to \fBname\fP\&. While the query name can be
specified without using the \fB\-q\fP option, it is sometimes necessary to
specified without using the \fI\%\-q\fP option, it is sometimes necessary to
disambiguate names from types or classes (for example, when looking
up the name "ns", which could be misinterpreted as the type NS, or
"ch", which could be misinterpreted as class CH).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t type\fP
.B \-t type
This option sets the query type to \fBtype\fP, which can be any valid query type
supported in BIND 9 except for zone transfer types AXFR and IXFR. As
with \fB\-q\fP, this is useful to distinguish query\-name types or classes
with \fI\%\-q\fP, this is useful to distinguish query\-name types or classes
when they are ambiguous. It is sometimes necessary to disambiguate
names from types.
.sp
The default query type is "A", unless the \fB\-x\fP option is supplied
The default query type is "A", unless the \fI\%\-x\fP option is supplied
to indicate a reverse lookup, in which case it is "PTR".
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v\fP
.B \-v
This option prints the \fBdelv\fP version and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-x addr\fP
.B \-x addr
This option performs a reverse lookup, mapping an address to a name. \fBaddr\fP
is an IPv4 address in dotted\-decimal notation, or a colon\-delimited
IPv6 address. When \fB\-x\fP is used, there is no need to provide the
IPv6 address. When \fI\%\-x\fP is used, there is no need to provide the
\fBname\fP or \fBtype\fP arguments; \fBdelv\fP automatically performs a
lookup for a name like \fB11.12.13.10.in\-addr.arpa\fP and sets the
query type to PTR. IPv6 addresses are looked up using nibble format
under the IP6.ARPA domain.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-4\fP
.B \-4
This option forces \fBdelv\fP to only use IPv4.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-6\fP
.B \-6
This option forces \fBdelv\fP to only use IPv6.
.UNINDENT
.SH QUERY OPTIONS
@ -211,7 +241,7 @@ assign values to options like the timeout interval. They have the form
\fB+keyword=value\fP\&. The query options are:
.INDENT 0.0
.TP
.B \fB+[no]cdflag\fP
.B +[no]cdflag
This option controls whether to set the CD (checking disabled) bit in queries
sent by \fBdelv\fP\&. This may be useful when troubleshooting DNSSEC
problems from behind a validating resolver. A validating resolver
@ -219,16 +249,22 @@ blocks invalid responses, making it difficult to retrieve them
for analysis. Setting the CD flag on queries causes the resolver
to return invalid responses, which \fBdelv\fP can then validate
internally and report the errors in detail.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]class\fP
.B +[no]class
This option controls whether to display the CLASS when printing a record. The
default is to display the CLASS.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ttl\fP
.B +[no]ttl
This option controls whether to display the TTL when printing a record. The
default is to display the TTL.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]rtrace\fP
.B +[no]rtrace
This option toggles resolver fetch logging. This reports the name and type of each
query sent by \fBdelv\fP in the process of carrying out the resolution
and validation process, including the original query
@ -237,96 +273,126 @@ of trust for DNSSEC validation.
.sp
This is equivalent to setting the debug level to 1 in the "resolver"
logging category. Setting the systemwide debug level to 1 using the
\fB\-d\fP option produces the same output, but affects other
\fI\%\-d\fP option produces the same output, but affects other
logging categories as well.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]mtrace\fP
.B +[no]mtrace
This option toggles message logging. This produces a detailed dump of the
responses received by \fBdelv\fP in the process of carrying out the
resolution and validation process.
.sp
This is equivalent to setting the debug level to 10 for the "packets"
module of the "resolver" logging category. Setting the systemwide
debug level to 10 using the \fB\-d\fP option produces the same
debug level to 10 using the \fI\%\-d\fP option produces the same
output, but affects other logging categories as well.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]vtrace\fP
.B +[no]vtrace
This option toggles validation logging. This shows the internal process of the
validator as it determines whether an answer is validly signed,
unsigned, or invalid.
.sp
This is equivalent to setting the debug level to 3 for the
"validator" module of the "dnssec" logging category. Setting the
systemwide debug level to 3 using the \fB\-d\fP option produces the
systemwide debug level to 3 using the \fI\%\-d\fP option produces the
same output, but affects other logging categories as well.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]short\fP
.B +[no]short
This option toggles between verbose and terse answers. The default is to print the answer in a
verbose form.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]comments\fP
.B +[no]comments
This option toggles the display of comment lines in the output. The default is to
print comments.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]rrcomments\fP
.B +[no]rrcomments
This option toggles the display of per\-record comments in the output (for example,
human\-readable key information about DNSKEY records). The default is
to print per\-record comments.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]crypto\fP
.B +[no]crypto
This option toggles the display of cryptographic fields in DNSSEC records. The
contents of these fields are unnecessary to debug most DNSSEC
validation failures and removing them makes it easier to see the
common failures. The default is to display the fields. When omitted,
they are replaced by the string \fB[omitted]\fP or, in the DNSKEY case, the
key ID is displayed as the replacement, e.g. \fB[ key id = value ]\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]trust\fP
.B +[no]trust
This option controls whether to display the trust level when printing a record.
The default is to display the trust level.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]split[=W]\fP
.B +[no]split[=W]
This option splits long hex\- or base64\-formatted fields in resource records into
chunks of \fBW\fP characters (where \fBW\fP is rounded up to the nearest
multiple of 4). \fB+nosplit\fP or \fB+split=0\fP causes fields not to be
split at all. The default is 56 characters, or 44 characters when
multiline mode is active.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]all\fP
.B +[no]all
This option sets or clears the display options \fB+[no]comments\fP,
\fB+[no]rrcomments\fP, and \fB+[no]trust\fP as a group.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]multiline\fP
.B +[no]multiline
This option prints long records (such as RRSIG, DNSKEY, and SOA records) in a
verbose multi\-line format with human\-readable comments. The default
is to print each record on a single line, to facilitate machine
parsing of the \fBdelv\fP output.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]dnssec\fP
.B +[no]dnssec
This option indicates whether to display RRSIG records in the \fBdelv\fP output.
The default is to do so. Note that (unlike in \fBdig\fP) this does
\fInot\fP control whether to request DNSSEC records or to
validate them. DNSSEC records are always requested, and validation
always occurs unless suppressed by the use of \fB\-i\fP or
always occurs unless suppressed by the use of \fI\%\-i\fP or
\fB+noroot\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]root[=ROOT]\fP
.B +[no]root[=ROOT]
This option indicates whether to perform conventional DNSSEC validation, and if so,
specifies the name of a trust anchor. The default is to validate using a
trust anchor of "." (the root zone), for which there is a built\-in key. If
specifying a different trust anchor, then \fB\-a\fP must be used to specify a
specifying a different trust anchor, then \fI\%\-a\fP must be used to specify a
file containing the key.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]tcp\fP
.B +[no]tcp
This option controls whether to use TCP when sending queries. The default is to
use UDP unless a truncated response has been received.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]unknownformat\fP
.B +[no]unknownformat
This option prints all RDATA in unknown RR\-type presentation format (\fI\%RFC 3597\fP).
The default is to print RDATA for known types in the type\(aqs
presentation format.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]yaml\fP
.B +[no]yaml
This option prints response data in YAML format.
.UNINDENT
.SH FILES

399
doc/man/dig.1in
View file

@ -49,7 +49,7 @@ than \fBdig\fP\&.
Although \fBdig\fP is normally used with command\-line arguments, it also
has a batch mode of operation for reading lookup requests from a file. A
brief summary of its command\-line arguments and options is printed when
the \fB\-h\fP option is given. The BIND 9
the \fI\%\-h\fP option is given. The BIND 9
implementation of \fBdig\fP allows multiple lookups to be issued from the
command line.
.sp
@ -62,12 +62,12 @@ performs an NS query for "." (the root).
.sp
It is possible to set per\-user defaults for \fBdig\fP via
\fB${HOME}/.digrc\fP\&. This file is read and any options in it are applied
before the command\-line arguments. The \fB\-r\fP option disables this
before the command\-line arguments. The \fI\%\-r\fP option disables this
feature, for scripts that need predictable behavior.
.sp
The IN and CH class names overlap with the IN and CH top\-level domain
names. Either use the \fB\-t\fP and \fB\-c\fP options to specify the type and
class, use the \fB\-q\fP to specify the domain name, or use "IN." and
names. Either use the \fI\%\-t\fP and \fI\%\-c\fP options to specify the type and
class, use the \fI\%\-q\fP to specify the domain name, or use "IN." and
"CH." when looking up these top\-level domains.
.SH SIMPLE USAGE
.sp
@ -86,7 +86,7 @@ dig @server name type
where:
.INDENT 0.0
.TP
.B \fBserver\fP
.B server
is the name or IP address of the name server to query. This can be an
IPv4 address in dotted\-decimal notation or an IPv6 address in
colon\-delimited notation. When the supplied \fBserver\fP argument is a
@ -95,16 +95,20 @@ server.
.sp
If no \fBserver\fP argument is provided, \fBdig\fP consults
\fB/etc/resolv.conf\fP; if an address is found there, it queries the
name server at that address. If either of the \fB\-4\fP or \fB\-6\fP
name server at that address. If either of the \fI\%\-4\fP or \fI\%\-6\fP
options are in use, then only addresses for the corresponding
transport are tried. If no usable addresses are found, \fBdig\fP
sends the query to the local host. The reply from the name server
that responds is displayed.
.UNINDENT
.INDENT 0.0
.TP
.B \fBname\fP
.B name
is the name of the resource record that is to be looked up.
.UNINDENT
.INDENT 0.0
.TP
.B \fBtype\fP
.B type
indicates what type of query is required \- ANY, A, MX, SIG, etc.
\fBtype\fP can be any valid query type. If no \fBtype\fP argument is
supplied, \fBdig\fP performs a lookup for an A record.
@ -112,57 +116,82 @@ supplied, \fBdig\fP performs a lookup for an A record.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-4\fP
.B \-4
This option indicates that only IPv4 should be used.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-6\fP
.B \-6
This option indicates that only IPv6 should be used.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-b address[#port]\fP
.B \-b address[#port]
This option sets the source IP address of the query. The \fBaddress\fP must be a
valid address on one of the host\(aqs network interfaces, or "0.0.0.0"
or "::". An optional port may be specified by appending \fB#port\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option sets the query class. The default \fBclass\fP is IN; other classes are
HS for Hesiod records or CH for Chaosnet records.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f file\fP
.B \-f file
This option sets batch mode, in which \fBdig\fP reads a list of lookup requests to process from
the given \fBfile\fP\&. Each line in the file should be organized in the
same way it would be presented as a query to \fBdig\fP using the
command\-line interface.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k keyfile\fP
.B \-h
Print a usage summary.
.UNINDENT
.INDENT 0.0
.TP
.B \-k keyfile
This option tells \fBnamed\fP to sign queries using TSIG using a key read from the given file. Key
files can be generated using \fBtsig\-keygen\fP\&. When using TSIG
authentication with \fBdig\fP, the name server that is queried needs to
know the key and algorithm that is being used. In BIND, this is done
by providing appropriate \fBkey\fP and \fBserver\fP statements in
\fBnamed.conf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-m\fP
.B \-m
This option enables memory usage debugging.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p port\fP
.B \-p port
This option sends the query to a non\-standard port on the server, instead of the
default port 53. This option is used to test a name server that
has been configured to listen for queries on a non\-standard port
number.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-q name\fP
.B \-q name
This option specifies the domain name to query. This is useful to distinguish the \fBname\fP
from other arguments.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-r\fP
.B \-r
This option indicates that options from \fB${HOME}/.digrc\fP should not be read. This is useful for
scripts that need predictable behavior.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t type\fP
.B \-t type
This option indicates the resource record type to query, which can be any valid query type. If
it is a resource record type supported in BIND 9, it can be given by
the type mnemonic (such as \fBNS\fP or \fBAAAA\fP). The default query type is
\fBA\fP, unless the \fB\-x\fP option is supplied to indicate a reverse
\fBA\fP, unless the \fI\%\-x\fP option is supplied to indicate a reverse
lookup. A zone transfer can be requested by specifying a type of
AXFR. When an incremental zone transfer (IXFR) is required, set the
\fBtype\fP to \fBixfr=N\fP\&. The incremental zone transfer contains
@ -172,24 +201,32 @@ SOA record was \fBN\fP\&.
All resource record types can be expressed as \fBTYPEnn\fP, where \fBnn\fP is
the number of the type. If the resource record type is not supported
in BIND 9, the result is displayed as described in \fI\%RFC 3597\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-u\fP
.B \-u
This option indicates that print query times should be provided in microseconds instead of milliseconds.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v\fP
.B \-v
This option prints the version number and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-x addr\fP
.B \-x addr
This option sets simplified reverse lookups, for mapping addresses to names. The
\fBaddr\fP is an IPv4 address in dotted\-decimal notation, or a
colon\-delimited IPv6 address. When the \fB\-x\fP option is used, there is no
colon\-delimited IPv6 address. When the \fI\%\-x\fP option is used, there is no
need to provide the \fBname\fP, \fBclass\fP, and \fBtype\fP arguments.
\fBdig\fP automatically performs a lookup for a name like
\fB94.2.0.192.in\-addr.arpa\fP and sets the query type and class to PTR
and IN respectively. IPv6 addresses are looked up using nibble format
under the IP6.ARPA domain.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-y [hmac:]keyname:secret\fP
.B \-y [hmac:]keyname:secret
This option signs queries using TSIG with the given authentication key.
\fBkeyname\fP is the name of the key, and \fBsecret\fP is the
base64\-encoded shared secret. \fBhmac\fP is the name of the key algorithm;
@ -202,8 +239,8 @@ not specified, the default is \fBhmac\-md5\fP; if MD5 was disabled, the default
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Only the \fB\-k\fP option should be used, rather than the \fB\-y\fP option,
because with \fB\-y\fP the shared secret is supplied as a command\-line
Only the \fI\%\-k\fP option should be used, rather than the \fI\%\-y\fP option,
because with \fI\%\-y\fP the shared secret is supplied as a command\-line
argument in clear text. This may be visible in the output from \fBps1\fP or
in a history file maintained by the user\(aqs shell.
.UNINDENT
@ -225,17 +262,23 @@ abbreviation is unambiguous; for example, \fB+cd\fP is equivalent to
\fB+cdflag\fP\&. The query options are:
.INDENT 0.0
.TP
.B \fB+[no]aaflag\fP
.B +[no]aaflag
This option is a synonym for \fB+[no]aaonly\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]aaonly\fP
.B +[no]aaonly
This option sets the \fBaa\fP flag in the query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]additional\fP
.B +[no]additional
This option displays [or does not display] the additional section of a reply. The
default is to display it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]adflag\fP
.B +[no]adflag
This option sets [or does not set] the AD (authentic data) bit in the query. This
requests the server to return whether all of the answer and authority
sections have been validated as secure, according to the security
@ -243,45 +286,65 @@ policy of the server. \fBAD=1\fP indicates that all records have been
validated as secure and the answer is not from a OPT\-OUT range. \fBAD=0\fP
indicates that some part of the answer was insecure or not validated.
This bit is set by default.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]all\fP
.B +[no]all
This option sets or clears all display flags.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]answer\fP
.B +[no]answer
This option displays [or does not display] the answer section of a reply. The default
is to display it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]authority\fP
.B +[no]authority
This option displays [or does not display] the authority section of a reply. The
default is to display it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]badcookie\fP
.B +[no]badcookie
This option retries the lookup with a new server cookie if a BADCOOKIE response is
received.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]besteffort\fP
.B +[no]besteffort
This option attempts to display the contents of messages which are malformed. The
default is to not display malformed answers.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+bufsize[=B]\fP
.B +bufsize[=B]
This option sets the UDP message buffer size advertised using EDNS0 to
\fBB\fP bytes. The maximum and minimum sizes of this buffer are 65535 and
0, respectively. \fB+bufsize\fP restores the default buffer size.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]cdflag\fP
.B +[no]cdflag
This option sets [or does not set] the CD (checking disabled) bit in the query. This
requests the server to not perform DNSSEC validation of responses.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]class\fP
.B +[no]class
This option displays [or does not display] the CLASS when printing the record.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]cmd\fP
.B +[no]cmd
This option toggles the printing of the initial comment in the output, identifying the
version of \fBdig\fP and the query options that have been applied. This option
always has a global effect; it cannot be set globally and then overridden on a
per\-lookup basis. The default is to print this comment.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]comments\fP
.B +[no]comments
This option toggles the display of some comment lines in the output, with
information about the packet header and OPT pseudosection, and the names of
the response section. The default is to print these comments.
@ -289,79 +352,109 @@ the response section. The default is to print these comments.
Other types of comments in the output are not affected by this option, but
can be controlled using other command\-line switches. These include
\fB+[no]cmd\fP, \fB+[no]question\fP, \fB+[no]stats\fP, and \fB+[no]rrcomments\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]cookie=####\fP
.B +[no]cookie=####
This option sends [or does not send] a COOKIE EDNS option, with an optional value. Replaying a COOKIE
from a previous response allows the server to identify a previous
client. The default is \fB+cookie\fP\&.
.sp
\fB+cookie\fP is also set when \fB+trace\fP is set to better emulate the
default queries from a nameserver.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]crypto\fP
.B +[no]crypto
This option toggles the display of cryptographic fields in DNSSEC records. The
contents of these fields are unnecessary for debugging most DNSSEC
validation failures and removing them makes it easier to see the
common failures. The default is to display the fields. When omitted,
they are replaced by the string \fB[omitted]\fP or, in the DNSKEY case, the
key ID is displayed as the replacement, e.g. \fB[ key id = value ]\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]defname\fP
.B +[no]defname
This option, which is deprecated, is treated as a synonym for \fB+[no]search\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]dns64prefix\fP
.B +[no]dns64prefix
Lookup IPV4ONLY.ARPA AAAA and print any DNS64 prefixes found.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]dnssec\fP
.B +[no]dnssec
This option requests that DNSSEC records be sent by setting the DNSSEC OK (DO) bit in
the OPT record in the additional section of the query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+domain=somename\fP
.B +domain=somename
This option sets the search list to contain the single domain \fBsomename\fP, as if
specified in a \fBdomain\fP directive in \fB/etc/resolv.conf\fP, and
enables search list processing as if the \fB+search\fP option were
given.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+dscp=value\fP
.B +dscp=value
This option sets the DSCP code point to be used when sending the query. Valid DSCP
code points are in the range [0...63]. By default no code point is
explicitly set.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]edns[=#]\fP
.B +[no]edns[=#]
This option specifies the EDNS version to query with. Valid values are 0 to 255.
Setting the EDNS version causes an EDNS query to be sent.
\fB+noedns\fP clears the remembered EDNS version. EDNS is set to 0 by
default.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ednsflags[=#]\fP
.B +[no]ednsflags[=#]
This option sets the must\-be\-zero EDNS flags bits (Z bits) to the specified value.
Decimal, hex, and octal encodings are accepted. Setting a named flag
(e.g., DO) is silently ignored. By default, no Z bits are set.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ednsnegotiation\fP
.B +[no]ednsnegotiation
This option enables/disables EDNS version negotiation. By default, EDNS version
negotiation is enabled.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ednsopt[=code[:value]]\fP
.B +[no]ednsopt[=code[:value]]
This option specifies the EDNS option with code point \fBcode\fP and an optional payload
of \fBvalue\fP as a hexadecimal string. \fBcode\fP can be either an EDNS
option name (for example, \fBNSID\fP or \fBECS\fP) or an arbitrary
numeric value. \fB+noednsopt\fP clears the EDNS options to be sent.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]expire\fP
.B +[no]expire
This option sends an EDNS Expire option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]fail\fP
.B +[no]fail
This option indicates that \fBnamed\fP should try [or not try] the next server if a SERVFAIL is received. The default is
to not try the next server, which is the reverse of normal stub
resolver behavior.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]header\-only\fP
.B +[no]header\-only
This option sends a query with a DNS header without a question section. The
default is to add a question section. The query type and query name
are ignored when this is set.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]https[=value]\fP
.B +[no]https[=value]
This option indicates whether to use DNS over HTTPS (DoH) when querying
name servers. When this option is in use, the port number defaults to 443.
The HTTP POST request mode is used when sending the query.
@ -369,65 +462,91 @@ The HTTP POST request mode is used when sending the query.
If \fBvalue\fP is specified, it will be used as the HTTP endpoint in the
query URI; the default is \fB/dns\-query\fP\&. So, for example, \fBdig
@example.com +https\fP will use the URI \fBhttps://example.com/dns\-query\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]https\-get[=value]\fP
.B +[no]https\-get[=value]
Similar to \fB+https\fP, except that the HTTP GET request mode is used
when sending the query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]https\-post[=value]\fP
.B +[no]https\-post[=value]
Same as \fB+https\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]http\-plain[=value]\fP
.B +[no]http\-plain[=value]
Similar to \fB+https\fP, except that HTTP queries will be sent over a
non\-encrypted channel. When this option is in use, the port number
defaults to 80 and the HTTP request mode is POST.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]http\-plain\-get[=value]\fP
.B +[no]http\-plain\-get[=value]
Similar to \fB+http\-plain\fP, except that the HTTP request mode is GET.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]http\-plain\-post[=value]\fP
.B +[no]http\-plain\-post[=value]
Same as \fB+http\-plain\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]identify\fP
.B +[no]identify
This option shows [or does not show] the IP address and port number that
supplied the answer, when the \fB+short\fP option is enabled. If short
form answers are requested, the default is not to show the source
address and port number of the server that provided the answer.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]idnin\fP
.B +[no]idnin
This option processes [or does not process] IDN domain names on input. This requires
\fBIDN SUPPORT\fP to have been enabled at compile time.
.sp
The default is to process IDN input when standard output is a tty.
The IDN processing on input is disabled when \fBdig\fP output is redirected
to files, pipes, and other non\-tty file descriptors.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]idnout\fP
.B +[no]idnout
This option converts [or does not convert] puny code on output. This requires
\fBIDN SUPPORT\fP to have been enabled at compile time.
.sp
The default is to process puny code on output when standard output is
a tty. The puny code processing on output is disabled when \fBdig\fP output
is redirected to files, pipes, and other non\-tty file descriptors.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ignore\fP
.B +[no]ignore
This option ignores [or does not ignore] truncation in UDP responses instead of retrying with TCP. By
default, TCP retries are performed.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]keepalive\fP
.B +[no]keepalive
This option sends [or does not send] an EDNS Keepalive option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]keepopen\fP
.B +[no]keepopen
This option keeps [or does not keep] the TCP socket open between queries, and reuses it rather than
creating a new TCP socket for each lookup. The default is
\fB+nokeepopen\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]multiline\fP
.B +[no]multiline
This option prints [or does not print] records, like the SOA records, in a verbose multi\-line format
with human\-readable comments. The default is to print each record on
a single line to facilitate machine parsing of the \fBdig\fP output.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+ndots=D\fP
.B +ndots=D
This option sets the number of dots (\fBD\fP) that must appear in \fBname\fP for
it to be considered absolute. The default value is that defined using
the \fBndots\fP statement in \fB/etc/resolv.conf\fP, or 1 if no \fBndots\fP
@ -435,25 +554,35 @@ statement is present. Names with fewer dots are interpreted as
relative names, and are searched for in the domains listed in the
\fBsearch\fP or \fBdomain\fP directive in \fB/etc/resolv.conf\fP if
\fB+search\fP is set.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]nsid\fP
.B +[no]nsid
When enabled, this option includes an EDNS name server ID request when sending a query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]nssearch\fP
.B +[no]nssearch
When this option is set, \fBdig\fP attempts to find the authoritative
name servers for the zone containing the name being looked up, and
display the SOA record that each name server has for the zone.
Addresses of servers that did not respond are also printed.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]onesoa\fP
.B +[no]onesoa
When enabled, this option prints only one (starting) SOA record when performing an AXFR. The
default is to print both the starting and ending SOA records.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]opcode=value\fP
.B +[no]opcode=value
When enabled, this option sets (restores) the DNS message opcode to the specified value. The
default value is QUERY (0).
.UNINDENT
.INDENT 0.0
.TP
.B \fB+padding=value\fP
.B +padding=value
This option pads the size of the query packet using the EDNS Padding option to
blocks of \fBvalue\fP bytes. For example, \fB+padding=32\fP causes a
48\-byte query to be padded to 64 bytes. The default block size is 0,
@ -461,43 +590,61 @@ which disables padding; the maximum is 512. Values are ordinarily
expected to be powers of two, such as 128; however, this is not
mandatory. Responses to padded queries may also be padded, but only
if the query uses TCP or DNS COOKIE.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+qid=value\fP
.B +qid=value
This option specifies the query ID to use when sending queries.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]qr\fP
.B +[no]qr
This option toggles the display of the query message as it is sent. By default, the query
is not printed.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]question\fP
.B +[no]question
This option toggles the display of the question section of a query when an answer is
returned. The default is to print the question section as a comment.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]raflag\fP
.B +[no]raflag
This option sets [or does not set] the RA (Recursion Available) bit in the query. The
default is \fB+noraflag\fP\&. This bit is ignored by the server for
QUERY.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]rdflag\fP
.B +[no]rdflag
This option is a synonym for \fB+[no]recurse\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]recurse\fP
.B +[no]recurse
This option toggles the setting of the RD (recursion desired) bit in the query.
This bit is set by default, which means \fBdig\fP normally sends
recursive queries. Recursion is automatically disabled when the
\fB+nssearch\fP or \fB+trace\fP query option is used.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+retry=T\fP
.B +retry=T
This option sets the number of times to retry UDP and TCP queries to server to \fBT\fP
instead of the default, 2. Unlike \fB+tries\fP, this does not include
the initial query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]rrcomments\fP
.B +[no]rrcomments
This option toggles the display of per\-record comments in the output (for example,
human\-readable key information about DNSKEY records). The default is
not to print record comments unless multiline mode is active.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]search\fP
.B +[no]search
This option uses [or does not use] the search list defined by the searchlist or domain
directive in \fBresolv.conf\fP, if any. The search list is not used by
default.
@ -505,37 +652,51 @@ default.
\fBndots\fP from \fBresolv.conf\fP (default 1), which may be overridden by
\fB+ndots\fP, determines whether the name is treated as relative
and hence whether a search is eventually performed.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]short\fP
.B +[no]short
This option toggles whether a terse answer is provided. The default is to print the answer in a verbose
form. This option always has a global effect; it cannot be set globally and
then overridden on a per\-lookup basis.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]showbadcookie\fP
.B +[no]showbadcookie
This option toggles whether to show the message containing the
BADCOOKIE rcode before retrying the request or not. The default
is to not show the messages.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]showsearch\fP
.B +[no]showsearch
This option performs [or does not perform] a search showing intermediate results.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]sigchase\fP
.B +[no]sigchase
This feature is now obsolete and has been removed; use \fBdelv\fP
instead.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+split=W\fP
.B +split=W
This option splits long hex\- or base64\-formatted fields in resource records into
chunks of \fBW\fP characters (where \fBW\fP is rounded up to the nearest
multiple of 4). \fB+nosplit\fP or \fB+split=0\fP causes fields not to be
split at all. The default is 56 characters, or 44 characters when
multiline mode is active.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]stats\fP
.B +[no]stats
This option toggles the printing of statistics: when the query was made, the size of the
reply, etc. The default behavior is to print the query statistics as a
comment after each lookup.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]subnet=addr[/prefix\-length]\fP
.B +[no]subnet=addr[/prefix\-length]
This option sends [or does not send] an EDNS CLIENT\-SUBNET option with the specified IP
address or network prefix.
.sp
@ -543,31 +704,43 @@ address or network prefix.
sends an EDNS CLIENT\-SUBNET option with an empty address and a source
prefix\-length of zero, which signals a resolver that the client\(aqs
address information must \fInot\fP be used when resolving this query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]tcflag\fP
.B +[no]tcflag
This option sets [or does not set] the TC (TrunCation) bit in the query. The default is
\fB+notcflag\fP\&. This bit is ignored by the server for QUERY.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]tcp\fP
.B +[no]tcp
This option indicates whether to use TCP when querying name servers.
The default behavior is to use UDP unless a type \fBany\fP or \fBixfr=N\fP
query is requested, in which case the default is TCP. AXFR queries
always use TCP.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+timeout=T\fP
.B +timeout=T
This option sets the timeout for a query to \fBT\fP seconds. The default timeout is
5 seconds. An attempt to set \fBT\fP to less than 1 is silently set to 1.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]tls\fP
.B +[no]tls
This option indicates whether to use DNS over TLS (DoT) when querying
name servers. When this option is in use, the port number defaults
to 853.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]topdown\fP
.B +[no]topdown
This feature is related to \fBdig +sigchase\fP, which is obsolete and
has been removed. Use \fBdelv\fP instead.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]trace\fP
.B +[no]trace
This option toggles tracing of the delegation path from the root name servers for
the name being looked up. Tracing is disabled by default. When
tracing is enabled, \fBdig\fP makes iterative queries to resolve the
@ -580,46 +753,62 @@ the root zone name servers.
.sp
\fB+dnssec\fP is also set when \fB+trace\fP is set, to better emulate the
default queries from a name server.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+tries=T\fP
.B +tries=T
This option sets the number of times to try UDP and TCP queries to server to \fBT\fP
instead of the default, 3. If \fBT\fP is less than or equal to zero,
the number of tries is silently rounded up to 1.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+trusted\-key=####\fP
.B +trusted\-key=####
This option formerly specified trusted keys for use with \fBdig +sigchase\fP\&. This
feature is now obsolete and has been removed; use \fBdelv\fP instead.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ttlid\fP
.B +[no]ttlid
This option displays [or does not display] the TTL when printing the record.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ttlunits\fP
.B +[no]ttlunits
This option displays [or does not display] the TTL in friendly human\-readable time
units of \fBs\fP, \fBm\fP, \fBh\fP, \fBd\fP, and \fBw\fP, representing seconds, minutes,
hours, days, and weeks. This implies \fB+ttlid\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]unknownformat\fP
.B +[no]unknownformat
This option prints all RDATA in unknown RR type presentation format (\fI\%RFC 3597\fP).
The default is to print RDATA for known types in the type\(aqs
presentation format.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]vc\fP
.B +[no]vc
This option uses [or does not use] TCP when querying name servers. This alternate
syntax to \fB+[no]tcp\fP is provided for backwards compatibility. The
\fBvc\fP stands for "virtual circuit."
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]yaml\fP
.B +[no]yaml
When enabled, this option prints the responses (and, if \fB+qr\fP is in use, also the
outgoing queries) in a detailed YAML format.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]zflag\fP
.B +[no]zflag
This option sets [or does not set] the last unassigned DNS header flag in a DNS query.
This flag is off by default.
.UNINDENT
.SH MULTIPLE QUERIES
.sp
The BIND 9 implementation of \fBdig\fP supports specifying multiple
queries on the command line (in addition to supporting the \fB\-f\fP batch
queries on the command line (in addition to supporting the \fI\%\-f\fP batch
file option). Each of those queries can be supplied with its own set of
flags, options, and query options.
.sp

62
doc/man/dnssec-cds.1in
View file

@ -43,9 +43,9 @@ its key\-signing keys (KSKs); by polling periodically with \fBdnssec\-cds\fP, th
parent can keep the DS records up\-to\-date and enable automatic rolling
of KSKs.
.sp
Two input files are required. The \fB\-f child\-file\fP option specifies a
Two input files are required. The \fI\%\-f child\-file\fP option specifies a
file containing the child\(aqs CDS and/or CDNSKEY records, plus RRSIG and
DNSKEY records so that they can be authenticated. The \fB\-d path\fP option
DNSKEY records so that they can be authenticated. The \fI\%\-d path\fP option
specifies the location of a file containing the current DS records. For
example, this could be a \fBdsset\-\fP file generated by
\fBdnssec\-signzone\fP, or the output of \fBdnssec\-dsfromkey\fP, or the
@ -59,7 +59,7 @@ is typically the pre\-existing KSK.
For protection against replay attacks, the signatures on the child
records must not be older than they were on a previous run of
\fBdnssec\-cds\fP\&. Their age is obtained from the modification time of the
\fBdsset\-\fP file, or from the \fB\-s\fP option.
\fBdsset\-\fP file, or from the \fI\%\-s\fP option.
.sp
To protect against breaking the delegation, \fBdnssec\-cds\fP ensures that
the DNSKEY RRset can be verified by every key algorithm in the new DS
@ -67,7 +67,7 @@ RRset, and that the same set of keys are covered by every DS digest
type.
.sp
By default, replacement DS records are written to the standard output;
with the \fB\-i\fP option the input file is overwritten in place. The
with the \fI\%\-i\fP option the input file is overwritten in place. The
replacement DS records are the same as the existing records, when no
change is required. The output can be empty if the CDS/CDNSKEY records
specify that the child zone wants to be insecure.
@ -79,13 +79,13 @@ Be careful not to delete the DS records when \fBdnssec\-cds\fP fails!
.UNINDENT
.UNINDENT
.sp
Alternatively, \fBdnssec\-cds \-u\fP writes an \fBnsupdate\fP script to the
standard output. The \fB\-u\fP and \fB\-i\fP options can be used together to
Alternatively, :option\(gadnssec\-cds \-u\(ga writes an \fBnsupdate\fP script to the
standard output. The \fI\%\-u\fP and \fI\%\-i\fP options can be used together to
maintain a \fBdsset\-\fP file as well as emit an \fBnsupdate\fP script.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-a algorithm\fP
.B \-a algorithm
When converting CDS records to DS records, this option specifies
the acceptable digest algorithms. This option can be repeated, so
that multiple digest types are allowed. If none of the CDS records
@ -99,36 +99,46 @@ are created for each CDNSKEY records.
The algorithm must be one of SHA\-1, SHA\-256, or SHA\-384. These values
are case\-insensitive, and the hyphen may be omitted. If no algorithm
is specified, the default is SHA\-256 only.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option specifies the DNS class of the zones.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D\fP
.B \-D
This option generates DS records from CDNSKEY records if both CDS and CDNSKEY
records are present in the child zone. By default CDS records are
preferred.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-d path\fP
.B \-d path
This specifies the location of the parent DS records. The path can be the name of a file
containing the DS records; if it is a directory, \fBdnssec\-cds\fP
looks for a \fBdsset\-\fP file for the domain inside the directory.
.sp
To protect against replay attacks, child records are rejected if they
were signed earlier than the modification time of the \fBdsset\-\fP
file. This can be adjusted with the \fB\-s\fP option.
file. This can be adjusted with the \fI\%\-s\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f child\-file\fP
.B \-f child\-file
This option specifies the file containing the child\(aqs CDS and/or CDNSKEY records, plus its
DNSKEY records and the covering RRSIG records, so that they can be
authenticated.
.sp
The examples below describe how to generate this file.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-iextension\fP
.B \-i extension
This option updates the \fBdsset\-\fP file in place, instead of writing DS records to
the standard output.
.sp
There must be no space between the \fB\-i\fP and the extension. If
There must be no space between the \fI\%\-i\fP and the extension. If
no extension is provided, the old \fBdsset\-\fP is discarded. If an
extension is present, a backup of the old \fBdsset\-\fP file is kept
with the extension appended to its filename.
@ -137,8 +147,10 @@ To protect against replay attacks, the modification time of the
\fBdsset\-\fP file is set to match the signature inception time of the
child records, provided that it is later than the file\(aqs current
modification time.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s start\-time\fP
.B \-s start\-time
This option specifies the date and time after which RRSIG records become
acceptable. This can be either an absolute or a relative time. An
absolute start time is indicated by a number in YYYYMMDDHHMMSS
@ -149,27 +161,37 @@ current time is indicated with \fBnow+N\fP\&.
.sp
If no start\-time is specified, the modification time of the
\fBdsset\-\fP file is used.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-T ttl\fP
.B \-T ttl
This option specifies a TTL to be used for new DS records. If not specified, the
default is the TTL of the old DS records. If they had no explicit TTL,
the new DS records also have no explicit TTL.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-u\fP
.B \-u
This option writes an \fBnsupdate\fP script to the standard output, instead of
printing the new DS reords. The output is empty if no change is
needed.
.sp
Note: The TTL of new records needs to be specified: it can be done in the
original \fBdsset\-\fP file, with the \fB\-T\fP option, or using the
original \fBdsset\-\fP file, with the \fI\%\-T\fP option, or using the
\fBnsupdate\fP \fBttl\fP command.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints version information.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v level\fP
.B \-v level
This option sets the debugging level. Level 1 is intended to be usefully verbose
for general users; higher levels are intended for developers.
.UNINDENT
.INDENT 0.0
.TP
.B \fBdomain\fP
This indicates the name of the delegation point/child zone apex.

70
doc/man/dnssec-dsfromkey.1in
View file

@ -42,10 +42,10 @@ dnssec-dsfromkey \- DNSSEC DS RR generation tool
.SH DESCRIPTION
.sp
The \fBdnssec\-dsfromkey\fP command outputs DS (Delegation Signer) resource records
(RRs), or CDS (Child DS) RRs with the \fB\-C\fP option.
(RRs), or CDS (Child DS) RRs with the \fI\%\-C\fP option.
.sp
By default, only KSKs are converted (keys with flags = 257). The
\fB\-A\fP option includes ZSKs (flags = 256). Revoked keys are never
\fI\%\-A\fP option includes ZSKs (flags = 256). Revoked keys are never
included.
.sp
The input keys can be specified in a number of ways:
@ -53,21 +53,25 @@ The input keys can be specified in a number of ways:
By default, \fBdnssec\-dsfromkey\fP reads a key file named in the format
\fBKnnnn.+aaa+iiiii.key\fP, as generated by \fBdnssec\-keygen\fP\&.
.sp
With the \fB\-f file\fP option, \fBdnssec\-dsfromkey\fP reads keys from a zone
With the \fI\%\-f file\fP option, \fBdnssec\-dsfromkey\fP reads keys from a zone
file or partial zone file (which can contain just the DNSKEY records).
.sp
With the \fB\-s\fP option, \fBdnssec\-dsfromkey\fP reads a \fBkeyset\-\fP file,
as generated by \fBdnssec\-keygen\fP \fB\-C\fP\&.
With the \fI\%\-s\fP option, \fBdnssec\-dsfromkey\fP reads a \fBkeyset\-\fP file,
as generated by \fBdnssec\-keygen\fP \fI\%\-C\fP\&.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-1\fP
This option is an abbreviation for \fB\-a SHA1\fP\&.
.B \-1
This option is an abbreviation for \fI\%\-a SHA1\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-2\fP
This option is an abbreviation for \fB\-a SHA\-256\fP\&.
.B \-2
This option is an abbreviation for \fI\%\-a SHA\-256\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-a algorithm\fP
.B \-a algorithm
This option specifies a digest algorithm to use when converting DNSKEY records to
DS records. This option can be repeated, so that multiple DS records
are created for each DNSKEY record.
@ -75,20 +79,28 @@ are created for each DNSKEY record.
The algorithm must be one of SHA\-1, SHA\-256, or SHA\-384. These values
are case\-insensitive, and the hyphen may be omitted. If no algorithm
is specified, the default is SHA\-256.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-A\fP
.B \-A
This option indicates that ZSKs are to be included when generating DS records. Without this option, only
keys which have the KSK flag set are converted to DS records and
printed. This option is only useful in \fB\-f\fP zone file mode.
printed. This option is only useful in \fI\%\-f\fP zone file mode.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c class\fP
This option specifies the DNS class; the default is IN. This option is only useful in \fB\-s\fP keyset
or \fB\-f\fP zone file mode.
.B \-c class
This option specifies the DNS class; the default is IN. This option is only useful in \fI\%\-s\fP keyset
or \fI\%\-f\fP zone file mode.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-C\fP
.B \-C
This option generates CDS records rather than DS records.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f file\fP
.B \-f file
This option sets zone file mode, in which the final dnsname argument of \fBdnssec\-dsfromkey\fP is the
DNS domain name of a zone whose master file can be read from
\fBfile\fP\&. If the zone name is the same as \fBfile\fP, then it may be
@ -99,24 +111,36 @@ input. This makes it possible to use the output of the \fBdig\fP
command as input, as in:
.sp
\fBdig dnskey example.com | dnssec\-dsfromkey \-f \- example.com\fP
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints usage information.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-K directory\fP
.B \-K directory
This option tells BIND 9 to look for key files or \fBkeyset\-\fP files in \fBdirectory\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s\fP
.B \-s
This option enables keyset mode, in which the final dnsname argument from \fBdnssec\-dsfromkey\fP is the DNS
domain name used to locate a \fBkeyset\-\fP file.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-T TTL\fP
.B \-T TTL
This option specifies the TTL of the DS records. By default the TTL is omitted.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v level\fP
.B \-v level
This option sets the debugging level.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints version information.
.UNINDENT
.SH EXAMPLE

38
doc/man/dnssec-importkey.1in
View file

@ -45,13 +45,13 @@ input, in which case both .key and .private files are generated.
.sp
The newly created .private file does \fInot\fP contain private key data, and
cannot be used for signing. However, having a .private file makes it
possible to set publication (\fB\-P\fP) and deletion (\fB\-D\fP) times for the
possible to set publication (\fI\%\-P\fP) and deletion (\fI\%\-D\fP) times for the
key, which means the public key can be added to and removed from the
DNSKEY RRset on schedule even if the true private key is stored offline.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-f filename\fP
.B \-f filename
This option indicates the zone file mode. Instead of a public keyfile name, the argument is the
DNS domain name of a zone master file, which can be read from
\fBfilename\fP\&. If the domain name is the same as \fBfilename\fP, then it may be
@ -59,24 +59,34 @@ omitted.
.sp
If \fBfilename\fP is set to \fB"\-"\fP, then the zone data is read from the
standard input.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-K directory\fP
.B \-K directory
This option sets the directory in which the key files are to reside.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-L ttl\fP
.B \-L ttl
This option sets the default TTL to use for this key when it is converted into a
DNSKEY RR. This is the TTL used when the key is imported into a zone,
unless there was already a DNSKEY RRset in
place, in which case the existing TTL takes precedence. Setting the default TTL to \fB0\fP or \fBnone\fP
removes it from the key.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option emits a usage message and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v level\fP
.B \-v level
This option sets the debugging level.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints version information.
.UNINDENT
.SH TIMING OPTIONS
@ -91,21 +101,27 @@ respectively. Without a suffix, the offset is computed in seconds. To
explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&.
.INDENT 0.0
.TP
.B \fB\-P date/offset\fP
.B \-P date/offset
This option sets the date on which a key is to be published to the zone. After
that date, the key is included in the zone but is not used
to sign it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-P sync date/offset\fP
.B \-P sync date/offset
This option sets the date on which CDS and CDNSKEY records that match this key
are to be published to the zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D date/offset\fP
.B \-D date/offset
This option sets the date on which the key is to be deleted. After that date, the
key is no longer included in the zone. (However, it may remain in the key
repository.)
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D sync date/offset\fP
.B \-D sync date/offset
This option sets the date on which the CDS and CDNSKEY records that match this
key are to be deleted.
.UNINDENT

120
doc/man/dnssec-keyfromlabel.1in
View file

@ -47,117 +47,153 @@ match the name of the zone for which the key is being generated.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-a algorithm\fP
.B \-a algorithm
This option selects the cryptographic algorithm. The value of \fBalgorithm\fP must
be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512,
ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448.
.sp
If no algorithm is specified, RSASHA1 is used by default
unless the \fB\-3\fP option is specified, in which case NSEC3RSASHA1
is used instead. (If \fB\-3\fP is used and an algorithm is
unless the \fI\%\-3\fP option is specified, in which case NSEC3RSASHA1
is used instead. (If \fI\%\-3\fP is used and an algorithm is
specified, that algorithm is checked for compatibility with
NSEC3.)
.sp
These values are case\-insensitive. In some cases, abbreviations are
supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for
ECDSAP384SHA384. If RSASHA1 is specified along with the \fB\-3\fP
ECDSAP384SHA384. If RSASHA1 is specified along with the \fI\%\-3\fP
option, then NSEC3RSASHA1 is used instead.
.sp
Since BIND 9.12.0, this option is mandatory except when using the
\fB\-S\fP option, which copies the algorithm from the predecessory key.
\fI\%\-S\fP option, which copies the algorithm from the predecessory key.
Previously, the default for newly generated keys was RSASHA1.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-3\fP
.B \-3
This option uses an NSEC3\-capable algorithm to generate a DNSSEC key. If this
option is used with an algorithm that has both NSEC and NSEC3
versions, then the NSEC3 version is used; for example,
\fBdnssec\-keygen \-3a RSASHA1\fP specifies the NSEC3RSASHA1 algorithm.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-E engine\fP
.B \-E engine
This option specifies the cryptographic hardware to use.
.sp
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
engine identifier that drives the cryptographic accelerator or
hardware service module (usually \fBpkcs11\fP).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-l label\fP
.B \-l label
This option specifies the label for a key pair in the crypto hardware.
.sp
When BIND 9 is built with OpenSSL\-based PKCS#11 support, the label is
an arbitrary string that identifies a particular key. It may be
preceded by an optional OpenSSL engine name, followed by a colon, as
in \fBpkcs11:keylabel\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-n nametype\fP
.B \-n nametype
This option specifies the owner type of the key. The value of \fBnametype\fP must
either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY
(for a key associated with a host (KEY)), USER (for a key associated
with a user (KEY)), or OTHER (DNSKEY). These values are
case\-insensitive.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-C\fP
.B \-C
This option enables compatibility mode, which generates an old\-style key, without any metadata.
By default, \fBdnssec\-keyfromlabel\fP includes the key\(aqs creation
date in the metadata stored with the private key; other dates may
be set there as well, including publication date, activation date, etc. Keys
that include this data may be incompatible with older versions of
BIND; the \fB\-C\fP option suppresses them.
BIND; the \fI\%\-C\fP option suppresses them.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option indicates that the DNS record containing the key should have the
specified class. If not specified, class IN is used.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f flag\fP
.B \-f flag
This option sets the specified flag in the \fBflag\fP field of the KEY/DNSKEY record.
The only recognized flags are KSK (Key\-Signing Key) and REVOKE.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-G\fP
.B \-G
This option generates a key, but does not publish it or sign with it. This option is
incompatible with \fB\-P\fP and \fB\-A\fP\&.
incompatible with \fI\%\-P\fP and \fI\%\-A\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints a short summary of the options and arguments to
\fBdnssec\-keyfromlabel\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-K directory\fP
.B \-K directory
This option sets the directory in which the key files are to be written.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k\fP
.B \-k
This option generates KEY records rather than DNSKEY records.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-L\fP ttl
.B \-L ttl
This option sets the default TTL to use for this key when it is converted into a
DNSKEY RR. This is the TTL used when the key is imported into a zone,
unless there was already a DNSKEY RRset in
place, in which case the existing TTL would take precedence. Setting
the default TTL to \fB0\fP or \fBnone\fP removes it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p protocol\fP
.B \-p protocol
This option sets the protocol value for the key. The protocol is a number between
0 and 255. The default is 3 (DNSSEC). Other possible values for this
argument are listed in \fI\%RFC 2535\fP and its successors.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-S key\fP
.B \-S key
This option generates a key as an explicit successor to an existing key. The name,
algorithm, size, and type of the key are set to match the
predecessor. The activation date of the new key is set to the
inactivation date of the existing one. The publication date is
set to the activation date minus the prepublication interval, which
defaults to 30 days.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t type\fP
.B \-t type
This option indicates the type of the key. \fBtype\fP must be one of AUTHCONF,
NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers
to the ability to authenticate data, and CONF to the ability to encrypt
data.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v level\fP
.B \-v level
This option sets the debugging level.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints version information.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-y\fP
.B \-y
This option allows DNSSEC key files to be generated even if the key ID would
collide with that of an existing key, in the event of either key
being revoked. (This is only safe to enable if
@ -176,41 +212,55 @@ respectively. Without a suffix, the offset is computed in seconds. To
explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&.
.INDENT 0.0
.TP
.B \fB\-P date/offset\fP
.B \-P date/offset
This option sets the date on which a key is to be published to the zone. After
that date, the key is included in the zone but is not used
to sign it. If not set, and if the \fB\-G\fP option has not been used, the
to sign it. If not set, and if the \fI\%\-G\fP option has not been used, the
default is the current date.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-P sync date/offset\fP
.B \-P sync date/offset
This option sets the date on which CDS and CDNSKEY records that match this key
are to be published to the zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-A date/offset\fP
.B \-A date/offset
This option sets the date on which the key is to be activated. After that date,
the key is included in the zone and used to sign it. If not set,
and if the \fB\-G\fP option has not been used, the default is the current date.
and if the \fI\%\-G\fP option has not been used, the default is the current date.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-R date/offset\fP
.B \-R date/offset
This option sets the date on which the key is to be revoked. After that date, the
key is flagged as revoked. It is included in the zone and
is used to sign it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-I date/offset\fP
.B \-I date/offset
This option sets the date on which the key is to be retired. After that date, the
key is still included in the zone, but it is not used to
sign it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D date/offset\fP
.B \-D date/offset
This option sets the date on which the key is to be deleted. After that date, the
key is no longer included in the zone. (However, it may remain in the key
repository.)
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D sync date/offset\fP
.B \-D sync date/offset
This option sets the date on which the CDS and CDNSKEY records that match this
key are to be deleted.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-i interval\fP
.B \-i interval
This option sets the prepublication interval for a key. If set, then the
publication and activation dates must be separated by at least this
much time. If the activation date is specified but the publication

148
doc/man/dnssec-keygen.1in
View file

@ -46,32 +46,36 @@ generated.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-3\fP
.B \-3
This option uses an NSEC3\-capable algorithm to generate a DNSSEC key. If this
option is used with an algorithm that has both NSEC and NSEC3
versions, then the NSEC3 version is selected; for example,
\fBdnssec\-keygen \-3a RSASHA1\fP specifies the NSEC3RSASHA1 algorithm.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-a algorithm\fP
.B \-a algorithm
This option selects the cryptographic algorithm. For DNSSEC keys, the value of
\fBalgorithm\fP must be one of RSASHA1, NSEC3RSASHA1, RSASHA256,
RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. For
TKEY, the value must be DH (Diffie\-Hellman); specifying this value
automatically sets the \fB\-T KEY\fP option as well.
automatically sets the \fI\%\-T KEY\fP option as well.
.sp
These values are case\-insensitive. In some cases, abbreviations are
supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for
ECDSAP384SHA384. If RSASHA1 is specified along with the \fB\-3\fP
ECDSAP384SHA384. If RSASHA1 is specified along with the \fI\%\-3\fP
option, NSEC3RSASHA1 is used instead.
.sp
This parameter \fImust\fP be specified except when using the \fB\-S\fP
This parameter \fImust\fP be specified except when using the \fI\%\-S\fP
option, which copies the algorithm from the predecessor key.
.sp
In prior releases, HMAC algorithms could be generated for use as TSIG
keys, but that feature was removed in BIND 9.13.0. Use
\fBtsig\-keygen\fP to generate TSIG keys.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-b keysize\fP
.B \-b keysize
This option specifies the number of bits in the key. The choice of key size
depends on the algorithm used: RSA keys must be between 1024 and 4096
bits; Diffie\-Hellman keys must be between 128 and 4096 bits. Elliptic
@ -80,54 +84,74 @@ curve algorithms do not need this parameter.
If the key size is not specified, some algorithms have pre\-defined
defaults. For example, RSA keys for use as DNSSEC zone\-signing keys
have a default size of 1024 bits; RSA keys for use as key\-signing
keys (KSKs, generated with \fB\-f KSK\fP) default to 2048 bits.
keys (KSKs, generated with \fI\%\-f KSK\fP) default to 2048 bits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-C\fP
.B \-C
This option enables compatibility mode, which generates an old\-style key, without any timing
metadata. By default, \fBdnssec\-keygen\fP includes the key\(aqs
creation date in the metadata stored with the private key; other
dates may be set there as well, including publication date, activation date,
etc. Keys that include this data may be incompatible with older
versions of BIND; the \fB\-C\fP option suppresses them.
versions of BIND; the \fI\%\-C\fP option suppresses them.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option indicates that the DNS record containing the key should have the
specified class. If not specified, class IN is used.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-d bits\fP
.B \-d bits
This option specifies the key size in bits. For the algorithms RSASHA1, NSEC3RSASA1, RSASHA256, and
RSASHA512 the key size must be between 1024 and 4096 bits; DH size is between 128
and 4096 bits. This option is ignored for algorithms ECDSAP256SHA256,
ECDSAP384SHA384, ED25519, and ED448.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-E engine\fP
.B \-E engine
This option specifies the cryptographic hardware to use, when applicable.
.sp
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
engine identifier that drives the cryptographic accelerator or
hardware service module (usually \fBpkcs11\fP).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f flag\fP
.B \-f flag
This option sets the specified flag in the flag field of the KEY/DNSKEY record.
The only recognized flags are KSK (Key\-Signing Key) and REVOKE.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-G\fP
.B \-G
This option generates a key, but does not publish it or sign with it. This option is
incompatible with \fB\-P\fP and \fB\-A\fP\&.
incompatible with \fI\%\-P\fP and \fI\%\-A\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-g generator\fP
.B \-g generator
This option indicates the generator to use if generating a Diffie\-Hellman key. Allowed
values are 2 and 5. If no generator is specified, a known prime from
\fI\%RFC 2539\fP is used if possible; otherwise the default is 2.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints a short summary of the options and arguments to
\fBdnssec\-keygen\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-K directory\fP
.B \-K directory
This option sets the directory in which the key files are to be written.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k policy\fP
.B \-k policy
This option creates keys for a specific \fBdnssec\-policy\fP\&. If a policy uses multiple keys,
\fBdnssec\-keygen\fP generates multiple keys. This also
creates a ".state" file to keep track of the key state.
@ -135,8 +159,10 @@ creates a ".state" file to keep track of the key state.
This option creates keys according to the \fBdnssec\-policy\fP configuration, hence
it cannot be used at the same time as many of the other options that
\fBdnssec\-keygen\fP provides.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-L ttl\fP
.B \-L ttl
This option sets the default TTL to use for this key when it is converted into a
DNSKEY RR. This is the TTL used when the key is imported into a zone,
unless there was already a DNSKEY RRset in
@ -144,25 +170,33 @@ place, in which case the existing TTL takes precedence. If this
value is not set and there is no existing DNSKEY RRset, the TTL
defaults to the SOA TTL. Setting the default TTL to \fB0\fP or \fBnone\fP
is the same as leaving it unset.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-l file\fP
.B \-l file
This option provides a configuration file that contains a \fBdnssec\-policy\fP statement
(matching the policy set with \fB\-k\fP).
(matching the policy set with \fI\%\-k\fP).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-n nametype\fP
.B \-n nametype
This option specifies the owner type of the key. The value of \fBnametype\fP must
either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY
(for a key associated with a host (KEY)), USER (for a key associated
with a user (KEY)), or OTHER (DNSKEY). These values are
case\-insensitive. The default is ZONE for DNSKEY generation.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p protocol\fP
.B \-p protocol
This option sets the protocol value for the generated key, for use with
\fB\-T KEY\fP\&. The protocol is a number between 0 and 255. The default
\fI\%\-T KEY\fP\&. The protocol is a number between 0 and 255. The default
is 3 (DNSSEC). Other possible values for this argument are listed in
\fI\%RFC 2535\fP and its successors.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-q\fP
.B \-q
This option sets quiet mode, which suppresses unnecessary output, including progress
indication. Without this option, when \fBdnssec\-keygen\fP is run
interactively to generate an RSA or DSA key pair, it prints a
@ -171,35 +205,47 @@ generation. A \fB\&.\fP indicates that a random number has been found which
passed an initial sieve test; \fB+\fP means a number has passed a single
round of the Miller\-Rabin primality test; and a space ( ) means that the
number has passed all the tests and is a satisfactory key.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-S key\fP
.B \-S key
This option creates a new key which is an explicit successor to an existing key.
The name, algorithm, size, and type of the key are set to match
the existing key. The activation date of the new key is set to
the inactivation date of the existing one. The publication date is
set to the activation date minus the prepublication interval,
which defaults to 30 days.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s strength\fP
.B \-s strength
This option specifies the strength value of the key. The strength is a number
between 0 and 15, and currently has no defined purpose in DNSSEC.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-T rrtype\fP
.B \-T rrtype
This option specifies the resource record type to use for the key. \fBrrtype\fP
must be either DNSKEY or KEY. The default is DNSKEY when using a
DNSSEC algorithm, but it can be overridden to KEY for use with
SIG(0).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t type\fP
This option indicates the type of the key for use with \fB\-T KEY\fP\&. \fBtype\fP
.B \-t type
This option indicates the type of the key for use with \fI\%\-T KEY\fP\&. \fBtype\fP
must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default
is AUTHCONF. AUTH refers to the ability to authenticate data, and
CONF to the ability to encrypt data.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints version information.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v level\fP
.B \-v level
This option sets the debugging level.
.UNINDENT
.SH TIMING OPTIONS
@ -214,43 +260,57 @@ respectively. Without a suffix, the offset is computed in seconds. To
explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&.
.INDENT 0.0
.TP
.B \fB\-P date/offset\fP
.B \-P date/offset
This option sets the date on which a key is to be published to the zone. After
that date, the key is included in the zone but is not used
to sign it. If not set, and if the \fB\-G\fP option has not been used, the
to sign it. If not set, and if the \fI\%\-G\fP option has not been used, the
default is the current date.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-P sync date/offset\fP
.B \-P sync date/offset
This option sets the date on which CDS and CDNSKEY records that match this key
are to be published to the zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-A date/offset\fP
.B \-A date/offset
This option sets the date on which the key is to be activated. After that date,
the key is included in the zone and used to sign it. If not set,
and if the \fB\-G\fP option has not been used, the default is the current date. If set,
and \fB\-P\fP is not set, the publication date is set to the
and if the \fI\%\-G\fP option has not been used, the default is the current date. If set,
and \fI\%\-P\fP is not set, the publication date is set to the
activation date minus the prepublication interval.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-R date/offset\fP
.B \-R date/offset
This option sets the date on which the key is to be revoked. After that date, the
key is flagged as revoked. It is included in the zone and
is used to sign it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-I date/offset\fP
.B \-I date/offset
This option sets the date on which the key is to be retired. After that date, the
key is still included in the zone, but it is not used to
sign it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D date/offset\fP
.B \-D date/offset
This option sets the date on which the key is to be deleted. After that date, the
key is no longer included in the zone. (However, it may remain in the key
repository.)
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D sync date/offset\fP
.B \-D sync date/offset
This option sets the date on which the CDS and CDNSKEY records that match this
key are to be deleted.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-i interval\fP
.B \-i interval
This option sets the prepublication interval for a key. If set, then the
publication and activation dates must be separated by at least this
much time. If the activation date is specified but the publication

30
doc/man/dnssec-revoke.1in
View file

@ -41,34 +41,48 @@ containing the now\-revoked key.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option emits a usage message and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-K directory\fP
.B \-K directory
This option sets the directory in which the key files are to reside.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-r\fP
.B \-r
This option indicates to remove the original keyset files after writing the new keyset files.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v level\fP
.B \-v level
This option sets the debugging level.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints version information.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-E engine\fP
.B \-E engine
This option specifies the cryptographic hardware to use, when applicable.
.sp
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
engine identifier that drives the cryptographic accelerator or
hardware service module (usually \fBpkcs11\fP).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f\fP
.B \-f
This option indicates a forced overwrite and causes \fBdnssec\-revoke\fP to write the new key pair,
even if a file already exists matching the algorithm and key ID of
the revoked key.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-R\fP
.B \-R
This option prints the key tag of the key with the REVOKE bit set, but does not
revoke the key.
.UNINDENT

116
doc/man/dnssec-settime.1in
View file

@ -36,10 +36,10 @@ dnssec-settime \- set the key timing metadata for a DNSSEC key
.SH DESCRIPTION
.sp
\fBdnssec\-settime\fP reads a DNSSEC private key file and sets the key
timing metadata as specified by the \fB\-P\fP, \fB\-A\fP, \fB\-R\fP, \fB\-I\fP, and
\fB\-D\fP options. The metadata can then be used by \fBdnssec\-signzone\fP or
other signing software to determine when a key is to be published,
whether it should be used for signing a zone, etc.
timing metadata as specified by the \fI\%\-P\fP, \fI\%\-A\fP, \fI\%\-R\fP,
\fI\%\-I\fP, and \fI\%\-D\fP options. The metadata can then be used by
\fBdnssec\-signzone\fP or other signing software to determine when a key is
to be published, whether it should be used for signing a zone, etc.
.sp
If none of these options is set on the command line,
\fBdnssec\-settime\fP simply prints the key timing metadata already stored
@ -55,12 +55,12 @@ the key file. The private file\(aqs permissions are always set to be
inaccessible to anyone other than the owner (mode 0600).
.sp
When working with state files, it is possible to update the timing metadata in
those files as well with \fB\-s\fP\&. With this option, it is also possible to update key
states with \fB\-d\fP (DS), \fB\-k\fP (DNSKEY), \fB\-r\fP (RRSIG of KSK), or \fB\-z\fP
(RRSIG of ZSK). Allowed states are HIDDEN, RUMOURED, OMNIPRESENT, and
UNRETENTIVE.
those files as well with \fI\%\-s\fP\&. With this option, it is also possible
to update key states with \fI\%\-d\fP (DS), \fI\%\-k\fP (DNSKEY), \fI\%\-r\fP
(RRSIG of KSK), or \fI\%\-z\fP (RRSIG of ZSK). Allowed states are HIDDEN,
RUMOURED, OMNIPRESENT, and UNRETENTIVE.
.sp
The goal state of the key can also be set with \fB\-g\fP\&. This should be either
The goal state of the key can also be set with \fI\%\-g\fP\&. This should be either
HIDDEN or OMNIPRESENT, representing whether the key should be removed from the
zone or published.
.sp
@ -69,7 +69,7 @@ purposes.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-f\fP
.B \-f
This option forces an update of an old\-format key with no metadata fields. Without
this option, \fBdnssec\-settime\fP fails when attempting to update a
legacy key. With this option, the key is recreated in the new
@ -77,11 +77,15 @@ format, but with the original key data retained. The key\(aqs creation
date is set to the present time. If no other values are
specified, then the key\(aqs publication and activation dates are also
set to the present time.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-K directory\fP
.B \-K directory
This option sets the directory in which the key files are to reside.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-L ttl\fP
.B \-L ttl
This option sets the default TTL to use for this key when it is converted into a
DNSKEY RR. This is the TTL used when the key is imported into a zone,
unless there was already a DNSKEY RRset in
@ -89,17 +93,25 @@ place, in which case the existing TTL takes precedence. If this
value is not set and there is no existing DNSKEY RRset, the TTL
defaults to the SOA TTL. Setting the default TTL to \fB0\fP or \fBnone\fP
removes it from the key.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option emits a usage message and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints version information.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v level\fP
.B \-v level
This option sets the debugging level.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-E engine\fP
.B \-E engine
This option specifies the cryptographic hardware to use, when applicable.
.sp
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
@ -118,55 +130,75 @@ respectively. Without a suffix, the offset is computed in seconds. To
explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&.
.INDENT 0.0
.TP
.B \fB\-P date/offset\fP
.B \-P date/offset
This option sets the date on which a key is to be published to the zone. After
that date, the key is included in the zone but is not used
to sign it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-P ds date/offset\fP
.B \-P ds date/offset
This option sets the date on which DS records that match this key have been
seen in the parent zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-P sync date/offset\fP
.B \-P sync date/offset
This option sets the date on which CDS and CDNSKEY records that match this key
are to be published to the zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-A date/offset\fP
.B \-A date/offset
This option sets the date on which the key is to be activated. After that date,
the key is included in the zone and used to sign it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-R date/offset\fP
.B \-R date/offset
This option sets the date on which the key is to be revoked. After that date, the
key is flagged as revoked. It is included in the zone and
is used to sign it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-I date/offset\fP
.B \-I date/offset
This option sets the date on which the key is to be retired. After that date, the
key is still included in the zone, but it is not used to
sign it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D date/offset\fP
.B \-D date/offset
This option sets the date on which the key is to be deleted. After that date, the
key is no longer included in the zone. (However, it may remain in the key
repository.)
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D ds date/offset\fP
.B \-D ds date/offset
This option sets the date on which the DS records that match this key have
been seen removed from the parent zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D sync date/offset\fP
.B \-D sync date/offset
This option sets the date on which the CDS and CDNSKEY records that match this
key are to be deleted.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-S predecessor key\fP
.B \-S predecessor key
This option selects a key for which the key being modified is an explicit
successor. The name, algorithm, size, and type of the predecessor key
must exactly match those of the key being modified. The activation
date of the successor key is set to the inactivation date of the
predecessor. The publication date is set to the activation date
minus the prepublication interval, which defaults to 30 days.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-i interval\fP
.B \-i interval
This option sets the prepublication interval for a key. If set, then the
publication and activation dates must be separated by at least this
much time. If the activation date is specified but the publication
@ -193,22 +225,32 @@ purpose, but should never be used in production.
Known key states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE.
.INDENT 0.0
.TP
.B \fB\-s\fP
.B \-s
This option indicates that when setting key timing data, the state file should also be updated.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-g state\fP
.B \-g state
This option sets the goal state for this key. Must be HIDDEN or OMNIPRESENT.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-d state date/offset\fP
.B \-d state date/offset
This option sets the DS state for this key as of the specified date, offset from the current date.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k state date/offset\fP
.B \-k state date/offset
This option sets the DNSKEY state for this key as of the specified date, offset from the current date.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-r state date/offset\fP
.B \-r state date/offset
This option sets the RRSIG (KSK) state for this key as of the specified date, offset from the current date.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-z state date/offset\fP
.B \-z state date/offset
This option sets the RRSIG (ZSK) state for this key as of the specified date, offset from the current date.
.UNINDENT
.SH PRINTING OPTIONS
@ -217,12 +259,14 @@ This option sets the RRSIG (ZSK) state for this key as of the specified date, of
associated with a key.
.INDENT 0.0
.TP
.B \fB\-u\fP
.B \-u
This option indicates that times should be printed in Unix epoch format.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all\fP
.B \-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all
This option prints a specific metadata value or set of metadata values.
The \fB\-p\fP option may be followed by one or more of the following letters or
The \fI\%\-p\fP option may be followed by one or more of the following letters or
strings to indicate which value or values to print: \fBC\fP for the
creation date, \fBP\fP for the publication date, \fBPds\(ga for the DS publication
date, \(ga\(gaPsync\fP for the CDS and CDNSKEY publication date, \fBA\fP for the

183
doc/man/dnssec-signzone.1in
View file

@ -43,49 +43,67 @@ file for each child zone.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-a\fP
.B \-a
This option verifies all generated signatures.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option specifies the DNS class of the zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-C\fP
.B \-C
This option sets compatibility mode, in which a \fBkeyset\-zonename\fP file is generated in addition
to \fBdsset\-zonename\fP when signing a zone, for use by older versions
of \fBdnssec\-signzone\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-d directory\fP
.B \-d directory
This option indicates the directory where BIND 9 should look for \fBdsset\-\fP or \fBkeyset\-\fP files.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D\fP
.B \-D
This option indicates that only those record types automatically managed by
\fBdnssec\-signzone\fP, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output.
If smart signing (\fB\-S\fP) is used, DNSKEY records are also included.
If smart signing (\fI\%\-S\fP) is used, DNSKEY records are also included.
The resulting file can be included in the original zone file with
\fB$INCLUDE\fP\&. This option cannot be combined with \fB\-O raw\fP
\fB$INCLUDE\fP\&. This option cannot be combined with \fI\%\-O raw\fP
or serial\-number updating.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-E engine\fP
.B \-E engine
This option specifies the hardware to use for cryptographic
operations, such as a secure key store used for signing, when applicable.
.sp
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
engine identifier that drives the cryptographic accelerator or
hardware service module (usually \fBpkcs11\fP).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-g\fP
.B \-g
This option indicates that DS records for child zones should be generated from a \fBdsset\-\fP or \fBkeyset\-\fP
file. Existing DS records are removed.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-K directory\fP
.B \-K directory
This option specifies the directory to search for DNSSEC keys. If not
specified, it defaults to the current directory.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k key\fP
.B \-k key
This option tells BIND 9 to treat the specified key as a key\-signing key, ignoring any key flags. This
option may be specified multiple times.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-M maxttl\fP
.B \-M maxttl
This option sets the maximum TTL for the signed zone. Any TTL higher than \fBmaxttl\fP
in the input zone is reduced to \fBmaxttl\fP in the output. This
provides certainty as to the largest possible TTL in the signed zone,
@ -93,10 +111,12 @@ which is useful to know when rolling keys. The maxttl is the longest
possible time before signatures that have been retrieved by resolvers
expire from resolver caches. Zones that are signed with this
option should be configured to use a matching \fBmax\-zone\-ttl\fP in
\fBnamed.conf\fP\&. (Note: This option is incompatible with \fB\-D\fP,
\fBnamed.conf\fP\&. (Note: This option is incompatible with \fI\%\-D\fP,
because it modifies non\-DNSSEC data in the output zone.)
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s start\-time\fP
.B \-s start\-time
This option specifies the date and time when the generated RRSIG records become
valid. This can be either an absolute or relative time. An absolute
start time is indicated by a number in YYYYMMDDHHMMSS notation;
@ -104,8 +124,10 @@ start time is indicated by a number in YYYYMMDDHHMMSS notation;
start time is indicated by \fB+N\fP, which is N seconds from the current
time. If no \fBstart\-time\fP is specified, the current time minus 1
hour (to allow for clock skew) is used.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-e end\-time\fP
.B \-e end\-time
This option specifies the date and time when the generated RRSIG records expire. As
with \fBstart\-time\fP, an absolute time is indicated in YYYYMMDDHHMMSS
notation. A time relative to the start time is indicated with \fB+N\fP,
@ -113,8 +135,10 @@ which is N seconds from the start time. A time relative to the
current time is indicated with \fBnow+N\fP\&. If no \fBend\-time\fP is
specified, 30 days from the start time is the default.
\fBend\-time\fP must be later than \fBstart\-time\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-X extended end\-time\fP
.B \-X extended end\-time
This option specifies the date and time when the generated RRSIG records for the
DNSKEY RRset expire. This is to be used in cases when the DNSKEY
signatures need to persist longer than signatures on other records;
@ -128,21 +152,29 @@ relative to the current time is indicated with \fBnow+N\fP\&. If no
\fBextended end\-time\fP is specified, the value of \fBend\-time\fP is used
as the default. (\fBend\-time\fP, in turn, defaults to 30 days from the
start time.) \fBextended end\-time\fP must be later than \fBstart\-time\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f output\-file\fP
.B \-f output\-file
This option indicates the name of the output file containing the signed zone. The default
is to append \fB\&.signed\fP to the input filename. If \fBoutput\-file\fP is
set to \fB\-\fP, then the signed zone is written to the standard
output, with a default output format of \fBfull\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints a short summary of the options and arguments to
\fBdnssec\-signzone\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints version information.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-i interval\fP
.B \-i interval
This option indicates that, when a previously signed zone is passed as input, records may be
re\-signed. The \fBinterval\fP option specifies the cycle interval as an
offset from the current time, in seconds. If a RRSIG record expires
@ -155,15 +187,19 @@ the signature end and start times. So if neither \fBend\-time\fP nor
signatures that are valid for 30 days, with a cycle interval of 7.5
days. Therefore, if any existing RRSIG records are due to expire in
less than 7.5 days, they are replaced.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-I input\-format\fP
.B \-I input\-format
This option sets the format of the input zone file. Possible formats are
\fBtext\fP (the default), and \fBraw\fP\&. This option is primarily
intended to be used for dynamic signed zones, so that the dumped zone
file in a non\-text format containing updates can be signed directly.
This option is not useful for non\-dynamic zones.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-j jitter\fP
.B \-j jitter
When signing a zone with a fixed signature lifetime, all RRSIG
records issued at the time of signing expire simultaneously. If the
zone is incrementally signed, i.e., a previously signed zone is passed
@ -177,17 +213,23 @@ servers by spreading out cache expiration, i.e., if large numbers of
RRSIGs do not expire at the same time from all caches, there is
less congestion than if all validators need to refetch at around the
same time.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-L serial\fP
.B \-L serial
When writing a signed zone to "raw" format, this option sets the "source
serial" value in the header to the specified \fBserial\fP number. (This is
expected to be used primarily for testing purposes.)
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-n ncpus\fP
.B \-n ncpus
This option specifies the number of threads to use. By default, one thread is
started for each detected CPU.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-N soa\-serial\-format\fP
.B \-N soa\-serial\-format
This option sets the SOA serial number format of the signed zone. Possible formats are
\fBkeep\fP (the default), \fBincrement\fP, \fBunixtime\fP, and
\fBdate\fP\&.
@ -211,12 +253,16 @@ YYYYMMDDNN format, unless the serial number is already greater
than or equal to that value, in which case it is simply
incremented by one.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-o origin\fP
.B \-o origin
This option sets the zone origin. If not specified, the name of the zone file is
assumed to be the origin.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-O output\-format\fP
.B \-O output\-format
This option sets the format of the output file containing the signed
zone. Possible formats are \fBtext\fP (the default), which is the standard
textual representation of the zone; \fBfull\fP, which is text output in a
@ -225,44 +271,54 @@ format suitable for processing by external scripts; and \fBraw\fP and
\fBnamed\fP\&. \fBraw=N\fP specifies the format version of the raw zone file:
if N is 0, the raw file can be read by any version of \fBnamed\fP; if N is
1, the file can be read by release 9.9.0 or higher. The default is 1.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-P\fP
.B \-P
This option disables post\-sign verification tests.
.sp
The post\-sign verification tests ensure that for each algorithm in
use there is at least one non\-revoked self\-signed KSK key, that all
revoked KSK keys are self\-signed, and that all records in the zone
are signed by the algorithm. This option skips these tests.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-Q\fP
.B \-Q
This option removes signatures from keys that are no longer active.
.sp
Normally, when a previously signed zone is passed as input to the
signer, and a DNSKEY record has been removed and replaced with a new
one, signatures from the old key that are still within their validity
period are retained. This allows the zone to continue to validate
with cached copies of the old DNSKEY RRset. The \fB\-Q\fP option forces
with cached copies of the old DNSKEY RRset. The \fI\%\-Q\fP option forces
\fBdnssec\-signzone\fP to remove signatures from keys that are no longer
active. This enables ZSK rollover using the procedure described in
\fI\%RFC 4641#4.2.1.1\fP ("Pre\-Publish Key Rollover").
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-q\fP
.B \-q
This option enables quiet mode, which suppresses unnecessary output. Without this option, when
\fBdnssec\-signzone\fP is run it prints three pieces of information to standard output: the number of
keys in use; the algorithms used to verify the zone was signed correctly and
other status information; and the filename containing the signed
zone. With the option that output is suppressed, leaving only the filename.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-R\fP
.B \-R
This option removes signatures from keys that are no longer published.
.sp
This option is similar to \fB\-Q\fP, except it forces
This option is similar to \fI\%\-Q\fP, except it forces
\fBdnssec\-signzone\fP to remove signatures from keys that are no longer
published. This enables ZSK rollover using the procedure described in
\fI\%RFC 4641#4.2.1.2\fP ("Double Signature Zone Signing Key
Rollover").
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-S\fP
.B \-S
This option enables smart signing, which instructs \fBdnssec\-signzone\fP to search the key
repository for keys that match the zone being signed, and to include
them in the zone if appropriate.
@ -297,64 +353,89 @@ If the key\(aqs sync deletion date is set and is in the past,
synchronization records (type CDS and/or CDNSKEY) are removed.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-T ttl\fP
.B \-T ttl
This option specifies a TTL to be used for new DNSKEY records imported into the
zone from the key repository. If not specified, the default is the
TTL value from the zone\(aqs SOA record. This option is ignored when
signing without \fB\-S\fP, since DNSKEY records are not imported from
signing without \fI\%\-S\fP, since DNSKEY records are not imported from
the key repository in that case. It is also ignored if there are any
pre\-existing DNSKEY records at the zone apex, in which case new
records\(aq TTL values are set to match them, or if any of the
imported DNSKEY records had a default TTL value. In the event of a
conflict between TTL values in imported keys, the shortest one is
used.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t\fP
.B \-t
This option prints statistics at completion.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-u\fP
.B \-u
This option updates the NSEC/NSEC3 chain when re\-signing a previously signed zone.
With this option, a zone signed with NSEC can be switched to NSEC3,
or a zone signed with NSEC3 can be switched to NSEC or to NSEC3 with
different parameters. Without this option, \fBdnssec\-signzone\fP
retains the existing chain when re\-signing.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v level\fP
.B \-v level
This option sets the debugging level.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-x\fP
.B \-x
This option indicates that BIND 9 should only sign the DNSKEY, CDNSKEY, and CDS RRsets with key\-signing keys,
and should omit signatures from zone\-signing keys. (This is similar to the
\fBdnssec\-dnskey\-kskonly yes;\fP zone option in \fBnamed\fP\&.)
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-z\fP
.B \-z
This option indicates that BIND 9 should ignore the KSK flag on keys when determining what to sign. This causes
KSK\-flagged keys to sign all records, not just the DNSKEY RRset.
(This is similar to the \fBupdate\-check\-ksk no;\fP zone option in
\fBnamed\fP\&.)
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-3 salt\fP
.B \-3 salt
This option generates an NSEC3 chain with the given hex\-encoded salt. A dash
(\-) can be used to indicate that no salt is to be used when
generating the NSEC3 chain.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-H iterations\fP
.B \-H iterations
This option indicates that, when generating an NSEC3 chain, BIND 9 should use this many iterations. The default
is 10.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-A\fP
.B \-A
This option indicates that, when generating an NSEC3 chain, BIND 9 should set the OPTOUT flag on all NSEC3
records and should not generate NSEC3 records for insecure delegations.
.sp
Using this option twice (i.e., \fB\-AA\fP) turns the OPTOUT flag off for
all records. This is useful when using the \fB\-u\fP option to modify an
.UNINDENT
.INDENT 0.0
.TP
.B \-AA
This option turns the OPTOUT flag off for
all records. This is useful when using the \fI\%\-u\fP option to modify an
NSEC3 chain which previously had OPTOUT set.
.UNINDENT
.INDENT 0.0
.TP
.B \fBzonefile\fP
.B zonefile
This option sets the file containing the zone to be signed.
.UNINDENT
.INDENT 0.0
.TP
.B \fBkey\fP
.B key
This option specifies which keys should be used to sign the zone. If no keys are
specified, the zone is examined for DNSKEY records at the
zone apex. If these records are found and there are matching private keys in
@ -364,10 +445,10 @@ the current directory, they are used for signing.
.sp
The following command signs the \fBexample.com\fP zone with the
ECDSAP256SHA256 key generated by \fBdnssec\-keygen\fP
(Kexample.com.+013+17247). Because the \fB\-S\fP option is not being used,
(Kexample.com.+013+17247). Because the \fI\%\-S\fP option is not being used,
the zone\(aqs keys must be in the master file (\fBdb.example.com\fP). This
invocation looks for \fBdsset\fP files in the current directory, so that
DS records can be imported from them (\fB\-g\fP).
DS records can be imported from them (\fI\%\-g\fP).
.INDENT 0.0
.INDENT 3.5
.sp

42
doc/man/dnssec-verify.1in
View file

@ -41,48 +41,64 @@ NSEC/NSEC3 chains are complete.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option specifies the DNS class of the zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-E engine\fP
.B \-E engine
This option specifies the cryptographic hardware to use, when applicable.
.sp
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
engine identifier that drives the cryptographic accelerator or
hardware service module (usually \fBpkcs11\fP).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-I input\-format\fP
.B \-I input\-format
This option sets the format of the input zone file. Possible formats are \fBtext\fP
(the default) and \fBraw\fP\&. This option is primarily intended to be used
for dynamic signed zones, so that the dumped zone file in a non\-text
format containing updates can be verified independently.
This option is not useful for non\-dynamic zones.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-o origin\fP
.B \-o origin
This option indicates the zone origin. If not specified, the name of the zone file is
assumed to be the origin.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v level\fP
.B \-v level
This option sets the debugging level.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints version information.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-q\fP
.B \-q
This option sets quiet mode, which suppresses output. Without this option, when \fBdnssec\-verify\fP
is run it prints to standard output the number of keys in use, the
algorithms used to verify the zone was signed correctly, and other status
information. With this option, all non\-error output is suppressed, and only the exit
code indicates success.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-x\fP
.B \-x
This option verifies only that the DNSKEY RRset is signed with key\-signing keys.
Without this flag, it is assumed that the DNSKEY RRset is signed
by all active keys. When this flag is set, it is not an error if
the DNSKEY RRset is not signed by zone\-signing keys. This corresponds
to the \fB\-x\fP option in \fBdnssec\-signzone\fP\&.
to the \fB\-x option in dnssec\-signzone\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-z\fP
.B \-z
This option indicates that the KSK flag on the keys should be ignored when determining whether the zone is
correctly signed. Without this flag, it is assumed that there is
a non\-revoked, self\-signed DNSKEY with the KSK flag set for each
@ -94,9 +110,11 @@ be at least one non\-revoked, self\-signed DNSKEY, regardless of
the KSK flag state, and that other RRsets be signed by a
non\-revoked key for the same algorithm that includes the self\-signed
key; the same key may be used for both purposes. This corresponds to
the \fB\-z\fP option in \fBdnssec\-signzone\fP\&.
the \fB\-z option in dnssec\-signzone\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBzonefile\fP
.B zonefile
This option indicates the file containing the zone to be signed.
.UNINDENT
.SH SEE ALSO

16
doc/man/dnstap-read.1in
View file

@ -37,23 +37,29 @@ dnstap-read \- print dnstap data in human-readable form
.sp
\fBdnstap\-read\fP reads \fBdnstap\fP data from a specified file and prints
it in a human\-readable format. By default, \fBdnstap\fP data is printed in
a short summary format, but if the \fB\-y\fP option is specified, a
a short summary format, but if the \fI\%\-y\fP option is specified, a
longer and more detailed YAML format is used.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-m\fP
.B \-m
This option indicates trace memory allocations, and is used for debugging memory leaks.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p\fP
.B \-p
This option prints the text form of the DNS
message that was encapsulated in the \fBdnstap\fP frame, after printing the \fBdnstap\fP data.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-x\fP
.B \-x
This option prints a hex dump of the wire form
of the DNS message that was encapsulated in the \fBdnstap\fP frame, after printing the \fBdnstap\fP data.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-y\fP
.B \-y
This option prints \fBdnstap\fP data in a detailed YAML format.
.UNINDENT
.SH SEE ALSO

110
doc/man/host.1in
View file

@ -49,107 +49,145 @@ server or servers listed in \fB/etc/resolv.conf\fP\&.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-4\fP
This option specifies that only IPv4 should be used for query transport. See also the \fB\-6\fP option.
.B \-4
This option specifies that only IPv4 should be used for query transport. See also the \fI\%\-6\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-6\fP
This option specifies that only IPv6 should be used for query transport. See also the \fB\-4\fP option.
.B \-6
This option specifies that only IPv6 should be used for query transport. See also the \fI\%\-4\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-a\fP
The \fB\-a\fP ("all") option is normally equivalent to \fB\-v \-t ANY\fP\&. It
also affects the behavior of the \fB\-l\fP list zone option.
.B \-a
The \fI\%\-a\fP ("all") option is normally equivalent to \fI\%\-v\fP \fI\%\-t ANY\fP\&. It
also affects the behavior of the \fI\%\-l\fP list zone option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-A\fP
The \fB\-A\fP ("almost all") option is equivalent to \fB\-a\fP, except that RRSIG,
.B \-A
The \fI\%\-A\fP ("almost all") option is equivalent to \fI\%\-a\fP, except that RRSIG,
NSEC, and NSEC3 records are omitted from the output.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option specifies the query class, which can be used to lookup HS (Hesiod) or CH (Chaosnet)
class resource records. The default class is IN (Internet).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-C\fP
.B \-C
This option indicates that \fBnamed\fP should check consistency, meaning that \fBhost\fP queries the SOA records for zone
\fBname\fP from all the listed authoritative name servers for that
zone. The list of name servers is defined by the NS records that are
found for the zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-d\fP
This option prints debugging traces, and is equivalent to the \fB\-v\fP verbose option.
.B \-d
This option prints debugging traces, and is equivalent to the \fI\%\-v\fP verbose option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-l\fP
.B \-l
This option tells \fBnamed\fP to list the zone, meaning the \fBhost\fP command performs a zone transfer of zone
\fBname\fP and prints out the NS, PTR, and address records (A/AAAA).
.sp
Together, the \fB\-l \-a\fP options print all records in the zone.
Together, the \fI\%\-l\fP \fI\%\-a\fP options print all records in the zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-N ndots\fP
.B \-N ndots
This option specifies the number of dots (\fBndots\fP) that have to be in \fBname\fP for it to be
considered absolute. The default value is that defined using the
\fBndots\fP statement in \fB/etc/resolv.conf\fP, or 1 if no \fBndots\fP statement
is present. Names with fewer dots are interpreted as relative names,
and are searched for in the domains listed in the \fBsearch\fP or
\fBdomain\fP directive in \fB/etc/resolv.conf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p port\fP
.B \-p port
This option specifies the port to query on the server. The default is 53.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-r\fP
.B \-r
This option specifies a non\-recursive query; setting this option clears the RD (recursion
desired) bit in the query. This means that the name server
receiving the query does not attempt to resolve \fBname\fP\&. The \fB\-r\fP
receiving the query does not attempt to resolve \fBname\fP\&. The \fI\%\-r\fP
option enables \fBhost\fP to mimic the behavior of a name server by
making non\-recursive queries, and expecting to receive answers to
those queries that can be referrals to other name servers.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-R number\fP
.B \-R number
This option specifies the number of retries for UDP queries. If \fBnumber\fP is negative or zero,
the number of retries is silently set to 1. The default value is 1, or
the value of the \fBattempts\fP option in \fB/etc/resolv.conf\fP, if set.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s\fP
.B \-s
This option tells \fBnamed\fP \fInot\fP to send the query to the next nameserver if any server responds
with a SERVFAIL response, which is the reverse of normal stub
resolver behavior.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t type\fP
.B \-t type
This option specifies the query type. The \fBtype\fP argument can be any recognized query type:
CNAME, NS, SOA, TXT, DNSKEY, AXFR, etc.
.sp
When no query type is specified, \fBhost\fP automatically selects an
appropriate query type. By default, it looks for A, AAAA, and MX
records. If the \fB\-C\fP option is given, queries are made for SOA
records. If the \fI\%\-C\fP option is given, queries are made for SOA
records. If \fBname\fP is a dotted\-decimal IPv4 address or
colon\-delimited IPv6 address, \fBhost\fP queries for PTR records.
.sp
If a query type of IXFR is chosen, the starting serial number can be
specified by appending an equals sign (=), followed by the starting serial
number, e.g., \fB\-t IXFR=12345678\fP\&.
number, e.g., \fI\%\-t IXFR=12345678\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-T\fP; \fB\-U\fP
.B \-T, \-U
This option specifies TCP or UDP. By default, \fBhost\fP uses UDP when making queries; the
\fB\-T\fP option makes it use a TCP connection when querying the name
\fI\%\-T\fP option makes it use a TCP connection when querying the name
server. TCP is automatically selected for queries that require
it, such as zone transfer (AXFR) requests. Type \fBANY\fP queries default
to TCP, but can be forced to use UDP initially via \fB\-U\fP\&.
to TCP, but can be forced to use UDP initially via \fI\%\-U\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-m flag\fP
.B \-m flag
This option sets memory usage debugging: the flag can be \fBrecord\fP, \fBusage\fP, or
\fBtrace\fP\&. The \fB\-m\fP option can be specified more than once to set
\fBtrace\fP\&. The \fI\%\-m\fP option can be specified more than once to set
multiple flags.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v\fP
This option sets verbose output, and is equivalent to the \fB\-d\fP debug option. Verbose output
.B \-v
This option sets verbose output, and is equivalent to the \fI\%\-d\fP debug option. Verbose output
can also be enabled by setting the \fBdebug\fP option in
\fB/etc/resolv.conf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints the version number and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-w\fP
.B \-w
This option sets "wait forever": the query timeout is set to the maximum possible. See
also the \fB\-W\fP option.
also the \fI\%\-W\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-W wait\fP
.B \-W wait
This options sets the length of the wait timeout, indicating that \fBnamed\fP should wait for up to \fBwait\fP seconds for a reply. If \fBwait\fP is
less than 1, the wait interval is set to 1 second.
.sp
@ -157,7 +195,7 @@ By default, \fBhost\fP waits for 5 seconds for UDP responses and 10
seconds for TCP connections. These defaults can be overridden by the
\fBtimeout\fP option in \fB/etc/resolv.conf\fP\&.
.sp
See also the \fB\-w\fP option.
See also the \fI\%\-w\fP option.
.UNINDENT
.SH IDN SUPPORT
.sp

202
doc/man/mdig.1in
View file

@ -70,39 +70,51 @@ assign values to options like the timeout interval. They have the form
.SH ANYWHERE OPTIONS
.INDENT 0.0
.TP
.B \fB\-f\fP
.B \-f
This option makes \fBmdig\fP operate in batch mode by reading a list
of lookup requests to process from the file \fBfilename\fP\&. The file
contains a number of queries, one per line. Each entry in the file
should be organized in the same way they would be presented as queries
to \fBmdig\fP using the command\-line interface.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option causes \fBmdig\fP to print detailed help information, with the full list
of options, and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v\fP
.B \-v
This option causes \fBmdig\fP to print the version number and exit.
.UNINDENT
.SH GLOBAL OPTIONS
.INDENT 0.0
.TP
.B \fB\-4\fP
.B \-4
This option forces \fBmdig\fP to only use IPv4 query transport.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-6\fP
.B \-6
This option forces \fBmdig\fP to only use IPv6 query transport.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-b address\fP
.B \-b address
This option sets the source IP address of the query to
\fBaddress\fP\&. This must be a valid address on one of the host\(aqs network
interfaces or "0.0.0.0" or "::". An optional port may be specified by
appending "#<port>"
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-m\fP
.B \-m
This option enables memory usage debugging.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p port#\fP
.B \-p port#
This option is used when a non\-standard port number is to be
queried. \fBport#\fP is the port number that \fBmdig\fP sends its
queries to, instead of the standard DNS port number 53. This option is
@ -113,90 +125,128 @@ queries on a non\-standard port number.
The global query options are:
.INDENT 0.0
.TP
.B \fB+[no]additional\fP
.B +[no]additional
This option displays [or does not display] the additional section of a reply. The
default is to display it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]all\fP
.B +[no]all
This option sets or clears all display flags.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]answer\fP
.B +[no]answer
This option displays [or does not display] the answer section of a reply. The default
is to display it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]authority\fP
.B +[no]authority
This option displays [or does not display] the authority section of a reply. The
default is to display it.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]besteffort\fP
.B +[no]besteffort
This option attempts to display [or does not display] the contents of messages which are malformed. The
default is to not display malformed answers.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+burst\fP
.B +burst
This option delays queries until the start of the next second.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]cl\fP
.B +[no]cl
This option displays [or does not display] the CLASS when printing the record.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]comments\fP
.B +[no]comments
This option toggles the display of comment lines in the output. The default is to
print comments.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]continue\fP
.B +[no]continue
This option toggles continuation on errors (e.g. timeouts).
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]crypto\fP
.B +[no]crypto
This option toggles the display of cryptographic fields in DNSSEC records. The
contents of these fields are unnecessary to debug most DNSSEC
validation failures and removing them makes it easier to see the
common failures. The default is to display the fields. When omitted,
they are replaced by the string "[omitted]"; in the DNSKEY case, the
key ID is displayed as the replacement, e.g., \fB[ key id = value ]\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+dscp[=value]\fP
.B +dscp[=value]
This option sets the DSCP code point to be used when sending the query. Valid DSCP
code points are in the range [0...63]. By default no code point is
explicitly set.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]multiline\fP
.B +[no]multiline
This option toggles printing of records, like the SOA records, in a verbose multi\-line format
with human\-readable comments. The default is to print each record on
a single line, to facilitate machine parsing of the \fBmdig\fP output.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]question\fP
.B +[no]question
This option prints [or does not print] the question section of a query when an answer
is returned. The default is to print the question section as a
comment.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]rrcomments\fP
.B +[no]rrcomments
This option toggles the display of per\-record comments in the output (for example,
human\-readable key information about DNSKEY records). The default is
not to print record comments unless multiline mode is active.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]short\fP
.B +[no]short
This option provides [or does not provide] a terse answer. The default is to print the answer in a
verbose form.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+split=W\fP
.B +split=W
This option splits long hex\- or base64\-formatted fields in resource records into
chunks of \fBW\fP characters (where \fBW\fP is rounded up to the nearest
multiple of 4). \fB+nosplit\fP or \fB+split=0\fP causes fields not to be
split. The default is 56 characters, or 44 characters when
multiline mode is active.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]tcp\fP
.B +[no]tcp
This option uses [or does not use] TCP when querying name servers. The default behavior
is to use UDP.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ttlid\fP
.B +[no]ttlid
This option displays [or does not display] the TTL when printing the record.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ttlunits\fP
.B +[no]ttlunits
This option displays [or does not display] the TTL in friendly human\-readable time
units of "s", "m", "h", "d", and "w", representing seconds, minutes,
hours, days, and weeks. This implies +ttlid.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]vc\fP
.B +[no]vc
This option uses [or does not use] TCP when querying name servers. This alternate
syntax to \fB+[no]tcp\fP is provided for backwards compatibility. The
\fBvc\fP stands for "virtual circuit".
@ -204,18 +254,22 @@ syntax to \fB+[no]tcp\fP is provided for backwards compatibility. The
.SH LOCAL OPTIONS
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option sets the query class to \fBclass\fP\&. It can be any valid
query class which is supported in BIND 9. The default query class is
"IN".
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t type\fP
.B \-t type
This option sets the query type to \fBtype\fP\&. It can be any valid
query type which is supported in BIND 9. The default query type is "A",
unless the \fB\-x\fP option is supplied to indicate a reverse lookup with
unless the \fI\%\-x\fP option is supplied to indicate a reverse lookup with
the "PTR" query type.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-x addr\fP
.B \-x addr
Reverse lookups \- mapping addresses to names \- are simplified by
this option. \fBaddr\fP is an IPv4 address in dotted\-decimal
notation, or a colon\-delimited IPv6 address. \fBmdig\fP automatically
@ -228,13 +282,17 @@ domain.
The local query options are:
.INDENT 0.0
.TP
.B \fB+[no]aaflag\fP
.B +[no]aaflag
This is a synonym for \fB+[no]aaonly\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]aaonly\fP
.B +[no]aaonly
This sets the \fBaa\fP flag in the query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]adflag\fP
.B +[no]adflag
This sets [or does not set] the AD (authentic data) bit in the query. This
requests the server to return whether all of the answer and authority
sections have all been validated as secure, according to the security
@ -242,91 +300,129 @@ policy of the server. AD=1 indicates that all records have been
validated as secure and the answer is not from a OPT\-OUT range. AD=0
indicates that some part of the answer was insecure or not validated.
This bit is set by default.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+bufsize=B\fP
.B +bufsize=B
This sets the UDP message buffer size advertised using EDNS0 to \fBB\fP
bytes. The maximum and minimum sizes of this buffer are 65535 and 0
respectively. Values outside this range are rounded up or down
appropriately. Values other than zero cause a EDNS query to be
sent.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]cdflag\fP
.B +[no]cdflag
This sets [or does not set] the CD (checking disabled) bit in the query. This
requests the server to not perform DNSSEC validation of responses.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]cookie=####\fP
.B +[no]cookie=####
This sends [or does not send] a COOKIE EDNS option, with an optional value. Replaying a COOKIE
from a previous response allows the server to identify a previous
client. The default is \fB+nocookie\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]dnssec\fP
.B +[no]dnssec
This requests that DNSSEC records be sent by setting the DNSSEC OK (DO) bit in
the OPT record in the additional section of the query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]edns[=#]\fP
.B +[no]edns[=#]
This specifies [or does not specify] the EDNS version to query with. Valid values are 0 to 255.
Setting the EDNS version causes an EDNS query to be sent.
\fB+noedns\fP clears the remembered EDNS version. EDNS is set to 0 by
default.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ednsflags[=#]\fP
.B +[no]ednsflags[=#]
This sets the must\-be\-zero EDNS flag bits (Z bits) to the specified value.
Decimal, hex, and octal encodings are accepted. Setting a named flag
(e.g. DO) is silently ignored. By default, no Z bits are set.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]ednsopt[=code[:value]]\fP
.B +[no]ednsopt[=code[:value]]
This specifies [or does not specify] an EDNS option with code point \fBcode\fP and an optional payload
of \fBvalue\fP as a hexadecimal string. \fB+noednsopt\fP clears the EDNS
options to be sent.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]expire\fP
.B +[no]expire
This toggles sending of an EDNS Expire option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]nsid\fP
.B +[no]nsid
This toggles inclusion of an EDNS name server ID request when sending a query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]recurse\fP
.B +[no]recurse
This toggles the setting of the RD (recursion desired) bit in the query.
This bit is set by default, which means \fBmdig\fP normally sends
recursive queries.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+retry=T\fP
.B +retry=T
This sets the number of times to retry UDP queries to server to \fBT\fP
instead of the default, 2. Unlike \fB+tries\fP, this does not include
the initial query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]subnet=addr[/prefix\-length]\fP
.B +[no]subnet=addr[/prefix\-length]
This sends [or does not send] an EDNS Client Subnet option with the specified IP
address or network prefix.
.UNINDENT
.INDENT 0.0
.TP
.B \fBmdig +subnet=0.0.0.0/0\fP, or simply \fBmdig +subnet=0\fP
This sends an EDNS client\-subnet option with an empty address and a source
prefix\-length of zero, which signals a resolver that the client\(aqs
address information must \fInot\fP be used when resolving this query.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+timeout=T\fP
.B +timeout=T
This sets the timeout for a query to \fBT\fP seconds. The default timeout is
5 seconds for UDP transport and 10 for TCP. An attempt to set \fBT\fP
to less than 1 results in a query timeout of 1 second being
applied.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+tries=T\fP
.B +tries=T
This sets the number of times to try UDP queries to server to \fBT\fP
instead of the default, 3. If \fBT\fP is less than or equal to zero,
the number of tries is silently rounded up to 1.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+udptimeout=T\fP
.B +udptimeout=T
This sets the timeout between UDP query retries to \fBT\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]unknownformat\fP
.B +[no]unknownformat
This prints [or does not print] all RDATA in unknown RR\-type presentation format (see \fI\%RFC 3597\fP).
The default is to print RDATA for known types in the type\(aqs
presentation format.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]yaml\fP
.B +[no]yaml
This toggles printing of the responses in a detailed YAML format.
.UNINDENT
.INDENT 0.0
.TP
.B \fB+[no]zflag\fP
.B +[no]zflag
This sets [or does not set] the last unassigned DNS header flag in a DNS query.
This flag is off by default.
.UNINDENT

46
doc/man/named-checkconf.1in
View file

@ -48,48 +48,68 @@ However, \fBnamed\-checkconf\fP can be run on these files explicitly.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints the usage summary and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-j\fP
.B \-j
When loading a zonefile, this option instructs \fBnamed\fP to read the journal if it exists.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-l\fP
.B \-l
This option lists all the configured zones. Each line of output contains the zone
name, class (e.g. IN), view, and type (e.g. primary or secondary).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c\fP
.B \-c
This option specifies that only the "core" configuration should be checked. This suppresses the loading of
plugin modules, and causes all parameters to \fBplugin\fP statements to
be ignored.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-i\fP
.B \-i
This option ignores warnings on deprecated options.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p\fP
.B \-p
This option prints out the \fBnamed.conf\fP and included files in canonical form if
no errors were detected. See also the \fB\-x\fP option.
no errors were detected. See also the \fI\%\-x\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t directory\fP
.B \-t directory
This option instructs \fBnamed\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the
configuration file are processed as if run by a similarly chrooted
\fBnamed\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v\fP
.B \-v
This option prints the version of the \fBnamed\-checkconf\fP program and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-x\fP
.B \-x
When printing the configuration files in canonical form, this option obscures
shared secrets by replacing them with strings of question marks
(\fB?\fP). This allows the contents of \fBnamed.conf\fP and related files
to be shared \- for example, when submitting bug reports \-
without compromising private data. This option cannot be used without
\fB\-p\fP\&.
\fI\%\-p\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-z\fP
.B \-z
This option performs a test load of all zones of type \fBprimary\fP found in \fBnamed.conf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBfilename\fP
.B filename
This indicates the name of the configuration file to be checked. If not specified,
it defaults to \fB@sysconfdir@/named.conf\fP\&.
.UNINDENT

112
doc/man/named-checkzone.1in
View file

@ -42,32 +42,46 @@ configuring them into a name server.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-d\fP
.B \-d
This option enables debugging.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints the usage summary and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-q\fP
.B \-q
This option sets quiet mode, which only sets an exit code to indicate
successful or failed completion.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v\fP
.B \-v
This option prints the version of the \fBnamed\-checkzone\fP program and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-j\fP
.B \-j
When loading a zone file, this option tells \fBnamed\fP to read the journal if it exists. The journal
file name is assumed to be the zone file name with the
string \fB\&.jnl\fP appended.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-J filename\fP
.B \-J filename
When loading the zone file, this option tells \fBnamed\fP to read the journal from the given file, if
it exists. This implies \fB\-j\fP\&.
it exists. This implies \fI\%\-j\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option specifies the class of the zone. If not specified, \fBIN\fP is assumed.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-i mode\fP
.B \-i mode
This option performs post\-load zone integrity checks. Possible modes are
\fBfull\fP (the default), \fBfull\-sibling\fP, \fBlocal\fP,
\fBlocal\-sibling\fP, and \fBnone\fP\&.
@ -92,12 +106,16 @@ checks, but are otherwise the same as \fBfull\fP and \fBlocal\fP,
respectively.
.sp
Mode \fBnone\fP disables the checks.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f format\fP
.B \-f format
This option specifies the format of the zone file. Possible formats are
\fBtext\fP (the default), and \fBraw\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-F format\fP
.B \-F format
This option specifies the format of the output file specified. For
\fBnamed\-checkzone\fP, this does not have any effect unless it dumps
the zone contents.
@ -108,44 +126,62 @@ store the zone in a binary format for rapid loading by \fBnamed\fP\&.
\fBraw=N\fP specifies the format version of the raw zone file: if \fBN\fP is
0, the raw file can be read by any version of \fBnamed\fP; if N is 1, the
file can only be read by release 9.9.0 or higher. The default is 1.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k mode\fP
.B \-k mode
This option performs \fBcheck\-names\fP checks with the specified failure mode.
Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-l ttl\fP
.B \-l ttl
This option sets a maximum permissible TTL for the input file. Any record with a
TTL higher than this value causes the zone to be rejected. This
is similar to using the \fBmax\-zone\-ttl\fP option in \fBnamed.conf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-L serial\fP
.B \-L serial
When compiling a zone to \fBraw\fP format, this option sets the "source
serial" value in the header to the specified serial number. This is
expected to be used primarily for testing purposes.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-m mode\fP
.B \-m mode
This option specifies whether MX records should be checked to see if they are
addresses. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and
\fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-M mode\fP
.B \-M mode
This option checks whether a MX record refers to a CNAME. Possible modes are
\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-n mode\fP
.B \-n mode
This option specifies whether NS records should be checked to see if they are
addresses. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-o filename\fP
.B \-o filename
This option writes the zone output to \fBfilename\fP\&. If \fBfilename\fP is \fB\-\fP, then
the zone output is written to standard output.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-r mode\fP
.B \-r mode
This option checks for records that are treated as different by DNSSEC but are
semantically equal in plain DNS. Possible modes are \fBfail\fP,
\fBwarn\fP (the default), and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s style\fP
.B \-s style
This option specifies the style of the dumped zone file. Possible styles are
\fBfull\fP (the default) and \fBrelative\fP\&. The \fBfull\fP format is most
suitable for processing automatically by a separate script.
@ -153,39 +189,55 @@ The relative format is more human\-readable and is thus
suitable for editing by hand. This does not have any effect unless it dumps
the zone contents. It also does not have any meaning if the output format
is not text.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-S mode\fP
.B \-S mode
This option checks whether an SRV record refers to a CNAME. Possible modes are
\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t directory\fP
.B \-t directory
This option tells \fBnamed\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the
configuration file are processed as if run by a similarly chrooted
\fBnamed\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-T mode\fP
.B \-T mode
This option checks whether Sender Policy Framework (SPF) records exist and issues a
warning if an SPF\-formatted TXT record is not also present. Possible
modes are \fBwarn\fP (the default) and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-w directory\fP
.B \-w directory
This option instructs \fBnamed\fP to chdir to \fBdirectory\fP, so that relative filenames in master file
\fB$INCLUDE\fP directives work. This is similar to the directory clause in
\fBnamed.conf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D\fP
.B \-D
This option dumps the zone file in canonical format.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-W mode\fP
.B \-W mode
This option specifies whether to check for non\-terminal wildcards. Non\-terminal
wildcards are almost always the result of a failure to understand the
wildcard matching algorithm (\fI\%RFC 4592\fP). Possible modes are \fBwarn\fP
(the default) and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBzonename\fP
.B zonename
This indicates the domain name of the zone being checked.
.UNINDENT
.INDENT 0.0
.TP
.B \fBfilename\fP
.B filename
This is the name of the zone file.
.UNINDENT
.SH RETURN VALUES
@ -194,8 +246,8 @@ This is the name of the zone file.
and 0 otherwise.
.SH SEE ALSO
.sp
\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-compilezone(8)\fP,
\fI\%RFC 1035\fP, BIND 9 Administrator Reference Manual.
\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-compilezone(8)\fP, \fI\%RFC 1035\fP, BIND 9 Administrator Reference
Manual.
.SH AUTHOR
Internet Systems Consortium
.SH COPYRIGHT

112
doc/man/named-compilezone.1in
View file

@ -44,32 +44,46 @@ strict as those specified in the \fBnamed\fP configuration file.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-d\fP
.B \-d
This option enables debugging.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints the usage summary and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-q\fP
.B \-q
This option sets quiet mode, which only sets an exit code to indicate
successful or failed completion.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v\fP
.B \-v
This option prints the version of the \fBnamed\-checkzone\fP program and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-j\fP
.B \-j
When loading a zone file, this option tells \fBnamed\fP to read the journal if it exists. The journal
file name is assumed to be the zone file name with the
string \fB\&.jnl\fP appended.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-J filename\fP
.B \-J filename
When loading the zone file, this option tells \fBnamed\fP to read the journal from the given file, if
it exists. This implies \fB\-j\fP\&.
it exists. This implies \fI\%\-j\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c class\fP
.B \-c class
This option specifies the class of the zone. If not specified, \fBIN\fP is assumed.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-i mode\fP
.B \-i mode
This option performs post\-load zone integrity checks. Possible modes are
\fBfull\fP (the default), \fBfull\-sibling\fP, \fBlocal\fP,
\fBlocal\-sibling\fP, and \fBnone\fP\&.
@ -94,12 +108,16 @@ checks, but are otherwise the same as \fBfull\fP and \fBlocal\fP,
respectively.
.sp
Mode \fBnone\fP disables the checks.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f format\fP
.B \-f format
This option specifies the format of the zone file. Possible formats are
\fBtext\fP (the default), and \fBraw\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-F format\fP
.B \-F format
This option specifies the format of the output file specified. For
\fBnamed\-checkzone\fP, this does not have any effect unless it dumps
the zone contents.
@ -110,84 +128,118 @@ store the zone in a binary format for rapid loading by \fBnamed\fP\&.
\fBraw=N\fP specifies the format version of the raw zone file: if \fBN\fP is
0, the raw file can be read by any version of \fBnamed\fP; if N is 1, the
file can only be read by release 9.9.0 or higher. The default is 1.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k mode\fP
.B \-k mode
This option performs \fBcheck\-names\fP checks with the specified failure mode.
Possible modes are \fBfail\fP (the default), \fBwarn\fP, and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-l ttl\fP
.B \-l ttl
This option sets a maximum permissible TTL for the input file. Any record with a
TTL higher than this value causes the zone to be rejected. This
is similar to using the \fBmax\-zone\-ttl\fP option in \fBnamed.conf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-L serial\fP
.B \-L serial
When compiling a zone to \fBraw\fP format, this option sets the "source
serial" value in the header to the specified serial number. This is
expected to be used primarily for testing purposes.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-m mode\fP
.B \-m mode
This option specifies whether MX records should be checked to see if they are
addresses. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and
\fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-M mode\fP
.B \-M mode
This option checks whether a MX record refers to a CNAME. Possible modes are
\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-n mode\fP
.B \-n mode
This option specifies whether NS records should be checked to see if they are
addresses. Possible modes are \fBfail\fP (the default), \fBwarn\fP, and
\fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-o filename\fP
.B \-o filename
This option writes the zone output to \fBfilename\fP\&. If \fBfilename\fP is \fB\-\fP, then
the zone output is written to standard output. This is mandatory for \fBnamed\-compilezone\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-r mode\fP
.B \-r mode
This option checks for records that are treated as different by DNSSEC but are
semantically equal in plain DNS. Possible modes are \fBfail\fP,
\fBwarn\fP (the default), and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s style\fP
.B \-s style
This option specifies the style of the dumped zone file. Possible styles are
\fBfull\fP (the default) and \fBrelative\fP\&. The \fBfull\fP format is most
suitable for processing automatically by a separate script.
The relative format is more human\-readable and is thus
suitable for editing by hand.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-S mode\fP
.B \-S mode
This option checks whether an SRV record refers to a CNAME. Possible modes are
\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t directory\fP
.B \-t directory
This option tells \fBnamed\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the
configuration file are processed as if run by a similarly chrooted
\fBnamed\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-T mode\fP
.B \-T mode
This option checks whether Sender Policy Framework (SPF) records exist and issues a
warning if an SPF\-formatted TXT record is not also present. Possible
modes are \fBwarn\fP (the default) and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-w directory\fP
.B \-w directory
This option instructs \fBnamed\fP to chdir to \fBdirectory\fP, so that relative filenames in master file
\fB$INCLUDE\fP directives work. This is similar to the directory clause in
\fBnamed.conf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D\fP
.B \-D
This option dumps the zone file in canonical format. This is always enabled for
\fBnamed\-compilezone\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-W mode\fP
.B \-W mode
This option specifies whether to check for non\-terminal wildcards. Non\-terminal
wildcards are almost always the result of a failure to understand the
wildcard matching algorithm (\fI\%RFC 4592\fP). Possible modes are \fBwarn\fP
(the default) and \fBignore\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBzonename\fP
.B zonename
This indicates the domain name of the zone being checked.
.UNINDENT
.INDENT 0.0
.TP
.B \fBfilename\fP
.B filename
This is the name of the zone file.
.UNINDENT
.SH RETURN VALUES
@ -196,8 +248,8 @@ This is the name of the zone file.
and 0 otherwise.
.SH SEE ALSO
.sp
\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-checkzone(8)\fP,
\fI\%RFC 1035\fP, BIND 9 Administrator Reference Manual.
\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-checkzone(8)\fP, \fI:rfc:\(ga1035\fP,
BIND 9 Administrator Reference Manual.
.SH AUTHOR
Internet Systems Consortium
.SH COPYRIGHT

2
doc/man/named-nzd2nzf.1in
View file

@ -43,7 +43,7 @@ version of BIND to an older version.
.SH ARGUMENTS
.INDENT 0.0
.TP
.B \fBfilename\fP
.B filename
This is the name of the \fB\&.nzd\fP file whose contents should be printed.
.UNINDENT
.SH SEE ALSO

18
doc/man/named-rrchecker.1in
View file

@ -40,22 +40,30 @@ input and checks whether it is syntactically correct.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints out the help menu.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-o origin\fP
.B \-o origin
This option specifies the origin to be used when interpreting
the record.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p\fP
.B \-p
This option prints out the resulting record in canonical form. If there
is no canonical form defined, the record is printed in unknown
record format.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-u\fP
.B \-u
This option prints out the resulting record in unknown record form.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-C\fP, \fB\-T\fP, and \fB\-P\fP
.B \-C, \-T, \-P
These options print out the known class, standard type,
and private type mnemonics, respectively.
.UNINDENT

90
doc/man/named.8in
View file

@ -45,47 +45,65 @@ listens for queries.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-4\fP
This option tells \fBnamed\fP to use only IPv4, even if the host machine is capable of IPv6. \fB\-4\fP and
\fB\-6\fP are mutually exclusive.
.B \-4
This option tells \fBnamed\fP to use only IPv4, even if the host machine is capable of IPv6. \fI\%\-4\fP and
\fI\%\-6\fP are mutually exclusive.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-6\fP
This option tells \fBnamed\fP to use only IPv6, even if the host machine is capable of IPv4. \fB\-4\fP and
\fB\-6\fP are mutually exclusive.
.B \-6
This option tells \fBnamed\fP to use only IPv6, even if the host machine is capable of IPv4. \fI\%\-4\fP and
\fI\%\-6\fP are mutually exclusive.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c config\-file\fP
.B \-c config\-file
This option tells \fBnamed\fP to use \fBconfig\-file\fP as its configuration file instead of the default,
\fB@sysconfdir@/named.conf\fP\&. To ensure that the configuration file
can be reloaded after the server has changed its working directory
due to to a possible \fBdirectory\fP option in the configuration file,
\fBconfig\-file\fP should be an absolute pathname.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-d debug\-level\fP
.B \-d debug\-level
This option sets the daemon\(aqs debug level to \fBdebug\-level\fP\&. Debugging traces from
\fBnamed\fP become more verbose as the debug level increases.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D string\fP
.B \-D string
This option specifies a string that is used to identify a instance of \fBnamed\fP
in a process listing. The contents of \fBstring\fP are not examined.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-E engine\-name\fP
.B \-E engine\-name
When applicable, this option specifies the hardware to use for cryptographic
operations, such as a secure key store used for signing.
.sp
When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
engine identifier that drives the cryptographic accelerator or
hardware service module (usually \fBpkcs11\fP).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f\fP
.B \-f
This option runs the server in the foreground (i.e., do not daemonize).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-g\fP
.B \-g
This option runs the server in the foreground and forces all logging to \fBstderr\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-L logfile\fP
.B \-L logfile
This option sets the log to the file \fBlogfile\fP by default, instead of the system log.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-M option\fP
.B \-M option
This option sets the default memory context options. If set to \fBexternal\fP,
the internal memory manager is bypassed in favor of
system\-provided memory allocation functions. If set to \fBfill\fP, blocks
@ -93,19 +111,25 @@ of memory are filled with tag values when allocated or freed, to
assist debugging of memory problems. \fBnofill\fP disables this behavior,
and is the default unless \fBnamed\fP has been compiled with developer
options.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-m flag\fP
.B \-m flag
This option turns on memory usage debugging flags. Possible flags are \fBusage\fP,
\fBtrace\fP, \fBrecord\fP, \fBsize\fP, and \fBmctx\fP\&. These correspond to the
\fBISC_MEM_DEBUGXXXX\fP flags described in \fB<isc/mem.h>\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-n #cpus\fP
.B \-n #cpus
This option creates \fB#cpus\fP worker threads to take advantage of multiple CPUs. If
not specified, \fBnamed\fP tries to determine the number of CPUs
present and creates one thread per CPU. If it is unable to determine
the number of CPUs, a single worker thread is created.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p value\fP
.B \-p value
This option specifies the port(s) on which the server will listen
for queries. If \fBvalue\fP is of the form \fB<portnum>\fP or
\fBdns=<portnum>\fP, the server will listen for DNS queries on
@ -116,8 +140,10 @@ If \fBvalue\fP is of the form \fBhttps=<portnum>\fP, the server will
listen for HTTPS queries on \fBportnum\fP; the default is 443.
If \fBvalue\fP is of the form \fBhttp=<portnum>\fP, the server will
listen for HTTP queries on \fBportnum\fP; the default is 80.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s\fP
.B \-s
This option writes memory usage statistics to \fBstdout\fP on exit.
.UNINDENT
.sp
@ -130,7 +156,7 @@ removed or changed in a future release.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-S #max\-socks\fP
.B \-S #max\-socks
This option is deprecated and no longer has any function.
.UNINDENT
.sp
@ -150,7 +176,7 @@ for its internal use.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t directory\fP
.B \-t directory
This option tells \fBnamed\fP to chroot to \fBdirectory\fP after processing the command\-line arguments, but
before reading the configuration file.
.UNINDENT
@ -158,7 +184,7 @@ before reading the configuration file.
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This option should be used in conjunction with the \fB\-u\fP option,
This option should be used in conjunction with the \fI\%\-u\fP option,
as chrooting a process running as root doesn\(aqt enhance security on
most systems; the way \fBchroot\fP is defined allows a process
with root privileges to escape a chroot jail.
@ -166,17 +192,19 @@ with root privileges to escape a chroot jail.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-U #listeners\fP
.B \-U #listeners
This option tells \fBnamed\fP the number of \fB#listeners\fP worker threads to listen on, for incoming UDP packets on
each address. If not specified, \fBnamed\fP calculates a default
value based on the number of detected CPUs: 1 for 1 CPU, and the
number of detected CPUs minus one for machines with more than 1 CPU.
This cannot be increased to a value higher than the number of CPUs.
If \fB\-n\fP has been set to a higher value than the number of detected
CPUs, then \fB\-U\fP may be increased as high as that value, but no
If \fI\%\-n\fP has been set to a higher value than the number of detected
CPUs, then \fI\%\-U\fP may be increased as high as that value, but no
higher.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-u user\fP
.B \-u user
This option sets the setuid to \fBuser\fP after completing privileged operations, such as
creating sockets that listen on privileged ports.
.UNINDENT
@ -187,7 +215,7 @@ creating sockets that listen on privileged ports.
On Linux, \fBnamed\fP uses the kernel\(aqs capability mechanism to drop
all root privileges except the ability to \fBbind\fP to a
privileged port and set process resource limits. Unfortunately,
this means that the \fB\-u\fP option only works when \fBnamed\fP is run
this means that the \fI\%\-u\fP option only works when \fBnamed\fP is run
on kernel 2.2.18 or later, or kernel 2.3.99\-pre3 or later, since
previous kernels did not allow privileges to be retained after
\fBsetuid\fP\&.
@ -195,13 +223,17 @@ previous kernels did not allow privileges to be retained after
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v\fP
.B \-v
This option reports the version number and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option reports the version number and build options, and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-X lock\-file\fP
.B \-X lock\-file
This option acquires a lock on the specified file at runtime; this helps to
prevent duplicate \fBnamed\fP instances from running simultaneously.
Use of this option overrides the \fBlock\-file\fP option in

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

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

18
doc/man/nsec3hash.1in
View file

@ -49,22 +49,30 @@ into a command line to confirm the correctness of an NSEC3 hash.
.SH ARGUMENTS
.INDENT 0.0
.TP
.B \fBsalt\fP
.B salt
This is the salt provided to the hash algorithm.
.UNINDENT
.INDENT 0.0
.TP
.B \fBalgorithm\fP
.B algorithm
This is a number indicating the hash algorithm. Currently the only supported
hash algorithm for NSEC3 is SHA\-1, which is indicated by the number
1; consequently "1" is the only useful value for this argument.
.UNINDENT
.INDENT 0.0
.TP
.B \fBflags\fP
.B flags
This is provided for compatibility with NSEC3 record presentation format, but
is ignored since the flags do not affect the hash.
.UNINDENT
.INDENT 0.0
.TP
.B \fBiterations\fP
.B iterations
This is the number of additional times the hash should be performed.
.UNINDENT
.INDENT 0.0
.TP
.B \fBdomain\fP
.B domain
This is the domain name to be hashed.
.UNINDENT
.SH SEE ALSO

103
doc/man/nsupdate.1in
View file

@ -61,102 +61,147 @@ statements are added to \fB@sysconfdir@/named.conf\fP so that the name server
can associate the appropriate secret key and algorithm with the IP
address of the client application that is using TSIG
authentication. \fBddns\-confgen\fP can generate suitable
configuration fragments. \fBnsupdate\fP uses the \fB\-y\fP or \fB\-k\fP options
configuration fragments. \fBnsupdate\fP uses the \fI\%\-y\fP or \fI\%\-k\fP options
to provide the TSIG shared secret; these options are mutually exclusive.
.sp
SIG(0) uses public key cryptography. To use a SIG(0) key, the public key
must be stored in a KEY record in a zone served by the name server.
.sp
GSS\-TSIG uses Kerberos credentials. Standard GSS\-TSIG mode is switched
on with the \fB\-g\fP flag. A non\-standards\-compliant variant of GSS\-TSIG
used by Windows 2000 can be switched on with the \fB\-o\fP flag.
on with the \fI\%\-g\fP flag. A non\-standards\-compliant variant of GSS\-TSIG
used by Windows 2000 can be switched on with the \fI\%\-o\fP flag.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-4\fP
.B \-4
This option sets use of IPv4 only.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-6\fP
.B \-6
This option sets use of IPv6 only.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-C\fP
.B \-C
Overrides the default \fIresolv.conf\fP file. This is only intended for testing.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-d\fP
.B \-d
This option sets debug mode, which provides tracing information about the update
requests that are made and the replies received from the name server.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-D\fP
.B \-D
This option sets extra debug mode.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-i\fP
.B \-g
This option enables standard GSS\-TSIG mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-i
This option forces interactive mode, even when standard input is not a terminal.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k keyfile\fP
.B \-k keyfile
This option indicates the file containing the TSIG authentication key. Keyfiles may be in
two formats: a single file containing a \fBnamed.conf\fP\-format \fBkey\fP
statement, which may be generated automatically by \fBddns\-confgen\fP;
or a pair of files whose names are of the format
\fBK{name}.+157.+{random}.key\fP and
\fBK{name}.+157.+{random}.private\fP, which can be generated by
\fBdnssec\-keygen\fP\&. The \fB\-k\fP option can also be used to specify a SIG(0)
\fBdnssec\-keygen\fP\&. The \fI\%\-k\fP option can also be used to specify a SIG(0)
key used to authenticate Dynamic DNS update requests. In this case,
the key specified is not an HMAC\-MD5 key.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-l\fP
.B \-l
This option sets local\-host only mode, which sets the server address to localhost
(disabling the \fBserver\fP so that the server address cannot be
overridden). Connections to the local server use a TSIG key
found in \fB@runstatedir@/session.key\fP, which is automatically
generated by \fBnamed\fP if any local \fBprimary\fP zone has set
\fBupdate\-policy\fP to \fBlocal\fP\&. The location of this key file can be
overridden with the \fB\-k\fP option.
overridden with the \fI\%\-k\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-L level\fP
.B \-L level
This option sets the logging debug level. If zero, logging is disabled.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p port\fP
.B \-o
This option enables a non\-standards\-compliant variant of GSS\-TSIG
used by Windows 2000.
.UNINDENT
.INDENT 0.0
.TP
.B \-p port
This option sets the port to use for connections to a name server. The default is
53.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-P\fP
.B \-P
This option prints the list of private BIND\-specific resource record types whose
format is understood by \fBnsupdate\fP\&. See also the \fB\-T\fP option.
format is understood by \fBnsupdate\fP\&. See also the \fI\%\-T\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-r udpretries\fP
.B \-r udpretries
This option sets the number of UDP retries. The default is 3. If zero, only one update
request is made.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t timeout\fP
.B \-t timeout
This option sets the maximum time an update request can take before it is aborted. The
default is 300 seconds. If zero, the timeout is disabled.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-T\fP
.B \-T
This option prints the list of IANA standard resource record types whose format is
understood by \fBnsupdate\fP\&. \fBnsupdate\fP exits after the lists
are printed. The \fB\-T\fP option can be combined with the \fB\-P\fP
are printed. The \fI\%\-T\fP option can be combined with the \fI\%\-P\fP
option.
.sp
Other types can be entered using \fBTYPEXXXXX\fP where \fBXXXXX\fP is the
decimal value of the type with no leading zeros. The rdata, if
present, is parsed using the UNKNOWN rdata format, (<backslash>
<hash> <space> <length> <space> <hexstring>).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-u udptimeout\fP
.B \-u udptimeout
This option sets the UDP retry interval. The default is 3 seconds. If zero, the
interval is computed from the timeout interval and number of UDP
retries.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-v\fP
.B \-v
This option specifies that TCP should be used even for small update requests. By default, \fBnsupdate\fP uses
UDP to send update requests to the name server unless they are too
large to fit in a UDP request, in which case TCP is used. TCP may
be preferable when a batch of update requests is made.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option prints the version number and exits.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-y [hmac:]keyname:secret\fP
.B \-y [hmac:]keyname:secret
This option sets the literal TSIG authentication key. \fBkeyname\fP is the name of the key,
and \fBsecret\fP is the base64 encoded shared secret. \fBhmac\fP is the
name of the key algorithm; valid choices are \fBhmac\-md5\fP,
@ -164,7 +209,7 @@ name of the key algorithm; valid choices are \fBhmac\-md5\fP,
\fBhmac\-sha512\fP\&. If \fBhmac\fP is not specified, the default is
\fBhmac\-md5\fP, or if MD5 was disabled, \fBhmac\-sha256\fP\&.
.sp
NOTE: Use of the \fB\-y\fP option is discouraged because the shared
NOTE: Use of the \fI\%\-y\fP option is discouraged because the shared
secret is supplied as a command\-line argument in clear text. This may
be visible in the output from ps1 or in a history file maintained by
the user\(aqs shell.
@ -224,15 +269,15 @@ This command specifies that all updates are to be TSIG\-signed using the
\fBkeyname\fP\-\fBsecret\fP pair. If \fBhmac\fP is specified, it sets
the signing algorithm in use. The default is \fBhmac\-md5\fP; if MD5
was disabled, the default is \fBhmac\-sha256\fP\&. The \fBkey\fP command overrides any key
specified on the command line via \fB\-y\fP or \fB\-k\fP\&.
specified on the command line via \fI\%\-y\fP or \fI\%\-k\fP\&.
.TP
.B \fBgsstsig\fP
This command uses GSS\-TSIG to sign the updates. This is equivalent to specifying
\fB\-g\fP on the command line.
\fI\%\-g\fP on the command line.
.TP
.B \fBoldgsstsig\fP
This command uses the Windows 2000 version of GSS\-TSIG to sign the updates. This is
equivalent to specifying \fB\-o\fP on the command line.
equivalent to specifying \fI\%\-o\fP on the command line.
.TP
.B \fBrealm [realm_name]\fP
When using GSS\-TSIG, this command specifies the use of \fBrealm_name\fP rather than the default realm

56
doc/man/rndc-confgen.8in
View file

@ -38,13 +38,13 @@ rndc-confgen \- rndc key generation tool
\fBrndc\-confgen\fP generates configuration files for \fBrndc\fP\&. It can be
used as a convenient alternative to writing the \fBrndc.conf\fP file and
the corresponding \fBcontrols\fP and \fBkey\fP statements in \fBnamed.conf\fP
by hand. Alternatively, it can be run with the \fB\-a\fP option to set up a
by hand. Alternatively, it can be run with the \fI\%\-a\fP option to set up a
\fBrndc.key\fP file and avoid the need for a \fBrndc.conf\fP file and a
\fBcontrols\fP statement altogether.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-a\fP
.B \-a
This option sets automatic \fBrndc\fP configuration, which creates a file
\fB@sysconfdir@/rndc.key\fP that is read by both \fBrndc\fP and \fBnamed\fP on startup.
The \fBrndc.key\fP file defines a default command channel and
@ -52,52 +52,72 @@ authentication key allowing \fBrndc\fP to communicate with \fBnamed\fP on
the local host with no further configuration.
.sp
If a more elaborate configuration than that generated by
\fBrndc\-confgen \-a\fP is required, for example if rndc is to be used
remotely, run \fBrndc\-confgen\fP without the \fB\-a\fP option
\fI\%rndc\-confgen \-a\fP is required, for example if rndc is to be used
remotely, run \fBrndc\-confgen\fP without the \fI\%\-a\fP option
and set up \fBrndc.conf\fP and \fBnamed.conf\fP as directed.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-A algorithm\fP
.B \-A algorithm
This option specifies the algorithm to use for the TSIG key. Available choices
are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, and
hmac\-sha512. The default is hmac\-sha256.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-b keysize\fP
.B \-b keysize
This option specifies the size of the authentication key in bits. The size must be between
1 and 512 bits; the default is the hash size.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c keyfile\fP
This option is used with the \fB\-a\fP option to specify an alternate location for
.B \-c keyfile
This option is used with the \fI\%\-a\fP option to specify an alternate location for
\fBrndc.key\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints a short summary of the options and arguments to
\fBrndc\-confgen\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k keyname\fP
.B \-k keyname
This option specifies the key name of the \fBrndc\fP authentication key. This must be a
valid domain name. The default is \fBrndc\-key\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p port\fP
.B \-p port
This option specifies the command channel port where \fBnamed\fP listens for
connections from \fBrndc\fP\&. The default is 953.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-q\fP
.B \-q
This option prevets printing the written path in automatic configuration mode.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s address\fP
.B \-s address
This option specifies the IP address where \fBnamed\fP listens for command\-channel
connections from \fBrndc\fP\&. The default is the loopback address
127.0.0.1.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-t chrootdir\fP
This option is used with the \fB\-a\fP option to specify a directory where \fBnamed\fP
.B \-t chrootdir
This option is used with the \fI\%\-a\fP option to specify a directory where \fBnamed\fP
runs chrooted. An additional copy of the \fBrndc.key\fP is
written relative to this directory, so that it is found by the
chrooted \fBnamed\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-u user\fP
This option is used with the \fB\-a\fP option to set the owner of the generated \fBrndc.key\fP file.
If \fB\-t\fP is also specified, only the file in the chroot
.B \-u user
This option is used with the \fI\%\-a\fP option to set the owner of the generated \fBrndc.key\fP file.
If \fI\%\-t\fP is also specified, only the file in the chroot
area has its owner changed.
.UNINDENT
.SH EXAMPLES

253
doc/man/rndc.8in
View file

@ -35,8 +35,7 @@ rndc \- name server control utility
\fBrndc\fP [\fB\-b\fP source\-address] [\fB\-c\fP config\-file] [\fB\-k\fP key\-file] [\fB\-s\fP server] [\fB\-p\fP port] [\fB\-q\fP] [\fB\-r\fP] [\fB\-V\fP] [\fB\-y\fP key_id] [[\fB\-4\fP] | [\fB\-6\fP]] {command}
.SH DESCRIPTION
.sp
\fBrndc\fP controls the operation of a name server; it supersedes the
\fBndc\fP utility. If \fBrndc\fP is
\fBrndc\fP controls the operation of a name server. If \fBrndc\fP is
invoked with no command line options or arguments, it prints a short
summary of the supported commands and the available options and their
arguments.
@ -56,51 +55,71 @@ server and decide what algorithm and key it should use.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-4\fP
.B \-4
This option indicates use of IPv4 only.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-6\fP
.B \-6
This option indicates use of IPv6 only.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-b source\-address\fP
.B \-b source\-address
This option indicates \fBsource\-address\fP as the source address for the connection to the
server. Multiple instances are permitted, to allow setting of both the
IPv4 and IPv6 source addresses.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-c config\-file\fP
.B \-c config\-file
This option indicates \fBconfig\-file\fP as the configuration file instead of the default,
\fB@sysconfdir@/rndc.conf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-k key\-file\fP
.B \-k key\-file
This option indicates \fBkey\-file\fP as the key file instead of the default,
\fB@sysconfdir@/rndc.key\fP\&. The key in \fB@sysconfdir@/rndc.key\fP is used to
authenticate commands sent to the server if the config\-file does not
exist.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-s server\fP
.B \-s server
\fBserver\fP is the name or address of the server which matches a server
statement in the configuration file for \fBrndc\fP\&. If no server is
supplied on the command line, the host named by the default\-server
clause in the options statement of the \fBrndc\fP configuration file
is used.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-p port\fP
.B \-p port
This option instructs BIND 9 to send commands to TCP port \fBport\fP instead of its default control
channel port, 953.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-q\fP
.B \-q
This option sets quiet mode, where message text returned by the server is not printed
unless there is an error.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-r\fP
.B \-r
This option instructs \fBrndc\fP to print the result code returned by \fBnamed\fP
after executing the requested command (e.g., ISC_R_SUCCESS,
ISC_R_FAILURE, etc.).
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-V\fP
.B \-V
This option enables verbose logging.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-y key_id\fP
.B \-y key_id
This option indicates use of the key \fBkey_id\fP from the configuration file. For control message validation to succeed, \fBkey_id\fP must be known
by \fBnamed\fP with the same algorithm and secret string. If no \fBkey_id\fP is specified,
\fBrndc\fP first looks for a key clause in the server statement of
@ -118,7 +137,7 @@ without arguments.
Currently supported commands are:
.INDENT 0.0
.TP
.B \fBaddzone\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] \fIconfiguration\fP
.B addzone zone [class [view]] configuration
This command adds a zone while the server is running. This command requires the
\fBallow\-new\-zones\fP option to be set to \fByes\fP\&. The configuration
string specified on the command line is the zone configuration text
@ -141,9 +160,11 @@ the default view:
(Note the brackets around and semi\-colon after the zone configuration
text.)
.sp
See also \fBrndc delzone\fP and \fBrndc modzone\fP\&.
See also \fI\%rndc delzone\fP and \fI\%rndc modzone\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fBdelzone\fP [\fB\-clean\fP] \fIzone\fP [\fIclass\fP [\fIview\fP]]
.B delzone [\-clean] zone [class [view]]
This command deletes a zone while the server is running.
.sp
If the \fB\-clean\fP argument is specified, the zone\(aqs master file (and
@ -159,9 +180,11 @@ when the server is restarted or reconfigured, the zone is
recreated. To remove it permanently, it must also be removed from
\fBnamed.conf\fP\&.
.sp
See also \fBrndc addzone\fP and \fBrndc modzone\fP\&.
See also \fI\%rndc addzone\fP and \fI\%rndc modzone\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fBdnssec\fP ( \fB\-status\fP | \fB\-rollover\fP \fB\-key\fP id [\fB\-alg\fP \fIalgorithm\fP] [\fB\-when\fP \fItime\fP] | \fB\-checkds\fP [\fB\-key\fP \fIid\fP [\fB\-alg\fP \fIalgorithm\fP]] [\fB\-when\fP \fItime\fP] ( \fIpublished\fP | \fIwithdrawn\fP )) \fIzone\fP [\fIclass\fP [\fIview\fP]]
.B dnssec (\-status | \-rollover \-key id [\-alg algorithm] [\-when time] | \-checkds [\-key id [\-alg algorithm]] [\-when time] published | withdraw)) zone [class [view]]
This command allows you to interact with the "dnssec\-policy" of a given
zone.
.sp
@ -179,8 +202,10 @@ is only one key acting as a KSK in the zone, assume the DS of that key (if
there are multiple keys with the same tag, use \fB\-alg algorithm\fP to
select the correct algorithm). The time that the DS has been published or
withdrawn is set to now, unless otherwise specified with the argument \fB\-when time\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fBdnstap\fP ( \fB\-reopen\fP | \fB\-roll\fP [\fInumber\fP] )
.B dnstap (\-reopen | \-roll [number])
This command closes and re\-opens DNSTAP output files. \fBrndc dnstap \-reopen\fP allows
the output file to be renamed externally, so that \fBnamed\fP can
truncate and re\-open it. \fBrndc dnstap \-roll\fP causes the output file
@ -188,35 +213,47 @@ to be rolled automatically, similar to log files. The most recent
output file has ".0" appended to its name; the previous most recent
output file is moved to ".1", and so on. If \fBnumber\fP is specified, then
the number of backup log files is limited to that number.
.UNINDENT
.INDENT 0.0
.TP
\fBdumpdb\fP [\fB\-all\fP | \fB\-cache\fP | \fB\-zones\fP | \fB\-adb\fP | \fB\-bad\fP | \fB\-expired\fP | \fB\-fail\fP] [\fIview ...\fP]
.B dumpdb [\-all | \-cache | \-zones | \-adb | \-bad | \-expired | \-fail] [view ...]
This command dumps the server\(aqs caches (default) and/or zones to the dump file for
the specified views. If no view is specified, all views are dumped.
(See the \fBdump\-file\fP option in the BIND 9 Administrator Reference
Manual.)
.UNINDENT
.INDENT 0.0
.TP
.B \fBflush\fP
.B flush
This command flushes the server\(aqs cache.
.UNINDENT
.INDENT 0.0
.TP
.B \fBflushname\fP \fIname\fP [\fIview\fP]
.B flushname name [view]
This command flushes the given name from the view\(aqs DNS cache and, if applicable,
from the view\(aqs nameserver address database, bad server cache, and
SERVFAIL cache.
.UNINDENT
.INDENT 0.0
.TP
.B \fBflushtree\fP \fIname\fP [\fIview\fP]
.B flushtree name [view]
This command flushes the given name, and all of its subdomains, from the view\(aqs
DNS cache, address database, bad server cache, and SERVFAIL cache.
.UNINDENT
.INDENT 0.0
.TP
.B \fBfreeze\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]]
.B freeze [zone [class [view]]]
This command suspends updates to a dynamic zone. If no zone is specified, then all
zones are suspended. This allows manual edits to be made to a zone
normally updated by dynamic update, and causes changes in the
journal file to be synced into the master file. All dynamic update
attempts are refused while the zone is frozen.
.sp
See also \fBrndc thaw\fP\&.
See also \fI\%rndc thaw\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fBhalt\fP [\fB\-p\fP]
.B halt [\-p]
This command stops the server immediately. Recent changes made through dynamic
update or IXFR are not saved to the master files, but are rolled
forward from the journal files when the server is restarted. If
@ -224,12 +261,14 @@ forward from the journal files when the server is restarted. If
an external process to determine when \fBnamed\fP has completed
halting.
.sp
See also \fBrndc stop\fP\&.
See also \fI\%rndc stop\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBloadkeys\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]]
.B loadkeys [zone [class [view]]]
This command fetches all DNSSEC keys for the given zone from the key directory. If
they are within their publication period, they are merged into the
zone\(aqs DNSKEY RRset. Unlike \fBrndc sign\fP, however, the zone is not
zone\(aqs DNSKEY RRset. Unlike \fI\%rndc sign\fP, however, the zone is not
immediately re\-signed by the new keys, but is allowed to
incrementally re\-sign over time.
.sp
@ -237,8 +276,10 @@ This command requires that the zone be configured with a \fBdnssec\-policy\fP, o
that the \fBauto\-dnssec\fP zone option be set to \fBmaintain\fP, and also requires the
zone to be configured to allow dynamic DNS. (See "Dynamic Update Policies" in
the Administrator Reference Manual for more details.)
.UNINDENT
.INDENT 0.0
.TP
.B \fBmanaged\-keys\fP (\fIstatus\fP | \fIrefresh\fP | \fIsync\fP | \fIdestroy\fP) [\fIclass\fP [\fIview\fP]]
.B managed\-keys (status | refresh | sync | destroy) [class [view]]
This command inspects and controls the "managed\-keys" database which handles
\fI\%RFC 5011\fP DNSSEC trust anchor maintenance. If a view is specified, these
commands are applied to that view; otherwise, they are applied to all
@ -269,7 +310,7 @@ However, key maintenance operations cease until \fBnamed\fP is
restarted or reconfigured, and all existing key maintenance states
are deleted.
.sp
Running \fBrndc reconfig\fP or restarting \fBnamed\fP immediately
Running \fI\%rndc reconfig\fP or restarting \fBnamed\fP immediately
after this command causes key maintenance to be reinitialized
from scratch, just as if the server were being started for the
first time. This is primarily intended for testing, but it may
@ -277,15 +318,17 @@ also be used, for example, to jumpstart the acquisition of new
keys in the event of a trust anchor rollover, or as a brute\-force
repair for key maintenance problems.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fBmodzone\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] \fIconfiguration\fP
.B modzone zone [class [view]] configuration
This command modifies the configuration of a zone while the server is running. This
command requires the \fBallow\-new\-zones\fP option to be set to \fByes\fP\&.
As with \fBaddzone\fP, the configuration string specified on the
command line is the zone configuration text that would ordinarily be
placed in \fBnamed.conf\fP\&.
.sp
If the zone was originally added via \fBrndc addzone\fP, the
If the zone was originally added via \fI\%rndc addzone\fP, the
configuration changes are recorded permanently and are still
in effect after the server is restarted or reconfigured. However, if
it was originally configured in \fBnamed.conf\fP, then that original
@ -294,17 +337,23 @@ reconfigured, the zone reverts to its original configuration. To
make the changes permanent, it must also be modified in
\fBnamed.conf\fP\&.
.sp
See also \fBrndc addzone\fP and \fBrndc delzone\fP\&.
See also \fI\%rndc addzone\fP and \fI\%rndc delzone\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBnotify\fP \fIzone\fP [\fIclass\fP [\fIview\fP]]
.B notify zone [class [view]]
This command resends NOTIFY messages for the zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fBnotrace\fP
.B notrace
This command sets the server\(aqs debugging level to 0.
.sp
See also \fBrndc trace\fP\&.
See also \fI\%rndc trace\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fBnta\fP [( \fB\-class\fP \fIclass\fP | \fB\-dump\fP | \fB\-force\fP | \fB\-remove\fP | \fB\-lifetime\fP \fIduration\fP)] \fIdomain\fP [\fIview\fP]
.B nta [(\-class class | \-dump | \-force | \-remove | \-lifetime duration)] domain [view]
This command sets a DNSSEC negative trust anchor (NTA) for \fBdomain\fP, with a
lifetime of \fBduration\fP\&. The default lifetime is configured in
\fBnamed.conf\fP via the \fBnta\-lifetime\fP option, and defaults to one
@ -354,8 +403,10 @@ All of these options can be shortened, i.e., to \fB\-l\fP, \fB\-r\fP,
Unrecognized options are treated as errors. To refer to a domain or
view name that begins with a hyphen, use a double\-hyphen (\-\-) on the
command line to indicate the end of options.
.UNINDENT
.INDENT 0.0
.TP
.B \fBquerylog\fP [(\fIon\fP | \fIoff\fP)]
.B querylog [(on | off)]
This command enables or disables query logging. For backward compatibility, this
command can also be used without an argument to toggle query logging
on and off.
@ -364,14 +415,18 @@ Query logging can also be enabled by explicitly directing the
\fBqueries\fP \fBcategory\fP to a \fBchannel\fP in the \fBlogging\fP section
of \fBnamed.conf\fP, or by specifying \fBquerylog yes;\fP in the
\fBoptions\fP section of \fBnamed.conf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBreconfig\fP
.B reconfig
This command reloads the configuration file and loads new zones, but does not reload
existing zone files even if they have changed. This is faster than a
full \fBreload\fP when there is a large number of zones, because it
full \fI\%rndc reload\fP when there is a large number of zones, because it
avoids the need to examine the modification times of the zone files.
.UNINDENT
.INDENT 0.0
.TP
.B \fBrecursing\fP
.B recursing
This command dumps the list of queries \fBnamed\fP is currently
recursing on, and the list of domains to which iterative queries
are currently being sent.
@ -390,30 +445,42 @@ cumulative over time; whenever the number of active fetches for
a domain drops to zero, the counter for that domain is deleted,
and the next time a fetch is sent to that domain, it is recreated
with the counters set to zero).
.UNINDENT
.INDENT 0.0
.TP
.B \fBrefresh\fP \fIzone\fP [\fIclass\fP [\fIview\fP]]
.B refresh zone [class [view]]
This command schedules zone maintenance for the given zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fBreload\fP
.B reload
This command reloads the configuration file and zones.
.UNINDENT
.INDENT 0.0
.TP
.B \fBreload\fP \fIzone\fP [\fIclass\fP [\fIview\fP]]
.B reload zone [class [view]]
This command reloads the given zone.
.UNINDENT
.INDENT 0.0
.TP
.B \fBretransfer\fP \fIzone\fP [\fIclass\fP [\fIview\fP]]
.B retransfer zone [class [view]]
This command retransfers the given secondary zone from the primary server.
.sp
If the zone is configured to use \fBinline\-signing\fP, the signed
version of the zone is discarded; after the retransfer of the
unsigned version is complete, the signed version is regenerated
with new signatures.
.UNINDENT
.INDENT 0.0
.TP
.B \fBscan\fP
.B scan
This command scans the list of available network interfaces for changes, without
performing a full \fBreconfig\fP or waiting for the
performing a full \fI\%rndc reconfig\fP or waiting for the
\fBinterface\-interval\fP timer.
.UNINDENT
.INDENT 0.0
.TP
\fBsecroots\fP [\fB\-\fP] [\fIview\fP ...]
.B secroots [\-] [view ...]
This command dumps the security roots (i.e., trust anchors configured via
\fBtrust\-anchors\fP, or the \fBmanaged\-keys\fP or \fBtrusted\-keys\fP statements
[both deprecated], or \fBdnssec\-validation auto\fP) and negative trust anchors
@ -428,9 +495,11 @@ Otherwise, it is written to the secroots dump file, which defaults to
\fBnamed.secroots\fP, but can be overridden via the \fBsecroots\-file\fP
option in \fBnamed.conf\fP\&.
.sp
See also \fBrndc managed\-keys\fP\&.
See also \fI\%rndc managed\-keys\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fBserve\-stale\fP (\fBon\fP | \fBoff\fP | \fBreset\fP | \fBstatus\fP) [\fIclass\fP [\fIview\fP]]
.B serve\-stale (on | off | reset | status) [class [view]]
This command enables, disables, resets, or reports the current status of
the serving of stale answers as configured in \fBnamed.conf\fP\&.
.sp
@ -441,13 +510,17 @@ serve\-stale reset\fP restores the setting as configured in \fBnamed.conf\fP\&.
\fBrndc serve\-stale status\fP reports whether caching and serving of stale
answers is currently enabled or disabled. It also reports the values of
\fBstale\-answer\-ttl\fP and \fBmax\-stale\-ttl\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBshowzone\fP \fIzone\fP [\fIclass\fP [\fIview\fP]]
.B showzone zone [class [view]]
This command prints the configuration of a running zone.
.sp
See also \fBrndc zonestatus\fP\&.
See also \fI\%rndc zonestatus\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBsign\fP \fIzone\fP [\fIclass\fP [\fIview\fP]]
.B sign zone [class [view]]
This command fetches all DNSSEC keys for the given zone from the key directory (see
the \fBkey\-directory\fP option in the BIND 9 Administrator Reference
Manual). If they are within their publication period, they are merged into
@ -460,9 +533,11 @@ and also requires the zone to be configured to allow dynamic DNS. (See
"Dynamic Update Policies" in the BIND 9 Administrator Reference Manual for more
details.)
.sp
See also \fBrndc loadkeys\fP\&.
See also \fI\%rndc loadkeys\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fBsigning\fP [(\fB\-list\fP | \fB\-clear\fP \fIkeyid/algorithm\fP | \fB\-clear\fP \fIall\fP | \fB\-nsec3param\fP ( \fIparameters\fP | none ) | \fB\-serial\fP \fIvalue\fP ) \fIzone\fP [\fIclass\fP [\fIview\fP]]
.B signing [(\-list | \-clear keyid/algorithm | \-clear all | \-nsec3param (parameters | none) | \-serial value) zone [class [view]]
This command lists, edits, or removes the DNSSEC signing\-state records for the
specified zone. The status of ongoing DNSSEC operations, such as
signing or generating NSEC3 chains, is stored in the zone in the form
@ -506,32 +581,42 @@ replaces it with NSEC.
\fBvalue\fP\&. If the value would cause the serial number to go backwards, it
is rejected. The primary use of this parameter is to set the serial number on inline
signed zones.
.UNINDENT
.INDENT 0.0
.TP
.B \fBstats\fP
.B stats
This command writes server statistics to the statistics file. (See the
\fBstatistics\-file\fP option in the BIND 9 Administrator Reference
Manual.)
.UNINDENT
.INDENT 0.0
.TP
.B \fBstatus\fP
.B status
This command displays the status of the server. Note that the number of zones includes
the internal \fBbind/CH\fP zone and the default \fB\&./IN\fP hint zone, if
there is no explicit root zone configured.
.UNINDENT
.INDENT 0.0
.TP
\fBstop\fP \fB\-p\fP
.B stop \-p
This command stops the server, making sure any recent changes made through dynamic
update or IXFR are first saved to the master files of the updated
zones. If \fB\-p\fP is specified, \fBnamed(8)\(ga\(aqs process ID is returned.
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 \fBrndc halt\fP\&.
See also \fI\%rndc halt\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fBsync\fP \fB\-clean\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]]
.B sync \-clean [zone [class [view]]]
This command syncs changes in the journal file for a dynamic zone to the master
file. If the "\-clean" option is specified, the journal file is also
removed. If no zone is specified, then all zones are synced.
.UNINDENT
.INDENT 0.0
.TP
.B \fBtcp\-timeouts\fP [\fIinitial\fP \fIidle\fP \fIkeepalive\fP \fIadvertised\fP]
.B tcp\-timeouts [initial idle keepalive advertised]
When called without arguments, this command displays the current values of the
\fBtcp\-initial\-timeout\fP, \fBtcp\-idle\-timeout\fP,
\fBtcp\-keepalive\-timeout\fP, and \fBtcp\-advertised\-timeout\fP options.
@ -539,8 +624,10 @@ When called with arguments, these values are updated. This allows an
administrator to make rapid adjustments when under a
denial\-of\-service (DoS) attack. See the descriptions of these options in the BIND 9
Administrator Reference Manual for details of their use.
.UNINDENT
.INDENT 0.0
.TP
.B \fBthaw\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]]
.B thaw [zone [class [view]]]
This command enables updates to a frozen dynamic zone. If no zone is specified,
then all frozen zones are enabled. This causes the server to reload
the zone from disk, and re\-enables dynamic updates after the load has
@ -550,33 +637,45 @@ option is in use, the journal file is updated to reflect
changes in the zone. Otherwise, if the zone has changed, any existing
journal file is removed.
.sp
See also \fBrndc freeze\fP\&.
See also \fI\%rndc freeze\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBtrace\fP
.B trace
This command increments the server\(aqs debugging level by one.
.UNINDENT
.INDENT 0.0
.TP
.B \fBtrace\fP \fIlevel\fP
.B trace level
This command sets the server\(aqs debugging level to an explicit value.
.sp
See also \fBrndc notrace\fP\&.
See also \fI\%rndc notrace\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \fBtsig\-delete\fP \fIkeyname\fP [\fIview\fP]
.B tsig\-delete keyname [view]
This command deletes a given TKEY\-negotiated key from the server. This does not
apply to statically configured TSIG keys.
.UNINDENT
.INDENT 0.0
.TP
.B \fBtsig\-list\fP
.B tsig\-list
This command lists the names of all TSIG keys currently configured for use by
\fBnamed\fP in each view. The list includes both statically configured keys and
dynamic TKEY\-negotiated keys.
.UNINDENT
.INDENT 0.0
.TP
\fBvalidation\fP (\fBon\fP | \fBoff\fP | \fBstatus\fP) [\fIview\fP ...]\(ga\(ga
.B validation (on | off | status) [view ...]
This command enables, disables, or checks the current status of DNSSEC validation. By
default, validation is enabled.
.sp
The cache is flushed when validation is turned on or off to avoid using data
that might differ between states.
.UNINDENT
.INDENT 0.0
.TP
.B \fBzonestatus\fP \fIzone\fP [\fIclass\fP [\fIview\fP]]
.B zonestatus zone [class [view]]
This command displays the current status of the given zone, including the master
file name and any include files from which it was loaded, when it was
most recently loaded, the current serial number, the number of nodes,
@ -584,11 +683,11 @@ whether the zone supports dynamic updates, whether the zone is DNSSEC
signed, whether it uses automatic DNSSEC key management or inline
signing, and the scheduled refresh or expiry times for the zone.
.sp
See also \fBrndc showzone\fP\&.
See also \fI\%rndc showzone\fP\&.
.UNINDENT
.sp
\fBrndc\fP commands that specify zone names, such as \fBreload\fP,
\fBretransfer\fP, or \fBzonestatus\fP, can be ambiguous when applied to zones
\fBrndc\fP commands that specify zone names, such as \fI\%reload\fP
\fI\%retransfer\fP, or \fI\%zonestatus\fP, can be ambiguous when applied to zones
of type \fBredirect\fP\&. Redirect zones are always called \fB\&.\fP, and can be
confused with zones of type \fBhint\fP or with secondary copies of the root
zone. To specify a redirect zone, use the special zone name
@ -603,7 +702,7 @@ Several error messages could be clearer.
.SH SEE ALSO
.sp
\fBrndc.conf(5)\fP, \fBrndc\-confgen(8)\fP,
\fBnamed(8)\fP, \fBnamed.conf(5)\fP, \fBndc(8)\fP, BIND 9 Administrator
\fBnamed(8)\fP, \fBnamed.conf(5)\fP, BIND 9 Administrator
Reference Manual.
.SH AUTHOR
Internet Systems Consortium

6
doc/man/tsig-keygen.8in
View file

@ -44,13 +44,15 @@ of the generated key. If no name is specified, the default is \fBtsig\-key\fP\&.
.SH OPTIONS
.INDENT 0.0
.TP
.B \fB\-a algorithm\fP
.B \-a algorithm
This option specifies the algorithm to use for the TSIG key. Available
choices are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384,
and hmac\-sha512. The default is hmac\-sha256. Options are
case\-insensitive, and the "hmac\-" prefix may be omitted.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-h\fP
.B \-h
This option prints a short summary of options and arguments.
.UNINDENT
.SH SEE ALSO

12
doc/misc/rst-options.pl
View file

@ -43,6 +43,8 @@ END
print <<END;
.. highlight: console
.. iscman:: named.conf
named.conf - configuration file for **named**
---------------------------------------------
@ -54,10 +56,10 @@ Synopsis
Description
~~~~~~~~~~~
``named.conf`` is the configuration file for ``named``. Statements are
enclosed in braces and terminated with a semi-colon. Clauses in the
statements are also semi-colon terminated. The usual comment styles are
supported:
:file:`named.conf` is the configuration file for :iscman:`named`.
Statements are enclosed in braces and terminated with a semi-colon.
Clauses in the statements are also semi-colon terminated. The usual
comment styles are supported:
C style: /\\* \\*/
@ -141,6 +143,6 @@ Files
See Also
~~~~~~~~
:manpage:`named(8)`, :manpage:`named-checkconf(8)`, :manpage:`rndc(8)`, :manpage:`rndc-confgen(8)`, :manpage:`tsig-keygen(8)`, BIND 9 Administrator Reference Manual.
:iscman:`named(8) <named>`, :iscman:`named-checkconf(8) <named-checkconf>`, :iscman:`rndc(8) <rndc>`, :iscman:`rndc-confgen(8) <rndc-confgen>`, :iscman:`tsig-keygen(8) <tsig-keygen>`, BIND 9 Administrator Reference Manual.
END

4
doc/notes/notes-9.17.0.rst
View file

@ -30,7 +30,7 @@ New Features
- When a secondary server receives a large incremental zone transfer
(IXFR), it can have a negative impact on query performance while the
incremental changes are applied to the zone. To address this,
``named`` can now limit the size of IXFR responses it sends in
:iscman:`named` can now limit the size of IXFR responses it sends in
response to zone transfer requests. If an IXFR response would be
larger than an AXFR of the entire zone, it will send an AXFR response
instead.
@ -63,7 +63,7 @@ Feature Changes
.. _bug: https://sourceware.org/bugzilla/show_bug.cgi?id=23844
- The ``rndc nta -dump`` and ``rndc secroots`` commands now both
- The :option:`rndc nta -dump <rndc nta>` and :option:`rndc secroots` commands now both
include ``validate-except`` entries when listing negative trust
anchors. These are indicated by the keyword ``permanent`` in place of
the expiry date. :gl:`#1532`

2
doc/notes/notes-9.17.1.rst
View file

@ -54,7 +54,7 @@ Bug Fixes
~~~~~~~~~
- When an RPZ policy zone was updated via zone transfer and a large
number of records was deleted, ``named`` could become nonresponsive
number of records was deleted, :iscman:`named` could become nonresponsive
for a short period while deleted names were removed from the RPZ
summary database. This database cleanup is now done incrementally
over a longer period of time, reducing such delays. :gl:`#1447`

24
doc/notes/notes-9.17.10.rst
View file

@ -15,26 +15,26 @@ Notes for BIND 9.17.10
New Features
~~~~~~~~~~~~
- Support for DNS-over-HTTPS (DoH) was added to ``named``. Because of
- Support for DNS-over-HTTPS (DoH) was added to :iscman:`named`. Because of
this, the ``nghttp2`` HTTP/2 library is now required for building the
development branch of BIND 9. Both TLS-encrypted and unencrypted
HTTP/2 connections are supported (the latter may be used to offload
encryption to other software).
Note that there is no client-side support for HTTPS as yet; this will
be added to ``dig`` in a future release. :gl:`#1144`
be added to :iscman:`dig` in a future release. :gl:`#1144`
- ``named`` now supports XFR-over-TLS (XoT) for incoming as well as
- :iscman:`named` now supports XFR-over-TLS (XoT) for incoming as well as
outgoing zone transfers. Addresses in a ``primaries`` list can now be
accompanied by an optional ``tls`` keyword, followed by either the
name of a previously configured ``tls`` statement or ``ephemeral``.
:gl:`#2392`
- A new option, ``stale-answer-client-timeout``, has been added to
improve ``named``'s behavior with respect to serving stale data. The
option defines the amount of time ``named`` waits before attempting to
improve :iscman:`named`'s behavior with respect to serving stale data. The
option defines the amount of time :iscman:`named` waits before attempting to
answer the query with a stale RRset from cache. If a stale answer is
found, ``named`` continues the ongoing fetches, attempting to refresh
found, :iscman:`named` continues the ongoing fetches, attempting to refresh
the RRset in cache until the ``resolver-query-timeout`` interval is
reached.
@ -57,7 +57,7 @@ Removed Features
failure: ``acache-cleaning-interval``, ``acache-enable``,
``additional-from-auth``, ``additional-from-cache``,
``allow-v6-synthesis``, ``cleaning-interval``, ``dnssec-enable``,
``dnssec-lookaside``, ``filter-aaaa``, ``filter-aaaa-on-v4``,
``dnssec-lookaside``, :iscman:`filter-aaaa`, ``filter-aaaa-on-v4``,
``filter-aaaa-on-v6``, ``geoip-use-ecs``, ``lwres``,
``max-acache-size``, ``nosit-udp-size``, ``queryport-pool-ports``,
``queryport-pool-updateinterval``, ``request-sit``, ``sit-secret``,
@ -66,11 +66,11 @@ Removed Features
Feature Changes
~~~~~~~~~~~~~~~
- When serve-stale is enabled and stale data is available, ``named`` now
- When serve-stale is enabled and stale data is available, :iscman:`named` now
returns stale answers upon encountering any unexpected error in the
query resolution process. This may happen, for example, if the
``fetches-per-server`` or ``fetches-per-zone`` limits are reached. In
this case, ``named`` attempts to answer DNS requests with stale data,
this case, :iscman:`named` attempts to answer DNS requests with stale data,
but does not start the ``stale-refresh-time`` window. :gl:`#2434`
- The default value of ``max-stale-ttl`` has been changed from 12 hours
@ -93,10 +93,10 @@ Feature Changes
Bug Fixes
~~~~~~~~~
- ``named`` failed to start when its configuration included a zone with
- :iscman:`named` failed to start when its configuration included a zone with
a non-builtin ``allow-update`` ACL attached. :gl:`#2413`
- Previously, ``dnssec-keyfromlabel`` crashed when operating on an ECDSA
- Previously, :iscman:`dnssec-keyfromlabel` crashed when operating on an ECDSA
key. This has been fixed. :gl:`#2178`
- KASP incorrectly set signature validity to the value of the DNSKEY
@ -115,5 +115,5 @@ Bug Fixes
(Equation (2)). :gl:`#2375`
- Performance of the DNSSEC verification code (used by
``dnssec-signzone``, ``dnssec-verify``, and mirror zones) has been
:iscman:`dnssec-signzone`, :iscman:`dnssec-verify`, and mirror zones) has been
improved. :gl:`#2073`

22
doc/notes/notes-9.17.11.rst
View file

@ -15,7 +15,7 @@ Notes for BIND 9.17.11
New Features
~~~~~~~~~~~~
- ``dig`` has been extended to support DNS-over-HTTPS (DoH) queries,
- :iscman:`dig` has been extended to support DNS-over-HTTPS (DoH) queries,
using ``dig +https`` and related options. :gl:`#1641`
- A new ``purge-keys`` option has been added to ``dnssec-policy``. It
@ -35,33 +35,33 @@ Feature Changes
- ``http default`` can now be specified in ``listen-on`` and
``listen-on-v6`` statements to use the default HTTP endpoint of
``/dns-query``. It is no longer necessary to include an ``http``
statement in ``named.conf`` unless overriding this value. :gl:`#2472`
statement in :iscman:`named.conf` unless overriding this value. :gl:`#2472`
Bug Fixes
~~~~~~~~~
- Zone journal (``.jnl``) files created by versions of ``named`` prior
- Zone journal (``.jnl``) files created by versions of :iscman:`named` prior
to 9.16.12 were no longer compatible; this could cause problems when
upgrading if journal files were not synchronized first. This has been
corrected: older journal files can now be read when starting up. When
an old-style journal file is detected, it is updated to the new format
immediately after loading.
Note that journals created by the current version of ``named`` are not
Note that journals created by the current version of :iscman:`named` are not
usable by versions prior to 9.16.12. Before downgrading to a prior
release, users are advised to ensure that all dynamic zones have been
synchronized using ``rndc sync -clean``.
synchronized using :option:`rndc sync -clean <rndc sync>`.
A journal file's format can be changed manually by running
``named-journalprint -d`` (downgrade) or ``named-journalprint -u``
(upgrade). Note that this *must not* be done while ``named`` is
(upgrade). Note that this *must not* be done while :iscman:`named` is
running. :gl:`#2505`
- ``named`` crashed when it was allowed to serve stale answers and
- :iscman:`named` crashed when it was allowed to serve stale answers and
``stale-answer-client-timeout`` was triggered without any (stale) data
available in the cache to answer the query. :gl:`#2503`
- If an outgoing packet exceeded ``max-udp-size``, ``named`` dropped it
- If an outgoing packet exceeded ``max-udp-size``, :iscman:`named` dropped it
instead of sending back a proper response. To prevent this problem,
the ``IP_DONTFRAG`` option is no longer set on UDP sockets, which has
been happening since BIND 9.17.6. :gl:`#2466`
@ -70,7 +70,7 @@ Bug Fixes
using ``dnssec-policy`` with ``nsec3param``. This has been fixed.
:gl:`#2498`
- A memory leak occurred when ``named`` was reconfigured after adding an
- A memory leak occurred when :iscman:`named` was reconfigured after adding an
inline-signed zone with ``auto-dnssec maintain`` enabled. This has
been fixed. :gl:`#2041`
@ -79,9 +79,9 @@ Bug Fixes
such a record was loaded. :gl:`#2499`
- If an invalid key name (e.g. ``a..b``) was specified in a
``primaries`` list in ``named.conf``, the wrong size was passed to
``primaries`` list in :iscman:`named.conf`, the wrong size was passed to
``isc_mem_put()``, which resulted in the returned memory being put on
the wrong free list and prevented ``named`` from starting up. This has
the wrong free list and prevented :iscman:`named` from starting up. This has
been fixed. :gl:`#2460`
- ``libtool`` was inadvertently introduced as a build-time requirement

20
doc/notes/notes-9.17.12.rst
View file

@ -16,12 +16,12 @@ Security Fixes
~~~~~~~~~~~~~~
- A malformed incoming IXFR transfer could trigger an assertion failure
in ``named``, causing it to quit abnormally. (CVE-2021-25214)
in :iscman:`named`, causing it to quit abnormally. (CVE-2021-25214)
ISC would like to thank Greg Kuechle of SaskTel for bringing this
vulnerability to our attention. :gl:`#2467`
- ``named`` crashed when a DNAME record placed in the ANSWER section
- :iscman:`named` crashed when a DNAME record placed in the ANSWER section
during DNAME chasing turned out to be the final answer to a client
query. (CVE-2021-25215)
@ -56,7 +56,7 @@ Bug Fixes
has been fixed. :gl:`#2583`
- When ``stale-answer-client-timeout`` was set to a positive value and
recursion for a client query completed when ``named`` was about to
recursion for a client query completed when :iscman:`named` was about to
look for a stale answer, an assertion could fail in
``query_respond()``, resulting in a crash. This has been fixed.
:gl:`#2594`
@ -64,24 +64,24 @@ Bug Fixes
- After upgrading to the previous release, journal files for trust
anchor databases (e.g. ``managed-keys.bind.jnl``) could be left in a
corrupt state. (Other zone journal files were not affected.) This has
been fixed. If a corrupt journal file is detected, ``named`` can now
been fixed. If a corrupt journal file is detected, :iscman:`named` can now
recover from it. :gl:`#2600`
- When sending queries over TCP, ``dig`` now properly handles ``+tries=1
- When sending queries over TCP, :iscman:`dig` now properly handles ``+tries=1
+retry=0`` by not retrying the connection when the remote server
closes the connection prematurely. :gl:`#2490`
- CDS/CDNSKEY DELETE records are now removed when a zone transitions
from a secure to an insecure state. ``named-checkzone`` also no longer
from a secure to an insecure state. :iscman:`named-checkzone` also no longer
reports an error when such records are found in an unsigned zone.
:gl:`#2517`
- Zones using KASP could not be thawed after they were frozen using
``rndc freeze``. This has been fixed. :gl:`#2523`
:option:`rndc freeze`. This has been fixed. :gl:`#2523`
- After ``rndc checkds -checkds`` or ``rndc dnssec -rollover`` is used,
``named`` now immediately attempts to reconfigure zone keys. This
- After :option:`rndc dnssec -checkds <rndc dnssec>` or :option:`rndc dnssec -rollover <rndc dnssec>` is used,
:iscman:`named` now immediately attempts to reconfigure zone keys. This
change prevents unnecessary key rollover delays. :gl:`#2488`
- ``named`` crashed after skipping a primary server while transferring a
- :iscman:`named` crashed after skipping a primary server while transferring a
zone over TLS. This has been fixed. :gl:`#2562`

14
doc/notes/notes-9.17.13.rst
View file

@ -21,7 +21,7 @@ Feature Changes
- The maximum supported number of NSEC3 iterations that can be
configured for a zone has been reduced to 150. :gl:`#2642`
- After the network manager was introduced to ``named`` to handle
- After the network manager was introduced to :iscman:`named` to handle
incoming traffic, it was discovered that recursive performance had
degraded compared to previous BIND 9 versions. This has now been
fixed by processing internal tasks inside network manager worker
@ -54,28 +54,28 @@ Bug Fixes
itself was preserved. :gl:`#2623`
- It was possible for corrupt journal files generated by an earlier
version of ``named`` to cause problems after an upgrade. This has been
version of :iscman:`named` to cause problems after an upgrade. This has been
fixed. :gl:`#2670`
- TTL values in cache dumps were reported incorrectly when
``stale-cache-enable`` was set to ``yes``. This has been fixed.
:gl:`#389` :gl:`#2289`
- A deadlock could occur when multiple ``rndc addzone``, ``rndc
delzone``, and/or ``rndc modzone`` commands were invoked
- A deadlock could occur when multiple :option:`rndc addzone`, :option:`rndc
delzone`, and/or :option:`rndc modzone` commands were invoked
simultaneously for different zones. This has been fixed. :gl:`#2626`
- ``inline-signing`` was incorrectly described as being inherited from
the ``options``/``view`` levels and was incorrectly accepted at those
levels without effect. This has been fixed; ``named.conf`` files with
levels without effect. This has been fixed; :iscman:`named.conf` files with
``inline-signing`` at those levels no longer load. :gl:`#2536`
- ``named`` and ``named-checkconf`` did not report an error when
- :iscman:`named` and :iscman:`named-checkconf` did not report an error when
multiple zones with the ``dnssec-policy`` option set were using the
same zone file. This has been fixed. :gl:`#2603`
- If ``dnssec-policy`` was active and a private key file was temporarily
offline during a rekey event, ``named`` could incorrectly introduce
offline during a rekey event, :iscman:`named` could incorrectly introduce
replacement keys and break a signed zone. This has been fixed.
:gl:`#2596`

2
doc/notes/notes-9.17.15.rst
View file

@ -15,7 +15,7 @@ Notes for BIND 9.17.15
Bug Fixes
~~~~~~~~~
- When preparing DNS responses, ``named`` could replace the letters
- When preparing DNS responses, :iscman:`named` could replace the letters
``W`` (uppercase) and ``w`` (lowercase) with ``\000``. This has been
fixed. :gl:`#2779`

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

@ -17,7 +17,7 @@ Security Fixes
- Sending DNS messages with the OPCODE field set to anything other than
QUERY (0) via DNS-over-TLS (DoT) or DNS-over-HTTPS (DoH) channels
triggered an assertion failure in ``named``. This has been fixed.
triggered an assertion failure in :iscman:`named`. This has been fixed.
ISC would like to thank Ville Heikkila of Synopsys Cybersecurity
Research Center for bringing this vulnerability to our attention.
@ -55,12 +55,12 @@ Bug Fixes
database of managed keys from subsequently being read back. This has
been fixed. :gl:`#2686`
- Signed, insecure delegation responses prepared by ``named`` either
- Signed, insecure delegation responses prepared by :iscman:`named` either
lacked the necessary NSEC records or contained duplicate NSEC records
when both wildcard expansion and CNAME chaining were required to
prepare the response. This has been fixed. :gl:`#2759`
- If ``nsupdate`` sends an SOA request and receives a REFUSED response,
- If :iscman:`nsupdate` sends an SOA request and receives a REFUSED response,
it now fails over to the next available server. :gl:`#2758`
- A bug that caused the NSEC3 salt to be changed on every restart for

12
doc/notes/notes-9.17.17.rst
View file

@ -15,11 +15,11 @@ Notes for BIND 9.17.17
Security Fixes
~~~~~~~~~~~~~~
- Fixed an assertion failure that occurred in ``named`` when it
- Fixed an assertion failure that occurred in :iscman:`named` when it
attempted to send a UDP packet that exceeded the MTU size, if
Response Rate Limiting (RRL) was enabled. (CVE-2021-25218) :gl:`#2856`
- ``named`` failed to check the opcode of responses when performing zone
- :iscman:`named` failed to check the opcode of responses when performing zone
refreshes, stub zone updates, and UPDATE forwarding. This could lead
to an assertion failure under certain conditions and has been
addressed by rejecting responses whose opcode does not match the
@ -43,7 +43,7 @@ New Features
Feature Changes
~~~~~~~~~~~~~~~
- Previously, ``named`` accepted FORMERR responses both with and without
- Previously, :iscman:`named` accepted FORMERR responses both with and without
an OPT record, as an indication that a given server did not support
EDNS. To implement full compliance with :rfc:`6891`, only FORMERR
responses without an OPT record are now accepted. This intentionally
@ -58,10 +58,10 @@ Feature Changes
enabled by default. :gl:`#2433`
- Testing revealed that setting the thread affinity for various types of
``named`` threads led to inconsistent recursive performance, as
:iscman:`named` threads led to inconsistent recursive performance, as
sometimes multiple sets of threads competed over a single resource.
Due to the above, ``named`` no longer sets thread affinity. This
Due to the above, :iscman:`named` no longer sets thread affinity. This
causes a slight dip of around 5% in authoritative performance, but
recursive performance is now consistently improved. :gl:`#2822`
@ -74,6 +74,6 @@ Feature Changes
Bug Fixes
~~~~~~~~~
- Authentication of ``rndc`` messages could fail if a ``controls``
- Authentication of :iscman:`rndc` messages could fail if a ``controls``
statement was configured with multiple key algorithms for the same
listener. This has been fixed. :gl:`#2756`

16
doc/notes/notes-9.17.18.rst
View file

@ -20,18 +20,18 @@ New Features
Feature Changes
~~~~~~~~~~~~~~~
- When ``dnssec-signzone`` signs a zone using a successor key whose
- When :iscman:`dnssec-signzone` signs a zone using a successor key whose
predecessor is still published, it now only refreshes signatures for
RRsets which have an invalid signature, an expired signature, or a
signature which expires within the provided cycle interval. This
allows ``dnssec-signzone`` to gradually replace signatures in a zone
allows :iscman:`dnssec-signzone` to gradually replace signatures in a zone
whose ZSK is being rolled over (similarly to what ``auto-dnssec
maintain;`` does). :gl:`#1551`
- ``dnssec-cds`` now only generates SHA-2 DS records by default and
- :iscman:`dnssec-cds` now only generates SHA-2 DS records by default and
avoids copying deprecated SHA-1 records from a child zone to its
delegation in the parent. If the child zone does not publish SHA-2 CDS
records, ``dnssec-cds`` will generate them from the CDNSKEY records.
records, :iscman:`dnssec-cds` will generate them from the CDNSKEY records.
The ``-a algorithm`` option now affects the process of generating DS
digest records from both CDS and CDNSKEY records. Thanks to Tony
Finch. :gl:`#2871`
@ -45,16 +45,16 @@ Bug Fixes
- A recent change to the internal memory structure of zone databases
inadvertently neglected to update the MAPAPI value for zone files in
``map`` format. This caused version 9.17.17 of ``named`` to attempt to
``map`` format. This caused version 9.17.17 of :iscman:`named` to attempt to
load files into memory that were no longer compatible, triggering an
assertion failure on startup. The MAPAPI value has now been updated,
so ``named`` rejects outdated files when encountering them.
so :iscman:`named` rejects outdated files when encountering them.
:gl:`#2872`
- Zone files in ``map`` format whose size exceeded 2 GB failed to load.
This has been fixed. :gl:`#2878`
- Stale data in the cache could cause ``named`` to send non-minimized
- Stale data in the cache could cause :iscman:`named` to send non-minimized
queries despite QNAME minimization being enabled. This has been fixed.
:gl:`#2665`
@ -63,6 +63,6 @@ Bug Fixes
a Combined Signing Key (CSK). :gl:`#2857`
- When a dynamic zone was made available in another view using the
``in-view`` statement, running ``rndc freeze`` always reported an
``in-view`` statement, running :option:`rndc freeze` always reported an
``already frozen`` error even though the zone was successfully
frozen. This has been fixed. :gl:`#2844`

16
doc/notes/notes-9.17.19.rst
View file

@ -15,7 +15,7 @@ Notes for BIND 9.17.19
Security Fixes
~~~~~~~~~~~~~~
- The ``lame-ttl`` option controls how long ``named`` caches certain
- The ``lame-ttl`` option controls how long :iscman:`named` caches certain
types of broken responses from authoritative servers (see the
`security advisory <https://kb.isc.org/docs/cve-2021-25219>`_ for
details). This caching mechanism could be abused by an attacker to
@ -65,12 +65,12 @@ Removed Features
which is part of the `OpenSC`_ project. :gl:`#2691`
- Old-style Dynamically Loadable Zones (DLZ) drivers that had to be
enabled in ``named`` at build time have been removed. New-style DLZ
enabled in :iscman:`named` at build time have been removed. New-style DLZ
modules should be used as a replacement. :gl:`#2814`
- Support for the ``map`` zone file format (``masterfile-format map;``)
has been removed. Users relying on the ``map`` format are advised to
convert their zones to the ``raw`` format with ``named-compilezone``
convert their zones to the ``raw`` format with :iscman:`named-compilezone`
and change the configuration appropriately prior to upgrading BIND 9.
:gl:`#2882`
@ -80,10 +80,10 @@ Feature Changes
~~~~~~~~~~~~~~~
- The network manager API is now used for sending all outgoing DNS
queries and requests from ``named`` and related tools, including
``delv``, ``mdig``, and ``nsupdate``. :gl:`#2401`
queries and requests from :iscman:`named` and related tools, including
:iscman:`delv`, :iscman:`mdig`, and :iscman:`nsupdate`. :gl:`#2401`
- ``named`` and ``named-checkconf`` now exit with an error when a single
- :iscman:`named` and :iscman:`named-checkconf` now exit with an error when a single
port configured for ``query-source``, ``transfer-source``,
``notify-source``, ``parental-source``, and/or their respective IPv6
counterparts clashes with a global listening port. This configuration
@ -91,7 +91,7 @@ Feature Changes
until now (even though sending UDP messages such as NOTIFY failed).
:gl:`#2888`
- ``named`` and ``named-checkconf`` now issue a warning when there is a
- :iscman:`named` and :iscman:`named-checkconf` now issue a warning when there is a
single port configured for ``query-source``, ``transfer-source``,
``notify-source``, ``parental-source``, and/or for their respective
IPv6 counterparts. :gl:`#2888`
@ -110,7 +110,7 @@ Bug Fixes
again. :gl:`#2911`
- When new IP addresses were set up by the operating system during
``named`` startup, it could fail to listen for TCP connections on the
:iscman:`named` startup, it could fail to listen for TCP connections on the
newly added interfaces. :gl:`#2852`
- Under specific circumstances, zone transfers over TCP and TLS could be

30
doc/notes/notes-9.17.2.rst
View file

@ -68,7 +68,7 @@ New Features
Docs`_. Release notes are no longer available as a separate document
accompanying a release. :gl:`#83`
- ``named`` and ``named-checkzone`` now reject master zones that have a
- :iscman:`named` and :iscman:`named-checkzone` now reject master zones that have a
DS RRset at the zone apex. Attempts to add DS records at the zone
apex via UPDATE will be logged but otherwise ignored. DS records
belong in the parent zone, not at the zone apex. :gl:`#1798`
@ -78,7 +78,7 @@ New Features
particular type that can be added to a domain name via dynamic
update. :gl:`#1657`
- ``dig`` and other tools can now print the Extended DNS Error (EDE)
- :iscman:`dig` and other tools can now print the Extended DNS Error (EDE)
option when it appears in a request or a response. :gl:`#1835`
- ``dig +qid=<num>`` allows the user to specify a particular query ID
@ -96,12 +96,12 @@ Feature Changes
~~~~~~~~~~~~~~~
- The default value of ``max-stale-ttl`` has changed from 1 week to 12
hours. This option controls how long ``named`` retains expired RRsets
hours. This option controls how long :iscman:`named` retains expired RRsets
in cache as a potential mitigation mechanism, should there be a
problem with one or more domains. Note that cache content retention
is independent of whether stale answers are used in response to
client queries (``stale-answer-enable yes|no`` and ``rndc serve-stale
on|off``). Serving of stale answers when the authoritative servers
client queries (``stale-answer-enable yes|no`` and :option:`rndc serve-stale
on|off <rndc serve-stale>`). Serving of stale answers when the authoritative servers
are not responding must be explicitly enabled, whereas the retention
of expired cache content takes place automatically on all versions of
BIND 9 that have this feature available. :gl:`#1877`
@ -109,8 +109,8 @@ Feature Changes
.. warning::
This change may be significant for administrators who expect that
stale cache content will be automatically retained for up to 1
week. Add option ``max-stale-ttl 1w;`` to ``named.conf`` to keep
the previous behavior of ``named``.
week. Add option ``max-stale-ttl 1w;`` to :iscman:`named.conf` to keep
the previous behavior of :iscman:`named`.
- BIND 9 no longer sets receive/send buffer sizes for UDP sockets,
relying on system defaults instead. :gl:`#1713`
@ -119,8 +119,8 @@ Feature Changes
BIND 9 rwlock implementation. :gl:`#1753`
- BIND 9 binaries which are neither daemons nor administrative programs
were moved to ``$bindir``. Only ``ddns-confgen``, ``named``,
``rndc``, ``rndc-confgen``, and ``tsig-confgen`` were left in
were moved to ``$bindir``. Only :iscman:`ddns-confgen`, :iscman:`named`,
:iscman:`rndc`, :iscman:`rndc-confgen`, and ``tsig-confgen`` were left in
``$sbindir``. :gl:`#1724`
- ``listen-on-v6 { any; }`` creates a separate socket for each
@ -160,12 +160,12 @@ Bug Fixes
processing step that was causing this delay has now been removed.
:gl:`#1834`
- ``named`` could crash with an assertion failure if the name of a
- :iscman:`named` could crash with an assertion failure if the name of a
database node was looked up while the database was being modified.
:gl:`#1857`
- When running on a system with support for Linux capabilities,
``named`` drops root privileges very soon after system startup. This
:iscman:`named` drops root privileges very soon after system startup. This
was causing a spurious log message, ``unable to set effective uid to
0: Operation not permitted``, which has now been silenced.
:gl:`#1042` :gl:`#1090`
@ -173,7 +173,7 @@ Bug Fixes
- A possible deadlock in ``lib/isc/unix/socket.c`` was fixed.
:gl:`#1859`
- Previously, ``named`` did not destroy some mutexes and conditional
- Previously, :iscman:`named` did not destroy some mutexes and conditional
variables in netmgr code, which caused a memory leak on FreeBSD. This
has been fixed. :gl:`#1893`
@ -195,17 +195,17 @@ Bug Fixes
of the current active key (the predecessor) was not changed and thus
never removed from the zone. :gl:`#1846`
- When ``named-checkconf -z`` was run, it would sometimes incorrectly
- When :option:`named-checkconf -z` was run, it would sometimes incorrectly
set its exit code. It reflected the status of the last view found; if
zone-loading errors were found in earlier configured views but not in
the last one, the exit code indicated success. Thanks to Graham
Clinch. :gl:`#1807`
- ``named-checkconf -p`` could include spurious text in
- :option:`named-checkconf -p` could include spurious text in
``server-addresses`` statements due to an uninitialized DSCP value.
This has been fixed. :gl:`#1812`
- When built without LMDB support, ``named`` failed to restart after a
- When built without LMDB support, :iscman:`named` failed to restart after a
zone with a double quote (") in its name was added with ``rndc
addzone``. Thanks to Alberto Fernández. :gl:`#1695`

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

@ -55,14 +55,14 @@ Feature Changes
a steady response rate on a loaded resolver while these internal data
structures are resized. :gl:`#2941`
- The output of ``rndc serve-stale status`` has been clarified. It now
- The output of :option:`rndc serve-stale status <rndc serve-stale>` has been clarified. It now
explicitly reports whether retention of stale data in the cache is
enabled (``stale-cache-enable``), and whether returning such data in
responses is enabled (``stale-answer-enable``). :gl:`#2742`
- The `UseSTD3ASCIIRules`_ flag is now set for libidn2 function calls.
This enables additional validation rules for IDN domains and hostnames
in ``dig``. :gl:`#1610`
in :iscman:`dig`. :gl:`#1610`
.. _UseSTD3ASCIIRules: http://www.unicode.org/reports/tr46/#UseSTD3ASCIIRules
@ -70,7 +70,7 @@ Bug Fixes
~~~~~~~~~
- Reloading a catalog zone which referenced a missing/deleted member
zone triggered a runtime check failure, causing ``named`` to exit
zone triggered a runtime check failure, causing :iscman:`named` to exit
prematurely. This has been fixed. :gl:`#2308`
- Some lame delegations could trigger a dependency loop, in which a

10
doc/notes/notes-9.17.21.rst
View file

@ -36,7 +36,7 @@ Feature Changes
- The `UseSTD3ASCIIRules`_ flag is now disabled again for libidn2
function calls. Applying additional validation rules for domain names
in ``dig`` (a change introduced in the previous BIND 9 release) caused
in :iscman:`dig` (a change introduced in the previous BIND 9 release) caused
characters which are disallowed in hostnames (e.g. underscore ``_``,
wildcard ``*``) to be silently stripped. That change was reverted.
:gl:`#1610`
@ -50,7 +50,7 @@ Feature Changes
following triggering events: ``socket is not connected``, ``quota
reached``, and ``soft quota reached``. :gl:`#2700`
- ``dnssec-dsfromkey`` no longer generates DS records from revoked keys.
- :iscman:`dnssec-dsfromkey` no longer generates DS records from revoked keys.
:gl:`#853`
.. _UseSTD3ASCIIRules: http://www.unicode.org/reports/tr46/#UseSTD3ASCIIRules
@ -59,9 +59,9 @@ Bug Fixes
~~~~~~~~~
- Removing a configured ``catalog-zone`` clause from the configuration,
running ``rndc reconfig``, then bringing back the removed
``catalog-zone`` clause and running ``rndc reconfig`` again caused
``named`` to crash. This has been fixed. :gl:`#1608`
running :option:`rndc reconfig`, then bringing back the removed
``catalog-zone`` clause and running :option:`rndc reconfig` again caused
:iscman:`named` to crash. This has been fixed. :gl:`#1608`
- The resolver could hang on shutdown due to dispatch resources not
being cleaned up when a TCP connection was reset, or due to dependency

Some files were not shown because too many files have changed in this diff Show more