DNS BIND Operations Statements

This page describes statements controlling operational behavior in BIND 9.3.x. The syntax and a single example statement are provided in more complex cases additional examples are provided. Full list of statements.

avoid-v4[v6]-udp-ports

 avoid-v4-udp-ports { port; ... };
 avoid-v6-udp-ports { port; ... };

Defines a list of port numbers that will not be used by BIND when initiating queries. This list may be used to avoid ports that are blocked by a firewall. This option can be defined in the global options clause only.

check-names

 check-names (master |slave| response) (warn|fail|ignore) ;
 check-names response warn;

The check-names statement will cause any host name of the defined type to be checked for compliance with RFC 952 and RFC 1123 and result in the defined action. Care should be taken when using this statement because many modern RRs e.g. SRV use names which do not meet these standards (they contain an underscore) but are permitted by RFC 2181 which greatly liberalized the rules for names (see labels and names). The type of host name to be checked may be master in which case the host names check only applies to master zones, slave applies only to slave zones and response applies to all host names that arrive in response to a query from this server. The default is not to perform host name checks. check-names may appear in a view or options clause with this syntax and also in a zone clause where it has a different syntax.

coresize

 coresize size_in_bytes;

The maximum size in bytes (may take the case insensitive shortforms k or m) of a core dump. This statement can be used in a global options clause only.

database

 database "database-name params";

Defines information to be supplied to the database included using one of BINDs APIs. The data is enclosed in a quoted string. database-name defines the name of the included database. The params string may be any number of space-separated values and are passed as arguments to the included functions to be interpreted in a way specific to the database type. This statement can be used in a global options clause only.

datasize

 datasize size_in_bytes;

The maximum size in bytes (may take the case insensitive shortforms k or m) of memory used by the server. This is a hard limit and may stop the server from working. The statements max-cache-size and recursive-clients may be used to limit memory. This statement can be used in a global options clause only.

dialup

 dialup dialup_options;

Optimizes behavior to minimize use of connect time on dial-up links. Default is no. This option can be defined in the view, zone and options clauses.

The dialup statement's behavior concentrates activity into the heartbeat-interval and triggers notify and zone refresh operations based on the value of the dialup_option and defined in the table below:

dialup_option	Normal refresh	heartbeat refresh	heartbeat notify	Notes
no	yes	no	no	-
yes	no	yes	yes	-
notify	yes	no	yes	-
refresh	no	yes	no	-
passive	no	no	no	-
notify-passive	no	no	yes	-

dual-stack-servers

 dual-stack-servers [ port pg_num ] { ( "host" [port p_num] | 
              ipv4 [port p_num] | ipv6 [port p_num] ); ... };
 dual-stack-servers {192.168.2.3; "bill.example.net"};

Defines the IP address of one or more dual-stacked (IPv4/IPv6) servers that can be used by this server to resolve a query using a stack it does not support. In the example above if only an AAAA (IPv6) RR is returned then this server, which is assumed to support only IPv4, can use the defined servers to resolve the query since they support both stacks. On dual-stack servers it is only effective if one of the stacks has been disabled on the command line. Using pg_num will act as a global port number for all subsequent server definitions or they can be defined individually with the p_num parameters. The parameter host is a quoted string and is the FQDN of the host which must be resolvable using the default protocol which may be either IPv4 or IPv6. This statement may be used in a view or global options clause.

dump-file

 dump-file path_name;

dump-file is a quoted string defining the absolute path where BIND dumps the database (cache) in response to a rndc dumpdb. If not specified, the default is named_dump.db in the location specified by a directory option. This option may only be specified in a 'global' options statement.

edns-udp-size

 edns-udp-size size_in_bytes ;

edns-udp-size defines the size_in_bytes that the server will advertize for an EDNS UDP buffer. Valid values are 512 to 4096, values outside this range will be silently adjusted. The default value is 4096. This statement may be used in a view or global options clause.

files

 files max_files ;

The maximum number of files the server may have open concurrently. The default is unlimited. This statement may be used in a view or global options clause.

hostname

 hostname ( "host-name" | none );
 hostname "myhost";

