5.1. named.conf - named program's configuration¶
5.1.1. Description¶
named.conf is the configuration file for named(8),
the DNS nameserver daemon.
5.1.2. Configuration grammar¶
The configuration file consists of configuration 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. Clauses in the statements are also semi-colon terminated. See the Comments syntax section for a description of comments, and the Loop User Manual for some examples.
named.conf supports the following statements:
aclDefines a named IP address matching list, for access control and other uses.
controlsDeclares remote control channels to be used by rndc to communicate with a named process.
includeIncludes a config file.
keySpecifies key information for use in authentication and authorization with TSIG, or the rndc control channel.
loggingSpecifies what the server logs, and where.
managed-keysSpecifies DNSSEC trust anchors to be kept up-to-date using RFC 5011 trust anchor maintenance.
mastersDefines a named masters list for inclusion in stub and slave zones'
mastersandalso-notifylists.optionsSpecifies global nameserver config options, which also sets the default values for some config options at the
viewandzonestatements.serverSpecifies some config options on a per-server basis.
trusted-keysSpecifies static DNSSEC trust anchors.
viewDefines a view, and specifies some config options at that view level.
zoneDefines a zone, and specifies some config options at that zone level.
Note
The logging and options statements may occur only once
in the configuration file.
5.1.2.1. Data types¶
Following is a list of data types used throughout the Loop configuration file:
<address_match_element>
<address_match_element>lists are primarily used to control access for various nameserver operations. They are also used in thelisten-onstatement. The elements which constitute an<address_match_element>list can be any of the following:
An IP address (IPv4 or IPv6)
An IP prefix (in `/' notation)
A key ID, as defined by the
keystatementThe name of an
<address_match_element>list defined with theaclstatementA nested
<address_match_element>list enclosed in braces
<address_match_element>s can be negated with!(a leading exclamation mark). Some pre-defined named<address_match_element>lists can be found in the description of theaclstatement.The addition of the
keyclause made the name of this type something of a misnomer, as security keys can be used to validate access without regard to an IP address. Nonetheless, the type is still called<address_match_element>.When a given IP address or prefix is compared to an
<address_match_element>list, the matching takes place in approximately O(1) time. However, key matching require that the list of keys be traversed until a matching key is found, and therefore may be somewhat slower as it is an O(N) operation.The interpretation of a match depends on whether the list is being used for access-control, or defining
listen-onports, and whether the<address_match_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, andblockall use<address_match_element>lists. Similarly, thelisten-onoption will cause the server to refuse queries on any of the machine's addresses which do not match the list.The order of insertion is significant. If more than one
<address_match_element>in an ACL is found to match a given IP address or prefix, preference will be 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, in1.2.3/24; ! 1.2.3.13;the 1.2.3.13 element is completely useless because the algorithm will match any lookup for 1.2.3.13 to the 1.2.3/24 element. Using! 1.2.3.13; 1.2.3/24fixes that problem by having 1.2.3.13 blocked by the negation, but all other 1.2.3.* hosts fall through.
<boolean>A boolean type. Takes the values
yesorno. The valuestrueandfalseare also accepted, as are the numbers1and0.
fixedpoint
integer
log_severity
netprefix
portrange
quoted_string
rrtypelist
server_key
size_no_default
sizeval
string
ttlval
Error
TODO: Complete the list of data types.
5.1.2.2. acl statement¶
acl <name:string> { <value:address_match_element>; ... }; // may occur multiple times
The acl statement defines a named access control list (ACL). It
assigns the given list of address match elements to the symbolic name
specified by name. The acl statement gets its name from a primary
use of address match elements which is in access control lists (ACLs).
The following ACL names are built into named:
anymatches all hosts.nonematches no hosts.localhostmatches the IPv4 and IPv6 addresses of all network interfaces on the system. When addresses are added or removed, thelocalhostACL element is updated to reflect the changes.localnetsmatches any host on an IPv4 or IPv6 network for which the system has an interface. When addresses are added or removed, thelocalnetsACL 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 a case,localnetsonly matches the local IPv6 addresses, just likelocalhost.
5.1.2.3. controls statement¶
controls {
inet ( <ipv4_address> | <ipv6_address> | * ) [ port ( <integer> | * ) ] allow { <allow:address_match_element>; ... } [ keys { <keys:string>; ... } ]; // may occur multiple times
}; // may occur multiple times
The controls statement declares control channels to be used by
system administrators to control the operation of
named. These control channels are used by the rndc
program to send commands to and retrieve results from named.
An inet control channel is a TCP socket listening at the specified
port number and IP address (which can be an IPv4 or IPv6 address). An IP
address specified as * (asterisk) is interpreted as the IPv4
wildcard address; connections will be accepted on any of the system's
IPv4 addresses. To listen on the IPv6 wildcard address, use an IP
address specified as ::. If you will only use rndc on the
localhost, using the loopback address (127.0.0.1 or ::1) is
recommended for maximum security.
If no port is specified, port number 953 is used by default. *
cannot be used for the port number.
Error
TODO: The grammar allows * for the port, so this
should be fixed to default to 953 when * is specified for
the 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_element list. This is for
simple IP address based filtering only; any key elements in the
address_match_element list are ignored.
The primary authorization mechanism of the control channel is the
keys list, which contains a list of key_ids. Each key_id in
the keys list is authorized to execute commands over the control
channel. See rndc.conf(5) for information about configuring
keys for rndc.
If no controls statement is present, named will set 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 will attempt to load the command channel key from the
file /etc/loop/rndc.key. To create this file, run:
$ rndc-confgen -a
The rndc.key feature does not have a high degree of
configurability. You cannot easily change the key name or the size of
the secret, so you should make an rndc.conf(5) configuration
file with your own key if you wish to change those settings. The
rndc.key file also has its permissions set such that only the owner
of the file (the user that named is running as) can access
it. If you desire greater flexibility in allowing other users to run
rndc commands, then you need to create an
rndc.conf(5) file and make it group readable by a group that
contains the users who should have access.
To disable the command channel, use an empty controls statement:
controls {};
5.1.2.4. include statement¶
include <quoted_string>;
The include statement inserts the specified file at the point where
the include statement is encountered. Glob patterns such as *
are supported in the filename, and all matching files are included.
The include statement facilitates the administration of
configuration files by permitting the reading or writing of some files
but not others. For example, the statement could include files with keys
that are readable only by the user the nameserver is running as.
5.1.2.5. key statement¶
key <string> {
algorithm <string>;
secret <string>;
}; // may occur multiple times
The key statement defines a shared secret key for use with TSIG or
the control channel (see controls statement).
The key statement can occur at the top level of the configuration
file, or within a view statement. Keys defined in top-level key
statements can be used in all views. Keys intended for use in a
controls statement must be defined at the top-level.
After the key keyword, the key statement contains a string which is
the key ID (also known as a key name) which is a DNS name that uniquely
identifies the key. It can be used in a server statement to cause
requests sent to that server to be TSIG-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 clause contains a string specifying the HMAC
algorithm. named supports hmac-md5, hmac-sha1,
hmac-sha224, hmac-sha256, hmac-sha384 and hmac-sha512
algorithms. Truncated hashes are supported by appending the minimum
number of required bits preceded by a dash, e.g. hmac-sha1-80.
Error
TODO: Remove support for truncated hashes.
The secret clause specifies the secret to be used by the HMAC
algorithm in Base64 encoding (RFC 4648).
The ddns-confgen program can be used with the -q argument
to generate just a key statement:
$ ddns-confgen -q
key "ddns-key" {
algorithm hmac-sha256;
secret "gxSW0mdkZ9o90OuxruPiqbxiaZjKyZ9+cst/cRu8Np0=";
};
$
5.1.2.6. logging statement¶
logging {
channel <string> {
file <quoted_string> [ versions ( "unlimited" | <integer> ) ] [ size <size> ];
syslog [ <syslog_facility> ];
null;
stderr;
severity <log_severity>;
print-time <boolean>;
print-severity <boolean>;
print-category <boolean>;
}; // may occur multiple times
category <name:string> { <destinations:string>; ... }; // may occur multiple times
};
The logging statement configures a wide variety of logging options
for named.. 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 to be used to define as many channels
and categories as are wanted. If there is no logging statement, the
logging configuration will be:
logging {
category default { default_syslog; default_debug; };
category unmatched { null; };
};
Note
The logging statement may occur only once in the
configuration file.
In Loop, the logging configuration is only established when the entire
configuration file has been parsed. When the server is starting up, all
logging messages regarding syntax errors in the configuration file go to
the default channels, or to standard error if the named
-g argument was specified.
5.1.2.6.1. channel phrase¶
All log output goes to one or more channels; you can make as many of them as you want.
Every channel definition must include a destination clause that says
whether messages selected for the channel go to a file, or to a
particular syslog facility, or to the standard error stream, or are
discarded. It can optionally also limit the message severity level that
will be accepted by the channel (the default is info), and whether
to include a named-generated time stamp, the category name,
and/or severity level. The default is not to include any.
- file <quoted_string> [ versions ( "unlimited" | <integer> ) ] [ size <size> ]¶
The
filedestination clause directs the channel to a disk file. It can include limitations both on how large the file is allowed to become, and how many versions of the file will be saved each time the file is opened.If you use the
versionslog file option, then named will retain that many backup versions of the file by renaming them when opening. For example, if you choose to keep three old versions of the filelamers.log, then just before it is openedlamers.log.1is renamed tolamers.log.2,lamers.log.0is renamed tolamers.log.1, andlamers.logis renamed tolamers.log.0. You can useversions unlimitedto not limit the number of versions. If asizeoption is associated with the log file, then renaming is only done when the file being opened exceeds the indicated size. No backup versions are kept by default; any existing log file is simply appended to.The
sizeoption for files is used to limit log growth. If the file ever exceeds the size, thennamedwill stop writing to the file unless it has aversionsoption associated with it. If backup versions are kept, the files are rolled as described above and a new one begun. If there is noversionsoption, no more data will be 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.Example usage of the
sizeandversionsoptions:channel an_example_channel { file "example.log" versions 3 size 20m; print-time yes; print-category yes; };
- syslog [ <syslog_facility> ]¶
The
syslogdestination clause directs the channel to the system log (see syslog(3)). Its argument is a syslog facility as described in the openlog(3) manpage. Known facilities arekern,user,mail,daemon,auth,syslog,lpr,news,uucp,cron,authpriv,ftp,local0,local1,local2,local3,local4,local5,local6andlocal7, however not all facilities are supported on all operating systems. How the syslog daemon will handle messages sent to this facility would be described in its documentation.
- null¶
The
nulldestination clause causes all messages sent to the channel to be discarded; in that case, other options for the channel are meaningless.
- stderr¶
The
stderrdestination 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, for example, when the administrator is debugging a configuration.The server can supply extensive debugging information when it is in debugging mode. If the server's global debug level is greater than zero, then debugging mode will be active. The global debug level is set either by starting named with the
-dargument followed by a positive integer, or by running therndc tracecommand. The global debug level can be set to zero, and debugging mode turned off, by runningrndc notrace. All debugging messages in the server have a debug level, and 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; };
will get debugging output of level 3 or less any time the server is in debugging mode, regardless of the global debugging level. Channels with
dynamicseverity use the server's global debug level to determine what messages to print.
- severity <log_severity>¶
The
severityclause works like syslog(3)'s "priorities", except that they can also be used if you are writing straight to a file rather than usingsyslog. Messages which are not at least of the severity level given will not be selected for the channel; messages of higher severity levels will be accepted.If you are using
syslog, then the syslog daemon configuration's priorities will also determine what eventually passes through. For example, defining a channel facility and severity asdaemonanddebugbut only loggingdaemon.warningvia the syslog daemon configuration's will cause messages of severityinfoandnoticeto be dropped. If the situation were reversed, with named writing messages of onlywarningor higher, then the syslog daemon would allow all messages it received from the channel.
- print-time <boolean>¶
If
print-timeis enabled, then the date and time will be logged.print-timemay be specified for asyslogchannel, but is usually pointless sincesyslogalso logs the date and time.
- print-severity <boolean>¶
If
print-severityis enabled, then the severity level of the message will be logged.
- print-category <boolean>¶
If
print-categoryis is enabled, then the category of the message will be logged as well.
The print-time, print-severity, and print-category options
may be used in any combination, and will always be printed in the
following order: time, category, severity. Here is an example where all
the three options are enabled:
28-Feb-2000 15:05:32.863 general: notice: running
There are four predefined channels that are used for named's default logging as follows. (See category phrase for how they are used.)
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 '-f' 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;
};
The default_debug channel has the special property that it only
produces output when the server's debug level is nonzero. It normally
writes to a file called named.run in the server's working
directory.
For security reasons, when the named -u argument 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 up and still running as root is
discarded. If you need to capture this output, you must run
named with the -g argument and redirect standard error to
a file.
Once a channel is defined, it cannot be redefined. Thus you cannot alter the built-in channels directly, but you can modify the default logging by pointing categories at channels you have defined.
5.1.2.6.2. category phrase¶
There are many categories, so you can send the logs you want to see
wherever you want, without seeing logs you don't want. If you don't
specify a list of channels for a category, then log messages in that
category will be sent to the default category instead. If you don't
specify a default category, the following "default default" is used:
category default { default_syslog; default_debug; };
As an example, let's say you want to log security events to a file, but you also want keep the default logging behavior. You'd 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 is a list of available categories and brief descriptions of the types of log information they contain. More categories may be added in future Loop releases.
clientProcessing of client requests.
cnameLogs nameservers that are skipped due to them being a CNAME rather than A / AAAA records.
configConfiguration file parsing and processing.
databaseMessages relating to the databases used internally by the name server to store zone and cache data.
defaultThe default category defines the logging options for those categories where no specific configuration has been defined.
delegation-onlyDelegation-only. Logs queries that have been forced to NXDOMAIN as the result of a delegation-only zone or a
delegation-onlyin a forward, hint or stub zone declaration.dispatchDispatching of incoming packets to the server modules where they are to be processed.
dnssecDNSSEC and TSIG protocol processing.
edns-disabledLog 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 RFC 1034 non-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 on DNSSEC validation which requires EDNS for the DNSSEC records to be returned.
generalThe catch-all category. Many messages still aren't classified into categories, and they will end up in the
generalcategory.lame-serversLame servers. These are misconfigurations in remote servers, discovered by Loop when trying to query those servers during resolution.
networkNetwork operations.
notifyDNS NOTIFY related.
queriesSpecify where queries should be logged to.
At startup, specifying the category
querieswill also enable query logging unless thequerylogoption has been configured.The query log entry reports the client's IP address, port number, the query name, class, and type. Next it reports whether the RD (Recursion Desired) flag was set (+ if set, - if not set), if the query was signed (S), if EDNS was used (E), if TCP was used (T), if DO (DNSSEC Ok) flag was set (D), or if CD (Checking Disabled) flag was set (C). After this, the destination address the query was sent to is reported.
For example,
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-errorsInformation about queries that resulted in some failure. The
query-errorscategory is specifically intended for debugging purposes: To identify why and how specific queries result in responses which indicate an error. Messages of this category are therefore only logged withdebuglevels.At the debug levels of 1 or higher, 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:3880This means an error resulting in SERVFAIL was detected at line 3880 of source code file
query.c. Log messages of this level will particularly help identify the cause of SERVFAIL for an authoritative server.At the debug levels of 2 or higher, detailed context information of recursive resolutions that resulted in SERVFAIL is logged. The log message will look like as follows:
fetch completed at resolver.c:2970 for www.example.com/A in 30.000183: timed out/success [domain:example.com,referral:2,restart:7,qrysent:8,timeout:5,lame: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 30.000183 seconds and the final result that led to the SERVFAIL was determined at line 2970 of source code file
resolver.c.The next part of the log message shows the detected final result and the latest result of DNSSEC validation. The latter is always success when no validation attempt is made. In this example, this query resulted in SERVFAIL probably because all name servers are down or unreachable, leading to a timeout in 30 seconds. DNSSEC validation was probably not attempted.
The last part of the log message enclosed in square brackets shows statistics information collected for this particular resolution attempt. The meaning of these fields is summarized below:
domainThe
domainfield 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 table.referralThe number of referrals the resolver received throughout the resolution process. In the above example this is 2, which are most likely com. and example.com.
restartThe number of cycles that the resolver tried remote nameservers at the
domainzone. In each cycle the resolver sends one query (possibly resending it, depending on the response) to each known nameserver of thedomainzone.qrysentThe number of queries the resolver sent at the
domainzone.timeoutThe number of timeouts since the resolver received the last response.
lameThe number of lame servers the resolver detected at the
domainzone. A server is detected to be lame by an invalid response.neterrThe number of erroneous results that the resolver encountered in sending queries at the
domainzone. One common case is the remote server is unreachable and the resolver receives an ICMP unreachable error message.badrespThe number of unexpected responses (other than
lame) to queries sent by the resolver at thedomainzone.adberrFailures in finding remote nameserver addresses of the
domainzone in the ADB. One common case of this is that the remote nameserver's hostname does not have any address records.findfailFailures of resolving remote server addresses. This is a total number of failures throughout the resolution process.
valfailFailures of DNSSEC validation. Validation failures are counted throughout the resolution process (not limited to the
domainzone), but should only happen indomain.At the debug levels of 3 or higher, the same messages as those at the debug 1 level are logged for other errors than SERVFAIL. Note that negative responses such as NXDOMAIN are not regarded as errors here.
At the debug levels of 4 or higher, the same messages as those at the debug 2 level are logged for other errors than SERVFAIL. Unlike the above case of level 3, messages are logged for negative responses. This is because any unexpected results can be difficult to debug in the recursion case.
rate-limitThe start, periodic, and final notices of the rate-limiting of a stream of responses are logged at
infoseverity 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 limit stops. A lack of memory can hurry the final notice, in which case it starts with*(asterisk). Various internal events are logged at debug level 1 and higher.Rate limiting of individual requests is logged in the
query-errorscategory.resolverDNS resolution, such as the recursive lookups performed on behalf of clients by a caching name server.
rpzInformation about errors in response policy zone files, rewritten responses, and at the highest
debuglevels, mere rewriting attempts.securityApproval and denial of requests.
spillLogs queries that have been terminated, either by dropping or responding with SERVFAIL, as a result of a fetchlimit quota being exceeded.
unmatchedMessages 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 theclientcategory. This category is best sent to a file or stderr, by default it is sent to thenullchannel.updateDNS UPDATE related.
update-securityApproval and denial of update requests.
xfer-inZone transfers the server is receiving.
xfer-outZone transfers the server is sending.
5.1.2.7. managed-keys statement¶
managed-keys { <name:string> <init:string> <flags:integer> <protocol:integer> <algorithm:integer> <key:quoted_string>; ... }; // may occur multiple times
The managed-keys statement (like the
trusted-keys statement), defines DNSSEC trust
anchors. The difference is that managed-keys specifies dynamic trust
anchors that can be kept up-to-date automatically, without intervention
from the resolver operator (see RFC 5011).
Suppose, for example, that a zone's key-signing key (KSK) was
compromised, and the zone owner had to revoke and replace the key. A
resolver which had the old key configured as a trust anchor in a
trusted-keys statement would be unable to validate this zone any
longer; it would reply with a SERVFAIL response code. This would
continue until the resolver operator had updated the trusted-keys
statement with the new key.
If, however, the zone were listed in a managed-keys statement
instead, then the zone owner could add a "stand-by" key to the zone in
advance. named would retrieve and store the stand-by key, and
when the original key was revoked, named would be able to
transition smoothly to the new trust anchor. It would also recognize
that the old key had been revoked, and cease using that key as a trust
anchor to validate answers, minimizing the damage that the compromised
key could do.
A managed-keys statement contains a list of the keys to be managed,
along with information about how the keys are to be initialized for the
first time using the init field. The only initialization method
currently supported is initial-key. This means the managed-keys
statement must contain a copy of the initializing key. (Future releases
may allow keys to be initialized by other methods, eliminating this
requirement.)
Consequently, a managed-keys statement appears similar to a
trusted-keys statement, differing in the presence of the second
field containing the keyword initial-key. The difference is that,
whereas the keys listed in a trusted-keys continue to be trusted
until they are removed from the config file, an initializing key listed
in a managed-keys statement is only trusted once: for as long as
it takes to load the managed key database and start the RFC 5011 key
maintenance process.
The first time named runs with a managed key configured in
the config file, it fetches the DNSKEY RRset directly from the zone's
apex, and validates it using the key specified in the managed-keys
statement. If the DNSKEY RRset is validly signed, then it is used as the
basis for a new managed keys database.
From that point on, whenever named runs, it sees the
managed-keys statement and checks to make sure RFC 5011 key
maintenance has already been initialized for the specified domain, and
if so, it simply moves on. The key specified in the managed-keys
statement in the config file is not used to validate answers; it has
been superseded by the key or keys stored in the managed keys database.
The next time named runs after a name has been removed from
the managed-keys statement, the corresponding zone will be removed
from the managed keys database, and RFC 5011 key maintenance will no
longer be used for that domain.
In the current implementation, the managed keys database is stored in a master-format zone file using experimental RR types.
On servers which do not use views, this file is named
managed-keys.loop. When views are in use, there will be a separate
managed keys database for each view; the filename will be a hash of the
view name followed by the suffix .mkeys.
When the key database is changed, the zone is updated. As with any other
dynamic zone, changes will be written into a journal file, e.g.,
managed-keys.loop.jnl. Changes are committed to the master file as
soon as possible afterward; this will usually occur within 30 seconds.
So, whenever named is using automatic key maintenance, the
zone file and journal file can be expected to exist in the working
directory.
Note
Unless the managed-keys-directory option is configured,
the working directory (see the directory option) should be
writable by named so that it can write to the
managed-keys database.
If the dnssec-validation option is set to auto, named
will automatically initialize a managed key for the root zone. The key
that is used to initialize the key maintenance process is built-in and
can be overridden with the dnssec-keys-file option.
5.1.2.8. masters statement¶
masters <name:string> [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <masters> | <ipv4_address> [ port <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <key:string> ]; ... }; // may occur multiple times
The masters statement can be used to specify a common set of masters
(a masters list) that can be used by multiple stub and slave zones in
their masters or also-notify lists. It is a convenience feature
so that the same masters need not be specified multiple times.
Error
TODO: Expand this description, and add examples.
5.1.2.9. options statement¶
options {
automatic-interface-scan <boolean>;
avoid-v4-udp-ports { <portrange>; ... };
avoid-v6-udp-ports { <portrange>; ... };
dnssec-keys-file <quoted_string>;
block { <address_match_element>; ... };
coresize ( default | unlimited | <sizeval> );
datasize ( default | unlimited | <sizeval> );
directory <quoted_string>;
dscp <integer>;
dump-file <quoted_string>;
files ( default | unlimited | <sizeval> );
flush-zones-on-shutdown <boolean>;
heartbeat-interval <integer>;
interface-interval <integer>;
listen-on [ port <port:integer> ] [ dscp <dscp:integer> ] { <acl:address_match_element>; ... }; // may occur multiple times
listen-on-v6 [ port <port:integer> ] [ dscp <dscp:integer> ] { <acl:address_match_element>; ... }; // may occur multiple times
managed-keys-directory <quoted_string>;
match-mapped-addresses <boolean>;
max-rsa-exponent-size <integer>;
pid-file ( <quoted_string> | none );
port <integer>;
querylog <boolean>;
recursing-file <quoted_string>;
recursive-clients <integer>;
reserved-sockets <integer>;
secroots-file <quoted_string>;
serial-query-rate <integer>;
server-id ( <quoted_string> | none | hostname );
session-keyalg <string>;
session-keyfile ( <quoted_string> | none );
session-keyname <string>;
cookie-algorithm ( hmac-sha256 | siphash );
cookie-secret <string>;
stacksize ( default | unlimited | <sizeval> );
statistics-file <quoted_string>;
tcp-clients <integer>;
tcp-listen-queue <integer>;
tkey-dhkey <name:quoted_string> <keyid:integer>;
tkey-domain <quoted_string>;
tkey-gssapi-credential <quoted_string>;
tkey-gssapi-keytab <quoted_string>;
transfers-in <integer>;
transfers-out <integer>;
transfers-per-ns <integer>;
use-v4-udp-ports { <portrange>; ... };
use-v6-udp-ports { <portrange>; ... };
version ( <quoted_string> | none );
allow-new-zones <boolean>;
allow-query-cache { <address_match_element>; ... };
allow-query-cache-on { <address_match_element>; ... };
allow-recursion { <address_match_element>; ... };
allow-recursion-on { <address_match_element>; ... };
attach-cache <string>;
auth-nxdomain <boolean>; // default changed
cache-file <quoted_string>; // test only
check-names ( master | slave | response ) ( fail | warn | ignore ); // may occur multiple times
clients-per-query <integer>;
deny-answer-addresses { <acl:address_match_element>; ... } [ except-from { <except-from:quoted_string>; ... } ];
deny-answer-aliases { <name:quoted_string>; ... } [ except-from { <except-from:quoted_string>; ... } ];
disable-algorithms <domain:string> { <algorithms:string>; ... }; // may occur multiple times
disable-ds-digests <domain:string> { <digests:string>; ... }; // may occur multiple times
disable-empty-zone <string>; // may occur multiple times
dns64 <netprefix> {
break-dnssec <boolean>;
clients { <address_match_element>; ... };
exclude { <address_match_element>; ... };
mapped { <address_match_element>; ... };
recursive-only <boolean>;
suffix <ipv6_address>;
}; // may occur multiple times
dns64-contact <string>;
dns64-server <string>;
dnssec-enable <boolean>;
dnssec-must-be-secure <domain:string> <value:boolean>; // may occur multiple times
dnssec-validation ( yes | no | auto );
dual-stack-servers [ port <port:integer> ] { ( <quoted_string> [ port <integer> ] [ dscp <integer> ] | <ipv4_address> [ port <integer> ] [ dscp <integer> ] | <ipv6_address> [ port <integer> ] [ dscp <integer> ] ); ... };
edns-udp-size <integer>;
empty-contact <string>;
empty-server <string>;
empty-zones-enable <boolean>;
fetch-quota-params <frequency:integer> <low:fixedpoint> <high:fixedpoint> <discount:fixedpoint>;
fetches-per-server <fetches:integer> [ ( drop | fail ) ];
fetches-per-zone <fetches:integer> [ ( drop | fail ) ];
ixfr-from-differences ( master | slave | <boolean> );
max-cache-size <size_no_default>;
max-cache-ttl <integer>;
max-clients-per-query <integer>;
max-ncache-ttl <integer>;
max-recursion-depth <integer>;
max-recursion-queries <integer>;
max-udp-size <integer>;
minimal-responses <boolean>;
no-case-compress { <address_match_element>; ... };
nocookie-udp-size <integer>;
preferred-glue <string>;
prefetch <trigger:integer> [ <integer> ];
provide-ixfr <boolean>;
query-source ( ( [ address ] ( <ipv4_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv4_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];
query-source-v6 ( ( [ address ] ( <ipv6_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv6_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];
rate-limit {
all-per-second <integer>;
errors-per-second <integer>;
exempt-clients { <address_match_element>; ... };
ipv4-prefix-length <integer>;
ipv6-prefix-length <integer>;
log-only <boolean>;
max-table-size <integer>;
min-table-size <integer>;
nodata-per-second <integer>;
nxdomains-per-second <integer>;
qps-scale <integer>;
referrals-per-second <integer>;
responses-per-second <integer>;
slip <integer>;
window <integer>;
};
recursion <boolean>;
request-nsid <boolean>;
request-cookie <boolean>;
resolver-query-timeout <integer>;
response-policy { zone <quoted_string> [ policy ( cname | disabled | drop | given | no-op | nodata | nxdomain | passthru | tcp-only <cname:quoted_string> ) ] [ recursive-only <boolean> ] [ max-policy-ttl <integer> ]; ... } [ recursive-only <boolean> ] [ break-dnssec <boolean> ] [ max-policy-ttl <integer> ] [ min-ns-dots <integer> ] [ qname-wait-recurse <boolean> ];
root-delegation-only [ exclude { <quoted_string>; ... } ];
rrset-order ( none | random );
zero-no-soa-ttl-cache <boolean>;
allow-notify { <address_match_element>; ... };
allow-query { <address_match_element>; ... };
allow-query-on { <address_match_element>; ... };
allow-transfer { <address_match_element>; ... };
allow-update { <address_match_element>; ... };
allow-update-forwarding { <address_match_element>; ... };
also-notify [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <masters> | <ipv4_address> [ port <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <key:string> ]; ... };
alt-transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
alt-transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
auto-dnssec ( allow | maintain | off );
check-dup-records ( fail | warn | ignore );
check-integrity <boolean>;
check-mx ( fail | warn | ignore );
check-mx-cname ( fail | warn | ignore );
check-sibling <boolean>;
check-spf ( warn | ignore );
check-srv-cname ( fail | warn | ignore );
check-wildcard <boolean>;
dialup ( notify | notify-passive | passive | refresh | <boolean> );
dnssec-dnskey-kskonly <boolean>;
dnssec-loadkeys-interval <integer>;
dnssec-secure-to-insecure <boolean>;
dnssec-update-mode ( maintain | no-resign );
forward ( first | only );
forwarders [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <ipv4_address> | <ipv6_address> ) [ port <integer> ] [ dscp <integer> ]; ... };
inline-signing <boolean>;
key-directory <quoted_string>;
max-journal-size <size_no_default>;
max-records <integer>;
max-refresh-time <integer>;
max-retry-time <integer>;
max-transfer-idle-in <integer>;
max-transfer-idle-out <integer>;
max-transfer-time-in <integer>;
max-transfer-time-out <integer>;
max-zone-ttl ( unlimited | <ttlval> );
min-refresh-time <integer>;
min-retry-time <integer>;
multi-master <boolean>;
notify ( explicit | master-only | <boolean> );
notify-delay <integer>;
notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
notify-to-soa <boolean>;
nsec3-test-zone <boolean>; // test only
request-ixfr <boolean>;
serial-update-method ( increment | unixtime );
sig-signing-nodes <integer>;
sig-signing-signatures <integer>;
sig-signing-type <integer>;
sig-validity-interval <validity:integer> [ <integer> ];
transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
try-tcp-refresh <boolean>;
update-check-ksk <boolean>;
use-alt-transfer-source <boolean>;
zero-no-soa-ttl <boolean>;
zone-statistics ( full | terse | none | <boolean> );
};
The options statement sets up global options to be used by Loop. If
there is no options statement, an options statement with each option
set to its default value will be used.
Note
The options statement may occur only once in the
configuration file.
- automatic-interface-scan <boolean>¶
Automatically rescan network interfaces when the interface addresses are added or removed. This feature uses routing sockets provided by the operating system. The default is
yes.
- avoid-v4-udp-ports { <portrange>; ... }¶
TBD.
- avoid-v6-udp-ports { <portrange>; ... }¶
TBD.
- dnssec-keys-file <quoted_string>¶
The pathname of a file to override the built-in DNSSEC trust anchors of named. It is not configured by default. See the discussion of
dnssec-validationfor details.named only loads the root zone's trust anchors from the specified file. The file cannot be used to provide trust anchors for other zones. The trust anchors in
dnssec-keys-fileare not used ifdnssec-validation autois not in use.Warning
The use of
dnssec-keys-fileis discouraged. Keeping the Loop software up-to-date is recommended instead, whereby the built-in trust anchors will always be the latest version.
- block { <address_match_element>; ... }¶
Specifies a list of addresses that the server will not accept queries from or use to resolve a query. Queries from these addresses will be dropped. The default value is
none.
- coresize ( default | unlimited | <sizeval> )¶
The maximum size of a core dump. The default value is
default.Error
TODO: This description should be updated to describe what
defaultmeans.
- datasize ( default | unlimited | <sizeval> )¶
The maximum amount of data memory the server may use. The default value is
default. This is a hard limit on server memory usage. If the server attempts to allocate memory in excess of this limit, the allocation will fail, which may in turn leave the server unable to perform DNS service. Therefore, this option is rarely useful as a way of limiting the amount of memory used by the server, but it can be used to raise an operating system data size limit that is too small by default. If you wish to limit the amount of memory used by the server, use themax-cache-sizeandrecursive-clientsoptions instead.Error
TODO: This description should be updated to describe what
defaultmeans.
- directory <quoted_string>¶
The working directory of the server. The directory specified should be an absolute path. Any non-absolute pathnames in the configuration file will be taken as relative to this directory. The default location for most server output files (e.g. :
named.run) is this directory. The default value is.(the directory from which the server was started).Note
It is strongly recommended that the directory be writable by the effective user ID of the named process. For example, unless the
managed-keys-directoryoption is configured, the working directory should be writable by named so that it can write to themanaged-keysdatabase.
- dscp <integer>¶
The global DSCP (Differentiated Services Code Point) value to classify outgoing DNS traffic. Valid values are between 0 and 63 inclusive. It is not configured by default.
- dump-file <quoted_string>¶
Pathname of the file that named dumps the database to when instructed to do so with the rndc
dumpdbcommand. The default value isnamed_dump.db.
- files ( default | unlimited | <sizeval> )¶
The maximum number of files the server may have open concurrently. The default value is
unlimited.
- flush-zones-on-shutdown <boolean>¶
This option controls whether to flush or not flush any pending zone writes when the nameserver exits because it received a SIGTERM signal. The default value is
no.Error
TODO: Check if it applies only due to SIGTERM or to other cases of shutdown too.
- heartbeat-interval <integer>¶
named will perform zone maintenance tasks for all zones marked as
dialupwhenever this interval expires. The default value 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 will occur.Error
TODO: specify units
- interface-interval <integer>¶
named will scan the network interface list every
interface-intervalminutes. The default value is 60 minutes. The maximum value is 28 days (40320 minutes). If set to 0, interface scanning will only occur when the configuration file is loaded. After the scan, the named will begin listening for queries on any newly discovered interfaces (provided they are configured by thelisten-onconfiguration), and will stop listening on interfaces that have gone away.
- listen-on [ port <port:integer> ] [ dscp <dscp:integer> ] { <acl:address_match_element>; ... }; // may occur multiple times¶
TBD.
- listen-on-v6 [ port <port:integer> ] [ dscp <dscp:integer> ] { <acl:address_match_element>; ... }; // may occur multiple times¶
TBD.
- managed-keys-directory <quoted_string>;¶
Specifies the directory in which named stores the
managed-keyszone master files. The default value is the working directory (see thedirectoryoption).Note
The directory must be writable by the effective user ID of the named process.
If named is not configured to use views, then managed keys for the server will be tracked in a single zone master file called
managed-keys.loop. Otherwise, managed keys will be tracked in separate files, one file per view; each file name will be the SHA-256 hash of the view name, followed by the extension.mkeys.
- match-mapped-addresses <boolean>;¶
If enabled, an IPv4-mapped IPv6 address will match any address match elements that match the corresponding IPv4 address. The default value is no.
This option was introduced to work around a kernel quirk in some operating systems that causes IPv4 TCP connections, such as zone transfers, to be accepted on an IPv6 socket using mapped addresses. This caused address match lists designed for IPv4 to fail to match. Using this option, named solves this problem internally. The use of this option is discouraged.
Error
TODO: Check if this option is required going forward.
- max-rsa-exponent-size <integer>;¶
The maximum RSA exponent size, in bits, that will be accepted when validating. Valid values are between 35 and 4096 inclusive. The default value is 0, which equivalent to 4096 bits.
Error
TODO: Check if this option is required going forward. The minimum value is also ridiculously low.
- pid-file ( <quoted_string> | none );¶
The pathname of the file the the named process writes its process ID (PID) to. The default is
/var/run/loop/named.pid. The PID file can be used by programs that want to send signals to the named process. Specifyingnonedisables the use of a PID file; no file will be written and any existing file will be removed.Note
noneis a keyword, not a filename, and therefore must not be enclosed in double quotes.
- port <integer>;¶
The UDP/TCP port number the server uses for receiving and sending DNS protocol traffic. The default value is 53.
Note
This option is mainly intended for testing purposes; a nameserver using a port other than 53 will not be able to communicate with the global DNS.
- dnssec-accept-expired <boolean>;¶
If enabled, named will accept expired signatures when validating DNSSEC signatures. The TTLs of such expired RRsets is limited to 120 seconds. Setting this option to yes leaves named vulnerable to replay attacks. The default value is no.
- querylog <boolean>;¶
If enabled, named logs all queries. The default value is determined by the presence of the logging category
queries.
- recursing-file <quoted_string>;¶
Pathname of the file that named dumps the list of queries that are currently recursing to, when instructed to do so with the rndc
recursingcommand. The default value isnamed.recursing.
- recursive-clients <integer>;¶
The maximum number of simultaneous resolutions the server will perform on behalf of clients. The default value is 1000.
recursive-clientsdefines a limit for pending recursive clients. When more clients than this are waiting on resolution, new incoming resolution requests will result in SERVFAIL responses.
- reserved-sockets <integer>;¶
The number of file descriptors reserved for TCP socket descriptors, standard input, etc. This needs to be big enough to cover the number of interfaces named listens on,
tcp-clientsas well as to provide room for outgoing TCP queries and incoming zone transfers. The default value is 512. The minimum value for this option is 128, and the maximum value is (maxsockets - 128), where maxsockets is set by named-S.Note
This option may be removed in the future.
- secroots-file <quoted_string>;¶
Pathname of the file that named dumps DNSSEC trust anchors to, when instructed to do so with the rndc
secrootscommand. The default value isnamed.secroot.
- serial-query-rate <integer>;¶
Slave servers will periodically query master servers to find out if zone serial numbers have changed. Each such query uses a tiny amount of the slave server's network bandwidth. To limit the amount of bandwidth used, Loop limits the rate at which queries are sent to a maximum of the value of the
serial-query-rateper second. The default value is 20. The minimum value for this option is 1. When set to 0, it is silently increased to 1.In addition to controlling the rate at which SOA refresh queries are issued,
serial-query-ratealso controls the rate at which NOTIFY messages are sent from both master and slave zones.
- server-id ( <quoted_string> | none | hostname );¶
The ID the nameserver should report in the NSID EDNS option in responses, when it receives a query with an NSID (Name Server Identifier) EDNS option (see RFC 5001). The primary purpose of such queries is to identify which of a group of anycast servers is actually answering queries.
A value of
nonecauses named to not return the NSID EDNS option in replies.A value of
hostnamecauses named to return the hostname as found by the gethostname(2) function. This is usually equal to the hostname set on the machine.In all other cases, the specified value is returned in the NSID EDNS option.
The default value is
noneand no NSID EDNS option is returned in responses.Note
noneandhostnameare keywords, and therefore must not be enclosed in double quotes.
- session-keyalg <string>;¶
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. The default value is hmac-sha256.
Error
TODO: Change this option's type to an enum.
- session-keyfile ( <quoted_string> | none );¶
Pathname of the file that named writes a generated TSIG session key to, for use by nsupdate
-l. The default value is/var/run/loop/session.key.Error
TODO: Document the value of
none.See the
update-policystatement'slocaloption for more information about this feature.Note
noneis a keyword, not a filename, and therefore must not be enclosed in double quotes.
- session-keyname <string>;¶
The key name to use for the TSIG session key. The default value is
local-ddns.
- cookie-algorithm ( hmac-sha256 | siphash );¶
The algorithm used for generating and verifying COOKIE EDNS options. The default value is siphash.
- cookie-secret <string>;¶
The secret, encoded as a hex string, used for generating and verifying COOKIE EDNS options. If not set, named will generate a random secret at startup. The secret must be 512 bits long for hmac-sha256 algorithm, and 64 bits long for siphash algorithm.
Error
TODO: Change the encoding to Base64 to align with TSIG and control channel HMAC secrets.
- stacksize ( default | unlimited | <sizeval> );¶
The maximum amount of stack memory the nameserver may use. The default is
default.Error
TODO: This description should be updated to describe what
defaultmeans.
- statistics-file <quoted_string>;¶
Pathname of the file that named appends statistics to, when instructed to do so with the rndc
statscommand. The default value isnamed.stats.
- tcp-clients <integer>;¶
The maximum number of simultaneous client TCP connections that the nameserver will accept. The default value is 100.
- tcp-listen-queue <integer>;¶
The TCP listen queue depth. The default and minimum value is 10. If the kernel supports the "dataready" accept(2) filter, this also controls the number of TCP connections that will be queued in kernel space waiting for some data before being passed to accept(2).
Non-zero values less than 10 will be silently raised to 10.
A value of 0 may also be used. On most platforms this sets the TCP listen queue depth to a system-defined default value.
- tkey-dhkey <name:quoted_string> <keyid:integer>;¶
The Diffie-Hellman key used by the server to generate shared keys with clients using the Diffie-Hellman mode of TKEY. It is not configured by default. The nameserver must be able to load the public and private keys from files in the working directory. In most cases, the key
nameshould be the nameserver's hostname.
- tkey-domain <quoted_string>;¶
The domain name appended to the names of all shared keys generated with TKEY. It is not configured by default.
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 shared key will be:
client specified part + tkey-domainOtherwise, the name of the shared key will be:
random hex digits + tkey-domainIn most cases, the
tkey-domain's value should be the nameserver's domain name, or an otherwise non-existent sub-domain like_tkey.<domain_name>.Note
If you are using GSS-TSIG, this variable must be defined, unless you specify a specific keytab using
tkey-gssapi-keytab.
- tkey-gssapi-credential <quoted_string>;¶
The security credential with which the server should authenticate keys requested by the GSS-TSIG protocol. It is not configured by default. Currently only Kerberos 5 authentication is available and the credential is a Kerberos principal which the server can acquire through the default system Kerberos keytab file, typically
/etc/krb5.keytab. The location of the keytab file can be overridden using thetkey-gssapi-keytaboption. Normally this principal is of the formDNS/<host.domain>.Note
To use GSS-TSIG,
tkey-domainmust also be set if a specific keytab is not set withtkey-gssapi-keytab.
- tkey-gssapi-keytab <quoted_string>;¶
Pathname of the Kerberos 5 keytab file to use for GSS-TSIG updates. It is not configured by default. If this option is configured and
tkey-gssapi-credentialis not configured, then transactions will be allowed with any key matching a principal in the keytab.
- transfers-in <integer>;¶
The maximum number of inbound zone transfers that can occur concurrently. The default value is 10. Increasing
transfers-inmay speed up the convergence of slave zones, but it also may increase the load on the local machine.
- transfers-out <integer>;¶
The maximum number of outbound zone transfers that can occur concurrently. Zone transfer requests in excess of the limit will be refused. The default value is 10.
- transfers-per-ns <integer>;¶
The maximum number of inbound zone transfers that can be concurrently transferring from any single remote nameserver. The default value is 2. Increasing
transfers-per-nsmay speed up the convergence of slave zones, but it also may increase the load on the remote nameserver.transfers-per-nsmay be overridden on a per-nameserver basis by using thetransfersphrase of theserverstatement.
- use-v4-udp-ports { <portrange>; ... };¶
TBD.
- use-v6-udp-ports { <portrange>; ... };¶
TBD.
- version ( <quoted_string> | none );¶
The version the nameserver should report in response to a query of the name
version.loopwith typeTXT, and classCHAOS. The default is the real version number of this server. Specifying a value ofnonedisables processing of the queries.Note
noneis a keyword, and therefore must not be enclosed in double quotes.Error
TODO: "disables processing of the queries" should be described better.
- allow-new-zones <boolean>;¶
If enabled, zones can be dynamically added at runtime via the rndc
addzonecommand, and such dynamically added zones can be deleted via the rndcdelzonecommand. The default value isno.
- allow-query-cache { <address_match_element>; ... };¶
Specifies which hosts are allowed to query answers from the cache. If
allow-query-cacheis not set then the value ofallow-recursionis used if set, otherwise the value ofallow-queryis used if set unlessrecursion no;is set in which casenoneis used, otherwise the default (localnets;localhost;) is used.
- allow-query-cache-on { <address_match_element>; ... };¶
Specifies local addresses to which queries made can give answers from the cache. If not specified, the default is to allow cache queries on any address,
localnetsandlocalhost.
- allow-recursion { <address_match_element>; ... };¶
Specifies which hosts are allowed to make recursive queries through this nameserver. If
allow-recursionis not set thenallow-query-cacheis used if set, otherwiseallow-queryis used if set, otherwise the default (localnets;localhost;) is used.
- allow-recursion-on { <address_match_element>; ... };¶
Specifies which local addresses can accept recursive queries. The default is to allow recursive queries on all addresses.
- attach-cache <string>;¶
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 can share a single cache to save memory and possibly improve cache hit rate and resolution efficiency by using this option.
The
attach-cacheoption may also be specified inviewstatements, in which case it overrides the globalattach-cacheoption.The option's value specifies the cache name to be shared. When named configures
viewstatements which are supposed to share a cache, it creates a cache with the specified name for the first view of these sharing views. The rest of the views will simply refer to the already created cache.One common configuration to share a cache would be to allow all views to share a single cache. This can be done by specifying the
attach-cacheas a global option with an arbitrary name.Another possible operation is to allow a subset of all views to share a cache while the others to retain their own caches. For example, if there are three views A, B, and C, and only A and B should share a cache, specify the
attach-cacheoption as a view A (or B)'s option, referring to the other view name:view "A" { // this view has its own cache ... }; view "B" { // this view refers to A's cache attach-cache "A"; }; view "C" { // this view has its own cache ... };
Views that share a cache must have the same policy on configurable parameters that may affect caching. The current implementation requires the following configurable options be consistent among these views:
check-names,dnssec-validation,max-cache-ttl,max-ncache-ttl,max-cache-size, andzero-no-soa-ttl.Error
TODO: Check if this is enforced in code.
Note
There may be other parameters that may cause confusion if they are inconsistent for different views that share a single cache. For example, if these views define different sets of forwarders that can return different answers for the same question, sharing the answer does not make sense or could even be harmful. It is administrator's responsibility to ensure configuration differences in different views do not cause disruption with a shared cache.
- auth-nxdomain <boolean>; // default changed¶
If enabled, the
AAbit is always set on NXDOMAIN responses, even if the server is not actually authoritative. The default value isno. If you are using very old DNS software, you may need to set it toyes.
- cache-file <quoted_string>; // test only¶
Pathname of the file that named loads the initial contents of the resolver's cache from. It is not configured by default.
Warning
This option is present for testing only. It is only of interest to Loop developers and may be removed or changed in a future release. Please don't use it.
- check-names ( master | slave | response ) ( fail | warn | ignore ); // may occur multiple times¶
This option is used to restrict the character set and syntax of certain domain names in master files and/or DNS responses received from the network. The default varies according to usage area:
For
masterzones the default isfail.For
slavezones the default iswarn.For answers received from the network (
response) the default isignore.
The rules for legal hostnames and mail domains are derived from RFC 952, and RFC 821 as modified by RFC 1123.
check-namesapplies to the owner names of A, AAAA, and MX records. It also applies to the domain names in the RDATA of NS, SOA, MX, and SRV records. It also applies to the RDATA of PTR records where the owner name indicated that it is a reverse lookup of an IP address (the owner name ends in IN-ADDR.ARPA, IP6.ARPA, or IP6.INT).
- clients-per-query <integer>;¶
Sets the initial and minimum number of concurrent recursive clients for any given query (<qname, qtype, qclass>) that named will accept before dropping additional clients. The default value is 10. named will attempt to self-tune the number of concurrent clients using
clients-per-query's value as the minimum andmax-clients-per-query's value as the maximum, and changes will be logged.This value should reflect the number of queries that come in for a given name during the time it takes to resolve that name. If the number of queries exceed this value, named will assume that it is dealing with a non-responsive zone and will drop the following queries. If it gets a response after dropping queries, it will raise the estimate. The estimate will then be lowered in 20 minutes if it has remained unchanged.
If
clients-per-queryis set to 0, then there is no limit on the number of clients per query and no queries will be dropped.
- deny-answer-addresses { <acl:address_match_element>; ... } [ except-from { <except-from:quoted_string>; ... } ];¶
TBD.
- deny-answer-aliases { <name:quoted_string>; ... } [ except-from { <except-from:quoted_string>; ... } ];¶
TBD.
- disable-algorithms <domain:string> { <algorithms:string>; ... }; // may occur multiple times¶
Disable the specified DNSSEC algorithms at and below the specified domain. This option can be specified multiple times. It is not configured by default.
The longest domain-matched
disable-algorithmsclause will be used to determine which algorithms are used. If all supported algorithms are disabled, the zones covered by thedisable-algorithmswill be treated as insecure.
- disable-ds-digests <domain:string> { <digests:string>; ... }; // may occur multiple times¶
Disable the specified DS digest types at and below the specified domain. This option can be specified multiple times. It is not configured by default.
The longest domain-matched
disable-ds-digestsclause will be used to determine which digest types are used. If all supported digest types are disabled, the zones covered by thedisable-ds-digestswill be treated as insecure.
- disable-empty-zone <string>; // may occur multiple times¶
Disable individual empty zones. This option can be specified multiple times. It is not configured by default. See the discussion of empty zones in the Loop User Manual.
- dns64 <netprefix> { ... };¶
dns64 <netprefix> { break-dnssec <boolean>; clients { <address_match_element>; ... }; exclude { <address_match_element>; ... }; mapped { <address_match_element>; ... }; recursive-only <boolean>; suffix <ipv6_address>; }; // may occur multiple times
This directive instructs named to return mapped IPv4 addresses in answers to AAAA queries when there are no AAAA records. It is intended to be used in conjunction with NAT64. Each
dns64option defines one DNS64 prefix. Multiple DNS64 prefixes can be defined. It is not configured by default.Compatible IPv6 prefixes have lengths of 32, 40, 48, 56, 64 and 96 as per RFC 6052.
Additionally a reverse IP6.ARPA zone will be created for the prefix to provide a mapping from the IP6.ARPA names to the corresponding IN-ADDR.ARPA names using synthesized CNAMEs. The
dns64-serveranddns64-contactoptions can be used to specify the SOA MNAME (primary server) and SOA RNAME (responsible person's mailbox) respectively for the zones.Each
dns64option supports the following optional sub-clauses:The
clientsACL determines which clients are affected by this directive. The default value isany.The
mappedACL selects which IPv4 addresses are to be mapped in the corresponding A RRset. The default value isany.Normally, DNS64 won't apply to a domain name that owns one or more AAAA records; these records will simply be returned. The
excludeACL allows specification of a list of IPv6 addresses that will be ignored if they appear in a domain name's AAAA records, and DNS64 will be applied to any A records the domain name owns. The default value is ::ffff:0.0.0.0/96.suffixcan be defined to set the bits trailing the mapped IPv4 address bits. The bits matching the prefix and mapped IPv4 address must all be 0. The default value is::.If
recursive-onlyis set toyesthe DNS64 synthesis will only happen for recursive queries. The default value isno.If
break-dnssecis set toyesthe DNS64 synthesis will happen even if the result, if validated, would cause a DNSSEC validation failure. If this option is set tono, and if DO=1 in the incoming query, and there are RRSIGs on the applicable records, then synthesis will not happen. The default value isno.
- dns64-contact <string>;¶
TBD.
- dns64-server <string>;¶
TBD.
- dnssec-enable <boolean>;¶
Whether DNSSEC-related resource records are to be returned by named. If set to
no, named will not return DNSSEC-related resource records unless specifically queried for. The default value isyes.
- dnssec-must-be-secure <domain:string> <value:boolean>; // may occur multiple times¶
Specify domains which must be or may not be secure (signed and validated). If set to
yes, thennamedwill only accept answers if they are secure at and below the specified domain. Ifno, then normal DNSSEC validation applies allowing for insecure answers to be accepted. The specified domain must be under atrusted-keysormanaged-keysstatement, ordnssec-validation automust be active. This option can be specified multiple times. It is not configured by default.
- dnssec-validation ( yes | no | auto );¶
Whether DNSSEC validation should be enabled.
If set to
no, DNSSEC validation is disabled.If set to
yes, DNSSEC validation is enabled, but a trust anchor should be explicitly configured using atrusted-keysormanaged-keysstatement. If no trust anchors are explicitly configured, then the root will be treated as insecure.If set to
auto, DNSSEC validation is enabled, and ICANN root zone trust anchors that are built into named are used. The built-in trust anchors are current as of the software release date. If they expire, updated trust anchors may be provided using thednssec-keys-fileconfig option.
The default value is
yes.Note
dnssec-enablealso needs to be set toyesfor this option to be effective.Note
Whenever the resolver sends queries to an EDNS-compliant server, it always sets the DO bit indicating it can support DNSSEC responses, even if
dnssec-validationis off.
- dual-stack-servers [ port <port:integer> ] { ( <quoted_string> [ port <integer> ] [ dscp <integer> ] | <ipv4_address> [ port <integer> ] [ dscp <integer> ] | <ipv6_address> [ port <integer> ] [ dscp <integer> ] ); ... };¶
Specifies hostnames or addresses of machines with access to both IPv4 and IPv6 transports. If a hostname is used, the nameserver must be able to resolve the name using only the transport it has. If the machine is dual stacked, then the
dual-stack-serversclause has no effect unless access to a transport has been disabled on the command line (e.g. with the named-4argument).Error
TODO: This has to be explained in more detail.
- edns-udp-size <integer>;¶
Sets the maximum advertised EDNS requestor's UDP payload size in octets (see RFC 6891 section 6.2.3) that is advertised by named when querying remote nameservers. Values should be configured between 512 and 4096 inclusive; values outside this range will be silently adjusted to the nearest value within it. The default value is 4096.
The usual reason for setting this option to a non-default value is to get DNS over UDP answers to pass through broken firewalls that block fragmented packets and/or block UDP DNS packets that are greater than 512 bytes.
When named first queries a remote server, it will advertise a UDP buffer size of 512, as this has the greatest chance of success on the first try:
If the initial response times out, named will try again with plain DNS, and if that is successful, it will be taken as evidence that the server does not support EDNS. After some failures using EDNS and successes using plain DNS, named will default to plain DNS for future communications with that server. Periodically, named will attempt an EDNS query to see if the situation has improved.
If the initial query was successful with the UDP buffer size of 512, then named will advertise progressively larger buffer sizes on successive queries, until responses begin timing out or the maximum (value of this option) is reached.
The default UDP buffer sizes advertised by named are 512, 1232, 1432, and 4096, but never exceeding this option's value. The values 1232 and 1432 are chosen to allow for an IPv4/IPv6 encapsulated UDP message to be sent without fragmentation at the minimum MTU sizes for Ethernet and IPv6 networks.
- empty-contact <string>;¶
Specify what value will appear in the returned SOA record's RNAME field for empty zones. The default value is "
." (the root name). See the discussion of empty zones in the Loop User Manual.
- empty-server <string>;¶
Specify what value will appear in the returned SOA record's MNAME field for empty zones. If none is specified, then the zone's name will be used. See the discussion of empty zones in the Loop User Manual.
- empty-zones-enable <boolean>;¶
Whether empty zones should be enabled. The default is
yes. See the discussion of empty zones in the Loop User Manual.
- fetch-quota-params <frequency:integer> <low:fixedpoint> <high:fixedpoint> <discount:fixedpoint>;¶
Sets the parameters to use for dynamic resizing of the
fetches-per-serverquota in response to detected congestion.The frequency value indicates how frequently to recalculate the moving average of the ratio of timeouts to responses for each server. The default value is 100, meaning we recalculate the average ratio after every 100 queries have either been answered or timed out.
The low value indicates the "low" threshold of timeout ratio. The default value is 0.1.
The high value indicates the "high" threshold of timeout ratio. The default value is 0.3.
The discount value indicates the discount rate for the moving average. A higher discount rate causes recent events to weigh more heavily when calculating the moving average; a lower discount rate causes past events to weigh more heavily, smoothing out short-term blips in the timeout ratio. The default value is 0.7.
The low, high, and discount fields accept values of fixed-point type with precision of 1/100, i.e., at most two places after the decimal point are significant.
Error
TODO: Improve this description; explain fetches-per-server in the features section of the Loop User Manual.
- fetches-per-server <fetches:integer> [ ( drop | fail ) ];¶
The maximum number of concurrent iterative queries that the resolver will allow to be sent to a single upstream nameserver before blocking additional queries. The value of fetches should reflect how many fetches would normally be sent to any one server in the time it would take to resolve them. It should be lower than
recursive-clients. The default value is 0, i.e., there is no limit on the number of fetches per server and no queries will be dropped or answered with SERVFAIL.Optionally, the value may be followed by the keyword
droporfail, indicating whether queries will be dropped with no response, or answered with SERVFAIL, when all of the nameservers authoritative for a zone are found to have exceeded the per-server quota. The default isfail.The
fetches-per-serverquota is dynamically adjusted in response to detected congestion. As resolver queries are sent to an upstream nameserver, and are either answered or timeout, an exponentially weighted moving average is calculated of the ratio of timeouts to responses:If the current average timeout ratio rises above a high threshold, then
fetches-per-serveris reduced for that server.If the current average timeout ratio drops below a low threshold, then
fetches-per-serveris increased.
The
fetch-quota-paramsoption can be used to adjust the parameters for this calculation.
- fetches-per-zone <fetches:integer> [ ( drop | fail ) ];¶
The maximum number of concurrent iterative queries to any one domain that the server will permit before blocking new queries for data in or beneath that zone. This value should reflect how many fetches would normally be sent to any one zone in the time it would take to resolve them. It should be smaller than
recursive-clients. The default value is 0, i.e., there is no limit on the number of fetches per zone and no queries will be dropped or answered with SERVFAIL.When many clients simultaneously query for the same name and type, the clients will all be attached to the same fetch, up to the
max-clients-per-querylimit, and only one iterative query will be sent. However, when clients are simultaneously querying for different names or types, multiple queries will be sent andmax-clients-per-queryis not effective as a limit.Optionally, the value may be followed by the keyword
droporfail, indicating whether queries will be dropped with no response, or answered with SERVFAIL, when queries exceed the fetch quota for a zone. The default isdrop.The current list of active fetches can be dumped by running the rndc
recursingcommand to a file namednamed.recursingin the working directory. The list includes the number of active fetches for each domain and the number of queries that have been passed or dropped as a result of thefetches-per-zonelimit.Note
These counters are not cumulative over time; whenever the number of active fetches for a domain drops to zero, the counter for that domain is deleted, and the next time a fetch is sent to that domain, it is recreated with the counters set to zero.
Error
TODO: Should this option be renamed to
fetches-per-domain?
- ixfr-from-differences ( master | slave | <boolean> );¶
If enabled, whenever the server loads a new version of a master zone from its zone file or receives a new version of a slave zone via zone transfer, it will compare the new version to the previous version and calculate a set of differences. The differences are then logged in the zone's journal file such that the changes can be transmitted to downstream slaves as an IXFR (incremental zone transfer). The default value is
no.By allowing IXFRs to be used for non-dynamic zones, this option saves bandwidth at the expense of increased CPU and memory consumption on the master's nameserver. In particular, if the new version of a zone is completely different from the previous one, the set of differences will be of a size comparable to the combined size of the old and new zone versions, and the nameserver will need to temporarily allocate memory to hold this complete difference set.
ixfr-from-differencesalso acceptsmasterandslaveat theviewandoptionsstatement levels which causesixfr-from-differencesto be enabled for allmasterorslavezones respectively.
- max-cache-size <size_no_default>;¶
The maximum amount of memory in bytes to use for the resolver's cache. When the amount of data in the cache reaches this limit, the resolver will evict cached records prematurely based on an LRU strategy so that the limit is not exceeded. The keyword
unlimitedor the value 0 will place no limit on cache size; records will be purged from the cache only when their TTLs expire. Any positive values less than 2MB will be silently increased to 2MB. When there are multiple views, the limit applies separately to the cache of each view. The default value isunlimited.Error
TODO: Add a keyword for automatic maximum size computation based on the machine's available RAM.
- max-cache-ttl <integer>;¶
Sets the maximum TTL in seconds for which the nameserver will cache positive answers. The default value is 7 days. A value of 0 may cause all queries to return SERVFAIL, because of lost caches of intermediate RRsets (such as NS and glue AAAA/A records) in the resolution process.
Error
TODO: In this case, a value of 0 is not useful and there should be a sane minimum.
- max-clients-per-query <integer>;¶
Sets the maximum number of concurrent recursive clients for any given query (<qname, qtype, qclass>) that named will accept before dropping additional clients. See
clients-per-queryfor more details. The default value is 100. If the value is set to 0, then there is no upper bound other than imposed byrecursive-clients.
- max-ncache-ttl <integer>;¶
To reduce work, reduce network traffic, and increase performance, named also caches negative answers (see RFC 2308). This option sets the maximum TTL in seconds for which the nameserver will cache negative answers. The value cannot exceed 7 days and will be silently truncated to 7 days if set to a greater value. The default value is 3 hours.
- max-recursion-depth <integer>;¶
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 nameserver addresses, which in turn requires resolving hostnames, etc. If the number of indirections exceeds this value, the recursive query is terminated and returns SERVFAIL. The default value is 7.
- max-recursion-queries <integer>;¶
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. Queries to look up top-level domains such as
com.andnet.and the DNS root zone are exempt from this limitation. The default value is 75.
- max-udp-size <integer>;¶
Sets the maximum EDNS UDP response message size that named will send in bytes. Values should be configured between 512 and 4096 inclusive; values outside this range will be silently adjusted to the nearest value within it. The default value is 4096.
The usual reason for setting this option to a non-default value is to get UDP answers to pass through broken firewalls that block fragmented packets and/or block UDP packets that are greater than 512 bytes.
This value applies to responses sent by named. To set the maximum advertised EDNS requestor's UDP payload size in queries, see
edns-udp-size.Note
Setting this to a low value could result in truncated DNS over UDP answers, and cause additional DNS over TCP traffic to the nameserver.
- minimal-responses <boolean>;¶
If enabled, when generating responses the server will only add records to the authority and additional data sections when they are required (delegations, negative responses, etc.). Enabling this option may reduce the amount of processing necessary to respond to queries, and improve the performance of the nameserver. The default value is
no.
- no-case-compress { <address_match_element>; ... };¶
Specifies a list of addresses for which named should perform case-sensitive name compression in response mesages. This ACL can be used when named answers to clients that do not comply with the requirement in RFC 1035 to use case-insensitive name comparisons when checking for matching domain names.
The default value is
none, i.e., case-insensitive compression will be used for all clients.Case-insensitive compression can result in slightly smaller responses: if a response contains RRs with owner names
example.comandexample.COM, case-insensitive compression would treat the second one as a duplicate. It also ensures that the case of all the owner names of returned RRs exactly matches the case of the query name in the question section, rather than matching the case of the records entered in the zone file.Case-insensitive compression is always used in AXFR and IXFR responses, regardless of whether the client matches this ACL.
There are circumstances in which named will not preserve the case of owner names of records. If a zone master file contains records of different types with the same name, but the capitalization of the name is different (e.g., "www.example.com./A" and "WWW.EXAMPLE.COM./AAAA"), then all responses for that name will use the first version of the name that was used in the zone file. However, domain names specified in the RDATA of resource records (i.e., records of type NS, MX, CNAME, etc) will always have their case preserved unless the client matches this ACL.
Error
TODO: Explain this some more, and in the Loop User Manual as well.
- nocookie-udp-size <integer>;¶
Sets the maximum size in bytes of UDP responses that will be sent to queries without a valid COOKIE EDNS option. A value below 128 will be silently increased to 128. The default value is 4096, but the
max-udp-sizeoption may further limit the response size.
- preferred-glue <string>;¶
If specified, the listed type (A or AAAA) will be 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 IPv4, and AAAA when responding to queries that arrived via IPv6.
Error
TODO: Change to an enum type.
- prefetch <trigger:integer> [ <integer> ];¶
When a query is received for cached data which is to expire shortly, named can refresh the data from the authoritative server immediately, ensuring that the cache has an answer available for future queries.
The trigger value specifies the TTL in seconds at which prefetch of the current query will take place. When a cached record with a lower TTL value is encountered during query processing, it will be refreshed. trigger values should be configured between 1 and 10. Values larger than 10 will be silently reduced to 10. Setting trigger to 0 causes the prefetching to be disabled. The default value for trigger is 2.
An optional second argument specifies the eligibility TTL value in seconds. The eligibility TTL is the smallest original TTL value of an RRset that will be accepted for prefetching. The eligibility TTL must be at least 6 seconds higher than the trigger TTL; if it isn't, named will silently increase it to be 6 seconds higher. The default value for the eligibility TTL is 9.
- provide-ixfr <boolean>;¶
Whether named, when acting as master, will respond with IXFRs (incremental zone transfers; see RFC 1995) when a remote nameserver, a slave or client, requests it.
If set to
yes, incremental transfer will be provided whenever possible.If set to
no, all transfers to the remote server or client will be AXFRs (non-incremental full zone transfer; see RFC 5936).
The default value is
yes.
- query-source ( ( [ address ] ( <ipv4_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv4_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];¶
The
query-sourceclause specifies the IPv4 source address to be used for DNS queries sent to remote nameservers.Error
TODO: Expand this description with the text from the "Query address" section.
- query-source-v6 ( ( [ address ] ( <ipv6_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv6_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];¶
The
query-source-v6clause specifies the IPv6 source address to be used for DNS queries sent to remote nameservers.Error
TODO: Expand this description with the text from the "Query address" section.
- rate-limit { ... };¶
rate-limit { all-per-second <integer>; errors-per-second <integer>; exempt-clients { <address_match_element>; ... }; ipv4-prefix-length <integer>; ipv6-prefix-length <integer>; log-only <boolean>; max-table-size <integer>; min-table-size <integer>; nodata-per-second <integer>; nxdomains-per-second <integer>; qps-scale <integer>; referrals-per-second <integer>; responses-per-second <integer>; slip <integer>; window <integer>; };
TBD.
- recursion <boolean>;¶
If enabled and if a DNS query requests recursion (RD=1), then the server will attempt to perform any recursive resolution required to answer the query. If the option is disabled and the server does not already know the answer, it will return a referral response. The default value is
yes.Note
Disabling this option does not prevent clients from getting data from the nameserver's cache. It only prevents new recursive resolutions from being performed for client queries. Recursive resolution and caching may still occur as a side-effect the nameserver's internal operation, such as NOTIFY address lookups.
- request-nsid <boolean>;¶
If enabled, an empty NSID (Name Server Identifier) EDNS option (see RFC 5001) is sent in all queries to name servers during iterative resolution, and also in SOA queries performed during zone refreshes. During resolution, if the name server returns an NSID EDNS option in its response, then its contents are logged in the
resolvercategory at levelinfo. The default value isno.Error
TODO: NSID is sent in NS queries too in the zonemgr. Also, should NSID from SOA refresh's responses be logged too?
- request-cookie <boolean>;¶
If enabled, named adds a COOKIE EDNS option (see RFC 7873) in requests sent to remote nameservers. The default value is
yes.If named determines that the COOKIE EDNS option is not supported by some remote nameservers, it may not add COOKIE EDNS options in requests to them.
If the resolver has previously talked to the server, the cookie returned in the previous transaction is sent to it. This is used by the server to determine whether the resolver has talked to it previously. A resolver sending the correct cookie is usually assumed not to be an off-path attacker sending a spoofed-source query; the query is therefore unlikely to be part of a reflection/amplification attack, so resolvers sending a correct COOKIE EDNS option are usually not subject to response rate limiting (RRL). Resolvers which do not send a correct COOKIE EDNS option may be limited to receiving smaller responses via the
nocookie-udp-sizeoption.Error
TODO: Should cookies be sent by the zonemgr too in the requests it makes?
- resolver-query-timeout <integer>;¶
The amount of time in seconds that the resolver will spend attempting to resolve a recursive query before failing. The default value is 10. Values should be configured between 10 and 30. If set to 0, it will be silently increased to the default value.
- response-policy { zone <quoted_string> [ policy ( cname | disabled | drop | given | no-op | nodata | nxdomain | passthru | tcp-only <cname:quoted_string> ) ] [ recursive-only <boolean> ] [ max-policy-ttl <integer> ]; ... } [ recursive-only <boolean> ] [ break-dnssec <boolean> ] [ max-policy-ttl <integer> ] [ min-ns-dots <integer> ] [ qname-wait-recurse <boolean> ];¶
TBD.
- root-delegation-only [ exclude { <quoted_string>; ... } ];¶
Turn on enforcement of
delegation-onlyin TLDs (top level domains) and root zones with an optional exclude list. It is not configured by default.DS queries are expected to be made to and be answered by delegation-only zones. Such queries and responses are treated as an exception to delegation-only processing and are not converted to NXDOMAIN responses provided a CNAME is not discovered at the query name.
If a delegation-only zone's name server also serves its child zone, it is not always possible to determine whether an answer comes from the delegation-only zone or the child zone. SOA, NS, and DNSKEY records are apex-only records and a matching response that contains these records or DS is treated as coming from a child zone. RRSIG records are also examined to see if they are signed by a child zone or not. The authority section is also examined to see if there is evidence that the answer is from the child zone. Answers that are determined to be from a child zone are not converted to NXDOMAIN responses. Despite all these checks, there is still a possibility of false negatives when a child zone is being served.
Similarly false positives can arise from empty nodes (no records at the name) in the delegation-only zone when the query type is not
ANY.Note
Some TLDs are not delegation-only. E.g. "DE", "LV", "US", "MUSEUM", etc. As an example, they can be configured as:
options { root-delegation-only exclude { "de"; "lv"; "us"; "museum"; }; };
- rrset-order ( none | random );¶
Configures the order of records in RRsets returned in answers:
If the value is
random, the records are re-ordered to be in random order.If the value is
none, no re-ordering is performed.
The default value is
none.
- zero-no-soa-ttl-cache <boolean>;¶
When caching a negative response to a SOA query, set the TTL to 0. The default value is
no.
- allow-notify { <address_match_element>; ... };¶
Configures which hosts are allowed to send DNS NOTIFY (see RFC 1996) messages to this nameserver of zone changes, in addition to the zone's masters. It is only meaningful for a slave zone. The default value is
none.
- allow-query { <address_match_element>; ... };¶
Configures which hosts are allowed to send ordinary DNS queries to this nameserver. The default value is
any.
- allow-query-on { <address_match_element>; ... };¶
Configures which local addresses can receive ordinary DNS queries. This makes it possible, for instance, to receive queries on internal-facing interfaces, but disallow them on external-facing ones, without necessarily knowing the internal network's addresses. The default value is
any.Note
allow-query-onis only checked for queries that are permitted byallow-query. A query must be allowed by both ACLs, or it will be refused.
- allow-transfer { <address_match_element>; ... };¶
Configures which addresses are allowed to transfer zones from this nameserver. The default value is
any.
- allow-update { <address_match_element>; ... };¶
Configures which hosts are allowed to perform DNS UPDATE transactions for master zones. If it is not configured, updates are refused. It is not configured by default.
Warning
Allowing updates based on the requestor's IP address is insecure, as the source IP address may be spoofed in the case UDP. See the Loop User Manual for more details.
- allow-update-forwarding { <address_match_element>; ... };¶
Specifies which hosts are allowed to submit DNS UPDATEs to slave zones to be forwarded to the master. The default value is
none, which means that no update forwarding will be performed. To enable update forwarding, specify a value ofany. Specifying values other thannoneoranyis usually counter-productive, as the responsibility for DNS UPDATE access-control should rest with the master server, not the slave servers.Warning
Allowing update forwarding on a slave server may expose master servers relying on insecure IP address based access-control to attacks. See the Loop User Manual for more details.
- also-notify [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <masters> | <ipv4_address> [ port <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <key:string> ]; ... };¶
Configures a list of IP addresses of nameservers that are also sent DNS 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 to ensure that copies of the zones will quickly converge on stealth nameservers. It is not configured by default.
Optionally, a port may be specified with each
also-notifyaddress to send the notify messages to a port other than the default of 53. An optional TSIG key can also be specified with each address to cause the notify messages to be signed; this can be useful when sending notifies to multiple views. In place of explicit addresses, one or more namedmasterslists can be used.Note
If a zone's
notifyoption is set tono, the IP addresses in thealso-notifylist will not be sent DNS NOTIFY messages for that zone.
- alt-transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];¶
Configures an alternate transfer source IPv4 address, for use if the one listed in
transfer-sourcefails anduse-alt-transfer-sourceis set.Note
If you do not wish the alternate transfer source to be used, you should set
use-alt-transfer-sourceappropriately and you should not depend upon getting an answer back to the first refresh query.
- alt-transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];¶
Configures an alternate transfer source IPv6 address, for use if the one listed in
transfer-source-v6fails anduse-alt-transfer-sourceis set.Note
If you do not wish the alternate transfer source to be used, you should set
use-alt-transfer-sourceappropriately and you should not depend upon getting an answer back to the first refresh query.
- auto-dnssec ( allow | maintain | off );¶
Zones configured for dynamic DNS may use this option to allow varying levels of automatic DNSSEC key management. There are three possible values:
allowpermits keys to be updated and the zone fully re-signed whenever the user issues the rndcsigncommand.maintainincludes the above, but also automatically adjusts the zone's DNSSEC keys on schedule, according to the keys' timing metadata (see dnssec-keygen(1) and dnssec-settime(1)).The rndc
signcommand causes named to load keys from the key repository and sign the zone with all keys that are active.The rndc
loadkeyscommand causes named to load keys from the key repository and schedule key maintenance events to occur in the future, but it does not sign the full zone immediately.Note
Once keys have been loaded for a zone the first time, the repository will be searched for changes periodically, regardless of whether the rndc
loadkeyscommand is used. The recheck interval is defined bydnssec-loadkeys-interval.
The default value is
off.Error
TODO: This description has to be rewritten.
- check-dup-records ( fail | warn | ignore );¶
Check master zones for records that are treated as different by DNSSEC but are semantically equal in plain DNS. The default value is
warn.Error
TODO: This description has to be rewritten.
- check-integrity <boolean>;¶
Whether to perform post-load zone integrity checks on master zones. This 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 records only in-zone hostnames are checked (for out-of-zone hostnames use named-checkzone). For NS records only names below top of zone are checked (for out-of-zone names and glue consistency checks use named-checkzone). The default value is
yes.The use of type SPF records for publishing "Sender Policy Framework" is deprecated as the migration from using type TXT records to type SPF records was abandoned. Enabling this option also checks that a type TXT "Sender Policy Framework" record exists (starts with "v=spf1") if there is an SPF record. Warnings are emitted if the type TXT record does not exist and can be suppressed with
check-spf.
- check-mx ( fail | warn | ignore );¶
Check whether the MX record appears to refer to a IP address. The default value is
warn.
- check-mx-cname ( fail | warn | ignore );¶
If
check-integrityis enabled, then fail, warn, or ignore MX records that refer to CNAMEs. The default valuewarn.
- check-sibling <boolean>;¶
When performing integrity checks, also check that sibling glue exists. The default value is
yes.
- check-spf ( warn | ignore );¶
If
check-integrityis enabled, then check that there is a type TXT "Sender Policy Framework" record present (starts with "v=spf1") if there is a type SPF record present. The default value iswarn.
- check-srv-cname ( fail | warn | ignore );¶
If
check-integrityis enabled, then fail, warn, or ignore SRV records that refer to CNAMEs. The default value iswarn.
- check-wildcard <boolean>;¶
If enabled, check for non-terminal wildcard owner names and issue a warning if they are present. The use of non-terminal wildcard owner names is usually due to a mis-understanding of the wildcard matching algorithm (see RFC 1034). This option affects master zones. The default value is
yes.
- dialup ( notify | notify-passive | passive | refresh | <boolean> );¶
If set to
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. This has different effects according to zone type and concentrates the zone maintenance so that it all happens in a short interval, once everyheartbeat-intervaland hopefully during the one call. It also suppresses some of the normal zone maintenance traffic. The default value isno.If the zone is a master zone, then the server will send out a NOTIFY request to all the slaves (default). This should trigger the zone SOA serial number check in the slave (providing it supports NOTIFY) allowing the slave to verify the zone while the connection is active. The set of servers to which NOTIFY is sent can be controlled by the
notifyandalso-notifyconfig options.If the zone is a slave or stub zone, then the server will suppress the regular "zone up to date" (refresh) queries and only perform them when the
heartbeat-intervalexpires in addition to sending NOTIFY requests.Finer control can be achieved by using the values:
notifywhich only sends NOTIFY messages,notify-passivewhich sends NOTIFY messages and suppresses the normal refresh queries,refreshwhich suppresses normal refresh processing and sends refresh queries when theheartbeat-intervalexpires, andpassivewhich just disables normal refresh processing.
Value
Normal refresh
Heartbeat refresh
Heartbeat notify
no(default)yes
no
no
yesno
yes
yes
notifyyes
no
yes
refreshno
yes
no
passiveno
no
no
notify-passiveno
no
yes
Note
Normal DNS NOTIFY processing is not affected by the
dialupoption.
- dnssec-dnskey-kskonly <boolean>;¶
When this option and the
update-check-kskoption's value are both enabled, only key-signing keys (i.e., keys with the KSK bit set) will be used to sign the DNSKEY RRset at the zone apex. Zone-signing keys (i.e., keys without the KSK bit set) will be used to sign the remainder of the zone, but not the DNSKEY RRset. This is similar to the dnssec-signzone program's-xcommand-line option. The default value isno. Ifupdate-check-ksk's value is set tono, this option is ignored.
- dnssec-loadkeys-interval <integer>;¶
When a zone has
auto-dnssecconfigured to the valuemaintain, 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 (see dnssec-keygen(1) and dnssec-settime(1)). This option sets the frequency of automatic repository checks in minutes. The default value is 60. Values should be configured between 1 and 1440 inclusive; values greater than this range will be silently lowered to the maximum value.
- dnssec-secure-to-insecure <boolean>;¶
Allow a dynamic zone to transition from secure to insecure (i.e., signed to unsigned) by deleting all of the DNSKEY records. The default value is
no. If enabled, and if the DNSKEY RRset at the zone apex is deleted, all RRSIG and NSEC records will be removed from the zone as well.Note
If the zone uses NSEC3, then it is also necessary to delete the NSEC3PARAM RRset from the zone apex; this will cause the removal of all corresponding NSEC3 records. (It is expected that this requirement will be eliminated in a future release.)
Error
TODO: Remove the need for the previous note.
Note
If a zone has
auto-dnssecconfigured tomaintainand the private keys remain accessible in the key repository, then the zone will be automatically signed again the next time named is started.
- dnssec-update-mode ( maintain | no-resign );¶
If this option is configured to
maintainin a zone of typemasterwhich is DNSSEC-signed and configured to allow DNS UPDATEs, and if named has access to the private signing key(s) for the zone, then it will automatically sign all new or changed records and maintain signatures for the zone by regenerating RRSIG records whenever they approach their expiration date.If the option is configured to
no-resign, then named will sign all new or changed records, but scheduled maintenance of signatures is disabled.With either of these values, named will reject updates to a DNSSEC-signed zone when the signing keys are inactive or unavailable to it.
The default value is
maintain.Note
A planned third configuration value,
external, will disable all automatic signing and allow DNSSEC data to be submitted into a zone via dynamic update; this is not yet implemented.Error
TODO: Implement the
externalvalue?
- forward ( first | only );¶
This option is only used by named if the
forwardersoption's value is not empty. A value offirstcauses the resolver to query the forwarders first, and if that doesn't answer the question, the resolver will then attempt to resolve the answer by itself. A value ofonlycauses the resolver to only query the forwarders. The default value isfirst.
- forwarders [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <ipv4_address> | <ipv6_address> ) [ port <integer> ] [ dscp <integer> ]; ... };¶
Specifies a list of IP addresses of upstream nameservers to forward queries to. Forwarding occurs only on those queries for which the server is not authoritative and does not have the answer in its cache. It is not configured by default (no forwarding occurs).
- inline-signing <boolean>;¶
TBD.
- key-directory <quoted_string>;¶
When performing DNS UPDATEs of secure zones, the directory where the public and private DNSSEC key files should be found, if it is different from the current working directory.
Note
This option has no effect on the paths for files containing non-DNSSEC keys such as
rndc.keyandsession.key.
- max-journal-size <size_no_default>;¶
Sets the maximum size for each journal file. When the journal file approaches the specified size, some of the oldest transactions in the journal will be automatically removed. The largest permitted value is 2 gigabytes. The default value is
unlimited, which also means 2 gigabytes. See the Loop User Manual for a description of journal files.
- max-records <integer>;¶
Sets the maximum number of resource records permitted in a zone. The default value is 0 which means unlimited.
- max-refresh-time <integer>;¶
This option controls 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 of 24 weeks. However, these values are set by the master, giving slave server administrators little control over their contents.
This option allows an administrator to configure the maximum refresh time in seconds. It is valid for slave and stub zones, and clamps the SOA refresh time to the specified value. The default value is 2419200 (4 weeks).
- max-retry-time <integer>;¶
This option controls 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 of 24 weeks. However, these values are set by the master, giving slave server administrators little control over their contents.
This option allows an administrator to configure the maximum retry time in seconds. It is valid for slave and stub zones, and clamps the SOA retry time to the specified value. The default value is 1209600 (2 weeks).
- max-transfer-idle-in <integer>;¶
Sets the maximum idle time in minutes for inbound zone transfers, after which transfers making no progress will be terminated. The default value is 60. The maximum value is 40320 (28 days).
- max-transfer-idle-out <integer>;¶
Sets the maximum idle time in minutes for outbound zone transfers, after which transfers making no progress will be terminated. The default value is 60. The maximum value is 40320 (28 days).
- max-transfer-time-in <integer>;¶
Sets the maximum transfer time in minutes for inbound zone transfers, after which transfers running longer will be terminated. The default value is 120. The maximum value is 40320 (28 days).
- max-transfer-time-out <integer>;¶
Sets the maximum transfer time in minutes for outbound zone transfers, after which transfers running longer will be terminated. The default value is 120. The maximum value is 40320 (28 days).
- max-zone-ttl ( unlimited | <ttlval> );¶
Specifies a maximum permissible TTL value in seconds within a zone. When loading a zone file, any record encountered with a TTL higher than the configured value will cause the zone to be rejected.
This is useful in DNSSEC-signed zones because when rolling to a new DNSKEY, the old key needs to remain available until RRSIG records have expired from caches. This config option guarantees that the largest TTL in the zone will be no higher the set value.
The default value is
unlimited. A value of 0 is treated asunlimited.
- min-refresh-time <integer>;¶
This option controls 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 of 24 weeks. However, these values are set by the master, giving slave server administrators little control over their contents.
This option allows an administrator to configure the minimum refresh time in seconds. It is valid for slave and stub zones, and clamps the SOA refresh time to the specified value. The default value is 300.
- min-retry-time <integer>;¶
This option controls 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 of 24 weeks. However, these values are set by the master, giving slave server administrators little control over their contents.
This option allows an administrator to configure the minimum retry time in seconds. It is valid for slave and stub zones, and clamps the SOA retry time to the specified value. The default value is 500.
- multi-master <boolean>;¶
This option is meant to be used when there are multiple masters for a zone and the addresses refer to different machines. If enabled, named will not log when the serial number on the master is less than what named currently has. The default value is
no.
- notify ( explicit | master-only | <boolean> );¶
This option configures generation of DNS NOTIFY messages:
If configured as
yes, DNS NOTIFY messages are sent when a zone that the nameserver is authoritative for changes. These messages are sent to the nameservers listed in the zone's NS records (except the master server identified in the SOA MNAME field), and to any other nameservers configured using thealso-notifyoption.If configured as
master-only, DNS NOTIFY messages are only sent for master zones.If configured as
explicit, notifies are sent only to servers explicitly listed usingalso-notify.If configured as
no, no notifies are sent.
The default value is
yes. See the Loop User Manual for a description of the DNS NOTIFY feature.
- notify-delay <integer>;¶
Configures the delay in seconds between sending sets of DNS NOTIFY messages for a zone. The default value is 5.
The overall rate at which DNS NOTIFY messages are sent for all zones is controlled by the
serial-query-rateoption.
- notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];¶
Determines which local source IPv4 address, and optionally UDP port, are used to send DNS NOTIFY messages over IPv4. This IP address must appear in the slave nameserver's
masterszone clause or in anallow-notifyclause. It is not configured by default.
- notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];¶
Determines which local source IPv6 address, and optionally UDP port, are used to send DNS NOTIFY messages over IPv6. This IP address must appear in the slave nameserver's
masterszone clause or in anallow-notifyclause. It is not configured by default.
- notify-to-soa <boolean>;¶
If enabled, named does not check the nameservers in the NS RRset against the SOA MNAME. Normally a DNS NOTIFY message is not sent to the nameserver in the SOA MNAME field as it is supposed to contain the name of the ultimate master. Sometimes, however, a slave nameserver is listed as the SOA MNAME in hidden master configurations and in that case you may want the ultimate master to still send NOTIFY messages to all the nameservers listed in the NS RRset.
- nsec3-test-zone <boolean>; // test only¶
TBD.
Warning
This option is present for testing only. It is only of interest to Loop developers and may be removed or changed in a future release. Please don't use it.
- request-ixfr <boolean>;¶
Whether the local nameserver, acting as a slave, will request IXFRs (incremental zone transfers; see RFC 1995) from the given remote nameserver, a master. The default value is
yes.IXFR requests to servers that do not support IXFR will automatically fall back to AXFR (non-incremental full zone transfer; see RFC 5936). Therefore, there is no need to explicitly list which servers support IXFR and which ones do not; the default of
yesshould always work. The purpose of theprovide-ixfrandrequest-ixfrclauses is to make it possible to disable the use of IXFR even when both master and slave claim to support it, for example if one of the servers is buggy and crashes or corrupts data when IXFR is used.
- serial-update-method ( increment | unixtime );¶
Zones configured for DNS UPDATEs may use this option to set the method that will be used to update the zone's SOA serial number.
If configured as
increment, the SOA serial number will be incremented by 1 each time the zone is updated.If configured as
unixtime, the SOA serial number will be set to the number of seconds since the UNIX epoch, unless the serial number is already greater than or equal to that value, in which case it is incremented by 1.
The default value is
increment.Error
TODO: What about the YYYYMMDDnn format in RFC 1912?
- sig-signing-nodes <integer>;¶
Specifies the maximum number of nodes to be examined in each quantum when signing a zone with a new DNSKEY. The default value is 100.
- sig-signing-signatures <integer>;¶
Specifies a threshold number of signatures that will terminate processing a quantum when signing a zone with a new DNSKEY. The default value is 10.
- sig-signing-type <integer>;¶
Specifies a RDATA type to be used when generating signing state records. Valid values are between 65280 and 65534 inclusive. The default value is 65534.
Note
It is expected that this parameter may be removed in a future version once there is a standard type.
Error
TODO: The range of values allowed is not enforced to be within the private use space.
Signing state records are internally used by named to track the current state of a zone-signing process, i.e., whether it is still active or has been completed.
The records can be inspected using the rndc
signing -listcommand.Once named has finished signing a zone with a particular key, the signing state record associated with that key can be removed from the zone using the rndc
signing -clearcommand.To clear all of the completed signing state records for a zone, use the rndc
signing -clear allcommand.
- sig-validity-interval <validity:integer> [ <integer> ];¶
Specifies the number of days into the future when DNSSEC signatures automatically generated as a result of DNS UPDATEs will expire, i.e., the signature validity interval.
There is an optional second field which specifies how long before expiry that the signatures will be regenerated. The second field is specified in days if validity is greater than 7 days otherwise it is specified in hours. If not specified, the signatures will be regenerated at 1/4 of validity.
The default value of validity (the signature validity interval) is 30, causing signatures to be re-regenerated every 7 1/2 days. The maximum value allowed for validity is 3660 (~10 years).
The signature inception time is unconditionally set to one hour before the current time to allow for a limited amount of clock skew.
The validity should be, at least, several multiples of the SOA expire interval to allow for reasonable interaction between the various timer and expiry dates.
- transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];¶
Determines which local IPv4 address will be bound to IPv4 TCP connections used to fetch zones transferred inbound by the server. It also determines the source IPv4 address, and optionally the UDP port, used for the SOA refresh queries and forwarded DNS UPDATEs. If not set, it defaults to a system controlled value which will usually be the address of the interface "closest to" the remote end. It is not configured by default.
Note
This address should also be allowed in the remote nameserver's
allow-transferoption for the zone being transferred.
- transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];¶
Determines which local IPv6 address will be bound to IPv6 TCP connections used to fetch zones transferred inbound by the server. It also determines the source IPv6 address, and optionally the UDP port, used for the SOA refresh queries and forwarded DNS UPDATEs. If not set, it defaults to a system controlled value which will usually be the address of the interface "closest to" the remote end. It is not configured by default.
Note
This address should also be allowed in the remote nameserver's
allow-transferoption for the zone being transferred.
- try-tcp-refresh <boolean>;¶
If enabled, named tries to send SOA refresh queries for zones using TCP, if SOA refresh queries over UDP fail. The default value is
yes.
- update-check-ksk <boolean>;¶
If enabled, named checks the KSK bit in each key to determine how the key should be used when generating RRSIGs for a secure zone. The default value is
yes.Ordinarily, zone-signing keys (i.e., keys without the KSK bit set) are used to sign the entire zone, while key-signing keys (i.e., keys with the KSK bit set) are only used to sign the DNSKEY RRset at the zone apex. However, if this option is set to
no, then the KSK bit is ignored; KSKs are treated as if they were ZSKs and are used to sign the entire zone. This is similar to running dnssec-signzone with the-zargument.When this option is set to
yes, there must be at least two active keys for every algorithm represented in the DNSKEY RRset, i.e., at least one KSK and one ZSK per algorithm. If there is any algorithm for which this requirement is not met, this option will be ignored for that algorithm.
- use-alt-transfer-source <boolean>;¶
Whether to use the
alt-transfer-sourceandalt-transfer-source-v6options. If views are specified, the default value isno, otherwise the default value isyes.
- zero-no-soa-ttl <boolean>;¶
If enabled, when returning authoritative negative responses to SOA queries, set the TTL of the SOA record returned in the authority section to 0. The default value is
yes.
- zone-statistics ( full | terse | none | <boolean> );¶
This option configures what statistics data is collected for zones:
If configured as
fulloryes, the nameserver will collect full zone statistics.Error
TODO: This has to be described in more detail.
If configured as
terse, the nameserver will collect minimal statistics on zones (including name and current serial number, but not query type counters).If configured as
noneorno, the nameserver will not collect any statistics for zones.
Zone statistics may be accessed by running the rndc
statscommand, which will dump them to the file listed in thestatistics-file. See the Loop User Manual for a description of the statistics data.The default value is
terse.
5.1.2.10. server statement¶
server <netprefix> {
bogus <boolean>;
edns <boolean>;
edns-udp-size <integer>;
keys <server_key>;
max-udp-size <integer>;
notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
provide-ixfr <boolean>;
query-source ( ( [ address ] ( <ipv4_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv4_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];
query-source-v6 ( ( [ address ] ( <ipv6_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv6_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];
request-ixfr <boolean>;
request-nsid <boolean>;
request-cookie <boolean>;
tcp-only <boolean>;
transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
transfers <integer>;
}; // may occur multiple times
The server statement defines characteristics to be associated with a
remote nameserver address. If a prefix length is specified as part of
the address, then a range of servers is covered. The most specific
server statement with the longest matching address prefix is used,
regardless of the order in which the server statements appear in the
config file.
The server statement can occur at the top-level of the configuration
file or within a view statement. If a view statement contains
one or more server statements, only those apply to the view and any
top-level ones are ignored. If a view contains no server statements,
any top-level server statements are used.
- bogus <boolean>¶
If you discover that a remote server is giving out bad data, marking it as bogus will prevent further queries to it. The default value of
bogusisno.
- edns <boolean>¶
The
ednsclause determines whether the local server will attempt to use EDNS (see RFC 6891) when communicating with the remote server. The default value ofednsisyes.
- edns-udp-size <integer>¶
The
edns-udp-sizeoption sets the advertised EDNS requestor's UDP payload size in octets (see RFC 6891 section 6.2.3) that is advertised by named when querying the remote nameserver. Valid values are between 512 and 4096 inclusive; values outside this range will be silently adjusted to the nearest value within it. This option is useful if you wish to advertise a different value to this server than the value you advertise globally, for example, when there is a firewall at the remote site that is blocking large replies.Note
Currently, this sets a fixed UDP size for all packets sent to the server. named will not deviate from this value. This differs from the behavior of
edns-udp-sizein theoptionsorviewstatements, where it specifies the maximum value for the advertised EDNS requestor's UDP payload size . Theserverstatement behavior may be brought into conformance with theoptionsandviewstatements' behavior in future releases.
- keys <server_key>¶
The
keysclause identifies a key defined by thekeystatement to be used to TSIG-sign DNS messages when talking to the remote nameserver. When a request is sent to the remote nameserver, a TSIG signature will be generated for it using the key specified here and appended to the message. A request originating from the remote nameserver is not required to be signed by this key.Note
Only a single key per server is currently supported.
- max-udp-size <integer>¶
The
max-udp-sizeoption sets the maximum EDNS UDP reply message size in octets that named will send to the remote nameserver. Valid values are between 512 and 4096 inclusive; values outside this range will be silently adjusted. This option is useful when you know that there is a firewall that is blocking large replies from named from getting through to the remote namesever.
- notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ]¶
The
notify-sourceclause specifies the IPv4 source address to be used for NOTIFY messages sent to the remote nameserver.Note
For an IPv6 remote server, this option must not be specified.
- notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ]¶
The
notify-source-v6clause specifies the IPv6 source address to be used for NOTIFY messages sent to the remote nameserver.Note
For an IPv4 remote server, this option must not be specified.
- provide-ixfr <boolean>¶
The
provide-ixfrclause determines whether the local nameserver, when acting as master, will respond with IXFRs (incremental zone transfers; see RFC 1995) when the given remote nameserver, a slave or client, requests it. If set toyes, incremental transfer will be provided whenever possible. If set tono, all transfers to the remote server or client will be AXFRs (non-incremental full zone transfer; see RFC 5936). If not set, the value of theprovide-ixfroption in thevieworoptionsstatement is used as the default.Error
TODO: It may also be set in the
zonestatement and, if set there, it will override theoptionsorviewstatement's setting for that zone?
- query-source ( ( [ address ] ( <ipv4_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv4_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];¶
The
query-sourceclause specifies the IPv4 source address to be used for DNS queries sent to the remote nameserver.Note
For an IPv6 remote server, this option must not be specified.
- query-source-v6 ( ( [ address ] ( <ipv6_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv6_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];¶
The
query-source-v6clause specifies the IPv6 source address to be used for DNS queries sent to the remote nameserver.Note
For an IPv4 remote server, this option must not be specified.
- request-ixfr <boolean>¶
Overrides the
request-ixfrvalue set at thevieworoptionsstatement level. See the documentation for therequest-ixfroption in theoptionsstatement.
- request-nsid <boolean>¶
Overrides the
request-nsidvalue set at thevieworoptionsstatement level. See the documentation for therequest-nsidoption in theoptionsstatement.
- request-cookie <boolean>¶
Overrides the
request-cookievalue set at thevieworoptionsstatement level. See the documentation for therequest-cookieoption in theoptionsstatement.
- tcp-only <boolean>¶
The
tcp-onlyoption forces the transport protocol to TCP. The default is to use the UDP transport and to fallback on TCP only if a truncated response is received.
- transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ]¶
The
transfer-sourceclause specifies the IPv4 source address to be used for zone transfers with the remote nameserver.Note
For an IPv6 remote server, this option must not be specified.
- transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ]¶
The
transfer-source-v6clause specifies the IPv6 source address to be used for zone transfers with the remote nameserver.Note
For an IPv4 remote server, this option must not be specified.
- transfers <integer>¶
The
transfersoption is used to limit the number of concurrent inbound zone transfers from the remote nameserver. If notransfersclause is specified, the limit is set according to thetransfers-per-nsoption.
5.1.2.11. trusted-keys statement¶
trusted-keys { <name:string> <flags:integer> <protocol:integer> <algorithm:integer> <key:quoted_string>; ... }; // may occur multiple times
The trusted-keys statement configures static DNSSEC trust anchors. A
trust anchor may be defined when the DNSKEY for a zone is known, but
cannot be securely obtained through DNS, either because it is the DNS
root zone or because its parent zone is unsigned. Once a key has been
configured as a trusted-key, it is treated as if it had been validated
and proven secure. The resolver attempts DNSSEC validation on all DNS
data in sub-domains of a trust anchor's domain.
All keys (and corresponding zones) listed in trusted-keys are deemed
to exist regardless of what parent zones say. Similarly for all keys
listed in trusted-keys, only those keys are used to validate the
DNSKEY RRset. The parent's DS RRset will not be used.
The trusted-keys statement may contain multiple keys, each
consisting of the key's domain name, flags, protocol, algorithm, and the
Base64 representation of the key data. Spaces, tabs, newlines and
carriage returns are ignored in the key data, so the configuration may
be split up into multiple lines.
trusted-keys may be set at the top level of the config file or
within a view statement. If it is set in both places, they are
additive, i.e., keys defined at the top-level are inherited by all
view statements, but keys defined in a view statement are only
used within that view.
5.1.2.12. view statement¶
view <name:string> [ <class> ] {
match-clients { <address_match_element>; ... };
match-destinations { <address_match_element>; ... };
match-recursive-only <boolean>;
key <string> {
algorithm <string>;
secret <string>;
}; // may occur multiple times
managed-keys { <name:string> <init:string> <flags:integer> <protocol:integer> <algorithm:integer> <key:quoted_string>; ... }; // may occur multiple times
server <netprefix> {
bogus <boolean>;
edns <boolean>;
edns-udp-size <integer>;
keys <server_key>;
max-udp-size <integer>;
notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
provide-ixfr <boolean>;
query-source ( ( [ address ] ( <ipv4_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv4_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];
query-source-v6 ( ( [ address ] ( <ipv6_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv6_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];
request-ixfr <boolean>;
request-nsid <boolean>;
request-cookie <boolean>;
tcp-only <boolean>;
transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
transfers <integer>;
}; // may occur multiple times
trusted-keys { <name:string> <flags:integer> <protocol:integer> <algorithm:integer> <key:quoted_string>; ... }; // may occur multiple times
zone <name:string> [ <class> ] {
type ( delegation-only | forward | hint | master | slave | static-stub | stub );
file <quoted_string>;
journal <quoted_string>;
masters [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <masters> | <ipv4_address> [ port <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <key:string> ]; ... };
update-policy ( local | { ( deny | grant ) <identity:string> ( 6to4-self | external | krb5-self | krb5-subdomain | ms-self | ms-subdomain | name | self | selfsub | selfwild | subdomain | tcp-self | wildcard | zonesub ) [ <name:string> ] <types:rrtypelist>; ... };
database <string>;
delegation-only <boolean>;
check-names ( fail | warn | ignore );
in-view <string>;
ixfr-from-differences <boolean>;
server-addresses { ( <ipv4_address> | <ipv6_address> ) [ port <integer> ]; ... };
server-names { <quoted_string>; ... };
allow-notify { <address_match_element>; ... };
allow-query { <address_match_element>; ... };
allow-query-on { <address_match_element>; ... };
allow-transfer { <address_match_element>; ... };
allow-update { <address_match_element>; ... };
allow-update-forwarding { <address_match_element>; ... };
also-notify [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <masters> | <ipv4_address> [ port <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <key:string> ]; ... };
alt-transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
alt-transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
auto-dnssec ( allow | maintain | off );
check-dup-records ( fail | warn | ignore );
check-integrity <boolean>;
check-mx ( fail | warn | ignore );
check-mx-cname ( fail | warn | ignore );
check-sibling <boolean>;
check-spf ( warn | ignore );
check-srv-cname ( fail | warn | ignore );
check-wildcard <boolean>;
dialup ( notify | notify-passive | passive | refresh | <boolean> );
dnssec-dnskey-kskonly <boolean>;
dnssec-loadkeys-interval <integer>;
dnssec-secure-to-insecure <boolean>;
dnssec-update-mode ( maintain | no-resign );
forward ( first | only );
forwarders [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <ipv4_address> | <ipv6_address> ) [ port <integer> ] [ dscp <integer> ]; ... };
inline-signing <boolean>;
key-directory <quoted_string>;
max-journal-size <size_no_default>;
max-records <integer>;
max-refresh-time <integer>;
max-retry-time <integer>;
max-transfer-idle-in <integer>;
max-transfer-idle-out <integer>;
max-transfer-time-in <integer>;
max-transfer-time-out <integer>;
max-zone-ttl ( unlimited | <ttlval> );
min-refresh-time <integer>;
min-retry-time <integer>;
multi-master <boolean>;
notify ( explicit | master-only | <boolean> );
notify-delay <integer>;
notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
notify-to-soa <boolean>;
nsec3-test-zone <boolean>; // test only
request-ixfr <boolean>;
serial-update-method ( increment | unixtime );
sig-signing-nodes <integer>;
sig-signing-signatures <integer>;
sig-signing-type <integer>;
sig-validity-interval <validity:integer> [ <integer> ];
transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
try-tcp-refresh <boolean>;
update-check-ksk <boolean>;
use-alt-transfer-source <boolean>;
zero-no-soa-ttl <boolean>;
zone-statistics ( full | terse | none | <boolean> );
}; // may occur multiple times
allow-new-zones <boolean>;
allow-query-cache { <address_match_element>; ... };
allow-query-cache-on { <address_match_element>; ... };
allow-recursion { <address_match_element>; ... };
allow-recursion-on { <address_match_element>; ... };
attach-cache <string>;
auth-nxdomain <boolean>; // default changed
cache-file <quoted_string>; // test only
check-names ( master | slave | response ) ( fail | warn | ignore ); // may occur multiple times
clients-per-query <integer>;
deny-answer-addresses { <acl:address_match_element>; ... } [ except-from { <except-from:quoted_string>; ... } ];
deny-answer-aliases { <name:quoted_string>; ... } [ except-from { <except-from:quoted_string>; ... } ];
disable-algorithms <domain:string> { <algorithms:string>; ... }; // may occur multiple times
disable-ds-digests <domain:string> { <digests:string>; ... }; // may occur multiple times
disable-empty-zone <string>; // may occur multiple times
dns64 <netprefix> {
break-dnssec <boolean>;
clients { <address_match_element>; ... };
exclude { <address_match_element>; ... };
mapped { <address_match_element>; ... };
recursive-only <boolean>;
suffix <ipv6_address>;
}; // may occur multiple times
dns64-contact <string>;
dns64-server <string>;
dnssec-enable <boolean>;
dnssec-must-be-secure <domain:string> <value:boolean>; // may occur multiple times
dnssec-validation ( yes | no | auto );
dual-stack-servers [ port <port:integer> ] { ( <quoted_string> [ port <integer> ] [ dscp <integer> ] | <ipv4_address> [ port <integer> ] [ dscp <integer> ] | <ipv6_address> [ port <integer> ] [ dscp <integer> ] ); ... };
edns-udp-size <integer>;
empty-contact <string>;
empty-server <string>;
empty-zones-enable <boolean>;
fetch-quota-params <frequency:integer> <low:fixedpoint> <high:fixedpoint> <discount:fixedpoint>;
fetches-per-server <fetches:integer> [ ( drop | fail ) ];
fetches-per-zone <fetches:integer> [ ( drop | fail ) ];
ixfr-from-differences ( master | slave | <boolean> );
max-cache-size <size_no_default>;
max-cache-ttl <integer>;
max-clients-per-query <integer>;
max-ncache-ttl <integer>;
max-recursion-depth <integer>;
max-recursion-queries <integer>;
max-udp-size <integer>;
minimal-responses <boolean>;
no-case-compress { <address_match_element>; ... };
nocookie-udp-size <integer>;
preferred-glue <string>;
prefetch <trigger:integer> [ <integer> ];
provide-ixfr <boolean>;
query-source ( ( [ address ] ( <ipv4_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv4_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];
query-source-v6 ( ( [ address ] ( <ipv6_address> | * ) [ port ( <integer> | * ) ] ) | ( [ [ address ] ( <ipv6_address> | * ) ] port ( <integer> | * ) ) ) [ dscp <integer> ];
rate-limit {
all-per-second <integer>;
errors-per-second <integer>;
exempt-clients { <address_match_element>; ... };
ipv4-prefix-length <integer>;
ipv6-prefix-length <integer>;
log-only <boolean>;
max-table-size <integer>;
min-table-size <integer>;
nodata-per-second <integer>;
nxdomains-per-second <integer>;
qps-scale <integer>;
referrals-per-second <integer>;
responses-per-second <integer>;
slip <integer>;
window <integer>;
};
recursion <boolean>;
request-nsid <boolean>;
request-cookie <boolean>;
resolver-query-timeout <integer>;
response-policy { zone <quoted_string> [ policy ( cname | disabled | drop | given | no-op | nodata | nxdomain | passthru | tcp-only <cname:quoted_string> ) ] [ recursive-only <boolean> ] [ max-policy-ttl <integer> ]; ... } [ recursive-only <boolean> ] [ break-dnssec <boolean> ] [ max-policy-ttl <integer> ] [ min-ns-dots <integer> ] [ qname-wait-recurse <boolean> ];
root-delegation-only [ exclude { <quoted_string>; ... } ];
rrset-order ( none | random );
zero-no-soa-ttl-cache <boolean>;
allow-notify { <address_match_element>; ... };
allow-query { <address_match_element>; ... };
allow-query-on { <address_match_element>; ... };
allow-transfer { <address_match_element>; ... };
allow-update { <address_match_element>; ... };
allow-update-forwarding { <address_match_element>; ... };
also-notify [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <masters> | <ipv4_address> [ port <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <key:string> ]; ... };
alt-transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
alt-transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
auto-dnssec ( allow | maintain | off );
check-dup-records ( fail | warn | ignore );
check-integrity <boolean>;
check-mx ( fail | warn | ignore );
check-mx-cname ( fail | warn | ignore );
check-sibling <boolean>;
check-spf ( warn | ignore );
check-srv-cname ( fail | warn | ignore );
check-wildcard <boolean>;
dialup ( notify | notify-passive | passive | refresh | <boolean> );
dnssec-dnskey-kskonly <boolean>;
dnssec-loadkeys-interval <integer>;
dnssec-secure-to-insecure <boolean>;
dnssec-update-mode ( maintain | no-resign );
forward ( first | only );
forwarders [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <ipv4_address> | <ipv6_address> ) [ port <integer> ] [ dscp <integer> ]; ... };
inline-signing <boolean>;
key-directory <quoted_string>;
max-journal-size <size_no_default>;
max-records <integer>;
max-refresh-time <integer>;
max-retry-time <integer>;
max-transfer-idle-in <integer>;
max-transfer-idle-out <integer>;
max-transfer-time-in <integer>;
max-transfer-time-out <integer>;
max-zone-ttl ( unlimited | <ttlval> );
min-refresh-time <integer>;
min-retry-time <integer>;
multi-master <boolean>;
notify ( explicit | master-only | <boolean> );
notify-delay <integer>;
notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
notify-to-soa <boolean>;
nsec3-test-zone <boolean>; // test only
request-ixfr <boolean>;
serial-update-method ( increment | unixtime );
sig-signing-nodes <integer>;
sig-signing-signatures <integer>;
sig-signing-type <integer>;
sig-validity-interval <validity:integer> [ <integer> ];
transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
try-tcp-refresh <boolean>;
update-check-ksk <boolean>;
use-alt-transfer-source <boolean>;
zero-no-soa-ttl <boolean>;
zone-statistics ( full | terse | none | <boolean> );
}; // may occur multiple times
The view statement is a powerful feature of Loop that lets a
nameserver answer a DNS query differently depending on who is asking. It
is particularly useful for implementing split-DNS setups without having
to run multiple servers.
Each view statement defines a view of the DNS namespace that will be
seen by a subset of the nameserver's clients. A client matches a view if
its source IP address matches the view's match-clients option value,
and its destination IP address matches the view's match-destinations
option value. In addition to checking IP addresses match-clients and
match-destinations can also take keys which provide a mechanism
to select the view for a query based on the TSIG key with which it was
signed. A view can also be specified as match-recursive-only, which
means that only recursive requests from matching clients will match that
view.
The lexical order of the view statements is significant. A client
query will be resolved in the context of the first view that it
matches in the configuration file.
Zones defined within a view statement will only be accessible to
clients that match the view. By defining a zone of the same name in
multiple views, different zone data can be returned to different
clients, for example, "internal" and "external" clients in a split-DNS
setup.
Many of the options given in the options statement can also be used
within a view statement, and they then apply only when processing
queries with that view. When no view-specific value is given, the value
in the options statement is used as a default. Also, zone
options can have default values specified in the view statement;
values specified at the view statement level take precedence over
those in the options statement.
Views are class specific. If no class is given, class IN is assumed. All non-IN views must contain a hint zone, since only the IN class has compiled-in default hints.
Error
TODO: Is the hint zone necessary when recursion is not enabled?
If there are no explicit view statements in the config file, an
implicit default view with the name _default that matches any client
is automatically created in class IN. Any zone statements specified
at the top-level of the configuration file are considered to be part of
this default view, and the options statement's config values will
apply to the default view.
Note
If any explicit view statements are present, all zone
statements must occur inside view statements.
Error
TODO: Document the view-specific options as a list below.
5.1.2.13. zone statement¶
zone <name:string> [ <class> ] {
type ( delegation-only | forward | hint | master | slave | static-stub | stub );
file <quoted_string>;
journal <quoted_string>;
masters [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <masters> | <ipv4_address> [ port <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <key:string> ]; ... };
update-policy ( local | { ( deny | grant ) <identity:string> ( 6to4-self | external | krb5-self | krb5-subdomain | ms-self | ms-subdomain | name | self | selfsub | selfwild | subdomain | tcp-self | wildcard | zonesub ) [ <name:string> ] <types:rrtypelist>; ... };
database <string>;
delegation-only <boolean>;
check-names ( fail | warn | ignore );
in-view <string>;
ixfr-from-differences <boolean>;
server-addresses { ( <ipv4_address> | <ipv6_address> ) [ port <integer> ]; ... };
server-names { <quoted_string>; ... };
allow-notify { <address_match_element>; ... };
allow-query { <address_match_element>; ... };
allow-query-on { <address_match_element>; ... };
allow-transfer { <address_match_element>; ... };
allow-update { <address_match_element>; ... };
allow-update-forwarding { <address_match_element>; ... };
also-notify [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <masters> | <ipv4_address> [ port <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <key:string> ]; ... };
alt-transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
alt-transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
auto-dnssec ( allow | maintain | off );
check-dup-records ( fail | warn | ignore );
check-integrity <boolean>;
check-mx ( fail | warn | ignore );
check-mx-cname ( fail | warn | ignore );
check-sibling <boolean>;
check-spf ( warn | ignore );
check-srv-cname ( fail | warn | ignore );
check-wildcard <boolean>;
dialup ( notify | notify-passive | passive | refresh | <boolean> );
dnssec-dnskey-kskonly <boolean>;
dnssec-loadkeys-interval <integer>;
dnssec-secure-to-insecure <boolean>;
dnssec-update-mode ( maintain | no-resign );
forward ( first | only );
forwarders [ port <port:integer> ] [ dscp <dscp:integer> ] { ( <ipv4_address> | <ipv6_address> ) [ port <integer> ] [ dscp <integer> ]; ... };
inline-signing <boolean>;
key-directory <quoted_string>;
max-journal-size <size_no_default>;
max-records <integer>;
max-refresh-time <integer>;
max-retry-time <integer>;
max-transfer-idle-in <integer>;
max-transfer-idle-out <integer>;
max-transfer-time-in <integer>;
max-transfer-time-out <integer>;
max-zone-ttl ( unlimited | <ttlval> );
min-refresh-time <integer>;
min-retry-time <integer>;
multi-master <boolean>;
notify ( explicit | master-only | <boolean> );
notify-delay <integer>;
notify-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
notify-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
notify-to-soa <boolean>;
nsec3-test-zone <boolean>; // test only
request-ixfr <boolean>;
serial-update-method ( increment | unixtime );
sig-signing-nodes <integer>;
sig-signing-signatures <integer>;
sig-signing-type <integer>;
sig-validity-interval <validity:integer> [ <integer> ];
transfer-source ( <ipv4_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
transfer-source-v6 ( <ipv6_address> | * ) [ port ( <integer> | * ) ] [ dscp <integer> ];
try-tcp-refresh <boolean>;
update-check-ksk <boolean>;
use-alt-transfer-source <boolean>;
zero-no-soa-ttl <boolean>;
zone-statistics ( full | terse | none | <boolean> );
}; // may occur multiple times
5.1.2.13.1. Zone Types¶
The type keyword is required for the zone configuration unless
it is an in-view configuration. Its acceptable values include:
delegation-only, forward, hint, master, slave,
static-stub, and stub.
|
The server has a master copy of the data for the zone and will be able to provide authoritative answers for it. |
|
A slave zone is a replica of a
master zone. The |
|
A stub zone is similar to a slave zone, except that it replicates only the NS records of a master zone instead of the entire zone. Stub zones are not a standard part of the DNS; they are a feature specific to the Loop implementation. Stub zones can be used to
eliminate the need for glue NS
record in a parent zone at the
expense of maintaining a stub
zone entry and a set of name
server addresses in
Stub zones can also be used as a
way of forcing the resolution of
a given domain to use a
particular set of authoritative
servers. For example, the caching
name servers on a private network
using RFC1918 addressing may be
configured with stub zones for
|
|
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 master server; when recursion is necessary for a query that matches a static-stub zone, the locally configured data (nameserver names and glue addresses) is always used even if different authoritative information is cached. Zone data is configured via the
The zone data is maintained in
the form of NS and (if necessary)
glue A or AAAA RRs internally,
which can be seen by dumping zone
databases by
Since the data is statically configured, no zone maintenance action takes place for a static-stub zone. For example, there is no periodic refresh attempt, and an incoming notify message will be rejected with an rcode of NOTAUTH. Each static-stub zone is configured with internally generated NS and (if necessary) glue A or AAAA RRs |
|
A "forward zone" is a way to
configure forwarding on a
per-domain basis. A |
|
The initial set of root name servers is specified using a "hint zone". When the server starts up, 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 defaults hints. |
|
This 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 will be treated as NXDOMAIN. This does not apply to the zone apex. This should not be applied to leaf zones.
See caveats in varlistentry_title. |
5.1.2.13.2. Class¶
The zone's name may optionally be followed by a class. If a class is not
specified, class IN (for Internet), is assumed. This is correct
for the vast majority of cases.
The hesiod class is named for an information service from MIT's
Project Athena. It is used to share information about various systems
databases, such as users, groups, printers and so on. The keyword HS
is a synonym for hesiod.
Another MIT development is Chaosnet, a LAN protocol created in the
mid-1970s. Zone data for it can be specified with the CHAOS class.
5.1.2.13.3. Zone Options¶
allow-notifySee the description of
allow-notifyin section_title.allow-querySee the description of
allow-queryin section_title.allow-query-onSee the description of
allow-query-onin section_title.allow-transferSee the description of
allow-transferin section_title.allow-updateSee the description of
allow-updatein section_title.update-policySpecifies a "Simple Secure Update" policy. See section_title.
allow-update-forwardingSee the description of
allow-update-forwardingin section_title.also-notifyOnly meaningful if
notifyis active for this zone. The set of machines that will receive aDNS NOTIFYmessage for this zone is made up of all the listed name servers (other than the primary master) for the zone plus any IP addresses specified withalso-notify. A port may be specified with eachalso-notifyaddress to send the notify messages to a port other than the default of 53. A TSIG key may also be specified to cause theNOTIFYto be signed by the given key.also-notifyis not meaningful for stub zones. The default is the empty list.check-namesThis option is used to restrict the character set and syntax of certain domain names in master files and/or DNS responses received from the network. The default varies according to zone type. For
masterzones the default isfail. Forslavezones the default iswarn. It is not implemented forhintzones.check-mxSee the description of
check-mxin section_title.check-spfSee the description of
check-spfin section_title.check-wildcardSee the description of
check-wildcardin section_title.check-integritySee the description of
check-integrityin section_title.check-siblingSee the description of
check-siblingin section_title.zero-no-soa-ttlSee the description of
zero-no-soa-ttlin section_title.update-check-kskSee the description of
update-check-kskin section_title.dnssec-loadkeys-intervalSee the description of
dnssec-loadkeys-intervalin section_title.dnssec-update-modeSee the description of
dnssec-update-modein section_title.dnssec-dnskey-kskonlySee the description of
dnssec-dnskey-kskonlyin section_title.try-tcp-refreshSee the description of
try-tcp-refreshin section_title.databaseSpecify the type of database to be used for storing the zone data. The string following the
databasekeyword is interpreted as a list of whitespace-delimited words. The first word identifies the database type, and any subsequent words are passed as arguments to the database to be interpreted in a way specific to the database type.The default is
"rbt", Loop's native in-memory red-black-tree database. This database does not take arguments.Other values are possible if additional database drivers have been linked into the server. Some sample drivers are included with the distribution but none are linked in by default.
dialupSee the description of
dialupin section_title.delegation-onlyThe flag only applies to forward, hint and stub zones. If set to
yes, then the zone will also be treated as if it is also a delegation-only type zone.See caveats in varlistentry_title.
fileSet the zone's filename. In
masterandhintzones which do not havemastersdefined, zone data is loaded from this file. Inslaveandstubzones which do havemastersdefined, zone data is retrieved from another server and saved in this file. This option is not applicable to other zone types.forwardOnly meaningful if the zone has a forwarders list. The
onlyvalue causes the lookup to fail after trying the forwarders and getting no answer, whilefirstwould allow a normal lookup to be tried.forwardersUsed to override the list of global forwarders. If it is not specified in a zone of type
forward, no forwarding is done for the zone and the global options are not used.journalAllow the default journal's filename to be overridden. The default is the zone's filename with "
.jnl" appended. This is applicable tomasterandslavezones.max-journal-sizeSee the description of
max-journal-sizein section_title.max-recordsSee the description of
max-recordsin section_title.max-transfer-time-inSee the description of
max-transfer-time-inin section_title.max-transfer-idle-inSee the description of
max-transfer-idle-inin section_title.max-transfer-time-outSee the description of
max-transfer-time-outin section_title.max-transfer-idle-outSee the description of
max-transfer-idle-outin section_title.notifySee the description of
notifyin section_title.notify-delaySee the description of
notify-delayin section_title.notify-to-soaSee the description of
notify-to-soain section_title.zone-statisticsSee the description of
zone-statisticsin section_title.server-addressesOnly 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 will internally configure the apex NS RR with associated glue A or AAAA RRs.
For example, if "example.com" is configured as a static-stub zone with 192.0.2.1 and 2001:db8::1234 in a
server-addressesoption, the following RRs will be internally configured.example.com. NS example.com. example.com. A 192.0.2.1 example.com. AAAA 2001:db8::1234
These records are internally used to resolve names under the static-stub zone. For instance, if the server receives a query for "www.example.com" with the RD bit on, the server will initiate recursive resolution and send queries to 192.0.2.1 and/or 2001:db8::1234.
server-namesOnly meaningful for static-stub zones. This is a list of domain names of nameservers that act as authoritative servers of the static-stub zone. These names will be resolved to IP addresses when
namedneeds to send queries to these servers. To make this supplemental resolution successful, these names must not be a subdomain of the origin name of static-stub zone. That is, when "example.net" is the origin of a static-stub zone, "ns.example" and "master.example.com" can be specified in theserver-namesoption, but "ns.example.net" cannot, and will be rejected by the configuration parser.A non empty list for this option will internally configure the apex NS RR with the specified names. For example, if "example.com" is configured as a static-stub zone with "ns1.example.net" and "ns2.example.net" in a
server-namesoption, the following RRs will be internally configured.example.com. NS ns1.example.net. example.com. NS ns2.example.net.
These records are internally used to resolve names under the static-stub zone. For instance, if the server receives a query for "www.example.com" with the RD bit on, the server initiate recursive resolution, resolve "ns1.example.net" and/or "ns2.example.net" to IP addresses, and then send queries to (one or more of) these addresses.
sig-validity-intervalSee the description of
sig-validity-intervalin section_title.sig-signing-nodesSee the description of
sig-signing-nodesin section_title.sig-signing-signaturesSee the description of
sig-signing-signaturesin section_title.sig-signing-typeSee the description of
sig-signing-typein section_title.transfer-sourceSee the description of
transfer-sourcein section_title.transfer-source-v6See the description of
transfer-source-v6in section_title.alt-transfer-sourceSee the description of
alt-transfer-sourcein section_title.alt-transfer-source-v6See the description of
alt-transfer-source-v6in section_title.use-alt-transfer-sourceSee the description of
use-alt-transfer-sourcein section_title.notify-sourceSee the description of
notify-sourcein section_title.notify-source-v6See the description of
notify-source-v6in section_title.min-refresh-time;max-refresh-time;min-retry-time;max-retry-timeSee the description in section_title.
ixfr-from-differencesSee the description of
ixfr-from-differencesin section_title. (Note that theixfr-from-differencesmasterandslavechoices are not available at the zone level.)key-directorySee the description of
key-directoryin section_title.auto-dnssecSee the description of
auto-dnssecin section_title.serial-update-methodSee the description of
serial-update-methodin section_title.inline-signingIf
yes, this enables "bump in the wire" signing of a zone, where a unsigned zone is transferred in or loaded from disk and a signed version of the zone is served, with possibly, a different serial number. This behaviour is disabled by default.multi-masterSee the description of
multi-masterin section_title.max-zone-ttlSee the description of
max-zone-ttlin section_title.dnssec-secure-to-insecureSee the description of
dnssec-secure-to-insecurein section_title.
5.1.4. Files¶
/etc/loop/named.conf
5.1.5. See also¶
ddns-confgen(1), named(8), named-checkconf(1), rndc(1), rndc.conf(5), rndc-confgen(1)
5.1.6. Copyright¶
Copyright (C) 2024 Banu Systems Private Limited. All rights reserved.
Copyright (c) 2004-2018 Internet Systems Consortium, Inc. ("ISC").
5.1.3. Comments syntax¶
The comment syntax allows for comments to appear anywhere that whitespace may appear in a config file. To appeal to all programmers, they can be written in the C, C++, or shell/Perl style:
C-style comments start with the two characters
/*(slash, star) and end with*/(star, slash). Because they are completely delimited within these characters, they can be used to comment only a portion of a line or to span multiple lines. For example:C-style comments cannot be nested. For example, the following syntax is not valid because the entire comment ends with the first
*/: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:Shell-style or Perl-style comments start with the character
#(number/hash sign) 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#character. For example:Note
You cannot use the ";" (semi-colon) character to start a comment such as you would in a zone file. The semicolon indicates the end of a configuration statement.