/contrib/bind9/doc/arm/Bv9ARM-book.xml
XML | 12029 lines | 11175 code | 821 blank | 33 comment | 0 complexity | 229a224015246795a39e20aab94ec4c8 MD5 | raw file
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 3 [<!ENTITY mdash "—">]> 4<!-- 5 - Copyright (C) 2004-2012 Internet Systems Consortium, Inc. ("ISC") 6 - Copyright (C) 2000-2003 Internet Software Consortium. 7 - 8 - Permission to use, copy, modify, and/or distribute this software for any 9 - purpose with or without fee is hereby granted, provided that the above 10 - copyright notice and this permission notice appear in all copies. 11 - 12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18 - PERFORMANCE OF THIS SOFTWARE. 19--> 20 21<!-- File: $Id$ --> 22<book xmlns:xi="http://www.w3.org/2001/XInclude"> 23 <title>BIND 9 Administrator Reference Manual</title> 24 25 <bookinfo> 26 <copyright> 27 <year>2004</year> 28 <year>2005</year> 29 <year>2006</year> 30 <year>2007</year> 31 <year>2008</year> 32 <year>2009</year> 33 <year>2010</year> 34 <year>2011</year> 35 <year>2012</year> 36 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 37 </copyright> 38 <copyright> 39 <year>2000</year> 40 <year>2001</year> 41 <year>2002</year> 42 <year>2003</year> 43 <holder>Internet Software Consortium.</holder> 44 </copyright> 45 </bookinfo> 46 47 <chapter id="Bv9ARM.ch01"> 48 <title>Introduction</title> 49 <para> 50 The Internet Domain Name System (<acronym>DNS</acronym>) 51 consists of the syntax 52 to specify the names of entities in the Internet in a hierarchical 53 manner, the rules used for delegating authority over names, and the 54 system implementation that actually maps names to Internet 55 addresses. <acronym>DNS</acronym> data is maintained in a 56 group of distributed 57 hierarchical databases. 58 </para> 59 60 <sect1> 61 <title>Scope of Document</title> 62 63 <para> 64 The Berkeley Internet Name Domain 65 (<acronym>BIND</acronym>) implements a 66 domain name server for a number of operating systems. This 67 document provides basic information about the installation and 68 care of the Internet Systems Consortium (<acronym>ISC</acronym>) 69 <acronym>BIND</acronym> version 9 software package for 70 system administrators. 71 </para> 72 73 <para> 74 This version of the manual corresponds to BIND version 9.8. 75 </para> 76 77 </sect1> 78 <sect1> 79 <title>Organization of This Document</title> 80 <para> 81 In this document, <emphasis>Chapter 1</emphasis> introduces 82 the basic <acronym>DNS</acronym> and <acronym>BIND</acronym> concepts. <emphasis>Chapter 2</emphasis> 83 describes resource requirements for running <acronym>BIND</acronym> in various 84 environments. Information in <emphasis>Chapter 3</emphasis> is 85 <emphasis>task-oriented</emphasis> in its presentation and is 86 organized functionally, to aid in the process of installing the 87 <acronym>BIND</acronym> 9 software. The task-oriented 88 section is followed by 89 <emphasis>Chapter 4</emphasis>, which contains more advanced 90 concepts that the system administrator may need for implementing 91 certain options. <emphasis>Chapter 5</emphasis> 92 describes the <acronym>BIND</acronym> 9 lightweight 93 resolver. The contents of <emphasis>Chapter 6</emphasis> are 94 organized as in a reference manual to aid in the ongoing 95 maintenance of the software. <emphasis>Chapter 7</emphasis> addresses 96 security considerations, and 97 <emphasis>Chapter 8</emphasis> contains troubleshooting help. The 98 main body of the document is followed by several 99 <emphasis>appendices</emphasis> which contain useful reference 100 information, such as a <emphasis>bibliography</emphasis> and 101 historic information related to <acronym>BIND</acronym> 102 and the Domain Name 103 System. 104 </para> 105 </sect1> 106 <sect1> 107 <title>Conventions Used in This Document</title> 108 109 <para> 110 In this document, we use the following general typographic 111 conventions: 112 </para> 113 114 <informaltable> 115 <tgroup cols="2"> 116 <colspec colname="1" colnum="1" colwidth="3.000in"/> 117 <colspec colname="2" colnum="2" colwidth="2.625in"/> 118 <tbody> 119 <row> 120 <entry colname="1"> 121 <para> 122 <emphasis>To describe:</emphasis> 123 </para> 124 </entry> 125 <entry colname="2"> 126 <para> 127 <emphasis>We use the style:</emphasis> 128 </para> 129 </entry> 130 </row> 131 <row> 132 <entry colname="1"> 133 <para> 134 a pathname, filename, URL, hostname, 135 mailing list name, or new term or concept 136 </para> 137 </entry> 138 <entry colname="2"> 139 <para> 140 <filename>Fixed width</filename> 141 </para> 142 </entry> 143 </row> 144 <row> 145 <entry colname="1"> 146 <para> 147 literal user 148 input 149 </para> 150 </entry> 151 <entry colname="2"> 152 <para> 153 <userinput>Fixed Width Bold</userinput> 154 </para> 155 </entry> 156 </row> 157 <row> 158 <entry colname="1"> 159 <para> 160 program output 161 </para> 162 </entry> 163 <entry colname="2"> 164 <para> 165 <computeroutput>Fixed Width</computeroutput> 166 </para> 167 </entry> 168 </row> 169 </tbody> 170 </tgroup> 171 </informaltable> 172 173 <para> 174 The following conventions are used in descriptions of the 175 <acronym>BIND</acronym> configuration file:<informaltable colsep="0" frame="all" rowsep="0"> 176 <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table"> 177 <colspec colname="1" colnum="1" colsep="0" colwidth="3.000in"/> 178 <colspec colname="2" colnum="2" colsep="0" colwidth="2.625in"/> 179 <tbody> 180 <row rowsep="0"> 181 <entry colname="1" colsep="1" rowsep="1"> 182 <para> 183 <emphasis>To describe:</emphasis> 184 </para> 185 </entry> 186 <entry colname="2" rowsep="1"> 187 <para> 188 <emphasis>We use the style:</emphasis> 189 </para> 190 </entry> 191 </row> 192 <row rowsep="0"> 193 <entry colname="1" colsep="1" rowsep="1"> 194 <para> 195 keywords 196 </para> 197 </entry> 198 <entry colname="2" rowsep="1"> 199 <para> 200 <literal>Fixed Width</literal> 201 </para> 202 </entry> 203 </row> 204 <row rowsep="0"> 205 <entry colname="1" colsep="1" rowsep="1"> 206 <para> 207 variables 208 </para> 209 </entry> 210 <entry colname="2" rowsep="1"> 211 <para> 212 <varname>Fixed Width</varname> 213 </para> 214 </entry> 215 </row> 216 <row rowsep="0"> 217 <entry colname="1" colsep="1"> 218 <para> 219 Optional input 220 </para> 221 </entry> 222 <entry colname="2"> 223 <para> 224 <optional>Text is enclosed in square brackets</optional> 225 </para> 226 </entry> 227 </row> 228 </tbody> 229 </tgroup> 230 </informaltable> 231 </para> 232 </sect1> 233 <sect1> 234 <title>The Domain Name System (<acronym>DNS</acronym>)</title> 235 <para> 236 The purpose of this document is to explain the installation 237 and upkeep of the <acronym>BIND</acronym> (Berkeley Internet 238 Name Domain) software package, and we 239 begin by reviewing the fundamentals of the Domain Name System 240 (<acronym>DNS</acronym>) as they relate to <acronym>BIND</acronym>. 241 </para> 242 243 <sect2> 244 <title>DNS Fundamentals</title> 245 246 <para> 247 The Domain Name System (DNS) is a hierarchical, distributed 248 database. It stores information for mapping Internet host names to 249 IP 250 addresses and vice versa, mail routing information, and other data 251 used by Internet applications. 252 </para> 253 254 <para> 255 Clients look up information in the DNS by calling a 256 <emphasis>resolver</emphasis> library, which sends queries to one or 257 more <emphasis>name servers</emphasis> and interprets the responses. 258 The <acronym>BIND</acronym> 9 software distribution 259 contains a 260 name server, <command>named</command>, and a resolver 261 library, <command>liblwres</command>. The older 262 <command>libbind</command> resolver library is also available 263 from ISC as a separate download. 264 </para> 265 266 </sect2><sect2> 267 <title>Domains and Domain Names</title> 268 269 <para> 270 The data stored in the DNS is identified by <emphasis>domain names</emphasis> that are organized as a tree according to 271 organizational or administrative boundaries. Each node of the tree, 272 called a <emphasis>domain</emphasis>, is given a label. The domain 273 name of the 274 node is the concatenation of all the labels on the path from the 275 node to the <emphasis>root</emphasis> node. This is represented 276 in written form as a string of labels listed from right to left and 277 separated by dots. A label need only be unique within its parent 278 domain. 279 </para> 280 281 <para> 282 For example, a domain name for a host at the 283 company <emphasis>Example, Inc.</emphasis> could be 284 <literal>ourhost.example.com</literal>, 285 where <literal>com</literal> is the 286 top level domain to which 287 <literal>ourhost.example.com</literal> belongs, 288 <literal>example</literal> is 289 a subdomain of <literal>com</literal>, and 290 <literal>ourhost</literal> is the 291 name of the host. 292 </para> 293 294 <para> 295 For administrative purposes, the name space is partitioned into 296 areas called <emphasis>zones</emphasis>, each starting at a node and 297 extending down to the leaf nodes or to nodes where other zones 298 start. 299 The data for each zone is stored in a <emphasis>name server</emphasis>, which answers queries about the zone using the 300 <emphasis>DNS protocol</emphasis>. 301 </para> 302 303 <para> 304 The data associated with each domain name is stored in the 305 form of <emphasis>resource records</emphasis> (<acronym>RR</acronym>s). 306 Some of the supported resource record types are described in 307 <xref linkend="types_of_resource_records_and_when_to_use_them"/>. 308 </para> 309 310 <para> 311 For more detailed information about the design of the DNS and 312 the DNS protocol, please refer to the standards documents listed in 313 <xref linkend="rfcs"/>. 314 </para> 315 </sect2> 316 317 <sect2> 318 <title>Zones</title> 319 <para> 320 To properly operate a name server, it is important to understand 321 the difference between a <emphasis>zone</emphasis> 322 and a <emphasis>domain</emphasis>. 323 </para> 324 325 <para> 326 As stated previously, a zone is a point of delegation in 327 the <acronym>DNS</acronym> tree. A zone consists of 328 those contiguous parts of the domain 329 tree for which a name server has complete information and over which 330 it has authority. It contains all domain names from a certain point 331 downward in the domain tree except those which are delegated to 332 other zones. A delegation point is marked by one or more 333 <emphasis>NS records</emphasis> in the 334 parent zone, which should be matched by equivalent NS records at 335 the root of the delegated zone. 336 </para> 337 338 <para> 339 For instance, consider the <literal>example.com</literal> 340 domain which includes names 341 such as <literal>host.aaa.example.com</literal> and 342 <literal>host.bbb.example.com</literal> even though 343 the <literal>example.com</literal> zone includes 344 only delegations for the <literal>aaa.example.com</literal> and 345 <literal>bbb.example.com</literal> zones. A zone can 346 map 347 exactly to a single domain, but could also include only part of a 348 domain, the rest of which could be delegated to other 349 name servers. Every name in the <acronym>DNS</acronym> 350 tree is a 351 <emphasis>domain</emphasis>, even if it is 352 <emphasis>terminal</emphasis>, that is, has no 353 <emphasis>subdomains</emphasis>. Every subdomain is a domain and 354 every domain except the root is also a subdomain. The terminology is 355 not intuitive and we suggest that you read RFCs 1033, 1034 and 1035 356 to 357 gain a complete understanding of this difficult and subtle 358 topic. 359 </para> 360 361 <para> 362 Though <acronym>BIND</acronym> is called a "domain name 363 server", 364 it deals primarily in terms of zones. The master and slave 365 declarations in the <filename>named.conf</filename> file 366 specify 367 zones, not domains. When you ask some other site if it is willing to 368 be a slave server for your <emphasis>domain</emphasis>, you are 369 actually asking for slave service for some collection of zones. 370 </para> 371 </sect2> 372 373 <sect2> 374 <title>Authoritative Name Servers</title> 375 376 <para> 377 Each zone is served by at least 378 one <emphasis>authoritative name server</emphasis>, 379 which contains the complete data for the zone. 380 To make the DNS tolerant of server and network failures, 381 most zones have two or more authoritative servers, on 382 different networks. 383 </para> 384 385 <para> 386 Responses from authoritative servers have the "authoritative 387 answer" (AA) bit set in the response packets. This makes them 388 easy to identify when debugging DNS configurations using tools like 389 <command>dig</command> (<xref linkend="diagnostic_tools"/>). 390 </para> 391 392 <sect3> 393 <title>The Primary Master</title> 394 395 <para> 396 The authoritative server where the master copy of the zone 397 data is maintained is called the 398 <emphasis>primary master</emphasis> server, or simply the 399 <emphasis>primary</emphasis>. Typically it loads the zone 400 contents from some local file edited by humans or perhaps 401 generated mechanically from some other local file which is 402 edited by humans. This file is called the 403 <emphasis>zone file</emphasis> or 404 <emphasis>master file</emphasis>. 405 </para> 406 407 <para> 408 In some cases, however, the master file may not be edited 409 by humans at all, but may instead be the result of 410 <emphasis>dynamic update</emphasis> operations. 411 </para> 412 </sect3> 413 414 <sect3> 415 <title>Slave Servers</title> 416 <para> 417 The other authoritative servers, the <emphasis>slave</emphasis> 418 servers (also known as <emphasis>secondary</emphasis> servers) 419 load 420 the zone contents from another server using a replication process 421 known as a <emphasis>zone transfer</emphasis>. Typically the data 422 are 423 transferred directly from the primary master, but it is also 424 possible 425 to transfer it from another slave. In other words, a slave server 426 may itself act as a master to a subordinate slave server. 427 </para> 428 </sect3> 429 430 <sect3> 431 <title>Stealth Servers</title> 432 433 <para> 434 Usually all of the zone's authoritative servers are listed in 435 NS records in the parent zone. These NS records constitute 436 a <emphasis>delegation</emphasis> of the zone from the parent. 437 The authoritative servers are also listed in the zone file itself, 438 at the <emphasis>top level</emphasis> or <emphasis>apex</emphasis> 439 of the zone. You can list servers in the zone's top-level NS 440 records that are not in the parent's NS delegation, but you cannot 441 list servers in the parent's delegation that are not present at 442 the zone's top level. 443 </para> 444 445 <para> 446 A <emphasis>stealth server</emphasis> is a server that is 447 authoritative for a zone but is not listed in that zone's NS 448 records. Stealth servers can be used for keeping a local copy of 449 a 450 zone to speed up access to the zone's records or to make sure that 451 the 452 zone is available even if all the "official" servers for the zone 453 are 454 inaccessible. 455 </para> 456 457 <para> 458 A configuration where the primary master server itself is a 459 stealth server is often referred to as a "hidden primary" 460 configuration. One use for this configuration is when the primary 461 master 462 is behind a firewall and therefore unable to communicate directly 463 with the outside world. 464 </para> 465 466 </sect3> 467 468 </sect2> 469 <sect2> 470 471 <title>Caching Name Servers</title> 472 473 <!-- 474 - Terminology here is inconsistent. Probably ought to 475 - convert to using "recursive name server" everywhere 476 - with just a note about "caching" terminology. 477 --> 478 479 <para> 480 The resolver libraries provided by most operating systems are 481 <emphasis>stub resolvers</emphasis>, meaning that they are not 482 capable of 483 performing the full DNS resolution process by themselves by talking 484 directly to the authoritative servers. Instead, they rely on a 485 local 486 name server to perform the resolution on their behalf. Such a 487 server 488 is called a <emphasis>recursive</emphasis> name server; it performs 489 <emphasis>recursive lookups</emphasis> for local clients. 490 </para> 491 492 <para> 493 To improve performance, recursive servers cache the results of 494 the lookups they perform. Since the processes of recursion and 495 caching are intimately connected, the terms 496 <emphasis>recursive server</emphasis> and 497 <emphasis>caching server</emphasis> are often used synonymously. 498 </para> 499 500 <para> 501 The length of time for which a record may be retained in 502 the cache of a caching name server is controlled by the 503 Time To Live (TTL) field associated with each resource record. 504 </para> 505 506 <sect3> 507 <title>Forwarding</title> 508 509 <para> 510 Even a caching name server does not necessarily perform 511 the complete recursive lookup itself. Instead, it can 512 <emphasis>forward</emphasis> some or all of the queries 513 that it cannot satisfy from its cache to another caching name 514 server, 515 commonly referred to as a <emphasis>forwarder</emphasis>. 516 </para> 517 518 <para> 519 There may be one or more forwarders, 520 and they are queried in turn until the list is exhausted or an 521 answer 522 is found. Forwarders are typically used when you do not 523 wish all the servers at a given site to interact directly with the 524 rest of 525 the Internet servers. A typical scenario would involve a number 526 of internal <acronym>DNS</acronym> servers and an 527 Internet firewall. Servers unable 528 to pass packets through the firewall would forward to the server 529 that can do it, and that server would query the Internet <acronym>DNS</acronym> servers 530 on the internal server's behalf. 531 </para> 532 </sect3> 533 534 </sect2> 535 536 <sect2> 537 <title>Name Servers in Multiple Roles</title> 538 539 <para> 540 The <acronym>BIND</acronym> name server can 541 simultaneously act as 542 a master for some zones, a slave for other zones, and as a caching 543 (recursive) server for a set of local clients. 544 </para> 545 546 <para> 547 However, since the functions of authoritative name service 548 and caching/recursive name service are logically separate, it is 549 often advantageous to run them on separate server machines. 550 551 A server that only provides authoritative name service 552 (an <emphasis>authoritative-only</emphasis> server) can run with 553 recursion disabled, improving reliability and security. 554 555 A server that is not authoritative for any zones and only provides 556 recursive service to local 557 clients (a <emphasis>caching-only</emphasis> server) 558 does not need to be reachable from the Internet at large and can 559 be placed inside a firewall. 560 </para> 561 562 </sect2> 563 </sect1> 564 565 </chapter> 566 567 <chapter id="Bv9ARM.ch02"> 568 <title><acronym>BIND</acronym> Resource Requirements</title> 569 570 <sect1> 571 <title>Hardware requirements</title> 572 573 <para> 574 <acronym>DNS</acronym> hardware requirements have 575 traditionally been quite modest. 576 For many installations, servers that have been pensioned off from 577 active duty have performed admirably as <acronym>DNS</acronym> servers. 578 </para> 579 <para> 580 The DNSSEC features of <acronym>BIND</acronym> 9 581 may prove to be quite 582 CPU intensive however, so organizations that make heavy use of these 583 features may wish to consider larger systems for these applications. 584 <acronym>BIND</acronym> 9 is fully multithreaded, allowing 585 full utilization of 586 multiprocessor systems for installations that need it. 587 </para> 588 </sect1> 589 <sect1> 590 <title>CPU Requirements</title> 591 <para> 592 CPU requirements for <acronym>BIND</acronym> 9 range from 593 i486-class machines 594 for serving of static zones without caching, to enterprise-class 595 machines if you intend to process many dynamic updates and DNSSEC 596 signed zones, serving many thousands of queries per second. 597 </para> 598 </sect1> 599 600 <sect1> 601 <title>Memory Requirements</title> 602 <para> 603 The memory of the server has to be large enough to fit the 604 cache and zones loaded off disk. The <command>max-cache-size</command> 605 option can be used to limit the amount of memory used by the cache, 606 at the expense of reducing cache hit rates and causing more <acronym>DNS</acronym> 607 traffic. 608 Additionally, if additional section caching 609 (<xref linkend="acache"/>) is enabled, 610 the <command>max-acache-size</command> option can be used to 611 limit the amount 612 of memory used by the mechanism. 613 It is still good practice to have enough memory to load 614 all zone and cache data into memory — unfortunately, the best 615 way 616 to determine this for a given installation is to watch the name server 617 in operation. After a few weeks the server process should reach 618 a relatively stable size where entries are expiring from the cache as 619 fast as they are being inserted. 620 </para> 621 <!-- 622 - Add something here about leaving overhead for attacks? 623 - How much overhead? Percentage? 624 --> 625 </sect1> 626 627 <sect1> 628 <title>Name Server Intensive Environment Issues</title> 629 <para> 630 For name server intensive environments, there are two alternative 631 configurations that may be used. The first is where clients and 632 any second-level internal name servers query a main name server, which 633 has enough memory to build a large cache. This approach minimizes 634 the bandwidth used by external name lookups. The second alternative 635 is to set up second-level internal name servers to make queries 636 independently. 637 In this configuration, none of the individual machines needs to 638 have as much memory or CPU power as in the first alternative, but 639 this has the disadvantage of making many more external queries, 640 as none of the name servers share their cached data. 641 </para> 642 </sect1> 643 644 <sect1> 645 <title>Supported Operating Systems</title> 646 <para> 647 ISC <acronym>BIND</acronym> 9 compiles and runs on a large 648 number 649 of Unix-like operating systems and on 650 Microsoft Windows Server 2003 and 2008, and Windows XP and Vista. 651 For an up-to-date 652 list of supported systems, see the README file in the top level 653 directory 654 of the BIND 9 source distribution. 655 </para> 656 </sect1> 657 </chapter> 658 659 <chapter id="Bv9ARM.ch03"> 660 <title>Name Server Configuration</title> 661 <para> 662 In this chapter we provide some suggested configurations along 663 with guidelines for their use. We suggest reasonable values for 664 certain option settings. 665 </para> 666 667 <sect1 id="sample_configuration"> 668 <title>Sample Configurations</title> 669 <sect2> 670 <title>A Caching-only Name Server</title> 671 <para> 672 The following sample configuration is appropriate for a caching-only 673 name server for use by clients internal to a corporation. All 674 queries 675 from outside clients are refused using the <command>allow-query</command> 676 option. Alternatively, the same effect could be achieved using 677 suitable 678 firewall rules. 679 </para> 680 681<programlisting> 682// Two corporate subnets we wish to allow queries from. 683acl corpnets { 192.168.4.0/24; 192.168.7.0/24; }; 684options { 685 // Working directory 686 directory "/etc/namedb"; 687 688 allow-query { corpnets; }; 689}; 690// Provide a reverse mapping for the loopback 691// address 127.0.0.1 692zone "0.0.127.in-addr.arpa" { 693 type master; 694 file "localhost.rev"; 695 notify no; 696}; 697</programlisting> 698 699 </sect2> 700 701 <sect2> 702 <title>An Authoritative-only Name Server</title> 703 <para> 704 This sample configuration is for an authoritative-only server 705 that is the master server for "<filename>example.com</filename>" 706 and a slave for the subdomain "<filename>eng.example.com</filename>". 707 </para> 708 709<programlisting> 710options { 711 // Working directory 712 directory "/etc/namedb"; 713 // Do not allow access to cache 714 allow-query-cache { none; }; 715 // This is the default 716 allow-query { any; }; 717 // Do not provide recursive service 718 recursion no; 719}; 720 721// Provide a reverse mapping for the loopback 722// address 127.0.0.1 723zone "0.0.127.in-addr.arpa" { 724 type master; 725 file "localhost.rev"; 726 notify no; 727}; 728// We are the master server for example.com 729zone "example.com" { 730 type master; 731 file "example.com.db"; 732 // IP addresses of slave servers allowed to 733 // transfer example.com 734 allow-transfer { 735 192.168.4.14; 736 192.168.5.53; 737 }; 738}; 739// We are a slave server for eng.example.com 740zone "eng.example.com" { 741 type slave; 742 file "eng.example.com.bk"; 743 // IP address of eng.example.com master server 744 masters { 192.168.4.12; }; 745}; 746</programlisting> 747 748 </sect2> 749 </sect1> 750 751 <sect1> 752 <title>Load Balancing</title> 753 <!-- 754 - Add explanation of why load balancing is fragile at best 755 - and completely pointless in the general case. 756 --> 757 758 <para> 759 A primitive form of load balancing can be achieved in 760 the <acronym>DNS</acronym> by using multiple records 761 (such as multiple A records) for one name. 762 </para> 763 764 <para> 765 For example, if you have three WWW servers with network addresses 766 of 10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the 767 following means that clients will connect to each machine one third 768 of the time: 769 </para> 770 771 <informaltable colsep="0" rowsep="0"> 772 <tgroup cols="5" colsep="0" rowsep="0" tgroupstyle="2Level-table"> 773 <colspec colname="1" colnum="1" colsep="0" colwidth="0.875in"/> 774 <colspec colname="2" colnum="2" colsep="0" colwidth="0.500in"/> 775 <colspec colname="3" colnum="3" colsep="0" colwidth="0.750in"/> 776 <colspec colname="4" colnum="4" colsep="0" colwidth="0.750in"/> 777 <colspec colname="5" colnum="5" colsep="0" colwidth="2.028in"/> 778 <tbody> 779 <row rowsep="0"> 780 <entry colname="1"> 781 <para> 782 Name 783 </para> 784 </entry> 785 <entry colname="2"> 786 <para> 787 TTL 788 </para> 789 </entry> 790 <entry colname="3"> 791 <para> 792 CLASS 793 </para> 794 </entry> 795 <entry colname="4"> 796 <para> 797 TYPE 798 </para> 799 </entry> 800 <entry colname="5"> 801 <para> 802 Resource Record (RR) Data 803 </para> 804 </entry> 805 </row> 806 <row rowsep="0"> 807 <entry colname="1"> 808 <para> 809 <literal>www</literal> 810 </para> 811 </entry> 812 <entry colname="2"> 813 <para> 814 <literal>600</literal> 815 </para> 816 </entry> 817 <entry colname="3"> 818 <para> 819 <literal>IN</literal> 820 </para> 821 </entry> 822 <entry colname="4"> 823 <para> 824 <literal>A</literal> 825 </para> 826 </entry> 827 <entry colname="5"> 828 <para> 829 <literal>10.0.0.1</literal> 830 </para> 831 </entry> 832 </row> 833 <row rowsep="0"> 834 <entry colname="1"> 835 <para/> 836 </entry> 837 <entry colname="2"> 838 <para> 839 <literal>600</literal> 840 </para> 841 </entry> 842 <entry colname="3"> 843 <para> 844 <literal>IN</literal> 845 </para> 846 </entry> 847 <entry colname="4"> 848 <para> 849 <literal>A</literal> 850 </para> 851 </entry> 852 <entry colname="5"> 853 <para> 854 <literal>10.0.0.2</literal> 855 </para> 856 </entry> 857 </row> 858 <row rowsep="0"> 859 <entry colname="1"> 860 <para/> 861 </entry> 862 <entry colname="2"> 863 <para> 864 <literal>600</literal> 865 </para> 866 </entry> 867 <entry colname="3"> 868 <para> 869 <literal>IN</literal> 870 </para> 871 </entry> 872 <entry colname="4"> 873 <para> 874 <literal>A</literal> 875 </para> 876 </entry> 877 <entry colname="5"> 878 <para> 879 <literal>10.0.0.3</literal> 880 </para> 881 </entry> 882 </row> 883 </tbody> 884 </tgroup> 885 </informaltable> 886 <para> 887 When a resolver queries for these records, <acronym>BIND</acronym> will rotate 888 them and respond to the query with the records in a different 889 order. In the example above, clients will randomly receive 890 records in the order 1, 2, 3; 2, 3, 1; and 3, 1, 2. Most clients 891 will use the first record returned and discard the rest. 892 </para> 893 <para> 894 For more detail on ordering responses, check the 895 <command>rrset-order</command> sub-statement in the 896 <command>options</command> statement, see 897 <xref endterm="rrset_ordering_title" linkend="rrset_ordering"/>. 898 </para> 899 900 </sect1> 901 902 <sect1> 903 <title>Name Server Operations</title> 904 905 <sect2> 906 <title>Tools for Use With the Name Server Daemon</title> 907 <para> 908 This section describes several indispensable diagnostic, 909 administrative and monitoring tools available to the system 910 administrator for controlling and debugging the name server 911 daemon. 912 </para> 913 <sect3 id="diagnostic_tools"> 914 <title>Diagnostic Tools</title> 915 <para> 916 The <command>dig</command>, <command>host</command>, and 917 <command>nslookup</command> programs are all command 918 line tools 919 for manually querying name servers. They differ in style and 920 output format. 921 </para> 922 923 <variablelist> 924 <varlistentry> 925 <term id="dig"><command>dig</command></term> 926 <listitem> 927 <para> 928 The domain information groper (<command>dig</command>) 929 is the most versatile and complete of these lookup tools. 930 It has two modes: simple interactive 931 mode for a single query, and batch mode which executes a 932 query for 933 each in a list of several query lines. All query options are 934 accessible 935 from the command line. 936 </para> 937 <cmdsynopsis label="Usage"> 938 <command>dig</command> 939 <arg>@<replaceable>server</replaceable></arg> 940 <arg choice="plain"><replaceable>domain</replaceable></arg> 941 <arg><replaceable>query-type</replaceable></arg> 942 <arg><replaceable>query-class</replaceable></arg> 943 <arg>+<replaceable>query-option</replaceable></arg> 944 <arg>-<replaceable>dig-option</replaceable></arg> 945 <arg>%<replaceable>comment</replaceable></arg> 946 </cmdsynopsis> 947 <para> 948 The usual simple use of <command>dig</command> will take the form 949 </para> 950 <simpara> 951 <command>dig @server domain query-type query-class</command> 952 </simpara> 953 <para> 954 For more information and a list of available commands and 955 options, see the <command>dig</command> man 956 page. 957 </para> 958 </listitem> 959 </varlistentry> 960 961 <varlistentry> 962 <term><command>host</command></term> 963 <listitem> 964 <para> 965 The <command>host</command> utility emphasizes 966 simplicity 967 and ease of use. By default, it converts 968 between host names and Internet addresses, but its 969 functionality 970 can be extended with the use of options. 971 </para> 972 <cmdsynopsis label="Usage"> 973 <command>host</command> 974 <arg>-aCdlnrsTwv</arg> 975 <arg>-c <replaceable>class</replaceable></arg> 976 <arg>-N <replaceable>ndots</replaceable></arg> 977 <arg>-t <replaceable>type</replaceable></arg> 978 <arg>-W <replaceable>timeout</replaceable></arg> 979 <arg>-R <replaceable>retries</replaceable></arg> 980 <arg>-m <replaceable>flag</replaceable></arg> 981 <arg>-4</arg> 982 <arg>-6</arg> 983 <arg choice="plain"><replaceable>hostname</replaceable></arg> 984 <arg><replaceable>server</replaceable></arg> 985 </cmdsynopsis> 986 <para> 987 For more information and a list of available commands and 988 options, see the <command>host</command> man 989 page. 990 </para> 991 </listitem> 992 </varlistentry> 993 994 <varlistentry> 995 <term><command>nslookup</command></term> 996 <listitem> 997 <para><command>nslookup</command> 998 has two modes: interactive and 999 non-interactive. Interactive mode allows the user to 1000 query name servers for information about various 1001 hosts and domains or to print a list of hosts in a 1002 domain. Non-interactive mode is used to print just 1003 the name and requested information for a host or 1004 domain. 1005 </para> 1006 <cmdsynopsis label="Usage"> 1007 <command>nslookup</command> 1008 <arg rep="repeat">-option</arg> 1009 <group> 1010 <arg><replaceable>host-to-find</replaceable></arg> 1011 <arg>- <arg>server</arg></arg> 1012 </group> 1013 </cmdsynopsis> 1014 <para> 1015 Interactive mode is entered when no arguments are given (the 1016 default name server will be used) or when the first argument 1017 is a 1018 hyphen (`-') and the second argument is the host name or 1019 Internet address 1020 of a name server. 1021 </para> 1022 <para> 1023 Non-interactive mode is used when the name or Internet 1024 address 1025 of the host to be looked up is given as the first argument. 1026 The 1027 optional second argument specifies the host name or address 1028 of a name server. 1029 </para> 1030 <para> 1031 Due to its arcane user interface and frequently inconsistent 1032 behavior, we do not recommend the use of <command>nslookup</command>. 1033 Use <command>dig</command> instead. 1034 </para> 1035 </listitem> 1036 1037 </varlistentry> 1038 </variablelist> 1039 </sect3> 1040 1041 <sect3 id="admin_tools"> 1042 <title>Administrative Tools</title> 1043 <para> 1044 Administrative tools play an integral part in the management 1045 of a server. 1046 </para> 1047 <variablelist> 1048 <varlistentry id="named-checkconf" xreflabel="Named Configuration Checking application"> 1049 1050 <term><command>named-checkconf</command></term> 1051 <listitem> 1052 <para> 1053 The <command>named-checkconf</command> program 1054 checks the syntax of a <filename>named.conf</filename> file. 1055 </para> 1056 <cmdsynopsis label="Usage"> 1057 <command>named-checkconf</command> 1058 <arg>-jvz</arg> 1059 <arg>-t <replaceable>directory</replaceable></arg> 1060 <arg><replaceable>filename</replaceable></arg> 1061 </cmdsynopsis> 1062 </listitem> 1063 </varlistentry> 1064 <varlistentry id="named-checkzone" xreflabel="Zone Checking application"> 1065 1066 <term><command>named-checkzone</command></term> 1067 <listitem> 1068 <para> 1069 The <command>named-checkzone</command> program 1070 checks a master file for 1071 syntax and consistency. 1072 </para> 1073 <cmdsynopsis label="Usage"> 1074 <command>named-checkzone</command> 1075 <arg>-djqvD</arg> 1076 <arg>-c <replaceable>class</replaceable></arg> 1077 <arg>-o <replaceable>output</replaceable></arg> 1078 <arg>-t <replaceable>directory</replaceable></arg> 1079 <arg>-w <replaceable>directory</replaceable></arg> 1080 <arg>-k <replaceable>(ignore|warn|fail)</replaceable></arg> 1081 <arg>-n <replaceable>(ignore|warn|fail)</replaceable></arg> 1082 <arg>-W <replaceable>(ignore|warn)</replaceable></arg> 1083 <arg choice="plain"><replaceable>zone</replaceable></arg> 1084 <arg><replaceable>filename</replaceable></arg> 1085 </cmdsynopsis> 1086 </listitem> 1087 </varlistentry> 1088 <varlistentry id="named-compilezone" xreflabel="Zone Compilation application"> 1089 <term><command>named-compilezone</command></term> 1090 <listitem> 1091 <para> 1092 Similar to <command>named-checkzone,</command> but 1093 it always dumps the zone content to a specified file 1094 (typically in a different format). 1095 </para> 1096 </listitem> 1097 </varlistentry> 1098 <varlistentry id="rndc" xreflabel="Remote Name Daemon Control application"> 1099 1100 <term><command>rndc</command></term> 1101 <listitem> 1102 <para> 1103 The remote name daemon control 1104 (<command>rndc</command>) program allows the 1105 system 1106 administrator to control the operation of a name server. 1107 Since <acronym>BIND</acronym> 9.2, <command>rndc</command> 1108 supports all the commands of the BIND 8 <command>ndc</command> 1109 utility except <command>ndc start</command> and 1110 <command>ndc restart</command>, which were also 1111 not supported in <command>ndc</command>'s 1112 channel mode. 1113 If you run <command>rndc</command> without any 1114 options 1115 it will display a usage message as follows: 1116 </para> 1117 <cmdsynopsis label="Usage"> 1118 <command>rndc</command> 1119 <arg>-c <replaceable>config</replaceable></arg> 1120 <arg>-s <replaceable>server</replaceable></arg> 1121 <arg>-p <replaceable>port</replaceable></arg> 1122 <arg>-y <replaceable>key</replaceable></arg> 1123 <arg choice="plain"><replaceable>command</replaceable></arg> 1124 <arg rep="repeat"><replaceable>command</replaceable></arg> 1125 </cmdsynopsis> 1126 <para>The <command>command</command> 1127 is one of the following: 1128 </para> 1129 1130 <variablelist> 1131 1132 <varlistentry> 1133 <term><userinput>reload</userinput></term> 1134 <listitem> 1135 <para> 1136 Reload configuration file and zones. 1137 </para> 1138 </listitem> 1139 </varlistentry> 1140 1141 <varlistentry> 1142 <term><userinput>reload <replaceable>zone</replaceable> 1143 <optional><replaceable>class</replaceable> 1144 <optional><replaceable>view</replaceable></optional></optional></userinput></term> 1145 <listitem> 1146 <para> 1147 Reload the given zone. 1148 </para> 1149 </listitem> 1150 </varlistentry> 1151 1152 <varlistentry> 1153 <term><userinput>refresh <replaceable>zone</replaceable> 1154 <optional><replaceable>class</replaceable> 1155 <optional><replaceable>view</replaceable></optional></optional></userinput></term> 1156 <listitem> 1157 <para> 1158 Schedule zone maintenance for the given zone. 1159 </para> 1160 </listitem> 1161 </varlistentry> 1162 1163 <varlistentry> 1164 <term><userinput>retransfer <replaceable>zone</replaceable> 1165 1166 <optional><replaceable>class</replaceable> 1167 <optional><replaceable>view</replaceable></optional></optional></userinput></term> 1168 <listitem> 1169 <para> 1170 Retransfer the given zone from the master. 1171 </para> 1172 </listitem> 1173 </varlistentry> 1174 1175 <varlistentry> 1176 <term><userinput>sign <replaceable>zone</replaceable> 1177 <optional><replaceable>class</replaceable> 1178 <optional><replaceable>view</replaceable></optional></optional></userinput></term> 1179 <listitem> 1180 <para> 1181 Fetch all DNSSEC keys for the given zone 1182 from the key directory (see 1183 <command>key-directory</command> in 1184 <xref linkend="options"/>). If they are within 1185 their publication period, merge them into the 1186 zone's DNSKEY RRset. If the DNSKEY RRset 1187 is changed, then the zone is automatically 1188 re-signed with the new key set. 1189 </para> 1190 <para> 1191 This command requires that the 1192 <command>auto-dnssec</command> zone option be set 1193 to <literal>allow</literal> or 1194 <literal>maintain</literal>, 1195 and also requires the zone to be configured to 1196 allow dynamic DNS. 1197 See <xref linkend="dynamic_update_policies"/> for 1198 more details. 1199 </para> 1200 </listitem> 1201 </varlistentry> 1202 1203 <varlistentry> 1204 <term><userinput>loadkeys <replaceable>zone</replaceable> 1205 <optional><replaceable>class</replaceable> 1206 <optional><replaceable>view</replaceable></optional></optional></userinput></term> 1207 <listitem> 1208 <para> 1209 Fetch all DNSSEC keys for the given zone 1210 from the key directory (see 1211 <command>key-directory</command> in 1212 <xref linkend="options"/>). If they are within 1213 their publication period, merge them into the 1214 zone's DNSKEY RRset. Unlike <command>rndc 1215 sign</command>, however, the zone is not 1216 immediately re-signed by the new keys, but is 1217 allowed to incrementally re-sign over time. 1218 </para> 1219 <para> 1220 This command requires that the 1221 <command>auto-dnssec</command> zone option 1222 be set to <literal>maintain</literal>, 1223 and also requires the zone to be configured to 1224 allow dynamic DNS. 1225 See <xref linkend="dynamic_update_policies"/> for 1226 more details. 1227 </para> 1228 </listitem> 1229 </varlistentry> 1230 1231 <varlistentry> 1232 <term><userinput>freeze 1233 <optional><replaceable>zone</replaceable> 1234 <optional><replaceable>class</replaceable> 1235 <optional><replaceable>view</replaceable></optional></optional></optional></userinput></term> 1236 <listitem> 1237 <para> 1238 Suspend updates to a dynamic zone. If no zone is 1239 specified, 1240 then all zones are suspended. This allows manual 1241 edits to be made to a zone normally updated by dynamic 1242 update. It 1243 also causes changes in the journal file to be synced 1244 into the master 1245 and the journal file to be removed. All dynamic 1246 update attempts will 1247 be refused while the zone is frozen. 1248 </para> 1249 </listitem> 1250 </varlistentry> 1251 1252 <varlistentry> 1253 <term><userinput>thaw 1254 <optional><replaceable>zone</replaceable> 1255 <optional><replaceable>class</replaceable> 1256 <optional><replaceable>view</replaceable></optional></optional></optional></userinput></term> 1257 <listitem> 1258 <para> 1259 Enable updates to a frozen dynamic zone. If no zone 1260 is 1261 specified, then all frozen zones are enabled. This 1262 causes 1263 the server to reload the zone from disk, and 1264 re-enables dynamic updates 1265 after the load has completed. After a zone is thawed, 1266 dynamic updates 1267 will no longer be refused. 1268 </para> 1269 </listitem> 1270 </varlistentry> 1271 1272 <varlistentry> 1273 <term><userinput>notify <replaceable>zone</replaceable> 1274 <optional><replaceable>class</replaceable> 1275 <optional><replaceable>view</replaceable></optional></optional></userinput></term> 1276 <listitem> 1277 <para> 1278 Resend NOTIFY messages for the zone. 1279 </para> 1280 </listitem> 1281 </varlistentry> 1282 1283 <varlistentry> 1284 <term><userinput>reconfig</userinput></term> 1285 <listitem> 1286 <para> 1287 Reload the configuration file and load new zones, 1288 but do not reload existing zone files even if they 1289 have changed. 1290 This is faster than a full <command>reload</command> when there 1291 is a large number of zones because it avoids the need 1292 to examine the 1293 modification times of the zones files. 1294 </para> 1295 </listitem> 1296 </varlistentry> 1297 1298 <varlistentry> 1299 <term><userinput>stats</userinput></term> 1300 <listitem> 1301 <para> 1302 Write server statistics to the statistics file. 1303 </para> 1304 </listitem> 1305 </varlistentry> 1306 1307 <varlistentry> 1308 <term><userinput>querylog</userinput></term> 1309 <listitem> 1310 <para> 1311 Toggle query logging. Query logging can also be enabled 1312 by explicitly directing the <command>queries</command> 1313 <command>category</command> to a 1314 <command>channel</command> in the 1315 <command>logging</command> section of 1316 <filename>named.conf</filename> or by specifying 1317 <command>querylog yes;</command> in the 1318 <command>options</command> section of 1319 <filename>named.conf</filename>. 1320 </para> 1321 </listitem> 1322 </varlistentry> 1323 1324 <varlistentry> 1325 <term><userinput>dumpdb 1326 <optional>-all|-cache|-zone</optional> 1327 <optional><replaceable>view ...</replaceable></optional></userinput></term> 1328 <listitem> 1329 <para> 1330 Dump the server's caches (default) and/or zones to 1331 the 1332 dump file for the specified views. If no view is 1333 specified, all 1334 views are dumped. 1335 </para> 1336 </listitem> 1337 </varlistentry> 1338 1339 <varlistentry> 1340 <term><userinput>secroots 1341 <optional><replaceable>view ...</replaceable></optional></userinput></term> 1342 <listitem> 1343 <para> 1344 Dump the server's security roots to the secroots 1345 file for the specified views. If no view is 1346 specified, security roots for all 1347 views are dumped. 1348 </para> 1349 </listitem> 1350 </varlistentry> 1351 1352 <varlistentry> 1353 <term><userinput>stop <optional>-p</optional></userinput></term> 1354 <listitem> 1355 <para> 1356 Stop the server, making sure any recent changes 1357 made through dynamic update or IXFR are first saved to 1358 the master files of the updated zones. 1359 If <option>-p</option> is specified <command>named</command>'s process id is returned. 1360 This allows an external process to determine when <command>named</command> 1361 had completed stopping. 1362 </para> 1363 </listitem> 1364 </varlistentry> 1365 1366 <varlistentry> 1367 <term><userinput>halt <optional>-p</optional></userinput></term> 1368 <listitem> 1369 <para> 1370 Stop the server immediately. Recent changes 1371 made through dynamic update or IXFR are not saved to 1372 the master files, but will be rolled forward from the 1373 journal files when the server is restarted. 1374 If <option>-p</option> is specified <command>named</command>'s process id is returned. 1375 This allows an external process to determine when <command>named</command> 1376 had completed halting. 1377 </para> 1378 </listitem> 1379 </varlistentry> 1380 1381 <varlistentry> 1382 <term><userinput>trace</userinput></term> 1383 <listitem> 1384 <para> 1385 Increment the servers debugging level by one. 1386 </para> 1387 </listitem> 1388 </varlistentry> 1389 1390 <varlistentry> 1391 <term><userinput>trace <replaceable>level</replaceable></userinput></term> 1392 <listitem> 1393 <para> 1394 Sets the server's debugging level to an explicit 1395 value. 1396 </para> 1397 </listitem> 1398 </varlistentry> 1399 1400 <varlistentry> 1401 <term><userinput>notrace</userinput></term> 1402 <listitem> 1403 <para> 1404 Sets the server's debugging level to 0. 1405 </para> 1406 </listitem> 1407 </varlistentry> 1408 1409 <varlistentry> 1410 <term><userinput>flush</userinput></term> 1411 <listitem> 1412 <para> 1413 Flushes the server's cache. 1414 </para> 1415 </listitem> 1416 </varlistentry> 1417 1418 <varlistentry> 1419 <term><userinput>flushname</userinput> <replaceable>name</replaceable></term> 1420 <listitem> 1421 <para> 1422 Flushes the given name from the server's cache. 1423 </para> 1424 </listitem> 1425 </varlistentry> 1426 1427 <varlistentry> 1428 <term><userinput>status</userinput></term> 1429 <listitem> 1430 <para> 1431 Display status of the server. 1432 Note that the number of zones includes the internal <command>bind/CH</command> zone 1433 and the default <command>./IN</command> 1434 hint zone if there is not an 1435 explicit root zone configured. 1436 </para> 1437 </listitem> 1438 </varlistentry> 1439 1440 <varlistentry> 1441 <term><userinput>recursing</userinput></term> 1442 <listitem> 1443 <para> 1444 Dump the list of queries <command>named</command> is currently recursing 1445 on. 1446 </para> 1447 </listitem> 1448 </varlistentry> 1449 1450 <varlistentry> 1451 <term><userinput>validation 1452 <optional>on|off</optional> 1453 <optional><replaceable>view ...</replaceable></optional> 1454 </userinput></term> 1455 <listitem> 1456 <para> 1457 Enable or disable DNSSEC validation. 1458 Note <command>dnssec-enable</command> also needs to be 1459 set to <userinput>yes</userinput> to be effective. 1460 It defaults to enabled. 1461 </para> 1462 </listitem> 1463 </varlistentry> 1464 1465 <varlistentry> 1466 <term><userinput>tsig-list</userinput></term> 1467 <listitem> 1468 <para> 1469 List the names of all TSIG keys currently configured 1470 for use by <command>named</command> in each view. The 1471 list both statically configured keys and dynamic 1472 TKEY-negotiated keys. 1473 </para> 1474 </listitem> 1475 </varlistentry> 1476 1477 <varlistentry> 1478 <term><userinput>tsig-delete</userinput> 1479 <replaceable>keyname</replaceable> 1480 <optional><replaceable>view</replaceable></optional></term> 1481 <listitem> 1482 <para> 1483 Delete a given TKEY-negotated key from the server. 1484 (This does not apply to statically configured TSIG 1485 keys.) 1486 </para> 1487 </listitem> 1488 </varlistentry> 1489 1490 <varlistentry> 1491 <term><userinput>addzone 1492 <replaceable>zone</replaceable> 1493 <optional><replaceable>class</replaceable> 1494 <optional><replaceable>view</replaceable></optional></optional> 1495 <replaceable>configuration</replaceable> 1496 </userinput></term> 1497 <listitem> 1498 <para> 1499 Add a zone while the server is running. This 1500 command requires the 1501 <command>allow-new-zones</command> option to be set 1502 to <userinput>yes</userinput>. The 1503 <replaceable>configuration</replaceable> string 1504 specified on the command line is the zone 1505 configuration text that would ordinarily be 1506 placed in <filename>named.conf</filename>. 1507 </para> 1508 <para> 1509 The configuration is saved in a file called 1510 <filename><replaceable>hash</replaceable>.nzf</filename>, 1511 where <replaceable>hash</replaceable> is a 1512 cryptographic hash generated from the name of 1513 the view. When <command>named</command> is 1514 restarted, the file will be loaded into the view 1515 configuration, so that zones that were added 1516 can persist after a restart. 1517 </para> 1518 <para> 1519 This sample <command>addzone</command> command 1520 would add the zone <literal>example.com</literal> 1521 to the default view: 1522 </para> 1523 <para> 1524<prompt>$ </prompt><userinput>rndc addzone example.com '{ type master; file "example.com.db"; };'</userinput> 1525 </para> 1526 <para> 1527 (Note the brackets and semi-colon around the zone 1528 configuration text.) 1529 </para> 1530 </listitem> 1531 </varlistentry> 1532 1533 <varlistentry> 1534 <term><userinput>delzone 1535 <replaceable>zone</replaceable> 1536 <optional><replaceable>class</replaceable> 1537 <optional><replaceable>view</replaceable></optional></optional> 1538 </userinput></term> 1539 <listitem> 1540 <para> 1541 Delete a zone while the server is running. 1542 Only zones that were originally added via 1543 <command>rndc addzone</command> can be deleted 1544 in this matter. 1545 </para> 1546 </listitem> 1547 </varlistentry> 1548 1549 </variablelist> 1550 1551 <para> 1552 A configuration file is required, since all 1553 communication with the server is authenticated with 1554 digital signatures that rely on a shared secret, and 1555 there is no way to provide that secret other than with a 1556 configuration file. The default location for the 1557 <command>rndc</command> configuration file is 1558 <filename>/etc/rndc.conf</filename>, but an 1559 alternate 1560 location can be specified with the <option>-c</option> 1561 option. If the configuration file is not found, 1562 <command>rndc</command> will also look in 1563 <filename>/etc/rndc.key</filename> (or whatever 1564 <varname>sysconfdir</varname> was defined when 1565 the <acronym>BIND</acronym> build was 1566 configured). 1567 The <filename>rndc.key</filename> file is 1568 generated by 1569 running <command>rndc-confgen -a</command> as 1570 described in 1571 <xref linkend="controls_statement_definition_and_usage"/>. 1572 </para> 1573 1574 <para> 1575 The format of the configuration file is similar to 1576 that of <filename>named.conf</filename>, but 1577 limited to 1578 only four statements, the <command>options</command>, 1579 <command>key</command>, <command>server</command> and 1580 <command>include</command> 1581 statements. These statements are what associate the 1582 secret keys to the servers with which they are meant to 1583 be shared. The order of statements is not 1584 significant. 1585 </para> 1586 1587 <para> 1588 The <command>options</command> statement has 1589 three clauses: 1590 <command>default-server</command>, <command>default-key</command>, 1591 and <command>default-port</command>. 1592 <command>default-server</command> takes a 1593 host name or address argument and represents the server 1594 that will 1595 be contacted if no <option>-s</option> 1596 option is provided on the command line. 1597 <command>default-key</command> takes 1598 the name of a key as its argument, as defined by a <command>key</command> statement. 1599 <command>default-port</command> specifies the 1600 port to which 1601 <command>rndc</command> should connect if no 1602 port is given on the command line or in a 1603 <command>server</command> statement. 1604 </para> 1605 1606 <para> 1607 The <command>key</command> statement defines a 1608 key to be used 1609 by <command>rndc</command> when authenticating 1610 with 1611 <command>named</command>. Its syntax is 1612 identical to the 1613 <command>key</command> statement in <filename>named.conf</filename>. 1614 The keyword <userinput>key</userinput> is 1615 followed by a key name, which must be a valid 1616 domain name, though it need not actually be hierarchical; 1617 thus, 1618 a string like "<userinput>rndc_key</userinput>" is a valid 1619 name. 1620 The <command>key</command> statement has two 1621 clauses: 1622 <command>algorithm</command> and <command>secret</command>. 1623 While the configuration parser will accept any string as the 1624 argument 1625 to algorithm, currently only the string "<userinput>hmac-md5</userinput>" 1626 has any meaning. The secret is a base-64 encoded string 1627 as specified in RFC 3548. 1628 </para> 1629 1630 <para> 1631 The <command>server</command> statement 1632 associates a key 1633 defined using the <command>key</command> 1634 statement with a server. 1635 The keyword <userinput>server</userinput> is followed by a 1636 host name or address. The <command>server</command> statement 1637 has two clauses: <command>key</command> and <command>port</command>. 1638 The <command>key</command> clause specifies the 1639 name of the key 1640 to be used when communicating with this server, and the 1641 <command>port</command> clause can be used to 1642 specify the port <command>rndc</command> should 1643 connect 1644 to on the server. 1645 </para> 1646 1647 <para> 1648 A sample minimal configuration file is as follows: 1649 </para> 1650 1651<programlisting> 1652key rndc_key { 1653 algorithm "hmac-md5"; 1654 secret 1655 "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K"; 1656}; 1657options { 1658 default-server 127.0.0.1; 1659 default-key rndc_key; 1660}; 1661</programlisting> 1662 1663 <para> 1664 This file, if installed as <filename>/etc/rndc.conf</filename>, 1665 would allow the command: 1666 </para> 1667 1668 <para> 1669 <prompt>$ </prompt><userinput>rndc reload</userinput> 1670 </para> 1671 1672 <para> 1673 to connect to 127.0.0.1 port 953 and cause the name server 1674 to reload, if a name server on the local machine were 1675 running with 1676 following controls statements: 1677 </para> 1678 1679<programlisting> 1680controls { 1681 inet 127.0.0.1 1682 allow { localhost; } keys { rndc_key; }; 1683}; 1684</programlisting> 1685 1686 <para> 1687 and it had an identical key statement for 1688 <literal>rndc_key</literal>. 1689 </para> 1690 1691 <para> 1692 Running the <command>rndc-confgen</command> 1693 program will 1694 conveniently create a <filename>rndc.conf</filename> 1695 file for you, and also display the 1696 corresponding <command>controls</command> 1697 statement that you need to 1698 add to <filename>named.conf</filename>. 1699 Alternatively, 1700 you can run <command>rndc-confgen -a</command> 1701 to set up 1702 a <filename>rndc.key</filename> file and not 1703 modify 1704 <filename>named.conf</filename> at all. 1705 </para> 1706 1707 </listitem> 1708 </varlistentry> 1709 </variablelist> 1710 1711 </sect3> 1712 </sect2> 1713 <sect2> 1714 1715 <title>Signals</title> 1716 <para> 1717 Certain UNIX signals cause the name server to take specific 1718 actions, as described in the following table. These signals can 1719 be sent using the <command>kill</command> command. 1720 </para> 1721 <informaltable frame="all"> 1722 <tgroup cols="2"> 1723 <colspec colname="1" colnum="1" colsep="0" colwidth="1.125in"/> 1724 <colspec colname="2" colnum="2" colsep="0" colwidth="4.000in"/> 1725 <tbody> 1726 <row rowsep="0"> 1727 <entry colname="1"> 1728 <para><command>SIGHUP</command></para> 1729 </entry> 1730 <entry colname="2"> 1731 <para> 1732 Causes the server to read <filename>named.conf</filename> and 1733 reload the database. 1734 </para> 1735 </entry> 1736 </row> 1737 <row rowsep="0"> 1738 <entry colname="1"> 1739 <para><command>SIGTERM</command></para> 1740 </entry> 1741 <entry colname="2"> 1742 <para> 1743 Causes the server to clean up and exit. 1744 </para> 1745 </entry> 1746 </row> 1747 <row rowsep="0"> 1748 <entry colname="1"> 1749 <para><command>SIGINT</command></para> 1750 </entry> 1751 <entry colname="2"> 1752 <para> 1753 Causes the server to clean up and exit. 1754 </para> 1755 </entry> 1756 </row> 1757 </tbody> 1758 </tgroup> 1759 </informaltable> 1760 </sect2> 1761 </sect1> 1762 </chapter> 1763 1764 <chapter id="Bv9ARM.ch04"> 1765 <title>Advanced DNS Features</title> 1766 1767 <sect1 id="notify"> 1768 1769 <title>Notify</title> 1770 <para> 1771 <acronym>DNS</acronym> NOTIFY is a mechanism that allows master 1772 servers to notify their slave servers of changes to a zone's data. In 1773 response to a <command>NOTIFY</command> from a master server, the 1774 slave will check to see that its version of the zone is the 1775 current version and, if not, initiate a zone transfer. 1776 </para> 1777 1778 <para> 1779 For more information about <acronym>DNS</acronym> 1780 <command>NOTIFY</command>, see the description of the 1781 <command>notify</command> option in <xref linkend="boolean_options"/> and 1782 the description of the zone option <command>also-notify</command> in 1783 <xref linkend="zone_transfers"/>. The <command>NOTIFY</command> 1784 protocol is specified in RFC 1996. 1785 </para> 1786 1787 <note> 1788 As a slave zone can also be a master to other slaves, <command>named</command>, 1789 by default, sends <command>NOTIFY</command> messages for every zone 1790 it loads. Specifying <command>notify master-only;</command> will 1791 cause <command>named</command> to only send <command>NOTIFY</command> for master 1792 zones that it loads. 1793 </note> 1794 1795 </sect1> 1796 1797 <sect1 id="dynamic_update"> 1798 <title>Dynamic Update</title> 1799 1800 <para> 1801 Dynamic Update is a method for adding, replacing or deleting 1802 records in a master server by sending it a special form of DNS 1803 messages. The format and meaning of these messages is specified 1804 in RFC 2136. 1805 </para> 1806 1807 <para> 1808 Dynamic update is enabled by including an 1809 <command>allow-update</command> or an <command>update-policy</command> 1810 clause in the <command>zone</command> statement. 1811 </para> 1812 1813 <para> 1814 If the zone's <command>update-policy</command> is set to 1815 <userinput>local</userinput>, updates to the zone 1816 will be permitted for the key <varname>local-ddns</varname>, 1817 which will be generated by <command>named</command> at startup. 1818 See <xref linkend="dynamic_update_policies"/> for more details. 1819 </para> 1820 1821 <para> 1822 Dynamic updates using Kerberos signed requests can be made 1823 using the TKEY/GSS protocol by setting either the 1824 <command>tkey-gssapi-keytab</command> option, or alternatively 1825 by setting both the <command>tkey-gssapi-credential</command> 1826 and <command>tkey-domain</command> options. Once enabled, 1827 Kerberos signed requests will be matched against the update 1828 policies for the zone, using the Kerberos principal as the 1829 signer for the request. 1830 </para> 1831 1832 <para> 1833 Updating of secure zones (zones using DNSSEC) follows RFC 1834 3007: RRSIG, NSEC and NSEC3 records affected by updates are 1835 automatically regenerated by the server using an online 1836 zone key. Update authorization is based on transaction 1837 signatures and an explicit server policy. 1838 </para> 1839 1840 <sect2 id="journal"> 1841 <title>The journal file</title> 1842 1843 <para> 1844 All changes made to a zone using dynamic update are stored 1845 in the zone's journal file. This file is automatically created 1846 by the server when the first dynamic update takes place. 1847 The name of the journal file is formed by appending the extension 1848 <filename>.jnl</filename> to the name of the 1849 corresponding zone 1850 file unless specifically overridden. The journal file is in a 1851 binary format and should not be edited manually. 1852 </para> 1853 1854 <para> 1855 The server will also occasionally write ("dump") 1856 the complete contents of the updated zone to its zone file. 1857 This is not done immediately after 1858 each dynamic update, because that would be too slow when a large 1859 zone is updated frequently. Instead, the dump is delayed by 1860 up to 15 minutes, allowing additional updates to take place. 1861 During the dump process, transient files will be created 1862 with the extensions <filename>.jnw</filename> and 1863 <filename>.jbk</filename>; under ordinary circumstances, these 1864 will be removed when the dump is complete, and can be safely 1865 ignored. 1866 </para> 1867 1868 <para> 1869 When a server is restarted after a shutdown or crash, it will replay 1870 the journal file to incorporate into the zone any updates that 1871 took 1872 place after the last zone dump. 1873 </para> 1874 1875 <para> 1876 Changes that result from incoming incremental zone transfers are 1877 also 1878 journalled in a similar way. 1879 </para> 1880 1881 <para> 1882 The zone files of dynamic zones cannot normally be edited by 1883 hand because they are not guaranteed to contain the most recent 1884 dynamic changes — those are only in the journal file. 1885 The only way to ensure that the zone file of a dynamic zone 1886 is up to date is to run <command>rndc stop</command>. 1887 </para> 1888 1889 <para> 1890 If you have to make changes to a dynamic zone 1891 manually, the following procedure will work: Disable dynamic updates 1892 to the zone using 1893 <command>rndc freeze <replaceable>zone</replaceable></command>. 1894 This will also remove the zone's <filename>.jnl</filename> file 1895 and update the master file. Edit the zone file. Run 1896 <command>rndc thaw <replaceable>zone</replaceable></command> 1897 to reload the changed zone and re-enable dynamic updates. 1898 </para> 1899 1900 </sect2> 1901 1902 </sect1> 1903 1904 <sect1 id="incremental_zone_transfers"> 1905 <title>Incremental Zone Transfers (IXFR)</title> 1906 1907 <para> 1908 The incremental zone transfer (IXFR) protocol is a way for 1909 slave servers to transfer only changed data, instead of having to 1910 transfer the entire zone. The IXFR protocol is specified in RFC 1911 1995. See <xref linkend="proposed_standards"/>. 1912 </para> 1913 1914 <para> 1915 When acting as a master, <acronym>BIND</acronym> 9 1916 supports IXFR for those zones 1917 where the necessary change history information is available. These 1918 include master zones maintained by dynamic update and slave zones 1919 whose data was obtained by IXFR. For manually maintained master 1920 zones, and for slave zones obtained by performing a full zone 1921 transfer (AXFR), IXFR is supported only if the option 1922 <command>ixfr-from-differences</command> is set 1923 to <userinput>yes</userinput>. 1924 </para> 1925 1926 <para> 1927 When acting as a slave, <acronym>BIND</acronym> 9 will attempt 1928 to use IXFR unless it is explicitly disabled via the 1929 <command>request-ixfr</command> option or the use of 1930 <command>ixfr-from-differences</command>. For 1931 more information about disabling IXFR, see the description 1932 of the <command>request-ixfr</command> clause of the 1933 <command>server</command> statement. 1934 </para> 1935 </sect1> 1936 1937 <sect1> 1938 <title>Split DNS</title> 1939 <para> 1940 Setting up different views, or visibility, of the DNS space to 1941 internal and external resolvers is usually referred to as a 1942 <emphasis>Split DNS</emphasis> setup. There are several 1943 reasons an organization would want to set up its DNS this way. 1944 </para> 1945 <para> 1946 One common reason for setting up a DNS system this way is 1947 to hide "internal" DNS information from "external" clients on the 1948 Internet. There is some debate as to whether or not this is actually 1949 useful. 1950 Internal DNS information leaks out in many ways (via email headers, 1951 for example) and most savvy "attackers" can find the information 1952 they need using other means. 1953 However, since listing addresses of internal servers that 1954 external clients cannot possibly reach can result in 1955 connection delays and other annoyances, an organization may 1956 choose to use a Split DNS to present a consistent view of itself 1957 to the outside world. 1958 </para> 1959 <para> 1960 Another common reason for setting up a Split DNS system is 1961 to allow internal networks that are behind filters or in RFC 1918 1962 space (reserved IP space, as documented in RFC 1918) to resolve DNS 1963 on the Internet. Split DNS can also be used to allow mail from outside 1964 back in to the internal network. 1965 </para> 1966 <sect2> 1967 <title>Example split DNS setup</title> 1968 <para> 1969 Let's say a company named <emphasis>Example, Inc.</emphasis> 1970 (<literal>example.com</literal>) 1971 has several corporate sites that have an internal network with 1972 reserved 1973 Internet Protocol (IP) space and an external demilitarized zone (DMZ), 1974 or "outside" section of a network, that is available to the public. 1975 </para> 1976 <para> 1977 <emphasis>Example, Inc.</emphasis> wants its internal clients 1978 to be able to resolve external hostnames and to exchange mail with 1979 people on the outside. The company also wants its internal resolvers 1980 to have access to certain internal-only zones that are not available 1981 at all outside of the internal network. 1982 </para> 1983 <para> 1984 In order to accomplish this, the company will set up two sets 1985 of name servers. One set will be on the inside network (in the 1986 reserved 1987 IP space) and the other set will be on bastion hosts, which are 1988 "proxy" 1989 hosts that can talk to both sides of its network, in the DMZ. 1990 </para> 1991 <para> 1992 The internal servers will be configured to forward all queries, 1993 except queries for <filename>site1.internal</filename>, <filename>site2.internal</filename>, <filename>site1.example.com</filename>, 1994 and <filename>site2.example.com</filename>, to the servers 1995 in the 1996 DMZ. These internal servers will have complete sets of information 1997 for <filename>site1.example.com</filename>, <filename>site2.example.com</filename>, <filename>site1.internal</filename>, 1998 and <filename>site2.internal</filename>. 1999 </para> 2000 <para> 2001 To protect the <filename>site1.internal</filename> and <filename>site2.internal</filename> domains, 2002 the internal name servers must be configured to disallow all queries 2003 to these domains from any external hosts, including the bastion 2004 hosts. 2005 </para> 2006 <para> 2007 The external servers, which are on the bastion hosts, will 2008 be configured to serve the "public" version of the <filename>site1</filename> and <filename>site2.example.com</filename> zones. 2009 This could include things such as the host records for public servers 2010 (<filename>www.example.com</filename> and <filename>ftp.example.com</filename>), 2011 and mail exchange (MX) records (<filename>a.mx.example.com</filename> and <filename>b.mx.example.com</filename>). 2012 </para> 2013 <para> 2014 In addition, the public <filename>site1</filename> and <filename>site2.example.com</filename> zones 2015 should have special MX records that contain wildcard (`*') records 2016 pointing to the bastion hosts. This is needed because external mail 2017 servers do not have any other way of looking up how to deliver mail 2018 to those internal hosts. With the wildcard records, the mail will 2019 be delivered to the bastion host, which can then forward it on to 2020 internal hosts. 2021 </para> 2022 <para> 2023 Here's an example of a wildcard MX record: 2024 </para> 2025 <programlisting>* IN MX 10 external1.example.com.</programlisting> 2026 <para> 2027 Now that they accept mail on behalf of anything in the internal 2028 network, the bastion hosts will need to know how to deliver mail 2029 to internal hosts. In order for this to work properly, the resolvers 2030 on 2031 the bastion hosts will need to be configured to point to the internal 2032 name servers for DNS resolution. 2033 </para> 2034 <para> 2035 Queries for internal hostnames will be answered by the internal 2036 servers, and queries for external hostnames will be forwarded back 2037 out to the DNS servers on the bastion hosts. 2038 </para> 2039 <para> 2040 In order for all this to work properly, internal clients will 2041 need to be configured to query <emphasis>only</emphasis> the internal 2042 name servers for DNS queries. This could also be enforced via 2043 selective 2044 filtering on the network. 2045 </para> 2046 <para> 2047 If everything has been set properly, <emphasis>Example, Inc.</emphasis>'s 2048 internal clients will now be able to: 2049 </para> 2050 <itemizedlist> 2051 <listitem> 2052 <simpara> 2053 Look up any hostnames in the <literal>site1</literal> 2054 and 2055 <literal>site2.example.com</literal> zones. 2056 </simpara> 2057 </listitem> 2058 <listitem> 2059 <simpara> 2060 Look up any hostnames in the <literal>site1.internal</literal> and 2061 <literal>site2.internal</literal> domains. 2062 </simpara> 2063 </listitem> 2064 <listitem> 2065 <simpara>Look up any hostnames on the Internet.</simpara> 2066 </listitem> 2067 <listitem> 2068 <simpara>Exchange mail with both internal and external people.</simpara> 2069 </listitem> 2070 </itemizedlist> 2071 <para> 2072 Hosts on the Internet will be able to: 2073 </para> 2074 <itemizedlist> 2075 <listitem> 2076 <simpara> 2077 Look up any hostnames in the <literal>site1</literal> 2078 and 2079 <literal>site2.example.com</literal> zones. 2080 </simpara> 2081 </listitem> 2082 <listitem> 2083 <simpara> 2084 Exchange mail with anyone in the <literal>site1</literal> and 2085 <literal>site2.example.com</literal> zones. 2086 </simpara> 2087 </listitem> 2088 </itemizedlist> 2089 2090 <para> 2091 Here is an example configuration for the setup we just 2092 described above. Note that this is only configuration information; 2093 for information on how to configure your zone files, see <xref linkend="sample_configuration"/>. 2094 </para> 2095 2096 <para> 2097 Internal DNS server config: 2098 </para> 2099 2100<programlisting> 2101 2102acl internals { 172.16.72.0/24; 192.168.1.0/24; }; 2103 2104acl externals { <varname>bastion-ips-go-here</varname>; }; 2105 2106options { 2107 ... 2108 ... 2109 forward only; 2110 // forward to external servers 2111 forwarders { 2112 <varname>bastion-ips-go-here</varname>; 2113 }; 2114 // sample allow-transfer (no one) 2115 allow-transfer { none; }; 2116 // restrict query access 2117 allow-query { internals; externals; }; 2118 // restrict recursion 2119 allow-recursion { internals; }; 2120 ... 2121 ... 2122}; 2123 2124// sample master zone 2125zone "site1.example.com" { 2126 type master; 2127 file "m/site1.example.com"; 2128 // do normal iterative resolution (do not forward) 2129 forwarders { }; 2130 allow-query { internals; externals; }; 2131 allow-transfer { internals; }; 2132}; 2133 2134// sample slave zone 2135zone "site2.example.com" { 2136 type slave; 2137 file "s/site2.example.com"; 2138 masters { 172.16.72.3; }; 2139 forwarders { }; 2140 allow-query { internals; externals; }; 2141 allow-transfer { internals; }; 2142}; 2143 2144zone "site1.internal" { 2145 type master; 2146 file "m/site1.internal"; 2147 forwarders { }; 2148 allow-query { internals; }; 2149 allow-transfer { internals; } 2150}; 2151 2152zone "site2.internal" { 2153 type slave; 2154 file "s/site2.internal"; 2155 masters { 172.16.72.3; }; 2156 forwarders { }; 2157 allow-query { internals }; 2158 allow-transfer { internals; } 2159}; 2160</programlisting> 2161 2162 <para> 2163 External (bastion host) DNS server config: 2164 </para> 2165 2166<programlisting> 2167acl internals { 172.16.72.0/24; 192.168.1.0/24; }; 2168 2169acl externals { bastion-ips-go-here; }; 2170 2171options { 2172 ... 2173 ... 2174 // sample allow-transfer (no one) 2175 allow-transfer { none; }; 2176 // default query access 2177 allow-query { any; }; 2178 // restrict cache access 2179 allow-query-cache { internals; externals; }; 2180 // restrict recursion 2181 allow-recursion { internals; externals; }; 2182 ... 2183 ... 2184}; 2185 2186// sample slave zone 2187zone "site1.example.com" { 2188 type master; 2189 file "m/site1.foo.com"; 2190 allow-transfer { internals; externals; }; 2191}; 2192 2193zone "site2.example.com" { 2194 type slave; 2195 file "s/site2.foo.com"; 2196 masters { another_bastion_host_maybe; }; 2197 allow-transfer { internals; externals; } 2198}; 2199</programlisting> 2200 2201 <para> 2202 In the <filename>resolv.conf</filename> (or equivalent) on 2203 the bastion host(s): 2204 </para> 2205 2206<programlisting> 2207search ... 2208nameserver 172.16.72.2 2209nameserver 172.16.72.3 2210nameserver 172.16.72.4 2211</programlisting> 2212 2213 </sect2> 2214 </sect1> 2215 <sect1 id="tsig"> 2216 <title>TSIG</title> 2217 <para> 2218 This is a short guide to setting up Transaction SIGnatures 2219 (TSIG) based transaction security in <acronym>BIND</acronym>. It describes changes 2220 to the configuration file as well as what changes are required for 2221 different features, including the process of creating transaction 2222 keys and using transaction signatures with <acronym>BIND</acronym>. 2223 </para> 2224 <para> 2225 <acronym>BIND</acronym> primarily supports TSIG for server 2226 to server communication. 2227 This includes zone transfer, notify, and recursive query messages. 2228 Resolvers based on newer versions of <acronym>BIND</acronym> 8 have limited support 2229 for TSIG. 2230 </para> 2231 2232 <para> 2233 TSIG can also be useful for dynamic update. A primary 2234 server for a dynamic zone should control access to the dynamic 2235 update service, but IP-based access control is insufficient. 2236 The cryptographic access control provided by TSIG 2237 is far superior. The <command>nsupdate</command> 2238 program supports TSIG via the <option>-k</option> and 2239 <option>-y</option> command line options or inline by use 2240 of the <command>key</command>. 2241 </para> 2242 2243 <sect2> 2244 <title>Generate Shared Keys for Each Pair of Hosts</title> 2245 <para> 2246 A shared secret is generated to be shared between <emphasis>host1</emphasis> and <emphasis>host2</emphasis>. 2247 An arbitrary key name is chosen: "host1-host2.". The key name must 2248 be the same on both hosts. 2249 </para> 2250 <sect3> 2251 <title>Automatic Generation</title> 2252 <para> 2253 The following command will generate a 128-bit (16 byte) HMAC-SHA256 2254 key as described above. Longer keys are better, but shorter keys 2255 are easier to read. Note that the maximum key length is the digest 2256 length, here 256 bits. 2257 </para> 2258 <para> 2259 <userinput>dnssec-keygen -a hmac-sha256 -b 128 -n HOST host1-host2.</userinput> 2260 </para> 2261 <para> 2262 The key is in the file <filename>Khost1-host2.+163+00000.private</filename>. 2263 Nothing directly uses this file, but the base-64 encoded string 2264 following "<literal>Key:</literal>" 2265 can be extracted from the file and used as a shared secret: 2266 </para> 2267 <programlisting>Key: La/E5CjG9O+os1jq0a2jdA==</programlisting> 2268 <para> 2269 The string "<literal>La/E5CjG9O+os1jq0a2jdA==</literal>" can 2270 be used as the shared secret. 2271 </para> 2272 </sect3> 2273 <sect3> 2274 <title>Manual Generation</title> 2275 <para> 2276 The shared secret is simply a random sequence of bits, encoded 2277 in base-64. Most ASCII strings are valid base-64 strings (assuming 2278 the length is a multiple of 4 and only valid characters are used), 2279 so the shared secret can be manually generated. 2280 </para> 2281 <para> 2282 Also, a known string can be run through <command>mmencode</command> or 2283 a similar program to generate base-64 encoded data. 2284 </para> 2285 </sect3> 2286 </sect2> 2287 <sect2> 2288 <title>Copying the Shared Secret to Both Machines</title> 2289 <para> 2290 This is beyond the scope of DNS. A secure transport mechanism 2291 should be used. This could be secure FTP, ssh, telephone, etc. 2292 </para> 2293 </sect2> 2294 <sect2> 2295 <title>Informing the Servers of the Key's Existence</title> 2296 <para> 2297 Imagine <emphasis>host1</emphasis> and <emphasis>host 2</emphasis> 2298 are 2299 both servers. The following is added to each server's <filename>named.conf</filename> file: 2300 </para> 2301 2302<programlisting> 2303key host1-host2. { 2304 algorithm hmac-sha256; 2305 secret "La/E5CjG9O+os1jq0a2jdA=="; 2306}; 2307</programlisting> 2308 2309 <para> 2310 The secret is the one generated above. Since this is a secret, it 2311 is recommended that either <filename>named.conf</filename> be 2312 non-world readable, or the key directive be added to a non-world 2313 readable file that is included by <filename>named.conf</filename>. 2314 </para> 2315 <para> 2316 At this point, the key is recognized. This means that if the 2317 server receives a message signed by this key, it can verify the 2318 signature. If the signature is successfully verified, the 2319 response is signed by the same key. 2320 </para> 2321 </sect2> 2322 2323 <sect2> 2324 <title>Instructing the Server to Use the Key</title> 2325 <para> 2326 Since keys are shared between two hosts only, the server must 2327 be told when keys are to be used. The following is added to the <filename>named.conf</filename> file 2328 for <emphasis>host1</emphasis>, if the IP address of <emphasis>host2</emphasis> is 2329 10.1.2.3: 2330 </para> 2331 2332<programlisting> 2333server 10.1.2.3 { 2334 keys { host1-host2. ;}; 2335}; 2336</programlisting> 2337 2338 <para> 2339 Multiple keys may be present, but only the first is used. 2340 This directive does not contain any secrets, so it may be in a 2341 world-readable 2342 file. 2343 </para> 2344 <para> 2345 If <emphasis>host1</emphasis> sends a message that is a request 2346 to that address, the message will be signed with the specified key. <emphasis>host1</emphasis> will 2347 expect any responses to signed messages to be signed with the same 2348 key. 2349 </para> 2350 <para> 2351 A similar statement must be present in <emphasis>host2</emphasis>'s 2352 configuration file (with <emphasis>host1</emphasis>'s address) for <emphasis>host2</emphasis> to 2353 sign request messages to <emphasis>host1</emphasis>. 2354 </para> 2355 </sect2> 2356 <sect2> 2357 <title>TSIG Key Based Access Control</title> 2358 <para> 2359 <acronym>BIND</acronym> allows IP addresses and ranges 2360 to be specified in ACL 2361 definitions and 2362 <command>allow-{ query | transfer | update }</command> 2363 directives. 2364 This has been extended to allow TSIG keys also. The above key would 2365 be denoted <command>key host1-host2.</command> 2366 </para> 2367 <para> 2368 An example of an <command>allow-update</command> directive would be: 2369 </para> 2370 2371<programlisting> 2372allow-update { key host1-host2. ;}; 2373</programlisting> 2374 2375 <para> 2376 This allows dynamic updates to succeed only if the request 2377 was signed by a key named "<command>host1-host2.</command>". 2378 </para> 2379 2380 <para> 2381 See <xref linkend="dynamic_update_policies"/> for a discussion of 2382 the more flexible <command>update-policy</command> statement. 2383 </para> 2384 2385 </sect2> 2386 <sect2> 2387 <title>Errors</title> 2388 2389 <para> 2390 The processing of TSIG signed messages can result in 2391 several errors. If a signed message is sent to a non-TSIG aware 2392 server, a FORMERR (format error) will be returned, since the server will not 2393 understand the record. This is a result of misconfiguration, 2394 since the server must be explicitly configured to send a TSIG 2395 signed message to a specific server. 2396 </para> 2397 2398 <para> 2399 If a TSIG aware server receives a message signed by an 2400 unknown key, the response will be unsigned with the TSIG 2401 extended error code set to BADKEY. If a TSIG aware server 2402 receives a message with a signature that does not validate, the 2403 response will be unsigned with the TSIG extended error code set 2404 to BADSIG. If a TSIG aware server receives a message with a time 2405 outside of the allowed range, the response will be signed with 2406 the TSIG extended error code set to BADTIME, and the time values 2407 will be adjusted so that the response can be successfully 2408 verified. In any of these cases, the message's rcode (response code) is set to 2409 NOTAUTH (not authenticated). 2410 </para> 2411 2412 </sect2> 2413 </sect1> 2414 <sect1> 2415 <title>TKEY</title> 2416 2417 <para><command>TKEY</command> 2418 is a mechanism for automatically generating a shared secret 2419 between two hosts. There are several "modes" of 2420 <command>TKEY</command> that specify how the key is generated 2421 or assigned. <acronym>BIND</acronym> 9 implements only one of 2422 these modes, the Diffie-Hellman key exchange. Both hosts are 2423 required to have a Diffie-Hellman KEY record (although this 2424 record is not required to be present in a zone). The 2425 <command>TKEY</command> process must use signed messages, 2426 signed either by TSIG or SIG(0). The result of 2427 <command>TKEY</command> is a shared secret that can be used to 2428 sign messages with TSIG. <command>TKEY</command> can also be 2429 used to delete shared secrets that it had previously 2430 generated. 2431 </para> 2432 2433 <para> 2434 The <command>TKEY</command> process is initiated by a 2435 client 2436 or server by sending a signed <command>TKEY</command> 2437 query 2438 (including any appropriate KEYs) to a TKEY-aware server. The 2439 server response, if it indicates success, will contain a 2440 <command>TKEY</command> record and any appropriate keys. 2441 After 2442 this exchange, both participants have enough information to 2443 determine the shared secret; the exact process depends on the 2444 <command>TKEY</command> mode. When using the 2445 Diffie-Hellman 2446 <command>TKEY</command> mode, Diffie-Hellman keys are 2447 exchanged, 2448 and the shared secret is derived by both participants. 2449 </para> 2450 2451 </sect1> 2452 <sect1> 2453 <title>SIG(0)</title> 2454 2455 <para> 2456 <acronym>BIND</acronym> 9 partially supports DNSSEC SIG(0) 2457 transaction signatures as specified in RFC 2535 and RFC 2931. 2458 SIG(0) 2459 uses public/private keys to authenticate messages. Access control 2460 is performed in the same manner as TSIG keys; privileges can be 2461 granted or denied based on the key name. 2462 </para> 2463 2464 <para> 2465 When a SIG(0) signed message is received, it will only be 2466 verified if the key is known and trusted by the server; the server 2467 will not attempt to locate and/or validate the key. 2468 </para> 2469 2470 <para> 2471 SIG(0) signing of multiple-message TCP streams is not 2472 supported. 2473 </para> 2474 2475 <para> 2476 The only tool shipped with <acronym>BIND</acronym> 9 that 2477 generates SIG(0) signed messages is <command>nsupdate</command>. 2478 </para> 2479 2480 </sect1> 2481 <sect1 id="DNSSEC"> 2482 <title>DNSSEC</title> 2483 2484 <para> 2485 Cryptographic authentication of DNS information is possible 2486 through the DNS Security (<emphasis>DNSSEC-bis</emphasis>) extensions, 2487 defined in RFC 4033, RFC 4034, and RFC 4035. 2488 This section describes the creation and use of DNSSEC signed zones. 2489 </para> 2490 2491 <para> 2492 In order to set up a DNSSEC secure zone, there are a series 2493 of steps which must be followed. <acronym>BIND</acronym> 2494 9 ships 2495 with several tools 2496 that are used in this process, which are explained in more detail 2497 below. In all cases, the <option>-h</option> option prints a 2498 full list of parameters. Note that the DNSSEC tools require the 2499 keyset files to be in the working directory or the 2500 directory specified by the <option>-d</option> option, and 2501 that the tools shipped with BIND 9.2.x and earlier are not compatible 2502 with the current ones. 2503 </para> 2504 2505 <para> 2506 There must also be communication with the administrators of 2507 the parent and/or child zone to transmit keys. A zone's security 2508 status must be indicated by the parent zone for a DNSSEC capable 2509 resolver to trust its data. This is done through the presence 2510 or absence of a <literal>DS</literal> record at the 2511 delegation 2512 point. 2513 </para> 2514 2515 <para> 2516 For other servers to trust data in this zone, they must 2517 either be statically configured with this zone's zone key or the 2518 zone key of another zone above this one in the DNS tree. 2519 </para> 2520 2521 <sect2> 2522 <title>Generating Keys</title> 2523 2524 <para> 2525 The <command>dnssec-keygen</command> program is used to 2526 generate keys. 2527 </para> 2528 2529 <para> 2530 A secure zone must contain one or more zone keys. The 2531 zone keys will sign all other records in the zone, as well as 2532 the zone keys of any secure delegated zones. Zone keys must 2533 have the same name as the zone, a name type of 2534 <command>ZONE</command>, and must be usable for 2535 authentication. 2536 It is recommended that zone keys use a cryptographic algorithm 2537 designated as "mandatory to implement" by the IETF; currently 2538 the only one is RSASHA1. 2539 </para> 2540 2541 <para> 2542 The following command will generate a 768-bit RSASHA1 key for 2543 the <filename>child.example</filename> zone: 2544 </para> 2545 2546 <para> 2547 <userinput>dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example.</userinput> 2548 </para> 2549 2550 <para> 2551 Two output files will be produced: 2552 <filename>Kchild.example.+005+12345.key</filename> and 2553 <filename>Kchild.example.+005+12345.private</filename> 2554 (where 2555 12345 is an example of a key tag). The key filenames contain 2556 the key name (<filename>child.example.</filename>), 2557 algorithm (3 2558 is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in 2559 this case). 2560 The private key (in the <filename>.private</filename> 2561 file) is 2562 used to generate signatures, and the public key (in the 2563 <filename>.key</filename> file) is used for signature 2564 verification. 2565 </para> 2566 2567 <para> 2568 To generate another key with the same properties (but with 2569 a different key tag), repeat the above command. 2570 </para> 2571 2572 <para> 2573 The <command>dnssec-keyfromlabel</command> program is used 2574 to get a key pair from a crypto hardware and build the key 2575 files. Its usage is similar to <command>dnssec-keygen</command>. 2576 </para> 2577 2578 <para> 2579 The public keys should be inserted into the zone file by 2580 including the <filename>.key</filename> files using 2581 <command>$INCLUDE</command> statements. 2582 </para> 2583 2584 </sect2> 2585 <sect2> 2586 <title>Signing the Zone</title> 2587 2588 <para> 2589 The <command>dnssec-signzone</command> program is used 2590 to sign a zone. 2591 </para> 2592 2593 <para> 2594 Any <filename>keyset</filename> files corresponding to 2595 secure subzones should be present. The zone signer will 2596 generate <literal>NSEC</literal>, <literal>NSEC3</literal> 2597 and <literal>RRSIG</literal> records for the zone, as 2598 well as <literal>DS</literal> for the child zones if 2599 <literal>'-g'</literal> is specified. If <literal>'-g'</literal> 2600 is not specified, then DS RRsets for the secure child 2601 zones need to be added manually. 2602 </para> 2603 2604 <para> 2605 The following command signs the zone, assuming it is in a 2606 file called <filename>zone.child.example</filename>. By 2607 default, all zone keys which have an available private key are 2608 used to generate signatures. 2609 </para> 2610 2611 <para> 2612 <userinput>dnssec-signzone -o child.example zone.child.example</userinput> 2613 </para> 2614 2615 <para> 2616 One output file is produced: 2617 <filename>zone.child.example.signed</filename>. This 2618 file 2619 should be referenced by <filename>named.conf</filename> 2620 as the 2621 input file for the zone. 2622 </para> 2623 2624 <para><command>dnssec-signzone</command> 2625 will also produce a keyset and dsset files and optionally a 2626 dlvset file. These are used to provide the parent zone 2627 administrators with the <literal>DNSKEYs</literal> (or their 2628 corresponding <literal>DS</literal> records) that are the 2629 secure entry point to the zone. 2630 </para> 2631 2632 </sect2> 2633 2634 <sect2> 2635 <title>Configuring Servers</title> 2636 2637 <para> 2638 To enable <command>named</command> to respond appropriately 2639 to DNS requests from DNSSEC aware clients, 2640 <command>dnssec-enable</command> must be set to yes. 2641 (This is the default setting.) 2642 </para> 2643 2644 <para> 2645 To enable <command>named</command> to validate answers from 2646 other servers, the <command>dnssec-enable</command> option 2647 must be set to <userinput>yes</userinput>, and the 2648 <command>dnssec-validation</command> options must be set to 2649 <userinput>yes</userinput> or <userinput>auto</userinput>. 2650 </para> 2651 2652 <para> 2653 If <command>dnssec-validation</command> is set to 2654 <userinput>auto</userinput>, then a default 2655 trust anchor for the DNS root zone will be used. 2656 If it is set to <userinput>yes</userinput>, however, 2657 then at least one trust anchor must be configured 2658 with a <command>trusted-keys</command> or 2659 <command>managed-keys</command> statement in 2660 <filename>named.conf</filename>, or DNSSEC validation 2661 will not occur. The default setting is 2662 <userinput>yes</userinput>. 2663 </para> 2664 2665 <para> 2666 <command>trusted-keys</command> are copies of DNSKEY RRs 2667 for zones that are used to form the first link in the 2668 cryptographic chain of trust. All keys listed in 2669 <command>trusted-keys</command> (and corresponding zones) 2670 are deemed to exist and only the listed keys will be used 2671 to validated the DNSKEY RRset that they are from. 2672 </para> 2673 2674 <para> 2675 <command>managed-keys</command> are trusted keys which are 2676 automatically kept up to date via RFC 5011 trust anchor 2677 maintenance. 2678 </para> 2679 2680 <para> 2681 <command>trusted-keys</command> and 2682 <command>managed-keys</command> are described in more detail 2683 later in this document. 2684 </para> 2685 2686 <para> 2687 Unlike <acronym>BIND</acronym> 8, <acronym>BIND</acronym> 2688 9 does not verify signatures on load, so zone keys for 2689 authoritative zones do not need to be specified in the 2690 configuration file. 2691 </para> 2692 2693 <para> 2694 After DNSSEC gets established, a typical DNSSEC configuration 2695 will look something like the following. It has one or 2696 more public keys for the root. This allows answers from 2697 outside the organization to be validated. It will also 2698 have several keys for parts of the namespace the organization 2699 controls. These are here to ensure that <command>named</command> 2700 is immune to compromises in the DNSSEC components of the security 2701 of parent zones. 2702 </para> 2703 2704<programlisting> 2705managed-keys { 2706 /* Root Key */ 2707 "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS 2708 JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh 2709 aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy 2710 4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg 2711 hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp 2712 5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke 2713 g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq 2714 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ 2715 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ 2716 dgxbcDTClU0CRBdiieyLMNzXG3"; 2717}; 2718 2719trusted-keys { 2720 /* Key for our organization's forward zone */ 2721 example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6 2722 5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z 2723 GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb 2724 4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL 2725 kBOUKUf/mC7HvfwYH/Be22GnClrinKJp1O 2726 g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S 2727 TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq 2728 FxmAVZP20igTixin/1LcrgX/KMEGd/biuv 2729 F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm 2730 /oyWR8BW/hWdzOvnSCThlHf3xiYleDbt/o 2731 1OTQ09A0="; 2732 2733 /* Key for our reverse zone. */ 2734 2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc 2735 xOdNax071L18QqZnQQQAVVr+i 2736 LhGTnNGp3HoWQLUIzKrJVZ3zg 2737 gy3WwNT6kZo6c0tszYqbtvchm 2738 gQC8CzKojM/W16i6MG/eafGU3 2739 siaOdS0yOI6BgPsw+YZdzlYMa 2740 IJGf4M4dyoKIhzdZyQ2bYQrjy 2741 Q4LB0lC7aOnsMyYKHHYeRvPxj 2742 IQXmdqgOJGq+vsevG06zW+1xg 2743 YJh9rCIfnm1GX/KMgxLPG2vXT 2744 D/RnLX+D3T3UL7HJYHJhAZD5L 2745 59VvjSPsZJHeDCUyWYrvPZesZ 2746 DIRvhDD52SKvbheeTJUm6Ehkz 2747 ytNN2SN96QRk8j/iI8ib"; 2748}; 2749 2750options { 2751 ... 2752 dnssec-enable yes; 2753 dnssec-validation yes; 2754}; 2755</programlisting> 2756 2757 <note> 2758 None of the keys listed in this example are valid. In particular, 2759 the root key is not valid. 2760 </note> 2761 2762 <para> 2763 When DNSSEC validation is enabled and properly configured, 2764 the resolver will reject any answers from signed, secure zones 2765 which fail to validate, and will return SERVFAIL to the client. 2766 </para> 2767 2768 <para> 2769 Responses may fail to validate for any of several reasons, 2770 including missing, expired, or invalid signatures, a key which 2771 does not match the DS RRset in the parent zone, or an insecure 2772 response from a zone which, according to its parent, should have 2773 been secure. 2774 </para> 2775 2776 <note> 2777 <para> 2778 When the validator receives a response from an unsigned zone 2779 that has a signed parent, it must confirm with the parent 2780 that the zone was intentionally left unsigned. It does 2781 this by verifying, via signed and validated NSEC/NSEC3 records, 2782 that the parent zone contains no DS records for the child. 2783 </para> 2784 <para> 2785 If the validator <emphasis>can</emphasis> prove that the zone 2786 is insecure, then the response is accepted. However, if it 2787 cannot, then it must assume an insecure response to be a 2788 forgery; it rejects the response and logs an error. 2789 </para> 2790 <para> 2791 The logged error reads "insecurity proof failed" and 2792 "got insecure response; parent indicates it should be secure". 2793 (Prior to BIND 9.7, the logged error was "not insecure". 2794 This referred to the zone, not the response.) 2795 </para> 2796 </note> 2797 </sect2> 2798 2799 </sect1> 2800 2801 <xi:include href="dnssec.xml"/> 2802 2803 <xi:include href="managed-keys.xml"/> 2804 2805 <xi:include href="pkcs11.xml"/> 2806 2807 <sect1> 2808 <title>IPv6 Support in <acronym>BIND</acronym> 9</title> 2809 2810 <para> 2811 <acronym>BIND</acronym> 9 fully supports all currently 2812 defined forms of IPv6 name to address and address to name 2813 lookups. It will also use IPv6 addresses to make queries when 2814 running on an IPv6 capable system. 2815 </para> 2816 2817 <para> 2818 For forward lookups, <acronym>BIND</acronym> 9 supports 2819 only AAAA records. RFC 3363 deprecated the use of A6 records, 2820 and client-side support for A6 records was accordingly removed 2821 from <acronym>BIND</acronym> 9. 2822 However, authoritative <acronym>BIND</acronym> 9 name servers still 2823 load zone files containing A6 records correctly, answer queries 2824 for A6 records, and accept zone transfer for a zone containing A6 2825 records. 2826 </para> 2827 2828 <para> 2829 For IPv6 reverse lookups, <acronym>BIND</acronym> 9 supports 2830 the traditional "nibble" format used in the 2831 <emphasis>ip6.arpa</emphasis> domain, as well as the older, deprecated 2832 <emphasis>ip6.int</emphasis> domain. 2833 Older versions of <acronym>BIND</acronym> 9 2834 supported the "binary label" (also known as "bitstring") format, 2835 but support of binary labels has been completely removed per 2836 RFC 3363. 2837 Many applications in <acronym>BIND</acronym> 9 do not understand 2838 the binary label format at all any more, and will return an 2839 error if given. 2840 In particular, an authoritative <acronym>BIND</acronym> 9 2841 name server will not load a zone file containing binary labels. 2842 </para> 2843 2844 <para> 2845 For an overview of the format and structure of IPv6 addresses, 2846 see <xref linkend="ipv6addresses"/>. 2847 </para> 2848 2849 <sect2> 2850 <title>Address Lookups Using AAAA Records</title> 2851 2852 <para> 2853 The IPv6 AAAA record is a parallel to the IPv4 A record, 2854 and, unlike the deprecated A6 record, specifies the entire 2855 IPv6 address in a single record. For example, 2856 </para> 2857 2858<programlisting> 2859$ORIGIN example.com. 2860host 3600 IN AAAA 2001:db8::1 2861</programlisting> 2862 2863 <para> 2864 Use of IPv4-in-IPv6 mapped addresses is not recommended. 2865 If a host has an IPv4 address, use an A record, not 2866 a AAAA, with <literal>::ffff:192.168.42.1</literal> as 2867 the address. 2868 </para> 2869 </sect2> 2870 <sect2> 2871 <title>Address to Name Lookups Using Nibble Format</title> 2872 2873 <para> 2874 When looking up an address in nibble format, the address 2875 components are simply reversed, just as in IPv4, and 2876 <literal>ip6.arpa.</literal> is appended to the 2877 resulting name. 2878 For example, the following would provide reverse name lookup for 2879 a host with address 2880 <literal>2001:db8::1</literal>. 2881 </para> 2882 2883<programlisting> 2884$ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. 28851.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0 14400 IN PTR ( 2886 host.example.com. ) 2887</programlisting> 2888 2889 </sect2> 2890 </sect1> 2891 </chapter> 2892 2893 <chapter id="Bv9ARM.ch05"> 2894 <title>The <acronym>BIND</acronym> 9 Lightweight Resolver</title> 2895 <sect1> 2896 <title>The Lightweight Resolver Library</title> 2897 <para> 2898 Traditionally applications have been linked with a stub resolver 2899 library that sends recursive DNS queries to a local caching name 2900 server. 2901 </para> 2902 <para> 2903 IPv6 once introduced new complexity into the resolution process, 2904 such as following A6 chains and DNAME records, and simultaneous 2905 lookup of IPv4 and IPv6 addresses. Though most of the complexity was 2906 then removed, these are hard or impossible 2907 to implement in a traditional stub resolver. 2908 </para> 2909 <para> 2910 <acronym>BIND</acronym> 9 therefore can also provide resolution 2911 services to local clients 2912 using a combination of a lightweight resolver library and a resolver 2913 daemon process running on the local host. These communicate using 2914 a simple UDP-based protocol, the "lightweight resolver protocol" 2915 that is distinct from and simpler than the full DNS protocol. 2916 </para> 2917 </sect1> 2918 <sect1 id="lwresd"> 2919 <title>Running a Resolver Daemon</title> 2920 2921 <para> 2922 To use the lightweight resolver interface, the system must 2923 run the resolver daemon <command>lwresd</command> or a 2924 local 2925 name server configured with a <command>lwres</command> 2926 statement. 2927 </para> 2928 2929 <para> 2930 By default, applications using the lightweight resolver library will 2931 make 2932 UDP requests to the IPv4 loopback address (127.0.0.1) on port 921. 2933 The 2934 address can be overridden by <command>lwserver</command> 2935 lines in 2936 <filename>/etc/resolv.conf</filename>. 2937 </para> 2938 2939 <para> 2940 The daemon currently only looks in the DNS, but in the future 2941 it may use other sources such as <filename>/etc/hosts</filename>, 2942 NIS, etc. 2943 </para> 2944 2945 <para> 2946 The <command>lwresd</command> daemon is essentially a 2947 caching-only name server that responds to requests using the 2948 lightweight 2949 resolver protocol rather than the DNS protocol. Because it needs 2950 to run on each host, it is designed to require no or minimal 2951 configuration. 2952 Unless configured otherwise, it uses the name servers listed on 2953 <command>nameserver</command> lines in <filename>/etc/resolv.conf</filename> 2954 as forwarders, but is also capable of doing the resolution 2955 autonomously if 2956 none are specified. 2957 </para> 2958 <para> 2959 The <command>lwresd</command> daemon may also be 2960 configured with a 2961 <filename>named.conf</filename> style configuration file, 2962 in 2963 <filename>/etc/lwresd.conf</filename> by default. A name 2964 server may also 2965 be configured to act as a lightweight resolver daemon using the 2966 <command>lwres</command> statement in <filename>named.conf</filename>. 2967 </para> 2968 2969 </sect1> 2970 </chapter> 2971 2972 <chapter id="Bv9ARM.ch06"> 2973 <title><acronym>BIND</acronym> 9 Configuration Reference</title> 2974 2975 <para> 2976 <acronym>BIND</acronym> 9 configuration is broadly similar 2977 to <acronym>BIND</acronym> 8; however, there are a few new 2978 areas 2979 of configuration, such as views. <acronym>BIND</acronym> 2980 8 configuration files should work with few alterations in <acronym>BIND</acronym> 2981 9, although more complex configurations should be reviewed to check 2982 if they can be more efficiently implemented using the new features 2983 found in <acronym>BIND</acronym> 9. 2984 </para> 2985 2986 <para> 2987 <acronym>BIND</acronym> 4 configuration files can be 2988 converted to the new format 2989 using the shell script 2990 <filename>contrib/named-bootconf/named-bootconf.sh</filename>. 2991 </para> 2992 <sect1 id="configuration_file_elements"> 2993 <title>Configuration File Elements</title> 2994 <para> 2995 Following is a list of elements used throughout the <acronym>BIND</acronym> configuration 2996 file documentation: 2997 </para> 2998 <informaltable colsep="0" rowsep="0"> 2999 <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table"> 3000 <colspec colname="1" colnum="1" colsep="0" colwidth="1.855in"/> 3001 <colspec colname="2" colnum="2" colsep="0" colwidth="3.770in"/> 3002 <tbody> 3003 <row rowsep="0"> 3004 <entry colname="1"> 3005 <para> 3006 <varname>acl_name</varname> 3007 </para> 3008 </entry> 3009 <entry colname="2"> 3010 <para> 3011 The name of an <varname>address_match_list</varname> as 3012 defined by the <command>acl</command> statement. 3013 </para> 3014 </entry> 3015 </row> 3016 <row rowsep="0"> 3017 <entry colname="1"> 3018 <para> 3019 <varname>address_match_list</varname> 3020 </para> 3021 </entry> 3022 <entry colname="2"> 3023 <para> 3024 A list of one or more 3025 <varname>ip_addr</varname>, 3026 <varname>ip_prefix</varname>, <varname>key_id</varname>, 3027 or <varname>acl_name</varname> elements, see 3028 <xref linkend="address_match_lists"/>. 3029 </para> 3030 </entry> 3031 </row> 3032 <row rowsep="0"> 3033 <entry colname="1"> 3034 <para> 3035 <varname>masters_list</varname> 3036 </para> 3037 </entry> 3038 <entry colname="2"> 3039 <para> 3040 A named list of one or more <varname>ip_addr</varname> 3041 with optional <varname>key_id</varname> and/or 3042 <varname>ip_port</varname>. 3043 A <varname>masters_list</varname> may include other 3044 <varname>masters_lists</varname>. 3045 </para> 3046 </entry> 3047 </row> 3048 <row rowsep="0"> 3049 <entry colname="1"> 3050 <para> 3051 <varname>domain_name</varname> 3052 </para> 3053 </entry> 3054 <entry colname="2"> 3055 <para> 3056 A quoted string which will be used as 3057 a DNS name, for example "<literal>my.test.domain</literal>". 3058 </para> 3059 </entry> 3060 </row> 3061 <row rowsep="0"> 3062 <entry colname="1"> 3063 <para> 3064 <varname>namelist</varname> 3065 </para> 3066 </entry> 3067 <entry colname="2"> 3068 <para> 3069 A list of one or more <varname>domain_name</varname> 3070 elements. 3071 </para> 3072 </entry> 3073 </row> 3074 <row rowsep="0"> 3075 <entry colname="1"> 3076 <para> 3077 <varname>dotted_decimal</varname> 3078 </para> 3079 </entry> 3080 <entry colname="2"> 3081 <para> 3082 One to four integers valued 0 through 3083 255 separated by dots (`.'), such as <command>123</command>, 3084 <command>45.67</command> or <command>89.123.45.67</command>. 3085 </para> 3086 </entry> 3087 </row> 3088 <row rowsep="0"> 3089 <entry colname="1"> 3090 <para> 3091 <varname>ip4_addr</varname> 3092 </para> 3093 </entry> 3094 <entry colname="2"> 3095 <para> 3096 An IPv4 address with exactly four elements 3097 in <varname>dotted_decimal</varname> notation. 3098 </para> 3099 </entry> 3100 </row> 3101 <row rowsep="0"> 3102 <entry colname="1"> 3103 <para> 3104 <varname>ip6_addr</varname> 3105 </para> 3106 </entry> 3107 <entry colname="2"> 3108 <para> 3109 An IPv6 address, such as <command>2001:db8::1234</command>. 3110 IPv6 scoped addresses that have ambiguity on their 3111 scope zones must be disambiguated by an appropriate 3112 zone ID with the percent character (`%') as 3113 delimiter. It is strongly recommended to use 3114 string zone names rather than numeric identifiers, 3115 in order to be robust against system configuration 3116 changes. However, since there is no standard 3117 mapping for such names and identifier values, 3118 currently only interface names as link identifiers 3119 are supported, assuming one-to-one mapping between 3120 interfaces and links. For example, a link-local 3121 address <command>fe80::1</command> on the link 3122 attached to the interface <command>ne0</command> 3123 can be specified as <command>fe80::1%ne0</command>. 3124 Note that on most systems link-local addresses 3125 always have the ambiguity, and need to be 3126 disambiguated. 3127 </para> 3128 </entry> 3129 </row> 3130 <row rowsep="0"> 3131 <entry colname="1"> 3132 <para> 3133 <varname>ip_addr</varname> 3134 </para> 3135 </entry> 3136 <entry colname="2"> 3137 <para> 3138 An <varname>ip4_addr</varname> or <varname>ip6_addr</varname>. 3139 </para> 3140 </entry> 3141 </row> 3142 <row rowsep="0"> 3143 <entry colname="1"> 3144 <para> 3145 <varname>ip_port</varname> 3146 </para> 3147 </entry> 3148 <entry colname="2"> 3149 <para> 3150 An IP port <varname>number</varname>. 3151 The <varname>number</varname> is limited to 0 3152 through 65535, with values 3153 below 1024 typically restricted to use by processes running 3154 as root. 3155 In some cases, an asterisk (`*') character can be used as a 3156 placeholder to 3157 select a random high-numbered port. 3158 </para> 3159 </entry> 3160 </row> 3161 <row rowsep="0"> 3162 <entry colname="1"> 3163 <para> 3164 <varname>ip_prefix</varname> 3165 </para> 3166 </entry> 3167 <entry colname="2"> 3168 <para> 3169 An IP network specified as an <varname>ip_addr</varname>, 3170 followed by a slash (`/') and then the number of bits in the 3171 netmask. 3172 Trailing zeros in a <varname>ip_addr</varname> 3173 may omitted. 3174 For example, <command>127/8</command> is the 3175 network <command>127.0.0.0</command> with 3176 netmask <command>255.0.0.0</command> and <command>1.2.3.0/28</command> is 3177 network <command>1.2.3.0</command> with netmask <command>255.255.255.240</command>. 3178 </para> 3179 <para> 3180 When specifying a prefix involving a IPv6 scoped address 3181 the scope may be omitted. In that case the prefix will 3182 match packets from any scope. 3183 </para> 3184 </entry> 3185 </row> 3186 <row rowsep="0"> 3187 <entry colname="1"> 3188 <para> 3189 <varname>key_id</varname> 3190 </para> 3191 </entry> 3192 <entry colname="2"> 3193 <para> 3194 A <varname>domain_name</varname> representing 3195 the name of a shared key, to be used for transaction 3196 security. 3197 </para> 3198 </entry> 3199 </row> 3200 <row rowsep="0"> 3201 <entry colname="1"> 3202 <para> 3203 <varname>key_list</varname> 3204 </para> 3205 </entry> 3206 <entry colname="2"> 3207 <para> 3208 A list of one or more 3209 <varname>key_id</varname>s, 3210 separated by semicolons and ending with a semicolon. 3211 </para> 3212 </entry> 3213 </row> 3214 <row rowsep="0"> 3215 <entry colname="1"> 3216 <para> 3217 <varname>number</varname> 3218 </para> 3219 </entry> 3220 <entry colname="2"> 3221 <para> 3222 A non-negative 32-bit integer 3223 (i.e., a number between 0 and 4294967295, inclusive). 3224 Its acceptable value might further 3225 be limited by the context in which it is used. 3226 </para> 3227 </entry> 3228 </row> 3229 <row rowsep="0"> 3230 <entry colname="1"> 3231 <para> 3232 <varname>path_name</varname> 3233 </para> 3234 </entry> 3235 <entry colname="2"> 3236 <para> 3237 A quoted string which will be used as 3238 a pathname, such as <filename>zones/master/my.test.domain</filename>. 3239 </para> 3240 </entry> 3241 </row> 3242 <row rowsep="0"> 3243 <entry colname="1"> 3244 <para> 3245 <varname>port_list</varname> 3246 </para> 3247 </entry> 3248 <entry colname="2"> 3249 <para> 3250 A list of an <varname>ip_port</varname> or a port 3251 range. 3252 A port range is specified in the form of 3253 <userinput>range</userinput> followed by 3254 two <varname>ip_port</varname>s, 3255 <varname>port_low</varname> and 3256 <varname>port_high</varname>, which represents 3257 port numbers from <varname>port_low</varname> through 3258 <varname>port_high</varname>, inclusive. 3259 <varname>port_low</varname> must not be larger than 3260 <varname>port_high</varname>. 3261 For example, 3262 <userinput>range 1024 65535</userinput> represents 3263 ports from 1024 through 65535. 3264 In either case an asterisk (`*') character is not 3265 allowed as a valid <varname>ip_port</varname>. 3266 </para> 3267 </entry> 3268 </row> 3269 <row rowsep="0"> 3270 <entry colname="1"> 3271 <para> 3272 <varname>size_spec</varname> 3273 </para> 3274 </entry> 3275 <entry colname="2"> 3276 <para> 3277 A number, the word <userinput>unlimited</userinput>, 3278 or the word <userinput>default</userinput>. 3279 </para> 3280 <para> 3281 An <varname>unlimited</varname> <varname>size_spec</varname> requests unlimited 3282 use, or the maximum available amount. A <varname>default size_spec</varname> uses 3283 the limit that was in force when the server was started. 3284 </para> 3285 <para> 3286 A <varname>number</varname> can optionally be 3287 followed by a scaling factor: 3288 <userinput>K</userinput> or <userinput>k</userinput> 3289 for kilobytes, 3290 <userinput>M</userinput> or <userinput>m</userinput> 3291 for megabytes, and 3292 <userinput>G</userinput> or <userinput>g</userinput> for gigabytes, 3293 which scale by 1024, 1024*1024, and 1024*1024*1024 3294 respectively. 3295 </para> 3296 <para> 3297 The value must be representable as a 64-bit unsigned integer 3298 (0 to 18446744073709551615, inclusive). 3299 Using <varname>unlimited</varname> is the best 3300 way 3301 to safely set a really large number. 3302 </para> 3303 </entry> 3304 </row> 3305 <row rowsep="0"> 3306 <entry colname="1"> 3307 <para> 3308 <varname>yes_or_no</varname> 3309 </para> 3310 </entry> 3311 <entry colname="2"> 3312 <para> 3313 Either <userinput>yes</userinput> or <userinput>no</userinput>. 3314 The words <userinput>true</userinput> and <userinput>false</userinput> are 3315 also accepted, as are the numbers <userinput>1</userinput> 3316 and <userinput>0</userinput>. 3317 </para> 3318 </entry> 3319 </row> 3320 <row rowsep="0"> 3321 <entry colname="1"> 3322 <para> 3323 <varname>dialup_option</varname> 3324 </para> 3325 </entry> 3326 <entry colname="2"> 3327 <para> 3328 One of <userinput>yes</userinput>, 3329 <userinput>no</userinput>, <userinput>notify</userinput>, 3330 <userinput>notify-passive</userinput>, <userinput>refresh</userinput> or 3331 <userinput>passive</userinput>. 3332 When used in a zone, <userinput>notify-passive</userinput>, 3333 <userinput>refresh</userinput>, and <userinput>passive</userinput> 3334 are restricted to slave and stub zones. 3335 </para> 3336 </entry> 3337 </row> 3338 </tbody> 3339 </tgroup> 3340 </informaltable> 3341 <sect2 id="address_match_lists"> 3342 <title>Address Match Lists</title> 3343 <sect3> 3344 <title>Syntax</title> 3345 3346<programlisting><varname>address_match_list</varname> = address_match_list_element ; 3347 <optional> address_match_list_element; ... </optional> 3348<varname>address_match_list_element</varname> = <optional> ! </optional> (ip_address <optional>/length</optional> | 3349 key key_id | acl_name | { address_match_list } ) 3350</programlisting> 3351 3352 </sect3> 3353 <sect3> 3354 <title>Definition and Usage</title> 3355 <para> 3356 Address match lists are primarily used to determine access 3357 control for various server operations. They are also used in 3358 the <command>listen-on</command> and <command>sortlist</command> 3359 statements. The elements which constitute an address match 3360 list can be any of the following: 3361 </para> 3362 <itemizedlist> 3363 <listitem> 3364 <simpara>an IP address (IPv4 or IPv6)</simpara> 3365 </listitem> 3366 <listitem> 3367 <simpara>an IP prefix (in `/' notation)</simpara> 3368 </listitem> 3369 <listitem> 3370 <simpara> 3371 a key ID, as defined by the <command>key</command> 3372 statement 3373 </simpara> 3374 </listitem> 3375 <listitem> 3376 <simpara>the name of an address match list defined with 3377 the <command>acl</command> statement 3378 </simpara> 3379 </listitem> 3380 <listitem> 3381 <simpara>a nested address match list enclosed in braces</simpara> 3382 </listitem> 3383 </itemizedlist> 3384 3385 <para> 3386 Elements can be negated with a leading exclamation mark (`!'), 3387 and the match list names "any", "none", "localhost", and 3388 "localnets" are predefined. More information on those names 3389 can be found in the description of the acl statement. 3390 </para> 3391 3392 <para> 3393 The addition of the key clause made the name of this syntactic 3394 element something of a misnomer, since security keys can be used 3395 to validate access without regard to a host or network address. 3396 Nonetheless, the term "address match list" is still used 3397 throughout the documentation. 3398 </para> 3399 3400 <para> 3401 When a given IP address or prefix is compared to an address 3402 match list, the comparison takes place in approximately O(1) 3403 time. However, key comparisons require that the list of keys 3404 be traversed until a matching key is found, and therefore may 3405 be somewhat slower. 3406 </para> 3407 3408 <para> 3409 The interpretation of a match depends on whether the list is being 3410 used for access control, defining <command>listen-on</command> ports, or in a 3411 <command>sortlist</command>, and whether the element was negated. 3412 </para> 3413 3414 <para> 3415 When used as an access control list, a non-negated match 3416 allows access and a negated match denies access. If 3417 there is no match, access is denied. The clauses 3418 <command>allow-notify</command>, 3419 <command>allow-recursion</command>, 3420 <command>allow-recursion-on</command>, 3421 <command>allow-query</command>, 3422 <command>allow-query-on</command>, 3423 <command>allow-query-cache</command>, 3424 <command>allow-query-cache-on</command>, 3425 <command>allow-transfer</command>, 3426 <command>allow-update</command>, 3427 <command>allow-update-forwarding</command>, and 3428 <command>blackhole</command> all use address match 3429 lists. Similarly, the <command>listen-on</command> option will cause the 3430 server to refuse queries on any of the machine's 3431 addresses which do not match the list. 3432 </para> 3433 3434 <para> 3435 Order of insertion is significant. If more than one element 3436 in an ACL is found to match a given IP address or prefix, 3437 preference will be given to the one that came 3438 <emphasis>first</emphasis> in the ACL definition. 3439 Because of this first-match behavior, an element that 3440 defines a subset of another element in the list should 3441 come before the broader element, regardless of whether 3442 either is negated. For example, in 3443 <command>1.2.3/24; ! 1.2.3.13;</command> 3444 the 1.2.3.13 element is completely useless because the 3445 algorithm will match any lookup for 1.2.3.13 to the 1.2.3/24 3446 element. Using <command>! 1.2.3.13; 1.2.3/24</command> fixes 3447 that problem by having 1.2.3.13 blocked by the negation, but 3448 all other 1.2.3.* hosts fall through. 3449 </para> 3450 </sect3> 3451 </sect2> 3452 3453 <sect2> 3454 <title>Comment Syntax</title> 3455 3456 <para> 3457 The <acronym>BIND</acronym> 9 comment syntax allows for 3458 comments to appear 3459 anywhere that whitespace may appear in a <acronym>BIND</acronym> configuration 3460 file. To appeal to programmers of all kinds, they can be written 3461 in the C, C++, or shell/perl style. 3462 </para> 3463 3464 <sect3> 3465 <title>Syntax</title> 3466 3467 <para> 3468 <programlisting>/* This is a <acronym>BIND</acronym> comment as in C */</programlisting> 3469 <programlisting>// This is a <acronym>BIND</acronym> comment as in C++</programlisting> 3470 <programlisting># This is a <acronym>BIND</acronym> comment as in common UNIX shells 3471# and perl</programlisting> 3472 </para> 3473 </sect3> 3474 <sect3> 3475 <title>Definition and Usage</title> 3476 <para> 3477 Comments may appear anywhere that whitespace may appear in 3478 a <acronym>BIND</acronym> configuration file. 3479 </para> 3480 <para> 3481 C-style comments start with the two characters /* (slash, 3482 star) and end with */ (star, slash). Because they are completely 3483 delimited with these characters, they can be used to comment only 3484 a portion of a line or to span multiple lines. 3485 </para> 3486 <para> 3487 C-style comments cannot be nested. For example, the following 3488 is not valid because the entire comment ends with the first */: 3489 </para> 3490 <para> 3491 3492<programlisting>/* This is the start of a comment. 3493 This is still part of the comment. 3494/* This is an incorrect attempt at nesting a comment. */ 3495 This is no longer in any comment. */ 3496</programlisting> 3497 3498 </para> 3499 3500 <para> 3501 C++-style comments start with the two characters // (slash, 3502 slash) and continue to the end of the physical line. They cannot 3503 be continued across multiple physical lines; to have one logical 3504 comment span multiple lines, each line must use the // pair. 3505 For example: 3506 </para> 3507 <para> 3508 3509<programlisting>// This is the start of a comment. The next line 3510// is a new comment, even though it is logically 3511// part of the previous comment. 3512</programlisting> 3513 3514 </para> 3515 <para> 3516 Shell-style (or perl-style, if you prefer) comments start 3517 with the character <literal>#</literal> (number sign) 3518 and continue to the end of the 3519 physical line, as in C++ comments. 3520 For example: 3521 </para> 3522 3523 <para> 3524 3525<programlisting># This is the start of a comment. The next line 3526# is a new comment, even though it is logically 3527# part of the previous comment. 3528</programlisting> 3529 3530 </para> 3531 3532 <warning> 3533 <para> 3534 You cannot use the semicolon (`;') character 3535 to start a comment such as you would in a zone file. The 3536 semicolon indicates the end of a configuration 3537 statement. 3538 </para> 3539 </warning> 3540 </sect3> 3541 </sect2> 3542 </sect1> 3543 3544 <sect1 id="Configuration_File_Grammar"> 3545 <title>Configuration File Grammar</title> 3546 3547 <para> 3548 A <acronym>BIND</acronym> 9 configuration consists of 3549 statements and comments. 3550 Statements end with a semicolon. Statements and comments are the 3551 only elements that can appear without enclosing braces. Many 3552 statements contain a block of sub-statements, which are also 3553 terminated with a semicolon. 3554 </para> 3555 3556 <para> 3557 The following statements are supported: 3558 </para> 3559 3560 <informaltable colsep="0" rowsep="0"> 3561 <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table"> 3562 <colspec colname="1" colnum="1" colsep="0" colwidth="1.336in"/> 3563 <colspec colname="2" colnum="2" colsep="0" colwidth="3.778in"/> 3564 <tbody> 3565 <row rowsep="0"> 3566 <entry colname="1"> 3567 <para><command>acl</command></para> 3568 </entry> 3569 <entry colname="2"> 3570 <para> 3571 defines a named IP address 3572 matching list, for access control and other uses. 3573 </para> 3574 </entry> 3575 </row> 3576 <row rowsep="0"> 3577 <entry colname="1"> 3578 <para><command>controls</command></para> 3579 </entry> 3580 <entry colname="2"> 3581 <para> 3582 declares control channels to be used 3583 by the <command>rndc</command> utility. 3584 </para> 3585 </entry> 3586 </row> 3587 <row rowsep="0"> 3588 <entry colname="1"> 3589 <para><command>include</command></para> 3590 </entry> 3591 <entry colname="2"> 3592 <para> 3593 includes a file. 3594 </para> 3595 </entry> 3596 </row> 3597 <row rowsep="0"> 3598 <entry colname="1"> 3599 <para><command>key</command></para> 3600 </entry> 3601 <entry colname="2"> 3602 <para> 3603 specifies key information for use in 3604 authentication and authorization using TSIG. 3605 </para> 3606 </entry> 3607 </row> 3608 <row rowsep="0"> 3609 <entry colname="1"> 3610 <para><command>logging</command></para> 3611 </entry> 3612 <entry colname="2"> 3613 <para> 3614 specifies what the server logs, and where 3615 the log messages are sent. 3616 </para> 3617 </entry> 3618 </row> 3619 <row rowsep="0"> 3620 <entry colname="1"> 3621 <para><command>lwres</command></para> 3622 </entry> 3623 <entry colname="2"> 3624 <para> 3625 configures <command>named</command> to 3626 also act as a light-weight resolver daemon (<command>lwresd</command>). 3627 </para> 3628 </entry> 3629 </row> 3630 <row rowsep="0"> 3631 <entry colname="1"> 3632 <para><command>masters</command></para> 3633 </entry> 3634 <entry colname="2"> 3635 <para> 3636 defines a named masters list for 3637 inclusion in stub and slave zone masters clauses. 3638 </para> 3639 </entry> 3640 </row> 3641 <row rowsep="0"> 3642 <entry colname="1"> 3643 <para><command>options</command></para> 3644 </entry> 3645 <entry colname="2"> 3646 <para> 3647 controls global server configuration 3648 options and sets defaults for other statements. 3649 </para> 3650 </entry> 3651 </row> 3652 <row rowsep="0"> 3653 <entry colname="1"> 3654 <para><command>server</command></para> 3655 </entry> 3656 <entry colname="2"> 3657 <para> 3658 sets certain configuration options on 3659 a per-server basis. 3660 </para> 3661 </entry> 3662 </row> 3663 <row rowsep="0"> 3664 <entry colname="1"> 3665 <para><command>statistics-channels</command></para> 3666 </entry> 3667 <entry colname="2"> 3668 <para> 3669 declares communication channels to get access to 3670 <command>named</command> statistics. 3671 </para> 3672 </entry> 3673 </row> 3674 <row rowsep="0"> 3675 <entry colname="1"> 3676 <para><command>trusted-keys</command></para> 3677 </entry> 3678 <entry colname="2"> 3679 <para> 3680 defines trusted DNSSEC keys. 3681 </para> 3682 </entry> 3683 </row> 3684 <row rowsep="0"> 3685 <entry colname="1"> 3686 <para><command>managed-keys</command></para> 3687 </entry> 3688 <entry colname="2"> 3689 <para> 3690 lists DNSSEC keys to be kept up to date 3691 using RFC 5011 trust anchor maintenance. 3692 </para> 3693 </entry> 3694 </row> 3695 <row rowsep="0"> 3696 <entry colname="1"> 3697 <para><command>view</command></para> 3698 </entry> 3699 <entry colname="2"> 3700 <para> 3701 defines a view. 3702 </para> 3703 </entry> 3704 </row> 3705 <row rowsep="0"> 3706 <entry colname="1"> 3707 <para><command>zone</command></para> 3708 </entry> 3709 <entry colname="2"> 3710 <para> 3711 defines a zone. 3712 </para> 3713 </entry> 3714 </row> 3715 </tbody> 3716 </tgroup> 3717 </informaltable> 3718 3719 <para> 3720 The <command>logging</command> and 3721 <command>options</command> statements may only occur once 3722 per 3723 configuration. 3724 </para> 3725 3726 <sect2> 3727 <title><command>acl</command> Statement Grammar</title> 3728 3729<programlisting><command>acl</command> acl-name { 3730 address_match_list 3731}; 3732</programlisting> 3733 3734 </sect2> 3735 <sect2 id="acl"> 3736 <title><command>acl</command> Statement Definition and 3737 Usage</title> 3738 3739 <para> 3740 The <command>acl</command> statement assigns a symbolic 3741 name to an address match list. It gets its name from a primary 3742 use of address match lists: Access Control Lists (ACLs). 3743 </para> 3744 3745 <para> 3746 Note that an address match list's name must be defined 3747 with <command>acl</command> before it can be used 3748 elsewhere; no forward references are allowed. 3749 </para> 3750 3751 <para> 3752 The following ACLs are built-in: 3753 </para> 3754 3755 <informaltable colsep="0" rowsep="0"> 3756 <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="3Level-table"> 3757 <colspec colname="1" colnum="1" colsep="0" colwidth="1.130in"/> 3758 <colspec colname="2" colnum="2" colsep="0" colwidth="4.000in"/> 3759 <tbody> 3760 <row rowsep="0"> 3761 <entry colname="1"> 3762 <para><command>any</command></para> 3763 </entry> 3764 <entry colname="2"> 3765 <para> 3766 Matches all hosts. 3767 </para> 3768 </entry> 3769 </row> 3770 <row rowsep="0"> 3771 <entry colname="1"> 3772 <para><command>none</command></para> 3773 </entry> 3774 <entry colname="2"> 3775 <para> 3776 Matches no hosts. 3777 </para> 3778 </entry> 3779 </row> 3780 <row rowsep="0"> 3781 <entry colname="1"> 3782 <para><command>localhost</command></para> 3783 </entry> 3784 <entry colname="2"> 3785 <para> 3786 Matches the IPv4 and IPv6 addresses of all network 3787 interfaces on the system. 3788 </para> 3789 </entry> 3790 </row> 3791 <row rowsep="0"> 3792 <entry colname="1"> 3793 <para><command>localnets</command></para> 3794 </entry> 3795 <entry colname="2"> 3796 <para> 3797 Matches any host on an IPv4 or IPv6 network 3798 for which the system has an interface. 3799 Some systems do not provide a way to determine the prefix 3800 lengths of 3801 local IPv6 addresses. 3802 In such a case, <command>localnets</command> 3803 only matches the local 3804 IPv6 addresses, just like <command>localhost</command>. 3805 </para> 3806 </entry> 3807 </row> 3808 </tbody> 3809 </tgroup> 3810 </informaltable> 3811 3812 </sect2> 3813 <sect2> 3814 <title><command>controls</command> Statement Grammar</title> 3815 3816<programlisting><command>controls</command> { 3817 [ inet ( ip_addr | * ) [ port ip_port ] 3818 allow { <replaceable> address_match_list </replaceable> } 3819 keys { <replaceable>key_list</replaceable> }; ] 3820 [ inet ...; ] 3821 [ unix <replaceable>path</replaceable> perm <replaceable>number</replaceable> owner <replaceable>number</replaceable> group <replaceable>number</replaceable> 3822 keys { <replaceable>key_list</replaceable> }; ] 3823 [ unix ...; ] 3824}; 3825</programlisting> 3826 3827 </sect2> 3828 3829 <sect2 id="controls_statement_definition_and_usage"> 3830 <title><command>controls</command> Statement Definition and 3831 Usage</title> 3832 3833 <para> 3834 The <command>controls</command> statement declares control 3835 channels to be used by system administrators to control the 3836 operation of the name server. These control channels are 3837 used by the <command>rndc</command> utility to send 3838 commands to and retrieve non-DNS results from a name server. 3839 </para> 3840 3841 <para> 3842 An <command>inet</command> control channel is a TCP socket 3843 listening at the specified <command>ip_port</command> on the 3844 specified <command>ip_addr</command>, which can be an IPv4 or IPv6 3845 address. An <command>ip_addr</command> of <literal>*</literal> (asterisk) is 3846 interpreted as the IPv4 wildcard address; connections will be 3847 accepted on any of the system's IPv4 addresses. 3848 To listen on the IPv6 wildcard address, 3849 use an <command>ip_addr</command> of <literal>::</literal>. 3850 If you will only use <command>rndc</command> on the local host, 3851 using the loopback address (<literal>127.0.0.1</literal> 3852 or <literal>::1</literal>) is recommended for maximum security. 3853 </para> 3854 3855 <para> 3856 If no port is specified, port 953 is used. The asterisk 3857 "<literal>*</literal>" cannot be used for <command>ip_port</command>. 3858 </para> 3859 3860 <para> 3861 The ability to issue commands over the control channel is 3862 restricted by the <command>allow</command> and 3863 <command>keys</command> clauses. 3864 Connections to the control channel are permitted based on the 3865 <command>address_match_list</command>. This is for simple 3866 IP address based filtering only; any <command>key_id</command> 3867 elements of the <command>address_match_list</command> 3868 are ignored. 3869 </para> 3870 3871 <para> 3872 A <command>unix</command> control channel is a UNIX domain 3873 socket listening at the specified path in the file system. 3874 Access to the socket is specified by the <command>perm</command>, 3875 <command>owner</command> and <command>group</command> clauses. 3876 Note on some platforms (SunOS and Solaris) the permissions 3877 (<command>perm</command>) are applied to the parent directory 3878 as the permissions on the socket itself are ignored. 3879 </para> 3880 3881 <para> 3882 The primary authorization mechanism of the command 3883 channel is the <command>key_list</command>, which 3884 contains a list of <command>key_id</command>s. 3885 Each <command>key_id</command> in the <command>key_list</command> 3886 is authorized to execute commands over the control channel. 3887 See <xref linkend="rndc"/> in <xref linkend="admin_tools"/>) 3888 for information about configuring keys in <command>rndc</command>. 3889 </para> 3890 3891 <para> 3892 If no <command>controls</command> statement is present, 3893 <command>named</command> will set up a default 3894 control channel listening on the loopback address 127.0.0.1 3895 and its IPv6 counterpart ::1. 3896 In this case, and also when the <command>controls</command> statement 3897 is present but does not have a <command>keys</command> clause, 3898 <command>named</command> will attempt to load the command channel key 3899 from the file <filename>rndc.key</filename> in 3900 <filename>/etc</filename> (or whatever <varname>sysconfdir</varname> 3901 was specified as when <acronym>BIND</acronym> was built). 3902 To create a <filename>rndc.key</filename> file, run 3903 <userinput>rndc-confgen -a</userinput>. 3904 </para> 3905 3906 <para> 3907 The <filename>rndc.key</filename> feature was created to 3908 ease the transition of systems from <acronym>BIND</acronym> 8, 3909 which did not have digital signatures on its command channel 3910 messages and thus did not have a <command>keys</command> clause. 3911 3912 It makes it possible to use an existing <acronym>BIND</acronym> 8 3913 configuration file in <acronym>BIND</acronym> 9 unchanged, 3914 and still have <command>rndc</command> work the same way 3915 <command>ndc</command> worked in BIND 8, simply by executing the 3916 command <userinput>rndc-confgen -a</userinput> after BIND 9 is 3917 installed. 3918 </para> 3919 3920 <para> 3921 Since the <filename>rndc.key</filename> feature 3922 is only intended to allow the backward-compatible usage of 3923 <acronym>BIND</acronym> 8 configuration files, this 3924 feature does not 3925 have a high degree of configurability. You cannot easily change 3926 the key name or the size of the secret, so you should make a 3927 <filename>rndc.conf</filename> with your own key if you 3928 wish to change 3929 those things. The <filename>rndc.key</filename> file 3930 also has its 3931 permissions set such that only the owner of the file (the user that 3932 <command>named</command> is running as) can access it. 3933 If you 3934 desire greater flexibility in allowing other users to access 3935 <command>rndc</command> commands, then you need to create 3936 a 3937 <filename>rndc.conf</filename> file and make it group 3938 readable by a group 3939 that contains the users who should have access. 3940 </para> 3941 3942 <para> 3943 To disable the command channel, use an empty 3944 <command>controls</command> statement: 3945 <command>controls { };</command>. 3946 </para> 3947 3948 </sect2> 3949 <sect2> 3950 <title><command>include</command> Statement Grammar</title> 3951 <programlisting><command>include</command> <replaceable>filename</replaceable>;</programlisting> 3952 </sect2> 3953 <sect2> 3954 <title><command>include</command> Statement Definition and 3955 Usage</title> 3956 3957 <para> 3958 The <command>include</command> statement inserts the 3959 specified file at the point where the <command>include</command> 3960 statement is encountered. The <command>include</command> 3961 statement facilitates the administration of configuration 3962 files 3963 by permitting the reading or writing of some things but not 3964 others. For example, the statement could include private keys 3965 that are readable only by the name server. 3966 </para> 3967 3968 </sect2> 3969 <sect2> 3970 <title><command>key</command> Statement Grammar</title> 3971 3972<programlisting><command>key</command> <replaceable>key_id</replaceable> { 3973 algorithm <replaceable>string</replaceable>; 3974 secret <replaceable>string</replaceable>; 3975}; 3976</programlisting> 3977 3978 </sect2> 3979 3980 <sect2> 3981 <title><command>key</command> Statement Definition and Usage</title> 3982 3983 <para> 3984 The <command>key</command> statement defines a shared 3985 secret key for use with TSIG (see <xref linkend="tsig"/>) 3986 or the command channel 3987 (see <xref linkend="controls_statement_definition_and_usage"/>). 3988 </para> 3989 3990 <para> 3991 The <command>key</command> statement can occur at the 3992 top level 3993 of the configuration file or inside a <command>view</command> 3994 statement. Keys defined in top-level <command>key</command> 3995 statements can be used in all views. Keys intended for use in 3996 a <command>controls</command> statement 3997 (see <xref linkend="controls_statement_definition_and_usage"/>) 3998 must be defined at the top level. 3999 </para> 4000 4001 <para> 4002 The <replaceable>key_id</replaceable>, also known as the 4003 key name, is a domain name uniquely identifying the key. It can 4004 be used in a <command>server</command> 4005 statement to cause requests sent to that 4006 server to be signed with this key, or in address match lists to 4007 verify that incoming requests have been signed with a key 4008 matching this name, algorithm, and secret. 4009 </para> 4010 4011 <para> 4012 The <replaceable>algorithm_id</replaceable> is a string 4013 that specifies a security/authentication algorithm. Named 4014 supports <literal>hmac-md5</literal>, 4015 <literal>hmac-sha1</literal>, <literal>hmac-sha224</literal>, 4016 <literal>hmac-sha256</literal>, <literal>hmac-sha384</literal> 4017 and <literal>hmac-sha512</literal> TSIG authentication. 4018 Truncated hashes are supported by appending the minimum 4019 number of required bits preceded by a dash, e.g. 4020 <literal>hmac-sha1-80</literal>. The 4021 <replaceable>secret_string</replaceable> is the secret 4022 to be used by the algorithm, and is treated as a base-64 4023 encoded string. 4024 </para> 4025 4026 </sect2> 4027 <sect2> 4028 <title><command>logging</command> Statement Grammar</title> 4029 4030<programlisting><command>logging</command> { 4031 [ <command>channel</command> <replaceable>channel_name</replaceable> { 4032 ( <command>file</command> <replaceable>path_name</replaceable> 4033 [ <command>versions</command> ( <replaceable>number</replaceable> | <command>unlimited</command> ) ] 4034 [ <command>size</command> <replaceable>size spec</replaceable> ] 4035 | <command>syslog</command> <replaceable>syslog_facility</replaceable> 4036 | <command>stderr</command> 4037 | <command>null</command> ); 4038 [ <command>severity</command> (<option>critical</option> | <option>error</option> | <option>warning</option> | <option>notice</option> | 4039 <option>info</option> | <option>debug</option> [ <replaceable>level</replaceable> ] | <option>dynamic</option> ); ] 4040 [ <command>print-category</command> <option>yes</option> or <option>no</option>; ] 4041 [ <command>print-severity</command> <option>yes</option> or <option>no</option>; ] 4042 [ <command>print-time</command> <option>yes</option> or <option>no</option>; ] 4043 }; ] 4044 [ <command>category</command> <replaceable>category_name</replaceable> { 4045 <replaceable>channel_name</replaceable> ; [ <replaceable>channel_name</replaceable> ; ... ] 4046 }; ] 4047 ... 4048}; 4049</programlisting> 4050 4051 </sect2> 4052 4053 <sect2> 4054 <title><command>logging</command> Statement Definition and 4055 Usage</title> 4056 4057 <para> 4058 The <command>logging</command> statement configures a 4059 wide 4060 variety of logging options for the name server. Its <command>channel</command> phrase 4061 associates output methods, format options and severity levels with 4062 a name that can then be used with the <command>category</command> phrase 4063 to select how various classes of messages are logged. 4064 </para> 4065 <para> 4066 Only one <command>logging</command> statement is used to 4067 define 4068 as many channels and categories as are wanted. If there is no <command>logging</command> statement, 4069 the logging configuration will be: 4070 </para> 4071 4072<programlisting>logging { 4073 category default { default_syslog; default_debug; }; 4074 category unmatched { null; }; 4075}; 4076</programlisting> 4077 4078 <para> 4079 In <acronym>BIND</acronym> 9, the logging configuration 4080 is only established when 4081 the entire configuration file has been parsed. In <acronym>BIND</acronym> 8, it was 4082 established as soon as the <command>logging</command> 4083 statement 4084 was parsed. When the server is starting up, all logging messages 4085 regarding syntax errors in the configuration file go to the default 4086 channels, or to standard error if the "<option>-g</option>" option 4087 was specified. 4088 </para> 4089 4090 <sect3> 4091 <title>The <command>channel</command> Phrase</title> 4092 4093 <para> 4094 All log output goes to one or more <emphasis>channels</emphasis>; 4095 you can make as many of them as you want. 4096 </para> 4097 4098 <para> 4099 Every channel definition must include a destination clause that 4100 says whether messages selected for the channel go to a file, to a 4101 particular syslog facility, to the standard error stream, or are 4102 discarded. It can optionally also limit the message severity level 4103 that will be accepted by the channel (the default is 4104 <command>info</command>), and whether to include a 4105 <command>named</command>-generated time stamp, the 4106 category name 4107 and/or severity level (the default is not to include any). 4108 </para> 4109 4110 <para> 4111 The <command>null</command> destination clause 4112 causes all messages sent to the channel to be discarded; 4113 in that case, other options for the channel are meaningless. 4114 </para> 4115 4116 <para> 4117 The <command>file</command> destination clause directs 4118 the channel 4119 to a disk file. It can include limitations 4120 both on how large the file is allowed to become, and how many 4121 versions 4122 of the file will be saved each time the file is opened. 4123 </para> 4124 4125 <para> 4126 If you use the <command>versions</command> log file 4127 option, then 4128 <command>named</command> will retain that many backup 4129 versions of the file by 4130 renaming them when opening. For example, if you choose to keep 4131 three old versions 4132 of the file <filename>lamers.log</filename>, then just 4133 before it is opened 4134 <filename>lamers.log.1</filename> is renamed to 4135 <filename>lamers.log.2</filename>, <filename>lamers.log.0</filename> is renamed 4136 to <filename>lamers.log.1</filename>, and <filename>lamers.log</filename> is 4137 renamed to <filename>lamers.log.0</filename>. 4138 You can say <command>versions unlimited</command> to 4139 not limit 4140 the number of versions. 4141 If a <command>size</command> option is associated with 4142 the log file, 4143 then renaming is only done when the file being opened exceeds the 4144 indicated size. No backup versions are kept by default; any 4145 existing 4146 log file is simply appended. 4147 </para> 4148 4149 <para> 4150 The <command>size</command> option for files is used 4151 to limit log 4152 growth. If the file ever exceeds the size, then <command>named</command> will 4153 stop writing to the file unless it has a <command>versions</command> option 4154 associated with it. If backup versions are kept, the files are 4155 rolled as 4156 described above and a new one begun. If there is no 4157 <command>versions</command> option, no more data will 4158 be written to the log 4159 until some out-of-band mechanism removes or truncates the log to 4160 less than the 4161 maximum size. The default behavior is not to limit the size of 4162 the 4163 file. 4164 </para> 4165 4166 <para> 4167 Example usage of the <command>size</command> and 4168 <command>versions</command> options: 4169 </para> 4170 4171<programlisting>channel an_example_channel { 4172 file "example.log" versions 3 size 20m; 4173 print-time yes; 4174 print-category yes; 4175}; 4176</programlisting> 4177 4178 <para> 4179 The <command>syslog</command> destination clause 4180 directs the 4181 channel to the system log. Its argument is a 4182 syslog facility as described in the <command>syslog</command> man 4183 page. Known facilities are <command>kern</command>, <command>user</command>, 4184 <command>mail</command>, <command>daemon</command>, <command>auth</command>, 4185 <command>syslog</command>, <command>lpr</command>, <command>news</command>, 4186 <command>uucp</command>, <command>cron</command>, <command>authpriv</command>, 4187 <command>ftp</command>, <command>local0</command>, <command>local1</command>, 4188 <command>local2</command>, <command>local3</command>, <command>local4</command>, 4189 <command>local5</command>, <command>local6</command> and 4190 <command>local7</command>, however not all facilities 4191 are supported on 4192 all operating systems. 4193 How <command>syslog</command> will handle messages 4194 sent to 4195 this facility is described in the <command>syslog.conf</command> man 4196 page. If you have a system which uses a very old version of <command>syslog</command> that 4197 only uses two arguments to the <command>openlog()</command> function, 4198 then this clause is silently ignored. 4199 </para> 4200 <para> 4201 The <command>severity</command> clause works like <command>syslog</command>'s 4202 "priorities", except that they can also be used if you are writing 4203 straight to a file rather than using <command>syslog</command>. 4204 Messages which are not at least of the severity level given will 4205 not be selected for the channel; messages of higher severity 4206 levels 4207 will be accepted. 4208 </para> 4209 <para> 4210 If you are using <command>syslog</command>, then the <command>syslog.conf</command> priorities 4211 will also determine what eventually passes through. For example, 4212 defining a channel facility and severity as <command>daemon</command> and <command>debug</command> but 4213 only logging <command>daemon.warning</command> via <command>syslog.conf</command> will 4214 cause messages of severity <command>info</command> and 4215 <command>notice</command> to 4216 be dropped. If the situation were reversed, with <command>named</command> writing 4217 messages of only <command>warning</command> or higher, 4218 then <command>syslogd</command> would 4219 print all messages it received from the channel. 4220 </para> 4221 4222 <para> 4223 The <command>stderr</command> destination clause 4224 directs the 4225 channel to the server's standard error stream. This is intended 4226 for 4227 use when the server is running as a foreground process, for 4228 example 4229 when debugging a configuration. 4230 </para> 4231 4232 <para> 4233 The server can supply extensive debugging information when 4234 it is in debugging mode. If the server's global debug level is 4235 greater 4236 than zero, then debugging mode will be active. The global debug 4237 level is set either by starting the <command>named</command> server 4238 with the <option>-d</option> flag followed by a positive integer, 4239 or by running <command>rndc trace</command>. 4240 The global debug level 4241 can be set to zero, and debugging mode turned off, by running <command>rndc 4242notrace</command>. All debugging messages in the server have a debug 4243 level, and higher debug levels give more detailed output. Channels 4244 that specify a specific debug severity, for example: 4245 </para> 4246 4247<programlisting>channel specific_debug_level { 4248 file "foo"; 4249 severity debug 3; 4250}; 4251</programlisting> 4252 4253 <para> 4254 will get debugging output of level 3 or less any time the 4255 server is in debugging mode, regardless of the global debugging 4256 level. Channels with <command>dynamic</command> 4257 severity use the 4258 server's global debug level to determine what messages to print. 4259 </para> 4260 <para> 4261 If <command>print-time</command> has been turned on, 4262 then 4263 the date and time will be logged. <command>print-time</command> may 4264 be specified for a <command>syslog</command> channel, 4265 but is usually 4266 pointless since <command>syslog</command> also logs 4267 the date and 4268 time. If <command>print-category</command> is 4269 requested, then the 4270 category of the message will be logged as well. Finally, if <command>print-severity</command> is 4271 on, then the severity level of the message will be logged. The <command>print-</command> options may 4272 be used in any combination, and will always be printed in the 4273 following 4274 order: time, category, severity. Here is an example where all 4275 three <command>print-</command> options 4276 are on: 4277 </para> 4278 4279 <para> 4280 <computeroutput>28-Feb-2000 15:05:32.863 general: notice: running</computeroutput> 4281 </para> 4282 4283 <para> 4284 There are four predefined channels that are used for 4285 <command>named</command>'s default logging as follows. 4286 How they are 4287 used is described in <xref linkend="the_category_phrase"/>. 4288 </para> 4289 4290<programlisting>channel default_syslog { 4291 // send to syslog's daemon facility 4292 syslog daemon; 4293 // only send priority info and higher 4294 severity info; 4295 4296channel default_debug { 4297 // write to named.run in the working directory 4298 // Note: stderr is used instead of "named.run" if 4299 // the server is started with the '-f' option. 4300 file "named.run"; 4301 // log at the server's current debug level 4302 severity dynamic; 4303}; 4304 4305channel default_stderr { 4306 // writes to stderr 4307 stderr; 4308 // only send priority info and higher 4309 severity info; 4310}; 4311 4312channel null { 4313 // toss anything sent to this channel 4314 null; 4315}; 4316</programlisting> 4317 4318 <para> 4319 The <command>default_debug</command> channel has the 4320 special 4321 property that it only produces output when the server's debug 4322 level is 4323 nonzero. It normally writes to a file called <filename>named.run</filename> 4324 in the server's working directory. 4325 </para> 4326 4327 <para> 4328 For security reasons, when the "<option>-u</option>" 4329 command line option is used, the <filename>named.run</filename> file 4330 is created only after <command>named</command> has 4331 changed to the 4332 new UID, and any debug output generated while <command>named</command> is 4333 starting up and still running as root is discarded. If you need 4334 to capture this output, you must run the server with the "<option>-g</option>" 4335 option and redirect standard error to a file. 4336 </para> 4337 4338 <para> 4339 Once a channel is defined, it cannot be redefined. Thus you 4340 cannot alter the built-in channels directly, but you can modify 4341 the default logging by pointing categories at channels you have 4342 defined. 4343 </para> 4344 </sect3> 4345 4346 <sect3 id="the_category_phrase"> 4347 <title>The <command>category</command> Phrase</title> 4348 4349 <para> 4350 There are many categories, so you can send the logs you want 4351 to see wherever you want, without seeing logs you don't want. If 4352 you don't specify a list of channels for a category, then log 4353 messages 4354 in that category will be sent to the <command>default</command> category 4355 instead. If you don't specify a default category, the following 4356 "default default" is used: 4357 </para> 4358 4359<programlisting>category default { default_syslog; default_debug; }; 4360</programlisting> 4361 4362 <para> 4363 As an example, let's say you want to log security events to 4364 a file, but you also want keep the default logging behavior. You'd 4365 specify the following: 4366 </para> 4367 4368<programlisting>channel my_security_channel { 4369 file "my_security_file"; 4370 severity info; 4371}; 4372category security { 4373 my_security_channel; 4374 default_syslog; 4375 default_debug; 4376};</programlisting> 4377 4378 <para> 4379 To discard all messages in a category, specify the <command>null</command> channel: 4380 </para> 4381 4382<programlisting>category xfer-out { null; }; 4383category notify { null; }; 4384</programlisting> 4385 4386 <para> 4387 Following are the available categories and brief descriptions 4388 of the types of log information they contain. More 4389 categories may be added in future <acronym>BIND</acronym> releases. 4390 </para> 4391 <informaltable colsep="0" rowsep="0"> 4392 <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> 4393 <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> 4394 <colspec colname="2" colnum="2" colsep="0" colwidth="3.350in"/> 4395 <tbody> 4396 <row rowsep="0"> 4397 <entry colname="1"> 4398 <para><command>default</command></para> 4399 </entry> 4400 <entry colname="2"> 4401 <para> 4402 The default category defines the logging 4403 options for those categories where no specific 4404 configuration has been 4405 defined. 4406 </para> 4407 </entry> 4408 </row> 4409 <row rowsep="0"> 4410 <entry colname="1"> 4411 <para><command>general</command></para> 4412 </entry> 4413 <entry colname="2"> 4414 <para> 4415 The catch-all. Many things still aren't 4416 classified into categories, and they all end up here. 4417 </para> 4418 </entry> 4419 </row> 4420 <row rowsep="0"> 4421 <entry colname="1"> 4422 <para><command>database</command></para> 4423 </entry> 4424 <entry colname="2"> 4425 <para> 4426 Messages relating to the databases used 4427 internally by the name server to store zone and cache 4428 data. 4429 </para> 4430 </entry> 4431 </row> 4432 <row rowsep="0"> 4433 <entry colname="1"> 4434 <para><command>security</command></para> 4435 </entry> 4436 <entry colname="2"> 4437 <para> 4438 Approval and denial of requests. 4439 </para> 4440 </entry> 4441 </row> 4442 <row rowsep="0"> 4443 <entry colname="1"> 4444 <para><command>config</command></para> 4445 </entry> 4446 <entry colname="2"> 4447 <para> 4448 Configuration file parsing and processing. 4449 </para> 4450 </entry> 4451 </row> 4452 <row rowsep="0"> 4453 <entry colname="1"> 4454 <para><command>resolver</command></para> 4455 </entry> 4456 <entry colname="2"> 4457 <para> 4458 DNS resolution, such as the recursive 4459 lookups performed on behalf of clients by a caching name 4460 server. 4461 </para> 4462 </entry> 4463 </row> 4464 <row rowsep="0"> 4465 <entry colname="1"> 4466 <para><command>xfer-in</command></para> 4467 </entry> 4468 <entry colname="2"> 4469 <para> 4470 Zone transfers the server is receiving. 4471 </para> 4472 </entry> 4473 </row> 4474 <row rowsep="0"> 4475 <entry colname="1"> 4476 <para><command>xfer-out</command></para> 4477 </entry> 4478 <entry colname="2"> 4479 <para> 4480 Zone transfers the server is sending. 4481 </para> 4482 </entry> 4483 </row> 4484 <row rowsep="0"> 4485 <entry colname="1"> 4486 <para><command>notify</command></para> 4487 </entry> 4488 <entry colname="2"> 4489 <para> 4490 The NOTIFY protocol. 4491 </para> 4492 </entry> 4493 </row> 4494 <row rowsep="0"> 4495 <entry colname="1"> 4496 <para><command>client</command></para> 4497 </entry> 4498 <entry colname="2"> 4499 <para> 4500 Processing of client requests. 4501 </para> 4502 </entry> 4503 </row> 4504 <row rowsep="0"> 4505 <entry colname="1"> 4506 <para><command>unmatched</command></para> 4507 </entry> 4508 <entry colname="2"> 4509 <para> 4510 Messages that <command>named</command> was unable to determine the 4511 class of or for which there was no matching <command>view</command>. 4512 A one line summary is also logged to the <command>client</command> category. 4513 This category is best sent to a file or stderr, by 4514 default it is sent to 4515 the <command>null</command> channel. 4516 </para> 4517 </entry> 4518 </row> 4519 <row rowsep="0"> 4520 <entry colname="1"> 4521 <para><command>network</command></para> 4522 </entry> 4523 <entry colname="2"> 4524 <para> 4525 Network operations. 4526 </para> 4527 </entry> 4528 </row> 4529 <row rowsep="0"> 4530 <entry colname="1"> 4531 <para><command>update</command></para> 4532 </entry> 4533 <entry colname="2"> 4534 <para> 4535 Dynamic updates. 4536 </para> 4537 </entry> 4538 </row> 4539 <row rowsep="0"> 4540 <entry colname="1"> 4541 <para><command>update-security</command></para> 4542 </entry> 4543 <entry colname="2"> 4544 <para> 4545 Approval and denial of update requests. 4546 </para> 4547 </entry> 4548 </row> 4549 <row rowsep="0"> 4550 <entry colname="1"> 4551 <para><command>queries</command></para> 4552 </entry> 4553 <entry colname="2"> 4554 <para> 4555 Specify where queries should be logged to. 4556 </para> 4557 <para> 4558 At startup, specifying the category <command>queries</command> will also 4559 enable query logging unless <command>querylog</command> option has been 4560 specified. 4561 </para> 4562 4563 <para> 4564 The query log entry reports the client's IP 4565 address and port number, and the query name, 4566 class and type. Next it reports whether the 4567 Recursion Desired flag was set (+ if set, - 4568 if not set), if the query was signed (S), 4569 EDNS was in use (E), if TCP was used (T), if 4570 DO (DNSSEC Ok) was set (D), or if CD (Checking 4571 Disabled) was set (C). After this the 4572 destination address the query was sent to is 4573 reported. 4574 </para> 4575 4576 <para> 4577 <computeroutput>client 127.0.0.1#62536: query: www.example.com IN AAAA +SE</computeroutput> 4578 </para> 4579 <para> 4580 <computeroutput>client ::1#62537: query: www.example.net IN AAAA -SE</computeroutput> 4581 </para> 4582 </entry> 4583 </row> 4584 <row rowsep="0"> 4585 <entry colname="1"> 4586 <para><command>query-errors</command></para> 4587 </entry> 4588 <entry colname="2"> 4589 <para> 4590 Information about queries that resulted in some 4591 failure. 4592 </para> 4593 </entry> 4594 </row> 4595 <row rowsep="0"> 4596 <entry colname="1"> 4597 <para><command>dispatch</command></para> 4598 </entry> 4599 <entry colname="2"> 4600 <para> 4601 Dispatching of incoming packets to the 4602 server modules where they are to be processed. 4603 </para> 4604 </entry> 4605 </row> 4606 <row rowsep="0"> 4607 <entry colname="1"> 4608 <para><command>dnssec</command></para> 4609 </entry> 4610 <entry colname="2"> 4611 <para> 4612 DNSSEC and TSIG protocol processing. 4613 </para> 4614 </entry> 4615 </row> 4616 <row rowsep="0"> 4617 <entry colname="1"> 4618 <para><command>lame-servers</command></para> 4619 </entry> 4620 <entry colname="2"> 4621 <para> 4622 Lame servers. These are misconfigurations 4623 in remote servers, discovered by BIND 9 when trying to 4624 query those servers during resolution. 4625 </para> 4626 </entry> 4627 </row> 4628 <row rowsep="0"> 4629 <entry colname="1"> 4630 <para><command>delegation-only</command></para> 4631 </entry> 4632 <entry colname="2"> 4633 <para> 4634 Delegation only. Logs queries that have been 4635 forced to NXDOMAIN as the result of a 4636 delegation-only zone or a 4637 <command>delegation-only</command> in a hint 4638 or stub zone declaration. 4639 </para> 4640 </entry> 4641 </row> 4642 <row rowsep="0"> 4643 <entry colname="1"> 4644 <para><command>edns-disabled</command></para> 4645 </entry> 4646 <entry colname="2"> 4647 <para> 4648 Log queries that have been forced to use plain 4649 DNS due to timeouts. This is often due to 4650 the remote servers not being RFC 1034 compliant 4651 (not always returning FORMERR or similar to 4652 EDNS queries and other extensions to the DNS 4653 when they are not understood). In other words, this is 4654 targeted at servers that fail to respond to 4655 DNS queries that they don't understand. 4656 </para> 4657 <para> 4658 Note: the log message can also be due to 4659 packet loss. Before reporting servers for 4660 non-RFC 1034 compliance they should be re-tested 4661 to determine the nature of the non-compliance. 4662 This testing should prevent or reduce the 4663 number of false-positive reports. 4664 </para> 4665 <para> 4666 Note: eventually <command>named</command> will have to stop 4667 treating such timeouts as due to RFC 1034 non 4668 compliance and start treating it as plain 4669 packet loss. Falsely classifying packet 4670 loss as due to RFC 1034 non compliance impacts 4671 on DNSSEC validation which requires EDNS for 4672 the DNSSEC records to be returned. 4673 </para> 4674 </entry> 4675 </row> 4676 <row rowsep="0"> 4677 <entry colname="1"> 4678 <para><command>RPZ</command></para> 4679 </entry> 4680 <entry colname="2"> 4681 <para> 4682 Information about errors in response policy zone files, 4683 rewritten responses, and at the highest 4684 <command>debug</command> levels, mere rewriting 4685 attempts. 4686 </para> 4687 </entry> 4688 </row> 4689 </tbody> 4690 </tgroup> 4691 </informaltable> 4692 </sect3> 4693 <sect3> 4694 <title>The <command>query-errors</command> Category</title> 4695 <para> 4696 The <command>query-errors</command> category is 4697 specifically intended for debugging purposes: To identify 4698 why and how specific queries result in responses which 4699 indicate an error. 4700 Messages of this category are therefore only logged 4701 with <command>debug</command> levels. 4702 </para> 4703 4704 <para> 4705 At the debug levels of 1 or higher, each response with the 4706 rcode of SERVFAIL is logged as follows: 4707 </para> 4708 <para> 4709 <computeroutput>client 127.0.0.1#61502: query failed (SERVFAIL) for www.example.com/IN/AAAA at query.c:3880</computeroutput> 4710 </para> 4711 <para> 4712 This means an error resulting in SERVFAIL was 4713 detected at line 3880 of source file 4714 <filename>query.c</filename>. 4715 Log messages of this level will particularly 4716 help identify the cause of SERVFAIL for an 4717 authoritative server. 4718 </para> 4719 <para> 4720 At the debug levels of 2 or higher, detailed context 4721 information of recursive resolutions that resulted in 4722 SERVFAIL is logged. 4723 The log message will look like as follows: 4724 </para> 4725 <para> 4726<!-- NOTE: newlines and some spaces added so this would fit on page --> 4727 <programlisting> 4728fetch completed at resolver.c:2970 for www.example.com/A 4729in 30.000183: timed out/success [domain:example.com, 4730referral:2,restart:7,qrysent:8,timeout:5,lame:0,neterr:0, 4731badresp:1,adberr:0,findfail:0,valfail:0] 4732 </programlisting> 4733 </para> 4734 <para> 4735 The first part before the colon shows that a recursive 4736 resolution for AAAA records of www.example.com completed 4737 in 30.000183 seconds and the final result that led to the 4738 SERVFAIL was determined at line 2970 of source file 4739 <filename>resolver.c</filename>. 4740 </para> 4741 <para> 4742 The following part shows the detected final result and the 4743 latest result of DNSSEC validation. 4744 The latter is always success when no validation attempt 4745 is made. 4746 In this example, this query resulted in SERVFAIL probably 4747 because all name servers are down or unreachable, leading 4748 to a timeout in 30 seconds. 4749 DNSSEC validation was probably not attempted. 4750 </para> 4751 <para> 4752 The last part enclosed in square brackets shows statistics 4753 information collected for this particular resolution 4754 attempt. 4755 The <varname>domain</varname> field shows the deepest zone 4756 that the resolver reached; 4757 it is the zone where the error was finally detected. 4758 The meaning of the other fields is summarized in the 4759 following table. 4760 </para> 4761 4762 <informaltable colsep="0" rowsep="0"> 4763 <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> 4764 <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> 4765 <colspec colname="2" colnum="2" colsep="0" colwidth="3.350in"/> 4766 <tbody> 4767 <row rowsep="0"> 4768 <entry colname="1"> 4769 <para><varname>referral</varname></para> 4770 </entry> 4771 <entry colname="2"> 4772 <para> 4773 The number of referrals the resolver received 4774 throughout the resolution process. 4775 In the above example this is 2, which are most 4776 likely com and example.com. 4777 </para> 4778 </entry> 4779 </row> 4780 <row rowsep="0"> 4781 <entry colname="1"> 4782 <para><varname>restart</varname></para> 4783 </entry> 4784 <entry colname="2"> 4785 <para> 4786 The number of cycles that the resolver tried 4787 remote servers at the <varname>domain</varname> 4788 zone. 4789 In each cycle the resolver sends one query 4790 (possibly resending it, depending on the response) 4791 to each known name server of 4792 the <varname>domain</varname> zone. 4793 </para> 4794 </entry> 4795 </row> 4796 <row rowsep="0"> 4797 <entry colname="1"> 4798 <para><varname>qrysent</varname></para> 4799 </entry> 4800 <entry colname="2"> 4801 <para> 4802 The number of queries the resolver sent at the 4803 <varname>domain</varname> zone. 4804 </para> 4805 </entry> 4806 </row> 4807 <row rowsep="0"> 4808 <entry colname="1"> 4809 <para><varname>timeout</varname></para> 4810 </entry> 4811 <entry colname="2"> 4812 <para> 4813 The number of timeouts since the resolver 4814 received the last response. 4815 </para> 4816 </entry> 4817 </row> 4818 <row rowsep="0"> 4819 <entry colname="1"> 4820 <para><varname>lame</varname></para> 4821 </entry> 4822 <entry colname="2"> 4823 <para> 4824 The number of lame servers the resolver detected 4825 at the <varname>domain</varname> zone. 4826 A server is detected to be lame either by an 4827 invalid response or as a result of lookup in 4828 BIND9's address database (ADB), where lame 4829 servers are cached. 4830 </para> 4831 </entry> 4832 </row> 4833 <row rowsep="0"> 4834 <entry colname="1"> 4835 <para><varname>neterr</varname></para> 4836 </entry> 4837 <entry colname="2"> 4838 <para> 4839 The number of erroneous results that the 4840 resolver encountered in sending queries 4841 at the <varname>domain</varname> zone. 4842 One common case is the remote server is 4843 unreachable and the resolver receives an ICMP 4844 unreachable error message. 4845 </para> 4846 </entry> 4847 </row> 4848 <row rowsep="0"> 4849 <entry colname="1"> 4850 <para><varname>badresp</varname></para> 4851 </entry> 4852 <entry colname="2"> 4853 <para> 4854 The number of unexpected responses (other than 4855 <varname>lame</varname>) to queries sent by the 4856 resolver at the <varname>domain</varname> zone. 4857 </para> 4858 </entry> 4859 </row> 4860 <row rowsep="0"> 4861 <entry colname="1"> 4862 <para><varname>adberr</varname></para> 4863 </entry> 4864 <entry colname="2"> 4865 <para> 4866 Failures in finding remote server addresses 4867 of the <varname>domain</varname> zone in the ADB. 4868 One common case of this is that the remote 4869 server's name does not have any address records. 4870 </para> 4871 </entry> 4872 </row> 4873 <row rowsep="0"> 4874 <entry colname="1"> 4875 <para><varname>findfail</varname></para> 4876 </entry> 4877 <entry colname="2"> 4878 <para> 4879 Failures of resolving remote server addresses. 4880 This is a total number of failures throughout 4881 the resolution process. 4882 </para> 4883 </entry> 4884 </row> 4885 <row rowsep="0"> 4886 <entry colname="1"> 4887 <para><varname>valfail</varname></para> 4888 </entry> 4889 <entry colname="2"> 4890 <para> 4891 Failures of DNSSEC validation. 4892 Validation failures are counted throughout 4893 the resolution process (not limited to 4894 the <varname>domain</varname> zone), but should 4895 only happen in <varname>domain</varname>. 4896 </para> 4897 </entry> 4898 </row> 4899 </tbody> 4900 </tgroup> 4901 </informaltable> 4902 <para> 4903 At the debug levels of 3 or higher, the same messages 4904 as those at the debug 1 level are logged for other errors 4905 than SERVFAIL. 4906 Note that negative responses such as NXDOMAIN are not 4907 regarded as errors here. 4908 </para> 4909 <para> 4910 At the debug levels of 4 or higher, the same messages 4911 as those at the debug 2 level are logged for other errors 4912 than SERVFAIL. 4913 Unlike the above case of level 3, messages are logged for 4914 negative responses. 4915 This is because any unexpected results can be difficult to 4916 debug in the recursion case. 4917 </para> 4918 </sect3> 4919 </sect2> 4920 4921 <sect2> 4922 <title><command>lwres</command> Statement Grammar</title> 4923 4924 <para> 4925 This is the grammar of the <command>lwres</command> 4926 statement in the <filename>named.conf</filename> file: 4927 </para> 4928 4929<programlisting><command>lwres</command> { 4930 <optional> listen-on { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; 4931 <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> 4932 <optional> view <replaceable>view_name</replaceable>; </optional> 4933 <optional> search { <replaceable>domain_name</replaceable> ; <optional> <replaceable>domain_name</replaceable> ; ... </optional> }; </optional> 4934 <optional> ndots <replaceable>number</replaceable>; </optional> 4935}; 4936</programlisting> 4937 4938 </sect2> 4939 <sect2> 4940 <title><command>lwres</command> Statement Definition and Usage</title> 4941 4942 <para> 4943 The <command>lwres</command> statement configures the 4944 name 4945 server to also act as a lightweight resolver server. (See 4946 <xref linkend="lwresd"/>.) There may be multiple 4947 <command>lwres</command> statements configuring 4948 lightweight resolver servers with different properties. 4949 </para> 4950 4951 <para> 4952 The <command>listen-on</command> statement specifies a 4953 list of 4954 addresses (and ports) that this instance of a lightweight resolver 4955 daemon 4956 should accept requests on. If no port is specified, port 921 is 4957 used. 4958 If this statement is omitted, requests will be accepted on 4959 127.0.0.1, 4960 port 921. 4961 </para> 4962 4963 <para> 4964 The <command>view</command> statement binds this 4965 instance of a 4966 lightweight resolver daemon to a view in the DNS namespace, so that 4967 the 4968 response will be constructed in the same manner as a normal DNS 4969 query 4970 matching this view. If this statement is omitted, the default view 4971 is 4972 used, and if there is no default view, an error is triggered. 4973 </para> 4974 4975 <para> 4976 The <command>search</command> statement is equivalent to 4977 the 4978 <command>search</command> statement in 4979 <filename>/etc/resolv.conf</filename>. It provides a 4980 list of domains 4981 which are appended to relative names in queries. 4982 </para> 4983 4984 <para> 4985 The <command>ndots</command> statement is equivalent to 4986 the 4987 <command>ndots</command> statement in 4988 <filename>/etc/resolv.conf</filename>. It indicates the 4989 minimum 4990 number of dots in a relative domain name that should result in an 4991 exact match lookup before search path elements are appended. 4992 </para> 4993 </sect2> 4994 <sect2> 4995 <title><command>masters</command> Statement Grammar</title> 4996 4997<programlisting> 4998<command>masters</command> <replaceable>name</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> { ( <replaceable>masters_list</replaceable> | 4999 <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> <optional>key <replaceable>key</replaceable></optional> ) ; <optional>...</optional> }; 5000</programlisting> 5001 5002 </sect2> 5003 5004 <sect2> 5005 <title><command>masters</command> Statement Definition and 5006 Usage</title> 5007 <para><command>masters</command> 5008 lists allow for a common set of masters to be easily used by 5009 multiple stub and slave zones. 5010 </para> 5011 </sect2> 5012 5013 <sect2> 5014 <title><command>options</command> Statement Grammar</title> 5015 5016 <para> 5017 This is the grammar of the <command>options</command> 5018 statement in the <filename>named.conf</filename> file: 5019 </para> 5020 5021<programlisting><command>options</command> { 5022 <optional> attach-cache <replaceable>cache_name</replaceable>; </optional> 5023 <optional> version <replaceable>version_string</replaceable>; </optional> 5024 <optional> hostname <replaceable>hostname_string</replaceable>; </optional> 5025 <optional> server-id <replaceable>server_id_string</replaceable>; </optional> 5026 <optional> directory <replaceable>path_name</replaceable>; </optional> 5027 <optional> key-directory <replaceable>path_name</replaceable>; </optional> 5028 <optional> managed-keys-directory <replaceable>path_name</replaceable>; </optional> 5029 <optional> named-xfer <replaceable>path_name</replaceable>; </optional> 5030 <optional> tkey-gssapi-keytab <replaceable>path_name</replaceable>; </optional> 5031 <optional> tkey-gssapi-credential <replaceable>principal</replaceable>; </optional> 5032 <optional> tkey-domain <replaceable>domainname</replaceable>; </optional> 5033 <optional> tkey-dhkey <replaceable>key_name</replaceable> <replaceable>key_tag</replaceable>; </optional> 5034 <optional> cache-file <replaceable>path_name</replaceable>; </optional> 5035 <optional> dump-file <replaceable>path_name</replaceable>; </optional> 5036 <optional> bindkeys-file <replaceable>path_name</replaceable>; </optional> 5037 <optional> secroots-file <replaceable>path_name</replaceable>; </optional> 5038 <optional> session-keyfile <replaceable>path_name</replaceable>; </optional> 5039 <optional> session-keyname <replaceable>key_name</replaceable>; </optional> 5040 <optional> session-keyalg <replaceable>algorithm_id</replaceable>; </optional> 5041 <optional> memstatistics <replaceable>yes_or_no</replaceable>; </optional> 5042 <optional> memstatistics-file <replaceable>path_name</replaceable>; </optional> 5043 <optional> pid-file <replaceable>path_name</replaceable>; </optional> 5044 <optional> recursing-file <replaceable>path_name</replaceable>; </optional> 5045 <optional> statistics-file <replaceable>path_name</replaceable>; </optional> 5046 <optional> zone-statistics <replaceable>yes_or_no</replaceable>; </optional> 5047 <optional> auth-nxdomain <replaceable>yes_or_no</replaceable>; </optional> 5048 <optional> deallocate-on-exit <replaceable>yes_or_no</replaceable>; </optional> 5049 <optional> dialup <replaceable>dialup_option</replaceable>; </optional> 5050 <optional> fake-iquery <replaceable>yes_or_no</replaceable>; </optional> 5051 <optional> fetch-glue <replaceable>yes_or_no</replaceable>; </optional> 5052 <optional> flush-zones-on-shutdown <replaceable>yes_or_no</replaceable>; </optional> 5053 <optional> has-old-clients <replaceable>yes_or_no</replaceable>; </optional> 5054 <optional> host-statistics <replaceable>yes_or_no</replaceable>; </optional> 5055 <optional> host-statistics-max <replaceable>number</replaceable>; </optional> 5056 <optional> minimal-responses <replaceable>yes_or_no</replaceable>; </optional> 5057 <optional> multiple-cnames <replaceable>yes_or_no</replaceable>; </optional> 5058 <optional> notify <replaceable>yes_or_no</replaceable> | <replaceable>explicit</replaceable> | <replaceable>master-only</replaceable>; </optional> 5059 <optional> recursion <replaceable>yes_or_no</replaceable>; </optional> 5060 <optional> rfc2308-type1 <replaceable>yes_or_no</replaceable>; </optional> 5061 <optional> use-id-pool <replaceable>yes_or_no</replaceable>; </optional> 5062 <optional> maintain-ixfr-base <replaceable>yes_or_no</replaceable>; </optional> 5063 <optional> ixfr-from-differences (<replaceable>yes_or_no</replaceable> | <constant>master</constant> | <constant>slave</constant>); </optional> 5064 <optional> dnssec-enable <replaceable>yes_or_no</replaceable>; </optional> 5065 <optional> dnssec-validation (<replaceable>yes_or_no</replaceable> | <constant>auto</constant>); </optional> 5066 <optional> dnssec-lookaside ( <replaceable>auto</replaceable> | 5067 <replaceable>no</replaceable> | 5068 <replaceable>domain</replaceable> trust-anchor <replaceable>domain</replaceable> ); </optional> 5069 <optional> dnssec-must-be-secure <replaceable>domain yes_or_no</replaceable>; </optional> 5070 <optional> dnssec-accept-expired <replaceable>yes_or_no</replaceable>; </optional> 5071 <optional> forward ( <replaceable>only</replaceable> | <replaceable>first</replaceable> ); </optional> 5072 <optional> forwarders { <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> 5073 <optional> dual-stack-servers <optional>port <replaceable>ip_port</replaceable></optional> { 5074 ( <replaceable>domain_name</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> | 5075 <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ) ; 5076 ... }; </optional> 5077 <optional> check-names ( <replaceable>master</replaceable> | <replaceable>slave</replaceable> | <replaceable>response</replaceable> ) 5078 ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional> 5079 <optional> check-dup-records ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional> 5080 <optional> check-mx ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional> 5081 <optional> check-wildcard <replaceable>yes_or_no</replaceable>; </optional> 5082 <optional> check-integrity <replaceable>yes_or_no</replaceable>; </optional> 5083 <optional> check-mx-cname ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional> 5084 <optional> check-srv-cname ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional> 5085 <optional> check-sibling <replaceable>yes_or_no</replaceable>; </optional> 5086 <optional> allow-new-zones { <replaceable>yes_or_no</replaceable> }; </optional> 5087 <optional> allow-notify { <replaceable>address_match_list</replaceable> }; </optional> 5088 <optional> allow-query { <replaceable>address_match_list</replaceable> }; </optional> 5089 <optional> allow-query-on { <replaceable>address_match_list</replaceable> }; </optional> 5090 <optional> allow-query-cache { <replaceable>address_match_list</replaceable> }; </optional> 5091 <optional> allow-query-cache-on { <replaceable>address_match_list</replaceable> }; </optional> 5092 <optional> allow-transfer { <replaceable>address_match_list</replaceable> }; </optional> 5093 <optional> allow-recursion { <replaceable>address_match_list</replaceable> }; </optional> 5094 <optional> allow-recursion-on { <replaceable>address_match_list</replaceable> }; </optional> 5095 <optional> allow-update { <replaceable>address_match_list</replaceable> }; </optional> 5096 <optional> allow-update-forwarding { <replaceable>address_match_list</replaceable> }; </optional> 5097 <optional> update-check-ksk <replaceable>yes_or_no</replaceable>; </optional> 5098 <optional> dnssec-dnskey-kskonly <replaceable>yes_or_no</replaceable>; </optional> 5099 <optional> dnssec-secure-to-insecure <replaceable>yes_or_no</replaceable> ;</optional> 5100 <optional> try-tcp-refresh <replaceable>yes_or_no</replaceable>; </optional> 5101 <optional> allow-v6-synthesis { <replaceable>address_match_list</replaceable> }; </optional> 5102 <optional> blackhole { <replaceable>address_match_list</replaceable> }; </optional> 5103 <optional> use-v4-udp-ports { <replaceable>port_list</replaceable> }; </optional> 5104 <optional> avoid-v4-udp-ports { <replaceable>port_list</replaceable> }; </optional> 5105 <optional> use-v6-udp-ports { <replaceable>port_list</replaceable> }; </optional> 5106 <optional> avoid-v6-udp-ports { <replaceable>port_list</replaceable> }; </optional> 5107 <optional> listen-on <optional> port <replaceable>ip_port</replaceable> </optional> { <replaceable>address_match_list</replaceable> }; </optional> 5108 <optional> listen-on-v6 <optional> port <replaceable>ip_port</replaceable> </optional> { <replaceable>address_match_list</replaceable> }; </optional> 5109 <optional> query-source ( ( <replaceable>ip4_addr</replaceable> | <replaceable>*</replaceable> ) 5110 <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> | 5111 <optional> address ( <replaceable>ip4_addr</replaceable> | <replaceable>*</replaceable> ) </optional> 5112 <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> ) ; </optional> 5113 <optional> query-source-v6 ( ( <replaceable>ip6_addr</replaceable> | <replaceable>*</replaceable> ) 5114 <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> | 5115 <optional> address ( <replaceable>ip6_addr</replaceable> | <replaceable>*</replaceable> ) </optional> 5116 <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> ) ; </optional> 5117 <optional> use-queryport-pool <replaceable>yes_or_no</replaceable>; </optional> 5118 <optional> queryport-pool-ports <replaceable>number</replaceable>; </optional> 5119 <optional> queryport-pool-updateinterval <replaceable>number</replaceable>; </optional> 5120 <optional> max-transfer-time-in <replaceable>number</replaceable>; </optional> 5121 <optional> max-transfer-time-out <replaceable>number</replaceable>; </optional> 5122 <optional> max-transfer-idle-in <replaceable>number</replaceable>; </optional> 5123 <optional> max-transfer-idle-out <replaceable>number</replaceable>; </optional> 5124 <optional> tcp-clients <replaceable>number</replaceable>; </optional> 5125 <optional> reserved-sockets <replaceable>number</replaceable>; </optional> 5126 <optional> recursive-clients <replaceable>number</replaceable>; </optional> 5127 <optional> serial-query-rate <replaceable>number</replaceable>; </optional> 5128 <optional> serial-queries <replaceable>number</replaceable>; </optional> 5129 <optional> tcp-listen-queue <replaceable>number</replaceable>; </optional> 5130 <optional> transfer-format <replaceable>( one-answer | many-answers )</replaceable>; </optional> 5131 <optional> transfers-in <replaceable>number</replaceable>; </optional> 5132 <optional> transfers-out <replaceable>number</replaceable>; </optional> 5133 <optional> transfers-per-ns <replaceable>number</replaceable>; </optional> 5134 <optional> transfer-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> 5135 <optional> transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> 5136 <optional> alt-transfer-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> 5137 <optional> alt-transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) 5138 <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> 5139 <optional> use-alt-transfer-source <replaceable>yes_or_no</replaceable>; </optional> 5140 <optional> notify-delay <replaceable>seconds</replaceable> ; </optional> 5141 <optional> notify-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> 5142 <optional> notify-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> 5143 <optional> notify-to-soa <replaceable>yes_or_no</replaceable> ; </optional> 5144 <optional> also-notify { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; 5145 <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> 5146 <optional> max-ixfr-log-size <replaceable>number</replaceable>; </optional> 5147 <optional> max-journal-size <replaceable>size_spec</replaceable>; </optional> 5148 <optional> coresize <replaceable>size_spec</replaceable> ; </optional> 5149 <optional> datasize <replaceable>size_spec</replaceable> ; </optional> 5150 <optional> files <replaceable>size_spec</replaceable> ; </optional> 5151 <optional> stacksize <replaceable>size_spec</replaceable> ; </optional> 5152 <optional> cleaning-interval <replaceable>number</replaceable>; </optional> 5153 <optional> heartbeat-interval <replaceable>number</replaceable>; </optional> 5154 <optional> interface-interval <replaceable>number</replaceable>; </optional> 5155 <optional> statistics-interval <replaceable>number</replaceable>; </optional> 5156 <optional> topology { <replaceable>address_match_list</replaceable> }</optional>; 5157 <optional> sortlist { <replaceable>address_match_list</replaceable> }</optional>; 5158 <optional> rrset-order { <replaceable>order_spec</replaceable> ; <optional> <replaceable>order_spec</replaceable> ; ... </optional> </optional> }; 5159 <optional> lame-ttl <replaceable>number</replaceable>; </optional> 5160 <optional> max-ncache-ttl <replaceable>number</replaceable>; </optional> 5161 <optional> max-cache-ttl <replaceable>number</replaceable>; </optional> 5162 <optional> sig-validity-interval <replaceable>number</replaceable> <optional><replaceable>number</replaceable></optional> ; </optional> 5163 <optional> sig-signing-nodes <replaceable>number</replaceable> ; </optional> 5164 <optional> sig-signing-signatures <replaceable>number</replaceable> ; </optional> 5165 <optional> sig-signing-type <replaceable>number</replaceable> ; </optional> 5166 <optional> min-roots <replaceable>number</replaceable>; </optional> 5167 <optional> use-ixfr <replaceable>yes_or_no</replaceable> ; </optional> 5168 <optional> provide-ixfr <replaceable>yes_or_no</replaceable>; </optional> 5169 <optional> request-ixfr <replaceable>yes_or_no</replaceable>; </optional> 5170 <optional> treat-cr-as-space <replaceable>yes_or_no</replaceable> ; </optional> 5171 <optional> min-refresh-time <replaceable>number</replaceable> ; </optional> 5172 <optional> max-refresh-time <replaceable>number</replaceable> ; </optional> 5173 <optional> min-retry-time <replaceable>number</replaceable> ; </optional> 5174 <optional> max-retry-time <replaceable>number</replaceable> ; </optional> 5175 <optional> port <replaceable>ip_port</replaceable>; </optional> 5176 <optional> additional-from-auth <replaceable>yes_or_no</replaceable> ; </optional> 5177 <optional> additional-from-cache <replaceable>yes_or_no</replaceable> ; </optional> 5178 <optional> random-device <replaceable>path_name</replaceable> ; </optional> 5179 <optional> max-cache-size <replaceable>size_spec</replaceable> ; </optional> 5180 <optional> match-mapped-addresses <replaceable>yes_or_no</replaceable>; </optional> 5181 <optional> filter-aaaa-on-v4 ( <replaceable>yes_or_no</replaceable> | <replaceable>break-dnssec</replaceable> ); </optional> 5182 <optional> filter-aaaa { <replaceable>address_match_list</replaceable> }; </optional> 5183 <optional> dns64 <replaceable>IPv6-prefix</replaceable> { 5184 <optional> clients { <replaceable>address_match_list</replaceable> }; </optional> 5185 <optional> mapped { <replaceable>address_match_list</replaceable> }; </optional> 5186 <optional> exclude { <replaceable>address_match_list</replaceable> }; </optional> 5187 <optional> suffix IPv6-address; </optional> 5188 <optional> recursive-only <replaceable>yes_or_no</replaceable>; </optional> 5189 <optional> break-dnssec <replaceable>yes_or_no</replaceable>; </optional> 5190 }; </optional>; 5191 <optional> dns64-server <replaceable>name</replaceable> </optional> 5192 <optional> dns64-contact <replaceable>name</replaceable> </optional> 5193 <optional> preferred-glue ( <replaceable>A</replaceable> | <replaceable>AAAA</replaceable> | <replaceable>NONE</replaceable> ); </optional> 5194 <optional> edns-udp-size <replaceable>number</replaceable>; </optional> 5195 <optional> max-udp-size <replaceable>number</replaceable>; </optional> 5196 <optional> root-delegation-only <optional> exclude { <replaceable>namelist</replaceable> } </optional> ; </optional> 5197 <optional> querylog <replaceable>yes_or_no</replaceable> ; </optional> 5198 <optional> disable-algorithms <replaceable>domain</replaceable> { <replaceable>algorithm</replaceable>; 5199 <optional> <replaceable>algorithm</replaceable>; </optional> }; </optional> 5200 <optional> acache-enable <replaceable>yes_or_no</replaceable> ; </optional> 5201 <optional> acache-cleaning-interval <replaceable>number</replaceable>; </optional> 5202 <optional> max-acache-size <replaceable>size_spec</replaceable> ; </optional> 5203 <optional> clients-per-query <replaceable>number</replaceable> ; </optional> 5204 <optional> max-clients-per-query <replaceable>number</replaceable> ; </optional> 5205 <optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>) ; </optional> 5206 <optional> empty-server <replaceable>name</replaceable> ; </optional> 5207 <optional> empty-contact <replaceable>name</replaceable> ; </optional> 5208 <optional> empty-zones-enable <replaceable>yes_or_no</replaceable> ; </optional> 5209 <optional> disable-empty-zone <replaceable>zone_name</replaceable> ; </optional> 5210 <optional> zero-no-soa-ttl <replaceable>yes_or_no</replaceable> ; </optional> 5211 <optional> zero-no-soa-ttl-cache <replaceable>yes_or_no</replaceable> ; </optional> 5212 <optional> resolver-query-timeout <replaceable>number</replaceable> ; </optional> 5213 <optional> deny-answer-addresses { <replaceable>address_match_list</replaceable> } <optional> except-from { <replaceable>namelist</replaceable> } </optional>;</optional> 5214 <optional> deny-answer-aliases { <replaceable>namelist</replaceable> } <optional> except-from { <replaceable>namelist</replaceable> } </optional>;</optional> 5215 <optional> response-policy { <replaceable>zone_name</replaceable> <optional> policy given | disabled | passthru | nxdomain | nodata | cname <replaceable>domain</replaceable> </optional> ; } ; </optional> 5216}; 5217</programlisting> 5218 5219 </sect2> 5220 5221 <sect2 id="options"> 5222 <title><command>options</command> Statement Definition and 5223 Usage</title> 5224 5225 <para> 5226 The <command>options</command> statement sets up global 5227 options 5228 to be used by <acronym>BIND</acronym>. This statement 5229 may appear only 5230 once in a configuration file. If there is no <command>options</command> 5231 statement, an options block with each option set to its default will 5232 be used. 5233 </para> 5234 5235 <variablelist> 5236 5237 <varlistentry> 5238 <term><command>attach-cache</command></term> 5239 <listitem> 5240 <para> 5241 Allows multiple views to share a single cache 5242 database. 5243 Each view has its own cache database by default, but 5244 if multiple views have the same operational policy 5245 for name resolution and caching, those views can 5246 share a single cache to save memory and possibly 5247 improve resolution efficiency by using this option. 5248 </para> 5249 5250 <para> 5251 The <command>attach-cache</command> option 5252 may also be specified in <command>view</command> 5253 statements, in which case it overrides the 5254 global <command>attach-cache</command> option. 5255 </para> 5256 5257 <para> 5258 The <replaceable>cache_name</replaceable> specifies 5259 the cache to be shared. 5260 When the <command>named</command> server configures 5261 views which are supposed to share a cache, it 5262 creates a cache with the specified name for the 5263 first view of these sharing views. 5264 The rest of the views will simply refer to the 5265 already created cache. 5266 </para> 5267 5268 <para> 5269 One common configuration to share a cache would be to 5270 allow all views to share a single cache. 5271 This can be done by specifying 5272 the <command>attach-cache</command> as a global 5273 option with an arbitrary name. 5274 </para> 5275 5276 <para> 5277 Another possible operation is to allow a subset of 5278 all views to share a cache while the others to 5279 retain their own caches. 5280 For example, if there are three views A, B, and C, 5281 and only A and B should share a cache, specify the 5282 <command>attach-cache</command> option as a view A (or 5283 B)'s option, referring to the other view name: 5284 </para> 5285 5286<programlisting> 5287 view "A" { 5288 // this view has its own cache 5289 ... 5290 }; 5291 view "B" { 5292 // this view refers to A's cache 5293 attach-cache "A"; 5294 }; 5295 view "C" { 5296 // this view has its own cache 5297 ... 5298 }; 5299</programlisting> 5300 5301 <para> 5302 Views that share a cache must have the same policy 5303 on configurable parameters that may affect caching. 5304 The current implementation requires the following 5305 configurable options be consistent among these 5306 views: 5307 <command>check-names</command>, 5308 <command>cleaning-interval</command>, 5309 <command>dnssec-accept-expired</command>, 5310 <command>dnssec-validation</command>, 5311 <command>max-cache-ttl</command>, 5312 <command>max-ncache-ttl</command>, 5313 <command>max-cache-size</command>, and 5314 <command>zero-no-soa-ttl</command>. 5315 </para> 5316 5317 <para> 5318 Note that there may be other parameters that may 5319 cause confusion if they are inconsistent for 5320 different views that share a single cache. 5321 For example, if these views define different sets of 5322 forwarders that can return different answers for the 5323 same question, sharing the answer does not make 5324 sense or could even be harmful. 5325 It is administrator's responsibility to ensure 5326 configuration differences in different views do 5327 not cause disruption with a shared cache. 5328 </para> 5329 </listitem> 5330 5331 </varlistentry> 5332 5333 <varlistentry> 5334 <term><command>directory</command></term> 5335 <listitem> 5336 <para> 5337 The working directory of the server. 5338 Any non-absolute pathnames in the configuration file will be 5339 taken 5340 as relative to this directory. The default location for most 5341 server 5342 output files (e.g. <filename>named.run</filename>) 5343 is this directory. 5344 If a directory is not specified, the working directory 5345 defaults to `<filename>.</filename>', the directory from 5346 which the server 5347 was started. The directory specified should be an absolute 5348 path. 5349 </para> 5350 </listitem> 5351 </varlistentry> 5352 5353 <varlistentry> 5354 <term><command>key-directory</command></term> 5355 <listitem> 5356 <para> 5357 When performing dynamic update of secure zones, the 5358 directory where the public and private DNSSEC key files 5359 should be found, if different than the current working 5360 directory. (Note that this option has no effect on the 5361 paths for files containing non-DNSSEC keys such as 5362 <filename>bind.keys</filename>, 5363 <filename>rndc.key</filename> or 5364 <filename>session.key</filename>.) 5365 </para> 5366 </listitem> 5367 </varlistentry> 5368 5369 <varlistentry> 5370 <term><command>managed-keys-directory</command></term> 5371 <listitem> 5372 <para> 5373 The directory used to hold the files used to track managed keys. 5374 By default it is the working directory. It there are no 5375 views then the file <filename>managed-keys.bind</filename> 5376 otherwise a SHA256 hash of the view name is used with 5377 <filename>.mkeys</filename> extension added. 5378 </para> 5379 </listitem> 5380 </varlistentry> 5381 5382 <varlistentry> 5383 <term><command>named-xfer</command></term> 5384 <listitem> 5385 <para> 5386 <emphasis>This option is obsolete.</emphasis> It 5387 was used in <acronym>BIND</acronym> 8 to specify 5388 the pathname to the <command>named-xfer</command> 5389 program. In <acronym>BIND</acronym> 9, no separate 5390 <command>named-xfer</command> program is needed; 5391 its functionality is built into the name server. 5392 </para> 5393 </listitem> 5394 </varlistentry> 5395 5396 <varlistentry> 5397 <term><command>tkey-gssapi-keytab</command></term> 5398 <listitem> 5399 <para> 5400 The KRB5 keytab file to use for GSS-TSIG updates. If 5401 this option is set and tkey-gssapi-credential is not 5402 set, then updates will be allowed with any key 5403 matching a principal in the specified keytab. 5404 </para> 5405 </listitem> 5406 </varlistentry> 5407 5408 <varlistentry> 5409 <term><command>tkey-gssapi-credential</command></term> 5410 <listitem> 5411 <para> 5412 The security credential with which the server should 5413 authenticate keys requested by the GSS-TSIG protocol. 5414 Currently only Kerberos 5 authentication is available 5415 and the credential is a Kerberos principal which the 5416 server can acquire through the default system key 5417 file, normally <filename>/etc/krb5.keytab</filename>. 5418 The location keytab file can be overridden using the 5419 tkey-gssapi-keytab option. Normally this principal is 5420 of the form "<userinput>DNS/</userinput><varname>server.domain</varname>". 5421 To use GSS-TSIG, <command>tkey-domain</command> must 5422 also be set if a specific keytab is not set with 5423 tkey-gssapi-keytab. 5424 </para> 5425 </listitem> 5426 </varlistentry> 5427 5428 <varlistentry> 5429 <term><command>tkey-domain</command></term> 5430 <listitem> 5431 <para> 5432 The domain appended to the names of all shared keys 5433 generated with <command>TKEY</command>. When a 5434 client requests a <command>TKEY</command> exchange, 5435 it may or may not specify the desired name for the 5436 key. If present, the name of the shared key will 5437 be <varname>client specified part</varname> + 5438 <varname>tkey-domain</varname>. Otherwise, the 5439 name of the shared key will be <varname>random hex 5440 digits</varname> + <varname>tkey-domain</varname>. 5441 In most cases, the <command>domainname</command> 5442 should be the server's domain name, or an otherwise 5443 non-existent subdomain like 5444 "_tkey.<varname>domainname</varname>". If you are 5445 using GSS-TSIG, this variable must be defined, unless 5446 you specify a specific keytab using tkey-gssapi-keytab. 5447 </para> 5448 </listitem> 5449 </varlistentry> 5450 5451 <varlistentry> 5452 <term><command>tkey-dhkey</command></term> 5453 <listitem> 5454 <para> 5455 The Diffie-Hellman key used by the server 5456 to generate shared keys with clients using the Diffie-Hellman 5457 mode 5458 of <command>TKEY</command>. The server must be 5459 able to load the 5460 public and private keys from files in the working directory. 5461 In 5462 most cases, the keyname should be the server's host name. 5463 </para> 5464 </listitem> 5465 </varlistentry> 5466 5467 <varlistentry> 5468 <term><command>cache-file</command></term> 5469 <listitem> 5470 <para> 5471 This is for testing only. Do not use. 5472 </para> 5473 </listitem> 5474 </varlistentry> 5475 5476 <varlistentry> 5477 <term><command>dump-file</command></term> 5478 <listitem> 5479 <para> 5480 The pathname of the file the server dumps 5481 the database to when instructed to do so with 5482 <command>rndc dumpdb</command>. 5483 If not specified, the default is <filename>named_dump.db</filename>. 5484 </para> 5485 </listitem> 5486 </varlistentry> 5487 5488 <varlistentry> 5489 <term><command>memstatistics-file</command></term> 5490 <listitem> 5491 <para> 5492 The pathname of the file the server writes memory 5493 usage statistics to on exit. If not specified, 5494 the default is <filename>named.memstats</filename>. 5495 </para> 5496 </listitem> 5497 </varlistentry> 5498 5499 <varlistentry> 5500 <term><command>pid-file</command></term> 5501 <listitem> 5502 <para> 5503 The pathname of the file the server writes its process ID 5504 in. If not specified, the default is 5505 <filename>/var/run/named/named.pid</filename>. 5506 The PID file is used by programs that want to send signals to 5507 the running 5508 name server. Specifying <command>pid-file none</command> disables the 5509 use of a PID file — no file will be written and any 5510 existing one will be removed. Note that <command>none</command> 5511 is a keyword, not a filename, and therefore is not enclosed 5512 in 5513 double quotes. 5514 </para> 5515 </listitem> 5516 </varlistentry> 5517 5518 <varlistentry> 5519 <term><command>recursing-file</command></term> 5520 <listitem> 5521 <para> 5522 The pathname of the file the server dumps 5523 the queries that are currently recursing when instructed 5524 to do so with <command>rndc recursing</command>. 5525 If not specified, the default is <filename>named.recursing</filename>. 5526 </para> 5527 </listitem> 5528 </varlistentry> 5529 5530 <varlistentry> 5531 <term><command>statistics-file</command></term> 5532 <listitem> 5533 <para> 5534 The pathname of the file the server appends statistics 5535 to when instructed to do so using <command>rndc stats</command>. 5536 If not specified, the default is <filename>named.stats</filename> in the 5537 server's current directory. The format of the file is 5538 described 5539 in <xref linkend="statsfile"/>. 5540 </para> 5541 </listitem> 5542 </varlistentry> 5543 5544 <varlistentry> 5545 <term><command>bindkeys-file</command></term> 5546 <listitem> 5547 <para> 5548 The pathname of a file to override the built-in trusted 5549 keys provided by <command>named</command>. 5550 See the discussion of <command>dnssec-lookaside</command> 5551 and <command>dnssec-validation</command> for details. 5552 If not specified, the default is 5553 <filename>/etc/bind.keys</filename>. 5554 </para> 5555 </listitem> 5556 </varlistentry> 5557 5558 <varlistentry> 5559 <term><command>secroots-file</command></term> 5560 <listitem> 5561 <para> 5562 The pathname of the file the server dumps 5563 security roots to when instructed to do so with 5564 <command>rndc secroots</command>. 5565 If not specified, the default is 5566 <filename>named.secroots</filename>. 5567 </para> 5568 </listitem> 5569 </varlistentry> 5570 5571 <varlistentry> 5572 <term><command>session-keyfile</command></term> 5573 <listitem> 5574 <para> 5575 The pathname of the file into which to write a TSIG 5576 session key generated by <command>named</command> for use by 5577 <command>nsupdate -l</command>. If not specified, the 5578 default is <filename>/var/run/named/session.key</filename>. 5579 (See <xref linkend="dynamic_update_policies"/>, and in 5580 particular the discussion of the 5581 <command>update-policy</command> statement's 5582 <userinput>local</userinput> option for more 5583 information about this feature.) 5584 </para> 5585 </listitem> 5586 </varlistentry> 5587 5588 <varlistentry> 5589 <term><command>session-keyname</command></term> 5590 <listitem> 5591 <para> 5592 The key name to use for the TSIG session key. 5593 If not specified, the default is "local-ddns". 5594 </para> 5595 </listitem> 5596 </varlistentry> 5597 5598 <varlistentry> 5599 <term><command>session-keyalg</command></term> 5600 <listitem> 5601 <para> 5602 The algorithm to use for the TSIG session key. 5603 Valid values are hmac-sha1, hmac-sha224, hmac-sha256, 5604 hmac-sha384, hmac-sha512 and hmac-md5. If not 5605 specified, the default is hmac-sha256. 5606 </para> 5607 </listitem> 5608 </varlistentry> 5609 5610 <varlistentry> 5611 <term><command>port</command></term> 5612 <listitem> 5613 <para> 5614 The UDP/TCP port number the server uses for 5615 receiving and sending DNS protocol traffic. 5616 The default is 53. This option is mainly intended for server 5617 testing; 5618 a server using a port other than 53 will not be able to 5619 communicate with 5620 the global DNS. 5621 </para> 5622 </listitem> 5623 </varlistentry> 5624 5625 <varlistentry> 5626 <term><command>random-device</command></term> 5627 <listitem> 5628 <para> 5629 The source of entropy to be used by the server. Entropy is 5630 primarily needed 5631 for DNSSEC operations, such as TKEY transactions and dynamic 5632 update of signed 5633 zones. This options specifies the device (or file) from which 5634 to read 5635 entropy. If this is a file, operations requiring entropy will 5636 fail when the 5637 file has been exhausted. If not specified, the default value 5638 is 5639 <filename>/dev/random</filename> 5640 (or equivalent) when present, and none otherwise. The 5641 <command>random-device</command> option takes 5642 effect during 5643 the initial configuration load at server startup time and 5644 is ignored on subsequent reloads. 5645 </para> 5646 </listitem> 5647 </varlistentry> 5648 5649 <varlistentry> 5650 <term><command>preferred-glue</command></term> 5651 <listitem> 5652 <para> 5653 If specified, the listed type (A or AAAA) will be emitted 5654 before other glue 5655 in the additional section of a query response. 5656 The default is not to prefer any type (NONE). 5657 </para> 5658 </listitem> 5659 </varlistentry> 5660 5661 <varlistentry id="root_delegation_only"> 5662 <term><command>root-delegation-only</command></term> 5663 <listitem> 5664 <para> 5665 Turn on enforcement of delegation-only in TLDs 5666 (top level domains) and root zones with an optional 5667 exclude list. 5668 </para> 5669 <para> 5670 DS queries are expected to be made to and be answered by 5671 delegation only zones. Such queries and responses are 5672 treated as an exception to delegation-only processing 5673 and are not converted to NXDOMAIN responses provided 5674 a CNAME is not discovered at the query name. 5675 </para> 5676 <para> 5677 If a delegation only zone server also serves a child 5678 zone it is not always possible to determine whether 5679 an answer comes from the delegation only zone or the 5680 child zone. SOA NS and DNSKEY records are apex 5681 only records and a matching response that contains 5682 these records or DS is treated as coming from a 5683 child zone. RRSIG records are also examined to see 5684 if they are signed by a child zone or not. The 5685 authority section is also examined to see if there 5686 is evidence that the answer is from the child zone. 5687 Answers that are determined to be from a child zone 5688 are not converted to NXDOMAIN responses. Despite 5689 all these checks there is still a possibility of 5690 false negatives when a child zone is being served. 5691 </para> 5692 <para> 5693 Similarly false positives can arise from empty nodes 5694 (no records at the name) in the delegation only zone 5695 when the query type is not ANY. 5696 </para> 5697 <para> 5698 Note some TLDs are not delegation only (e.g. "DE", "LV", 5699 "US" and "MUSEUM"). This list is not exhaustive. 5700 </para> 5701 5702<programlisting> 5703options { 5704 root-delegation-only exclude { "de"; "lv"; "us"; "museum"; }; 5705}; 5706</programlisting> 5707 5708 </listitem> 5709 </varlistentry> 5710 5711 <varlistentry> 5712 <term><command>disable-algorithms</command></term> 5713 <listitem> 5714 <para> 5715 Disable the specified DNSSEC algorithms at and below the 5716 specified name. 5717 Multiple <command>disable-algorithms</command> 5718 statements are allowed. 5719 Only the most specific will be applied. 5720 </para> 5721 </listitem> 5722 </varlistentry> 5723 5724 <varlistentry> 5725 <term><command>dnssec-lookaside</command></term> 5726 <listitem> 5727 <para> 5728 When set, <command>dnssec-lookaside</command> provides the 5729 validator with an alternate method to validate DNSKEY 5730 records at the top of a zone. When a DNSKEY is at or 5731 below a domain specified by the deepest 5732 <command>dnssec-lookaside</command>, and the normal DNSSEC 5733 validation has left the key untrusted, the trust-anchor 5734 will be appended to the key name and a DLV record will be 5735 looked up to see if it can validate the key. If the DLV 5736 record validates a DNSKEY (similarly to the way a DS 5737 record does) the DNSKEY RRset is deemed to be trusted. 5738 </para> 5739 <para> 5740 If <command>dnssec-lookaside</command> is set to 5741 <userinput>auto</userinput>, then built-in default 5742 values for the DLV domain and trust anchor will be 5743 used, along with a built-in key for validation. 5744 </para> 5745 <para> 5746 If <command>dnssec-lookaside</command> is set to 5747 <userinput>no</userinput>, then dnssec-lookaside 5748 is not used. 5749 </para> 5750 <para> 5751 The default DLV key is stored in the file 5752 <filename>bind.keys</filename>; 5753 <command>named</command> will load that key at 5754 startup if <command>dnssec-lookaside</command> is set to 5755 <constant>auto</constant>. A copy of the file is 5756 installed along with <acronym>BIND</acronym> 9, and is 5757 current as of the release date. If the DLV key expires, a 5758 new copy of <filename>bind.keys</filename> can be downloaded 5759 from <ulink>https://www.isc.org/solutions/dlv</ulink>. 5760 </para> 5761 <para> 5762 (To prevent problems if <filename>bind.keys</filename> is 5763 not found, the current key is also compiled in to 5764 <command>named</command>. Relying on this is not 5765 recommended, however, as it requires <command>named</command> 5766 to be recompiled with a new key when the DLV key expires.) 5767 </para> 5768 <para> 5769 NOTE: <command>named</command> only loads certain specific 5770 keys from <filename>bind.keys</filename>: those for the 5771 DLV zone and for the DNS root zone. The file cannot be 5772 used to store keys for other zones. 5773 </para> 5774 </listitem> 5775 </varlistentry> 5776 5777 <varlistentry> 5778 <term><command>dnssec-must-be-secure</command></term> 5779 <listitem> 5780 <para> 5781 Specify hierarchies which must be or may not be secure 5782 (signed and validated). If <userinput>yes</userinput>, 5783 then <command>named</command> will only accept answers if 5784 they are secure. If <userinput>no</userinput>, then normal 5785 DNSSEC validation applies allowing for insecure answers to 5786 be accepted. The specified domain must be under a 5787 <command>trusted-keys</command> or 5788 <command>managed-keys</command> statement, or 5789 <command>dnssec-lookaside</command> must be active. 5790 </para> 5791 </listitem> 5792 </varlistentry> 5793 5794 <varlistentry> 5795 <term><command>dns64</command></term> 5796 <listitem> 5797 <para> 5798 This directive instructs <command>named</command> to 5799 return mapped IPv4 addresses to AAAA queries when 5800 there are no AAAA records. It is intended to be 5801 used in conjunction with a NAT64. Each 5802 <command>dns64</command> defines one DNS64 prefix. 5803 Multiple DNS64 prefixes can be defined. 5804 </para> 5805 <para> 5806 Compatible IPv6 prefixes have lengths of 32, 40, 48, 56, 5807 64 and 96 as per RFC 6052. 5808 </para> 5809 <para> 5810 Additionally a reverse IP6.ARPA zone will be created for 5811 the prefix to provide a mapping from the IP6.ARPA names 5812 to the corresponding IN-ADDR.ARPA names using synthesized 5813 CNAMEs. <command>dns64-server</command> and 5814 <command>dns64-contact</command> can be used to specify 5815 the name of the server and contact for the zones. These 5816 are settable at the view / options level. These are 5817 not settable on a per-prefix basis. 5818 </para> 5819 <para> 5820 Each <command>dns64</command> supports an optional 5821 <command>clients</command> ACL that determines which 5822 clients are affected by this directive. If not defined, 5823 it defaults to <userinput>any;</userinput>. 5824 </para> 5825 <para> 5826 Each <command>dns64</command> supports an optional 5827 <command>mapped</command> ACL that selects which 5828 IPv4 addresses are to be mapped in the corresponding 5829 A RRset. If not defined it defaults to 5830 <userinput>any;</userinput>. 5831 </para> 5832 <para> 5833 Normally, DNS64 won't apply to a domain name that 5834 owns one or more AAAA records; these records will 5835 simply be returned. The optional 5836 <command>exclude</command> ACL allows specification 5837 of a list of IPv6 addresses that will be ignored 5838 if they appear in a domain name's AAAA records, and 5839 DNS64 will be applied to any A records the domain 5840 name owns. If not defined, <command>exclude</command> 5841 defaults to none. 5842 </para> 5843 <para> 5844 A optional <command>suffix</command> can also 5845 be defined to set the bits trailing the mapped 5846 IPv4 address bits. By default these bits are 5847 set to <userinput>::</userinput>. The bits 5848 matching the prefix and mapped IPv4 address 5849 must be zero. 5850 </para> 5851 <para> 5852 If <command>recursive-only</command> is set to 5853 <command>yes</command> the DNS64 synthesis will 5854 only happen for recursive queries. The default 5855 is <command>no</command>. 5856 </para> 5857 <para> 5858 If <command>break-dnssec</command> is set to 5859 <command>yes</command> the DNS64 synthesis will 5860 happen even if the result, if validated, would 5861 cause a DNSSEC validation failure. If this option 5862 is set to <command>no</command> (the default), the DO 5863 is set on the incoming query, and there are RRSIGs on 5864 the applicable records, then synthesis will not happen. 5865 </para> 5866<programlisting> 5867 acl rfc1918 { 10/8; 192.168/16; 172.16/12; }; 5868 5869 dns64 64:FF9B::/96 { 5870 clients { any; }; 5871 mapped { !rfc1918; any; }; 5872 exclude { 64:FF9B::/96; ::ffff:0000:0000/96; }; 5873 suffix ::; 5874 }; 5875</programlisting> 5876 </listitem> 5877 </varlistentry> 5878 5879 </variablelist> 5880 5881 <sect3 id="boolean_options"> 5882 <title>Boolean Options</title> 5883 5884 <variablelist> 5885 5886 <varlistentry> 5887 <term><command>allow-new-zones</command></term> 5888 <listitem> 5889 <para> 5890 If <userinput>yes</userinput>, then zones can be 5891 added at runtime via <command>rndc addzone</command> 5892 or deleted via <command>rndc delzone</command>. 5893 The default is <userinput>no</userinput>. 5894 </para> 5895 </listitem> 5896 </varlistentry> 5897 5898 <varlistentry> 5899 <term><command>auth-nxdomain</command></term> 5900 <listitem> 5901 <para> 5902 If <userinput>yes</userinput>, then the <command>AA</command> bit 5903 is always set on NXDOMAIN responses, even if the server is 5904 not actually 5905 authoritative. The default is <userinput>no</userinput>; 5906 this is 5907 a change from <acronym>BIND</acronym> 8. If you 5908 are using very old DNS software, you 5909 may need to set it to <userinput>yes</userinput>. 5910 </para> 5911 </listitem> 5912 </varlistentry> 5913 5914 <varlistentry> 5915 <term><command>deallocate-on-exit</command></term> 5916 <listitem> 5917 <para> 5918 This option was used in <acronym>BIND</acronym> 5919 8 to enable checking 5920 for memory leaks on exit. <acronym>BIND</acronym> 9 ignores the option and always performs 5921 the checks. 5922 </para> 5923 </listitem> 5924 </varlistentry> 5925 5926 <varlistentry> 5927 <term><command>memstatistics</command></term> 5928 <listitem> 5929 <para> 5930 Write memory statistics to the file specified by 5931 <command>memstatistics-file</command> at exit. 5932 The default is <userinput>no</userinput> unless 5933 '-m record' is specified on the command line in 5934 which case it is <userinput>yes</userinput>. 5935 </para> 5936 </listitem> 5937 </varlistentry> 5938 5939 <varlistentry> 5940 <term><command>dialup</command></term> 5941 <listitem> 5942 <para> 5943 If <userinput>yes</userinput>, then the 5944 server treats all zones as if they are doing zone transfers 5945 across 5946 a dial-on-demand dialup link, which can be brought up by 5947 traffic 5948 originating from this server. This has different effects 5949 according 5950 to zone type and concentrates the zone maintenance so that 5951 it all 5952 happens in a short interval, once every <command>heartbeat-interval</command> and 5953 hopefully during the one call. It also suppresses some of 5954 the normal 5955 zone maintenance traffic. The default is <userinput>no</userinput>. 5956 </para> 5957 <para> 5958 The <command>dialup</command> option 5959 may also be specified in the <command>view</command> and 5960 <command>zone</command> statements, 5961 in which case it overrides the global <command>dialup</command> 5962 option. 5963 </para> 5964 <para> 5965 If the zone is a master zone, then the server will send out a 5966 NOTIFY 5967 request to all the slaves (default). This should trigger the 5968 zone serial 5969 number check in the slave (providing it supports NOTIFY) 5970 allowing the slave 5971 to verify the zone while the connection is active. 5972 The set of servers to which NOTIFY is sent can be controlled 5973 by 5974 <command>notify</command> and <command>also-notify</command>. 5975 </para> 5976 <para> 5977 If the 5978 zone is a slave or stub zone, then the server will suppress 5979 the regular 5980 "zone up to date" (refresh) queries and only perform them 5981 when the 5982 <command>heartbeat-interval</command> expires in 5983 addition to sending 5984 NOTIFY requests. 5985 </para> 5986 <para> 5987 Finer control can be achieved by using 5988 <userinput>notify</userinput> which only sends NOTIFY 5989 messages, 5990 <userinput>notify-passive</userinput> which sends NOTIFY 5991 messages and 5992 suppresses the normal refresh queries, <userinput>refresh</userinput> 5993 which suppresses normal refresh processing and sends refresh 5994 queries 5995 when the <command>heartbeat-interval</command> 5996 expires, and 5997 <userinput>passive</userinput> which just disables normal 5998 refresh 5999 processing. 6000 </para> 6001 6002 <informaltable colsep="0" rowsep="0"> 6003 <tgroup cols="4" colsep="0" rowsep="0" tgroupstyle="4Level-table"> 6004 <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> 6005 <colspec colname="2" colnum="2" colsep="0" colwidth="1.150in"/> 6006 <colspec colname="3" colnum="3" colsep="0" colwidth="1.150in"/> 6007 <colspec colname="4" colnum="4" colsep="0" colwidth="1.150in"/> 6008 <tbody> 6009 <row rowsep="0"> 6010 <entry colname="1"> 6011 <para> 6012 dialup mode 6013 </para> 6014 </entry> 6015 <entry colname="2"> 6016 <para> 6017 normal refresh 6018 </para> 6019 </entry> 6020 <entry colname="3"> 6021 <para> 6022 heart-beat refresh 6023 </para> 6024 </entry> 6025 <entry colname="4"> 6026 <para> 6027 heart-beat notify 6028 </para> 6029 </entry> 6030 </row> 6031 <row rowsep="0"> 6032 <entry colname="1"> 6033 <para><command>no</command> (default)</para> 6034 </entry> 6035 <entry colname="2"> 6036 <para> 6037 yes 6038 </para> 6039 </entry> 6040 <entry colname="3"> 6041 <para> 6042 no 6043 </para> 6044 </entry> 6045 <entry colname="4"> 6046 <para> 6047 no 6048 </para> 6049 </entry> 6050 </row> 6051 <row rowsep="0"> 6052 <entry colname="1"> 6053 <para><command>yes</command></para> 6054 </entry> 6055 <entry colname="2"> 6056 <para> 6057 no 6058 </para> 6059 </entry> 6060 <entry colname="3"> 6061 <para> 6062 yes 6063 </para> 6064 </entry> 6065 <entry colname="4"> 6066 <para> 6067 yes 6068 </para> 6069 </entry> 6070 </row> 6071 <row rowsep="0"> 6072 <entry colname="1"> 6073 <para><command>notify</command></para> 6074 </entry> 6075 <entry colname="2"> 6076 <para> 6077 yes 6078 </para> 6079 </entry> 6080 <entry colname="3"> 6081 <para> 6082 no 6083 </para> 6084 </entry> 6085 <entry colname="4"> 6086 <para> 6087 yes 6088 </para> 6089 </entry> 6090 </row> 6091 <row rowsep="0"> 6092 <entry colname="1"> 6093 <para><command>refresh</command></para> 6094 </entry> 6095 <entry colname="2"> 6096 <para> 6097 no 6098 </para> 6099 </entry> 6100 <entry colname="3"> 6101 <para> 6102 yes 6103 </para> 6104 </entry> 6105 <entry colname="4"> 6106 <para> 6107 no 6108 </para> 6109 </entry> 6110 </row> 6111 <row rowsep="0"> 6112 <entry colname="1"> 6113 <para><command>passive</command></para> 6114 </entry> 6115 <entry colname="2"> 6116 <para> 6117 no 6118 </para> 6119 </entry> 6120 <entry colname="3"> 6121 <para> 6122 no 6123 </para> 6124 </entry> 6125 <entry colname="4"> 6126 <para> 6127 no 6128 </para> 6129 </entry> 6130 </row> 6131 <row rowsep="0"> 6132 <entry colname="1"> 6133 <para><command>notify-passive</command></para> 6134 </entry> 6135 <entry colname="2"> 6136 <para> 6137 no 6138 </para> 6139 </entry> 6140 <entry colname="3"> 6141 <para> 6142 no 6143 </para> 6144 </entry> 6145 <entry colname="4"> 6146 <para> 6147 yes 6148 </para> 6149 </entry> 6150 </row> 6151 </tbody> 6152 </tgroup> 6153 </informaltable> 6154 6155 <para> 6156 Note that normal NOTIFY processing is not affected by 6157 <command>dialup</command>. 6158 </para> 6159 6160 </listitem> 6161 </varlistentry> 6162 6163 <varlistentry> 6164 <term><command>fake-iquery</command></term> 6165 <listitem> 6166 <para> 6167 In <acronym>BIND</acronym> 8, this option 6168 enabled simulating the obsolete DNS query type 6169 IQUERY. <acronym>BIND</acronym> 9 never does 6170 IQUERY simulation. 6171 </para> 6172 </listitem> 6173 </varlistentry> 6174 6175 <varlistentry> 6176 <term><command>fetch-glue</command></term> 6177 <listitem> 6178 <para> 6179 This option is obsolete. 6180 In BIND 8, <userinput>fetch-glue yes</userinput> 6181 caused the server to attempt to fetch glue resource records 6182 it 6183 didn't have when constructing the additional 6184 data section of a response. This is now considered a bad 6185 idea 6186 and BIND 9 never does it. 6187 </para> 6188 </listitem> 6189 </varlistentry> 6190 6191 <varlistentry> 6192 <term><command>flush-zones-on-shutdown</command></term> 6193 <listitem> 6194 <para> 6195 When the nameserver exits due receiving SIGTERM, 6196 flush or do not flush any pending zone writes. The default 6197 is 6198 <command>flush-zones-on-shutdown</command> <userinput>no</userinput>. 6199 </para> 6200 </listitem> 6201 </varlistentry> 6202 6203 <varlistentry> 6204 <term><command>has-old-clients</command></term> 6205 <listitem> 6206 <para> 6207 This option was incorrectly implemented 6208 in <acronym>BIND</acronym> 8, and is ignored by <acronym>BIND</acronym> 9. 6209 To achieve the intended effect 6210 of 6211 <command>has-old-clients</command> <userinput>yes</userinput>, specify 6212 the two separate options <command>auth-nxdomain</command> <userinput>yes</userinput> 6213 and <command>rfc2308-type1</command> <userinput>no</userinput> instead. 6214 </para> 6215 </listitem> 6216 </varlistentry> 6217 6218 <varlistentry> 6219 <term><command>host-statistics</command></term> 6220 <listitem> 6221 <para> 6222 In BIND 8, this enables keeping of 6223 statistics for every host that the name server interacts 6224 with. 6225 Not implemented in BIND 9. 6226 </para> 6227 </listitem> 6228 </varlistentry> 6229 6230 <varlistentry> 6231 <term><command>maintain-ixfr-base</command></term> 6232 <listitem> 6233 <para> 6234 <emphasis>This option is obsolete</emphasis>. 6235 It was used in <acronym>BIND</acronym> 8 to 6236 determine whether a transaction log was 6237 kept for Incremental Zone Transfer. <acronym>BIND</acronym> 9 maintains a transaction 6238 log whenever possible. If you need to disable outgoing 6239 incremental zone 6240 transfers, use <command>provide-ixfr</command> <userinput>no</userinput>. 6241 </para> 6242 </listitem> 6243 </varlistentry> 6244 6245 <varlistentry> 6246 <term><command>minimal-responses</command></term> 6247 <listitem> 6248 <para> 6249 If <userinput>yes</userinput>, then when generating 6250 responses the server will only add records to the authority 6251 and additional data sections when they are required (e.g. 6252 delegations, negative responses). This may improve the 6253 performance of the server. 6254 The default is <userinput>no</userinput>. 6255 </para> 6256 </listitem> 6257 </varlistentry> 6258 6259 <varlistentry> 6260 <term><command>multiple-cnames</command></term> 6261 <listitem> 6262 <para> 6263 This option was used in <acronym>BIND</acronym> 8 to allow 6264 a domain name to have multiple CNAME records in violation of 6265 the DNS standards. <acronym>BIND</acronym> 9.2 onwards 6266 always strictly enforces the CNAME rules both in master 6267 files and dynamic updates. 6268 </para> 6269 </listitem> 6270 </varlistentry> 6271 6272 <varlistentry> 6273 <term><command>notify</command></term> 6274 <listitem> 6275 <para> 6276 If <userinput>yes</userinput> (the default), 6277 DNS NOTIFY messages are sent when a zone the server is 6278 authoritative for 6279 changes, see <xref linkend="notify"/>. The messages are 6280 sent to the 6281 servers listed in the zone's NS records (except the master 6282 server identified 6283 in the SOA MNAME field), and to any servers listed in the 6284 <command>also-notify</command> option. 6285 </para> 6286 <para> 6287 If <userinput>master-only</userinput>, notifies are only 6288 sent 6289 for master zones. 6290 If <userinput>explicit</userinput>, notifies are sent only 6291 to 6292 servers explicitly listed using <command>also-notify</command>. 6293 If <userinput>no</userinput>, no notifies are sent. 6294 </para> 6295 <para> 6296 The <command>notify</command> option may also be 6297 specified in the <command>zone</command> 6298 statement, 6299 in which case it overrides the <command>options notify</command> statement. 6300 It would only be necessary to turn off this option if it 6301 caused slaves 6302 to crash. 6303 </para> 6304 </listitem> 6305 </varlistentry> 6306 6307 <varlistentry> 6308 <term><command>notify-to-soa</command></term> 6309 <listitem> 6310 <para> 6311 If <userinput>yes</userinput> do not check the nameservers 6312 in the NS RRset against the SOA MNAME. Normally a NOTIFY 6313 message is not sent to the SOA MNAME (SOA ORIGIN) as it is 6314 supposed to contain the name of the ultimate master. 6315 Sometimes, however, a slave is listed as the SOA MNAME in 6316 hidden master configurations and in that case you would 6317 want the ultimate master to still send NOTIFY messages to 6318 all the nameservers listed in the NS RRset. 6319 </para> 6320 </listitem> 6321 </varlistentry> 6322 6323 <varlistentry> 6324 <term><command>recursion</command></term> 6325 <listitem> 6326 <para> 6327 If <userinput>yes</userinput>, and a 6328 DNS query requests recursion, then the server will attempt 6329 to do 6330 all the work required to answer the query. If recursion is 6331 off 6332 and the server does not already know the answer, it will 6333 return a 6334 referral response. The default is 6335 <userinput>yes</userinput>. 6336 Note that setting <command>recursion no</command> does not prevent 6337 clients from getting data from the server's cache; it only 6338 prevents new data from being cached as an effect of client 6339 queries. 6340 Caching may still occur as an effect the server's internal 6341 operation, such as NOTIFY address lookups. 6342 See also <command>fetch-glue</command> above. 6343 </para> 6344 </listitem> 6345 </varlistentry> 6346 6347 <varlistentry> 6348 <term><command>rfc2308-type1</command></term> 6349 <listitem> 6350 <para> 6351 Setting this to <userinput>yes</userinput> will 6352 cause the server to send NS records along with the SOA 6353 record for negative 6354 answers. The default is <userinput>no</userinput>. 6355 </para> 6356 <note> 6357 <simpara> 6358 Not yet implemented in <acronym>BIND</acronym> 6359 9. 6360 </simpara> 6361 </note> 6362 </listitem> 6363 </varlistentry> 6364 6365 <varlistentry> 6366 <term><command>use-id-pool</command></term> 6367 <listitem> 6368 <para> 6369 <emphasis>This option is obsolete</emphasis>. 6370 <acronym>BIND</acronym> 9 always allocates query 6371 IDs from a pool. 6372 </para> 6373 </listitem> 6374 </varlistentry> 6375 6376 <varlistentry> 6377 <term><command>zone-statistics</command></term> 6378 <listitem> 6379 <para> 6380 If <userinput>yes</userinput>, the server will collect 6381 statistical data on all zones (unless specifically turned 6382 off 6383 on a per-zone basis by specifying <command>zone-statistics no</command> 6384 in the <command>zone</command> statement). 6385 The default is <userinput>no</userinput>. 6386 These statistics may be accessed 6387 using <command>rndc stats</command>, which will 6388 dump them to the file listed 6389 in the <command>statistics-file</command>. See 6390 also <xref linkend="statsfile"/>. 6391 </para> 6392 </listitem> 6393 </varlistentry> 6394 6395 <varlistentry> 6396 <term><command>use-ixfr</command></term> 6397 <listitem> 6398 <para> 6399 <emphasis>This option is obsolete</emphasis>. 6400 If you need to disable IXFR to a particular server or 6401 servers, see 6402 the information on the <command>provide-ixfr</command> option 6403 in <xref linkend="server_statement_definition_and_usage"/>. 6404 See also 6405 <xref linkend="incremental_zone_transfers"/>. 6406 </para> 6407 </listitem> 6408 </varlistentry> 6409 6410 <varlistentry> 6411 <term><command>provide-ixfr</command></term> 6412 <listitem> 6413 <para> 6414 See the description of 6415 <command>provide-ixfr</command> in 6416 <xref linkend="server_statement_definition_and_usage"/>. 6417 </para> 6418 </listitem> 6419 </varlistentry> 6420 6421 <varlistentry> 6422 <term><command>request-ixfr</command></term> 6423 <listitem> 6424 <para> 6425 See the description of 6426 <command>request-ixfr</command> in 6427 <xref linkend="server_statement_definition_and_usage"/>. 6428 </para> 6429 </listitem> 6430 </varlistentry> 6431 6432 <varlistentry> 6433 <term><command>treat-cr-as-space</command></term> 6434 <listitem> 6435 <para> 6436 This option was used in <acronym>BIND</acronym> 6437 8 to make 6438 the server treat carriage return ("<command>\r</command>") characters the same way 6439 as a space or tab character, 6440 to facilitate loading of zone files on a UNIX system that 6441 were generated 6442 on an NT or DOS machine. In <acronym>BIND</acronym> 9, both UNIX "<command>\n</command>" 6443 and NT/DOS "<command>\r\n</command>" newlines 6444 are always accepted, 6445 and the option is ignored. 6446 </para> 6447 </listitem> 6448 </varlistentry> 6449 6450 <varlistentry> 6451 <term><command>additional-from-auth</command></term> 6452 <term><command>additional-from-cache</command></term> 6453 <listitem> 6454 6455 <para> 6456 These options control the behavior of an authoritative 6457 server when 6458 answering queries which have additional data, or when 6459 following CNAME 6460 and DNAME chains. 6461 </para> 6462 6463 <para> 6464 When both of these options are set to <userinput>yes</userinput> 6465 (the default) and a 6466 query is being answered from authoritative data (a zone 6467 configured into the server), the additional data section of 6468 the 6469 reply will be filled in using data from other authoritative 6470 zones 6471 and from the cache. In some situations this is undesirable, 6472 such 6473 as when there is concern over the correctness of the cache, 6474 or 6475 in servers where slave zones may be added and modified by 6476 untrusted third parties. Also, avoiding 6477 the search for this additional data will speed up server 6478 operations 6479 at the possible expense of additional queries to resolve 6480 what would 6481 otherwise be provided in the additional section. 6482 </para> 6483 6484 <para> 6485 For example, if a query asks for an MX record for host <literal>foo.example.com</literal>, 6486 and the record found is "<literal>MX 10 mail.example.net</literal>", normally the address 6487 records (A and AAAA) for <literal>mail.example.net</literal> will be provided as well, 6488 if known, even though they are not in the example.com zone. 6489 Setting these options to <command>no</command> 6490 disables this behavior and makes 6491 the server only search for additional data in the zone it 6492 answers from. 6493 </para> 6494 6495 <para> 6496 These options are intended for use in authoritative-only 6497 servers, or in authoritative-only views. Attempts to set 6498 them to <command>no</command> without also 6499 specifying 6500 <command>recursion no</command> will cause the 6501 server to 6502 ignore the options and log a warning message. 6503 </para> 6504 6505 <para> 6506 Specifying <command>additional-from-cache no</command> actually 6507 disables the use of the cache not only for additional data 6508 lookups 6509 but also when looking up the answer. This is usually the 6510 desired 6511 behavior in an authoritative-only server where the 6512 correctness of 6513 the cached data is an issue. 6514 </para> 6515 6516 <para> 6517 When a name server is non-recursively queried for a name 6518 that is not 6519 below the apex of any served zone, it normally answers with 6520 an 6521 "upwards referral" to the root servers or the servers of 6522 some other 6523 known parent of the query name. Since the data in an 6524 upwards referral 6525 comes from the cache, the server will not be able to provide 6526 upwards 6527 referrals when <command>additional-from-cache no</command> 6528 has been specified. Instead, it will respond to such 6529 queries 6530 with REFUSED. This should not cause any problems since 6531 upwards referrals are not required for the resolution 6532 process. 6533 </para> 6534 6535 </listitem> 6536 </varlistentry> 6537 6538 <varlistentry> 6539 <term><command>match-mapped-addresses</command></term> 6540 <listitem> 6541 <para> 6542 If <userinput>yes</userinput>, then an 6543 IPv4-mapped IPv6 address will match any address match 6544 list entries that match the corresponding IPv4 address. 6545 </para> 6546 <para> 6547 This option was introduced to work around a kernel quirk 6548 in some operating systems that causes IPv4 TCP 6549 connections, such as zone transfers, to be accepted on an 6550 IPv6 socket using mapped addresses. This caused address 6551 match lists designed for IPv4 to fail to match. However, 6552 <command>named</command> now solves this problem 6553 internally. The use of this option is discouraged. 6554 </para> 6555 </listitem> 6556 </varlistentry> 6557 6558 <varlistentry> 6559 <term><command>filter-aaaa-on-v4</command></term> 6560 <listitem> 6561 <para> 6562 This option is only available when 6563 <acronym>BIND</acronym> 9 is compiled with the 6564 <userinput>--enable-filter-aaaa</userinput> option on the 6565 "configure" command line. It is intended to help the 6566 transition from IPv4 to IPv6 by not giving IPv6 addresses 6567 to DNS clients unless they have connections to the IPv6 6568 Internet. This is not recommended unless absolutely 6569 necessary. The default is <userinput>no</userinput>. 6570 The <command>filter-aaaa-on-v4</command> option 6571 may also be specified in <command>view</command> statements 6572 to override the global <command>filter-aaaa-on-v4</command> 6573 option. 6574 </para> 6575 <para> 6576 If <userinput>yes</userinput>, 6577 the DNS client is at an IPv4 address, in <command>filter-aaaa</command>, 6578 and if the response does not include DNSSEC signatures, 6579 then all AAAA records are deleted from the response. 6580 This filtering applies to all responses and not only 6581 authoritative responses. 6582 </para> 6583 <para> 6584 If <userinput>break-dnssec</userinput>, 6585 then AAAA records are deleted even when dnssec is enabled. 6586 As suggested by the name, this makes the response not verify, 6587 because the DNSSEC protocol is designed detect deletions. 6588 </para> 6589 <para> 6590 This mechanism can erroneously cause other servers to 6591 not give AAAA records to their clients. 6592 A recursing server with both IPv6 and IPv4 network connections 6593 that queries an authoritative server using this mechanism 6594 via IPv4 will be denied AAAA records even if its client is 6595 using IPv6. 6596 </para> 6597 <para> 6598 This mechanism is applied to authoritative as well as 6599 non-authoritative records. 6600 A client using IPv4 that is not allowed recursion can 6601 erroneously be given AAAA records because the server is not 6602 allowed to check for A records. 6603 </para> 6604 <para> 6605 Some AAAA records are given to IPv4 clients in glue records. 6606 IPv4 clients that are servers can then erroneously 6607 answer requests for AAAA records received via IPv4. 6608 </para> 6609 </listitem> 6610 </varlistentry> 6611 6612 <varlistentry> 6613 <term><command>ixfr-from-differences</command></term> 6614 <listitem> 6615 <para> 6616 When <userinput>yes</userinput> and the server loads a new version of a master 6617 zone from its zone file or receives a new version of a slave 6618 file by a non-incremental zone transfer, it will compare 6619 the new version to the previous one and calculate a set 6620 of differences. The differences are then logged in the 6621 zone's journal file such that the changes can be transmitted 6622 to downstream slaves as an incremental zone transfer. 6623 </para> 6624 <para> 6625 By allowing incremental zone transfers to be used for 6626 non-dynamic zones, this option saves bandwidth at the 6627 expense of increased CPU and memory consumption at the 6628 master. 6629 In particular, if the new version of a zone is completely 6630 different from the previous one, the set of differences 6631 will be of a size comparable to the combined size of the 6632 old and new zone version, and the server will need to 6633 temporarily allocate memory to hold this complete 6634 difference set. 6635 </para> 6636 <para><command>ixfr-from-differences</command> 6637 also accepts <command>master</command> and 6638 <command>slave</command> at the view and options 6639 levels which causes 6640 <command>ixfr-from-differences</command> to be enabled for 6641 all <command>master</command> or 6642 <command>slave</command> zones respectively. 6643 It is off by default. 6644 </para> 6645 </listitem> 6646 </varlistentry> 6647 6648 <varlistentry> 6649 <term><command>multi-master</command></term> 6650 <listitem> 6651 <para> 6652 This should be set when you have multiple masters for a zone 6653 and the 6654 addresses refer to different machines. If <userinput>yes</userinput>, <command>named</command> will 6655 not log 6656 when the serial number on the master is less than what <command>named</command> 6657 currently 6658 has. The default is <userinput>no</userinput>. 6659 </para> 6660 </listitem> 6661 </varlistentry> 6662 6663 <varlistentry> 6664 <term><command>dnssec-enable</command></term> 6665 <listitem> 6666 <para> 6667 Enable DNSSEC support in <command>named</command>. Unless set to <userinput>yes</userinput>, 6668 <command>named</command> behaves as if it does not support DNSSEC. 6669 The default is <userinput>yes</userinput>. 6670 </para> 6671 </listitem> 6672 </varlistentry> 6673 6674 <varlistentry> 6675 <term><command>dnssec-validation</command></term> 6676 <listitem> 6677 <para> 6678 Enable DNSSEC validation in <command>named</command>. 6679 Note <command>dnssec-enable</command> also needs to be 6680 set to <userinput>yes</userinput> to be effective. 6681 If set to <userinput>no</userinput>, DNSSEC validation 6682 is disabled. If set to <userinput>auto</userinput>, 6683 DNSSEC validation is enabled, and a default 6684 trust-anchor for the DNS root zone is used. If set to 6685 <userinput>yes</userinput>, DNSSEC validation is enabled, 6686 but a trust anchor must be manually configured using 6687 a <command>trusted-keys</command> or 6688 <command>managed-keys</command> statement. The default 6689 is <userinput>yes</userinput>. 6690 </para> 6691 </listitem> 6692 </varlistentry> 6693 6694 <varlistentry> 6695 <term><command>dnssec-accept-expired</command></term> 6696 <listitem> 6697 <para> 6698 Accept expired signatures when verifying DNSSEC signatures. 6699 The default is <userinput>no</userinput>. 6700 Setting this option to <userinput>yes</userinput> 6701 leaves <command>named</command> vulnerable to 6702 replay attacks. 6703 </para> 6704 </listitem> 6705 </varlistentry> 6706 6707 <varlistentry> 6708 <term><command>querylog</command></term> 6709 <listitem> 6710 <para> 6711 Specify whether query logging should be started when <command>named</command> 6712 starts. 6713 If <command>querylog</command> is not specified, 6714 then the query logging 6715 is determined by the presence of the logging category <command>queries</command>. 6716 </para> 6717 </listitem> 6718 </varlistentry> 6719 6720 <varlistentry> 6721 <term><command>check-names</command></term> 6722 <listitem> 6723 <para> 6724 This option is used to restrict the character set and syntax 6725 of 6726 certain domain names in master files and/or DNS responses 6727 received 6728 from the network. The default varies according to usage 6729 area. For 6730 <command>master</command> zones the default is <command>fail</command>. 6731 For <command>slave</command> zones the default 6732 is <command>warn</command>. 6733 For answers received from the network (<command>response</command>) 6734 the default is <command>ignore</command>. 6735 </para> 6736 <para> 6737 The rules for legal hostnames and mail domains are derived 6738 from RFC 952 and RFC 821 as modified by RFC 1123. 6739 </para> 6740 <para><command>check-names</command> 6741 applies to the owner names of A, AAAA and MX records. 6742 It also applies to the domain names in the RDATA of NS, SOA, 6743 MX, and SRV records. 6744 It also applies to the RDATA of PTR records where the owner 6745 name indicated that it is a reverse lookup of a hostname 6746 (the owner name ends in IN-ADDR.ARPA, IP6.ARPA, or IP6.INT). 6747 </para> 6748 </listitem> 6749 </varlistentry> 6750 6751 <varlistentry> 6752 <term><command>check-dup-records</command></term> 6753 <listitem> 6754 <para> 6755 Check master zones for records that are treated as different 6756 by DNSSEC but are semantically equal in plain DNS. The 6757 default is to <command>warn</command>. Other possible 6758 values are <command>fail</command> and 6759 <command>ignore</command>. 6760 </para> 6761 </listitem> 6762 </varlistentry> 6763 6764 <varlistentry> 6765 <term><command>check-mx</command></term> 6766 <listitem> 6767 <para> 6768 Check whether the MX record appears to refer to a IP address. 6769 The default is to <command>warn</command>. Other possible 6770 values are <command>fail</command> and 6771 <command>ignore</command>. 6772 </para> 6773 </listitem> 6774 </varlistentry> 6775 6776 <varlistentry> 6777 <term><command>check-wildcard</command></term> 6778 <listitem> 6779 <para> 6780 This option is used to check for non-terminal wildcards. 6781 The use of non-terminal wildcards is almost always as a 6782 result of a failure 6783 to understand the wildcard matching algorithm (RFC 1034). 6784 This option 6785 affects master zones. The default (<command>yes</command>) is to check 6786 for non-terminal wildcards and issue a warning. 6787 </para> 6788 </listitem> 6789 </varlistentry> 6790 6791 <varlistentry> 6792 <term><command>check-integrity</command></term> 6793 <listitem> 6794 <para> 6795 Perform post load zone integrity checks on master 6796 zones. This checks that MX and SRV records refer 6797 to address (A or AAAA) records and that glue 6798 address records exist for delegated zones. For 6799 MX and SRV records only in-zone hostnames are 6800 checked (for out-of-zone hostnames use 6801 <command>named-checkzone</command>). 6802 For NS records only names below top of zone are 6803 checked (for out-of-zone names and glue consistency 6804 checks use <command>named-checkzone</command>). 6805 The default is <command>yes</command>. 6806 </para> 6807 </listitem> 6808 </varlistentry> 6809 6810 <varlistentry> 6811 <term><command>check-mx-cname</command></term> 6812 <listitem> 6813 <para> 6814 If <command>check-integrity</command> is set then 6815 fail, warn or ignore MX records that refer 6816 to CNAMES. The default is to <command>warn</command>. 6817 </para> 6818 </listitem> 6819 </varlistentry> 6820 6821 <varlistentry> 6822 <term><command>check-srv-cname</command></term> 6823 <listitem> 6824 <para> 6825 If <command>check-integrity</command> is set then 6826 fail, warn or ignore SRV records that refer 6827 to CNAMES. The default is to <command>warn</command>. 6828 </para> 6829 </listitem> 6830 </varlistentry> 6831 6832 <varlistentry> 6833 <term><command>check-sibling</command></term> 6834 <listitem> 6835 <para> 6836 When performing integrity checks, also check that 6837 sibling glue exists. The default is <command>yes</command>. 6838 </para> 6839 </listitem> 6840 </varlistentry> 6841 6842 <varlistentry> 6843 <term><command>zero-no-soa-ttl</command></term> 6844 <listitem> 6845 <para> 6846 When returning authoritative negative responses to 6847 SOA queries set the TTL of the SOA record returned in 6848 the authority section to zero. 6849 The default is <command>yes</command>. 6850 </para> 6851 </listitem> 6852 </varlistentry> 6853 6854 <varlistentry> 6855 <term><command>zero-no-soa-ttl-cache</command></term> 6856 <listitem> 6857 <para> 6858 When caching a negative response to a SOA query 6859 set the TTL to zero. 6860 The default is <command>no</command>. 6861 </para> 6862 </listitem> 6863 </varlistentry> 6864 6865 <varlistentry> 6866 <term><command>update-check-ksk</command></term> 6867 <listitem> 6868 <para> 6869 When set to the default value of <literal>yes</literal>, 6870 check the KSK bit in each key to determine how the key 6871 should be used when generating RRSIGs for a secure zone. 6872 </para> 6873 <para> 6874 Ordinarily, zone-signing keys (that is, keys without the 6875 KSK bit set) are used to sign the entire zone, while 6876 key-signing keys (keys with the KSK bit set) are only 6877 used to sign the DNSKEY RRset at the zone apex. 6878 However, if this option is set to <literal>no</literal>, 6879 then the KSK bit is ignored; KSKs are treated as if they 6880 were ZSKs and are used to sign the entire zone. This is 6881 similar to the <command>dnssec-signzone -z</command> 6882 command line option. 6883 </para> 6884 <para> 6885 When this option is set to <literal>yes</literal>, there 6886 must be at least two active keys for every algorithm 6887 represented in the DNSKEY RRset: at least one KSK and one 6888 ZSK per algorithm. If there is any algorithm for which 6889 this requirement is not met, this option will be ignored 6890 for that algorithm. 6891 </para> 6892 </listitem> 6893 </varlistentry> 6894 6895 <varlistentry> 6896 <term><command>dnssec-dnskey-kskonly</command></term> 6897 <listitem> 6898 <para> 6899 When this option and <command>update-check-ksk</command> 6900 are both set to <literal>yes</literal>, only key-signing 6901 keys (that is, keys with the KSK bit set) will be used 6902 to sign the DNSKEY RRset at the zone apex. Zone-signing 6903 keys (keys without the KSK bit set) will be used to sign 6904 the remainder of the zone, but not the DNSKEY RRset. 6905 This is similar to the 6906 <command>dnssec-signzone -x</command> command line option. 6907 </para> 6908 <para> 6909 The default is <command>no</command>. If 6910 <command>update-check-ksk</command> is set to 6911 <literal>no</literal>, this option is ignored. 6912 </para> 6913 </listitem> 6914 </varlistentry> 6915 6916 <varlistentry> 6917 <term><command>try-tcp-refresh</command></term> 6918 <listitem> 6919 <para> 6920 Try to refresh the zone using TCP if UDP queries fail. 6921 For BIND 8 compatibility, the default is 6922 <command>yes</command>. 6923 </para> 6924 </listitem> 6925 </varlistentry> 6926 6927 <varlistentry> 6928 <term><command>dnssec-secure-to-insecure</command></term> 6929 <listitem> 6930 <para> 6931 Allow a dynamic zone to transition from secure to 6932 insecure (i.e., signed to unsigned) by deleting all 6933 of the DNSKEY records. The default is <command>no</command>. 6934 If set to <command>yes</command>, and if the DNSKEY RRset 6935 at the zone apex is deleted, all RRSIG and NSEC records 6936 will be removed from the zone as well. 6937 </para> 6938 <para> 6939 If the zone uses NSEC3, then it is also necessary to 6940 delete the NSEC3PARAM RRset from the zone apex; this will 6941 cause the removal of all corresponding NSEC3 records. 6942 (It is expected that this requirement will be eliminated 6943 in a future release.) 6944 </para> 6945 <para> 6946 Note that if a zone has been configured with 6947 <command>auto-dnssec maintain</command> and the 6948 private keys remain accessible in the key repository, 6949 then the zone will be automatically signed again the 6950 next time <command>named</command> is started. 6951 </para> 6952 </listitem> 6953 </varlistentry> 6954 6955 </variablelist> 6956 6957 </sect3> 6958 6959 <sect3> 6960 <title>Forwarding</title> 6961 <para> 6962 The forwarding facility can be used to create a large site-wide 6963 cache on a few servers, reducing traffic over links to external 6964 name servers. It can also be used to allow queries by servers that 6965 do not have direct access to the Internet, but wish to look up 6966 exterior 6967 names anyway. Forwarding occurs only on those queries for which 6968 the server is not authoritative and does not have the answer in 6969 its cache. 6970 </para> 6971 6972 <variablelist> 6973 <varlistentry> 6974 <term><command>forward</command></term> 6975 <listitem> 6976 <para> 6977 This option is only meaningful if the 6978 forwarders list is not empty. A value of <varname>first</varname>, 6979 the default, causes the server to query the forwarders 6980 first — and 6981 if that doesn't answer the question, the server will then 6982 look for 6983 the answer itself. If <varname>only</varname> is 6984 specified, the 6985 server will only query the forwarders. 6986 </para> 6987 </listitem> 6988 </varlistentry> 6989 6990 <varlistentry> 6991 <term><command>forwarders</command></term> 6992 <listitem> 6993 <para> 6994 Specifies the IP addresses to be used 6995 for forwarding. The default is the empty list (no 6996 forwarding). 6997 </para> 6998 </listitem> 6999 </varlistentry> 7000 7001 </variablelist> 7002 7003 <para> 7004 Forwarding can also be configured on a per-domain basis, allowing 7005 for the global forwarding options to be overridden in a variety 7006 of ways. You can set particular domains to use different 7007 forwarders, 7008 or have a different <command>forward only/first</command> behavior, 7009 or not forward at all, see <xref linkend="zone_statement_grammar"/>. 7010 </para> 7011 </sect3> 7012 7013 <sect3> 7014 <title>Dual-stack Servers</title> 7015 <para> 7016 Dual-stack servers are used as servers of last resort to work 7017 around 7018 problems in reachability due the lack of support for either IPv4 7019 or IPv6 7020 on the host machine. 7021 </para> 7022 7023 <variablelist> 7024 <varlistentry> 7025 <term><command>dual-stack-servers</command></term> 7026 <listitem> 7027 <para> 7028 Specifies host names or addresses of machines with access to 7029 both IPv4 and IPv6 transports. If a hostname is used, the 7030 server must be able 7031 to resolve the name using only the transport it has. If the 7032 machine is dual 7033 stacked, then the <command>dual-stack-servers</command> have no effect unless 7034 access to a transport has been disabled on the command line 7035 (e.g. <command>named -4</command>). 7036 </para> 7037 </listitem> 7038 </varlistentry> 7039 </variablelist> 7040 </sect3> 7041 7042 <sect3 id="access_control"> 7043 <title>Access Control</title> 7044 7045 <para> 7046 Access to the server can be restricted based on the IP address 7047 of the requesting system. See <xref linkend="address_match_lists"/> for 7048 details on how to specify IP address lists. 7049 </para> 7050 7051 <variablelist> 7052 7053 <varlistentry> 7054 <term><command>allow-notify</command></term> 7055 <listitem> 7056 <para> 7057 Specifies which hosts are allowed to 7058 notify this server, a slave, of zone changes in addition 7059 to the zone masters. 7060 <command>allow-notify</command> may also be 7061 specified in the 7062 <command>zone</command> statement, in which case 7063 it overrides the 7064 <command>options allow-notify</command> 7065 statement. It is only meaningful 7066 for a slave zone. If not specified, the default is to 7067 process notify messages 7068 only from a zone's master. 7069 </para> 7070 </listitem> 7071 </varlistentry> 7072 7073 <varlistentry> 7074 <term><command>allow-query</command></term> 7075 <listitem> 7076 <para> 7077 Specifies which hosts are allowed to ask ordinary 7078 DNS questions. <command>allow-query</command> may 7079 also be specified in the <command>zone</command> 7080 statement, in which case it overrides the 7081 <command>options allow-query</command> statement. 7082 If not specified, the default is to allow queries 7083 from all hosts. 7084 </para> 7085 <note> 7086 <para> 7087 <command>allow-query-cache</command> is now 7088 used to specify access to the cache. 7089 </para> 7090 </note> 7091 </listitem> 7092 </varlistentry> 7093 7094 <varlistentry> 7095 <term><command>allow-query-on</command></term> 7096 <listitem> 7097 <para> 7098 Specifies which local addresses can accept ordinary 7099 DNS questions. This makes it possible, for instance, 7100 to allow queries on internal-facing interfaces but 7101 disallow them on external-facing ones, without 7102 necessarily knowing the internal network's addresses. 7103 </para> 7104 <para> 7105 <command>allow-query-on</command> may 7106 also be specified in the <command>zone</command> 7107 statement, in which case it overrides the 7108 <command>options allow-query-on</command> statement. 7109 </para> 7110 <para> 7111 If not specified, the default is to allow queries 7112 on all addresses. 7113 </para> 7114 <note> 7115 <para> 7116 <command>allow-query-cache</command> is 7117 used to specify access to the cache. 7118 </para> 7119 </note> 7120 </listitem> 7121 </varlistentry> 7122 7123 <varlistentry> 7124 <term><command>allow-query-cache</command></term> 7125 <listitem> 7126 <para> 7127 Specifies which hosts are allowed to get answers 7128 from the cache. If <command>allow-query-cache</command> 7129 is not set then <command>allow-recursion</command> 7130 is used if set, otherwise <command>allow-query</command> 7131 is used if set unless <command>recursion no;</command> is 7132 set in which case <command>none;</command> is used, 7133 otherwise the default (<command>localnets;</command> 7134 <command>localhost;</command>) is used. 7135 </para> 7136 </listitem> 7137 </varlistentry> 7138 7139 <varlistentry> 7140 <term><command>allow-query-cache-on</command></term> 7141 <listitem> 7142 <para> 7143 Specifies which local addresses can give answers 7144 from the cache. If not specified, the default is 7145 to allow cache queries on any address, 7146 <command>localnets</command> and 7147 <command>localhost</command>. 7148 </para> 7149 </listitem> 7150 </varlistentry> 7151 7152 <varlistentry> 7153 <term><command>allow-recursion</command></term> 7154 <listitem> 7155 <para> 7156 Specifies which hosts are allowed to make recursive 7157 queries through this server. If 7158 <command>allow-recursion</command> is not set 7159 then <command>allow-query-cache</command> is 7160 used if set, otherwise <command>allow-query</command> 7161 is used if set, otherwise the default 7162 (<command>localnets;</command> 7163 <command>localhost;</command>) is used. 7164 </para> 7165 </listitem> 7166 </varlistentry> 7167 7168 <varlistentry> 7169 <term><command>allow-recursion-on</command></term> 7170 <listitem> 7171 <para> 7172 Specifies which local addresses can accept recursive 7173 queries. If not specified, the default is to allow 7174 recursive queries on all addresses. 7175 </para> 7176 </listitem> 7177 </varlistentry> 7178 7179 <varlistentry> 7180 <term><command>allow-update</command></term> 7181 <listitem> 7182 <para> 7183 Specifies which hosts are allowed to 7184 submit Dynamic DNS updates for master zones. The default is 7185 to deny 7186 updates from all hosts. Note that allowing updates based 7187 on the requestor's IP address is insecure; see 7188 <xref linkend="dynamic_update_security"/> for details. 7189 </para> 7190 </listitem> 7191 </varlistentry> 7192 7193 <varlistentry> 7194 <term><command>allow-update-forwarding</command></term> 7195 <listitem> 7196 <para> 7197 Specifies which hosts are allowed to 7198 submit Dynamic DNS updates to slave zones to be forwarded to 7199 the 7200 master. The default is <userinput>{ none; }</userinput>, 7201 which 7202 means that no update forwarding will be performed. To 7203 enable 7204 update forwarding, specify 7205 <userinput>allow-update-forwarding { any; };</userinput>. 7206 Specifying values other than <userinput>{ none; }</userinput> or 7207 <userinput>{ any; }</userinput> is usually 7208 counterproductive, since 7209 the responsibility for update access control should rest 7210 with the 7211 master server, not the slaves. 7212 </para> 7213 <para> 7214 Note that enabling the update forwarding feature on a slave 7215 server 7216 may expose master servers relying on insecure IP address 7217 based 7218 access control to attacks; see <xref linkend="dynamic_update_security"/> 7219 for more details. 7220 </para> 7221 </listitem> 7222 </varlistentry> 7223 7224 <varlistentry> 7225 <term><command>allow-v6-synthesis</command></term> 7226 <listitem> 7227 <para> 7228 This option was introduced for the smooth transition from 7229 AAAA 7230 to A6 and from "nibble labels" to binary labels. 7231 However, since both A6 and binary labels were then 7232 deprecated, 7233 this option was also deprecated. 7234 It is now ignored with some warning messages. 7235 </para> 7236 </listitem> 7237 </varlistentry> 7238 7239 <varlistentry> 7240 <term><command>allow-transfer</command></term> 7241 <listitem> 7242 <para> 7243 Specifies which hosts are allowed to 7244 receive zone transfers from the server. <command>allow-transfer</command> may 7245 also be specified in the <command>zone</command> 7246 statement, in which 7247 case it overrides the <command>options allow-transfer</command> statement. 7248 If not specified, the default is to allow transfers to all 7249 hosts. 7250 </para> 7251 </listitem> 7252 </varlistentry> 7253 7254 <varlistentry> 7255 <term><command>blackhole</command></term> 7256 <listitem> 7257 <para> 7258 Specifies a list of addresses that the 7259 server will not accept queries from or use to resolve a 7260 query. Queries 7261 from these addresses will not be responded to. The default 7262 is <userinput>none</userinput>. 7263 </para> 7264 </listitem> 7265 </varlistentry> 7266 7267 <varlistentry> 7268 <term><command>filter-aaaa</command></term> 7269 <listitem> 7270 <para> 7271 Specifies a list of addresses to which 7272 <command>filter-aaaa-on-v4</command> 7273 is applies. The default is <userinput>any</userinput>. 7274 </para> 7275 </listitem> 7276 </varlistentry> 7277 7278 <varlistentry> 7279 <term><command>resolver-query-timeout</command></term> 7280 <listitem> 7281 <para> 7282 The amount of time the resolver will spend attempting 7283 to resolve a recursive query before failing. The 7284 default is <literal>10</literal> and the maximum is 7285 <literal>30</literal>. Setting it to <literal>0</literal> 7286 will result in the default being used. 7287 </para> 7288 </listitem> 7289 </varlistentry> 7290 </variablelist> 7291 7292 </sect3> 7293 7294 <sect3> 7295 <title>Interfaces</title> 7296 <para> 7297 The interfaces and ports that the server will answer queries 7298 from may be specified using the <command>listen-on</command> option. <command>listen-on</command> takes 7299 an optional port and an <varname>address_match_list</varname>. 7300 The server will listen on all interfaces allowed by the address 7301 match list. If a port is not specified, port 53 will be used. 7302 </para> 7303 <para> 7304 Multiple <command>listen-on</command> statements are 7305 allowed. 7306 For example, 7307 </para> 7308 7309<programlisting>listen-on { 5.6.7.8; }; 7310listen-on port 1234 { !1.2.3.4; 1.2/16; }; 7311</programlisting> 7312 7313 <para> 7314 will enable the name server on port 53 for the IP address 7315 5.6.7.8, and on port 1234 of an address on the machine in net 7316 1.2 that is not 1.2.3.4. 7317 </para> 7318 7319 <para> 7320 If no <command>listen-on</command> is specified, the 7321 server will listen on port 53 on all IPv4 interfaces. 7322 </para> 7323 7324 <para> 7325 The <command>listen-on-v6</command> option is used to 7326 specify the interfaces and the ports on which the server will 7327 listen 7328 for incoming queries sent using IPv6. 7329 </para> 7330 7331 <para> 7332 When <programlisting>{ any; }</programlisting> is 7333 specified 7334 as the <varname>address_match_list</varname> for the 7335 <command>listen-on-v6</command> option, 7336 the server does not bind a separate socket to each IPv6 interface 7337 address as it does for IPv4 if the operating system has enough API 7338 support for IPv6 (specifically if it conforms to RFC 3493 and RFC 7339 3542). 7340 Instead, it listens on the IPv6 wildcard address. 7341 If the system only has incomplete API support for IPv6, however, 7342 the behavior is the same as that for IPv4. 7343 </para> 7344 7345 <para> 7346 A list of particular IPv6 addresses can also be specified, in 7347 which case 7348 the server listens on a separate socket for each specified 7349 address, 7350 regardless of whether the desired API is supported by the system. 7351 </para> 7352 7353 <para> 7354 Multiple <command>listen-on-v6</command> options can 7355 be used. 7356 For example, 7357 </para> 7358 7359<programlisting>listen-on-v6 { any; }; 7360listen-on-v6 port 1234 { !2001:db8::/32; any; }; 7361</programlisting> 7362 7363 <para> 7364 will enable the name server on port 53 for any IPv6 addresses 7365 (with a single wildcard socket), 7366 and on port 1234 of IPv6 addresses that is not in the prefix 7367 2001:db8::/32 (with separate sockets for each matched address.) 7368 </para> 7369 7370 <para> 7371 To make the server not listen on any IPv6 address, use 7372 </para> 7373 7374<programlisting>listen-on-v6 { none; }; 7375</programlisting> 7376 7377 <para> 7378 If no <command>listen-on-v6</command> option is 7379 specified, the server will not listen on any IPv6 address 7380 unless <command>-6</command> is specified when <command>named</command> is 7381 invoked. If <command>-6</command> is specified then 7382 <command>named</command> will listen on port 53 on all IPv6 interfaces by default. 7383 </para> 7384 </sect3> 7385 7386 <sect3 id="query_address"> 7387 <title>Query Address</title> 7388 <para> 7389 If the server doesn't know the answer to a question, it will 7390 query other name servers. <command>query-source</command> specifies 7391 the address and port used for such queries. For queries sent over 7392 IPv6, there is a separate <command>query-source-v6</command> option. 7393 If <command>address</command> is <command>*</command> (asterisk) or is omitted, 7394 a wildcard IP address (<command>INADDR_ANY</command>) 7395 will be used. 7396 </para> 7397 7398 <para> 7399 If <command>port</command> is <command>*</command> or is omitted, 7400 a random port number from a pre-configured 7401 range is picked up and will be used for each query. 7402 The port range(s) is that specified in 7403 the <command>use-v4-udp-ports</command> (for IPv4) 7404 and <command>use-v6-udp-ports</command> (for IPv6) 7405 options, excluding the ranges specified in 7406 the <command>avoid-v4-udp-ports</command> 7407 and <command>avoid-v6-udp-ports</command> options, respectively. 7408 </para> 7409 7410 <para> 7411 The defaults of the <command>query-source</command> and 7412 <command>query-source-v6</command> options 7413 are: 7414 </para> 7415 7416<programlisting>query-source address * port *; 7417query-source-v6 address * port *; 7418</programlisting> 7419 7420 <para> 7421 If <command>use-v4-udp-ports</command> or 7422 <command>use-v6-udp-ports</command> is unspecified, 7423 <command>named</command> will check if the operating 7424 system provides a programming interface to retrieve the 7425 system's default range for ephemeral ports. 7426 If such an interface is available, 7427 <command>named</command> will use the corresponding system 7428 default range; otherwise, it will use its own defaults: 7429 </para> 7430 7431<programlisting>use-v4-udp-ports { range 1024 65535; }; 7432use-v6-udp-ports { range 1024 65535; }; 7433</programlisting> 7434 7435 <para> 7436 Note: make sure the ranges be sufficiently large for 7437 security. A desirable size depends on various parameters, 7438 but we generally recommend it contain at least 16384 ports 7439 (14 bits of entropy). 7440 Note also that the system's default range when used may be 7441 too small for this purpose, and that the range may even be 7442 changed while <command>named</command> is running; the new 7443 range will automatically be applied when <command>named</command> 7444 is reloaded. 7445 It is encouraged to 7446 configure <command>use-v4-udp-ports</command> and 7447 <command>use-v6-udp-ports</command> explicitly so that the 7448 ranges are sufficiently large and are reasonably 7449 independent from the ranges used by other applications. 7450 </para> 7451 7452 <para> 7453 Note: the operational configuration 7454 where <command>named</command> runs may prohibit the use 7455 of some ports. For example, UNIX systems will not allow 7456 <command>named</command> running without a root privilege 7457 to use ports less than 1024. 7458 If such ports are included in the specified (or detected) 7459 set of query ports, the corresponding query attempts will 7460 fail, resulting in resolution failures or delay. 7461 It is therefore important to configure the set of ports 7462 that can be safely used in the expected operational environment. 7463 </para> 7464 7465 <para> 7466 The defaults of the <command>avoid-v4-udp-ports</command> and 7467 <command>avoid-v6-udp-ports</command> options 7468 are: 7469 </para> 7470 7471<programlisting>avoid-v4-udp-ports {}; 7472avoid-v6-udp-ports {}; 7473</programlisting> 7474 7475 <para> 7476 Note: BIND 9.5.0 introduced 7477 the <command>use-queryport-pool</command> 7478 option to support a pool of such random ports, but this 7479 option is now obsolete because reusing the same ports in 7480 the pool may not be sufficiently secure. 7481 For the same reason, it is generally strongly discouraged to 7482 specify a particular port for the 7483 <command>query-source</command> or 7484 <command>query-source-v6</command> options; 7485 it implicitly disables the use of randomized port numbers. 7486 </para> 7487 7488 <variablelist> 7489 <varlistentry> 7490 <term><command>use-queryport-pool</command></term> 7491 <listitem> 7492 <para> 7493 This option is obsolete. 7494 </para> 7495 </listitem> 7496 </varlistentry> 7497 7498 <varlistentry> 7499 <term><command>queryport-pool-ports</command></term> 7500 <listitem> 7501 <para> 7502 This option is obsolete. 7503 </para> 7504 </listitem> 7505 </varlistentry> 7506 7507 <varlistentry> 7508 <term><command>queryport-pool-updateinterval</command></term> 7509 <listitem> 7510 <para> 7511 This option is obsolete. 7512 </para> 7513 </listitem> 7514 </varlistentry> 7515 7516 </variablelist> 7517 <note> 7518 <para> 7519 The address specified in the <command>query-source</command> option 7520 is used for both UDP and TCP queries, but the port applies only 7521 to UDP queries. TCP queries always use a random 7522 unprivileged port. 7523 </para> 7524 </note> 7525 <note> 7526 <para> 7527 Solaris 2.5.1 and earlier does not support setting the source 7528 address for TCP sockets. 7529 </para> 7530 </note> 7531 <note> 7532 <para> 7533 See also <command>transfer-source</command> and 7534 <command>notify-source</command>. 7535 </para> 7536 </note> 7537 </sect3> 7538 7539 <sect3 id="zone_transfers"> 7540 <title>Zone Transfers</title> 7541 <para> 7542 <acronym>BIND</acronym> has mechanisms in place to 7543 facilitate zone transfers 7544 and set limits on the amount of load that transfers place on the 7545 system. The following options apply to zone transfers. 7546 </para> 7547 7548 <variablelist> 7549 7550 <varlistentry> 7551 <term><command>also-notify</command></term> 7552 <listitem> 7553 <para> 7554 Defines a global list of IP addresses of name servers 7555 that are also sent NOTIFY messages whenever a fresh copy of 7556 the 7557 zone is loaded, in addition to the servers listed in the 7558 zone's NS records. 7559 This helps to ensure that copies of the zones will 7560 quickly converge on stealth servers. 7561 Optionally, a port may be specified with each 7562 <command>also-notify</command> address to send 7563 the notify messages to a port other than the 7564 default of 53. 7565 If an <command>also-notify</command> list 7566 is given in a <command>zone</command> statement, 7567 it will override 7568 the <command>options also-notify</command> 7569 statement. When a <command>zone notify</command> 7570 statement 7571 is set to <command>no</command>, the IP 7572 addresses in the global <command>also-notify</command> list will 7573 not be sent NOTIFY messages for that zone. The default is 7574 the empty 7575 list (no global notification list). 7576 </para> 7577 </listitem> 7578 </varlistentry> 7579 7580 <varlistentry> 7581 <term><command>max-transfer-time-in</command></term> 7582 <listitem> 7583 <para> 7584 Inbound zone transfers running longer than 7585 this many minutes will be terminated. The default is 120 7586 minutes 7587 (2 hours). The maximum value is 28 days (40320 minutes). 7588 </para> 7589 </listitem> 7590 </varlistentry> 7591 7592 <varlistentry> 7593 <term><command>max-transfer-idle-in</command></term> 7594 <listitem> 7595 <para> 7596 Inbound zone transfers making no progress 7597 in this many minutes will be terminated. The default is 60 7598 minutes 7599 (1 hour). The maximum value is 28 days (40320 minutes). 7600 </para> 7601 </listitem> 7602 </varlistentry> 7603 7604 <varlistentry> 7605 <term><command>max-transfer-time-out</command></term> 7606 <listitem> 7607 <para> 7608 Outbound zone transfers running longer than 7609 this many minutes will be terminated. The default is 120 7610 minutes 7611 (2 hours). The maximum value is 28 days (40320 minutes). 7612 </para> 7613 </listitem> 7614 </varlistentry> 7615 7616 <varlistentry> 7617 <term><command>max-transfer-idle-out</command></term> 7618 <listitem> 7619 <para> 7620 Outbound zone transfers making no progress 7621 in this many minutes will be terminated. The default is 60 7622 minutes (1 7623 hour). The maximum value is 28 days (40320 minutes). 7624 </para> 7625 </listitem> 7626 </varlistentry> 7627 7628 <varlistentry> 7629 <term><command>serial-query-rate</command></term> 7630 <listitem> 7631 <para> 7632 Slave servers will periodically query master 7633 servers to find out if zone serial numbers have 7634 changed. Each such query uses a minute amount of 7635 the slave server's network bandwidth. To limit 7636 the amount of bandwidth used, BIND 9 limits the 7637 rate at which queries are sent. The value of the 7638 <command>serial-query-rate</command> option, an 7639 integer, is the maximum number of queries sent 7640 per second. The default is 20. 7641 </para> 7642 <para> 7643 In addition to controlling the rate SOA refresh 7644 queries are issued at 7645 <command>serial-query-rate</command> also controls 7646 the rate at which NOTIFY messages are sent from 7647 both master and slave zones. 7648 </para> 7649 </listitem> 7650 </varlistentry> 7651 7652 <varlistentry> 7653 <term><command>serial-queries</command></term> 7654 <listitem> 7655 <para> 7656 In BIND 8, the <command>serial-queries</command> 7657 option 7658 set the maximum number of concurrent serial number queries 7659 allowed to be outstanding at any given time. 7660 BIND 9 does not limit the number of outstanding 7661 serial queries and ignores the <command>serial-queries</command> option. 7662 Instead, it limits the rate at which the queries are sent 7663 as defined using the <command>serial-query-rate</command> option. 7664 </para> 7665 </listitem> 7666 </varlistentry> 7667 7668 <varlistentry> 7669 <term><command>transfer-format</command></term> 7670 <listitem> 7671 7672 <para> 7673 Zone transfers can be sent using two different formats, 7674 <command>one-answer</command> and 7675 <command>many-answers</command>. 7676 The <command>transfer-format</command> option is used 7677 on the master server to determine which format it sends. 7678 <command>one-answer</command> uses one DNS message per 7679 resource record transferred. 7680 <command>many-answers</command> packs as many resource 7681 records as possible into a message. 7682 <command>many-answers</command> is more efficient, but is 7683 only supported by relatively new slave servers, 7684 such as <acronym>BIND</acronym> 9, <acronym>BIND</acronym> 7685 8.x and <acronym>BIND</acronym> 4.9.5 onwards. 7686 The <command>many-answers</command> format is also supported by 7687 recent Microsoft Windows nameservers. 7688 The default is <command>many-answers</command>. 7689 <command>transfer-format</command> may be overridden on a 7690 per-server basis by using the <command>server</command> 7691 statement. 7692 </para> 7693 7694 </listitem> 7695 </varlistentry> 7696 7697 <varlistentry> 7698 <term><command>transfers-in</command></term> 7699 <listitem> 7700 <para> 7701 The maximum number of inbound zone transfers 7702 that can be running concurrently. The default value is <literal>10</literal>. 7703 Increasing <command>transfers-in</command> may 7704 speed up the convergence 7705 of slave zones, but it also may increase the load on the 7706 local system. 7707 </para> 7708 </listitem> 7709 </varlistentry> 7710 7711 <varlistentry> 7712 <term><command>transfers-out</command></term> 7713 <listitem> 7714 <para> 7715 The maximum number of outbound zone transfers 7716 that can be running concurrently. Zone transfer requests in 7717 excess 7718 of the limit will be refused. The default value is <literal>10</literal>. 7719 </para> 7720 </listitem> 7721 </varlistentry> 7722 7723 <varlistentry> 7724 <term><command>transfers-per-ns</command></term> 7725 <listitem> 7726 <para> 7727 The maximum number of inbound zone transfers 7728 that can be concurrently transferring from a given remote 7729 name server. 7730 The default value is <literal>2</literal>. 7731 Increasing <command>transfers-per-ns</command> 7732 may 7733 speed up the convergence of slave zones, but it also may 7734 increase 7735 the load on the remote name server. <command>transfers-per-ns</command> may 7736 be overridden on a per-server basis by using the <command>transfers</command> phrase 7737 of the <command>server</command> statement. 7738 </para> 7739 </listitem> 7740 </varlistentry> 7741 7742 <varlistentry> 7743 <term><command>transfer-source</command></term> 7744 <listitem> 7745 <para><command>transfer-source</command> 7746 determines which local address will be bound to IPv4 7747 TCP connections used to fetch zones transferred 7748 inbound by the server. It also determines the 7749 source IPv4 address, and optionally the UDP port, 7750 used for the refresh queries and forwarded dynamic 7751 updates. If not set, it defaults to a system 7752 controlled value which will usually be the address 7753 of the interface "closest to" the remote end. This 7754 address must appear in the remote end's 7755 <command>allow-transfer</command> option for the 7756 zone being transferred, if one is specified. This 7757 statement sets the 7758 <command>transfer-source</command> for all zones, 7759 but can be overridden on a per-view or per-zone 7760 basis by including a 7761 <command>transfer-source</command> statement within 7762 the <command>view</command> or 7763 <command>zone</command> block in the configuration 7764 file. 7765 </para> 7766 <note> 7767 <para> 7768 Solaris 2.5.1 and earlier does not support setting the 7769 source address for TCP sockets. 7770 </para> 7771 </note> 7772 </listitem> 7773 </varlistentry> 7774 7775 <varlistentry> 7776 <term><command>transfer-source-v6</command></term> 7777 <listitem> 7778 <para> 7779 The same as <command>transfer-source</command>, 7780 except zone transfers are performed using IPv6. 7781 </para> 7782 </listitem> 7783 </varlistentry> 7784 7785 <varlistentry> 7786 <term><command>alt-transfer-source</command></term> 7787 <listitem> 7788 <para> 7789 An alternate transfer source if the one listed in 7790 <command>transfer-source</command> fails and 7791 <command>use-alt-transfer-source</command> is 7792 set. 7793 </para> 7794 <note> 7795 If you do not wish the alternate transfer source 7796 to be used, you should set 7797 <command>use-alt-transfer-source</command> 7798 appropriately and you should not depend upon 7799 getting an answer back to the first refresh 7800 query. 7801 </note> 7802 </listitem> 7803 </varlistentry> 7804 7805 <varlistentry> 7806 <term><command>alt-transfer-source-v6</command></term> 7807 <listitem> 7808 <para> 7809 An alternate transfer source if the one listed in 7810 <command>transfer-source-v6</command> fails and 7811 <command>use-alt-transfer-source</command> is 7812 set. 7813 </para> 7814 </listitem> 7815 </varlistentry> 7816 7817 <varlistentry> 7818 <term><command>use-alt-transfer-source</command></term> 7819 <listitem> 7820 <para> 7821 Use the alternate transfer sources or not. If views are 7822 specified this defaults to <command>no</command> 7823 otherwise it defaults to 7824 <command>yes</command> (for BIND 8 7825 compatibility). 7826 </para> 7827 </listitem> 7828 </varlistentry> 7829 7830 <varlistentry> 7831 <term><command>notify-source</command></term> 7832 <listitem> 7833 <para><command>notify-source</command> 7834 determines which local source address, and 7835 optionally UDP port, will be used to send NOTIFY 7836 messages. This address must appear in the slave 7837 server's <command>masters</command> zone clause or 7838 in an <command>allow-notify</command> clause. This 7839 statement sets the <command>notify-source</command> 7840 for all zones, but can be overridden on a per-zone or 7841 per-view basis by including a 7842 <command>notify-source</command> statement within 7843 the <command>zone</command> or 7844 <command>view</command> block in the configuration 7845 file. 7846 </para> 7847 <note> 7848 <para> 7849 Solaris 2.5.1 and earlier does not support setting the 7850 source address for TCP sockets. 7851 </para> 7852 </note> 7853 </listitem> 7854 </varlistentry> 7855 7856 <varlistentry> 7857 <term><command>notify-source-v6</command></term> 7858 <listitem> 7859 <para> 7860 Like <command>notify-source</command>, 7861 but applies to notify messages sent to IPv6 addresses. 7862 </para> 7863 </listitem> 7864 </varlistentry> 7865 7866 </variablelist> 7867 7868 </sect3> 7869 7870 <sect3> 7871 <title>UDP Port Lists</title> 7872 <para> 7873 <command>use-v4-udp-ports</command>, 7874 <command>avoid-v4-udp-ports</command>, 7875 <command>use-v6-udp-ports</command>, and 7876 <command>avoid-v6-udp-ports</command> 7877 specify a list of IPv4 and IPv6 UDP ports that will be 7878 used or not used as source ports for UDP messages. 7879 See <xref linkend="query_address"/> about how the 7880 available ports are determined. 7881 For example, with the following configuration 7882 </para> 7883 7884<programlisting> 7885use-v6-udp-ports { range 32768 65535; }; 7886avoid-v6-udp-ports { 40000; range 50000 60000; }; 7887</programlisting> 7888 7889 <para> 7890 UDP ports of IPv6 messages sent 7891 from <command>named</command> will be in one 7892 of the following ranges: 32768 to 39999, 40001 to 49999, 7893 and 60001 to 65535. 7894 </para> 7895 7896 <para> 7897 <command>avoid-v4-udp-ports</command> and 7898 <command>avoid-v6-udp-ports</command> can be used 7899 to prevent <command>named</command> from choosing as its random source port a 7900 port that is blocked by your firewall or a port that is 7901 used by other applications; 7902 if a query went out with a source port blocked by a 7903 firewall, the 7904 answer would not get by the firewall and the name server would 7905 have to query again. 7906 Note: the desired range can also be represented only with 7907 <command>use-v4-udp-ports</command> and 7908 <command>use-v6-udp-ports</command>, and the 7909 <command>avoid-</command> options are redundant in that 7910 sense; they are provided for backward compatibility and 7911 to possibly simplify the port specification. 7912 </para> 7913 </sect3> 7914 7915 <sect3> 7916 <title>Operating System Resource Limits</title> 7917 7918 <para> 7919 The server's usage of many system resources can be limited. 7920 Scaled values are allowed when specifying resource limits. For 7921 example, <command>1G</command> can be used instead of 7922 <command>1073741824</command> to specify a limit of 7923 one 7924 gigabyte. <command>unlimited</command> requests 7925 unlimited use, or the 7926 maximum available amount. <command>default</command> 7927 uses the limit 7928 that was in force when the server was started. See the description 7929 of <command>size_spec</command> in <xref linkend="configuration_file_elements"/>. 7930 </para> 7931 7932 <para> 7933 The following options set operating system resource limits for 7934 the name server process. Some operating systems don't support 7935 some or 7936 any of the limits. On such systems, a warning will be issued if 7937 the 7938 unsupported limit is used. 7939 </para> 7940 7941 <variablelist> 7942 7943 <varlistentry> 7944 <term><command>coresize</command></term> 7945 <listitem> 7946 <para> 7947 The maximum size of a core dump. The default 7948 is <literal>default</literal>. 7949 </para> 7950 </listitem> 7951 </varlistentry> 7952 7953 <varlistentry> 7954 <term><command>datasize</command></term> 7955 <listitem> 7956 <para> 7957 The maximum amount of data memory the server 7958 may use. The default is <literal>default</literal>. 7959 This is a hard limit on server memory usage. 7960 If the server attempts to allocate memory in excess of this 7961 limit, the allocation will fail, which may in turn leave 7962 the server unable to perform DNS service. Therefore, 7963 this option is rarely useful as a way of limiting the 7964 amount of memory used by the server, but it can be used 7965 to raise an operating system data size limit that is 7966 too small by default. If you wish to limit the amount 7967 of memory used by the server, use the 7968 <command>max-cache-size</command> and 7969 <command>recursive-clients</command> 7970 options instead. 7971 </para> 7972 </listitem> 7973 </varlistentry> 7974 7975 <varlistentry> 7976 <term><command>files</command></term> 7977 <listitem> 7978 <para> 7979 The maximum number of files the server 7980 may have open concurrently. The default is <literal>unlimited</literal>. 7981 </para> 7982 </listitem> 7983 </varlistentry> 7984 7985 <varlistentry> 7986 <term><command>stacksize</command></term> 7987 <listitem> 7988 <para> 7989 The maximum amount of stack memory the server 7990 may use. The default is <literal>default</literal>. 7991 </para> 7992 </listitem> 7993 </varlistentry> 7994 7995 </variablelist> 7996 7997 </sect3> 7998 7999 <sect3 id="server_resource_limits"> 8000 <title>Server Resource Limits</title> 8001 8002 <para> 8003 The following options set limits on the server's 8004 resource consumption that are enforced internally by the 8005 server rather than the operating system. 8006 </para> 8007 8008 <variablelist> 8009 8010 <varlistentry> 8011 <term><command>max-ixfr-log-size</command></term> 8012 <listitem> 8013 <para> 8014 This option is obsolete; it is accepted 8015 and ignored for BIND 8 compatibility. The option 8016 <command>max-journal-size</command> performs a 8017 similar function in BIND 9. 8018 </para> 8019 </listitem> 8020 </varlistentry> 8021 8022 <varlistentry> 8023 <term><command>max-journal-size</command></term> 8024 <listitem> 8025 <para> 8026 Sets a maximum size for each journal file 8027 (see <xref linkend="journal"/>). When the journal file 8028 approaches 8029 the specified size, some of the oldest transactions in the 8030 journal 8031 will be automatically removed. The default is 8032 <literal>unlimited</literal>. 8033 This may also be set on a per-zone basis. 8034 </para> 8035 </listitem> 8036 </varlistentry> 8037 8038 <varlistentry> 8039 <term><command>host-statistics-max</command></term> 8040 <listitem> 8041 <para> 8042 In BIND 8, specifies the maximum number of host statistics 8043 entries to be kept. 8044 Not implemented in BIND 9. 8045 </para> 8046 </listitem> 8047 </varlistentry> 8048 8049 <varlistentry> 8050 <term><command>recursive-clients</command></term> 8051 <listitem> 8052 <para> 8053 The maximum number of simultaneous recursive lookups 8054 the server will perform on behalf of clients. The default 8055 is 8056 <literal>1000</literal>. Because each recursing 8057 client uses a fair 8058 bit of memory, on the order of 20 kilobytes, the value of 8059 the 8060 <command>recursive-clients</command> option may 8061 have to be decreased 8062 on hosts with limited memory. 8063 </para> 8064 </listitem> 8065 </varlistentry> 8066 8067 <varlistentry> 8068 <term><command>tcp-clients</command></term> 8069 <listitem> 8070 <para> 8071 The maximum number of simultaneous client TCP 8072 connections that the server will accept. 8073 The default is <literal>100</literal>. 8074 </para> 8075 </listitem> 8076 </varlistentry> 8077 8078 <varlistentry> 8079 <term><command>reserved-sockets</command></term> 8080 <listitem> 8081 <para> 8082 The number of file descriptors reserved for TCP, stdio, 8083 etc. This needs to be big enough to cover the number of 8084 interfaces <command>named</command> listens on, <command>tcp-clients</command> as well as 8085 to provide room for outgoing TCP queries and incoming zone 8086 transfers. The default is <literal>512</literal>. 8087 The minimum value is <literal>128</literal> and the 8088 maximum value is <literal>128</literal> less than 8089 maxsockets (-S). This option may be removed in the future. 8090 </para> 8091 <para> 8092 This option has little effect on Windows. 8093 </para> 8094 </listitem> 8095 </varlistentry> 8096 8097 <varlistentry> 8098 <term><command>max-cache-size</command></term> 8099 <listitem> 8100 <para> 8101 The maximum amount of memory to use for the 8102 server's cache, in bytes. 8103 When the amount of data in the cache 8104 reaches this limit, the server will cause records to expire 8105 prematurely based on an LRU based strategy so that 8106 the limit is not exceeded. 8107 A value of 0 is special, meaning that 8108 records are purged from the cache only when their 8109 TTLs expire. 8110 Another special keyword <userinput>unlimited</userinput> 8111 means the maximum value of 32-bit unsigned integers 8112 (0xffffffff), which may not have the same effect as 8113 0 on machines that support more than 32 bits of 8114 memory space. 8115 Any positive values less than 2MB will be ignored reset 8116 to 2MB. 8117 In a server with multiple views, the limit applies 8118 separately to the cache of each view. 8119 The default is 0. 8120 </para> 8121 </listitem> 8122 </varlistentry> 8123 8124 <varlistentry> 8125 <term><command>tcp-listen-queue</command></term> 8126 <listitem> 8127 <para> 8128 The listen queue depth. The default and minimum is 3. 8129 If the kernel supports the accept filter "dataready" this 8130 also controls how 8131 many TCP connections that will be queued in kernel space 8132 waiting for 8133 some data before being passed to accept. Values less than 3 8134 will be 8135 silently raised. 8136 </para> 8137 </listitem> 8138 </varlistentry> 8139 8140 </variablelist> 8141 8142 </sect3> 8143 8144 <sect3> 8145 <title>Periodic Task Intervals</title> 8146 8147 <variablelist> 8148 8149 <varlistentry> 8150 <term><command>cleaning-interval</command></term> 8151 <listitem> 8152 <para> 8153 This interval is effectively obsolete. Previously, 8154 the server would remove expired resource records 8155 from the cache every <command>cleaning-interval</command> minutes. 8156 <acronym>BIND</acronym> 9 now manages cache 8157 memory in a more sophisticated manner and does not 8158 rely on the periodic cleaning any more. 8159 Specifying this option therefore has no effect on 8160 the server's behavior. 8161 </para> 8162 </listitem> 8163 </varlistentry> 8164 8165 <varlistentry> 8166 <term><command>heartbeat-interval</command></term> 8167 <listitem> 8168 <para> 8169 The server will perform zone maintenance tasks 8170 for all zones marked as <command>dialup</command> whenever this 8171 interval expires. The default is 60 minutes. Reasonable 8172 values are up 8173 to 1 day (1440 minutes). The maximum value is 28 days 8174 (40320 minutes). 8175 If set to 0, no zone maintenance for these zones will occur. 8176 </para> 8177 </listitem> 8178 </varlistentry> 8179 8180 <varlistentry> 8181 <term><command>interface-interval</command></term> 8182 <listitem> 8183 <para> 8184 The server will scan the network interface list 8185 every <command>interface-interval</command> 8186 minutes. The default 8187 is 60 minutes. The maximum value is 28 days (40320 minutes). 8188 If set to 0, interface scanning will only occur when 8189 the configuration file is loaded. After the scan, the 8190 server will 8191 begin listening for queries on any newly discovered 8192 interfaces (provided they are allowed by the 8193 <command>listen-on</command> configuration), and 8194 will 8195 stop listening on interfaces that have gone away. 8196 </para> 8197 </listitem> 8198 </varlistentry> 8199 8200 <varlistentry> 8201 <term><command>statistics-interval</command></term> 8202 <listitem> 8203 <para> 8204 Name server statistics will be logged 8205 every <command>statistics-interval</command> 8206 minutes. The default is 8207 60. The maximum value is 28 days (40320 minutes). 8208 If set to 0, no statistics will be logged. 8209 </para><note> 8210 <simpara> 8211 Not yet implemented in 8212 <acronym>BIND</acronym> 9. 8213 </simpara> 8214 </note> 8215 </listitem> 8216 </varlistentry> 8217 8218 </variablelist> 8219 8220 </sect3> 8221 8222 <sect3 id="topology"> 8223 <title>Topology</title> 8224 8225 <para> 8226 All other things being equal, when the server chooses a name 8227 server 8228 to query from a list of name servers, it prefers the one that is 8229 topologically closest to itself. The <command>topology</command> statement 8230 takes an <command>address_match_list</command> and 8231 interprets it 8232 in a special way. Each top-level list element is assigned a 8233 distance. 8234 Non-negated elements get a distance based on their position in the 8235 list, where the closer the match is to the start of the list, the 8236 shorter the distance is between it and the server. A negated match 8237 will be assigned the maximum distance from the server. If there 8238 is no match, the address will get a distance which is further than 8239 any non-negated list element, and closer than any negated element. 8240 For example, 8241 </para> 8242 8243<programlisting>topology { 8244 10/8; 8245 !1.2.3/24; 8246 { 1.2/16; 3/8; }; 8247};</programlisting> 8248 8249 <para> 8250 will prefer servers on network 10 the most, followed by hosts 8251 on network 1.2.0.0 (netmask 255.255.0.0) and network 3, with the 8252 exception of hosts on network 1.2.3 (netmask 255.255.255.0), which 8253 is preferred least of all. 8254 </para> 8255 <para> 8256 The default topology is 8257 </para> 8258 8259<programlisting> topology { localhost; localnets; }; 8260</programlisting> 8261 8262 <note> 8263 <simpara> 8264 The <command>topology</command> option 8265 is not implemented in <acronym>BIND</acronym> 9. 8266 </simpara> 8267 </note> 8268 </sect3> 8269 8270 <sect3 id="the_sortlist_statement"> 8271 8272 <title>The <command>sortlist</command> Statement</title> 8273 8274 <para> 8275 The response to a DNS query may consist of multiple resource 8276 records (RRs) forming a resource records set (RRset). 8277 The name server will normally return the 8278 RRs within the RRset in an indeterminate order 8279 (but see the <command>rrset-order</command> 8280 statement in <xref linkend="rrset_ordering"/>). 8281 The client resolver code should rearrange the RRs as appropriate, 8282 that is, using any addresses on the local net in preference to 8283 other addresses. 8284 However, not all resolvers can do this or are correctly 8285 configured. 8286 When a client is using a local server, the sorting can be performed 8287 in the server, based on the client's address. This only requires 8288 configuring the name servers, not all the clients. 8289 </para> 8290 8291 <para> 8292 The <command>sortlist</command> statement (see below) 8293 takes 8294 an <command>address_match_list</command> and 8295 interprets it even 8296 more specifically than the <command>topology</command> 8297 statement 8298 does (<xref linkend="topology"/>). 8299 Each top level statement in the <command>sortlist</command> must 8300 itself be an explicit <command>address_match_list</command> with 8301 one or two elements. The first element (which may be an IP 8302 address, 8303 an IP prefix, an ACL name or a nested <command>address_match_list</command>) 8304 of each top level list is checked against the source address of 8305 the query until a match is found. 8306 </para> 8307 <para> 8308 Once the source address of the query has been matched, if 8309 the top level statement contains only one element, the actual 8310 primitive 8311 element that matched the source address is used to select the 8312 address 8313 in the response to move to the beginning of the response. If the 8314 statement is a list of two elements, then the second element is 8315 treated the same as the <command>address_match_list</command> in 8316 a <command>topology</command> statement. Each top 8317 level element 8318 is assigned a distance and the address in the response with the 8319 minimum 8320 distance is moved to the beginning of the response. 8321 </para> 8322 <para> 8323 In the following example, any queries received from any of 8324 the addresses of the host itself will get responses preferring 8325 addresses 8326 on any of the locally connected networks. Next most preferred are 8327 addresses 8328 on the 192.168.1/24 network, and after that either the 8329 192.168.2/24 8330 or 8331 192.168.3/24 network with no preference shown between these two 8332 networks. Queries received from a host on the 192.168.1/24 network 8333 will prefer other addresses on that network to the 192.168.2/24 8334 and 8335 192.168.3/24 networks. Queries received from a host on the 8336 192.168.4/24 8337 or the 192.168.5/24 network will only prefer other addresses on 8338 their directly connected networks. 8339 </para> 8340 8341<programlisting>sortlist { 8342 // IF the local host 8343 // THEN first fit on the following nets 8344 { localhost; 8345 { localnets; 8346 192.168.1/24; 8347 { 192.168.2/24; 192.168.3/24; }; }; }; 8348 // IF on class C 192.168.1 THEN use .1, or .2 or .3 8349 { 192.168.1/24; 8350 { 192.168.1/24; 8351 { 192.168.2/24; 192.168.3/24; }; }; }; 8352 // IF on class C 192.168.2 THEN use .2, or .1 or .3 8353 { 192.168.2/24; 8354 { 192.168.2/24; 8355 { 192.168.1/24; 192.168.3/24; }; }; }; 8356 // IF on class C 192.168.3 THEN use .3, or .1 or .2 8357 { 192.168.3/24; 8358 { 192.168.3/24; 8359 { 192.168.1/24; 192.168.2/24; }; }; }; 8360 // IF .4 or .5 THEN prefer that net 8361 { { 192.168.4/24; 192.168.5/24; }; 8362 }; 8363};</programlisting> 8364 8365 <para> 8366 The following example will give reasonable behavior for the 8367 local host and hosts on directly connected networks. It is similar 8368 to the behavior of the address sort in <acronym>BIND</acronym> 4.9.x. Responses sent 8369 to queries from the local host will favor any of the directly 8370 connected 8371 networks. Responses sent to queries from any other hosts on a 8372 directly 8373 connected network will prefer addresses on that same network. 8374 Responses 8375 to other queries will not be sorted. 8376 </para> 8377 8378<programlisting>sortlist { 8379 { localhost; localnets; }; 8380 { localnets; }; 8381}; 8382</programlisting> 8383 8384 </sect3> 8385 <sect3 id="rrset_ordering"> 8386 <title id="rrset_ordering_title">RRset Ordering</title> 8387 <para> 8388 When multiple records are returned in an answer it may be 8389 useful to configure the order of the records placed into the 8390 response. 8391 The <command>rrset-order</command> statement permits 8392 configuration 8393 of the ordering of the records in a multiple record response. 8394 See also the <command>sortlist</command> statement, 8395 <xref linkend="the_sortlist_statement"/>. 8396 </para> 8397 8398 <para> 8399 An <command>order_spec</command> is defined as 8400 follows: 8401 </para> 8402 <para> 8403 <optional>class <replaceable>class_name</replaceable></optional> 8404 <optional>type <replaceable>type_name</replaceable></optional> 8405 <optional>name <replaceable>"domain_name"</replaceable></optional> 8406 order <replaceable>ordering</replaceable> 8407 </para> 8408 <para> 8409 If no class is specified, the default is <command>ANY</command>. 8410 If no type is specified, the default is <command>ANY</command>. 8411 If no name is specified, the default is "<command>*</command>" (asterisk). 8412 </para> 8413 <para> 8414 The legal values for <command>ordering</command> are: 8415 </para> 8416 <informaltable colsep="0" rowsep="0"> 8417 <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> 8418 <colspec colname="1" colnum="1" colsep="0" colwidth="0.750in"/> 8419 <colspec colname="2" colnum="2" colsep="0" colwidth="3.750in"/> 8420 <tbody> 8421 <row rowsep="0"> 8422 <entry colname="1"> 8423 <para><command>fixed</command></para> 8424 </entry> 8425 <entry colname="2"> 8426 <para> 8427 Records are returned in the order they 8428 are defined in the zone file. 8429 </para> 8430 </entry> 8431 </row> 8432 <row rowsep="0"> 8433 <entry colname="1"> 8434 <para><command>random</command></para> 8435 </entry> 8436 <entry colname="2"> 8437 <para> 8438 Records are returned in some random order. 8439 </para> 8440 </entry> 8441 </row> 8442 <row rowsep="0"> 8443 <entry colname="1"> 8444 <para><command>cyclic</command></para> 8445 </entry> 8446 <entry colname="2"> 8447 <para> 8448 Records are returned in a cyclic round-robin order. 8449 </para> 8450 <para> 8451 If <acronym>BIND</acronym> is configured with the 8452 "--enable-fixed-rrset" option at compile time, then 8453 the initial ordering of the RRset will match the 8454 one specified in the zone file. 8455 </para> 8456 </entry> 8457 </row> 8458 </tbody> 8459 </tgroup> 8460 </informaltable> 8461 <para> 8462 For example: 8463 </para> 8464 8465<programlisting>rrset-order { 8466 class IN type A name "host.example.com" order random; 8467 order cyclic; 8468}; 8469</programlisting> 8470 8471 <para> 8472 will cause any responses for type A records in class IN that 8473 have "<literal>host.example.com</literal>" as a 8474 suffix, to always be returned 8475 in random order. All other records are returned in cyclic order. 8476 </para> 8477 <para> 8478 If multiple <command>rrset-order</command> statements 8479 appear, 8480 they are not combined — the last one applies. 8481 </para> 8482 8483 <note> 8484 <simpara> 8485 In this release of <acronym>BIND</acronym> 9, the 8486 <command>rrset-order</command> statement does not support 8487 "fixed" ordering by default. Fixed ordering can be enabled 8488 at compile time by specifying "--enable-fixed-rrset" on 8489 the "configure" command line. 8490 </simpara> 8491 </note> 8492 </sect3> 8493 8494 <sect3 id="tuning"> 8495 <title>Tuning</title> 8496 8497 <variablelist> 8498 8499 <varlistentry> 8500 <term><command>lame-ttl</command></term> 8501 <listitem> 8502 <para> 8503 Sets the number of seconds to cache a 8504 lame server indication. 0 disables caching. (This is 8505 <emphasis role="bold">NOT</emphasis> recommended.) 8506 The default is <literal>600</literal> (10 minutes) and the 8507 maximum value is 8508 <literal>1800</literal> (30 minutes). 8509 </para> 8510 8511 <para> 8512 Lame-ttl also controls the amount of time DNSSEC 8513 validation failures are cached. There is a minimum 8514 of 30 seconds applied to bad cache entries if the 8515 lame-ttl is set to less than 30 seconds. 8516 </para> 8517 8518 </listitem> 8519 </varlistentry> 8520 8521 <varlistentry> 8522 <term><command>max-ncache-ttl</command></term> 8523 <listitem> 8524 <para> 8525 To reduce network traffic and increase performance, 8526 the server stores negative answers. <command>max-ncache-ttl</command> is 8527 used to set a maximum retention time for these answers in 8528 the server 8529 in seconds. The default 8530 <command>max-ncache-ttl</command> is <literal>10800</literal> seconds (3 hours). 8531 <command>max-ncache-ttl</command> cannot exceed 8532 7 days and will 8533 be silently truncated to 7 days if set to a greater value. 8534 </para> 8535 </listitem> 8536 </varlistentry> 8537 8538 <varlistentry> 8539 <term><command>max-cache-ttl</command></term> 8540 <listitem> 8541 <para> 8542 Sets the maximum time for which the server will 8543 cache ordinary (positive) answers. The default is 8544 one week (7 days). 8545 A value of zero may cause all queries to return 8546 SERVFAIL, because of lost caches of intermediate 8547 RRsets (such as NS and glue AAAA/A records) in the 8548 resolution process. 8549 </para> 8550 </listitem> 8551 </varlistentry> 8552 8553 <varlistentry> 8554 <term><command>min-roots</command></term> 8555 <listitem> 8556 <para> 8557 The minimum number of root servers that 8558 is required for a request for the root servers to be 8559 accepted. The default 8560 is <userinput>2</userinput>. 8561 </para> 8562 <note> 8563 <simpara> 8564 Not implemented in <acronym>BIND</acronym> 9. 8565 </simpara> 8566 </note> 8567 </listitem> 8568 </varlistentry> 8569 8570 <varlistentry> 8571 <term><command>sig-validity-interval</command></term> 8572 <listitem> 8573 <para> 8574 Specifies the number of days into the future when 8575 DNSSEC signatures automatically generated as a 8576 result of dynamic updates (<xref 8577 linkend="dynamic_update"/>) will expire. There 8578 is an optional second field which specifies how 8579 long before expiry that the signatures will be 8580 regenerated. If not specified, the signatures will 8581 be regenerated at 1/4 of base interval. The second 8582 field is specified in days if the base interval is 8583 greater than 7 days otherwise it is specified in hours. 8584 The default base interval is <literal>30</literal> days 8585 giving a re-signing interval of 7 1/2 days. The maximum 8586 values are 10 years (3660 days). 8587 </para> 8588 <para> 8589 The signature inception time is unconditionally 8590 set to one hour before the current time to allow 8591 for a limited amount of clock skew. 8592 </para> 8593 <para> 8594 The <command>sig-validity-interval</command> 8595 should be, at least, several multiples of the SOA 8596 expire interval to allow for reasonable interaction 8597 between the various timer and expiry dates. 8598 </para> 8599 </listitem> 8600 </varlistentry> 8601 8602 <varlistentry> 8603 <term><command>sig-signing-nodes</command></term> 8604 <listitem> 8605 <para> 8606 Specify the maximum number of nodes to be 8607 examined in each quantum when signing a zone with 8608 a new DNSKEY. The default is 8609 <literal>100</literal>. 8610 </para> 8611 </listitem> 8612 </varlistentry> 8613 8614 <varlistentry> 8615 <term><command>sig-signing-signatures</command></term> 8616 <listitem> 8617 <para> 8618 Specify a threshold number of signatures that 8619 will terminate processing a quantum when signing 8620 a zone with a new DNSKEY. The default is 8621 <literal>10</literal>. 8622 </para> 8623 </listitem> 8624 </varlistentry> 8625 8626 <varlistentry> 8627 <term><command>sig-signing-type</command></term> 8628 <listitem> 8629 <para> 8630 Specify a private RDATA type to be used when generating 8631 key signing records. The default is 8632 <literal>65534</literal>. 8633 </para> 8634 <para> 8635 It is expected that this parameter may be removed 8636 in a future version once there is a standard type. 8637 </para> 8638 </listitem> 8639 </varlistentry> 8640 8641 <varlistentry> 8642 <term><command>min-refresh-time</command></term> 8643 <term><command>max-refresh-time</command></term> 8644 <term><command>min-retry-time</command></term> 8645 <term><command>max-retry-time</command></term> 8646 <listitem> 8647 <para> 8648 These options control the server's behavior on refreshing a 8649 zone 8650 (querying for SOA changes) or retrying failed transfers. 8651 Usually the SOA values for the zone are used, but these 8652 values 8653 are set by the master, giving slave server administrators 8654 little 8655 control over their contents. 8656 </para> 8657 <para> 8658 These options allow the administrator to set a minimum and 8659 maximum 8660 refresh and retry time either per-zone, per-view, or 8661 globally. 8662 These options are valid for slave and stub zones, 8663 and clamp the SOA refresh and retry times to the specified 8664 values. 8665 </para> 8666 <para> 8667 The following defaults apply. 8668 <command>min-refresh-time</command> 300 seconds, 8669 <command>max-refresh-time</command> 2419200 seconds 8670 (4 weeks), <command>min-retry-time</command> 500 seconds, 8671 and <command>max-retry-time</command> 1209600 seconds 8672 (2 weeks). 8673 </para> 8674 </listitem> 8675 </varlistentry> 8676 8677 <varlistentry> 8678 <term><command>edns-udp-size</command></term> 8679 <listitem> 8680 <para> 8681 Sets the advertised EDNS UDP buffer size in bytes 8682 to control the size of packets received. 8683 Valid values are 512 to 4096 (values outside this range 8684 will be silently adjusted). The default value 8685 is 4096. The usual reason for setting 8686 <command>edns-udp-size</command> to a non-default 8687 value is to get UDP answers to pass through broken 8688 firewalls that block fragmented packets and/or 8689 block UDP packets that are greater than 512 bytes. 8690 </para> 8691 <para> 8692 <command>named</command> will fallback to using 512 bytes 8693 if it get a series of timeout at the initial value. 512 8694 bytes is not being offered to encourage sites to fix their 8695 firewalls. Small EDNS UDP sizes will result in the 8696 excessive use of TCP. 8697 </para> 8698 </listitem> 8699 </varlistentry> 8700 8701 <varlistentry> 8702 <term><command>max-udp-size</command></term> 8703 <listitem> 8704 <para> 8705 Sets the maximum EDNS UDP message size 8706 <command>named</command> will send in bytes. 8707 Valid values are 512 to 4096 (values outside this 8708 range will be silently adjusted). The default 8709 value is 4096. The usual reason for setting 8710 <command>max-udp-size</command> to a non-default 8711 value is to get UDP answers to pass through broken 8712 firewalls that block fragmented packets and/or 8713 block UDP packets that are greater than 512 bytes. 8714 This is independent of the advertised receive 8715 buffer (<command>edns-udp-size</command>). 8716 </para> 8717 <para> 8718 Setting this to a low value will encourage additional 8719 TCP traffic to the nameserver. 8720 </para> 8721 </listitem> 8722 </varlistentry> 8723 8724 <varlistentry> 8725 <term><command>masterfile-format</command></term> 8726 <listitem> 8727 <para>Specifies 8728 the file format of zone files (see 8729 <xref linkend="zonefile_format"/>). 8730 The default value is <constant>text</constant>, which is the 8731 standard textual representation. Files in other formats 8732 than <constant>text</constant> are typically expected 8733 to be generated by the <command>named-compilezone</command> tool. 8734 Note that when a zone file in a different format than 8735 <constant>text</constant> is loaded, <command>named</command> 8736 may omit some of the checks which would be performed for a 8737 file in the <constant>text</constant> format. In particular, 8738 <command>check-names</command> checks do not apply 8739 for the <constant>raw</constant> format. This means 8740 a zone file in the <constant>raw</constant> format 8741 must be generated with the same check level as that 8742 specified in the <command>named</command> configuration 8743 file. This statement sets the 8744 <command>masterfile-format</command> for all zones, 8745 but can be overridden on a per-zone or per-view basis 8746 by including a <command>masterfile-format</command> 8747 statement within the <command>zone</command> or 8748 <command>view</command> block in the configuration 8749 file. 8750 </para> 8751 </listitem> 8752 </varlistentry> 8753 8754 <varlistentry id="clients-per-query"> 8755 <term><command>clients-per-query</command></term> 8756 <term><command>max-clients-per-query</command></term> 8757 <listitem> 8758 <para>These set the 8759 initial value (minimum) and maximum number of recursive 8760 simultaneous clients for any given query 8761 (<qname,qtype,qclass>) that the server will accept 8762 before dropping additional clients. <command>named</command> will attempt to 8763 self tune this value and changes will be logged. The 8764 default values are 10 and 100. 8765 </para> 8766 <para> 8767 This value should reflect how many queries come in for 8768 a given name in the time it takes to resolve that name. 8769 If the number of queries exceed this value, <command>named</command> will 8770 assume that it is dealing with a non-responsive zone 8771 and will drop additional queries. If it gets a response 8772 after dropping queries, it will raise the estimate. The 8773 estimate will then be lowered in 20 minutes if it has 8774 remained unchanged. 8775 </para> 8776 <para> 8777 If <command>clients-per-query</command> is set to zero, 8778 then there is no limit on the number of clients per query 8779 and no queries will be dropped. 8780 </para> 8781 <para> 8782 If <command>max-clients-per-query</command> is set to zero, 8783 then there is no upper bound other than imposed by 8784 <command>recursive-clients</command>. 8785 </para> 8786 </listitem> 8787 </varlistentry> 8788 8789 <varlistentry> 8790 <term><command>notify-delay</command></term> 8791 <listitem> 8792 <para> 8793 The delay, in seconds, between sending sets of notify 8794 messages for a zone. The default is five (5) seconds. 8795 </para> 8796 <para> 8797 The overall rate that NOTIFY messages are sent for all 8798 zones is controlled by <command>serial-query-rate</command>. 8799 </para> 8800 </listitem> 8801 </varlistentry> 8802 </variablelist> 8803 8804 </sect3> 8805 8806 <sect3 id="builtin"> 8807 <title>Built-in server information zones</title> 8808 8809 <para> 8810 The server provides some helpful diagnostic information 8811 through a number of built-in zones under the 8812 pseudo-top-level-domain <literal>bind</literal> in the 8813 <command>CHAOS</command> class. These zones are part 8814 of a 8815 built-in view (see <xref linkend="view_statement_grammar"/>) of 8816 class 8817 <command>CHAOS</command> which is separate from the 8818 default view of 8819 class <command>IN</command>; therefore, any global 8820 server options 8821 such as <command>allow-query</command> do not apply 8822 the these zones. 8823 If you feel the need to disable these zones, use the options 8824 below, or hide the built-in <command>CHAOS</command> 8825 view by 8826 defining an explicit view of class <command>CHAOS</command> 8827 that matches all clients. 8828 </para> 8829 8830 <variablelist> 8831 8832 <varlistentry> 8833 <term><command>version</command></term> 8834 <listitem> 8835 <para> 8836 The version the server should report 8837 via a query of the name <literal>version.bind</literal> 8838 with type <command>TXT</command>, class <command>CHAOS</command>. 8839 The default is the real version number of this server. 8840 Specifying <command>version none</command> 8841 disables processing of the queries. 8842 </para> 8843 </listitem> 8844 </varlistentry> 8845 8846 <varlistentry> 8847 <term><command>hostname</command></term> 8848 <listitem> 8849 <para> 8850 The hostname the server should report via a query of 8851 the name <filename>hostname.bind</filename> 8852 with type <command>TXT</command>, class <command>CHAOS</command>. 8853 This defaults to the hostname of the machine hosting the 8854 name server as 8855 found by the gethostname() function. The primary purpose of such queries 8856 is to 8857 identify which of a group of anycast servers is actually 8858 answering your queries. Specifying <command>hostname none;</command> 8859 disables processing of the queries. 8860 </para> 8861 </listitem> 8862 </varlistentry> 8863 8864 <varlistentry> 8865 <term><command>server-id</command></term> 8866 <listitem> 8867 <para> 8868 The ID the server should report when receiving a Name 8869 Server Identifier (NSID) query, or a query of the name 8870 <filename>ID.SERVER</filename> with type 8871 <command>TXT</command>, class <command>CHAOS</command>. 8872 The primary purpose of such queries is to 8873 identify which of a group of anycast servers is actually 8874 answering your queries. Specifying <command>server-id none;</command> 8875 disables processing of the queries. 8876 Specifying <command>server-id hostname;</command> will cause <command>named</command> to 8877 use the hostname as found by the gethostname() function. 8878 The default <command>server-id</command> is <command>none</command>. 8879 </para> 8880 </listitem> 8881 </varlistentry> 8882 8883 </variablelist> 8884 8885 </sect3> 8886 8887 <sect3 id="empty"> 8888 <title>Built-in Empty Zones</title> 8889 <para> 8890 Named has some built-in empty zones (SOA and NS records only). 8891 These are for zones that should normally be answered locally 8892 and which queries should not be sent to the Internet's root 8893 servers. The official servers which cover these namespaces 8894 return NXDOMAIN responses to these queries. In particular, 8895 these cover the reverse namespaces for addresses from 8896 RFC 1918, RFC 4193, and RFC 5737. They also include the 8897 reverse namespace for IPv6 local address (locally assigned), 8898 IPv6 link local addresses, the IPv6 loopback address and the 8899 IPv6 unknown address. 8900 </para> 8901 <para> 8902 Named will attempt to determine if a built-in zone already exists 8903 or is active (covered by a forward-only forwarding declaration) 8904 and will not create an empty zone in that case. 8905 </para> 8906 <para> 8907 The current list of empty zones is: 8908 <itemizedlist> 8909 <listitem>10.IN-ADDR.ARPA</listitem> 8910 <listitem>16.172.IN-ADDR.ARPA</listitem> 8911 <listitem>17.172.IN-ADDR.ARPA</listitem> 8912 <listitem>18.172.IN-ADDR.ARPA</listitem> 8913 <listitem>19.172.IN-ADDR.ARPA</listitem> 8914 <listitem>20.172.IN-ADDR.ARPA</listitem> 8915 <listitem>21.172.IN-ADDR.ARPA</listitem> 8916 <listitem>22.172.IN-ADDR.ARPA</listitem> 8917 <listitem>23.172.IN-ADDR.ARPA</listitem> 8918 <listitem>24.172.IN-ADDR.ARPA</listitem> 8919 <listitem>25.172.IN-ADDR.ARPA</listitem> 8920 <listitem>26.172.IN-ADDR.ARPA</listitem> 8921 <listitem>27.172.IN-ADDR.ARPA</listitem> 8922 <listitem>28.172.IN-ADDR.ARPA</listitem> 8923 <listitem>29.172.IN-ADDR.ARPA</listitem> 8924 <listitem>30.172.IN-ADDR.ARPA</listitem> 8925 <listitem>31.172.IN-ADDR.ARPA</listitem> 8926 <listitem>168.192.IN-ADDR.ARPA</listitem> 8927 <listitem>0.IN-ADDR.ARPA</listitem> 8928 <listitem>127.IN-ADDR.ARPA</listitem> 8929 <listitem>254.169.IN-ADDR.ARPA</listitem> 8930 <listitem>2.0.192.IN-ADDR.ARPA</listitem> 8931 <listitem>100.51.198.IN-ADDR.ARPA</listitem> 8932 <listitem>113.0.203.IN-ADDR.ARPA</listitem> 8933 <listitem>255.255.255.255.IN-ADDR.ARPA</listitem> 8934 <listitem>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</listitem> 8935 <listitem>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</listitem> 8936 <listitem>8.B.D.0.1.0.0.2.IP6.ARPA</listitem> 8937 <listitem>D.F.IP6.ARPA</listitem> 8938 <listitem>8.E.F.IP6.ARPA</listitem> 8939 <listitem>9.E.F.IP6.ARPA</listitem> 8940 <listitem>A.E.F.IP6.ARPA</listitem> 8941 <listitem>B.E.F.IP6.ARPA</listitem> 8942 </itemizedlist> 8943 </para> 8944 <para> 8945 Empty zones are settable at the view level and only apply to 8946 views of class IN. Disabled empty zones are only inherited 8947 from options if there are no disabled empty zones specified 8948 at the view level. To override the options list of disabled 8949 zones, you can disable the root zone at the view level, for example: 8950<programlisting> 8951 disable-empty-zone "."; 8952</programlisting> 8953 </para> 8954 <para> 8955 If you are using the address ranges covered here, you should 8956 already have reverse zones covering the addresses you use. 8957 In practice this appears to not be the case with many queries 8958 being made to the infrastructure servers for names in these 8959 spaces. So many in fact that sacrificial servers were needed 8960 to be deployed to channel the query load away from the 8961 infrastructure servers. 8962 </para> 8963 <note> 8964 The real parent servers for these zones should disable all 8965 empty zone under the parent zone they serve. For the real 8966 root servers, this is all built-in empty zones. This will 8967 enable them to return referrals to deeper in the tree. 8968 </note> 8969 <variablelist> 8970 <varlistentry> 8971 <term><command>empty-server</command></term> 8972 <listitem> 8973 <para> 8974 Specify what server name will appear in the returned 8975 SOA record for empty zones. If none is specified, then 8976 the zone's name will be used. 8977 </para> 8978 </listitem> 8979 </varlistentry> 8980 8981 <varlistentry> 8982 <term><command>empty-contact</command></term> 8983 <listitem> 8984 <para> 8985 Specify what contact name will appear in the returned 8986 SOA record for empty zones. If none is specified, then 8987 "." will be used. 8988 </para> 8989 </listitem> 8990 </varlistentry> 8991 8992 <varlistentry> 8993 <term><command>empty-zones-enable</command></term> 8994 <listitem> 8995 <para> 8996 Enable or disable all empty zones. By default, they 8997 are enabled. 8998 </para> 8999 </listitem> 9000 </varlistentry> 9001 9002 <varlistentry> 9003 <term><command>disable-empty-zone</command></term> 9004 <listitem> 9005 <para> 9006 Disable individual empty zones. By default, none are 9007 disabled. This option can be specified multiple times. 9008 </para> 9009 </listitem> 9010 </varlistentry> 9011 </variablelist> 9012 </sect3> 9013 9014 <sect3 id="acache"> 9015 <title>Additional Section Caching</title> 9016 9017 <para> 9018 The additional section cache, also called <command>acache</command>, 9019 is an internal cache to improve the response performance of BIND 9. 9020 When additional section caching is enabled, BIND 9 will 9021 cache an internal short-cut to the additional section content for 9022 each answer RR. 9023 Note that <command>acache</command> is an internal caching 9024 mechanism of BIND 9, and is not related to the DNS caching 9025 server function. 9026 </para> 9027 9028 <para> 9029 Additional section caching does not change the 9030 response content (except the RRsets ordering of the additional 9031 section, see below), but can improve the response performance 9032 significantly. 9033 It is particularly effective when BIND 9 acts as an authoritative 9034 server for a zone that has many delegations with many glue RRs. 9035 </para> 9036 9037 <para> 9038 In order to obtain the maximum performance improvement 9039 from additional section caching, setting 9040 <command>additional-from-cache</command> 9041 to <command>no</command> is recommended, since the current 9042 implementation of <command>acache</command> 9043 does not short-cut of additional section information from the 9044 DNS cache data. 9045 </para><