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 '1915-edits-to-man-pages-for-bind-arm' into 'main'

Browse source 
Resolve "Edits to man pages for BIND ARM"

Closes #1915

See merge request isc-projects/bind9!3644
This commit is contained in:
Ondřej Surý 2020-07-02 08:19:07 +00:00
commit a8faf4f7cb
11 changed files with 665 additions and 646 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -29,7 +29,7 @@ dnssec-cds - change DS records for a child zone based on CDS/CDNSKEY
Synopsis
~~~~~~~~
:program:`dnssec-cds` [**-a** alg...] [**-c** class] [**-D**] {**-d** dsset-file} {**-f** child-file} [**-i** [extension]] [**-s** start-time] [**-T** ttl] [**-u**] [**-v** level] [**-V**] {domain}
:program:`dnssec-cds` [**-a** alg...] [**-c** class] [**-D**] {**-d** dsset-file} {**-f** child-file} [**-i**[extension]] [**-s** start-time] [**-T** ttl] [**-u**] [**-v** level] [**-V**] {domain}
Description
~~~~~~~~~~~
@ -38,8 +38,8 @@ The ``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; by polling periodically with ``dnssec-cds``, the
parent can keep the DS records up to date and enable automatic rolling
its key-signing keys (KSKs); by polling periodically with ``dnssec-cds``, the
parent can keep the DS records up-to-date and enable automatic rolling
of KSKs.
Two input files are required. The ``-f child-file`` option specifies a
@ -52,12 +52,12 @@ output of a previous run of ``dnssec-cds``.
The ``dnssec-cds`` command uses special DNSSEC validation logic
specified by :rfc:`7344`. It requires that the CDS and/or CDNSKEY records
are validly signed by a key represented in the existing DS records. This
will typically be the pre-existing key-signing key (KSK).
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``. This time is obtained from the modification time of the
``dnssec-cds``. Their age is obtained from the modification time of the
``dsset-`` file, or from the ``-s`` option.
To protect against breaking the delegation, ``dnssec-cds`` ensures that
@ -67,103 +67,104 @@ type.
By default, replacement DS records are written to the standard output;
with the ``-i`` option the input file is overwritten in place. The
replacement DS records will be 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 go insecure.
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!
.. warning::
Be careful not to delete the DS records when ``dnssec-cds`` fails!
Alternatively, ``dnssec-cds -u`` writes an ``nsupdate`` script to the
standard output. You can use the ``-u`` and ``-i`` options together to
standard output. The ``-u`` and ``-i`` options can be used together to
maintain a ``dsset-`` file as well as emit an ``nsupdate`` script.
Options
~~~~~~~
**-a** algorithm
Specify a digest algorithm to use when converting CDNSKEY records to
``-a algorithm``
This option specifies a digest algorithm to use when converting CDNSKEY records to
DS records. This option can be repeated, so that multiple DS records
are created for each CDNSKEY record. This option has no effect when
using CDS 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
are case-insensitive, and the hyphen may be omitted. If no algorithm
is specified, the default is SHA-256.
**-c** class
Specifies the DNS class of the zones.
``-c class``
This option specifies the DNS class of the zones.
**-D**
Generate DS records from CDNSKEY records if both CDS and CDNSKEY
``-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
Location of the parent DS records. The path can be the name of a file
containing the DS records, or if it is a directory, ``dnssec-cds``
``-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``
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.
**-f** child-file
File containing the child's CDS and/or CDNSKEY records, plus its
DNSKEY records and the covering RRSIG records so that they can be
``-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.
The examples below describe how to generate this file.
**-iextension**
Update the ``dsset-`` file in place, instead of writing DS records to
``-iextension``
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 you
provide no extension then the old ``dsset-`` is discarded. If an
There must be no space between the ``-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.
To protect against replay attacks, the modification time of the
``dsset-`` file is set to match the signature inception time of the
child records, provided that is later than the file's current
child records, provided that it is later than the file's current
modification time.
**-s** start-time
Specify the date and time after which RRSIG records become
acceptable. This can be either an absolute or relative time. An
``-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
notation; 20170827133700 denotes 13:37:00 UTC on August 27th, 2017. A
time relative to the ``dsset-`` file is indicated with -N, which is N
time relative to the ``dsset-`` file is indicated with ``-N``, which is N
seconds before the file modification time. A time relative to the
current time is indicated with now+N.
current time is indicated with ``now+N``.
If no start-time is specified, the modification time of the
``dsset-`` file is used.
**-T** ttl
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
then the new DS records also have no explicit TTL.
``-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**
Write an ``nsupdate`` script to the standard output, instead of
printing the new DS reords. The output will be empty if no change is
``-u``
This option writes an ``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, either in the
original ``dsset-`` file, or with the ``-T`` option, or using the
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.
**-V**
Print version information.
``-V``
This option prints version information.
**-v** level
Sets the debugging level. Level 1 is intended to be usefully verbose
``-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.
domain
The name of the delegation point / child zone apex.
``domain``
This indicates the name of the delegation point/child zone apex.
Exit Status
~~~~~~~~~~~
@ -171,17 +172,17 @@ Exit Status
The ``dnssec-cds`` command exits 0 on success, or non-zero if an error
occurred.
In the success case, the DS records might or might not need to be
If successful, the DS records may or may not need to be
changed.
Examples
~~~~~~~~
Before running ``dnssec-signzone``, you can ensure that the delegations
Before running ``dnssec-signzone``, ensure that the delegations
are up-to-date by running ``dnssec-cds`` on every ``dsset-`` file.
To fetch the child records required by ``dnssec-cds`` you can invoke
``dig`` as in the script below. It's okay if the ``dig`` fails since
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.
::
@ -193,10 +194,10 @@ To fetch the child records required by ``dnssec-cds`` you can invoke
dnssec-cds -i -f /dev/stdin -d $f $d
done
When the parent zone is automatically signed by ``named``, you can use
``dnssec-cds`` with ``nsupdate`` to maintain a delegation as follows.
When the parent zone is automatically signed by ``named``,
``dnssec-cds`` can be used with ``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 keeps the replay attack
validate the parent DS records, and it maintains the replay attack
protection time.
::

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

