Commit 78af7e54 authored by Suzanne Goldlust's avatar Suzanne Goldlust Committed by Ondřej Surý
Browse files

Text edits to manual paages

This commit updates the wording in following man pages:

* ddns-confgen.rst
* delv.rst
* dig.rst
* dnssec-dsfromkey.rst
* dnssec-importkey.rst
* dnssec-keyfromlabel.rst
* dnssec-keygen.rst
* dnssec-revoke.rst
* dnssec-settime.rst
* dnssec-signzone.rst
* dnssec-verify.rst
* dnstap-read.rst
* filter-aaaa.rst
* host.rst
* mdig.rst
* named-checkconf.rst
* named-checkzone.rst
* named-nzd2nzf.rst
* named.conf.rst
* named.rst
* nsec3hash.rst
* nsupdate.rst
* pkcs11-destroy.rst
* pkcs11-keygen.rst
* pkcs11-list.rst
* pkcs11-tokens.rst
* rndc-confgen.rst
* rndc.rst
parent a8faf4f7
......@@ -35,62 +35,62 @@ Description
~~~~~~~~~~~
``named-checkconf`` checks the syntax, but not the semantics, of a
``named`` configuration file. The file is parsed and checked for syntax
errors, along with all files included by it. If no file is specified,
``named`` configuration file. The file, along with all files included by it, is parsed and checked for syntax
errors. If no file is specified,
``/etc/named.conf`` is read by default.
Note: files that ``named`` reads in separate parser contexts, such as
``rndc.key`` and ``bind.keys``, are not automatically read by
``named-checkconf``. Configuration errors in these files may cause
``named`` to fail to run, even if ``named-checkconf`` was successful.
``named-checkconf`` can be run on these files explicitly, however.
However, ``named-checkconf`` can be run on these files explicitly.
Options
~~~~~~~
**-h**
Print the usage summary and exit.
``-h``
This option prints the usage summary and exits.
**-j**
When loading a zonefile read the journal if it exists.
``-j``
When loading a zonefile, this option instructs ``named`` to read the journal if it exists.
**-l**
List all the configured zones. Each line of output contains the zone
``-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**
Check "core" configuration only. This suppresses the loading of
``-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**
Ignore warnings on deprecated options.
``-i``
This option ignores warnings on deprecated options.
**-p**
Print out the ``named.conf`` and included files in canonical form if
``-p``
This option prints out the ``named.conf`` and included files in canonical form if
no errors were detected. See also the ``-x`` option.
**-t** directory
Chroot to ``directory`` so that include directives in the
``-t directory``
This option instructs ``named`` to chroot to ``directory``, so that ``include`` directives in the
configuration file are processed as if run by a similarly chrooted
``named``.
**-v**
Print the version of the ``named-checkconf`` program and exit.
``-v``
This option prints the version of the ``named-checkconf`` program and exits.
**-x**
When printing the configuration files in canonical form, obscure
``-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 ``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``.
**-z**
Perform a test load of all zones of type ``primary`` found in ``named.conf``.
``-z``
This option performs a test load of all zones of type ``primary`` found in ``named.conf``.
filename
The name of the configuration file to be checked. If not specified,
``filename``
This indicates the name of the configuration file to be checked. If not specified,
it defaults to ``/etc/named.conf``.
Return Values
......
......@@ -43,163 +43,164 @@ 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.
Additionally, it applies stricter check levels by default, since the
dump output will be used as an actual zone file loaded by ``named``.
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
~~~~~~~
**-d**
Enable debugging.
``-d``
This option enables debugging.
**-h**
Print the usage summary and exit.
``-h``
This option prints the usage summary and exits.
**-q**
Quiet mode - exit code only.
``-q``
This option sets quiet mode, which only sets an exit code to indicate
successful or failed completion.
**-v**
Print the version of the ``named-checkzone`` program and exit.
``-v``
This option prints the version of the ``named-checkzone`` program and exits.
**-j**
When loading a zone file, read the journal if it exists. The journal
file name is assumed to be the zone file name appended with the
string ``.jnl``.
``-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 read the journal from the given file, if
it exists. (Implies -j.)
``-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
Specify the class of the zone. If not specified, "IN" is assumed.
``-c class``
This option specifies the class of the zone. If not specified, ``IN`` is assumed.
**-i** mode
Perform post-load zone integrity checks. Possible modes are
``"full"`` (default), ``"full-sibling"``, ``"local"``,
``"local-sibling"`` and ``"none"``.
``-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 record
(both in-zone and out-of-zone hostnames). Mode ``"local"`` only
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 record
(both in-zone and out-of-zone hostnames). Mode ``"local"`` only
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
record (both in-zone and out-of-zone hostnames). It also checks that
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 that some required glue exists, that is when the
nameserver is in a child zone.
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.
Mode ``"full-sibling"`` and ``"local-sibling"`` disable sibling glue
checks but are otherwise the same as ``"full"`` and ``"local"``
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.
Mode ``none`` disables the checks.
**-f** format
Specify the format of the zone file. Possible formats are ``"text"``
(default), ``"raw"``, and ``"map"``.
``-f format``
This option specifies the format of the zone file. Possible formats are ``text``
(the default), ``raw``, and ``map``.
**-F** format
Specify the format of the output file specified. For
``named-checkzone``, this does not cause any effects unless it dumps
``-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"`` (default), which is the standard
textual representation of the zone, and ``"map"``, ``"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 be read by release 9.9.0 or
higher; the default is 1.
**-k** mode
Perform ``"check-names"`` checks with the specified failure mode.
Possible modes are ``"fail"`` (default for ``named-compilezone``),
``"warn"`` (default for ``named-checkzone``) and ``"ignore"``.
**-l** ttl
Sets a maximum permissible TTL for the input file. Any record with a
TTL higher than this value will cause the zone to be rejected. This
Possible formats are ``text`` (the default), which is the standard
textual representation of the zone, and ``map``, ``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 for ``named-compilezone``),
``warn`` (the default for ``named-checkzone``), 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" or "map" format, set the "source
serial" value in the header to the specified serial number. (This is
expected to be used primarily for testing purposes.)
**-m** mode
Specify whether MX records should be checked to see if they are
addresses. Possible modes are ``"fail"``, ``"warn"`` (default) and
``"ignore"``.
**-M** mode
Check if a MX record refers to a CNAME. Possible modes are
``"fail"``, ``"warn"`` (default) and ``"ignore"``.
**-n** mode
Specify whether NS records should be checked to see if they are
addresses. Possible modes are ``"fail"`` (default for
``named-compilezone``), ``"warn"`` (default for ``named-checkzone``)
and ``"ignore"``.
**-o** filename
Write zone output to ``filename``. If ``filename`` is ``-`` then
write to standard out. This is mandatory for ``named-compilezone``.
**-r** mode
Check for records that are treated as different by DNSSEC but are
semantically equal in plain DNS. Possible modes are ``"fail"``,
``"warn"`` (default) and ``"ignore"``.
**-s** style
Specify the style of the dumped zone file. Possible styles are
``"full"`` (default) and ``"relative"``. The full format is most
suitable for processing automatically by a separate script. On the
other hand, the relative format is more human-readable and is thus
suitable for editing by hand. For ``named-checkzone`` this does not
cause any effects unless it dumps the zone contents. It also does not
``-L serial``
When compiling a zone to ``raw`` or ``map`` 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 for
``named-compilezone``), ``warn`` (the default for ``named-checkzone``),
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. 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.
**-S** mode
Check if a SRV record refers to a CNAME. Possible modes are
``"fail"``, ``"warn"`` (default) and ``"ignore"``.
``-S mode``
This option checks whether an SRV record refers to a CNAME. Possible modes are
``fail``, ``warn`` (the default), and ``ignore``.
**-t** directory
Chroot to ``directory`` so that include directives in the
``-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
Check if Sender Policy Framework (SPF) records exist and issues a
``-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"`` (default), ``"ignore"``.
modes are ``warn`` (the default) and ``ignore``.
**-w** directory
chdir to ``directory`` so that relative filenames in master file
$INCLUDE directives work. This is similar to the directory clause in
``-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**
Dump zone file in canonical format. This is always enabled for
``-D``
This option dumps the zone file in canonical format. This is always enabled for
``named-compilezone``.
**-W** mode
Specify whether to check for non-terminal wildcards. Non-terminal
``-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"``
(default) and ``"ignore"``.
wildcard matching algorithm (:rfc:`1034`). Possible modes are ``warn``
(the default) and ``ignore``.
zonename
The domain name of the zone being checked.
``zonename``
This indicates the domain name of the zone being checked.
filename
The name of the zone file.
``filename``
This is the name of the zone file.
Return Values
~~~~~~~~~~~~~
......
......@@ -41,17 +41,17 @@ 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 which will be used as the name of the generated key. If no
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 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 similar to the ``rndc-confgen``
command for setting up command channel security.)
``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
``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.
......@@ -59,40 +59,40 @@ be used from a remote system.
Options
~~~~~~~
**-a** algorithm
Specifies the algorithm to use for the TSIG key. Available choices
are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384 and
``-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**
Prints a short summary of options and arguments.
``-h``
This option prints a short summary of options and arguments.
**-k** keyname
Specifies the key name of the DDNS authentication key. The default is
``-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.
letters, digits, hyphens, and periods.
**-q**
(``ddns-confgen`` only.) Quiet mode: Print only the key, with no
explanatory text or usage examples; This is essentially identical to
``-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.) Generate configuration example to allow
``-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
"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.) Generate configuration example to allow
dynamic updates of a zone: The example ``named.conf`` text shows how
``-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.
......
......@@ -41,79 +41,75 @@ 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
``controls`` statement altogether.
Arguments
~~~~~~~~~
Options
~~~~~~~
**-a**
Do automatic ``rndc`` configuration. This creates a file ``rndc.key``
in ``/etc`` (or whatever ``sysconfdir`` was specified as when BIND
``-a``
This option sets automatic ``rndc`` configuration, which creates a file ``rndc.key``
in ``/etc`` (or a different ``sysconfdir`` specified when BIND
was built) that is read by both ``rndc`` and ``named`` on startup.
The ``rndc.key`` file defines a default command channel and
authentication key allowing ``rndc`` to communicate with ``named`` on
the local host with no further configuration.
Running ``rndc-confgen -a`` allows BIND 9 and ``rndc`` to be used as
drop-in replacements for BIND 8 and ``ndc``, with no changes to the
existing BIND 8 ``named.conf`` file.
If a more elaborate configuration than that generated by
``rndc-confgen -a`` is required, for example if rndc is to be used
remotely, you should run ``rndc-confgen`` without the ``-a`` option
and set up a ``rndc.conf`` and ``named.conf`` as directed.
remotely, run ``rndc-confgen`` without the ``-a`` option
and set up ``rndc.conf`` and ``named.conf`` as directed.
**-A** algorithm
Specifies the algorithm to use for the TSIG key. Available choices
are: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384 and
``-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
Specifies the size of the authentication key in bits. Must be between
``-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
Used with the ``-a`` option to specify an alternate location for
``-c keyfile``
This option is used with the ``-a`` option to specify an alternate location for
``rndc.key``.
**-h**
Prints a short summary of the options and arguments to
``-h``
This option prints a short summary of the options and arguments to
``rndc-confgen``.
**-k** keyname
Specifies the key name of the rndc authentication key. This must be a
``-k keyname``
This option specifies the key name of the ``rndc`` authentication key. This must be a
valid domain name. The default is ``rndc-key``.
**-p** port
Specifies the command channel port where ``named`` listens for
``-p port``
This option specifies the command channel port where ``named`` listens for
connections from ``rndc``. The default is 953.
**-q**
Omits printing written path in automatic configuration mode.
``-q``
This option prevets printing the written path in automatic configuration mode.
**-s** address
Specifies the IP address where ``named`` listens for command channel
``-s address``
This option specifies the IP address where ``named`` listens for command-channel
connections from ``rndc``. The default is the loopback address
127.0.0.1.
**-t** chrootdir
Used with the ``-a`` option to specify a directory where ``named``
will run chrooted. An additional copy of the ``rndc.key`` will be
written relative to this directory so that it will be found by the
``-t chrootdir``
This option is used with the ``-a`` option to specify a directory where ``named``
runs chrooted. An additional copy of the ``rndc.key`` is
written relative to this directory, so that it is found by the
chrooted ``named``.
**-u** user
Used with the ``-a`` option to set the owner of the ``rndc.key`` file
generated. If ``-t`` is also specified only the file in the chroot
``-u user``
This option is used with the ``-a`` option to set the owner of the generated ``rndc.key`` file.
If ``-t`` is also specified, only the file in the chroot
area has its owner changed.
Examples
~~~~~~~~
To allow ``rndc`` to be used with no manual configuration, run
To allow ``rndc`` to be used with no manual configuration, run:
``rndc-confgen -a``
To print a sample ``rndc.conf`` file and corresponding ``controls`` and
``key`` statements to be manually inserted into ``named.conf``, run
To print a sample ``rndc.conf`` file and the corresponding ``controls`` and
``key`` statements to be manually inserted into ``named.conf``, run:
``rndc-confgen``
......
......@@ -43,15 +43,15 @@ Description
``delv`` is a tool for sending DNS queries and validating the results,
using the same internal resolver and validator logic as ``named``.
``delv`` will send to a specified name server all queries needed to
``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, and
requested query, subsequent queries to follow CNAME or DNAME chains,
queries for DNSKEY, and DS records to establish a chain of trust for
DNSSEC validation. It does not perform iterative resolution, but
simulates the behavior of a name server configured for DNSSEC validating
and forwarding.
By default, responses are validated using built-in DNSSEC trust anchor
By default, responses are validated using the built-in DNSSEC trust anchor
for the root zone ("."). Records returned by ``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
......@@ -59,13 +59,13 @@ in detail. Because ``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`` will try
Unless it is told to query a specific name server, ``delv`` tries
each of the servers listed in ``/etc/resolv.conf``. If no usable server
addresses are found, ``delv`` will send queries to the localhost
addresses are found, ``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`` will
perform an NS query for "." (the root zone).
When no command-line arguments or options are given, ``delv``
performs an NS query for "." (the root zone).
Simple Usage
~~~~~~~~~~~~
......@@ -89,109 +89,109 @@ where:
If no ``server`` argument is provided, ``delv`` consults
``/etc/resolv.conf``; if an address is found there, it queries the
name server at that address. If either of the ``-4`` or ``-6``
options are in use, then only addresses for the corresponding
transport will be tried. If no usable addresses are found, ``delv``
will send queries to the localhost addresses (127.0.0.1 for IPv4, ::1
options is in use, then only addresses for the corresponding
transport are tried. If no usable addresses are found, ``delv``
sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1
for IPv6).
``name``
is the domain name to be looked up.
``type``
indicates what type of query is required MDASH ANY, A, MX, etc.
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`` will perform a lookup for an A record.
supplied, ``delv`` performs a lookup for an A record.
Options
~~~~~~~
**-a** anchor-file
Specifies a file from which to read DNSSEC trust anchors. The default
``-a anchor-file``
This option specifies a file from which to read DNSSEC trust anchors. The default
is ``/etc/bind.keys``, which is included with BIND 9 and contains one
or more trust anchors for the root zone (".").