ComputerSurge/bind9
3
0
Fork 0
Code Pull Requests 1 Activity

Merge branch '2799-documentation-for-administrative-tools-is-out-of-sync-with-manual-pages' into 'main'

Browse Source 
Fix Administrative Tools section in the ARM

Closes #2799 and #2826

See merge request isc-projects/bind9!5254
This commit is contained in:
Petr Špaček
2022-03-10 19:17:03 +00:00
parent ca1da46ac1 178aef5b8c
commit 1357d44605
14 changed files with 371 additions and 233 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitlab-ci.yml
View File

@@ -505,11 +505,13 @@ tarball-create:
- autoreconf -fi
- ./configure --enable-maintainer-mode
- make -j${BUILD_PARALLEL_JOBS:-1} all V=1
- if test "$(git status --porcelain | grep -Ev '\?\?' | wc -l)" -gt "0"; then git status --short; exit 1; fi
- if test "$(git status --porcelain | grep -Ev '\?\?' | wc -l)" -gt "0"; then git status --short; git diff > diff.patch; exit 1; fi
- make -j${BUILD_PARALLEL_JOBS:-1} dist V=1
artifacts:
paths:
- diff.patch
- bind-*.tar.${TARBALL_EXTENSION}
when: always
needs:
- job: autoreconf
artifacts: true

41
bin/check/named-checkzone.rst
View File

@@ -11,16 +11,18 @@
.. highlight: console
named-checkzone, named-compilezone - zone file validity checking or converting tool
-----------------------------------------------------------------------------------
.. BEWARE: Do not forget to edit also named-compilezone.rst!
.. _man_named-checkzone:
named-checkzone - zone file validation tool
-------------------------------------------
Synopsis
~~~~~~~~
:program:`named-checkzone` [**-d**] [**-h**] [**-j**] [**-q**] [**-v**] [**-c** class] [**-f** format] [**-F** format] [**-J** filename] [**-i** mode] [**-k** mode] [**-m** mode] [**-M** mode] [**-n** mode] [**-l** ttl] [**-L** serial] [**-o** filename] [**-r** mode] [**-s** style] [**-S** mode] [**-t** directory] [**-T** mode] [**-w** directory] [**-D**] [**-W** mode] {zonename} {filename}
:program:`named-compilezone` [**-d**] [**-j**] [**-q**] [**-v**] [**-c** class] [**-C** mode] [**-f** format] [**-F** format] [**-J** filename] [**-i** mode] [**-k** mode] [**-m** mode] [**-n** mode] [**-l** ttl] [**-L** serial] [**-r** mode] [**-s** style] [**-t** directory] [**-T** mode] [**-w** directory] [**-D**] [**-W** mode] {**-o** filename} {zonename} {filename}
Description
~~~~~~~~~~~
@@ -29,13 +31,6 @@ performs the same checks as ``named`` does when loading a zone. This
makes ``named-checkzone`` useful for checking zone files before
configuring them into a name server.
``named-compilezone`` is similar to ``named-checkzone``, but it always
dumps the zone contents to a specified file in a specified format.
It also applies stricter check levels by default, since the
dump output is used as an actual zone file loaded by ``named``.
When manually specified otherwise, the check levels must at least be as
strict as those specified in the ``named`` configuration file.
Options
~~~~~~~
@@ -108,8 +103,7 @@ Options
``-k mode``
This option performs ``check-names`` checks with the specified failure mode.
Possible modes are ``fail`` (the default for ``named-compilezone``),
``warn`` (the default for ``named-checkzone``), and ``ignore``.
Possible modes are ``fail``, ``warn`` (the default), and ``ignore``.
``-l ttl``
This option sets a maximum permissible TTL for the input file. Any record with a
@@ -132,13 +126,11 @@ Options
``-n mode``
This option specifies whether NS records should be checked to see if they are
addresses. Possible modes are ``fail`` (the default for
``named-compilezone``), ``warn`` (the default for ``named-checkzone``),
and ``ignore``.
addresses. Possible modes are ``fail``, ``warn`` (the default), 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``.
the zone output is written to standard output.
``-r mode``
This option checks for records that are treated as different by DNSSEC but are
@@ -150,9 +142,9 @@ Options
``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. For ``named-checkzone``, 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.
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.
``-S mode``
This option checks whether an SRV record refers to a CNAME. Possible modes are
@@ -174,13 +166,12 @@ Options
``named.conf``.
``-D``
This option dumps the zone file in canonical format. This is always enabled for
``named-compilezone``.
This option dumps the zone file in canonical format.
``-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:`1034`). Possible modes are ``warn``
wildcard matching algorithm (:rfc:`4592`). Possible modes are ``warn``
(the default) and ``ignore``.
``zonename``
@@ -198,5 +189,5 @@ and 0 otherwise.
See Also
~~~~~~~~
:manpage:`named(8)`, :manpage:`named-checkconf(8)`, :rfc:`1035`, BIND 9 Administrator Reference
Manual.
:manpage:`named(8)`, :manpage:`named-checkconf(8)`, :manpage:`named-compilezone(8)`,
:rfc:`1035`, BIND 9 Administrator Reference Manual.