@ -34,11 +34,11 @@ Synopsis
Description
~~~~~~~~~~~
``dnssec-keyfromlabel`` generates a key pair of files that referencing a
``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
key material is stored within the HSM, and the actual signing takes
key material is stored within the HSM and the actual signing takes
place there.
The ``name`` of the key is specified on the command line. This must
@ -47,194 +47,194 @@ match the name of the zone for which the key is being generated.
Options
~~~~~~~
**-a** algorithm
Selects the cryptographic algorithm. The value of ``algorithm`` must
``-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.
ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448.
If no algorithm is specified, then RSASHA1 will be used by default,
If no algorithm is specified, RSASHA1 is used by default
unless the ``-3`` option is specified, in which case NSEC3RSASHA1
will be used instead. (If ``-3`` is used and an algorithm is
specified, that algorithm will be checked for compatibility with
is used instead. (If ``-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
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``
option, then NSEC3RSASHA1 will be used instead.
option, then NSEC3RSASHA1 is used instead.
As of BIND 9.12.0, this option is mandatory except when using the
``-S`` option (which copies the algorithm from the predecessory key).
Since BIND 9.12.0, this option is mandatory except when using the
``-S`` option, which copies the algorithm from the predecessory key.
Previously, the default for newly generated keys was RSASHA1.
**-3**
Use an NSEC3-capable algorithm to generate a DNSSEC key. If this
``-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 will be used; for example,
versions, then the NSEC3 version is used; for example,
``dnssec-keygen -3a RSASHA1`` specifies the NSEC3RSASHA1 algorithm.
**-E** engine
Specifies the cryptographic hardware to use.
``-E engine``
This option specifies the cryptographic hardware to use.
When BIND is built with OpenSSL PKCS#11 support, this defaults to the
string "pkcs11", which identifies an OpenSSL engine that can drive a
When BIND 9 is built with OpenSSL PKCS#11 support, this defaults to the
string ``pkcs11``, which identifies an OpenSSL engine that can drive a
cryptographic accelerator or hardware service module. When BIND is
built with native PKCS#11 cryptography (--enable-native-pkcs11), it
built with native PKCS#11 cryptography (``--enable-native-pkcs11``), it
defaults to the path of the PKCS#11 provider library specified via
"--with-pkcs11".
``--with-pkcs11``.
**-l** label
Specifies the label for a key pair in the crypto hardware.
``-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
an arbitrary string that identifies a particular key. It may be
preceded by an optional OpenSSL engine name, followed by a colon, as
in "pkcs11:keylabel".
in ``pkcs11:keylabel``.
When BIND 9 is built with native PKCS#11 support, the label is a
PKCS#11 URI string in the format
"pkcs11:``keyword``\ =value[;\ ``keyword``\ =value;...]" Keywords
include "token", which identifies the HSM; "object", which identifies
the key; and "pin-source", which identifies a file from which the
HSM's PIN code can be obtained. The label will be stored in the
on-disk "private" file.
``pkcs11:keyword\ =value[;\ keyword\ =value;...]``. Keywords
include ``token``, which identifies the HSM; ``object``, which identifies
the key; and ``pin-source``, which identifies a file from which the
HSM's PIN code can be obtained. The label is stored in the
on-disk ``private`` file.
If the label contains a ``pin-source`` field, tools using the
generated key files will be able to use the HSM for signing and other
generated key files are able to use the HSM for signing and other
operations without any need for an operator to manually enter a PIN.
Note: Making the HSM's PIN accessible in this manner may reduce the
security advantage of using an HSM; be sure this is what you want to
do before making use of this feature.
security advantage of using an HSM; use caution
when using this feature.
**-n** nametype
Specifies the owner type of the key. The value of ``nametype`` must
``-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.
with a user (KEY)), or OTHER (DNSKEY). These values are
case-insensitive.
**-C**
Compatibility mode: generates an old-style key, without any metadata.
By default, ``dnssec-keyfromlabel`` will include the key's creation
date in the metadata stored with the private key, and other dates may
be set there as well (publication date, activation date, etc). Keys
``-C``
This option enables compatibility mode, which generates an old-style key, without any metadata.
By default, ``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.
**-c** class
Indicates that the DNS record containing the key should have the
``-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
Set the specified flag in the flag field of the KEY/DNSKEY record.
The only recognized flags are KSK (Key Signing Key) and REVOKE.
``-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**
Generate a key, but do not publish it or sign with it. This option is
incompatible with -P and -A.
``-G``
This option generates a key, but does not publish it or sign with it. This option is
incompatible with ``-P`` and ``-A``.
**-h**
Prints a short summary of the options and arguments to
``-h``
This option prints a short summary of the options and arguments to
``dnssec-keyfromlabel``.
**-K** directory
Sets the directory in which the key files are to be written.
``-K directory``
This option sets the directory in which the key files are to be written.
**-k**
Generate KEY records rather than DNSKEY records.
``-k``
This option generates KEY records rather than DNSKEY records.
**-L** ttl
Sets the default TTL to use for this key when it is converted into a
DNSKEY RR. If the key is imported into a zone, this is the TTL that
will be used for it, unless there was already a DNSKEY RRset in
``-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
Sets the protocol value for the key. The protocol is a number between
``-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
Generate a key as an explicit successor to an existing key. The name,
algorithm, size, and type of the key will be set to match the
predecessor. The activation date of the new key will be set to the
inactivation date of the existing one. The publication date will be
``-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.
**-t** type
Indicates the use of the key. ``type`` must be one of AUTHCONF,
``-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 the ability to encrypt
to the ability to authenticate data, and CONF to the ability to encrypt
data.
**-v** level
Sets the debugging level.
``-v level``
This option sets the debugging level.
**-V**
Prints version information.
``-V``
This option prints version information.
**-y**
Allows DNSSEC key files to be generated even if the key ID would
``-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 use if you are sure you won't be
using :rfc:`5011` trust anchor maintenance with either of the keys
being revoked. (This is only safe to enable if
:rfc:`5011` trust anchor maintenance is not used with either of the keys
involved.)
Timing Options
~~~~~~~~~~~~~~
Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the
argument begins with a '+' or '-', it is interpreted as an offset from
argument begins with a ``+`` or ``-``, it is interpreted as an offset from
the present time. For convenience, if such an offset is followed by one
of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the offset is
of the suffixes ``y``, ``mo``, ``w``, ``d``, ``h``, or ``mi``, then the offset is
computed in years (defined as 365 24-hour days, ignoring leap years),
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'.
explicitly prevent a date from being set, use ``none`` or ``never``.
**-P** date/offset
Sets the date on which a key is to be published to the zone. After
that date, the key will be included in the zone but will not be used
to sign it. If not set, and if the -G option has not been used, the
default is "now".
``-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
default is the current date.
**-P** sync date/offset
Sets the date on which the CDS and CDNSKEY records which match this
key are to be published to the zone.
``-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
Sets the date on which the key is to be activated. After that date,
the key will be included in the zone and used to sign it. If not set,
and if the -G option has not been used, the default is "now".
``-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.
**-R** date/offset
Sets the date on which the key is to be revoked. After that date, the
key will be flagged as revoked. It will be included in the zone and
will be used to sign it.
``-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
Sets the date on which the key is to be retired. After that date, the
key will still be included in the zone, but it will not be used to
``-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
Sets the date on which the key is to be deleted. After that date, the
key will no longer be included in the zone. (It may remain in the key
repository, however.)
``-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
Sets the date on which the CDS and CDNSKEY records which match this
``-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
Sets the prepublication interval for a key. If set, then the
``-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
date isn't, then the publication date will default to this much time
date is not, the publication date defaults to this much time
before the activation date; conversely, if the publication date is
specified but activation date isn't, then activation will be set to
specified but not the activation date, activation is set to
this much time after publication.
If the key is being created as an explicit successor to another key,
@ -242,7 +242,7 @@ explicitly prevent a date from being set, use 'none' or 'never'.
zero.
As with date offsets, if the argument is followed by one of the
suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the interval is
suffixes ``y``, ``mo``, ``w``, ``d``, ``h``, or ``mi``, the interval is
measured in years, months, weeks, days, hours, or minutes,
respectively. Without a suffix, the interval is measured in seconds.
@ -264,7 +264,7 @@ printed string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and
``Knnnn.+aaa+iiiii.private`` contains the private key.
The ``.key`` file contains a DNS KEY record that can be inserted into a
zone file (directly or with a $INCLUDE statement).
zone file (directly or with an $INCLUDE statement).
The ``.private`` file contains algorithm-specific fields. For obvious
security reasons, this file does not have general read permission.
@ -273,4 +273,4 @@ See Also
~~~~~~~~
:manpage:`dnssec-keygen(8)`, :manpage:`dnssec-signzone(8)`, BIND 9 Administrator Reference Manual,
:rfc:`4034`, The PKCS#11 URI Scheme (draft-pechanec-pkcs11uri-13).
:rfc:`4034`, :rfc:`7512`.

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

@ -46,220 +46,220 @@ generated.
Options
~~~~~~~
**-3**
Use an NSEC3-capable algorithm to generate a DNSSEC key. If this
``-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 will be used; for example,
versions, then the NSEC3 version is selected; for example,
``dnssec-keygen -3a RSASHA1`` specifies the NSEC3RSASHA1 algorithm.
**-a** algorithm
Selects the cryptographic algorithm. For DNSSEC keys, the value of
``-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 his value
will automatically set the ``-T KEY`` option as well.
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.
These values are case insensitive. In some cases, abbreviations are
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``
option, then NSEC3RSASHA1 will be used instead.
option, NSEC3RSASHA1 is used instead.
This parameter *must* be specified except when using the ``-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 has been removed as of BIND 9.13.0. Use
keys, but that feature was removed in BIND 9.13.0. Use
``tsig-keygen`` to generate TSIG keys.
**-b** keysize
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
curve algorithms don't need this parameter.
``-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
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
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.
**-C**
Compatibility mode: generates an old-style key, without any timing
metadata. By default, ``dnssec-keygen`` will include the key's
creation date in the metadata stored with the private key, and other
dates may be set there as well (publication date, activation date,
etc). Keys that include this data may be incompatible with older
``-C``
This option enables compatibility mode, which generates an old-style key, without any timing
metadata. By default, ``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.
**-c** class
Indicates that the DNS record containing the key should have the
``-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
Key size in bits. For the algorithms RSASHA1, NSEC3RSASA1, RSASHA256 and
RSASHA512 the key size must be in range 1024-4096. DH size is between 128
and 4096. This option is ignored for algorithms ECDSAP256SHA256,
ECDSAP384SHA384, ED25519 and ED448.
``-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
Specifies the cryptographic hardware to use, when applicable.
``-E engine``
This option specifies the cryptographic hardware to use, when applicable.
When BIND is built with OpenSSL PKCS#11 support, this defaults to the
string "pkcs11", which identifies an OpenSSL engine that can drive a
string ``pkcs11``, which identifies an OpenSSL engine that can drive a
cryptographic accelerator or hardware service module. When BIND is
built with native PKCS#11 cryptography (--enable-native-pkcs11), it
built with native PKCS#11 cryptography (``--enable-native-pkcs11``), it
defaults to the path of the PKCS#11 provider library specified via
"--with-pkcs11".
``--with-pkcs11``.
**-f** flag
Set the specified flag in the flag field of the KEY/DNSKEY record.
The only recognized flags are KSK (Key Signing Key) and REVOKE.
``-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**
Generate a key, but do not publish it or sign with it. This option is
incompatible with -P and -A.
``-G``
This option generates a key, but does not publish it or sign with it. This option is
incompatible with ``-P`` and ``-A``.
**-g** generator
If generating a Diffie Hellman key, use this generator. Allowed
``-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` will be used if possible; otherwise the default is 2.
:rfc:`2539` is used if possible; otherwise the default is 2.
**-h**
Prints a short summary of the options and arguments to
``-h``
This option prints a short summary of the options and arguments to
``dnssec-keygen``.
**-K** directory
Sets the directory in which the key files are to be written.
``-K directory``
This option sets the directory in which the key files are to be written.
**-k** policy
Create keys for a specific dnssec-policy. If a policy uses multiple keys,
``dnssec-keygen`` will generate multiple keys. This will also
create a ".state" file to keep track of the key state.
``-k policy``
This option creates keys for a specific ``dnssec-policy``. If a policy uses multiple keys,
``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 together with many of the other options that
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.
**-L** ttl
Sets the default TTL to use for this key when it is converted into a
DNSKEY RR. If the key is imported into a zone, this is the TTL that
will be used for it, unless there was already a DNSKEY RRset in
place, in which case the existing TTL would take precedence. If this
value is not set and there is no existing DNSKEY RRset, the TTL will
default to the SOA TTL. Setting the default TTL to ``0`` or ``none``
``-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. 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 ``0`` or ``none``
is the same as leaving it unset.
**-l** file
Provide a configuration file that contains a dnssec-policy statement
``-l file``
This option provides a configuration file that contains a ``dnssec-policy`` statement
(matching the policy set with ``-k``).
**-n** nametype
Specifies the owner type of the key. The value of ``nametype`` must
``-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. Defaults to ZONE for DNSKEY generation.
with a user (KEY)), or OTHER (DNSKEY). These values are
case-insensitive. The default is ZONE for DNSKEY generation.
**-p** protocol
Sets the protocol value for the generated key, for use with
``-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
is 3 (DNSSEC). Other possible values for this argument are listed in
:rfc:`2535` and its successors.
**-q**
Quiet mode: Suppresses unnecessary output, including progress
``-q``
This option sets quiet mode, which suppresses unnecessary output, including progress
indication. Without this option, when ``dnssec-keygen`` is run
interactively to generate an RSA or DSA key pair, it will print a
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
passed an initial sieve test; '+' means a number has passed a single
round of the Miller-Rabin primality test; a space means that the
generation. A ``.`` indicates that a random number has been found which
passed an initial sieve test; ``+`` 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.
**-S** key
Create a new key which is an explicit successor to an existing key.
The name, algorithm, size, and type of the key will be set to match
the existing key. The activation date of the new key will be set to
the inactivation date of the existing one. The publication date will
be set to the activation date minus the prepublication interval,
``-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.
**-s** strength
Specifies the strength value of the key. The strength is a number
``-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
Specifies the resource record type to use for the key. ``rrtype``
``-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
Indicates the use of the key, for use with ``-T KEY``. ``type``
``-t type``
This option indicates the type of the key for use with ``-T 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 the ability to encrypt data.
CONF to the ability to encrypt data.
**-V**
Prints version information.
``-V``
This option prints version information.
**-v** level
Sets the debugging level.
``-v level``
This option sets the debugging level.
Timing Options
~~~~~~~~~~~~~~
Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the
argument begins with a '+' or '-', it is interpreted as an offset from
argument begins with a ``+`` or ``-``, it is interpreted as an offset from
the present time. For convenience, if such an offset is followed by one
of the suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the offset is
of the suffixes ``y``, ``mo``, ``w``, ``d``, ``h``, or ``mi``, then the offset is
computed in years (defined as 365 24-hour days, ignoring leap years),
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'.
explicitly prevent a date from being set, use ``none`` or ``never``.
**-P** date/offset
Sets the date on which a key is to be published to the zone. After
that date, the key will be included in the zone but will not be used
to sign it. If not set, and if the -G option has not been used, the
default is "now".
``-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
default is the current date.
**-P** sync date/offset
Sets the date on which CDS and CDNSKEY records that match this key
``-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
Sets the date on which the key is to be activated. After that date,
the key will be included in the zone and used to sign it. If not set,
and if the -G option has not been used, the default is "now". If set,
if and -P is not set, then the publication date will be set to the
``-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
activation date minus the prepublication interval.
**-R** date/offset
Sets the date on which the key is to be revoked. After that date, the
key will be flagged as revoked. It will be included in the zone and
will be used to sign it.
``-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
Sets the date on which the key is to be retired. After that date, the
key will still be included in the zone, but it will not be used to
``-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
Sets the date on which the key is to be deleted. After that date, the
key will no longer be included in the zone. (It may remain in the key
repository, however.)
``-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
Sets the date on which the CDS and CDNSKEY records that match this
``-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
Sets the prepublication interval for a key. If set, then the
``-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
date isn't, then the publication date will default to this much time
date is not, the publication date defaults to this much time
before the activation date; conversely, if the publication date is
specified but activation date isn't, then activation will be set to
specified but not the activation date, activation is set to
this much time after publication.
If the key is being created as an explicit successor to another key,
@ -267,7 +267,7 @@ explicitly prevent a date from being set, use 'none' or 'never'.
zero.
As with date offsets, if the argument is followed by one of the
suffixes 'y', 'mo', 'w', 'd', 'h', or 'mi', then the interval is
suffixes ``y``, ``mo``, ``w``, ``d``, ``h``, or ``mi``, the interval is
measured in years, months, weeks, days, hours, or minutes,
respectively. Without a suffix, the interval is measured in seconds.
@ -289,9 +289,9 @@ string. ``Knnnn.+aaa+iiiii.key`` contains the public key, and
``Knnnn.+aaa+iiiii.private`` contains the private key.
The ``.key`` file contains a DNSKEY or KEY record. When a zone is being
signed by ``named`` or ``dnssec-signzone`` ``-S``, DNSKEY records are
signed by ``named`` or ``dnssec-signzone -S``, DNSKEY records are
included automatically. In other cases, the ``.key`` file can be
inserted into a zone file manually or with a ``$INCLUDE`` statement.
inserted into a zone file manually or with an ``$INCLUDE`` statement.
The ``.private`` file contains algorithm-specific fields. For obvious
security reasons, this file does not have general read permission.
@ -304,7 +304,7 @@ To generate an ECDSAP256SHA256 zone-signing key for the zone
``dnssec-keygen -a ECDSAP256SHA256 example.com``
The command would print a string of the form:
The command prints a string of the form:
``Kexample.com.+013+26160``

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

@ -41,38 +41,38 @@ containing the now-revoked key.
Options
~~~~~~~
**-h**
Emit usage message and exit.
``-h``
This option emits a usage message and exits.
**-K** directory
Sets the directory in which the key files are to reside.
``-K directory``
This option sets the directory in which the key files are to reside.
**-r**
After writing the new keyset files remove the original keyset files.
``-r``
This option indicates to remove the original keyset files after writing the new keyset files.
**-v** level
Sets the debugging level.
``-v level``
This option sets the debugging level.
**-V**
Prints version information.
``-V``
This option prints version information.
**-E** engine
Specifies the cryptographic hardware to use, when applicable.
``-E engine``
This option specifies the cryptographic hardware to use, when applicable.
When BIND is built with OpenSSL PKCS#11 support, this defaults to the
string "pkcs11", which identifies an OpenSSL engine that can drive a
When BIND 9 is built with OpenSSL PKCS#11 support, this defaults to the
string ``pkcs11``, which identifies an OpenSSL engine that can drive a
cryptographic accelerator or hardware service module. When BIND is
built with native PKCS#11 cryptography (--enable-native-pkcs11), it
built with native PKCS#11 cryptography (``--enable-native-pkcs11``), it
defaults to the path of the PKCS#11 provider library specified via
"--with-pkcs11".
``--with-pkcs11``.
**-f**
Force overwrite: Causes ``dnssec-revoke`` to write the new key pair
``-f``
This option indicates a forced overwrite and causes ``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**
Print the key tag of the key with the REVOKE bit set but do not
``-R``
This option prints the key tag of the key with the REVOKE bit set, but does not
revoke the key.
See Also

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

@ -47,39 +47,39 @@ C++ style: // to end of line
Unix style: # to end of line
``rndc.conf`` is much simpler than ``named.conf``. The file uses three
statements: an options statement, a server statement and a key
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
will be used when no name server is given as an argument to ``rndc``.
The ``default-key`` clause is followed by the name of a key which is
is used when no name server is given as an argument to ``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
``server`` statement, this default key will be used to authenticate the
``server`` statement, this default key is used to authenticate the
server's commands and responses. The ``default-port`` clause is followed
by the port to connect to on the remote name server. If no ``port``
option is provided on the rndc command line, and no ``port`` clause is
found in a matching ``server`` statement, this default port will be used
found in a matching ``server`` statement, this default port is used
to connect. The ``default-source-address`` and
``default-source-address-v6`` clauses which can be used to set the IPv4
``default-source-address-v6`` clauses can be used to set the IPv4
and IPv6 source addresses respectively.
After the ``server`` keyword, the server statement includes a string
which is the hostname or address for a name server. The statement has
three possible clauses: ``key``, ``port`` and ``addresses``. The key
three possible clauses: ``key``, ``port``, and ``addresses``. The key
name must match the name of a key statement in the file. The port number
specifies the port to connect to. If an ``addresses`` clause is supplied
these addresses will be used instead of the server name. Each address
specifies the port to connect to. If an ``addresses`` clause is supplied,
these addresses are used instead of the server name. Each address
can take an optional port. If an ``source-address`` or
``source-address-v6`` of supplied then these will be used to specify the
IPv4 and IPv6 source addresses respectively.
``source-address-v6`` is supplied, it is used to specify the
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
(for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (default),
HMAC-SHA384 and HMAC-SHA512 are supported. This is followed by a secret
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.
@ -87,7 +87,7 @@ 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
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
not ship with BIND 9 but is available on many systems. See the Example
section for sample command lines for each.
Example
@ -128,23 +128,23 @@ Example
};
In the above example, ``rndc`` will by default use the server at
localhost (127.0.0.1) and the key called samplekey. Commands to the
localhost server will use the samplekey key, which must also be defined
In the above example, ``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
key statement indicates that samplekey uses the HMAC-SHA256 algorithm
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`` will connect to server
on localhost port 5353 using the key testkey.
If ``rndc -s testserver`` is used, then ``rndc`` connects to the server
on localhost port 5353 using the key "testkey".
To generate a random secret with ``rndc-confgen``:
``rndc-confgen``
A complete ``rndc.conf`` file, including the randomly generated key,
will be written to the standard output. Commented-out ``key`` and
is written to the standard output. Commented-out ``key`` and
``controls`` statements for ``named.conf`` are also printed.
To generate a base-64 secret with ``mmencode``:

355
bin/rndc/rndc.rst
View file

@ -34,8 +34,8 @@ Synopsis
Description
~~~~~~~~~~~
``rndc`` controls the operation of a name server. It supersedes the
``ndc`` utility that was provided in old BIND releases. If ``rndc`` is
``rndc`` controls the operation of a name server; it supersedes the
``ndc`` utility. If ``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.
@ -44,8 +44,8 @@ arguments.
sending commands authenticated with digital signatures. In the current
versions of ``rndc`` and ``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. This provides TSIG-style
HMAC-SHA256 (default), HMAC-SHA384, and HMAC-SHA512. They use a shared
secret on each end of the connection, which provides TSIG-style
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.
@ -56,59 +56,58 @@ server and decide what algorithm and key it should use.
Options
~~~~~~~
**-4**
Use IPv4 only.
``-4``
This indicates use of IPv4 only.
**-6**
Use IPv6 only.
``-6``
This indicates use of IPv6 only.
**-b** source-address
Use source-address as the source address for the connection to the
server. Multiple instances are permitted to allow setting of both the
``-b source-address``
This 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
Use config-file as the configuration file instead of the default,
``-c config-file``
This indicates ``config-file`` as the configuration file instead of the default,
``/etc/rndc.conf``.
**-k** key-file
Use key-file as the key file instead of the default,
``/etc/rndc.key``. The key in ``/etc/rndc.key`` will be used to
``-k key-file``
This indicates ``key-file`` as the key file instead of the default,
``/etc/rndc.key``. The key in ``/etc/rndc.key`` is used to
authenticate commands sent to the server if the config-file does not
exist.
**-s** server
server is the name or address of the server which matches a server
``-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
supplied on the command line, the host named by the default-server
clause in the options statement of the ``rndc`` configuration file
will be used.
is used.
**-p** port
Send commands to TCP port port instead of BIND 9's default control
``-p port``
This instructs BIND 9 to send commands to TCP port ``port`` instead of its default control
channel port, 953.
**-q**
Quiet mode: Message text returned by the server will not be printed
except when there is an error.
``-q``
This sets quiet mode, where message text returned by the server is not printed
unless there is an error.
**-r**
Instructs ``rndc`` to print the result code returned by ``named``
``-r``
This instructs ``rndc`` to print the result code returned by ``named``
after executing the requested command (e.g., ISC_R_SUCCESS,
ISC_R_FAILURE, etc).
ISC_R_FAILURE, etc.).
**-V**
Enable verbose logging.
``-V``
This enables verbose logging.
**-y** key_id
Use the key key_id from the configuration file. key_id must be known
by ``named`` with the same algorithm and secret string in order for
control message validation to succeed. If no key_id is specified,
``rndc`` will first look for a key clause in the server statement of
``-y key_id``
This 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
the server being used, or if no server statement is present for that
host, then the default-key clause of the options statement. Note 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
authenticated control commands to name servers. It should therefore
authenticated control commands to name servers, and should therefore
not have general read or write access.
Commands
@ -120,45 +119,45 @@ without arguments.
Currently supported commands are:
``addzone`` *zone* [*class* [*view*]] *configuration*
Add a zone while the server is running. This command requires the
This 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 :manpage:`named.conf(5)`.
that would ordinarily be placed in ``named.conf``.
The configuration is saved in a file called ``viewname.nzf`` (or, if
:manpage:`named(8)` is compiled with liblmdb, an LMDB database file called
``viewname.nzd``). viewname is the name of the view, unless the view
``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 :manpage:`named(8)` is restarted, the file will be loaded into
the view configuration, so that zones that were added can persist
instead. When ``named`` is restarted, the file is loaded into
the view configuration so that zones that were added can persist
after a restart.
This sample ``addzone`` command would add the zone ``example.com`` to
This sample ``addzone`` command adds the zone ``example.com`` to
the default view:
``$``\ ``rndc addzone example.com '{ type master; file "example.com.db"; };'``
``$ \ rndc addzone example.com '{ type master; file "example.com.db"; };'``
(Note the brackets and semi-colon around the zone configuration
(Note the brackets around and semi-colon after the zone configuration
text.)
See also ``rndc delzone`` and ``rndc modzone``.
``delzone`` [**-clean**] *zone* [*class* [*view*]]
Delete a zone while the server is running.
This deletes a zone while the server is running.
If the ``-clean`` argument is specified, the zone's master file (and
journal file, if any) will be deleted along with the zone. Without
the ``-clean`` option, zone files must be cleaned up by hand. (If the
zone is of type ``secondary`` or ``stub``, the files needing to be cleaned up
will be reported in the output of the ``rndc delzone`` command.)
journal file, if any) are deleted along with the zone. Without
the ``-clean`` option, zone files must be deleted manually. (If the
zone is of type ``secondary`` or ``stub``, the files needing to be removed
are reported in the output of the ``rndc delzone`` command.)
If the zone was originally added via ``rndc addzone``, then it will
be removed permanently. However, if it was originally configured in
``named.conf``, then that original configuration is still in place;
when the server is restarted or reconfigured, the zone will come
back. To remove it permanently, it must also be removed from
``named.conf``
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;
when the server is restarted or reconfigured, the zone is
recreated. To remove it permanently, it must also be removed from
``named.conf``.
See also ``rndc addzone`` and ``rndc modzone``.
@ -167,78 +166,78 @@ Currently supported commands are:
zone to have a "dnssec-policy".
``dnstap`` ( **-reopen** | **-roll** [*number*] )
Close and re-open DNSTAP output files. ``rndc dnstap -reopen`` allows
the output file to be renamed externally, so that :manpage:`named(8)` can
This closes and re-opens DNSTAP output files. ``rndc dnstap -reopen`` allows
the output file to be renamed externally, so that ``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
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
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** | **-fail**] [*view ...*]
Dump the server's caches (default) and/or zones to the dump file for
This 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``
Flushes the server's cache.
This flushes the server's cache.
``flushname`` *name* [*view*]
Flushes the given name from the view's DNS cache and, if applicable,
from the view's nameserver address database, bad server cache and
This 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*]
Flushes the given name, and all of its subdomains, from the view's
This 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*]]]
Suspend updates to a dynamic zone. If no zone is specified, then all
This 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. It also causes changes in the
normally updated by dynamic update, and causes changes in the
journal file to be synced into the master file. All dynamic update
attempts will be refused while the zone is frozen.
attempts are refused while the zone is frozen.
See also ``rndc thaw``.
``halt`` [**-p**]
Stop the server immediately. Recent changes made through dynamic
update or IXFR are not saved to the master files, but will be rolled
This 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 :manpage:`named(8)`'s process id is returned. This allows
an external process to determine when :manpage:`named(8)` had completed
``-p`` is specified, ``named``'s process ID is returned. This allows
an external process to determine when ``named`` has completed
halting.
See also ``rndc stop``.
``loadkeys`` [*zone* [*class* [*view*]]]
Fetch all DNSSEC keys for the given zone from the key directory. If
they are within their publication period, merge them into the
This 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
immediately re-signed by the new keys, but is allowed to
incrementally re-sign over time.
This command requires that zone is configured with a ``dnssec-policy``, or
the ``auto-dnssec`` zone option be set to ``maintain``, and also requires the
This command requires that the zone be configured with a ``dnssec-policy``, or
that the ``auto-dnssec`` zone option be set to ``maintain``, and also requires the
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*]]
Inspect and control the "managed-keys" database which handles
This 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
commands are applied to that view; otherwise, they are applied to all
views.
- When run with the ``status`` keyword, prints the current status of
- When run with the ``status`` keyword, this prints the current status of
the managed-keys database.
- When run with the ``refresh`` keyword, forces an immediate refresh
- When run with the ``refresh`` keyword, this forces an immediate refresh
query to be sent for all the managed keys, updating the
managed-keys database if any new keys are found, without waiting
the normal refresh interval.
- When run with the ``sync`` keyword, forces an immediate dump of
- When run with the ``sync`` keyword, this forces an immediate dump of
the managed-keys database to disk (in the file
``managed-keys.bind`` or (``viewname.mkeys``). This synchronizes
the database with its journal file, so that the database's current
@ -250,12 +249,12 @@ 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 will cease until :manpage:`named(8)` is
restarted or reconfigured, and all existing key maintenance state
will be deleted.
However, key maintenance operations cease until ``named`` is
restarted or reconfigured, and all existing key maintenance states
are deleted.
Running ``rndc reconfig`` or restarting :manpage:`named(8)` immediately
after this command will cause key maintenance to be reinitialized
Running ``rndc reconfig`` or restarting ``named`` immediately
after this command causes key maintenance to be reinitialized
from scratch, just as if the server were being started for the
first time. This is primarily intended for testing, but it may
also be used, for example, to jumpstart the acquisition of new
@ -263,33 +262,33 @@ Currently supported commands are:
repair for key maintenance problems.
``modzone`` *zone* [*class* [*view*]] *configuration*
Modify the configuration of a zone while the server is running. This
This 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``.
If the zone was originally added via ``rndc addzone``, the
configuration changes will be recorded permanently and will still be
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
configuration is still in place; when the server is restarted or
reconfigured, the zone will revert to its original configuration. To
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``
``named.conf``.
See also ``rndc addzone`` and ``rndc delzone``.
``notify`` *zone* [*class* [*view*]]
Resend NOTIFY messages for the zone.
This resends NOTIFY messages for the zone.
``notrace``
Sets the server's debugging level to 0.
This sets the server's debugging level to 0.
See also ``rndc trace``.
``nta`` [( **-class** *class* | **-dump** | **-force** | **-remove** | **-lifetime** *duration*)] *domain* [*view*]
Sets a DNSSEC negative trust anchor (NTA) for ``domain``, with a
This 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
hour. The lifetime cannot exceed one week.
@ -297,15 +296,15 @@ Currently supported commands are:
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), :manpage:`named(8)` will
abort the DNSSEC validation process and treat the data as insecure
rather than bogus. This continues until the NTA's lifetime is
NTA (and above any other configured trust anchors), ``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 :manpage:`named(8)` server. The NTAs for a
view are saved in a file called ``name.nta``, where name is the name
of the view, or if it contains characters that are incompatible with
use as a file name, a cryptographic hash generated from the name of
NTAs persist across restarts of the ``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
the view.
An existing NTA can be removed by using the ``-remove`` option.
@ -313,18 +312,18 @@ Currently supported commands are:
An NTA's lifetime can be specified with the ``-lifetime`` option.
TTL-style suffixes can be used to specify the lifetime in seconds,
minutes, or hours. If the specified NTA already exists, its lifetime
will be updated to the new value. Setting ``lifetime`` to zero is
is updated to the new value. Setting ``lifetime`` to zero is
equivalent to ``-remove``.
If the ``-dump`` is used, any other arguments are ignored, and a list
of existing NTAs is printed (note that this may include NTAs that are
expired but have not yet been cleaned up).
If ``-dump`` is used, any other arguments are ignored and a list
of existing NTAs is printed. Note that this may include NTAs that are
expired but have not yet been cleaned up.
Normally, :manpage:`named(8)` will periodically test to see whether data below
Normally, ``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 will
be allowed to expire early. The ``-force`` overrides this behavior
validated, then the NTA is regarded as no longer necessary and is
allowed to expire early. The ``-force`` parameter overrides this behavior
and forces an NTA to persist for its entire lifetime, regardless of
whether data could be validated if the NTA were not present.
@ -335,65 +334,65 @@ Currently supported commands are:
All of these options can be shortened, i.e., to ``-l``, ``-r``,
``-d``, ``-f``, and ``-c``.
Unrecognized options are treated as errors. To reference a domain or
view name that begins with a hyphen, use a double-hyphen on the
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.
``querylog`` [(*on* | *off*)]
Enable or disable query logging. (For backward compatibility, this
This enables or disables query logging. For backward compatibility, this
command can also be used without an argument to toggle query logging
on and off.)
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
of ``named.conf``, or by specifying ``querylog yes;`` in the
``options`` section of ``named.conf``.
``reconfig``
Reload the configuration file and load new zones, but do not reload
This 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
avoids the need to examine the modification times of the zones files.
full ``reload`` when there is a large number of zones, because it
avoids the need to examine the modification times of the zone files.
``recursing``
Dump the list of queries :manpage:`named(8)` is currently recursing on, and the
This dumps the list of queries ``named`` is currently recursing on, and the
list of domains to which iterative queries are currently being sent.
(The second list includes the number of fetches currently active for
The second list includes the number of fetches currently active for
the given domain, and how many have been passed or dropped because of
the ``fetches-per-zone`` option.)
the ``fetches-per-zone`` option.
``refresh`` *zone* [*class* [*view*]]
Schedule zone maintenance for the given zone.
This schedules zone maintenance for the given zone.
``reload``
Reload configuration file and zones.
This reloads the configuration file and zones.
``reload`` *zone* [*class* [*view*]]
Reload the given zone.
This reloads the given zone.
``retransfer`` *zone* [*class* [*view*]]
Retransfer the given secondary zone from the primary server.
This retransfers the given secondary zone from the primary server.
If the zone is configured to use ``inline-signing``, the signed
version of the zone is discarded; after the retransfer of the
unsigned version is complete, the signed version will be regenerated
with all new signatures.
unsigned version is complete, the signed version is regenerated
with new signatures.
``scan``
Scan the list of available network interfaces for changes, without
This scans the list of available network interfaces for changes, without
performing a full ``reconfig`` or waiting for the
``interface-interval`` timer.
``secroots`` [**-**] [*view* ...]
Dump the security roots (i.e., trust anchors configured via
This 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
[both deprecated], or ``dnssec-validation auto``) and negative trust anchors
for the specified views. If no view is specified, all views are
dumped. Security roots will indicate whether they are configured as trusted
dumped. Security roots indicate whether they are configured as trusted
keys, managed keys, or initializing managed keys (managed keys that have not
yet been updated by a successful key refresh query).
If the first argument is "-", then the output is returned via the
If the first argument is ``-``, then the output is returned via the
``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``
@ -402,43 +401,43 @@ Currently supported commands are:
See also ``rndc managed-keys``.
``serve-stale`` (**on** | **off** | **reset** | **status**) [*class* [*view*]]
Enable, disable, reset, or report the current status of the serving
This enables, disables, resets, or reports the current status of the serving
of stale answers as configured in ``named.conf``.
If serving of stale answers is disabled by ``rndc-serve-stale off``,
then it will remain disabled even if :manpage:`named(8)` is reloaded or
then it remains disabled even if ``named`` is reloaded or
reconfigured. ``rndc serve-stale reset`` restores the setting as
configured in ``named.conf``.
``rndc serve-stale status`` will report whether serving of stale
``rndc serve-stale status`` reports whether serving of stale
answers is currently enabled, disabled by the configuration, or
disabled by ``rndc``. It will also report the values of
disabled by ``rndc``. It also reports the values of
``stale-answer-ttl`` and ``max-stale-ttl``.
``showzone`` *zone* [*class* [*view*]]
Print the configuration of a running zone.
This prints the configuration of a running zone.
See also ``rndc zonestatus``.
``sign`` *zone* [*class* [*view*]]
Fetch all DNSSEC keys for the given zone from the key directory (see
This 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, merge them into
Manual). If they are within their publication period, they are merged into
the zone's DNSKEY RRset. If the DNSKEY RRset is changed, then the
zone is automatically re-signed with the new key set.
This command requires that the zone is configure with a ``dnssec-policy``, or
This command requires that the zone be configured with a ``dnssec-policy``, or
that the ``auto-dnssec`` zone option be set to ``allow`` or ``maintain``,
and also requires the zone to be configured to allow dynamic DNS. (See
"Dynamic Update Policies" in the Administrator Reference Manual for more
"Dynamic Update Policies" in the BIND 9 Administrator Reference Manual for more
details.)
See also ``rndc loadkeys``.
``signing`` [(**-list** | **-clear** *keyid/algorithm* | **-clear** *all* | **-nsec3param** ( *parameters* | none ) | **-serial** *value* ) *zone* [*class* [*view*]]
List, edit, or remove 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
This 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
of DNS resource records of type ``sig-signing-type``.
``rndc signing -list`` converts these records into a human-readable
form, indicating which keys are currently signing or have finished
@ -448,22 +447,22 @@ Currently supported commands are:
``rndc signing -clear`` can remove a single key (specified in the
same format that ``rndc signing -list`` uses to display it), or all
keys. In either case, only completed keys are removed; any record
indicating that a key has not yet finished signing the zone will be
indicating that a key has not yet finished signing the zone is
retained.
``rndc signing -nsec3param`` sets the NSEC3 parameters for a zone.
This is the only supported mechanism for using NSEC3 with
``inline-signing`` zones. Parameters are specified in the same format
as an NSEC3PARAM resource record: hash algorithm, flags, iterations,
and salt, in that order.
as an NSEC3PARAM resource record: ``hash algorithm``, ``flags``, ``iterations``,
and ``salt``, in that order.
Currently, the only defined value for hash algorithm is ``1``,
Currently, the only defined value for ``hash algorithm`` is ``1``,
representing SHA-1. The ``flags`` may be set to ``0`` or ``1``,
depending on whether the opt-out bit should be set in the NSEC3
chain. ``iterations`` defines the number of additional times to apply
depending on whether the opt-out bit in the NSEC3
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 :manpage:`named(8)` to generate a
used, or the keyword ``auto``, which causes ``named`` to generate a
random 64-bit salt.
So, for example, to create an NSEC3 chain using the SHA-1 hash
@ -476,81 +475,81 @@ Currently supported commands are:
replaces it with NSEC.
``rndc signing -serial value`` sets the serial number of the zone to
value. If the value would cause the serial number to go backwards it
will be rejected. The primary use is to set the serial on inline
``value``. 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.
``stats``
Write server statistics to the statistics file. (See the
This writes server statistics to the statistics file. (See the
``statistics-file`` option in the BIND 9 Administrator Reference
Manual.)
``status``
Display 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 not an explicit root zone configured.
This 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**
Stop the server, making sure any recent changes made through dynamic
This 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 :manpage:`named(8)`'s process id is returned.
This allows an external process to determine when :manpage:`named(8)` had
zones. If ``-p`` is specified, ``named(8)`'s process ID is returned.
This allows an external process to determine when ``named`` has
completed stopping.
See also ``rndc halt``.
``sync`` **-clean** [*zone* [*class* [*view*]]]
Sync changes in the journal file for a dynamic zone to the master
This 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*]
When called without arguments, display the current values of the
When called without arguments, this displays the current values of the
``tcp-initial-timeout``, ``tcp-idle-timeout``,
``tcp-keepalive-timeout`` and ``tcp-advertised-timeout`` options.
When called with arguments, update these values. This allows an
administrator to make rapid adjustments when under a denial of
service attack. See the descriptions of these options in the BIND 9
``tcp-keepalive-timeout``, and ``tcp-advertised-timeout`` options.
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.
``thaw`` [*zone* [*class* [*view*]]]
Enable updates to a frozen dynamic zone. If no zone is specified,
This 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
completed. After a zone is thawed, dynamic updates will no longer be
completed. After a zone is thawed, dynamic updates are no longer
refused. If the zone has changed and the ``ixfr-from-differences``
option is in use, then the journal file will be updated to reflect
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 will be removed.
journal file is removed.
See also ``rndc freeze``.
``trace``
Increment the servers debugging level by one.
This increments the server's debugging level by one.
``trace`` *level*
Sets the server's debugging level to an explicit value.
This sets the server's debugging level to an explicit value.
See also ``rndc notrace``.
``tsig-delete`` *keyname* [*view*]
Delete a given TKEY-negotiated key from the server. (This does not
apply to statically configured TSIG keys.)
This deletes a given TKEY-negotiated key from the server. This does not
apply to statically configured TSIG keys.
``tsig-list``
List the names of all TSIG keys currently configured for use by
:manpage:`named(8)` in each view. The list both statically configured keys and
This lists the names of all TSIG keys currently configured for use by
``named`` in each view. The list includes both statically configured keys and
dynamic TKEY-negotiated keys.
``validation`` (**on** | **off** | **status**) [*view* ...]``
Enable, disable, or check the current status of DNSSEC validation. By
This 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*]]
Displays the current status of the given zone, including the master
This 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,
whether the zone supports dynamic updates, whether the zone is DNSSEC
@ -560,8 +559,8 @@ Currently supported commands are:
See also ``rndc showzone``.
``rndc`` commands that specify zone names, such as ``reload``,
``retransfer`` or ``zonestatus``, can be ambiguous when applied to zones
of type ``redirect``. Redirect zones are always called ".", and can be
``retransfer``, or ``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
``-redirect``, without a trailing period. (With a trailing period, this

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

@ -36,25 +36,25 @@ Description
``dnstap-read`` reads ``dnstap`` data from a specified file and prints
it in a human-readable format. By default, ``dnstap`` data is printed in
a short summary format, but if the ``-y`` option is specified, then a
longer and more detailed YAML format is used instead.
a short summary format, but if the ``-y`` option is specified, a
longer and more detailed YAML format is used.
Options
~~~~~~~
**-m**
Trace memory allocations; used for debugging memory leaks.
``-m``
This indicates trace memory allocations, and is used for debugging memory leaks.
**-p**
After printing the ``dnstap`` data, print the text form of the DNS
message that was encapsulated in the ``dnstap`` frame.
``-p``
This option prints the text form of the DNS
message that was encapsulated in the ``dnstap`` frame, after printing the ``dnstap`` data.
**-x**
After printing the ``dnstap`` data, print a hex dump of the wire form
of the DNS message that was encapsulated in the ``dnstap`` frame.
``-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**
Print ``dnstap`` data in a detailed YAML format.
``-y``
This prints ``dnstap`` data in a detailed YAML format.
See Also
~~~~~~~~

201
bin/tools/mdig.rst
View file

@ -44,11 +44,11 @@ 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
into "anywhere options" which can occur anywhere, "global options" which
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.
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
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
retrieved from ``/etc/resolv.conf``.) It can be an IPv4 address in
dotted-decimal notation, an IPv6 address in colon-delimited notation, or
@ -70,246 +70,257 @@ assign values to options like the timeout interval. They have the form
Anywhere Options
~~~~~~~~~~~~~~~~
The ``-f`` option makes ``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.
``-f``
This option makes ``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.
The ``-h`` causes ``mdig`` to print the detailed help with the full list
of options and exit.
``-h``
This option causes ``mdig`` to print detailed help information, with the full list
of options, and exit.
The ``-v`` causes ``mdig`` to print the version number and exit.
``-v``
This option causes ``mdig`` to print the version number and exit.
Global Options
~~~~~~~~~~~~~~
The ``-4`` option forces ``mdig`` to only use IPv4 query transport.
``-4``
This option forces ``mdig`` to only use IPv4 query transport.
The ``-6`` option forces ``mdig`` to only use IPv6 query transport.
``-6``
This option forces ``mdig`` to only use IPv6 query transport.
The ``-b`` 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>"
``-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>"
The ``-m`` option enables memory usage debugging.
``-m``
This option enables memory usage debugging.
The ``-p`` option is used when a non-standard port number is to be
queried. ``port#`` is the port number that ``mdig`` will send its
queries instead of the standard DNS port number 53. This option would be
used to test a name server that has been configured to listen for
queries on a non-standard port number.
``-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
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``
Display [do not display] the additional section of a reply. The
This option displays [or does not display] the additional section of a reply. The
default is to display it.
``+[no]all``
Set or clear all display flags.
This option sets or clears all display flags.
``+[no]answer``
Display [do not display] the answer section of a reply. The default
This option displays [or does not display] the answer section of a reply. The default
is to display it.
``+[no]authority``
Display [do not display] the authority section of a reply. The
This option displays [or does not display] the authority section of a reply. The
default is to display it.
``+[no]besteffort``
Attempt to display the contents of messages which are malformed. The
This option attempts to display [or does not display] the contents of messages which are malformed. The
default is to not display malformed answers.
``+[no]cl``
Display [do not display] the CLASS when printing the record.
This option displays [or does not display] the CLASS when printing the record.
``+[no]comments``
Toggle the display of comment lines in the output. The default is to
This option toggles the display of comment lines in the output. The default is to
print comments.
``+[no]continue``
Continue on errors (e.g. timeouts).
This option toggles continuation on errors (e.g. timeouts).
``+[no]crypto``
Toggle the display of cryptographic fields in DNSSEC records. The
contents of these field are unnecessary to debug most DNSSEC
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]" or in the DNSKEY case the
key id is displayed as the replacement, e.g. "[ key id = value ]".
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., ``[ key id = value ]``.
``+dscp[=value]``
Set 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
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``
Print records like the SOA records in a verbose multi-line format
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.
``+[no]question``
Print [do not print] the question section of a query when an answer
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``
Toggle the display of per-record comments in the output (for example,
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``
Provide a terse answer. The default is to print the answer in a
This option provides [or does not provide] a terse answer. The default is to print the answer in a
verbose form.
``+split=W``
Split long hex- or base64-formatted fields in resource records into
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
split. The default is 56 characters, or 44 characters when
multiline mode is active.
``+[no]tcp``
Use [do not use] TCP when querying name servers. The default behavior
This option uses [or does not use] TCP when querying name servers. The default behavior
is to use UDP.
``+[no]ttlid``
Display [do not display] the TTL when printing the record.
This option displays [or does not display] the TTL when printing the record.
``+[no]ttlunits``
Display [do not display] the TTL in friendly human-readable time
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. Implies +ttlid.
hours, days, and weeks. This implies +ttlid.
``+[no]vc``
Use [do not use] TCP when querying name servers. This alternate
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".
``vc`` stands for "virtual circuit".
Local Options
~~~~~~~~~~~~~
The ``-c`` 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".
``-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".
The ``-t`` 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
the "PTR" query type.
``-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
the "PTR" query type.
Reverse lookups MDASH mapping addresses to names MDASH are simplified by
the ``-x`` option. ``addr`` is an IPv4 address in dotted-decimal
notation, or a colon-delimited IPv6 address. ``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
domain.
``-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
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
domain.
The local query options are:
``+[no]aaflag``
A synonym for ``+[no]aaonly``.
This is a synonym for ``+[no]aaonly``.
``+[no]aaonly``
Sets the "aa" flag in the query.
This sets the ``aa`` flag in the query.
``+[no]adflag``
Set [do not set] the AD (authentic data) bit in the query. This
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
sections have all been validated as secure, according to the security
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
indicate that some part of the answer was insecure or not validated.
indicates that some part of the answer was insecure or not validated.
This bit is set by default.
``+bufsize=B``
Set the UDP message buffer size advertised using EDNS0 to ``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 will cause a EDNS query to be
appropriately. Values other than zero cause a EDNS query to be
sent.
``+[no]cdflag``
Set [do not set] the CD (checking disabled) bit in the query. This
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=####``
Send a COOKIE EDNS option, with optional value. Replaying a COOKIE
from a previous response will allow the server to identify a previous
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``
Requests DNSSEC records be sent by setting the DNSSEC OK bit (DO) in
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[=#]``
Specify the EDNS version to query with. Valid values are 0 to 255.
Setting the EDNS version will cause a EDNS query to be sent.
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[=#]``
Set 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) will silently be ignored. By default, no Z bits are set.
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]]``
Specify EDNS option with code point ``code`` and optionally payload
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``
Send an EDNS Expire option.
This toggles sending of an EDNS Expire option.
``+[no]nsid``
Include an EDNS name server ID request when sending a query.
This toggles inclusion of an EDNS name server ID request when sending a query.
``+[no]recurse``
Toggle the setting of the RD (recursion desired) bit in the query.
This toggles the setting of the RD (recursion desired) bit in the query.
This bit is set by default, which means ``mdig`` normally sends
recursive queries.
``+retry=T``
Sets the number of times to retry UDP queries to server to ``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]``
Send (don't send) an EDNS Client Subnet option with the specified IP
This sends [or does not send] an EDNS Client Subnet option with the specified IP
address or network prefix.
``mdig +subnet=0.0.0.0/0``, or simply ``mdig +subnet=0`` for short,
sends an EDNS client-subnet option with an empty address and a source
``mdig +subnet=0.0.0.0/0``, or simply ``mdig +subnet=0``
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's
address information must *not* be used when resolving this query.
``+timeout=T``
Sets the timeout for a query to ``T`` seconds. The default timeout is
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 will result in a query timeout of 1 second being
to less than 1 results in a query timeout of 1 second being
applied.
``+tries=T``
Sets the number of times to try UDP queries to server to ``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``
Sets the timeout between UDP query retries.
This sets the timeout between UDP query retries to ``T``.
``+[no]unknownformat``
Print all RDATA in unknown RR type presentation format (:rfc:`3597`).
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``
Print the responses in a detailed YAML format.
This toggles printing of the responses in a detailed YAML format.
``+[no]zflag``
Set [do not set] the last unassigned DNS header flag in a DNS query.
This sets [or does not set] the last unassigned DNS header flag in a DNS query.
This flag is off by default.
See Also

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

@ -43,8 +43,8 @@ version of BIND to an older version.
Arguments
~~~~~~~~~
filename
The name of the ``.nzd`` file whose contents should be printed.
``filename``
This is the name of the ``.nzd`` file whose contents should be printed.
See Also
~~~~~~~~

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

@ -34,22 +34,30 @@ Synopsis
Description
~~~~~~~~~~~
``named-rrchecker`` read a individual DNS resource record from standard
input and checks if it is syntactically correct.
``named-rrchecker`` reads a individual DNS resource record from standard
input and checks whether it is syntactically correct.
The ``-h`` prints out the help menu.
Options
~~~~~~~
The ``-o origin`` option specifies a origin to be used when interpreting
the record.
``-h``
This option prints out the help menu.
The ``-p`` prints out the resulting record in canonical form. If there
is no canonical form defined then the record will be printed in unknown
record format.
``-o origin``
This option specifies the origin to be used when interpreting
the record.
The ``-u`` prints out the resulting record in unknown record form.
``-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.
The ``-C``, ``-T`` and ``-P`` print out the known class, standard type
and private type mnemonics respectively.
``-u``
This option prints out the resulting record in unknown record form.
``-C``, ``-T``, and ``-P``
These options print out the known class, standard type,
and private type mnemonics, respectively.
See Also
~~~~~~~~

18
bin/tools/nsec3hash.rst
View file

@ -40,9 +40,9 @@ Description
parameters. This can be used to check the validity of NSEC3 records in a
signed zone.
If this command is invoked as ``nsec3hash -r``, it takes arguments in an
order matching the first four fields of an NSEC3 record, followed by the
domain name: algorithm, flags, iterations, salt, domain. This makes it
If this command is invoked as ``nsec3hash -r``, it takes arguments in
order, matching the first four fields of an NSEC3 record followed by the
domain name: ``algorithm``, ``flags``, ``iterations``, ``salt``, ``domain``. This makes it
convenient to copy and paste a portion of an NSEC3 or NSEC3PARAM record
into a command line to confirm the correctness of an NSEC3 hash.
@ -50,22 +50,22 @@ Arguments
~~~~~~~~~
``salt``
The salt provided to the hash algorithm.
This is the salt provided to the hash algorithm.
``algorithm``
A number indicating the hash algorithm. Currently the only supported
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``
Provided for compatibility with NSEC3 record presentation format, but
ignored since the flags do not affect the hash.
This is provided for compatibility with NSEC3 record presentation format, but
is ignored since the flags do not affect the hash.
``iterations``
The number of additional times the hash should be performed.
This is the number of additional times the hash should be performed.
``domain``
The domain name to be hashed.
This is the domain name to be hashed.
See Also
~~~~~~~~