1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2.. 3.. SPDX-License-Identifier: MPL-2.0 4.. 5.. This Source Code Form is subject to the terms of the Mozilla Public 6.. License, v. 2.0. If a copy of the MPL was not distributed with this 7.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8.. 9.. See the COPYRIGHT file distributed with this work for additional 10.. information regarding copyright ownership. 11 12.. _config_resolver_samples: 13 14Resolver (Caching Name Servers) 15------------------------------- 16 17Resolvers handle :ref:`recursive user queries <recursive_query>` and provide 18complete answers; that is, they issue one or more :ref:`iterative queries 19<iterative_query>` to the DNS hierarchy. Having obtained a complete answer (or 20an error), a resolver passes the answer to the user and places it in its cache. 21Subsequent user requests for the same query will be answered from the 22resolver's cache until the :term:`TTL` of the cached answer has expired, when 23it will be flushed from the cache; the next user query that requests the same 24information results in a new series of queries to the DNS hierarchy. 25 26Resolvers are frequently referred to by a bewildering variety of names, 27including caching name servers, recursive name servers, forwarding resolvers, 28area resolvers, and full-service resolvers. 29 30The following diagram shows how resolvers can function in a typical networked 31environment: 32 33.. figure:: resolver-forward.png 34 :align: center 35 36Resolver and Forwarding Resolver 37 381. End-user systems are all distributed with a local **stub resolver** as a 39 standard feature. Today, the majority of stub resolvers also provide a local 40 cache service to speed up user response times. 41 422. A stub resolver has limited functionality; specifically, it cannot follow 43 :ref:`referrals<referral>`. When a stub resolver receives a request for a 44 name from a local program, such as a browser, and the answer is not in its 45 local cache, it sends a :ref:`recursive user query<recursive_query>` (1) to 46 a locally configured resolver (5), which may have the answer available in 47 its cache. If it does not, it issues :ref:`iterative 48 queries<iterative_query>` (2) to the DNS hierarchy to obtain the answer. The 49 resolver to which the local system sends the user query is configured, for 50 Linux and Unix hosts, in ``/etc/resolv.conf``; for Windows users it is 51 configured or changed via the Control Panel or Settings interface. 52 533. Alternatively, the user query can be sent to a **forwarding resolver** (4). 54 Forwarding resolvers on first glance look fairly pointless, since they 55 appear to be acting as a simple pass-though and, like the stub resolver, 56 require a full-service resolver (5). However, forwarding resolvers can be 57 very powerful additions to a network for the following reasons: 58 59 a) Cost and Performance. Each **recursive user query** (1) at the forwarding 60 resolver (4) results in two messages - the query and its answer. The resolver 61 (5) may have to issue three, four, or more query pairs (2) to get the required 62 answer. Traffic is reduced dramatically, increasing performance or reducing 63 cost (if the link is tariffed). Additionally, since the forwarding resolver is 64 typically shared across multiple hosts, its cache is more likely to contain 65 answers, again improving user performance. 66 67 b) Network Maintenance. Forwarding resolvers (4) can be used to ease the burden 68 of local administration by providing a single point at which changes to remote 69 name servers can be managed, rather than having to update all hosts. Thus, all 70 hosts in a particular network section or area can be configured to point to a 71 forwarding resolver, which can be configured to stream DNS traffic as desired 72 and changed over time with minimal effort. 73 74 c) Sanitizing Traffic. Especially in larger private networks it may be sensible 75 to stream DNS traffic using a forwarding resolver structure. The forwarding 76 resolver (4) may be configured, for example, to handle all in-domain traffic 77 (relatively safe) and forward all external traffic to a **hardened** resolver 78 (5). 79 80 d) Stealth Networks. Forwarding resolvers are extensively used in :ref:`stealth 81 or split networks<split_dns_sample>`. 82 834. Forwarding resolvers (4) can be configured to forward all traffic to a 84 resolver (5), or to only forward selective traffic (5) while directly 85 resolving other traffic (3). 86 87.. Attention:: While the diagram above shows **recursive user queries** 88 arriving via interface (1), there is nothing to stop them from arriving via 89 interface (2) via the public network. If no limits are placed on the source 90 IPs that can send such queries, the resolver is termed an **open resolver**. 91 Indeed, when the world was young this was the way things worked on the 92 Internet. Much has changed and what seems to be a friendly, generous action 93 can be used by rogue actors to cause all kinds of problems including 94 **Denial of Service (DoS)** attacks. Resolvers should always be configured 95 to limit the IP addresses that can use their services. BIND 9 provides a 96 number of statements and blocks to simplify defining these IP limits and 97 configuring a **closed resolver**. The resolver samples given here all 98 configure closed resolvers using a variety of techniques. 99 100Additional Zone Files 101~~~~~~~~~~~~~~~~~~~~~ 102 103Root Servers (Hint) Zone File 104^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 105 106Resolvers (although not necessarily forwarding resolvers) need to access the 107DNS hierarchy. To do this, they need to know the addresses (IPv4 and/or IPv6) 108of the 13 :ref:`root servers<root_servers>`. This is done by the provision of a 109root server zone file, which is contained in the standard BIND 9 distribution 110as the file ``named.root`` (normally found in /etc/namedb or 111/usr/local/namedb). This file may also be obtained from the IANA website 112(https://www.iana.org/domains/root/files). 113 114 115 .. Note:: Many distributions rename this file for historical reasons. 116 Consult the appropriate distribution documentation for the actual file name. 117 118 119The hint zone file is referenced using the :any:`type hint` statement and 120a zone (domain) name of "." (the generally silent dot). 121 122 .. Note:: The root server IP addresses have been stable for a number of 123 years and are likely to remain stable for the near future. BIND 9 has a 124 root-server list in its executable such that even if this file is omitted, 125 out-of-date, or corrupt BIND 9 can still function. For this reason, many 126 sample configurations omit the hints file. All the samples given here 127 include the hints file primarily as a reminder of the functionality of the 128 configuration, rather than as an absolute necessity. 129 130Private IP Reverse Map Zone Files 131^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 132 133Resolvers are configured to send :ref:`iterative queries<iterative_query>` to 134the public DNS hierarchy when the information requested is not in their cache 135or not defined in any local zone file. Many networks make extensive use of 136private IP addresses (defined by :rfc:`1918`, :rfc:`2193`, :rfc:`5737`, and 137:rfc:`6598`). By their nature these IP addresses are forward-mapped in various 138user zone files. However, certain applications may issue **reverse map** 139queries (mapping an IP address to a name). If the private IP addresses are not 140defined in one or more reverse-mapped zone file(s), the resolver sends them to 141the DNS hierarchy where they are simply useless traffic, slowing down DNS 142responses for all users. 143 144Private IP addresses may be defined using standard :ref:`reverse-mapping 145techniques<ipv4_reverse>` or using the 146:any:`empty-zones-enable` statement. By 147default this statement is set to ``empty-zones-enable yes;`` and thus automatically prevents 148unnecessary DNS traffic by sending an NXDOMAIN error response (indicating the 149name does not exist) to any request. However, some applications may require a 150genuine answer to such reverse-mapped requests or they will fail to function. 151Mail systems in particular perform reverse DNS queries as a first-line spam 152check; in this case a reverse-mapped zone file is essential. The sample 153configuration files given here for both the resolver and the forwarding 154resolver provide a reverse-mapping zone file for the private IP address 155192.168.254.4, which is the mail server address in the :ref:`base zone 156file<base_zone_file>`, as an illustration of the reverse-map technique. The 157file is named ``192.168.254.rev`` and has a zone name of 158**254.168.192.in-addr.arpa**. 159 160.. code-block:: 161 162 ; reverse map zone file for 192.168.254.4 only 163 $TTL 2d ; 172800 seconds 164 $ORIGIN 254.168.192.IN-ADDR.ARPA. 165 @ IN SOA ns1.example.com. hostmaster.example.com. ( 166 2003080800 ; serial number 167 3h ; refresh 168 15m ; update retry 169 3w ; expiry 170 3h ; nx = nxdomain ttl 171 ) 172 ; only one NS is required for this local file 173 ; and is an out of zone name 174 IN NS ns1.example.com. 175 ; other IP addresses can be added as required 176 ; this maps 192.168.254.4 as shown 177 4 IN PTR mail.example.com. ; fully qualified domain name (FQDN) 178 179.. _sample_resolver: 180 181Resolver Configuration 182~~~~~~~~~~~~~~~~~~~~~~ 183 184The resolver provides :ref:`recursive query support<recursive_query>` to a defined set of IP addresses. 185It is therefore a **closed** resolver and cannot be used in wider network attacks. 186 187.. code-block:: c 188 189 // resolver named.conf file 190 // Two corporate subnets we wish to allow queries from 191 // defined in an acl clause 192 acl corpnets { 193 192.168.4.0/24; 194 192.168.7.0/24; 195 }; 196 197 // options clause defining the server-wide properties 198 options { 199 // all relative paths use this directory as a base 200 directory "/var"; 201 // version statement for security to avoid hacking known weaknesses 202 // if the real version number is revealed 203 version "not currently available"; 204 // this is the default 205 recursion yes; 206 // recursive queries only allowed from these ips 207 // and references the acl clause 208 allow-query { corpnets; }; 209 // this ensures that any reverse map for private IPs 210 // not defined in a zone file will *not* be passed to the public network 211 // it is the default value 212 empty-zones-enable yes; 213 }; 214 215 // logging clause 216 // log to /var/log/named/example.log all events from info UP in severity (no debug) 217 // uses 3 files in rotation swaps files when size reaches 250K 218 // failure messages that occur before logging is established are 219 // in syslog (/var/log/messages) 220 // 221 logging { 222 channel example_log { 223 // uses a relative path name and the directory statement to 224 // expand to /var/log/named/example.log 225 file "log/named/example.log" versions 3 size 250k; 226 // only log info and up messages - all others discarded 227 severity info; 228 }; 229 category default { 230 example_log; 231 }; 232 }; 233 234 // zone file for the root servers 235 // discretionary zone (see root server discussion above) 236 zone "." { 237 type hint; 238 file "named.root"; 239 }; 240 241 // zone file for the localhost forward map 242 // discretionary zone depending on hosts file (see discussion) 243 zone "localhost" { 244 type primary; 245 file "masters/localhost-forward.db"; 246 notify no; 247 }; 248 249 // zone file for the loopback address 250 // necessary zone 251 zone "0.0.127.in-addr.arpa" { 252 type primary; 253 file "localhost.rev"; 254 notify no; 255 }; 256 257 // zone file for local IP reverse map 258 // discretionary file depending on requirements 259 zone "254.168.192.in-addr.arpa" { 260 type primary; 261 file "192.168.254.rev"; 262 notify no; 263 }; 264 265The :any:`zone` and :any:`acl` blocks, and the 266:any:`allow-query`, :any:`empty-zones-enable`, 267:any:`file`, :namedconf:ref:`notify`, :any:`recursion`, and 268:any:`type` statements are described in detail in the appropriate 269sections. 270 271As a reminder, the configuration of this resolver does **not** access the DNS 272hierarchy (does not use the public network) for any recursive query for which: 273 2741. The answer is already in the cache. 275 2762. The domain name is **localhost** (zone localhost). 277 2783. Is a reverse-map query for 127.0.0.1 (zone 0.0.127.in-addr.arpa). 279 2804. Is a reverse-map query for 192.168.254/24 (zone 254.168.192.in-addr.arpa). 281 2825. Is a reverse-map query for any local IP (:any:`empty-zones-enable` 283 statement). 284 285All other recursive queries will result in access to the DNS hierarchy to 286resolve the query. 287 288.. _sample_forwarding: 289 290Forwarding Resolver Configuration 291~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 292 293This forwarding resolver configuration forwards all recursive queries, other 294than those for the defined zones and those for which the answer is already in 295its cache, to a full-service resolver at the IP address 192.168.250.3, with an 296alternative at 192.168.230.27. The forwarding resolver will cache all responses 297from these servers. The configuration is closed, in that it defines those IPs 298from which it will accept recursive queries. 299 300A second configuration in which selective forwarding occurs :ref:`is also 301provided<selective_forward_sample>`. 302 303.. code-block:: c 304 305 // forwarding named.conf file 306 // Two corporate subnets we wish to allow queries from 307 // defined in an acl clause 308 acl corpnets { 309 192.168.4.0/24; 310 192.168.7.0/24; 311 }; 312 313 // options clause defining the server-wide properties 314 options { 315 // all relative paths use this directory as a base 316 directory "/var"; 317 // version statement for security to avoid hacking known weaknesses 318 // if the real version number is revealed 319 version "not currently available"; 320 // this is the default 321 recursion yes; 322 // recursive queries only allowed from these ips 323 // and references the acl clause 324 allow-query { corpnets; }; 325 // this ensures that any reverse map for private IPs 326 // not defined in a zone file will *not* be passed to the public network 327 // it is the default value 328 empty-zones-enable yes; 329 // this defines the addresses of the resolvers to which queries will be forwarded 330 forwarders { 331 192.168.250.3; 332 192.168.230.27; 333 }; 334 // indicates all queries will be forwarded other than for defined zones 335 forward only; 336 }; 337 338 // logging clause 339 // log to /var/log/named/example.log all events from info UP in severity (no debug) 340 // uses 3 files in rotation swaps files when size reaches 250K 341 // failure messages that occur before logging is established are 342 // in syslog (/var/log/messages) 343 // 344 logging { 345 channel example_log { 346 // uses a relative path name and the directory statement to 347 // expand to /var/log/named/example.log 348 file "log/named/example.log" versions 3 size 250k; 349 // only log info and up messages - all others discarded 350 severity info; 351 }; 352 category default { 353 example_log; 354 }; 355 }; 356 357 // hints zone file is not required 358 359 // zone file for the localhost forward map 360 // discretionary zone depending on hosts file (see discussion) 361 zone "localhost" { 362 type primary; 363 file "masters/localhost-forward.db"; 364 notify no; 365 }; 366 367 // zone file for the loopback address 368 // necessary zone 369 zone "0.0.127.in-addr.arpa" { 370 type primary; 371 file "localhost.rev"; 372 notify no; 373 }; 374 375 // zone file for local IP reverse map 376 // discretionary file depending on requirements 377 zone "254.168.192.in-addr.arpa" { 378 type primary; 379 file "192.168.254.rev"; 380 notify no; 381 }; 382 383The :any:`zone` and :any:`acl` blocks, and the 384:any:`allow-query`, :any:`empty-zones-enable`, 385:any:`file`, :any:`forward`, :any:`forwarders`, 386:namedconf:ref:`notify`, :any:`recursion`, and :any:`type` 387statements are described in detail in the appropriate sections. 388 389As a reminder, the configuration of this forwarding resolver does **not** 390forward any recursive query for which: 391 3921. The answer is already in the cache. 393 3942. The domain name is **localhost** (zone localhost). 395 3963. Is a reverse-map query for 127.0.0.1 (zone 0.0.127.in-addr.arpa). 397 3984. Is a reverse-map query for 192.168.254/24 (zone 254.168.192.in-addr.arpa). 399 4005. Is a reverse-map query for any local IP (:any:`empty-zones-enable` statement). 401 402All other recursive queries will be forwarded to resolve the query. 403 404.. _selective_forward_sample: 405 406Selective Forwarding Resolver Configuration 407~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 408 409This forwarding resolver configuration only forwards recursive queries for the 410zone **example.com** to the resolvers at 192.168.250.3 and 192.168.230.27. All 411other recursive queries, other than those for the defined zones and those for 412which the answer is already in its cache, are handled by this resolver. The 413forwarding resolver will cache all responses from both the public network and 414from the forwarded resolvers. The configuration is closed, in that it defines 415those IPs from which it will accept recursive queries. 416 417.. code-block:: c 418 419 // selective forwarding named.conf file 420 // Two corporate subnets we wish to allow queries from 421 // defined in an acl clause 422 acl corpnets { 423 192.168.4.0/24; 424 192.168.7.0/24; 425 }; 426 427 // options clause defining the server-wide properties 428 options { 429 // all relative paths use this directory as a base 430 directory "/var"; 431 // version statement for security to avoid hacking known weaknesses 432 // if the real version number is revealed 433 version "not currently available"; 434 // this is the default 435 recursion yes; 436 // recursive queries only allowed from these ips 437 // and references the acl clause 438 allow-query { corpnets; }; 439 // this ensures that any reverse map for private IPs 440 // not defined in a zone file will *not* be passed to the public network 441 // it is the default value 442 empty-zones-enable yes; 443 444 // forwarding is not global but selective by zone in this configuration 445 }; 446 447 // logging clause 448 // log to /var/log/named/example.log all events from info UP in severity (no debug) 449 // uses 3 files in rotation swaps files when size reaches 250K 450 // failure messages that occur before logging is established are 451 // in syslog (/var/log/messages) 452 // 453 logging { 454 channel example_log { 455 // uses a relative path name and the directory statement to 456 // expand to /var/log/named/example.log 457 file "log/named/example.log" versions 3 size 250k; 458 // only log info and up messages - all others discarded 459 severity info; 460 }; 461 category default { 462 example_log; 463 }; 464 }; 465 466 // zone file for the root servers 467 // discretionary zone (see root server discussion above) 468 zone "." { 469 type hint; 470 file "named.root"; 471 }; 472 473 // zone file for the localhost forward map 474 // discretionary zone depending on hosts file (see discussion) 475 zone "localhost" { 476 type primary; 477 file "masters/localhost-forward.db"; 478 notify no; 479 }; 480 481 // zone file for the loopback address 482 // necessary zone 483 zone "0.0.127.in-addr.arpa" { 484 type primary; 485 file "localhost.rev"; 486 notify no; 487 }; 488 489 // zone file for local IP reverse map 490 // discretionary file depending on requirements 491 zone "254.168.192.in-addr.arpa" { 492 type primary; 493 file "192.168.254.rev"; 494 notify no; 495 }; 496 // zone file forwarded example.com 497 zone "example.com" { 498 type forward; 499 // this defines the addresses of the resolvers to 500 // which queries for this zone will be forwarded 501 forwarders { 502 192.168.250.3; 503 192.168.230.27; 504 }; 505 // indicates all queries for this zone will be forwarded 506 forward only; 507 }; 508 509 510The :any:`zone` and :any:`acl` blocks, and the 511:any:`allow-query`, :any:`empty-zones-enable`, 512:any:`file`, :any:`forward`, :any:`forwarders`, 513:namedconf:ref:`notify`, :any:`recursion`, and :any:`type` 514statements are described in detail in the appropriate sections. 515 516As a reminder, the configuration of this resolver does **not** access the DNS 517hierarchy (does not use the public network) for any recursive query for which: 518 5191. The answer is already in the cache. 520 5212. The domain name is **localhost** (zone localhost). 522 5233. Is a reverse-map query for 127.0.0.1 (zone 0.0.127.in-addr.arpa). 524 5254. Is a reverse-map query for 192.168.254/24 (zone 254.168.192.in-addr.arpa). 526 5275. Is a reverse-map query for any local IP (empty-zones-enable statement). 528 5296. Is a query for the domain name **example.com**, in which case it will be 530 forwarded to either 192.168.250.3 or 192.168.230.27 (zone example.com). 531 532All other recursive queries will result in access to the DNS hierarchy to 533resolve the query. 534 535.. _load_balancing: 536 537Load Balancing 538-------------- 539 540A primitive form of load balancing can be achieved in the DNS by using multiple 541resource records (RRs) in a :ref:`zone file<zone_file>` (such as multiple A 542records) for one name. 543 544For example, assuming three HTTP servers with network addresses of 54510.0.0.1, 10.0.0.2, and 10.0.0.3, a set of records such as the following 546means that clients will connect to each machine one-third of the time: 547 548+-----------+------+----------+----------+----------------------------+ 549| Name | TTL | CLASS | TYPE | Resource Record (RR) Data | 550+-----------+------+----------+----------+----------------------------+ 551| www | 600 | IN | A | 10.0.0.1 | 552+-----------+------+----------+----------+----------------------------+ 553| | 600 | IN | A | 10.0.0.2 | 554+-----------+------+----------+----------+----------------------------+ 555| | 600 | IN | A | 10.0.0.3 | 556+-----------+------+----------+----------+----------------------------+ 557 558When a resolver queries for these records, BIND rotates them and 559responds to the query with the records in a random order. In the 560example above, clients randomly receive records in the order 1, 2, 5613; 2, 3, 1; and 3, 1, 2. Most clients use the first record returned 562and discard the rest. 563 564For more detail on ordering responses, refer to the 565:ref:`rrset-order<rrset_ordering>` statement in the 566:namedconf:ref:`options` block. 567
