Bind9 Reference
From:
https://bind9.readthedocs.io/en/v9_18_4/reference.html
8. Configuration Reference
8.1. Configuration File Elements
Following is a list of elements used throughout the BIND configuration file
documentation:
acl_name
The name of an address_match_list as defined by the acl statement.
address_match_list
A list of one or more ip_addr, ip_prefix, key_id, or acl_name elements; see
Address Match Lists.
remoteserver_list
A named list of one or more ip_addr with optional tls_id, key_id and/or
ip_port. A remoteserver_list may include other remoteserver_list.
domain_name
A quoted string which is used as a DNS name; for example. my.test.domain.
namelist
A list of one or more domain_name elements.
dotted_decimal
One to four integers valued 0 through 255 separated by dots (.), such as
123.45.67 or 89.123.45.67.
ip4_addr
An IPv4 address with exactly four elements in dotted_decimal notation.
ip6_addr
An IPv6 address, such as 2001:db8::1234. IPv6-scoped addresses that have
ambiguity on their scope zones must be disambiguated by an appropriate zone ID
with the percent character (%) as a delimiter. It is strongly recommended to use
string zone names rather than numeric identifiers, to be robust against system
configuration changes. However, since there is no standard mapping for such
names and identifier values, only interface names as link identifiers are
supported, assuming one-to-one mapping between interfaces and links. For example
, a link-local address fe80::1 on the link attached to the interface ne0 can be
specified as fe80::1%ne0. Note that on most systems link-local addresses always
have ambiguity and need to be disambiguated.
ip_addr
An ip4_addr or ip6_addr.
ip_dscp
A number between 0 and 63, used to select a differentiated services code
point (DSCP) value for use with outgoing traffic on operating systems that
support DSCP.
ip_port
An IP port number. The number is limited to 0 through 65535, with values
below 1024 typically restricted to use by processes running as root. In some
cases, an asterisk (*) character can be used as a placeholder to select a random
high-numbered port.
ip_prefix
An IP network specified as an ip_addr, followed by a slash (/) and then the
number of bits in the netmask. Trailing zeros in an``ip_addr`` may be omitted.
For example, 127/8 is the network 127.0.0.0``with netmask ``255.0.0.0 and
1.2.3.0/28 is network 1.2.3.0 with netmask 255.255.255.240. When specifying a
prefix involving a IPv6-scoped address, the scope may be omitted. In that case,
the prefix matches packets from any scope.
key_id
A domain_name representing the name of a shared key, to be used for
transaction security.
key_list
A list of one or more key_id, separated by semicolons and ending with a
semicolon.
tls_id
A string representing a TLS configuration object, including a key and
certificate.
number
A non-negative 32-bit integer (i.e., a number between 0 and 4294967295,
inclusive). Its acceptable value might be further limited by the context in
which it is used.
fixedpoint
A non-negative real number that can be specified to the nearest
one-hundredth. Up to five digits can be specified before a decimal point, and up
to two digits after, so the maximum value is 99999.99. Acceptable values might
be further limited by the contexts in which they are used.
path_name
A quoted string which is used as a pathname, such as
zones/master/my.test.domain.
port_list
A list of an ip_port or a port range. A port range is specified in the form
of range followed by two ip_port``s, ``port_low and port_high, which represents
port numbers from port_low through port_high, inclusive. port_low must not be
larger than port_high. For example, range 1024 65535 represents ports from 1024
through 65535. In either case an asterisk (*) character is not allowed as a
valid ip_port.
size_spec
A 64-bit unsigned integer, or the keywords unlimited or default. Integers
may take values 0 <= value <= 18446744073709551615, though certain parameters
(such as max-journal-size) may use a more limited range within these extremes.
In most cases, setting a value to 0 does not literally mean zero; it means
“undefined” or “as big as possible,” depending on the context. See the
explanations of particular parameters that use size_spec for details on how they
interpret its use. Numeric values can optionally be followed by a scaling
factor: K or k for kilobytes, M or m for megabytes, and G or g for gigabytes,
which scale by 1024, 1024*1024, and 1024*1024*1024 respectively. unlimited
generally means “as big as possible,” and is usually the best way to safely set
a very large number. default uses the limit that was in force when the server
was started.
size_or_percent
A size_spec or integer value followed by % to represent percent. The
behavior is exactly the same as size_spec, but size_or_percent also allows
specifying a positive integer value followed by the % sign to represent percent.
yes_or_no
Either yes or no. The words true and false are also accepted, as are the
numbers 1 and 0.
dialup_option
One of yes, no, notify, notify-passive, refresh, or passive. When used in a
zone, notify-passive, refresh, and passive are restricted to secondary and stub
zones.
8.1.1. Address Match Lists
8.1.1.1. Syntax
address_match_list = address_match_list_element ; ...
address_match_list_element = [ ! ] ( ip_address | ip_prefix |
key key_id | acl_name | { address_match_list } )
8.1.1.2. Definition and Usage
Address match lists are primarily used to determine access control for various
server operations. They are also used in the listen-on and sortlist statements.
The elements which constitute an address match list can be any of the following:
- an IP address (IPv4 or IPv6)
- IP prefix (in / notation)
- key ID, as defined by the key statement
- name of an address match list defined with the acl statement
- nested address match list enclosed in braces
Elements can be negated with a leading exclamation mark (!), and the match list
names “any”, “none”, “localhost”, and “localnets” are predefined. More
information on those names can be found in the description of the acl statement.
The addition of the key clause made the name of this syntactic element something
of a misnomer, since security keys can be used to validate access without regard
to a host or network address. Nonetheless, the term “address match list” is
still used throughout the documentation.
When a given IP address or prefix is compared to an address match list, the
comparison takes place in approximately O(1) time. However, key comparisons
require that the list of keys be traversed until a matching key is found, and
therefore may be somewhat slower.
The interpretation of a match depends on whether the list is being used for
access control, defining listen-on ports, or in a sortlist, and whether the
element was negated.
When used as an access control list, a non-negated match allows access and a
negated match denies access. If there is no match, access is denied. The clauses
allow-notify, allow-recursion, allow-recursion-on, allow-query, allow-query-on,
allow-query-cache, allow-query-cache-on, allow-transfer, allow-update,
allow-update-forwarding, blackhole, and keep-response-order all use address
match lists. Similarly, the listen-on option causes the server to refuse queries
on any of the machine’s addresses which do not match the list.
Order of insertion is significant. If more than one element in an ACL is found
to match a given IP address or prefix, preference is given to the one that came
first in the ACL definition. Because of this first-match behavior, an element
that defines a subset of another element in the list should come before the
broader element, regardless of whether either is negated. For example, in
1.2.3/24; ! 1.2.3.13; the 1.2.3.13 element is completely useless because the
algorithm matches any lookup for 1.2.3.13 to the 1.2.3/24 element.
Using ! 1.2.3.13; 1.2.3/24 fixes that problem by blocking 1.2.3.13 via the
negation, but all other 1.2.3.* hosts pass through.
8.1.2. Comment Syntax
The BIND 9 comment syntax allows comments to appear anywhere that whitespace may
appear in a BIND configuration file. To appeal to programmers of all kinds, they
can be written in the C, C++, or shell/perl style.
8.1.2.1. Syntax
/* This is a BIND comment as in C */
// This is a BIND comment as in C++
# This is a BIND comment as in common Unix shells
# and perl
8.1.2.2. Definition and Usage
Comments may appear anywhere that whitespace may appear in a BIND configuration
file.
C-style comments start with the two characters /* (slash, star) and end with */
(star, slash). Because they are completely delimited with these characters, they
can be used to comment only a portion of a line or to span multiple lines.
C-style comments cannot be nested. For example, the following is not valid
because the entire comment ends with the first */:
/* This is the start of a comment.
This is still part of the comment.
/* This is an incorrect attempt at nesting a comment. */
This is no longer in any comment. */
C++-style comments start with the two characters // (slash, slash) and continue
to the end of the physical line. They cannot be continued across multiple
physical lines; to have one logical comment span multiple lines, each line must
use the // pair. For example:
// This is the start of a comment. The next line
// is a new comment, even though it is logically
// part of the previous comment.
Shell-style (or perl-style) comments start with the character # (number sign)
and continue to the end of the physical line, as in C++ comments. For example:
# This is the start of a comment. The next line
# is a new comment, even though it is logically
# part of the previous comment.
Warning
The semicolon (;) character cannot start a comment, unlike in a zone file. The
semicolon indicates the end of a configuration statement.
8.2. Configuration File Grammar
A BIND 9 configuration consists of statements and comments. Statements end with
a semicolon; statements and comments are the only elements that can appear
without enclosing braces. Many statements contain a block of sub-statements,
which are also terminated with a semicolon.
The following statements are supported:
acl
Defines a named IP address matching list, for access control and other
uses.
controls
Declares control channels to be used by the rndc utility.
dnssec-policy
Describes a DNSSEC key and signing policy for zones. See dnssec-policy
Grammar for details.
include
Includes a file.
key
Specifies key information for use in authentication and authorization
using TSIG.
logging
Specifies what information the server logs and where the log messages
are sent.
masters
Synonym for primaries.
options
Controls global server configuration options and sets defaults for other
statements.
parental-agents
Defines a named list of servers for inclusion in primary and secondary
zones’ parental-agents lists.
primaries
Defines a named list of servers for inclusion in stub and secondary
zones’ primaries or also-notify lists. (Note: this is a synonym for the
original keyword masters, which can still be used, but is no longer the
preferred terminology.)
server
Sets certain configuration options on a per-server basis.
statistics-channels
Declares communication channels to get access to named statistics.
tls
Specifies configuration information for a TLS connection, including a
key-file, cert-file, ca-file, dhparam-file, remote-hostname, ciphers,
protocols, prefer-server-ciphers, and session-tickets.
http
Specifies configuration information for an HTTP connection, including
endponts, listener-clients and streams-per-connection.
trust-anchors
Defines DNSSEC trust anchors: if used with the initial-key or initial-ds
keyword, trust anchors are kept up-to-date using RFC 5011 trust anchor
maintenance; if used with static-key or static-ds, keys are permanent.
managed-keys
Is identical to trust-anchors; this option is deprecated in favor of
trust-anchors with the initial-key keyword, and may be removed in a
future release.
trusted-keys
Defines permanent trusted DNSSEC keys; this option is deprecated in
favor of trust-anchors with the static-key keyword, and may be removed
in a future release.
view
Defines a view.
zone
Defines a zone.
The logging and options statements may only occur once per configuration.
8.2.1. acl Statement Grammar
acl { ; ... };
8.2.2. acl Statement Definition and Usage
The acl statement assigns a symbolic name to an address match list. It gets its
name from one of the primary uses of address match lists: Access Control Lists ACLs).
The following ACLs are built-in:
any
Matches all hosts.
none
Matches no hosts.
localhost
Matches the IPv4 and IPv6 addresses of all network interfaces on the
system. When addresses are added or removed, the localhost ACL element
is updated to reflect the changes.
localnets
Matches any host on an IPv4 or IPv6 network for which the system has an
interface. When addresses are added or removed, the localnets ACL
element is updated to reflect the changes. Some systems do not provide
a way to determine the prefix lengths of local IPv6 addresses; in such
cases, localnets only matches the local IPv6 addresses, just like
localhost.
8.2.3. controls Statement Grammar
controls
{
inet ( | |
* ) [ port ( | * ) ] allow
{ ; ... } [
keys { ; ... } ] [ read-only
];
unix perm
owner group [
keys { ; ... } ] [ read-only
];
};
8.2.4. controls Statement Definition and Usage
The controls statement declares control channels to be used by system
administrators to manage the operation of the name server. These control
channels are used by the rndc utility to send commands to 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 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 Administrative Tools for
information about configuring keys in 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.
If no controls statement is present, named sets up a default control channel
listening on the loopback address 127.0.0.1 and its IPv6 counterpart, ::1. In
this case, and also when the controls statement is present but does not have a
keys clause, named attempts to load the command channel key from the file
/etc/rndc.key. To create an rndc.key file, run rndc-confgen -a.
To disable the command channel, use an empty controls statement: controls { };.
8.2.5. include Statement Grammar
include filename;
8.2.6. include Statement Definition and Usage
The include statement inserts the specified file (or files if a valid glob
expression is detected) at the point where the include statement is encountered.
The include statement facilitates the administration of configuration files by
permitting the reading or writing of some things but not others. For example,
the statement could include private keys that are readable only by the name
server.
8.2.7. key Statement Grammar
key
{
algorithm ;
secret ;
};
8.2.8. key Statement Definition and Usage
The key statement defines a shared secret key for use with TSIG (see TSIG) or
the command channel (see controls Statement Definition and Usage).
The key statement can occur at the top level of the configuration file or
inside a view statement. Keys defined in top-level key statements can be used in
all views. Keys intended for use in a controls statement (see controls Statement
Definition and Usage) must be defined at the top level.
The key_id, also known as the key name, is a domain name that uniquely
identifies the key. It can be used in a server statement to cause requests sent
to that server to be signed with this key, or in address 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 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.
8.2.9. logging Statement Grammar
logging
{
category { ; ... };
channel
{
buffered ;
file [ versions ( unlimited | ) ]
[ size ] [ suffix ( increment | timestamp ) ];
null;
print-category ;
print-severity ;
print-time ( iso8601 | iso8601-utc | local | );
severity ;
stderr;
syslog [ ];
};
};
8.2.10. logging Statement Definition and Usage
The logging statement configures a wide variety of logging options for the name
server. Its channel phrase associates output methods, format options, and
severity levels with a name that can then be used with the category phrase to
select how various classes of messages are logged.
Only one logging statement is used to define as many channels and categories as
desired. If there is no logging statement, the logging configuration is:
logging
{
category default { default_syslog; default_debug; };
category unmatched { null; };
};
If named is started with the -L option, it logs to the specified file at startup,
instead of using syslog. In this case the logging configuration is:
logging
{
category default { default_logfile; default_debug; };
category unmatched { null; };
};
The logging configuration is only established when the entire configuration file
has been parsed. When the server starts up, all logging messages regarding
syntax errors in the configuration file go to the default channels, or to
standard error if the -g option was specified.
8.2.10.1. The channel Phrase
All log output goes to one or more channels; there is no limit to the number of
channels that can be created.
Every channel definition must include a destination clause that says whether
messages selected for the channel go to a file, go to a particular syslog
facility, go to the standard error stream, or are discarded. The definition can
optionally also limit the message severity level that is accepted by the channel
(the default is info), and whether to include a named -generated time stamp, the
category name, and/or the severity level (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 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;
};
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 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
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.
The server can supply extensive debugging information when it is in debugging
mode. If the server’s global debug level is greater than zero, debugging mode is
active. The global debug level is set either by starting the named server with
the -d flag followed by a positive integer, or by running rndc trace. The global
debug level can be set to zero, and debugging mode turned off, by running rndc
notrace. All debugging messages in the server have a debug level; higher debug
levels give more detailed output. Channels that specify a specific debug
severity, for example:
channel specific_debug_level
{
file "foo";
severity debug 3;
};
get debugging output of level 3 or less any time the server is in debugging
mode, regardless of the global debugging level. Channels with 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:
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.
There are four predefined channels that are used for named’s default logging, as
follows. If named is started with the -L option, then a fifth channel,
default_logfile, is added. How they are used is described in The category Phrase.
channel default_syslog
{
// SEND TO SYSLOG'S DAEMON FACILITY
syslog daemon;
// ONLY SEND PRIORITY INFO AND HIGHER
severity info;
};
channel default_debug {
// WRITE TO NAMED.RUN IN THE WORKING DIRECTORY
// nOTE: STDERR IS USED INSTEAD OF "named.run" IF
// THE SERVER IS STARTED WITH THE '-g' OPTION.
file "named.run";
// LOG AT THE SERVER'S CURRENT DEBUG LEVEL
severity dynamic;
};
channel default_stderr
{
// WRITES TO STDERR
stderr;
// ONLY SEND PRIORITY INFO AND HIGHER
severity info;
};
channel null
{
// TOSS ANYTHING SENT TO THIS CHANNEL
null;
};
channel default_logfile
{
// THIS CHANNEL IS ONLY PRESENT IF NAMED IS
// STARTED WITH THE -L OPTION, WHOSE ARGUMENT
// PROVIDES THE FILE NAME
file "...";
// LOG AT THE SERVER'S CURRENT DEBUG LEVEL
severity dynamic;
};
The default_debug channel has the special property that it only produces output
when the server’s debug level is non-zero. It normally writes to a file called
named.run in the server’s working directory.
For security reasons, when the -u command-line option is used, the named.run
file is created only after named has changed to the new UID, and any debug
output generated while named is starting - and still running as root - is
discarded. To capture this output, run the server with the -L option to specify
a default logfile, or the -g option to log to standard error which can be
redirected to a file.
Once a channel is defined, it cannot be redefined. The built-in channels cannot
be altered directly, but the default logging can be modified by pointing
categories at defined channels.
8.2.10.2. 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 category are sent to the default category instead. If no
default category is specified, the following “default default” is used:
category default { default_syslog; default_debug; };
If named is started with the -L option, the default category is:
category default { default_logfile; default_debug; };
As an example, let’s say a user wants to log security events to a file, but also
wants to keep the default logging behavior. They would specify the following:
channel my_security_channel
{
file "my_security_file";
severity info;
};
category security
{
my_security_channel;
default_syslog;
default_debug;
};
To discard all messages in a category, specify the null channel:
category xfer-out { null; };
category notify { null; };
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.
client
Processing of client requests.
cname
Name servers that are skipped for being a CNAME rather than A/AAAA records.
config
Configuration file parsing and processing.
database
Messages relating to the databases used internally by the name server to
store zone and cache data.
default
Logging options for those categories where no specific configuration has
been defined.
delegation-only
Queries that have been forced to NXDOMAIN as the result of a delegation-only
zone or a delegation-only in a forward, hint, or stub zone declaration.
dispatch
Dispatching of incoming packets to the server modules where they are to be
processed.
dnssec
DNSSEC and TSIG protocol processing.
dnstap
The “dnstap” DNS traffic capture system.
edns-disabled
Log queries that have been forced to use plain DNS due to timeouts. This is
often due to the remote servers not being RFC 1034-compliant (not always
returning FORMERR or similar to EDNS queries and other extensions to the DNS
when they are not understood). In other words, this is targeted at servers
that fail to respond to DNS queries that they don’t understand.
Note: the log message can also be due to packet loss. Before reporting
servers for non-RFC 1034 compliance they should be re-tested to determine
the nature of the non-compliance. This testing should prevent or reduce the
number of false-positive reports.
Note: eventually named will have to stop treating such timeouts as due to
RFC 1034 non-compliance and start treating it as plain packet loss. Falsely
classifying packet loss as due to RFC 1034 non-compliance impacts DNSSEC
validation, which requires EDNS for the DNSSEC records to be returned.
general
A catch-all for many things that still are not classified into categories.
lame-servers
Misconfigurations in remote servers, discovered by BIND 9 when trying to
query those servers during resolution.
network
Network operations.
notify
The NOTIFY protocol.
nsid
NSID options received from upstream servers.
queries
A location where queries should be logged.
At startup, specifying the category queries also enables query logging
unless the querylog option has been specified.
The query log entry first reports a client object identifier in
@0x format. Next, it reports the client’s IP address and
port number, and the query name, class, and type. Next, it reports whether
the Recursion Desired flag was set (+ if set, - if not set), whether the
query was signed (S), whether EDNS was in use along with the EDNS version
number (E(#)), whether TCP was used (T), whether DO (DNSSEC Ok) was set (D),
whether CD (Checking Disabled) was set (C), whether a valid DNS Server
COOKIE was received (V), and whether a DNS COOKIE option without a valid
Server COOKIE was present (K). After this, the destination address the query
was sent to is reported. Finally, if any CLIENT-SUBNET option was present in
the client query, it is included in square brackets in the format [ECS
address/source/scope].
client 127.0.0.1#62536 (www.example.com): query: www.example.com IN AAAA +SE
client ::1#62537 (www.example.net): query: www.example.net IN AAAA -SE
The first part of this log message, showing the client address/port number
and query name, is repeated in all subsequent log messages related to the
same query.
query-errors
Information about queries that resulted in some failure.
rate-limit
Start, periodic, and final notices of the rate limiting of a stream of
responses that are logged at info severity in this category. These messages
include a hash value of the domain name of the response and the name itself,
except when there is insufficient memory to record the name for the final
notice. The final notice is normally delayed until about one minute after
rate limiting stops. A lack of memory can hurry the final notice, which is
indicated by an initial asterisk (*). Various internal events are logged at
debug level 1 and higher.
Rate limiting of individual requests is logged in the query-errors category.
resolver
DNS resolution, such as the recursive lookups performed on behalf of clients
by a caching name server.
rpz
Information about errors in response policy zone files, rewritten responses,
and, at the highest debug levels, mere rewriting attempts.
rpz-passthru
Information about RPZ PASSTHRU policy activity. This category allows
pre-approved policy activity to be logged into a dedicated channel.
security
Approval and denial of requests.
serve-stale
Indication of whether a stale answer is used following a resolver failure.
spill
Queries that have been terminated, either by dropping or responding with
SERVFAIL, as a result of a fetchlimit quota being exceeded.
sslkeylog
TLS pre-master secrets (for debugging purposes).
trust-anchor-telemetry
Trust-anchor-telemetry requests received by named.
unmatched
Messages that named was unable to determine the class of, or for which there
was no matching view. A one-line summary is also logged to the client
category. This category is best sent to a file or stderr; by default it is
sent to the null channel.
update
Dynamic updates.
update-security
Approval and denial of update requests.
xfer-in
Zone transfers the server is receiving.
xfer-out
Zone transfers the server is sending.
zoneload
Loading of zones and creation of automatic empty zones.
8.2.10.3. The query-errors Category
The query-errors category is used to indicate why and how specific queries
resulted in responses which indicate an error. Normally, these messages are
logged at debug logging levels; note, however, that if query logging is active,
some are logged at info. The logging levels are described below:
At debug level 1 or higher - or at info when query logging is active - each
response with the rcode of SERVFAIL is logged as follows:
client 127.0.0.1#61502: query failed (SERVFAIL) for www.example.com/IN/AAAA at
query.c:3880
This means an error resulting in SERVFAIL was detected at line 3880 of source
file query.c. Log messages of this level are particularly helpful in identifying
the cause of SERVFAIL for an authoritative server.
At debug level 2 or higher, detailed context information about recursive
resolutions that resulted in SERVFAIL is logged. The log message looks like
this:
fetch completed at resolver.c:2970 for www.example.com/A
in 10.000183: timed out/success [domain:example.com,
referral:2,restart:7,qrysent:8,timeout:5,lame:0,quota:0,neterr:0,
badresp:1,adberr:0,findfail:0,valfail:0]
The first part before the colon shows that a recursive resolution for AAAA
records of www.example.com completed in 10.000183 seconds, and the final result
that led to the SERVFAIL was determined at line 2970 of source file resolver.c.
The next part shows the detected final result and the latest result of DNSSEC
validation. The latter is always “success” when no validation attempt was made.
In this example, this query probably resulted in SERVFAIL because all name
servers are down or unreachable, leading to a timeout in 10 seconds. DNSSEC
validation was probably not attempted.
The last part, enclosed in square brackets, shows statistics collected for this
particular resolution attempt. The domain field shows the deepest zone that the
resolver reached; it is the zone where the error was finally detected. The
meaning of the other fields is summarized in the following list.
referral
The number of referrals the resolver received throughout the resolution
process. In the above example.com there are two.
restart
The number of cycles that the resolver tried remote servers at the domain
zone. In each cycle, the resolver sends one query (possibly resending it,
depending on the response) to each known name server of the domain zone.
qrysent
The number of queries the resolver sent at the domain zone.
timeout
The number of timeouts the resolver received since the last response.
lame
The number of lame servers the resolver detected at the domain zone. A
server is detected to be lame either by an invalid response or as a result
of lookup in BIND 9’s address database (ADB), where lame servers are cached.
quota
The number of times the resolver was unable to send a query because it had
exceeded the permissible fetch quota for a server.
neterr
The number of erroneous results that the resolver encountered in sending
queries at the domain zone. One common case is when the remote server is
unreachable and the resolver receives an “ICMP unreachable” error message.
badresp
The number of unexpected responses (other than lame) to queries sent by the
resolver at the domain zone.
adberr
Failures in finding remote server addresses of the``domain`` zone in the
ADB. One common case of this is that the remote server’s name does not have
any address records.
findfail
Failures to resolve remote server addresses. This is a total number of
failures throughout the resolution process.
valfail
Failures of DNSSEC validation. Validation failures are counted throughout
the resolution process (not limited to the domain zone), but should only
happen in domain.
At debug level 3 or higher, the same messages as those at debug level 1 are
logged for errors other than SERVFAIL. Note that negative responses such as
NXDOMAIN are not errors, and are not logged at this debug level.
At debug level 4 or higher, the detailed context information logged at debug
level 2 is logged for errors other than SERVFAIL and for negative responses such
as NXDOMAIN.
8.2.11. parental-agents Statement Grammar
parental-agents [ port ] [
dscp ] { ( |
[ port ] |
[ port ] ) [ key
] [ tls ]; ... };
8.2.12. parental-agents Statement Definition and Usage
parental-agents lists allow for a common set of parental agents to be easily
used by multiple primary and secondary zones in their parental-agents lists. A
parental agent is the entity that the zone has a relationship with to change its
delegation information (defined in RFC 7344).
8.2.13. primaries Statement Grammar
primaries [ port ] [ dscp
] { ( |
[ port ] |
[ port ] ) [ key
] [ tls ]; ... };
8.2.14. primaries Statement Definition and Usage
primaries lists allow for a common set of primary servers to be easily used by
multiple stub and secondary zones in their primaries or also-notify lists.
(Note: primaries is a synonym for the original keyword masters, which can still
be used, but is no longer the preferred terminology.)
To force the zone transfer requests to be sent over TLS, use tls keyword, e.g.
primaries { 192.0.2.1 tls tls-configuration-name; };, where
tls-configuration-name refers to a previously defined tls statement.
Warning
Please note that TLS connections to primaries are not authenticated unless
remote-hostname or ca-file are specified within the tls statement in use (see
information on Strict TLS and Mutual TLS for more details). Not authenticated
mode (Opportunistic TLS) provides protection from passive observers but does not
protect from man-in-the-middle attacks on zone transfers.
8.2.15. options Statement Grammar
This is the grammar of the options statement in the named.conf file:
options
{
allow-new-zones ;
allow-notify { ; ... };
allow-query { ; ... };
allow-query-cache { ; ... };
allow-query-cache-on { ; ... };
allow-query-on { ; ... };
allow-recursion { ; ... };
allow-recursion-on { ; ... };
allow-transfer [ port ] [ transport ] {
; ... };
allow-update { ; ... };
allow-update-forwarding { ; ... };
also-notify [ port ] [ dscp ] { (
| [ port ] |
[ port ] ) [ key ] [ tls
]; ... };
alt-transfer-source ( | * ) [ port ( | * )
] [ dscp ];
alt-transfer-source-v6 ( | * ) [ port ( |
* ) ] [ dscp ];
answer-cookie ;
attach-cache ;
auth-nxdomain ;
auto-dnssec ( allow | maintain | off );
automatic-interface-scan ;
avoid-v4-udp-ports { ; ... };
avoid-v6-udp-ports { ; ... };
bindkeys-file ;
blackhole { ; ... };
catalog-zones { zone [ default-primaries [ port
] [ dscp ] { ( | [
port ] | [ port ] ) [ key
] [ tls ]; ... } ] [ zone-directory
] [ in-memory ] [ min-update-interval
]; ... };
check-dup-records ( fail | warn | ignore );
check-integrity ;
check-mx ( fail | warn | ignore );
check-mx-cname ( fail | warn | ignore );
check-names ( primary | master |
secondary | slave | response ) (
fail | warn | ignore );
check-sibling ;
check-spf ( warn | ignore );
check-srv-cname ( fail | warn | ignore );
check-wildcard ;
clients-per-query ;
cookie-algorithm ( aes | siphash24 );
cookie-secret ;
coresize ( default | unlimited | );
datasize ( default | unlimited | );
deny-answer-addresses { ; ... } [
except-from { ; ... } ];
deny-answer-aliases { ; ... } [ except-from { ; ...
} ];
dialup ( notify | notify-passive | passive | refresh | );
directory ;
disable-algorithms { ;
... };
disable-ds-digests { ;
... };
disable-empty-zone ;
dns64
{
break-dnssec ;
clients { ; ... };
exclude { ; ... };
mapped { ; ... };
recursive-only ;
suffix ;
};
dns64-contact ;
dns64-server ;
dnskey-sig-validity ;
dnsrps-enable ;
dnsrps-options { };
dnssec-accept-expired ;
dnssec-dnskey-kskonly ;
dnssec-loadkeys-interval ;
dnssec-must-be-secure ;
dnssec-policy ;
dnssec-secure-to-insecure ;
dnssec-update-mode ( maintain | no-resign );
dnssec-validation ( yes | no | auto );
dnstap { ( all | auth | client | forwarder | resolver | update ) [
( query | response ) ]; ... };
dnstap-identity ( | none | hostname );
dnstap-output ( file | unix ) [ size ( unlimited |
) ] [ versions ( unlimited | ) ] [ suffix (
increment | timestamp ) ];
dnstap-version ( | none );
dscp ;
dual-stack-servers [ port ] { ( [ port
] [ dscp ] | [ port
] [ dscp ] | [ port
] [ dscp ] ); ... };
dump-file ;
edns-udp-size ;
empty-contact ;
empty-server ;
empty-zones-enable ;
fetch-quota-params ;
fetches-per-server [ ( drop | fail ) ];
fetches-per-zone [ ( drop | fail ) ];
files ( default | unlimited | );
flush-zones-on-shutdown ;
forward ( first | only );
forwarders [ port ] [ dscp ] { (
| ) [ port ] [ dscp ]; ... };
fstrm-set-buffer-hint ;
fstrm-set-flush-timeout ;
fstrm-set-input-queue-size ;
fstrm-set-output-notify-threshold ;
fstrm-set-output-queue-model ( mpsc | spsc );
fstrm-set-output-queue-size ;
fstrm-set-reopen-interval ;
geoip-directory ( | none );
glue-cache ; // deprecated
heartbeat-interval ;
hostname ( | none );
http-listener-clients ;
http-port ;
http-streams-per-connection ;
https-port ;
interface-interval ;
ipv4only-contact ;
ipv4only-enable ;
ipv4only-server ;
ixfr-from-differences ( primary | master | secondary | slave |
);
keep-response-order { ; ... };
key-directory ;
lame-ttl ;
listen-on [ port ] [ dscp
] [ tls ] [ http
] { ; ... };
listen-on-v6 [ port ] [ dscp
] [ tls ] [ http
] { ; ... };
lmdb-mapsize ;
lock-file ( | none );
managed-keys-directory ;
masterfile-format ( raw | text );
masterfile-style ( full | relative );
match-mapped-addresses ;
max-cache-size ( default | unlimited | | );
max-cache-ttl ;
max-clients-per-query ;
max-ixfr-ratio ( unlimited | );
max-journal-size ( default | unlimited | );
max-ncache-ttl ;
max-records ;
max-recursion-depth ;
max-recursion-queries ;
max-refresh-time ;
max-retry-time ;
max-rsa-exponent-size ;
max-stale-ttl ;
max-transfer-idle-in ;
max-transfer-idle-out ;
max-transfer-time-in ;
max-transfer-time-out ;
max-udp-size ;
max-zone-ttl ( unlimited | );
memstatistics ;
memstatistics-file ;
message-compression ;
min-cache-ttl ;
min-ncache-ttl ;
min-refresh-time ;
min-retry-time ;
minimal-any ;
minimal-responses ( no-auth | no-auth-recursive | );
multi-master ;
new-zones-directory ;
no-case-compress { ; ... };
nocookie-udp-size ;
notify ( explicit | master-only | primary-only | );
notify-delay ;
notify-rate ;
notify-source ( | * ) [ port ( | * ) ] [
dscp ];
notify-source-v6 ( | * ) [ port ( | * ) ]
[ dscp ];
notify-to-soa ;
nta-lifetime ;
nta-recheck ;
nxdomain-redirect ;
parental-source ( | * ) [ port ( | * ) ] [
dscp ];
parental-source-v6 ( | * ) [ port ( | * )
] [ dscp ];
pid-file ( | none );
port ;
preferred-glue ;
prefetch [ ];
provide-ixfr ;
qname-minimization ( strict | relaxed | disabled | off );
query-source ( ( [ address ] ( | * ) [ port (
| * ) ] ) | ( [ [ address ] ( | * ) ]
port ( | * ) ) ) [ dscp ];
query-source-v6 ( ( [ address ] ( | * ) [ port (
| * ) ] ) | ( [ [ address ] ( | * ) ]
port ( | * ) ) ) [ dscp ];
querylog ;
random-device ( | none );
rate-limit
{
all-per-second ;
errors-per-second ;
exempt-clients { ; ... };
ipv4-prefix-length ;
ipv6-prefix-length ;
log-only ;
max-table-size ;
min-table-size ;
nodata-per-second ;
nxdomains-per-second ;
qps-scale ;
referrals-per-second ;
responses-per-second ;
slip ;
window ;
};
recursing-file ;
recursion ;
recursive-clients ;
request-expire ;
request-ixfr ;
request-nsid ;
require-server-cookie ;
reserved-sockets