~~~~~~~~~~~
:program:`named-checkconf` checks the syntax, but not the semantics, of a
-``named`` configuration file. The file, along with all files included by it, is parsed and checked for syntax
+:iscman:`named` configuration file. The file, along with all files included by it, is parsed and checked for syntax
errors. If no file is specified,
|named_conf| is read by default.
-Note: files that ``named`` reads in separate parser contexts, such as
+Note: files that :iscman:`named` reads in separate parser contexts, such as
``rndc.key`` and ``bind.keys``, are not automatically read by
:program:`named-checkconf`. Configuration errors in these files may cause
-``named`` to fail to run, even if :program:`named-checkconf` was successful.
+:iscman:`named` to fail to run, even if :program:`named-checkconf` was successful.
However, :program:`named-checkconf` can be run on these files explicitly.
Options
.. option:: -j
- When loading a zonefile, this option instructs ``named`` to read the journal if it exists.
+ When loading a zonefile, this option instructs :iscman:`named` to read the journal if it exists.
.. option:: -l
.. option:: -p
- This option prints out the ``named.conf`` and included files in canonical form if
+ This option prints out the :iscman:`named.conf` and included files in canonical form if
no errors were detected. See also the :option:`-x` option.
.. option:: -t directory
- This option instructs ``named`` to chroot to ``directory``, so that ``include`` directives in the
+ This option instructs :iscman:`named` to chroot to ``directory``, so that ``include`` directives in the
configuration file are processed as if run by a similarly chrooted
- ``named``.
+ :iscman:`named`.
.. option:: -v
When printing the configuration files in canonical form, this option obscures
shared secrets by replacing them with strings of question marks
- (``?``). This allows the contents of ``named.conf`` and related files
+ (``?``). This allows the contents of :iscman:`named.conf` and related files
to be shared - for example, when submitting bug reports -
without compromising private data. This option cannot be used without
:option:`-p`.
.. option:: -z
- This option performs a test load of all zones of type ``primary`` found in ``named.conf``.
+ This option performs a test load of all zones of type ``primary`` found in :iscman:`named.conf`.
.. option:: filename
~~~~~~~~~~~
:program:`named-checkzone` checks the syntax and integrity of a zone file. It
-performs the same checks as ``named`` does when loading a zone. This
+performs the same checks as :iscman:`named` does when loading a zone. This
makes :program:`named-checkzone` useful for checking zone files before
configuring them into a name server.
.. option:: -j
- When loading a zone file, this option tells ``named`` to read the journal if it exists. The journal
+ When loading a zone file, this option tells :iscman:`named` to read the journal if it exists. The journal
file name is assumed to be the zone file name with the
string ``.jnl`` appended.
.. option:: -J filename
- When loading the zone file, this option tells ``named`` to read the journal from the given file, if
+ When loading the zone file, this option tells :iscman:`named` to read the journal from the given file, if
it exists. This implies :option:`-j`.
.. option:: -c class
Possible formats are ``text`` (the default), which is the standard
textual representation of the zone, and ``raw`` and ``raw=N``, which
- store the zone in a binary format for rapid loading by ``named``.
+ store the zone in a binary format for rapid loading by :iscman:`named`.
``raw=N`` specifies the format version of the raw zone file: if ``N`` is
- 0, the raw file can be read by any version of ``named``; if N is 1, the
+ 0, the raw file can be read by any version of :iscman:`named`; if N is 1, the
file can only be read by release 9.9.0 or higher. The default is 1.
.. option:: -k mode
This option sets a maximum permissible TTL for the input file. Any record with a
TTL higher than this value causes the zone to be rejected. This
- is similar to using the ``max-zone-ttl`` option in ``named.conf``.
+ is similar to using the ``max-zone-ttl`` option in :iscman:`named.conf`.
.. option:: -L serial
.. option:: -t directory
- This option tells ``named`` to chroot to ``directory``, so that ``include`` directives in the
+ This option tells :iscman:`named` to chroot to ``directory``, so that ``include`` directives in the
configuration file are processed as if run by a similarly chrooted
- ``named``.
+ :iscman:`named`.
.. option:: -T mode
.. option:: -w directory
- This option instructs ``named`` to chdir to ``directory``, so that relative filenames in master file
+ This option instructs :iscman:`named` to chdir to ``directory``, so that relative filenames in master file
``$INCLUDE`` directives work. This is similar to the directory clause in
- ``named.conf``.
+ :iscman:`named.conf`.
.. option:: -D
:program:`named-compilezone` checks the syntax and integrity of a zone file,
and dumps the zone contents to a specified file in a specified format.
It applies strict check levels by default, since the
-dump output is used as an actual zone file loaded by ``named``.
+dump output is used as an actual zone file loaded by :iscman:`named`.
When manually specified otherwise, the check levels must at least be as
-strict as those specified in the ``named`` configuration file.
+strict as those specified in the :iscman:`named` configuration file.
Options
~~~~~~~
.. option:: -v
- This option prints the version of the ``named-checkzone`` program and exits.
+ This option prints the version of the :iscman:`named-checkzone` program and exits.
.. option:: -j
- When loading a zone file, this option tells ``named`` to read the journal if it exists. The journal
+ When loading a zone file, this option tells :iscman:`named` to read the journal if it exists. The journal
file name is assumed to be the zone file name with the
string ``.jnl`` appended.
.. option:: -J filename
- When loading the zone file, this option tells ``named`` to read the journal from the given file, if
+ When loading the zone file, this option tells :iscman:`named` to read the journal from the given file, if
it exists. This implies :option:`-j`.
.. option:: -c class
.. option:: -F format
This option specifies the format of the output file specified. For
- ``named-checkzone``, this does not have any effect unless it dumps
+ :iscman:`named-checkzone`, this does not have any effect unless it dumps
the zone contents.
Possible formats are ``text`` (the default), which is the standard
textual representation of the zone, and ``raw`` and ``raw=N``, which
- store the zone in a binary format for rapid loading by ``named``.
+ store the zone in a binary format for rapid loading by :iscman:`named`.
``raw=N`` specifies the format version of the raw zone file: if ``N`` is
- 0, the raw file can be read by any version of ``named``; if N is 1, the
+ 0, the raw file can be read by any version of :iscman:`named`; if N is 1, the
file can only be read by release 9.9.0 or higher. The default is 1.
.. option:: -k mode
This option sets a maximum permissible TTL for the input file. Any record with a
TTL higher than this value causes the zone to be rejected. This
- is similar to using the ``max-zone-ttl`` option in ``named.conf``.
+ is similar to using the ``max-zone-ttl`` option in :iscman:`named.conf`.
.. option:: -L serial
.. option:: -t directory
- This option tells ``named`` to chroot to ``directory``, so that ``include`` directives in the
+ This option tells :iscman:`named` to chroot to ``directory``, so that ``include`` directives in the
configuration file are processed as if run by a similarly chrooted
- ``named``.
+ :iscman:`named`.
.. option:: -T mode
.. option:: -w directory
- This option instructs ``named`` to chdir to ``directory``, so that relative filenames in master file
+ This option instructs :iscman:`named` to chdir to ``directory``, so that relative filenames in master file
``$INCLUDE`` directives work. This is similar to the directory clause in
- ``named.conf``.
+ :iscman:`named.conf`.
.. option:: -D
:program:`ddns-confgen` is an utility that generates keys for use in TSIG signing.
The resulting keys can be used, for example, to secure dynamic DNS updates
-to a zone, or for the ``rndc`` command channel.
+to a zone, or for the :iscman:`rndc` command channel.
The key name can specified using :option:`-k` parameter and defaults to ``ddns-key``.
The generated key is accompanied by configuration text and instructions that
-can be used with ``nsupdate`` and ``named`` when setting up dynamic DNS,
+can be used with :iscman:`nsupdate` and :iscman:`named` when setting up dynamic DNS,
including an example ``update-policy`` statement.
-(This usage is similar to the ``rndc-confgen`` command for setting up
+(This usage is similar to the :iscman:`rndc-confgen` command for setting up
command-channel security.)
-Note that ``named`` itself can configure a local DDNS key for use with
+Note that :iscman:`named` itself can configure a local DDNS key for use with
:option:`nsupdate -l`; it does this when a zone is configured with
``update-policy local;``. :program:`ddns-confgen` is only needed when a more
-elaborate configuration is required: for instance, if ``nsupdate`` is to
+elaborate configuration is required: for instance, if :iscman:`nsupdate` is to
be used from a remote system.
Options
This option enables quiet mode, which prints only the key, with no
explanatory text or usage examples. This is essentially identical to
- ``tsig-keygen``.
+ :iscman:`tsig-keygen`.
.. option:: -s name
This option generates a configuration example to allow dynamic updates
- of a single hostname. The example ``named.conf`` text shows how to set
+ of a single hostname. The example :iscman:`named.conf` text shows how to set
an update policy for the specified name using the "name" nametype. The
default key name is ``ddns-key.name``. Note that the "self" nametype
cannot be used, since the name to be updated may differ from the key
.. option:: -z zone
This option generates a configuration example to allow
- dynamic updates of a zone. The example ``named.conf`` text shows how
+ dynamic updates of a zone. The example :iscman:`named.conf` text shows how
to set an update policy for the specified zone using the "zonesub"
nametype, allowing updates to all subdomain names within that zone.
This option cannot be used with the :option:`-s` option.
Description
~~~~~~~~~~~
-:program:`rndc-confgen` generates configuration files for ``rndc``. It can be
-used as a convenient alternative to writing the ``rndc.conf`` file and
-the corresponding ``controls`` and ``key`` statements in ``named.conf``
+:program:`rndc-confgen` generates configuration files for :iscman:`rndc`. It can be
+used as a convenient alternative to writing the :iscman:`rndc.conf` file and
+the corresponding ``controls`` and ``key`` statements in :iscman:`named.conf`
by hand. Alternatively, it can be run with the :option:`-a` option to set up a
-``rndc.key`` file and avoid the need for a ``rndc.conf`` file and a
+``rndc.key`` file and avoid the need for a :iscman:`rndc.conf` file and a
``controls`` statement altogether.
Options
.. option:: -a
- This option sets automatic ``rndc`` configuration, which creates a file
- |rndc_key| that is read by both ``rndc`` and ``named`` on startup.
+ This option sets automatic :iscman:`rndc` configuration, which creates a file
+ |rndc_key| that is read by both :iscman:`rndc` and :iscman:`named` on startup.
The ``rndc.key`` file defines a default command channel and
- authentication key allowing ``rndc`` to communicate with ``named`` on
+ authentication key allowing :iscman:`rndc` to communicate with :iscman:`named` on
the local host with no further configuration.
If a more elaborate configuration than that generated by
:option:`rndc-confgen -a` is required, for example if rndc is to be used
remotely, run :program:`rndc-confgen` without the :option:`-a` option
- and set up ``rndc.conf`` and ``named.conf`` as directed.
+ and set up :iscman:`rndc.conf` and :iscman:`named.conf` as directed.
.. option:: -A algorithm
.. option:: -k keyname
- This option specifies the key name of the ``rndc`` authentication key. This must be a
+ This option specifies the key name of the :iscman:`rndc` authentication key. This must be a
valid domain name. The default is ``rndc-key``.
.. option:: -p port
- This option specifies the command channel port where ``named`` listens for
- connections from ``rndc``. The default is 953.
+ This option specifies the command channel port where :iscman:`named` listens for
+ connections from :iscman:`rndc`. The default is 953.
.. option:: -q
.. option:: -s address
- This option specifies the IP address where ``named`` listens for command-channel
- connections from ``rndc``. The default is the loopback address
+ This option specifies the IP address where :iscman:`named` listens for command-channel
+ connections from :iscman:`rndc`. The default is the loopback address
127.0.0.1.
.. option:: -t chrootdir
- This option is used with the :option:`-a` option to specify a directory where ``named``
+ This option is used with the :option:`-a` option to specify a directory where :iscman:`named`
runs chrooted. An additional copy of the ``rndc.key`` is
written relative to this directory, so that it is found by the
- chrooted ``named``.
+ chrooted :iscman:`named`.
.. option:: -u user
Examples
~~~~~~~~
-To allow ``rndc`` to be used with no manual configuration, run:
+To allow :iscman:`rndc` to be used with no manual configuration, run:
``rndc-confgen -a``
-To print a sample ``rndc.conf`` file and the corresponding ``controls`` and
-``key`` statements to be manually inserted into ``named.conf``, run:
+To print a sample :iscman:`rndc.conf` file and the corresponding ``controls`` and
+``key`` statements to be manually inserted into :iscman:`named.conf`, run:
:program:`rndc-confgen`
:program:`tsig-keygen` is an utility that generates keys for use in TSIG signing.
The resulting keys can be used, for example, to secure dynamic DNS updates
-to a zone, or for the ``rndc`` command channel.
+to a zone, or for the :iscman:`rndc` command channel.
A domain name can be specified on the command line to be used as the name
of the generated key. If no name is specified, the default is ``tsig-key``.
~~~~~~~~~~~
:program:`delv` is a tool for sending DNS queries and validating the results,
-using the same internal resolver and validator logic as ``named``.
+using the same internal resolver and validator logic as :iscman:`named`.
:program:`delv` sends to a specified name server all queries needed to
fetch and validate the requested data; this includes the original
``initial-key``, and ``static-key`` identically. That is, for a managed key,
it is the *initial* key that is trusted; :rfc:`5011` key management is not
supported. :program:`delv` does not consult the managed-keys database maintained by
- ``named``, which means that if either of the keys in |bind_keys| is
+ :iscman:`named`, which means that if either of the keys in |bind_keys| is
revoked and rolled over, |bind_keys| must be updated to
use DNSSEC validation in :program:`delv`.
.. option:: +[no]dnssec
This option indicates whether to display RRSIG records in the :program:`delv` output.
- The default is to do so. Note that (unlike in ``dig``) this does
+ The default is to do so. Note that (unlike in :iscman:`dig`) this does
*not* control whether to request DNSSEC records or to
validate them. DNSSEC records are always requested, and validation
always occurs unless suppressed by the use of :option:`-i` or
.. option:: -k keyfile
- This option tells ``named`` to sign queries using TSIG using a key read from the given file. Key
- files can be generated using ``tsig-keygen``. When using TSIG
+ This option tells :iscman:`named` to sign queries using TSIG using a key read from the given file. Key
+ files can be generated using :iscman:`tsig-keygen`. When using TSIG
authentication with :program:`dig`, the name server that is queried needs to
know the key and algorithm that is being used. In BIND, this is done
by providing appropriate ``key`` and ``server`` statements in
- ``named.conf``.
+ :iscman:`named.conf`.
.. option:: -m
.. option:: +[no]fail
- This option indicates that ``named`` should try [or not try] the next server if a SERVFAIL is received. The default is
+ This option indicates that :iscman:`named` should try [or not try] the next server if a SERVFAIL is received. The default is
to not try the next server, which is the reverse of normal stub
resolver behavior.
.. option:: +[no]sigchase
- This feature is now obsolete and has been removed; use ``delv``
+ This feature is now obsolete and has been removed; use :iscman:`delv`
instead.
.. option:: +split=W
.. option:: +[no]topdown
This feature is related to ``dig +sigchase``, which is obsolete and
- has been removed. Use ``delv`` instead.
+ has been removed. Use :iscman:`delv` instead.
.. option:: +[no]trace
.. option:: +trusted-key=####
This option formerly specified trusted keys for use with ``dig +sigchase``. This
- feature is now obsolete and has been removed; use ``delv`` instead.
+ feature is now obsolete and has been removed; use :iscman:`delv` instead.
.. option:: +[no]ttlid
.. option:: -C
- This option indicates that ``named`` should check consistency, meaning that :program:`host` queries the SOA records for zone
+ This option indicates that :iscman:`named` should check consistency, meaning that :program:`host` queries the SOA records for zone
``name`` from all the listed authoritative name servers for that
zone. The list of name servers is defined by the NS records that are
found for the zone.
.. option:: -l
- This option tells ``named`` to list the zone, meaning the :program:`host` command performs a zone transfer of zone
+ This option tells :iscman:`named` to list the zone, meaning the :program:`host` command performs a zone transfer of zone
``name`` and prints out the NS, PTR, and address records (A/AAAA).
Together, the :option:`-l` :option:`-a` options print all records in the zone.
.. option:: -s
- This option tells ``named`` *not* to send the query to the next nameserver if any server responds
+ This option tells :iscman:`named` *not* to send the query to the next nameserver if any server responds
with a SERVFAIL response, which is the reverse of normal stub
resolver behavior.
.. option:: -W wait
- This options sets the length of the wait timeout, indicating that ``named`` should wait for up to ``wait`` seconds for a reply. If ``wait`` is
+ This options sets the length of the wait timeout, indicating that :iscman:`named` should wait for up to ``wait`` seconds for a reply. If ``wait`` is
less than 1, the wait interval is set to 1 second.
By default, :program:`host` waits for 5 seconds for UDP responses and 10
~~~~~~~~~~~~~~~~~~~~
``host [server]``
- This command looks up information for ``host`` using the current default server or
- using ``server``, if specified. If ``host`` is an Internet address and the
- query type is A or PTR, the name of the host is returned. If ``host`` is
+ This command looks up information for :iscman:`host` using the current default server or
+ using ``server``, if specified. If :iscman:`host` is an Internet address and the
+ query type is A or PTR, the name of the host is returned. If :iscman:`host` is
a name and does not have a trailing period (``.``), the search list is used
to qualify the name.
DNSKEY records so that they can be authenticated. The :option:`-d path <-d>` option
specifies the location of a file containing the current DS records. For
example, this could be a ``dsset-`` file generated by
-``dnssec-signzone``, or the output of ``dnssec-dsfromkey``, or the
+:iscman:`dnssec-signzone`, or the output of :iscman:`dnssec-dsfromkey`, or the
output of a previous run of :program:`dnssec-cds`.
The :program:`dnssec-cds` command uses special DNSSEC validation logic
Be careful not to delete the DS records when :program:`dnssec-cds` fails!
-Alternatively, :option`dnssec-cds -u` writes an ``nsupdate`` script to the
+Alternatively, :option`dnssec-cds -u` writes an :iscman:`nsupdate` script to the
standard output. The :option:`-u` and :option:`-i` options can be used together to
-maintain a ``dsset-`` file as well as emit an ``nsupdate`` script.
+maintain a ``dsset-`` file as well as emit an :iscman:`nsupdate` script.
Options
~~~~~~~
.. option:: -u
- This option writes an ``nsupdate`` script to the standard output, instead of
+ This option writes an :iscman:`nsupdate` script to the standard output, instead of
printing the new DS reords. The output is empty if no change is
needed.
Note: The TTL of new records needs to be specified: it can be done in the
original ``dsset-`` file, with the :option:`-T` option, or using the
- ``nsupdate`` ``ttl`` command.
+ :iscman:`nsupdate` ``ttl`` command.
.. option:: -V
Examples
~~~~~~~~
-Before running ``dnssec-signzone``, ensure that the delegations
+Before running :iscman:`dnssec-signzone`, ensure that the delegations
are up-to-date by running :program:`dnssec-cds` on every ``dsset-`` file.
To fetch the child records required by :program:`dnssec-cds`, invoke
-``dig`` as in the script below. It is acceptable if the ``dig`` fails, since
+:iscman:`dig` as in the script below. It is acceptable if the :iscman:`dig` fails, since
:program:`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``,
-:program:`dnssec-cds` can be used with ``nsupdate`` to maintain a delegation as follows.
+When the parent zone is automatically signed by :iscman:`named`,
+:program:`dnssec-cds` can be used with :iscman:`nsupdate` to maintain a delegation as follows.
The ``dsset-`` file allows the script to avoid having to fetch and
validate the parent DS records, and it maintains the replay attack
protection time.
The input keys can be specified in a number of ways:
By default, :program:`dnssec-dsfromkey` reads a key file named in the format
-``Knnnn.+aaa+iiiii.key``, as generated by ``dnssec-keygen``.
+``Knnnn.+aaa+iiiii.key``, as generated by :iscman:`dnssec-keygen`.
With the :option:`-f file <-f>` option, :program:`dnssec-dsfromkey` reads keys from a zone
file or partial zone file (which can contain just the DNSKEY records).
With the :option:`-s` option, :program:`dnssec-dsfromkey` reads a ``keyset-`` file,
-as generated by ``dnssec-keygen`` :option:`-C`.
+as generated by :iscman:`dnssec-keygen` :option:`-C`.
Options
~~~~~~~
omitted.
If ``file`` is ``-``, then the zone data is read from the standard
- input. This makes it possible to use the output of the ``dig``
+ input. This makes it possible to use the output of the :iscman:`dig`
command as input, as in:
``dig dnskey example.com | dnssec-dsfromkey -f - example.com``
The keyfile can be designated by the key identification
``Knnnn.+aaa+iiiii`` or the full file name ``Knnnn.+aaa+iiiii.key``, as
-generated by ``dnssec-keygen``.
+generated by :iscman:`dnssec-keygen`.
The keyset file name is built from the ``directory``, the string
``keyset-``, and the ``dnsname``.
A keyfile can be designed by the key identification ``Knnnn.+aaa+iiiii``
or the full file name ``Knnnn.+aaa+iiiii.key``, as generated by
-``dnssec-keygen``.
+:iscman:`dnssec-keygen`.
See Also
~~~~~~~~
:program:`dnssec-keyfromlabel` generates a pair of key files that reference a
key object stored in a cryptographic hardware service module (HSM). The
private key file can be used for DNSSEC signing of zone data as if it
-were a conventional signing key created by ``dnssec-keygen``, but the
+were a conventional signing key created by :iscman:`dnssec-keygen`, but the
key material is stored within the HSM and the actual signing takes
place there.
In prior releases, HMAC algorithms could be generated for use as TSIG
keys, but that feature was removed in BIND 9.13.0. Use
- ``tsig-keygen`` to generate TSIG keys.
+ :iscman:`tsig-keygen` to generate TSIG keys.
.. option:: -b keysize
``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 :option:`dnssec-signzone -S`, DNSKEY records are
+signed by :iscman:`named` or :option:`dnssec-signzone -S`, DNSKEY records are
included automatically. In other cases, the ``.key`` file can be
inserted into a zone file manually or with an ``$INCLUDE`` statement.
:program:`dnssec-settime` reads a DNSSEC private key file and sets the key
timing metadata as specified by the :option:`-P`, :option:`-A`, :option:`-R`,
:option:`-I`, and :option:`-D` options. The metadata can then be used by
-``dnssec-signzone`` or other signing software to determine when a key is
+:iscman:`dnssec-signzone` or other signing software to determine when a key is
to be published, whether it should be used for signing a zone, etc.
If none of these options is set on the command line,
possible time before signatures that have been retrieved by resolvers
expire from resolver caches. Zones that are signed with this
option should be configured to use a matching ``max-zone-ttl`` in
- ``named.conf``. (Note: This option is incompatible with :option:`-D`,
+ :iscman:`named.conf`. (Note: This option is incompatible with :option:`-D`,
because it modifies non-DNSSEC data in the output zone.)
.. option:: -s start-time
textual representation of the zone; ``full``, which is text output in a
format suitable for processing by external scripts; and ``raw`` and
``raw=N``, which store the zone in binary formats for rapid loading by
- ``named``. ``raw=N`` specifies the format version of the raw zone file:
- if N is 0, the raw file can be read by any version of ``named``; if N is
+ :iscman:`named`. ``raw=N`` specifies the format version of the raw zone file:
+ if N is 0, the raw file can be read by any version of :iscman:`named`; if N is
1, the file can be read by release 9.9.0 or higher. The default is 1.
.. option:: -P
This option indicates that BIND 9 should only sign the DNSKEY, CDNSKEY, and CDS RRsets with key-signing keys,
and should omit signatures from zone-signing keys. (This is similar to the
- ``dnssec-dnskey-kskonly yes;`` zone option in ``named``.)
+ ``dnssec-dnskey-kskonly yes;`` zone option in :iscman:`named`.)
.. option:: -z
This option indicates that BIND 9 should ignore the KSK flag on keys when determining what to sign. This causes
KSK-flagged keys to sign all records, not just the DNSKEY RRset.
(This is similar to the ``update-check-ksk no;`` zone option in
- ``named``.)
+ :iscman:`named`.)
.. option:: -3 salt
~~~~~~~
The following command signs the ``example.com`` zone with the
-ECDSAP256SHA256 key generated by ``dnssec-keygen``
+ECDSAP256SHA256 key generated by :iscman:`dnssec-keygen`
(Kexample.com.+013+17247). Because the :option:`-S` option is not being used,
the zone's keys must be in the master file (``db.example.com``). This
invocation looks for ``dsset`` files in the current directory, so that
In the above example, :program:`dnssec-signzone` creates the file
``db.example.com.signed``. This file should be referenced in a zone
-statement in the ``named.conf`` file.
+statement in the :iscman:`named.conf` file.
This example re-signs a previously signed zone with default parameters.
The private keys are assumed to be in the current directory.
Description
~~~~~~~~~~~
-``named.conf`` is the configuration file for ``named``. Statements are
+:iscman:`named.conf` is the configuration file for :iscman:`named`. Statements are
enclosed in braces and terminated with a semi-colon. Clauses in the
statements are also semi-colon terminated. The usual comment styles are
supported:
This option acquires a lock on the specified file at runtime; this helps to
prevent duplicate :program:`named` instances from running simultaneously.
Use of this option overrides the ``lock-file`` option in
- ``named.conf``. If set to ``none``, the lock file check is disabled.
+ :iscman:`named.conf`. If set to ``none``, the lock file check is disabled.
Signals
~~~~~~~
In routine operation, signals should not be used to control the
-nameserver; ``rndc`` should be used instead.
+nameserver; :iscman:`rndc` should be used instead.
SIGHUP
This signal forces a reload of the server.
statements are added to |named_conf| so that the name server
can associate the appropriate secret key and algorithm with the IP
address of the client application that is using TSIG
-authentication. ``ddns-confgen`` can generate suitable
+authentication. :iscman:`ddns-confgen` can generate suitable
configuration fragments. :program:`nsupdate` uses the :option:`-y` or :option:`-k` options
to provide the TSIG shared secret; these options are mutually exclusive.
.. option:: -k keyfile
This option indicates the file containing the TSIG authentication key. Keyfiles may be in
- two formats: a single file containing a ``named.conf``-format ``key``
- statement, which may be generated automatically by ``ddns-confgen``;
+ two formats: a single file containing a :iscman:`named.conf`-format ``key``
+ statement, which may be generated automatically by :iscman:`ddns-confgen`;
or a pair of files whose names are of the format
``K{name}.+157.+{random}.key`` and
``K{name}.+157.+{random}.private``, which can be generated by
- ``dnssec-keygen``. The :option:`-k` option can also be used to specify a SIG(0)
+ :iscman:`dnssec-keygen`. The :option:`-k` option can also be used to specify a SIG(0)
key used to authenticate Dynamic DNS update requests. In this case,
the key specified is not an HMAC-MD5 key.
(disabling the ``server`` so that the server address cannot be
overridden). Connections to the local server use a TSIG key
found in |session_key|, which is automatically
- generated by ``named`` if any local ``primary`` zone has set
+ generated by :iscman:`named` if any local ``primary`` zone has set
``update-policy`` to ``local``. The location of this key file can be
overridden with the :option:`-k` option.
Sets the default TSIG key for use in local-only mode
``K{name}.+157.+{random}.key``
- Base-64 encoding of the HMAC-MD5 key created by ``dnssec-keygen``.
+ Base-64 encoding of the HMAC-MD5 key created by :iscman:`dnssec-keygen`.
``K{name}.+157.+{random}.private``
- Base-64 encoding of the HMAC-MD5 key created by ``dnssec-keygen``.
+ Base-64 encoding of the HMAC-MD5 key created by :iscman:`dnssec-keygen`.
See Also
~~~~~~~~
Description
~~~~~~~~~~~
-``filter-a.so`` is a query plugin module for ``named``, enabling
-``named`` to omit some IPv4 addresses when responding to clients.
+:program:`filter-a.so` is a query plugin module for :iscman:`named`, enabling
+:iscman:`named` to omit some IPv4 addresses when responding to clients.
For example:
Description
~~~~~~~~~~~
-``filter-aaaa.so`` is a query plugin module for ``named``, enabling
-``named`` to omit some IPv6 addresses when responding to clients.
+:program:`filter-aaaa.so` is a query plugin module for :iscman:`named`, enabling
+:iscman:`named` to omit some IPv6 addresses when responding to clients.
-Until BIND 9.12, this feature was implemented natively in ``named`` and
+Until BIND 9.12, this feature was implemented natively in :iscman:`named` and
enabled with the ``filter-aaaa`` ACL and the ``filter-aaaa-on-v4`` and
``filter-aaaa-on-v6`` options. These options are now deprecated in
-``named.conf`` but can be passed as parameters to the
+:iscman:`named.conf` but can be passed as parameters to the
``filter-aaaa.so`` plugin, for example:
::
Description
~~~~~~~~~~~
-:program:`rndc.conf` is the configuration file for ``rndc``, the BIND 9 name
+:program:`rndc.conf` is the configuration file for :iscman:`rndc`, the BIND 9 name
server control utility. This file has a similar structure and syntax to
-``named.conf``. Statements are enclosed in braces and terminated with a
+:iscman:`named.conf`. Statements are enclosed in braces and terminated with a
semi-colon. Clauses in the statements are also semi-colon terminated.
The usual comment styles are supported:
Unix style: # to end of line
-:program:`rndc.conf` is much simpler than ``named.conf``. The file uses three
+:program:`rndc.conf` is much simpler than :iscman:`named.conf`. The file uses three
statements: an options statement, a server statement, and a key
statement.
The ``options`` statement contains five clauses. The ``default-server``
clause is followed by the name or address of a name server. This host
-is used when no name server is given as an argument to ``rndc``.
+is used when no name server is given as an argument to :iscman:`rndc`.
The ``default-key`` clause is followed by the name of a key, which is
identified by a ``key`` statement. If no ``keyid`` is provided on the
rndc command line, and no ``key`` clause is found in a matching
The ``key`` statement begins with an identifying string, the name of the
key. The statement has two clauses. ``algorithm`` identifies the
-authentication algorithm for ``rndc`` to use; currently only HMAC-MD5
+authentication algorithm for :iscman:`rndc` to use; currently only HMAC-MD5
(for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (default),
HMAC-SHA384, and HMAC-SHA512 are supported. This is followed by a secret
clause which contains the base-64 encoding of the algorithm's
authentication key. The base-64 string is enclosed in double quotes.
There are two common ways to generate the base-64 string for the secret.
-The BIND 9 program ``rndc-confgen`` can be used to generate a random
+The BIND 9 program :iscman:`rndc-confgen` can be used to generate a random
key, or the ``mmencode`` program, also known as ``mimencode``, can be
used to generate a base-64 string from known input. ``mmencode`` does
not ship with BIND 9 but is available on many systems. See the Example
};
-In the above example, ``rndc`` by default uses the server at
+In the above example, :iscman:`rndc` by default uses the server at
localhost (127.0.0.1) and the key called "samplekey". Commands to the
localhost server use the "samplekey" key, which must also be defined
in the server's configuration file with the same name and secret. The
and its secret clause contains the base-64 encoding of the HMAC-SHA256
secret enclosed in double quotes.
-If :option:`rndc -s testserver <rndc -s>` is used, then ``rndc`` connects to the server
+If :option:`rndc -s testserver <rndc -s>` is used, then :iscman:`rndc` connects to the server
on localhost port 5353 using the key "testkey".
-To generate a random secret with ``rndc-confgen``:
+To generate a random secret with :iscman:`rndc-confgen`:
-``rndc-confgen``
+:iscman:`rndc-confgen`
A complete :program:`rndc.conf` file, including the randomly generated key,
is written to the standard output. Commented-out ``key`` and
-``controls`` statements for ``named.conf`` are also printed.
+``controls`` statements for :iscman:`named.conf` are also printed.
To generate a base-64 secret with ``mmencode``:
The name server must be configured to accept rndc connections and to
recognize the key specified in the :program:`rndc.conf` file, using the
-controls statement in ``named.conf``. See the sections on the
+controls statement in :iscman:`named.conf`. See the sections on the
``controls`` statement in the BIND 9 Administrator Reference Manual for
details.
:program:`rndc` communicates with the name server over a TCP connection,
sending commands authenticated with digital signatures. In the current
-versions of :program:`rndc` and ``named``, the only supported authentication
+versions of :program:`rndc` and :iscman:`named`, the only supported authentication
algorithms are HMAC-MD5 (for compatibility), HMAC-SHA1, HMAC-SHA224,
HMAC-SHA256 (default), HMAC-SHA384, and HMAC-SHA512. They use a shared
secret on each end of the connection, which provides TSIG-style
.. option:: -r
- This option instructs :program:`rndc` to print the result code returned by ``named``
+ This option instructs :program:`rndc` to print the result code returned by :iscman:`named`
after executing the requested command (e.g., ISC_R_SUCCESS,
ISC_R_FAILURE, etc.).
.. option:: -y key_id
This option indicates use of the key ``key_id`` from the configuration file. For control message validation to succeed, ``key_id`` must be known
- by ``named`` with the same algorithm and secret string. If no ``key_id`` is specified,
+ by :iscman:`named` with the same algorithm and secret string. If no ``key_id`` is specified,
:program:`rndc` first looks for a key clause in the server statement of
the server being used, or if no server statement is present for that
host, then in the default-key clause of the options statement. Note that
This command adds a zone while the server is running. This command requires the
``allow-new-zones`` option to be set to ``yes``. The configuration
string specified on the command line is the zone configuration text
- that would ordinarily be placed in ``named.conf``.
+ that would ordinarily be placed in :iscman:`named.conf`.
The configuration is saved in a file called ``viewname.nzf`` (or, if
- ``named`` is compiled with liblmdb, an LMDB database file called
+ :iscman:`named` is compiled with liblmdb, an LMDB database file called
``viewname.nzd``). ``viewname`` is the name of the view, unless the view
name contains characters that are incompatible with use as a file
name, in which case a cryptographic hash of the view name is used
- instead. When ``named`` is restarted, the file is loaded into
+ instead. When :iscman:`named` is restarted, the file is loaded into
the view configuration so that zones that were added can persist
after a restart.
If the zone was originally added via ``rndc addzone``, then it is
removed permanently. However, if it was originally configured in
- ``named.conf``, then that original configuration remains in place;
+ :iscman:`named.conf`, then that original configuration remains in place;
when the server is restarted or reconfigured, the zone is
recreated. To remove it permanently, it must also be removed from
- ``named.conf``.
+ :iscman:`named.conf`.
See also :option:`rndc addzone` and :option:`rndc modzone`.
``rndc dnssec -rollover`` allows you to schedule key rollover for a
specific key (overriding the original key lifetime).
- ``rndc dnssec -checkds`` will let ``named`` know that the DS for the given
+ ``rndc dnssec -checkds`` will let :iscman:`named` know that the DS for the given
key has been seen published into or withdrawn from the parent. This is
required in order to complete a KSK rollover. If the ``-key id`` argument
is specified, look for the key with the given identifier, otherwise if there
.. option:: dnstap (-reopen | -roll [number])
This command closes and re-opens DNSTAP output files. ``rndc dnstap -reopen`` allows
- the output file to be renamed externally, so that ``named`` can
+ the output file to be renamed externally, so that :iscman:`named` can
truncate and re-open it. ``rndc dnstap -roll`` causes the output file
to be rolled automatically, similar to log files. The most recent
output file has ".0" appended to its name; the previous most recent
This command stops the server immediately. Recent changes made through dynamic
update or IXFR are not saved to the master files, but are rolled
forward from the journal files when the server is restarted. If
- ``-p`` is specified, ``named``'s process ID is returned. This allows
- an external process to determine when ``named`` has completed
+ ``-p`` is specified, :iscman:`named`'s process ID is returned. This allows
+ an external process to determine when :iscman:`named` has completed
halting.
See also :option:`rndc stop`.
Existing keys that are already trusted are not deleted from
memory; DNSSEC validation can continue after this command is used.
- However, key maintenance operations cease until ``named`` is
+ However, key maintenance operations cease until :iscman:`named` is
restarted or reconfigured, and all existing key maintenance states
are deleted.
- Running :option:`rndc reconfig` or restarting ``named`` immediately
+ Running :option:`rndc reconfig` or restarting :iscman:`named` immediately
after this command causes key maintenance to be reinitialized
from scratch, just as if the server were being started for the
first time. This is primarily intended for testing, but it may
command requires the ``allow-new-zones`` option to be set to ``yes``.
As with ``addzone``, the configuration string specified on the
command line is the zone configuration text that would ordinarily be
- placed in ``named.conf``.
+ placed in :iscman:`named.conf`.
If the zone was originally added via :option:`rndc addzone`, the
configuration changes are recorded permanently and are still
in effect after the server is restarted or reconfigured. However, if
- it was originally configured in ``named.conf``, then that original
+ it was originally configured in :iscman:`named.conf`, then that original
configuration remains in place; when the server is restarted or
reconfigured, the zone reverts to its original configuration. To
make the changes permanent, it must also be modified in
- ``named.conf``.
+ :iscman:`named.conf`.
See also :option:`rndc addzone` and :option:`rndc delzone`.
This command sets a DNSSEC negative trust anchor (NTA) for ``domain``, with a
lifetime of ``duration``. The default lifetime is configured in
- ``named.conf`` via the ``nta-lifetime`` option, and defaults to one
+ :iscman:`named.conf` via the ``nta-lifetime`` option, and defaults to one
hour. The lifetime cannot exceed one week.
A negative trust anchor selectively disables DNSSEC validation for
zones that are known to be failing because of misconfiguration rather
than an attack. When data to be validated is at or below an active
- NTA (and above any other configured trust anchors), ``named``
+ NTA (and above any other configured trust anchors), :iscman:`named`
aborts the DNSSEC validation process and treats the data as insecure
rather than bogus. This continues until the NTA's lifetime has
elapsed.
- NTAs persist across restarts of the ``named`` server. The NTAs for a
+ NTAs persist across restarts of the :iscman:`named` server. The NTAs for a
view are saved in a file called ``name.nta``, where ``name`` is the name
of the view; if it contains characters that are incompatible with
use as a file name, a cryptographic hash is generated from the name of
of existing NTAs is printed. Note that this may include NTAs that are
expired but have not yet been cleaned up.
- Normally, ``named`` periodically tests to see whether data below
+ Normally, :iscman:`named` periodically tests to see whether data below
an NTA can now be validated (see the ``nta-recheck`` option in the
Administrator Reference Manual for details). If data can be
validated, then the NTA is regarded as no longer necessary and is
Query logging can also be enabled by explicitly directing the
``queries`` ``category`` to a ``channel`` in the ``logging`` section
- of ``named.conf``, or by specifying ``querylog yes;`` in the
- ``options`` section of ``named.conf``.
+ of :iscman:`named.conf`, or by specifying ``querylog yes;`` in the
+ ``options`` section of :iscman:`named.conf`.
.. option:: reconfig
.. option:: recursing
- This command dumps the list of queries ``named`` is currently
+ This command dumps the list of queries :iscman:`named` is currently
recursing on, and the list of domains to which iterative queries
are currently being sent.
:program:`rndc` response channel and printed to the standard output.
Otherwise, it is written to the secroots dump file, which defaults to
``named.secroots``, but can be overridden via the ``secroots-file``
- option in ``named.conf``.
+ option in :iscman:`named.conf`.
See also :option:`rndc managed-keys`.
.. option:: serve-stale (on | off | reset | status) [class [view]]
This command enables, disables, resets, or reports the current status of
- the serving of stale answers as configured in ``named.conf``.
+ the serving of stale answers as configured in :iscman:`named.conf`.
If serving of stale answers is disabled by ``rndc-serve-stale off``, then it
- remains disabled even if ``named`` is reloaded or reconfigured. ``rndc
- serve-stale reset`` restores the setting as configured in ``named.conf``.
+ remains disabled even if :iscman:`named` is reloaded or reconfigured. ``rndc
+ serve-stale reset`` restores the setting as configured in :iscman:`named.conf`.
``rndc serve-stale status`` reports whether caching and serving of stale
answers is currently enabled or disabled. It also reports the values of
chain should be set. ``iterations`` defines the number of additional times to apply
the algorithm when generating an NSEC3 hash. The ``salt`` is a string
of data expressed in hexadecimal, a hyphen (`-') if no salt is to be
- used, or the keyword ``auto``, which causes ``named`` to generate a
+ used, or the keyword ``auto``, which causes :iscman:`named` to generate a
random 64-bit salt.
So, for example, to create an NSEC3 chain using the SHA-1 hash
This command stops the server, making sure any recent changes made through dynamic
update or IXFR are first saved to the master files of the updated
- zones. If ``-p`` is specified, ``named(8)`'s process ID is returned.
- This allows an external process to determine when ``named`` has
+ zones. If ``-p`` is specified, :iscman:`named`'s process ID is returned.
+ This allows an external process to determine when :iscman:`named` has
completed stopping.
See also :option:`rndc halt`.
.. option:: tsig-list
This command lists the names of all TSIG keys currently configured for use by
- ``named`` in each view. The list includes both statically configured keys and
+ :iscman:`named` in each view. The list includes both statically configured keys and
dynamic TKEY-negotiated keys.
.. option:: validation (on | off | status) [view ...]
Description
~~~~~~~~~~~
-:program:`mdig` is a multiple/pipelined query version of ``dig``: instead of
+:program:`mdig` is a multiple/pipelined query version of :iscman:`dig`: instead of
waiting for a response after sending each query, it begins by sending
all queries. Responses are displayed in the order in which they are
received, not in the order the corresponding queries were sent.
-:program:`mdig` options are a subset of the ``dig`` options, and are divided
+:program:`mdig` options are a subset of the :iscman:`dig` options, and are divided
into "anywhere options," which can occur anywhere, "global options," which
must occur before the query name (or they are ignored with a warning),
and "local options," which apply to the next query on the command line.
The ``@server`` option is a mandatory global option. It is the name or IP
-address of the name server to query. (Unlike ``dig``, this value is not
+address of the name server to query. (Unlike :iscman:`dig`, this value is not
retrieved from ``/etc/resolv.conf``.) It can be an IPv4 address in
dotted-decimal notation, an IPv6 address in colon-delimited notation, or
a hostname. When the supplied ``server`` argument is a hostname,
printing it in a human-readable form, or, optionally, converting it
to a different journal file format.
-Journal files are automatically created by ``named`` when changes are
-made to dynamic zones (e.g., by ``nsupdate``). They record each addition
+Journal files are automatically created by :iscman:`named` when changes are
+made to dynamic zones (e.g., by :iscman:`nsupdate`). They record each addition
or deletion of a resource record, in binary format, allowing the changes
to be re-applied to the zone when the server is restarted after a
shutdown or crash. By default, the name of the journal file is formed by
The ``-c`` (compact) option provides a mechanism to reduce the size of
a journal by removing (most/all) transactions prior to the specified
-serial number. Note: this option *must not* be used while ``named`` is
+serial number. Note: this option *must not* be used while :iscman:`named` is
running, and can cause data loss if the zone file has not been updated
to contain the data being removed from the journal. Use with extreme caution.
versions of BIND up to 9.16.11; ``-u`` writes it out in the format used
by versions since 9.16.13. (9.16.12 is omitted due to a journal-formatting
bug in that release.) Note that these options *must not* be used while
-``named`` is running.
+:iscman:`named` is running.
See Also
~~~~~~~~
:program:`named-nzd2nzf` converts an NZD database to NZF format and prints it
to standard output. This can be used to review the configuration of
-zones that were added to ``named`` via :option:`rndc addzone`. It can also be
+zones that were added to :iscman:`named` via :option:`rndc addzone`. It can also be
used to restore the old file format when rolling back from a newer
version of BIND to an older version.
.. note::
- As a secondary zone can also be a primary to other secondaries, ``named``, by
+ As a secondary zone can also be a primary to other secondaries, :iscman:`named`, by
default, sends ``NOTIFY`` messages for every zone it loads.
- Specifying ``notify primary-only;`` causes ``named`` to only send
+ Specifying ``notify primary-only;`` causes :iscman:`named` to only send
``NOTIFY`` for primary zones that it loads.
.. _dynamic_update:
If the zone's ``update-policy`` is set to ``local``, updates to the zone
are permitted for the key ``local-ddns``, which is generated by
-``named`` at startup. See :ref:`dynamic_update_policies` for more details.
+:iscman:`named` at startup. See :ref:`dynamic_update_policies` for more details.
Dynamic updates using Kerberos-signed requests can be made using the
TKEY/GSS protocol, either by setting the ``tkey-gssapi-keytab`` option
This section is a guide to setting up TSIG in BIND. It describes the
configuration syntax and the process of creating TSIG keys.
-``named`` supports TSIG for server-to-server communication, and some of
+:iscman:`named` supports TSIG for server-to-server communication, and some of
the tools included with BIND support it for sending messages to
-``named``:
+:iscman:`named`:
* :ref:`man_nsupdate` supports TSIG via the :option:`-k <nsupdate -k>`, :option:`-l <nsupdate -l>`, and :option:`-y <nsupdate -y>` command-line options, or via the ``key`` command when running interactively.
* :ref:`man_dig` supports TSIG via the :option:`-k <nsupdate -k>` and :option:`-y <nsupdate -y>` command-line options.
Generating a Shared Key
~~~~~~~~~~~~~~~~~~~~~~~
-TSIG keys can be generated using the ``tsig-keygen`` command; the output
+TSIG keys can be generated using the :iscman:`tsig-keygen` command; the output
of the command is a ``key`` directive suitable for inclusion in
-``named.conf``. The key name, algorithm, and size can be specified by
+:iscman:`named.conf`. The key name, algorithm, and size can be specified by
command-line parameters; the defaults are "tsig-key", HMAC-SHA256, and
256 bits, respectively.
mechanism should be used: secure FTP, SSL, ssh, telephone, encrypted
email, etc.)
-``tsig-keygen`` can also be run as ``ddns-confgen``, in which case its
+:iscman:`tsig-keygen` can also be run as :iscman:`ddns-confgen`, in which case its
output includes additional configuration text for setting up dynamic DNS
-in ``named``. See :ref:`man_ddns-confgen` for details.
+in :iscman:`named`. See :ref:`man_ddns-confgen` for details.
Loading a New Key
~~~~~~~~~~~~~~~~~
For a key shared between servers called ``host1`` and ``host2``, the
-following could be added to each server's ``named.conf`` file:
+following could be added to each server's :iscman:`named.conf` file:
::
secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY=";
};
-(This is the same key generated above using ``tsig-keygen``.)
+(This is the same key generated above using :iscman:`tsig-keygen`.)
Since this text contains a secret, it is recommended that either
-``named.conf`` not be world-readable, or that the ``key`` directive be
+:iscman:`named.conf` not be world-readable, or that the ``key`` directive be
stored in a file which is not world-readable and which is included in
-``named.conf`` via the ``include`` directive.
+:iscman:`named.conf` via the ``include`` directive.
-Once a key has been added to ``named.conf`` and the server has been
+Once a key has been added to :iscman:`named.conf` and the server has been
restarted or reconfigured, the server can recognize the key. If the
server receives a message signed by the key, it is able to verify
the signature. If the signature is valid, the response is signed
SIG(0) signing of multiple-message TCP streams is not supported.
The only tool shipped with BIND 9 that generates SIG(0) signed messages
-is ``nsupdate``.
+is :iscman:`nsupdate`.
.. _DNSSEC:
Generating Keys
~~~~~~~~~~~~~~~
-The ``dnssec-keygen`` program is used to generate keys.
+The :iscman:`dnssec-keygen` program is used to generate keys.
A secure zone must contain one or more zone keys. The zone keys
sign all other records in the zone, as well as the zone keys of any
To generate another key with the same properties but with a different
key tag, repeat the above command.
-The ``dnssec-keyfromlabel`` program is used to get a key pair from a
+The :iscman:`dnssec-keyfromlabel` program is used to get a key pair from a
crypto hardware device and build the key files. Its usage is similar to
-``dnssec-keygen``.
+:iscman:`dnssec-keygen`.
The public keys should be inserted into the zone file by including the
``.key`` files using ``$INCLUDE`` statements.
Signing the Zone
~~~~~~~~~~~~~~~~
-The ``dnssec-signzone`` program is used to sign a zone.
+The :iscman:`dnssec-signzone` program is used to sign a zone.
Any ``keyset`` files corresponding to secure sub-zones should be
present. The zone signer generates ``NSEC``, ``NSEC3``, and ``RRSIG``
``dnssec-signzone -o child.example zone.child.example``
One output file is produced: ``zone.child.example.signed``. This file
-should be referenced by ``named.conf`` as the input file for the zone.
+should be referenced by :iscman:`named.conf` as the input file for the zone.
-``dnssec-signzone`` also produces keyset and dsset files. These are used
+:iscman:`dnssec-signzone` also produces keyset and dsset files. These are used
to provide the parent zone administrators with the ``DNSKEYs`` (or their
corresponding ``DS`` records) that are the secure entry point to the zone.
Configuring Servers for DNSSEC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To enable ``named`` to validate answers received from other servers, the
+To enable :iscman:`named` to validate answers received from other servers, the
``dnssec-validation`` option must be set to either ``yes`` or ``auto``.
When ``dnssec-validation`` is set to ``auto``, a trust anchor for the
When ``dnssec-validation`` is set to ``yes``, DNSSEC validation
only occurs if at least one trust anchor has been explicitly configured
-in ``named.conf``, using a ``trust-anchors`` statement (or the
+in :iscman:`named.conf`, using a ``trust-anchors`` statement (or the
``managed-keys`` and ``trusted-keys`` statements, both deprecated).
When ``dnssec-validation`` is set to ``no``, DNSSEC validation does not
table of trust anchors, and can only be changed by altering the
configuration. Keys configured with ``initial-key`` or ``initial-ds`` are used
to initialize :rfc:`5011` trust anchor maintenance, and are kept up-to-date
-automatically after the first time ``named`` runs.
+automatically after the first time :iscman:`named` runs.
``trust-anchors`` is described in more detail later in this document.
something like the following. It has one or more public keys for the
root, which allows answers from outside the organization to be validated.
It also has several keys for parts of the namespace that the
-organization controls. These are here to ensure that ``named`` is immune
+organization controls. These are here to ensure that :iscman:`named` is immune
to compromised security in the DNSSEC components of parent zones.
::
(https://developers.google.com/protocol-buffers) must be installed, and
BIND must be configured with ``--enable-dnstap``.
-To support internationalized domain names in ``dig``, ``libidn2``
+To support internationalized domain names in :iscman:`dig`, ``libidn2``
(https://www.gnu.org/software/libidn/#libidn2) must be installed. If the
library is installed in a nonstandard location, specify the prefix using
``--with-libidn2=/prefix`` or adjust ``PKG_CONFIG_PATH``.
-For line editing in ``nsupdate`` and ``nslookup``, either the
+For line editing in :iscman:`nsupdate` and :iscman:`nslookup`, either the
``readline`` (https://tiswww.case.edu/php/chet/readline/rltop.html) or
the ``libedit`` library (https://www.thrysoee.dk/editline/) must be
installed. If these are installed at a nonstandard location, adjust
``configure`` command line. By default, fixed RRset-order is disabled to
reduce memory footprint.
-The ``--enable-querytrace`` option causes ``named`` to log every step
+The ``--enable-querytrace`` option causes :iscman:`named` to log every step
while processing every query. The ``--enable-singletrace`` option turns
on the same verbose tracing, but allows an individual query to be
separately traced by setting its query ID to 0. These options should
only be enabled when debugging, because they have a significant negative
impact on query performance.
-``make install`` installs ``named`` and the various BIND 9 libraries. By
+``make install`` installs :iscman:`named` and the various BIND 9 libraries. By
default, installation is into /usr/local, but this can be changed with
the ``--prefix`` option when running ``configure``.
The option ``--sysconfdir`` can be specified to set the directory where
-configuration files such as ``named.conf`` go by default;
+configuration files such as :iscman:`named.conf` go by default;
``--localstatedir`` can be used to set the default parent directory of
``run/named.pid``. ``--sysconfdir`` defaults to ``$prefix/etc`` and
``--localstatedir`` defaults to ``$prefix/var``.
~~~~~~~~~~~~~~~~~~~~~~
Normally, if a zone is to be served by a secondary server, the
-``named.conf`` file on the server must list the zone, or the zone must
+:iscman:`named.conf` file on the server must list the zone, or the zone must
be added using :option:`rndc addzone`. In environments with a large number of
secondary servers, and/or where the zones being served are changing
frequently, the overhead involved in maintaining consistent zone
To use a catalog zone, it must first be set up as a normal zone on both the
primary and secondary servers that are configured to use it. It
must also be added to a ``catalog-zones`` list in the ``options`` or
-``view`` statement in ``named.conf``. This is comparable to the way a
+``view`` statement in :iscman:`named.conf`. This is comparable to the way a
policy zone is configured as a normal zone and also listed in a
``response-policy`` statement.
To use the catalog zone feature to serve a new member zone:
- Set up the member zone to be served on the primary as normal. This
- can be done by editing ``named.conf`` or by running
+ can be done by editing :iscman:`named.conf` or by running
:option:`rndc addzone`.
- Add an entry to the catalog zone for the new member zone. This can
be done by editing the catalog zone's zone file and running
- :option:`rndc reload`, or by updating the zone using ``nsupdate``.
+ :option:`rndc reload`, or by updating the zone using :iscman:`nsupdate`.
The change to the catalog zone is propagated from the primary to all
secondaries using the normal AXFR/IXFR mechanism. When the secondary receives the
~~~~~~~~~~~~~~~~~~~~~~~~~
Catalog zones are configured with a ``catalog-zones`` statement in the
-``options`` or ``view`` section of ``named.conf``. For example:
+``options`` or ``view`` section of :iscman:`named.conf`. For example:
::
These options are the equivalents of ``allow-query`` and
- ``allow-transfer`` in a zone declaration in the ``named.conf``
+ ``allow-transfer`` in a zone declaration in the :iscman:`named.conf`
configuration file. The ACL is processed in order; if there is no
match to any rule, the default policy is to deny access. For the
syntax of the APL RR, see :rfc:`3123`.
Diagnostic Tools
^^^^^^^^^^^^^^^^
-The ``dig``, ``host``, and ``nslookup`` programs are all command-line
+The :iscman:`dig`, :iscman:`host`, and :iscman:`nslookup` programs are all command-line
tools for manually querying name servers. They differ in style and
output format.
-``dig``
- ``dig`` is the most versatile and complete of these lookup tools. It
+:iscman:`dig`
+ :iscman:`dig` is the most versatile and complete of these lookup tools. It
has two modes: simple interactive mode for a single query, and batch
mode, which executes a query for each in a list of several query
lines. All query options are accessible from the command line.
For more information and a list of available commands and options,
see :ref:`man_dig`.
-``host``
- The ``host`` utility emphasizes simplicity and ease of use. By
+:iscman:`host`
+ The :iscman:`host` utility emphasizes simplicity and ease of use. By
default, it converts between host names and Internet addresses, but
its functionality can be extended with the use of options.
For more information and a list of available commands and options,
see :ref:`man_host`.
-``nslookup``
- ``nslookup`` has two modes: interactive and non-interactive.
+:iscman:`nslookup`
+ :iscman:`nslookup` has two modes: interactive and non-interactive.
Interactive mode allows the user to query name servers for
information about various hosts and domains, or to print a list of
hosts in a domain. Non-interactive mode is used to print just the
name and requested information for a host or domain.
Due to its arcane user interface and frequently inconsistent
- behavior, we do not recommend the use of ``nslookup``. Use ``dig``
+ behavior, we do not recommend the use of :iscman:`nslookup`. Use :iscman:`dig`
instead.
.. _admin_tools:
Administrative tools play an integral part in the management of a
server.
-``named-checkconf``
- The ``named-checkconf`` program checks the syntax of a ``named.conf``
+:iscman:`named-checkconf`
+ The :iscman:`named-checkconf` program checks the syntax of a :iscman:`named.conf`
file.
For more information and a list of available commands and options,
see :ref:`man_named-checkconf`.
-``named-checkzone``
- The ``named-checkzone`` program checks a zone file for syntax and
+:iscman:`named-checkzone`
+ The :iscman:`named-checkzone` program checks a zone file for syntax and
consistency.
For more information and a list of available commands and options,
see :ref:`man_named-checkzone`.
-``named-compilezone``
- This tool is similar to ``named-checkzone`` but it always dumps the zone content
+:iscman:`named-compilezone`
+ This tool is similar to :iscman:`named-checkzone` but it always dumps the zone content
to a specified file (typically in a different format).
For more information and a list of available commands and options,
see :ref:`man_named-compilezone`.
-``rndc``
- The remote name daemon control (``rndc``) program allows the system
+:iscman:`rndc`
+ The remote name daemon control (:iscman:`rndc`) program allows the system
administrator to control the operation of a name server.
- See :ref:`man_rndc` for details of the available ``rndc``
+ See :ref:`man_rndc` for details of the available :iscman:`rndc`
commands.
- ``rndc`` requires a configuration file, since all communication with
+ :iscman:`rndc` requires a configuration file, since all communication with
the server is authenticated with digital signatures that rely on a
shared secret, and there is no way to provide that secret other than
- with a configuration file. The default location for the ``rndc``
+ with a configuration file. The default location for the :iscman:`rndc`
configuration file is |rndc_conf|, but an alternate location
can be specified with the :option:`-c <rndc -c>` option. If the configuration file is
- not found, ``rndc`` also looks in |rndc_key| (or whatever
+ not found, :iscman:`rndc` also looks in |rndc_key| (or whatever
``sysconfdir`` was defined when the BIND build was configured). The
``rndc.key`` file is generated by running :option:`rndc-confgen -a` as
described in :ref:`controls_statement_definition_and_usage`.
The format of the configuration file is similar to that of
- ``named.conf``, but is limited to only four statements: the ``options``,
+ :iscman:`named.conf`, but is limited to only four statements: the ``options``,
``key``, ``server``, and ``include`` statements. These statements are
what associate the secret keys to the servers with which they are
meant to be shared. The order of statements is not significant.
contacted if no :option:`-s <rndc -s>` option is provided on the command line.
``default-key`` takes the name of a key as its argument, as defined
by a ``key`` statement. ``default-port`` specifies the port to which
- ``rndc`` should connect if no port is given on the command line or in
+ :iscman:`rndc` should connect if no port is given on the command line or in
a ``server`` statement.
- The ``key`` statement defines a key to be used by ``rndc`` when
- authenticating with ``named``. Its syntax is identical to the ``key``
- statement in ``named.conf``. The keyword ``key`` is followed by a key
+ The ``key`` statement defines a key to be used by :iscman:`rndc` when
+ authenticating with :iscman:`named`. Its syntax is identical to the ``key``
+ statement in :iscman:`named.conf`. The keyword ``key`` is followed by a key
name, which must be a valid domain name, though it need not actually
be hierarchical; thus, a string like ``rndc_key`` is a valid name.
The ``key`` statement has two clauses: ``algorithm`` and ``secret``.
name or address. The ``server`` statement has two clauses: ``key``
and ``port``. The ``key`` clause specifies the name of the key to be
used when communicating with this server, and the ``port`` clause can
- be used to specify the port ``rndc`` should connect to on the server.
+ be used to specify the port :iscman:`rndc` should connect to on the server.
A sample minimal configuration file is as follows:
and it has an identical key statement for ``rndc_key``.
- Running the ``rndc-confgen`` program conveniently creates an
- ``rndc.conf`` file, and also displays the corresponding
- ``controls`` statement needed to add to ``named.conf``.
+ Running the :iscman:`rndc-confgen` program conveniently creates an
+ :iscman:`rndc.conf` file, and also displays the corresponding
+ ``controls`` statement needed to add to :iscman:`named.conf`.
Alternatively, it is possible to run :option:`rndc-confgen -a` to set up an
- ``rndc.key`` file and not modify ``named.conf`` at all.
+ ``rndc.key`` file and not modify :iscman:`named.conf` at all.
Signals
~~~~~~~
described in the following table. These signals can be sent using the
``kill`` command.
-+--------------+-------------------------------------------------------+
-| ``SIGHUP`` | Causes the server to read ``named.conf`` and reload |
-| | the database. |
-+--------------+-------------------------------------------------------+
-| ``SIGTERM`` | Causes the server to clean up and exit. |
-+--------------+-------------------------------------------------------+
-| ``SIGINT`` | Causes the server to clean up and exit. |
-+--------------+-------------------------------------------------------+
++--------------+-------------------------------------------------------------+
+| ``SIGHUP`` | Causes the server to read :iscman:`named.conf` and reload |
+| | the database. |
++--------------+-------------------------------------------------------------+
+| ``SIGTERM`` | Causes the server to clean up and exit. |
++--------------+-------------------------------------------------------------+
+| ``SIGINT`` | Causes the server to clean up and exit. |
++--------------+-------------------------------------------------------------+
.. include:: plugins.rst
database backends, including MySQL and LDAP, and can be
written for any other.
-The DLZ module provides data to ``named`` in text
-format, which is then converted to DNS wire format by ``named``. This
+The DLZ module provides data to :iscman:`named` in text
+format, which is then converted to DNS wire format by :iscman:`named`. This
conversion, and the lack of any internal caching, places significant
limits on the query performance of DLZ modules. Consequently, DLZ is not
recommended for use on high-volume servers. However, it can be used in a
Configuring DLZ
~~~~~~~~~~~~~~~
-A DLZ database is configured with a ``dlz`` statement in ``named.conf``:
+A DLZ database is configured with a ``dlz`` statement in :iscman:`named.conf`:
::
dynamic DNS update, via the ``auto-dnssec`` zone option, or by setting a
DNSSEC policy for the zone with ``dnssec-policy``.
-For any method, ``named`` must be configured so that it can see
+For any method, :iscman:`named` must be configured so that it can see
the ``K*`` files which contain the public and private parts of the keys
that are used to sign the zone. These files are generated
-by ``dnssec-keygen``, or created when needed by ``named`` if
+by :iscman:`dnssec-keygen`, or created when needed by :iscman:`named` if
``dnssec-policy`` is used. Keys should be placed in the
-key-directory, as specified in ``named.conf``:
+key-directory, as specified in :iscman:`named.conf`:
::
> send
While the update request completes almost immediately, the zone is
-not completely signed until ``named`` has had time to "walk" the zone
+not completely signed until :iscman:`named` has had time to "walk" the zone
and generate the NSEC and RRSIG records. The NSEC record at the apex
is added last, to signal that there is a complete NSEC chain.
> send
Again, this update request completes almost immediately; however,
-the record does not show up until ``named`` has had a chance to
+the record does not show up until :iscman:`named` has had a chance to
build/remove the relevant chain. A private type record is created
to record the state of the operation (see below for more details), and
is removed once the operation completes.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable automatic signing, set a ``dnssec-policy`` or add the
-``auto-dnssec`` option to the zone statement in ``named.conf``.
+``auto-dnssec`` option to the zone statement in :iscman:`named.conf`.
``auto-dnssec`` has two possible arguments: ``allow`` or ``maintain``.
-With ``auto-dnssec allow``, ``named`` can search the key directory for
+With ``auto-dnssec allow``, :iscman:`named` can search the key directory for
keys matching the zone, insert them into the zone, and use them to sign
the zone. It does so only when it receives an
:option:`rndc sign zonename <rndc sign>`.
``dnssec-policy`` is similar to ``auto-dnssec maintain``, but
``dnssec-policy`` also automatically creates new keys when necessary. In
addition, any configuration related to DNSSEC signing is retrieved from the
-policy, ignoring existing DNSSEC ``named.conf`` options.
+policy, ignoring existing DNSSEC :iscman:`named.conf` options.
-``named`` periodically searches the key directory for keys matching
+:iscman:`named` periodically searches the key directory for keys matching
the zone; if the keys' metadata indicates that any change should be
made to the zone - such as adding, removing, or revoking a key - then that
action is carried out. By default, the key directory is checked for
changes every 60 minutes; this period can be adjusted with
``dnssec-loadkeys-interval``, up to a maximum of 24 hours. The
-:option:`rndc loadkeys` command forces ``named`` to check for key updates immediately.
+:option:`rndc loadkeys` command forces :iscman:`named` to check for key updates immediately.
If keys are present in the key directory the first time the zone is
loaded, the zone is signed immediately, without waiting for an
~~~~~~~~~~~~~~~~~~~~~~~~~
To perform key rollovers via a dynamic update, the ``K*``
-files for the new keys must be added so that ``named`` can find them.
-The new DNSKEY RRs can then be added via dynamic update. ``named`` then causes the
+files for the new keys must be added so that :iscman:`named` can find them.
+The new DNSKEY RRs can then be added via dynamic update. :iscman:`named` then causes the
zone to be signed with the new keys; when the signing is complete, the
private type records are updated so that the last octet is non-zero.
when the old DNSKEY is removed.
The old DNSKEY can be removed via UPDATE, taking care to specify the
-correct key. ``named`` cleans out any signatures generated by the
+correct key. :iscman:`named` cleans out any signatures generated by the
old key after the update completes.
Automatic Key Rollovers
~~~~~~~~~~~~~~~~~~~~~~~
-When a new key reaches its activation date (as set by ``dnssec-keygen``
-or ``dnssec-settime``), and if the ``auto-dnssec`` zone option is set to
-``maintain``, ``named`` automatically carries out the key rollover.
+When a new key reaches its activation date (as set by :iscman:`dnssec-keygen`
+or :iscman:`dnssec-settime`), and if the ``auto-dnssec`` zone option is set to
+``maintain``, :iscman:`named` automatically carries out the key rollover.
If the key's algorithm has not previously been used to sign the zone,
then the zone is fully signed as quickly as possible. However, if
the new key replaces an existing key of the same algorithm, the
Add a ``nsec3param`` option to your ``dnssec-policy`` and
run :option:`rndc reconfig`.
-Or use ``nsupdate`` to add an NSEC3PARAM record.
+Or use :iscman:`nsupdate` to add an NSEC3PARAM record.
In both cases, the NSEC3 chain is generated and the NSEC3PARAM record is
added before the NSEC chain is destroyed.
To do this, remove the ``nsec3param`` option from the ``dnssec-policy`` and
run :option:`rndc reconfig`.
-Or use ``nsupdate`` to remove all NSEC3PARAM records with a
+Or use :iscman:`nsupdate` to remove all NSEC3PARAM records with a
zero flag field. The NSEC chain is generated before the NSEC3 chain
is removed.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To convert a signed zone to unsigned using dynamic DNS, delete all the
-DNSKEY records from the zone apex using ``nsupdate``. All signatures,
+DNSKEY records from the zone apex using :iscman:`nsupdate`. All signatures,
NSEC or NSEC3 chains, and associated NSEC3PARAM records are removed
automatically. This takes place after the update request completes.
This requires the ``dnssec-secure-to-insecure`` option to be set to
-``yes`` in ``named.conf``.
+``yes`` in :iscman:`named.conf`.
In addition, if the ``auto-dnssec maintain`` zone statement is used, it
should be removed or changed to ``allow`` instead; otherwise it will re-sign.
Periodic Re-signing
~~~~~~~~~~~~~~~~~~~
-In any secure zone which supports dynamic updates, ``named``
+In any secure zone which supports dynamic updates, :iscman:`named`
periodically re-signs RRsets which have not been re-signed as a result of
some update action. The signature lifetimes are adjusted to
spread the re-sign load over time rather than all at once.
NSEC3 and OPTOUT
~~~~~~~~~~~~~~~~
-``named`` only supports creating new NSEC3 chains where all the NSEC3
-records in the zone have the same OPTOUT state. ``named`` supports
+:iscman:`named` only supports creating new NSEC3 chains where all the NSEC3
+records in the zone have the same OPTOUT state. :iscman:`named` supports
UPDATES to zones where the NSEC3 records in the chain have mixed OPTOUT
-state. ``named`` does not support changing the OPTOUT state of an
+state. :iscman:`named` does not support changing the OPTOUT state of an
individual NSEC3 record; if the
OPTOUT state of an individual NSEC3 needs to be changed, the entire chain must be changed.
~~~~~~~~~~~~~~~~~
A DynDB database is configured with a ``dyndb`` statement in
-``named.conf``:
+:iscman:`named.conf`:
::
.. [#rfc4955] BIND 9 interoperates with correctly designed experiments.
-.. [#rfc5452] ``named`` only uses ports to extend the ID space; addresses are not
+.. [#rfc5452] :iscman:`named` only uses ports to extend the ID space; addresses are not
used.
-.. [#rfc6147] Section 5.5 does not match reality. ``named`` uses the presence
+.. [#rfc6147] Section 5.5 does not match reality. :iscman:`named` uses the presence
of DO=1 to detect if validation may be occurring. CD has no bearing
on whether validation occurs.
.. [#rfc7344] Updating of parent zones is not yet implemented.
-.. [#rfc7830] ``named`` does not currently encrypt DNS requests, so the PAD option
+.. [#rfc7830] :iscman:`named` does not currently encrypt DNS requests, so the PAD option
is accepted but not returned in responses.
.. [#rfc3363] Section 4 is ignored.
Clients look up information in the DNS by calling a *resolver* library,
which sends queries to one or more *name servers* and interprets the
responses. The BIND 9 software distribution contains a name server,
-``named``, and a set of associated tools.
+:iscman:`named`, and a set of associated tools.
.. _domain_names:
understanding of this difficult and subtle topic.
Though BIND 9 is called a "domain name server," it deals primarily in
-terms of zones. The ``primary`` and ``secondary`` declarations in the ``named.conf``
+terms of zones. The ``primary`` and ``secondary`` declarations in the :iscman:`named.conf`
file specify zones, not domains. When BIND asks some other site if it is
willing to be a secondary server for a *domain*, it is actually asking
for secondary service for some collection of *zones*.
Responses from authoritative servers have the "authoritative answer"
(AA) bit set in the response packets. This makes them easy to identify
-when debugging DNS configurations using tools like ``dig`` (:ref:`diagnostic_tools`).
+when debugging DNS configurations using tools like :iscman:`dig` (:ref:`diagnostic_tools`).
.. _primary_master:
forwarding them to the wider Internet.
There may be one or more forwarders in a given setup. The order in which
-the forwarders are listed in ``named.conf`` does not determine the
-sequence in which they are queried; rather, ``named`` uses the response
+the forwarders are listed in :iscman:`named.conf` does not determine the
+sequence in which they are queried; rather, :iscman:`named` uses the response
times from previous queries to select the server that is likely to
respond the most quickly. A server that has not yet been queried is
given an initial small random response time to ensure that it is tried
Note: the log message can also be due to packet loss. Before reporting servers for non-:rfc:`1034` compliance they should be re-tested to determine the nature of the non-compliance. This testing should prevent or reduce the number of false-positive reports.
- Note: eventually ``named`` will have to stop treating such timeouts as due to :rfc:`1034` non-compliance and start treating it as plain packet loss. Falsely classifying packet loss as due to :rfc:`1034` non-compliance impacts DNSSEC validation, which requires EDNS for the DNSSEC records to be returned.
+ Note: eventually :iscman:`named` will have to stop treating such timeouts as due to :rfc:`1034` non-compliance and start treating it as plain packet loss. Falsely classifying packet loss as due to :rfc:`1034` non-compliance impacts DNSSEC validation, which requires EDNS for the DNSSEC records to be returned.
``general``
A catch-all for many things that still are not classified into categories.
TLS pre-master secrets (for debugging purposes).
``trust-anchor-telemetry``
- Trust-anchor-telemetry requests received by ``named``.
+ Trust-anchor-telemetry requests received by :iscman:`named`.
``unmatched``
- Messages that ``named`` was unable to determine the class of, or for which there was no matching ``view``. A one-line summary is also logged to the ``client`` category. This category is best sent to a file or stderr; by default it is sent to the ``null`` channel.
+ Messages that :iscman:`named` was unable to determine the class of, or for which there was no matching ``view``. A one-line summary is also logged to the ``client`` category. This category is best sent to a file or stderr; by default it is sent to the ``null`` channel.
``update``
Dynamic updates.
-------------------------------
BIND is able to maintain DNSSEC trust anchors using :rfc:`5011` key
-management. This feature allows ``named`` to keep track of changes to
+management. This feature allows :iscman:`named` to keep track of changes to
critical DNSSEC keys without any need for the operator to make changes
to configuration files.
"rolled over" to the newly accepted key.
The easiest way to place a stand-by key in a zone is to use the "smart
-signing" features of ``dnssec-keygen`` and ``dnssec-signzone``. If a key
+signing" features of :iscman:`dnssec-keygen` and :iscman:`dnssec-signzone`. If a key
exists with a publication date in the past, but an activation date which is
unset or in the future, :option:`dnssec-signzone -S` includes the
DNSKEY record in the zone but does not sign with it:
$ dnssec-keygen -K keys -f KSK -P now -A now+2y example.net
$ dnssec-signzone -S -K keys example.net
-To revoke a key, use the command ``dnssec-revoke``. This
+To revoke a key, use the command :iscman:`dnssec-revoke`. This
adds the REVOKED bit to the key flags and regenerates the ``K*.key``
and ``K*.private`` files.
If two keys have IDs exactly 128 apart and one is revoked, the two
key IDs will collide, causing several problems. To prevent this,
-``dnssec-keygen`` does not generate a new key if another key
+:iscman:`dnssec-keygen` does not generate a new key if another key
which may collide is present. This checking only occurs if the new keys are
written to the same directory that holds all other keys in use for that
zone.
label to reference the private key.
Convert the RSA keys stored in the HSM into a format that BIND 9 understands.
-The ``dnssec-keyfromlabel`` tool from BIND 9 can link the raw keys stored in the
+The :iscman:`dnssec-keyfromlabel` tool from BIND 9 can link the raw keys stored in the
HSM with the ``K<zone>+<alg>+<id>`` files. You'll need to provide the OpenSSL
engine name (``pkcs11``), the algorithm (``RSASHA256``) and the PKCS#11 label
that specify the token (we asume that it has been initialized as bind9), the
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When using OpenSSL-based PKCS#11, the "engine" to be used by OpenSSL can be
-specified in ``named`` and all of the BIND ``dnssec-*`` tools by using the ``-E
+specified in :iscman:`named` and all of the BIND ``dnssec-*`` tools by using the ``-E
<engine>`` command line option. Specifying the engine is generally not necessary
unless a different OpenSSL engine is used.
dnssec-signzone -E pkcs11 -S -o example.net example.net
-Running ``named`` With Automatic Zone Re-signing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Running :iscman:`named` With Automatic Zone Re-signing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The zone can also be signed automatically by named. Again, we need to provide
the name of the OpenSSL engine using the :option:`-E <named -E>` command line option.
DNSKEY example.net/RSASHA256/42231 (ZSK) is now published
DNSKEY example.net/RSA256SHA256/42231 (ZSK) is now active
-For ``named`` to dynamically re-sign zones using HSM keys,
-and/or to sign new records inserted via nsupdate, ``named`` must
+For :iscman:`named` to dynamically re-sign zones using HSM keys,
+and/or to sign new records inserted via nsupdate, :iscman:`named` must
have access to the HSM PIN. In OpenSSL-based PKCS#11, this is
accomplished by placing the PIN into the ``openssl.cnf`` file (in the above
examples, ``/opt/pkcs11/usr/ssl/openssl.cnf``).
The location of the openssl.cnf file can be overridden by setting the
-``OPENSSL_CONF`` environment variable before running ``named``.
+``OPENSSL_CONF`` environment variable before running :iscman:`named`.
Here is a sample ``openssl.cnf``:
Plugins
-------
-Plugins are a mechanism to extend the functionality of ``named`` using
+Plugins are a mechanism to extend the functionality of :iscman:`named` using
dynamically loadable libraries. By using plugins, core server
functionality can be kept simple for the majority of users; more complex
code implementing optional features need only be installed by users that
these modify the name server query logic. Other plugin types may be
added in the future.
-The only plugin currently included in BIND is ``filter-aaaa.so``, which
+The only plugin currently included in BIND is :iscman:`filter-aaaa.so <filter-aaaa>`, which
replaces the ``filter-aaaa`` feature that previously existed natively as
-part of ``named``. The code for this feature has been removed from
-``named`` and can no longer be configured using standard ``named.conf``
-syntax, but linking in the ``filter-aaaa.so`` plugin provides identical
+part of :iscman:`named`. The code for this feature has been removed from
+:iscman:`named` and can no longer be configured using standard :iscman:`named.conf`
+syntax, but linking in the :iscman:`filter-aaaa.so <filter-aaaa>` plugin provides identical
functionality.
Configuring Plugins
~~~~~~~~~~~~~~~~~~~
-A plugin is configured with the ``plugin`` statement in ``named.conf``:
+A plugin is configured with the ``plugin`` statement in :iscman:`named.conf`:
::
- ``plugin_register``
to allocate memory, configure a plugin instance, and attach to hook
points within
- ``named``
+ :iscman:`named`
,
- ``plugin_destroy``
to tear down the plugin instance and free memory,
- ``plugin_check``
to test syntactic correctness of the plugin parameters.
-At various locations within the ``named`` source code, there are "hook
+At various locations within the :iscman:`named` source code, there are "hook
points" at which a plugin may register itself. When a hook point is
-reached while ``named`` is running, it is checked to see whether any
+reached while :iscman:`named` is running, it is checked to see whether any
plugins have registered themselves there; if so, the associated "hook
action" - a function within the plugin library - is called. Hook
actions may examine the runtime state and make changes: for example,
Defines a named IP address matching list, for access control and other uses.
``controls``
- Declares control channels to be used by the ``rndc`` utility.
+ Declares control channels to be used by the :iscman:`rndc` utility.
``dnssec-policy``
Describes a DNSSEC key and signing policy for zones. See :ref:`dnssec-policy Grammar <dnssec_policy_grammar>` for details.
Sets certain configuration options on a per-server basis.
``statistics-channels``
- Declares communication channels to get access to ``named`` statistics.
+ Declares communication channels to get access to :iscman:`named` statistics.
``tls``
Specifies configuration information for a TLS connection, including a ``key-file``, ``cert-file``, ``dhparam-file``, ``ciphers``, ``protocols``, ``prefer-server-ciphers``, and ``session-tickets``.
The ``controls`` statement declares control channels to be used by
system administrators to manage the operation of the name server. These
-control channels are used by the ``rndc`` utility to send commands to
+control channels are used by the :iscman:`rndc` utility to send commands to
and retrieve non-DNS results from a name server.
An ``inet`` control channel is a TCP socket listening at the specified
address. An ``ip_addr`` of ``*`` (asterisk) is interpreted as the IPv4
wildcard address; connections are accepted on any of the system's
IPv4 addresses. To listen on the IPv6 wildcard address, use an
-``ip_addr`` of ``::``. If ``rndc`` is only used on the local host,
+``ip_addr`` of ``::``. If :iscman:`rndc` is only used on the local host,
using the loopback address (``127.0.0.1`` or ``::1``) is recommended for
maximum security.
``key_list``, which contains a list of ``key_id``s. Each ``key_id`` in
the ``key_list`` is authorized to execute commands over the control
channel. See :ref:`admin_tools` for information about
-configuring keys in ``rndc``.
+configuring keys in :iscman:`rndc`.
If the ``read-only`` clause is enabled, the control channel is limited
to the following set of read-only commands: ``nta -dump``, ``null``,
``read-only`` is not enabled and the control channel allows read-write
access.
-If no ``controls`` statement is present, ``named`` sets up a default
+If no ``controls`` statement is present, :iscman:`named` sets up a default
control channel listening on the loopback address 127.0.0.1 and its IPv6
counterpart, ::1. In this case, and also when the ``controls`` statement
-is present but does not have a ``keys`` clause, ``named`` attempts
+is present but does not have a ``keys`` clause, :iscman:`named` attempts
to load the command channel key from the file |rndc_key|.
To create an ``rndc.key`` file, run :option:`rndc-confgen -a`.
matching this name, algorithm, and secret.
The ``algorithm_id`` is a string that specifies a security/authentication
-algorithm. The ``named`` server supports ``hmac-md5``, ``hmac-sha1``,
+algorithm. The :iscman:`named` server supports ``hmac-md5``, ``hmac-sha1``,
``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, and ``hmac-sha512``
TSIG authentication. Truncated hashes are supported by appending the
minimum number of required bits preceded by a dash, e.g.,
category unmatched { null; };
};
-If ``named`` is started with the :option:`-L <named -L>` option, it logs to the specified
+If :iscman:`named` is started with the :option:`-L <named -L>` option, it logs to the specified
file at startup, instead of using syslog. In this case the logging
configuration is:
syslog facility, go to the standard error stream, or are discarded. The definition can
optionally also limit the message severity level that is accepted
by the channel (the default is ``info``), and whether to include a
-``named``-generated time stamp, the category name, and/or the severity level
+:iscman:`named`-generated time stamp, the category name, and/or the severity level
(the default is not to include any).
The ``null`` destination clause causes all messages sent to the channel
(``suffix``).
The ``size`` option is used to limit log file growth. If the file ever
-exceeds the specified size, then ``named`` stops writing to the file
+exceeds the specified size, then :iscman:`named` stops writing to the file
unless it has a ``versions`` option associated with it. If backup
versions are kept, the files are rolled as described below. If there is
no ``versions`` option, no more data is written to the log until
channel facility and severity as ``daemon`` and ``debug``, but only
logging ``daemon.warning`` via ``syslog.conf``, causes messages of
severity ``info`` and ``notice`` to be dropped. If the situation were
-reversed, with ``named`` writing messages of only ``warning`` or higher,
+reversed, with :iscman:`named` writing messages of only ``warning`` or higher,
then ``syslogd`` would print all messages it received from the channel.
The ``stderr`` destination clause directs the channel to the server's
The server can supply extensive debugging information when it is in
debugging mode. If the server's global debug level is greater than zero,
debugging mode is active. The global debug level is set either
-by starting the ``named`` server with the :option:`-d <named -d>` flag followed by a
+by starting the :iscman:`named` server with the :option:`-d <named -d>` flag followed by a
positive integer, or by running :option:`rndc trace`. The global debug level
can be set to zero, and debugging mode turned off, by running ``rndc
notrace``. All debugging messages in the server have a debug level;
If ``buffered`` has been turned on, the output to files is not
flushed after each log entry. By default all log messages are flushed.
-There are four predefined channels that are used for ``named``'s default
-logging, as follows. If ``named`` is started with the :option:`-L <named -L>` option, then a fifth
+There are four predefined channels that are used for :iscman:`named`'s default
+logging, as follows. If :iscman:`named` is started with the :option:`-L <named -L>` option, then a fifth
channel, ``default_logfile``, is added. How they are used is described in
:ref:`the_category_phrase`.
writes to a file called ``named.run`` in the server's working directory.
For security reasons, when the :option:`-u <named -u>` command-line option is used, the
-``named.run`` file is created only after ``named`` has changed to the
-new UID, and any debug output generated while ``named`` is starting -
+``named.run`` file is created only after :iscman:`named` has changed to the
+new UID, and any debug output generated while :iscman:`named` is starting -
and still running as root - is discarded. To capture this
output, run the server with the :option:`-L <named -L>` option to specify a
default logfile, or the :option:`-g <named -g>` option to log to standard error which can
category default { default_syslog; default_debug; };
-If ``named`` is started with the :option:`-L <named -L>` option, the default category
+If :iscman:`named` is started with the :option:`-L <named -L>` option, the default category
is:
::
``options`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This is the grammar of the ``options`` statement in the ``named.conf``
+This is the grammar of the ``options`` statement in the :iscman:`named.conf`
file:
.. include:: ../misc/options.grammar.rst
statements, in which case it overrides the global ``attach-cache``
option.
- The ``cache_name`` specifies the cache to be shared. When the ``named``
+ The ``cache_name`` specifies the cache to be shared. When the :iscman:`named`
server configures views which are supposed to share a cache, it
creates a cache with the specified name for the first view of these
sharing views. The rest of the views simply refer to the
the working directory defaults to ``"."``, the directory from
which the server was started. The directory specified should be an
absolute path, and *must* be writable by the effective user ID of the
- ``named`` process.
+ :iscman:`named` process.
The option takes effect only at the time that the configuration
option is parsed; if other files are being included before or after specifying the
resolver query;
};
- Logged ``dnstap`` messages can be parsed using the ``dnstap-read``
+ Logged ``dnstap`` messages can be parsed using the :iscman:`dnstap-read`
utility (see :ref:`man_dnstap-read` for details).
For more information on ``dnstap``, see http://dnstap.info.
The fstrm library has a number of tunables that are exposed in
- ``named.conf``, and can be modified if necessary to improve
+ :iscman:`named.conf`, and can be modified if necessary to improve
performance or prevent loss of data. These are:
- ``fstrm-set-buffer-hint``: The threshold number of bytes to
rolling.
``dnstap-output`` can only be set globally in ``options``. Currently,
- it can only be set once while ``named`` is running; once set, it
+ it can only be set once while :iscman:`named` is running; once set, it
cannot be changed by :option:`rndc reload` or :option:`rndc reconfig`.
``dnstap-identity``
``none``, no version string is sent.
``geoip-directory``
- When ``named`` is compiled using the MaxMind GeoIP2 geolocation API, this
+ When :iscman:`named` is compiled using the MaxMind GeoIP2 geolocation API, this
specifies the directory containing GeoIP database files. By default, the
option is set based on the prefix used to build the ``libmaxminddb`` module;
for example, if the library is installed in ``/usr/local/lib``, then the
``bind.keys``, ``rndc.key``, or ``session.key``.)
``lmdb-mapsize``
- When ``named`` is built with liblmdb, this option sets a maximum size
+ When :iscman:`named` is built with liblmdb, this option sets a maximum size
for the memory map of the new-zone database (NZD) in LMDB database
format. This database is used to store configuration information for
zones added using :option:`rndc addzone`. Note that this is not the NZD
to.
Because the database file is memory-mapped, its size is limited by
- the address space of the ``named`` process. The default of 32 megabytes
- was chosen to be usable with 32-bit ``named`` builds. The largest
+ the address space of the :iscman:`named` process. The default of 32 megabytes
+ was chosen to be usable with 32-bit :iscman:`named` builds. The largest
permitted value is 1 terabyte. Given typical zone configurations
without elaborate ACLs, a 32 MB NZD file ought to be able to hold
configurations of about 100,000 zones.
keys (i.e., those configured using the ``initial-key`` or ``initial-ds``
keywords in a ``trust-anchors`` statement). By default, this is the working
directory. The directory *must* be writable by the effective user ID of the
- ``named`` process.
+ :iscman:`named` process.
- If ``named`` is not configured to use views, managed keys for
+ If :iscman:`named` is not configured to use views, managed keys for
the server are tracked in a single file called
``managed-keys.bind``. Otherwise, managed keys are tracked in
separate files, one file per view; each file name is the view
``max-ixfr-ratio``
This sets the size threshold (expressed as a percentage of the size
- of the full zone) beyond which ``named`` chooses to use an AXFR
+ of the full zone) beyond which :iscman:`named` chooses to use an AXFR
response rather than IXFR when answering zone transfer requests. See
:ref:`incremental_zone_transfers`.
parameters for zones added via :option:`rndc addzone`. By default, this is
the working directory. If set to a relative path, it is relative
to the working directory. The directory *must* be writable by the
- effective user ID of the ``named`` process.
+ effective user ID of the :iscman:`named` process.
``qname-minimization``
This option controls QNAME minimization behavior in the BIND
on exit. If not specified, the default is ``named.memstats``.
``lock-file``
- This is the pathname of a file on which ``named`` attempts to acquire a
+ This is the pathname of a file on which :iscman:`named` attempts to acquire a
file lock when starting for the first time; if unsuccessful, the
server terminates, under the assumption that another server
is already running. If not specified, the default is
``none``.
Specifying ``lock-file none`` disables the use of a lock file.
- ``lock-file`` is ignored if ``named`` was run using the :option:`-X <named -X>`
+ ``lock-file`` is ignored if :iscman:`named` was run using the :option:`-X <named -X>`
option, which overrides it. Changes to ``lock-file`` are ignored if
- ``named`` is being reloaded or reconfigured; it is only effective
+ :iscman:`named` is being reloaded or reconfigured; it is only effective
when the server is first started.
``pid-file``
``bindkeys-file``
This is the pathname of a file to override the built-in trusted keys provided
- by ``named``. See the discussion of ``dnssec-validation`` for
+ by :iscman:`named`. See the discussion of ``dnssec-validation`` for
details. If not specified, the default is |bind_keys|.
``secroots-file``
``session-keyfile``
This is the pathname of the file into which to write a TSIG session key
- generated by ``named`` for use by ``nsupdate -l``. If not specified,
+ generated by :iscman:`named` for use by ``nsupdate -l``. If not specified,
the default is |session_key|. (See :ref:`dynamic_update_policies`,
and in particular the discussion of the ``update-policy`` statement's
``local`` option, for more information about this feature.)
``dnssec-must-be-secure``
This specifies hierarchies which must be or may not be secure (signed and
- validated). If ``yes``, then ``named`` only accepts answers if
+ validated). If ``yes``, then :iscman:`named` only accepts answers if
they are secure. If ``no``, then normal DNSSEC validation applies,
allowing insecure answers to be accepted. The specified domain
must be defined as a trust anchor, for instance in a ``trust-anchors``
statement, or ``dnssec-validation auto`` must be active.
``dns64``
- This directive instructs ``named`` to return mapped IPv4 addresses to
+ This directive instructs :iscman:`named` to return mapped IPv4 addresses to
AAAA queries when there are no AAAA records. It is intended to be
used in conjunction with a NAT64. Each ``dns64`` defines one DNS64
prefix. Multiple DNS64 prefixes can be defined.
``dnssec-update-mode``
If this option is set to its default value of ``maintain`` in a zone
of type ``primary`` which is DNSSEC-signed and configured to allow
- dynamic updates (see :ref:`dynamic_update_policies`), and if ``named`` has access
- to the private signing key(s) for the zone, then ``named``
+ dynamic updates (see :ref:`dynamic_update_policies`), and if :iscman:`named` has access
+ to the private signing key(s) for the zone, then :iscman:`named`
automatically signs all new or changed records and maintains signatures
for the zone by regenerating RRSIG records whenever they approach
their expiration date.
- If the option is changed to ``no-resign``, then ``named`` signs
+ If the option is changed to ``no-resign``, then :iscman:`named` signs
all new or changed records, but scheduled maintenance of signatures
is disabled.
- With either of these settings, ``named`` rejects updates to a
+ With either of these settings, :iscman:`named` rejects updates to a
DNSSEC-signed zone when the signing keys are inactive or unavailable
- to ``named``. (A planned third option, ``external``, will disable all
+ to :iscman:`named`. (A planned third option, ``external``, will disable all
automatic signing and allow DNSSEC data to be submitted into a zone
via dynamic update; this is not yet implemented.)
A negative trust anchor selectively disables DNSSEC validation for
zones that are known to be failing because of misconfiguration, rather
than an attack. When data to be validated is at or below an active
- NTA (and above any other configured trust anchors), ``named``
+ NTA (and above any other configured trust anchors), :iscman:`named`
aborts the DNSSEC validation process and treats the data as insecure
rather than bogus. This continues until the NTA's lifetime has
- elapsed. NTAs persist across ``named`` restarts.
+ elapsed. NTAs persist across :iscman:`named` restarts.
For convenience, TTL-style time-unit suffixes can be used to specify the NTA
lifetime in seconds, minutes, or hours. It also accepts ISO 8601 duration
A negative trust anchor is normally used when a domain has stopped
validating due to operator error; it temporarily disables DNSSEC
validation for that domain. In the interest of ensuring that DNSSEC
- validation is turned back on as soon as possible, ``named``
+ validation is turned back on as soon as possible, :iscman:`named`
periodically sends a query to the domain, ignoring negative trust
anchors, to find out whether it can now be validated. If so, the
negative trust anchor is allowed to expire early.
Newly added zones' configuration parameters are stored so that they
can persist after the server is restarted. The configuration
information is saved in a file called ``viewname.nzf`` (or, if
- ``named`` is compiled with liblmdb, in an LMDB database file called
+ :iscman:`named` is compiled with liblmdb, in 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
Configurations for zones added at runtime are stored either in
a new-zone file (NZF) or a new-zone database (NZD), depending on
- whether ``named`` was linked with liblmdb at compile time. See
+ whether :iscman:`named` was linked with liblmdb at compile time. See
:ref:`man_rndc` for further details about :option:`rndc addzone`.
``auth-nxdomain``
at the global options level, not per-view.
``answer-cookie no`` is intended as a temporary measure, for use when
- ``named`` shares an IP address with other servers that do not yet
+ :iscman:`named` shares an IP address with other servers that do not yet
support DNS COOKIE. A mismatch between servers on the same address is
not expected to cause operational problems, but the option to disable
COOKIE responses so that all servers have the same behavior is
Stale answers can also be enabled or disabled at runtime via
:option:`rndc serve-stale on <rndc serve-stale>` or :option:`rndc serve-stale off <rndc serve-stale>`; these override
the configured setting. :option:`rndc serve-stale reset <rndc serve-stale>` restores the
- setting to the one specified in ``named.conf``. Note that if stale
- answers have been disabled by ``rndc``, they cannot be
- re-enabled by reloading or reconfiguring ``named``; they must be
+ setting to the one specified in :iscman:`named.conf`. Note that if stale
+ answers have been disabled by :iscman:`rndc`, they cannot be
+ re-enabled by reloading or reconfiguring :iscman:`named`; they must be
re-enabled with :option:`rndc serve-stale on <rndc serve-stale>`, or the server must be
restarted.
log category.
``stale-answer-client-timeout``
- This option defines the amount of time (in milliseconds) that ``named``
+ This option defines the amount of time (in milliseconds) that :iscman:`named`
waits before attempting to answer the query with a stale RRset from cache.
- If a stale answer is found, ``named`` continues the ongoing fetches,
+ If a stale answer is found, :iscman:`named` continues the ongoing fetches,
attempting to refresh the RRset in cache until the
``resolver-query-timeout`` interval is reached.
``stale-refresh-time``
If the name servers for a given zone are not answering, this sets the time
- window for which ``named`` will promptly return "stale" cached answers for
+ window for which :iscman:`named` will promptly return "stale" cached answers for
that RRSet being requested before a new attempt in contacting the servers
is made. For convenience, TTL-style time-unit suffixes may be used to
specify the value. It also accepts ISO 8601 duration formats.
The default ``stale-refresh-time`` is 30 seconds, as :rfc:`8767` recommends
that attempts to refresh to be done no more frequently than every 30
seconds. A value of zero disables the feature, meaning that normal
- resolution will take place first, if that fails only then ``named`` will
+ resolution will take place first, if that fails only then :iscman:`named` will
return "stale" cached answers.
``nocookie-udp-size``
or "aes".
If there are multiple secrets specified, the first one listed in
- ``named.conf`` is used to generate new server cookies. The others
+ :iscman:`named.conf` is used to generate new server cookies. The others
are only used to verify returned cookies.
``response-padding``
of two (for instance, 128), but this is not mandatory.
``trust-anchor-telemetry``
- This causes ``named`` to send specially formed queries once per day to
+ This causes :iscman:`named` to send specially formed queries once per day to
domains for which trust anchors have been configured via, e.g.,
``trust-anchors`` or ``dnssec-validation auto``.
operating systems that causes IPv4 TCP connections, such as zone
transfers, to be accepted on an IPv6 socket using mapped addresses.
This caused address-match lists designed for IPv4 to fail to match.
- However, ``named`` now solves this problem internally. The use of
+ However, :iscman:`named` now solves this problem internally. The use of
this option is discouraged.
``ixfr-from-differences``
``multi-master``
This should be set when there are multiple primary servers for a zone and the
- addresses refer to different machines. If ``yes``, ``named`` does not
- log when the serial number on the primary is less than what ``named``
+ addresses refer to different machines. If ``yes``, :iscman:`named` does not
+ log when the serial number on the primary is less than what :iscman:`named`
currently has. The default is ``no``.
``auto-dnssec``
automatically adjusts the zone's DNSSEC keys on a schedule, according
to the keys' timing metadata (see :ref:`man_dnssec-keygen` and
:ref:`man_dnssec-settime`). The command :option:`rndc sign zonename <rndc sign>`
- causes ``named`` to load keys from the key repository and sign the
+ causes :iscman:`named` to load keys from the key repository and sign the
zone with all keys that are active. :option:`rndc loadkeys zonename <rndc loadkeys>`
- causes ``named`` to load keys from the key repository and schedule
+ causes :iscman:`named` to load keys from the key repository and schedule
key maintenance events to occur in the future, but it does not sign
the full zone immediately. Note: once keys have been loaded for a
zone the first time, the repository is searched for changes
.. _dnssec-validation-option:
``dnssec-validation``
- This option enables DNSSEC validation in ``named``.
+ This option enables DNSSEC validation in :iscman:`named`.
If set to ``auto``, DNSSEC validation is enabled and a default trust
anchor for the DNS root zone is used.
``yes``.
The default root trust anchor is stored in the file ``bind.keys``.
- ``named`` loads that key at startup if ``dnssec-validation`` is
+ :iscman:`named` loads that key at startup if ``dnssec-validation`` is
set to ``auto``. A copy of the file is installed along with BIND 9,
and is current as of the release date. If the root key expires, a new
copy of ``bind.keys`` can be downloaded from
https://www.isc.org/bind-keys.
(To prevent problems if ``bind.keys`` is not found, the current trust
- anchor is also compiled in ``named``. Relying on this is not
- recommended, however, as it requires ``named`` to be recompiled with
+ anchor is also compiled in :iscman:`named`. Relying on this is not
+ recommended, however, as it requires :iscman:`named` to be recompiled with
a new key when the root key expires.)
- .. note:: ``named`` loads *only* the root key from ``bind.keys``. The file
+ .. note:: :iscman:`named` loads *only* the root key from ``bind.keys``. The file
cannot be used to store keys for other zones. The root key in
``bind.keys`` is ignored if ``dnssec-validation auto`` is not in
use.
``dnssec-accept-expired``
This accepts expired signatures when verifying DNSSEC signatures. The
- default is ``no``. Setting this option to ``yes`` leaves ``named``
+ default is ``no``. Setting this option to ``yes`` leaves :iscman:`named`
vulnerable to replay attacks.
``querylog``
cost to performance which may be significant on heavily loaded servers.
The ``querylog`` option specifies whether query logging should be active when
- ``named`` first starts. If ``querylog`` is not specified, then query logging
+ :iscman:`named` first starts. If ``querylog`` is not specified, then query logging
is determined by the presence of the logging category ``queries``. Query
logging can also be activated at runtime using the command ``rndc querylog
on``, or deactivated with :option:`rndc querylog off <rndc querylog>`.
that MX and SRV records refer to address (A or AAAA) records and that
glue address records exist for delegated zones. For MX and SRV
records, only in-zone hostnames are checked (for out-of-zone hostnames,
- use ``named-checkzone``). For NS records, only names below top-of-zone
+ use :iscman:`named-checkzone`). For NS records, only names below top-of-zone
are checked (for out-of-zone names and glue consistency checks, use
- ``named-checkzone``). The default is ``yes``.
+ :iscman:`named-checkzone`). The default is ``yes``.
The use of the SPF record to publish Sender Policy Framework is
deprecated, as the migration from using TXT records to SPF records was
Note that if a zone has been configured with ``auto-dnssec maintain``
and the private keys remain accessible in the key repository,
- the zone will be automatically signed again the next time ``named``
+ the zone will be automatically signed again the next time :iscman:`named`
is started.
``synth-from-dnssec``
``allow-recursion-on`` is not set, then ``allow-query-cache-on`` is
used if set; otherwise, the default is to allow recursive queries on
all addresses. Any client permitted to send recursive queries can
- send them to any address on which ``named`` is listening. Note: both
+ send them to any address on which :iscman:`named` is listening. Note: both
``allow-recursion`` and ``allow-recursion-on`` must be satisfied
before recursion is allowed; a client that is blocked by one cannot
be allowed by the other.
``no-case-compress``
This specifies a list of addresses which require responses to use
- case-insensitive compression. This ACL can be used when ``named``
+ case-insensitive compression. This ACL can be used when :iscman:`named`
needs to work with clients that do not comply with the requirement in
:rfc:`1034` to use case-insensitive name comparisons when checking for
matching domain names.
Case-insensitive compression is *always* used in AXFR and IXFR
responses, regardless of whether the client matches this ACL.
- There are circumstances in which ``named`` does not preserve the case
+ There are circumstances in which :iscman:`named` does not preserve the case
of owner names of records: if a zone file defines records of
different types with the same name, but the capitalization of the
name is different (e.g., "www.example.com/A" and
If no ``listen-on-v6`` is specified, the default is to listen for standard
DNS queries on port 53 of all IPv6 interfaces.
-If a TLS configuration is specified, ``named`` will listen for DNS-over-TLS
+If a TLS configuration is specified, :iscman:`named` will listen for DNS-over-TLS
(DoT) connections, using the key and certificate specified in the
referenced ``tls`` statement. If the name ``ephemeral`` is used,
an ephemeral key and certificate created for the currently running
-``named`` process will be used.
+:iscman:`named` process will be used.
-If an HTTP configuration is specified, ``named`` will listen for
+If an HTTP configuration is specified, :iscman:`named` will listen for
DNS-over-HTTPS (DoH) connections using the HTTP endpoint specified in the
referenced ``http`` statement. If the name ``default`` is used, then
-``named`` will listen for connections at the default endpoint,
+:iscman:`named` will listen for connections at the default endpoint,
``/dns-query``.
Use of an ``http`` specification requires ``tls`` to be specified
query-source-v6 address * port *;
If ``use-v4-udp-ports`` or ``use-v6-udp-ports`` is unspecified,
-``named`` checks whether the operating system provides a programming
+:iscman:`named` checks whether the operating system provides a programming
interface to retrieve the system's default range for ephemeral ports. If
-such an interface is available, ``named`` uses the corresponding
+such an interface is available, :iscman:`named` uses the corresponding
system default range; otherwise, it uses its own defaults:
::
desirable size depends on several parameters, but we generally recommend
it contain at least 16384 ports (14 bits of entropy). Note also that the
system's default range when used may be too small for this purpose, and
- that the range may even be changed while ``named`` is running; the new
- range is automatically applied when ``named`` is reloaded. Explicit
+ that the range may even be changed while :iscman:`named` is running; the new
+ range is automatically applied when :iscman:`named` is reloaded. Explicit
configuration of ``use-v4-udp-ports`` and ``use-v6-udp-ports`` is encouraged,
so that the ranges are sufficiently large and are reasonably
independent from the ranges used by other applications.
-.. note:: The operational configuration where ``named`` runs may prohibit
+.. note:: The operational configuration where :iscman:`named` runs may prohibit
the use of some ports. For example, Unix systems do not allow
- ``named``, if run without root privilege, to use ports less than 1024.
+ :iscman:`named`, if run without root privilege, to use ports less than 1024.
If such ports are included in the specified (or detected) set of query
ports, the corresponding query attempts will fail, resulting in
resolution failures or delay. It is therefore important to configure the
use-v6-udp-ports { range 32768 65535; };
avoid-v6-udp-ports { 40000; range 50000 60000; };
-UDP ports of IPv6 messages sent from ``named`` are in one of the
+UDP ports of IPv6 messages sent from :iscman:`named` are in one of the
following ranges: 32768 to 39999, 40001 to 49999, and 60001 to 65535.
``avoid-v4-udp-ports`` and ``avoid-v6-udp-ports`` can be used to prevent
-``named`` from choosing as its random source port a port that is blocked
+:iscman:`named` from choosing as its random source port a port that is blocked
by a firewall or a port that is used by other applications; if a
query went out with a source port blocked by a firewall, the answer
would not pass through the firewall and the name server would have to query
``clients-per-query``; ``max-clients-per-query``
These set the initial value (minimum) and maximum number of recursive
simultaneous clients for any given query (<qname,qtype,qclass>) that
- the server accepts before dropping additional clients. ``named``
+ the server accepts before dropping additional clients. :iscman:`named`
attempts to self-tune this value and changes are logged. The
default values are 10 and 100.
This value should reflect how many queries come in for a given name
in the time it takes to resolve that name. If the number of queries
- exceeds this value, ``named`` assumes that it is dealing with a
+ exceeds this value, :iscman:`named` assumes that it is dealing with a
non-responsive zone and drops additional queries. If it gets a
response after dropping queries, it raises the estimate. The
estimate is then lowered in 20 minutes if it has remained
:ref:`attach-cache <attach-cache>` option is used).
When the amount of data in a cache database reaches the configured
- limit, ``named`` starts purging non-expired records (following an
+ limit, :iscman:`named` starts purging non-expired records (following an
LRU-based strategy).
The default size limit for each individual cache is:
On systems where detection of the amount of physical memory is not
supported, percentage-based values fall back to ``unlimited``. Note
that the amount of physical memory available is only detected on
- startup, so ``named`` does not adjust the cache size limits if the
+ startup, so :iscman:`named` does not adjust the cache size limits if the
amount of physical memory is changed at runtime.
``tcp-listen-queue``
long as the database is not modified.
The default RRset order used depends on whether any ``rrset-order``
-statements are present in the configuration file used by ``named``:
+statements are present in the configuration file used by :iscman:`named`:
- If no ``rrset-order`` statement is present in the configuration
file, the implicit default is to return all records in ``random``
``sig-validity-interval``
this specifies the upper bound of the number of days that RRSIGs
- generated by ``named`` are valid; the default is ``30`` days,
+ generated by :iscman:`named` are valid; the default is ``30`` days,
with a maximum of 3660 days (10 years). The optional second value
specifies the minimum bound on those RRSIGs and also determines
- how long before expiry ``named`` starts regenerating those RRSIGs.
+ how long before expiry :iscman:`named` starts regenerating those RRSIGs.
The default value for the lower bound is 1/4 of the upper bound;
it is expressed in days if the upper bound is greater than 7,
and hours if it is less than or equal to 7 days.
This parameter may be removed in a future version,
once there is a standard type.
- Signing-state records are used internally by ``named`` to track
+ Signing-state records are used internally by :iscman:`named` to track
the current state of a zone-signing process, i.e., whether it is
still active or has been completed. The records can be inspected
- using the command :option:`rndc signing -list zone <rndc signing>`. Once ``named`` has
+ using the command :option:`rndc signing -list zone <rndc signing>`. Once :iscman:`named` has
finished signing a zone with a particular key, the signing-state
record associated with that key can be removed from the zone by
running :option:`rndc signing -clear keyid/algorithm zone <rndc signing>`. To clear all of
fragmented packets and/or block UDP DNS packets that are greater than
512 bytes.
- When ``named`` first queries a remote server, it advertises a UDP
+ When :iscman:`named` first queries a remote server, it advertises a UDP
buffer size of 1232.
Query timeouts observed for any given server affect the buffer size
dropping patterns, the query is retried over TCP. Per-server EDNS statistics
are only retained in memory for the lifetime of a given server's ADB entry.
- The ``named`` now sets the DON'T FRAGMENT flag on outgoing UDP packets.
+ The :iscman:`named` now sets the DON'T FRAGMENT flag on outgoing UDP packets.
According to the measurements done by multiple parties this should not be
causing any operational problems as most of the Internet "core" is able to
cope with IP message sizes between 1400-1500 bytes, the 1232 size was picked
the above rules.
``max-udp-size``
- This sets the maximum EDNS UDP message size that ``named`` sends, in bytes.
+ This sets the maximum EDNS UDP message size that :iscman:`named` sends, in bytes.
Valid values are 512 to 4096; values outside this range are
silently adjusted to the nearest value within it. The default value
is 1232.
for details). The default value is ``text``, which is the standard
textual representation, except for secondary zones, in which the default
value is ``raw``. Files in formats other than ``text`` are typically
- expected to be generated by the ``named-compilezone`` tool, or dumped by
- ``named``.
+ expected to be generated by the :iscman:`named-compilezone` tool, or dumped by
+ :iscman:`named`.
Note that when a zone file in a format other than ``text`` is loaded,
- ``named`` may omit some of the checks which are performed for a file in
+ :iscman:`named` may omit some of the checks which are performed for a file in
``text`` format. For example, ``check-names`` only applies when loading
zones in ``text`` format, and ``max-zone-ttl`` only applies to ``text``
and ``raw``. Zone files in binary formats should be generated with the
- same check level as that specified in the ``named`` configuration file.
+ same check level as that specified in the :iscman:`named` configuration file.
When configured in ``options``, this statement sets the
``masterfile-format`` for all zones, but it can be overridden on a
``prefetch``
When a query is received for cached data which is to expire shortly,
- ``named`` can refresh the data from the authoritative server
+ :iscman:`named` can refresh the data from the authoritative server
immediately, ensuring that the cache always has an answer available.
``prefetch`` specifies the "trigger" TTL value at which prefetch
An optional second argument specifies the "eligibility" TTL: the
smallest *original* TTL value that is accepted for a record to
be eligible for prefetching. The eligibility TTL must be at least six
- seconds longer than the trigger TTL; if not, ``named``
+ seconds longer than the trigger TTL; if not, :iscman:`named`
silently adjusts it upward. The default eligibility TTL is ``9``.
``v6-bias``
type ``TXT`` and class ``CHAOS``. The primary purpose of such queries is
to identify which of a group of anycast servers is actually answering
the queries. Specifying ``server-id none;`` disables processing of
- the queries. Specifying ``server-id hostname;`` causes ``named``
+ the queries. Specifying ``server-id hostname;`` causes :iscman:`named`
to use the hostname as found by the ``gethostname()`` function. The
default ``server-id`` is ``none``.
Built-in Empty Zones
^^^^^^^^^^^^^^^^^^^^
-The ``named`` server has some built-in empty zones, for SOA and NS records
+The :iscman:`named` server has some built-in empty zones, for SOA and NS records
only. These are for zones that should normally be answered locally and for
which queries should not be sent to the Internet's root servers. The
official servers that cover these namespaces return NXDOMAIN responses
``nsdname-enable`` phrase turns NSDNAME triggers off or on for a single
policy zone or for all zones.
- If authoritative name servers for the query name are not yet known, ``named``
+ If authoritative name servers for the query name are not yet known, :iscman:`named`
recursively looks up the authoritative servers for the query name before
applying an RPZ-NSDNAME rule, which can cause a processing delay. To speed up
processing at the cost of precision, the ``nsdname-wait-recurse`` option can
exclude top-level domains. The ``nsip-enable`` phrase turns NSIP
triggers off or on for a single policy zone or for all zones.
- If a name server's IP address is not yet known, ``named``
+ If a name server's IP address is not yet known, :iscman:`named`
recursively looks up the IP address before applying an RPZ-NSIP rule,
which can cause a processing delay. To speed up processing at the cost
of precision, the ``nsip-wait-recurse`` option can be used; when set
done to discover problems at the authoritative server.
The ``dnsrps-enable yes`` option turns on the DNS Response Policy Service
-(DNSRPS) interface, if it has been compiled in ``named`` using
+(DNSRPS) interface, if it has been compiled in :iscman:`named` using
``configure --enable-dnsrps``.
The ``dnsrps-options`` block provides additional RPZ configuration
``dnsrpzd-conf``, ``dnsrpzd-sock``, and ``dnzrpzd-args`` (for details of
these options, see the ``librpz`` documentation). Other RPZ
configuration settings could be included in ``dnsrps-options`` as well,
-but if ``named`` were switched back to traditional RPZ by setting
+but if :iscman:`named` were switched back to traditional RPZ by setting
``dnsrps-enable`` to "no", those options would be ignored.
The TTL of a record modified by RPZ policies is set from the TTL of the
NXDOMAIN Redirection
^^^^^^^^^^^^^^^^^^^^
-``named`` supports NXDOMAIN redirection via two methods:
+:iscman:`named` supports NXDOMAIN redirection via two methods:
- Redirect zone (:ref:`zone_statement_grammar`)
- Redirect namespace
-With either method, when ``named`` gets an NXDOMAIN response it examines a
+With either method, when :iscman:`named` gets an NXDOMAIN response it examines a
separate namespace to see if the NXDOMAIN response should be replaced
with an alternative response.
The ``server`` statement defines characteristics to be associated with a
remote name server. If a prefix length is specified, then a range of
servers is covered. Only the most specific server clause applies,
-regardless of the order in ``named.conf``.
+regardless of the order in :iscman:`named.conf`.
The ``server`` statement can occur at the top level of the configuration
file or inside a ``view`` statement. If a ``view`` statement contains
``yes``.
The ``edns-udp-size`` option sets the EDNS UDP size that is advertised
-by ``named`` when querying the remote server. Valid values are 512 to
+by :iscman:`named` when querying the remote server. Valid values are 512 to
4096 bytes; values outside this range are silently adjusted to the
nearest value within it. This option is useful when
advertising a different value to this server than the value advertised
globally: for example, when there is a firewall at the remote site that
is blocking large replies. Note: currently, this sets a single UDP size
-for all packets sent to the server; ``named`` does not deviate from this
+for all packets sent to the server; :iscman:`named` does not deviate from this
value. This differs from the behavior of ``edns-udp-size`` in
``options`` or ``view`` statements, where it specifies a maximum value.
The ``server`` statement behavior may be brought into conformance with
higher EDNS versions than 0 are in use.
The ``max-udp-size`` option sets the maximum EDNS UDP message size
-``named`` sends. Valid values are 512 to 4096 bytes; values outside
+:iscman:`named` sends. Valid values are 512 to 4096 bytes; values outside
this range are silently adjusted. This option is useful when
there is a firewall that is blocking large replies from
-``named``.
+:iscman:`named`.
The ``padding`` option adds EDNS Padding options to outgoing messages,
increasing the packet size to a multiple of the specified block size.
The ``send-cookie`` clause determines whether the local server adds
a COOKIE EDNS option to requests sent to the server. This overrides
-``send-cookie`` set at the view or option level. The ``named`` server
+``send-cookie`` set at the view or option level. The :iscman:`named` server
may determine that COOKIE is not supported by the remote server and not
add a COOKIE EDNS option to requests.
Attempts to open a statistics channel are restricted by the
optional ``allow`` clause. Connections to the statistics channel are
permitted based on the ``address_match_list``. If no ``allow`` clause is
-present, ``named`` accepts connection attempts from any address; since
+present, :iscman:`named` accepts connection attempts from any address; since
the statistics may contain sensitive internal information, it is highly
recommended to restrict the source of connection requests appropriately.
-If no ``statistics-channels`` statement is present, ``named`` does not
+If no ``statistics-channels`` statement is present, :iscman:`named` does not
open any communication channels.
The statistics are available in various formats and views, depending on
The ``tls`` statement is used to configure a TLS connection; this
configuration can then be referenced by a ``listen-on`` or ``listen-on-v6``
-statement to cause ``named`` to listen for incoming requests via TLS,
+statement to cause :iscman:`named` to listen for incoming requests via TLS,
or in the ``primaries`` statement for a zone of type ``secondary`` to
cause zone transfer requests to be sent via TLS.
-``tls`` can only be set at the top level of ``named.conf``.
+``tls`` can only be set at the top level of :iscman:`named.conf`.
The following options can be specified in a ``tls`` statement:
not contain any sensitive data and can be shared if required.
There are two built-in TLS connection configurations: ``ephemeral``,
-uses a temporary key and certificate created for the current ``named``
+uses a temporary key and certificate created for the current :iscman:`named`
session only, and ``none``, which can be used when setting up an HTTP
listener with no encryption.
The ``http`` statement is used to configure HTTP endpoints on which
to listen for DNS-over-HTTPS (DoH) queries. This configuration can
then be referenced by a ``listen-on`` or ``listen-on-v6`` statement to
-cause ``named`` to listen for incoming requests over HTTPS.
+cause :iscman:`named` to listen for incoming requests over HTTPS.
-``http`` can only be set at the top level of ``named.conf``.
+``http`` can only be set at the top level of :iscman:`named.conf`.
The following options can be specified in an ``http`` statement:
configured as trust anchors are used to validate the DNSKEY RRset for
the corresponding name. The parent's DS RRset is not used.
-``trust-anchors`` may be set at the top level of ``named.conf`` or within
+``trust-anchors`` may be set at the top level of :iscman:`named.conf` or within
a view. If it is set in both places, the configurations are additive;
keys defined at the top level are inherited by all views, but keys
defined in a view are only used within that view.
If, however, the trust anchor had been configured using
``initial-key`` or ``initial-ds``
instead, the zone owner could add a "stand-by" key to
-the zone in advance. ``named`` would store
+the zone in advance. :iscman:`named` would store
the stand-by key, and when the original key was revoked,
-``named`` would be able to transition smoothly
+:iscman:`named` would be able to transition smoothly
to the new key. It would also recognize that the old key had
been revoked and cease using that key to validate answers,
minimizing the damage that the compromised key could do.
Whereas ``static-key`` and
``static-ds`` trust anchors continue
to be trusted until they are removed from
-``named.conf``, an
+:iscman:`named.conf`, an
``initial-key`` or ``initial-ds``
is only trusted *once*: for as long as it
takes to load the managed key database and start the
It is not possible to mix static with initial trust anchors
for the same domain name.
-The first time ``named`` runs with an
+The first time :iscman:`named` runs with an
``initial-key`` or ``initial-ds``
-configured in ``named.conf``, it fetches the
+configured in :iscman:`named.conf`, it fetches the
DNSKEY RRset directly from the zone apex,
and validates it
using the trust anchor specified in ``trust-anchors``.
the trust anchor, then it is used as the basis for a new
managed-keys database.
-From that point on, whenever ``named`` runs, it sees the ``initial-key`` or ``initial-ds``
+From that point on, whenever :iscman:`named` runs, it sees the ``initial-key`` or ``initial-ds``
listed in ``trust-anchors``, checks to make sure :rfc:`5011` key maintenance
has already been initialized for the specified domain, and if so,
simply moves on. The key specified in the ``trust-anchors`` statement is
not used to validate answers; it is superseded by the key or keys stored
in the managed-keys database.
-The next time ``named`` runs after an ``initial-key`` or ``initial-ds`` has been *removed*
+The next time :iscman:`named` runs after an ``initial-key`` or ``initial-ds`` has been *removed*
from the ``trust-anchors`` statement (or changed to a ``static-key`` or ``static-ds``), the
corresponding zone is removed from the managed-keys database, and
:rfc:`5011` key maintenance is no longer used for that domain.
dynamic zone, changes are written into a journal file, e.g.,
``managed-keys.bind.jnl`` or ``internal.mkeys.jnl``. Changes are
committed to the primary file as soon as possible afterward,
-usually within 30 seconds. Whenever ``named`` is using
+usually within 30 seconds. Whenever :iscman:`named` is using
automatic key maintenance, the zone file and journal file can be
expected to exist in the working directory. (For this reason, among
others, the working directory should be always be writable by
-``named``.)
+:iscman:`named`.)
-If the ``dnssec-validation`` option is set to ``auto``, ``named``
+If the ``dnssec-validation`` option is set to ``auto``, :iscman:`named`
automatically initializes an ``initial-key`` for the root zone. The key
that is used to initialize the key-maintenance process is stored in
``bind.keys``; the location of this file can be overridden with the
``bindkeys-file`` option. As a fallback in the event no ``bind.keys``
can be found, the initializing key is also compiled directly into
-``named``.
+:iscman:`named`.
.. _dnssec_policy_grammar:
Key rollover timing is computed for each key according to the key
lifetime defined in the KASP. The lifetime may be modified by zone TTLs
and propagation delays, to prevent validation failures. When a key
-reaches the end of its lifetime, ``named`` generates and publishes a new
+reaches the end of its lifetime, :iscman:`named` generates and publishes a new
key automatically, then deactivates the old key and activates the new
one; finally, the old key is retired according to a computed schedule.
``default``.
If a ``dnssec-policy`` statement is modified and the server restarted or
-reconfigured, ``named`` attempts to change the policy smoothly from the
+reconfigured, :iscman:`named` attempts to change the policy smoothly from the
old one to the new. For example, if the key algorithm is changed, then
a new key is generated with the new algorithm, and the old algorithm is
retired when the existing key's lifetime ends.
``purge-keys``
This is the time after when DNSSEC keys that have been deleted from
the zone can be removed from disk. If a key still determined to have
- presence (for example in some resolver cache), ``named`` will not
+ presence (for example in some resolver cache), :iscman:`named` will not
remove the key files.
The default is ``P90D`` (90 days). Set this option to ``0`` to never
The default is to use NSEC. The ``iterations``, ``optout`` and
``salt-length`` parts are optional, but if not set, the values in
the example above are the default NSEC3 parameters. Note that you don't
- specify a specific salt string, ``named`` will create a salt for you
+ specify a specific salt string, :iscman:`named` will create a salt for you
of the provided salt length.
``zone-propagation-delay``
data is subject to DNSSEC validation before being used in answers.
Validation is applied to the entire zone during the zone transfer
process, and again when the zone file is loaded from disk upon
- restarting ``named``. If validation of a new version of a mirror zone
+ restarting :iscman:`named`. If validation of a new version of a mirror zone
fails, a retransfer is scheduled; in the meantime, the most recent
correctly validated version of that zone is used until it either
expires or a newer version validates correctly. If no usable zone
Mirror zones are intended to be used to set up a fast local copy of
the root zone (see :rfc:`8806`). A default list of primary servers
- for the IANA root zone is built into ``named``, so its mirroring can
+ for the IANA root zone is built into :iscman:`named`, so its mirroring can
be enabled using the following configuration:
::
relevant zone (or view). Other, more efficient zone verification
methods may be added in the future.
- To make mirror zone contents persist between ``named`` restarts, use
+ To make mirror zone contents persist between :iscman:`named` restarts, use
the :ref:`file <file-option>` option.
Mirroring a zone other than root requires an explicit list of primary
Stub zones can be used to eliminate the need for a glue NS record in a parent
zone, at the expense of maintaining a stub zone entry and a set of name
- server addresses in ``named.conf``. This usage is not recommended for
+ server addresses in :iscman:`named.conf`. This usage is not recommended for
new configurations, and BIND 9 supports it only in a limited way. If a BIND 9
primary, serving a parent zone, has child stub
zones configured, all the secondary servers for the parent zone also need to
``server-names``
This option is only meaningful for static-stub zones. This is a list of domain names
of name servers that act as authoritative servers of the static-stub
- zone. These names are resolved to IP addresses when ``named``
+ zone. These names are resolved to IP addresses when :iscman:`named`
needs to send queries to these servers. For this supplemental
resolution to be successful, these names must not be a subdomain of the
origin name of the static-stub zone. That is, when "example.net" is the
``update-policy`` at the same time.
A pre-defined ``update-policy`` rule can be switched on with the command
-``update-policy local;``. ``named`` automatically
+``update-policy local;``. :iscman:`named` automatically
generates a TSIG session key when starting and stores it in a file;
this key can then be used by local clients to update the zone while
-``named`` is running. By default, the session key is stored in the file
+:iscman:`named` is running. By default, the session key is stored in the file
|session_key|, the key name is "local-ddns", and the
key algorithm is HMAC-SHA256. These values are configurable with the
``session-keyfile``, ``session-keyname``, and ``session-keyalg`` options,
with the additional restriction that only clients connecting from the
local system are permitted to send updates.
-Note that only one session key is generated by ``named``; all zones
+Note that only one session key is generated by :iscman:`named`; all zones
configured to use ``update-policy local`` accept the same key.
The command ``nsupdate -l`` implements this feature, sending requests to
It is theoretically possible to spoof these TCP sessions.
``external``
- This rule allows ``named`` to defer the decision of whether to allow a given update to an external daemon.
+ This rule allows :iscman:`named` to defer the decision of whether to allow a given update to an external daemon.
The method of communicating with the daemon is specified in the ``identity`` field, the format of which is "``local:``\ path", where "path" is the location of a Unix-domain socket. (Currently, "local" is the only supported mechanism.)
This reads and processes the file ``filename`` as if it were included in the
file at this point. The ``filename`` can be an absolute path, or a relative
-path. In the latter case it is read from ``named``'s working directory. If
+path. In the latter case it is read from :iscman:`named`'s working directory. If
``origin`` is specified, the file is processed with ``$ORIGIN`` set to that
value; otherwise, the current ``$ORIGIN`` is used.
parsing text, load time is significantly reduced.
For a primary server, a zone file in ``raw`` format is expected
-to be generated from a text zone file by the ``named-compilezone`` command.
+to be generated from a text zone file by the :iscman:`named-compilezone` command.
For a secondary server or a dynamic zone, the zone file is automatically
-generated when ``named`` dumps the zone contents after zone transfer or
+generated when :iscman:`named` dumps the zone contents after zone transfer or
when applying prior updates, if one of these formats is specified by the
``masterfile-format`` option.
If a zone file in ``raw`` format needs manual modification, it first must
-be converted to ``text`` format by the ``named-compilezone`` command,
+be converted to ``text`` format by the :iscman:`named-compilezone` command,
then converted back after editing. For example:
::
On Unix servers, it is possible to run BIND in a *chrooted* environment
(using the ``chroot()`` function) by specifying the :option:`-t <named -t>` option for
-``named``. This can help improve system security by placing BIND in a
+:iscman:`named`. This can help improve system security by placing BIND in a
"sandbox," which limits the damage done if a server is compromised.
Another useful feature in the Unix version of BIND is the ability to run
as an unprivileged user when using the ``chroot`` feature.
Here is an example command line to load BIND in a ``chroot`` sandbox,
-``/var/named``, and to run ``named`` ``setuid`` to user 202:
+``/var/named``, and to run :iscman:`named` ``setuid`` to user 202:
``/usr/local/sbin/named -u 202 -t /var/named``
must be adjusted to account for this.
Unlike with earlier versions of BIND,
-``named`` does *not* typically need to be compiled statically, nor do shared libraries need to be installed under the new
+:iscman:`named` does *not* typically need to be compiled statically, nor do shared libraries need to be installed under the new
root. However, depending on the operating system, it may be necessary to set
up locations such as ``/dev/zero``, ``/dev/random``, ``/dev/log``, and
``/etc/localtime``.
Using the ``setuid`` Function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Prior to running the ``named`` daemon, use the ``touch`` utility (to
+Prior to running the :iscman:`named` daemon, use the ``touch`` utility (to
change file access and modification times) or the ``chown`` utility (to
set the user id and/or group id) on files where BIND should
write.
.. note::
- If the ``named`` daemon is running as an unprivileged user, it
+ If the :iscman:`named` daemon is running as an unprivileged user, it
cannot bind to new restricted ports if the server is
reloaded.
is opaque to packet sniffers, which makes debugging problems with
encrypted DNS close to impossible. However, Wireshark_ offers a
solution_ to this problem by being able to read key log files. In order
-to make ``named`` prepare such a file, set the ``SSLKEYLOGFILE``
+to make :iscman:`named` prepare such a file, set the ``SSLKEYLOGFILE``
environment variable to either:
- the string ``config`` (``SSLKEYLOGFILE=config``); this requires
unusable.
When the ``SSLKEYLOGFILE`` environment variable is set, each TLS
-connection established by ``named`` (both incoming and outgoing) causes
+connection established by :iscman:`named` (both incoming and outgoing) causes
about 1 kilobyte of data to be written to the key log file.
.. warning::
Due to the limitations of the current logging code in BIND 9,
- enabling TLS pre-master secret logging adversely affects ``named``
+ enabling TLS pre-master secret logging adversely affects :iscman:`named`
performance.
.. _Wireshark: https://www.wireshark.org/
security versus resources.
- *Salt*: The salt cannot be configured explicitly, but you can provide
- a salt length and ``named`` generates a random salt of the given length.
+ a salt length and :iscman:`named` generates a random salt of the given length.
We learn more about salt in :ref:`advanced_discussions_nsec3_salt`.
If you want to use these NSEC3 parameters for a zone, you can add the
care to avoid breaking DNSSEC validation.
If you are managing DNSSEC by using the ``dnssec-policy`` configuration,
-``named`` handles the rollover for you. Simply change the algorithm
-for the relevant keys, and ``named`` uses the new algorithm when the
+:iscman:`named` handles the rollover for you. Simply change the algorithm
+for the relevant keys, and :iscman:`named` uses the new algorithm when the
key is next rolled. It performs a smooth transition to the new
algorithm, ensuring that the zone remains valid throughout rollover.
with other key rollovers, when the zone is a primary zone, an algorithm
rollover can be accomplished using dynamic updates or automatic key
rollovers. For secondary zones, only automatic key rollovers are
-possible, but the ``dnssec-settime`` utility can be used to control the
+possible, but the :iscman:`dnssec-settime` utility can be used to control the
timing.
In any case, the first step is to put DNSKEYs in place using the new algorithm.
You must generate the ``K*`` files for the new algorithm and put
-them in the zone's key directory, where ``named`` can access them. Take
+them in the zone's key directory, where :iscman:`named` can access them. Take
care to set appropriate ownership and permissions on the keys. If the
-``auto-dnssec`` zone option is set to ``maintain``, ``named``
+``auto-dnssec`` zone option is set to ``maintain``, :iscman:`named`
automatically signs the zone with the new keys, based on their timing
metadata when the ``dnssec-loadkeys-interval`` elapses or when you issue the
:option:`rndc loadkeys` command. Otherwise, for primary zones, you can use
-``nsupdate`` to add the new DNSKEYs to the zone; this causes ``named``
+:iscman:`nsupdate` to add the new DNSKEYs to the zone; this causes :iscman:`named`
to use them to sign the zone. For secondary zones, e.g., on a
-"bump in the wire" signing server, ``nsupdate`` cannot be used.
+"bump in the wire" signing server, :iscman:`nsupdate` cannot be used.
Once the zone has been signed by the new DNSKEYs (and you have waited
for at least one TTL period), you must inform the parent zone and any trust
so that the old DS records disappear from all resolver caches.
The next step is to remove the DNSKEYs using the old algorithm from your
-zone. Again this can be accomplished using ``nsupdate`` to delete the
+zone. Again this can be accomplished using :iscman:`nsupdate` to delete the
old DNSKEYs (for primary zones only) or by automatic key rollover when
``auto-dnssec`` is set to ``maintain``. You can cause the automatic key
-rollover to take place immediately by using the ``dnssec-settime``
+rollover to take place immediately by using the :iscman:`dnssec-settime`
utility to set the *Delete* date on all keys to any time in the past.
(See the :option:`dnssec-settime -D date/offset <dnssec-settime -D>` option.)
After adjusting the timing metadata, the :option:`rndc loadkeys` command
-causes ``named`` to remove the DNSKEYs and
+causes :iscman:`named` to remove the DNSKEYs and
RRSIGs for the old algorithm from the zone. Note also that with the
-``nsupdate`` method, removing the DNSKEYs also causes ``named`` to
+:iscman:`nsupdate` method, removing the DNSKEYs also causes :iscman:`named` to
remove the associated RRSIGs automatically.
Once you have verified that the old DNSKEYs and RRSIGs have been removed
updating zone data works the same way as with traditional (insecure)
DNS: you can use :option:`rndc freeze` before editing the zone file, and
:option:`rndc thaw` when you have finished editing, or you can use the
-command ``nsupdate`` to add, edit, or remove records like this:
+command :iscman:`nsupdate` to add, edit, or remove records like this:
::
> send
> quit
-The examples provided in this guide make ``named`` automatically
+The examples provided in this guide make :iscman:`named` automatically
re-sign the zone whenever its content has changed. If you decide to sign
your own zone file manually, you need to remember to execute the
-``dnssec-signzone`` command whenever your zone file has been updated.
+:iscman:`dnssec-signzone` command whenever your zone file has been updated.
As far as system resources and performance are concerned, be mindful that
with a DNSSEC zone that changes frequently, every time the zone
specific key rollover requirements) get their own key pairs, while other,
more "generic" zones can use a single key pair for easier management. Note that
at present (mid-2020), fully automatic signing (using the ``dnssec-policy``
- clause in your ``named`` configuration file) does not support reuse of keys
+ clause in your :iscman:`named` configuration file) does not support reuse of keys
except when the same zone appears in multiple views (see next question).
To use the same key for multiple zones, sign your
zones using semi-automatic signing. Each zone wishing to use the key
Will there be any problems if I change the DNSSEC policy for a zone?
If you are using fully automatic signing, no. Just change the parameters in the
- ``dnssec-policy`` statement and reload the configuration file. ``named``
+ ``dnssec-policy`` statement and reload the configuration file. :iscman:`named`
makes a smooth transition to the new policy, ensuring that your zone
remains valid at all times.
Most configuration examples given in this document require BIND version
9.16.0 or newer (although many do work with all versions of BIND
-later than 9.9). To check the version of ``named`` you have installed,
+later than 9.9). To check the version of :iscman:`named` you have installed,
use the :option:`-v <named -v>` switch as shown below:
::
Using the method described in
:ref:`easy_start_guide_for_authoritative_servers`, we just need to
add a ``dnssec-policy`` statement to the relevant zone clause. This is
-what the ``named.conf`` zone statement looks like on the primary server, 192.168.1.1:
+what the :iscman:`named.conf` zone statement looks like on the primary server, 192.168.1.1:
::
file and select it in the zone statement (as described in
:ref:`signing_custom_policy`).
-On the secondary servers, ``named.conf`` does not need to be updated,
+On the secondary servers, :iscman:`named.conf` does not need to be updated,
and it looks like this:
::
primary 192.168.1.1 to receive the unsigned data; then, using keys
accessible to this middle box, to sign data on the fly; and finally, to send out the
signed data via zone transfer to the other three DNS secondaries. Its
-``named.conf`` zone statement looks like this:
+:iscman:`named.conf` zone statement looks like this:
::
Finally, on the three secondary servers, the configuration should be updated
to receive a zone transfer from 192.168.1.5 (the middle box) instead of
-from 192.168.1.1 (the hidden primary). If using BIND, the ``named.conf`` file looks
+from 192.168.1.1 (the hidden primary). If using BIND, the :iscman:`named.conf` file looks
like this:
::
you want your keys to be valid for, the time
taken for information to propagate through your zone, the time it takes
for your parent zone to register a new DS record, etc., and that's more
-or less it. ``named`` implements everything for you automatically, apart from
+or less it. :iscman:`named` implements everything for you automatically, apart from
uploading the new DS records to your parent zone - which is covered in
:ref:`signing_easy_start_upload_to_parent_zone`. (Some
screenshots from a session where a KSK is uploaded to the parent zone
``/etc/bind/keys/example.com/``, where keys for ``example.com`` are
stored.
-The second, ``dnssec-settime``, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1,
+The second, :iscman:`dnssec-settime`, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1,
2021, and a deletion (:option:`-D <dnssec-settime -D>`) date of February 1, 2021, for the current ZSK
(``Kexample.com.+008+17694``).
-The third command, ``dnssec-keygen``, creates a successor key, using
+The third command, :iscman:`dnssec-keygen`, creates a successor key, using
the exact same parameters (algorithms, key sizes, etc.) as the current
ZSK. The new ZSK created in our example is ``Kexample.com.+008+51623``.
-Make sure the successor keys are readable by ``named``.
+Make sure the successor keys are readable by :iscman:`named`.
-``named``'s logging messages indicate when the next
+:iscman:`named`'s logging messages indicate when the next
key checking event is scheduled to occur, the frequency of which can be
controlled by ``dnssec-loadkeys-interval``. The log message looks like
this:
Again, technically there is nothing you need to do on this day,
but it doesn't hurt to verify that the old ZSK (17694) is now completely
-gone from your zone. ``named`` will not touch
+gone from your zone. :iscman:`named` will not touch
``Kexample.com.+008+17694.private`` and ``Kexample.com.+008+17694.key``
-on your file system. Running the same ``dig`` command for DNSKEY should
+on your file system. Running the same :iscman:`dig` command for DNSKEY should
suffice:
::
``/etc/bind/keys/example.com/``, where keys for ``example.com`` are
stored.
-The second, ``dnssec-settime``, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1,
+The second, :iscman:`dnssec-settime`, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1,
2021, and a deletion (:option:`-D <dnssec-settime -D>`) date of February 1, 2021 for the current KSK
(``Kexample.com.+007+24848``).
-The third command, ``dnssec-keygen``, creates a successor key, using
+The third command, :iscman:`dnssec-keygen`, creates a successor key, using
the exact same parameters (algorithms, key sizes, etc.) as the current
KSK. The new key pair created in our example is ``Kexample.com.+007+23550``.
-The fourth and final command, ``dnssec-dsfromkey``, creates a DS record
+The fourth and final command, :iscman:`dnssec-dsfromkey`, creates a DS record
from the new KSK (23550), using SHA-1 as the digest type. Again, in
practice most people generate two DS records for both supported digest
types (SHA-1 and SHA-256), but for our example here we are only using
one to keep the output small and hopefully clearer.
-Make sure the successor keys are readable by ``named``.
+Make sure the successor keys are readable by :iscman:`named`.
The ``syslog`` message indicates when the next key
checking event is. The log message looks like this:
++++++++++++++++++++++++++++
While the removal of the old DNSKEY from the zone should be automated by
-``named``, the removal of the DS record is manual. You should make sure
+:iscman:`named`, the removal of the DS record is manual. You should make sure
the old DNSKEY record is gone from your zone first, by querying for the
DNSKEY records of the zone; this time we expect not to see
the key with an ID of 24828:
This recipe describes how to transition from using NSEC to NSEC3, as described
in :ref:`advanced_discussions_proof_of_nonexistence`. This recipe
-assumes that the zones are already signed, and that ``named`` is configured
+assumes that the zones are already signed, and that :iscman:`named` is configured
according to the steps described in
:ref:`easy_start_guide_for_authoritative_servers`.
nsec3param iterations 10 optout no salt-length 16;
};
-Then reconfigure the server with ``rndc``. You can tell that it worked if you
+Then reconfigure the server with :iscman:`rndc`. You can tell that it worked if you
see the following debug log messages:
::
same salt length, so to change your NSEC3 salt you need to change the
``salt-length`` value and reconfigure your server. You should see
the following messages in the log, assuming your old salt was
-"1234567890ABCDEF" and ``named`` created "FEDCBA09" (salt length 8)
+"1234567890ABCDEF" and :iscman:`named` created "FEDCBA09" (salt length 8)
as the new salt:
::
.. note::
NSEC3 hashes the plain text domain name, and we can compute our own
- hashes using the tool ``nsec3hash``. For example, to compute the
+ hashes using the tool :iscman:`nsec3hash`. For example, to compute the
hashed name for ``www.example.com`` using the parameters we listed
above, we can execute this command:
information has expired (usually this means one TTL interval has passed),
you may reconfigure your zone.
-Here is what ``named.conf`` looks like when it is signed:
+Here is what :iscman:`named.conf` looks like when it is signed:
::
unsigned.
When the DS records have been removed from the parent zone, use
-:option:`rndc dnssec -checkds -key id withdrawn example.com <rndc dnssec>` to tell ``named`` that
+:option:`rndc dnssec -checkds -key id withdrawn example.com <rndc dnssec>` to tell :iscman:`named` that
the DS is removed, and the remaining DNSSEC records will be removed in a timely
manner. Or if you have parental agents configured, the DNSSEC records will be
automatically removed after BIND has seen that the parental agents no longer
format. You can verify by checking that all DNSKEY and RRSIG records have been
removed from the zone.
-You can then remove the ``dnssec-policy`` line from your ``named.conf`` and
+You can then remove the ``dnssec-policy`` line from your :iscman:`named.conf` and
reload the zone. The zone will now no longer be subject to any DNSSEC
maintenance.
:ref:`signing_custom_policy`, but for the moment we are accepting the
default values.
-When the configuration file is updated, tell ``named`` to
+When the configuration file is updated, tell :iscman:`named` to
reload the configuration file by running :option:`rndc reconfig`:
::
It then starts signing the zone. How long this process takes depends on the
size of the zone, the speed of the server, and how much activity is
-taking place. We can check what is happening by using ``rndc``,
+taking place. We can check what is happening by using :iscman:`rndc`,
entering the command:
::
When the second message appears, the zone is signed.
Before moving on to the next step of coordinating with the parent zone,
-let's make sure everything looks good using ``delv``. We want to
+let's make sure everything looks good using :iscman:`delv`. We want to
simulate what a validating resolver will check, by telling
-``delv`` to use a specific trust anchor.
+:iscman:`delv` to use a specific trust anchor.
First, we need to make a copy of the key created by BIND. This
is in the directory you set with the ``directory`` statement in
example.com. static-key 257 3 13 "6saiq99qDB...dqp+o0dw==";
};
-Now we can run the ``delv`` command and instruct it to use this
+Now we can run the :iscman:`delv` command and instruct it to use this
trusted-key file to validate the answer it receives from the
authoritative name server 192.168.1.13:
example.com. 3600 IN DNSKEY 257 3 13 6saiq99qDB...dqp+o0dw==
The DS record format may be generated from the DNSKEY using the
-``dnssec-dsfromkey`` tool, which is covered in
+:iscman:`dnssec-dsfromkey` tool, which is covered in
:ref:`parent_ds_record_format`. For more details and examples on how
to work with your parent zone, please see
:ref:`working_with_parent_zone`.
DNSSEC-enabled. What happens next? That is basically it - BIND
takes care of everything else. As for updating your zone file, you can
continue to update it the same way as prior to signing your
-zone; the normal work flow of editing a zone file and using the ``rndc``
+zone; the normal work flow of editing a zone file and using the :iscman:`rndc`
command to reload the zone still works as usual, and although you are
editing the unsigned version of the zone, BIND generates the signed
version automatically.
oq4yBQumOhO5WX61LjA17l1DuLWcd/ASwlUZWFGCYQ== )
The serial number was automatically incremented from the old, unsigned
-version. ``named`` keeps track of the serial number of the signed version of
+version. :iscman:`named` keeps track of the serial number of the signed version of
the zone independently of the unsigned version. If the unsigned zone is
updated with a new serial number that is higher than the one in the
signed copy, then the signed copy is increased to match it;
Examine the Zone File
^^^^^^^^^^^^^^^^^^^^^
-Our original zone file ``example.com.db`` remains untouched, and ``named`` has
+Our original zone file ``example.com.db`` remains untouched, and :iscman:`named` has
generated three additional files automatically for us (shown below). The
signed DNS data is stored in ``example.com.db.signed`` and in the
associated journal file.
A quick description of each of the files:
-- ``.jbk``: a transient file used by ``named``
+- ``.jbk``: a transient file used by :iscman:`named`
- ``.signed``: the signed version of the zone in raw format
- ``.signed.jnl``: a journal file for the signed version of the zone
These files are stored in raw (binary) format for faster loading. To
-reveal the human-readable version, use ``named-compilezone``
+reveal the human-readable version, use :iscman:`named-compilezone`
as shown below. In the example below, we run the command on the
raw format zone ``example.com.db.signed`` to produce a text version of
the zone ``example.com.text``:
But how can you get each of the formats from your existing data?
-When ``named`` turned on automatic
+When :iscman:`named` turned on automatic
DNSSEC maintenance, essentially the first thing it did was to create
the DNSSEC keys and put them in the directory you specified in the
configuration file. If you look in that directory, you will see three
The policy has multiple parts:
- The name must be specified. As each zone can use a different policy,
- ``named`` needs to be able to distinguish between policies. This is
+ :iscman:`named` needs to be able to distinguish between policies. This is
done by giving each policy a name, such as ``standard`` in the above
example.
during the process.
Having defined a new policy called "standard", we now need to tell
-``named`` to use it. We do this by adding a ``dnssec-policy standard;``
+:iscman:`named` to use it. We do this by adding a ``dnssec-policy standard;``
statement to the configuration file. Like many other configuration
statements, it can be placed in the ``options`` statement (thus applying
to all zones on the server), a ``view`` statement (applying to all zones
...
};
-Finally, tell ``named`` to use the new policy:
+Finally, tell :iscman:`named` to use the new policy:
::
# rndc reconfig
-... and that's it. ``named`` now applies the "standard" policy to
+... and that's it. :iscman:`named` now applies the "standard" policy to
your zone.
.. _signing_maintenance_tasks:
both don't have the DS included yet the rollover is paused, and the check for
DS presence is retried after an hour. The same applies for DS withdrawal.
-Alternatively, you can use the ``rndc`` tool to tell ``named`` that the DS
+Alternatively, you can use the :iscman:`rndc` tool to tell :iscman:`named` that the DS
record has been published or withdrawn. For example:
::
If your parent zone doesn't support CDS/CDNSKEY, you will have to supply
the DNSKEY or DS record to the parent zone manually when a new KSK appears in
your zone, presumably using the same mechanism you used to upload the
-records for the first time. Again, you need to use the ``rndc`` tool
-to tell ``named`` that the DS record has been published.
+records for the first time. Again, you need to use the :iscman:`rndc` tool
+to tell :iscman:`named` that the DS record has been published.
.. [#]
For security reasons, a parent zone that supports CDS/CDNSKEY may require
"Manual" signing was the first method to be introduced into BIND and
its name describes it perfectly: the user needs to do everything. In the
more-automated methods, you load an unsigned zone file into
- ``named``, which takes care of signing it. With manual signing, you
- have to provide a signed zone for ``named`` to serve.
+ :iscman:`named`, which takes care of signing it. With manual signing, you
+ have to provide a signed zone for :iscman:`named` to serve.
In practice, this means creating an unsigned zone file as usual, then
- using the BIND-provided tools ``dnssec-keygen`` to create the keys
- and ``dnssec-signzone`` to sign the zone. The signed zone is stored
+ using the BIND-provided tools :iscman:`dnssec-keygen` to create the keys
+ and :iscman:`dnssec-signzone` to sign the zone. The signed zone is stored
in another file and is the one you tell BIND to load. To
update the zone (for example, to add a resource record), you update the
- unsigned zone, re-sign it, and tell ``named`` to load the updated
+ unsigned zone, re-sign it, and tell :iscman:`named` to load the updated
signed copy. The same goes for refreshing signatures or rolling keys;
the user is responsible for providing the signed zone served by
- ``named``. (In the case of rolling keys, you are also responsible for
+ :iscman:`named`. (In the case of rolling keys, you are also responsible for
ensuring that the keys are added and removed at the correct times.)
Why would you want to sign your zone this way? You probably
Semi-Automatic
The first step in DNSSEC automation came with BIND 9.7, when the
- ``auto-dnssec`` option was added. This causes ``named`` to
+ ``auto-dnssec`` option was added. This causes :iscman:`named` to
periodically search the directory holding the key files (see
:ref:`generate_keys` for a description) and to
use the information in them to both add and remove keys and sign the
Use of ``auto-dnssec`` alone requires that the zone be dynamic,
something not suitable for a number of situations, so BIND 9.9 added the
- ``inline-signing`` option. With this, ``named`` essentially keeps the
+ ``inline-signing`` option. With this, :iscman:`named` essentially keeps the
signed and unsigned copies of the zone separate. The signed zone is
created from the unsigned one using the key information; when the
- unsigned zone is updated and the zone reloaded, ``named`` detects the
+ unsigned zone is updated and the zone reloaded, :iscman:`named` detects the
changes and updates the signed copy of the zone.
This mode of signing has been termed "semi-automatic" in this
(probably via ``cron``). It reads a DNSSEC policy from its
configuration file and reads timing information from the DNSSEC key
files. With this information it creates new key files with timing
- information in them consistent with the policy. ``named`` is run as
+ information in them consistent with the policy. :iscman:`named` is run as
usual, picking up the timing information in the key files to
determine when to add and remove keys, and when to sign with them.
As noted above, the term semi-automatic signing has been used in this
document to indicate the mode of signing enabled by the ``auto-dnssec``
-and ``inline-signing`` keywords. ``named`` signs the zone without any
+and ``inline-signing`` keywords. :iscman:`named` signs the zone without any
manual intervention, based purely on the timing information in the
DNSSEC key files. The files, however, must be created manually.
The two files ending in ``.key`` are the public keys. These contain the
DNSKEY resource records that appear in the zone. The two files
ending in ``.private`` are the private keys, and contain the information
-that ``named`` actually uses to sign the zone.
+that :iscman:`named` actually uses to sign the zone.
Of the two pairs, one is the zone-signing key (ZSK), and one is the
key-signing key (KSK). We can tell which is which by looking at the file
our example, 8 means the algorithm RSASHA256. Finally, the "keyid" is
essentially a hash of the key itself.
-Make sure these files are readable by ``named`` and make sure that the
+Make sure these files are readable by :iscman:`named` and make sure that the
``.private`` files are not readable by anyone else.
Refer to :ref:`system_entropy` for information on how to
You may remember that in the above description of this method, we said
that time information related to rolling keys is stored in the key
-files. This is placed there by ``dnssec-keygen`` when the file is
-created, and it can be modified using ``dnssec-settime``. By default,
+files. This is placed there by :iscman:`dnssec-keygen` when the file is
+created, and it can be modified using :iscman:`dnssec-settime`. By default,
only a limited amount of timing information is included in the file, as
illustrated in the examples in the previous section.
All the dates are the same, and are the date and time that
-``dnssec-keygen`` created the key. We can use ``dnssec-settime`` to
+:iscman:`dnssec-keygen` created the key. We can use :iscman:`dnssec-settime` to
modify the dates [#]_. For example, to publish this key in
the zone on 1 July 2020, use it to sign records for a year starting on
15 July 2020, and remove it from the zone at the end of July 2021, we
copy of the new key in their cache before there are any resource
records signed with it. By default, if not specified at creation
time, this is set to the current time, meaning the key is
- published as soon as ``named`` picks it up.
+ published as soon as :iscman:`named` picks it up.
3. *Activate*: This sets the date on which the key is to be activated. After
that date, resource records are signed with the key. By default,
if not specified during creation time, this is set to the current
- time, meaning the key is used to sign data as soon as ``named``
+ time, meaning the key is used to sign data as soon as :iscman:`named`
picks it up.
4. *Revoke:* This sets the date on which the key is to be revoked. After that
After a specified period, BIND stops using it to sign records, and at some
other specified later time it is removed from the zone.
-Finally, we should note that the ``dnssec-keygen`` command supports the
+Finally, we should note that the :iscman:`dnssec-keygen` command supports the
same set of switches so we could have set the dates
when we created the key.
Having created the keys with the appropriate timing information, the
next step is to turn on DNSSEC signing. Below is a very simple
-``named.conf``; in our example environment, this file is
+:iscman:`named.conf`; in our example environment, this file is
``/etc/bind/named.conf``.
::
inline-signing yes;
};
-Once the configuration file is updated, tell ``named`` to
+Once the configuration file is updated, tell :iscman:`named` to
reload:
::
information for existing keys with the defined policy, and adjusts it if
necessary. It also creates additional keys as required.
-``dnssec-keymgr`` is completely separate from ``named``. As we will see,
+``dnssec-keymgr`` is completely separate from :iscman:`named`. As we will see,
the policy states a coverage period; ``dnssec-keymgr`` generates
enough key files to handle all rollovers in that period. However, it is
a good idea to schedule it to run on a regular basis; that way there is
keyttl 300;
};
-As can be seen, the syntax is similar to that of the ``named``
+As can be seen, the syntax is similar to that of the :iscman:`named`
configuration file.
In the example above, we define a DNSSEC policy called "standard". Keys
zone 30 days before it becomes active, and is retained in the zone for
30 days after it is rolled. ZSKs have a key size of 2048 bits and roll
every 90 days; like the KSKs, the are added to the zone 30 days before
-they are used for signing, and retained for 30 days after ``named``
+they are used for signing, and retained for 30 days after :iscman:`named`
ceases signing with them.
The policy is applied to two zones, ``example.com`` and ``example.net``.
setting for the DNSKEY TTL has been overridden and set to 300 seconds.
To apply the policy, we need to run ``dnssec-keymgr``. Since this does
-not read the ``named`` configuration file, it relies on the presence of
+not read the :iscman:`named` configuration file, it relies on the presence of
at least one key file for a zone to tell it that the zone is
DNSSEC-enabled. If a key file does not already exist, we first need to create
one for each zone. We can do that either by running
-``dnssec-keygen`` to create a key file for each zone [#]_, or by
+:iscman:`dnssec-keygen` to create a key file for each zone [#]_, or by
specifying the zones in question on the command line. Here, we do the
latter:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The latest development in DNSSEC key management appeared with BIND 9.16,
-and is the full integration of key management into ``named``. Managing
+and is the full integration of key management into :iscman:`named`. Managing
the signing process and rolling of these keys has been described in
:ref:`easy_start_guide_for_authoritative_servers` and is not
repeated here. A few points are worth noting, though:
-- The ``dnssec-policy`` statement in the ``named`` configuration file
+- The ``dnssec-policy`` statement in the :iscman:`named` configuration file
describes all aspects of the DNSSEC policy, including the signing.
With ``dnssec-keymgr``, this is split between two configuration files
and two programs.
The first step is to create the keys as described in :ref:`generate_keys`.
Then, edit the zone file to make sure
the proper DNSKEY entries are included in your zone file. Finally, use the
-command ``dnssec-signzone``:
+command :iscman:`dnssec-signzone`:
::
also generates a plain text file ``/etc/bind/db/example.com.signed.db``,
which you can verify for correctness.
-Finally, you'll need to update ``named.conf`` to load the signed version
+Finally, you'll need to update :iscman:`named.conf` to load the signed version
of the zone, which looks something like this:
::
};
Once the :option:`rndc reconfig` command is issued, BIND serves a signed
-zone. The file ``dsset-example.com`` (created by ``dnssec-signzone``
+zone. The file ``dsset-example.com`` (created by :iscman:`dnssec-signzone`
when it signed the ``example.com`` zone) contains the DS record for the
zone's KSK. You will need to pass that to the administrator of the parent
zone, to be placed in the zone.
.. [#]
The dates can also be modified using an editor, but that is likely to
- be more error-prone than using ``dnssec-settime``.
+ be more error-prone than using :iscman:`dnssec-settime`.
.. [#]
Only one key file - for either a KSK or ZSK - is needed to signal the
- presence of the zone. ``dnssec-keygen`` creates files of both
+ presence of the zone. :iscman:`dnssec-keygen` creates files of both
types as needed.
After determining the query path, it is necessary to
determine whether the problem is actually related to DNSSEC
-validation. You can use the ``+cd`` flag in ``dig`` to disable
+validation. You can use the ``+cd`` flag in :iscman:`dig` to disable
validation, as described in
:ref:`how_do_i_know_validation_problem`.
;; WHEN: Wed Mar 18 15:12:49 GMT 2020
;; MSG SIZE rcvd: 72
-With ``delv``, a "resolution failed" message is output instead:
+With :iscman:`delv`, a "resolution failed" message is output instead:
::
there's anything wrong. Since we are having trouble validating, we
can use the ``+cd`` option to temporarily disable checking and return
results, even though they do not pass the validation tests. The
-``+multiline`` option tells ``dig`` to print the type, algorithm type,
+``+multiline`` option tells :iscman:`dig` to print the type, algorithm type,
and key id for DNSKEY records. Again,
some long strings are shortened for ease of display:
^^^^^^^^^^^^^^^^^^^
This is a simple yet common issue. If the key files are present but
-unreadable by ``named`` for some reason, the ``syslog`` returns clear error
+unreadable by :iscman:`named` for some reason, the ``syslog`` returns clear error
messages, as shown below:
::
named[32516]: zone example.com/IN (signed): next key event: 27-Nov-2014 20:07:09.292
This happens to look exactly the same as if the keys were present and
-readable, and appears to indicate that ``named`` loaded the keys and signed the zone. It
+readable, and appears to indicate that :iscman:`named` loaded the keys and signed the zone. It
even generates the internal (raw) files:
::
# ls
example.com.db example.com.db.jbk example.com.db.signed
-If ``named`` really loaded the keys and signed the zone, you should see
+If :iscman:`named` really loaded the keys and signed the zone, you should see
the following files:
::
^^^^^^^^^^^^^^^^^^^^^
In most cases, you never need to explicitly configure trust
-anchors. ``named`` supplies the current root trust anchor and,
+anchors. :iscman:`named` supplies the current root trust anchor and,
with the default setting of ``dnssec-validation``, updates it on the
infrequent occasions when it is changed.
;; QUESTION SECTION:
;www.example.org. IN A
-``delv`` shows a similar result:
+:iscman:`delv` shows a similar result:
::
*temporarily* disable DNSSEC validation for a zone when you know that
the zone's DNSSEC is misconfigured.
-NTAs are added using the ``rndc`` command, e.g.:
+NTAs are added using the :iscman:`rndc` command, e.g.:
::
The list of currently configured NTAs can also be examined using
-``rndc``, e.g.:
+:iscman:`rndc`, e.g.:
::
polls the zone every five minutes to see if the zone correctly
validates, at which point the NTA automatically expires. Both the
default lifetime and the polling interval may be configured via
-``named.conf``, and the lifetime can be overridden on a per-zone basis
+:iscman:`named.conf`, and the lifetime can be overridden on a per-zone basis
using the ``-lifetime duration`` parameter to ``rndc nta``. Both timer
values have a permitted maximum value of one week.
NSEC3 Troubleshooting
~~~~~~~~~~~~~~~~~~~~~
-BIND includes a tool called ``nsec3hash`` that runs through the same
+BIND includes a tool called :iscman:`nsec3hash` that runs through the same
steps as a validating resolver, to generate the correct hashed name
based on NSEC3PARAM parameters. The command takes the following
parameters in order: salt, algorithm, iterations, and domain. For
...
};
-Restart ``named`` or run :option:`rndc reconfig`, and your recursive server is
+Restart :iscman:`named` or run :option:`rndc reconfig`, and your recursive server is
now happily validating each DNS response. If this does not work for you,
and you have already verified DNSSEC support as described in
:ref:`dnssec_support_in_bind`, you may have some other
.. _using_dig_to_verify:
-Using ``dig`` to Verify
-^^^^^^^^^^^^^^^^^^^^^^^
+Using :iscman:`dig` to Verify
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Web-based DNSSEC-verification tools often employ JavaScript. If you don't trust the
JavaScript magic that the web-based tools rely on, you can take matters
into your own hands and use a command-line DNS tool to check your
validating resolver yourself.
-While ``nslookup`` is popular, partly because it comes pre-installed on
-most systems, it is not DNSSEC-aware. ``dig``, on the other hand, fully
+While :iscman:`nslookup` is popular, partly because it comes pre-installed on
+most systems, it is not DNSSEC-aware. :iscman:`dig`, on the other hand, fully
supports the DNSSEC standard and comes as a part of BIND. If you do not
-have ``dig`` already installed on your system, install it by downloading
+have :iscman:`dig` already installed on your system, install it by downloading
it from ISC's `website <https://www.isc.org/download>`__. ISC provides pre-compiled
Windows versions on its website.
-``dig`` is a flexible tool for interrogating DNS name servers. It
+:iscman:`dig` is a flexible tool for interrogating DNS name servers. It
performs DNS lookups and displays the answers that are returned from the
name servers that were queried. Most seasoned DNS administrators use
-``dig`` to troubleshoot DNS problems because of its flexibility, ease of
+:iscman:`dig` to troubleshoot DNS problems because of its flexibility, ease of
use, and clarity of output.
-The example below shows how to use ``dig`` to query the name server 10.53.0.1
+The example below shows how to use :iscman:`dig` to query the name server 10.53.0.1
for the A record for ``ftp.isc.org`` when DNSSEC validation is enabled
(i.e. the default). The address 10.53.0.1 is only used as an example;
replace it with the actual address or host name of your
};
If the server is restarted (to ensure a clean cache) and the same
-``dig`` command executed, the result is very similar:
+:iscman:`dig` command executed, the result is very similar:
::
;; MSG SIZE rcvd: 187
However, this time there is no ``ad`` flag in the header. Although
-``dig`` is still returning the DNSSEC-related resource records, it is
+:iscman:`dig` is still returning the DNSSEC-related resource records, it is
not checking them, and thus cannot vouch for the authenticity of the answer.
If you do carry out this test, remember to re-enable DNSSEC validation
(by removing the ``dnssec-validation no;`` line from the configuration
Since all DNSSEC validation failures result in a general ``SERVFAIL``
message, how do we know if it was really a validation error?
-Fortunately, there is a flag in ``dig``, (``+cd``, for "checking
+Fortunately, there is a flag in :iscman:`dig`, (``+cd``, for "checking
disabled") which tells the server to disable DNSSEC validation. If
you receive a ``SERVFAIL`` message, re-run the query a second time
and set the ``+cd`` flag. If the query succeeds with ``+cd``, but
For many years, BIND has had EDNS enabled by default,
and the UDP packet size is set to a maximum of 4096 bytes. The DNS
administrator should not need to perform any reconfiguration. You can
-use ``dig`` to verify that your server supports EDNS and see the UDP packet
-size it allows with this ``dig`` command:
+use :iscman:`dig` to verify that your server supports EDNS and see the UDP packet
+size it allows with this :iscman:`dig` command:
::
\fBnamed.conf\fP
.SH DESCRIPTION
.sp
-\fBnamed.conf\fP is the configuration file for \fBnamed\fP\&. Statements are
+\fI\%named.conf\fP is the configuration file for \fBnamed\fP\&. Statements are
enclosed in braces and terminated with a semi\-colon. Clauses in the
statements are also semi\-colon terminated. The usual comment styles are
supported:
.B stop \-p
This command stops the server, making sure any recent changes made through dynamic
update or IXFR are first saved to the master files of the updated
-zones. If \fB\-p\fP is specified, \fBnamed(8)\(ga\(aqs process ID is returned.
-This allows an external process to determine when \(ga\(ganamed\fP has
+zones. If \fB\-p\fP is specified, \fBnamed\fP\(aqs process ID is returned.
+This allows an external process to determine when \fBnamed\fP has
completed stopping.
.sp
See also \fI\%rndc halt\fP\&.
- When a secondary server receives a large incremental zone transfer
(IXFR), it can have a negative impact on query performance while the
incremental changes are applied to the zone. To address this,
- ``named`` can now limit the size of IXFR responses it sends in
+ :iscman:`named` can now limit the size of IXFR responses it sends in
response to zone transfer requests. If an IXFR response would be
larger than an AXFR of the entire zone, it will send an AXFR response
instead.
~~~~~~~~~
- When an RPZ policy zone was updated via zone transfer and a large
- number of records was deleted, ``named`` could become nonresponsive
+ number of records was deleted, :iscman:`named` could become nonresponsive
for a short period while deleted names were removed from the RPZ
summary database. This database cleanup is now done incrementally
over a longer period of time, reducing such delays. :gl:`#1447`
New Features
~~~~~~~~~~~~
-- Support for DNS-over-HTTPS (DoH) was added to ``named``. Because of
+- Support for DNS-over-HTTPS (DoH) was added to :iscman:`named`. Because of
this, the ``nghttp2`` HTTP/2 library is now required for building the
development branch of BIND 9. Both TLS-encrypted and unencrypted
HTTP/2 connections are supported (the latter may be used to offload
encryption to other software).
Note that there is no client-side support for HTTPS as yet; this will
- be added to ``dig`` in a future release. :gl:`#1144`
+ be added to :iscman:`dig` in a future release. :gl:`#1144`
-- ``named`` now supports XFR-over-TLS (XoT) for incoming as well as
+- :iscman:`named` now supports XFR-over-TLS (XoT) for incoming as well as
outgoing zone transfers. Addresses in a ``primaries`` list can now be
accompanied by an optional ``tls`` keyword, followed by either the
name of a previously configured ``tls`` statement or ``ephemeral``.
:gl:`#2392`
- A new option, ``stale-answer-client-timeout``, has been added to
- improve ``named``'s behavior with respect to serving stale data. The
- option defines the amount of time ``named`` waits before attempting to
+ improve :iscman:`named`'s behavior with respect to serving stale data. The
+ option defines the amount of time :iscman:`named` waits before attempting to
answer the query with a stale RRset from cache. If a stale answer is
- found, ``named`` continues the ongoing fetches, attempting to refresh
+ found, :iscman:`named` continues the ongoing fetches, attempting to refresh
the RRset in cache until the ``resolver-query-timeout`` interval is
reached.
failure: ``acache-cleaning-interval``, ``acache-enable``,
``additional-from-auth``, ``additional-from-cache``,
``allow-v6-synthesis``, ``cleaning-interval``, ``dnssec-enable``,
- ``dnssec-lookaside``, ``filter-aaaa``, ``filter-aaaa-on-v4``,
+ ``dnssec-lookaside``, :iscman:`filter-aaaa`, ``filter-aaaa-on-v4``,
``filter-aaaa-on-v6``, ``geoip-use-ecs``, ``lwres``,
``max-acache-size``, ``nosit-udp-size``, ``queryport-pool-ports``,
``queryport-pool-updateinterval``, ``request-sit``, ``sit-secret``,
Feature Changes
~~~~~~~~~~~~~~~
-- When serve-stale is enabled and stale data is available, ``named`` now
+- When serve-stale is enabled and stale data is available, :iscman:`named` now
returns stale answers upon encountering any unexpected error in the
query resolution process. This may happen, for example, if the
``fetches-per-server`` or ``fetches-per-zone`` limits are reached. In
- this case, ``named`` attempts to answer DNS requests with stale data,
+ this case, :iscman:`named` attempts to answer DNS requests with stale data,
but does not start the ``stale-refresh-time`` window. :gl:`#2434`
- The default value of ``max-stale-ttl`` has been changed from 12 hours
Bug Fixes
~~~~~~~~~
-- ``named`` failed to start when its configuration included a zone with
+- :iscman:`named` failed to start when its configuration included a zone with
a non-builtin ``allow-update`` ACL attached. :gl:`#2413`
-- Previously, ``dnssec-keyfromlabel`` crashed when operating on an ECDSA
+- Previously, :iscman:`dnssec-keyfromlabel` crashed when operating on an ECDSA
key. This has been fixed. :gl:`#2178`
- KASP incorrectly set signature validity to the value of the DNSKEY
(Equation (2)). :gl:`#2375`
- Performance of the DNSSEC verification code (used by
- ``dnssec-signzone``, ``dnssec-verify``, and mirror zones) has been
+ :iscman:`dnssec-signzone`, :iscman:`dnssec-verify`, and mirror zones) has been
improved. :gl:`#2073`
New Features
~~~~~~~~~~~~
-- ``dig`` has been extended to support DNS-over-HTTPS (DoH) queries,
+- :iscman:`dig` has been extended to support DNS-over-HTTPS (DoH) queries,
using ``dig +https`` and related options. :gl:`#1641`
- A new ``purge-keys`` option has been added to ``dnssec-policy``. It
- ``http default`` can now be specified in ``listen-on`` and
``listen-on-v6`` statements to use the default HTTP endpoint of
``/dns-query``. It is no longer necessary to include an ``http``
- statement in ``named.conf`` unless overriding this value. :gl:`#2472`
+ statement in :iscman:`named.conf` unless overriding this value. :gl:`#2472`
Bug Fixes
~~~~~~~~~
-- Zone journal (``.jnl``) files created by versions of ``named`` prior
+- Zone journal (``.jnl``) files created by versions of :iscman:`named` prior
to 9.16.12 were no longer compatible; this could cause problems when
upgrading if journal files were not synchronized first. This has been
corrected: older journal files can now be read when starting up. When
an old-style journal file is detected, it is updated to the new format
immediately after loading.
- Note that journals created by the current version of ``named`` are not
+ Note that journals created by the current version of :iscman:`named` are not
usable by versions prior to 9.16.12. Before downgrading to a prior
release, users are advised to ensure that all dynamic zones have been
synchronized using :option:`rndc sync -clean <rndc sync>`.
A journal file's format can be changed manually by running
``named-journalprint -d`` (downgrade) or ``named-journalprint -u``
- (upgrade). Note that this *must not* be done while ``named`` is
+ (upgrade). Note that this *must not* be done while :iscman:`named` is
running. :gl:`#2505`
-- ``named`` crashed when it was allowed to serve stale answers and
+- :iscman:`named` crashed when it was allowed to serve stale answers and
``stale-answer-client-timeout`` was triggered without any (stale) data
available in the cache to answer the query. :gl:`#2503`
-- If an outgoing packet exceeded ``max-udp-size``, ``named`` dropped it
+- If an outgoing packet exceeded ``max-udp-size``, :iscman:`named` dropped it
instead of sending back a proper response. To prevent this problem,
the ``IP_DONTFRAG`` option is no longer set on UDP sockets, which has
been happening since BIND 9.17.6. :gl:`#2466`
using ``dnssec-policy`` with ``nsec3param``. This has been fixed.
:gl:`#2498`
-- A memory leak occurred when ``named`` was reconfigured after adding an
+- A memory leak occurred when :iscman:`named` was reconfigured after adding an
inline-signed zone with ``auto-dnssec maintain`` enabled. This has
been fixed. :gl:`#2041`
such a record was loaded. :gl:`#2499`
- If an invalid key name (e.g. ``a..b``) was specified in a
- ``primaries`` list in ``named.conf``, the wrong size was passed to
+ ``primaries`` list in :iscman:`named.conf`, the wrong size was passed to
``isc_mem_put()``, which resulted in the returned memory being put on
- the wrong free list and prevented ``named`` from starting up. This has
+ the wrong free list and prevented :iscman:`named` from starting up. This has
been fixed. :gl:`#2460`
- ``libtool`` was inadvertently introduced as a build-time requirement
~~~~~~~~~~~~~~
- A malformed incoming IXFR transfer could trigger an assertion failure
- in ``named``, causing it to quit abnormally. (CVE-2021-25214)
+ in :iscman:`named`, causing it to quit abnormally. (CVE-2021-25214)
ISC would like to thank Greg Kuechle of SaskTel for bringing this
vulnerability to our attention. :gl:`#2467`
-- ``named`` crashed when a DNAME record placed in the ANSWER section
+- :iscman:`named` crashed when a DNAME record placed in the ANSWER section
during DNAME chasing turned out to be the final answer to a client
query. (CVE-2021-25215)
has been fixed. :gl:`#2583`
- When ``stale-answer-client-timeout`` was set to a positive value and
- recursion for a client query completed when ``named`` was about to
+ recursion for a client query completed when :iscman:`named` was about to
look for a stale answer, an assertion could fail in
``query_respond()``, resulting in a crash. This has been fixed.
:gl:`#2594`
- After upgrading to the previous release, journal files for trust
anchor databases (e.g. ``managed-keys.bind.jnl``) could be left in a
corrupt state. (Other zone journal files were not affected.) This has
- been fixed. If a corrupt journal file is detected, ``named`` can now
+ been fixed. If a corrupt journal file is detected, :iscman:`named` can now
recover from it. :gl:`#2600`
-- When sending queries over TCP, ``dig`` now properly handles ``+tries=1
+- When sending queries over TCP, :iscman:`dig` now properly handles ``+tries=1
+retry=0`` by not retrying the connection when the remote server
closes the connection prematurely. :gl:`#2490`
- CDS/CDNSKEY DELETE records are now removed when a zone transitions
- from a secure to an insecure state. ``named-checkzone`` also no longer
+ from a secure to an insecure state. :iscman:`named-checkzone` also no longer
reports an error when such records are found in an unsigned zone.
:gl:`#2517`
:option:`rndc freeze`. This has been fixed. :gl:`#2523`
- After :option:`rndc dnssec -checkds <rndc dnssec>` or :option:`rndc dnssec -rollover <rndc dnssec>` is used,
- ``named`` now immediately attempts to reconfigure zone keys. This
+ :iscman:`named` now immediately attempts to reconfigure zone keys. This
change prevents unnecessary key rollover delays. :gl:`#2488`
-- ``named`` crashed after skipping a primary server while transferring a
+- :iscman:`named` crashed after skipping a primary server while transferring a
zone over TLS. This has been fixed. :gl:`#2562`
- The maximum supported number of NSEC3 iterations that can be
configured for a zone has been reduced to 150. :gl:`#2642`
-- After the network manager was introduced to ``named`` to handle
+- After the network manager was introduced to :iscman:`named` to handle
incoming traffic, it was discovered that recursive performance had
degraded compared to previous BIND 9 versions. This has now been
fixed by processing internal tasks inside network manager worker
itself was preserved. :gl:`#2623`
- It was possible for corrupt journal files generated by an earlier
- version of ``named`` to cause problems after an upgrade. This has been
+ version of :iscman:`named` to cause problems after an upgrade. This has been
fixed. :gl:`#2670`
- TTL values in cache dumps were reported incorrectly when
- ``inline-signing`` was incorrectly described as being inherited from
the ``options``/``view`` levels and was incorrectly accepted at those
- levels without effect. This has been fixed; ``named.conf`` files with
+ levels without effect. This has been fixed; :iscman:`named.conf` files with
``inline-signing`` at those levels no longer load. :gl:`#2536`
-- ``named`` and ``named-checkconf`` did not report an error when
+- :iscman:`named` and :iscman:`named-checkconf` did not report an error when
multiple zones with the ``dnssec-policy`` option set were using the
same zone file. This has been fixed. :gl:`#2603`
- If ``dnssec-policy`` was active and a private key file was temporarily
- offline during a rekey event, ``named`` could incorrectly introduce
+ offline during a rekey event, :iscman:`named` could incorrectly introduce
replacement keys and break a signed zone. This has been fixed.
:gl:`#2596`
Bug Fixes
~~~~~~~~~
-- When preparing DNS responses, ``named`` could replace the letters
+- When preparing DNS responses, :iscman:`named` could replace the letters
``W`` (uppercase) and ``w`` (lowercase) with ``\000``. This has been
fixed. :gl:`#2779`
- Sending DNS messages with the OPCODE field set to anything other than
QUERY (0) via DNS-over-TLS (DoT) or DNS-over-HTTPS (DoH) channels
- triggered an assertion failure in ``named``. This has been fixed.
+ triggered an assertion failure in :iscman:`named`. This has been fixed.
ISC would like to thank Ville Heikkila of Synopsys Cybersecurity
Research Center for bringing this vulnerability to our attention.
database of managed keys from subsequently being read back. This has
been fixed. :gl:`#2686`
-- Signed, insecure delegation responses prepared by ``named`` either
+- Signed, insecure delegation responses prepared by :iscman:`named` either
lacked the necessary NSEC records or contained duplicate NSEC records
when both wildcard expansion and CNAME chaining were required to
prepare the response. This has been fixed. :gl:`#2759`
-- If ``nsupdate`` sends an SOA request and receives a REFUSED response,
+- If :iscman:`nsupdate` sends an SOA request and receives a REFUSED response,
it now fails over to the next available server. :gl:`#2758`
- A bug that caused the NSEC3 salt to be changed on every restart for
Security Fixes
~~~~~~~~~~~~~~
-- Fixed an assertion failure that occurred in ``named`` when it
+- Fixed an assertion failure that occurred in :iscman:`named` when it
attempted to send a UDP packet that exceeded the MTU size, if
Response Rate Limiting (RRL) was enabled. (CVE-2021-25218) :gl:`#2856`
-- ``named`` failed to check the opcode of responses when performing zone
+- :iscman:`named` failed to check the opcode of responses when performing zone
refreshes, stub zone updates, and UPDATE forwarding. This could lead
to an assertion failure under certain conditions and has been
addressed by rejecting responses whose opcode does not match the
Feature Changes
~~~~~~~~~~~~~~~
-- Previously, ``named`` accepted FORMERR responses both with and without
+- Previously, :iscman:`named` accepted FORMERR responses both with and without
an OPT record, as an indication that a given server did not support
EDNS. To implement full compliance with :rfc:`6891`, only FORMERR
responses without an OPT record are now accepted. This intentionally
enabled by default. :gl:`#2433`
- Testing revealed that setting the thread affinity for various types of
- ``named`` threads led to inconsistent recursive performance, as
+ :iscman:`named` threads led to inconsistent recursive performance, as
sometimes multiple sets of threads competed over a single resource.
- Due to the above, ``named`` no longer sets thread affinity. This
+ Due to the above, :iscman:`named` no longer sets thread affinity. This
causes a slight dip of around 5% in authoritative performance, but
recursive performance is now consistently improved. :gl:`#2822`
Bug Fixes
~~~~~~~~~
-- Authentication of ``rndc`` messages could fail if a ``controls``
+- Authentication of :iscman:`rndc` messages could fail if a ``controls``
statement was configured with multiple key algorithms for the same
listener. This has been fixed. :gl:`#2756`
Feature Changes
~~~~~~~~~~~~~~~
-- When ``dnssec-signzone`` signs a zone using a successor key whose
+- When :iscman:`dnssec-signzone` signs a zone using a successor key whose
predecessor is still published, it now only refreshes signatures for
RRsets which have an invalid signature, an expired signature, or a
signature which expires within the provided cycle interval. This
- allows ``dnssec-signzone`` to gradually replace signatures in a zone
+ allows :iscman:`dnssec-signzone` to gradually replace signatures in a zone
whose ZSK is being rolled over (similarly to what ``auto-dnssec
maintain;`` does). :gl:`#1551`
-- ``dnssec-cds`` now only generates SHA-2 DS records by default and
+- :iscman:`dnssec-cds` now only generates SHA-2 DS records by default and
avoids copying deprecated SHA-1 records from a child zone to its
delegation in the parent. If the child zone does not publish SHA-2 CDS
- records, ``dnssec-cds`` will generate them from the CDNSKEY records.
+ records, :iscman:`dnssec-cds` will generate them from the CDNSKEY records.
The ``-a algorithm`` option now affects the process of generating DS
digest records from both CDS and CDNSKEY records. Thanks to Tony
Finch. :gl:`#2871`
- A recent change to the internal memory structure of zone databases
inadvertently neglected to update the MAPAPI value for zone files in
- ``map`` format. This caused version 9.17.17 of ``named`` to attempt to
+ ``map`` format. This caused version 9.17.17 of :iscman:`named` to attempt to
load files into memory that were no longer compatible, triggering an
assertion failure on startup. The MAPAPI value has now been updated,
- so ``named`` rejects outdated files when encountering them.
+ so :iscman:`named` rejects outdated files when encountering them.
:gl:`#2872`
- Zone files in ``map`` format whose size exceeded 2 GB failed to load.
This has been fixed. :gl:`#2878`
-- Stale data in the cache could cause ``named`` to send non-minimized
+- Stale data in the cache could cause :iscman:`named` to send non-minimized
queries despite QNAME minimization being enabled. This has been fixed.
:gl:`#2665`
Security Fixes
~~~~~~~~~~~~~~
-- The ``lame-ttl`` option controls how long ``named`` caches certain
+- The ``lame-ttl`` option controls how long :iscman:`named` caches certain
types of broken responses from authoritative servers (see the
`security advisory <https://kb.isc.org/docs/cve-2021-25219>`_ for
details). This caching mechanism could be abused by an attacker to
which is part of the `OpenSC`_ project. :gl:`#2691`
- Old-style Dynamically Loadable Zones (DLZ) drivers that had to be
- enabled in ``named`` at build time have been removed. New-style DLZ
+ enabled in :iscman:`named` at build time have been removed. New-style DLZ
modules should be used as a replacement. :gl:`#2814`
- Support for the ``map`` zone file format (``masterfile-format map;``)
has been removed. Users relying on the ``map`` format are advised to
- convert their zones to the ``raw`` format with ``named-compilezone``
+ convert their zones to the ``raw`` format with :iscman:`named-compilezone`
and change the configuration appropriately prior to upgrading BIND 9.
:gl:`#2882`
~~~~~~~~~~~~~~~
- The network manager API is now used for sending all outgoing DNS
- queries and requests from ``named`` and related tools, including
- ``delv``, ``mdig``, and ``nsupdate``. :gl:`#2401`
+ queries and requests from :iscman:`named` and related tools, including
+ :iscman:`delv`, :iscman:`mdig`, and :iscman:`nsupdate`. :gl:`#2401`
-- ``named`` and ``named-checkconf`` now exit with an error when a single
+- :iscman:`named` and :iscman:`named-checkconf` now exit with an error when a single
port configured for ``query-source``, ``transfer-source``,
``notify-source``, ``parental-source``, and/or their respective IPv6
counterparts clashes with a global listening port. This configuration
until now (even though sending UDP messages such as NOTIFY failed).
:gl:`#2888`
-- ``named`` and ``named-checkconf`` now issue a warning when there is a
+- :iscman:`named` and :iscman:`named-checkconf` now issue a warning when there is a
single port configured for ``query-source``, ``transfer-source``,
``notify-source``, ``parental-source``, and/or for their respective
IPv6 counterparts. :gl:`#2888`
again. :gl:`#2911`
- When new IP addresses were set up by the operating system during
- ``named`` startup, it could fail to listen for TCP connections on the
+ :iscman:`named` startup, it could fail to listen for TCP connections on the
newly added interfaces. :gl:`#2852`
- Under specific circumstances, zone transfers over TCP and TLS could be
Docs`_. Release notes are no longer available as a separate document
accompanying a release. :gl:`#83`
-- ``named`` and ``named-checkzone`` now reject master zones that have a
+- :iscman:`named` and :iscman:`named-checkzone` now reject master zones that have a
DS RRset at the zone apex. Attempts to add DS records at the zone
apex via UPDATE will be logged but otherwise ignored. DS records
belong in the parent zone, not at the zone apex. :gl:`#1798`
particular type that can be added to a domain name via dynamic
update. :gl:`#1657`
-- ``dig`` and other tools can now print the Extended DNS Error (EDE)
+- :iscman:`dig` and other tools can now print the Extended DNS Error (EDE)
option when it appears in a request or a response. :gl:`#1835`
- ``dig +qid=<num>`` allows the user to specify a particular query ID
~~~~~~~~~~~~~~~
- The default value of ``max-stale-ttl`` has changed from 1 week to 12
- hours. This option controls how long ``named`` retains expired RRsets
+ hours. This option controls how long :iscman:`named` retains expired RRsets
in cache as a potential mitigation mechanism, should there be a
problem with one or more domains. Note that cache content retention
is independent of whether stale answers are used in response to
.. warning::
This change may be significant for administrators who expect that
stale cache content will be automatically retained for up to 1
- week. Add option ``max-stale-ttl 1w;`` to ``named.conf`` to keep
- the previous behavior of ``named``.
+ week. Add option ``max-stale-ttl 1w;`` to :iscman:`named.conf` to keep
+ the previous behavior of :iscman:`named`.
- BIND 9 no longer sets receive/send buffer sizes for UDP sockets,
relying on system defaults instead. :gl:`#1713`
BIND 9 rwlock implementation. :gl:`#1753`
- BIND 9 binaries which are neither daemons nor administrative programs
- were moved to ``$bindir``. Only ``ddns-confgen``, ``named``,
- ``rndc``, ``rndc-confgen``, and ``tsig-confgen`` were left in
+ were moved to ``$bindir``. Only :iscman:`ddns-confgen`, :iscman:`named`,
+ :iscman:`rndc`, :iscman:`rndc-confgen`, and ``tsig-confgen`` were left in
``$sbindir``. :gl:`#1724`
- ``listen-on-v6 { any; }`` creates a separate socket for each
processing step that was causing this delay has now been removed.
:gl:`#1834`
-- ``named`` could crash with an assertion failure if the name of a
+- :iscman:`named` could crash with an assertion failure if the name of a
database node was looked up while the database was being modified.
:gl:`#1857`
- When running on a system with support for Linux capabilities,
- ``named`` drops root privileges very soon after system startup. This
+ :iscman:`named` drops root privileges very soon after system startup. This
was causing a spurious log message, ``unable to set effective uid to
0: Operation not permitted``, which has now been silenced.
:gl:`#1042` :gl:`#1090`
- A possible deadlock in ``lib/isc/unix/socket.c`` was fixed.
:gl:`#1859`
-- Previously, ``named`` did not destroy some mutexes and conditional
+- Previously, :iscman:`named` did not destroy some mutexes and conditional
variables in netmgr code, which caused a memory leak on FreeBSD. This
has been fixed. :gl:`#1893`
``server-addresses`` statements due to an uninitialized DSCP value.
This has been fixed. :gl:`#1812`
-- When built without LMDB support, ``named`` failed to restart after a
+- When built without LMDB support, :iscman:`named` failed to restart after a
zone with a double quote (") in its name was added with ``rndc
addzone``. Thanks to Alberto Fernández. :gl:`#1695`
- The `UseSTD3ASCIIRules`_ flag is now set for libidn2 function calls.
This enables additional validation rules for IDN domains and hostnames
- in ``dig``. :gl:`#1610`
+ in :iscman:`dig`. :gl:`#1610`
.. _UseSTD3ASCIIRules: http://www.unicode.org/reports/tr46/#UseSTD3ASCIIRules
~~~~~~~~~
- Reloading a catalog zone which referenced a missing/deleted member
- zone triggered a runtime check failure, causing ``named`` to exit
+ zone triggered a runtime check failure, causing :iscman:`named` to exit
prematurely. This has been fixed. :gl:`#2308`
- Some lame delegations could trigger a dependency loop, in which a
- The `UseSTD3ASCIIRules`_ flag is now disabled again for libidn2
function calls. Applying additional validation rules for domain names
- in ``dig`` (a change introduced in the previous BIND 9 release) caused
+ in :iscman:`dig` (a change introduced in the previous BIND 9 release) caused
characters which are disallowed in hostnames (e.g. underscore ``_``,
wildcard ``*``) to be silently stripped. That change was reverted.
:gl:`#1610`
following triggering events: ``socket is not connected``, ``quota
reached``, and ``soft quota reached``. :gl:`#2700`
-- ``dnssec-dsfromkey`` no longer generates DS records from revoked keys.
+- :iscman:`dnssec-dsfromkey` no longer generates DS records from revoked keys.
:gl:`#853`
.. _UseSTD3ASCIIRules: http://www.unicode.org/reports/tr46/#UseSTD3ASCIIRules
- Removing a configured ``catalog-zone`` clause from the configuration,
running :option:`rndc reconfig`, then bringing back the removed
``catalog-zone`` clause and running :option:`rndc reconfig` again caused
- ``named`` to crash. This has been fixed. :gl:`#1608`
+ :iscman:`named` to crash. This has been fixed. :gl:`#1608`
- The resolver could hang on shutdown due to dispatch resources not
being cleaned up when a TCP connection was reset, or due to dependency
New Features
~~~~~~~~~~~~
-- ``named`` now logs TLS pre-master secrets for debugging purposes when
+- :iscman:`named` now logs TLS pre-master secrets for debugging purposes when
the ``SSLKEYLOGFILE`` environment variable is set. This enables
troubleshooting issues with encrypted DNS traffic. :gl:`#2723`
Feature Changes
~~~~~~~~~~~~~~~
-- Overall memory use by ``named`` has been optimized and reduced,
+- Overall memory use by :iscman:`named` has been optimized and reduced,
especially on systems with many CPU cores. :gl:`#2398` :gl:`#3048`
-- ``named`` formerly generated an ephemeral key and certificate for the
+- :iscman:`named` formerly generated an ephemeral key and certificate for the
``tls ephemeral`` configuration using the RSA algorithm with 4096-bit
keys. This has been changed to the ECDSA P-256 algorithm. :gl:`#2264`
- Under certain circumstances, the signed version of an inline-signed
zone could be dumped to disk without the serial number of the unsigned
version of the zone. This prevented resynchronization of the zone
- contents after ``named`` restarted, if the unsigned zone file was
- modified while ``named`` was not running. This has been fixed.
+ contents after :iscman:`named` restarted, if the unsigned zone file was
+ modified while :iscman:`named` was not running. This has been fixed.
:gl:`#3071`
New Features
~~~~~~~~~~~~
-- New ``rndc`` command :option:`rndc dnssec -status <rndc dnssec>` shows the current DNSSEC
+- New :iscman:`rndc` command :option:`rndc dnssec -status <rndc dnssec>` shows the current DNSSEC
policy and keys in use, the key states, and rollover status.
:gl:`#1612`
- As part of an ongoing effort to use :rfc:`8499` terminology,
``primaries`` can now be used as a synonym for ``masters`` in
- ``named.conf``. Similarly, ``notify primary-only`` can now be used as
+ :iscman:`named.conf`. Similarly, ``notify primary-only`` can now be used as
a synonym for ``notify master-only``. The output of ``rndc
zonestatus`` now uses ``primary`` and ``secondary`` terminology.
:gl:`#1948`
~~~~~~~~~
- A race condition could occur if a TCP socket connection was closed
- while ``named`` was waiting for a recursive response. The attempt to
+ while :iscman:`named` was waiting for a recursive response. The attempt to
send a response over the closing connection triggered an assertion
failure in the function ``isc__nm_tcpdns_send()``. :gl:`#1937`
-- A race condition could occur when ``named`` attempted to use a UDP
+- A race condition could occur when :iscman:`named` attempted to use a UDP
interface that was shutting down. This triggered an assertion failure
in ``uv__udp_finish_close()``. :gl:`#1938`
- Fix assertion failure when server was under load and root zone had not
yet been loaded. :gl:`#1862`
-- ``named`` could crash when cleaning dead nodes in ``lib/dns/rbtdb.c``
+- :iscman:`named` could crash when cleaning dead nodes in ``lib/dns/rbtdb.c``
that were being reused. :gl:`#1968`
-- ``named`` crashed on shutdown when a new ``rndc`` connection was
+- :iscman:`named` crashed on shutdown when a new :iscman:`rndc` connection was
received during shutdown. This has been fixed. :gl:`#1747`
- The DS RRset returned by ``dns_keynode_dsset()`` was used in a
ISC would like to thank Emanuel Almeida of Cisco Systems, Inc. for
bringing this vulnerability to our attention. :gl:`#1996`
-- ``named`` could crash after failing an assertion check in certain
+- :iscman:`named` could crash after failing an assertion check in certain
query resolution scenarios where QNAME minimization and forwarding
were both enabled. To prevent such crashes, QNAME minimization is now
always disabled for a given query resolution process, if forwarders
- A new configuration option ``stale-cache-enable`` has been introduced
to enable or disable keeping stale answers in cache. :gl:`#1712`
-- ``rndc`` has been updated to use the new BIND network manager API.
+- :iscman:`rndc` has been updated to use the new BIND network manager API.
This change had the side effect of altering the TCP timeout for RNDC
connections from 60 seconds to the ``tcp-idle-timeout`` value, which
defaults to 30 seconds. Also, because the network manager currently
has no support for UNIX-domain sockets, those cannot now be used
- with ``rndc``. This will be addressed in a future release, either by
+ with :iscman:`rndc`. This will be addressed in a future release, either by
restoring UNIX-domain socket support or by formally declaring them
to be obsolete in the control channel. :gl:`#1759`
``response-policy`` statement. This has been fixed. :gl:`#1619`
- The IPv6 Duplicate Address Detection (DAD) mechanism could
- inadvertently prevent ``named`` from binding to new IPv6 interfaces,
+ inadvertently prevent :iscman:`named` from binding to new IPv6 interfaces,
by causing multiple route socket messages to be sent for each IPv6
- address. ``named`` monitors for new interfaces to ``bind()`` to when
+ address. :iscman:`named` monitors for new interfaces to ``bind()`` to when
it is configured to listen on ``any`` or on a specific range of
addresses. New IPv6 interfaces can be in a "tentative" state before
they are fully available for use. When DAD is in use, two messages are
emitted by the route socket: one when the interface first appears and
- then a second one when it is fully "up." An attempt by ``named`` to
+ then a second one when it is fully "up." An attempt by :iscman:`named` to
``bind()`` to the new interface prematurely would fail, causing it
thereafter to ignore that address/interface. The problem was worked
around by setting the ``IP_FREEBIND`` option on the socket and trying
New Features
~~~~~~~~~~~~
-- Add a new ``rndc`` command, :option:`rndc dnssec -checkds <rndc dnssec>`, which signals to
- ``named`` that a DS record for a given zone or key has been published
+- Add a new :iscman:`rndc` command, :option:`rndc dnssec -checkds <rndc dnssec>`, which signals to
+ :iscman:`named` that a DS record for a given zone or key has been published
or withdrawn from the parent. This command replaces the time-based
``parent-registration-delay`` configuration option. :gl:`#1613`
-- Log when ``named`` adds a CDS/CDNSKEY to the zone. :gl:`#1748`
+- Log when :iscman:`named` adds a CDS/CDNSKEY to the zone. :gl:`#1748`
Removed Features
~~~~~~~~~~~~~~~~
Bug Fixes
~~~~~~~~~
-- In rare circumstances, ``named`` would exit with an assertion failure
+- In rare circumstances, :iscman:`named` would exit with an assertion failure
when the number of nodes stored in the red-black tree exceeded the
maximum allowed size of the internal hash table. :gl:`#2104`
resulted in a generic protocol error being returned instead of a more
specific error code. :gl:`#1928`
-- With query name minimization enabled, ``named`` failed to resolve
+- With query name minimization enabled, :iscman:`named` failed to resolve
``ip6.arpa.`` names that had extra labels to the left of the IPv6
- part. For example, when ``named`` attempted query name minimization on
+ part. For example, when :iscman:`named` attempted query name minimization on
a name like ``A.B.1.2.3.4.(...).ip6.arpa.``, it stopped at the
leftmost IPv6 label, i.e. ``1.2.3.4.(...).ip6.arpa.``, without
considering the extra labels (``A.B``). That caused a query loop when
- resolving the name: if ``named`` received NXDOMAIN answers, then the
+ resolving the name: if :iscman:`named` received NXDOMAIN answers, then the
same query was repeatedly sent until the number of queries sent
reached the value of the ``max-recursion-queries`` configuration
option. :gl:`#1847`
New Features
~~~~~~~~~~~~
-- Add a new ``rndc`` command, :option:`rndc dnssec -rollover <rndc dnssec>`, which triggers
+- Add a new :iscman:`rndc` command, :option:`rndc dnssec -rollover <rndc dnssec>`, which triggers
a manual rollover for a specific key. :gl:`#1749`
-- Add a new ``rndc`` command, :option:`rndc dumpdb -expired <rndc dumpdb>`, which dumps the
+- Add a new :iscman:`rndc` command, :option:`rndc dumpdb -expired <rndc dumpdb>`, which dumps the
cache database, including expired RRsets that are awaiting cleanup, to
the ``dump-file`` for diagnostic purposes. :gl:`#1870`
- DNS Flag Day 2020: The default EDNS buffer size has been changed from
4096 to 1232 bytes, the EDNS buffer size probing has been removed, and
- ``named`` now sets the DF (Don't Fragment) flag on outgoing UDP
+ :iscman:`named` now sets the DF (Don't Fragment) flag on outgoing UDP
packets. According to measurements done by multiple parties, this
should not cause any operational problems as most of the Internet
"core" is able to cope with IP message sizes between 1400-1500 bytes;
Bug Fixes
~~~~~~~~~
-- ``named`` reported an invalid memory size when running in an
+- :iscman:`named` reported an invalid memory size when running in an
environment that did not properly report the number of available
memory pages and/or the size of each memory page. :gl:`#2166`
-- With multiple forwarders configured, ``named`` could fail the
+- With multiple forwarders configured, :iscman:`named` could fail the
``REQUIRE(msg->state == (-1))`` assertion in ``lib/dns/message.c``,
causing it to crash. This has been fixed. :gl:`#2124`
-- ``named`` erroneously performed continuous key rollovers for KASP
+- :iscman:`named` erroneously performed continuous key rollovers for KASP
policies that used algorithm Ed25519 or Ed448 due to a mismatch
between created key size and expected key size. :gl:`#2171`
New Features
~~~~~~~~~~~~
-- Support for DNS over TLS (DoT) has been added: the ``dig`` tool is now
- able to send DoT queries (``+tls`` option) and ``named`` can handle
- DoT queries (``listen-on tls ...`` option). ``named`` can use either a
+- Support for DNS over TLS (DoT) has been added: the :iscman:`dig` tool is now
+ able to send DoT queries (``+tls`` option) and :iscman:`named` can handle
+ DoT queries (``listen-on tls ...`` option). :iscman:`named` can use either a
certificate provided by the user or an ephemeral certificate generated
automatically upon startup. :gl:`#1840`
Feature Changes
~~~~~~~~~~~~~~~
-- The ``dig``, ``host``, and ``nslookup`` tools have been converted to
+- The :iscman:`dig`, :iscman:`host`, and :iscman:`nslookup` tools have been converted to
use the new network manager API rather than the older ISC socket API.
As a side effect of this change, the ``dig +unexpected`` option no
longer works. This could previously be used to diagnose broken servers
or network configurations by listening for replies from servers other
than the one that was queried. With the new API, such answers are
- filtered before they ever reach ``dig``, so the option has been
+ filtered before they ever reach :iscman:`dig`, so the option has been
removed. :gl:`#2140`
-- The network manager API is now used by ``named`` to send zone transfer
+- The network manager API is now used by :iscman:`named` to send zone transfer
requests. :gl:`#2016`
Bug Fixes
~~~~~~~~~
-- ``named`` could crash with an assertion failure if a TCP connection
+- :iscman:`named` could crash with an assertion failure if a TCP connection
were closed while a request was still being processed. :gl:`#2227`
-- ``named`` acting as a resolver could incorrectly treat signed zones
+- :iscman:`named` acting as a resolver could incorrectly treat signed zones
with no DS record at the parent as bogus. Such zones should be treated
as insecure. This has been fixed. :gl:`#2236`
NSEC3 salt collisions are automatically prevented during resalting.
:gl:`#1620`
-- ``dig`` output now includes the transport protocol used (UDP, TCP, or
+- :iscman:`dig` output now includes the transport protocol used (UDP, TCP, or
TLS). :gl:`#1816`
-- ``dig`` can now report the DNS64 prefixes in use (``+dns64prefix``).
- This is useful when the host on which ``dig`` is run is behind an
+- :iscman:`dig` can now report the DNS64 prefixes in use (``+dns64prefix``).
+ This is useful when the host on which :iscman:`dig` is run is behind an
IPv6-only link, using DNS64/NAT64 or 464XLAT for IPv4aaS (IPv4 as a
Service). :gl:`#1154`
- Earlier releases of BIND versions 9.16 and newer required the
operating system to support load-balanced sockets in order for
- ``named`` to be able to achieve high performance (by distributing
+ :iscman:`named` to be able to achieve high performance (by distributing
incoming queries among multiple threads). However, the only operating
systems currently known to support load-balanced sockets are Linux and
FreeBSD 12, which means both UDP and TCP performance were limited to a
- single thread on other systems. As of BIND 9.17.8, ``named`` attempts
+ single thread on other systems. As of BIND 9.17.8, :iscman:`named` attempts
to distribute incoming queries among multiple threads on systems which
lack support for load-balanced sockets (except Windows). :gl:`#2137`
described in :rfc:`8078`. :gl:`#1750`
- When using the ``unixtime`` or ``date`` method to update the SOA
- serial number, ``named`` and ``dnssec-signzone`` silently fell back to
+ serial number, :iscman:`named` and :iscman:`dnssec-signzone` silently fell back to
the ``increment`` method to prevent the new serial number from being
smaller than the old serial number (using serial number arithmetics).
- ``dnssec-signzone`` now prints a warning message, and ``named`` logs a
+ :iscman:`dnssec-signzone` now prints a warning message, and :iscman:`named` logs a
warning, when such a fallback happens. :gl:`#2058`
Bug Fixes
the same time, resulting in an unpredictable but low-probability
assertion failure in ``free_rbtdb()``. This has been fixed. :gl:`#2317`
-- ``named`` no longer attempts to assign threads to CPUs outside the CPU
+- :iscman:`named` no longer attempts to assign threads to CPUs outside the CPU
affinity set. Thanks to Ole Bjørn Hessen. :gl:`#2245`
-- When reconfiguring ``named``, removing ``auto-dnssec`` did not turn
+- When reconfiguring :iscman:`named`, removing ``auto-dnssec`` did not turn
off DNSSEC maintenance. This has been fixed. :gl:`#2341`
- The report of intermittent BIND assertion failures triggered in
``lib/dns/resolver.c:dns_name_issubdomain()`` has now been closed
without further action. Our initial response to this was to add
- diagnostic logging instead of terminating ``named``, anticipating that
+ diagnostic logging instead of terminating :iscman:`named`, anticipating that
we would receive further useful troubleshooting input. This workaround
first appeared in BIND releases 9.17.5 and 9.16.7. However, since
those releases were published, there have been no new reports of
New Features
~~~~~~~~~~~~
-- ``dnssec-verify`` and ``dnssec-signzone`` now accept a ``-J`` option to
+- :iscman:`dnssec-verify` and :iscman:`dnssec-signzone` now accept a ``-J`` option to
specify a journal file to read when loading the zone to be verified or
signed. :gl:`#2486`
~~~~~~~~~~~~~~~~
- The IPv6 sockets are now explicitly restricted to sending and receiving IPv6
- packets only. This renders the ``dig`` option ``+mapped`` non-functioning and
+ packets only. This renders the :iscman:`dig` option ``+mapped`` non-functioning and
thus the option has been removed. :gl:`#3093`
- The ``keep-order-response`` option has been declared obsolete and the
- functionality has been removed. ``named`` expects DNS clients to be
+ functionality has been removed. :iscman:`named` expects DNS clients to be
fully compliant with :rfc:`7766`. :gl:`#3140`
Feature Changes
Bug Fixes
~~~~~~~~~
-- With libuv >= 1.37.0, the recvmmsg support would not be enabled in ``named``
+- With libuv >= 1.37.0, the recvmmsg support would not be enabled in :iscman:`named`
reducing the maximum query-response performance. The recvmmsg support would
be used only in libuv 1.35.0 and 1.36.0. This has been fixed. :gl:`#3095`
change in the previous release. This has been fixed. :gl:`#3111`
- An error in the processing of the ``blackhole`` ACL could cause some DNS
- requests sent by ``named`` to fail - for example, zone transfer requests
+ requests sent by :iscman:`named` to fail - for example, zone transfer requests
and SOA refresh queries - if the destination address or prefix was
specifically excluded from the ACL using ``!``, or if the ACL was set
to ``none``. ``blackhole`` worked correctly when it was left unset, or
projects / thirdparty / bind9.git / commitdiff
