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