``acl`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: acl
+
.. include:: ../misc/acl.grammar.rst
.. _acl:
``controls`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: controls
.. include:: ../misc/controls.grammar.rst
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
-``ip_port`` on the specified ``ip_addr``, which can be an IPv4 or IPv6
-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 :iscman:`rndc` is only used on the local host,
-using the loopback address (``127.0.0.1`` or ``::1``) is recommended for
-maximum security.
-
-If no port is specified, port 953 is used. The asterisk ``*`` cannot
-be used for ``ip_port``.
-
-The ability to issue commands over the control channel is restricted by
-the ``allow`` and ``keys`` clauses. Connections to the control channel
-are permitted based on the ``address_match_list``. This is for simple IP
-address-based filtering only; any ``key_id`` elements of the
-``address_match_list`` are ignored.
-
-A ``unix`` control channel is a Unix domain socket listening at the
-specified path in the file system. Access to the socket is specified by
-the ``perm``, ``owner``, and ``group`` clauses. Note that on some platforms
-(SunOS and Solaris), the permissions (``perm``) are applied to the parent
-directory as the permissions on the socket itself are ignored.
-
-The primary authorization mechanism of the command channel is the
-``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 :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``,
-``status``, ``showzone``, ``testgen``, and ``zonestatus``. By default,
-``read-only`` is not enabled and the control channel allows read-write
-access.
+.. namedconf:statement:: unix
+
+ A ``unix`` control channel is a Unix domain socket listening at the
+ specified path in the file system. Access to the socket is specified by
+ the ``perm``, ``owner``, and ``group`` clauses. Note that on some platforms
+ (SunOS and Solaris), the permissions (``perm``) are applied to the parent
+ directory as the permissions on the socket itself are ignored.
+
+
+.. namedconf:statement:: inet
+
+ An ``inet`` control channel is a TCP socket listening at the specified
+ ``ip_port`` on the specified ``ip_addr``, which can be an IPv4 or IPv6
+ 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 :iscman:`rndc` is only used on the local host,
+ using the loopback address (``127.0.0.1`` or ``::1``) is recommended for
+ maximum security.
+
+ If no port is specified, port 953 is used. The asterisk ``*`` cannot
+ be used for ``ip_port``.
+
+ The ability to issue commands over the control channel is restricted by
+ the ``allow`` and ``keys`` clauses.
+
+ .. namedconf:statement:: allow
+
+ Connections to the control channel
+ are permitted based on the ``address_match_list``. This is for simple IP
+ address-based filtering only; any ``key_id`` elements of the
+ ``address_match_list`` are ignored.
+
+.. namedconf:statement:: keys
+
+ The primary authorization mechanism of the command channel is the
+ ``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 :iscman:`rndc`.
+
+.. namedconf:statement:: read-only
+
+ If the ``read-only`` clause is enabled, the control channel is limited
+ to the following set of read-only commands: ``nta -dump``, ``null``,
+ ``status``, ``showzone``, ``testgen``, and ``zonestatus``. By default,
+ ``read-only`` is not enabled and the control channel allows read-write
+ access.
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
``key`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: key
.. include:: ../misc/key.grammar.rst
match lists to verify that incoming requests have been signed with a key
matching this name, algorithm, and secret.
-The ``algorithm_id`` is a string that specifies a security/authentication
-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.,
-``hmac-sha1-80``. The ``secret_string`` is the secret to be used by the
-algorithm, and is treated as a Base64-encoded string.
+.. namedconf:statement:: algorithm
+
+ The ``algorithm_id`` is a string that specifies a security/authentication
+ 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.,
+ ``hmac-sha1-80``.
+
+.. namedconf:statement:: secret
+
+ The ``secret_string`` is the secret to be used by the
+ algorithm, and is treated as a Base64-encoded string.
.. _logging_grammar:
``logging`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: logging
.. include:: ../misc/logging.grammar.rst
The ``channel`` Phrase
^^^^^^^^^^^^^^^^^^^^^^
+.. namedconf:statement:: channel
All log output goes to one or more ``channels``; there is no limit to
the number of channels that can be created.
: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
-to be discarded; in that case, other options for the channel are
-meaningless.
-
-The ``file`` destination clause directs the channel to a disk file. It
-can include additional arguments to specify how large the file is
-allowed to become before it is rolled to a backup file (``size``), how
-many backup versions of the file are saved each time this happens
-(``versions``), and the format to use for naming backup versions
-(``suffix``).
-
-The ``size`` option is used to limit log file growth. If the file ever
-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
-some out-of-band mechanism removes or truncates the log to less than the
-maximum size. The default behavior is not to limit the size of the file.
-
-File rolling only occurs when the file exceeds the size specified with
-the ``size`` option. No backup versions are kept by default; any
-existing log file is simply appended. The ``versions`` option specifies
-how many backup versions of the file should be kept. If set to
-``unlimited``, there is no limit.
-
-The ``suffix`` option can be set to either ``increment`` or
-``timestamp``. If set to ``timestamp``, then when a log file is rolled,
-it is saved with the current timestamp as a file suffix. If set to
-``increment``, then backup files are saved with incrementing numbers as
-suffixes; older files are renamed when rolling. For example, if
-``versions`` is set to 3 and ``suffix`` to ``increment``, then when
-``filename.log`` reaches the size specified by ``size``,
-``filename.log.1`` is renamed to ``filename.log.2``, ``filename.log.0``
-is renamed to ``filename.log.1``, and ``filename.log`` is renamed to
-``filename.log.0``, whereupon a new ``filename.log`` is opened.
-
-Here is an example using the ``size``, ``versions``, and ``suffix`` options:
+.. namedconf:statement:: null
+
+ The ``null`` destination clause causes all messages sent to the channel
+ to be discarded; in that case, other options for the channel are
+ meaningless.
+
+.. namedconf:statement:: file
+
+ The ``file`` destination clause directs the channel to a disk file. It
+ can include additional arguments to specify how large the file is
+ allowed to become before it is rolled to a backup file (``size``), how
+ many backup versions of the file are saved each time this happens
+ (``versions``), and the format to use for naming backup versions
+ (``suffix``).
+
+ The ``size`` option is used to limit log file growth. If the file ever
+ 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
+ some out-of-band mechanism removes or truncates the log to less than the
+ maximum size. The default behavior is not to limit the size of the file.
+
+ File rolling only occurs when the file exceeds the size specified with
+ the ``size`` option. No backup versions are kept by default; any
+ existing log file is simply appended. The ``versions`` option specifies
+ how many backup versions of the file should be kept. If set to
+ ``unlimited``, there is no limit.
+
+ The ``suffix`` option can be set to either ``increment`` or
+ ``timestamp``. If set to ``timestamp``, then when a log file is rolled,
+ it is saved with the current timestamp as a file suffix. If set to
+ ``increment``, then backup files are saved with incrementing numbers as
+ suffixes; older files are renamed when rolling. For example, if
+ ``versions`` is set to 3 and ``suffix`` to ``increment``, then when
+ ``filename.log`` reaches the size specified by ``size``,
+ ``filename.log.1`` is renamed to ``filename.log.2``, ``filename.log.0``
+ is renamed to ``filename.log.1``, and ``filename.log`` is renamed to
+ ``filename.log.0``, whereupon a new ``filename.log`` is opened.
+
+ Here is an example using the ``size``, ``versions``, and ``suffix`` options:
-::
+ ::
- channel an_example_channel {
- file "example.log" versions 3 size 20m suffix increment;
- print-time yes;
- print-category yes;
- };
+ channel an_example_channel {
+ file "example.log" versions 3 size 20m suffix increment;
+ print-time yes;
+ print-category yes;
+ };
+
+.. namedconf:statement:: syslog
-The ``syslog`` destination clause directs the channel to the system log.
-Its argument is a syslog facility as described in the ``syslog`` man
-page. Known facilities are ``kern``, ``user``, ``mail``, ``daemon``,
-``auth``, ``syslog``, ``lpr``, ``news``, ``uucp``, ``cron``,
-``authpriv``, ``ftp``, ``local0``, ``local1``, ``local2``, ``local3``,
-``local4``, ``local5``, ``local6``, and ``local7``; however, not all
-facilities are supported on all operating systems. How ``syslog``
-handles messages sent to this facility is described in the
-``syslog.conf`` man page. On a system which uses a very old
-version of ``syslog``, which only uses two arguments to the ``openlog()``
-function, this clause is silently ignored.
+ The ``syslog`` destination clause directs the channel to the system log.
+ Its argument is a syslog facility as described in the ``syslog`` man
+ page. Known facilities are ``kern``, ``user``, ``mail``, ``daemon``,
+ ``auth``, ``syslog``, ``lpr``, ``news``, ``uucp``, ``cron``,
+ ``authpriv``, ``ftp``, ``local0``, ``local1``, ``local2``, ``local3``,
+ ``local4``, ``local5``, ``local6``, and ``local7``; however, not all
+ facilities are supported on all operating systems. How ``syslog``
+ handles messages sent to this facility is described in the
+ ``syslog.conf`` man page. On a system which uses a very old
+ version of ``syslog``, which only uses two arguments to the ``openlog()``
+ function, this clause is silently ignored.
.. _severity:
-The ``severity`` clause works like ``syslog``'s "priorities," except
-that they can also be used when writing straight to a file rather
-than using ``syslog``. Messages which are not at least of the severity
-level given are not selected for the channel; messages of higher
-severity levels are accepted.
-
-When using ``syslog``, the ``syslog.conf`` priorities
-also determine what eventually passes through. For example, defining a
-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 :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
-standard error stream. This is intended for use when the server is
-running as a foreground process, as when debugging a
-configuration, for example.
+.. namedconf:statement:: severity
+
+ The ``severity`` clause works like ``syslog``'s "priorities," except
+ that they can also be used when writing straight to a file rather
+ than using ``syslog``. Messages which are not at least of the severity
+ level given are not selected for the channel; messages of higher
+ severity levels are accepted.
+
+ When using ``syslog``, the ``syslog.conf`` priorities
+ also determine what eventually passes through. For example, defining a
+ 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 :iscman:`named` writing messages of only ``warning`` or higher,
+ then ``syslogd`` would print all messages it received from the channel.
+
+.. namedconf:statement:: stderr
+
+ The ``stderr`` destination clause directs the channel to the server's
+ standard error stream. This is intended for use when the server is
+ running as a foreground process, as when debugging a
+ configuration, for example.
The server can supply extensive debugging information when it is in
debugging mode. If the server's global debug level is greater than zero,
``dynamic`` severity use the server's global debug level to determine
what messages to print.
-``print-time`` can be set to ``yes``, ``no``, or a time format
-specifier, which may be one of ``local``, ``iso8601``, or
-``iso8601-utc``. If set to ``no``, the date and time are not
-logged. If set to ``yes`` or ``local``, the date and time are logged in
-a human-readable format, using the local time zone. If set to
-``iso8601``, the local time is logged in ISO 8601 format. If set to
-``iso8601-utc``, the date and time are logged in ISO 8601 format,
-with time zone set to UTC. The default is ``no``.
-
-``print-time`` may be specified for a ``syslog`` channel, but it is
-usually pointless since ``syslog`` also logs the date and time.
-
-If ``print-category`` is requested, then the category of the message
-is logged as well. Finally, if ``print-severity`` is on, then the
-severity level of the message is logged. The ``print-`` options may
-be used in any combination, and are always printed in the following
-order: time, category, severity. Here is an example where all three
-``print-`` options are on:
+.. namedconf:statement:: print-time
+
+ ``print-time`` can be set to ``yes``, ``no``, or a time format
+ Specifier, which may be one of ``local``, ``iso8601``, or
+ ``iso8601-utc``. If set to ``no``, the date and time are not
+ Logged. If set to ``yes`` or ``local``, the date and time are logged in
+ A human-readable format, using the local time zone. If set to
+ ``iso8601``, the local time is logged in ISO 8601 format. If set to
+ ``iso8601-utc``, the date and time are logged in ISO 8601 format,
+ With time zone set to UTC. The default is ``no``.
+
+ ``print-time`` may be specified for a ``syslog`` channel, but it is
+ Usually pointless since ``syslog`` also logs the date and time.
+
+.. namedconf:statement:: print-category
+
+ If ``print-category`` is requested, then the category of the message
+ is logged as well.
+
+.. namedconf:statement:: print-severity
+
+ If ``print-severity`` is on, then the
+ severity level of the message is logged. The ``print-`` options may
+ be used in any combination, and are always printed in the following
+ order: time, category, severity.
+
+Here is an example where all three ``print-`` options are on:
``28-Feb-2000 15:05:32.863 general: notice: running``
-If ``buffered`` has been turned on, the output to files is not
-flushed after each log entry. By default all log messages are flushed.
+.. namedconf:statement:: buffered
+
+ 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 :iscman:`named`'s default
logging, as follows. If :iscman:`named` is started with the :option:`-L <named -L>` option, then a fifth
The ``category`` Phrase
^^^^^^^^^^^^^^^^^^^^^^^
-
There are many categories, so desired logs can be sent anywhere
while unwanted logs are ignored. If
a list of channels is not specified for a category, log messages in that
default_debug;
};
+
+.. namedconf:statement:: null
+
To discard all messages in a category, specify the ``null`` channel:
::
category xfer-out { null; };
category notify { null; };
+.. namedconf:statement:: category
+
The following are the available categories and brief descriptions of the
types of log information they contain. More categories may be added in
future BIND releases.
``parental-agents`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: parental-agents
.. include:: ../misc/parental-agents.grammar.rst
``primaries`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: primaries
.. include:: ../misc/primaries.grammar.rst
``options`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: options
This is the grammar of the ``options`` statement in the :iscman:`named.conf`
file:
.. _attach-cache:
-``attach-cache``
+.. namedconf:statement:: attach-cache
+
This option allows multiple views to share a single cache database. Each view has
its own cache database by default, but if multiple views have the
same operational policy for name resolution and caching, those views
.. _directory:
-``directory``
+.. namedconf:statement:: directory
+
This sets the working directory of the server. Any non-absolute pathnames in
the configuration file are taken as relative to this directory.
The default location for most server output files (e.g.,
before any other directive (like ``include``) that can work with relative
files. The safest way to include files is to use absolute file names.
-``dnstap``
+.. namedconf:statement:: dnstap
+
``dnstap`` is a fast, flexible method for capturing and logging DNS
traffic. Developed by Robert Edmonds at Farsight Security, Inc., and
supported by multiple DNS implementations, ``dnstap`` uses
: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
+ .. namedconf:statement:: fstrm-set-buffer-hint
+
+ The threshold number of bytes to
accumulate in the output buffer before forcing a buffer flush. The
minimum is 1024, the maximum is 65536, and the default is 8192.
- - ``fstrm-set-flush-timeout``: The number of seconds to allow
+ .. namedconf:statement:: fstrm-set-flush-timeout
+
+ The number of seconds to allow
unflushed data to remain in the output buffer. The minimum is 1
second, the maximum is 600 seconds (10 minutes), and the default
is 1 second.
- - ``fstrm-set-output-notify-threshold``: The number of outstanding
+ .. namedconf:statement:: fstrm-set-output-notify-threshold
+
+ The number of outstanding
queue entries to allow on an input queue before waking the I/O
thread. The minimum is 1 and the default is 32.
- - ``fstrm-set-output-queue-model``: The queuing semantics
+ .. namedconf:statement:: fstrm-set-output-queue-model
+
+ The queuing semantics
to use for queue objects. The default is ``mpsc`` (multiple
producer, single consumer); the other option is ``spsc`` (single
producer, single consumer).
- - ``fstrm-set-input-queue-size``: The number of queue entries to
+ .. namedconf:statement:: fstrm-set-input-queue-size
+
+ The number of queue entries to
allocate for each input queue. This value must be a power of 2.
The minimum is 2, the maximum is 16384, and the default is 512.
- - ``fstrm-set-output-queue-size``: The number of queue entries to
+ .. namedconf:statement:: fstrm-set-output-queue-size
+
+ The number of queue entries to
allocate for each output queue. The minimum is 2, the maximum is
system-dependent and based on ``IOV_MAX``, and the default is 64.
- - ``fstrm-set-reopen-interval``: The number of seconds to wait
+ .. namedconf:statement:: fstrm-set-reopen-interval
+
+ The number of seconds to wait
between attempts to reopen a closed output stream. The minimum is
1 second, the maximum is 600 seconds (10 minutes), and the default
is 5 seconds. For convenience, TTL-style time-unit suffixes may be
future versions of the library. See the ``libfstrm`` documentation
for more information.
-``dnstap-output``
+.. namedconf:statement:: dnstap-output
+
This configures the path to which the ``dnstap`` frame stream is sent
if ``dnstap`` is enabled at compile time and active.
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``
+.. namedconf:statement:: dnstap-identity
+
This specifies an ``identity`` string to send in ``dnstap`` messages. If
set to ``hostname``, which is the default, the server's hostname
is sent. If set to ``none``, no identity string is sent.
-``dnstap-version``
+.. namedconf:statement:: dnstap-version
+
This specifies a ``version`` string to send in ``dnstap`` messages. The
default is the version number of the BIND release. If set to
``none``, no version string is sent.
-``geoip-directory``
+.. namedconf:statement:: geoip-directory
+
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;
default ``geoip-directory`` is ``/usr/local/share/GeoIP``. See :ref:`acl`
for details about ``geoip`` ACLs.
-``key-directory``
+.. namedconf:statement:: key-directory
+
This is the directory where the public and private DNSSEC key files should be
found when performing a dynamic update of secure zones, if different
than the current working directory. (Note that this option has no
effect on the paths for files containing non-DNSSEC keys such as
``bind.keys``, ``rndc.key``, or ``session.key``.)
-``lmdb-mapsize``
+.. namedconf:statement:: lmdb-mapsize
+
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
without elaborate ACLs, a 32 MB NZD file ought to be able to hold
configurations of about 100,000 zones.
-``managed-keys-directory``
+.. namedconf:statement:: managed-keys-directory
+
This specifies the directory in which to store the files that track managed DNSSEC
keys (i.e., those configured using the ``initial-key`` or ``initial-ds``
keywords in a ``trust-anchors`` statement). By default, this is the working
if a file using the old name format is found to exist, it is
used instead of the new format.)
-``max-ixfr-ratio``
+.. namedconf:statement:: max-ixfr-ratio
+
This sets the size threshold (expressed as a percentage of the size
of the full zone) beyond which :iscman:`named` chooses to use an AXFR
response rather than IXFR when answering zone transfer requests. See
The minimum value is ``1%``. The keyword ``unlimited`` disables ratio
checking and allows IXFRs of any size. The default is ``100%``.
-``new-zones-directory``
+.. namedconf:statement:: new-zones-directory
+
This specifies the directory in which to store the configuration
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 :iscman:`named` process.
-``qname-minimization``
+.. namedconf:statement:: qname-minimization
+
This option controls QNAME minimization behavior in the BIND
resolver. When set to ``strict``, BIND follows the QNAME
minimization algorithm to the letter, as specified in :rfc:`7816`.
minimization completely. The current default is ``relaxed``, but it
may be changed to ``strict`` in a future release.
-``tkey-gssapi-keytab``
+.. namedconf:statement:: tkey-gssapi-keytab
+
This is the KRB5 keytab file to use for GSS-TSIG updates. If this option is
set and tkey-gssapi-credential is not set, updates are
allowed with any key matching a principal in the specified keytab.
-``tkey-gssapi-credential``
+.. namedconf:statement:: tkey-gssapi-credential
+
This is the security credential with which the server should authenticate
keys requested by the GSS-TSIG protocol. Currently only Kerberos 5
authentication is available; the credential is a Kerberos
GSS-TSIG, ``tkey-domain`` must also be set if a specific keytab is
not set with ``tkey-gssapi-keytab``.
-``tkey-domain``
+.. namedconf:statement:: tkey-domain
+
This domain is appended to the names of all shared keys generated with
``TKEY``. When a client requests a ``TKEY`` exchange, it may or may
not specify the desired name for the key. If present, the name of the
this variable must be defined, unless a specific keytab
is specified using ``tkey-gssapi-keytab``.
-``tkey-dhkey``
+.. namedconf:statement:: tkey-dhkey
+
This is the Diffie-Hellman key used by the server to generate shared keys
with clients using the Diffie-Hellman mode of ``TKEY``. The server
must be able to load the public and private keys from files in the
working directory. In most cases, the ``key_name`` should be the
server's host name.
-``dump-file``
+.. namedconf:statement:: dump-file
+
This is the pathname of the file the server dumps the database to, when
instructed to do so with :option:`rndc dumpdb`. If not specified, the
default is ``named_dump.db``.
-``memstatistics-file``
+.. namedconf:statement:: memstatistics-file
+
This is the pathname of the file the server writes memory usage statistics to
on exit. If not specified, the default is ``named.memstats``.
-``lock-file``
+.. namedconf:statement:: lock-file
+
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
:iscman:`named` is being reloaded or reconfigured; it is only effective
when the server is first started.
-``pid-file``
+.. namedconf:statement:: pid-file
+
This is the pathname of the file the server writes its process ID in. If not
specified, the default is |named_pid|. The PID file
is used by programs that send signals to the running name
that ``none`` is a keyword, not a filename, and therefore is not
enclosed in double quotes.
-``recursing-file``
+.. namedconf:statement:: recursing-file
+
This is the pathname of the file where the server dumps the queries that are
currently recursing, when instructed to do so with :option:`rndc recursing`.
If not specified, the default is ``named.recursing``.
-``statistics-file``
+.. namedconf:statement:: statistics-file
+
This is the pathname of the file the server appends statistics to, when
instructed to do so using :option:`rndc stats`. If not specified, the
default is ``named.stats`` in the server's current directory. The
format of the file is described in :ref:`statsfile`.
-``bindkeys-file``
+.. namedconf:statement:: bindkeys-file
+
This is the pathname of a file to override the built-in trusted keys provided
by :iscman:`named`. See the discussion of ``dnssec-validation`` for
details. If not specified, the default is |bind_keys|.
-``secroots-file``
+.. namedconf:statement:: secroots-file
+
This is the pathname of the file the server dumps security roots to, when
instructed to do so with :option:`rndc secroots`. If not specified, the
default is ``named.secroots``.
-``session-keyfile``
+.. namedconf:statement:: session-keyfile
+
This is the pathname of the file into which to write a TSIG session key
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.)
-``session-keyname``
+.. namedconf:statement:: session-keyname
+
This is the key name to use for the TSIG session key. If not specified, the
default is ``local-ddns``.
-``session-keyalg``
+.. namedconf:statement:: session-keyalg
+
This is the algorithm to use for the TSIG session key. Valid values are
hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, hmac-sha512, and
hmac-md5. If not specified, the default is hmac-sha256.
-``port``
+.. namedconf:statement:: port
+
This is the UDP/TCP port number the server uses to receive and send DNS
protocol traffic. The default is 53. This option is mainly intended
for server testing; a server using a port other than 53 is not
able to communicate with the global DNS.
-``tls-port``
+.. namedconf:statement:: tls-port
+
This is the TCP port number the server uses to receive and send
DNS-over-TLS protocol traffic. The default is 853.
-``https-port``
+.. namedconf:statement:: https-port
+
This is the TCP port number the server uses to receive and send
DNS-over-HTTPS protocol traffic. The default is 443.
-``http-port``
+.. namedconf:statement:: http-port
+
This is the TCP port number the server uses to receive and send
unencrypted DNS traffic via HTTP (a configuration that may be useful
when encryption is handled by third-party software or by a reverse
proxy).
-``http-listener-clients``
+.. namedconf:statement:: http-listener-clients
+
This sets the hard quota on the number of active concurrent connections
on a per-listener basis. The default value is 300; setting it to 0
removes the quota.
-``http-streams-per-connection``
+.. namedconf:statement:: http-streams-per-connection
+
This sets the hard limit on the number of active concurrent HTTP/2
streams on a per-connection basis. The default value is 100;
setting it to 0 removes the limit. Once the limit is exceeded, the
server finishes the HTTP session.
-``dscp``
+.. namedconf:statement:: dscp
+
This is the global Differentiated Services Code Point (DSCP) value to
classify outgoing DNS traffic, on operating systems that support DSCP.
Valid values are 0 through 63. It is not configured by default.
-``random-device``
+.. namedconf:statement:: random-device
+
This specifies a source of entropy to be used by the server; it is a
device or file from which to read entropy. If it is a file,
operations requiring entropy will fail when the file has been
configuration load at server startup time and is ignored on
subsequent reloads.
-``preferred-glue``
+.. namedconf:statement:: preferred-glue
+
If specified, the listed type (A or AAAA) is emitted before
other glue in the additional section of a query response. The default
is to prefer A records when responding to queries that arrived via
.. _root-delegation-only:
-``root-delegation-only``
+.. namedconf:statement:: root-delegation-only
+
This turns on enforcement of delegation-only in TLDs (top-level domains)
and root zones with an optional exclude list.
root-delegation-only exclude { "de"; "lv"; "us"; "museum"; };
};
-``disable-algorithms``
+.. namedconf:statement:: disable-algorithms
+
This disables the specified DNSSEC algorithms at and below the specified
name. Multiple ``disable-algorithms`` statements are allowed. Only
the best-match ``disable-algorithms`` clause is used to
``trusted-keys``) that match a disabled algorithm are ignored and treated
as if they were not configured.
-``disable-ds-digests``
+.. namedconf:statement:: disable-ds-digests
+
This disables the specified DS digest types at and below the specified
name. Multiple ``disable-ds-digests`` statements are allowed. Only
the best-match ``disable-ds-digests`` clause is used to
If all supported digest types are disabled, the zones covered by
``disable-ds-digests`` are treated as insecure.
-``dnssec-must-be-secure``
+.. namedconf:statement:: dnssec-must-be-secure
+
This specifies hierarchies which must be or may not be secure (signed and
validated). If ``yes``, then :iscman:`named` only accepts answers if
they are secure. If ``no``, then normal DNSSEC validation applies,
must be defined as a trust anchor, for instance in a ``trust-anchors``
statement, or ``dnssec-validation auto`` must be active.
-``dns64``
+.. namedconf:statement:: dns64
+
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
In addition, a reverse IP6.ARPA zone is created for the prefix
to provide a mapping from the IP6.ARPA names to the corresponding
- IN-ADDR.ARPA names using synthesized CNAMEs. ``dns64-server`` and
- ``dns64-contact`` can be used to specify the name of the server and
- contact for the zones. These can be set at the view/options
- level but not on a per-prefix basis.
-
- ``dns64`` will also cause IPV4ONLY.ARPA to be created if not
- explicitly disabled using ``ipv4only-enable``.
-
- Each ``dns64`` supports an optional ``clients`` ACL that determines
- which clients are affected by this directive. If not defined, it
- defaults to ``any;``.
-
- Each ``dns64`` supports an optional ``mapped`` ACL that selects which
- IPv4 addresses are to be mapped in the corresponding A RRset. If not
- defined, it defaults to ``any;``.
-
- Normally, DNS64 does not apply to a domain name that owns one or more
- AAAA records; these records are simply returned. The optional
- ``exclude`` ACL allows specification of a list of IPv6 addresses that
- are ignored if they appear in a domain name's AAAA records;
- DNS64 is applied to any A records the domain name owns. If not
- defined, ``exclude`` defaults to ::ffff:0.0.0.0/96.
-
- An optional ``suffix`` can also be defined to set the bits trailing
- the mapped IPv4 address bits. By default these bits are set to
- ``::``. The bits matching the prefix and mapped IPv4 address must be
- zero.
-
- If ``recursive-only`` is set to ``yes``, the DNS64 synthesis only
- happens for recursive queries. The default is ``no``.
-
- If ``break-dnssec`` is set to ``yes``, the DNS64 synthesis happens
- even if the result, if validated, would cause a DNSSEC validation
- failure. If this option is set to ``no`` (the default), the DO is set
- on the incoming query, and there are RRSIGs on the applicable
- records, then synthesis does not happen.
+ IN-ADDR.ARPA names using synthesized CNAMEs.
+
+ .. namedconf:statement:: dns64-server
+ .. namedconf:statement:: dns64-contact
+
+ ``dns64-server`` and
+ ``dns64-contact`` can be used to specify the name of the server and
+ contact for the zones. These can be set at the view/options
+ level but not on a per-prefix basis.
+
+ ``dns64`` will also cause IPV4ONLY.ARPA to be created if not
+ explicitly disabled using ``ipv4only-enable``.
+
+ .. namedconf:statement:: clients
+
+ Each ``dns64`` supports an optional ``clients`` ACL that determines
+ which clients are affected by this directive. If not defined, it
+ defaults to ``any;``.
+
+ .. namedconf:statement:: mapped
+
+ Each ``dns64`` supports an optional ``mapped`` ACL that selects which
+ IPv4 addresses are to be mapped in the corresponding A RRset. If not
+ defined, it defaults to ``any;``.
+
+ .. namedconf:statement:: exclude
+
+ Normally, DNS64 does not apply to a domain name that owns one or more
+ AAAA records; these records are simply returned. The optional
+ ``exclude`` ACL allows specification of a list of IPv6 addresses that
+ are ignored if they appear in a domain name's AAAA records;
+ DNS64 is applied to any A records the domain name owns. If not
+ defined, ``exclude`` defaults to ::ffff:0.0.0.0/96.
+
+ .. namedconf:statement:: suffix
+
+ An optional ``suffix`` can also be defined to set the bits trailing
+ the mapped IPv4 address bits. By default these bits are set to
+ ``::``. The bits matching the prefix and mapped IPv4 address must be
+ zero.
+
+ .. namedconf:statement:: recursive-only
+
+ If ``recursive-only`` is set to ``yes``, the DNS64 synthesis only
+ happens for recursive queries. The default is ``no``.
+
+ .. namedconf:statement:: break-dnssec
+
+ If ``break-dnssec`` is set to ``yes``, the DNS64 synthesis happens
+ even if the result, if validated, would cause a DNSSEC validation
+ failure. If this option is set to ``no`` (the default), the DO is set
+ on the incoming query, and there are RRSIGs on the applicable
+ records, then synthesis does not happen.
::
suffix ::;
};
-``dnssec-loadkeys-interval``
+.. namedconf:statement:: dnssec-loadkeys-interval
+
When a zone is configured with ``auto-dnssec maintain;``, its key
repository must be checked periodically to see if any new keys have
been added or any existing keys' timing metadata has been updated
the maximum is ``1440`` (24 hours); any higher value is silently
reduced.
-``dnssec-policy``
+.. namedconf:statement:: dnssec-policy
+
This specifies which key and signing policy (KASP) should be used for this
zone. This is a string referring to a ``dnssec-policy`` statement. There
are three built-in policies: ``default``, which uses the default policy,
``none``, which means no DNSSEC policy. The default is ``none``.
See :ref:`dnssec-policy Grammar <dnssec_policy_grammar>` for more details.
-``dnssec-update-mode``
+.. namedconf:statement:: 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 :iscman:`named` has access
automatic signing and allow DNSSEC data to be submitted into a zone
via dynamic update; this is not yet implemented.)
-``nta-lifetime``
+.. namedconf:statement:: nta-lifetime
+
This specifies the default lifetime, in seconds, for
negative trust anchors added via :option:`rndc nta`.
``nta-lifetime`` defaults to one hour; it cannot exceed one week.
-``nta-recheck``
+.. namedconf:statement:: nta-recheck
+
This specifies how often to check whether negative trust anchors added via
:option:`rndc nta` are still necessary.
The default is five minutes. It cannot be longer than ``nta-lifetime``, which
cannot be longer than a week.
-``max-zone-ttl``
+.. namedconf:statement:: max-zone-ttl
+
This specifies a maximum permissible TTL value in seconds. For
convenience, TTL-style time-unit suffixes may be used to specify the
maximum value. When loading a zone file using a ``masterfile-format``
The default value is ``unlimited``. A ``max-zone-ttl`` of zero is
treated as ``unlimited``.
-``stale-answer-ttl``
+.. namedconf:statement:: stale-answer-ttl
+
This specifies the TTL to be returned on stale answers. The default is 30
seconds. The minimum allowed is 1 second; a value of 0 is updated silently
to 1 second.
configuration file using ``stale-answer-enable`` or via
:option:`rndc serve-stale on <rndc serve-stale>`.
-``serial-update-method``
+.. namedconf:statement:: serial-update-method
+
Zones configured for dynamic DNS may use this option to set the
update method to be used for the zone serial number in the SOA
record.
zeroes, unless the existing serial number is already greater than or
equal to that value, in which case it is incremented by one.
-``zone-statistics``
+.. namedconf:statement:: zone-statistics
+
If ``full``, the server collects statistical data on all zones,
unless specifically turned off on a per-zone basis by specifying
``zone-statistics terse`` or ``zone-statistics none`` in the ``zone``
Boolean Options
^^^^^^^^^^^^^^^
-``automatic-interface-scan``
+.. namedconf:statement:: automatic-interface-scan
+
If ``yes`` and supported by the operating system, this automatically rescans
network interfaces when the interface addresses are added or removed. The
default is ``yes``. This configuration option does not affect the time-based
network interface discovery; therefore, the operating system must
support the routing sockets for this feature to work.
-``allow-new-zones``
+.. namedconf:statement:: allow-new-zones
+
If ``yes``, then zones can be added at runtime via :option:`rndc addzone`.
The default is ``no``.
whether :iscman:`named` was linked with liblmdb at compile time. See
:ref:`man_rndc` for further details about :option:`rndc addzone`.
-``auth-nxdomain``
+.. namedconf:statement:: auth-nxdomain
+
If ``yes``, then the ``AA`` bit is always set on NXDOMAIN responses,
even if the server is not actually authoritative. The default is
``no``.
-``memstatistics``
+.. namedconf:statement:: memstatistics
+
This writes memory statistics to the file specified by
``memstatistics-file`` at exit. The default is ``no`` unless :option:`-m
record <named -m>` is specified on the command line, in which case it is ``yes``.
-``dialup``
+.. namedconf:statement:: dialup
+
If ``yes``, then the server treats all zones as if they are doing
zone transfers across a dial-on-demand dialup link, which can be
brought up by traffic originating from this server. Although this setting has
Note that normal NOTIFY processing is not affected by ``dialup``.
-``flush-zones-on-shutdown``
+.. namedconf:statement:: flush-zones-on-shutdown
+
When the name server exits upon receiving SIGTERM, flush or do not
flush any pending zone writes. The default is
``flush-zones-on-shutdown no``.
-``root-key-sentinel``
+.. namedconf:statement:: root-key-sentinel
+
If ``yes``, respond to root key sentinel probes as described in
draft-ietf-dnsop-kskroll-sentinel-08. The default is ``yes``.
-``reuseport``
+.. namedconf:statement:: reuseport
+
This option enables kernel load-balancing of sockets on systems which support
it, including Linux (SO_REUSEPORT) and FreeBSD (SO_REUSEPORT_LB). This
instructs the kernel to distribute incoming socket connections among the
Changes will not take effect during reconfiguration; the server
must be restarted.
-``message-compression``
+.. namedconf:statement:: message-compression
+
If ``yes``, DNS name compression is used in responses to regular
queries (not including AXFR or IXFR, which always use compression).
Setting this option to ``no`` reduces CPU usage on servers and may
compression disabled is out of compliance with :rfc:`1123` Section
6.1.3.2. The default is ``yes``.
-``minimal-responses``
+.. namedconf:statement:: minimal-responses
+
This option controls the addition of records to the authority and
additional sections of responses. Such records may be included in
responses to be helpful to clients; for example, NS or MX records may
The default is ``no-auth-recursive``.
-``glue-cache``
+.. namedconf:statement:: glue-cache
+
When set to ``yes``, a cache is used to improve query performance
when adding address-type (A and AAAA) glue records to the additional
section of DNS response messages that delegate to a child zone.
.. note:: This option is deprecated and its use is discouraged. The
glue cache will be permanently *enabled* in a future release.
-``minimal-any``
+.. namedconf:statement:: minimal-any
+
If set to ``yes``, the server replies with only one of
the RRsets for the query name, and its covering RRSIGs if any,
when generating a positive response to a query of type ANY over UDP,
.. _notify_st:
-``notify``
+.. namedconf:statement:: notify
+
If set to ``yes`` (the default), DNS NOTIFY messages are sent when a
zone the server is authoritative for changes; see :ref:`using notify<notify>`.
The messages are sent to the servers listed in the zone's NS records
statement. It would only be necessary to turn off this option if it
caused secondary zones to crash.
-``notify-to-soa``
+.. namedconf:statement:: notify-to-soa
+
If ``yes``, do not check the name servers in the NS RRset against the
SOA MNAME. Normally a NOTIFY message is not sent to the SOA MNAME
(SOA ORIGIN), as it is supposed to contain the name of the ultimate
.. _recursion:
-``recursion``
+.. namedconf:statement:: recursion
+
If ``yes``, and a DNS query requests recursion, then the server
attempts to do all the work required to answer the query. If recursion
is off and the server does not already know the answer, it
effect of client queries. Caching may still occur as an effect of the
server's internal operation, such as NOTIFY address lookups.
-``request-nsid``
+.. namedconf:statement:: request-nsid
+
If ``yes``, then an empty EDNS(0) NSID (Name Server Identifier)
option is sent with all queries to authoritative name servers during
iterative resolution. If the authoritative server returns an NSID
option in its response, then its contents are logged in the ``nsid``
category at level ``info``. The default is ``no``.
-``require-server-cookie``
+.. namedconf:statement:: require-server-cookie
+
If ``yes``, require a valid server cookie before sending a full response to a UDP
request from a cookie-aware client. BADCOOKIE is sent if there is a
bad or nonexistent server cookie.
response, while also requiring a legitimate client to follow up with a second
query with the new, valid, cookie.
-``answer-cookie``
+.. namedconf:statement:: answer-cookie
+
When set to the default value of ``yes``, COOKIE EDNS options are
sent when applicable in replies to client queries. If set to ``no``,
COOKIE EDNS options are not sent in replies. This can only be set
security mechanism, and should not be disabled unless absolutely
necessary.
-``send-cookie``
+.. namedconf:statement:: send-cookie
+
If ``yes``, then a COOKIE EDNS option is sent along with the query.
If the resolver has previously communicated with the server, the COOKIE
returned in the previous transaction is sent. This is used by the
The default is ``yes``.
-``stale-answer-enable``
+.. namedconf:statement:: stale-answer-enable
+
If ``yes``, enable the returning of "stale" cached answers when the name
servers for a zone are not answering and the ``stale-cache-enable`` option is
also enabled. The default is not to return stale answers.
Information about stale answers is logged under the ``serve-stale``
log category.
-``stale-answer-client-timeout``
+.. namedconf:statement:: stale-answer-client-timeout
+
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, :iscman:`named` continues the ongoing fetches,
refresh the data in cache. :rfc:`8767` recommends a value of ``1800``
(milliseconds).
-``stale-cache-enable``
+.. namedconf:statement:: stale-cache-enable
+
If ``yes``, enable the retaining of "stale" cached answers. Default ``no``.
-``stale-refresh-time``
+.. namedconf:statement:: stale-refresh-time
+
If the name servers for a given zone are not answering, this sets the time
window for which :iscman:`named` will promptly return "stale" cached answers for
that RRSet being requested before a new attempt in contacting the servers
resolution will take place first, if that fails only then :iscman:`named` will
return "stale" cached answers.
-``nocookie-udp-size``
+.. namedconf:statement:: nocookie-udp-size
+
This sets the maximum size of UDP responses that are sent to queries
without a valid server COOKIE. A value below 128 is silently
raised to 128. The default value is 4096, but the ``max-udp-size``
option may further limit the response size as the default for
``max-udp-size`` is 1232.
-``cookie-algorithm``
+.. namedconf:statement:: cookie-algorithm
+
This sets the algorithm to be used when generating the server cookie; the options are
"aes" or "siphash24". The default is "siphash24". The "aes" option remains for legacy
purposes.
-``cookie-secret``
+.. namedconf:statement:: cookie-secret
+
If set, this is a shared secret used for generating and verifying
EDNS COOKIE options within an anycast cluster. If not set, the system
generates a random secret at startup. The shared secret is
:iscman:`named.conf` is used to generate new server cookies. The others
are only used to verify returned cookies.
-``response-padding``
+.. namedconf:statement:: response-padding
+
The EDNS Padding option is intended to improve confidentiality when
DNS queries are sent over an encrypted channel, by reducing the
variability in packet sizes. If a query:
is truncated to 512. Block sizes are ordinarily expected to be powers
of two (for instance, 128), but this is not mandatory.
-``trust-anchor-telemetry``
+.. namedconf:statement:: trust-anchor-telemetry
+
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``.
The default is ``yes``.
-``provide-ixfr``
+.. namedconf:statement:: provide-ixfr
+
See the description of ``provide-ixfr`` in :ref:`server_statement_definition_and_usage`.
-``request-ixfr``
+.. namedconf:statement:: request-ixfr
+
See the description of ``request-ixfr`` in :ref:`server_statement_definition_and_usage`.
-``request-expire``
+.. namedconf:statement:: request-expire
+
See the description of ``request-expire`` in :ref:`server_statement_definition_and_usage`.
-``match-mapped-addresses``
+.. namedconf:statement:: match-mapped-addresses
+
If ``yes``, then an IPv4-mapped IPv6 address matches any
address-match list entries that match the corresponding IPv4 address.
However, :iscman:`named` now solves this problem internally. The use of
this option is discouraged.
-``ixfr-from-differences``
+.. namedconf:statement:: ixfr-from-differences
+
When ``yes`` and the server loads a new version of a primary zone from
its zone file or receives a new version of a secondary file via zone
transfer, it compares the new version to the previous one and
Note: if inline signing is enabled for a zone, the user-provided
``ixfr-from-differences`` setting is ignored for that zone.
-``multi-master``
+.. namedconf:statement:: multi-master
+
This should be set when there are multiple primary servers for a zone and the
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``
+.. namedconf:statement:: auto-dnssec
+
Zones configured for dynamic DNS may use this option to allow varying
levels of automatic DNSSEC key management. There are three possible
settings:
.. _dnssec-validation-option:
-``dnssec-validation``
+.. namedconf:statement:: dnssec-validation
+
This option enables DNSSEC validation in :iscman:`named`.
If set to ``auto``, DNSSEC validation is enabled and a default trust
server, it always sets the DO bit indicating it can support DNSSEC
responses, even if ``dnssec-validation`` is off.
-``validate-except``
+.. namedconf:statement:: validate-except
+
This specifies a list of domain names at and beneath which DNSSEC
validation should *not* be performed, regardless of the presence of a
trust anchor at or above those names. This may be used, for example,
whereas negative trust anchors expire and are removed after a set
period of time.)
-``dnssec-accept-expired``
+.. namedconf:statement:: dnssec-accept-expired
+
This accepts expired signatures when verifying DNSSEC signatures. The
default is ``no``. Setting this option to ``yes`` leaves :iscman:`named`
vulnerable to replay attacks.
-``querylog``
+.. namedconf:statement:: querylog
+
Query logging provides a complete log of all incoming queries and all query
errors. This provides more insight into the server's activity, but with a
cost to performance which may be significant on heavily loaded servers.
logging can also be activated at runtime using the command ``rndc querylog
on``, or deactivated with :option:`rndc querylog off <rndc querylog>`.
-``check-names``
+.. namedconf:statement:: check-names
+
This option is used to restrict the character set and syntax of
certain domain names in primary files and/or DNS responses received
from the network. The default varies according to usage area. For
owner name indicates that it is a reverse lookup of a hostname (the
owner name ends in IN-ADDR.ARPA, IP6.ARPA, or IP6.INT).
-``check-dup-records``
+.. namedconf:statement:: check-dup-records
+
This checks primary zones for records that are treated as different by
DNSSEC but are semantically equal in plain DNS. The default is to
``warn``. Other possible values are ``fail`` and ``ignore``.
-``check-mx``
+.. namedconf:statement:: check-mx
+
This checks whether the MX record appears to refer to an IP address. The
default is to ``warn``. Other possible values are ``fail`` and
``ignore``.
-``check-wildcard``
+.. namedconf:statement:: check-wildcard
+
This option is used to check for non-terminal wildcards. The use of
non-terminal wildcards is almost always as a result of a lack of
understanding of the wildcard matching algorithm (:rfc:`1034`). This option
affects primary zones. The default (``yes``) is to check for
non-terminal wildcards and issue a warning.
-``check-integrity``
+.. namedconf:statement:: check-integrity
+
This performs post-load zone integrity checks on primary zones. It checks
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
record. Warnings are emitted if the TXT record does not exist; they can
be suppressed with ``check-spf``.
-``check-mx-cname``
+.. namedconf:statement:: check-mx-cname
+
If ``check-integrity`` is set, then fail, warn, or ignore MX records
that refer to CNAMES. The default is to ``warn``.
-``check-srv-cname``
+.. namedconf:statement:: check-srv-cname
+
If ``check-integrity`` is set, then fail, warn, or ignore SRV records
that refer to CNAMES. The default is to ``warn``.
-``check-sibling``
+.. namedconf:statement:: check-sibling
+
When performing integrity checks, also check that sibling glue
exists. The default is ``yes``.
-``check-spf``
+.. namedconf:statement:: check-spf
+
If ``check-integrity`` is set, check that there is a TXT Sender
Policy Framework record present (starts with "v=spf1") if there is an
SPF record present. The default is ``warn``.
-``zero-no-soa-ttl``
+.. namedconf:statement:: zero-no-soa-ttl
+
If ``yes``, when returning authoritative negative responses to SOA queries, set
the TTL of the SOA record returned in the authority section to zero.
The default is ``yes``.
-``zero-no-soa-ttl-cache``
+.. namedconf:statement:: zero-no-soa-ttl-cache
+
If ``yes``, when caching a negative response to an SOA query set the TTL to zero.
The default is ``no``.
-``update-check-ksk``
+.. namedconf:statement:: update-check-ksk
+
When set to the default value of ``yes``, check the KSK bit in each
key to determine how the key should be used when generating RRSIGs
for a secure zone.
which this requirement is not met, this option is ignored for
that algorithm.
-``dnssec-dnskey-kskonly``
+.. namedconf:statement:: dnssec-dnskey-kskonly
+
When this option and ``update-check-ksk`` are both set to ``yes``,
only key-signing keys (that is, keys with the KSK bit set) are
used to sign the DNSKEY, CDNSKEY, and CDS RRsets at the zone apex.
The default is ``yes``. If ``update-check-ksk`` is set to ``no``, this
option is ignored.
-``try-tcp-refresh``
+.. namedconf:statement:: try-tcp-refresh
+
If ``yes``, try to refresh the zone using TCP if UDP queries fail. The default is
``yes``.
-``dnssec-secure-to-insecure``
+.. namedconf:statement:: dnssec-secure-to-insecure
+
This allows a dynamic zone to transition from secure to insecure (i.e.,
signed to unsigned) by deleting all of the DNSKEY records. The
default is ``no``. If set to ``yes``, and if the DNSKEY RRset at the
the zone will be automatically signed again the next time :iscman:`named`
is started.
-``synth-from-dnssec``
+.. namedconf:statement:: synth-from-dnssec
+
This option enables support for :rfc:`8198`, Aggressive Use of
DNSSEC-Validated Cache. It allows the resolver to send a smaller number
of queries when resolving queries for DNSSEC-signed domains
.. _forward:
-``forward``
+.. namedconf:statement:: forward
+
This option is only meaningful if the forwarders list is not empty. A
value of ``first`` is the default and causes the server to query the
forwarders first; if that does not answer the question, the
.. _forwarders:
-``forwarders``
+.. namedconf:statement:: forwarders
+
This specifies a list of IP addresses to which queries are forwarded. The
default is the empty list (no forwarding). Each address in the list can be
associated with an optional port number and/or DSCP value, and a default port
problems in reachability due to the lack of support for either IPv4 or IPv6
on the host machine.
-``dual-stack-servers``
+.. namedconf:statement:: dual-stack-servers
+
This specifies host names or addresses of machines with access to both
IPv4 and IPv6 transports. If a hostname is used, the server must be
able to resolve the name using only the transport it has. If the
requesting system. See :ref:`address_match_lists`
for details on how to specify IP address lists.
-``allow-notify``
+.. namedconf:statement:: allow-notify
+
This ACL specifies which hosts may send NOTIFY messages to inform
this server of changes to zones for which it is acting as a secondary
server. This is only applicable for secondary zones (i.e., type
the configured ``primaries`` for the zone. ``allow-notify`` can be used
to expand the list of permitted hosts, not to reduce it.
-``allow-query``
- This specifies which hosts are allowed to ask ordinary DNS questions.
+.. namedconf:statement:: allow-query
+ :tags: query
+ :short: Specifies which hosts (an IP address list) are allowed to send queries to this resolver.
+
``allow-query`` may also be specified in the ``zone`` statement, in
which case it overrides the ``options allow-query`` statement. If not
specified, the default is to allow queries from all hosts.
.. note:: ``allow-query-cache`` is used to specify access to the cache.
-``allow-query-on``
- This specifies which local addresses can accept ordinary DNS questions.
+.. namedconf:statement:: allow-query-on
+ :tags: query
+ :short: Specifies which local addresses (an IP address list) are allowed to send queries to this resolver. Used in multi-homed configurations.
+
This makes it possible, for instance, to allow queries on
internal-facing interfaces but disallow them on external-facing ones,
without necessarily knowing the internal network's addresses.
.. note:: ``allow-query-cache`` is used to specify access to the cache.
-.. _allow-query-cache:
+.. namedconf:statement:: allow-query-cache
+ :tags: query
+ :short: Specifies which hosts (an IP address list) can access this servers cache and thus effectively controls recursion.
+
+ Defines an :term:`address_match_list` of IP address(es) which are allowed to
+ issue queries that access the local cache - without access to the local
+ cache recursive queries are effectively useless so, in effect, this
+ statement (or its default) controls recursive behavior. This statements's
+ default setting depends on:
+
+ 1. If :namedconf:ref:`recursion no; <recursion>` present, defaults to
+ ``allow-query-cache {none;};``. No local cache access permitted.
-``allow-query-cache``
- This specifies which hosts are allowed to get answers from the cache. If
- ``allow-recursion`` is not set, BIND checks to see if the following parameters
- are set, in order: ``allow-query-cache`` and ``allow-query`` (unless ``recursion no;`` is set).
- If neither of those parameters is set, the default (localnets; localhost;) is used.
+ 2. If :namedconf:ref:`recursion yes; <recursion>` (default) then, if
+ :any:`allow-recursion` present, defaults to the value of
+ :any:`allow-recursion`. Local cache access permitted to the same
+ :term:`address_match_list` as :any:`allow-recursion`.
+
+ 3. If :namedconf:ref:`recursion yes; <recursion>` (default) then, if
+ :any:`allow-recursion` is **not** present, defaults to
+ ``allow-query-cache {localnets; localhost;};``. Local cache access permitted
+ to :term:`address_match_list` localnets and localhost IP addresses only.
+
+.. namedconf:statement:: allow-query-cache-on
+ :tags: query
+ :short: Specifies which hosts (an IP address list) can access this servers cache. Used in multi-homed configurations.
-``allow-query-cache-on``
This specifies which local addresses can send answers from the cache. If
``allow-query-cache-on`` is not set, then ``allow-recursion-on`` is
used if set. Otherwise, the default is to allow cache responses to be
can be sent; a client that is blocked by one cannot be allowed by the
other.
-``allow-recursion``
+.. namedconf:statement:: allow-recursion
+
This specifies which hosts are allowed to make recursive queries through
this server. BIND checks to see if the following parameters are set, in
order: ``allow-query-cache`` and ``allow-query``. If neither of those parameters
is set, the default (localnets; localhost;) is used.
-``allow-recursion-on``
+.. namedconf:statement:: allow-recursion-on
+
This specifies which local addresses can accept recursive queries. If
``allow-recursion-on`` is not set, then ``allow-query-cache-on`` is
used if set; otherwise, the default is to allow recursive queries on
before recursion is allowed; a client that is blocked by one cannot
be allowed by the other.
-``allow-update``
+.. namedconf:statement:: allow-update
+
When set in the ``zone`` statement for a primary zone, this specifies which
hosts are allowed to submit Dynamic DNS updates to that zone. The
default is to deny updates from all hosts.
Updates are written to the zone's filename that is set in ``file``.
-``allow-update-forwarding``
+.. namedconf:statement:: allow-update-forwarding
+
When set in the ``zone`` statement for a secondary zone, this specifies which
hosts are allowed to submit Dynamic DNS updates and have them be
forwarded to the primary. The default is ``{ none; }``, which means
.. _allow-transfer:
-``allow-transfer``
+.. namedconf:statement:: allow-transfer
+
This specifies which hosts are allowed to receive zone transfers from the
server. ``allow-transfer`` may also be specified in the ``zone``
statement, in which case it overrides the ``allow-transfer``
or consider implementing :ref:`Mutual TLS <mutual-tls>`
authentication.
-``blackhole``
+.. namedconf:statement:: blackhole
+
This specifies a list of addresses which the server does not accept queries
from or use to resolve a query. Queries from these addresses are not
responded to. The default is ``none``.
-``no-case-compress``
+.. namedconf:statement:: no-case-compress
+
This specifies a list of addresses which require responses to use
case-insensitive compression. This ACL can be used when :iscman:`named`
needs to work with clients that do not comply with the requirement in
type NS, MX, CNAME, etc.) always have their case preserved unless
the client matches this ACL.
-``resolver-query-timeout``
+.. namedconf:statement:: resolver-query-timeout
+
This is the amount of time in milliseconds that the resolver spends
attempting to resolve a recursive query before failing. The default
and minimum is ``10000`` and the maximum is ``30000``. Setting it to
The interfaces, ports, and protocols that the server can use to answer
queries may be specified using the ``listen-on`` and ``listen-on-v6`` options.
-``listen-on`` and ``listen-on-v6`` statements can each take an optional
-port, TLS configuration identifier, and/or HTTP configuration identifier,
-in addition to an ``address_match_list``.
+.. namedconf:statement:: listen-on
+.. namedconf:statement:: listen-on-v6
-The ``address_match_list`` in ``listen-on`` specifies the IPv4 addresses
-on which the server will listen. (IPv6 addresses are ignored, with a
-logged warning.) The server listens on all interfaces allowed by the
-address match list. If no ``listen-on`` is specified, the default is
-to listen for standard DNS queries on port 53 of all IPv4 interfaces.
+ ``listen-on`` and ``listen-on-v6`` statements can each take an optional
+ port, TLS configuration identifier, and/or HTTP configuration identifier,
+ in addition to an ``address_match_list``.
-``listen-on-v6`` takes an ``address_match_list`` of IPv6 addresses.
-The server listens on all interfaces allowed by the address match list.
-If no ``listen-on-v6`` is specified, the default is to listen for standard
-DNS queries on port 53 of all IPv6 interfaces.
+ The ``address_match_list`` in ``listen-on`` specifies the IPv4 addresses
+ on which the server will listen. (IPv6 addresses are ignored, with a
+ logged warning.) The server listens on all interfaces allowed by the
+ address match list. If no ``listen-on`` is specified, the default is
+ to listen for standard DNS queries on port 53 of all IPv4 interfaces.
-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
-:iscman:`named` process will be used.
+ ``listen-on-v6`` takes an ``address_match_list`` of IPv6 addresses.
+ The server listens on all interfaces allowed by the address match list.
+ If no ``listen-on-v6`` is specified, the default is to listen for standard
+ DNS queries on port 53 of all IPv6 interfaces.
-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
-:iscman:`named` will listen for connections at the default endpoint,
-``/dns-query``.
+ 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
+ :iscman:`named` process will be used.
-Use of an ``http`` specification requires ``tls`` to be specified
-as well. If an unencrypted connection is desired (for example,
-on load-sharing servers behind a reverse proxy), ``tls none`` may be used.
+ 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
+ :iscman:`named` will listen for connections at the default endpoint,
+ ``/dns-query``.
-If a port number is not specified, the default is 53 for standard DNS,
-853 for DNS over TLS, 443 for DNS over HTTPS, and 80 for
-DNS over HTTP (unencrypted). These defaults may be overridden using the
-``port``, ``tls-port``, ``https-port`` and ``http-port`` options.
+ Use of an ``http`` specification requires ``tls`` to be specified
+ as well. If an unencrypted connection is desired (for example,
+ on load-sharing servers behind a reverse proxy), ``tls none`` may be used.
-Multiple ``listen-on`` statements are allowed. For example:
+ If a port number is not specified, the default is 53 for standard DNS,
+ 853 for DNS over TLS, 443 for DNS over HTTPS, and 80 for
+ DNS over HTTP (unencrypted). These defaults may be overridden using the
+ ``port``, ``tls-port``, ``https-port`` and ``http-port`` options.
-::
+ Multiple ``listen-on`` statements are allowed. For example:
- listen-on { 5.6.7.8; };
- listen-on port 1234 { !1.2.3.4; 1.2/16; };
- listen-on port 8853 tls ephemeral { 4.3.2.1; };
- listen-on port 8453 tls ephemeral http myserver { 8.7.6.5; };
+ ::
-The first two lines instruct the name server to listen for standard DNS
-queries on port 53 of the IP address 5.6.7.8 and on port 1234 of an address
-on the machine in net 1.2 that is not 1.2.3.4. The third line instructs the
-server to listen for DNS-over-TLS connections on port 8853 of the IP
-address 4.3.2.1 using the ephemeral key and certifcate. The fourth line
-enables DNS-over-HTTPS connections on port 8453 of address 8.7.6.5, using
-the ephemeral key and certificate, and the HTTP endpoint or endpoints
-configured in an ``http`` statement with the name ``myserver``.
+ listen-on { 5.6.7.8; };
+ listen-on port 1234 { !1.2.3.4; 1.2/16; };
+ listen-on port 8853 tls ephemeral { 4.3.2.1; };
+ listen-on port 8453 tls ephemeral http myserver { 8.7.6.5; };
-Multiple ``listen-on-v6`` options can be used. For example:
+ The first two lines instruct the name server to listen for standard DNS
+ queries on port 53 of the IP address 5.6.7.8 and on port 1234 of an address
+ on the machine in net 1.2 that is not 1.2.3.4. The third line instructs the
+ server to listen for DNS-over-TLS connections on port 8853 of the IP
+ address 4.3.2.1 using the ephemeral key and certifcate. The fourth line
+ enables DNS-over-HTTPS connections on port 8453 of address 8.7.6.5, using
+ the ephemeral key and certificate, and the HTTP endpoint or endpoints
+ configured in an ``http`` statement with the name ``myserver``.
-::
+ Multiple ``listen-on-v6`` options can be used. For example:
- listen-on-v6 { any; };
- listen-on-v6 port 1234 { !2001:db8::/32; any; };
- listen-on port 8853 tls example-tls { 2001:db8::100; };
- listen-on port 8453 tls example-tls http default { 2001:db8::100; };
- listen-on port 8000 tls none http myserver { 2001:db8::100; };
-
-The first two lines instruct the name server to listen for standard DNS
-queries on port 53 of any IPv6 addresses, and on port 1234 of IPv6
-addresses that are not in the prefix 2001:db8::/32. The third line
-instructs the server to listen for for DNS-over-TLS connections on port
-8853 of the address 2001:db8::100, using a TLS key and certificate specified
-in the a ``tls`` statement with the name ``example-tls``. The fourth
-instructs the server to listen for DNS-over-HTTPS connections, again using
-``example-tls``, on the default HTTP endpoint. The fifth line, in which
-the ``tls`` parameter is set to ``none``, instructs the server to listen
-for *unencrypted* DNS queries over HTTP at the endpoint specified in
-``myserver``..
-
-To instruct the server not to listen on any IPv6 addresses, use:
+ ::
-::
+ listen-on-v6 { any; };
+ listen-on-v6 port 1234 { !2001:db8::/32; any; };
+ listen-on port 8853 tls example-tls { 2001:db8::100; };
+ listen-on port 8453 tls example-tls http default { 2001:db8::100; };
+ listen-on port 8000 tls none http myserver { 2001:db8::100; };
+
+ The first two lines instruct the name server to listen for standard DNS
+ queries on port 53 of any IPv6 addresses, and on port 1234 of IPv6
+ addresses that are not in the prefix 2001:db8::/32. The third line
+ instructs the server to listen for for DNS-over-TLS connections on port
+ 8853 of the address 2001:db8::100, using a TLS key and certificate specified
+ in the a ``tls`` statement with the name ``example-tls``. The fourth
+ instructs the server to listen for DNS-over-HTTPS connections, again using
+ ``example-tls``, on the default HTTP endpoint. The fifth line, in which
+ the ``tls`` parameter is set to ``none``, instructs the server to listen
+ for *unencrypted* DNS queries over HTTP at the endpoint specified in
+ ``myserver``..
+
+ To instruct the server not to listen on any IPv6 addresses, use:
- listen-on-v6 { none; };
+ ::
+
+ listen-on-v6 { none; };
.. _query_address:
Query Address
^^^^^^^^^^^^^
-If the server does not know the answer to a question, it queries other
-name servers. ``query-source`` specifies the address and port used for
-such queries. For queries sent over IPv6, there is a separate
-``query-source-v6`` option. If ``address`` is ``*`` (asterisk) or is
-omitted, a wildcard IP address (``INADDR_ANY``) is used.
+.. namedconf:statement:: query-source
+.. namedconf:statement:: query-source-v6
-If ``port`` is ``*`` or is omitted, a random port number from a
-pre-configured range is picked up and used for each query. The
-port range(s) is specified in the ``use-v4-udp-ports`` (for IPv4)
-and ``use-v6-udp-ports`` (for IPv6) options, excluding the ranges
-specified in the ``avoid-v4-udp-ports`` and ``avoid-v6-udp-ports``
-options, respectively.
+ If the server does not know the answer to a question, it queries other
+ name servers. ``query-source`` specifies the address and port used for
+ such queries. For queries sent over IPv6, there is a separate
+ ``query-source-v6`` option. If ``address`` is ``*`` (asterisk) or is
+ omitted, a wildcard IP address (``INADDR_ANY``) is used.
-The defaults of the ``query-source`` and ``query-source-v6`` options
-are:
+.. namedconf:statement:: use-v4-udp-ports
+.. namedconf:statement:: use-v6-udp-ports
-::
+ If ``port`` is ``*`` or is omitted, a random port number from a
+ pre-configured range is picked up and used for each query. The
+ port range(s) is specified in the ``use-v4-udp-ports`` (for IPv4)
+ and ``use-v6-udp-ports`` (for IPv6) options.
- query-source address * port *;
- query-source-v6 address * port *;
+.. namedconf:statement:: avoid-v4-udp-ports
+.. namedconf:statement:: avoid-v6-udp-ports
-If ``use-v4-udp-ports`` or ``use-v6-udp-ports`` is unspecified,
-: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, :iscman:`named` uses the corresponding
-system default range; otherwise, it uses its own defaults:
+ The ranges excluded from those
+ specified in the ``avoid-v4-udp-ports`` and ``avoid-v6-udp-ports``
+ options, respectively.
-::
+ The defaults of the ``query-source`` and ``query-source-v6`` options
+ are:
- use-v4-udp-ports { range 1024 65535; };
- use-v6-udp-ports { range 1024 65535; };
+ ::
-The defaults of the ``avoid-v4-udp-ports`` and ``avoid-v6-udp-ports``
-options are:
+ query-source address * port *;
+ query-source-v6 address * port *;
-::
- avoid-v4-udp-ports {};
- avoid-v6-udp-ports {};
+ If ``use-v4-udp-ports`` or ``use-v6-udp-ports`` is unspecified,
+ :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, :iscman:`named` uses the corresponding
+ system default range; otherwise, it uses its own defaults:
-.. note:: Make sure the ranges are sufficiently large for security. A
- 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 :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 :iscman:`named` runs may prohibit
- the use of some ports. For example, Unix systems do not allow
- :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
- set of ports that can be safely used in the expected operational
- environment.
+ use-v4-udp-ports { range 1024 65535; };
+ use-v6-udp-ports { range 1024 65535; };
-.. note:: The address specified in the ``query-source`` option is used for both
- UDP and TCP queries, but the port applies only to UDP queries. TCP
- queries always use a random unprivileged port.
+ The defaults of the ``avoid-v4-udp-ports`` and ``avoid-v6-udp-ports``
+ options are:
-.. warning:: Specifying a single port is discouraged, as it removes a layer of
- protection against spoofing errors.
+ ::
-.. warning:: The configured ``port`` must not be same as the listening port.
+ avoid-v4-udp-ports {};
+ avoid-v6-udp-ports {};
+
+ .. note:: Make sure the ranges are sufficiently large for security. A
+ 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 :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 :iscman:`named` runs may prohibit
+ the use of some ports. For example, Unix systems do not allow
+ :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
+ set of ports that can be safely used in the expected operational
+ environment.
+
+ .. note:: The address specified in the ``query-source`` option is used for both
+ UDP and TCP queries, but the port applies only to UDP queries. TCP
+ queries always use a random unprivileged port.
-.. note:: See also ``transfer-source``, ``notify-source`` and ``parental-source``.
+ .. warning:: Specifying a single port is discouraged, as it removes a layer of
+ protection against spoofing errors.
+
+ .. warning:: The configured ``port`` must not be same as the listening port.
+
+ .. note:: See also ``transfer-source``, ``notify-source`` and ``parental-source``.
.. _zone_transfers:
.. _also-notify:
-``also-notify``
+.. namedconf:statement:: also-notify
+
This option defines a global list of IP addresses of name servers that are also
sent NOTIFY messages whenever a fresh copy of the zone is loaded, in
addition to the servers listed in the zone's NS records. This helps
global ``also-notify`` list are not sent NOTIFY messages for that
zone. The default is the empty list (no global notification list).
-``max-transfer-time-in``
+.. namedconf:statement:: max-transfer-time-in
+
Inbound zone transfers running longer than this many minutes are
terminated. The default is 120 minutes (2 hours). The maximum value
is 28 days (40320 minutes).
-``max-transfer-idle-in``
+.. namedconf:statement:: max-transfer-idle-in
+
Inbound zone transfers making no progress in this many minutes are
terminated. The default is 60 minutes (1 hour). The maximum value
is 28 days (40320 minutes).
-``max-transfer-time-out``
+.. namedconf:statement:: max-transfer-time-out
+
Outbound zone transfers running longer than this many minutes are
terminated. The default is 120 minutes (2 hours). The maximum value
is 28 days (40320 minutes).
-``max-transfer-idle-out``
+.. namedconf:statement:: max-transfer-idle-out
+
Outbound zone transfers making no progress in this many minutes are
terminated. The default is 60 minutes (1 hour). The maximum value
is 28 days (40320 minutes).
-``notify-rate``
+.. namedconf:statement:: notify-rate
+
This specifies the rate at which NOTIFY requests are sent during normal zone
maintenance operations. (NOTIFY requests due to initial zone loading
are subject to a separate rate limit; see below.) The default is 20
per second. The lowest possible rate is one per second; when set to
zero, it is silently raised to one.
-``startup-notify-rate``
+.. namedconf:statement:: startup-notify-rate
+
This is the rate at which NOTIFY requests are sent when the name server
is first starting up, or when zones have been newly added to the
name server. The default is 20 per second. The lowest possible rate is
one per second; when set to zero, it is silently raised to one.
-``serial-query-rate``
+.. namedconf:statement:: serial-query-rate
+
Secondary servers periodically query primary servers to find out if
zone serial numbers have changed. Each such query uses a minute
amount of the secondary server's network bandwidth. To limit the amount
second. The lowest possible rate is one per second; when set to zero,
it is silently raised to one.
-``transfer-format``
+.. namedconf:statement:: transfer-format
+
Zone transfers can be sent using two different formats,
``one-answer`` and ``many-answers``. The ``transfer-format`` option
is used on the primary server to determine which format it sends.
``transfer-format`` may be overridden on a per-server basis by using
the ``server`` statement.
-``transfer-message-size``
+.. namedconf:statement:: transfer-message-size
+
This is an upper bound on the uncompressed size of DNS messages used
in zone transfers over TCP. If a message grows larger than this size,
additional messages are used to complete the zone transfer.
This option is mainly intended for server testing; there is rarely
any benefit in setting a value other than the default.
-``transfers-in``
+.. namedconf:statement:: transfers-in
+
This is the maximum number of inbound zone transfers that can run
concurrently. The default value is ``10``. Increasing
``transfers-in`` may speed up the convergence of secondary zones, but it
also may increase the load on the local system.
-``transfers-out``
+.. namedconf:statement:: transfers-out
+
This is the maximum number of outbound zone transfers that can run
concurrently. Zone transfer requests in excess of the limit are
refused. The default value is ``10``.
-``transfers-per-ns``
+.. namedconf:statement:: transfers-per-ns
+
This is the maximum number of inbound zone transfers that can concurrently
transfer from a given remote name server. The default value is
``2``. Increasing ``transfers-per-ns`` may speed up the convergence
server. ``transfers-per-ns`` may be overridden on a per-server basis
by using the ``transfers`` phrase of the ``server`` statement.
-``transfer-source``
+.. namedconf:statement:: transfer-source
+
``transfer-source`` determines which local address is bound to
IPv4 TCP connections used to fetch zones transferred inbound by the
server. It also determines the source IPv4 address, and optionally
.. warning:: The configured ``port`` must not be same as the listening port.
-``transfer-source-v6``
+.. namedconf:statement:: transfer-source-v6
+
This option is the same as ``transfer-source``, except zone transfers are performed
using IPv6.
-``alt-transfer-source``
+.. namedconf:statement:: alt-transfer-source
+
This indicates an alternate transfer source if the one listed in ``transfer-source``
fails and ``use-alt-transfer-source`` is set.
do not depend upon getting an answer back to the first refresh
query.
-``alt-transfer-source-v6``
+.. namedconf:statement:: alt-transfer-source-v6
+
This indicates an alternate transfer source if the one listed in
``transfer-source-v6`` fails and ``use-alt-transfer-source`` is set.
-``use-alt-transfer-source``
+.. namedconf:statement:: use-alt-transfer-source
+
This indicates whether the alternate transfer sources should be used. If views are specified,
this defaults to ``no``; otherwise, it defaults to ``yes``.
-``notify-source``
+.. namedconf:statement:: notify-source
+
``notify-source`` determines which local source address, and
optionally UDP port, is used to send NOTIFY messages. This
address must appear in the secondary server's ``primaries`` zone clause or
.. warning:: The configured ``port`` must not be same as the listening port.
-``notify-source-v6``
+.. namedconf:statement:: notify-source-v6
+
This option acts like ``notify-source``, but applies to notify messages sent to IPv6
addresses.
UDP Port Lists
^^^^^^^^^^^^^^
+.. namedconf:statement:: use-v4-udp-ports
+.. namedconf:statement:: avoid-v4-udp-ports
+.. namedconf:statement:: use-v6-udp-ports
+.. namedconf:statement:: avoid-v6-udp-ports
-``use-v4-udp-ports``, ``avoid-v4-udp-ports``, ``use-v6-udp-ports``, and
-``avoid-v6-udp-ports`` specify a list of IPv4 and IPv6 UDP ports that
-are or are not used as source ports for UDP messages. See
-:ref:`query_address` about how the available ports are
-determined. For example, with the following configuration:
+ These statements specify a list of IPv4 and IPv6 UDP ports that
+ are or are not used as source ports for UDP messages. See
+ :ref:`query_address` about how the available ports are
+ determined. For example, with the following configuration:
-::
+ ::
- use-v6-udp-ports { range 32768 65535; };
- avoid-v6-udp-ports { 40000; range 50000 60000; };
+ use-v6-udp-ports { range 32768 65535; };
+ avoid-v6-udp-ports { 40000; range 50000 60000; };
-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.
+ 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
-: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
-again. Note: the desired range can also be represented only with
-``use-v4-udp-ports`` and ``use-v6-udp-ports``, and the ``avoid-``
-options are redundant in that sense; they are provided for backward
-compatibility and to possibly simplify the port specification.
+ ``avoid-v4-udp-ports`` and ``avoid-v6-udp-ports`` can be used to prevent
+ :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
+ again. Note: the desired range can also be represented only with
+ ``use-v4-udp-ports`` and ``use-v6-udp-ports``, and the ``avoid-``
+ options are redundant in that sense; they are provided for backward
+ compatibility and to possibly simplify the port specification.
.. _resource_limits:
can be used instead of ``1073741824`` to specify a limit of one
gigabyte. ``unlimited`` requests unlimited use, or the maximum available
amount. ``default`` uses the limit that was in force when the server was
-started. See the description of ``size_spec`` in :ref:`configuration_file_elements`.
+started. See the description of :term:`size_spec`.
The following options set operating system resource limits for the name
server process. Some operating systems do not support some or any of the
limits; on such systems, a warning is issued if an unsupported
limit is used.
-``coresize``
+.. namedconf:statement:: coresize
+
This sets the maximum size of a core dump. The default is ``default``.
-``datasize``
+.. namedconf:statement:: datasize
+
This sets the maximum amount of data memory the server may use. The default is
``default``. This is a hard limit on server memory usage; if the
server attempts to allocate memory in excess of this limit, the
server, use the ``max-cache-size`` and ``recursive-clients`` options
instead.
-``files``
+.. namedconf:statement:: files
+
This sets the maximum number of files the server may have open concurrently.
The default is ``unlimited``.
-``stacksize``
+.. namedconf:statement:: stacksize
+
This sets the maximum amount of stack memory the server may use. The default is
``default``.
that are enforced internally by the server rather than by the operating
system.
-``max-journal-size``
+.. namedconf:statement:: max-journal-size
+
This sets a maximum size for each journal file (see :ref:`journal`),
expressed in bytes or, if followed by an
optional unit suffix ('k', 'm', or 'g'), in kilobytes, megabytes, or
This option may also be set on a per-zone basis.
-``max-records``
+.. namedconf:statement:: max-records
+
This sets the maximum number of records permitted in a zone. The default is
zero, which means the maximum is unlimited.
-``recursive-clients``
+.. namedconf:statement:: recursive-clients
+
This sets the maximum number (a "hard quota") of simultaneous recursive lookups
the server performs on behalf of clients. The default is
``1000``. Because each recursing client uses a fair bit of memory (on
soft quota is set to ``recursive-clients`` minus 100; otherwise it is
set to 90% of ``recursive-clients``.
-``tcp-clients``
+.. namedconf:statement:: tcp-clients
+
This is the maximum number of simultaneous client TCP connections that the
server accepts. The default is ``150``.
.. _clients-per-query:
-``clients-per-query``; ``max-clients-per-query``
- These set the initial value (minimum) and maximum number of recursive
+.. namedconf:statement:: clients-per-query
+
+ Sets the initial value (minimum) number of recursive
simultaneous clients for any given query (<qname,qtype,qclass>) that
the server accepts before dropping additional clients. :iscman:`named`
attempts to self-tune this value and changes are logged. The
If ``clients-per-query`` is set to zero, there is no limit on
the number of clients per query and no queries are dropped.
+.. namedconf:statement:: max-clients-per-query
+
+ Sets the maximum number of recursive
+ simultaneous clients for any given query (<qname,qtype,qclass>) that
+ the server accepts before dropping additional clients.
+
If ``max-clients-per-query`` is set to zero, there is no upper
bound other than that imposed by ``recursive-clients``.
-``fetches-per-zone``
+.. namedconf:statement:: fetches-per-zone
+
This sets the maximum number of simultaneous iterative queries to any one
domain that the server permits before blocking new queries for
data in or beneath that zone. This value should reflect how many
is sent to that domain, it is recreated with the counters set
to zero.)
-``fetches-per-server``
+.. namedconf:statement:: fetches-per-server
+
This sets the maximum number of simultaneous iterative queries that the server
allows to be sent to a single upstream name server before
blocking additional queries. This value should reflect how many
increased. The ``fetch-quota-params`` options can be used to adjust
the parameters for this calculation.
-``fetch-quota-params``
+.. namedconf:statement:: fetch-quota-params
+
This sets the parameters to use for dynamic resizing of the
``fetches-per-server`` quota in response to detected congestion.
arguments are all fixed-point numbers with precision of 1/100; at
most two places after the decimal point are significant.
-``reserved-sockets``
+.. namedconf:statement:: reserved-sockets
+
This option is deprecated and no longer has any effect.
.. _max-cache-size:
-``max-cache-size``
+.. namedconf:statement:: max-cache-size
+
This sets the maximum amount of memory to use for an individual cache
database and its associated metadata, in bytes or percentage of total
physical memory. By default, each view has its own separate cache,
startup, so :iscman:`named` does not adjust the cache size limits if the
amount of physical memory is changed at runtime.
-``tcp-listen-queue``
+.. namedconf:statement:: tcp-listen-queue
+
This sets the listen-queue depth. The default and minimum is 10. If the kernel
supports the accept filter "dataready", this also controls how many
TCP connections are queued in kernel space waiting for some
silently raised. A value of 0 may also be used; on most platforms
this sets the listen-queue length to a system-defined default value.
-``tcp-initial-timeout``
+.. namedconf:statement:: tcp-initial-timeout
+
This sets the amount of time (in units of 100 milliseconds) that the server waits on
a new TCP connection for the first message from the client. The
default is 300 (30 seconds), the minimum is 25 (2.5 seconds), and the
client will ever have enough time to submit a message.) This value
can be updated at runtime by using :option:`rndc tcp-timeouts`.
-``tcp-idle-timeout``
+.. namedconf:statement:: tcp-idle-timeout
+
This sets the amount of time (in units of 100 milliseconds) that the server waits on
an idle TCP connection before closing it, when the client is not using
the EDNS TCP keepalive option. The default is 300 (30 seconds), the
clients using the EDNS TCP keepalive option. This value can be
updated at runtime by using :option:`rndc tcp-timeouts`.
-``tcp-keepalive-timeout``
+.. namedconf:statement:: tcp-keepalive-timeout
+
This sets the amount of time (in units of 100 milliseconds) that the server waits on
an idle TCP connection before closing it, when the client is using the
EDNS TCP keepalive option. The default is 300 (30 seconds), the
option are expected to use TCP connections for more than one message.
This value can be updated at runtime by using :option:`rndc tcp-timeouts`.
-``tcp-advertised-timeout``
+.. namedconf:statement:: tcp-advertised-timeout
+
This sets the timeout value (in units of 100 milliseconds) that the server sends
in responses containing the EDNS TCP keepalive option, which informs a
client of the amount of time it may keep the session open. The
Periodic Task Intervals
^^^^^^^^^^^^^^^^^^^^^^^
-``heartbeat-interval``
+.. namedconf:statement:: heartbeat-interval
+
The server performs zone maintenance tasks for all zones marked
as ``dialup`` whenever this interval expires. The default is 60
minutes. Reasonable values are up to 1 day (1440 minutes). The
maximum value is 28 days (40320 minutes). If set to 0, no zone
maintenance for these zones occurs.
-``interface-interval``
+.. namedconf:statement:: interface-interval
+
The server scans the network interface list every ``interface-interval``
minutes. The default is 60 minutes; the maximum value is 28 days (40320
minutes). If set to 0, interface scanning only occurs when the configuration
client's address. This only requires configuring the name servers, not
all the clients.
-The ``sortlist`` statement (see below) takes an ``address_match_list`` and
-interprets it in a special way. Each top-level statement in the ``sortlist``
-must itself be an explicit ``address_match_list`` with one or two elements. The
-first element (which may be an IP address, an IP prefix, an ACL name, or a nested
-``address_match_list``) of each top-level list is checked against the source
-address of the query until a match is found. When the addresses in the first
-element overlap, the first rule to match is selected.
-
-Once the source address of the query has been matched, if the top-level
-statement contains only one element, the actual primitive element that
-matched the source address is used to select the address in the response
-to move to the beginning of the response. If the statement is a list of
-two elements, then the second element is interpreted as a topology
-preference list. Each top-level element is assigned a distance, and the
-address in the response with the minimum distance is moved to the
-beginning of the response.
-
-In the following example, any queries received from any of the addresses
-of the host itself get responses preferring addresses on any of the
-locally connected networks. Next most preferred are addresses on the
-192.168.1/24 network, and after that either the 192.168.2/24 or
-192.168.3/24 network, with no preference shown between these two
-networks. Queries received from a host on the 192.168.1/24 network
-prefer other addresses on that network to the 192.168.2/24 and
-192.168.3/24 networks. Queries received from a host on the 192.168.4/24
-or the 192.168.5/24 network only prefer other addresses on their
-directly connected networks.
+.. namedconf:statement:: sortlist
+
+ The ``sortlist`` statement (see below) takes an ``address_match_list`` and
+ interprets it in a special way. Each top-level statement in the ``sortlist``
+ must itself be an explicit ``address_match_list`` with one or two elements. The
+ first element (which may be an IP address, an IP prefix, an ACL name, or a nested
+ ``address_match_list``) of each top-level list is checked against the source
+ address of the query until a match is found. When the addresses in the first
+ element overlap, the first rule to match is selected.
+
+ Once the source address of the query has been matched, if the top-level
+ statement contains only one element, the actual primitive element that
+ matched the source address is used to select the address in the response
+ to move to the beginning of the response. If the statement is a list of
+ two elements, then the second element is interpreted as a topology
+ preference list. Each top-level element is assigned a distance, and the
+ address in the response with the minimum distance is moved to the
+ beginning of the response.
+
+ In the following example, any queries received from any of the addresses
+ of the host itself get responses preferring addresses on any of the
+ locally connected networks. Next most preferred are addresses on the
+ 192.168.1/24 network, and after that either the 192.168.2/24 or
+ 192.168.3/24 network, with no preference shown between these two
+ networks. Queries received from a host on the 192.168.1/24 network
+ prefer other addresses on that network to the 192.168.2/24 and
+ 192.168.3/24 networks. Queries received from a host on the 192.168.4/24
+ or the 192.168.5/24 network only prefer other addresses on their
+ directly connected networks.
::
caveats apply (mostly stemming from caching) which usually make it a
suboptimal choice for load balancing purposes when used on its own.
-The ``rrset-order`` statement permits configuration of the ordering of
-the records in a multiple-record response. See also:
-:ref:`the_sortlist_statement`.
+.. namedconf:statement:: rrset-order
-Each rule in an ``rrset-order`` statement is defined as follows:
+ The ``rrset-order`` statement permits configuration of the ordering of
+ the records in a multiple-record response. See also:
+ :ref:`the_sortlist_statement`.
-::
+ Each rule in an ``rrset-order`` statement is defined as follows:
- [class <class_name>] [type <type_name>] [name "<domain_name>"] order <ordering>
+ ::
-The default qualifiers for each rule are:
+ [class <class_name>] [type <type_name>] [name "<domain_name>"] order <ordering>
- - If no ``class`` is specified, the default is ``ANY``.
- - If no ``type`` is specified, the default is ``ANY``.
- - If no ``name`` is specified, the default is ``*`` (asterisk).
+ The default qualifiers for each rule are:
-``<domain_name>`` only matches the name itself, not any of its
-subdomains. To make a rule match all subdomains of a given name, a
-wildcard name (``*.<domain_name>``) must be used. Note that
-``*.<domain_name>`` does *not* match ``<domain_name>`` itself; to
-specify RRset ordering for a name and all of its subdomains, two
-separate rules must be defined: one for ``<domain_name>`` and one for
-``*.<domain_name>``.
+ - If no ``class`` is specified, the default is ``ANY``.
+ - If no ``type`` is specified, the default is ``ANY``.
+ - If no ``name`` is specified, the default is ``*`` (asterisk).
-The legal values for ``<ordering>`` are:
+ ``<domain_name>`` only matches the name itself, not any of its
+ subdomains. To make a rule match all subdomains of a given name, a
+ wildcard name (``*.<domain_name>``) must be used. Note that
+ ``*.<domain_name>`` does *not* match ``<domain_name>`` itself; to
+ specify RRset ordering for a name and all of its subdomains, two
+ separate rules must be defined: one for ``<domain_name>`` and one for
+ ``*.<domain_name>``.
-``fixed``
- Records are returned in the order they are defined in the zone file.
+ The legal values for ``<ordering>`` are:
-.. note::
+ ``fixed``
+ Records are returned in the order they are defined in the zone file.
+
+ .. note::
- The ``fixed`` option is only available if BIND is configured with
- ``--enable-fixed-rrset`` at compile time.
+ The ``fixed`` option is only available if BIND is configured with
+ ``--enable-fixed-rrset`` at compile time.
-``random``
- Records are returned in a random order.
+ ``random``
+ Records are returned in a random order.
-``cyclic``
- Records are returned in a cyclic round-robin order, rotating by one
- record per query.
+ ``cyclic``
+ Records are returned in a cyclic round-robin order, rotating by one
+ record per query.
-``none``
- Records are returned in the order they were retrieved from the
- database. This order is indeterminate, but remains consistent as
- long as the database is not modified.
+ ``none``
+ Records are returned in the order they were retrieved from the
+ database. This order is indeterminate, but remains consistent as
+ 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 :iscman:`named`:
+ The default RRset order used depends on whether any ``rrset-order``
+ 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``
- order.
+ - If no ``rrset-order`` statement is present in the configuration
+ file, the implicit default is to return all records in ``random``
+ order.
- - If any ``rrset-order`` statements are present in the configuration
- file, but no ordering rule specified in these statements matches a
- given RRset, the default order for that RRset is ``none``.
+ - If any ``rrset-order`` statements are present in the configuration
+ file, but no ordering rule specified in these statements matches a
+ given RRset, the default order for that RRset is ``none``.
-Note that if multiple ``rrset-order`` statements are present in the
-configuration file (at both the ``options`` and ``view`` levels), they
-are *not* combined; instead, the more-specific one (``view``) replaces
-the less-specific one (``options``).
+ Note that if multiple ``rrset-order`` statements are present in the
+ configuration file (at both the ``options`` and ``view`` levels), they
+ are *not* combined; instead, the more-specific one (``view``) replaces
+ the less-specific one (``options``).
-If multiple rules within a single ``rrset-order`` statement match a
-given RRset, the first matching rule is applied.
+ If multiple rules within a single ``rrset-order`` statement match a
+ given RRset, the first matching rule is applied.
-Example:
+ Example:
-::
+ ::
+
+ rrset-order {
+ type A name "foo.isc.org" order random;
+ type AAAA name "foo.isc.org" order cyclic;
+ name "bar.isc.org" order fixed;
+ name "*.bar.isc.org" order random;
+ name "*.baz.isc.org" order cyclic;
+ };
- rrset-order {
- type A name "foo.isc.org" order random;
- type AAAA name "foo.isc.org" order cyclic;
- name "bar.isc.org" order fixed;
- name "*.bar.isc.org" order random;
- name "*.baz.isc.org" order cyclic;
- };
-
-With the above configuration, the following RRset ordering is used:
-
-=================== ======== ===========
-QNAME QTYPE RRset Order
-=================== ======== ===========
-``foo.isc.org`` ``A`` ``random``
-``foo.isc.org`` ``AAAA`` ``cyclic``
-``foo.isc.org`` ``TXT`` ``none``
-``sub.foo.isc.org`` all ``none``
-``bar.isc.org`` all ``fixed``
-``sub.bar.isc.org`` all ``random``
-``baz.isc.org`` all ``none``
-``sub.baz.isc.org`` all ``cyclic``
-=================== ======== ===========
+ With the above configuration, the following RRset ordering is used:
+
+ =================== ======== ===========
+ QNAME QTYPE RRset Order
+ =================== ======== ===========
+ ``foo.isc.org`` ``A`` ``random``
+ ``foo.isc.org`` ``AAAA`` ``cyclic``
+ ``foo.isc.org`` ``TXT`` ``none``
+ ``sub.foo.isc.org`` all ``none``
+ ``bar.isc.org`` all ``fixed``
+ ``sub.bar.isc.org`` all ``random``
+ ``baz.isc.org`` all ``none``
+ ``sub.baz.isc.org`` all ``cyclic``
+ =================== ======== ===========
.. _tuning:
Tuning
^^^^^^
-``lame-ttl``
+.. namedconf:statement:: lame-ttl
+
This is always set to 0. More information is available in the
`security advisory for CVE-2021-25219
<https://kb.isc.org/docs/cve-2021-25219>`_.
-``servfail-ttl``
+.. namedconf:statement:: servfail-ttl
+
This sets the number of seconds to cache a SERVFAIL response due to DNSSEC
validation failure or other general server failure. If set to ``0``,
SERVFAIL caching is disabled. The SERVFAIL cache is not consulted if
The maximum value is ``30`` seconds; any higher value is
silently reduced. The default is ``1`` second.
-``min-ncache-ttl``
+.. namedconf:statement:: min-ncache-ttl
+
To reduce network traffic and increase performance, the server stores
negative answers. ``min-ncache-ttl`` is used to set a minimum
retention time for these answers in the server, in seconds. For
exceed 90 seconds and is truncated to 90 seconds if set to a greater
value.
-``min-cache-ttl``
+.. namedconf:statement:: min-cache-ttl
+
This sets the minimum time for which the server caches ordinary (positive)
answers, in seconds. For convenience, TTL-style time-unit suffixes may be used
to specify the value. It also accepts ISO 8601 duration formats.
exceed 90 seconds and is truncated to 90 seconds if set to a greater
value.
-``max-ncache-ttl``
+.. namedconf:statement:: max-ncache-ttl
+
To reduce network traffic and increase performance, the server stores
negative answers. ``max-ncache-ttl`` is used to set a maximum retention time
for these answers in the server, in seconds. For convenience, TTL-style
cannot exceed 7 days and is silently truncated to 7 days if set to a
greater value.
-``max-cache-ttl``
+.. namedconf:statement:: max-cache-ttl
+
This sets the maximum time for which the server caches ordinary (positive)
answers, in seconds. For convenience, TTL-style time-unit suffixes may be used
to specify the value. It also accepts ISO 8601 duration formats.
all queries to return SERVFAIL, because of lost caches of intermediate RRsets
(such as NS and glue AAAA/A records) in the resolution process.
-``max-stale-ttl``
+.. namedconf:statement:: max-stale-ttl
+
If retaining stale RRsets in cache is enabled, and returning of stale cached
answers is also enabled, ``max-stale-ttl`` sets the maximum time for which
the server retains records past their normal expiry to return them as stale
When ``stale-cache-enable`` is set to ``no``, setting the ``max-stale-ttl``
has no effect, the value of ``max-cache-ttl`` will be ``0`` in such case.
-``resolver-nonbackoff-tries``
+.. namedconf:statement:: resolver-nonbackoff-tries
+
This specifies how many retries occur before exponential backoff kicks in. The
default is ``3``.
-``resolver-retry-interval``
+.. namedconf:statement:: resolver-retry-interval
+
This sets the base retry interval in milliseconds. The default is ``800``.
-``sig-validity-interval``
+.. namedconf:statement:: sig-validity-interval
+
this specifies the upper bound of the number of days that RRSIGs
generated by :iscman:`named` are valid; the default is ``30`` days,
with a maximum of 3660 days (10 years). The optional second value
of the SOA expire interval, to allow for reasonable interaction
between the various timer and expiry dates.
-``dnskey-sig-validity``
+.. namedconf:statement:: dnskey-sig-validity
+
This specifies the number of days into the future when DNSSEC signatures
that are automatically generated for DNSKEY RRsets as a result of
dynamic updates (:ref:`dynamic_update`) will expire.
``sig-validity-interval`` is used. The maximum value is 3660 days (10
years), and higher values are rejected.
-``sig-signing-nodes``
+.. namedconf:statement:: sig-signing-nodes
+
This specifies the maximum number of nodes to be examined in each quantum,
when signing a zone with a new DNSKEY. The default is ``100``.
-``sig-signing-signatures``
+.. namedconf:statement:: sig-signing-signatures
+
This specifies a threshold number of signatures that terminates
processing a quantum, when signing a zone with a new DNSKEY. The
default is ``10``.
-``sig-signing-type``
+.. namedconf:statement:: sig-signing-type
+
This specifies a private RDATA type to be used when generating signing-state
records. The default is ``65534``.
the completed signing-state records for a zone, use
:option:`rndc signing -clear all zone <rndc signing>`.
-``min-refresh-time``; ``max-refresh-time``; ``min-retry-time``; ``max-retry-time``
+.. namedconf:statement:: min-refresh-time
+.. namedconf:statement:: max-refresh-time
+.. namedconf:statement:: min-retry-time
+.. namedconf:statement:: max-retry-time
+
These options control the server's behavior on refreshing a zone
(querying for SOA changes) or retrying failed transfers. Usually the
SOA values for the zone are used, up to a hard-coded maximum expiry
``max-refresh-time`` 2419200 seconds (4 weeks), ``min-retry-time``
500 seconds, and ``max-retry-time`` 1209600 seconds (2 weeks).
-``edns-udp-size``
+.. namedconf:statement:: edns-udp-size
+
This sets the maximum advertised EDNS UDP buffer size, in bytes, to control
the size of packets received from authoritative servers in response
to recursive queries. Valid values are 512 to 4096; values outside
Any server-specific ``edns-udp-size`` setting has precedence over all
the above rules.
-``max-udp-size``
+.. namedconf:statement:: max-udp-size
+
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
Setting this to a low value encourages additional TCP traffic to
the name server.
-``masterfile-format``
+.. namedconf:statement:: masterfile-format
+
This specifies the file format of zone files (see :ref:`zonefile_format`
for details). The default value is ``text``, which is the standard
textual representation, except for secondary zones, in which the default
statement within the ``zone`` or ``view`` block in the configuration
file.
-``masterfile-style``
+.. namedconf:statement:: masterfile-style
+
This specifies the formatting of zone files during dump, when the
``masterfile-format`` is ``text``. This option is ignored with any
other ``masterfile-format``.
format is more human-readable, and is thus suitable when a zone is to
be edited by hand. The default is ``relative``.
-``max-recursion-depth``
+.. namedconf:statement:: max-recursion-depth
+
This sets the maximum number of levels of recursion that are permitted at
any one time while servicing a recursive query. Resolving a name may
require looking up a name server address, which in turn requires
this value, the recursive query is terminated and returns SERVFAIL.
The default is 7.
-``max-recursion-queries``
+.. namedconf:statement:: max-recursion-queries
+
This sets the maximum number of iterative queries that may be sent while
servicing a recursive query. If more queries are sent, the recursive
query is terminated and returns SERVFAIL. The default is 100.
-``notify-delay``
+.. namedconf:statement:: notify-delay
+
This sets the delay, in seconds, between sending sets of NOTIFY messages
for a zone. Whenever a NOTIFY message is sent for a zone, a timer will
be set for this duration. If the zone is updated again before the timer
The overall rate at which NOTIFY messages are sent for all zones is
controlled by ``notify-rate``.
-``max-rsa-exponent-size``
+.. namedconf:statement:: max-rsa-exponent-size
+
This sets the maximum RSA exponent size, in bits, that is accepted when
validating. Valid values are 35 to 4096 bits. The default, zero, is
also accepted and is equivalent to 4096.
-``prefetch``
+.. namedconf:statement:: prefetch
+
When a query is received for cached data which is to expire shortly,
:iscman:`named` can refresh the data from the authoritative server
immediately, ensuring that the cache always has an answer available.
seconds longer than the trigger TTL; if not, :iscman:`named`
silently adjusts it upward. The default eligibility TTL is ``9``.
-``v6-bias``
+.. namedconf:statement:: v6-bias
+
When determining the next name server to try, this indicates by how many
milliseconds to prefer IPv6 name servers. The default is ``50``
milliseconds.
-``tcp-receive-buffer``; ``udp-receive-buffer``
+.. namedconf:statement:: tcp-receive-buffer
+.. namedconf:statement:: udp-receive-buffer
+
These options control the operating system's receive buffer sizes
(``SO_RCVBUF``) for TCP and UDP sockets, respectively. Buffering at
the operating system level can prevent packet drops during brief load
is determined by the kernel, and values exceeding the maximum are
silently reduced.
-``tcp-send-buffer``; ``udp-send-buffer``
+.. namedconf:statement:: tcp-send-buffer
+.. namedconf:statement:: udp-send-buffer
+
These options control the operating system's send buffer sizes
(``SO_SNDBUF``) for TCP and UDP sockets, respectively. Buffering at
the operating system level can prevent packet drops during brief load
built-in ``CHAOS`` view by defining an explicit view of class ``CHAOS``
that matches all clients.
-``version``
+.. namedconf:statement:: version
+
This is the version the server should report via a query of the name
``version.bind`` with type ``TXT`` and class ``CHAOS``. The default is
the real version number of this server. Specifying ``version none``
Setting ``version`` to any value (including ``none``) also disables
queries for ``authors.bind TXT CH``.
-``hostname``
+.. namedconf:statement:: hostname
+
This is the hostname the server should report via a query of the name
``hostname.bind`` with type ``TXT`` and class ``CHAOS``. This defaults
to the hostname of the machine hosting the name server, as found by
the queries. Specifying ``hostname none;`` disables processing of
the queries.
-``server-id``
+.. namedconf:statement:: server-id
+
This is the ID the server should report when receiving a Name Server
Identifier (NSID) query, or a query of the name ``ID.SERVER`` with
type ``TXT`` and class ``CHAOS``. The primary purpose of such queries is
all built-in empty zones. This enables them to return referrals
to deeper in the tree.
-``empty-server``
+.. namedconf:statement:: empty-server
+
This specifies the server name that appears in the returned SOA record for
empty zones. If none is specified, the zone's name is used.
-``empty-contact``
+.. namedconf:statement:: empty-contact
+
This specifies the contact name that appears in the returned SOA record for
empty zones. If none is specified, "." is used.
.. _empty-zones-enable:
-``empty-zones-enable``
+.. namedconf:statement:: empty-zones-enable
+
This enables or disables all empty zones. By default, they are enabled.
.. _disable-empty-zone:
-``disable-empty-zone``
+.. namedconf:statement:: disable-empty-zone
+
This disables individual empty zones. By default, none are disabled. This
option can be specified multiple times.
Content Filtering
^^^^^^^^^^^^^^^^^
-BIND 9 provides the ability to filter out responses from external
-DNS servers containing certain types of data in the answer section.
-Specifically, it can reject address (A or AAAA) records if the
-corresponding IPv4 or IPv6 addresses match the given
-``address_match_list`` of the ``deny-answer-addresses`` option. It can
-also reject CNAME or DNAME records if the "alias" name (i.e., the CNAME
-alias or the substituted query name due to DNAME) matches the given
-``namelist`` of the ``deny-answer-aliases`` option, where "match" means
-the alias name is a subdomain of one of the ``name_list`` elements. If
-the optional ``namelist`` is specified with ``except-from``, records
-whose query name matches the list are accepted regardless of the
-filter setting. Likewise, if the alias name is a subdomain of the
-corresponding zone, the ``deny-answer-aliases`` filter does not apply;
-for example, even if "example.com" is specified for
-``deny-answer-aliases``,
+.. namedconf:statement:: deny-answer-addresses
-::
+ BIND 9 provides the ability to filter out responses from external
+ DNS servers containing certain types of data in the answer section.
+ Specifically, it can reject address (A or AAAA) records if the
+ corresponding IPv4 or IPv6 addresses match the given
+ ``address_match_list`` of the ``deny-answer-addresses`` option.
+
+ In the ``address_match_list`` of the ``deny-answer-addresses`` option,
+ only ``ip_addr`` and ``ip_prefix`` are meaningful; any ``key_id`` is
+ silently ignored.
- www.example.com. CNAME xxx.example.com.
-returned by an "example.com" server is accepted.
+.. namedconf:statement:: deny-answer-aliases
-In the ``address_match_list`` of the ``deny-answer-addresses`` option,
-only ``ip_addr`` and ``ip_prefix`` are meaningful; any ``key_id`` is
-silently ignored.
+ It can
+ also reject CNAME or DNAME records if the "alias" name (i.e., the CNAME
+ alias or the substituted query name due to DNAME) matches the given
+ ``namelist`` of the ``deny-answer-aliases`` option, where "match" means
+ the alias name is a subdomain of one of the ``name_list`` elements. If
+ the optional ``namelist`` is specified with ``except-from``, records
+ whose query name matches the list are accepted regardless of the
+ filter setting. Likewise, if the alias name is a subdomain of the
+ corresponding zone, the ``deny-answer-aliases`` filter does not apply;
+ for example, even if "example.com" is specified for
+ ``deny-answer-aliases``,
+
+ ::
+
+ www.example.com. CNAME xxx.example.com.
+
+ returned by an "example.com" server is accepted.
If a response message is rejected due to the filtering, the entire
message is discarded without being cached, and a SERVFAIL error is
deny the existence of domains (NXDOMAIN), deny the existence of IP
addresses for domains (NODATA), or contain other IP addresses or data.
-Response policy zones are named in the ``response-policy`` option for
-the view, or among the global options if there is no ``response-policy``
-option for the view. Response policy zones are ordinary DNS zones
-containing RRsets that can be queried normally if allowed. It is usually
-best to restrict those queries with something like
-``allow-query { localhost; };``.
+.. namedconf:statement:: response-policy
-A ``response-policy`` option can support multiple policy zones. To
-maximize performance, a radix tree is used to quickly identify response
-policy zones containing triggers that match the current query. This
-imposes an upper limit of 64 on the number of policy zones in a single
-``response-policy`` option; more than that is a configuration error.
+ Response policy zones are named in the ``response-policy`` option for
+ the view, or among the global options if there is no ``response-policy``
+ option for the view. Response policy zones are ordinary DNS zones
+ containing RRsets that can be queried normally if allowed. It is usually
+ best to restrict those queries with something like
+ ``allow-query { localhost; };``.
+
+ A ``response-policy`` option can support multiple policy zones. To
+ maximize performance, a radix tree is used to quickly identify response
+ policy zones containing triggers that match the current query. This
+ imposes an upper limit of 64 on the number of policy zones in a single
+ ``response-policy`` option; more than that is a configuration error.
Rules encoded in response policy zones are processed after those defined in
:ref:`access_control`. All queries from clients which are not permitted access
such as SERVFAIL to appear to be rewritten, since no recursion is being
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 :iscman:`named` using
-``configure --enable-dnsrps``.
-
-The ``dnsrps-options`` block provides additional RPZ configuration
-settings, which are passed through to the DNSRPS provider library.
-Multiple DNSRPS settings in an ``dnsrps-options`` string should be
-separated with semi-colons (;). The DNSRPS provider, librpz, is passed a
-configuration string consisting of the ``dnsrps-options`` text,
-concatenated with settings derived from the ``response-policy``
-statement.
-
-Note: the ``dnsrps-options`` text should only include configuration
-settings that are specific to the DNSRPS provider. For example, the
-DNSRPS provider from Farsight Security takes options such as
-``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 :iscman:`named` were switched back to traditional RPZ by setting
-``dnsrps-enable`` to "no", those options would be ignored.
+.. namedconf:statement:: dnsrps-enable
+
+ The ``dnsrps-enable yes`` option turns on the DNS Response Policy Service
+ (DNSRPS) interface, if it has been compiled in :iscman:`named` using
+ ``configure --enable-dnsrps``.
+
+.. namedconf:statement:: dnsrps-options
+
+ The block provides additional RPZ configuration
+ settings, which are passed through to the DNSRPS provider library.
+ Multiple DNSRPS settings in an ``dnsrps-options`` string should be
+ separated with semi-colons (;). The DNSRPS provider, librpz, is passed a
+ configuration string consisting of the ``dnsrps-options`` text,
+ concatenated with settings derived from the ``response-policy``
+ statement.
+
+ Note: the ``dnsrps-options`` text should only include configuration
+ settings that are specific to the DNSRPS provider. For example, the
+ DNSRPS provider from Farsight Security takes options such as
+ ``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 :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
relevant record in the policy zone. It is then limited to a maximum value.
Response Rate Limiting
^^^^^^^^^^^^^^^^^^^^^^
-Excessive, almost-identical UDP *responses* can be controlled by
-configuring a ``rate-limit`` clause in an ``options`` or ``view``
-statement. This mechanism keeps authoritative BIND 9 from being used to
-amplify reflection denial-of-service (DoS) attacks. Short BADCOOKIE errors or
-truncated (TC=1) responses can be sent to provide rate-limited responses to
-legitimate clients within a range of forged, attacked IP addresses.
-Legitimate clients react to dropped responses by retrying,
-to BADCOOKIE errors by including a server cookie when retrying,
-and to truncated responses by switching to TCP.
-
-This mechanism is intended for authoritative DNS servers. It can be used
-on recursive servers, but can slow applications such as SMTP servers
-(mail receivers) and HTTP clients (web browsers) that repeatedly request
-the same domains. When possible, closing "open" recursive servers is
-better.
-
-Response rate limiting uses a "credit" or "token bucket" scheme. Each
-combination of identical response and client has a conceptual "account"
-that earns a specified number of credits every second. A prospective
-response debits its account by one. Responses are dropped or truncated
-while the account is negative. Responses are tracked within a rolling
-window of time which defaults to 15 seconds, but which can be configured with
-the ``window`` option to any value from 1 to 3600 seconds (1 hour). The
-account cannot become more positive than the per-second limit or more
-negative than ``window`` times the per-second limit. When the specified
-number of credits for a class of responses is set to 0, those responses
-are not rate-limited.
-
-The notions of "identical response" and "DNS client" for rate limiting
-are not simplistic. All responses to an address block are counted as if
-to a single client. The prefix lengths of address blocks are specified
-with ``ipv4-prefix-length`` (default 24) and ``ipv6-prefix-length``
-(default 56).
-
-All non-empty responses for a valid domain name (qname) and record type
-(qtype) are identical and have a limit specified with
-``responses-per-second`` (default 0 or no limit). All empty (NODATA)
-responses for a valid domain, regardless of query type, are identical.
-Responses in the NODATA class are limited by ``nodata-per-second``
-(default ``responses-per-second``). Requests for any and all undefined
-subdomains of a given valid domain result in NXDOMAIN errors, and are
-identical regardless of query type. They are limited by
-``nxdomains-per-second`` (default ``responses-per-second``). This
-controls some attacks using random names, but can be relaxed or turned
-off (set to 0) on servers that expect many legitimate NXDOMAIN
-responses, such as from anti-spam rejection lists. Referrals or delegations
-to the server of a given domain are identical and are limited by
-``referrals-per-second`` (default ``responses-per-second``).
-
-Responses generated from local wildcards are counted and limited as if
-they were for the parent domain name. This controls flooding using
-random.wild.example.com.
-
-All requests that result in DNS errors other than NXDOMAIN, such as
-SERVFAIL and FORMERR, are identical regardless of requested name (qname)
-or record type (qtype). This controls attacks using invalid requests or
-distant, broken authoritative servers. By default the limit on errors is
-the same as the ``responses-per-second`` value, but it can be set
-separately with ``errors-per-second``.
-
-Many attacks using DNS involve UDP requests with forged source
-addresses. Rate limiting prevents the use of BIND 9 to flood a network
-with responses to requests with forged source addresses, but could let a
-third party block responses to legitimate requests. There is a mechanism
-that can answer some legitimate requests from a client whose address is
-being forged in a flood. Setting ``slip`` to 2 (its default) causes
-every other UDP request without a valid server cookie to be answered with
-a small response. The small size and reduced frequency, and resulting lack of
-amplification, of "slipped" responses make them unattractive for
-reflection DoS attacks. ``slip`` must be between 0 and 10. A value of 0
-does not "slip"; no small responses are sent due to rate limiting. Rather,
-all responses are dropped. A value of 1 causes every response to slip;
-values between 2 and 10 cause every nth response to slip.
-
-If the request included a client cookie, then a "slipped" response is
-a BADCOOKIE error with a server cookie, which allows a legitimate client
-to include the server cookie to be exempted from the rate limiting
-when it retries the request.
-If the request did not include a cookie, then a "slipped" response is
-a truncated (TC=1) response, which prompts a legitimate client to
-switch to TCP and thus be exempted from the rate limiting. Some error
-responses, including REFUSED and SERVFAIL, cannot be replaced with
-truncated responses and are instead leaked at the ``slip`` rate.
-
-(Note: dropped responses from an authoritative server may reduce the
-difficulty of a third party successfully forging a response to a
-recursive resolver. The best security against forged responses is for
-authoritative operators to sign their zones using DNSSEC and for
-resolver operators to validate the responses. When this is not an
-option, operators who are more concerned with response integrity than
-with flood mitigation may consider setting ``slip`` to 1, causing all
-rate-limited responses to be truncated rather than dropped. This reduces
-the effectiveness of rate-limiting against reflection attacks.)
-
-When the approximate query-per-second rate exceeds the ``qps-scale``
-value, the ``responses-per-second``, ``errors-per-second``,
-``nxdomains-per-second``, and ``all-per-second`` values are reduced by
-the ratio of the current rate to the ``qps-scale`` value. This feature
-can tighten defenses during attacks. For example, with
-``qps-scale 250; responses-per-second 20;`` and a total query rate of
-1000 queries/second for all queries from all DNS clients including via
-TCP, then the effective responses/second limit changes to (250/1000)*20,
-or 5. Responses to requests that included a valid server cookie,
-and responses sent via TCP, are not limited but are counted to compute
-the query-per-second rate.
-
-Communities of DNS clients can be given their own parameters or no
-rate limiting by putting ``rate-limit`` statements in ``view`` statements
-instead of in the global ``option`` statement. A ``rate-limit`` statement
-in a view replaces, rather than supplements, a ``rate-limit``
-statement among the main options. DNS clients within a view can be
-exempted from rate limits with the ``exempt-clients`` clause.
-
-UDP responses of all kinds can be limited with the ``all-per-second``
-phrase. This rate limiting is unlike the rate limiting provided by
-``responses-per-second``, ``errors-per-second``, and
-``nxdomains-per-second`` on a DNS server, which are often invisible to
-the victim of a DNS reflection attack. Unless the forged requests of the
-attack are the same as the legitimate requests of the victim, the
-victim's requests are not affected. Responses affected by an
-``all-per-second`` limit are always dropped; the ``slip`` value has no
-effect. An ``all-per-second`` limit should be at least 4 times as large
-as the other limits, because single DNS clients often send bursts of
-legitimate requests. For example, the receipt of a single mail message
-can prompt requests from an SMTP server for NS, PTR, A, and AAAA records
-as the incoming SMTP/TCP/IP connection is considered. The SMTP server
-can need additional NS, A, AAAA, MX, TXT, and SPF records as it
-considers the SMTP ``Mail From`` command. Web browsers often repeatedly
-resolve the same names that are duplicated in HTML <IMG> tags in a page.
-``all-per-second`` is similar to the rate limiting offered by firewalls
-but is often inferior. Attacks that justify ignoring the contents of DNS
-responses are likely to be attacks on the DNS server itself. They
-usually should be discarded before the DNS server spends resources making
-TCP connections or parsing DNS requests, but that rate limiting must be
-done before the DNS server sees the requests.
-
-The maximum size of the table used to track requests and rate-limit
-responses is set with ``max-table-size``. Each entry in the table is
-between 40 and 80 bytes. The table needs approximately as many entries
-as the number of requests received per second. The default is 20,000. To
-reduce the cold start of growing the table, ``min-table-size`` (default 500)
-can set the minimum table size. Enable ``rate-limit`` category
-logging to monitor expansions of the table and inform choices for the
-initial and maximum table size.
-
-Use ``log-only yes`` to test rate-limiting parameters without actually
-dropping any requests.
-
-Responses dropped by rate limits are included in the ``RateDropped`` and
-``QryDropped`` statistics. Responses that are truncated by rate limits are
-included in ``RateSlipped`` and ``RespTruncated``.
+.. namedconf:statement:: rate-limit
+
+ Excessive, almost-identical UDP *responses* can be controlled by
+ configuring a ``rate-limit`` clause in an ``options`` or ``view``
+ statement. This mechanism keeps authoritative BIND 9 from being used to
+ amplify reflection denial-of-service (DoS) attacks. Short BADCOOKIE errors or
+ truncated (TC=1) responses can be sent to provide rate-limited responses to
+ legitimate clients within a range of forged, attacked IP addresses.
+ Legitimate clients react to dropped responses by retrying,
+ to BADCOOKIE errors by including a server cookie when retrying,
+ and to truncated responses by switching to TCP.
+
+ This mechanism is intended for authoritative DNS servers. It can be used
+ on recursive servers, but can slow applications such as SMTP servers
+ (mail receivers) and HTTP clients (web browsers) that repeatedly request
+ the same domains. When possible, closing "open" recursive servers is
+ better.
+
+ Response rate limiting uses a "credit" or "token bucket" scheme. Each
+ combination of identical response and client has a conceptual "account"
+ that earns a specified number of credits every second. A prospective
+ response debits its account by one. Responses are dropped or truncated
+ while the account is negative.
+
+ .. namedconf:statement:: window
+
+ Responses are tracked within a rolling
+ window of time which defaults to 15 seconds, but which can be configured with
+ the ``window`` option to any value from 1 to 3600 seconds (1 hour). The
+ account cannot become more positive than the per-second limit or more
+ negative than ``window`` times the per-second limit. When the specified
+ number of credits for a class of responses is set to 0, those responses
+ are not rate-limited.
+
+ .. namedconf:statement:: ipv4-prefix-length
+ .. namedconf:statement:: ipv6-prefix-length
+
+ The notions of "identical response" and "DNS client" for rate limiting
+ are not simplistic. All responses to an address block are counted as if
+ to a single client. The prefix lengths of address blocks are specified
+ with ``ipv4-prefix-length`` (default 24) and ``ipv6-prefix-length``
+ (default 56).
+
+ .. namedconf:statement:: responses-per-second
+
+ All non-empty responses for a valid domain name (qname) and record type
+ (qtype) are identical and have a limit specified with
+ ``responses-per-second`` (default 0 or no limit).
+
+ .. namedconf:statement:: nodata-per-second
+
+ All empty (NODATA)
+ responses for a valid domain, regardless of query type, are identical.
+ Responses in the NODATA class are limited by ``nodata-per-second``
+ (default ``responses-per-second``).
+
+ .. namedconf:statement:: nxdomains-per-second
+
+ Requests for any and all undefined
+ subdomains of a given valid domain result in NXDOMAIN errors, and are
+ identical regardless of query type. They are limited by
+ ``nxdomains-per-second`` (default ``responses-per-second``). This
+ controls some attacks using random names, but can be relaxed or turned
+ off (set to 0) on servers that expect many legitimate NXDOMAIN
+ responses, such as from anti-spam rejection lists.
+
+ .. namedconf:statement:: referrals-per-second
+
+ Referrals or delegations
+ to the server of a given domain are identical and are limited by
+ ``referrals-per-second`` (default ``responses-per-second``).
+
+ Responses generated from local wildcards are counted and limited as if
+ they were for the parent domain name. This controls flooding using
+ random.wild.example.com.
+
+ All requests that result in DNS errors other than NXDOMAIN, such as
+ SERVFAIL and FORMERR, are identical regardless of requested name (qname)
+ or record type (qtype). This controls attacks using invalid requests or
+ distant, broken authoritative servers.
+
+
+ .. namedconf:statement:: errors-per-second
+
+ By default the limit on errors is
+ the same as the ``responses-per-second`` value, but it can be set
+ separately with ``errors-per-second``.
+
+ .. namedconf:statement:: slip
+
+ Many attacks using DNS involve UDP requests with forged source
+ addresses. Rate limiting prevents the use of BIND 9 to flood a network
+ with responses to requests with forged source addresses, but could let a
+ third party block responses to legitimate requests. There is a mechanism
+ that can answer some legitimate requests from a client whose address is
+ being forged in a flood. Setting ``slip`` to 2 (its default) causes
+ every other UDP request without a valid server cookie to be answered with
+ a small response. The small size and reduced frequency, and resulting lack of
+ amplification, of "slipped" responses make them unattractive for
+ reflection DoS attacks. ``slip`` must be between 0 and 10. A value of 0
+ does not "slip"; no small responses are sent due to rate limiting. Rather,
+ all responses are dropped. A value of 1 causes every response to slip;
+ values between 2 and 10 cause every nth response to slip.
+
+ If the request included a client cookie, then a "slipped" response is
+ a BADCOOKIE error with a server cookie, which allows a legitimate client
+ to include the server cookie to be exempted from the rate limiting
+ when it retries the request.
+ If the request did not include a cookie, then a "slipped" response is
+ a truncated (TC=1) response, which prompts a legitimate client to
+ switch to TCP and thus be exempted from the rate limiting. Some error
+ responses, including REFUSED and SERVFAIL, cannot be replaced with
+ truncated responses and are instead leaked at the ``slip`` rate.
+
+ (Note: dropped responses from an authoritative server may reduce the
+ difficulty of a third party successfully forging a response to a
+ recursive resolver. The best security against forged responses is for
+ authoritative operators to sign their zones using DNSSEC and for
+ resolver operators to validate the responses. When this is not an
+ option, operators who are more concerned with response integrity than
+ with flood mitigation may consider setting ``slip`` to 1, causing all
+ rate-limited responses to be truncated rather than dropped. This reduces
+ the effectiveness of rate-limiting against reflection attacks.)
+
+ .. namedconf:statement:: qps-scale
+
+ When the approximate query-per-second rate exceeds the ``qps-scale``
+ value, the ``responses-per-second``, ``errors-per-second``,
+ ``nxdomains-per-second``, and ``all-per-second`` values are reduced by
+ the ratio of the current rate to the ``qps-scale`` value. This feature
+ can tighten defenses during attacks. For example, with
+ ``qps-scale 250; responses-per-second 20;`` and a total query rate of
+ 1000 queries/second for all queries from all DNS clients including via
+ TCP, then the effective responses/second limit changes to (250/1000)*20,
+ or 5. Responses to requests that included a valid server cookie,
+ and responses sent via TCP, are not limited but are counted to compute
+ the query-per-second rate.
+
+ .. namedconf:statement:: exempt-clients
+
+ Communities of DNS clients can be given their own parameters or no
+ rate limiting by putting ``rate-limit`` statements in ``view`` statements
+ instead of in the global ``option`` statement. A ``rate-limit`` statement
+ in a view replaces, rather than supplements, a ``rate-limit``
+ statement among the main options.
+
+ DNS clients within a view can be
+ exempted from rate limits with the ``exempt-clients`` clause.
+
+ .. namedconf:statement:: all-per-second
+
+ UDP responses of all kinds can be limited with the ``all-per-second``
+ phrase. This rate limiting is unlike the rate limiting provided by
+ ``responses-per-second``, ``errors-per-second``, and
+ ``nxdomains-per-second`` on a DNS server, which are often invisible to
+ the victim of a DNS reflection attack. Unless the forged requests of the
+ attack are the same as the legitimate requests of the victim, the
+ victim's requests are not affected. Responses affected by an
+ ``all-per-second`` limit are always dropped; the ``slip`` value has no
+ effect. An ``all-per-second`` limit should be at least 4 times as large
+ as the other limits, because single DNS clients often send bursts of
+ legitimate requests. For example, the receipt of a single mail message
+ can prompt requests from an SMTP server for NS, PTR, A, and AAAA records
+ as the incoming SMTP/TCP/IP connection is considered. The SMTP server
+ can need additional NS, A, AAAA, MX, TXT, and SPF records as it
+ considers the SMTP ``Mail From`` command. Web browsers often repeatedly
+ resolve the same names that are duplicated in HTML <IMG> tags in a page.
+ ``all-per-second`` is similar to the rate limiting offered by firewalls
+ but is often inferior. Attacks that justify ignoring the contents of DNS
+ responses are likely to be attacks on the DNS server itself. They
+ usually should be discarded before the DNS server spends resources making
+ TCP connections or parsing DNS requests, but that rate limiting must be
+ done before the DNS server sees the requests.
+
+
+ .. namedconf:statement:: max-table-size
+ .. namedconf:statement:: min-table-size
+
+ The maximum size of the table used to track requests and rate-limit
+ responses is set with ``max-table-size``. Each entry in the table is
+ between 40 and 80 bytes. The table needs approximately as many entries
+ as the number of requests received per second. The default is 20,000. To
+ reduce the cold start of growing the table, ``min-table-size`` (default 500)
+ can set the minimum table size. Enable ``rate-limit`` category
+ logging to monitor expansions of the table and inform choices for the
+ initial and maximum table size.
+
+ .. namedconf:statement:: log-only
+
+ Use ``log-only yes`` to test rate-limiting parameters without actually
+ dropping any requests.
+
+ Responses dropped by rate limits are included in the ``RateDropped`` and
+ ``QryDropped`` statistics. Responses that are truncated by rate limits are
+ included in ``RateSlipped`` and ``RespTruncated``.
NXDOMAIN Redirection
^^^^^^^^^^^^^^^^^^^^
the normal namespace. All the redirect information is contained in the
zone; there are no delegations.
-With a redirect namespace (``option { nxdomain-redirect <suffix> };``),
-the data used to replace the NXDOMAIN is part of the normal namespace
-and is looked up by appending the specified suffix to the original
-query name. This roughly doubles the cache required to process
-NXDOMAIN responses, as both the original NXDOMAIN response and the
-replacement data (or an NXDOMAIN indicating that there is no
-replacement) must be stored.
+.. namedconf:statement:: nxdomain-redirect
+
+ With a redirect namespace (``option { nxdomain-redirect <suffix> };``),
+ the data used to replace the NXDOMAIN is part of the normal namespace
+ and is looked up by appending the specified suffix to the original
+ query name. This roughly doubles the cache required to process
+ NXDOMAIN responses, as both the original NXDOMAIN response and the
+ replacement data (or an NXDOMAIN indicating that there is no
+ replacement) must be stored.
If both a redirect zone and a redirect namespace are configured, the
redirect zone is tried first.
``server`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: server
.. include:: ../misc/server.grammar.rst
top-level ones are ignored. If a view contains no ``server`` statements,
any top-level ``server`` statements are used as defaults.
-If a remote server is giving out bad data, marking it
-as bogus prevents further queries to it. The default value of
-``bogus`` is ``no``.
-
-The ``provide-ixfr`` clause determines whether the local server, acting
-as primary, responds with an incremental zone transfer when the given
-remote server, a secondary, requests it. If set to ``yes``, incremental
-transfer is provided whenever possible. If set to ``no``, all
-transfers to the remote server are non-incremental. If not set, the
-value of the ``provide-ixfr`` option in the view or global options block
-is used as a default.
-
-The ``request-ixfr`` clause determines whether the local server, acting
-as a secondary, requests incremental zone transfers from the given
-remote server, a primary. If not set, the value of the ``request-ixfr``
-option in the view or global options block is used as a default. It may
-also be set in the zone block; if set there, it overrides the
-global or view setting for that zone.
-
-IXFR requests to servers that do not support IXFR automatically
-fall back to AXFR. Therefore, there is no need to manually list which
-servers support IXFR and which ones do not; the global default of
-``yes`` should always work. The purpose of the ``provide-ixfr`` and
-``request-ixfr`` clauses is to make it possible to disable the use of
-IXFR even when both primary and secondary claim to support it: for example, if
-one of the servers is buggy and crashes or corrupts data when IXFR is
-used.
-
-The ``request-expire`` clause determines whether the local server, when
-acting as a secondary, requests the EDNS EXPIRE value. The EDNS EXPIRE
-value indicates the remaining time before the zone data expires and
-needs to be refreshed. This is used when a secondary server transfers
-a zone from another secondary server; when transferring from the
-primary, the expiration timer is set from the EXPIRE field of the SOA
-record instead. The default is ``yes``.
-
-The ``edns`` clause determines whether the local server attempts to
-use EDNS when communicating with the remote server. The default is
-``yes``.
-
-The ``edns-udp-size`` option sets the EDNS UDP size that is advertised
-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; :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
-the ``options``/``view`` behavior in future releases.
-
-The ``edns-version`` option sets the maximum EDNS VERSION that is
-sent to the server(s) by the resolver. The actual EDNS version sent is
-still subject to normal EDNS version-negotiation rules (see :rfc:`6891`),
-the maximum EDNS version supported by the server, and any other
-heuristics that indicate that a lower version should be sent. This
-option is intended to be used when a remote server reacts badly to a
-given EDNS version or higher; it should be set to the highest version
-the remote server is known to support. Valid values are 0 to 255; higher
-values are silently adjusted. This option is not needed until
-higher EDNS versions than 0 are in use.
-
-The ``max-udp-size`` option sets the maximum EDNS UDP message size
-: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
-:iscman:`named`.
-The ``padding`` option adds EDNS Padding options to outgoing messages,
-increasing the packet size to a multiple of the specified block size.
-Valid block sizes range from 0 (the default, which disables the use of
-EDNS Padding) to 512 bytes. Larger values are reduced to 512, with a
-logged warning. Note: this option is not currently compatible with no
-TSIG or SIG(0), as the EDNS OPT record containing the padding would have
-to be added to the packet after it had already been signed.
-
-The ``tcp-only`` option sets the transport protocol to TCP. The default
-is to use the UDP transport and to fallback on TCP only when a truncated
-response is received.
-
-The ``tcp-keepalive`` option adds EDNS TCP keepalive to messages sent
-over TCP. Note that currently idle timeouts in responses are ignored.
-
-The server supports two zone transfer methods. The first,
-``one-answer``, uses one DNS message per resource record transferred.
-``many-answers`` packs as many resource records as possible into a single
-message, which is more efficient.
-It is possible to specify which method to use for a server via the
-``transfer-format`` option; if not set there, the
-``transfer-format`` specified by the ``options`` statement is used.
-
-``transfers`` is used to limit the number of concurrent inbound zone
-transfers from the specified server. If no ``transfers`` clause is
-specified, the limit is set according to the ``transfers-per-ns``
-option.
-
-The ``keys`` clause identifies a ``key_id`` defined by the ``key``
-statement, to be used for transaction security (see :ref:`tsig`)
-when talking to the remote server. When a request is sent to the remote
-server, a request signature is generated using the key specified
-here and appended to the message. A request originating from the remote
-server is not required to be signed by this key.
-
-Only a single key per server is currently supported.
-
-The ``transfer-source`` and ``transfer-source-v6`` clauses specify the
-IPv4 and IPv6 source address, respectively, to be used for zone transfer with the
-remote server. For an IPv4 remote server, only
-``transfer-source`` can be specified. Similarly, for an IPv6 remote
-server, only ``transfer-source-v6`` can be specified. For more details,
-see the description of ``transfer-source`` and ``transfer-source-v6`` in
-:ref:`zone_transfers`.
-
-The ``notify-source`` and ``notify-source-v6`` clauses specify the IPv4
-and IPv6 source address, respectively, to be used for notify messages sent to remote
-servers. For an IPv4 remote server, only ``notify-source``
-can be specified. Similarly, for an IPv6 remote server, only
-``notify-source-v6`` can be specified.
-
-The ``query-source`` and ``query-source-v6`` clauses specify the IPv4
-and IPv6 source address, respectively, to be used for queries sent to remote servers.
-For an IPv4 remote server, only ``query-source`` can be
-specified. Similarly, for an IPv6 remote server, only
-``query-source-v6`` can be specified.
-
-The ``request-nsid`` clause determines whether the local server adds
-an NSID EDNS option to requests sent to the server. This overrides
-``request-nsid`` set at the view or option level.
-
-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 :iscman:`named` server
-may determine that COOKIE is not supported by the remote server and not
-add a COOKIE EDNS option to requests.
+.. namedconf:statement:: bogus
+
+ If a remote server is giving out bad data, marking it
+ as bogus prevents further queries to it. The default value of
+ ``bogus`` is ``no``.
+
+.. namedconf:statement:: provide-ixfr
+
+ The ``provide-ixfr`` clause determines whether the local server, acting
+ as primary, responds with an incremental zone transfer when the given
+ remote server, a secondary, requests it. If set to ``yes``, incremental
+ transfer is provided whenever possible. If set to ``no``, all
+ transfers to the remote server are non-incremental. If not set, the
+ value of the ``provide-ixfr`` option in the view or global options block
+ is used as a default.
+
+.. namedconf:statement:: request-ixfr
+
+ The ``request-ixfr`` clause determines whether the local server, acting
+ as a secondary, requests incremental zone transfers from the given
+ remote server, a primary. If not set, the value of the ``request-ixfr``
+ option in the view or global options block is used as a default. It may
+ also be set in the zone block; if set there, it overrides the
+ global or view setting for that zone.
+
+ IXFR requests to servers that do not support IXFR automatically
+ fall back to AXFR. Therefore, there is no need to manually list which
+ servers support IXFR and which ones do not; the global default of
+ ``yes`` should always work. The purpose of the ``provide-ixfr`` and
+ ``request-ixfr`` clauses is to make it possible to disable the use of
+ IXFR even when both primary and secondary claim to support it: for example, if
+ one of the servers is buggy and crashes or corrupts data when IXFR is
+ used.
+
+.. namedconf:statement:: request-expire
+
+ The ``request-expire`` clause determines whether the local server, when
+ acting as a secondary, requests the EDNS EXPIRE value. The EDNS EXPIRE
+ value indicates the remaining time before the zone data expires and
+ needs to be refreshed. This is used when a secondary server transfers
+ a zone from another secondary server; when transferring from the
+ primary, the expiration timer is set from the EXPIRE field of the SOA
+ record instead. The default is ``yes``.
+
+.. namedconf:statement:: edns
+
+ The ``edns`` clause determines whether the local server attempts to
+ use EDNS when communicating with the remote server. The default is
+ ``yes``.
+
+.. namedconf:statement:: edns-udp-size
+
+ The ``edns-udp-size`` option sets the EDNS UDP size that is advertised
+ 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; :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
+ the ``options``/``view`` behavior in future releases.
+
+.. namedconf:statement:: edns-version
+
+ The ``edns-version`` option sets the maximum EDNS VERSION that is
+ sent to the server(s) by the resolver. The actual EDNS version sent is
+ still subject to normal EDNS version-negotiation rules (see :rfc:`6891`),
+ the maximum EDNS version supported by the server, and any other
+ heuristics that indicate that a lower version should be sent. This
+ option is intended to be used when a remote server reacts badly to a
+ given EDNS version or higher; it should be set to the highest version
+ the remote server is known to support. Valid values are 0 to 255; higher
+ values are silently adjusted. This option is not needed until
+ higher EDNS versions than 0 are in use.
+
+.. namedconf:statement:: max-udp-size
+
+ The option sets the maximum EDNS UDP message size
+ :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
+ :iscman:`named`.
+
+.. namedconf:statement:: padding
+
+ The option adds EDNS Padding options to outgoing messages,
+ increasing the packet size to a multiple of the specified block size.
+ Valid block sizes range from 0 (the default, which disables the use of
+ EDNS Padding) to 512 bytes. Larger values are reduced to 512, with a
+ logged warning. Note: this option is not currently compatible with no
+ TSIG or SIG(0), as the EDNS OPT record containing the padding would have
+ to be added to the packet after it had already been signed.
+
+.. namedconf:statement:: tcp-only
+
+ The option sets the transport protocol to TCP. The default
+ is to use the UDP transport and to fallback on TCP only when a truncated
+ response is received.
+
+.. namedconf:statement:: tcp-keepalive
+
+ The option adds EDNS TCP keepalive to messages sent
+ over TCP. Note that currently idle timeouts in responses are ignored.
+
+.. namedconf:statement:: transfer-format
+
+ The server supports two zone transfer methods. The first,
+ ``one-answer``, uses one DNS message per resource record transferred.
+ ``many-answers`` packs as many resource records as possible into a single
+ message, which is more efficient.
+ It is possible to specify which method to use for a server via the
+ ``transfer-format`` option; if not set there, the
+ ``transfer-format`` specified by the ``options`` statement is used.
+
+.. namedconf:statement:: transfers
+
+ ``transfers`` is used to limit the number of concurrent inbound zone
+ transfers from the specified server. If no ``transfers`` clause is
+ specified, the limit is set according to the ``transfers-per-ns``
+ option.
+
+.. namedconf:statement:: keys
+
+ The option identifies a ``key_id`` defined by the ``key``
+ statement, to be used for transaction security (see :ref:`tsig`)
+ when talking to the remote server. When a request is sent to the remote
+ server, a request signature is generated using the key specified
+ here and appended to the message. A request originating from the remote
+ server is not required to be signed by this key.
+
+ Only a single key per server is currently supported.
+
+.. namedconf:statement:: transfer-source
+.. namedconf:statement:: transfer-source-v6
+
+ The ``transfer-source`` and ``transfer-source-v6`` clauses specify the
+ IPv4 and IPv6 source address, respectively, to be used for zone transfer with the
+ remote server. For an IPv4 remote server, only
+ ``transfer-source`` can be specified. Similarly, for an IPv6 remote
+ server, only ``transfer-source-v6`` can be specified. For more details,
+ see the description of ``transfer-source`` and ``transfer-source-v6`` in
+ :ref:`zone_transfers`.
+
+.. namedconf:statement:: notify-source
+.. namedconf:statement:: notify-source-v6
+
+ The ``notify-source`` and ``notify-source-v6`` clauses specify the IPv4
+ and IPv6 source address, respectively, to be used for notify messages sent to remote
+ servers. For an IPv4 remote server, only ``notify-source``
+ can be specified. Similarly, for an IPv6 remote server, only
+ ``notify-source-v6`` can be specified.
+
+.. namedconf:statement:: query-source
+.. namedconf:statement:: query-source-v6
+
+ The ``query-source`` and ``query-source-v6`` clauses specify the IPv4
+ and IPv6 source address, respectively, to be used for queries sent to remote servers.
+ For an IPv4 remote server, only ``query-source`` can be
+ specified. Similarly, for an IPv6 remote server, only
+ ``query-source-v6`` can be specified.
+
+.. namedconf:statement:: request-nsid
+
+ The ``request-nsid`` clause determines whether the local server adds
+ an NSID EDNS option to requests sent to the server. This overrides
+ ``request-nsid`` set at the view or option level.
+
+.. namedconf:statement:: send-cookie
+
+ 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 :iscman:`named` server
+ may determine that COOKIE is not supported by the remote server and not
+ add a COOKIE EDNS option to requests.
.. _statschannels:
``statistics-channels`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: statistics-channels
.. include:: ../misc/statistics-channels.grammar.rst
``tls`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: tls
.. include:: ../misc/tls.grammar.rst
The following options can be specified in a ``tls`` statement:
- ``key-file``
+.. namedconf:statement:: key-file
+
Path to a file containing the private TLS key to be used for
the connection.
- ``cert-file``
+.. namedconf:statement:: cert-file
+
Path to a file containing the TLS certificate to be used for
the connection.
- ``ca-file``
+.. namedconf:statement:: ca-file
+
Path to a file containing trusted CA-authorities TLS
certificates used to verify remote peer certificates. Specifying
this option enables remote peer certificates verification. For
connections, if ``remote-hostname`` is not specified, then the remote
server IP address is used instead.
- ``dhparam-file``
+.. namedconf:statement:: dhparam-file
+
Path to a file containing Diffie-Hellman parameters,
which is needed to enable the cipher suites depending on the
Diffie-Hellman ephemeral key exchange (DHE). Having these parameters
specified is essential for enabling perfect forward secrecy capable
ciphers in TLSv1.2.
- ``remote-hostname``
+.. namedconf:statement:: remote-hostname
+
The expected hostname in the TLS certificate of the
remote server. This option enables a remote server certificate
verification. If ``ca-file`` is not specified, then the
only and, thus, is ignored when ``tls`` statements are referenced
by ``listen-on`` or ``listen-on-v6`` statements.
- ``protocols``
+.. namedconf:statement:: protocols
+
Allowed versions of the TLS protocol. TLS version 1.2 and higher are
supported, depending on the cryptographic library in use. Multiple
versions might be specified (e.g.
``protocols { TLSv1.2; TLSv1.3; };``).
- ``ciphers``
+.. namedconf:statement:: ciphers
+
Cipher list which defines allowed ciphers, such as
``HIGH:!aNULL:!MD5:!SHA1:!SHA256:!SHA384``. The string must be
formed according to the rules specified in the OpenSSL documentation
(see https://www.openssl.org/docs/man1.1.1/man1/ciphers.html
for details).
- ``prefer-server-ciphers``
+.. namedconf:statement:: prefer-server-ciphers
+
Specifies that server ciphers should be preferred over client ones.
- ``session-tickets``
+.. namedconf:statement:: session-tickets
+
Enables or disables session resumption through TLS session tickets,
as defined in RFC5077. Disabling the stateless session tickets
might be required in the cases when forward secrecy is needed,
``http`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: http
.. include:: ../misc/http.grammar.rst
The following options can be specified in an ``http`` statement:
- ``endpoints``
+.. namedconf:statement:: endpoints
+
A list of HTTP query paths on which to listen. This is the portion
of an :rfc:`3986`-compliant URI following the hostname; it must be
an absolute path, beginning with "/". The default value
is ``"/dns-query"``, if omitted.
- ``listener-clients``
+.. namedconf:statement:: listener-clients
+
The option specifies a per-listener quota for active connections.
- ``streams-per-connection``
+.. namedconf:statement:: streams-per-connection
+
The option specifies the hard limit on the number of concurrent
HTTP/2 streams over an HTTP/2 connection.
``trust-anchors`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: trust-anchors
.. include:: ../misc/trust-anchors.grammar.rst
``dnssec-policy`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: dnssec-policy
.. include:: ../misc/dnssec-policy.grammar.rst
The following options can be specified in a ``dnssec-policy`` statement:
- ``dnskey-ttl``
+.. namedconf:statement:: dnskey-ttl
+
This indicates the TTL to use when generating DNSKEY resource
records. The default is 1 hour (3600 seconds).
- ``keys``
+.. namedconf:statement:: keys
+
This is a list specifying the algorithms and roles to use when
generating keys and signing the zone. Entries in this list do not
represent specific DNSSEC keys, which may be changed on a regular
Each KSK/ZSK pair must have the same algorithm. A CSK combines the
functionality of a ZSK and a KSK.
- ``purge-keys``
+.. namedconf:statement:: 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), :iscman:`named` will not
The default is ``P90D`` (90 days). Set this option to ``0`` to never
purge deleted keys.
- ``publish-safety``
+.. namedconf:statement:: publish-safety
+
This is a margin that is added to the pre-publication interval in
rollover timing calculations, to give some extra time to cover
unforeseen events. This increases the time between when keys are
published and when they become active. The default is ``PT1H`` (1
hour).
- ``retire-safety``
+.. namedconf:statement:: retire-safety
+
This is a margin that is added to the post-publication interval in
rollover timing calculations, to give some extra time to cover
unforeseen events. This increases the time a key remains published
after it is no longer active. The default is ``PT1H`` (1 hour).
- ``signatures-refresh``
+.. namedconf:statement:: signatures-refresh
+
This determines how frequently an RRSIG record needs to be
refreshed. The signature is renewed when the time until the
expiration time is less than the specified interval. The default is
90% of the minimum value of ``signatures-validity`` and
``signatures-validity-dnskey``.
- ``signatures-validity``
+.. namedconf:statement:: signatures-validity
+
This indicates the validity period of an RRSIG record (subject to
inception offset and jitter). The default is ``P2W`` (2 weeks).
- ``signatures-validity-dnskey``
+.. namedconf:statement:: signatures-validity-dnskey
+
This is similar to ``signatures-validity``, but for DNSKEY records.
The default is ``P2W`` (2 weeks).
- ``max-zone-ttl``
+.. namedconf:statement:: max-zone-ttl
+
Like the ``max-zone-ttl`` zone option, this specifies the maximum
permissible TTL value, in seconds, for the zone.
The default value is ``PT24H`` (24 hours). A ``max-zone-ttl`` of
zero is treated as if the default value were in use.
- ``nsec3param``
+.. namedconf:statement:: nsec3param
+
Use NSEC3 instead of NSEC, and optionally set the NSEC3 parameters.
Here is an example of an ``nsec3`` configuration:
A higher number of iterations causes interoperability problems and opens
servers to CPU-exhausting DoS attacks.
- ``zone-propagation-delay``
+.. namedconf:statement:: zone-propagation-delay
+
This is the expected propagation delay from the time when a zone is
first updated to the time when the new version of the zone is served
by all secondary servers. The default is ``PT5M`` (5 minutes).
- ``parent-ds-ttl``
+.. namedconf:statement:: parent-ds-ttl
+
This is the TTL of the DS RRset that the parent zone uses. The
default is ``P1D`` (1 day).
- ``parent-propagation-delay``
+.. namedconf:statement:: parent-propagation-delay
+
This is the expected propagation delay from the time when the parent
zone is updated to the time when the new version is served by all of
the parent zone's name servers. The default is ``PT1H`` (1 hour).
The following options apply to DS queries sent to ``parental-agents``:
-``parental-source``
+.. namedconf:statement:: parental-source
+
``parental-source`` determines which local source address, and optionally
UDP port, is used to send parental DS queries. This statement sets the
``parental-source`` for all zones, but can be overridden on a per-zone or
.. warning:: The configured ``port`` must not be same as the listening port.
-``parental-source-v6``
+.. namedconf:statement:: parental-source-v6
+
This option acts like ``parental-source``, but applies to parental DS
queries sent to IPv6 addresses.
``managed-keys`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: managed-keys
.. include:: ../misc/managed-keys.grammar.rst
``trusted-keys`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: trusted-keys
.. include:: ../misc/trusted-keys.grammar.rst
``view`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: view
::
particularly useful for implementing split DNS setups without having to
run multiple servers.
-Each ``view`` statement defines a view of the DNS namespace that is
-seen by a subset of clients. A client matches a view if its source IP
-address matches the ``address_match_list`` of the view's
-``match-clients`` clause, and its destination IP address matches the
-``address_match_list`` of the view's ``match-destinations`` clause. If
-not specified, both ``match-clients`` and ``match-destinations`` default
-to matching all addresses. In addition to checking IP addresses,
-``match-clients`` and ``match-destinations`` can also take ``keys``
-which provide an mechanism for the client to select the view. A view can
-also be specified as ``match-recursive-only``, which means that only
-recursive requests from matching clients match that view. The order
-of the ``view`` statements is significant; a client request is
-resolved in the context of the first ``view`` that it matches.
+.. namedconf:statement:: match-clients
+.. namedconf:statement:: match-destinations
+
+ Each ``view`` statement defines a view of the DNS namespace that is
+ seen by a subset of clients. A client matches a view if its source IP
+ address matches the ``address_match_list`` of the view's
+ ``match-clients`` clause, and its destination IP address matches the
+ ``address_match_list`` of the view's ``match-destinations`` clause. If
+ not specified, both ``match-clients`` and ``match-destinations`` default
+ to matching all addresses. In addition to checking IP addresses,
+ ``match-clients`` and ``match-destinations`` can also take ``keys``
+ which provide an mechanism for the client to select the view.
+
+.. namedconf:statement:: match-recursive-only
+
+ A view can
+ also be specified as ``match-recursive-only``, which means that only
+ recursive requests from matching clients match that view. The order
+ of the ``view`` statements is significant; a client request is
+ resolved in the context of the first ``view`` that it matches.
Zones defined within a ``view`` statement are only accessible to
clients that match the ``view``. By defining a zone of the same name in
``zone`` Statement Grammar
~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. namedconf:statement:: zone
.. include:: ../misc/primary.zoneopt.rst
.. include:: ../misc/secondary.zoneopt.rst
Zone Types
^^^^^^^^^^
+.. namedconf:statement:: type
+
+ The ``type`` keyword is required for the ``zone`` configuration unless
+ it is an ``in-view`` configuration. Its acceptable values are:
+ ``primary`` (or ``master``), ``secondary`` (or ``slave``), ``mirror``,
+ ``hint``, ``stub``, ``static-stub``, ``forward``, ``redirect``,
+ or ``delegation-only``.
-The ``type`` keyword is required for the ``zone`` configuration unless
-it is an ``in-view`` configuration. Its acceptable values are:
-``primary`` (or ``master``), ``secondary`` (or ``slave``), ``mirror``,
-``hint``, ``stub``, ``static-stub``, ``forward``, ``redirect``,
-or ``delegation-only``.
+.. namedconf:statement:: type primary
-``primary``
A primary zone has a master copy of the data for the zone and is able
to provide authoritative answers for it. Type ``master`` is a synonym
for ``primary``.
-``secondary``
+.. namedconf:statement:: type secondary
+
A secondary zone is a replica of a primary zone. Type ``slave`` is a
synonym for ``secondary``. The ``primaries`` list specifies one or more IP
addresses of primary servers that the secondary contacts to update
letters of the zone name. (Most operating systems
behave very slowly if there are 100000 files in a single directory.)
-``mirror``
+.. namedconf:statement:: type mirror
+
A mirror zone is similar to a zone of type ``secondary``, except its
data is subject to DNSSEC validation before being used in answers.
Validation is applied to the entire zone during the zone transfer
considered *experimental* and may cause performance issues,
especially for zones that are large and/or frequently updated.
-``hint``
+.. namedconf:statement:: type hint
+
The initial set of root name servers is specified using a hint zone.
When the server starts, it uses the root hints to find a root name
server and get the most recent list of root name servers. If no hint zone
is specified for class IN, the server uses a compiled-in default set of
root servers hints. Classes other than IN have no built-in default hints.
-``stub``
+.. namedconf:statement:: type stub
+
A stub zone is similar to a secondary zone, except that it replicates only
the NS records of a primary zone instead of the entire zone. Stub zones
are not a standard part of the DNS; they are a feature specific to the
configured with stub zones for ``10.in-addr.arpa`` to use a set of
internal name servers as the authoritative servers for that domain.
-``static-stub``
+.. namedconf:statement:: type static-stub
+
A static-stub zone is similar to a stub zone, with the following
exceptions: the zone data is statically configured, rather than
transferred from a primary server; and when recursion is necessary for a query
Each static-stub zone is configured with internally generated NS and (if
necessary) glue A or AAAA RRs.
-``forward``
+.. namedconf:statement:: type forward
+
A forward zone is a way to configure forwarding on a per-domain basis.
A ``zone`` statement of type ``forward`` can contain a ``forward`` and/or
``forwarders`` statement, which applies to queries within the domain
then "forward only", or vice versa), but use the same servers as set
globally, re-specify the global forwarders.
-``redirect``
+.. namedconf:statement:: type redirect
+
Redirect zones are used to provide answers to queries when normal
resolution would result in NXDOMAIN being returned. Only one redirect zone
is supported per view. ``allow-query`` can be used to restrict which
When using :option:`rndc reload` without specifying a zone name, redirect
zones are reloaded along with other zones.
-``delegation-only``
+.. namedconf:statement:: type delegation-only
+
This zone type is used to enforce the delegation-only status of infrastructure
zones (e.g., COM, NET, ORG). Any answer that is received without an
explicit or implicit delegation in the authority section is treated
See caveats in :ref:`root-delegation-only <root-delegation-only>`.
-``in-view``
+.. namedconf:statement:: in-view
+
When using multiple views, a ``primary`` or ``secondary`` zone configured
in one view can be referenced in a subsequent view. This allows both views
to use the same zone without the overhead of loading it more than once. This
``try-tcp-refresh``
See the description of ``try-tcp-refresh`` in :ref:`boolean_options`.
-``database``
+.. namedconf:statement:: database
+
This specifies the type of database to be used to store the zone data.
The string following the ``database`` keyword is interpreted as a
list of whitespace-delimited words. The first word identifies the
``dialup``
See the description of ``dialup`` in :ref:`boolean_options`.
-``delegation-only``
+.. namedconf:statement:: delegation-only
+
This flag only applies to forward, hint, and stub zones. If set to
``yes``, then the zone is treated as if it is also a
delegation-only type zone.
.. _file:
-``file``
+.. namedconf:statement:: file
+
This sets the zone's filename. In ``primary``, ``hint``, and ``redirect``
zones which do not have ``primaries`` defined, zone data is loaded from
this file. In ``secondary``, ``mirror``, ``stub``, and ``redirect`` zones
specified in a zone of type ``forward``, no forwarding is done for
the zone and the global options are not used.
-``journal``
+.. namedconf:statement:: journal
+
This allows the default journal's filename to be overridden. The default is
the zone's filename with "``.jnl``" appended. This is applicable to
``primary`` and ``secondary`` zones.
``zone-statistics``
See the description of ``zone-statistics`` in :ref:`options`.
-``server-addresses``
+.. namedconf:statement:: server-addresses
+
This option is only meaningful for static-stub zones. This is a list of IP addresses
to which queries should be sent in recursive resolution for the zone.
A non-empty list for this option internally configures the apex
recursive resolution and sends queries to 192.0.2.1 and/or
2001:db8::1234.
-``server-names``
+.. namedconf:statement:: 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 :iscman:`named`
``serial-update-method``
See the description of ``serial-update-method`` in :ref:`options`.
-``inline-signing``
+.. namedconf:statement:: inline-signing
+
If ``yes``, BIND 9 maintains a separate signed version of the zone.
An unsigned zone is transferred in or loaded from disk and the signed
version of the zone is served with, possibly, a different serial
or ``update-policy`` options. In both cases, BIND 9 writes the updates
to the zone's filename set in ``file``.
-The ``allow-update`` clause is a simple access control list. Any client
-that matches the ACL is granted permission to update any record in the
-zone.
-
-The ``update-policy`` clause allows more fine-grained control over which
-updates are allowed. It specifies a set of rules, in which each rule
-either grants or denies permission for one or more names in the zone to
-be updated by one or more identities. Identity is determined by the key
-that signed the update request, using either TSIG or SIG(0). In most
-cases, ``update-policy`` rules only apply to key-based identities. There
-is no way to specify update permissions based on the client source address.
-
-``update-policy`` rules are only meaningful for zones of type
-``primary``, and are not allowed in any other zone type. It is a
-configuration error to specify both ``allow-update`` and
-``update-policy`` at the same time.
-
-A pre-defined ``update-policy`` rule can be switched on with the command
-``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
-: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,
-respectively. A client running on the local system, if run with
-appropriate permissions, may read the session key from the key file and
-use it to sign update requests. The zone's update policy is set to
-allow that key to change any record within the zone. Assuming the key
-name is "local-ddns", this policy is equivalent to:
+.. namedconf:statement:: allow-update
+
+ The ``allow-update`` clause is a simple access control list. Any client
+ that matches the ACL is granted permission to update any record in the
+ zone.
+
+.. namedconf:statement:: update-policy
+
+ The ``update-policy`` clause allows more fine-grained control over which
+ updates are allowed. It specifies a set of rules, in which each rule
+ either grants or denies permission for one or more names in the zone to
+ be updated by one or more identities. Identity is determined by the key
+ that signed the update request, using either TSIG or SIG(0). In most
+ cases, ``update-policy`` rules only apply to key-based identities. There
+ is no way to specify update permissions based on the client source address.
+
+ ``update-policy`` rules are only meaningful for zones of type
+ ``primary``, and are not allowed in any other zone type. It is a
+ configuration error to specify both ``allow-update`` and
+ ``update-policy`` at the same time.
+
+ A pre-defined ``update-policy`` rule can be switched on with the command
+ ``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
+ :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,
+ respectively. A client running on the local system, if run with
+ appropriate permissions, may read the session key from the key file and
+ use it to sign update requests. The zone's update policy is set to
+ allow that key to change any record within the zone. Assuming the key
+ name is "local-ddns", this policy is equivalent to:
-::
+ ::
- update-policy { grant local-ddns zonesub any; };
+ update-policy { grant local-ddns zonesub any; };
-with the additional restriction that only clients connecting from the
-local system are permitted to send updates.
+ 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 :iscman:`named`; all zones
-configured to use ``update-policy local`` accept the same key.
+ 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
-localhost and signing them using the key retrieved from the session key
-file.
+ The command ``nsupdate -l`` implements this feature, sending requests to
+ localhost and signing them using the key retrieved from the session key
+ file.
-Other rule definitions look like this:
+ Other rule definitions look like this:
-::
+ ::
- ( grant | deny ) identity ruletype name types
-
-Each rule grants or denies privileges. Rules are checked in the order in
-which they are specified in the ``update-policy`` statement. Once a
-message has successfully matched a rule, the operation is immediately
-granted or denied, and no further rules are examined. There are 16 types
-of rules; the rule type is specified by the ``ruletype`` field, and the
-interpretation of other fields varies depending on the rule type.
-
-In general, a rule is matched when the key that signed an update request
-matches the ``identity`` field, the name of the record to be updated
-matches the ``name`` field (in the manner specified by the ``ruletype``
-field), and the type of the record to be updated matches the ``types``
-field. Details for each rule type are described below.
-
-The ``identity`` field must be set to a fully qualified domain name. In
-most cases, this represents the name of the TSIG or SIG(0) key that
-must be used to sign the update request. If the specified name is a
-wildcard, it is subject to DNS wildcard expansion, and the rule may
-apply to multiple identities. When a TKEY exchange has been used to
-create a shared secret, the identity of the key used to authenticate the
-TKEY exchange is used as the identity of the shared secret. Some
-rule types use identities matching the client's Kerberos principal (e.g,
-``"host/machine@REALM"``) or Windows realm (``machine$@REALM``).
-
-The ``name`` field also specifies a fully qualified domain name. This often
-represents the name of the record to be updated. Interpretation of this
-field is dependent on rule type.
-
-If no ``types`` are explicitly specified, then a rule matches all types
-except RRSIG, NS, SOA, NSEC, and NSEC3. Types may be specified by name,
-including ``ANY``; ANY matches all types except NSEC and NSEC3, which can
-never be updated. Note that when an attempt is made to delete all
-records associated with a name, the rules are checked for each existing
-record type.
-
-If the type is immediately followed by a number in parentheses,
-that number is the maximum number of records of that type permitted
-to exist in the RRset after an update has been applied. For example,
-``PTR(1)`` indicates that only one PTR record is allowed. If an
-attempt is made to add two PTR records in an update, the second one
-is silently discarded. If a PTR record already exists, both
-new records are silently discarded.
-
-If type ANY is specified with a limit, then that limit applies to
-all types that are not otherwise specified. For example, ``A PTR(1)
-ANY(2)`` indicates that an unlimited number of A records can exist,
-but only one PTR record, and no more than two of any other type.
-
-Typical use with a rule ``grant * tcp-self . PTR(1);`` in the zone
-2.0.192.IN-ADDR.ARPA looks like this:
+ ( grant | deny ) identity ruletype name types
+
+ Each rule grants or denies privileges. Rules are checked in the order in
+ which they are specified in the ``update-policy`` statement. Once a
+ message has successfully matched a rule, the operation is immediately
+ granted or denied, and no further rules are examined. There are 16 types
+ of rules; the rule type is specified by the ``ruletype`` field, and the
+ interpretation of other fields varies depending on the rule type.
+
+ In general, a rule is matched when the key that signed an update request
+ matches the ``identity`` field, the name of the record to be updated
+ matches the ``name`` field (in the manner specified by the ``ruletype``
+ field), and the type of the record to be updated matches the ``types``
+ field. Details for each rule type are described below.
+
+ The ``identity`` field must be set to a fully qualified domain name. In
+ most cases, this represents the name of the TSIG or SIG(0) key that
+ must be used to sign the update request. If the specified name is a
+ wildcard, it is subject to DNS wildcard expansion, and the rule may
+ apply to multiple identities. When a TKEY exchange has been used to
+ create a shared secret, the identity of the key used to authenticate the
+ TKEY exchange is used as the identity of the shared secret. Some
+ rule types use identities matching the client's Kerberos principal (e.g,
+ ``"host/machine@REALM"``) or Windows realm (``machine$@REALM``).
+
+ The ``name`` field also specifies a fully qualified domain name. This often
+ represents the name of the record to be updated. Interpretation of this
+ field is dependent on rule type.
+
+ If no ``types`` are explicitly specified, then a rule matches all types
+ except RRSIG, NS, SOA, NSEC, and NSEC3. Types may be specified by name,
+ including ``ANY``; ANY matches all types except NSEC and NSEC3, which can
+ never be updated. Note that when an attempt is made to delete all
+ records associated with a name, the rules are checked for each existing
+ record type.
+
+ If the type is immediately followed by a number in parentheses,
+ that number is the maximum number of records of that type permitted
+ to exist in the RRset after an update has been applied. For example,
+ ``PTR(1)`` indicates that only one PTR record is allowed. If an
+ attempt is made to add two PTR records in an update, the second one
+ is silently discarded. If a PTR record already exists, both
+ new records are silently discarded.
+
+ If type ANY is specified with a limit, then that limit applies to
+ all types that are not otherwise specified. For example, ``A PTR(1)
+ ANY(2)`` indicates that an unlimited number of A records can exist,
+ but only one PTR record, and no more than two of any other type.
+
+ Typical use with a rule ``grant * tcp-self . PTR(1);`` in the zone
+ 2.0.192.IN-ADDR.ARPA looks like this:
-::
+ ::
- nsupdate -v <<EOF
- local 192.0.2.1
- del 1.2.0.192.IN-ADDR.ARPA PTR
- add 1.2.0.192.IN-ADDR.ARPA 0 PTR EXAMPLE.COM
- send
- EOF
+ nsupdate -v <<EOF
+ local 192.0.2.1
+ del 1.2.0.192.IN-ADDR.ARPA PTR
+ add 1.2.0.192.IN-ADDR.ARPA 0 PTR EXAMPLE.COM
+ send
+ EOF
-The ruletype field has 20 values: ``name``, ``subdomain``, ``zonesub``,
-``wildcard``, ``self``, ``selfsub``, ``selfwild``, ``ms-self``,
-``ms-selfsub``, ``ms-subdomain``, ``ms-subdomain-self-rhs``, ``krb5-self``,
-``krb5-selfsub``, ``krb5-subdomain``, ``krb5-subdomain-self-rhs``,
-``tcp-self``, ``6to4-self``, and ``external``.
+ The ruletype field has 20 values: ``name``, ``subdomain``, ``zonesub``,
+ ``wildcard``, ``self``, ``selfsub``, ``selfwild``, ``ms-self``,
+ ``ms-selfsub``, ``ms-subdomain``, ``ms-subdomain-self-rhs``, ``krb5-self``,
+ ``krb5-selfsub``, ``krb5-subdomain``, ``krb5-subdomain-self-rhs``,
+ ``tcp-self``, ``6to4-self``, and ``external``.
-``name``
- With exact-match semantics, this rule matches when the name being updated is identical to the contents of the ``name`` field.
+ ``name``
+ With exact-match semantics, this rule matches when the name being updated is identical to the contents of the ``name`` field.
-``subdomain``
- This rule matches when the name being updated is a subdomain of, or identical to, the contents of the ``name`` field.
+ ``subdomain``
+ This rule matches when the name being updated is a subdomain of, or identical to, the contents of the ``name`` field.
-``zonesub``
- This rule is similar to subdomain, except that it matches when the name being updated is a subdomain of the zone in which the ``update-policy`` statement appears. This obviates the need to type the zone name twice, and enables the use of a standard ``update-policy`` statement in multiple zones without modification.
- When this rule is used, the ``name`` field is omitted.
+ ``zonesub``
+ This rule is similar to subdomain, except that it matches when the name being updated is a subdomain of the zone in which the ``update-policy`` statement appears. This obviates the need to type the zone name twice, and enables the use of a standard ``update-policy`` statement in multiple zones without modification.
+ When this rule is used, the ``name`` field is omitted.
-``wildcard``
- The ``name`` field is subject to DNS wildcard expansion, and this rule matches when the name being updated is a valid expansion of the wildcard.
+ ``wildcard``
+ The ``name`` field is subject to DNS wildcard expansion, and this rule matches when the name being updated is a valid expansion of the wildcard.
-``self``
- This rule matches when the name of the record being updated matches the contents of the ``identity`` field. The ``name`` field is ignored. To avoid confusion, it is recommended that this field be set to the same value as the ``identity`` field or to "."
- The ``self`` rule type is most useful when allowing one key per name to update, where the key has the same name as the record to be updated. In this case, the ``identity`` field can be specified as ``*`` (asterisk).
+ ``self``
+ This rule matches when the name of the record being updated matches the contents of the ``identity`` field. The ``name`` field is ignored. To avoid confusion, it is recommended that this field be set to the same value as the ``identity`` field or to "."
+ The ``self`` rule type is most useful when allowing one key per name to update, where the key has the same name as the record to be updated. In this case, the ``identity`` field can be specified as ``*`` (asterisk).
-``selfsub``
- This rule is similar to ``self``, except that subdomains of ``self`` can also be updated.
+ ``selfsub``
+ This rule is similar to ``self``, except that subdomains of ``self`` can also be updated.
-``selfwild``
- This rule is similar to ``self``, except that only subdomains of ``self`` can be updated.
+ ``selfwild``
+ This rule is similar to ``self``, except that only subdomains of ``self`` can be updated.
-``ms-self``
- When a client sends an UPDATE using a Windows machine principal (for example, ``machine$@REALM``), this rule allows records with the absolute name of ``machine.REALM`` to be updated.
+ ``ms-self``
+ When a client sends an UPDATE using a Windows machine principal (for example, ``machine$@REALM``), this rule allows records with the absolute name of ``machine.REALM`` to be updated.
- The realm to be matched is specified in the ``identity`` field.
+ The realm to be matched is specified in the ``identity`` field.
- The ``name`` field has no effect on this rule; it should be set to "." as a placeholder.
+ The ``name`` field has no effect on this rule; it should be set to "." as a placeholder.
- For example, ``grant EXAMPLE.COM ms-self . A AAAA`` allows any machine with a valid principal in the realm ``EXAMPLE.COM`` to update its own address records.
+ For example, ``grant EXAMPLE.COM ms-self . A AAAA`` allows any machine with a valid principal in the realm ``EXAMPLE.COM`` to update its own address records.
-``ms-selfsub``
- This is similar to ``ms-self``, except it also allows updates to any subdomain of the name specified in the Windows machine principal, not just to the name itself.
+ ``ms-selfsub``
+ This is similar to ``ms-self``, except it also allows updates to any subdomain of the name specified in the Windows machine principal, not just to the name itself.
-``ms-subdomain``
- When a client sends an UPDATE using a Windows machine principal (for example, ``machine$@REALM``), this rule allows any machine in the specified realm to update any record in the zone or in a specified subdomain of the zone.
+ ``ms-subdomain``
+ When a client sends an UPDATE using a Windows machine principal (for example, ``machine$@REALM``), this rule allows any machine in the specified realm to update any record in the zone or in a specified subdomain of the zone.
- The realm to be matched is specified in the ``identity`` field.
+ The realm to be matched is specified in the ``identity`` field.
- The ``name`` field specifies the subdomain that may be updated. If set to "." or any other name at or above the zone apex, any name in the zone can be updated.
+ The ``name`` field specifies the subdomain that may be updated. If set to "." or any other name at or above the zone apex, any name in the zone can be updated.
- For example, if ``update-policy`` for the zone "example.com" includes ``grant EXAMPLE.COM ms-subdomain hosts.example.com. AA AAAA``, any machine with a valid principal in the realm ``EXAMPLE.COM`` is able to update address records at or below ``hosts.example.com``.
+ For example, if ``update-policy`` for the zone "example.com" includes ``grant EXAMPLE.COM ms-subdomain hosts.example.com. AA AAAA``, any machine with a valid principal in the realm ``EXAMPLE.COM`` is able to update address records at or below ``hosts.example.com``.
-``ms-subdomain-self-rhs``
- This rule is similar to ``ms-subdomain``, with an additional
- restriction that PTR and SRV target names must match the name of the
- machine identified in the principal.
+ ``ms-subdomain-self-rhs``
+ This rule is similar to ``ms-subdomain``, with an additional
+ restriction that PTR and SRV target names must match the name of the
+ machine identified in the principal.
-``krb5-self``
- When a client sends an UPDATE using a Kerberos machine principal (for example, ``host/machine@REALM``), this rule allows records with the absolute name of ``machine`` to be updated, provided it has been authenticated by REALM. This is similar but not identical to ``ms-self``, due to the ``machine`` part of the Kerberos principal being an absolute name instead of an unqualified name.
+ ``krb5-self``
+ When a client sends an UPDATE using a Kerberos machine principal (for example, ``host/machine@REALM``), this rule allows records with the absolute name of ``machine`` to be updated, provided it has been authenticated by REALM. This is similar but not identical to ``ms-self``, due to the ``machine`` part of the Kerberos principal being an absolute name instead of an unqualified name.
- The realm to be matched is specified in the ``identity`` field.
+ The realm to be matched is specified in the ``identity`` field.
- The ``name`` field has no effect on this rule; it should be set to "." as a placeholder.
+ The ``name`` field has no effect on this rule; it should be set to "." as a placeholder.
- For example, ``grant EXAMPLE.COM krb5-self . A AAAA`` allows any machine with a valid principal in the realm ``EXAMPLE.COM`` to update its own address records.
+ For example, ``grant EXAMPLE.COM krb5-self . A AAAA`` allows any machine with a valid principal in the realm ``EXAMPLE.COM`` to update its own address records.
-``krb5-selfsub``
- This is similar to ``krb5-self``, except it also allows updates to any subdomain of the name specified in the ``machine`` part of the Kerberos principal, not just to the name itself.
+ ``krb5-selfsub``
+ This is similar to ``krb5-self``, except it also allows updates to any subdomain of the name specified in the ``machine`` part of the Kerberos principal, not just to the name itself.
-``krb5-subdomain``
- This rule is identical to ``ms-subdomain``, except that it works with Kerberos machine principals (i.e., ``host/machine@REALM``) rather than Windows machine principals.
+ ``krb5-subdomain``
+ This rule is identical to ``ms-subdomain``, except that it works with Kerberos machine principals (i.e., ``host/machine@REALM``) rather than Windows machine principals.
-``krb5-subdomain-self-rhs``
- This rule is similar to ``krb5-subdomain``, with an additional
- restriction that PTR and SRV target names must match the name of the
- machine identified in the principal.
+ ``krb5-subdomain-self-rhs``
+ This rule is similar to ``krb5-subdomain``, with an additional
+ restriction that PTR and SRV target names must match the name of the
+ machine identified in the principal.
-``tcp-self``
- This rule allows updates that have been sent via TCP and for which the standard mapping from the client's IP address into the ``in-addr.arpa`` and ``ip6.arpa`` namespaces matches the name to be updated. The ``identity`` field must match that name. The ``name`` field should be set to ".". Note that, since identity is based on the client's IP address, it is not necessary for update request messages to be signed.
+ ``tcp-self``
+ This rule allows updates that have been sent via TCP and for which the standard mapping from the client's IP address into the ``in-addr.arpa`` and ``ip6.arpa`` namespaces matches the name to be updated. The ``identity`` field must match that name. The ``name`` field should be set to ".". Note that, since identity is based on the client's IP address, it is not necessary for update request messages to be signed.
- .. note::
- It is theoretically possible to spoof these TCP sessions.
+ .. note::
+ It is theoretically possible to spoof these TCP sessions.
-``6to4-self``
- This allows the name matching a 6to4 IPv6 prefix, as specified in :rfc:`3056`, to be updated by any TCP connection from either the 6to4 network or from the corresponding IPv4 address. This is intended to allow NS or DNAME RRsets to be added to the ``ip6.arpa`` reverse tree.
+ ``6to4-self``
+ This allows the name matching a 6to4 IPv6 prefix, as specified in :rfc:`3056`, to be updated by any TCP connection from either the 6to4 network or from the corresponding IPv4 address. This is intended to allow NS or DNAME RRsets to be added to the ``ip6.arpa`` reverse tree.
- The ``identity`` field must match the 6to4 prefix in ``ip6.arpa``. The ``name`` field should be set to ".". Note that, since identity is based on the client's IP address, it is not necessary for update request messages to be signed.
+ The ``identity`` field must match the 6to4 prefix in ``ip6.arpa``. The ``name`` field should be set to ".". Note that, since identity is based on the client's IP address, it is not necessary for update request messages to be signed.
- In addition, if specified for an ``ip6.arpa`` name outside of the ``2.0.0.2.ip6.arpa`` namespace, the corresponding /48 reverse name can be updated. For example, TCP/IPv6 connections from 2001:DB8:ED0C::/48 can update records at ``C.0.D.E.8.B.D.0.1.0.0.2.ip6.arpa``.
+ In addition, if specified for an ``ip6.arpa`` name outside of the ``2.0.0.2.ip6.arpa`` namespace, the corresponding /48 reverse name can be updated. For example, TCP/IPv6 connections from 2001:DB8:ED0C::/48 can update records at ``C.0.D.E.8.B.D.0.1.0.0.2.ip6.arpa``.
- .. note::
- It is theoretically possible to spoof these TCP sessions.
+ .. note::
+ It is theoretically possible to spoof these TCP sessions.
-``external``
- This rule allows :iscman:`named` to defer the decision of whether to allow a given update to an external daemon.
+ ``external``
+ 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.)
+ 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.)
- Requests to the external daemon are sent over the Unix-domain socket as datagrams with the following format:
+ Requests to the external daemon are sent over the Unix-domain socket as datagrams with the following format:
- ::
+ ::
+
+ Protocol version number (4 bytes, network byte order, currently 1)
+ Request length (4 bytes, network byte order)
+ Signer (null-terminated string)
+ Name (null-terminated string)
+ TCP source address (null-terminated string)
+ Rdata type (null-terminated string)
+ Key (null-terminated string)
+ TKEY token length (4 bytes, network byte order)
+ TKEY token (remainder of packet)
- Protocol version number (4 bytes, network byte order, currently 1)
- Request length (4 bytes, network byte order)
- Signer (null-terminated string)
- Name (null-terminated string)
- TCP source address (null-terminated string)
- Rdata type (null-terminated string)
- Key (null-terminated string)
- TKEY token length (4 bytes, network byte order)
- TKEY token (remainder of packet)
-
- The daemon replies with a four-byte value in network byte order, containing either 0 or 1; 0 indicates that the specified update is not permitted, and 1 indicates that it is.
+ The daemon replies with a four-byte value in network byte order, containing either 0 or 1; 0 indicates that the specified update is not permitted, and 1 indicates that it is.
.. _multiple_views:
projects / thirdparty / bind9.git / commitdiff
