mail us  |  mail this page

products  |  company  |  support  |  training  |  contact us

ZYTRAX OPEN LOGO

Blucat Banner

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.

  1. avoid-v4[v6]-udp-ports
  2. check-names
  3. coresize
  4. database
  5. datasize
  6. avoid-v4[v6]-udp-ports
  7. dialup
  8. directory
  9. dual-stack-servers
  10. dump-file
  11. edns-udp-size
  12. files
  13. hostname
  14. key-directory
  15. lame-ttl
  16. listen-on
  17. listen-on-v6
  18. match-mapped-addresses
  19. max-cache-size
  20. max-cache-ttl
  21. max-ncache-ttl
  22. memstatistics-file
  23. pid-file
  24. port
  25. preferred-glue
  26. querylog
  27. rate-limit
  28. recursing-file
  29. server-id
  30. stacksize
  31. statistics-file
  32. tcp-clients
  33. tcp-listen-queue
  34. version
  35. zone-statistics

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 -

directory

 directory "path_name";

directory is a quoted string defining the absolute path for the server e.g. "/var/named". All subsequent relative paths use this base directory. If no directory options is specified the directory from which BIND was loaded is used. This option may only be specified in a 'global' options statement.

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 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 TTLs are used on cached RRs serious negative effects can result. The statement may be used in a global options or a view clause.

rate-limit {
     [ domain domain-name ; ]
     [ responses-per-second [size number] [ratio fixedpoint] 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. Multiple rate-limit statements may be defined in either the options or a view clause. Rate-limiting log messages may be streamed by defining the rate-limit category in the logging clause. When an equivalent rate-limit statement is encountered (with the same domain domain-name parameter) in a view statement it replaces that of the 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
domain domain-name Defines the scope of this rate-limit statement. If omitted it defaults to "." (root) in which case this statement applies to the whole DNS name space. Multiple rate-limit statements may be defined to provide finer control, thus the authoritative server for the domain example.com could use the following configuration:
// named.conf for authoritative server example.com
...
options {
 ...
 rate-limit {
 // no domain defined - applies to noise queries
 // not for this domain (which is covered by
 // the second rate-limit statement)
  responses-per-second 1; 
  ...
 };
 rate-limit (
 // provides a higher limit for potentially valid
 // queries for this domain
  domain example.com;
  responses-per-second 10; 
  ...
 };
};
...
responses-per-second [size bytes] [ratio n.nn] number Up to 5 responses-per-second parameters may be defined in a single rate-limit statement. This parameter defines the number of identical responses per second (though actually recognized by the query characteristics) allowed from any given source IP address. If not defined it defaults to 0 (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. Further granularity for responses-per-second can be defined using the optional size bytes in which case the responses-per-second parameter only applies to messages greater than or equal to bytes, the ratio n.nn applies when the ratio of query size (QNAME) to Answer name (ANAME) exceeds the defined n.nn where n.nn lies in the range 99.99 to 0.01, thus if we define ratio 15.70 then if the QNAME field is 30 bytes and answer name is 300 bytes (ratio = 10.00) this parameter will not be triggered, whereas if the query is 30 bytes and the answer is 700 bytes (ratio=23.33) it will.
// named.conf for authoritative server example.com
...
options {
 ...
 rate-limit (
  ...
  responses-per-second 0; // responses in range 1 to 511 bytes - no limits
  responses-per-second size 512 7; // 512 to 1023
  responses-per-second size 1024 ratio 10.00 5; // 1024 to 1499 only if 
                                                // amplification > 10:1
  responses-per-second size 1500 2; // > 1500
  ...
 };
};
...
referrals-per-second number Defaults to value of responses-per-second. Typically used by 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. 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 message 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;
 }
 ...
};

Different limits for each domain name serviced by this authoritative server for reasons best known to the operator.

# named.conf fragment
options {
 ...
 rate-limit {
  domain example.com;
  responses-per-second 5;
  window 5;
 }
 rate-limit {
  domain example.net;
  responses-per-second 10;
 }
 ...
}

Limit placed only on message size greater that 512 bytes.

# named.conf fragment
options{
 ...
 rate-limit {
  responses-per-second 0;
  responses-per-second size 512 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.

Pro DNS and BIND by Ron Aitchison

Contents

tech info
guides home
dns articles
intro
contents
1 objectives
big picture
2 concepts
3 reverse map
4 dns types
quickstart
5 install bind
6 samples
reference
7 named.conf
8 dns records
operations
9 howtos
10 tools
11 trouble
programming
12 bind api's
security
13 dns security
bits & bytes
15 messages
resources
notes & tips
registration FAQ
dns resources
dns rfc's
change log

Creative Commons License
This work is licensed under a Creative Commons License.

If you are happy it's OK - but your browser is giving a less than optimal experience on our site. You could, at no charge, upgrade to a W3C STANDARDS COMPLIANT browser such as Firefox

web zytrax.com

Share Page

share page via facebook tweet this page submit page to stumbleupon submit page to reddit.com

Page Features

Page comment feature Send to a friend feature print this page Decrease font size Increase font size

RSS Feed Icon RSS Feed

Resources

Systems

FreeBSD
NetBSD
OpenBSD
DragonFlyBSD
Linux.org
Debian Linux

Applications

LibreOffice
OpenOffice
Mozilla
SourceForge
GNU-Free SW Foundation

Organisations

Open Source Initiative
Creative Commons

Misc.

Ibiblio - Library
Open Book Project
Open Directory
Wikipedia

SPF Resources

Draft RFC
SPF Web Site
SPF Testing
SPF Testing (member only)

Display full width page Full width page

Print this page Print this page

SPF Record Conformant Domain Logo

Copyright © 1994 - 2014 ZyTrax, Inc.
All rights reserved. Legal and Privacy
site by zytrax
Hosted by super.net.sg
web-master at zytrax
Page modified: May 13 2014.