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