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