The host-name (a quotes string) the server should report via a query of the name hostname.bind with type TXT, class CHAOS. This defaults to the host-name of the machine hosting the name server as found by gethostname(). Using dig this information may be easily discovered. Specifying none disables processing of the queries. This statement may be used in a view or global options clause.

key-directory

key-directory path_name;

key-directory is a quoted string defining the absolute path, for example, "/var/named/keys" where the keys used in the dynamic update of secure zones may be found. Only required if this directory is different from that defined by a directory option. This statement may only be used in a global options clause.

lame-ttl

 lame-ttl seconds;
 lame-ttl 1800;

lame-ttl defines the number of seconds to cache lame delegations or lame servers, that is, servers which should be authoritative (obtained via a referral or delegation from a parent) but do not respond as authoritative. The value 0 disables caching and is NOT recommended, the default is 600 (10 minutes) and the maximum value is 1800 (30 minutes). This statement may be used in a view or global options clause.

listen-on

 listen-on [ port ip_port ] { address_match_list };

listen-on defines the port and IP address(es) on which BIND will listen for incoming queries. The default is port 53 on all server interfaces. Multiple listen-on statements are allowed. This statement may only be used in a global options clause.

listen-on-v6

 listen-on-v6 [ port ip_port ] { address_match_list };

listen-on-v6 turns on BIND to listen for IPv6 queries. If this statement is not present and the server supports IPv6 (only or in dual stack mode) the server will listen for IPv6 on port 53 on all server interfaces. If the OS supports RFC 3493 and RFC 3542 compliant IPv6 sockets and the address_match_list uses the special any name then a single listen is issued to the wildcard address. If the OS does not support this feature a socket is opened for every required address and port. The port default is 53. Multiple listen-on-v6 statements are allowed. This statement may only be used in a global options clause. Do not try to start bind with the -4 argument when you use this statement.

options {
....
    // turns on IPv6 for port 53
    listen-on-v6 {any;};
    // turns off IPv6 
    listen-on-v6 {none;};
    // turns on IPv6 for port 53 for 16 IP range
    listen-on-v6 {2001:db8::/124;};
};

match-mapped-addresses

 match-mapped-addresses yes | no ;
 match-mapped-addresses no;

If yes indicates that an address_match_list containing an IPv4 address will be checked against an IPv4 mapped IPv6 address. This feature can incur significant CPU overheads and should only be used as a workaround where the OS software accepts such connections. This statement may only be used in a global options clause.

max-cache-size

 max-cache-size size_in_bytes;

max-cache-size defines the maximum amount of memory to use for the server's cache, in bytes (case insensitive shortforms of k or m are allowed). When the amount of data in the cache reaches this limit, the server will cause records to expire prematurely so that the limit is not exceeded. In a server with multiple views, the limit applies separately to the cache of each view. The default is unlimited, meaning that records are purged from the cache only when their TTLs expire. This statement may be used in view or a global options clause.

max-cache-ttl

 max-cache-ttl seconds;

max-cache-ttl sets the maximum time (in seconds) for which the server will cache positive answers (negative answers NXDOMAIN is defined by max-ncache-ttl). The default is one week (7 days). This statement may be used in view or a global options clause.

max-ncache-ttl

 max-ncache-ttl seconds;

max-ncache-ttl sets the maximum time (in seconds) for which the server will cache negative (NXDOMAIN) answers (positives are defined by max-cache-ttl). The default max-ncache-ttl is 10800 seconds (3 hours). max-ncache-ttl cannot exceed 7 days and will be silently truncated to 7 days if set to a greater value. This statement may be used in view or a global options clause.

memstatistics-file

 memstatistics-file "file-name";
 memstatistics-file "/var/stats/named/bind.stats";

This statement defines the file-name to which BIND memory usage statistics will be written when it exits. May be an absolute or relative (to directory) path. If the parameter is not present the stats are written to named.memstats in the path defined by directory or its default. This statement may only be used in a global options clause.

pid-file

 pid-file "path_name" ;
 pid-file "/var/named/named.pid";

pid-file is a quoted string and allows you to define where the pid (Process Identifier) used by BIND is written. If not present it is distribution or OS specific typically /var/run/named.pid or /etc/named.pid. It may be defined using an absolute path or relative to the directory parameter. This statement may only be used in a global options clause.