195
bin/check/named-compilezone.rst Normal file
View File

@@ -0,0 +1,195 @@
.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
..
.. SPDX-License-Identifier: MPL-2.0
..
.. This Source Code Form is subject to the terms of the Mozilla Public
.. License, v. 2.0. If a copy of the MPL was not distributed with this
.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
..
.. See the COPYRIGHT file distributed with this work for additional
.. information regarding copyright ownership.
.. highlight: console
.. BEWARE: Do not forget to edit also named-checkzone.rst!
.. _man_named-compilezone:
named-compilezone - zone file converting tool
---------------------------------------------
Synopsis
~~~~~~~~
:program:`named-compilezone` [**-d**] [**-h**] [**-j**] [**-q**] [**-v**] [**-c** class] [**-f** format] [**-F** format] [**-J** filename] [**-i** mode] [**-k** mode] [**-m** mode] [**-M** mode] [**-n** mode] [**-l** ttl] [**-L** serial] [**-r** mode] [**-s** style] [**-S** mode] [**-t** directory] [**-T** mode] [**-w** directory] [**-D**] [**-W** mode] {**-o** filename} {zonename} {filename}
Description
~~~~~~~~~~~
``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``.
When manually specified otherwise, the check levels must at least be as
strict as those specified in the ``named`` configuration file.
Options
~~~~~~~
``-d``
This option enables debugging.
``-h``
This option prints the usage summary and exits.
``-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.
``-j``
When loading a zone file, this option tells ``named`` to read the journal if it exists. The journal
file name is assumed to be the zone file name with the
string ``.jnl`` appended.
``-J filename``
When loading the zone file, this option tells ``named`` to read the journal from the given file, if
it exists. This implies ``-j``.
``-c class``
This option specifies the class of the zone. If not specified, ``IN`` is assumed.
``-i mode``
This option performs post-load zone integrity checks. Possible modes are
``full`` (the default), ``full-sibling``, ``local``,
``local-sibling``, and ``none``.
Mode ``full`` checks that MX records refer to A or AAAA records
(both in-zone and out-of-zone hostnames). Mode ``local`` only
checks MX records which refer to in-zone hostnames.
Mode ``full`` checks that SRV records refer to A or AAAA records
(both in-zone and out-of-zone hostnames). Mode ``local`` only
checks SRV records which refer to in-zone hostnames.
Mode ``full`` checks that delegation NS records refer to A or AAAA
records (both in-zone and out-of-zone hostnames). It also checks that
glue address records in the zone match those advertised by the child.
Mode ``local`` only checks NS records which refer to in-zone
hostnames or verifies that some required glue exists, i.e., when the
name server is in a child zone.
Modes ``full-sibling`` and ``local-sibling`` disable sibling glue
checks, but are otherwise the same as ``full`` and ``local``,
respectively.
Mode ``none`` disables the checks.
``-f format``
This option specifies the format of the zone file. Possible formats are
``text`` (the default), and ``raw``.
``-F format``
This option specifies the format of the output file specified. For
``named-checkzone``, this does not have any effect unless it dumps
the zone contents.
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``.
``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
file can only be read by release 9.9.0 or higher. The default is 1.
``-k mode``
This option performs ``check-names`` checks with the specified failure mode.
Possible modes are ``fail`` (the default), ``warn``, and ``ignore``.
``-l ttl``
This option sets a maximum permissible TTL for the input file. Any record with a
TTL higher than this value causes the zone to be rejected. This
is similar to using the ``max-zone-ttl`` option in ``named.conf``.
``-L serial``
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``
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``
This option checks whether a MX record refers to a CNAME. Possible modes are
``fail``, ``warn`` (the default), and ``ignore``.
``-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``.
``-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``
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``
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``.
``-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``.
``-D``
This option dumps the zone file in canonical format. This is always enabled for
``named-compilezone``.
``-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``
This indicates the domain name of the zone being checked.
``filename``
This is the name of the zone file.
Return Values
~~~~~~~~~~~~~
``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.

