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