port

 port ip_port ;
 port 1175;

ip_port allows the user to define on which port BIND will provide UDP or TCP services. The default is 53. This option is intended primarily for testing and setting it to a non-standard value will not allow the server to communicate with 'normal' DNS systems. This statement may only be used in a global options clause and must come before any other option which defines ports or IP addresses.

preferred-glue

 preferred-glue A | AAAA;
 preferred-glue AAAA;

Defines the order of preference in which glue records will be listed in the additional section of the response. If not specified they will be listed in the order they appear in the zone file. This statement may be used in view or a global options clause.

querylog

 querylog yes | no ;
 querylog yes;

This statement may override the setting of the logging clause and controls whether query logging should be started when named starts. If querylog is not specified then query logging is controlled by the logging category queries. This statement may only be used in a global options clause.

rate-limit

Introduced with BIND 9.10 (and later 9.9 versions) the rate-limit statement is used to limit identical response queries from the same client IP address based on a number of criteria. When rate-limiting is triggered the normal action is to simply drop the query response (this can be modified - see slip parameter below). While it is typically only used by Authoritative Name servers (masters or slaves) to mitigate the effects of DDoS amplification attacks it can be used by recursive servers (a.k.a full-service resolvers) as a method of load limiting but especially when very short (or 0) TTLs are used on cached RRs serious negative effects can result. The statement may be used in a global options or a view clause.

<ouch> Previous version of this page documented an early experimental version of rate limiting since we considered (still do) it to be a significant DNS feature and wanted to expose readers to the feature as soon as possible. Our policy under these conditions is to download the source code to verify clause and statement formats as well as running a number of tests before releasing web documentation. A number of changes took place when a production version of rate-limit was released. Our documentation was not updated to reflect these changes.</ouch>

rate-limit {
     [ responses-per-second number ; ]
     [ referrals-per-second number ; ]
     [ nodata-per-second number ; ]
     [ nxdomains-per-second number ; ]
     [ errors-per-second number ; ]
     [ all-per-second number ; ]
     [ window number ; ]
     [ log-only yes_or_no ; ]
     [ qps-scale number ; ]
     [ ipv4-prefix-length number ; ]
     [ ipv6-prefix-length number ; ]
     [ slip number ; ]
     [ exempt-clients { address_match_list } ; ]
     [ max-table-size number ; ]
     [ min-table-size number ; ] 
};

BIND's rate-limit feature is limited only to queries received by UDP. Queries received by TCP are not limited but are counted in the statistics maintained by the rate-limit function. Rate-limit statements may be defined in either the options or a view clause. If a rate-limit statement appears in the global options clause and a view clause then the view clause version replaces all the parameters defined in the rate-limit of the options clause. Rate-limiting log messages may be streamed by defining the rate-limit category in the logging clause. When a rate-limit statement is encountered in a view clause it replaces that of the global options clause. The rate-limit statement can take an unhealthy number of optional, semi-colon(;) separated, parameters to provide fine control over the conditions under which rate-limiting is invoked and the form that rate-limiting will take:

