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
~~~~~~~~~~~
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
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
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
~~~~~~~~~~~
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.
::
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.
::
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
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.
-
-**-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
+ with a user (KEY)), or OTHER (DNSKEY). These values are
+ case-insensitive.
+
+``-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'.
-
-**-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** sync date/offset
- Sets the date on which the CDS and CDNSKEY records which 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".
-
-**-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.
-
-**-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
+explicitly prevent a date from being set, use ``none`` or ``never``.
+
+``-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``
+ 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``
+ 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``
+ 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``
+ 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,
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.
``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.
~~~~~~~~
: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`.
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,
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.
``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.
``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``
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
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.
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
};
-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``:
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.
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.
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
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.)
-
- 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``
+ 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 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``.
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
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
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.
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.
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.
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``
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
``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
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
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
``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
~~~~~~~~
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
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".
-
-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.
-
-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.
+``-c class``
+ This option sets the query class to ``class``. It can be any valid
+ query class which is supported in BIND 9. The default query class is
+ "IN".
+
+``-t type``
+ 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.
+
+``-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
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
~~~~~~~~
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
~~~~~~~~
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.
~~~~~~~~~
``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
~~~~~~~~
projects / thirdparty / bind9.git / commitdiff