88
bin/confgen/ddns-confgen.rst Normal file
View File

@@ -0,0 +1,88 @@
.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
..
.. SPDX-License-Identifier: MPL-2.0
..
.. This Source Code Form is subject to the terms of the Mozilla Public
.. License, v. 2.0. If a copy of the MPL was not distributed with this
.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
..
.. See the COPYRIGHT file distributed with this work for additional
.. information regarding copyright ownership.
.. highlight: console
.. BEWARE: Do not forget to edit also tsig-keygen.rst!
.. _man_ddns-confgen:
ddns-confgen - TSIG key generation tool
---------------------------------------
Synopsis
~~~~~~~~
:program:`ddns-confgen` [**-a** algorithm] [**-h**] [**-k** keyname] [**-q**] [**-s** name] [**-z** zone]
Description
~~~~~~~~~~~
``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.
The key name can specified using ``-k`` parameter and defaults to ``ddns-key``.
The generated key is accompanied by configuration text and instructions that
can be used with ``nsupdate`` and ``named`` when setting up dynamic DNS,
including an example ``update-policy`` statement.
(This usage is similar to the ``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
be used from a remote system.
Options
~~~~~~~
``-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``
This option prints a short summary of options and arguments.
``-k keyname``
This option specifies the key name of the DDNS authentication key. The
default is ``ddns-key`` when neither the ``-s`` nor ``-z`` option is
specified; otherwise, the default is ``ddns-key`` as a separate label
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``
This option enables quiet mode, which prints only the key, with no
explanatory text or usage examples. This is essentially identical to
``tsig-keygen``.
``-s name``
This option generates a configuration example to allow dynamic updates
of a single hostname. The example ``named.conf`` text shows how to set
an update policy for the specified name using the "name" nametype. The
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.
``-z zone``
This option generates a configuration example to allow
dynamic updates of a zone. The example ``named.conf`` text shows how
to set an update policy for the specified zone using the "zonesub"
nametype, allowing updates to all subdomain names within that zone.
This option cannot be used with the ``-s`` option.
See Also
~~~~~~~~
:manpage:`nsupdate(1)`, :manpage:`named.conf(5)`, :manpage:`named(8)`, BIND 9 Administrator Reference Manual.

65
bin/confgen/tsig-keygen.rst
View File

@@ -11,39 +11,26 @@
.. highlight: console
tsig-keygen, ddns-confgen - TSIG key generation tool
----------------------------------------------------
.. BEWARE: Do not forget to edit also ddns-confgen.rst!
.. _man_tsig-keygen:
tsig-keygen - TSIG key generation tool
--------------------------------------
Synopsis
~~~~~~~~
:program:`tsig-keygen` [**-a** algorithm] [**-h**] [**-r** randomfile] [name]
:program:`ddns-confgen` [**-a** algorithm] [**-h**] [**-k** keyname] [**-q**] [**-r** randomfile] [**-s** name] [**-z** zone]
:program:`tsig-keygen` [**-a** algorithm] [**-h**] [name]
Description
~~~~~~~~~~~
``tsig-keygen`` and ``ddns-confgen`` are invocation methods for a
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.
``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.
When run as ``tsig-keygen``, 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``.
When run as ``ddns-confgen``, the key name can specified using ``-k``
parameter and defaults to ``ddns-key``. The generated key is accompanied
by configuration text and instructions that can be used with ``nsupdate``
and ``named`` when setting up dynamic DNS, including an example
``update-policy`` statement. (This usage is similar to the ``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
be used from a remote system.
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``.
Options
~~~~~~~
@@ -57,34 +44,6 @@ Options
``-h``
This option prints a short summary of options and arguments.
``-k keyname``
This option specifies the key name of the DDNS authentication key. The
default is ``ddns-key`` when neither the ``-s`` nor ``-z`` option is
specified; otherwise, the default is ``ddns-key`` as a separate label
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`` (``ddns-confgen`` only)
This option enables quiet mode, which prints only the key, with no
explanatory text or usage examples. This is essentially identical to
``tsig-keygen``.
``-s name`` (``ddns-confgen`` only)
This option generates a configuration example to allow dynamic updates
of a single hostname. The example ``named.conf`` text shows how to set
an update policy for the specified name using the "name" nametype. The
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.
``-z zone`` (``ddns-confgen`` only)
This option generates a configuration example to allow
dynamic updates of a zone. The example ``named.conf`` text shows how
to set an update policy for the specified zone using the "zonesub"
nametype, allowing updates to all subdomain names within that zone.
This option cannot be used with the ``-s`` option.
See Also
~~~~~~~~

3
doc/arm/advanced.rst
View File

@@ -417,8 +417,7 @@ email, etc.)
``tsig-keygen`` can also be run as ``ddns-confgen``, in which case its
output includes additional configuration text for setting up dynamic DNS
in ``named``. See :ref:`tsig-keygen, ddns-confgen - TSIG key generation
tool <man_tsig-keygen_ddns-confgen>` for details.
in ``named``. See :ref:`man_ddns-confgen` for details.
Loading a New Key
~~~~~~~~~~~~~~~~~

42
doc/arm/configuration.rst
View File

@@ -155,25 +155,16 @@ output format.
mode, which executes a query for each in a list of several query
lines. All query options are accessible from the command line.
``dig [@server] domain [query-type][query-class][+query-option][-dig-option][%comment]``
The usual simple use of ``dig`` takes the form
``dig @server domain query-type query-class``
For more information and a list of available commands and options,
see the ``dig`` man page.
see :ref:`man_dig`.
``host``
The ``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.
``host [-aCdlnrsTwv][-c class][-N ndots][-t type][-W timeout][-R retries]
[-m flag][-4][-6] hostname [server]``
For more information and a list of available commands and options,
see the ``host`` man page.
see :ref:`man_host`.
``nslookup``
``nslookup`` has two modes: interactive and non-interactive.
@@ -182,17 +173,6 @@ output format.
hosts in a domain. Non-interactive mode is used to print just the
name and requested information for a host or domain.
``nslookup [-option][ [host-to-find]|[-[server]] ]``
Interactive mode is entered when no arguments are given (the default
name server is used) or when the first argument is a hyphen
(``-``) and the second argument is the host name or Internet address of
a name server.
Non-interactive mode is used when the name or Internet address of the
host to be looked up is given as the first argument. The optional
second argument specifies the host name or address of a name server.
Due to its arcane user interface and frequently inconsistent
behavior, we do not recommend the use of ``nslookup``. Use ``dig``
instead.
@@ -209,26 +189,26 @@ server.
The ``named-checkconf`` program checks the syntax of a ``named.conf``
file.
``named-checkconf [-jvz][-t directory][filename]``
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
consistency.
``named-checkzone [-djqvD][-c class][-o output][-t directory][-w directory]
[-k (ignore|warn|fail)][-n (ignore|warn|fail)][-W (ignore|warn)] zone [filename]``
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
This tool is similar to ``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
administrator to control the operation of a name server. If ``rndc`` is run
without any options, it displays a usage message as
follows:
``rndc [-c config][-s server][-p port][-y key] command [command...]``
administrator to control the operation of a name server.
See :ref:`man_rndc` for details of the available ``rndc``
commands.

4
doc/arm/manpages.rst
View File

@@ -15,6 +15,7 @@ Manual Pages
============
.. include:: ../../bin/tools/arpaname.rst
.. include:: ../../bin/confgen/ddns-confgen.rst
.. include:: ../../bin/delv/delv.rst
.. include:: ../../bin/dig/dig.rst
.. include:: ../../bin/dnssec/dnssec-cds.rst
@@ -31,8 +32,8 @@ Manual Pages
.. include:: ../../bin/dig/host.rst
.. include:: ../../bin/tools/mdig.rst
.. include:: ../../bin/check/named-checkconf.rst
.. _man_named-checkzone_named-compilezone:
.. include:: ../../bin/check/named-checkzone.rst
.. include:: ../../bin/check/named-compilezone.rst
.. include:: ../../bin/tools/named-journalprint.rst
.. include:: ../../bin/tools/named-nzd2nzf.rst
.. include:: ../../bin/tools/named-rrchecker.rst
@@ -44,5 +45,4 @@ Manual Pages
.. include:: ../../bin/confgen/rndc-confgen.rst
.. include:: ../../bin/rndc/rndc.conf.rst
.. include:: ../../bin/rndc/rndc.rst
.. _man_tsig-keygen_ddns-confgen:
.. include:: ../../bin/confgen/tsig-keygen.rst

33
doc/man/ddns-confgen.8in
View File

@@ -32,26 +32,19 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
ddns-confgen \- ddns key generation tool
.SH SYNOPSIS
.sp
\fBtsig\-keygen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [\fB\-r\fP randomfile] [name]
.sp
\fBddns\-confgen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [\fB\-k\fP keyname] [\fB\-q\fP] [\fB\-r\fP randomfile] [\fB\-s\fP name] [\fB\-z\fP zone]
\fBddns\-confgen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [\fB\-k\fP keyname] [\fB\-q\fP] [\fB\-s\fP name] [\fB\-z\fP zone]
.SH DESCRIPTION
.sp
\fBtsig\-keygen\fP and \fBddns\-confgen\fP are invocation methods for a
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 \fBrndc\fP command channel.
\fBddns\-confgen\fP 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 \fBrndc\fP command channel.
.sp
When run as \fBtsig\-keygen\fP, 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 \fBtsig\-key\fP\&.
.sp
When run as \fBddns\-confgen\fP, the key name can specified using \fB\-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. (This usage is similar to the \fBrndc\-confgen\fP
command for setting up command\-channel security.)
The key name can specified using \fB\-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.
(This usage is similar to the \fBrndc\-confgen\fP command for setting up
command\-channel security.)
.sp
Note that \fBnamed\fP itself can configure a local DDNS key for use with
\fBnsupdate \-l\fP; it does this when a zone is configured with
@@ -78,12 +71,12 @@ 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.
.TP
.B \fB\-q\fP (\fBddns\-confgen\fP only)
.B \fB\-q\fP
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\&.
.TP
.B \fB\-s name\fP (\fBddns\-confgen\fP only)
.B \fB\-s name\fP
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
@@ -91,7 +84,7 @@ 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.
.TP
.B \fB\-z zone\fP (\fBddns\-confgen\fP only)
.B \fB\-z zone\fP
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"

2
doc/man/ddns-confgen.rst
View File

@@ -11,4 +11,4 @@
:orphan:
.. include:: ../../bin/confgen/tsig-keygen.rst
.. include:: ../../bin/confgen/ddns-confgen.rst

33
doc/man/named-checkzone.1in
View File

@@ -33,21 +33,12 @@ named-checkzone \- zone file validity checking or converting tool
.SH SYNOPSIS
.sp
\fBnamed\-checkzone\fP [\fB\-d\fP] [\fB\-h\fP] [\fB\-j\fP] [\fB\-q\fP] [\fB\-v\fP] [\fB\-c\fP class] [\fB\-f\fP format] [\fB\-F\fP format] [\fB\-J\fP filename] [\fB\-i\fP mode] [\fB\-k\fP mode] [\fB\-m\fP mode] [\fB\-M\fP mode] [\fB\-n\fP mode] [\fB\-l\fP ttl] [\fB\-L\fP serial] [\fB\-o\fP filename] [\fB\-r\fP mode] [\fB\-s\fP style] [\fB\-S\fP mode] [\fB\-t\fP directory] [\fB\-T\fP mode] [\fB\-w\fP directory] [\fB\-D\fP] [\fB\-W\fP mode] {zonename} {filename}
.sp
\fBnamed\-compilezone\fP [\fB\-d\fP] [\fB\-j\fP] [\fB\-q\fP] [\fB\-v\fP] [\fB\-c\fP class] [\fB\-C\fP mode] [\fB\-f\fP format] [\fB\-F\fP format] [\fB\-J\fP filename] [\fB\-i\fP mode] [\fB\-k\fP mode] [\fB\-m\fP mode] [\fB\-n\fP mode] [\fB\-l\fP ttl] [\fB\-L\fP serial] [\fB\-r\fP mode] [\fB\-s\fP style] [\fB\-t\fP directory] [\fB\-T\fP mode] [\fB\-w\fP directory] [\fB\-D\fP] [\fB\-W\fP mode] {\fB\-o\fP filename} {zonename} {filename}
.SH DESCRIPTION
.sp
\fBnamed\-checkzone\fP checks the syntax and integrity of a zone file. It
performs the same checks as \fBnamed\fP does when loading a zone. This
makes \fBnamed\-checkzone\fP useful for checking zone files before
configuring them into a name server.
.sp
\fBnamed\-compilezone\fP is similar to \fBnamed\-checkzone\fP, but it always
dumps the zone contents to a specified file in a specified format.
It also applies stricter check levels by default, since the
dump output is used as an actual zone file loaded by \fBnamed\fP\&.
When manually specified otherwise, the check levels must at least be as
strict as those specified in the \fBnamed\fP configuration file.
.SH OPTIONS
.INDENT 0.0
.TP
@@ -120,8 +111,7 @@ file can only be read by release 9.9.0 or higher. The default is 1.
.TP
.B \fB\-k mode\fP
This option performs \fBcheck\-names\fP checks with the specified failure mode.
Possible modes are \fBfail\fP (the default for \fBnamed\-compilezone\fP),
\fBwarn\fP (the default for \fBnamed\-checkzone\fP), and \fBignore\fP\&.
Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&.
.TP
.B \fB\-l ttl\fP
This option sets a maximum permissible TTL for the input file. Any record with a
@@ -144,13 +134,11 @@ This option checks whether a MX record refers to a CNAME. Possible modes are
.TP
.B \fB\-n mode\fP
This option specifies whether NS records should be checked to see if they are
addresses. Possible modes are \fBfail\fP (the default for
\fBnamed\-compilezone\fP), \fBwarn\fP (the default for \fBnamed\-checkzone\fP),
and \fBignore\fP\&.
addresses. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&.
.TP
.B \fB\-o filename\fP
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\&.
the zone output is written to standard output.
.TP
.B \fB\-r mode\fP
This option checks for records that are treated as different by DNSSEC but are
@@ -162,9 +150,9 @@ 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. For \fBnamed\-checkzone\fP, 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.
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.
.TP
.B \fB\-S mode\fP
This option checks whether an SRV record refers to a CNAME. Possible modes are
@@ -186,13 +174,12 @@ This option instructs \fBnamed\fP to chdir to \fBdirectory\fP, so that relative
\fBnamed.conf\fP\&.
.TP
.B \fB\-D\fP
This option dumps the zone file in canonical format. This is always enabled for
\fBnamed\-compilezone\fP\&.
This option dumps the zone file in canonical format.
.TP
.B \fB\-W mode\fP
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 1034\fP). Possible modes are \fBwarn\fP
wildcard matching algorithm (\fI\%RFC 4592\fP). Possible modes are \fBwarn\fP
(the default) and \fBignore\fP\&.
.TP
.B \fBzonename\fP
@@ -207,8 +194,8 @@ This is the name of the zone file.
and 0 otherwise.
.SH SEE ALSO
.sp
\fBnamed(8)\fP, \fBnamed\-checkconf(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

35
doc/man/named-compilezone.1in
View File

@@ -32,19 +32,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
named-compilezone \- zone file validity checking or converting tool
.SH SYNOPSIS
.sp
\fBnamed\-checkzone\fP [\fB\-d\fP] [\fB\-h\fP] [\fB\-j\fP] [\fB\-q\fP] [\fB\-v\fP] [\fB\-c\fP class] [\fB\-f\fP format] [\fB\-F\fP format] [\fB\-J\fP filename] [\fB\-i\fP mode] [\fB\-k\fP mode] [\fB\-m\fP mode] [\fB\-M\fP mode] [\fB\-n\fP mode] [\fB\-l\fP ttl] [\fB\-L\fP serial] [\fB\-o\fP filename] [\fB\-r\fP mode] [\fB\-s\fP style] [\fB\-S\fP mode] [\fB\-t\fP directory] [\fB\-T\fP mode] [\fB\-w\fP directory] [\fB\-D\fP] [\fB\-W\fP mode] {zonename} {filename}
.sp
\fBnamed\-compilezone\fP [\fB\-d\fP] [\fB\-j\fP] [\fB\-q\fP] [\fB\-v\fP] [\fB\-c\fP class] [\fB\-C\fP mode] [\fB\-f\fP format] [\fB\-F\fP format] [\fB\-J\fP filename] [\fB\-i\fP mode] [\fB\-k\fP mode] [\fB\-m\fP mode] [\fB\-n\fP mode] [\fB\-l\fP ttl] [\fB\-L\fP serial] [\fB\-r\fP mode] [\fB\-s\fP style] [\fB\-t\fP directory] [\fB\-T\fP mode] [\fB\-w\fP directory] [\fB\-D\fP] [\fB\-W\fP mode] {\fB\-o\fP filename} {zonename} {filename}
\fBnamed\-compilezone\fP [\fB\-d\fP] [\fB\-h\fP] [\fB\-j\fP] [\fB\-q\fP] [\fB\-v\fP] [\fB\-c\fP class] [\fB\-f\fP format] [\fB\-F\fP format] [\fB\-J\fP filename] [\fB\-i\fP mode] [\fB\-k\fP mode] [\fB\-m\fP mode] [\fB\-M\fP mode] [\fB\-n\fP mode] [\fB\-l\fP ttl] [\fB\-L\fP serial] [\fB\-r\fP mode] [\fB\-s\fP style] [\fB\-S\fP mode] [\fB\-t\fP directory] [\fB\-T\fP mode] [\fB\-w\fP directory] [\fB\-D\fP] [\fB\-W\fP mode] {\fB\-o\fP filename} {zonename} {filename}
.SH DESCRIPTION
.sp
\fBnamed\-checkzone\fP checks the syntax and integrity of a zone file. It
performs the same checks as \fBnamed\fP does when loading a zone. This
makes \fBnamed\-checkzone\fP useful for checking zone files before
configuring them into a name server.
.sp
\fBnamed\-compilezone\fP is similar to \fBnamed\-checkzone\fP, but it always
dumps the zone contents to a specified file in a specified format.
It also applies stricter check levels by default, since the
\fBnamed\-compilezone\fP 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 \fBnamed\fP\&.
When manually specified otherwise, the check levels must at least be as
strict as those specified in the \fBnamed\fP configuration file.
@@ -120,8 +113,7 @@ file can only be read by release 9.9.0 or higher. The default is 1.
.TP
.B \fB\-k mode\fP
This option performs \fBcheck\-names\fP checks with the specified failure mode.
Possible modes are \fBfail\fP (the default for \fBnamed\-compilezone\fP),
\fBwarn\fP (the default for \fBnamed\-checkzone\fP), and \fBignore\fP\&.
Possible modes are \fBfail\fP (the default), \fBwarn\fP, and \fBignore\fP\&.
.TP
.B \fB\-l ttl\fP
This option sets a maximum permissible TTL for the input file. Any record with a
@@ -144,9 +136,8 @@ This option checks whether a MX record refers to a CNAME. Possible modes are
.TP
.B \fB\-n mode\fP
This option specifies whether NS records should be checked to see if they are
addresses. Possible modes are \fBfail\fP (the default for
\fBnamed\-compilezone\fP), \fBwarn\fP (the default for \fBnamed\-checkzone\fP),
and \fBignore\fP\&.
addresses. Possible modes are \fBfail\fP (the default), \fBwarn\fP, and
\fBignore\fP\&.
.TP
.B \fB\-o filename\fP
This option writes the zone output to \fBfilename\fP\&. If \fBfilename\fP is \fB\-\fP, then
@@ -162,9 +153,7 @@ 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. For \fBnamed\-checkzone\fP, 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.
suitable for editing by hand.
.TP
.B \fB\-S mode\fP
This option checks whether an SRV record refers to a CNAME. Possible modes are
@@ -192,7 +181,7 @@ This option dumps the zone file in canonical format. This is always enabled for
.B \fB\-W mode\fP
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 1034\fP). Possible modes are \fBwarn\fP
wildcard matching algorithm (\fI\%RFC 4592\fP). Possible modes are \fBwarn\fP
(the default) and \fBignore\fP\&.
.TP
.B \fBzonename\fP
@@ -203,12 +192,12 @@ This is the name of the zone file.
.UNINDENT
.SH RETURN VALUES
.sp
\fBnamed\-checkzone\fP returns an exit status of 1 if errors were detected
\fBnamed\-compilezone\fP returns an exit status of 1 if errors were detected
and 0 otherwise.
.SH SEE ALSO
.sp
\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fI\%RFC 1035\fP, BIND 9 Administrator Reference
Manual.
\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-checkzone(8)\fP,
\fI\%RFC 1035\fP, BIND 9 Administrator Reference Manual.
.SH AUTHOR
Internet Systems Consortium
.SH COPYRIGHT