Name	Value	Notes
responses-per-second	number	This parameter defines the number of identical responses per second (though actually recognized by the query characteristics) allowed from any given source IP address and liess in the range 0 to 1000. If not defined it defaults to 0 (indicates no limits are applied). Identical responses are defined as having the same query name (QNAME) and query type (QTYPE). The following are also counted as identical responses but each is separately counted and thus triggers its own rate-limit: referrals (defaulted to same count value as responses-per-second but can be separately controlled by referrals-per-second); empty responses (NODATA) (defaulted to same count valuee as responses-per-second but can be separately controlled by nodata-per-second); NXDOMAIN responses (defaulted to same count value as responses-per-second but can be separately controlled by nxdomain-per-second); all other errors (in this case the QNAME/QTYPE criteria is not used) such as SERVFAIL, REFUSED and FORMERR (defaulted to same count value as responses-per-second though these can be separately controlled by errors-per-second.
referrals-per-second	number	Defaults to value of responses-per-second. Typically used by Root/TLD's (or user domains with subdomain delegations) and defines the number of referrals per second allowed before rate-limiting is triggered. While typically used instead of responses-per-second in delegation centric domains (for example, TLDs) it may be used in conjunction with responses-per-second or nxdomains-per-second to cover error conditions in delegation centric or mixed domains. Setting a value of 0 indicates that no limits are applied for this category.
nodata-per-second	number	Defaults to the value of responses-per-second. This parameter may be used to separately control rate-limiting based on the number of NODATA responses. Setting a value of 0 indicates that no limits are applied for this category.
nxdomains-per-second	number	Defaults to the value of responses-per-second. This parameter may be used to separately control rate-limiting based on the number of NXDOMAIN (name does not exist) responses. Setting a value of 0 indicates that no limits are applied for this category.
errors-per-second	number	Defaults to the value of responses-per-second. The error count is incremented for each error irrespective of whether the QNAME/QTYPE are identical (the criteria used for all other counts). This parameter may be used to separately control rate-limiting based on the number of error (FORMERR, REFUSED, SERVFAIL) responses. Setting a value of 0 indicates that no limits are applied for this category.
all-per-second	number	The all-per-second parameter simply counts all the responses sent to a particular client IP - the normal identical query criteria is not applied. When the count exceeds number rate-limiting is triggered. The slip parameter is not effective when this parameter is non-zero. Caution should be exercised when using this parameter since certain actions - notably email - can trigger short bursts of hectic, but legitimate, DNS activity - in particular the value of the window parameter should be carefully considered as well as the value of number. Set to 0 by default (no rate-limiting is triggered for this criteria).
window	seconds	The rate-limiting function maintains a rolling window (in seconds) defined by this parameter. The window adds a longer-term dimension to rate limiting. Assume we define a responses-per-second value of 5 and window value of 5 then a single client is rate limited to 5 identical responses in any second and no more that 25 ( 5 x 5) such responses within any 5 second window period. May take a value in the range 1 to 3600 seconds. Default is 15 seconds.
log-only	yes \| no	Default is no. If set to yes then the rate limiting function will not be performed will log (to rate-limit category of the logging clause) when the rate-limit function would have been invoked. It is a diagnostic aid to determine both the effectivess of a particular rate limiting policy and to check for accidental collateral damage.
qps-scale	number	Range allowed is 1 to very big number (actually 32 bit unsigned value, which is still a very big number). Default is not to apply qps-scaling. The rate limiting function calculates the approximate query per second load on the DNS from all sources (including TCP queries). The qps-scale, if defined, is then applied which may result in a reduction of the user supplied limits, such as responses-per-second during high-load situations. Thus, assume the user defined responses-per-second 10; and a qps-scale 200; then if the DNS server is receiving queries (from all sources, including TCP) at a rate of 500 per second the following algorithm is applied (qps-scale/DNS query arrival rate) * responses-per-second = effective rate-limit, substituting actual values gives (200/500) * 10 = 4, meaning that in the defined load conditions the 5th and subsequent identical response in any 1 second to any specific client will be dropped (or trigger any defined slip parameter action). The qps-scale value, if used, should thus be set to the maximum desired DNS transaction (query response) rate for the server.
ipv4-prefix-length	number	Range 1 to 32, default is 24. Rate-limiting is performed per client IP address where the client IP address is modified by the IP Prefix to create an IP address block. The default is 24 (256 IP addresses). Thus, if the incoming IP address is 192.168.2.45 then this is added to the count for the address block covering 192.168.2.0 to 192.168.2.255. If individual IP addresses are required for the purposes of rate-limiting then ipv4-prefix-length 32; should be used.
ipv6-prefix-length	number	Range 1 to 128, default is 56. Rate-limiting is performed per client IP address where the client IP address is modified by the IP Prefix to create an IP address block. The default is 56 (lots of IPv6 addresses). Thus, if the incoming IP address is 2001:db8::fe then this is added to the count for the address block covering 2001:db8:: to 2001:db8::FF:FFFF:FFFF:FFFF. If individual IP addresses are required for the purposes of rate-limiting then ipv6-prefix-length 128; should be used.
slip	number	By default the rate-limit function simply drops the response. The slip parameter allows the DNS to set the Truncate (TC) bit in the response which has the effect of forcing the requestor to use TCP. The default is 0 which means that all identical responses are dropped. A value in the range 1 to 10 (maximum allowed) indicates that every n'th message has the TC bit set, thus 1 means that every message has the TC bit set and 7 means every 7th message has the TC bit set. Forcing use of TCP will slow up the requestor slightly (though a zombie used in a DDoS attack may not even retry) but will increase the load on the DNS (TCP uses more round trip messages).
exempt-clients	address-match-list	Defines an address match list structure of all clients to whom the rate-limiting function does not apply, for example, known or trusted sources whose address cannot be forged due to architectural/network design. Defaults to exempt-clients {none;};.
max-table-size	number	Rate-limit information is defined in tables (each entry of which lies in the range 40 to 80 bytes). A maximum size of 20K entries is defaulted for all rate-limiting tables covered by this rate-limit statement. The range allowed is min-table-size (default is 500) to a very big number (32 bit unsigned).
min-table-size	number	Rate-limit information is defined in tables (each entry of which lies in the range 40 to 80 bytes). A minimum size of 500 entries is defaulted at start-up (the table is allowed to grow to max-table-size) for all rate-limiting tables covered by this rate-limit statement. The range allowed is 1 to max-table-size.

When using server statistics, dropped responses are included in the RateDropped and QryDropped counts, Truncated responses (TC bit set) are included in RateSlipped and RespTruncated counts.

Examples

Tight but reasonable limits for all domains serviced by this DNS for all but brain-dead DNS clients.

# named.conf fragment
options{
 ...
 rate-limit {
  responses-per-second 5;
  window 5;
 }
 ...
};

Precise limits placed on all types of responses.

# named.conf fragment
options{
 ...
 rate-limit {
  responses-per-second 5; // covers non-empty identical queries
  referrals-per-second 2;
  nxdomains-per-second 3;
  nodata-per-second 5;
  errors-per-second 2;
  all-per-second 20;  // covers all queries from client
 }
 ...
};

recursing-file

 recursing-file "file-name";
 recursing-file "bind.recurse";

This statement defines the file-name to which data will be written when the command rndc recursing is issued. May be an absolute or relative (to directory) path. If the parameter is not present the information is written to named.recursing in the path defined by directory or its default. This statement may only be used in a global options clause.

server-id

 server-id ( "id-string" | none );
 server-id none;

The ID the server will return via a query for ID.SERVER with type TXT, under class CH (CHAOS). Specifying none disables processing of the queries otherwise it will return id-string. The default is none. This statement may only be used in a global options clause.

stacksize

 stacksize size_in_bytes;
 stacksize 10k;

The maximum size in bytes (may take the case insensitive shortforms k or m) of the stack memory used by the server. This is a hard limit and may stop the server from working. The default is none. This statement may only be used in a global options clause.

statistics-file

 statistics-file "file-name";
 statistics-file "bind.stats";

This statement defines the file-name to which data will be written when the command rndc stats is issued. May be an absolute or relative (to directory) path. If the parameter is not present the information is written to named.stats in the path defined by directory or its default. This statement may only be used in a global options clause.

tcp-clients

 tcp-clients number ;
 tcp-clients 20;

By default DNS uses UDP port 53 for queries but is defined to allow both TCP and UDP. The tcp-clients allows the user to define the maximum number of TCP connections to be supported. The BIND 9 default is 100. This statement may only be used in a global options clause.

tcp-listen-queue

 tcp-listen-queue number;
 tcp-listen-queue 7;

Controls how many TCP listen operations are queued for incoming zone transfers. The default and minimum is 3. Depending on OS features this also controls how many TCP connections that will be queued in kernel space waiting for some data before being passed to accept. Values less than 3 will be silently raised. This statement may only be used in a global options clause.

version

 version "version_string" ;
 version "Get Lost Pal";

version specifies the string that will be returned to a version.bind query when using the chaos class only. version_string is a quoted string, for example, "get lost" or something equally to the point. We tend to use it in all named.conf files to avoid giving out a version number such that an attacker can exploit known version-specific weaknesses. This statement may only be used in a global options clause.

zone-statistics

 zone-statistics yes | no ;
 zone-statistics no;

This statement defines whether zone statistics will be maintained. The default is no. The zone statistics may be accessed using rndc stats. This statement may be used in view, zone or a global options clause.

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.