1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2.. 3.. SPDX-License-Identifier: MPL-2.0 4.. 5.. This Source Code Form is subject to the terms of the Mozilla Public 6.. License, v. 2.0. If a copy of the MPL was not distributed with this 7.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8.. 9.. See the COPYRIGHT file distributed with this work for additional 10.. information regarding copyright ownership. 11 12.. Reference: 13 14BIND 9 Configuration Reference 15============================== 16 17.. _configuration_file_elements: 18 19Configuration File Elements 20--------------------------- 21 22Following is a list of elements used throughout the BIND configuration 23file documentation: 24 25.. glossary:: 26 27 ``acl_name`` 28 The name of an ``address_match_list`` as defined by the ``acl`` statement. 29 30 ``address_match_list`` 31 A list of one or more ``ip_addr``, ``ip_prefix``, ``key_id``, or ``acl_name`` elements; see :ref:`address_match_lists`. 32 33 ``remoteserver_list`` 34 A named list of one or more ``ip_addr`` with optional ``key_id`` and/or ``ip_port``. A ``remoteserver_list`` may include other ``remoteserver_list``. 35 36 ``domain_name`` 37 A quoted string which is used as a DNS name; for example. ``my.test.domain``. 38 39 ``namelist`` 40 A list of one or more ``domain_name`` elements. 41 42 ``dotted_decimal`` 43 One to four integers valued 0 through 255 separated by dots (``.``), such as ``123.45.67`` or ``89.123.45.67``. 44 45 ``ip4_addr`` 46 An IPv4 address with exactly four elements in ``dotted_decimal`` notation. 47 48 ``ip6_addr`` 49 An IPv6 address, such as ``2001:db8::1234``. IPv6-scoped addresses that have ambiguity on their scope zones must be disambiguated by an appropriate zone ID with the percent character (``%``) as a delimiter. It is strongly recommended to use string zone names rather than numeric identifiers, to be robust against system configuration changes. However, since there is no standard mapping for such names and identifier values, only interface names as link identifiers are supported, assuming one-to-one mapping between interfaces and links. For example, a link-local address ``fe80::1`` on the link attached to the interface ``ne0`` can be specified as ``fe80::1%ne0``. Note that on most systems link-local addresses always have ambiguity and need to be disambiguated. 50 51 ``ip_addr`` 52 An ``ip4_addr`` or ``ip6_addr``. 53 54 ``ip_dscp`` 55 A ``number`` between 0 and 63, used to select a differentiated services code point (DSCP) value for use with outgoing traffic on operating systems that support DSCP. 56 57 ``ip_port`` 58 An IP port ``number``. The ``number`` is limited to 0 through 65535, with values below 1024 typically restricted to use by processes running as root. In some cases, an asterisk (``*``) character can be used as a placeholder to select a random high-numbered port. 59 60 ``ip_prefix`` 61 An IP network specified as an ``ip_addr``, followed by a slash (``/``) and then the number of bits in the netmask. Trailing zeros in an``ip_addr`` may be omitted. For example, ``127/8`` is the network ``127.0.0.0``with netmask ``255.0.0.0`` and ``1.2.3.0/28`` is network ``1.2.3.0`` with netmask ``255.255.255.240``. 62 When specifying a prefix involving a IPv6-scoped address, the scope may be omitted. In that case, the prefix matches packets from any scope. 63 64 ``key_id`` 65 A ``domain_name`` representing the name of a shared key, to be used for transaction security. 66 67 ``key_list`` 68 A list of one or more ``key_id``, separated by semicolons and ending with a semicolon. 69 70 ``number`` 71 A non-negative 32-bit integer (i.e., a number between 0 and 4294967295, inclusive). Its acceptable value might be further limited by the context in which it is used. 72 73 ``fixedpoint`` 74 A non-negative real number that can be specified to the nearest one-hundredth. Up to five digits can be specified before a decimal point, and up to two digits after, so the maximum value is 99999.99. Acceptable values might be further limited by the contexts in which they are used. 75 76 ``path_name`` 77 A quoted string which is used as a pathname, such as ``zones/master/my.test.domain``. 78 79 ``port_list`` 80 A list of an ``ip_port`` or a port range. A port range is specified in the form of ``range`` followed by two ``ip_port``s, ``port_low`` and ``port_high``, which represents port numbers from ``port_low`` through ``port_high``, inclusive. ``port_low`` must not be larger than ``port_high``. For example, ``range 1024 65535`` represents ports from 1024 through 65535. In either case an asterisk (``*``) character is not allowed as a valid ``ip_port``. 81 82 ``size_spec`` 83 A 64-bit unsigned integer, or the keywords ``unlimited`` or ``default``. Integers may take values 0 <= value <= 18446744073709551615, though certain parameters (such as ``max-journal-size``) may use a more limited range within these extremes. In most cases, setting a value to 0 does not literally mean zero; it means "undefined" or "as big as possible," depending on the context. See the explanations of particular parameters that use ``size_spec`` for details on how they interpret its use. Numeric values can optionally be followed by a scaling factor: ``K`` or ``k`` for kilobytes, ``M`` or ``m`` for megabytes, and ``G`` or ``g`` for gigabytes, which scale by 1024, 1024*1024, and 1024*1024*1024 respectively. 84 ``unlimited`` generally means "as big as possible," and is usually the best way to safely set a very large number. 85 ``default`` uses the limit that was in force when the server was started. 86 87 ``size_or_percent`` 88 A ``size_spec`` or integer value followed by ``%`` to represent percent. The behavior is exactly the same as ``size_spec``, but ``size_or_percent`` also allows specifying a positive integer value followed by the ``%`` sign to represent percent. 89 90 ``yes_or_no`` 91 Either ``yes`` or ``no``. The words ``true`` and ``false`` are also accepted, as are the numbers ``1`` and ``0``. 92 93 ``dialup_option`` 94 One of ``yes``, ``no``, ``notify``, ``notify-passive``, ``refresh``, or ``passive``. When used in a zone, ``notify-passive``, ``refresh``, and ``passive`` are restricted to secondary and stub zones. 95 96.. _address_match_lists: 97 98Address Match Lists 99~~~~~~~~~~~~~~~~~~~ 100 101Syntax 102^^^^^^ 103 104:: 105 106 address_match_list = address_match_list_element ; ... 107 108 address_match_list_element = [ ! ] ( ip_address | ip_prefix | 109 key key_id | acl_name | { address_match_list } ) 110 111Definition and Usage 112^^^^^^^^^^^^^^^^^^^^ 113 114Address match lists are primarily used to determine access control for 115various server operations. They are also used in the ``listen-on`` and 116``sortlist`` statements. The elements which constitute an address match 117list can be any of the following: 118 119- an IP address (IPv4 or IPv6) 120 121- an IP prefix (in ``/`` notation) 122 123- a key ID, as defined by the ``key`` statement 124 125- the name of an address match list defined with the ``acl`` statement 126 127- a nested address match list enclosed in braces 128 129Elements can be negated with a leading exclamation mark (``!``), and the 130match list names "any", "none", "localhost", and "localnets" are 131predefined. More information on those names can be found in the 132description of the ``acl`` statement. 133 134The addition of the key clause made the name of this syntactic element 135something of a misnomer, since security keys can be used to validate 136access without regard to a host or network address. Nonetheless, the 137term "address match list" is still used throughout the documentation. 138 139When a given IP address or prefix is compared to an address match list, 140the comparison takes place in approximately O(1) time. However, key 141comparisons require that the list of keys be traversed until a matching 142key is found, and therefore may be somewhat slower. 143 144The interpretation of a match depends on whether the list is being used 145for access control, defining ``listen-on`` ports, or in a ``sortlist``, 146and whether the element was negated. 147 148When used as an access control list, a non-negated match allows access 149and a negated match denies access. If there is no match, access is 150denied. The clauses ``allow-notify``, ``allow-recursion``, 151``allow-recursion-on``, ``allow-query``, ``allow-query-on``, 152``allow-query-cache``, ``allow-query-cache-on``, ``allow-transfer``, 153``allow-update``, ``allow-update-forwarding``, ``blackhole``, and 154``keep-response-order`` all use address match lists. Similarly, the 155``listen-on`` option causes the server to refuse queries on any of 156the machine's addresses which do not match the list. 157 158Order of insertion is significant. If more than one element in an ACL is 159found to match a given IP address or prefix, preference is given to 160the one that came *first* in the ACL definition. Because of this 161first-match behavior, an element that defines a subset of another 162element in the list should come before the broader element, regardless 163of whether either is negated. For example, in ``1.2.3/24; ! 1.2.3.13;`` 164the 1.2.3.13 element is completely useless because the algorithm 165matches any lookup for 1.2.3.13 to the 1.2.3/24 element. Using 166``! 1.2.3.13; 1.2.3/24`` fixes that problem by blocking 1.2.3.13 167via the negation, but all other 1.2.3.\* hosts pass through. 168 169.. _comment_syntax: 170 171Comment Syntax 172~~~~~~~~~~~~~~ 173 174The BIND 9 comment syntax allows comments to appear anywhere that 175whitespace may appear in a BIND configuration file. To appeal to 176programmers of all kinds, they can be written in the C, C++, or 177shell/perl style. 178 179Syntax 180^^^^^^ 181 182:: 183 184 /* This is a BIND comment as in C */ 185 186:: 187 188 // This is a BIND comment as in C++ 189 190:: 191 192 # This is a BIND comment as in common Unix shells 193 # and perl 194 195Definition and Usage 196^^^^^^^^^^^^^^^^^^^^ 197 198Comments may appear anywhere that whitespace may appear in a BIND 199configuration file. 200 201C-style comments start with the two characters /\* (slash, star) and end 202with \*/ (star, slash). Because they are completely delimited with these 203characters, they can be used to comment only a portion of a line or to 204span multiple lines. 205 206C-style comments cannot be nested. For example, the following is not 207valid because the entire comment ends with the first \*/: 208 209:: 210 211 /* This is the start of a comment. 212 This is still part of the comment. 213 /* This is an incorrect attempt at nesting a comment. */ 214 This is no longer in any comment. */ 215 216C++-style comments start with the two characters // (slash, slash) and 217continue to the end of the physical line. They cannot be continued 218across multiple physical lines; to have one logical comment span 219multiple lines, each line must use the // pair. For example: 220 221:: 222 223 // This is the start of a comment. The next line 224 // is a new comment, even though it is logically 225 // part of the previous comment. 226 227Shell-style (or perl-style) comments start with the 228character ``#`` (number sign) and continue to the end of the physical 229line, as in C++ comments. For example: 230 231:: 232 233 # This is the start of a comment. The next line 234 # is a new comment, even though it is logically 235 # part of the previous comment. 236 237.. 238 239.. warning:: 240 241 The semicolon (``;``) character cannot start a comment, unlike 242 in a zone file. The semicolon indicates the end of a 243 configuration statement. 244 245.. _Configuration_File_Grammar: 246 247Configuration File Grammar 248-------------------------- 249 250A BIND 9 configuration consists of statements and comments. Statements 251end with a semicolon; statements and comments are the only elements that 252can appear without enclosing braces. Many statements contain a block of 253sub-statements, which are also terminated with a semicolon. 254 255The following statements are supported: 256 257 ``acl`` 258 Defines a named IP address matching list, for access control and other uses. 259 260 ``controls`` 261 Declares control channels to be used by the ``rndc`` utility. 262 263 ``dnssec-policy`` 264 Describes a DNSSEC key and signing policy for zones. See :ref:`dnssec-policy Grammar <dnssec_policy_grammar>` for details. 265 266 ``include`` 267 Includes a file. 268 269 ``key`` 270 Specifies key information for use in authentication and authorization using TSIG. 271 272 ``logging`` 273 Specifies what information the server logs and where the log messages are sent. 274 275 ``masters`` 276 Synonym for ``primaries``. 277 278 ``options`` 279 Controls global server configuration options and sets defaults for other statements. 280 281 ``parental-agents`` 282 Defines a named list of servers for inclusion in primary and secondary zones' ``parental-agents`` lists. 283 284 ``primaries`` 285 Defines a named list of servers for inclusion in stub and secondary zones' ``primaries`` or ``also-notify`` lists. (Note: this is a synonym for the original keyword ``masters``, which can still be used, but is no longer the preferred terminology.) 286 287 ``server`` 288 Sets certain configuration options on a per-server basis. 289 290 ``statistics-channels`` 291 Declares communication channels to get access to ``named`` statistics. 292 293 ``trust-anchors`` 294 Defines DNSSEC trust anchors: if used with the ``initial-key`` or ``initial-ds`` keyword, trust anchors are kept up-to-date using :rfc:`5011` trust anchor maintenance; if used with ``static-key`` or ``static-ds``, keys are permanent. 295 296 ``managed-keys`` 297 Is identical to ``trust-anchors``; this option is deprecated in favor of ``trust-anchors`` with the ``initial-key`` keyword, and may be removed in a future release. 298 299 ``trusted-keys`` 300 Defines permanent trusted DNSSEC keys; this option is deprecated in favor of ``trust-anchors`` with the ``static-key`` keyword, and may be removed in a future release. 301 302 ``view`` 303 Defines a view. 304 305 ``zone`` 306 Defines a zone. 307 308The ``logging`` and ``options`` statements may only occur once per 309configuration. 310 311.. _acl_grammar: 312 313``acl`` Statement Grammar 314~~~~~~~~~~~~~~~~~~~~~~~~~ 315 316.. include:: ../misc/acl.grammar.rst 317 318.. _acl: 319 320``acl`` Statement Definition and Usage 321~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 322 323The ``acl`` statement assigns a symbolic name to an address match list. 324It gets its name from one of the primary uses of address match lists: Access 325Control Lists (ACLs). 326 327The following ACLs are built-in: 328 329 ``any`` 330 Matches all hosts. 331 332 ``none`` 333 Matches no hosts. 334 335 ``localhost`` 336 Matches the IPv4 and IPv6 addresses of all network interfaces on the system. When addresses are added or removed, the ``localhost`` ACL element is updated to reflect the changes. 337 338 ``localnets`` 339 Matches any host on an IPv4 or IPv6 network for which the system has an interface. When addresses are added or removed, the ``localnets`` ACL element is updated to reflect the changes. Some systems do not provide a way to determine the prefix lengths of local IPv6 addresses; in such cases, ``localnets`` only matches the local IPv6 addresses, just like ``localhost``. 340 341.. _controls_grammar: 342 343``controls`` Statement Grammar 344~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 345 346.. include:: ../misc/controls.grammar.rst 347 348.. _controls_statement_definition_and_usage: 349 350``controls`` Statement Definition and Usage 351~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 352 353The ``controls`` statement declares control channels to be used by 354system administrators to manage the operation of the name server. These 355control channels are used by the ``rndc`` utility to send commands to 356and retrieve non-DNS results from a name server. 357 358An ``inet`` control channel is a TCP socket listening at the specified 359``ip_port`` on the specified ``ip_addr``, which can be an IPv4 or IPv6 360address. An ``ip_addr`` of ``*`` (asterisk) is interpreted as the IPv4 361wildcard address; connections are accepted on any of the system's 362IPv4 addresses. To listen on the IPv6 wildcard address, use an 363``ip_addr`` of ``::``. If ``rndc`` is only used on the local host, 364using the loopback address (``127.0.0.1`` or ``::1``) is recommended for 365maximum security. 366 367If no port is specified, port 953 is used. The asterisk ``*`` cannot 368be used for ``ip_port``. 369 370The ability to issue commands over the control channel is restricted by 371the ``allow`` and ``keys`` clauses. Connections to the control channel 372are permitted based on the ``address_match_list``. This is for simple IP 373address-based filtering only; any ``key_id`` elements of the 374``address_match_list`` are ignored. 375 376A ``unix`` control channel is a Unix domain socket listening at the 377specified path in the file system. Access to the socket is specified by 378the ``perm``, ``owner``, and ``group`` clauses. Note that on some platforms 379(SunOS and Solaris), the permissions (``perm``) are applied to the parent 380directory as the permissions on the socket itself are ignored. 381 382The primary authorization mechanism of the command channel is the 383``key_list``, which contains a list of ``key_id``s. Each ``key_id`` in 384the ``key_list`` is authorized to execute commands over the control 385channel. See :ref:`admin_tools` for information about 386configuring keys in ``rndc``. 387 388If the ``read-only`` clause is enabled, the control channel is limited 389to the following set of read-only commands: ``nta -dump``, ``null``, 390``status``, ``showzone``, ``testgen``, and ``zonestatus``. By default, 391``read-only`` is not enabled and the control channel allows read-write 392access. 393 394If no ``controls`` statement is present, ``named`` sets up a default 395control channel listening on the loopback address 127.0.0.1 and its IPv6 396counterpart, ::1. In this case, and also when the ``controls`` statement 397is present but does not have a ``keys`` clause, ``named`` attempts 398to load the command channel key from the file ``rndc.key`` in ``/etc`` 399(or whatever ``sysconfdir`` was specified when BIND was built). To 400create an ``rndc.key`` file, run ``rndc-confgen -a``. 401 402To disable the command channel, use an empty ``controls`` statement: 403``controls { };``. 404 405.. _include_grammar: 406 407``include`` Statement Grammar 408~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 409 410:: 411 412 include filename; 413 414.. _include_statement: 415 416``include`` Statement Definition and Usage 417~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 418 419The ``include`` statement inserts the specified file at the point where the 420``include`` statement is encountered. The ``include`` statement facilitates 421the administration of configuration files by permitting the reading or 422writing of some things but not others. For example, the statement could 423include private keys that are readable only by the name server. 424 425.. _key_grammar: 426 427``key`` Statement Grammar 428~~~~~~~~~~~~~~~~~~~~~~~~~ 429 430.. include:: ../misc/key.grammar.rst 431 432.. _key_statement: 433 434``key`` Statement Definition and Usage 435~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 436 437The ``key`` statement defines a shared secret key for use with TSIG (see 438:ref:`tsig`) or the command channel (see :ref:`controls_statement_definition_and_usage`). 439 440The ``key`` statement can occur at the top level of the configuration 441file or inside a ``view`` statement. Keys defined in top-level ``key`` 442statements can be used in all views. Keys intended for use in a 443``controls`` statement (see :ref:`controls_statement_definition_and_usage`) 444must be defined at the top level. 445 446The ``key_id``, also known as the key name, is a domain name that uniquely 447identifies the key. It can be used in a ``server`` statement to cause 448requests sent to that server to be signed with this key, or in address 449match lists to verify that incoming requests have been signed with a key 450matching this name, algorithm, and secret. 451 452The ``algorithm_id`` is a string that specifies a security/authentication 453algorithm. The ``named`` server supports ``hmac-md5``, ``hmac-sha1``, 454``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, and ``hmac-sha512`` 455TSIG authentication. Truncated hashes are supported by appending the 456minimum number of required bits preceded by a dash, e.g., 457``hmac-sha1-80``. The ``secret_string`` is the secret to be used by the 458algorithm, and is treated as a Base64-encoded string. 459 460.. _logging_grammar: 461 462``logging`` Statement Grammar 463~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 464 465.. include:: ../misc/logging.grammar.rst 466 467.. _logging_statement: 468 469``logging`` Statement Definition and Usage 470~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 471 472The ``logging`` statement configures a wide variety of logging options 473for the name server. Its ``channel`` phrase associates output methods, 474format options, and severity levels with a name that can then be used 475with the ``category`` phrase to select how various classes of messages 476are logged. 477 478Only one ``logging`` statement is used to define as many channels and 479categories as desired. If there is no ``logging`` statement, the 480logging configuration is: 481 482:: 483 484 logging { 485 category default { default_syslog; default_debug; }; 486 category unmatched { null; }; 487 }; 488 489If ``named`` is started with the ``-L`` option, it logs to the specified 490file at startup, instead of using syslog. In this case the logging 491configuration is: 492 493:: 494 495 logging { 496 category default { default_logfile; default_debug; }; 497 category unmatched { null; }; 498 }; 499 500The logging configuration is only established when the entire 501configuration file has been parsed. When the server starts up, all 502logging messages regarding syntax errors in the configuration file go to 503the default channels, or to standard error if the ``-g`` option was 504specified. 505 506.. _channel: 507 508The ``channel`` Phrase 509^^^^^^^^^^^^^^^^^^^^^^ 510 511All log output goes to one or more ``channels``; there is no limit to 512the number of channels that can be created. 513 514Every channel definition must include a destination clause that says 515whether messages selected for the channel go to a file, go to a particular 516syslog facility, go to the standard error stream, or are discarded. The definition can 517optionally also limit the message severity level that is accepted 518by the channel (the default is ``info``), and whether to include a 519``named``-generated time stamp, the category name, and/or the severity level 520(the default is not to include any). 521 522The ``null`` destination clause causes all messages sent to the channel 523to be discarded; in that case, other options for the channel are 524meaningless. 525 526The ``file`` destination clause directs the channel to a disk file. It 527can include additional arguments to specify how large the file is 528allowed to become before it is rolled to a backup file (``size``), how 529many backup versions of the file are saved each time this happens 530(``versions``), and the format to use for naming backup versions 531(``suffix``). 532 533The ``size`` option is used to limit log file growth. If the file ever 534exceeds the specified size, then ``named`` stops writing to the file 535unless it has a ``versions`` option associated with it. If backup 536versions are kept, the files are rolled as described below. If there is 537no ``versions`` option, no more data is written to the log until 538some out-of-band mechanism removes or truncates the log to less than the 539maximum size. The default behavior is not to limit the size of the file. 540 541File rolling only occurs when the file exceeds the size specified with 542the ``size`` option. No backup versions are kept by default; any 543existing log file is simply appended. The ``versions`` option specifies 544how many backup versions of the file should be kept. If set to 545``unlimited``, there is no limit. 546 547The ``suffix`` option can be set to either ``increment`` or 548``timestamp``. If set to ``timestamp``, then when a log file is rolled, 549it is saved with the current timestamp as a file suffix. If set to 550``increment``, then backup files are saved with incrementing numbers as 551suffixes; older files are renamed when rolling. For example, if 552``versions`` is set to 3 and ``suffix`` to ``increment``, then when 553``filename.log`` reaches the size specified by ``size``, 554``filename.log.1`` is renamed to ``filename.log.2``, ``filename.log.0`` 555is renamed to ``filename.log.1``, and ``filename.log`` is renamed to 556``filename.log.0``, whereupon a new ``filename.log`` is opened. 557 558Here is an example using the ``size``, ``versions``, and ``suffix`` options: 559 560:: 561 562 channel an_example_channel { 563 file "example.log" versions 3 size 20m suffix increment; 564 print-time yes; 565 print-category yes; 566 }; 567 568The ``syslog`` destination clause directs the channel to the system log. 569Its argument is a syslog facility as described in the ``syslog`` man 570page. Known facilities are ``kern``, ``user``, ``mail``, ``daemon``, 571``auth``, ``syslog``, ``lpr``, ``news``, ``uucp``, ``cron``, 572``authpriv``, ``ftp``, ``local0``, ``local1``, ``local2``, ``local3``, 573``local4``, ``local5``, ``local6``, and ``local7``; however, not all 574facilities are supported on all operating systems. How ``syslog`` 575handles messages sent to this facility is described in the 576``syslog.conf`` man page. On a system which uses a very old 577version of ``syslog``, which only uses two arguments to the ``openlog()`` 578function, this clause is silently ignored. 579 580On Windows machines, syslog messages are directed to the EventViewer. 581 582The ``severity`` clause works like ``syslog``'s "priorities," except 583that they can also be used when writing straight to a file rather 584than using ``syslog``. Messages which are not at least of the severity 585level given are not selected for the channel; messages of higher 586severity levels are accepted. 587 588When using ``syslog``, the ``syslog.conf`` priorities 589also determine what eventually passes through. For example, defining a 590channel facility and severity as ``daemon`` and ``debug``, but only 591logging ``daemon.warning`` via ``syslog.conf``, causes messages of 592severity ``info`` and ``notice`` to be dropped. If the situation were 593reversed, with ``named`` writing messages of only ``warning`` or higher, 594then ``syslogd`` would print all messages it received from the channel. 595 596The ``stderr`` destination clause directs the channel to the server's 597standard error stream. This is intended for use when the server is 598running as a foreground process, as when debugging a 599configuration, for example. 600 601The server can supply extensive debugging information when it is in 602debugging mode. If the server's global debug level is greater than zero, 603debugging mode is active. The global debug level is set either 604by starting the ``named`` server with the ``-d`` flag followed by a 605positive integer, or by running ``rndc trace``. The global debug level 606can be set to zero, and debugging mode turned off, by running ``rndc 607notrace``. All debugging messages in the server have a debug level; 608higher debug levels give more detailed output. Channels that specify a 609specific debug severity, for example: 610 611:: 612 613 channel specific_debug_level { 614 file "foo"; 615 severity debug 3; 616 }; 617 618get debugging output of level 3 or less any time the server is in 619debugging mode, regardless of the global debugging level. Channels with 620``dynamic`` severity use the server's global debug level to determine 621what messages to print. 622 623``print-time`` can be set to ``yes``, ``no``, or a time format 624specifier, which may be one of ``local``, ``iso8601``, or 625``iso8601-utc``. If set to ``no``, the date and time are not 626logged. If set to ``yes`` or ``local``, the date and time are logged in 627a human-readable format, using the local time zone. If set to 628``iso8601``, the local time is logged in ISO 8601 format. If set to 629``iso8601-utc``, the date and time are logged in ISO 8601 format, 630with time zone set to UTC. The default is ``no``. 631 632``print-time`` may be specified for a ``syslog`` channel, but it is 633usually pointless since ``syslog`` also logs the date and time. 634 635If ``print-category`` is requested, then the category of the message 636is logged as well. Finally, if ``print-severity`` is on, then the 637severity level of the message is logged. The ``print-`` options may 638be used in any combination, and are always printed in the following 639order: time, category, severity. Here is an example where all three 640``print-`` options are on: 641 642``28-Feb-2000 15:05:32.863 general: notice: running`` 643 644If ``buffered`` has been turned on, the output to files is not 645flushed after each log entry. By default all log messages are flushed. 646 647There are four predefined channels that are used for ``named``'s default 648logging, as follows. If ``named`` is started with the ``-L`` option, then a fifth 649channel, ``default_logfile``, is added. How they are used is described in 650:ref:`the_category_phrase`. 651 652:: 653 654 channel default_syslog { 655 // send to syslog's daemon facility 656 syslog daemon; 657 // only send priority info and higher 658 severity info; 659 }; 660 661 channel default_debug { 662 // write to named.run in the working directory 663 // Note: stderr is used instead of "named.run" if 664 // the server is started with the '-g' option. 665 file "named.run"; 666 // log at the server's current debug level 667 severity dynamic; 668 }; 669 670 channel default_stderr { 671 // writes to stderr 672 stderr; 673 // only send priority info and higher 674 severity info; 675 }; 676 677 channel null { 678 // toss anything sent to this channel 679 null; 680 }; 681 682 channel default_logfile { 683 // this channel is only present if named is 684 // started with the -L option, whose argument 685 // provides the file name 686 file "..."; 687 // log at the server's current debug level 688 severity dynamic; 689 }; 690 691The ``default_debug`` channel has the special property that it only 692produces output when the server's debug level is non-zero. It normally 693writes to a file called ``named.run`` in the server's working directory. 694 695For security reasons, when the ``-u`` command-line option is used, the 696``named.run`` file is created only after ``named`` has changed to the 697new UID, and any debug output generated while ``named`` is starting - 698and still running as root - is discarded. To capture this 699output, run the server with the ``-L`` option to specify a 700default logfile, or the ``-g`` option to log to standard error which can 701be redirected to a file. 702 703Once a channel is defined, it cannot be redefined. The 704built-in channels cannot be altered directly, but the default logging 705can be modified by pointing categories at defined channels. 706 707.. _the_category_phrase: 708 709The ``category`` Phrase 710^^^^^^^^^^^^^^^^^^^^^^^ 711 712There are many categories, so desired logs can be sent anywhere 713while unwanted logs are ignored. If 714a list of channels is not specified for a category, log messages in that 715category are sent to the ``default`` category instead. If no 716default category is specified, the following "default default" is used: 717 718:: 719 720 category default { default_syslog; default_debug; }; 721 722If ``named`` is started with the ``-L`` option, the default category 723is: 724 725:: 726 727 category default { default_logfile; default_debug; }; 728 729As an example, let's say a user wants to log security events to a file, but 730also wants to keep the default logging behavior. They would specify the 731following: 732 733:: 734 735 channel my_security_channel { 736 file "my_security_file"; 737 severity info; 738 }; 739 category security { 740 my_security_channel; 741 default_syslog; 742 default_debug; 743 }; 744 745To discard all messages in a category, specify the ``null`` channel: 746 747:: 748 749 category xfer-out { null; }; 750 category notify { null; }; 751 752The following are the available categories and brief descriptions of the 753types of log information they contain. More categories may be added in 754future BIND releases. 755 756.. include:: logging-categories.rst 757 758.. _query_errors: 759 760The ``query-errors`` Category 761^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 762 763The ``query-errors`` category is used to indicate why and how specific queries 764resulted in responses which indicate an error. Normally, these messages are 765logged at ``debug`` logging levels; note, however, that if query logging is 766active, some are logged at ``info``. The logging levels are described below: 767 768At ``debug`` level 1 or higher - or at ``info`` when query logging is 769active - each response with the rcode of SERVFAIL is logged as follows: 770 771``client 127.0.0.1#61502: query failed (SERVFAIL) for www.example.com/IN/AAAA at query.c:3880`` 772 773This means an error resulting in SERVFAIL was detected at line 3880 of source 774file ``query.c``. Log messages of this level are particularly helpful in identifying 775the cause of SERVFAIL for an authoritative server. 776 777At ``debug`` level 2 or higher, detailed context information about recursive 778resolutions that resulted in SERVFAIL is logged. The log message looks 779like this: 780 781:: 782 783 fetch completed at resolver.c:2970 for www.example.com/A 784 in 10.000183: timed out/success [domain:example.com, 785 referral:2,restart:7,qrysent:8,timeout:5,lame:0,quota:0,neterr:0, 786 badresp:1,adberr:0,findfail:0,valfail:0] 787 788The first part before the colon shows that a recursive resolution for 789AAAA records of www.example.com completed in 10.000183 seconds, and the 790final result that led to the SERVFAIL was determined at line 2970 of 791source file ``resolver.c``. 792 793The next part shows the detected final result and the latest result of 794DNSSEC validation. The latter is always "success" when no validation attempt 795was made. In this example, this query probably resulted in SERVFAIL because all 796name servers are down or unreachable, leading to a timeout in 10 seconds. 797DNSSEC validation was probably not attempted. 798 799The last part, enclosed in square brackets, shows statistics collected for this 800particular resolution attempt. The ``domain`` field shows the deepest zone that 801the resolver reached; it is the zone where the error was finally detected. The 802meaning of the other fields is summarized in the following list. 803 804``referral`` 805 The number of referrals the resolver received throughout the resolution process. In the above ``example.com`` there are two. 806 807``restart`` 808 The number of cycles that the resolver tried remote servers at the ``domain`` zone. In each cycle, the resolver sends one query (possibly resending it, depending on the response) to each known name server of the ``domain`` zone. 809 810``qrysent`` 811 The number of queries the resolver sent at the ``domain`` zone. 812 813``timeout`` 814 The number of timeouts the resolver received since the last response. 815 816``lame`` 817 The number of lame servers the resolver detected at the ``domain`` zone. A server is detected to be lame either by an invalid response or as a result of lookup in BIND 9's address database (ADB), where lame servers are cached. 818 819``quota`` 820 The number of times the resolver was unable to send a query because it had exceeded the permissible fetch quota for a server. 821 822``neterr`` 823 The number of erroneous results that the resolver encountered in sending queries at the ``domain`` zone. One common case is when the remote server is unreachable and the resolver receives an "ICMP unreachable" error message. 824 825``badresp`` 826 The number of unexpected responses (other than ``lame``) to queries sent by the resolver at the ``domain`` zone. 827 828``adberr`` 829 Failures in finding remote server addresses of the``domain`` zone in the ADB. One common case of this is that the remote server's name does not have any address records. 830 831``findfail`` 832 Failures to resolve remote server addresses. This is a total number of failures throughout the resolution process. 833 834``valfail`` 835 Failures of DNSSEC validation. Validation failures are counted throughout the resolution process (not limited to the ``domain`` zone), but should only happen in ``domain``. 836 837At ``debug`` level 3 or higher, the same messages as those at 838``debug`` level 1 are logged for errors other than 839SERVFAIL. Note that negative responses such as NXDOMAIN are not errors, and are 840not logged at this debug level. 841 842At ``debug`` level 4 or higher, the detailed context information logged at 843``debug`` level 2 is logged for errors other than SERVFAIL and for negative 844responses such as NXDOMAIN. 845 846.. _parental_agents_grammar: 847 848``parental-agents`` Statement Grammar 849~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 850 851.. include:: ../misc/parental-agents.grammar.rst 852 853.. _parental_agents_statement: 854 855``parental-agents`` Statement Definition and Usage 856~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 857 858``parental-agents`` lists allow for a common set of parental agents to be easily 859used by multiple primary and secondary zones in their ``parental-agents`` lists. 860A parental agent is the entity that the zone has a relationship with to 861change its delegation information (defined in :rfc:`7344`). 862 863.. _primaries_grammar: 864 865``primaries`` Statement Grammar 866~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 867 868.. include:: ../misc/primaries.grammar.rst 869 870.. _primaries_statement: 871 872``primaries`` Statement Definition and Usage 873~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 874 875``primaries`` lists allow for a common set of primary servers to be easily 876used by multiple stub and secondary zones in their ``primaries`` or 877``also-notify`` lists. (Note: ``primaries`` is a synonym for the original 878keyword ``masters``, which can still be used, but is no longer the 879preferred terminology.) 880 881.. _options_grammar: 882 883``options`` Statement Grammar 884~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 885 886This is the grammar of the ``options`` statement in the ``named.conf`` 887file: 888 889.. include:: ../misc/options.grammar.rst 890 891.. _options: 892 893``options`` Statement Definition and Usage 894~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 895 896The ``options`` statement sets up global options to be used by BIND. 897This statement may appear only once in a configuration file. If there is 898no ``options`` statement, an options block with each option set to its 899default is used. 900 901.. _attach-cache: 902 903``attach-cache`` 904 This option allows multiple views to share a single cache database. Each view has 905 its own cache database by default, but if multiple views have the 906 same operational policy for name resolution and caching, those views 907 can share a single cache to save memory, and possibly improve 908 resolution efficiency, by using this option. 909 910 The ``attach-cache`` option may also be specified in ``view`` 911 statements, in which case it overrides the global ``attach-cache`` 912 option. 913 914 The ``cache_name`` specifies the cache to be shared. When the ``named`` 915 server configures views which are supposed to share a cache, it 916 creates a cache with the specified name for the first view of these 917 sharing views. The rest of the views simply refer to the 918 already-created cache. 919 920 One common configuration to share a cache is to allow all views 921 to share a single cache. This can be done by specifying 922 ``attach-cache`` as a global option with an arbitrary name. 923 924 Another possible operation is to allow a subset of all views to share 925 a cache while the others retain their own caches. For example, if 926 there are three views A, B, and C, and only A and B should share a 927 cache, specify the ``attach-cache`` option as a view of A (or B)'s 928 option, referring to the other view name: 929 930 :: 931 932 view "A" { 933 // this view has its own cache 934 ... 935 }; 936 view "B" { 937 // this view refers to A's cache 938 attach-cache "A"; 939 }; 940 view "C" { 941 // this view has its own cache 942 ... 943 }; 944 945 Views that share a cache must have the same policy on configurable 946 parameters that may affect caching. The current implementation 947 requires the following configurable options be consistent among these 948 views: ``check-names``, ``dnssec-accept-expired``, 949 ``dnssec-validation``, ``max-cache-ttl``, ``max-ncache-ttl``, 950 ``max-stale-ttl``, ``max-cache-size``, ``min-cache-ttl``, 951 ``min-ncache-ttl``, and ``zero-no-soa-ttl``. 952 953 Note that there may be other parameters that may cause confusion if 954 they are inconsistent for different views that share a single cache. 955 For example, if these views define different sets of forwarders that 956 can return different answers for the same question, sharing the 957 answer does not make sense or could even be harmful. It is the 958 administrator's responsibility to ensure that configuration differences in 959 different views do not cause disruption with a shared cache. 960 961``directory`` 962 This sets the working directory of the server. Any non-absolute pathnames in 963 the configuration file are taken as relative to this directory. 964 The default location for most server output files (e.g., 965 ``named.run``) is this directory. If a directory is not specified, 966 the working directory defaults to ``"."``, the directory from 967 which the server was started. The directory specified should be an 968 absolute path, and *must* be writable by the effective user ID of the 969 ``named`` process. 970 971 The option takes effect only at the time that the configuration 972 option is parsed; if other files are being included before or after specifying the 973 new ``directory``, the ``directory`` option must be listed 974 before any other directive (like ``include``) that can work with relative 975 files. The safest way to include files is to use absolute file names. 976 977``dnstap`` 978 ``dnstap`` is a fast, flexible method for capturing and logging DNS 979 traffic. Developed by Robert Edmonds at Farsight Security, Inc., and 980 supported by multiple DNS implementations, ``dnstap`` uses 981 ``libfstrm`` (a lightweight high-speed framing library; see 982 https://github.com/farsightsec/fstrm) to send event payloads which 983 are encoded using Protocol Buffers (``libprotobuf-c``, a mechanism 984 for serializing structured data developed by Google, Inc.; see 985 https://developers.google.com/protocol-buffers/). 986 987 To enable ``dnstap`` at compile time, the ``fstrm`` and 988 ``protobuf-c`` libraries must be available, and BIND must be 989 configured with ``--enable-dnstap``. 990 991 The ``dnstap`` option is a bracketed list of message types to be 992 logged. These may be set differently for each view. Supported types 993 are ``client``, ``auth``, ``resolver``, ``forwarder``, and 994 ``update``. Specifying type ``all`` causes all ``dnstap`` 995 messages to be logged, regardless of type. 996 997 Each type may take an additional argument to indicate whether to log 998 ``query`` messages or ``response`` messages; if not specified, both 999 queries and responses are logged. 1000 1001 Example: To log all authoritative queries and responses, recursive 1002 client responses, and upstream queries sent by the resolver, use: 1003 1004 :: 1005 1006 dnstap { 1007 auth; 1008 client response; 1009 resolver query; 1010 }; 1011 1012 Logged ``dnstap`` messages can be parsed using the ``dnstap-read`` 1013 utility (see :ref:`man_dnstap-read` for details). 1014 1015 For more information on ``dnstap``, see http://dnstap.info. 1016 1017 The fstrm library has a number of tunables that are exposed in 1018 ``named.conf``, and can be modified if necessary to improve 1019 performance or prevent loss of data. These are: 1020 1021 - ``fstrm-set-buffer-hint``: The threshold number of bytes to 1022 accumulate in the output buffer before forcing a buffer flush. The 1023 minimum is 1024, the maximum is 65536, and the default is 8192. 1024 1025 - ``fstrm-set-flush-timeout``: The number of seconds to allow 1026 unflushed data to remain in the output buffer. The minimum is 1 1027 second, the maximum is 600 seconds (10 minutes), and the default 1028 is 1 second. 1029 1030 - ``fstrm-set-output-notify-threshold``: The number of outstanding 1031 queue entries to allow on an input queue before waking the I/O 1032 thread. The minimum is 1 and the default is 32. 1033 1034 - ``fstrm-set-output-queue-model``: The queuing semantics 1035 to use for queue objects. The default is ``mpsc`` (multiple 1036 producer, single consumer); the other option is ``spsc`` (single 1037 producer, single consumer). 1038 1039 - ``fstrm-set-input-queue-size``: The number of queue entries to 1040 allocate for each input queue. This value must be a power of 2. 1041 The minimum is 2, the maximum is 16384, and the default is 512. 1042 1043 - ``fstrm-set-output-queue-size``: The number of queue entries to 1044 allocate for each output queue. The minimum is 2, the maximum is 1045 system-dependent and based on ``IOV_MAX``, and the default is 64. 1046 1047 - ``fstrm-set-reopen-interval``: The number of seconds to wait 1048 between attempts to reopen a closed output stream. The minimum is 1049 1 second, the maximum is 600 seconds (10 minutes), and the default 1050 is 5 seconds. For convenience, TTL-style time-unit suffixes may be 1051 used to specify the value. 1052 1053 Note that all of the above minimum, maximum, and default values are 1054 set by the ``libfstrm`` library, and may be subject to change in 1055 future versions of the library. See the ``libfstrm`` documentation 1056 for more information. 1057 1058``dnstap-output`` 1059 This configures the path to which the ``dnstap`` frame stream is sent 1060 if ``dnstap`` is enabled at compile time and active. 1061 1062 The first argument is either ``file`` or ``unix``, indicating whether 1063 the destination is a file or a Unix domain socket. The second 1064 argument is the path of the file or socket. (Note: when using a 1065 socket, ``dnstap`` messages are only sent if another process such 1066 as ``fstrm_capture`` (provided with ``libfstrm``) is listening on the 1067 socket.) 1068 1069 If the first argument is ``file``, then up to three additional 1070 options can be added: ``size`` indicates the size to which a 1071 ``dnstap`` log file can grow before being rolled to a new file; 1072 ``versions`` specifies the number of rolled log files to retain; and 1073 ``suffix`` indicates whether to retain rolled log files with an 1074 incrementing counter as the suffix (``increment``) or with the 1075 current timestamp (``timestamp``). These are similar to the ``size``, 1076 ``versions``, and ``suffix`` options in a ``logging`` channel. The 1077 default is to allow ``dnstap`` log files to grow to any size without 1078 rolling. 1079 1080 ``dnstap-output`` can only be set globally in ``options``. Currently, 1081 it can only be set once while ``named`` is running; once set, it 1082 cannot be changed by ``rndc reload`` or ``rndc reconfig``. 1083 1084``dnstap-identity`` 1085 This specifies an ``identity`` string to send in ``dnstap`` messages. If 1086 set to ``hostname``, which is the default, the server's hostname 1087 is sent. If set to ``none``, no identity string is sent. 1088 1089``dnstap-version`` 1090 This specifies a ``version`` string to send in ``dnstap`` messages. The 1091 default is the version number of the BIND release. If set to 1092 ``none``, no version string is sent. 1093 1094``geoip-directory`` 1095 When ``named`` is compiled using the MaxMind GeoIP2 geolocation API, this 1096 specifies the directory containing GeoIP database files. By default, the 1097 option is set based on the prefix used to build the ``libmaxminddb`` module; 1098 for example, if the library is installed in ``/usr/local/lib``, then the 1099 default ``geoip-directory`` is ``/usr/local/share/GeoIP``. On Windows, 1100 the default is the ``named`` working directory. See :ref:`acl` 1101 for details about ``geoip`` ACLs. 1102 1103``key-directory`` 1104 This is the directory where the public and private DNSSEC key files should be 1105 found when performing a dynamic update of secure zones, if different 1106 than the current working directory. (Note that this option has no 1107 effect on the paths for files containing non-DNSSEC keys such as 1108 ``bind.keys``, ``rndc.key``, or ``session.key``.) 1109 1110``lmdb-mapsize`` 1111 When ``named`` is built with liblmdb, this option sets a maximum size 1112 for the memory map of the new-zone database (NZD) in LMDB database 1113 format. This database is used to store configuration information for 1114 zones added using ``rndc addzone``. Note that this is not the NZD 1115 database file size, but the largest size that the database may grow 1116 to. 1117 1118 Because the database file is memory-mapped, its size is limited by 1119 the address space of the ``named`` process. The default of 32 megabytes 1120 was chosen to be usable with 32-bit ``named`` builds. The largest 1121 permitted value is 1 terabyte. Given typical zone configurations 1122 without elaborate ACLs, a 32 MB NZD file ought to be able to hold 1123 configurations of about 100,000 zones. 1124 1125``managed-keys-directory`` 1126 This specifies the directory in which to store the files that track managed DNSSEC 1127 keys (i.e., those configured using the ``initial-key`` or ``initial-ds`` 1128 keywords in a ``trust-anchors`` statement). By default, this is the working 1129 directory. The directory *must* be writable by the effective user ID of the 1130 ``named`` process. 1131 1132 If ``named`` is not configured to use views, managed keys for 1133 the server are tracked in a single file called 1134 ``managed-keys.bind``. Otherwise, managed keys are tracked in 1135 separate files, one file per view; each file name is the view 1136 name (or, if it contains characters that are incompatible with use as 1137 a file name, the SHA256 hash of the view name), followed by the 1138 extension ``.mkeys``. 1139 1140 (Note: in earlier releases, file names for views always used the 1141 SHA256 hash of the view name. To ensure compatibility after upgrading, 1142 if a file using the old name format is found to exist, it is 1143 used instead of the new format.) 1144 1145``max-ixfr-ratio`` 1146 This sets the size threshold (expressed as a percentage of the size 1147 of the full zone) beyond which ``named`` chooses to use an AXFR 1148 response rather than IXFR when answering zone transfer requests. See 1149 :ref:`incremental_zone_transfers`. 1150 1151 The minimum value is ``1%``. The keyword ``unlimited`` disables ratio 1152 checking and allows IXFRs of any size. The default is ``unlimited``. 1153 1154``new-zones-directory`` 1155 This specifies the directory in which to store the configuration 1156 parameters for zones added via ``rndc addzone``. By default, this is 1157 the working directory. If set to a relative path, it is relative 1158 to the working directory. The directory *must* be writable by the 1159 effective user ID of the ``named`` process. 1160 1161``qname-minimization`` 1162 When this is set to ``strict``, BIND follows the QNAME 1163 minimization algorithm to the letter, as specified in :rfc:`7816`. 1164 1165 Setting this option to ``relaxed`` causes BIND to fall back to 1166 normal (non-minimized) query mode when it receives either NXDOMAIN or 1167 other unexpected responses (e.g., SERVFAIL, improper zone cut, 1168 REFUSED) to a minimized query. A resolver can use a leading 1169 underscore, like ``_.example.com``, in an attempt to improve 1170 interoperability. (See :rfc:`7816` section 3.) 1171 1172 ``disabled`` disables QNAME minimization completely. 1173 ``off`` is a synonym for ``disabled``. 1174 1175 The current default is ``relaxed``, but it 1176 may be changed to ``strict`` in a future release. 1177 1178``tkey-gssapi-keytab`` 1179 This is the KRB5 keytab file to use for GSS-TSIG updates. If this option is 1180 set and tkey-gssapi-credential is not set, updates are 1181 allowed with any key matching a principal in the specified keytab. 1182 1183``tkey-gssapi-credential`` 1184 This is the security credential with which the server should authenticate 1185 keys requested by the GSS-TSIG protocol. Currently only Kerberos 5 1186 authentication is available; the credential is a Kerberos 1187 principal which the server can acquire through the default system key 1188 file, normally ``/etc/krb5.keytab``. The location of the keytab file can be 1189 overridden using the ``tkey-gssapi-keytab`` option. Normally this 1190 principal is of the form ``DNS/server.domain``. To use 1191 GSS-TSIG, ``tkey-domain`` must also be set if a specific keytab is 1192 not set with ``tkey-gssapi-keytab``. 1193 1194``tkey-domain`` 1195 This domain is appended to the names of all shared keys generated with 1196 ``TKEY``. When a client requests a ``TKEY`` exchange, it may or may 1197 not specify the desired name for the key. If present, the name of the 1198 shared key is ``client-specified part`` + ``tkey-domain``. 1199 Otherwise, the name of the shared key is ``random hex digits`` 1200 + ``tkey-domain``. In most cases, the ``domainname`` 1201 should be the server's domain name, or an otherwise nonexistent 1202 subdomain like ``_tkey.domainname``. If using GSS-TSIG, 1203 this variable must be defined, unless a specific keytab 1204 is specified using ``tkey-gssapi-keytab``. 1205 1206``tkey-dhkey`` 1207 This is the Diffie-Hellman key used by the server to generate shared keys 1208 with clients using the Diffie-Hellman mode of ``TKEY``. The server 1209 must be able to load the public and private keys from files in the 1210 working directory. In most cases, the ``key_name`` should be the 1211 server's host name. 1212 1213``cache-file`` 1214 This is for testing only. Do not use. 1215 1216``dump-file`` 1217 This is the pathname of the file the server dumps the database to, when 1218 instructed to do so with ``rndc dumpdb``. If not specified, the 1219 default is ``named_dump.db``. 1220 1221``memstatistics-file`` 1222 This is the pathname of the file the server writes memory usage statistics to 1223 on exit. If not specified, the default is ``named.memstats``. 1224 1225``lock-file`` 1226 This is the pathname of a file on which ``named`` attempts to acquire a 1227 file lock when starting for the first time; if unsuccessful, the 1228 server terminates, under the assumption that another server 1229 is already running. If not specified, the default is 1230 ``none``. 1231 1232 Specifying ``lock-file none`` disables the use of a lock file. 1233 ``lock-file`` is ignored if ``named`` was run using the ``-X`` 1234 option, which overrides it. Changes to ``lock-file`` are ignored if 1235 ``named`` is being reloaded or reconfigured; it is only effective 1236 when the server is first started. 1237 1238``pid-file`` 1239 This is the pathname of the file the server writes its process ID in. If not 1240 specified, the default is ``/var/run/named/named.pid``. The PID file 1241 is used by programs that send signals to the running name 1242 server. Specifying ``pid-file none`` disables the use of a PID file; 1243 no file is written and any existing one is removed. Note 1244 that ``none`` is a keyword, not a filename, and therefore is not 1245 enclosed in double quotes. 1246 1247``recursing-file`` 1248 This is the pathname of the file where the server dumps the queries that are 1249 currently recursing, when instructed to do so with ``rndc recursing``. 1250 If not specified, the default is ``named.recursing``. 1251 1252``statistics-file`` 1253 This is the pathname of the file the server appends statistics to, when 1254 instructed to do so using ``rndc stats``. If not specified, the 1255 default is ``named.stats`` in the server's current directory. The 1256 format of the file is described in :ref:`statsfile`. 1257 1258``bindkeys-file`` 1259 This is the pathname of a file to override the built-in trusted keys provided 1260 by ``named``. See the discussion of ``dnssec-validation`` for 1261 details. If not specified, the default is ``/etc/bind.keys``. 1262 1263``secroots-file`` 1264 This is the pathname of the file the server dumps security roots to, when 1265 instructed to do so with ``rndc secroots``. If not specified, the 1266 default is ``named.secroots``. 1267 1268``session-keyfile`` 1269 This is the pathname of the file into which to write a TSIG session key 1270 generated by ``named`` for use by ``nsupdate -l``. If not specified, 1271 the default is ``/var/run/named/session.key``. (See :ref:`dynamic_update_policies`, 1272 and in particular the discussion of the ``update-policy`` statement's 1273 ``local`` option, for more information about this feature.) 1274 1275``session-keyname`` 1276 This is the key name to use for the TSIG session key. If not specified, the 1277 default is ``local-ddns``. 1278 1279``session-keyalg`` 1280 This is the algorithm to use for the TSIG session key. Valid values are 1281 hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, hmac-sha512, and 1282 hmac-md5. If not specified, the default is hmac-sha256. 1283 1284``port`` 1285 This is the UDP/TCP port number the server uses to receive and send DNS 1286 protocol traffic. The default is 53. This option is mainly intended 1287 for server testing; a server using a port other than 53 is not 1288 able to communicate with the global DNS. 1289 1290``dscp`` 1291 This is the global Differentiated Services Code Point (DSCP) value to 1292 classify outgoing DNS traffic, on operating systems that support DSCP. 1293 Valid values are 0 through 63. It is not configured by default. 1294 1295``random-device`` 1296 This specifies a source of entropy to be used by the server; it is a 1297 device or file from which to read entropy. If it is a file, 1298 operations requiring entropy will fail when the file has been 1299 exhausted. 1300 1301 Entropy is needed for cryptographic operations such as TKEY 1302 transactions, dynamic update of signed zones, and generation of TSIG 1303 session keys. It is also used for seeding and stirring the 1304 pseudo-random number generator which is used for less critical 1305 functions requiring randomness, such as generation of DNS message 1306 transaction IDs. 1307 1308 If ``random-device`` is not specified, or if it is set to ``none``, 1309 entropy is read from the random number generation function 1310 supplied by the cryptographic library with which BIND was linked 1311 (i.e. OpenSSL or a PKCS#11 provider). 1312 1313 The ``random-device`` option takes effect during the initial 1314 configuration load at server startup time and is ignored on 1315 subsequent reloads. 1316 1317``preferred-glue`` 1318 If specified, the listed type (A or AAAA) is emitted before 1319 other glue in the additional section of a query response. The default 1320 is to prefer A records when responding to queries that arrived via 1321 IPv4 and AAAA when responding to queries that arrived via IPv6. 1322 1323.. _root-delegation-only: 1324 1325``root-delegation-only`` 1326 This turns on enforcement of delegation-only in TLDs (top-level domains) 1327 and root zones with an optional exclude list. 1328 1329 DS queries are expected to be made to and be answered by delegation-only 1330 zones. Such queries and responses are treated as an exception to 1331 delegation-only processing and are not converted to NXDOMAIN 1332 responses, provided a CNAME is not discovered at the query name. 1333 1334 If a delegation-only zone server also serves a child zone, it is not 1335 always possible to determine whether an answer comes from the 1336 delegation-only zone or the child zone. SOA NS and DNSKEY records are 1337 apex-only records and a matching response that contains these records 1338 or DS is treated as coming from a child zone. RRSIG records are also 1339 examined to see whether they are signed by a child zone, and the 1340 authority section is examined to see if there is evidence that 1341 the answer is from the child zone. Answers that are determined to be 1342 from a child zone are not converted to NXDOMAIN responses. Despite 1343 all these checks, there is still a possibility of false negatives when 1344 a child zone is being served. 1345 1346 Similarly, false positives can arise from empty nodes (no records at 1347 the name) in the delegation-only zone when the query type is not ``ANY``. 1348 1349 Note that some TLDs are not delegation-only; e.g., "DE", "LV", "US", and 1350 "MUSEUM". This list is not exhaustive. 1351 1352 :: 1353 1354 options { 1355 root-delegation-only exclude { "de"; "lv"; "us"; "museum"; }; 1356 }; 1357 1358``disable-algorithms`` 1359 This disables the specified DNSSEC algorithms at and below the specified 1360 name. Multiple ``disable-algorithms`` statements are allowed. Only 1361 the best-match ``disable-algorithms`` clause is used to 1362 determine the algorithms. 1363 1364 If all supported algorithms are disabled, the zones covered by the 1365 ``disable-algorithms`` setting are treated as insecure. 1366 1367 Configured trust anchors in ``trust-anchors`` (or ``managed-keys`` or 1368 ``trusted-keys``) that match a disabled algorithm are ignored and treated 1369 as if they were not configured. 1370 1371``disable-ds-digests`` 1372 This disables the specified DS digest types at and below the specified 1373 name. Multiple ``disable-ds-digests`` statements are allowed. Only 1374 the best-match ``disable-ds-digests`` clause is used to 1375 determine the digest types. 1376 1377 If all supported digest types are disabled, the zones covered by 1378 ``disable-ds-digests`` are treated as insecure. 1379 1380``dnssec-must-be-secure`` 1381 This specifies hierarchies which must be or may not be secure (signed and 1382 validated). If ``yes``, then ``named`` only accepts answers if 1383 they are secure. If ``no``, then normal DNSSEC validation applies, 1384 allowing insecure answers to be accepted. The specified domain 1385 must be defined as a trust anchor, for instance in a ``trust-anchors`` 1386 statement, or ``dnssec-validation auto`` must be active. 1387 1388``dns64`` 1389 This directive instructs ``named`` to return mapped IPv4 addresses to 1390 AAAA queries when there are no AAAA records. It is intended to be 1391 used in conjunction with a NAT64. Each ``dns64`` defines one DNS64 1392 prefix. Multiple DNS64 prefixes can be defined. 1393 1394 Compatible IPv6 prefixes have lengths of 32, 40, 48, 56, 64, and 96, per 1395 :rfc:`6052`. Bits 64..71 inclusive must be zero, with the most significant bit 1396 of the prefix in position 0. 1397 1398 In addition, a reverse IP6.ARPA zone is created for the prefix 1399 to provide a mapping from the IP6.ARPA names to the corresponding 1400 IN-ADDR.ARPA names using synthesized CNAMEs. ``dns64-server`` and 1401 ``dns64-contact`` can be used to specify the name of the server and 1402 contact for the zones. These can be set at the view/options 1403 level but not on a per-prefix basis. 1404 1405 Each ``dns64`` supports an optional ``clients`` ACL that determines 1406 which clients are affected by this directive. If not defined, it 1407 defaults to ``any;``. 1408 1409 Each ``dns64`` supports an optional ``mapped`` ACL that selects which 1410 IPv4 addresses are to be mapped in the corresponding A RRset. If not 1411 defined, it defaults to ``any;``. 1412 1413 Normally, DNS64 does not apply to a domain name that owns one or more 1414 AAAA records; these records are simply returned. The optional 1415 ``exclude`` ACL allows specification of a list of IPv6 addresses that 1416 are ignored if they appear in a domain name's AAAA records; 1417 DNS64 is applied to any A records the domain name owns. If not 1418 defined, ``exclude`` defaults to ::ffff:0.0.0.0/96. 1419 1420 An optional ``suffix`` can also be defined to set the bits trailing 1421 the mapped IPv4 address bits. By default these bits are set to 1422 ``::``. The bits matching the prefix and mapped IPv4 address must be 1423 zero. 1424 1425 If ``recursive-only`` is set to ``yes``, the DNS64 synthesis only 1426 happens for recursive queries. The default is ``no``. 1427 1428 If ``break-dnssec`` is set to ``yes``, the DNS64 synthesis happens 1429 even if the result, if validated, would cause a DNSSEC validation 1430 failure. If this option is set to ``no`` (the default), the DO is set 1431 on the incoming query, and there are RRSIGs on the applicable 1432 records, then synthesis does not happen. 1433 1434 :: 1435 1436 acl rfc1918 { 10/8; 192.168/16; 172.16/12; }; 1437 1438 dns64 64:FF9B::/96 { 1439 clients { any; }; 1440 mapped { !rfc1918; any; }; 1441 exclude { 64:FF9B::/96; ::ffff:0000:0000/96; }; 1442 suffix ::; 1443 }; 1444 1445``dnssec-loadkeys-interval`` 1446 When a zone is configured with ``auto-dnssec maintain;``, its key 1447 repository must be checked periodically to see if any new keys have 1448 been added or any existing keys' timing metadata has been updated 1449 (see :ref:`man_dnssec-keygen` and :ref:`man_dnssec-settime`). 1450 The ``dnssec-loadkeys-interval`` option 1451 sets the frequency of automatic repository checks, in minutes. The 1452 default is ``60`` (1 hour), the minimum is ``1`` (1 minute), and 1453 the maximum is ``1440`` (24 hours); any higher value is silently 1454 reduced. 1455 1456``dnssec-policy`` 1457 This specifies which key and signing policy (KASP) should be used for this 1458 zone. This is a string referring to a ``dnssec-policy`` statement. There 1459 are three built-in policies: ``default``, which uses the default policy, 1460 ``insecure``, to be used when you want to gracefully unsign your zone, and 1461 ``none``, which means no DNSSEC policy. The default is ``none``. 1462 See :ref:`dnssec-policy Grammar <dnssec_policy_grammar>` for more details. 1463 1464``dnssec-update-mode`` 1465 If this option is set to its default value of ``maintain`` in a zone 1466 of type ``primary`` which is DNSSEC-signed and configured to allow 1467 dynamic updates (see :ref:`dynamic_update_policies`), and if ``named`` has access 1468 to the private signing key(s) for the zone, then ``named`` 1469 automatically signs all new or changed records and maintains signatures 1470 for the zone by regenerating RRSIG records whenever they approach 1471 their expiration date. 1472 1473 If the option is changed to ``no-resign``, then ``named`` signs 1474 all new or changed records, but scheduled maintenance of signatures 1475 is disabled. 1476 1477 With either of these settings, ``named`` rejects updates to a 1478 DNSSEC-signed zone when the signing keys are inactive or unavailable 1479 to ``named``. (A planned third option, ``external``, will disable all 1480 automatic signing and allow DNSSEC data to be submitted into a zone 1481 via dynamic update; this is not yet implemented.) 1482 1483``nta-lifetime`` 1484 This specifies the default lifetime, in seconds, for 1485 negative trust anchors added via ``rndc nta``. 1486 1487 A negative trust anchor selectively disables DNSSEC validation for 1488 zones that are known to be failing because of misconfiguration, rather 1489 than an attack. When data to be validated is at or below an active 1490 NTA (and above any other configured trust anchors), ``named`` 1491 aborts the DNSSEC validation process and treats the data as insecure 1492 rather than bogus. This continues until the NTA's lifetime has 1493 elapsed. NTAs persist across ``named`` restarts. 1494 1495 For convenience, TTL-style time-unit suffixes can be used to specify the NTA 1496 lifetime in seconds, minutes, or hours. It also accepts ISO 8601 duration 1497 formats. 1498 1499 ``nta-lifetime`` defaults to one hour; it cannot exceed one week. 1500 1501``nta-recheck`` 1502 This specifies how often to check whether negative trust anchors added via 1503 ``rndc nta`` are still necessary. 1504 1505 A negative trust anchor is normally used when a domain has stopped 1506 validating due to operator error; it temporarily disables DNSSEC 1507 validation for that domain. In the interest of ensuring that DNSSEC 1508 validation is turned back on as soon as possible, ``named`` 1509 periodically sends a query to the domain, ignoring negative trust 1510 anchors, to find out whether it can now be validated. If so, the 1511 negative trust anchor is allowed to expire early. 1512 1513 Validity checks can be disabled for an individual NTA by using 1514 ``rndc nta -f``, or for all NTAs by setting ``nta-recheck`` to zero. 1515 1516 For convenience, TTL-style time-unit suffixes can be used to specify the NTA 1517 recheck interval in seconds, minutes, or hours. It also accepts ISO 8601 1518 duration formats. 1519 1520 The default is five minutes. It cannot be longer than ``nta-lifetime``, which 1521 cannot be longer than a week. 1522 1523``max-zone-ttl`` 1524 1525 This should now be configured as part of ``dnssec-policy``. 1526 Use of this option in ``options``, ``view`` and ``zone`` blocks has no 1527 effect on any zone for which a ``dnssec-policy`` has also been configured. 1528 1529 ``max-zone-ttl`` specifies a maximum permissible TTL value in seconds. 1530 For convenience, TTL-style time-unit suffixes may be used to specify the 1531 maximum value. When a zone file is loaded, any record encountered with a 1532 TTL higher than ``max-zone-ttl`` causes the zone to be rejected. 1533 1534 This is useful in DNSSEC-signed zones because when rolling to a new 1535 DNSKEY, the old key needs to remain available until RRSIG records 1536 have expired from caches. The ``max-zone-ttl`` option guarantees that 1537 the largest TTL in the zone is no higher than the set value. 1538 1539 (Note: because ``map``-format files load directly into memory, this 1540 option cannot be used with them.) 1541 1542 The default value is ``unlimited``. Setting ``max-zone-ttl`` to zero is 1543 equivalent to ``unlimited``. 1544 1545``stale-answer-ttl`` 1546 This specifies the TTL to be returned on stale answers. The default is 30 1547 seconds. The minimum allowed is 1 second; a value of 0 is updated silently 1548 to 1 second. 1549 1550 For stale answers to be returned, they must be enabled, either in the 1551 configuration file using ``stale-answer-enable`` or via 1552 ``rndc serve-stale on``. 1553 1554``serial-update-method`` 1555 Zones configured for dynamic DNS may use this option to set the 1556 update method to be used for the zone serial number in the SOA 1557 record. 1558 1559 With the default setting of ``serial-update-method increment;``, the 1560 SOA serial number is incremented by one each time the zone is 1561 updated. 1562 1563 When set to ``serial-update-method unixtime;``, the SOA serial number 1564 is set to the number of seconds since the Unix epoch, unless the 1565 serial number is already greater than or equal to that value, in 1566 which case it is simply incremented by one. 1567 1568 When set to ``serial-update-method date;``, the new SOA serial number 1569 is the current date in the form "YYYYMMDD", followed by two 1570 zeroes, unless the existing serial number is already greater than or 1571 equal to that value, in which case it is incremented by one. 1572 1573``zone-statistics`` 1574 If ``full``, the server collects statistical data on all zones, 1575 unless specifically turned off on a per-zone basis by specifying 1576 ``zone-statistics terse`` or ``zone-statistics none`` in the ``zone`` 1577 statement. The statistical data includes, for example, DNSSEC signing 1578 operations and the number of authoritative answers per query type. The 1579 default is ``terse``, providing minimal statistics on zones 1580 (including name and current serial number, but not query type 1581 counters). 1582 1583 These statistics may be accessed via the ``statistics-channel`` or 1584 using ``rndc stats``, which dumps them to the file listed in the 1585 ``statistics-file``. See also :ref:`statsfile`. 1586 1587 For backward compatibility with earlier versions of BIND 9, the 1588 ``zone-statistics`` option can also accept ``yes`` or ``no``; ``yes`` 1589 has the same meaning as ``full``. As of BIND 9.10, ``no`` has the 1590 same meaning as ``none``; previously, it was the same as ``terse``. 1591 1592.. _boolean_options: 1593 1594Boolean Options 1595^^^^^^^^^^^^^^^ 1596 1597``automatic-interface-scan`` 1598 If ``yes`` and supported by the operating system, this automatically rescans 1599 network interfaces when the interface addresses are added or removed. The 1600 default is ``yes``. This configuration option does not affect the time-based 1601 ``interface-interval`` option; it is recommended to set the time-based 1602 ``interface-interval`` to 0 when the operator confirms that automatic 1603 interface scanning is supported by the operating system. 1604 1605 The ``automatic-interface-scan`` implementation uses routing sockets for the 1606 network interface discovery; therefore, the operating system must 1607 support the routing sockets for this feature to work. 1608 1609``allow-new-zones`` 1610 If ``yes``, then zones can be added at runtime via ``rndc addzone``. 1611 The default is ``no``. 1612 1613 Newly added zones' configuration parameters are stored so that they 1614 can persist after the server is restarted. The configuration 1615 information is saved in a file called ``viewname.nzf`` (or, if 1616 ``named`` is compiled with liblmdb, in an LMDB database file called 1617 ``viewname.nzd``). "viewname" is the name of the view, unless the view 1618 name contains characters that are incompatible with use as a file 1619 name, in which case a cryptographic hash of the view name is used 1620 instead. 1621 1622 Configurations for zones added at runtime are stored either in 1623 a new-zone file (NZF) or a new-zone database (NZD), depending on 1624 whether ``named`` was linked with liblmdb at compile time. See 1625 :ref:`man_rndc` for further details about ``rndc addzone``. 1626 1627``auth-nxdomain`` 1628 If ``yes``, then the ``AA`` bit is always set on NXDOMAIN responses, 1629 even if the server is not actually authoritative. The default is 1630 ``no``. 1631 1632``memstatistics`` 1633 This writes memory statistics to the file specified by 1634 ``memstatistics-file`` at exit. The default is ``no`` unless ``-m 1635 record`` is specified on the command line, in which case it is ``yes``. 1636 1637``dialup`` 1638 If ``yes``, then the server treats all zones as if they are doing 1639 zone transfers across a dial-on-demand dialup link, which can be 1640 brought up by traffic originating from this server. Although this setting has 1641 different effects according to zone type, it concentrates the zone 1642 maintenance so that everything happens quickly, once every 1643 ``heartbeat-interval``, ideally during a single call. It also 1644 suppresses some normal zone maintenance traffic. The default 1645 is ``no``. 1646 1647 If specified in the ``view`` and 1648 ``zone`` statements, the ``dialup`` option overrides the global ``dialup`` 1649 option. 1650 1651 If the zone is a primary zone, the server sends out a NOTIFY 1652 request to all the secondaries (default). This should trigger the zone 1653 serial number check in the secondary (providing it supports NOTIFY), 1654 allowing the secondary to verify the zone while the connection is active. 1655 The set of servers to which NOTIFY is sent can be controlled by 1656 ``notify`` and ``also-notify``. 1657 1658 If the zone is a secondary or stub zone, the server suppresses 1659 the regular "zone up to date" (refresh) queries and only performs them 1660 when the ``heartbeat-interval`` expires, in addition to sending NOTIFY 1661 requests. 1662 1663 Finer control can be achieved by using ``notify``, which only sends 1664 NOTIFY messages; ``notify-passive``, which sends NOTIFY messages and 1665 suppresses the normal refresh queries; ``refresh``, which suppresses 1666 normal refresh processing and sends refresh queries when the 1667 ``heartbeat-interval`` expires; and ``passive``, which disables 1668 normal refresh processing. 1669 1670 +--------------------+-----------------+-----------------+-----------------+ 1671 | dialup mode | normal refresh | heart-beat | heart-beat | 1672 | | | refresh | notify | 1673 +--------------------+-----------------+-----------------+-----------------+ 1674 | ``no`` | yes | no | no | 1675 | (default) | | | | 1676 +--------------------+-----------------+-----------------+-----------------+ 1677 | ``yes`` | no | yes | yes | 1678 +--------------------+-----------------+-----------------+-----------------+ 1679 | ``notify`` | yes | no | yes | 1680 +--------------------+-----------------+-----------------+-----------------+ 1681 | ``refresh`` | no | yes | no | 1682 +--------------------+-----------------+-----------------+-----------------+ 1683 | ``passive`` | no | no | no | 1684 +--------------------+-----------------+-----------------+-----------------+ 1685 | ``notify-passive`` | no | no | yes | 1686 +--------------------+-----------------+-----------------+-----------------+ 1687 1688 Note that normal NOTIFY processing is not affected by ``dialup``. 1689 1690``flush-zones-on-shutdown`` 1691 When the name server exits upon receiving SIGTERM, flush or do not 1692 flush any pending zone writes. The default is 1693 ``flush-zones-on-shutdown no``. 1694 1695``geoip-use-ecs`` 1696 This option was part of an experimental implementation of the EDNS 1697 CLIENT-SUBNET for authoritative servers, but is now obsolete. 1698 1699``root-key-sentinel`` 1700 If ``yes``, respond to root key sentinel probes as described in 1701 draft-ietf-dnsop-kskroll-sentinel-08. The default is ``yes``. 1702 1703``reuseport`` 1704 This option enables kernel load-balancing of sockets on systems which support 1705 it, including Linux (SO_REUSEPORT) and FreeBSD (SO_REUSEPORT_LB). This 1706 instructs the kernel to distribute incoming socket connections among the 1707 networking threads based on a hashing scheme. For more information, see the 1708 receive network flow classification options (``rx-flow-hash``) section in the 1709 ``ethtool`` manual page. The default is ``yes``. 1710 1711 Enabling ``reuseport`` significantly increases general throughput when 1712 incoming traffic is distributed uniformly onto the threads by the 1713 operating system. However, in cases where a worker thread is busy with a 1714 long-lasting operation, such as processing a Response Policy Zone (RPZ) or 1715 Catalog Zone update or an unusually large zone transfer, incoming traffic 1716 that hashes onto that thread may be delayed. On servers where these events 1717 occur frequently, it may be preferable to disable socket load-balancing so 1718 that other threads can pick up the traffic that would have been sent to the 1719 busy thread. 1720 1721 Note: this option can only be set when ``named`` first starts. 1722 Changes will not take effect during reconfiguration; the server 1723 must be restarted. 1724 1725``message-compression`` 1726 If ``yes``, DNS name compression is used in responses to regular 1727 queries (not including AXFR or IXFR, which always use compression). 1728 Setting this option to ``no`` reduces CPU usage on servers and may 1729 improve throughput. However, it increases response size, which may 1730 cause more queries to be processed using TCP; a server with 1731 compression disabled is out of compliance with :rfc:`1123` Section 1732 6.1.3.2. The default is ``yes``. 1733 1734``minimal-responses`` 1735 This option controls the addition of records to the authority and 1736 additional sections of responses. Such records may be included in 1737 responses to be helpful to clients; for example, MX records may 1738 have associated address records included in the additional section, 1739 obviating the need for a separate address lookup. However, adding 1740 these records to responses is not mandatory and requires additional 1741 database lookups, causing extra latency when marshalling responses. 1742 1743 Responses to DNSKEY, DS, CDNSKEY, and CDS requests will never have 1744 optional additional records added. Responses to NS requests will 1745 always have additional section processing. 1746 1747 ``minimal-responses`` takes one of four values: 1748 1749 - ``no``: the server is as complete as possible when generating 1750 responses. 1751 - ``yes``: the server only adds records to the authority and additional 1752 sections when such records are required by the DNS protocol (for 1753 example, when returning delegations or negative responses). This 1754 provides the best server performance but may result in more client 1755 queries. 1756 - ``no-auth``: the server omits records from the authority section except 1757 when they are required, but it may still add records to the 1758 additional section. 1759 - ``no-auth-recursive``: the same as ``no-auth`` when recursion is requested 1760 in the query (RD=1), or the same as ``no`` if recursion is not requested. 1761 1762 ``no-auth`` and ``no-auth-recursive`` are useful when answering stub 1763 clients, which usually ignore the authority section. 1764 ``no-auth-recursive`` is meant for use in mixed-mode servers that 1765 handle both authoritative and recursive queries. 1766 1767 The default is ``no-auth-recursive``. 1768 1769``glue-cache`` 1770 When set to ``yes``, a cache is used to improve query performance 1771 when adding address-type (A and AAAA) glue records to the additional 1772 section of DNS response messages that delegate to a child zone. 1773 1774 The glue cache uses memory proportional to the number of delegations 1775 in the zone. The default setting is ``yes``, which improves 1776 performance at the cost of increased memory usage for the zone. To avoid 1777 this, set it to ``no``. 1778 1779``minimal-any`` 1780 If set to ``yes``, the server replies with only one of 1781 the RRsets for the query name, and its covering RRSIGs if any, 1782 when generating a positive response to a query of type ANY over UDP, 1783 instead of replying with all known RRsets for the name. Similarly, a 1784 query for type RRSIG is answered with the RRSIG records covering 1785 only one type. This can reduce the impact of some kinds of attack 1786 traffic, without harming legitimate clients. (Note, however, that the 1787 RRset returned is the first one found in the database; it is not 1788 necessarily the smallest available RRset.) Additionally, 1789 ``minimal-responses`` is turned on for these queries, so no 1790 unnecessary records are added to the authority or additional 1791 sections. The default is ``no``. 1792 1793``notify`` 1794 If set to ``yes`` (the default), DNS NOTIFY messages are sent when a 1795 zone the server is authoritative for changes; see :ref:`notify`. 1796 The messages are sent to the servers listed in the zone's NS records 1797 (except the primary server identified in the SOA MNAME field), and to 1798 any servers listed in the ``also-notify`` option. 1799 1800 If set to ``primary-only`` (or the older keyword ``master-only``), 1801 notifies are only sent for primary zones. If set to ``explicit``, 1802 notifies are sent only to servers explicitly listed using 1803 ``also-notify``. If set to ``no``, no notifies are sent. 1804 1805 The ``notify`` option may also be specified in the ``zone`` 1806 statement, in which case it overrides the ``options notify`` 1807 statement. It would only be necessary to turn off this option if it 1808 caused secondary zones to crash. 1809 1810``notify-to-soa`` 1811 If ``yes``, do not check the name servers in the NS RRset against the 1812 SOA MNAME. Normally a NOTIFY message is not sent to the SOA MNAME 1813 (SOA ORIGIN), as it is supposed to contain the name of the ultimate 1814 primary server. Sometimes, however, a secondary server is listed as the SOA MNAME in 1815 hidden primary configurations; in that case, the 1816 ultimate primary should be set to still send NOTIFY messages to all the name servers 1817 listed in the NS RRset. 1818 1819``recursion`` 1820 If ``yes``, and a DNS query requests recursion, then the server 1821 attempts to do all the work required to answer the query. If recursion 1822 is off and the server does not already know the answer, it 1823 returns a referral response. The default is ``yes``. Note that setting 1824 ``recursion no`` does not prevent clients from getting data from the 1825 server's cache; it only prevents new data from being cached as an 1826 effect of client queries. Caching may still occur as an effect of the 1827 server's internal operation, such as NOTIFY address lookups. 1828 1829``request-nsid`` 1830 If ``yes``, then an empty EDNS(0) NSID (Name Server Identifier) 1831 option is sent with all queries to authoritative name servers during 1832 iterative resolution. If the authoritative server returns an NSID 1833 option in its response, then its contents are logged in the ``nsid`` 1834 category at level ``info``. The default is ``no``. 1835 1836``request-sit`` 1837 This experimental option is obsolete. 1838 1839``require-server-cookie`` 1840 If ``yes``, require a valid server cookie before sending a full response to a UDP 1841 request from a cookie-aware client. BADCOOKIE is sent if there is a 1842 bad or nonexistent server cookie. 1843 1844 The default is ``no``. 1845 1846 Users wishing to test that DNS COOKIE clients correctly handle 1847 BADCOOKIE, or who are getting a lot of forged DNS requests with DNS COOKIES 1848 present, should set this to ``yes``. Setting this to ``yes`` results in a reduced amplification effect 1849 in a reflection attack, as the BADCOOKIE response is smaller than a full 1850 response, while also requiring a legitimate client to follow up with a second 1851 query with the new, valid, cookie. 1852 1853``answer-cookie`` 1854 When set to the default value of ``yes``, COOKIE EDNS options are 1855 sent when applicable in replies to client queries. If set to ``no``, 1856 COOKIE EDNS options are not sent in replies. This can only be set 1857 at the global options level, not per-view. 1858 1859 ``answer-cookie no`` is intended as a temporary measure, for use when 1860 ``named`` shares an IP address with other servers that do not yet 1861 support DNS COOKIE. A mismatch between servers on the same address is 1862 not expected to cause operational problems, but the option to disable 1863 COOKIE responses so that all servers have the same behavior is 1864 provided out of an abundance of caution. DNS COOKIE is an important 1865 security mechanism, and should not be disabled unless absolutely 1866 necessary. 1867 1868``send-cookie`` 1869 If ``yes``, then a COOKIE EDNS option is sent along with the query. 1870 If the resolver has previously communicated with the server, the COOKIE 1871 returned in the previous transaction is sent. This is used by the 1872 server to determine whether the resolver has talked to it before. A 1873 resolver sending the correct COOKIE is assumed not to be an off-path 1874 attacker sending a spoofed-source query; the query is therefore 1875 unlikely to be part of a reflection/amplification attack, so 1876 resolvers sending a correct COOKIE option are not subject to response 1877 rate limiting (RRL). Resolvers which do not send a correct COOKIE 1878 option may be limited to receiving smaller responses via the 1879 ``nocookie-udp-size`` option. 1880 1881 The default is ``yes``. 1882 1883``stale-answer-enable`` 1884 If ``yes``, enable the returning of "stale" cached answers when the name 1885 servers for a zone are not answering and the ``stale-cache-enable`` option is 1886 also enabled. The default is not to return stale answers. 1887 1888 Stale answers can also be enabled or disabled at runtime via 1889 ``rndc serve-stale on`` or ``rndc serve-stale off``; these override 1890 the configured setting. ``rndc serve-stale reset`` restores the 1891 setting to the one specified in ``named.conf``. Note that if stale 1892 answers have been disabled by ``rndc``, they cannot be 1893 re-enabled by reloading or reconfiguring ``named``; they must be 1894 re-enabled with ``rndc serve-stale on``, or the server must be 1895 restarted. 1896 1897 Information about stale answers is logged under the ``serve-stale`` 1898 log category. 1899 1900``stale-answer-client-timeout`` 1901 This option defines the amount of time (in milliseconds) that ``named`` 1902 waits before attempting to answer the query with a stale RRset from cache. 1903 If a stale answer is found, ``named`` continues the ongoing fetches, 1904 attempting to refresh the RRset in cache until the 1905 ``resolver-query-timeout`` interval is reached. 1906 1907 This option is off by default, which is equivalent to setting it to 1908 ``off`` or ``disabled``. It also has no effect if ``stale-answer-enable`` 1909 is disabled. 1910 1911 The maximum value for this option is ``resolver-query-timeout`` minus 1912 one second. The minimum value, ``0``, causes a cached (stale) RRset to be 1913 immediately returned if it is available while still attempting to 1914 refresh the data in cache. :rfc:`8767` recommends a value of ``1800`` 1915 (milliseconds). 1916 1917``stale-cache-enable`` 1918 If ``yes``, enable the retaining of "stale" cached answers. Default ``yes``. 1919 1920``stale-refresh-time`` 1921 If the name servers for a given zone are not answering, this sets the time 1922 window for which ``named`` will promptly return "stale" cached answers for 1923 that RRSet being requested before a new attempt in contacting the servers 1924 is made. For convenience, TTL-style time-unit suffixes may be used to 1925 specify the value. It also accepts ISO 8601 duration formats. 1926 1927 The default ``stale-refresh-time`` is 30 seconds, as :rfc:`8767` recommends 1928 that attempts to refresh to be done no more frequently than every 30 1929 seconds. A value of zero disables the feature, meaning that normal 1930 resolution will take place first, if that fails only then ``named`` will 1931 return "stale" cached answers. 1932 1933``nocookie-udp-size`` 1934 This sets the maximum size of UDP responses that are sent to queries 1935 without a valid server COOKIE. A value below 128 is silently 1936 raised to 128. The default value is 4096, but the ``max-udp-size`` 1937 option may further limit the response size as the default for 1938 ``max-udp-size`` is 4096. 1939 1940``sit-secret`` 1941 This experimental option is obsolete. 1942 1943``cookie-algorithm`` 1944 This sets the algorithm to be used when generating the server cookie; the options are 1945 "aes" or "siphash24". The default is "siphash24". The "aes" option remains for legacy 1946 purposes. 1947 1948``cookie-secret`` 1949 If set, this is a shared secret used for generating and verifying 1950 EDNS COOKIE options within an anycast cluster. If not set, the system 1951 generates a random secret at startup. The shared secret is 1952 encoded as a hex string and needs to be 128 bits for either "siphash24" 1953 or "aes". 1954 1955 If there are multiple secrets specified, the first one listed in 1956 ``named.conf`` is used to generate new server cookies. The others 1957 are only used to verify returned cookies. 1958 1959``response-padding`` 1960 The EDNS Padding option is intended to improve confidentiality when 1961 DNS queries are sent over an encrypted channel, by reducing the 1962 variability in packet sizes. If a query: 1963 1964 1. contains an EDNS Padding option, 1965 2. includes a valid server cookie or uses TCP, 1966 3. is not signed using TSIG or SIG(0), and 1967 4. is from a client whose address matches the specified ACL, 1968 1969 then the response is padded with an EDNS Padding option to a multiple 1970 of ``block-size`` bytes. If these conditions are not met, the 1971 response is not padded. 1972 1973 If ``block-size`` is 0 or the ACL is ``none;``, this feature is 1974 disabled and no padding occurs; this is the default. If 1975 ``block-size`` is greater than 512, a warning is logged and the value 1976 is truncated to 512. Block sizes are ordinarily expected to be powers 1977 of two (for instance, 128), but this is not mandatory. 1978 1979``trust-anchor-telemetry`` 1980 This causes ``named`` to send specially formed queries once per day to 1981 domains for which trust anchors have been configured via, e.g., 1982 ``trust-anchors`` or ``dnssec-validation auto``. 1983 1984 The query name used for these queries has the form 1985 ``_ta-xxxx(-xxxx)(...).<domain>``, where each "xxxx" is a group of four 1986 hexadecimal digits representing the key ID of a trusted DNSSEC key. 1987 The key IDs for each domain are sorted smallest to largest prior to 1988 encoding. The query type is NULL. 1989 1990 By monitoring these queries, zone operators are able to see which 1991 resolvers have been updated to trust a new key; this may help them 1992 decide when it is safe to remove an old one. 1993 1994 The default is ``yes``. 1995 1996``use-ixfr`` 1997 *This option is obsolete*. To disable IXFR to a 1998 particular server or servers, see the information on the 1999 ``provide-ixfr`` option in :ref:`server_statement_definition_and_usage`. 2000 See also :ref:`incremental_zone_transfers`. 2001 2002``provide-ixfr`` 2003 See the description of ``provide-ixfr`` in :ref:`server_statement_definition_and_usage`. 2004 2005``request-ixfr`` 2006 See the description of ``request-ixfr`` in :ref:`server_statement_definition_and_usage`. 2007 2008``request-expire`` 2009 See the description of ``request-expire`` in :ref:`server_statement_definition_and_usage`. 2010 2011``match-mapped-addresses`` 2012 If ``yes``, then an IPv4-mapped IPv6 address matches any 2013 address-match list entries that match the corresponding IPv4 address. 2014 2015 This option was introduced to work around a kernel quirk in some 2016 operating systems that causes IPv4 TCP connections, such as zone 2017 transfers, to be accepted on an IPv6 socket using mapped addresses. 2018 This caused address-match lists designed for IPv4 to fail to match. 2019 However, ``named`` now solves this problem internally. The use of 2020 this option is discouraged. 2021 2022``ixfr-from-differences`` 2023 When ``yes`` and the server loads a new version of a primary zone from 2024 its zone file or receives a new version of a secondary file via zone 2025 transfer, it compares the new version to the previous one and 2026 calculates a set of differences. The differences are then logged in 2027 the zone's journal file so that the changes can be transmitted to 2028 downstream secondaries as an incremental zone transfer. 2029 2030 By allowing incremental zone transfers to be used for non-dynamic 2031 zones, this option saves bandwidth at the expense of increased CPU 2032 and memory consumption at the primary server. In particular, if the new 2033 version of a zone is completely different from the previous one, the 2034 set of differences is of a size comparable to the combined size 2035 of the old and new zone versions, and the server needs to 2036 temporarily allocate memory to hold this complete difference set. 2037 2038 ``ixfr-from-differences`` also accepts ``primary`` 2039 and ``secondary`` at the view and options levels, 2040 which causes ``ixfr-from-differences`` to be enabled for all primary 2041 or secondary zones, respectively. It is off for all zones by default. 2042 2043 Note: if inline signing is enabled for a zone, the user-provided 2044 ``ixfr-from-differences`` setting is ignored for that zone. 2045 2046``multi-master`` 2047 This should be set when there are multiple primary servers for a zone and the 2048 addresses refer to different machines. If ``yes``, ``named`` does not 2049 log when the serial number on the primary is less than what ``named`` 2050 currently has. The default is ``no``. 2051 2052``auto-dnssec`` 2053 Zones configured for dynamic DNS may use this option to allow varying 2054 levels of automatic DNSSEC key management. There are three possible 2055 settings: 2056 2057 ``auto-dnssec allow;`` permits keys to be updated and the zone fully 2058 re-signed whenever the user issues the command ``rndc sign zonename``. 2059 2060 ``auto-dnssec maintain;`` includes the above, but also 2061 automatically adjusts the zone's DNSSEC keys on a schedule, according 2062 to the keys' timing metadata (see :ref:`man_dnssec-keygen` and 2063 :ref:`man_dnssec-settime`). The command ``rndc sign zonename`` 2064 causes ``named`` to load keys from the key repository and sign the 2065 zone with all keys that are active. ``rndc loadkeys zonename`` 2066 causes ``named`` to load keys from the key repository and schedule 2067 key maintenance events to occur in the future, but it does not sign 2068 the full zone immediately. Note: once keys have been loaded for a 2069 zone the first time, the repository is searched for changes 2070 periodically, regardless of whether ``rndc loadkeys`` is used. The 2071 recheck interval is defined by ``dnssec-loadkeys-interval``. 2072 2073 ``auto-dnssec off;`` does not allow for DNSSEC key management. 2074 This is the default setting. 2075 2076 This option may only be activated at the zone level; if configured 2077 at the view or options level, it must be set to ``off``. 2078 2079 The DNSSEC records are written to the zone's filename set in ``file``, 2080 unless ``inline-signing`` is enabled. 2081 2082``dnssec-enable`` 2083 This option is obsolete and has no effect. 2084 2085.. _dnssec-validation-option: 2086 2087``dnssec-validation`` 2088 This option enables DNSSEC validation in ``named``. 2089 2090 If set to ``auto``, DNSSEC validation is enabled and a default trust 2091 anchor for the DNS root zone is used. This trust anchor is provided 2092 as part of BIND and is kept up-to-date using :ref:`rfc5011.support` key 2093 management. 2094 2095 If set to ``yes``, DNSSEC validation is enabled, but a trust anchor must be 2096 manually configured using a ``trust-anchors`` statement (or the 2097 ``managed-keys`` or ``trusted-keys`` statements, both deprecated). If 2098 there is no configured trust anchor, validation does not take place. 2099 2100 If set to ``no``, DNSSEC validation is disabled. 2101 2102 The default is ``auto``, unless BIND is built with 2103 ``configure --disable-auto-validation``, in which case the default is 2104 ``yes``. 2105 2106 The default root trust anchor is stored in the file ``bind.keys``. 2107 ``named`` loads that key at startup if ``dnssec-validation`` is 2108 set to ``auto``. A copy of the file is installed along with BIND 9, 2109 and is current as of the release date. If the root key expires, a new 2110 copy of ``bind.keys`` can be downloaded from 2111 https://www.isc.org/bind-keys. 2112 2113 (To prevent problems if ``bind.keys`` is not found, the current trust 2114 anchor is also compiled in ``named``. Relying on this is not 2115 recommended, however, as it requires ``named`` to be recompiled with 2116 a new key when the root key expires.) 2117 2118 .. note:: ``named`` loads *only* the root key from ``bind.keys``. The file 2119 cannot be used to store keys for other zones. The root key in 2120 ``bind.keys`` is ignored if ``dnssec-validation auto`` is not in 2121 use. 2122 2123 Whenever the resolver sends out queries to an EDNS-compliant 2124 server, it always sets the DO bit indicating it can support DNSSEC 2125 responses, even if ``dnssec-validation`` is off. 2126 2127``validate-except`` 2128 This specifies a list of domain names at and beneath which DNSSEC 2129 validation should *not* be performed, regardless of the presence of a 2130 trust anchor at or above those names. This may be used, for example, 2131 when configuring a top-level domain intended only for local use, so 2132 that the lack of a secure delegation for that domain in the root zone 2133 does not cause validation failures. (This is similar to setting a 2134 negative trust anchor except that it is a permanent configuration, 2135 whereas negative trust anchors expire and are removed after a set 2136 period of time.) 2137 2138``dnssec-accept-expired`` 2139 This accepts expired signatures when verifying DNSSEC signatures. The 2140 default is ``no``. Setting this option to ``yes`` leaves ``named`` 2141 vulnerable to replay attacks. 2142 2143``querylog`` 2144 Query logging provides a complete log of all incoming queries and all query 2145 errors. This provides more insight into the server's activity, but with a 2146 cost to performance which may be significant on heavily loaded servers. 2147 2148 The ``querylog`` option specifies whether query logging should be active when 2149 ``named`` first starts. If ``querylog`` is not specified, then query logging 2150 is determined by the presence of the logging category ``queries``. Query 2151 logging can also be activated at runtime using the command ``rndc querylog 2152 on``, or deactivated with ``rndc querylog off``. 2153 2154``check-names`` 2155 This option is used to restrict the character set and syntax of 2156 certain domain names in primary files and/or DNS responses received 2157 from the network. The default varies according to usage area. For 2158 ``primary`` zones the default is ``fail``. For ``secondary`` zones the 2159 default is ``warn``. For answers received from the network 2160 (``response``), the default is ``ignore``. 2161 2162 The rules for legal hostnames and mail domains are derived from 2163 :rfc:`952` and :rfc:`821` as modified by :rfc:`1123`. 2164 2165 ``check-names`` applies to the owner names of A, AAAA, and MX records. 2166 It also applies to the domain names in the RDATA of NS, SOA, MX, and 2167 SRV records. It further applies to the RDATA of PTR records where the 2168 owner name indicates that it is a reverse lookup of a hostname (the 2169 owner name ends in IN-ADDR.ARPA, IP6.ARPA, or IP6.INT). 2170 2171``check-dup-records`` 2172 This checks primary zones for records that are treated as different by 2173 DNSSEC but are semantically equal in plain DNS. The default is to 2174 ``warn``. Other possible values are ``fail`` and ``ignore``. 2175 2176``check-mx`` 2177 This checks whether the MX record appears to refer to an IP address. The 2178 default is to ``warn``. Other possible values are ``fail`` and 2179 ``ignore``. 2180 2181``check-wildcard`` 2182 This option is used to check for non-terminal wildcards. The use of 2183 non-terminal wildcards is almost always as a result of a lack of 2184 understanding of the wildcard matching algorithm (:rfc:`1034`). This option 2185 affects primary zones. The default (``yes``) is to check for 2186 non-terminal wildcards and issue a warning. 2187 2188``check-integrity`` 2189 This performs post-load zone integrity checks on primary zones. It checks 2190 that MX and SRV records refer to address (A or AAAA) records and that 2191 glue address records exist for delegated zones. For MX and SRV 2192 records, only in-zone hostnames are checked (for out-of-zone hostnames, 2193 use ``named-checkzone``). For NS records, only names below top-of-zone 2194 are checked (for out-of-zone names and glue consistency checks, use 2195 ``named-checkzone``). The default is ``yes``. 2196 2197 The use of the SPF record to publish Sender Policy Framework is 2198 deprecated, as the migration from using TXT records to SPF records was 2199 abandoned. Enabling this option also checks that a TXT Sender Policy 2200 Framework record exists (starts with "v=spf1") if there is an SPF 2201 record. Warnings are emitted if the TXT record does not exist; they can 2202 be suppressed with ``check-spf``. 2203 2204``check-mx-cname`` 2205 If ``check-integrity`` is set, then fail, warn, or ignore MX records 2206 that refer to CNAMES. The default is to ``warn``. 2207 2208``check-srv-cname`` 2209 If ``check-integrity`` is set, then fail, warn, or ignore SRV records 2210 that refer to CNAMES. The default is to ``warn``. 2211 2212``check-sibling`` 2213 When performing integrity checks, also check that sibling glue 2214 exists. The default is ``yes``. 2215 2216``check-spf`` 2217 If ``check-integrity`` is set, check that there is a TXT Sender 2218 Policy Framework record present (starts with "v=spf1") if there is an 2219 SPF record present. The default is ``warn``. 2220 2221``zero-no-soa-ttl`` 2222 If ``yes``, when returning authoritative negative responses to SOA queries, set 2223 the TTL of the SOA record returned in the authority section to zero. 2224 The default is ``yes``. 2225 2226``zero-no-soa-ttl-cache`` 2227 If ``yes``, when caching a negative response to an SOA query set the TTL to zero. 2228 The default is ``no``. 2229 2230``update-check-ksk`` 2231 When set to the default value of ``yes``, check the KSK bit in each 2232 key to determine how the key should be used when generating RRSIGs 2233 for a secure zone. 2234 2235 Ordinarily, zone-signing keys (that is, keys without the KSK bit set) 2236 are used to sign the entire zone, while key-signing keys (keys with 2237 the KSK bit set) are only used to sign the DNSKEY RRset at the zone 2238 apex. However, if this option is set to ``no``, then the KSK bit is 2239 ignored; KSKs are treated as if they were ZSKs and are used to sign 2240 the entire zone. This is similar to the ``dnssec-signzone -z`` 2241 command-line option. 2242 2243 When this option is set to ``yes``, there must be at least two active 2244 keys for every algorithm represented in the DNSKEY RRset: at least 2245 one KSK and one ZSK per algorithm. If there is any algorithm for 2246 which this requirement is not met, this option is ignored for 2247 that algorithm. 2248 2249``dnssec-dnskey-kskonly`` 2250 When this option and ``update-check-ksk`` are both set to ``yes``, 2251 only key-signing keys (that is, keys with the KSK bit set) are 2252 used to sign the DNSKEY, CDNSKEY, and CDS RRsets at the zone apex. 2253 Zone-signing keys (keys without the KSK bit set) are used to sign 2254 the remainder of the zone, but not the DNSKEY RRset. This is similar 2255 to the ``dnssec-signzone -x`` command-line option. 2256 2257 The default is ``no``. If ``update-check-ksk`` is set to ``no``, this 2258 option is ignored. 2259 2260``try-tcp-refresh`` 2261 If ``yes``, try to refresh the zone using TCP if UDP queries fail. The default is 2262 ``yes``. 2263 2264``dnssec-secure-to-insecure`` 2265 This allows a dynamic zone to transition from secure to insecure (i.e., 2266 signed to unsigned) by deleting all of the DNSKEY records. The 2267 default is ``no``. If set to ``yes``, and if the DNSKEY RRset at the 2268 zone apex is deleted, all RRSIG and NSEC records are removed from 2269 the zone as well. 2270 2271 If the zone uses NSEC3, it is also necessary to delete the 2272 NSEC3PARAM RRset from the zone apex; this causes the removal of 2273 all corresponding NSEC3 records. (It is expected that this 2274 requirement will be eliminated in a future release.) 2275 2276 Note that if a zone has been configured with ``auto-dnssec maintain`` 2277 and the private keys remain accessible in the key repository, 2278 the zone will be automatically signed again the next time ``named`` 2279 is started. 2280 2281``synth-from-dnssec`` 2282 This option synthesizes answers from cached NSEC, NSEC3, and other RRsets that have been 2283 proved to be correct using DNSSEC. The default is ``no``, but it will become 2284 ``yes`` again in future releases. 2285 2286 .. note:: DNSSEC validation must be enabled for this option to be effective. 2287 This initial implementation only covers synthesis of answers from 2288 NSEC records; synthesis from NSEC3 is planned for the future. This 2289 will also be controlled by ``synth-from-dnssec``. 2290 2291Forwarding 2292^^^^^^^^^^ 2293 2294The forwarding facility can be used to create a large site-wide cache on 2295a few servers, reducing traffic over links to external name servers. It 2296can also be used to allow queries by servers that do not have direct 2297access to the Internet, but wish to look up exterior names anyway. 2298Forwarding occurs only on those queries for which the server is not 2299authoritative and does not have the answer in its cache. 2300 2301``forward`` 2302 This option is only meaningful if the forwarders list is not empty. A 2303 value of ``first`` is the default and causes the server to query the 2304 forwarders first; if that does not answer the question, the 2305 server then looks for the answer itself. If ``only`` is 2306 specified, the server only queries the forwarders. 2307 2308``forwarders`` 2309 This specifies a list of IP addresses to which queries are forwarded. The 2310 default is the empty list (no forwarding). Each address in the list can be 2311 associated with an optional port number and/or DSCP value, and a default port 2312 number and DSCP value can be set for the entire list. 2313 2314Forwarding can also be configured on a per-domain basis, allowing for 2315the global forwarding options to be overridden in a variety of ways. 2316Particular domains can be set to use different forwarders, or have a 2317different ``forward only/first`` behavior, or not forward at all; see 2318:ref:`zone_statement_grammar`. 2319 2320.. _dual_stack: 2321 2322Dual-stack Servers 2323^^^^^^^^^^^^^^^^^^ 2324 2325Dual-stack servers are used as servers of last resort, to work around 2326problems in reachability due to the lack of support for either IPv4 or IPv6 2327on the host machine. 2328 2329``dual-stack-servers`` 2330 This specifies host names or addresses of machines with access to both 2331 IPv4 and IPv6 transports. If a hostname is used, the server must be 2332 able to resolve the name using only the transport it has. If the 2333 machine is dual-stacked, the ``dual-stack-servers`` parameter has no 2334 effect unless access to a transport has been disabled on the command 2335 line (e.g., ``named -4``). 2336 2337.. _access_control: 2338 2339Access Control 2340^^^^^^^^^^^^^^ 2341 2342Access to the server can be restricted based on the IP address of the 2343requesting system. See :ref:`address_match_lists` 2344for details on how to specify IP address lists. 2345 2346``allow-notify`` 2347 This ACL specifies which hosts may send NOTIFY messages to inform 2348 this server of changes to zones for which it is acting as a secondary 2349 server. This is only applicable for secondary zones (i.e., type 2350 ``secondary`` or ``slave``). 2351 2352 If this option is set in ``view`` or ``options``, it is globally 2353 applied to all secondary zones. If set in the ``zone`` statement, the 2354 global value is overridden. 2355 2356 If not specified, the default is to process NOTIFY messages only from 2357 the configured ``primaries`` for the zone. ``allow-notify`` can be used 2358 to expand the list of permitted hosts, not to reduce it. 2359 2360``allow-query`` 2361 This specifies which hosts are allowed to ask ordinary DNS questions. 2362 ``allow-query`` may also be specified in the ``zone`` statement, in 2363 which case it overrides the ``options allow-query`` statement. If not 2364 specified, the default is to allow queries from all hosts. 2365 2366 .. note:: ``allow-query-cache`` is used to specify access to the cache. 2367 2368``allow-query-on`` 2369 This specifies which local addresses can accept ordinary DNS questions. 2370 This makes it possible, for instance, to allow queries on 2371 internal-facing interfaces but disallow them on external-facing ones, 2372 without necessarily knowing the internal network's addresses. 2373 2374 Note that ``allow-query-on`` is only checked for queries that are 2375 permitted by ``allow-query``. A query must be allowed by both ACLs, 2376 or it is refused. 2377 2378 ``allow-query-on`` may also be specified in the ``zone`` statement, 2379 in which case it overrides the ``options allow-query-on`` statement. 2380 2381 If not specified, the default is to allow queries on all addresses. 2382 2383 .. note:: ``allow-query-cache`` is used to specify access to the cache. 2384 2385``allow-query-cache`` 2386 This specifies which hosts are allowed to get answers from the cache. If 2387 ``allow-recursion`` is not set, BIND checks to see if the following parameters 2388 are set, in order: ``allow-query-cache`` and ``allow-query`` (unless ``recursion no;`` is set). 2389 If neither of those parameters is set, the default (localnets; localhost;) is used. 2390 2391``allow-query-cache-on`` 2392 This specifies which local addresses can send answers from the cache. If 2393 ``allow-query-cache-on`` is not set, then ``allow-recursion-on`` is 2394 used if set. Otherwise, the default is to allow cache responses to be 2395 sent from any address. Note: both ``allow-query-cache`` and 2396 ``allow-query-cache-on`` must be satisfied before a cache response 2397 can be sent; a client that is blocked by one cannot be allowed by the 2398 other. 2399 2400``allow-recursion`` 2401 This specifies which hosts are allowed to make recursive queries through 2402 this server. BIND checks to see if the following parameters are set, in 2403 order: ``allow-query-cache`` and ``allow-query``. If neither of those parameters 2404 is set, the default (localnets; localhost;) is used. 2405 2406``allow-recursion-on`` 2407 This specifies which local addresses can accept recursive queries. If 2408 ``allow-recursion-on`` is not set, then ``allow-query-cache-on`` is 2409 used if set; otherwise, the default is to allow recursive queries on 2410 all addresses. Any client permitted to send recursive queries can 2411 send them to any address on which ``named`` is listening. Note: both 2412 ``allow-recursion`` and ``allow-recursion-on`` must be satisfied 2413 before recursion is allowed; a client that is blocked by one cannot 2414 be allowed by the other. 2415 2416``allow-update`` 2417 When set in the ``zone`` statement for a primary zone, this specifies which 2418 hosts are allowed to submit Dynamic DNS updates to that zone. The 2419 default is to deny updates from all hosts. 2420 2421 Note that allowing updates based on the requestor's IP address is 2422 insecure; see :ref:`dynamic_update_security` for details. 2423 2424 In general, this option should only be set at the ``zone`` level. 2425 While a default value can be set at the ``options`` or ``view`` level 2426 and inherited by zones, this could lead to some zones unintentionally 2427 allowing updates. 2428 2429 Updates are written to the zone's filename that is set in ``file``. 2430 2431``allow-update-forwarding`` 2432 When set in the ``zone`` statement for a secondary zone, this specifies which 2433 hosts are allowed to submit Dynamic DNS updates and have them be 2434 forwarded to the primary. The default is ``{ none; }``, which means 2435 that no update forwarding is performed. 2436 2437 To enable update forwarding, specify 2438 ``allow-update-forwarding { any; };`` in the ``zone`` statement. 2439 Specifying values other than ``{ none; }`` or ``{ any; }`` is usually 2440 counterproductive; the responsibility for update access control 2441 should rest with the primary server, not the secondary. 2442 2443 Note that enabling the update forwarding feature on a secondary server 2444 may expose primary servers to attacks if they rely on insecure 2445 IP-address-based access control; see :ref:`dynamic_update_security` for more details. 2446 2447 In general this option should only be set at the ``zone`` level. 2448 While a default value can be set at the ``options`` or ``view`` level 2449 and inherited by zones, this can lead to some zones unintentionally 2450 forwarding updates. 2451 2452.. _allow-transfer-access: 2453 2454``allow-transfer`` 2455 This specifies which hosts are allowed to receive zone transfers from the 2456 server. ``allow-transfer`` may also be specified in the ``zone`` 2457 statement, in which case it overrides the ``allow-transfer`` 2458 statement set in ``options`` or ``view``. If not specified, the 2459 default is to allow transfers to all hosts. 2460 2461``blackhole`` 2462 This specifies a list of addresses which the server does not accept queries 2463 from or use to resolve a query. Queries from these addresses are not 2464 responded to. The default is ``none``. 2465 2466``keep-response-order`` 2467 This specifies a list of addresses to which the server sends responses 2468 to TCP queries, in the same order in which they were received. This 2469 disables the processing of TCP queries in parallel. The default is 2470 ``none``. 2471 2472``no-case-compress`` 2473 This specifies a list of addresses which require responses to use 2474 case-insensitive compression. This ACL can be used when ``named`` 2475 needs to work with clients that do not comply with the requirement in 2476 :rfc:`1034` to use case-insensitive name comparisons when checking for 2477 matching domain names. 2478 2479 If left undefined, the ACL defaults to ``none``: case-insensitive 2480 compression is used for all clients. If the ACL is defined and 2481 matches a client, case is ignored when compressing domain 2482 names in DNS responses sent to that client. 2483 2484 This can result in slightly smaller responses; if a response contains 2485 the names "example.com" and "example.COM", case-insensitive 2486 compression treats the second one as a duplicate. It also 2487 ensures that the case of the query name exactly matches the case of 2488 the owner names of returned records, rather than matches the case of 2489 the records entered in the zone file. This allows responses to 2490 exactly match the query, which is required by some clients due to 2491 incorrect use of case-sensitive comparisons. 2492 2493 Case-insensitive compression is *always* used in AXFR and IXFR 2494 responses, regardless of whether the client matches this ACL. 2495 2496 There are circumstances in which ``named`` does not preserve the case 2497 of owner names of records: if a zone file defines records of 2498 different types with the same name, but the capitalization of the 2499 name is different (e.g., "www.example.com/A" and 2500 "WWW.EXAMPLE.COM/AAAA"), then all responses for that name use 2501 the *first* version of the name that was used in the zone file. This 2502 limitation may be addressed in a future release. However, domain 2503 names specified in the rdata of resource records (i.e., records of 2504 type NS, MX, CNAME, etc.) always have their case preserved unless 2505 the client matches this ACL. 2506 2507``resolver-query-timeout`` 2508 This is the amount of time in milliseconds that the resolver spends 2509 attempting to resolve a recursive query before failing. The default 2510 and minimum is ``10000`` and the maximum is ``30000``. Setting it to 2511 ``0`` results in the default being used. 2512 2513 This value was originally specified in seconds. Values less than or 2514 equal to 300 are treated as seconds and converted to 2515 milliseconds before applying the above limits. 2516 2517Interfaces 2518^^^^^^^^^^ 2519 2520The interfaces and ports that the server answers queries from may be 2521specified using the ``listen-on`` option. ``listen-on`` takes an 2522optional port and an ``address_match_list`` of IPv4 addresses. (IPv6 2523addresses are ignored, with a logged warning.) The server listens on 2524all interfaces allowed by the address match list. If a port is not 2525specified, port 53 is used. 2526 2527Multiple ``listen-on`` statements are allowed. For example: 2528 2529:: 2530 2531 listen-on { 5.6.7.8; }; 2532 listen-on port 1234 { !1.2.3.4; 1.2/16; }; 2533 2534enables the name server on port 53 for the IP address 5.6.7.8, and 2535on port 1234 of an address on the machine in net 1.2 that is not 25361.2.3.4. 2537 2538If no ``listen-on`` is specified, the server listens on port 53 on 2539all IPv4 interfaces. 2540 2541The ``listen-on-v6`` option is used to specify the interfaces and the 2542ports on which the server listens for incoming queries sent using 2543IPv6. If not specified, the server listens on port 53 on all IPv6 2544interfaces. 2545 2546Multiple ``listen-on-v6`` options can be used. For example: 2547 2548:: 2549 2550 listen-on-v6 { any; }; 2551 listen-on-v6 port 1234 { !2001:db8::/32; any; }; 2552 2553enables the name server on port 53 for any IPv6 addresses (with a 2554single wildcard socket), and on port 1234 of IPv6 addresses that are not 2555in the prefix 2001:db8::/32 (with separate sockets for each matched 2556address). 2557 2558To instruct the server not to listen on any IPv6 address, use: 2559 2560:: 2561 2562 listen-on-v6 { none; }; 2563 2564.. _query_address: 2565 2566Query Address 2567^^^^^^^^^^^^^ 2568 2569If the server does not know the answer to a question, it queries other 2570name servers. ``query-source`` specifies the address and port used for 2571such queries. For queries sent over IPv6, there is a separate 2572``query-source-v6`` option. If ``address`` is ``*`` (asterisk) or is 2573omitted, a wildcard IP address (``INADDR_ANY``) is used. 2574 2575If ``port`` is ``*`` or is omitted, a random port number from a 2576pre-configured range is picked up and used for each query. The 2577port range(s) is specified in the ``use-v4-udp-ports`` (for IPv4) 2578and ``use-v6-udp-ports`` (for IPv6) options, excluding the ranges 2579specified in the ``avoid-v4-udp-ports`` and ``avoid-v6-udp-ports`` 2580options, respectively. 2581 2582The defaults of the ``query-source`` and ``query-source-v6`` options 2583are: 2584 2585:: 2586 2587 query-source address * port *; 2588 query-source-v6 address * port *; 2589 2590If ``use-v4-udp-ports`` or ``use-v6-udp-ports`` is unspecified, 2591``named`` checks whether the operating system provides a programming 2592interface to retrieve the system's default range for ephemeral ports. If 2593such an interface is available, ``named`` uses the corresponding 2594system default range; otherwise, it uses its own defaults: 2595 2596:: 2597 2598 use-v4-udp-ports { range 1024 65535; }; 2599 use-v6-udp-ports { range 1024 65535; }; 2600 2601.. note:: Make sure the ranges are sufficiently large for security. A 2602 desirable size depends on several parameters, but we generally recommend 2603 it contain at least 16384 ports (14 bits of entropy). Note also that the 2604 system's default range when used may be too small for this purpose, and 2605 that the range may even be changed while ``named`` is running; the new 2606 range is automatically applied when ``named`` is reloaded. Explicit 2607 configuration of ``use-v4-udp-ports`` and ``use-v6-udp-ports`` is encouraged, 2608 so that the ranges are sufficiently large and are reasonably 2609 independent from the ranges used by other applications. 2610 2611.. note:: The operational configuration where ``named`` runs may prohibit 2612 the use of some ports. For example, Unix systems do not allow 2613 ``named``, if run without root privilege, to use ports less than 1024. 2614 If such ports are included in the specified (or detected) set of query 2615 ports, the corresponding query attempts will fail, resulting in 2616 resolution failures or delay. It is therefore important to configure the 2617 set of ports that can be safely used in the expected operational 2618 environment. 2619 2620The defaults of the ``avoid-v4-udp-ports`` and ``avoid-v6-udp-ports`` 2621options are: 2622 2623:: 2624 2625 avoid-v4-udp-ports {}; 2626 avoid-v6-udp-ports {}; 2627 2628.. note:: BIND 9.5.0 introduced the ``use-queryport-pool`` option to support 2629 a pool of such random ports, but this option is now obsolete because 2630 reusing the same ports in the pool may not be sufficiently secure. For 2631 the same reason, it is generally strongly discouraged to specify a 2632 particular port for the ``query-source`` or ``query-source-v6`` options; 2633 it implicitly disables the use of randomized port numbers. 2634 2635``use-queryport-pool`` 2636 This option is obsolete. 2637 2638``queryport-pool-ports`` 2639 This option is obsolete. 2640 2641``queryport-pool-updateinterval`` 2642 This option is obsolete. 2643 2644.. note:: The address specified in the ``query-source`` option is used for both 2645 UDP and TCP queries, but the port applies only to UDP queries. TCP 2646 queries always use a random unprivileged port. 2647 2648.. warning:: Specifying a single port is discouraged, as it removes a layer of 2649 protection against spoofing errors. 2650 2651.. warning:: The configured ``port`` must not be same as the listening port. 2652 2653.. note:: See also ``transfer-source``, ``notify-source`` and ``parental-source``. 2654 2655.. _zone_transfers: 2656 2657Zone Transfers 2658^^^^^^^^^^^^^^ 2659 2660BIND has mechanisms in place to facilitate zone transfers and set limits 2661on the amount of load that transfers place on the system. The following 2662options apply to zone transfers. 2663 2664``also-notify`` 2665 This option defines a global list of IP addresses of name servers that are also 2666 sent NOTIFY messages whenever a fresh copy of the zone is loaded, in 2667 addition to the servers listed in the zone's NS records. This helps 2668 to ensure that copies of the zones quickly converge on stealth 2669 servers. Optionally, a port may be specified with each 2670 ``also-notify`` address to send the notify messages to a port other 2671 than the default of 53. An optional TSIG key can also be specified 2672 with each address to cause the notify messages to be signed; this can 2673 be useful when sending notifies to multiple views. In place of 2674 explicit addresses, one or more named ``primaries`` lists can be used. 2675 2676 If an ``also-notify`` list is given in a ``zone`` statement, it 2677 overrides the ``options also-notify`` statement. When a 2678 ``zone notify`` statement is set to ``no``, the IP addresses in the 2679 global ``also-notify`` list are not sent NOTIFY messages for that 2680 zone. The default is the empty list (no global notification list). 2681 2682``max-transfer-time-in`` 2683 Inbound zone transfers running longer than this many minutes are 2684 terminated. The default is 120 minutes (2 hours). The maximum value 2685 is 28 days (40320 minutes). 2686 2687``max-transfer-idle-in`` 2688 Inbound zone transfers making no progress in this many minutes are 2689 terminated. The default is 60 minutes (1 hour). The maximum value 2690 is 28 days (40320 minutes). 2691 2692``max-transfer-time-out`` 2693 Outbound zone transfers running longer than this many minutes are 2694 terminated. The default is 120 minutes (2 hours). The maximum value 2695 is 28 days (40320 minutes). 2696 2697``max-transfer-idle-out`` 2698 Outbound zone transfers making no progress in this many minutes are 2699 terminated. The default is 60 minutes (1 hour). The maximum value 2700 is 28 days (40320 minutes). 2701 2702``notify-rate`` 2703 This specifies the rate at which NOTIFY requests are sent during normal zone 2704 maintenance operations. (NOTIFY requests due to initial zone loading 2705 are subject to a separate rate limit; see below.) The default is 20 2706 per second. The lowest possible rate is one per second; when set to 2707 zero, it is silently raised to one. 2708 2709``startup-notify-rate`` 2710 This is the rate at which NOTIFY requests are sent when the name server 2711 is first starting up, or when zones have been newly added to the 2712 name server. The default is 20 per second. The lowest possible rate is 2713 one per second; when set to zero, it is silently raised to one. 2714 2715``serial-query-rate`` 2716 Secondary servers periodically query primary servers to find out if 2717 zone serial numbers have changed. Each such query uses a minute 2718 amount of the secondary server's network bandwidth. To limit the amount 2719 of bandwidth used, BIND 9 limits the rate at which queries are sent. 2720 The value of the ``serial-query-rate`` option, an integer, is the 2721 maximum number of queries sent per second. The default is 20 per 2722 second. The lowest possible rate is one per second; when set to zero, 2723 it is silently raised to one. 2724 2725``transfer-format`` 2726 Zone transfers can be sent using two different formats, 2727 ``one-answer`` and ``many-answers``. The ``transfer-format`` option 2728 is used on the primary server to determine which format it sends. 2729 ``one-answer`` uses one DNS message per resource record transferred. 2730 ``many-answers`` packs as many resource records as possible into one 2731 message. ``many-answers`` is more efficient; the default is ``many-answers``. 2732 ``transfer-format`` may be overridden on a per-server basis by using 2733 the ``server`` statement. 2734 2735``transfer-message-size`` 2736 This is an upper bound on the uncompressed size of DNS messages used 2737 in zone transfers over TCP. If a message grows larger than this size, 2738 additional messages are used to complete the zone transfer. 2739 (Note, however, that this is a hint, not a hard limit; if a message 2740 contains a single resource record whose RDATA does not fit within the 2741 size limit, a larger message will be permitted so the record can be 2742 transferred.) 2743 2744 Valid values are between 512 and 65535 octets; any values outside 2745 that range are adjusted to the nearest value within it. The 2746 default is ``20480``, which was selected to improve message 2747 compression; most DNS messages of this size will compress to less 2748 than 16536 bytes. Larger messages cannot be compressed as 2749 effectively, because 16536 is the largest permissible compression 2750 offset pointer in a DNS message. 2751 2752 This option is mainly intended for server testing; there is rarely 2753 any benefit in setting a value other than the default. 2754 2755``transfers-in`` 2756 This is the maximum number of inbound zone transfers that can run 2757 concurrently. The default value is ``10``. Increasing 2758 ``transfers-in`` may speed up the convergence of secondary zones, but it 2759 also may increase the load on the local system. 2760 2761``transfers-out`` 2762 This is the maximum number of outbound zone transfers that can run 2763 concurrently. Zone transfer requests in excess of the limit are 2764 refused. The default value is ``10``. 2765 2766``transfers-per-ns`` 2767 This is the maximum number of inbound zone transfers that can concurrently 2768 transfer from a given remote name server. The default value is 2769 ``2``. Increasing ``transfers-per-ns`` may speed up the convergence 2770 of secondary zones, but it also may increase the load on the remote name 2771 server. ``transfers-per-ns`` may be overridden on a per-server basis 2772 by using the ``transfers`` phrase of the ``server`` statement. 2773 2774``transfer-source`` 2775 ``transfer-source`` determines which local address is bound to 2776 IPv4 TCP connections used to fetch zones transferred inbound by the 2777 server. It also determines the source IPv4 address, and optionally 2778 the UDP port, used for the refresh queries and forwarded dynamic 2779 updates. If not set, it defaults to a system-controlled value which 2780 is usually the address of the interface "closest to" the remote 2781 end. This address must appear in the remote end's ``allow-transfer`` 2782 option for the zone being transferred, if one is specified. This 2783 statement sets the ``transfer-source`` for all zones, but can be 2784 overridden on a per-view or per-zone basis by including a 2785 ``transfer-source`` statement within the ``view`` or ``zone`` block 2786 in the configuration file. 2787 2788 .. warning:: Specifying a single port is discouraged, as it removes a layer of 2789 protection against spoofing errors. 2790 2791 .. warning:: The configured ``port`` must not be same as the listening port. 2792 2793``transfer-source-v6`` 2794 This option is the same as ``transfer-source``, except zone transfers are performed 2795 using IPv6. 2796 2797``alt-transfer-source`` 2798 This indicates an alternate transfer source if the one listed in ``transfer-source`` 2799 fails and ``use-alt-transfer-source`` is set. 2800 2801 .. note:: To avoid using the alternate transfer source, 2802 set ``use-alt-transfer-source`` appropriately and 2803 do not depend upon getting an answer back to the first refresh 2804 query. 2805 2806``alt-transfer-source-v6`` 2807 This indicates an alternate transfer source if the one listed in 2808 ``transfer-source-v6`` fails and ``use-alt-transfer-source`` is set. 2809 2810``use-alt-transfer-source`` 2811 This indicates whether the alternate transfer sources should be used. If views are specified, 2812 this defaults to ``no``; otherwise, it defaults to ``yes``. 2813 2814``notify-source`` 2815 ``notify-source`` determines which local source address, and 2816 optionally UDP port, is used to send NOTIFY messages. This 2817 address must appear in the secondary server's ``primaries`` zone clause or 2818 in an ``allow-notify`` clause. This statement sets the 2819 ``notify-source`` for all zones, but can be overridden on a per-zone 2820 or per-view basis by including a ``notify-source`` statement within 2821 the ``zone`` or ``view`` block in the configuration file. 2822 2823 .. warning:: Specifying a single port is discouraged, as it removes a layer of 2824 protection against spoofing errors. 2825 2826 .. warning:: The configured ``port`` must not be same as the listening port. 2827 2828``notify-source-v6`` 2829 This option acts like ``notify-source``, but applies to notify messages sent to IPv6 2830 addresses. 2831 2832.. _port_lists: 2833 2834UDP Port Lists 2835^^^^^^^^^^^^^^ 2836 2837``use-v4-udp-ports``, ``avoid-v4-udp-ports``, ``use-v6-udp-ports``, and 2838``avoid-v6-udp-ports`` specify a list of IPv4 and IPv6 UDP ports that 2839are or are not used as source ports for UDP messages. See 2840:ref:`query_address` about how the available ports are 2841determined. For example, with the following configuration: 2842 2843:: 2844 2845 use-v6-udp-ports { range 32768 65535; }; 2846 avoid-v6-udp-ports { 40000; range 50000 60000; }; 2847 2848UDP ports of IPv6 messages sent from ``named`` are in one of the 2849following ranges: 32768 to 39999, 40001 to 49999, and 60001 to 65535. 2850 2851``avoid-v4-udp-ports`` and ``avoid-v6-udp-ports`` can be used to prevent 2852``named`` from choosing as its random source port a port that is blocked 2853by a firewall or a port that is used by other applications; if a 2854query went out with a source port blocked by a firewall, the answer 2855would not pass through the firewall and the name server would have to query 2856again. Note: the desired range can also be represented only with 2857``use-v4-udp-ports`` and ``use-v6-udp-ports``, and the ``avoid-`` 2858options are redundant in that sense; they are provided for backward 2859compatibility and to possibly simplify the port specification. 2860 2861.. _resource_limits: 2862 2863Operating System Resource Limits 2864^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2865 2866The server's usage of many system resources can be limited. Scaled 2867values are allowed when specifying resource limits. For example, ``1G`` 2868can be used instead of ``1073741824`` to specify a limit of one 2869gigabyte. ``unlimited`` requests unlimited use, or the maximum available 2870amount. ``default`` uses the limit that was in force when the server was 2871started. See the description of ``size_spec`` in :ref:`configuration_file_elements`. 2872 2873The following options set operating system resource limits for the name 2874server process. Some operating systems do not support some or any of the 2875limits; on such systems, a warning is issued if an unsupported 2876limit is used. 2877 2878``coresize`` 2879 This sets the maximum size of a core dump. The default is ``default``. 2880 2881``datasize`` 2882 This sets the maximum amount of data memory the server may use. The default is 2883 ``default``. This is a hard limit on server memory usage; if the 2884 server attempts to allocate memory in excess of this limit, the 2885 allocation will fail, which may in turn leave the server unable to 2886 perform DNS service. Therefore, this option is rarely useful as a way 2887 to limit the amount of memory used by the server, but it can be 2888 used to raise an operating system data size limit that is too small 2889 by default. To limit the amount of memory used by the 2890 server, use the ``max-cache-size`` and ``recursive-clients`` options 2891 instead. 2892 2893``files`` 2894 This sets the maximum number of files the server may have open concurrently. 2895 The default is ``unlimited``. 2896 2897``stacksize`` 2898 This sets the maximum amount of stack memory the server may use. The default is 2899 ``default``. 2900 2901.. _server_resource_limits: 2902 2903Server Resource Limits 2904^^^^^^^^^^^^^^^^^^^^^^ 2905 2906The following options set limits on the server's resource consumption 2907that are enforced internally by the server rather than by the operating 2908system. 2909 2910``max-journal-size`` 2911 This sets a maximum size for each journal file (see :ref:`journal`), 2912 expressed in bytes or, if followed by an 2913 optional unit suffix ('k', 'm', or 'g'), in kilobytes, megabytes, or 2914 gigabytes. When the journal file approaches the specified size, some 2915 of the oldest transactions in the journal are automatically 2916 removed. The largest permitted value is 2 gigabytes. Very small 2917 values are rounded up to 4096 bytes. It is possible to specify ``unlimited``, 2918 which also means 2 gigabytes. If the limit is set to ``default`` or 2919 left unset, the journal is allowed to grow up to twice as large 2920 as the zone. (There is little benefit in storing larger journals.) 2921 2922 This option may also be set on a per-zone basis. 2923 2924``max-records`` 2925 This sets the maximum number of records permitted in a zone. The default is 2926 zero, which means the maximum is unlimited. 2927 2928``recursive-clients`` 2929 This sets the maximum number (a "hard quota") of simultaneous recursive lookups 2930 the server performs on behalf of clients. The default is 2931 ``1000``. Because each recursing client uses a fair bit of memory (on 2932 the order of 20 kilobytes), the value of the ``recursive-clients`` 2933 option may have to be decreased on hosts with limited memory. 2934 2935 ``recursive-clients`` defines a "hard quota" limit for pending 2936 recursive clients; when more clients than this are pending, new 2937 incoming requests are not accepted, and for each incoming request 2938 a previous pending request is dropped. 2939 2940 A "soft quota" is also set. When this lower quota is exceeded, 2941 incoming requests are accepted, but for each one, a pending request 2942 is dropped. If ``recursive-clients`` is greater than 1000, the 2943 soft quota is set to ``recursive-clients`` minus 100; otherwise it is 2944 set to 90% of ``recursive-clients``. 2945 2946``tcp-clients`` 2947 This is the maximum number of simultaneous client TCP connections that the 2948 server accepts. The default is ``150``. 2949 2950.. _clients-per-query: 2951 2952``clients-per-query``; ``max-clients-per-query`` 2953 These set the initial value (minimum) and maximum number of recursive 2954 simultaneous clients for any given query (<qname,qtype,qclass>) that 2955 the server accepts before dropping additional clients. ``named`` 2956 attempts to self-tune this value and changes are logged. The 2957 default values are 10 and 100. 2958 2959 This value should reflect how many queries come in for a given name 2960 in the time it takes to resolve that name. If the number of queries 2961 exceeds this value, ``named`` assumes that it is dealing with a 2962 non-responsive zone and drops additional queries. If it gets a 2963 response after dropping queries, it raises the estimate. The 2964 estimate is then lowered in 20 minutes if it has remained 2965 unchanged. 2966 2967 If ``clients-per-query`` is set to zero, there is no limit on 2968 the number of clients per query and no queries are dropped. 2969 2970 If ``max-clients-per-query`` is set to zero, there is no upper 2971 bound other than that imposed by ``recursive-clients``. 2972 2973``fetches-per-zone`` 2974 This sets the maximum number of simultaneous iterative queries to any one 2975 domain that the server permits before blocking new queries for 2976 data in or beneath that zone. This value should reflect how many 2977 fetches would normally be sent to any one zone in the time it would 2978 take to resolve them. It should be smaller than 2979 ``recursive-clients``. 2980 2981 When many clients simultaneously query for the same name and type, 2982 the clients are all attached to the same fetch, up to the 2983 ``max-clients-per-query`` limit, and only one iterative query is 2984 sent. However, when clients are simultaneously querying for 2985 *different* names or types, multiple queries are sent and 2986 ``max-clients-per-query`` is not effective as a limit. 2987 2988 Optionally, this value may be followed by the keyword ``drop`` or 2989 ``fail``, indicating whether queries which exceed the fetch quota for 2990 a zone are dropped with no response, or answered with SERVFAIL. 2991 The default is ``drop``. 2992 2993 If ``fetches-per-zone`` is set to zero, there is no limit on the 2994 number of fetches per query and no queries are dropped. The 2995 default is zero. 2996 2997 The current list of active fetches can be dumped by running 2998 ``rndc recursing``. The list includes the number of active fetches 2999 for each domain and the number of queries that have been passed 3000 (allowed) or dropped (spilled) as a result of the ``fetches-per-zone`` 3001 limit. (Note: these counters are not cumulative over time; 3002 whenever the number of active fetches for a domain drops to zero, 3003 the counter for that domain is deleted, and the next time a fetch 3004 is sent to that domain, it is recreated with the counters set 3005 to zero.) 3006 3007``fetches-per-server`` 3008 This sets the maximum number of simultaneous iterative queries that the server 3009 allows to be sent to a single upstream name server before 3010 blocking additional queries. This value should reflect how many 3011 fetches would normally be sent to any one server in the time it would 3012 take to resolve them. It should be smaller than 3013 ``recursive-clients``. 3014 3015 Optionally, this value may be followed by the keyword ``drop`` or 3016 ``fail``, indicating whether queries are dropped with no 3017 response or answered with SERVFAIL, when all of the servers 3018 authoritative for a zone are found to have exceeded the per-server 3019 quota. The default is ``fail``. 3020 3021 If ``fetches-per-server`` is set to zero, there is no limit on 3022 the number of fetches per query and no queries are dropped. The 3023 default is zero. 3024 3025 The ``fetches-per-server`` quota is dynamically adjusted in response 3026 to detected congestion. As queries are sent to a server and either are 3027 answered or time out, an exponentially weighted moving average 3028 is calculated of the ratio of timeouts to responses. If the current 3029 average timeout ratio rises above a "high" threshold, then 3030 ``fetches-per-server`` is reduced for that server. If the timeout 3031 ratio drops below a "low" threshold, then ``fetches-per-server`` is 3032 increased. The ``fetch-quota-params`` options can be used to adjust 3033 the parameters for this calculation. 3034 3035``fetch-quota-params`` 3036 This sets the parameters to use for dynamic resizing of the 3037 ``fetches-per-server`` quota in response to detected congestion. 3038 3039 The first argument is an integer value indicating how frequently to 3040 recalculate the moving average of the ratio of timeouts to responses 3041 for each server. The default is 100, meaning that BIND recalculates the 3042 average ratio after every 100 queries have either been answered or 3043 timed out. 3044 3045 The remaining three arguments represent the "low" threshold 3046 (defaulting to a timeout ratio of 0.1), the "high" threshold 3047 (defaulting to a timeout ratio of 0.3), and the discount rate for the 3048 moving average (defaulting to 0.7). A higher discount rate causes 3049 recent events to weigh more heavily when calculating the moving 3050 average; a lower discount rate causes past events to weigh more 3051 heavily, smoothing out short-term blips in the timeout ratio. These 3052 arguments are all fixed-point numbers with precision of 1/100; at 3053 most two places after the decimal point are significant. 3054 3055``reserved-sockets`` 3056 This sets the number of file descriptors reserved for TCP, stdio, etc. This 3057 needs to be big enough to cover the number of interfaces ``named`` 3058 listens on plus ``tcp-clients``, as well as to provide room for 3059 outgoing TCP queries and incoming zone transfers. The default is 3060 ``512``. The minimum value is ``128`` and the maximum value is 3061 ``128`` fewer than maxsockets (-S). This option may be removed in the 3062 future. 3063 3064 This option has little effect on Windows. 3065 3066``max-cache-size`` 3067 This sets the maximum amount of memory to use for an individual cache 3068 database and its associated metadata, in bytes or percentage of total 3069 physical memory. By default, each view has its own separate cache, 3070 which means the total amount of memory required for cache data is the 3071 sum of the cache database sizes for all views (unless the 3072 :ref:`attach-cache <attach-cache>` option is used). 3073 3074 When the amount of data in a cache database reaches the configured 3075 limit, ``named`` starts purging non-expired records (following an 3076 LRU-based strategy). 3077 3078 The default size limit for each individual cache is: 3079 3080 - 90% of physical memory for views with ``recursion`` set to 3081 ``yes`` (the default), or 3082 3083 - 2 MB for views with ``recursion`` set to ``no``. 3084 3085 Any positive value smaller than 2 MB is ignored and reset to 2 MB. 3086 The keyword ``unlimited``, or the value ``0``, places no limit on the 3087 cache size; records are then purged from the cache only when they 3088 expire (according to their TTLs). 3089 3090 .. note:: 3091 3092 For configurations which define multiple views with separate 3093 caches and recursion enabled, it is recommended to set 3094 ``max-cache-size`` appropriately for each view, as using the 3095 default value of that option (90% of physical memory for each 3096 individual cache) may lead to memory exhaustion over time. 3097 3098 .. note:: 3099 3100 ``max-cache-size`` does not work reliably for the maximum 3101 amount of memory of 100 MB or lower. 3102 3103 Upon startup and reconfiguration, caches with a limited size 3104 preallocate a small amount of memory (less than 1% of 3105 ``max-cache-size`` for a given view). This preallocation serves as an 3106 optimization to eliminate extra latency introduced by resizing 3107 internal cache structures. 3108 3109 On systems where detection of the amount of physical memory is not 3110 supported, percentage-based values fall back to ``unlimited``. Note 3111 that the amount of physical memory available is only detected on 3112 startup, so ``named`` does not adjust the cache size limits if the 3113 amount of physical memory is changed at runtime. 3114 3115``tcp-listen-queue`` 3116 This sets the listen-queue depth. The default and minimum is 10. If the kernel 3117 supports the accept filter "dataready", this also controls how many 3118 TCP connections are queued in kernel space waiting for some 3119 data before being passed to accept. Non-zero values less than 10 are 3120 silently raised. A value of 0 may also be used; on most platforms 3121 this sets the listen-queue length to a system-defined default value. 3122 3123``tcp-initial-timeout`` 3124 This sets the amount of time (in units of 100 milliseconds) that the server waits on 3125 a new TCP connection for the first message from the client. The 3126 default is 300 (30 seconds), the minimum is 25 (2.5 seconds), and the 3127 maximum is 1200 (two minutes). Values above the maximum or below the 3128 minimum are adjusted with a logged warning. (Note: this value 3129 must be greater than the expected round-trip delay time; otherwise, no 3130 client will ever have enough time to submit a message.) This value 3131 can be updated at runtime by using ``rndc tcp-timeouts``. 3132 3133``tcp-idle-timeout`` 3134 This sets the amount of time (in units of 100 milliseconds) that the server waits on 3135 an idle TCP connection before closing it, when the client is not using 3136 the EDNS TCP keepalive option. The default is 300 (30 seconds), the 3137 maximum is 1200 (two minutes), and the minimum is 1 (one-tenth of a 3138 second). Values above the maximum or below the minimum are 3139 adjusted with a logged warning. See ``tcp-keepalive-timeout`` for 3140 clients using the EDNS TCP keepalive option. This value can be 3141 updated at runtime by using ``rndc tcp-timeouts``. 3142 3143``tcp-keepalive-timeout`` 3144 This sets the amount of time (in units of 100 milliseconds) that the server waits on 3145 an idle TCP connection before closing it, when the client is using the 3146 EDNS TCP keepalive option. The default is 300 (30 seconds), the 3147 maximum is 65535 (about 1.8 hours), and the minimum is 1 (one-tenth 3148 of a second). Values above the maximum or below the minimum are 3149 adjusted with a logged warning. This value may be greater than 3150 ``tcp-idle-timeout`` because clients using the EDNS TCP keepalive 3151 option are expected to use TCP connections for more than one message. 3152 This value can be updated at runtime by using ``rndc tcp-timeouts``. 3153 3154``tcp-advertised-timeout`` 3155 This sets the timeout value (in units of 100 milliseconds) that the server sends 3156 in responses containing the EDNS TCP keepalive option, which informs a 3157 client of the amount of time it may keep the session open. The 3158 default is 300 (30 seconds), the maximum is 65535 (about 1.8 hours), 3159 and the minimum is 0, which signals that the clients must close TCP 3160 connections immediately. Ordinarily this should be set to the same 3161 value as ``tcp-keepalive-timeout``. This value can be updated at 3162 runtime by using ``rndc tcp-timeouts``. 3163 3164``update-quota`` 3165 This is the maximum number of simultaneous DNS UPDATE messages that 3166 the server will accept for updating local authoritiative zones or 3167 forwarding to a primary server. The default is ``100``. 3168 3169.. _intervals: 3170 3171Periodic Task Intervals 3172^^^^^^^^^^^^^^^^^^^^^^^ 3173 3174``cleaning-interval`` 3175 This option is obsolete. 3176 3177``heartbeat-interval`` 3178 The server performs zone maintenance tasks for all zones marked 3179 as ``dialup`` whenever this interval expires. The default is 60 3180 minutes. Reasonable values are up to 1 day (1440 minutes). The 3181 maximum value is 28 days (40320 minutes). If set to 0, no zone 3182 maintenance for these zones occurs. 3183 3184``interface-interval`` 3185 The server scans the network interface list every ``interface-interval`` 3186 minutes. The default is 60 minutes; the maximum value is 28 days (40320 3187 minutes). If set to 0, interface scanning only occurs when the configuration 3188 file is loaded, or when ``automatic-interface-scan`` is enabled and supported 3189 by the operating system. After the scan, the server begins listening for 3190 queries on any newly discovered interfaces (provided they are allowed by the 3191 ``listen-on`` configuration), and stops listening on interfaces that have 3192 gone away. For convenience, TTL-style time-unit suffixes may be used to 3193 specify the value. It also accepts ISO 8601 duration formats. 3194 3195.. _the_sortlist_statement: 3196 3197The ``sortlist`` Statement 3198^^^^^^^^^^^^^^^^^^^^^^^^^^ 3199 3200The response to a DNS query may consist of multiple resource records 3201(RRs) forming a resource record set (RRset). The name server 3202normally returns the RRs within the RRset in an indeterminate order (but 3203see the ``rrset-order`` statement in :ref:`rrset_ordering`). The client resolver code should 3204rearrange the RRs as appropriate: that is, using any addresses on the 3205local net in preference to other addresses. However, not all resolvers 3206can do this or are correctly configured. When a client is using a local 3207server, the sorting can be performed in the server, based on the 3208client's address. This only requires configuring the name servers, not 3209all the clients. 3210 3211The ``sortlist`` statement (see below) takes an ``address_match_list`` and 3212interprets it in a special way. Each top-level statement in the ``sortlist`` 3213must itself be an explicit ``address_match_list`` with one or two elements. The 3214first element (which may be an IP address, an IP prefix, an ACL name, or a nested 3215``address_match_list``) of each top-level list is checked against the source 3216address of the query until a match is found. When the addresses in the first 3217element overlap, the first rule to match is selected. 3218 3219Once the source address of the query has been matched, if the top-level 3220statement contains only one element, the actual primitive element that 3221matched the source address is used to select the address in the response 3222to move to the beginning of the response. If the statement is a list of 3223two elements, then the second element is interpreted as a topology 3224preference list. Each top-level element is assigned a distance, and the 3225address in the response with the minimum distance is moved to the 3226beginning of the response. 3227 3228In the following example, any queries received from any of the addresses 3229of the host itself get responses preferring addresses on any of the 3230locally connected networks. Next most preferred are addresses on the 3231192.168.1/24 network, and after that either the 192.168.2/24 or 3232192.168.3/24 network, with no preference shown between these two 3233networks. Queries received from a host on the 192.168.1/24 network 3234prefer other addresses on that network to the 192.168.2/24 and 3235192.168.3/24 networks. Queries received from a host on the 192.168.4/24 3236or the 192.168.5/24 network only prefer other addresses on their 3237directly connected networks. 3238 3239:: 3240 3241 sortlist { 3242 // IF the local host 3243 // THEN first fit on the following nets 3244 { localhost; 3245 { localnets; 3246 192.168.1/24; 3247 { 192.168.2/24; 192.168.3/24; }; }; }; 3248 // IF on class C 192.168.1 THEN use .1, or .2 or .3 3249 { 192.168.1/24; 3250 { 192.168.1/24; 3251 { 192.168.2/24; 192.168.3/24; }; }; }; 3252 // IF on class C 192.168.2 THEN use .2, or .1 or .3 3253 { 192.168.2/24; 3254 { 192.168.2/24; 3255 { 192.168.1/24; 192.168.3/24; }; }; }; 3256 // IF on class C 192.168.3 THEN use .3, or .1 or .2 3257 { 192.168.3/24; 3258 { 192.168.3/24; 3259 { 192.168.1/24; 192.168.2/24; }; }; }; 3260 // IF .4 or .5 THEN prefer that net 3261 { { 192.168.4/24; 192.168.5/24; }; 3262 }; 3263 }; 3264 3265The following example illlustrates reasonable behavior for the local host 3266and hosts on directly connected networks. Responses sent to queries from the 3267local host favor any of the directly connected networks. Responses 3268sent to queries from any other hosts on a directly connected network 3269prefer addresses on that same network. Responses to other queries 3270are not sorted. 3271 3272:: 3273 3274 sortlist { 3275 { localhost; localnets; }; 3276 { localnets; }; 3277 }; 3278 3279.. _rrset_ordering: 3280 3281RRset Ordering 3282^^^^^^^^^^^^^^ 3283 3284.. note:: 3285 3286 While alternating the order of records in a DNS response between 3287 subsequent queries is a known load distribution technique, certain 3288 caveats apply (mostly stemming from caching) which usually make it a 3289 suboptimal choice for load balancing purposes when used on its own. 3290 3291The ``rrset-order`` statement permits configuration of the ordering of 3292the records in a multiple-record response. See also: 3293:ref:`the_sortlist_statement`. 3294 3295Each rule in an ``rrset-order`` statement is defined as follows: 3296 3297:: 3298 3299 [class <class_name>] [type <type_name>] [name "<domain_name>"] order <ordering> 3300 3301The default qualifiers for each rule are: 3302 3303 - If no ``class`` is specified, the default is ``ANY``. 3304 - If no ``type`` is specified, the default is ``ANY``. 3305 - If no ``name`` is specified, the default is ``*`` (asterisk). 3306 3307``<domain_name>`` only matches the name itself, not any of its 3308subdomains. To make a rule match all subdomains of a given name, a 3309wildcard name (``*.<domain_name>``) must be used. Note that 3310``*.<domain_name>`` does *not* match ``<domain_name>`` itself; to 3311specify RRset ordering for a name and all of its subdomains, two 3312separate rules must be defined: one for ``<domain_name>`` and one for 3313``*.<domain_name>``. 3314 3315The legal values for ``<ordering>`` are: 3316 3317``fixed`` 3318 Records are returned in the order they are defined in the zone file. 3319 3320.. note:: 3321 3322 The ``fixed`` option is only available if BIND is configured with 3323 ``--enable-fixed-rrset`` at compile time. 3324 3325``random`` 3326 Records are returned in a random order. 3327 3328``cyclic`` 3329 Records are returned in a cyclic round-robin order, rotating by one 3330 record per query. 3331 3332``none`` 3333 Records are returned in the order they were retrieved from the 3334 database. This order is indeterminate, but remains consistent as 3335 long as the database is not modified. 3336 3337The default RRset order used depends on whether any ``rrset-order`` 3338statements are present in the configuration file used by ``named``: 3339 3340 - If no ``rrset-order`` statement is present in the configuration 3341 file, the implicit default is to return all records in ``random`` 3342 order. 3343 3344 - If any ``rrset-order`` statements are present in the configuration 3345 file, but no ordering rule specified in these statements matches a 3346 given RRset, the default order for that RRset is ``none``. 3347 3348Note that if multiple ``rrset-order`` statements are present in the 3349configuration file (at both the ``options`` and ``view`` levels), they 3350are *not* combined; instead, the more-specific one (``view``) replaces 3351the less-specific one (``options``). 3352 3353If multiple rules within a single ``rrset-order`` statement match a 3354given RRset, the first matching rule is applied. 3355 3356Example: 3357 3358:: 3359 3360 rrset-order { 3361 type A name "foo.isc.org" order random; 3362 type AAAA name "foo.isc.org" order cyclic; 3363 name "bar.isc.org" order fixed; 3364 name "*.bar.isc.org" order random; 3365 name "*.baz.isc.org" order cyclic; 3366 }; 3367 3368With the above configuration, the following RRset ordering is used: 3369 3370=================== ======== =========== 3371QNAME QTYPE RRset Order 3372=================== ======== =========== 3373``foo.isc.org`` ``A`` ``random`` 3374``foo.isc.org`` ``AAAA`` ``cyclic`` 3375``foo.isc.org`` ``TXT`` ``none`` 3376``sub.foo.isc.org`` all ``none`` 3377``bar.isc.org`` all ``fixed`` 3378``sub.bar.isc.org`` all ``random`` 3379``baz.isc.org`` all ``none`` 3380``sub.baz.isc.org`` all ``cyclic`` 3381=================== ======== =========== 3382 3383.. _tuning: 3384 3385Tuning 3386^^^^^^ 3387 3388``lame-ttl`` 3389 This is always set to 0. More information is available in the 3390 `security advisory for CVE-2021-25219 3391 <https://kb.isc.org/docs/cve-2021-25219>`_. 3392 3393``servfail-ttl`` 3394 This sets the number of seconds to cache a SERVFAIL response due to DNSSEC 3395 validation failure or other general server failure. If set to ``0``, 3396 SERVFAIL caching is disabled. The SERVFAIL cache is not consulted if 3397 a query has the CD (Checking Disabled) bit set; this allows a query 3398 that failed due to DNSSEC validation to be retried without waiting 3399 for the SERVFAIL TTL to expire. 3400 3401 The maximum value is ``30`` seconds; any higher value is 3402 silently reduced. The default is ``1`` second. 3403 3404``min-ncache-ttl`` 3405 To reduce network traffic and increase performance, the server stores 3406 negative answers. ``min-ncache-ttl`` is used to set a minimum 3407 retention time for these answers in the server, in seconds. For 3408 convenience, TTL-style time-unit suffixes may be used to specify the 3409 value. It also accepts ISO 8601 duration formats. 3410 3411 The default ``min-ncache-ttl`` is ``0`` seconds. ``min-ncache-ttl`` cannot 3412 exceed 90 seconds and is truncated to 90 seconds if set to a greater 3413 value. 3414 3415``min-cache-ttl`` 3416 This sets the minimum time for which the server caches ordinary (positive) 3417 answers, in seconds. For convenience, TTL-style time-unit suffixes may be used 3418 to specify the value. It also accepts ISO 8601 duration formats. 3419 3420 The default ``min-cache-ttl`` is ``0`` seconds. ``min-cache-ttl`` cannot 3421 exceed 90 seconds and is truncated to 90 seconds if set to a greater 3422 value. 3423 3424``max-ncache-ttl`` 3425 To reduce network traffic and increase performance, the server stores 3426 negative answers. ``max-ncache-ttl`` is used to set a maximum retention time 3427 for these answers in the server, in seconds. For convenience, TTL-style 3428 time-unit suffixes may be used to specify the value. It also accepts ISO 8601 3429 duration formats. 3430 3431 The default ``max-ncache-ttl`` is 10800 seconds (3 hours). ``max-ncache-ttl`` 3432 cannot exceed 7 days and is silently truncated to 7 days if set to a 3433 greater value. 3434 3435``max-cache-ttl`` 3436 This sets the maximum time for which the server caches ordinary (positive) 3437 answers, in seconds. For convenience, TTL-style time-unit suffixes may be used 3438 to specify the value. It also accepts ISO 8601 duration formats. 3439 3440 The default ``max-cache-ttl`` is 604800 (one week). A value of zero may cause 3441 all queries to return SERVFAIL, because of lost caches of intermediate RRsets 3442 (such as NS and glue AAAA/A records) in the resolution process. 3443 3444``max-stale-ttl`` 3445 If retaining stale RRsets in cache is enabled, and returning of stale cached 3446 answers is also enabled, ``max-stale-ttl`` sets the maximum time for which 3447 the server retains records past their normal expiry to return them as stale 3448 records, when the servers for those records are not reachable. The default 3449 is 1 day. The minimum allowed is 1 second; a value of 0 is updated silently 3450 to 1 second. 3451 3452 For stale answers to be returned, the retaining of them in cache must be 3453 enabled via the configuration option ``stale-cache-enable``, and returning 3454 cached answers must be enabled, either in the configuration file using the 3455 ``stale-answer-enable`` option or by calling ``rndc serve-stale on``. 3456 3457 When ``stale-cache-enable`` is set to ``no``, setting the ``max-stale-ttl`` 3458 has no effect, the value of ``max-cache-ttl`` will be ``0`` in such case. 3459 3460``resolver-nonbackoff-tries`` 3461 This specifies how many retries occur before exponential backoff kicks in. The 3462 default is ``3``. 3463 3464``resolver-retry-interval`` 3465 This sets the base retry interval in milliseconds. The default is ``800``. 3466 3467``sig-validity-interval`` 3468 this specifies the upper bound of the number of days that RRSIGs 3469 generated by ``named`` are valid; the default is ``30`` days, 3470 with a maximum of 3660 days (10 years). The optional second value 3471 specifies the minimum bound on those RRSIGs and also determines 3472 how long before expiry ``named`` starts regenerating those RRSIGs. 3473 The default value for the lower bound is 1/4 of the upper bound; 3474 it is expressed in days if the upper bound is greater than 7, 3475 and hours if it is less than or equal to 7 days. 3476 3477 When new RRSIGs are generated, the length of time is randomly 3478 chosen between these two limits, to spread out the re-signing 3479 load. When RRSIGs are re-generated, the upper bound is used, with 3480 a small amount of jitter added. New RRSIGs are generated by a 3481 number of processes, including the processing of UPDATE requests 3482 (ref:`dynamic_update`), the addition and removal of records via 3483 in-line signing, and the initial signing of a zone. 3484 3485 The signature inception time is unconditionally set to one hour 3486 before the current time, to allow for a limited amount of clock skew. 3487 3488 The ``sig-validity-interval`` can be overridden for DNSKEY records by 3489 setting ``dnskey-sig-validity``. 3490 3491 The ``sig-validity-interval`` should be at least several multiples 3492 of the SOA expire interval, to allow for reasonable interaction 3493 between the various timer and expiry dates. 3494 3495``dnskey-sig-validity`` 3496 This specifies the number of days into the future when DNSSEC signatures 3497 that are automatically generated for DNSKEY RRsets as a result of 3498 dynamic updates (:ref:`dynamic_update`) will expire. 3499 If set to a non-zero value, this overrides the value set by 3500 ``sig-validity-interval``. The default is zero, meaning 3501 ``sig-validity-interval`` is used. The maximum value is 3660 days (10 3502 years), and higher values are rejected. 3503 3504``sig-signing-nodes`` 3505 This specifies the maximum number of nodes to be examined in each quantum, 3506 when signing a zone with a new DNSKEY. The default is ``100``. 3507 3508``sig-signing-signatures`` 3509 This specifies a threshold number of signatures that terminates 3510 processing a quantum, when signing a zone with a new DNSKEY. The 3511 default is ``10``. 3512 3513``sig-signing-type`` 3514 This specifies a private RDATA type to be used when generating signing-state 3515 records. The default is ``65534``. 3516 3517 This parameter may be removed in a future version, 3518 once there is a standard type. 3519 3520 Signing-state records are used internally by ``named`` to track 3521 the current state of a zone-signing process, i.e., whether it is 3522 still active or has been completed. The records can be inspected 3523 using the command ``rndc signing -list zone``. Once ``named`` has 3524 finished signing a zone with a particular key, the signing-state 3525 record associated with that key can be removed from the zone by 3526 running ``rndc signing -clear keyid/algorithm zone``. To clear all of 3527 the completed signing-state records for a zone, use 3528 ``rndc signing -clear all zone``. 3529 3530``min-refresh-time``; ``max-refresh-time``; ``min-retry-time``; ``max-retry-time`` 3531 These options control the server's behavior on refreshing a zone 3532 (querying for SOA changes) or retrying failed transfers. Usually the 3533 SOA values for the zone are used, up to a hard-coded maximum expiry 3534 of 24 weeks. However, these values are set by the primary, giving 3535 secondary server administrators little control over their contents. 3536 3537 These options allow the administrator to set a minimum and maximum 3538 refresh and retry time in seconds per-zone, per-view, or globally. 3539 These options are valid for secondary and stub zones, and clamp the SOA 3540 refresh and retry times to the specified values. 3541 3542 The following defaults apply: ``min-refresh-time`` 300 seconds, 3543 ``max-refresh-time`` 2419200 seconds (4 weeks), ``min-retry-time`` 3544 500 seconds, and ``max-retry-time`` 1209600 seconds (2 weeks). 3545 3546``edns-udp-size`` 3547 This sets the maximum advertised EDNS UDP buffer size, in bytes, to control 3548 the size of packets received from authoritative servers in response 3549 to recursive queries. Valid values are 512 to 4096; values outside 3550 this range are silently adjusted to the nearest value within it. 3551 The default value is 1232. 3552 3553 The usual reason for setting ``edns-udp-size`` to a non-default value 3554 is to get UDP answers to pass through broken firewalls that block 3555 fragmented packets and/or block UDP DNS packets that are greater than 3556 512 bytes. 3557 3558 When ``named`` first queries a remote server, it advertises a UDP 3559 buffer size of 512, as this has the greatest chance of success on the 3560 first try. 3561 3562 If the initial query is successful with EDNS advertising a buffer size of 3563 512, then ``named`` will advertise progressively larger buffer sizes on 3564 successive queries, until responses begin timing out or ``edns-udp-size`` is 3565 reached. 3566 3567 The default buffer sizes used by ``named`` are 512, 1232, 1432, and 3568 4096, but never exceeding ``edns-udp-size``. (The values 1232 and 3569 1432 are chosen to allow for an IPv4-/IPv6-encapsulated UDP message 3570 to be sent without fragmentation at the minimum MTU sizes for 3571 Ethernet and IPv6 networks.) 3572 3573 According to the measurements done by multiple parties the default value 3574 should not be causing the fragmentation as most of the Internet "core" is able to 3575 cope with IP message sizes between 1400-1500 bytes, the 1232 size was picked 3576 as a conservative minimal number that could be changed by the DNS operator to 3577 a estimated path MTU minus the estimated header space. In practice, the 3578 smallest MTU witnessed in the operational DNS community is 1500 octets, the 3579 Ethernet maximum payload size, so a a useful default for maximum DNS/UDP 3580 payload size on **reliable** networks would be 1432. 3581 3582 Any server-specific ``edns-udp-size`` setting has precedence over all 3583 the above rules. 3584 3585``max-udp-size`` 3586 This sets the maximum EDNS UDP message size that ``named`` sends, in bytes. 3587 Valid values are 512 to 4096; values outside this range are 3588 silently adjusted to the nearest value within it. The default value 3589 is 1232. 3590 3591 This value applies to responses sent by a server; to set the 3592 advertised buffer size in queries, see ``edns-udp-size``. 3593 3594 The usual reason for setting ``max-udp-size`` to a non-default value 3595 is to allow UDP answers to pass through broken firewalls that block 3596 fragmented packets and/or block UDP packets that are greater than 512 3597 bytes. This is independent of the advertised receive buffer 3598 (``edns-udp-size``). 3599 3600 Setting this to a low value encourages additional TCP traffic to 3601 the name server. 3602 3603``masterfile-format`` 3604 This specifies the file format of zone files (see :ref:`zonefile_format` 3605 for details). The default value is ``text``, which is the standard 3606 textual representation, except for secondary zones, in which the default 3607 value is ``raw``. Files in formats other than ``text`` are typically 3608 expected to be generated by the ``named-compilezone`` tool, or dumped by 3609 ``named``. 3610 3611 Note that when a zone file in a format other than ``text`` is loaded, 3612 ``named`` may omit some of the checks which are performed for a file in 3613 ``text`` format. For example, ``check-names`` only applies when loading 3614 zones in ``text`` format, and ``max-zone-ttl`` only applies to ``text`` 3615 and ``raw``. Zone files in binary formats should be generated with the 3616 same check level as that specified in the ``named`` configuration file. 3617 3618 ``map`` format files are loaded directly into memory via memory mapping, 3619 with only minimal validity checking. Because they are not guaranteed to 3620 be compatible from one version of BIND 9 to another, and are not 3621 compatible from one system architecture to another, they should be used 3622 with caution. See :ref:`zonefile_format` for further discussion. 3623 3624 When configured in ``options``, this statement sets the 3625 ``masterfile-format`` for all zones, but it can be overridden on a 3626 per-zone or per-view basis by including a ``masterfile-format`` 3627 statement within the ``zone`` or ``view`` block in the configuration 3628 file. 3629 3630``masterfile-style`` 3631 This specifies the formatting of zone files during dump, when the 3632 ``masterfile-format`` is ``text``. This option is ignored with any 3633 other ``masterfile-format``. 3634 3635 When set to ``relative``, records are printed in a multi-line format, 3636 with owner names expressed relative to a shared origin. When set to 3637 ``full``, records are printed in a single-line format with absolute 3638 owner names. The ``full`` format is most suitable when a zone file 3639 needs to be processed automatically by a script. The ``relative`` 3640 format is more human-readable, and is thus suitable when a zone is to 3641 be edited by hand. The default is ``relative``. 3642 3643``max-recursion-depth`` 3644 This sets the maximum number of levels of recursion that are permitted at 3645 any one time while servicing a recursive query. Resolving a name may 3646 require looking up a name server address, which in turn requires 3647 resolving another name, etc.; if the number of recursions exceeds 3648 this value, the recursive query is terminated and returns SERVFAIL. 3649 The default is 7. 3650 3651``max-recursion-queries`` 3652 This sets the maximum number of iterative queries that may be sent while 3653 servicing a recursive query. If more queries are sent, the recursive 3654 query is terminated and returns SERVFAIL. The default is 100. 3655 3656``notify-delay`` 3657 This sets the delay, in seconds, between sending sets of NOTIFY messages 3658 for a zone. Whenever a NOTIFY message is sent for a zone, a timer will 3659 be set for this duration. If the zone is updated again before the timer 3660 expires, the NOTIFY for that update will be postponed. The default is 5 3661 seconds. 3662 3663 The overall rate at which NOTIFY messages are sent for all zones is 3664 controlled by ``notify-rate``. 3665 3666``max-rsa-exponent-size`` 3667 This sets the maximum RSA exponent size, in bits, that is accepted when 3668 validating. Valid values are 35 to 4096 bits. The default, zero, is 3669 also accepted and is equivalent to 4096. 3670 3671``prefetch`` 3672 When a query is received for cached data which is to expire shortly, 3673 ``named`` can refresh the data from the authoritative server 3674 immediately, ensuring that the cache always has an answer available. 3675 3676 ``prefetch`` specifies the "trigger" TTL value at which prefetch 3677 of the current query takes place; when a cache record with a 3678 lower or equal TTL value is encountered during query processing, it is 3679 refreshed. Valid trigger TTL values are 1 to 10 seconds. Values 3680 larger than 10 seconds are silently reduced to 10. Setting a 3681 trigger TTL to zero causes prefetch to be disabled. The default 3682 trigger TTL is ``2``. 3683 3684 An optional second argument specifies the "eligibility" TTL: the 3685 smallest *original* TTL value that is accepted for a record to 3686 be eligible for prefetching. The eligibility TTL must be at least six 3687 seconds longer than the trigger TTL; if not, ``named`` 3688 silently adjusts it upward. The default eligibility TTL is ``9``. 3689 3690``v6-bias`` 3691 When determining the next name server to try, this indicates by how many 3692 milliseconds to prefer IPv6 name servers. The default is ``50`` 3693 milliseconds. 3694 3695.. _builtin: 3696 3697Built-in Server Information Zones 3698^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3699 3700The server provides some helpful diagnostic information through a number 3701of built-in zones under the pseudo-top-level-domain ``bind`` in the 3702``CHAOS`` class. These zones are part of a built-in view 3703(see :ref:`view_statement_grammar`) of class ``CHAOS``, which is 3704separate from the default view of class ``IN``. Most global 3705configuration options (``allow-query``, etc.) apply to this view, 3706but some are locally overridden: ``notify``, ``recursion``, and 3707``allow-new-zones`` are always set to ``no``, and ``rate-limit`` is set 3708to allow three responses per second. 3709 3710To disable these zones, use the options below or hide the 3711built-in ``CHAOS`` view by defining an explicit view of class ``CHAOS`` 3712that matches all clients. 3713 3714``version`` 3715 This is the version the server should report via a query of the name 3716 ``version.bind`` with type ``TXT`` and class ``CHAOS``. The default is 3717 the real version number of this server. Specifying ``version none`` 3718 disables processing of the queries. 3719 3720 Setting ``version`` to any value (including ``none``) also disables 3721 queries for ``authors.bind TXT CH``. 3722 3723``hostname`` 3724 This is the hostname the server should report via a query of the name 3725 ``hostname.bind`` with type ``TXT`` and class ``CHAOS``. This defaults 3726 to the hostname of the machine hosting the name server, as found by 3727 the ``gethostname()`` function. The primary purpose of such queries is to 3728 identify which of a group of anycast servers is actually answering 3729 the queries. Specifying ``hostname none;`` disables processing of 3730 the queries. 3731 3732``server-id`` 3733 This is the ID the server should report when receiving a Name Server 3734 Identifier (NSID) query, or a query of the name ``ID.SERVER`` with 3735 type ``TXT`` and class ``CHAOS``. The primary purpose of such queries is 3736 to identify which of a group of anycast servers is actually answering 3737 the queries. Specifying ``server-id none;`` disables processing of 3738 the queries. Specifying ``server-id hostname;`` causes ``named`` 3739 to use the hostname as found by the ``gethostname()`` function. The 3740 default ``server-id`` is ``none``. 3741 3742.. _empty: 3743 3744Built-in Empty Zones 3745^^^^^^^^^^^^^^^^^^^^ 3746 3747The ``named`` server has some built-in empty zones, for SOA and NS records 3748only. These are for zones that should normally be answered locally and for 3749which queries should not be sent to the Internet's root servers. The 3750official servers that cover these namespaces return NXDOMAIN responses 3751to these queries. In particular, these cover the reverse namespaces for 3752addresses from :rfc:`1918`, :rfc:`4193`, :rfc:`5737`, and :rfc:`6598`. They also 3753include the reverse namespace for the IPv6 local address (locally assigned), 3754IPv6 link local addresses, the IPv6 loopback address, and the IPv6 3755unknown address. 3756 3757The server attempts to determine if a built-in zone already exists 3758or is active (covered by a forward-only forwarding declaration) and does 3759not create an empty zone if either is true. 3760 3761The current list of empty zones is: 3762 3763- 10.IN-ADDR.ARPA 3764- 16.172.IN-ADDR.ARPA 3765- 17.172.IN-ADDR.ARPA 3766- 18.172.IN-ADDR.ARPA 3767- 19.172.IN-ADDR.ARPA 3768- 20.172.IN-ADDR.ARPA 3769- 21.172.IN-ADDR.ARPA 3770- 22.172.IN-ADDR.ARPA 3771- 23.172.IN-ADDR.ARPA 3772- 24.172.IN-ADDR.ARPA 3773- 25.172.IN-ADDR.ARPA 3774- 26.172.IN-ADDR.ARPA 3775- 27.172.IN-ADDR.ARPA 3776- 28.172.IN-ADDR.ARPA 3777- 29.172.IN-ADDR.ARPA 3778- 30.172.IN-ADDR.ARPA 3779- 31.172.IN-ADDR.ARPA 3780- 168.192.IN-ADDR.ARPA 3781- 64.100.IN-ADDR.ARPA 3782- 65.100.IN-ADDR.ARPA 3783- 66.100.IN-ADDR.ARPA 3784- 67.100.IN-ADDR.ARPA 3785- 68.100.IN-ADDR.ARPA 3786- 69.100.IN-ADDR.ARPA 3787- 70.100.IN-ADDR.ARPA 3788- 71.100.IN-ADDR.ARPA 3789- 72.100.IN-ADDR.ARPA 3790- 73.100.IN-ADDR.ARPA 3791- 74.100.IN-ADDR.ARPA 3792- 75.100.IN-ADDR.ARPA 3793- 76.100.IN-ADDR.ARPA 3794- 77.100.IN-ADDR.ARPA 3795- 78.100.IN-ADDR.ARPA 3796- 79.100.IN-ADDR.ARPA 3797- 80.100.IN-ADDR.ARPA 3798- 81.100.IN-ADDR.ARPA 3799- 82.100.IN-ADDR.ARPA 3800- 83.100.IN-ADDR.ARPA 3801- 84.100.IN-ADDR.ARPA 3802- 85.100.IN-ADDR.ARPA 3803- 86.100.IN-ADDR.ARPA 3804- 87.100.IN-ADDR.ARPA 3805- 88.100.IN-ADDR.ARPA 3806- 89.100.IN-ADDR.ARPA 3807- 90.100.IN-ADDR.ARPA 3808- 91.100.IN-ADDR.ARPA 3809- 92.100.IN-ADDR.ARPA 3810- 93.100.IN-ADDR.ARPA 3811- 94.100.IN-ADDR.ARPA 3812- 95.100.IN-ADDR.ARPA 3813- 96.100.IN-ADDR.ARPA 3814- 97.100.IN-ADDR.ARPA 3815- 98.100.IN-ADDR.ARPA 3816- 99.100.IN-ADDR.ARPA 3817- 100.100.IN-ADDR.ARPA 3818- 101.100.IN-ADDR.ARPA 3819- 102.100.IN-ADDR.ARPA 3820- 103.100.IN-ADDR.ARPA 3821- 104.100.IN-ADDR.ARPA 3822- 105.100.IN-ADDR.ARPA 3823- 106.100.IN-ADDR.ARPA 3824- 107.100.IN-ADDR.ARPA 3825- 108.100.IN-ADDR.ARPA 3826- 109.100.IN-ADDR.ARPA 3827- 110.100.IN-ADDR.ARPA 3828- 111.100.IN-ADDR.ARPA 3829- 112.100.IN-ADDR.ARPA 3830- 113.100.IN-ADDR.ARPA 3831- 114.100.IN-ADDR.ARPA 3832- 115.100.IN-ADDR.ARPA 3833- 116.100.IN-ADDR.ARPA 3834- 117.100.IN-ADDR.ARPA 3835- 118.100.IN-ADDR.ARPA 3836- 119.100.IN-ADDR.ARPA 3837- 120.100.IN-ADDR.ARPA 3838- 121.100.IN-ADDR.ARPA 3839- 122.100.IN-ADDR.ARPA 3840- 123.100.IN-ADDR.ARPA 3841- 124.100.IN-ADDR.ARPA 3842- 125.100.IN-ADDR.ARPA 3843- 126.100.IN-ADDR.ARPA 3844- 127.100.IN-ADDR.ARPA 3845- 0.IN-ADDR.ARPA 3846- 127.IN-ADDR.ARPA 3847- 254.169.IN-ADDR.ARPA 3848- 2.0.192.IN-ADDR.ARPA 3849- 100.51.198.IN-ADDR.ARPA 3850- 113.0.203.IN-ADDR.ARPA 3851- 255.255.255.255.IN-ADDR.ARPA 3852- 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA 3853- 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA 3854- 8.B.D.0.1.0.0.2.IP6.ARPA 3855- D.F.IP6.ARPA 3856- 8.E.F.IP6.ARPA 3857- 9.E.F.IP6.ARPA 3858- A.E.F.IP6.ARPA 3859- B.E.F.IP6.ARPA 3860- EMPTY.AS112.ARPA 3861- HOME.ARPA 3862 3863Empty zones can be set at the view level and only apply to views of 3864class IN. Disabled empty zones are only inherited from options if there 3865are no disabled empty zones specified at the view level. To override the 3866options list of disabled zones, disable the root zone at the 3867view level. For example: 3868 3869:: 3870 3871 disable-empty-zone "."; 3872 3873If using the address ranges covered here, 3874reverse zones covering the addresses should already be in place. In practice this 3875appears to not be the case, with many queries being made to the 3876infrastructure servers for names in these spaces. So many, in fact, that 3877sacrificial servers had to be deployed to channel the query load 3878away from the infrastructure servers. 3879 3880.. note:: 3881 3882 The real parent servers for these zones should disable all empty zones 3883 under the parent zone they serve. For the real root servers, this is 3884 all built-in empty zones. This enables them to return referrals 3885 to deeper in the tree. 3886 3887``empty-server`` 3888 This specifies the server name that appears in the returned SOA record for 3889 empty zones. If none is specified, the zone's name is used. 3890 3891``empty-contact`` 3892 This specifies the contact name that appears in the returned SOA record for 3893 empty zones. If none is specified, "." is used. 3894 3895``empty-zones-enable`` 3896 This enables or disables all empty zones. By default, they are enabled. 3897 3898``disable-empty-zone`` 3899 This disables individual empty zones. By default, none are disabled. This 3900 option can be specified multiple times. 3901 3902.. _content_filtering: 3903 3904Content Filtering 3905^^^^^^^^^^^^^^^^^ 3906 3907BIND 9 provides the ability to filter out responses from external 3908DNS servers containing certain types of data in the answer section. 3909Specifically, it can reject address (A or AAAA) records if the 3910corresponding IPv4 or IPv6 addresses match the given 3911``address_match_list`` of the ``deny-answer-addresses`` option. It can 3912also reject CNAME or DNAME records if the "alias" name (i.e., the CNAME 3913alias or the substituted query name due to DNAME) matches the given 3914``namelist`` of the ``deny-answer-aliases`` option, where "match" means 3915the alias name is a subdomain of one of the ``name_list`` elements. If 3916the optional ``namelist`` is specified with ``except-from``, records 3917whose query name matches the list are accepted regardless of the 3918filter setting. Likewise, if the alias name is a subdomain of the 3919corresponding zone, the ``deny-answer-aliases`` filter does not apply; 3920for example, even if "example.com" is specified for 3921``deny-answer-aliases``, 3922 3923:: 3924 3925 www.example.com. CNAME xxx.example.com. 3926 3927returned by an "example.com" server is accepted. 3928 3929In the ``address_match_list`` of the ``deny-answer-addresses`` option, 3930only ``ip_addr`` and ``ip_prefix`` are meaningful; any ``key_id`` is 3931silently ignored. 3932 3933If a response message is rejected due to the filtering, the entire 3934message is discarded without being cached, and a SERVFAIL error is 3935returned to the client. 3936 3937This filtering is intended to prevent "DNS rebinding attacks," in which 3938an attacker, in response to a query for a domain name the attacker 3939controls, returns an IP address within the user's own network or an alias name 3940within the user's own domain. A naive web browser or script could then serve 3941as an unintended proxy, allowing the attacker to get access to an 3942internal node of the local network that could not be externally accessed 3943otherwise. See the paper available at 3944https://dl.acm.org/doi/10.1145/1315245.1315298 for more details 3945about these attacks. 3946 3947For example, with a domain named "example.net" and an internal 3948network using an IPv4 prefix 192.0.2.0/24, an administrator might specify the 3949following rules: 3950 3951:: 3952 3953 deny-answer-addresses { 192.0.2.0/24; } except-from { "example.net"; }; 3954 deny-answer-aliases { "example.net"; }; 3955 3956If an external attacker let a web browser in the local network look up 3957an IPv4 address of "attacker.example.com", the attacker's DNS server 3958would return a response like this: 3959 3960:: 3961 3962 attacker.example.com. A 192.0.2.1 3963 3964in the answer section. Since the rdata of this record (the IPv4 address) 3965matches the specified prefix 192.0.2.0/24, this response would be 3966ignored. 3967 3968On the other hand, if the browser looked up a legitimate internal web 3969server "www.example.net" and the following response were returned to the 3970BIND 9 server: 3971 3972:: 3973 3974 www.example.net. A 192.0.2.2 3975 3976it would be accepted, since the owner name "www.example.net" matches the 3977``except-from`` element, "example.net". 3978 3979Note that this is not really an attack on the DNS per se. In fact, there 3980is nothing wrong with having an "external" name mapped to an "internal" 3981IP address or domain name from the DNS point of view; it might actually 3982be provided for a legitimate purpose, such as for debugging. As long as 3983the mapping is provided by the correct owner, it either is not possible or does 3984not make sense to detect whether the intent of the mapping is legitimate 3985within the DNS. The "rebinding" attack must primarily be 3986protected at the application that uses the DNS. For a large site, 3987however, it may be difficult to protect all possible applications at 3988once. This filtering feature is provided only to help such an 3989operational environment; turning it on is generally discouraged 3990unless there is no other choice and the attack is a 3991real threat to applications. 3992 3993Care should be particularly taken if using this option for 3994addresses within 127.0.0.0/8. These addresses are obviously "internal," 3995but many applications conventionally rely on a DNS mapping from some 3996name to such an address. Filtering out DNS records containing this 3997address spuriously can break such applications. 3998 3999.. _rpz: 4000 4001Response Policy Zone (RPZ) Rewriting 4002^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4003 4004BIND 9 includes a limited mechanism to modify DNS responses for requests 4005analogous to email anti-spam DNS rejection lists. Responses can be changed to 4006deny the existence of domains (NXDOMAIN), deny the existence of IP 4007addresses for domains (NODATA), or contain other IP addresses or data. 4008 4009Response policy zones are named in the ``response-policy`` option for 4010the view, or among the global options if there is no ``response-policy`` 4011option for the view. Response policy zones are ordinary DNS zones 4012containing RRsets that can be queried normally if allowed. It is usually 4013best to restrict those queries with something like 4014``allow-query { localhost; };``. Note that zones using 4015``masterfile-format map`` cannot be used as policy zones. 4016 4017A ``response-policy`` option can support multiple policy zones. To 4018maximize performance, a radix tree is used to quickly identify response 4019policy zones containing triggers that match the current query. This 4020imposes an upper limit of 64 on the number of policy zones in a single 4021``response-policy`` option; more than that is a configuration error. 4022 4023Rules encoded in response policy zones are processed after those defined in 4024:ref:`access_control`. All queries from clients which are not permitted access 4025to the resolver are answered with a status code of REFUSED, regardless of 4026configured RPZ rules. 4027 4028Five policy triggers can be encoded in RPZ records. 4029 4030``RPZ-CLIENT-IP`` 4031 IP records are triggered by the IP address of the DNS client. Client 4032 IP address triggers are encoded in records that have owner names that 4033 are subdomains of ``rpz-client-ip``, relativized to the policy zone 4034 origin name, and that encode an address or address block. IPv4 addresses 4035 are represented as ``prefixlength.B4.B3.B2.B1.rpz-client-ip``. The 4036 IPv4 prefix length must be between 1 and 32. All four bytes - B4, B3, 4037 B2, and B1 - must be present. B4 is the decimal value of the least 4038 significant byte of the IPv4 address as in IN-ADDR.ARPA. 4039 4040 IPv6 addresses are encoded in a format similar to the standard IPv6 4041 text representation, 4042 ``prefixlength.W8.W7.W6.W5.W4.W3.W2.W1.rpz-client-ip``. Each of 4043 W8,...,W1 is a one- to four-digit hexadecimal number representing 16 4044 bits of the IPv6 address as in the standard text representation of 4045 IPv6 addresses, but reversed as in IP6.ARPA. (Note that this 4046 representation of IPv6 addresses is different from IP6.ARPA, where each 4047 hex digit occupies a label.) All 8 words must be present except when 4048 one set of consecutive zero words is replaced with ``.zz.``, analogous 4049 to double colons (::) in standard IPv6 text encodings. The IPv6 4050 prefix length must be between 1 and 128. 4051 4052``QNAME`` 4053 QNAME policy records are triggered by query names of requests and 4054 targets of CNAME records resolved to generate the response. The owner 4055 name of a QNAME policy record is the query name relativized to the 4056 policy zone. 4057 4058``RPZ-IP`` 4059 IP triggers are IP addresses in an A or AAAA record in the ANSWER 4060 section of a response. They are encoded like client-IP triggers, 4061 except as subdomains of ``rpz-ip``. 4062 4063``RPZ-NSDNAME`` 4064 NSDNAME triggers match names of authoritative servers for the query name, a 4065 parent of the query name, a CNAME for the query name, or a parent of a CNAME. 4066 They are encoded as subdomains of ``rpz-nsdname``, relativized 4067 to the RPZ origin name. NSIP triggers match IP addresses in A and AAAA 4068 RRsets for domains that can be checked against NSDNAME policy records. The 4069 ``nsdname-enable`` phrase turns NSDNAME triggers off or on for a single 4070 policy zone or for all zones. 4071 4072 If authoritative name servers for the query name are not yet known, ``named`` 4073 recursively looks up the authoritative servers for the query name before 4074 applying an RPZ-NSDNAME rule, which can cause a processing delay. 4075 4076``RPZ-NSIP`` 4077 NSIP triggers match the IP addresses of authoritative servers. They 4078 are encoded like IP triggers, except as subdomains of ``rpz-nsip``. 4079 NSDNAME and NSIP triggers are checked only for names with at least 4080 ``min-ns-dots`` dots. The default value of ``min-ns-dots`` is 1, to 4081 exclude top-level domains. The ``nsip-enable`` phrase turns NSIP 4082 triggers off or on for a single policy zone or for all zones. 4083 4084 If a name server's IP address is not yet known, ``named`` 4085 recursively looks up the IP address before applying an RPZ-NSIP rule, 4086 which can cause a processing delay. To speed up processing at the cost 4087 of precision, the ``nsip-wait-recurse`` option can be used; when set 4088 to ``no``, RPZ-NSIP rules are only applied when a name server's 4089 IP address has already been looked up and cached. If a server's IP 4090 address is not in the cache, the RPZ-NSIP rule is ignored, 4091 but the address is looked up in the background and the rule 4092 is applied to subsequent queries. The default is ``yes``, 4093 meaning RPZ-NSIP rules are always applied, even if an address 4094 needs to be looked up first. 4095 4096The query response is checked against all response policy zones, so two 4097or more policy records can be triggered by a response. Because DNS 4098responses are rewritten according to at most one policy record, a single 4099record encoding an action (other than ``DISABLED`` actions) must be 4100chosen. Triggers, or the records that encode them, are chosen for 4101rewriting in the following order: 4102 41031. Choose the triggered record in the zone that appears first in the 4104 response-policy option. 41052. Prefer CLIENT-IP to QNAME to IP to NSDNAME to NSIP triggers in a 4106 single zone. 41073. Among NSDNAME triggers, prefer the trigger that matches the smallest 4108 name under the DNSSEC ordering. 41094. Among IP or NSIP triggers, prefer the trigger with the longest 4110 prefix. 41115. Among triggers with the same prefix length, prefer the IP or NSIP 4112 trigger that matches the smallest IP address. 4113 4114When the processing of a response is restarted to resolve DNAME or CNAME 4115records and a policy record set has not been triggered, all response 4116policy zones are again consulted for the DNAME or CNAME names and 4117addresses. 4118 4119RPZ record sets are any types of DNS record, except DNAME or DNSSEC, that 4120encode actions or responses to individual queries. Any of the policies 4121can be used with any of the triggers. For example, while the 4122``TCP-only`` policy is commonly used with ``client-IP`` triggers, it can 4123be used with any type of trigger to force the use of TCP for responses 4124with owner names in a zone. 4125 4126``PASSTHRU`` 4127 The auto-acceptance policy is specified by a CNAME whose target is 4128 ``rpz-passthru``. It causes the response to not be rewritten and is 4129 most often used to "poke holes" in policies for CIDR blocks. 4130 4131``DROP`` 4132 The auto-rejection policy is specified by a CNAME whose target is 4133 ``rpz-drop``. It causes the response to be discarded. Nothing is sent 4134 to the DNS client. 4135 4136``TCP-Only`` 4137 The "slip" policy is specified by a CNAME whose target is 4138 ``rpz-tcp-only``. It changes UDP responses to short, truncated DNS 4139 responses that require the DNS client to try again with TCP. It is 4140 used to mitigate distributed DNS reflection attacks. 4141 4142``NXDOMAIN`` 4143 The "domain undefined" response is encoded by a CNAME whose target is 4144 the root domain (.). 4145 4146``NODATA`` 4147 The empty set of resource records is specified by a CNAME whose target 4148 is the wildcard top-level domain (``*.``). It rewrites the response to 4149 NODATA or ANCOUNT=0. 4150 4151``Local Data`` 4152 A set of ordinary DNS records can be used to answer queries. Queries 4153 for record types not in the set are answered with NODATA. 4154 4155 A special form of local data is a CNAME whose target is a wildcard 4156 such as \*.example.com. It is used as if an ordinary CNAME after 4157 the asterisk (\*) has been replaced with the query name. 4158 This special form is useful for query logging in the walled garden's 4159 authoritative DNS server. 4160 4161All of the actions specified in all of the individual records in a 4162policy zone can be overridden with a ``policy`` clause in the 4163``response-policy`` option. An organization using a policy zone provided 4164by another organization might use this mechanism to redirect domains to 4165its own walled garden. 4166 4167``GIVEN`` 4168 The placeholder policy says "do not override but perform the action 4169 specified in the zone." 4170 4171``DISABLED`` 4172 The testing override policy causes policy zone records to do nothing 4173 but log what they would have done if the policy zone were not 4174 disabled. The response to the DNS query is written (or not) 4175 according to any triggered policy records that are not disabled. 4176 Disabled policy zones should appear first, because they are often 4177 not logged if a higher-precedence trigger is found first. 4178 4179``PASSTHRU``; ``DROP``; ``TCP-Only``; ``NXDOMAIN``; ``NODATA`` 4180 These settings each override the corresponding per-record policy. 4181 4182``CNAME domain`` 4183 This causes all RPZ policy records to act as if they were "cname domain" 4184 records. 4185 4186By default, the actions encoded in a response policy zone are applied 4187only to queries that ask for recursion (RD=1). That default can be 4188changed for a single policy zone, or for all response policy zones in a view, 4189with a ``recursive-only no`` clause. This feature is useful for serving 4190the same zone files both inside and outside an :rfc:`1918` cloud and using 4191RPZ to delete answers that would otherwise contain :rfc:`1918` values on 4192the externally visible name server or view. 4193 4194Also by default, RPZ actions are applied only to DNS requests that 4195either do not request DNSSEC metadata (DO=0) or when no DNSSEC records 4196are available for the requested name in the original zone (not the response 4197policy zone). This default can be changed for all response policy zones 4198in a view with a ``break-dnssec yes`` clause. In that case, RPZ actions 4199are applied regardless of DNSSEC. The name of the clause option reflects 4200the fact that results rewritten by RPZ actions cannot verify. 4201 4202No DNS records are needed for a QNAME or Client-IP trigger; the name or 4203IP address itself is sufficient, so in principle the query name need not 4204be recursively resolved. However, not resolving the requested name can 4205leak the fact that response policy rewriting is in use, and that the name 4206is listed in a policy zone, to operators of servers for listed names. To 4207prevent that information leak, by default any recursion needed for a 4208request is done before any policy triggers are considered. Because 4209listed domains often have slow authoritative servers, this behavior can 4210cost significant time. The ``qname-wait-recurse no`` option overrides 4211the default and enables that behavior when recursion cannot change a 4212non-error response. The option does not affect QNAME or client-IP 4213triggers in policy zones listed after other zones containing IP, NSIP, 4214and NSDNAME triggers, because those may depend on the A, AAAA, and NS 4215records that would be found during recursive resolution. It also does 4216not affect DNSSEC requests (DO=1) unless ``break-dnssec yes`` is in use, 4217because the response would depend on whether RRSIG records were 4218found during resolution. Using this option can cause error responses 4219such as SERVFAIL to appear to be rewritten, since no recursion is being 4220done to discover problems at the authoritative server. 4221 4222The ``dnsrps-enable yes`` option turns on the DNS Response Policy Service 4223(DNSRPS) interface, if it has been compiled in ``named`` using 4224``configure --enable-dnsrps``. 4225 4226The ``dnsrps-options`` block provides additional RPZ configuration 4227settings, which are passed through to the DNSRPS provider library. 4228Multiple DNSRPS settings in an ``dnsrps-options`` string should be 4229separated with semi-colons (;). The DNSRPS provider, librpz, is passed a 4230configuration string consisting of the ``dnsrps-options`` text, 4231concatenated with settings derived from the ``response-policy`` 4232statement. 4233 4234Note: the ``dnsrps-options`` text should only include configuration 4235settings that are specific to the DNSRPS provider. For example, the 4236DNSRPS provider from Farsight Security takes options such as 4237``dnsrpzd-conf``, ``dnsrpzd-sock``, and ``dnzrpzd-args`` (for details of 4238these options, see the ``librpz`` documentation). Other RPZ 4239configuration settings could be included in ``dnsrps-options`` as well, 4240but if ``named`` were switched back to traditional RPZ by setting 4241``dnsrps-enable`` to "no", those options would be ignored. 4242 4243The TTL of a record modified by RPZ policies is set from the TTL of the 4244relevant record in the policy zone. It is then limited to a maximum value. 4245The ``max-policy-ttl`` clause changes the maximum number of seconds from its 4246default of 5. For convenience, TTL-style time-unit suffixes may be used 4247to specify the value. It also accepts ISO 8601 duration formats. 4248 4249For example, an administrator might use this option statement: 4250 4251:: 4252 4253 response-policy { zone "badlist"; }; 4254 4255and this zone statement: 4256 4257:: 4258 4259 zone "badlist" {type primary; file "primary/badlist"; allow-query {none;}; }; 4260 4261with this zone file: 4262 4263:: 4264 4265 $TTL 1H 4266 @ SOA LOCALHOST. named-mgr.example.com (1 1h 15m 30d 2h) 4267 NS LOCALHOST. 4268 4269 ; QNAME policy records. There are no periods (.) after the owner names. 4270 nxdomain.domain.com CNAME . ; NXDOMAIN policy 4271 *.nxdomain.domain.com CNAME . ; NXDOMAIN policy 4272 nodata.domain.com CNAME *. ; NODATA policy 4273 *.nodata.domain.com CNAME *. ; NODATA policy 4274 bad.domain.com A 10.0.0.1 ; redirect to a walled garden 4275 AAAA 2001:2::1 4276 bzone.domain.com CNAME garden.example.com. 4277 4278 ; do not rewrite (PASSTHRU) OK.DOMAIN.COM 4279 ok.domain.com CNAME rpz-passthru. 4280 4281 ; redirect x.bzone.domain.com to x.bzone.domain.com.garden.example.com 4282 *.bzone.domain.com CNAME *.garden.example.com. 4283 4284 ; IP policy records that rewrite all responses containing A records in 127/8 4285 ; except 127.0.0.1 4286 8.0.0.0.127.rpz-ip CNAME . 4287 32.1.0.0.127.rpz-ip CNAME rpz-passthru. 4288 4289 ; NSDNAME and NSIP policy records 4290 ns.domain.com.rpz-nsdname CNAME . 4291 48.zz.2.2001.rpz-nsip CNAME . 4292 4293 ; auto-reject and auto-accept some DNS clients 4294 112.zz.2001.rpz-client-ip CNAME rpz-drop. 4295 8.0.0.0.127.rpz-client-ip CNAME rpz-drop. 4296 4297 ; force some DNS clients and responses in the example.com zone to TCP 4298 16.0.0.1.10.rpz-client-ip CNAME rpz-tcp-only. 4299 example.com CNAME rpz-tcp-only. 4300 *.example.com CNAME rpz-tcp-only. 4301 4302RPZ can affect server performance. Each configured response policy zone 4303requires the server to perform one to four additional database lookups 4304before a query can be answered. For example, a DNS server with four 4305policy zones, each with all four kinds of response triggers (QNAME, IP, 4306NSIP, and NSDNAME), requires a total of 17 times as many database lookups 4307as a similar DNS server with no response policy zones. A BIND 9 server 4308with adequate memory and one response policy zone with QNAME and IP 4309triggers might achieve a maximum queries-per-second (QPS) rate about 20% 4310lower. A server with four response policy zones with QNAME and IP 4311triggers might have a maximum QPS rate about 50% lower. 4312 4313Responses rewritten by RPZ are counted in the ``RPZRewrites`` 4314statistics. 4315 4316The ``log`` clause can be used to optionally turn off rewrite logging 4317for a particular response policy zone. By default, all rewrites are 4318logged. 4319 4320The ``add-soa`` option controls whether the RPZ's SOA record is added to 4321the section for traceback of changes from this zone. 4322This can be set at the individual policy zone level or at the 4323response-policy level. The default is ``yes``. 4324 4325Updates to RPZ zones are processed asynchronously; if there is more than 4326one update pending they are bundled together. If an update to a RPZ zone 4327(for example, via IXFR) happens less than ``min-update-interval`` 4328seconds after the most recent update, the changes are not 4329carried out until this interval has elapsed. The default is ``60`` 4330seconds. For convenience, TTL-style time-unit suffixes may be used to 4331specify the value. It also accepts ISO 8601 duration formats. 4332 4333.. _rrl: 4334 4335Response Rate Limiting 4336^^^^^^^^^^^^^^^^^^^^^^ 4337 4338Excessive, almost-identical UDP *responses* can be controlled by 4339configuring a ``rate-limit`` clause in an ``options`` or ``view`` 4340statement. This mechanism keeps authoritative BIND 9 from being used to 4341amplify reflection denial-of-service (DoS) attacks. Short BADCOOKIE errors or 4342truncated (TC=1) responses can be sent to provide rate-limited responses to 4343legitimate clients within a range of forged, attacked IP addresses. 4344Legitimate clients react to dropped responses by retrying, 4345to BADCOOKIE errors by including a server cookie when retrying, 4346and to truncated responses by switching to TCP. 4347 4348This mechanism is intended for authoritative DNS servers. It can be used 4349on recursive servers, but can slow applications such as SMTP servers 4350(mail receivers) and HTTP clients (web browsers) that repeatedly request 4351the same domains. When possible, closing "open" recursive servers is 4352better. 4353 4354Response rate limiting uses a "credit" or "token bucket" scheme. Each 4355combination of identical response and client has a conceptual "account" 4356that earns a specified number of credits every second. A prospective 4357response debits its account by one. Responses are dropped or truncated 4358while the account is negative. Responses are tracked within a rolling 4359window of time which defaults to 15 seconds, but which can be configured with 4360the ``window`` option to any value from 1 to 3600 seconds (1 hour). The 4361account cannot become more positive than the per-second limit or more 4362negative than ``window`` times the per-second limit. When the specified 4363number of credits for a class of responses is set to 0, those responses 4364are not rate-limited. 4365 4366The notions of "identical response" and "DNS client" for rate limiting 4367are not simplistic. All responses to an address block are counted as if 4368to a single client. The prefix lengths of address blocks are specified 4369with ``ipv4-prefix-length`` (default 24) and ``ipv6-prefix-length`` 4370(default 56). 4371 4372All non-empty responses for a valid domain name (qname) and record type 4373(qtype) are identical and have a limit specified with 4374``responses-per-second`` (default 0 or no limit). All valid wildcard 4375domain names are interpreted as the zone's origin name concatenated to 4376the "*" name. All empty (NODATA) responses for a valid domain, 4377regardless of query type, are identical. Responses in the NODATA class 4378are limited by ``nodata-per-second`` (default ``responses-per-second``). 4379Requests for any and all undefined subdomains of a given valid domain 4380result in NXDOMAIN errors, and are identical regardless of query type. 4381They are limited by ``nxdomains-per-second`` (default 4382``responses-per-second``). This controls some attacks using random 4383names, but can be relaxed or turned off (set to 0) on servers that 4384expect many legitimate NXDOMAIN responses, such as from anti-spam 4385rejection lists. Referrals or delegations to the server of a given 4386domain are identical and are limited by ``referrals-per-second`` 4387(default ``responses-per-second``). 4388 4389Responses generated from local wildcards are counted and limited as if 4390they were for the parent domain name. This controls flooding using 4391random.wild.example.com. 4392 4393All requests that result in DNS errors other than NXDOMAIN, such as 4394SERVFAIL and FORMERR, are identical regardless of requested name (qname) 4395or record type (qtype). This controls attacks using invalid requests or 4396distant, broken authoritative servers. By default the limit on errors is 4397the same as the ``responses-per-second`` value, but it can be set 4398separately with ``errors-per-second``. 4399 4400Many attacks using DNS involve UDP requests with forged source 4401addresses. Rate limiting prevents the use of BIND 9 to flood a network 4402with responses to requests with forged source addresses, but could let a 4403third party block responses to legitimate requests. There is a mechanism 4404that can answer some legitimate requests from a client whose address is 4405being forged in a flood. Setting ``slip`` to 2 (its default) causes 4406every other UDP request without a valid server cookie to be answered with 4407a small response. The small size and reduced frequency, and resulting lack of 4408amplification, of "slipped" responses make them unattractive for 4409reflection DoS attacks. ``slip`` must be between 0 and 10. A value of 0 4410does not "slip"; no small responses are sent due to rate limiting. Rather, 4411all responses are dropped. A value of 1 causes every response to slip; 4412values between 2 and 10 cause every nth response to slip. 4413 4414If the request included a client cookie, then a "slipped" response is 4415a BADCOOKIE error with a server cookie, which allows a legitimate client 4416to include the server cookie to be exempted from the rate limiting 4417when it retries the request. 4418If the request did not include a cookie, then a "slipped" response is 4419a truncated (TC=1) response, which prompts a legitimate client to 4420switch to TCP and thus be exempted from the rate limiting. Some error 4421responses, including REFUSED and SERVFAIL, cannot be replaced with 4422truncated responses and are instead leaked at the ``slip`` rate. 4423 4424(Note: dropped responses from an authoritative server may reduce the 4425difficulty of a third party successfully forging a response to a 4426recursive resolver. The best security against forged responses is for 4427authoritative operators to sign their zones using DNSSEC and for 4428resolver operators to validate the responses. When this is not an 4429option, operators who are more concerned with response integrity than 4430with flood mitigation may consider setting ``slip`` to 1, causing all 4431rate-limited responses to be truncated rather than dropped. This reduces 4432the effectiveness of rate-limiting against reflection attacks.) 4433 4434When the approximate query-per-second rate exceeds the ``qps-scale`` 4435value, the ``responses-per-second``, ``errors-per-second``, 4436``nxdomains-per-second``, and ``all-per-second`` values are reduced by 4437the ratio of the current rate to the ``qps-scale`` value. This feature 4438can tighten defenses during attacks. For example, with 4439``qps-scale 250; responses-per-second 20;`` and a total query rate of 44401000 queries/second for all queries from all DNS clients including via 4441TCP, then the effective responses/second limit changes to (250/1000)*20, 4442or 5. Responses to requests that included a valid server cookie, 4443and responses sent via TCP, are not limited but are counted to compute 4444the query-per-second rate. 4445 4446Communities of DNS clients can be given their own parameters or no 4447rate limiting by putting ``rate-limit`` statements in ``view`` statements 4448instead of in the global ``option`` statement. A ``rate-limit`` statement 4449in a view replaces, rather than supplements, a ``rate-limit`` 4450statement among the main options. DNS clients within a view can be 4451exempted from rate limits with the ``exempt-clients`` clause. 4452 4453UDP responses of all kinds can be limited with the ``all-per-second`` 4454phrase. This rate limiting is unlike the rate limiting provided by 4455``responses-per-second``, ``errors-per-second``, and 4456``nxdomains-per-second`` on a DNS server, which are often invisible to 4457the victim of a DNS reflection attack. Unless the forged requests of the 4458attack are the same as the legitimate requests of the victim, the 4459victim's requests are not affected. Responses affected by an 4460``all-per-second`` limit are always dropped; the ``slip`` value has no 4461effect. An ``all-per-second`` limit should be at least 4 times as large 4462as the other limits, because single DNS clients often send bursts of 4463legitimate requests. For example, the receipt of a single mail message 4464can prompt requests from an SMTP server for NS, PTR, A, and AAAA records 4465as the incoming SMTP/TCP/IP connection is considered. The SMTP server 4466can need additional NS, A, AAAA, MX, TXT, and SPF records as it 4467considers the SMTP ``Mail From`` command. Web browsers often repeatedly 4468resolve the same names that are duplicated in HTML <IMG> tags in a page. 4469``all-per-second`` is similar to the rate limiting offered by firewalls 4470but is often inferior. Attacks that justify ignoring the contents of DNS 4471responses are likely to be attacks on the DNS server itself. They 4472usually should be discarded before the DNS server spends resources making 4473TCP connections or parsing DNS requests, but that rate limiting must be 4474done before the DNS server sees the requests. 4475 4476The maximum size of the table used to track requests and rate-limit 4477responses is set with ``max-table-size``. Each entry in the table is 4478between 40 and 80 bytes. The table needs approximately as many entries 4479as the number of requests received per second. The default is 20,000. To 4480reduce the cold start of growing the table, ``min-table-size`` (default 500) 4481can set the minimum table size. Enable ``rate-limit`` category 4482logging to monitor expansions of the table and inform choices for the 4483initial and maximum table size. 4484 4485Use ``log-only yes`` to test rate-limiting parameters without actually 4486dropping any requests. 4487 4488Responses dropped by rate limits are included in the ``RateDropped`` and 4489``QryDropped`` statistics. Responses that are truncated by rate limits are 4490included in ``RateSlipped`` and ``RespTruncated``. 4491 4492NXDOMAIN Redirection 4493^^^^^^^^^^^^^^^^^^^^ 4494 4495``named`` supports NXDOMAIN redirection via two methods: 4496 4497- Redirect zone (:ref:`zone_statement_grammar`) 4498- Redirect namespace 4499 4500With either method, when ``named`` gets an NXDOMAIN response it examines a 4501separate namespace to see if the NXDOMAIN response should be replaced 4502with an alternative response. 4503 4504With a redirect zone (``zone "." { type redirect; };``), the data used 4505to replace the NXDOMAIN is held in a single zone which is not part of 4506the normal namespace. All the redirect information is contained in the 4507zone; there are no delegations. 4508 4509With a redirect namespace (``option { nxdomain-redirect <suffix> };``), 4510the data used to replace the NXDOMAIN is part of the normal namespace 4511and is looked up by appending the specified suffix to the original 4512query name. This roughly doubles the cache required to process 4513NXDOMAIN responses, as both the original NXDOMAIN response and the 4514replacement data (or an NXDOMAIN indicating that there is no 4515replacement) must be stored. 4516 4517If both a redirect zone and a redirect namespace are configured, the 4518redirect zone is tried first. 4519 4520.. _server_statement_grammar: 4521 4522``server`` Statement Grammar 4523~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4524 4525.. include:: ../misc/server.grammar.rst 4526 4527.. _server_statement_definition_and_usage: 4528 4529``server`` Statement Definition and Usage 4530~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4531 4532The ``server`` statement defines characteristics to be associated with a 4533remote name server. If a prefix length is specified, then a range of 4534servers is covered. Only the most specific server clause applies, 4535regardless of the order in ``named.conf``. 4536 4537The ``server`` statement can occur at the top level of the configuration 4538file or inside a ``view`` statement. If a ``view`` statement contains 4539one or more ``server`` statements, only those apply to the view and any 4540top-level ones are ignored. If a view contains no ``server`` statements, 4541any top-level ``server`` statements are used as defaults. 4542 4543If a remote server is giving out bad data, marking it 4544as bogus prevents further queries to it. The default value of 4545``bogus`` is ``no``. 4546 4547The ``provide-ixfr`` clause determines whether the local server, acting 4548as primary, responds with an incremental zone transfer when the given 4549remote server, a secondary, requests it. If set to ``yes``, incremental 4550transfer is provided whenever possible. If set to ``no``, all 4551transfers to the remote server are non-incremental. If not set, the 4552value of the ``provide-ixfr`` option in the view or global options block 4553is used as a default. 4554 4555The ``request-ixfr`` clause determines whether the local server, acting 4556as a secondary, requests incremental zone transfers from the given 4557remote server, a primary. If not set, the value of the ``request-ixfr`` 4558option in the view or global options block is used as a default. It may 4559also be set in the zone block; if set there, it overrides the 4560global or view setting for that zone. 4561 4562IXFR requests to servers that do not support IXFR automatically 4563fall back to AXFR. Therefore, there is no need to manually list which 4564servers support IXFR and which ones do not; the global default of 4565``yes`` should always work. The purpose of the ``provide-ixfr`` and 4566``request-ixfr`` clauses is to make it possible to disable the use of 4567IXFR even when both primary and secondary claim to support it: for example, if 4568one of the servers is buggy and crashes or corrupts data when IXFR is 4569used. 4570 4571The ``request-expire`` clause determines whether the local server, when 4572acting as a secondary, requests the EDNS EXPIRE value. The EDNS EXPIRE 4573value indicates the remaining time before the zone data expires and 4574needs to be refreshed. This is used when a secondary server transfers 4575a zone from another secondary server; when transferring from the 4576primary, the expiration timer is set from the EXPIRE field of the SOA 4577record instead. The default is ``yes``. 4578 4579The ``edns`` clause determines whether the local server attempts to 4580use EDNS when communicating with the remote server. The default is 4581``yes``. 4582 4583The ``edns-udp-size`` option sets the EDNS UDP size that is advertised 4584by ``named`` when querying the remote server. Valid values are 512 to 45854096 bytes; values outside this range are silently adjusted to the 4586nearest value within it. This option is useful when 4587advertising a different value to this server than the value advertised 4588globally: for example, when there is a firewall at the remote site that 4589is blocking large replies. Note: currently, this sets a single UDP size 4590for all packets sent to the server; ``named`` does not deviate from this 4591value. This differs from the behavior of ``edns-udp-size`` in 4592``options`` or ``view`` statements, where it specifies a maximum value. 4593The ``server`` statement behavior may be brought into conformance with 4594the ``options``/``view`` behavior in future releases. 4595 4596The ``edns-version`` option sets the maximum EDNS VERSION that is 4597sent to the server(s) by the resolver. The actual EDNS version sent is 4598still subject to normal EDNS version-negotiation rules (see :rfc:`6891`), 4599the maximum EDNS version supported by the server, and any other 4600heuristics that indicate that a lower version should be sent. This 4601option is intended to be used when a remote server reacts badly to a 4602given EDNS version or higher; it should be set to the highest version 4603the remote server is known to support. Valid values are 0 to 255; higher 4604values are silently adjusted. This option is not needed until 4605higher EDNS versions than 0 are in use. 4606 4607The ``max-udp-size`` option sets the maximum EDNS UDP message size 4608``named`` sends. Valid values are 512 to 4096 bytes; values outside 4609this range are silently adjusted. This option is useful when 4610there is a firewall that is blocking large replies from 4611``named``. 4612 4613The ``padding`` option adds EDNS Padding options to outgoing messages, 4614increasing the packet size to a multiple of the specified block size. 4615Valid block sizes range from 0 (the default, which disables the use of 4616EDNS Padding) to 512 bytes. Larger values are reduced to 512, with a 4617logged warning. Note: this option is not currently compatible with no 4618TSIG or SIG(0), as the EDNS OPT record containing the padding would have 4619to be added to the packet after it had already been signed. 4620 4621The ``tcp-only`` option sets the transport protocol to TCP. The default 4622is to use the UDP transport and to fallback on TCP only when a truncated 4623response is received. 4624 4625The ``tcp-keepalive`` option adds EDNS TCP keepalive to messages sent 4626over TCP. Note that currently idle timeouts in responses are ignored. 4627 4628The server supports two zone transfer methods. The first, 4629``one-answer``, uses one DNS message per resource record transferred. 4630``many-answers`` packs as many resource records as possible into a single 4631message, which is more efficient. 4632It is possible to specify which method to use for a server via the 4633``transfer-format`` option; if not set there, the 4634``transfer-format`` specified by the ``options`` statement is used. 4635 4636``transfers`` is used to limit the number of concurrent inbound zone 4637transfers from the specified server. If no ``transfers`` clause is 4638specified, the limit is set according to the ``transfers-per-ns`` 4639option. 4640 4641The ``keys`` clause identifies a ``key_id`` defined by the ``key`` 4642statement, to be used for transaction security (see :ref:`tsig`) 4643when talking to the remote server. When a request is sent to the remote 4644server, a request signature is generated using the key specified 4645here and appended to the message. A request originating from the remote 4646server is not required to be signed by this key. 4647 4648Only a single key per server is currently supported. 4649 4650The ``transfer-source`` and ``transfer-source-v6`` clauses specify the 4651IPv4 and IPv6 source address, respectively, to be used for zone transfer with the 4652remote server. For an IPv4 remote server, only 4653``transfer-source`` can be specified. Similarly, for an IPv6 remote 4654server, only ``transfer-source-v6`` can be specified. For more details, 4655see the description of ``transfer-source`` and ``transfer-source-v6`` in 4656:ref:`zone_transfers`. 4657 4658The ``notify-source`` and ``notify-source-v6`` clauses specify the IPv4 4659and IPv6 source address, respectively, to be used for notify messages sent to remote 4660servers. For an IPv4 remote server, only ``notify-source`` 4661can be specified. Similarly, for an IPv6 remote server, only 4662``notify-source-v6`` can be specified. 4663 4664The ``query-source`` and ``query-source-v6`` clauses specify the IPv4 4665and IPv6 source address, respectively, to be used for queries sent to remote servers. 4666For an IPv4 remote server, only ``query-source`` can be 4667specified. Similarly, for an IPv6 remote server, only 4668``query-source-v6`` can be specified. 4669 4670The ``request-nsid`` clause determines whether the local server adds 4671an NSID EDNS option to requests sent to the server. This overrides 4672``request-nsid`` set at the view or option level. 4673 4674The ``send-cookie`` clause determines whether the local server adds 4675a COOKIE EDNS option to requests sent to the server. This overrides 4676``send-cookie`` set at the view or option level. The ``named`` server 4677may determine that COOKIE is not supported by the remote server and not 4678add a COOKIE EDNS option to requests. 4679 4680.. _statschannels: 4681 4682``statistics-channels`` Statement Grammar 4683~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4684 4685.. include:: ../misc/statistics-channels.grammar.rst 4686 4687.. _statistics_channels: 4688 4689``statistics-channels`` Statement Definition and Usage 4690~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4691 4692The ``statistics-channels`` statement declares communication channels to 4693be used by system administrators to get access to statistics information 4694on the name server. 4695 4696This statement is intended to be flexible to support multiple communication 4697protocols in the future, but currently only HTTP access is supported. It 4698requires that BIND 9 be compiled with libxml2 and/or json-c (also known 4699as libjson0); the ``statistics-channels`` statement is still accepted 4700even if it is built without the library, but any HTTP access fails 4701with an error. 4702 4703An ``inet`` control channel is a TCP socket listening at the specified 4704``ip_port`` on the specified ``ip_addr``, which can be an IPv4 or IPv6 4705address. An ``ip_addr`` of ``*`` (asterisk) is interpreted as the IPv4 4706wildcard address; connections are accepted on any of the system's 4707IPv4 addresses. To listen on the IPv6 wildcard address, use an 4708``ip_addr`` of ``::``. 4709 4710If no port is specified, port 80 is used for HTTP channels. The asterisk 4711(``*``) cannot be used for ``ip_port``. 4712 4713Attempts to open a statistics channel are restricted by the 4714optional ``allow`` clause. Connections to the statistics channel are 4715permitted based on the ``address_match_list``. If no ``allow`` clause is 4716present, ``named`` accepts connection attempts from any address. Since 4717the statistics may contain sensitive internal information, the source of 4718connection requests must be restricted appropriately so that only 4719trusted parties can access the statistics channel. 4720 4721Gathering data exposed by the statistics channel locks various subsystems in 4722``named``, which could slow down query processing if statistics data is 4723requested too often. 4724 4725An issue in the statistics channel would be considered a security issue 4726only if it could be exploited by unprivileged users circumventing the access 4727control list. In other words, any issue in the statistics channel that could be 4728used to access information unavailable otherwise, or to crash ``named``, is 4729not considered a security issue if it can be avoided through the 4730use of a secure configuration. 4731 4732If no ``statistics-channels`` statement is present, ``named`` does not 4733open any communication channels. 4734 4735The statistics are available in various formats and views, depending on 4736the URI used to access them. For example, if the statistics channel is 4737configured to listen on 127.0.0.1 port 8888, then the statistics are 4738accessible in XML format at http://127.0.0.1:8888/ or 4739http://127.0.0.1:8888/xml. A CSS file is included, which can format the 4740XML statistics into tables when viewed with a stylesheet-capable 4741browser, and into charts and graphs using the Google Charts API when 4742using a JavaScript-capable browser. 4743 4744Broken-out subsets of the statistics can be viewed at 4745http://127.0.0.1:8888/xml/v3/status (server uptime and last 4746reconfiguration time), http://127.0.0.1:8888/xml/v3/server (server and 4747resolver statistics), http://127.0.0.1:8888/xml/v3/zones (zone 4748statistics), http://127.0.0.1:8888/xml/v3/net (network status and socket 4749statistics), http://127.0.0.1:8888/xml/v3/mem (memory manager 4750statistics), http://127.0.0.1:8888/xml/v3/tasks (task manager 4751statistics), and http://127.0.0.1:8888/xml/v3/traffic (traffic sizes). 4752 4753The full set of statistics can also be read in JSON format at 4754http://127.0.0.1:8888/json, with the broken-out subsets at 4755http://127.0.0.1:8888/json/v1/status (server uptime and last 4756reconfiguration time), http://127.0.0.1:8888/json/v1/server (server and 4757resolver statistics), http://127.0.0.1:8888/json/v1/zones (zone 4758statistics), http://127.0.0.1:8888/json/v1/net (network status and 4759socket statistics), http://127.0.0.1:8888/json/v1/mem (memory manager 4760statistics), http://127.0.0.1:8888/json/v1/tasks (task manager 4761statistics), and http://127.0.0.1:8888/json/v1/traffic (traffic sizes). 4762 4763.. _trust_anchors: 4764 4765``trust-anchors`` Statement Grammar 4766~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4767 4768.. include:: ../misc/trust-anchors.grammar.rst 4769 4770.. _trust-anchors: 4771 4772``trust-anchors`` Statement Definition and Usage 4773~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4774 4775The ``trust-anchors`` statement defines DNSSEC trust anchors. DNSSEC is 4776described in :ref:`DNSSEC`. 4777 4778A trust anchor is defined when the public key or public key digest for a non-authoritative 4779zone is known but cannot be securely obtained through DNS, either 4780because it is the DNS root zone or because its parent zone is unsigned. 4781Once a key or digest has been configured as a trust anchor, it is treated as if it 4782has been validated and proven secure. 4783 4784The resolver attempts DNSSEC validation on all DNS data in subdomains of 4785configured trust anchors. Validation below specified names can be 4786temporarily disabled by using ``rndc nta``, or permanently disabled with 4787the ``validate-except`` option. 4788 4789All keys listed in ``trust-anchors``, and their corresponding zones, are 4790deemed to exist regardless of what parent zones say. Only keys 4791configured as trust anchors are used to validate the DNSKEY RRset for 4792the corresponding name. The parent's DS RRset is not used. 4793 4794``trust-anchors`` may be set at the top level of ``named.conf`` or within 4795a view. If it is set in both places, the configurations are additive; 4796keys defined at the top level are inherited by all views, but keys 4797defined in a view are only used within that view. 4798 4799The ``trust-anchors`` statement can contain 4800multiple trust-anchor entries, each consisting of a 4801domain name, followed by an "anchor type" keyword indicating 4802the trust anchor's format, followed by the key or digest data. 4803 4804If the anchor type is ``static-key`` or 4805``initial-key``, then it is followed with the 4806key's flags, protocol, and algorithm, plus the Base64 representation 4807of the public key data. This is identical to the text 4808representation of a DNSKEY record. Spaces, tabs, newlines, and 4809carriage returns are ignored in the key data, so the 4810configuration may be split into multiple lines. 4811 4812If the anchor type is ``static-ds`` or 4813``initial-ds``, it is followed with the 4814key tag, algorithm, digest type, and the hexadecimal 4815representation of the key digest. This is identical to the 4816text representation of a DS record. Spaces, tabs, newlines, 4817and carriage returns are ignored. 4818 4819Trust anchors configured with the 4820``static-key`` or ``static-ds`` 4821anchor types are immutable, while keys configured with 4822``initial-key`` or ``initial-ds`` 4823can be kept up-to-date automatically, without intervention from the resolver operator. 4824(``static-key`` keys are identical to keys configured using the 4825deprecated ``trusted-keys`` statement.) 4826 4827Suppose, for example, that a zone's key-signing key was compromised, and 4828the zone owner had to revoke and replace the key. A resolver which had 4829the original key 4830configured using ``static-key`` or 4831``static-ds`` would be unable to validate 4832this zone any longer; it would reply with a SERVFAIL response 4833code. This would continue until the resolver operator had 4834updated the ``trust-anchors`` statement with 4835the new key. 4836 4837If, however, the trust anchor had been configured using 4838``initial-key`` or ``initial-ds`` 4839instead, the zone owner could add a "stand-by" key to 4840the zone in advance. ``named`` would store 4841the stand-by key, and when the original key was revoked, 4842``named`` would be able to transition smoothly 4843to the new key. It would also recognize that the old key had 4844been revoked and cease using that key to validate answers, 4845minimizing the damage that the compromised key could do. 4846This is the process used to keep the ICANN root DNSSEC key 4847up-to-date. 4848 4849Whereas ``static-key`` and 4850``static-ds`` trust anchors continue 4851to be trusted until they are removed from 4852``named.conf``, an 4853``initial-key`` or ``initial-ds`` 4854is only trusted *once*: for as long as it 4855takes to load the managed key database and start the 4856:rfc:`5011` key maintenance process. 4857 4858It is not possible to mix static with initial trust anchors 4859for the same domain name. 4860 4861The first time ``named`` runs with an 4862``initial-key`` or ``initial-ds`` 4863configured in ``named.conf``, it fetches the 4864DNSKEY RRset directly from the zone apex, 4865and validates it 4866using the trust anchor specified in ``trust-anchors``. 4867If the DNSKEY RRset is validly signed by a key matching 4868the trust anchor, then it is used as the basis for a new 4869managed-keys database. 4870 4871From that point on, whenever ``named`` runs, it sees the ``initial-key`` or ``initial-ds`` 4872listed in ``trust-anchors``, checks to make sure :rfc:`5011` key maintenance 4873has already been initialized for the specified domain, and if so, 4874simply moves on. The key specified in the ``trust-anchors`` statement is 4875not used to validate answers; it is superseded by the key or keys stored 4876in the managed-keys database. 4877 4878The next time ``named`` runs after an ``initial-key`` or ``initial-ds`` has been *removed* 4879from the ``trust-anchors`` statement (or changed to a ``static-key`` or ``static-ds``), the 4880corresponding zone is removed from the managed-keys database, and 4881:rfc:`5011` key maintenance is no longer used for that domain. 4882 4883In the current implementation, the managed-keys database is stored as a 4884master-format zone file. 4885 4886On servers which do not use views, this file is named 4887``managed-keys.bind``. When views are in use, there is a separate 4888managed-keys database for each view; the filename is the view name 4889(or, if a view name contains characters which would make it illegal as a 4890filename, a hash of the view name), followed by the suffix ``.mkeys``. 4891 4892When the key database is changed, the zone is updated. As with any other 4893dynamic zone, changes are written into a journal file, e.g., 4894``managed-keys.bind.jnl`` or ``internal.mkeys.jnl``. Changes are 4895committed to the primary file as soon as possible afterward, 4896usually within 30 seconds. Whenever ``named`` is using 4897automatic key maintenance, the zone file and journal file can be 4898expected to exist in the working directory. (For this reason, among 4899others, the working directory should be always be writable by 4900``named``.) 4901 4902If the ``dnssec-validation`` option is set to ``auto``, ``named`` 4903automatically initializes an ``initial-key`` for the root zone. The key 4904that is used to initialize the key-maintenance process is stored in 4905``bind.keys``; the location of this file can be overridden with the 4906``bindkeys-file`` option. As a fallback in the event no ``bind.keys`` 4907can be found, the initializing key is also compiled directly into 4908``named``. 4909 4910.. _dnssec_policy_grammar: 4911 4912``dnssec-policy`` Statement Grammar 4913~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4914 4915.. include:: ../misc/dnssec-policy.grammar.rst 4916 4917.. _dnssec_policy: 4918 4919``dnssec-policy`` Statement Definition and Usage 4920~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4921 4922The ``dnssec-policy`` statement defines a key and signing policy (KASP) 4923for zones. 4924 4925A KASP determines how one or more zones are signed with DNSSEC. For 4926example, it specifies how often keys should roll, which cryptographic 4927algorithms to use, and how often RRSIG records need to be refreshed. 4928 4929Keys are not shared among zones, which means that one set of keys per 4930zone is generated even if they have the same policy. If multiple views 4931are configured with different versions of the same zone, each separate 4932version uses the same set of signing keys. 4933 4934Multiple key and signing policies can be configured. To attach a policy 4935to a zone, add a ``dnssec-policy`` option to the ``zone`` statement, 4936specifying the name of the policy that should be used. 4937 4938The ``dnssec-policy`` statement requires dynamic DNS to be set up, or 4939``inline-signing`` to be enabled. 4940 4941If ``inline-signing`` is enabled, this means that a signed version of the 4942zone is maintained separately and is written out to a different file on disk 4943(the zone's filename plus a ``.signed`` extension). 4944 4945If the zone is dynamic because it is configured with an ``update-policy`` or 4946``allow-update``, the DNSSEC records are written to the filename set in the 4947original zone's ``file``, unless ``inline-signing`` is explicitly set. 4948 4949Key rollover timing is computed for each key according to the key 4950lifetime defined in the KASP. The lifetime may be modified by zone TTLs 4951and propagation delays, to prevent validation failures. When a key 4952reaches the end of its lifetime, ``named`` generates and publishes a new 4953key automatically, then deactivates the old key and activates the new 4954one; finally, the old key is retired according to a computed schedule. 4955 4956Zone-signing key (ZSK) rollovers require no operator input. Key-signing 4957key (KSK) and combined-signing key (CSK) rollovers require action to be 4958taken to submit a DS record to the parent. Rollover timing for KSKs and 4959CSKs is adjusted to take into account delays in processing and 4960propagating DS updates. 4961 4962There are two predefined ``dnssec-policy`` names: ``none`` and 4963``default``. Setting a zone's policy to ``none`` is the same as not 4964setting ``dnssec-policy`` at all; the zone is not signed. Policy 4965``default`` causes the zone to be signed with a single combined-signing 4966key (CSK) using algorithm ECDSAP256SHA256; this key has an unlimited 4967lifetime. (A verbose copy of this policy may be found in the source 4968tree, in the file ``doc/misc/dnssec-policy.default.conf``.) 4969 4970.. note:: The default signing policy may change in future releases. 4971 This could require changes to a signing policy when upgrading to a 4972 new version of BIND. Check the release notes carefully when 4973 upgrading to be informed of such changes. To prevent policy changes 4974 on upgrade, use an explicitly defined ``dnssec-policy``, rather than 4975 ``default``. 4976 4977If a ``dnssec-policy`` statement is modified and the server restarted or 4978reconfigured, ``named`` attempts to change the policy smoothly from the 4979old one to the new. For example, if the key algorithm is changed, then 4980a new key is generated with the new algorithm, and the old algorithm is 4981retired when the existing key's lifetime ends. 4982 4983.. note:: Rolling to a new policy while another key rollover is already 4984 in progress is not yet supported, and may result in unexpected 4985 behavior. 4986 4987The following options can be specified in a ``dnssec-policy`` statement: 4988 4989 ``dnskey-ttl`` 4990 This indicates the TTL to use when generating DNSKEY resource 4991 records. The default is 1 hour (3600 seconds). 4992 4993 ``keys`` 4994 This is a list specifying the algorithms and roles to use when 4995 generating keys and signing the zone. Entries in this list do not 4996 represent specific DNSSEC keys, which may be changed on a regular 4997 basis, but the roles that keys play in the signing policy. For 4998 example, configuring a KSK of algorithm RSASHA256 ensures that the 4999 DNSKEY RRset always includes a key-signing key for that algorithm. 5000 5001 Here is an example (for illustration purposes only) of some possible 5002 entries in a ``keys`` list: 5003 5004 :: 5005 5006 keys { 5007 ksk key-directory lifetime unlimited algorithm rsasha256 2048; 5008 zsk lifetime P30D algorithm 8; 5009 csk lifetime P6MT12H3M15S algorithm ecdsa256; 5010 }; 5011 5012 This example specifies that three keys should be used in the zone. 5013 The first token determines which role the key plays in signing 5014 RRsets. If set to ``ksk``, then this is a key-signing key; it has 5015 the KSK flag set and is only used to sign DNSKEY, CDS, and CDNSKEY 5016 RRsets. If set to ``zsk``, this is a zone-signing key; the KSK flag 5017 is unset, and the key signs all RRsets *except* DNSKEY, CDS, and 5018 CDNSKEY. If set to ``csk``, the key has the KSK flag set and is 5019 used to sign all RRsets. 5020 5021 An optional second token determines where the key is stored. 5022 Currently, keys can only be stored in the configured 5023 ``key-directory``. This token may be used in the future to store 5024 keys in hardware security modules or separate directories. 5025 5026 The ``lifetime`` parameter specifies how long a key may be used 5027 before rolling over. In the example above, the first key has an 5028 unlimited lifetime, the second key may be used for 30 days, and the 5029 third key has a rather peculiar lifetime of 6 months, 12 hours, 3 5030 minutes, and 15 seconds. A lifetime of 0 seconds is the same as 5031 ``unlimited``. 5032 5033 Note that the lifetime of a key may be extended if retiring it too 5034 soon would cause validation failures. For example, if the key were 5035 configured to roll more frequently than its own TTL, its lifetime 5036 would automatically be extended to account for this. 5037 5038 The ``algorithm`` parameter specifies the key's algorithm, expressed 5039 either as a string ("rsasha256", "ecdsa384", etc.) or as a decimal 5040 number. An optional second parameter specifies the key's size in 5041 bits. If it is omitted, as shown in the example for the second and 5042 third keys, an appropriate default size for the algorithm is used. 5043 Each KSK/ZSK pair must have the same algorithm. A CSK combines the 5044 functionality of a ZSK and a KSK. 5045 5046 ``purge-keys`` 5047 This is the time after when DNSSEC keys that have been deleted from 5048 the zone can be removed from disk. If a key still determined to have 5049 presence (for example in some resolver cache), ``named`` will not 5050 remove the key files. 5051 5052 The default is ``P90D`` (90 days). Set this option to ``0`` to never 5053 purge deleted keys. 5054 5055 ``publish-safety`` 5056 This is a margin that is added to the pre-publication interval in 5057 rollover timing calculations, to give some extra time to cover 5058 unforeseen events. This increases the time between when keys are 5059 published and when they become active. The default is ``PT1H`` (1 5060 hour). 5061 5062 ``retire-safety`` 5063 This is a margin that is added to the post-publication interval in 5064 rollover timing calculations, to give some extra time to cover 5065 unforeseen events. This increases the time a key remains published 5066 after it is no longer active. The default is ``PT1H`` (1 hour). 5067 5068 ``signatures-refresh`` 5069 This determines how frequently an RRSIG record needs to be 5070 refreshed. The signature is renewed when the time until the 5071 expiration time is less than the specified interval. The default is 5072 ``P5D`` (5 days), meaning signatures that expire in 5 days or sooner 5073 are refreshed. 5074 5075 ``signatures-validity`` 5076 This indicates the validity period of an RRSIG record (subject to 5077 inception offset and jitter). The default is ``P2W`` (2 weeks). 5078 5079 ``signatures-validity-dnskey`` 5080 This is similar to ``signatures-validity``, but for DNSKEY records. 5081 The default is ``P2W`` (2 weeks). 5082 5083 ``max-zone-ttl`` 5084 5085 This specifies the maximum permissible TTL value for the zone. When 5086 a zone file is loaded, any record encountered with a TTL higher than 5087 ``max-zone-ttl`` causes the zone to be rejected. 5088 5089 This ensures that when rolling to a new DNSKEY, the old key will remain 5090 available until RRSIG records have expired from caches. The 5091 ``max-zone-ttl`` option guarantees that the largest TTL in the 5092 zone is no higher than a known and predictable value. 5093 5094 .. note:: Because ``map``-format files load directly into memory, 5095 this option cannot be used with them. 5096 5097 The default value ``PT24H`` (24 hours). A value of zero is treated 5098 as if the default value were in use. 5099 5100 5101 ``nsec3param`` 5102 Use NSEC3 instead of NSEC, and optionally set the NSEC3 parameters. 5103 5104 Here is an example of an ``nsec3`` configuration: 5105 5106 :: 5107 5108 nsec3param iterations 5 optout no salt-length 8; 5109 5110 The default is to use NSEC. The ``iterations``, ``optout``, and 5111 ``salt-length`` parts are optional, but if not set, the values in 5112 the example above are the default NSEC3 parameters. Note that the 5113 specific salt string is not specified by the user; :iscman:`named` creates a salt 5114 of the indicated length. 5115 5116 .. warning:: 5117 Do not use extra :term:`iterations <Iterations>`, :term:`salt <Salt>`, and 5118 :term:`opt-out <Opt-out>` unless their implications are fully understood. 5119 A higher number of iterations causes interoperability problems and opens 5120 servers to CPU-exhausting DoS attacks. 5121 5122 ``zone-propagation-delay`` 5123 This is the expected propagation delay from the time when a zone is 5124 first updated to the time when the new version of the zone is served 5125 by all secondary servers. The default is ``PT5M`` (5 minutes). 5126 5127 ``parent-ds-ttl`` 5128 This is the TTL of the DS RRset that the parent zone uses. The 5129 default is ``P1D`` (1 day). 5130 5131 ``parent-propagation-delay`` 5132 This is the expected propagation delay from the time when the parent 5133 zone is updated to the time when the new version is served by all of 5134 the parent zone's name servers. The default is ``PT1H`` (1 hour). 5135 5136Automated KSK Rollovers 5137^^^^^^^^^^^^^^^^^^^^^^^ 5138 5139BIND has mechanisms in place to facilitate automated KSK rollovers. It 5140publishes CDS and CDNSKEY records that can be used by the parent zone to 5141publish or withdraw the zone's DS records. BIND will query the parental 5142agents to see if the new DS is actually published before withdrawing the 5143old DNSSEC key. 5144 5145 .. note:: 5146 The DS response is not validated so it is recommended to set up a 5147 trust relationship with the parental agent. For example, use TSIG to 5148 authenticate the parental agent, or point to a validating resolver. 5149 5150The following options apply to DS queries sent to ``parental-agents``: 5151 5152``parental-source`` 5153 ``parental-source`` determines which local source address, and optionally 5154 UDP port, is used to send parental DS queries. This statement sets the 5155 ``parental-source`` for all zones, but can be overridden on a per-zone or 5156 per-view basis by including a ``parental-source`` statement within the 5157 ``zone`` or ``view`` block in the configuration file. 5158 5159 .. warning:: Specifying a single port is discouraged, as it removes a layer of 5160 protection against spoofing errors. 5161 5162 .. warning:: The configured ``port`` must not be same as the listening port. 5163 5164``parental-source-v6`` 5165 This option acts like ``parental-source``, but applies to parental DS 5166 queries sent to IPv6 addresses. 5167 5168.. _managed-keys: 5169 5170``managed-keys`` Statement Grammar 5171~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5172 5173.. include:: ../misc/managed-keys.grammar.rst 5174 5175.. _managed_keys: 5176 5177``managed-keys`` Statement Definition and Usage 5178~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5179 5180The ``managed-keys`` statement has been 5181deprecated in favor of :ref:`trust_anchors` 5182with the ``initial-key`` keyword. 5183 5184.. _trusted-keys: 5185 5186``trusted-keys`` Statement Grammar 5187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5188 5189.. include:: ../misc/trusted-keys.grammar.rst 5190 5191.. _trusted_keys: 5192 5193``trusted-keys`` Statement Definition and Usage 5194~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5195 5196The ``trusted-keys`` statement has been deprecated in favor of 5197:ref:`trust_anchors` with the ``static-key`` keyword. 5198 5199.. _view_statement_grammar: 5200 5201``view`` Statement Grammar 5202~~~~~~~~~~~~~~~~~~~~~~~~~~ 5203 5204:: 5205 5206 view view_name [ class ] { 5207 match-clients { address_match_list } ; 5208 match-destinations { address_match_list } ; 5209 match-recursive-only yes_or_no ; 5210 [ view_option ; ... ] 5211 [ zone_statement ; ... ] 5212 } ; 5213 5214.. _view_statement: 5215 5216``view`` Statement Definition and Usage 5217~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5218 5219The ``view`` statement is a powerful feature of BIND 9 that lets a name 5220server answer a DNS query differently depending on who is asking. It is 5221particularly useful for implementing split DNS setups without having to 5222run multiple servers. 5223 5224Each ``view`` statement defines a view of the DNS namespace that is 5225seen by a subset of clients. A client matches a view if its source IP 5226address matches the ``address_match_list`` of the view's 5227``match-clients`` clause, and its destination IP address matches the 5228``address_match_list`` of the view's ``match-destinations`` clause. If 5229not specified, both ``match-clients`` and ``match-destinations`` default 5230to matching all addresses. In addition to checking IP addresses, 5231``match-clients`` and ``match-destinations`` can also take ``keys`` 5232which provide an mechanism for the client to select the view. A view can 5233also be specified as ``match-recursive-only``, which means that only 5234recursive requests from matching clients match that view. The order 5235of the ``view`` statements is significant; a client request is 5236resolved in the context of the first ``view`` that it matches. 5237 5238Zones defined within a ``view`` statement are only accessible to 5239clients that match the ``view``. By defining a zone of the same name in 5240multiple views, different zone data can be given to different clients: 5241for example, "internal" and "external" clients in a split DNS setup. 5242 5243Many of the options given in the ``options`` statement can also be used 5244within a ``view`` statement, and then apply only when resolving queries 5245with that view. When no view-specific value is given, the value in the 5246``options`` statement is used as a default. Also, zone options can have 5247default values specified in the ``view`` statement; these view-specific 5248defaults take precedence over those in the ``options`` statement. 5249 5250Views are class-specific. If no class is given, class IN is assumed. 5251Note that all non-IN views must contain a hint zone, since only the IN 5252class has compiled-in default hints. 5253 5254If there are no ``view`` statements in the config file, a default view 5255that matches any client is automatically created in class IN. Any 5256``zone`` statements specified on the top level of the configuration file 5257are considered to be part of this default view, and the ``options`` 5258statement applies to the default view. If any explicit ``view`` 5259statements are present, all ``zone`` statements must occur inside 5260``view`` statements. 5261 5262Here is an example of a typical split DNS setup implemented using 5263``view`` statements: 5264 5265:: 5266 5267 view "internal" { 5268 // This should match our internal networks. 5269 match-clients { 10.0.0.0/8; }; 5270 5271 // Provide recursive service to internal 5272 // clients only. 5273 recursion yes; 5274 5275 // Provide a complete view of the example.com 5276 // zone including addresses of internal hosts. 5277 zone "example.com" { 5278 type primary; 5279 file "example-internal.db"; 5280 }; 5281 }; 5282 5283 view "external" { 5284 // Match all clients not matched by the 5285 // previous view. 5286 match-clients { any; }; 5287 5288 // Refuse recursive service to external clients. 5289 recursion no; 5290 5291 // Provide a restricted view of the example.com 5292 // zone containing only publicly accessible hosts. 5293 zone "example.com" { 5294 type primary; 5295 file "example-external.db"; 5296 }; 5297 }; 5298 5299.. _zone_statement_grammar: 5300 5301``zone`` Statement Grammar 5302~~~~~~~~~~~~~~~~~~~~~~~~~~ 5303 5304.. include:: ../misc/master.zoneopt.rst 5305.. include:: ../misc/slave.zoneopt.rst 5306.. include:: ../misc/mirror.zoneopt.rst 5307.. include:: ../misc/hint.zoneopt.rst 5308.. include:: ../misc/stub.zoneopt.rst 5309.. include:: ../misc/static-stub.zoneopt.rst 5310.. include:: ../misc/forward.zoneopt.rst 5311.. include:: ../misc/redirect.zoneopt.rst 5312.. include:: ../misc/delegation-only.zoneopt.rst 5313.. include:: ../misc/in-view.zoneopt.rst 5314 5315.. _zone_statement: 5316 5317``zone`` Statement Definition and Usage 5318~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5319 5320.. _zone_types: 5321 5322Zone Types 5323^^^^^^^^^^ 5324 5325The ``type`` keyword is required for the ``zone`` configuration unless 5326it is an ``in-view`` configuration. Its acceptable values are: 5327``primary`` (or ``master``), ``secondary`` (or ``slave``), ``mirror``, 5328``hint``, ``stub``, ``static-stub``, ``forward``, ``redirect``, 5329or ``delegation-only``. 5330 5331``primary`` 5332 A primary zone has a master copy of the data for the zone and is able 5333 to provide authoritative answers for it. Type ``master`` is a synonym 5334 for ``primary``. 5335 5336``secondary`` 5337 A secondary zone is a replica of a primary zone. Type ``slave`` is a 5338 synonym for ``secondary``. The ``primaries`` list specifies one or more IP 5339 addresses of primary servers that the secondary contacts to update 5340 its copy of the zone. Primaries list elements can 5341 also be names of other primaries lists. By default, 5342 transfers are made from port 53 on the servers; 5343 this can be changed for all servers by specifying 5344 a port number before the list of IP addresses, 5345 or on a per-server basis after the IP address. 5346 Authentication to the primary can also be done with 5347 per-server TSIG keys. If a file is specified, then the 5348 replica is written to this file 5349 whenever the zone 5350 is changed, and reloaded from this file on a server 5351 restart. Use of a file is recommended, since it 5352 often speeds server startup and eliminates a 5353 needless waste of bandwidth. Note that for large 5354 numbers (in the tens or hundreds of thousands) of 5355 zones per server, it is best to use a two-level 5356 naming scheme for zone filenames. For example, 5357 a secondary server for the zone 5358 ``example.com`` might place 5359 the zone contents into a file called 5360 ``ex/example.com``, where 5361 ``ex/`` is just the first two 5362 letters of the zone name. (Most operating systems 5363 behave very slowly if there are 100000 files in a single directory.) 5364 5365``mirror`` 5366 A mirror zone is similar to a zone of type ``secondary``, except its 5367 data is subject to DNSSEC validation before being used in answers. 5368 Validation is applied to the entire zone during the zone transfer 5369 process, and again when the zone file is loaded from disk upon 5370 restarting ``named``. If validation of a new version of a mirror zone 5371 fails, a retransfer is scheduled; in the meantime, the most recent 5372 correctly validated version of that zone is used until it either 5373 expires or a newer version validates correctly. If no usable zone 5374 data is available for a mirror zone, due to either transfer failure 5375 or expiration, traditional DNS recursion is used to look up the 5376 answers instead. Mirror zones cannot be used in a view that does not 5377 have recursion enabled. 5378 5379 Answers coming from a mirror zone look almost exactly like answers 5380 from a zone of type ``secondary``, with the notable exceptions that 5381 the AA bit ("authoritative answer") is not set, and the AD bit 5382 ("authenticated data") is. 5383 5384 Mirror zones are intended to be used to set up a fast local copy of 5385 the root zone (see :rfc:`8806`). A default list of primary servers 5386 for the IANA root zone is built into ``named``, so its mirroring can 5387 be enabled using the following configuration: 5388 5389 :: 5390 5391 zone "." { 5392 type mirror; 5393 }; 5394 5395 Mirror zone validation always happens for the entire zone contents. 5396 This ensures that each version of the zone used by the resolver is 5397 fully self-consistent with respect to DNSSEC. For incoming mirror 5398 zone IXFRs, every revision of the zone contained in the IXFR sequence 5399 is validated independently, in the order in which the zone revisions 5400 appear on the wire. For this reason, it might be useful to force use 5401 of AXFR for mirror zones by setting ``request-ixfr no;`` for the 5402 relevant zone (or view). Other, more efficient zone verification 5403 methods may be added in the future. 5404 5405 To make mirror zone contents persist between ``named`` restarts, use 5406 the :ref:`file <file-option>` option. 5407 5408 Mirroring a zone other than root requires an explicit list of primary 5409 servers to be provided using the ``primaries`` option (see 5410 :ref:`primaries_grammar` for details), and a key-signing key (KSK) 5411 for the specified zone to be explicitly configured as a trust anchor 5412 (see :ref:`trust-anchors`). 5413 5414 When configuring NOTIFY for a mirror zone, only ``notify no;`` and 5415 ``notify explicit;`` can be used at the zone level; any other 5416 ``notify`` setting at the zone level is a configuration error. Using 5417 any other ``notify`` setting at the ``options`` or ``view`` level 5418 causes that setting to be overridden with ``notify explicit;`` for 5419 the mirror zone. The global default for the ``notify`` option is 5420 ``yes``, so mirror zones are by default configured with ``notify 5421 explicit;``. 5422 5423 Outgoing transfers of mirror zones are disabled by default but may be 5424 enabled using :ref:`allow-transfer <allow-transfer-access>`. 5425 5426 .. note:: 5427 Use of this zone type with any zone other than the root should be 5428 considered *experimental* and may cause performance issues, 5429 especially for zones that are large and/or frequently updated. 5430 5431``hint`` 5432 The initial set of root name servers is specified using a hint zone. 5433 When the server starts, it uses the root hints to find a root name 5434 server and get the most recent list of root name servers. If no hint zone 5435 is specified for class IN, the server uses a compiled-in default set of 5436 root servers hints. Classes other than IN have no built-in default hints. 5437 5438``stub`` 5439 A stub zone is similar to a secondary zone, except that it replicates only 5440 the NS records of a primary zone instead of the entire zone. Stub zones 5441 are not a standard part of the DNS; they are a feature specific to the 5442 BIND implementation. 5443 5444 Stub zones can be used to eliminate the need for a glue NS record in a parent 5445 zone, at the expense of maintaining a stub zone entry and a set of name 5446 server addresses in ``named.conf``. This usage is not recommended for 5447 new configurations, and BIND 9 supports it only in a limited way. If a BIND 9 5448 primary, serving a parent zone, has child stub 5449 zones configured, all the secondary servers for the parent zone also need to 5450 have the same child stub zones configured. 5451 5452 Stub zones can also be used as a way to force the resolution of a given 5453 domain to use a particular set of authoritative servers. For example, the 5454 caching name servers on a private network using :rfc:`1918` addressing may be 5455 configured with stub zones for ``10.in-addr.arpa`` to use a set of 5456 internal name servers as the authoritative servers for that domain. 5457 5458``static-stub`` 5459 A static-stub zone is similar to a stub zone, with the following 5460 exceptions: the zone data is statically configured, rather than 5461 transferred from a primary server; and when recursion is necessary for a query 5462 that matches a static-stub zone, the locally configured data (name server 5463 names and glue addresses) is always used, even if different authoritative 5464 information is cached. 5465 5466 Zone data is configured via the ``server-addresses`` and ``server-names`` 5467 zone options. 5468 5469 The zone data is maintained in the form of NS and (if necessary) glue A or 5470 AAAA RRs internally, which can be seen by dumping zone databases with 5471 ``rndc dumpdb -all``. The configured RRs are considered local configuration 5472 parameters rather than public data. Non-recursive queries (i.e., those 5473 with the RD bit off) to a static-stub zone are therefore prohibited and 5474 are responded to with REFUSED. 5475 5476 Since the data is statically configured, no zone maintenance action takes 5477 place for a static-stub zone. For example, there is no periodic refresh 5478 attempt, and an incoming notify message is rejected with an rcode 5479 of NOTAUTH. 5480 5481 Each static-stub zone is configured with internally generated NS and (if 5482 necessary) glue A or AAAA RRs. 5483 5484``forward`` 5485 A forward zone is a way to configure forwarding on a per-domain basis. 5486 A ``zone`` statement of type ``forward`` can contain a ``forward`` and/or 5487 ``forwarders`` statement, which applies to queries within the domain 5488 given by the zone name. If no ``forwarders`` statement is present, or an 5489 empty list for ``forwarders`` is given, then no forwarding is done 5490 for the domain, canceling the effects of any forwarders in the ``options`` 5491 statement. Thus, to use this type of zone to change the 5492 behavior of the global ``forward`` option (that is, "forward first" to, 5493 then "forward only", or vice versa), but use the same servers as set 5494 globally, re-specify the global forwarders. 5495 5496``redirect`` 5497 Redirect zones are used to provide answers to queries when normal 5498 resolution would result in NXDOMAIN being returned. Only one redirect zone 5499 is supported per view. ``allow-query`` can be used to restrict which 5500 clients see these answers. 5501 5502 If the client has requested DNSSEC records (DO=1) and the NXDOMAIN response 5503 is signed, no substitution occurs. 5504 5505 To redirect all NXDOMAIN responses to 100.100.100.2 and 5506 2001:ffff:ffff::100.100.100.2, configure a type ``redirect`` zone 5507 named ".", with the zone file containing wildcard records that point to 5508 the desired addresses: ``*. IN A 100.100.100.2`` and 5509 ``*. IN AAAA 2001:ffff:ffff::100.100.100.2``. 5510 5511 As another example, to redirect all Spanish names (under .ES), use similar entries 5512 but with the names ``*.ES.`` instead of ``*.``. To redirect all commercial 5513 Spanish names (under COM.ES), use wildcard entries 5514 called ``*.COM.ES.``. 5515 5516 Note that the redirect zone supports all possible types; it is not 5517 limited to A and AAAA records. 5518 5519 If a redirect zone is configured with a ``primaries`` option, then it is 5520 transferred in as if it were a secondary zone. Otherwise, it is loaded from a 5521 file as if it were a primary zone. 5522 5523 Because redirect zones are not referenced directly by name, they are not 5524 kept in the zone lookup table with normal primary and secondary zones. To reload 5525 a redirect zone, use ``rndc reload -redirect``; to retransfer a 5526 redirect zone configured as a secondary, use ``rndc retransfer -redirect``. 5527 When using ``rndc reload`` without specifying a zone name, redirect 5528 zones are reloaded along with other zones. 5529 5530``delegation-only`` 5531 This zone type is used to enforce the delegation-only status of infrastructure 5532 zones (e.g., COM, NET, ORG). Any answer that is received without an 5533 explicit or implicit delegation in the authority section is treated 5534 as NXDOMAIN. This does not apply to the zone apex, and should not be 5535 applied to leaf zones. 5536 5537 ``delegation-only`` has no effect on answers received from forwarders. 5538 5539 See caveats in :ref:`root-delegation-only <root-delegation-only>`. 5540 5541``in-view`` 5542 When using multiple views, a ``primary`` or ``secondary`` zone configured 5543 in one view can be referenced in a subsequent view. This allows both views 5544 to use the same zone without the overhead of loading it more than once. This 5545 is configured using a ``zone`` statement, with an ``in-view`` option 5546 specifying the view in which the zone is defined. A ``zone`` statement 5547 containing ``in-view`` does not need to specify a type, since that is part 5548 of the zone definition in the other view. 5549 5550 See :ref:`multiple_views` for more information. 5551 5552Class 5553^^^^^ 5554 5555The zone's name may optionally be followed by a class. If a class is not 5556specified, class ``IN`` (for ``Internet``) is assumed. This is correct 5557for the vast majority of cases. 5558 5559The ``hesiod`` class is named for an information service from MIT's 5560Project Athena. It was used to share information about various systems 5561databases, such as users, groups, printers, and so on. The keyword ``HS`` 5562is a synonym for hesiod. 5563 5564Another MIT development is Chaosnet, a LAN protocol created in the 5565mid-1970s. Zone data for it can be specified with the ``CHAOS`` class. 5566 5567.. _zone_options: 5568 5569Zone Options 5570^^^^^^^^^^^^ 5571 5572``allow-notify`` 5573 See the description of ``allow-notify`` in :ref:`access_control`. 5574 5575``allow-query`` 5576 See the description of ``allow-query`` in :ref:`access_control`. 5577 5578``allow-query-on`` 5579 See the description of ``allow-query-on`` in :ref:`access_control`. 5580 5581``allow-transfer`` 5582 See the description of ``allow-transfer`` in :ref:`access_control`. 5583 5584``allow-update`` 5585 See the description of ``allow-update`` in :ref:`access_control`. 5586 5587``update-policy`` 5588 This specifies a "Simple Secure Update" policy. See :ref:`dynamic_update_policies`. 5589 5590``allow-update-forwarding`` 5591 See the description of ``allow-update-forwarding`` in :ref:`access_control`. 5592 5593``also-notify`` 5594 This option is only meaningful if ``notify`` is active for this zone. The set of 5595 machines that receive a ``DNS NOTIFY`` message for this zone is 5596 made up of all the listed name servers (other than the primary) 5597 for the zone, plus any IP addresses specified with 5598 ``also-notify``. A port may be specified with each ``also-notify`` 5599 address to send the notify messages to a port other than the default 5600 of 53. A TSIG key may also be specified to cause the ``NOTIFY`` to be 5601 signed by the given key. ``also-notify`` is not meaningful for stub 5602 zones. The default is the empty list. 5603 5604``check-names`` 5605 This option is used to restrict the character set and syntax of 5606 certain domain names in primary files and/or DNS responses received 5607 from the network. The default varies according to zone type. For 5608 ``primary`` zones the default is ``fail``; for ``secondary`` zones the 5609 default is ``warn``. It is not implemented for ``hint`` zones. 5610 5611``check-mx`` 5612 See the description of ``check-mx`` in :ref:`boolean_options`. 5613 5614``check-spf`` 5615 See the description of ``check-spf`` in :ref:`boolean_options`. 5616 5617``check-wildcard`` 5618 See the description of ``check-wildcard`` in :ref:`boolean_options`. 5619 5620``check-integrity`` 5621 See the description of ``check-integrity`` in :ref:`boolean_options`. 5622 5623``check-sibling`` 5624 See the description of ``check-sibling`` in :ref:`boolean_options`. 5625 5626``zero-no-soa-ttl`` 5627 See the description of ``zero-no-soa-ttl`` in :ref:`boolean_options`. 5628 5629``update-check-ksk`` 5630 See the description of ``update-check-ksk`` in :ref:`boolean_options`. 5631 5632``dnssec-loadkeys-interval`` 5633 See the description of ``dnssec-loadkeys-interval`` in :ref:`options`. 5634 5635``dnssec-update-mode`` 5636 See the description of ``dnssec-update-mode`` in :ref:`options`. 5637 5638``dnssec-dnskey-kskonly`` 5639 See the description of ``dnssec-dnskey-kskonly`` in :ref:`boolean_options`. 5640 5641``try-tcp-refresh`` 5642 See the description of ``try-tcp-refresh`` in :ref:`boolean_options`. 5643 5644``database`` 5645 This specifies the type of database to be used to store the zone data. 5646 The string following the ``database`` keyword is interpreted as a 5647 list of whitespace-delimited words. The first word identifies the 5648 database type, and any subsequent words are passed as arguments to 5649 the database to be interpreted in a way specific to the database 5650 type. 5651 5652 The default is ``rbt``, BIND 9's native in-memory red-black tree 5653 database. This database does not take arguments. 5654 5655 Other values are possible if additional database drivers have been 5656 linked into the server. Some sample drivers are included with the 5657 distribution but none are linked in by default. 5658 5659``dialup`` 5660 See the description of ``dialup`` in :ref:`boolean_options`. 5661 5662``delegation-only`` 5663 This flag only applies to forward, hint, and stub zones. If set to 5664 ``yes``, then the zone is treated as if it is also a 5665 delegation-only type zone. 5666 5667 See caveats in :ref:`root-delegation-only <root-delegation-only>`. 5668 5669.. _file-option: 5670 5671``file`` 5672 This sets the zone's filename. In ``primary``, ``hint``, and ``redirect`` 5673 zones which do not have ``primaries`` defined, zone data is loaded from 5674 this file. In ``secondary``, ``mirror``, ``stub``, and ``redirect`` zones 5675 which do have ``primaries`` defined, zone data is retrieved from 5676 another server and saved in this file. This option is not applicable 5677 to other zone types. 5678 5679``forward`` 5680 This option is only meaningful if the zone has a forwarders list. The ``only`` value 5681 causes the lookup to fail after trying the forwarders and getting no 5682 answer, while ``first`` allows a normal lookup to be tried. 5683 5684``forwarders`` 5685 This is used to override the list of global forwarders. If it is not 5686 specified in a zone of type ``forward``, no forwarding is done for 5687 the zone and the global options are not used. 5688 5689``journal`` 5690 This allows the default journal's filename to be overridden. The default is 5691 the zone's filename with "``.jnl``" appended. This is applicable to 5692 ``primary`` and ``secondary`` zones. 5693 5694``max-ixfr-ratio`` 5695 See the description of ``max-ixfr-ratio`` in :ref:`options`. 5696 5697``max-journal-size`` 5698 See the description of ``max-journal-size`` in :ref:`server_resource_limits`. 5699 5700``max-records`` 5701 See the description of ``max-records`` in :ref:`server_resource_limits`. 5702 5703``max-transfer-time-in`` 5704 See the description of ``max-transfer-time-in`` in :ref:`zone_transfers`. 5705 5706``max-transfer-idle-in`` 5707 See the description of ``max-transfer-idle-in`` in :ref:`zone_transfers`. 5708 5709``max-transfer-time-out`` 5710 See the description of ``max-transfer-time-out`` in :ref:`zone_transfers`. 5711 5712``max-transfer-idle-out`` 5713 See the description of ``max-transfer-idle-out`` in :ref:`zone_transfers`. 5714 5715``notify`` 5716 See the description of ``notify`` in :ref:`boolean_options`. 5717 5718``notify-delay`` 5719 See the description of ``notify-delay`` in :ref:`tuning`. 5720 5721``notify-to-soa`` 5722 See the description of ``notify-to-soa`` in :ref:`boolean_options`. 5723 5724``zone-statistics`` 5725 See the description of ``zone-statistics`` in :ref:`options`. 5726 5727``server-addresses`` 5728 This option is only meaningful for static-stub zones. This is a list of IP addresses 5729 to which queries should be sent in recursive resolution for the zone. 5730 A non-empty list for this option internally configures the apex 5731 NS RR with associated glue A or AAAA RRs. 5732 5733 For example, if "example.com" is configured as a static-stub zone 5734 with 192.0.2.1 and 2001:db8::1234 in a ``server-addresses`` option, 5735 the following RRs are internally configured: 5736 5737 :: 5738 5739 example.com. NS example.com. 5740 example.com. A 192.0.2.1 5741 example.com. AAAA 2001:db8::1234 5742 5743 These records are used internally to resolve names under the 5744 static-stub zone. For instance, if the server receives a query for 5745 "www.example.com" with the RD bit on, the server initiates 5746 recursive resolution and sends queries to 192.0.2.1 and/or 5747 2001:db8::1234. 5748 5749``server-names`` 5750 This option is only meaningful for static-stub zones. This is a list of domain names 5751 of name servers that act as authoritative servers of the static-stub 5752 zone. These names are resolved to IP addresses when ``named`` 5753 needs to send queries to these servers. For this supplemental 5754 resolution to be successful, these names must not be a subdomain of the 5755 origin name of the static-stub zone. That is, when "example.net" is the 5756 origin of a static-stub zone, "ns.example" and "master.example.com" 5757 can be specified in the ``server-names`` option, but "ns.example.net" 5758 cannot; it is rejected by the configuration parser. 5759 5760 A non-empty list for this option internally configures the apex 5761 NS RR with the specified names. For example, if "example.com" is 5762 configured as a static-stub zone with "ns1.example.net" and 5763 "ns2.example.net" in a ``server-names`` option, the following RRs 5764 are internally configured: 5765 5766 :: 5767 5768 example.com. NS ns1.example.net. 5769 example.com. NS ns2.example.net. 5770 5771 These records are used internally to resolve names under the 5772 static-stub zone. For instance, if the server receives a query for 5773 "www.example.com" with the RD bit on, the server initiates recursive 5774 resolution, resolves "ns1.example.net" and/or "ns2.example.net" to IP 5775 addresses, and then sends queries to one or more of these addresses. 5776 5777``sig-validity-interval`` 5778 See the description of ``sig-validity-interval`` in :ref:`tuning`. 5779 5780``sig-signing-nodes`` 5781 See the description of ``sig-signing-nodes`` in :ref:`tuning`. 5782 5783``sig-signing-signatures`` 5784 See the description of ``sig-signing-signatures`` in 5785 :ref:`tuning`. 5786 5787``sig-signing-type`` 5788 See the description of ``sig-signing-type`` in :ref:`tuning`. 5789 5790``transfer-source`` 5791 See the description of ``transfer-source`` in :ref:`zone_transfers`. 5792 5793``transfer-source-v6`` 5794 See the description of ``transfer-source-v6`` in :ref:`zone_transfers`. 5795 5796``alt-transfer-source`` 5797 See the description of ``alt-transfer-source`` in :ref:`zone_transfers`. 5798 5799``alt-transfer-source-v6`` 5800 See the description of ``alt-transfer-source-v6`` in :ref:`zone_transfers`. 5801 5802``use-alt-transfer-source`` 5803 See the description of ``use-alt-transfer-source`` in :ref:`zone_transfers`. 5804 5805``notify-source`` 5806 See the description of ``notify-source`` in :ref:`zone_transfers`. 5807 5808``notify-source-v6`` 5809 See the description of ``notify-source-v6`` in :ref:`zone_transfers`. 5810 5811``min-refresh-time``; ``max-refresh-time``; ``min-retry-time``; ``max-retry-time`` 5812 See the descriptions in :ref:`tuning`. 5813 5814``ixfr-from-differences`` 5815 See the description of ``ixfr-from-differences`` in :ref:`boolean_options`. 5816 (Note that the ``ixfr-from-differences`` choices of ``primary`` and ``secondary`` 5817 are not available at the zone level.) 5818 5819``key-directory`` 5820 See the description of ``key-directory`` in :ref:`options`. 5821 5822``auto-dnssec`` 5823 See the description of ``auto-dnssec`` in :ref:`options`. 5824 5825``serial-update-method`` 5826 See the description of ``serial-update-method`` in :ref:`options`. 5827 5828``inline-signing`` 5829 If ``yes``, BIND 9 maintains a separate signed version of the zone. 5830 An unsigned zone is transferred in or loaded from disk and the signed 5831 version of the zone is served with, possibly, a different serial 5832 number. The signed version of the zone is stored in a file that is 5833 the zone's filename (set in ``file``) with a ``.signed`` extension. 5834 This behavior is disabled by default. 5835 5836``multi-master`` 5837 See the description of ``multi-master`` in :ref:`boolean_options`. 5838 5839``masterfile-format`` 5840 See the description of ``masterfile-format`` in :ref:`tuning`. 5841 5842``max-zone-ttl`` 5843 See the description of ``max-zone-ttl`` in :ref:`options`. 5844 5845``dnssec-secure-to-insecure`` 5846 See the description of ``dnssec-secure-to-insecure`` in :ref:`boolean_options`. 5847 5848.. _dynamic_update_policies: 5849 5850Dynamic Update Policies 5851^^^^^^^^^^^^^^^^^^^^^^^ 5852 5853BIND 9 supports two methods of granting clients the right to 5854perform dynamic updates to a zone: 5855 5856- ``allow-update`` - a simple access control list 5857- ``update-policy`` - fine-grained access control 5858 5859In both cases, BIND 9 writes the updates to the zone's filename 5860set in ``file``. 5861 5862In the case of a DNSSEC zone, DNSSEC records are also written to 5863the zone's filename, unless ``inline-signing`` is enabled. 5864 5865 .. note:: The zone file can no longer be manually updated while ``named`` 5866 is running; it is now necessary to perform :option:`rndc freeze`, edit, 5867 and then perform :option:`rndc thaw`. Comments and formatting 5868 in the zone file are lost when dynamic updates occur. 5869 5870The ``allow-update`` clause is a simple access control list. Any client 5871that matches the ACL is granted permission to update any record in the 5872zone. 5873 5874The ``update-policy`` clause allows more fine-grained control over which 5875updates are allowed. It specifies a set of rules, in which each rule 5876either grants or denies permission for one or more names in the zone to 5877be updated by one or more identities. Identity is determined by the key 5878that signed the update request, using either TSIG or SIG(0). In most 5879cases, ``update-policy`` rules only apply to key-based identities. There 5880is no way to specify update permissions based on the client source address. 5881 5882``update-policy`` rules are only meaningful for zones of type 5883``primary``, and are not allowed in any other zone type. It is a 5884configuration error to specify both ``allow-update`` and 5885``update-policy`` at the same time. 5886 5887A pre-defined ``update-policy`` rule can be switched on with the command 5888``update-policy local;``. ``named`` automatically 5889generates a TSIG session key when starting and stores it in a file; 5890this key can then be used by local clients to update the zone while 5891``named`` is running. By default, the session key is stored in the file 5892``/var/run/named/session.key``, the key name is "local-ddns", and the 5893key algorithm is HMAC-SHA256. These values are configurable with the 5894``session-keyfile``, ``session-keyname``, and ``session-keyalg`` options, 5895respectively. A client running on the local system, if run with 5896appropriate permissions, may read the session key from the key file and 5897use it to sign update requests. The zone's update policy is set to 5898allow that key to change any record within the zone. Assuming the key 5899name is "local-ddns", this policy is equivalent to: 5900 5901:: 5902 5903 update-policy { grant local-ddns zonesub any; }; 5904 5905with the additional restriction that only clients connecting from the 5906local system are permitted to send updates. 5907 5908Note that only one session key is generated by ``named``; all zones 5909configured to use ``update-policy local`` accept the same key. 5910 5911The command ``nsupdate -l`` implements this feature, sending requests to 5912localhost and signing them using the key retrieved from the session key 5913file. 5914 5915Other rule definitions look like this: 5916 5917:: 5918 5919 ( grant | deny ) identity ruletype name types 5920 5921Each rule grants or denies privileges. Rules are checked in the order in 5922which they are specified in the ``update-policy`` statement. Once a 5923message has successfully matched a rule, the operation is immediately 5924granted or denied, and no further rules are examined. There are 13 types 5925of rules; the rule type is specified by the ``ruletype`` field, and the 5926interpretation of other fields varies depending on the rule type. 5927 5928In general, a rule is matched when the key that signed an update request 5929matches the ``identity`` field, the name of the record to be updated 5930matches the ``name`` field (in the manner specified by the ``ruletype`` 5931field), and the type of the record to be updated matches the ``types`` 5932field. Details for each rule type are described below. 5933 5934The ``identity`` field must be set to a fully qualified domain name. In 5935most cases, this represents the name of the TSIG or SIG(0) key that 5936must be used to sign the update request. If the specified name is a 5937wildcard, it is subject to DNS wildcard expansion, and the rule may 5938apply to multiple identities. When a TKEY exchange has been used to 5939create a shared secret, the identity of the key used to authenticate the 5940TKEY exchange is used as the identity of the shared secret. Some 5941rule types use identities matching the client's Kerberos principal (e.g, 5942``"host/machine@REALM"``) or Windows realm (``machine$@REALM``). 5943 5944The ``name`` field also specifies a fully qualified domain name. This often 5945represents the name of the record to be updated. Interpretation of this 5946field is dependent on rule type. 5947 5948If no ``types`` are explicitly specified, then a rule matches all types 5949except RRSIG, NS, SOA, NSEC, and NSEC3. Types may be specified by name, 5950including ``ANY``; ANY matches all types except NSEC and NSEC3, which can 5951never be updated. Note that when an attempt is made to delete all 5952records associated with a name, the rules are checked for each existing 5953record type. 5954 5955The ruletype field has 16 values: ``name``, ``subdomain``, ``zonesub``, ``wildcard``, 5956``self``, ``selfsub``, ``selfwild``, ``ms-self``, ``ms-selfsub``, ``ms-subdomain``, 5957``krb5-self``, ``krb5-selfsub``, ``krb5-subdomain``, 5958``tcp-self``, ``6to4-self``, and ``external``. 5959 5960``name`` 5961 With exact-match semantics, this rule matches when the name being updated is identical to the contents of the ``name`` field. 5962 5963``subdomain`` 5964 This rule matches when the name being updated is a subdomain of, or identical to, the contents of the ``name`` field. 5965 5966``zonesub`` 5967 This rule is similar to subdomain, except that it matches when the name being updated is a subdomain of the zone in which the ``update-policy`` statement appears. This obviates the need to type the zone name twice, and enables the use of a standard ``update-policy`` statement in multiple zones without modification. 5968 When this rule is used, the ``name`` field is omitted. 5969 5970``wildcard`` 5971 The ``name`` field is subject to DNS wildcard expansion, and this rule matches when the name being updated is a valid expansion of the wildcard. 5972 5973``self`` 5974 This rule matches when the name of the record being updated matches the contents of the ``identity`` field. The ``name`` field is ignored. To avoid confusion, it is recommended that this field be set to the same value as the ``identity`` field or to "." 5975 The ``self`` rule type is most useful when allowing one key per name to update, where the key has the same name as the record to be updated. In this case, the ``identity`` field can be specified as ``*`` (asterisk). 5976 5977``selfsub`` 5978 This rule is similar to ``self``, except that subdomains of ``self`` can also be updated. 5979 5980``selfwild`` 5981 This rule is similar to ``self``, except that only subdomains of ``self`` can be updated. 5982 5983``ms-self`` 5984 When a client sends an UPDATE using a Windows machine principal (for example, ``machine$@REALM``), this rule allows records with the absolute name of ``machine.REALM`` to be updated. 5985 5986 The realm to be matched is specified in the ``identity`` field. 5987 5988 The ``name`` field has no effect on this rule; it should be set to "." as a placeholder. 5989 5990 For example, ``grant EXAMPLE.COM ms-self . A AAAA`` allows any machine with a valid principal in the realm ``EXAMPLE.COM`` to update its own address records. 5991 5992``ms-selfsub`` 5993 This is similar to ``ms-self``, except it also allows updates to any subdomain of the name specified in the Windows machine principal, not just to the name itself. 5994 5995``ms-subdomain`` 5996 When a client sends an UPDATE using a Windows machine principal (for example, ``machine$@REALM``), this rule allows any machine in the specified realm to update any record in the zone or in a specified subdomain of the zone. 5997 5998 The realm to be matched is specified in the ``identity`` field. 5999 6000 The ``name`` field specifies the subdomain that may be updated. If set to "." or any other name at or above the zone apex, any name in the zone can be updated. 6001 6002 For example, if ``update-policy`` for the zone "example.com" includes ``grant EXAMPLE.COM ms-subdomain hosts.example.com. AA AAAA``, any machine with a valid principal in the realm ``EXAMPLE.COM`` is able to update address records at or below ``hosts.example.com``. 6003 6004``krb5-self`` 6005 When a client sends an UPDATE using a Kerberos machine principal (for example, ``host/machine@REALM``), this rule allows records with the absolute name of ``machine`` to be updated, provided it has been authenticated by REALM. This is similar but not identical to ``ms-self``, due to the ``machine`` part of the Kerberos principal being an absolute name instead of an unqualified name. 6006 6007 The realm to be matched is specified in the ``identity`` field. 6008 6009 The ``name`` field has no effect on this rule; it should be set to "." as a placeholder. 6010 6011 For example, ``grant EXAMPLE.COM krb5-self . A AAAA`` allows any machine with a valid principal in the realm ``EXAMPLE.COM`` to update its own address records. 6012 6013``krb5-selfsub`` 6014 This is similar to ``krb5-self``, except it also allows updates to any subdomain of the name specified in the ``machine`` part of the Kerberos principal, not just to the name itself. 6015 6016``krb5-subdomain`` 6017 This rule is identical to ``ms-subdomain``, except that it works with Kerberos machine principals (i.e., ``host/machine@REALM``) rather than Windows machine principals. 6018 6019``tcp-self`` 6020 This rule allows updates that have been sent via TCP and for which the standard mapping from the client's IP address into the ``in-addr.arpa`` and ``ip6.arpa`` namespaces matches the name to be updated. The ``identity`` field must match that name. The ``name`` field should be set to ".". Note that, since identity is based on the client's IP address, it is not necessary for update request messages to be signed. 6021 6022 .. note:: 6023 It is theoretically possible to spoof these TCP sessions. 6024 6025``6to4-self`` 6026 This allows the name matching a 6to4 IPv6 prefix, as specified in :rfc:`3056`, to be updated by any TCP connection from either the 6to4 network or from the corresponding IPv4 address. This is intended to allow NS or DNAME RRsets to be added to the ``ip6.arpa`` reverse tree. 6027 6028 The ``identity`` field must match the 6to4 prefix in ``ip6.arpa``. The ``name`` field should be set to ".". Note that, since identity is based on the client's IP address, it is not necessary for update request messages to be signed. 6029 6030 In addition, if specified for an ``ip6.arpa`` name outside of the ``2.0.0.2.ip6.arpa`` namespace, the corresponding /48 reverse name can be updated. For example, TCP/IPv6 connections from 2001:DB8:ED0C::/48 can update records at ``C.0.D.E.8.B.D.0.1.0.0.2.ip6.arpa``. 6031 6032 .. note:: 6033 It is theoretically possible to spoof these TCP sessions. 6034 6035``external`` 6036 This rule allows ``named`` to defer the decision of whether to allow a given update to an external daemon. 6037 6038 The method of communicating with the daemon is specified in the ``identity`` field, the format of which is "``local:``\ path", where "path" is the location of a Unix-domain socket. (Currently, "local" is the only supported mechanism.) 6039 6040 Requests to the external daemon are sent over the Unix-domain socket as datagrams with the following format: 6041 6042 :: 6043 6044 Protocol version number (4 bytes, network byte order, currently 1) 6045 Request length (4 bytes, network byte order) 6046 Signer (null-terminated string) 6047 Name (null-terminated string) 6048 TCP source address (null-terminated string) 6049 Rdata type (null-terminated string) 6050 Key (null-terminated string) 6051 TKEY token length (4 bytes, network byte order) 6052 TKEY token (remainder of packet) 6053 6054 The daemon replies with a four-byte value in network byte order, containing either 0 or 1; 0 indicates that the specified update is not permitted, and 1 indicates that it is. 6055 6056 .. warning:: The external daemon must not delay communication. This policy is evaluated synchronously; any wait period negatively affects :iscman:`named` performance. 6057 6058.. _multiple_views: 6059 6060Multiple Views 6061^^^^^^^^^^^^^^ 6062 6063When multiple views are in use, a zone may be referenced by more than 6064one of them. Often, the views contain different zones with the same 6065name, allowing different clients to receive different answers for the 6066same queries. At times, however, it is desirable for multiple views to 6067contain identical zones. The ``in-view`` zone option provides an 6068efficient way to do this; it allows a view to reference a zone that was 6069defined in a previously configured view. For example: 6070 6071:: 6072 6073 view internal { 6074 match-clients { 10/8; }; 6075 6076 zone example.com { 6077 type primary; 6078 file "example-external.db"; 6079 }; 6080 }; 6081 6082 view external { 6083 match-clients { any; }; 6084 6085 zone example.com { 6086 in-view internal; 6087 }; 6088 }; 6089 6090An ``in-view`` option cannot refer to a view that is configured later in 6091the configuration file. 6092 6093A ``zone`` statement which uses the ``in-view`` option may not use any 6094other options, with the exception of ``forward`` and ``forwarders``. 6095(These options control the behavior of the containing view, rather than 6096change the zone object itself.) 6097 6098Zone-level ACLs (e.g., allow-query, allow-transfer), and other 6099configuration details of the zone, are all set in the view the referenced 6100zone is defined in. Be careful to ensure that ACLs are wide 6101enough for all views referencing the zone. 6102 6103An ``in-view`` zone cannot be used as a response policy zone. 6104 6105An ``in-view`` zone is not intended to reference a ``forward`` zone. 6106 6107.. _zone_file: 6108 6109Zone File 6110--------- 6111 6112.. _types_of_resource_records_and_when_to_use_them: 6113 6114Types of Resource Records and When to Use Them 6115~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 6116 6117This section, largely borrowed from :rfc:`1034`, describes the concept of a 6118Resource Record (RR) and explains when each type is used. Since the 6119publication of :rfc:`1034`, several new RRs have been identified and 6120implemented in the DNS. These are also included. 6121 6122Resource Records 6123^^^^^^^^^^^^^^^^ 6124 6125A domain name identifies a node. Each node has a set of resource 6126information, which may be empty. The set of resource information 6127associated with a particular name is composed of separate RRs. The order 6128of RRs in a set is not significant and need not be preserved by name 6129servers, resolvers, or other parts of the DNS. However, sorting of 6130multiple RRs is permitted for optimization purposes: for example, to 6131specify that a particular nearby server be tried first. See 6132:ref:`the_sortlist_statement` and :ref:`rrset_ordering`. 6133 6134The components of a Resource Record are: 6135 6136owner name 6137 The domain name where the RR is found. 6138 6139type 6140 An encoded 16-bit value that specifies the type of the resource record. 6141 6142TTL 6143 The time-to-live of the RR. This field is a 32-bit integer in units of seconds, and is primarily used by resolvers when they cache RRs. The TTL describes how long a RR can be cached before it should be discarded. 6144 6145class 6146 An encoded 16-bit value that identifies a protocol family or an instance of a protocol. 6147 6148RDATA 6149 The resource data. The format of the data is type- and sometimes class-specific. 6150 6151For a complete list of *types* of valid RRs, including those that have been obsoleted, please refer to https://en.wikipedia.org/wiki/List_of_DNS_record_types. 6152 6153The following *classes* of resource records are currently valid in the 6154DNS: 6155 6156IN 6157 The Internet. 6158 6159CH 6160 Chaosnet, a LAN protocol created at MIT in the mid-1970s. It was rarely used for its historical purpose, but was reused for BIND's built-in server information zones, e.g., ``version.bind``. 6161 6162HS 6163 Hesiod, an information service developed by MIT's Project Athena. It was used to share information about various systems databases, such as users, groups, printers, etc. 6164 6165The owner name is often implicit, rather than forming an integral part 6166of the RR. For example, many name servers internally form tree or hash 6167structures for the name space, and chain RRs off nodes. The remaining RR 6168parts are the fixed header (type, class, TTL), which is consistent for 6169all RRs, and a variable part (RDATA) that fits the needs of the resource 6170being described. 6171 6172The TTL field is a time limit on how long an RR can be 6173kept in a cache. This limit does not apply to authoritative data in 6174zones; that also times out, but follows the refreshing policies for the 6175zone. The TTL is assigned by the administrator for the zone where the 6176data originates. While short TTLs can be used to minimize caching, and a 6177zero TTL prohibits caching, the realities of Internet performance 6178suggest that these times should be on the order of days for the typical 6179host. If a change is anticipated, the TTL can be reduced prior to 6180the change to minimize inconsistency, and then 6181increased back to its former value following the change. 6182 6183The data in the RDATA section of RRs is carried as a combination of 6184binary strings and domain names. The domain names are frequently used as 6185"pointers" to other data in the DNS. 6186 6187.. _rr_text: 6188 6189Textual Expression of RRs 6190^^^^^^^^^^^^^^^^^^^^^^^^^ 6191 6192RRs are represented in binary form in the packets of the DNS protocol, 6193and are usually represented in highly encoded form when stored in a name 6194server or resolver. In the examples provided in :rfc:`1034`, a style 6195similar to that used in primary files was employed in order to show the 6196contents of RRs. In this format, most RRs are shown on a single line, 6197although continuation lines are possible using parentheses. 6198 6199The start of the line gives the owner of the RR. If a line begins with a 6200blank, then the owner is assumed to be the same as that of the previous 6201RR. Blank lines are often included for readability. 6202 6203Following the owner are listed the TTL, type, and class of the RR. Class 6204and type use the mnemonics defined above, and TTL is an integer before 6205the type field. To avoid ambiguity in parsing, type and class 6206mnemonics are disjoint, TTLs are integers, and the type mnemonic is 6207always last. The IN class and TTL values are often omitted from examples 6208in the interest of clarity. 6209 6210The resource data or RDATA section of the RR is given using knowledge 6211of the typical representation for the data. 6212 6213For example, the RRs carried in a message might be shown as: 6214 6215 +---------------------+---------------+--------------------------------+ 6216 | ``ISI.EDU.`` | ``MX`` | ``10 VENERA.ISI.EDU.`` | 6217 +---------------------+---------------+--------------------------------+ 6218 | | ``MX`` | ``10 VAXA.ISI.EDU`` | 6219 +---------------------+---------------+--------------------------------+ 6220 | ``VENERA.ISI.EDU`` | ``A`` | ``128.9.0.32`` | 6221 +---------------------+---------------+--------------------------------+ 6222 | | ``A`` | ``10.1.0.52`` | 6223 +---------------------+---------------+--------------------------------+ 6224 | ``VAXA.ISI.EDU`` | ``A`` | ``10.2.0.27`` | 6225 +---------------------+---------------+--------------------------------+ 6226 | | ``A`` | ``128.9.0.33`` | 6227 +---------------------+---------------+--------------------------------+ 6228 6229The MX RRs have an RDATA section which consists of a 16-bit number 6230followed by a domain name. The address RRs use a standard IP address 6231format to contain a 32-bit Internet address. 6232 6233The above example shows six RRs, with two RRs at each of three domain 6234names. 6235 6236Here is another possible example: 6237 6238 +----------------------+---------------+-------------------------------+ 6239 | ``XX.LCS.MIT.EDU.`` | ``IN A`` | ``10.0.0.44`` | 6240 +----------------------+---------------+-------------------------------+ 6241 | | ``CH A`` | ``MIT.EDU. 2420`` | 6242 +----------------------+---------------+-------------------------------+ 6243 6244This shows two addresses for ``XX.LCS.MIT.EDU``, each of a 6245different class. 6246 6247.. _mx_records: 6248 6249Discussion of MX Records 6250~~~~~~~~~~~~~~~~~~~~~~~~ 6251 6252As described above, domain servers store information as a series of 6253resource records, each of which contains a particular piece of 6254information about a given domain name (which is usually, but not always, 6255a host). The simplest way to think of an RR is as a typed pair of data, a 6256domain name matched with a relevant datum and stored with some 6257additional type information, to help systems determine when the RR is 6258relevant. 6259 6260MX records are used to control delivery of email. The data specified in 6261the record is a priority and a domain name. The priority controls the 6262order in which email delivery is attempted, with the lowest number 6263first. If two priorities are the same, a server is chosen randomly. If 6264no servers at a given priority are responding, the mail transport agent 6265falls back to the next largest priority. Priority numbers do not 6266have any absolute meaning; they are relevant only respective to other 6267MX records for that domain name. The domain name given is the machine to 6268which the mail is delivered. It *must* have an associated address 6269record (A or AAAA); CNAME is not sufficient. 6270 6271For a given domain, if there is both a CNAME record and an MX record, 6272the MX record is in error and is ignored. Instead, the mail is 6273delivered to the server specified in the MX record pointed to by the 6274CNAME. For example: 6275 6276 +------------------------+--------+--------+--------------+------------------------+ 6277 | ``example.com.`` | ``IN`` | ``MX`` | ``10`` | ``mail.example.com.`` | 6278 +------------------------+--------+--------+--------------+------------------------+ 6279 | | ``IN`` | ``MX`` | ``10`` | ``mail2.example.com.`` | 6280 +------------------------+--------+--------+--------------+------------------------+ 6281 | | ``IN`` | ``MX`` | ``20`` | ``mail.backup.org.`` | 6282 +------------------------+--------+--------+--------------+------------------------+ 6283 | ``mail.example.com.`` | ``IN`` | ``A`` | ``10.0.0.1`` | | 6284 +------------------------+--------+--------+--------------+------------------------+ 6285 | ``mail2.example.com.`` | ``IN`` | ``A`` | ``10.0.0.2`` | | 6286 +------------------------+--------+--------+--------------+------------------------+ 6287 6288Mail delivery is attempted to ``mail.example.com`` and 6289``mail2.example.com`` (in any order); if neither of those succeeds, 6290delivery to ``mail.backup.org`` is attempted. 6291 6292.. _Setting_TTLs: 6293 6294Setting TTLs 6295~~~~~~~~~~~~ 6296 6297The time-to-live (TTL) of the RR field is a 32-bit integer represented in 6298units of seconds, and is primarily used by resolvers when they cache 6299RRs. The TTL describes how long an RR can be cached before it should be 6300discarded. The following three types of TTLs are currently used in a zone 6301file. 6302 6303SOA 6304 The last field in the SOA is the negative caching TTL. This controls how long other servers cache no-such-domain (NXDOMAIN) responses from this server. 6305 6306 The maximum time for negative caching is 3 hours (3h). 6307 6308$TTL 6309 The $TTL directive at the top of the zone file (before the SOA) gives a default TTL for every RR without a specific TTL set. 6310 6311RR TTLs 6312 Each RR can have a TTL as the second field in the RR, which controls how long other servers can cache it. 6313 6314All of these TTLs default to units of seconds, though units can be 6315explicitly specified: for example, ``1h30m``. 6316 6317.. _ipv4_reverse: 6318 6319Inverse Mapping in IPv4 6320~~~~~~~~~~~~~~~~~~~~~~~ 6321 6322Reverse name resolution (that is, translation from IP address to name) 6323is achieved by means of the ``in-addr.arpa`` domain and PTR records. 6324Entries in the in-addr.arpa domain are made in least-to-most significant 6325order, read left to right. This is the opposite order to the way IP 6326addresses are usually written. Thus, a machine with an IP address of 632710.1.2.3 would have a corresponding in-addr.arpa name of 63283.2.1.10.in-addr.arpa. This name should have a PTR resource record whose 6329data field is the name of the machine or, optionally, multiple PTR 6330records if the machine has more than one name. For example, in the 6331``example.com`` domain: 6332 6333 +--------------+-------------------------------------------------------+ 6334 | ``$ORIGIN`` | ``2.1.10.in-addr.arpa`` | 6335 +--------------+-------------------------------------------------------+ 6336 | ``3`` | ``IN PTR foo.example.com.`` | 6337 +--------------+-------------------------------------------------------+ 6338 6339.. note:: 6340 6341 The ``$ORIGIN`` line in this example is only to provide context; 6342 it does not necessarily appear in the actual 6343 usage. It is only used here to indicate that the example is 6344 relative to the listed origin. 6345 6346.. _zone_directives: 6347 6348Other Zone File Directives 6349~~~~~~~~~~~~~~~~~~~~~~~~~~ 6350 6351The DNS "master file" format was initially defined in :rfc:`1035` and has 6352subsequently been extended. While the format itself is class-independent, 6353all records in a zone file must be of the same class. 6354 6355Master file directives include ``$ORIGIN``, ``$INCLUDE``, and ``$TTL.`` 6356 6357.. _atsign: 6358 6359The ``@`` (at-sign) 6360^^^^^^^^^^^^^^^^^^^ 6361 6362When used in the label (or name) field, the asperand or at-sign (@) 6363symbol represents the current origin. At the start of the zone file, it 6364is the <``zone_name``>, followed by a trailing dot (.). 6365 6366.. _origin_directive: 6367 6368The ``$ORIGIN`` Directive 6369^^^^^^^^^^^^^^^^^^^^^^^^^ 6370 6371Syntax: ``$ORIGIN`` domain-name [comment] 6372 6373``$ORIGIN`` sets the domain name that is appended to any 6374unqualified records. When a zone is first read, there is an implicit 6375``$ORIGIN`` <``zone_name``>``.``; note the trailing dot. The 6376current ``$ORIGIN`` is appended to the domain specified in the 6377``$ORIGIN`` argument if it is not absolute. 6378 6379:: 6380 6381 $ORIGIN example.com. 6382 WWW CNAME MAIN-SERVER 6383 6384is equivalent to 6385 6386:: 6387 6388 WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM. 6389 6390.. _include_directive: 6391 6392The ``$INCLUDE`` Directive 6393^^^^^^^^^^^^^^^^^^^^^^^^^^ 6394 6395Syntax: ``$INCLUDE`` filename [origin] [comment] 6396 6397This reads and processes the file ``filename`` as if it were included in the 6398file at this point. The ``filename`` can be an absolute path, or a relative 6399path. In the latter case it is read from ``named``'s working directory. If 6400``origin`` is specified, the file is processed with ``$ORIGIN`` set to that 6401value; otherwise, the current ``$ORIGIN`` is used. 6402 6403The origin and the current domain name revert to the values they had 6404prior to the ``$INCLUDE`` once the file has been read. 6405 6406.. note:: 6407 6408 :rfc:`1035` specifies that the current origin should be restored after 6409 an ``$INCLUDE``, but it is silent on whether the current domain name 6410 should also be restored. BIND 9 restores both of them. This could be 6411 construed as a deviation from :rfc:`1035`, a feature, or both. 6412 6413.. _ttl_directive: 6414 6415The ``$TTL`` Directive 6416^^^^^^^^^^^^^^^^^^^^^^ 6417 6418Syntax: ``$TTL`` default-ttl [comment] 6419 6420This sets the default Time-To-Live (TTL) for subsequent records with undefined 6421TTLs. Valid TTLs are of the range 0-2147483647 seconds. 6422 6423``$TTL`` is defined in :rfc:`2308`. 6424 6425.. _generate_directive: 6426 6427BIND Primary File Extension: the ``$GENERATE`` Directive 6428~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 6429 6430Syntax: ``$GENERATE`` range owner [ttl] [class] type rdata [comment] 6431 6432``$GENERATE`` is used to create a series of resource records that only 6433differ from each other by an iterator. 6434 6435``range`` 6436 This can be one of two forms: start-stop or start-stop/step. 6437 If the first form is used, then step is set to 1. "start", 6438 "stop", and "step" must be positive integers between 0 and 6439 (2^31)-1. "start" must not be larger than "stop". 6440 6441``owner`` 6442 This describes the owner name of the resource records to be created. 6443 6444 The ``owner`` string may include one or more ``$`` (dollar sign) 6445 symbols, which will be replaced with the iterator value when 6446 generating records; see below for details. 6447 6448``ttl`` 6449 This specifies the time-to-live of the generated records. If 6450 not specified, this is inherited using the normal TTL inheritance 6451 rules. 6452 6453 ``class`` and ``ttl`` can be entered in either order. 6454 6455``class`` 6456 This specifies the class of the generated records. This must 6457 match the zone class if it is specified. 6458 6459 ``class`` and ``ttl`` can be entered in either order. 6460 6461``type`` 6462 This can be any valid type. 6463 6464``rdata`` 6465 This is a string containing the RDATA of the resource record 6466 to be created. As with ``owner``, the ``rdata`` string may 6467 include one or more ``$`` symbols, which are replaced with the 6468 iterator value. ``rdata`` may be quoted if there are spaces in 6469 the string; the quotation marks do not appear in the generated 6470 record. 6471 6472 Any single ``$`` (dollar sign) symbols within the ``owner`` or 6473 ``rdata`` strings are replaced by the iterator value. To get a ``$`` 6474 in the output, escape the ``$`` using a backslash ``\\``, e.g., 6475 ``\$``. (For compatibility with earlier versions, ``$$`` is also 6476 recognized as indicating a literal ``$`` in the output.) 6477 6478 The ``$`` may optionally be followed by modifiers which change 6479 the offset from the iterator, field width, and base. Modifiers 6480 are introduced by a ``{`` (left brace) immediately following 6481 the ``$``, as in ``${offset[,width[,base]]}``. For example, 6482 ``${-20,3,d}`` subtracts 20 from the current value and prints 6483 the result as a decimal in a zero-padded field of width 3. 6484 Available output forms are decimal (``d``), octal (``o``), 6485 hexadecimal (``x`` or ``X`` for uppercase), and nibble (``n`` 6486 or ``N`` for uppercase). The modfiier cannot contain whitespace 6487 or newlines. 6488 6489 The default modifier is ``${0,0,d}``. If the ``owner`` is not 6490 absolute, the current ``$ORIGIN`` is appended to the name. 6491 6492 In nibble mode, the value is treated as if it were a reversed 6493 hexadecimal string, with each hexadecimal digit as a separate 6494 label. The width field includes the label separator. 6495 6496Examples: 6497 6498``$GENERATE`` can be used to easily generate the sets of records required 6499to support sub-/24 reverse delegations described in :rfc:`2317`: 6500 6501:: 6502 6503 $ORIGIN 0.0.192.IN-ADDR.ARPA. 6504 $GENERATE 1-2 @ NS SERVER$.EXAMPLE. 6505 $GENERATE 1-127 $ CNAME $.0 6506 6507is equivalent to 6508 6509:: 6510 6511 0.0.0.192.IN-ADDR.ARPA. NS SERVER1.EXAMPLE. 6512 0.0.0.192.IN-ADDR.ARPA. NS SERVER2.EXAMPLE. 6513 1.0.0.192.IN-ADDR.ARPA. CNAME 1.0.0.0.192.IN-ADDR.ARPA. 6514 2.0.0.192.IN-ADDR.ARPA. CNAME 2.0.0.0.192.IN-ADDR.ARPA. 6515 ... 6516 127.0.0.192.IN-ADDR.ARPA. CNAME 127.0.0.0.192.IN-ADDR.ARPA. 6517 6518This example creates a set of A and MX records. Note the MX's ``rdata`` 6519is a quoted string; the quotes are stripped when ``$GENERATE`` is processed: 6520 6521:: 6522 6523 $ORIGIN EXAMPLE. 6524 $GENERATE 1-127 HOST-$ A 1.2.3.$ 6525 $GENERATE 1-127 HOST-$ MX "0 ." 6526 6527is equivalent to 6528 6529:: 6530 6531 HOST-1.EXAMPLE. A 1.2.3.1 6532 HOST-1.EXAMPLE. MX 0 . 6533 HOST-2.EXAMPLE. A 1.2.3.2 6534 HOST-2.EXAMPLE. MX 0 . 6535 HOST-3.EXAMPLE. A 1.2.3.3 6536 HOST-3.EXAMPLE. MX 0 . 6537 ... 6538 HOST-127.EXAMPLE. A 1.2.3.127 6539 HOST-127.EXAMPLE. MX 0 . 6540 6541 6542This example generates A and AAAA records using modifiers; the AAAA 6543``owner`` names are generated using nibble mode: 6544 6545:: 6546 6547 $ORIGIN EXAMPLE. 6548 $GENERATE 0-2 HOST-${0,4,d} A 1.2.3.${1,0,d} 6549 $GENERATE 1024-1026 ${0,3,n} AAAA 2001:db8::${0,4,x} 6550 6551is equivalent to: 6552 6553:: 6554 6555 HOST-0000.EXAMPLE. A 1.2.3.1 6556 HOST-0001.EXAMPLE. A 1.2.3.2 6557 HOST-0002.EXAMPLE. A 1.2.3.3 6558 0.0.4.EXAMPLE. AAAA 2001:db8::400 6559 1.0.4.EXAMPLE. AAAA 2001:db8::401 6560 2.0.4.EXAMPLE. AAAA 2001:db8::402 6561 6562The ``$GENERATE`` directive is a BIND extension and not part of the 6563standard zone file format. 6564 6565.. _zonefile_format: 6566 6567Additional File Formats 6568~~~~~~~~~~~~~~~~~~~~~~~ 6569 6570In addition to the standard text format, BIND 9 supports the ability 6571to read or dump to zone files in other formats. 6572 6573The ``raw`` format is a binary representation of zone data in a manner 6574similar to that used in zone transfers. Since it does not require 6575parsing text, load time is significantly reduced. 6576 6577An even faster alternative is the ``map`` format, which is an image of a 6578BIND 9 in-memory zone database; it can be loaded directly into memory via 6579the ``mmap()`` function and the zone can begin serving queries almost 6580immediately. Because records are not indivdually processed when loading a 6581``map`` file, zones using this format cannot be used in ``response-policy`` 6582statements. 6583 6584For a primary server, a zone file in ``raw`` or ``map`` format is expected 6585to be generated from a text zone file by the ``named-compilezone`` command. 6586For a secondary server or a dynamic zone, the zone file is automatically 6587generated when ``named`` dumps the zone contents after zone transfer or 6588when applying prior updates, if one of these formats is specified by the 6589``masterfile-format`` option. 6590 6591If a zone file in a binary format needs manual modification, it first must 6592be converted to ``text`` format by the ``named-compilezone`` command, 6593then converted back after editing. For example: 6594 6595:: 6596 named-compilezone -f map -F text -o zonefile.text <origin> zonefile.map 6597 [edit zonefile.text] 6598 named-compilezone -f text -F map -o zonefile.map <origin> zonefile.text 6599 6600Note that the ``map`` format is highly architecture-specific. A ``map`` 6601file *cannot* be used on a system with different pointer size, endianness, 6602or data alignment than the system on which it was generated, and should in 6603general be used only inside a single system. 6604 6605The ``map`` format is also dependent on the internal memory representation 6606of a zone database, which may change from one release of BIND 9 to another. 6607``map`` files are never compatible across major releases, and may not be 6608compatible across minor releases; any upgrade to BIND 9 may cause ``map`` 6609files to be rejected when loading. If a ``map`` file is being used for a 6610primary zone, it will need to be regenerated from text before restarting 6611the server. If it used for a secondary zone, this is unnecessary; the 6612rejection of the file will trigger a retransfer of the zone from the 6613primary. (To avoid a spike in traffic upon restart, it may be desirable in 6614some cases to convert ``map`` files to ``text`` format using 6615``named-compilezone`` before an upgrade, then back to ``map`` format with 6616the new version of ``named-compilezone`` afterward.) 6617 6618The use of ``map`` format may also be limited by operating system 6619mmap(2) limits like ``sysctl vm.max_map_count``. For Linux, this 6620defaults to 65536, which limits the number of mapped zones that can 6621be used without increasing ``vm.max_map_count``. 6622 6623``raw`` format uses network byte order and avoids architecture- 6624dependent data alignment so that it is as portable as possible, but it is 6625still primarily expected to be used inside the same single system. To 6626export a zone file in either ``raw`` or ``map`` format, or make a portable 6627backup of such a file, conversion to ``text`` format is recommended. 6628 6629.. _statistics: 6630 6631BIND 9 Statistics 6632----------------- 6633 6634BIND 9 maintains lots of statistics information and provides several 6635interfaces for users to access those statistics. The available 6636statistics include all statistics counters that are meaningful in BIND 9, 6637and other information that is considered useful. 6638 6639The statistics information is categorized into the following sections: 6640 6641Incoming Requests 6642 The number of incoming DNS requests for each OPCODE. 6643 6644Incoming Queries 6645 The number of incoming queries for each RR type. 6646 6647Outgoing Queries 6648 The number of outgoing queries for each RR type sent from the internal 6649 resolver, maintained per view. 6650 6651Name Server Statistics 6652 Statistics counters for incoming request processing. 6653 6654Zone Maintenance Statistics 6655 Statistics counters regarding zone maintenance operations, such as zone 6656 transfers. 6657 6658Resolver Statistics 6659 Statistics counters for name resolutions performed in the internal resolver, 6660 maintained per view. 6661 6662Cache DB RRsets 6663 Statistics counters related to cache contents, maintained per view. 6664 6665 The "NXDOMAIN" counter is the number of names that have been cached as 6666 nonexistent. Counters named for RR types indicate the number of active 6667 RRsets for each type in the cache database. 6668 6669 If an RR type name is preceded by an exclamation point (!), it represents the 6670 number of records in the cache which indicate that the type does not exist 6671 for a particular name; this is also known as "NXRRSET". If an RR type name 6672 is preceded by a hash mark (#), it represents the number of RRsets for this 6673 type that are present in the cache but whose TTLs have expired; these RRsets 6674 may only be used if stale answers are enabled. If an RR type name is 6675 preceded by a tilde (~), it represents the number of RRsets for this type 6676 that are present in the cache database but are marked for garbage collection; 6677 these RRsets cannot be used. 6678 6679Socket I/O Statistics 6680 Statistics counters for network-related events. 6681 6682A subset of Name Server Statistics is collected and shown per zone for 6683which the server has the authority, when ``zone-statistics`` is set to 6684``full`` (or ``yes``), for backward compatibility. See the description of 6685``zone-statistics`` in :ref:`options` for further details. 6686 6687These statistics counters are shown with their zone and view names. The 6688view name is omitted when the server is not configured with explicit 6689views. 6690 6691There are currently two user interfaces to get access to the statistics. 6692One is in plain-text format, dumped to the file specified by the 6693``statistics-file`` configuration option; the other is remotely 6694accessible via a statistics channel when the ``statistics-channels`` 6695statement is specified in the configuration file (see :ref:`statschannels`.) 6696 6697.. _statsfile: 6698 6699The Statistics File 6700~~~~~~~~~~~~~~~~~~~ 6701 6702The text format statistics dump begins with a line, like: 6703 6704``+++ Statistics Dump +++ (973798949)`` 6705 6706The number in parentheses is a standard Unix-style timestamp, measured 6707in seconds since January 1, 1970. Following that line is a set of 6708statistics information, which is categorized as described above. Each 6709section begins with a line, like: 6710 6711``++ Name Server Statistics ++`` 6712 6713Each section consists of lines, each containing the statistics counter 6714value followed by its textual description; see below for available 6715counters. For brevity, counters that have a value of 0 are not shown in 6716the statistics file. 6717 6718The statistics dump ends with the line where the number is identical to 6719the number in the beginning line; for example: 6720 6721``--- Statistics Dump --- (973798949)`` 6722 6723.. _statistics_counters: 6724 6725Statistics Counters 6726~~~~~~~~~~~~~~~~~~~ 6727 6728The following lists summarize the statistics counters that BIND 9 provides. 6729For each counter, the abbreviated 6730symbol name is given; these symbols are shown in the statistics 6731information accessed via an HTTP statistics channel. 6732The description of the counter is also shown in the 6733statistics file but, in this document, may be slightly 6734modified for better readability. 6735 6736.. _stats_counters: 6737 6738Name Server Statistics Counters 6739^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6740 6741``Requestv4`` 6742 This indicates the number of IPv4 requests received. Note: this also counts non-query requests. 6743 6744``Requestv6`` 6745 This indicates the number of IPv6 requests received. Note: this also counts non-query requests. 6746 6747``ReqEdns0`` 6748 This indicates the number of requests received with EDNS(0). 6749 6750``ReqBadEDN SVer`` 6751 This indicates the number of requests received with an unsupported EDNS version. 6752 6753``ReqTSIG`` 6754 This indicates the number of requests received with TSIG. 6755 6756``ReqSIG0`` 6757 This indicates the number of requests received with SIG(0). 6758 6759``ReqBadSIG`` 6760 This indicates the number of requests received with an invalid (TSIG or SIG(0)) signature. 6761 6762``ReqTCP`` 6763 This indicates the number of TCP requests received. 6764 6765``AuthQryRej`` 6766 This indicates the number of rejected authoritative (non-recursive) queries. 6767 6768``RecQryRej`` 6769 This indicates the number of rejected recursive queries. 6770 6771``XfrRej`` 6772 This indicates the number of rejected zone transfer requests. 6773 6774``UpdateRej`` 6775 This indicates the number of rejected dynamic update requests. 6776 6777``Response`` 6778 This indicates the number of responses sent. 6779 6780``RespTruncated`` 6781 This indicates the number of truncated responses sent. 6782 6783``RespEDNS0`` 6784 This indicates the number of responses sent with EDNS(0). 6785 6786``RespTSIG`` 6787 This indicates the number of responses sent with TSIG. 6788 6789``RespSIG0`` 6790 This indicates the number of responses sent with SIG(0). 6791 6792``QrySuccess`` 6793 This indicates the number of queries that resulted in a successful answer, meaning queries which return a NOERROR response with at least one answer RR. This corresponds to the ``success`` counter of previous versions of BIND 9. 6794 6795``QryAuthAns`` 6796 This indicates the number of queries that resulted in an authoritative answer. 6797 6798``QryNoauthAns`` 6799 This indicates the number of queries that resulted in a non-authoritative answer. 6800 6801``QryReferral`` 6802 This indicates the number of queries that resulted in a referral answer. This corresponds to the ``referral`` counter of previous versions of BIND 9. 6803 6804``QryNxrrset`` 6805 This indicates the number of queries that resulted in NOERROR responses with no data. This corresponds to the ``nxrrset`` counter of previous versions of BIND 9. 6806 6807``QrySERVFAIL`` 6808 This indicates the number of queries that resulted in SERVFAIL. 6809 6810``QryFORMERR`` 6811 This indicates the number of queries that resulted in FORMERR. 6812 6813``QryNXDOMAIN`` 6814 This indicates the number of queries that resulted in NXDOMAIN. This corresponds to the ``nxdomain`` counter of previous versions of BIND 9. 6815 6816``QryRecursion`` 6817 This indicates the number of queries that caused the server to perform recursion in order to find the final answer. This corresponds to the ``recursion`` counter of previous versions of BIND 9. 6818 6819``QryDuplicate`` 6820 This indicates the number of queries which the server attempted to recurse but for which it discovered an existing query with the same IP address, port, query ID, name, type, and class already being processed. This corresponds to the ``duplicate`` counter of previous versions of BIND 9. 6821 6822``QryDropped`` 6823 This indicates the number of recursive queries for which the server discovered an excessive number of existing recursive queries for the same name, type, and class, and which were subsequently dropped. This is the number of dropped queries due to the reason explained with the ``clients-per-query`` and ``max-clients-per-query`` options (see :ref:`clients-per-query <clients-per-query>`). This corresponds to the ``dropped`` counter of previous versions of BIND 9. 6824 6825``QryFailure`` 6826 This indicates the number of query failures. This corresponds to the ``failure`` counter of previous versions of BIND 9. Note: this counter is provided mainly for backward compatibility with previous versions; normally, more fine-grained counters such as ``AuthQryRej`` and ``RecQryRej`` that would also fall into this counter are provided, so this counter is not of much interest in practice. 6827 6828``QryNXRedir`` 6829 This indicates the number of queries that resulted in NXDOMAIN that were redirected. 6830 6831``QryNXRedirRLookup`` 6832 This indicates the number of queries that resulted in NXDOMAIN that were redirected and resulted in a successful remote lookup. 6833 6834``XfrReqDone`` 6835 This indicates the number of requested and completed zone transfers. 6836 6837``UpdateReqFwd`` 6838 This indicates the number of forwarded update requests. 6839 6840``UpdateRespFwd`` 6841 This indicates the number of forwarded update responses. 6842 6843``UpdateFwdFail`` 6844 This indicates the number of forwarded dynamic updates that failed. 6845 6846``UpdateDone`` 6847 This indicates the number of completed dynamic updates. 6848 6849``UpdateFail`` 6850 This indicates the number of failed dynamic updates. 6851 6852``UpdateBadPrereq`` 6853 This indicates the number of dynamic updates rejected due to a prerequisite failure. 6854 6855``UpdateQuota`` 6856 This indicates the number of times a dynamic update or update 6857 forwarding request was rejected because the number of pending 6858 requests exceeded ``update-quota``. 6859 6860``RateDropped`` 6861 This indicates the number of responses dropped due to rate limits. 6862 6863``RateSlipped`` 6864 This indicates the number of responses truncated by rate limits. 6865 6866``RPZRewrites`` 6867 This indicates the number of response policy zone rewrites. 6868 6869.. _zone_stats: 6870 6871Zone Maintenance Statistics Counters 6872^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6873 6874``NotifyOutv4`` 6875 This indicates the number of IPv4 notifies sent. 6876 6877``NotifyOutv6`` 6878 This indicates the number of IPv6 notifies sent. 6879 6880``NotifyInv4`` 6881 This indicates the number of IPv4 notifies received. 6882 6883``NotifyInv6`` 6884 This indicates the number of IPv6 notifies received. 6885 6886``NotifyRej`` 6887 This indicates the number of incoming notifies rejected. 6888 6889``SOAOutv4`` 6890 This indicates the number of IPv4 SOA queries sent. 6891 6892``SOAOutv6`` 6893 This indicates the number of IPv6 SOA queries sent. 6894 6895``AXFRReqv4`` 6896 This indicates the number of requested IPv4 AXFRs. 6897 6898``AXFRReqv6`` 6899 This indicates the number of requested IPv6 AXFRs. 6900 6901``IXFRReqv4`` 6902 This indicates the number of requested IPv4 IXFRs. 6903 6904``IXFRReqv6`` 6905 This indicates the number of requested IPv6 IXFRs. 6906 6907``XfrSuccess`` 6908 This indicates the number of successful zone transfer requests. 6909 6910``XfrFail`` 6911 This indicates the number of failed zone transfer requests. 6912 6913.. _resolver_stats: 6914 6915Resolver Statistics Counters 6916^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6917 6918``Queryv4`` 6919 This indicates the number of IPv4 queries sent. 6920 6921``Queryv6`` 6922 This indicates the number of IPv6 queries sent. 6923 6924``Responsev4`` 6925 This indicates the number of IPv4 responses received. 6926 6927``Responsev6`` 6928 This indicates the number of IPv6 responses received. 6929 6930``NXDOMAIN`` 6931 This indicates the number of NXDOMAINs received. 6932 6933``SERVFAIL`` 6934 This indicates the number of SERVFAILs received. 6935 6936``FORMERR`` 6937 This indicates the number of FORMERRs received. 6938 6939``OtherError`` 6940 This indicates the number of other errors received. 6941 6942``EDNS0Fail`` 6943 This indicates the number of EDNS(0) query failures. 6944 6945``Mismatch`` 6946 This indicates the number of mismatched responses received, meaning the DNS ID, response's source address, and/or the response's source port does not match what was expected. (The port must be 53 or as defined by the ``port`` option.) This may be an indication of a cache poisoning attempt. 6947 6948``Truncated`` 6949 This indicates the number of truncated responses received. 6950 6951``Lame`` 6952 This indicates the number of lame delegations received. 6953 6954``Retry`` 6955 This indicates the number of query retries performed. 6956 6957``QueryAbort`` 6958 This indicates the number of queries aborted due to quota control. 6959 6960``QuerySockFail`` 6961 This indicates the number of failures in opening query sockets. One common reason for such failures is due to a limitation on file descriptors. 6962 6963``QueryTimeout`` 6964 This indicates the number of query timeouts. 6965 6966``GlueFetchv4`` 6967 This indicates the number of IPv4 NS address fetches invoked. 6968 6969``GlueFetchv6`` 6970 This indicates the number of IPv6 NS address fetches invoked. 6971 6972``GlueFetchv4Fail`` 6973 This indicates the number of failed IPv4 NS address fetches. 6974 6975``GlueFetchv6Fail`` 6976 This indicates the number of failed IPv6 NS address fetches. 6977 6978``ValAttempt`` 6979 This indicates the number of attempted DNSSEC validations. 6980 6981``ValOk`` 6982 This indicates the number of successful DNSSEC validations. 6983 6984``ValNegOk`` 6985 This indicates the number of successful DNSSEC validations on negative information. 6986 6987``ValFail`` 6988 This indicates the number of failed DNSSEC validations. 6989 6990``QryRTTnn`` 6991 This provides a frequency table on query round-trip times (RTTs). Each ``nn`` specifies the corresponding frequency. In the sequence of ``nn_1``, ``nn_2``, ..., ``nn_m``, the value of ``nn_i`` is the number of queries whose RTTs are between ``nn_(i-1)`` (inclusive) and ``nn_i`` (exclusive) milliseconds. For the sake of convenience, we define ``nn_0`` to be 0. The last entry should be represented as ``nn_m+``, which means the number of queries whose RTTs are equal to or greater than ``nn_m`` milliseconds. 6992 6993.. _socket_stats: 6994 6995Socket I/O Statistics Counters 6996^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6997 6998Socket I/O statistics counters are defined per socket type, which are 6999``UDP4`` (UDP/IPv4), ``UDP6`` (UDP/IPv6), ``TCP4`` (TCP/IPv4), ``TCP6`` 7000(TCP/IPv6), ``Unix`` (Unix Domain), and ``FDwatch`` (sockets opened 7001outside the socket module). In the following list, ``<TYPE>`` represents 7002a socket type. Not all counters are available for all socket types; 7003exceptions are noted in the descriptions. 7004 7005``<TYPE>Open`` 7006 This indicates the number of sockets opened successfully. This counter does not apply to the ``FDwatch`` type. 7007 7008``<TYPE>OpenFail`` 7009 This indicates the number of failures to open sockets. This counter does not apply to the ``FDwatch`` type. 7010 7011``<TYPE>Close`` 7012 This indicates the number of closed sockets. 7013 7014``<TYPE>BindFail`` 7015 This indicates the number of failures to bind sockets. 7016 7017``<TYPE>ConnFail`` 7018 This indicates the number of failures to connect sockets. 7019 7020``<TYPE>Conn`` 7021 This indicates the number of connections established successfully. 7022 7023``<TYPE>AcceptFail`` 7024 This indicates the number of failures to accept incoming connection requests. This counter does not apply to the ``UDP`` and ``FDwatch`` types. 7025 7026``<TYPE>Accept`` 7027 This indicates the number of incoming connections successfully accepted. This counter does not apply to the ``UDP`` and ``FDwatch`` types. 7028 7029``<TYPE>SendErr`` 7030 This indicates the number of errors in socket send operations. 7031 7032``<TYPE>RecvErr`` 7033 This indicates the number of errors in socket receive operations, including errors of send operations on a connected UDP socket, notified by an ICMP error message. 7034