2
doc/man/named-compilezone.rst
View File

@@ -11,4 +11,4 @@
:orphan:
.. include:: ../../bin/check/named-checkzone.rst
.. include:: ../../bin/check/named-compilezone.rst

57
doc/man/tsig-keygen.8in
View File

@@ -32,32 +32,15 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
tsig-keygen \- TSIG key generation tool
.SH SYNOPSIS
.sp
\fBtsig\-keygen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [\fB\-r\fP randomfile] [name]
.sp
\fBddns\-confgen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [\fB\-k\fP keyname] [\fB\-q\fP] [\fB\-r\fP randomfile] [\fB\-s\fP name] [\fB\-z\fP zone]
\fBtsig\-keygen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [name]
.SH DESCRIPTION
.sp
\fBtsig\-keygen\fP and \fBddns\-confgen\fP are invocation methods for a
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 \fBrndc\fP command channel.
\fBtsig\-keygen\fP 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 \fBrndc\fP command channel.
.sp
When run as \fBtsig\-keygen\fP, 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 \fBtsig\-key\fP\&.
.sp
When run as \fBddns\-confgen\fP, the key name can specified using \fB\-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. (This usage is similar to the \fBrndc\-confgen\fP
command for setting up command\-channel security.)
.sp
Note that \fBnamed\fP itself can configure a local DDNS key for use with
\fBnsupdate \-l\fP; it does this when a zone is configured with
\fBupdate\-policy local;\fP\&. \fBddns\-confgen\fP is only needed when a more
elaborate configuration is required: for instance, if \fBnsupdate\fP is to
be used from a remote system.
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 \fBtsig\-key\fP\&.
.SH OPTIONS
.INDENT 0.0
.TP
@@ -69,34 +52,6 @@ case\-insensitive, and the "hmac\-" prefix may be omitted.
.TP
.B \fB\-h\fP
This option prints a short summary of options and arguments.
.TP
.B \fB\-k keyname\fP
This option specifies the key name of the DDNS authentication key. The
default is \fBddns\-key\fP when neither the \fB\-s\fP nor \fB\-z\fP option is
specified; otherwise, the default is \fBddns\-key\fP as a separate label
followed by the argument of the option, e.g., \fBddns\-key.example.com.\fP
The key name must have the format of a valid domain name, consisting of
letters, digits, hyphens, and periods.
.TP
.B \fB\-q\fP (\fBddns\-confgen\fP only)
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\&.
.TP
.B \fB\-s name\fP (\fBddns\-confgen\fP only)
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.
.TP
.B \fB\-z zone\fP (\fBddns\-confgen\fP only)
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.
.UNINDENT
.SH SEE ALSO
.sp