1.. 2 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 3 4.. 5 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 6 7.. 8 IT HELPS PEOPLE DIFFING THE CHANGES 9 10.. 11 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 12 13.. 14 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 15 16.. 17 IT HELPS PEOPLE DIFFING THE CHANGES 18 19.. 20 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 21 22.. 23 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 24 25.. 26 IT HELPS PEOPLE DIFFING THE CHANGES 27 28.. 29 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 30 31.. 32 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 33 34.. 35 IT HELPS PEOPLE DIFFING THE CHANGES 36 37unbound.conf(5) 38=============== 39 40Synopsis 41-------- 42 43**unbound.conf** 44 45Description 46----------- 47 48**unbound.conf** is used to configure :doc:`unbound(8)</manpages/unbound>`. 49The file format has attributes and values. 50Some attributes have attributes inside them. 51The notation is: ``attribute: value``. 52 53Comments start with ``#`` and last to the end of line. 54Empty lines are ignored as is whitespace at the beginning of a line. 55 56The utility :doc:`unbound-checkconf(8)</manpages/unbound-checkconf>` can be 57used to check ``unbound.conf`` prior to usage. 58 59Example 60------- 61 62An example config file is shown below. 63Copy this to :file:`/etc/unbound/unbound.conf` and start the server with: 64 65.. code-block:: text 66 67 $ unbound -c /etc/unbound/unbound.conf 68 69Most settings are the defaults. 70Stop the server with: 71 72.. code-block:: text 73 74 $ kill `cat /etc/unbound/unbound.pid` 75 76Below is a minimal config file. 77The source distribution contains an extensive :file:`example.conf` file with 78all the options. 79 80.. code-block:: text 81 82 # unbound.conf(5) config file for unbound(8). 83 server: 84 directory: "/etc/unbound" 85 username: unbound 86 # make sure unbound can access entropy from inside the chroot. 87 # e.g. on linux the use these commands (on BSD, devfs(8) is used): 88 # mount --bind -n /dev/urandom /etc/unbound/dev/urandom 89 # and mount --bind -n /dev/log /etc/unbound/dev/log 90 chroot: "/etc/unbound" 91 # logfile: "/etc/unbound/unbound.log" #uncomment to use logfile. 92 pidfile: "/etc/unbound/unbound.pid" 93 # verbosity: 1 # uncomment and increase to get more logging. 94 # listen on all interfaces, answer queries from the local subnet. 95 interface: 0.0.0.0 96 interface: ::0 97 access-control: 10.0.0.0/8 allow 98 access-control: 2001:DB8::/64 allow 99 100File Format 101----------- 102 103There must be whitespace between keywords. 104Attribute keywords end with a colon ``':'``. 105An attribute is followed by a value, or its containing attributes in which case 106it is referred to as a clause. 107Clauses can be repeated throughout the file (or included files) to group 108attributes under the same clause. 109 110.. _unbound.conf.include: 111 112Files can be included using the **include:** directive. 113It can appear anywhere, it accepts a single file name as argument. 114Processing continues as if the text from the included file was copied into the 115config file at that point. 116If also using :ref:`chroot<unbound.conf.chroot>`, using full path names for 117the included files works, relative pathnames for the included names work if the 118directory where the daemon is started equals its chroot/working directory or is 119specified before the include statement with :ref:`directory: 120dir<unbound.conf.directory>`. 121Wildcards can be used to include multiple files, see *glob(7)*. 122 123.. _unbound.conf.include-toplevel: 124 125For a more structural include option, the **include-toplevel:** directive can 126be used. 127This closes whatever clause is currently active (if any) and forces the use of 128clauses in the included files and right after this directive. 129 130.. _unbound.conf.server: 131 132Server Options 133^^^^^^^^^^^^^^ 134 135These options are part of the **server:** clause. 136 137 138@@UAHL@unbound.conf@verbosity@@: *<number>* 139 The verbosity level. 140 141 Level 0 142 No verbosity, only errors. 143 144 Level 1 145 Gives operational information. 146 147 Level 2 148 Gives detailed operational information including short information per 149 query. 150 151 Level 3 152 Gives query level information, output per query. 153 154 Level 4 155 Gives algorithm level information. 156 157 Level 5 158 Logs client identification for cache misses. 159 160 The verbosity can also be increased from the command line and during run 161 time via remote control. See :doc:`unbound(8)</manpages/unbound>` and 162 :doc:`unbound-control(8)</manpages/unbound-control>` respectively. 163 164 Default: 1 165 166 167@@UAHL@unbound.conf@statistics-interval@@: *<seconds>* 168 The number of seconds between printing statistics to the log for every 169 thread. 170 Disable with value ``0`` or ``""``. 171 The histogram statistics are only printed if replies were sent during the 172 statistics interval, requestlist statistics are printed for every interval 173 (but can be 0). 174 This is because the median calculation requires data to be present. 175 176 Default: 0 (disabled) 177 178 179@@UAHL@unbound.conf@statistics-cumulative@@: *<yes or no>* 180 If enabled, statistics are cumulative since starting Unbound, without 181 clearing the statistics counters after logging the statistics. 182 183 Default: no 184 185 186@@UAHL@unbound.conf@extended-statistics@@: *<yes or no>* 187 If enabled, extended statistics are printed from 188 :doc:`unbound-control(8)</manpages/unbound-control>`. 189 The counters are listed in 190 :doc:`unbound-control(8)</manpages/unbound-control>`. 191 Keeping track of more statistics takes time. 192 193 Default: no 194 195 196@@UAHL@unbound.conf@statistics-inhibit-zero@@: *<yes or no>* 197 If enabled, selected extended statistics with a value of 0 are inhibited 198 from printing with 199 :doc:`unbound-control(8)</manpages/unbound-control>`. 200 These are query types, query classes, query opcodes, answer rcodes 201 (except NOERROR, FORMERR, SERVFAIL, NXDOMAIN, NOTIMPL, REFUSED) 202 and PRZ actions. 203 204 Default: yes 205 206 207@@UAHL@unbound.conf@num-threads@@: *<number>* 208 The number of threads to create to serve clients. Use 1 for no threading. 209 210 Default: 1 211 212 213@@UAHL@unbound.conf@port@@: *<port number>* 214 The port number on which the server responds to queries. 215 216 Default: 53 217 218 219@@UAHL@unbound.conf@interface@@: *<IP address or interface name[@port]>* 220 Interface to use to connect to the network. 221 This interface is listened to for queries from clients, and answers to 222 clients are given from it. 223 Can be given multiple times to work on several interfaces. 224 If none are given the default is to listen on localhost. 225 226 If an interface name is used instead of an IP address, the list of IP 227 addresses on that interface are used. 228 The interfaces are not changed on a reload (``kill -HUP``) but only on 229 restart. 230 231 A port number can be specified with @port (without spaces between interface 232 and port number), if not specified the default port (from 233 :ref:`port<unbound.conf.port>`) is used. 234 235 236@@UAHL@unbound.conf@ip-address@@: *<IP address or interface name[@port]>* 237 Same as :ref:`interface<unbound.conf.interface>` (for ease of 238 compatibility with :external+nsd:doc:`manpages/nsd.conf`). 239 240 241@@UAHL@unbound.conf@interface-automatic@@: *<yes or no>* 242 Listen on all addresses on all (current and future) interfaces, detect the 243 source interface on UDP queries and copy them to replies. 244 This is a lot like :ref:`ip-transparent<unbound.conf.ip-transparent>`, but 245 this option services all interfaces whilst with 246 :ref:`ip-transparent<unbound.conf.ip-transparent>` you can select which 247 (future) interfaces Unbound provides service on. 248 This feature is experimental, and needs support in your OS for particular 249 socket options. 250 251 Default: no 252 253 254@@UAHL@unbound.conf@interface-automatic-ports@@: *"<string>"* 255 List the port numbers that 256 :ref:`interface-automatic<unbound.conf.interface-automatic>` listens on. 257 If empty, the default port is listened on. 258 The port numbers are separated by spaces in the string. 259 260 This can be used to have interface automatic to deal with the interface, 261 and listen on the normal port number, by including it in the list, and 262 also HTTPS or DNS-over-TLS port numbers by putting them in the list as 263 well. 264 265 Default: "" 266 267 268@@UAHL@unbound.conf@outgoing-interface@@: *<IPv4/IPv6 address or IPv6 netblock>* 269 Interface to use to connect to the network. 270 This interface is used to send queries to authoritative servers and receive 271 their replies. 272 Can be given multiple times to work on several interfaces. 273 If none are given the default (all) is used. 274 You can specify the same interfaces in 275 :ref:`interface<unbound.conf.interface>` and 276 :ref:`outgoing-interface<unbound.conf.outgoing-interface>` lines, the 277 interfaces are then used for both purposes. 278 Outgoing queries are sent via a random outgoing interface to counter 279 spoofing. 280 281 If an IPv6 netblock is specified instead of an individual IPv6 address, 282 outgoing UDP queries will use a randomised source address taken from the 283 netblock to counter spoofing. 284 Requires the IPv6 netblock to be routed to the host running Unbound, and 285 requires OS support for unprivileged non-local binds (currently only 286 supported on Linux). 287 Several netblocks may be specified with multiple 288 :ref:`outgoing-interface<unbound.conf.outgoing-interface>` options, but do 289 not specify both an individual IPv6 address and an IPv6 netblock, or the 290 randomisation will be compromised. 291 Consider combining with :ref:`prefer-ip6: yes<unbound.conf.prefer-ip6>` to 292 increase the likelihood of IPv6 nameservers being selected for queries. 293 On Linux you need these two commands to be able to use the freebind socket 294 option to receive traffic for the ip6 netblock: 295 296 .. code-block:: text 297 298 ip -6 addr add mynetblock/64 dev lo && \ 299 ip -6 route add local mynetblock/64 dev lo 300 301 302@@UAHL@unbound.conf@outgoing-range@@: *<number>* 303 Number of ports to open. 304 This number of file descriptors can be opened per thread. 305 Must be at least 1. 306 Default depends on compile options. 307 Larger numbers need extra resources from the operating system. 308 For performance a very large value is best, use libevent to make this 309 possible. 310 311 Default: 4096 (libevent) / 960 (minievent) / 48 (windows) 312 313 314@@UAHL@unbound.conf@outgoing-port-permit@@: *<port number or range>* 315 Permit Unbound to open this port or range of ports for use to send queries. 316 A larger number of permitted outgoing ports increases resilience against 317 spoofing attempts. 318 Make sure these ports are not needed by other daemons. 319 By default only ports above 1024 that have not been assigned by IANA are 320 used. 321 Give a port number or a range of the form "low-high", without spaces. 322 323 The :ref:`outgoing-port-permit<unbound.conf.outgoing-port-permit>` and 324 :ref:`outgoing-port-avoid<unbound.conf.outgoing-port-avoid>` statements 325 are processed in the line order of the config file, adding the permitted 326 ports and subtracting the avoided ports from the set of allowed ports. 327 The processing starts with the non IANA allocated ports above 1024 in the 328 set of allowed ports. 329 330 331@@UAHL@unbound.conf@outgoing-port-avoid@@: *<port number or range>* 332 Do not permit Unbound to open this port or range of ports for use to send 333 queries. 334 Use this to make sure Unbound does not grab a port that another daemon 335 needs. 336 The port is avoided on all outgoing interfaces, both IPv4 and IPv6. 337 By default only ports above 1024 that have not been assigned by IANA are 338 used. 339 Give a port number or a range of the form "low-high", without spaces. 340 341 342@@UAHL@unbound.conf@outgoing-num-tcp@@: *<number>* 343 Number of outgoing TCP buffers to allocate per thread. 344 If set to 0, or if :ref:`do-tcp: no<unbound.conf.do-tcp>` is set, no TCP 345 queries to authoritative servers are done. 346 For larger installations increasing this value is a good idea. 347 348 Default: 10 349 350 351@@UAHL@unbound.conf@incoming-num-tcp@@: *<number>* 352 Number of incoming TCP buffers to allocate per thread. 353 If set to 0, or if :ref:`do-tcp: no<unbound.conf.do-tcp>` is set, no TCP 354 queries from clients are accepted. 355 For larger installations increasing this value is a good idea. 356 357 Default: 10 358 359 360@@UAHL@unbound.conf@edns-buffer-size@@: *<number>* 361 Number of bytes size to advertise as the EDNS reassembly buffer size. 362 This is the value put into datagrams over UDP towards peers. 363 The actual buffer size is determined by 364 :ref:`msg-buffer-size<unbound.conf.msg-buffer-size>` (both for TCP and 365 UDP). 366 Do not set higher than that value. 367 Setting to 512 bypasses even the most stringent path MTU problems, but is 368 seen as extreme, since the amount of TCP fallback generated is excessive 369 (probably also for this resolver, consider tuning 370 :ref:`outgoing-num-tcp<unbound.conf.outgoing-num-tcp>`). 371 372 Default: 1232 (`DNS Flag Day 2020 recommendation 373 <https://dnsflagday.net/2020/>`__) 374 375 376@@UAHL@unbound.conf@max-udp-size@@: *<number>* 377 Maximum UDP response size (not applied to TCP response). 378 65536 disables the UDP response size maximum, and uses the choice from the 379 client, always. 380 Suggested values are 512 to 4096. 381 382 Default: 1232 (same as :ref:`edns-buffer-size<unbound.conf.edns-buffer-size>`) 383 384 385@@UAHL@unbound.conf@stream-wait-size@@: *<number>* 386 Number of bytes size maximum to use for waiting stream buffers. 387 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes 388 or gigabytes (1024*1024 bytes in a megabyte). 389 As TCP and TLS streams queue up multiple results, the amount of memory used 390 for these buffers does not exceed this number, otherwise the responses are 391 dropped. 392 This manages the total memory usage of the server (under heavy use), the 393 number of requests that can be queued up per connection is also limited, 394 with further requests waiting in TCP buffers. 395 396 Default: 4m 397 398 399@@UAHL@unbound.conf@msg-buffer-size@@: *<number>* 400 Number of bytes size of the message buffers. 401 Default is 65552 bytes, enough for 64 Kb packets, the maximum DNS message 402 size. 403 No message larger than this can be sent or received. 404 Can be reduced to use less memory, but some requests for DNS data, such as 405 for huge resource records, will result in a SERVFAIL reply to the client. 406 407 Default: 65552 408 409 410@@UAHL@unbound.conf@msg-cache-size@@: *<number>* 411 Number of bytes size of the message cache. 412 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes 413 or gigabytes (1024*1024 bytes in a megabyte). 414 415 Default: 4m 416 417 418@@UAHL@unbound.conf@msg-cache-slabs@@: *<number>* 419 Number of slabs in the message cache. 420 Slabs reduce lock contention by threads. 421 Must be set to a power of 2. 422 Setting (close) to the number of cpus is a fairly good setting. 423 If left unconfigured, it will be configured automatically to be a power of 424 2 close to the number of configured threads in multi-threaded environments. 425 426 Default: (unconfigured) 427 428 429@@UAHL@unbound.conf@num-queries-per-thread@@: *<number>* 430 The number of queries that every thread will service simultaneously. 431 If more queries arrive that need servicing, and no queries can be jostled 432 out (see :ref:`jostle-timeout<unbound.conf.jostle-timeout>`), then the 433 queries are dropped. 434 This forces the client to resend after a timeout; allowing the server time 435 to work on the existing queries. 436 Default depends on compile options. 437 438 Default: 2048 (libevent) / 512 (minievent) / 24 (windows) 439 440 441@@UAHL@unbound.conf@jostle-timeout@@: *<msec>* 442 Timeout used when the server is very busy. 443 Set to a value that usually results in one roundtrip to the authority 444 servers. 445 446 If too many queries arrive, then 50% of the queries are allowed to run to 447 completion, and the other 50% are replaced with the new incoming query if 448 they have already spent more than their allowed time. 449 This protects against denial of service by slow queries or high query 450 rates. 451 452 The effect is that the qps for long-lasting queries is about: 453 454 .. code-block:: text 455 456 (num-queries-per-thread / 2) / (average time for such long queries) qps 457 458 The qps for short queries can be about: 459 460 .. code-block:: text 461 462 (num-queries-per-thread / 2) / (jostle-timeout in whole seconds) qps per thread 463 464 about (2048/2)*5 = 5120 qps by default. 465 466 Default: 200 467 468 469@@UAHL@unbound.conf@delay-close@@: *<msec>* 470 Extra delay for timeouted UDP ports before they are closed, in msec. 471 This prevents very delayed answer packets from the upstream (recursive) 472 servers from bouncing against closed ports and setting off all sort of 473 close-port counters, with eg. 1500 msec. 474 When timeouts happen you need extra sockets, it checks the ID and remote IP 475 of packets, and unwanted packets are added to the unwanted packet counter. 476 477 Default: 0 (disabled) 478 479 480@@UAHL@unbound.conf@udp-connect@@: *<yes or no>* 481 Perform *connect(2)* for UDP sockets that mitigates ICMP side channel 482 leakage. 483 484 Default: yes 485 486 487@@UAHL@unbound.conf@unknown-server-time-limit@@: *<msec>* 488 The wait time in msec for waiting for an unknown server to reply. 489 Increase this if you are behind a slow satellite link, to eg. 1128. 490 That would then avoid re-querying every initial query because it times out. 491 492 Default: 376 493 494 495@@UAHL@unbound.conf@discard-timeout@@: *<msec>* 496 The wait time in msec where recursion requests are dropped. 497 This is to stop a large number of replies from accumulating. 498 They receive no reply, the work item continues to recurse. 499 It is nice to be a bit larger than 500 :ref:`serve-expired-client-timeout<unbound.conf.serve-expired-client-timeout>` 501 if that is enabled. 502 A value of ``1900`` msec is suggested. 503 The value ``0`` disables it. 504 505 Default: 1900 506 507 508@@UAHL@unbound.conf@wait-limit@@: *<number>* 509 The number of replies that can wait for recursion, for an IP address. 510 This makes a ratelimit per IP address of waiting replies for recursion. 511 It stops very large amounts of queries waiting to be returned to one 512 destination. 513 The value ``0`` disables wait limits. 514 515 Default: 1000 516 517 518@@UAHL@unbound.conf@wait-limit-cookie@@: *<number>* 519 The number of replies that can wait for recursion, for an IP address 520 that sent the query with a valid DNS Cookie. 521 Since the cookie validates the client address, this limit can be higher. 522 523 Default: 10000 524 525 526@@UAHL@unbound.conf@wait-limit-netblock@@: *<netblock>* *<number>* 527 The wait limit for the netblock. 528 If not given the 529 :ref:`wait-limit<unbound.conf.wait-limit>` 530 value is used. 531 The most specific netblock is used to determine the limit. 532 Useful for overriding the default for a specific, group or individual, 533 server. 534 The value ``-1`` disables wait limits for the netblock. 535 By default the loopback has a wait limit netblock of ``-1``, it is not 536 limited, because it is separated from the rest of network for spoofed 537 packets. 538 The loopback addresses ``127.0.0.0/8`` and ``::1/128`` are default at ``-1``. 539 540 Default: (none) 541 542 543@@UAHL@unbound.conf@wait-limit-cookie-netblock@@: *<netblock>* *<number>* 544 The wait limit for the netblock, when the query has a DNS Cookie. 545 If not given, the 546 :ref:`wait-limit-cookie<unbound.conf.wait-limit-cookie>` 547 value is used. 548 The value ``-1`` disables wait limits for the netblock. 549 The loopback addresses ``127.0.0.0/8`` and ``::1/128`` are default at ``-1``. 550 551 Default: (none) 552 553 554@@UAHL@unbound.conf@so-rcvbuf@@: *<number>* 555 If not 0, then set the SO_RCVBUF socket option to get more buffer space on 556 UDP port 53 incoming queries. 557 So that short spikes on busy servers do not drop packets (see counter in 558 ``netstat -su``). 559 Otherwise, the number of bytes to ask for, try "4m" on a busy server. 560 561 The OS caps it at a maximum, on linux Unbound needs root permission to 562 bypass the limit, or the admin can use ``sysctl net.core.rmem_max``. 563 564 On BSD change ``kern.ipc.maxsockbuf`` in ``/etc/sysctl.conf``. 565 566 On OpenBSD change header and recompile kernel. 567 568 On Solaris ``ndd -set /dev/udp udp_max_buf 8388608``. 569 570 Default: 0 (use system value) 571 572 573@@UAHL@unbound.conf@so-sndbuf@@: *<number>* 574 If not 0, then set the SO_SNDBUF socket option to get more buffer space on 575 UDP port 53 outgoing queries. 576 This for very busy servers handles spikes in answer traffic, otherwise: 577 578 .. code-block:: text 579 580 send: resource temporarily unavailable 581 582 can get logged, the buffer overrun is also visible by ``netstat -su``. 583 If set to 0 it uses the system value. 584 Specify the number of bytes to ask for, try "8m" on a very busy server. 585 586 It needs some space to be able to deal with packets that wait for local 587 address resolution, from like ARP and NDP discovery, before they are sent 588 out, hence it is elevated above the system default by default. 589 590 The OS caps it at a maximum, on linux Unbound needs root permission to 591 bypass the limit, or the admin can use ``sysctl net.core.wmem_max``. 592 593 On BSD, Solaris changes are similar to 594 :ref:`so-rcvbuf<unbound.conf.so-rcvbuf>`. 595 596 Default: 4m 597 598 599@@UAHL@unbound.conf@so-reuseport@@: *<yes or no>* 600 If yes, then open dedicated listening sockets for incoming queries for each 601 thread and try to set the SO_REUSEPORT socket option on each socket. 602 May distribute incoming queries to threads more evenly. 603 604 On Linux it is supported in kernels >= 3.9. 605 606 On other systems, FreeBSD, OSX it may also work. 607 608 You can enable it (on any platform and kernel), it then attempts to open 609 the port and passes the option if it was available at compile time, if that 610 works it is used, if it fails, it continues silently (unless verbosity 3) 611 without the option. 612 613 At extreme load it could be better to turn it off to distribute the queries 614 evenly, reported for Linux systems (4.4.x). 615 616 Default: yes 617 618 619@@UAHL@unbound.conf@ip-transparent@@: *<yes or no>* 620 If yes, then use IP_TRANSPARENT socket option on sockets where Unbound is 621 listening for incoming traffic. 622 Allows you to bind to non-local interfaces. 623 For example for non-existent IP addresses that are going to exist later on, 624 with host failover configuration. 625 626 This is a lot like 627 :ref:`interface-automatic<unbound.conf.interface-automatic>`, but that one 628 services all interfaces and with this option you can select which (future) 629 interfaces Unbound provides service on. 630 631 This option needs Unbound to be started with root permissions on some 632 systems. 633 The option uses IP_BINDANY on FreeBSD systems and SO_BINDANY on OpenBSD 634 systems. 635 636 Default: no 637 638 639@@UAHL@unbound.conf@ip-freebind@@: *<yes or no>* 640 If yes, then use IP_FREEBIND socket option on sockets where Unbound is 641 listening to incoming traffic. 642 Allows you to bind to IP addresses that are nonlocal or do not exist, like 643 when the network interface or IP address is down. 644 645 Exists only on Linux, where the similar 646 :ref:`ip-transparent<unbound.conf.ip-transparent>` option is also 647 available. 648 649 Default: no 650 651 652@@UAHL@unbound.conf@ip-dscp@@: *<number>* 653 The value of the Differentiated Services Codepoint (DSCP) in the 654 differentiated services field (DS) of the outgoing IP packet headers. 655 The field replaces the outdated IPv4 Type-Of-Service field and the IPv6 656 traffic class field. 657 658 659@@UAHL@unbound.conf@rrset-cache-size@@: *<number>* 660 Number of bytes size of the RRset cache. 661 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes 662 or gigabytes (1024*1024 bytes in a megabyte). 663 664 Default: 4m 665 666 667@@UAHL@unbound.conf@rrset-cache-slabs@@: *<number>* 668 Number of slabs in the RRset cache. 669 Slabs reduce lock contention by threads. 670 Must be set to a power of 2. 671 Setting (close) to the number of cpus is a fairly good setting. 672 If left unconfigured, it will be configured automatically to be a power of 673 2 close to the number of configured threads in multi-threaded environments. 674 675 Default: (unconfigured) 676 677 678@@UAHL@unbound.conf@cache-max-ttl@@: *<seconds>* 679 Time to live maximum for RRsets and messages in the cache. 680 When the TTL expires, the cache item has expired. 681 Can be set lower to force the resolver to query for data often, and not 682 trust (very large) TTL values. 683 Downstream clients also see the lower TTL. 684 685 686 Default: 86400 (1 day) 687 688 689@@UAHL@unbound.conf@cache-min-ttl@@: *<seconds>* 690 Time to live minimum for RRsets and messages in the cache. 691 If the minimum kicks in, the data is cached for longer than the domain 692 owner intended, and thus less queries are made to look up the data. 693 Zero makes sure the data in the cache is as the domain owner intended, 694 higher values, especially more than an hour or so, can lead to trouble as 695 the data in the cache does not match up with the actual data any more. 696 697 Default: 0 (disabled) 698 699 700@@UAHL@unbound.conf@cache-max-negative-ttl@@: *<seconds>* 701 Time to live maximum for negative responses, these have a SOA in the 702 authority section that is limited in time. 703 This applies to NXDOMAIN and NODATA answers. 704 705 Default: 3600 706 707 708@@UAHL@unbound.conf@cache-min-negative-ttl@@: *<seconds>* 709 Time to live minimum for negative responses, these have a SOA in the 710 authority section that is limited in time. 711 If this is disabled and 712 :ref:`cache-min-ttl<unbound.conf.cache-min-ttl>` 713 is configured, it will take effect instead. 714 In that case you can set this to ``1`` to honor the upstream TTL. 715 This applies to NXDOMAIN and NODATA answers. 716 717 Default: 0 (disabled) 718 719 720@@UAHL@unbound.conf@infra-host-ttl@@: *<seconds>* 721 Time to live for entries in the host cache. 722 The host cache contains roundtrip timing, lameness and EDNS support 723 information. 724 725 Default: 900 726 727 728@@UAHL@unbound.conf@infra-cache-slabs@@: *<number>* 729 Number of slabs in the infrastructure cache. 730 Slabs reduce lock contention by threads. 731 Must be set to a power of 2. 732 Setting (close) to the number of cpus is a fairly good setting. 733 If left unconfigured, it will be configured automatically to be a power of 734 2 close to the number of configured threads in multi-threaded environments. 735 736 Default: (unconfigured) 737 738 739@@UAHL@unbound.conf@infra-cache-numhosts@@: *<number>* 740 Number of hosts for which information is cached. 741 742 Default: 10000 743 744 745@@UAHL@unbound.conf@infra-cache-min-rtt@@: *<msec>* 746 Lower limit for dynamic retransmit timeout calculation in infrastructure 747 cache. 748 Increase this value if using forwarders needing more time to do recursive 749 name resolution. 750 751 Default: 50 752 753 754@@UAHL@unbound.conf@infra-cache-max-rtt@@: *<msec>* 755 Upper limit for dynamic retransmit timeout calculation in infrastructure 756 cache. 757 758 Default: 120000 (2 minutes) 759 760 761@@UAHL@unbound.conf@infra-keep-probing@@: *<yes or no>* 762 If enabled the server keeps probing hosts that are down, in the one probe 763 at a time regime. 764 Hosts that are down, eg. they did not respond during the one probe at a 765 time period, are marked as down and it may take 766 :ref:`infra-host-ttl<unbound.conf.infra-host-ttl>` time to get probed 767 again. 768 769 Default: no 770 771 772@@UAHL@unbound.conf@define-tag@@: *"<list of tags>"* 773 Define the tags that can be used with 774 :ref:`local-zone<unbound.conf.local-zone>` and 775 :ref:`access-control<unbound.conf.access-control>`. 776 Enclose the list between quotes (``""``) and put spaces between tags. 777 778 779@@UAHL@unbound.conf@do-ip4@@: *<yes or no>* 780 Enable or disable whether IPv4 queries are answered or issued. 781 782 Default: yes 783 784 785@@UAHL@unbound.conf@do-ip6@@: *<yes or no>* 786 Enable or disable whether IPv6 queries are answered or issued. 787 If disabled, queries are not answered on IPv6, and queries are not sent on 788 IPv6 to the internet nameservers. 789 With this option you can disable the IPv6 transport for sending DNS 790 traffic, it does not impact the contents of the DNS traffic, which may have 791 IPv4 (A) and IPv6 (AAAA) addresses in it. 792 793 Default: yes 794 795 796@@UAHL@unbound.conf@prefer-ip4@@: *<yes or no>* 797 If enabled, prefer IPv4 transport for sending DNS queries to internet 798 nameservers. 799 Useful if the IPv6 netblock the server has, the entire /64 of that is not 800 owned by one operator and the reputation of the netblock /64 is an issue, 801 using IPv4 then uses the IPv4 filters that the upstream servers have. 802 803 Default: no 804 805 806@@UAHL@unbound.conf@prefer-ip6@@: *<yes or no>* 807 If enabled, prefer IPv6 transport for sending DNS queries to internet 808 nameservers. 809 810 Default: no 811 812 813@@UAHL@unbound.conf@do-udp@@: *<yes or no>* 814 Enable or disable whether UDP queries are answered or issued. 815 816 Default: yes 817 818 819@@UAHL@unbound.conf@do-tcp@@: *<yes or no>* 820 Enable or disable whether TCP queries are answered or issued. 821 822 Default: yes 823 824 825@@UAHL@unbound.conf@tcp-mss@@: *<number>* 826 Maximum segment size (MSS) of TCP socket on which the server responds to 827 queries. 828 Value lower than common MSS on Ethernet (1220 for example) will address 829 path MTU problem. 830 Note that not all platform supports socket option to set MSS (TCP_MAXSEG). 831 Default is system default MSS determined by interface MTU and negotiation 832 between server and client. 833 834 835@@UAHL@unbound.conf@outgoing-tcp-mss@@: *<number>* 836 Maximum segment size (MSS) of TCP socket for outgoing queries (from Unbound 837 to other servers). 838 Value lower than common MSS on Ethernet (1220 for example) will address 839 path MTU problem. 840 Note that not all platform supports socket option to set MSS (TCP_MAXSEG). 841 Default is system default MSS determined by interface MTU and negotiation 842 between Unbound and other servers. 843 844 845@@UAHL@unbound.conf@tcp-idle-timeout@@: *<msec>* 846 The period Unbound will wait for a query on a TCP connection. 847 If this timeout expires Unbound closes the connection. 848 When the number of free incoming TCP buffers falls below 50% of the total 849 number configured, the option value used is progressively reduced, first to 850 1% of the configured value, then to 0.2% of the configured value if the 851 number of free buffers falls below 35% of the total number configured, and 852 finally to 0 if the number of free buffers falls below 20% of the total 853 number configured. 854 A minimum timeout of 200 milliseconds is observed regardless of the option 855 value used. 856 It will be overridden by 857 :ref:`edns-tcp-keepalive-timeout<unbound.conf.edns-tcp-keepalive-timeout>` 858 if 859 :ref:`edns-tcp-keepalive<unbound.conf.edns-tcp-keepalive>` 860 is enabled. 861 862 Default: 30000 (30 seconds) 863 864 865@@UAHL@unbound.conf@tcp-reuse-timeout@@: *<msec>* 866 The period Unbound will keep TCP persistent connections open to authority 867 servers. 868 869 Default: 60000 (60 seconds) 870 871 872@@UAHL@unbound.conf@max-reuse-tcp-queries@@: *<number>* 873 The maximum number of queries that can be sent on a persistent TCP 874 connection. 875 876 Default: 200 877 878 879@@UAHL@unbound.conf@tcp-auth-query-timeout@@: *<number>* 880 Timeout in milliseconds for TCP queries to auth servers. 881 882 Default: 3000 (3 seconds) 883 884 885@@UAHL@unbound.conf@edns-tcp-keepalive@@: *<yes or no>* 886 Enable or disable EDNS TCP Keepalive. 887 888 Default: no 889 890 891@@UAHL@unbound.conf@edns-tcp-keepalive-timeout@@: *<msec>* 892 Overrides 893 :ref:`tcp-idle-timeout<unbound.conf.tcp-idle-timeout>` 894 when 895 :ref:`edns-tcp-keepalive<unbound.conf.edns-tcp-keepalive>` 896 is enabled. 897 If the client supports the EDNS TCP Keepalive option, 898 If the client supports the EDNS TCP Keepalive option, Unbound sends the 899 timeout value to the client to encourage it to close the connection before 900 the server times out. 901 902 Default: 120000 (2 minutes) 903 904 905@@UAHL@unbound.conf@sock-queue-timeout@@: *<sec>* 906 UDP queries that have waited in the socket buffer for a long time can be 907 dropped. 908 The time is set in seconds, 3 could be a good value to ignore old queries 909 that likely the client does not need a reply for any more. 910 This could happen if the host has not been able to service the queries for 911 a while, i.e. Unbound is not running, and then is enabled again. 912 It uses timestamp socket options. 913 The socket option is available on the Linux and FreeBSD platforms. 914 915 Default: 0 (disabled) 916 917 918@@UAHL@unbound.conf@tcp-upstream@@: *<yes or no>* 919 Enable or disable whether the upstream queries use TCP only for transport. 920 Useful in tunneling scenarios. 921 If set to no you can specify TCP transport only for selected forward or 922 stub zones using 923 :ref:`forward-tcp-upstream<unbound.conf.forward.forward-tcp-upstream>` or 924 :ref:`stub-tcp-upstream<unbound.conf.stub.stub-tcp-upstream>` 925 respectively. 926 927 Default: no 928 929 930@@UAHL@unbound.conf@udp-upstream-without-downstream@@: *<yes or no>* 931 Enable UDP upstream even if :ref:`do-udp: no<unbound.conf.do-udp>` is set. 932 Useful for TLS service providers, that want no UDP downstream but use UDP 933 to fetch data upstream. 934 935 Default: no (no changes) 936 937 938@@UAHL@unbound.conf@tls-upstream@@: *<yes or no>* 939 Enabled or disable whether the upstream queries use TLS only for transport. 940 Useful in tunneling scenarios. 941 The TLS contains plain DNS in TCP wireformat. 942 The other server must support this (see 943 :ref:`tls-service-key<unbound.conf.tls-service-key>`). 944 945 If you enable this, also configure a 946 :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>` or use 947 :ref:`tls-win-cert<unbound.conf.tls-win-cert>` or 948 :ref:`tls-system-cert<unbound.conf.tls-system-cert>` to load CA certs, 949 otherwise the connections cannot be authenticated. 950 951 This option enables TLS for all of them, but if you do not set this you can 952 configure TLS specifically for some forward zones with 953 :ref:`forward-tls-upstream<unbound.conf.forward.forward-tls-upstream>`. 954 And also with 955 :ref:`stub-tls-upstream<unbound.conf.stub.stub-tls-upstream>`. 956 If the 957 :ref:`tls-upstream<unbound.conf.tls-upstream>` 958 option is enabled, it is for all the forwards and stubs, where the 959 :ref:`forward-tls-upstream<unbound.conf.forward.forward-tls-upstream>` 960 and 961 :ref:`stub-tls-upstream<unbound.conf.stub.stub-tls-upstream>` 962 options are ignored, as if they had been set to yes. 963 964 Default: no 965 966 967@@UAHL@unbound.conf@ssl-upstream@@: *<yes or no>* 968 Alternate syntax for :ref:`tls-upstream<unbound.conf.tls-upstream>`. 969 If both are present in the config file the last is used. 970 971 972@@UAHL@unbound.conf@tls-service-key@@: *<file>* 973 If enabled, the server provides DNS-over-TLS or DNS-over-HTTPS service on 974 the TCP ports marked implicitly or explicitly for these services with 975 :ref:`tls-port<unbound.conf.tls-port>` or 976 :ref:`https-port<unbound.conf.https-port>`. 977 The file must contain the private key for the TLS session, the public 978 certificate is in the :ref:`tls-service-pem<unbound.conf.tls-service-pem>` 979 file and it must also be specified if 980 :ref:`tls-service-key<unbound.conf.tls-service-key>` is specified. 981 Enabling or disabling this service requires a restart (a reload is not 982 enough), because the key is read while root permissions are held and before 983 chroot (if any). 984 The ports enabled implicitly or explicitly via 985 :ref:`tls-port<unbound.conf.tls-port>` and 986 :ref:`https-port<unbound.conf.https-port>` do not provide normal DNS TCP 987 service. 988 989 .. note:: 990 Unbound needs to be compiled with libnghttp2 in order to provide 991 DNS-over-HTTPS. 992 993 Default: "" (disabled) 994 995 996@@UAHL@unbound.conf@ssl-service-key@@: *<file>* 997 Alternate syntax for :ref:`tls-service-key<unbound.conf.tls-service-key>`. 998 999 1000@@UAHL@unbound.conf@tls-service-pem@@: *<file>* 1001 The public key certificate pem file for the tls service. 1002 1003 Default: "" (disabled) 1004 1005 1006@@UAHL@unbound.conf@ssl-service-pem@@: *<file>* 1007 Alternate syntax for :ref:`tls-service-pem<unbound.conf.tls-service-pem>`. 1008 1009 1010@@UAHL@unbound.conf@tls-port@@: *<number>* 1011 The port number on which to provide TCP TLS service. 1012 Only interfaces configured with that port number as @number get the TLS 1013 service. 1014 1015 Default: 853 1016 1017 1018@@UAHL@unbound.conf@ssl-port@@: *<number>* 1019 Alternate syntax for :ref:`tls-port<unbound.conf.tls-port>`. 1020 1021 1022@@UAHL@unbound.conf@tls-cert-bundle@@: *<file>* 1023 If null or ``""``, no file is used. 1024 Set it to the certificate bundle file, for example 1025 :file:`/etc/pki/tls/certs/ca-bundle.crt`. 1026 These certificates are used for authenticating connections made to outside 1027 peers. 1028 For example :ref:`auth-zone urls<unbound.conf.auth.url>`, and also 1029 DNS-over-TLS connections. 1030 It is read at start up before permission drop and chroot. 1031 1032 Default: "" (disabled) 1033 1034 1035@@UAHL@unbound.conf@ssl-cert-bundle@@: *<file>* 1036 Alternate syntax for :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>`. 1037 1038 1039@@UAHL@unbound.conf@tls-win-cert@@: *<yes or no>* 1040 Add the system certificates to the cert bundle certificates for 1041 authentication. 1042 If no cert bundle, it uses only these certificates. 1043 On windows this option uses the certificates from the cert store. 1044 Use the :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>` option on 1045 other systems. 1046 On other systems, this option enables the system certificates. 1047 1048 Default: no 1049 1050 1051@@UAHL@unbound.conf@tls-system-cert@@: *<yes or no>* 1052 This the same attribute as the 1053 :ref:`tls-win-cert<unbound.conf.tls-win-cert>` attribute, under a 1054 different name. 1055 Because it is not windows specific. 1056 1057 1058@@UAHL@unbound.conf@tls-additional-port@@: *<portnr>* 1059 List port numbers as 1060 :ref:`tls-additional-port<unbound.conf.tls-additional-port>`, and when 1061 interfaces are defined, eg. with the @port suffix, as this port number, 1062 they provide DNS-over-TLS service. 1063 Can list multiple, each on a new statement. 1064 1065 1066@@UAHL@unbound.conf@tls-session-ticket-keys@@: *<file>* 1067 If not ``""``, lists files with 80 bytes of random contents that are used 1068 to perform TLS session resumption for clients using the Unbound server. 1069 These files contain the secret key for the TLS session tickets. 1070 First key use to encrypt and decrypt TLS session tickets. 1071 Other keys use to decrypt only. 1072 1073 With this you can roll over to new keys, by generating a new first file and 1074 allowing decrypt of the old file by listing it after the first file for 1075 some time, after the wait clients are not using the old key any more and 1076 the old key can be removed. 1077 One way to create the file is: 1078 1079 .. code-block:: text 1080 1081 dd if=/dev/random bs=1 count=80 of=ticket.dat 1082 1083 The first 16 bytes should be different from the old one if you create a 1084 second key, that is the name used to identify the key. 1085 Then there is 32 bytes random data for an AES key and then 32 bytes random 1086 data for the HMAC key. 1087 1088 Default: "" 1089 1090 1091@@UAHL@unbound.conf@tls-ciphers@@: *<string with cipher list>* 1092 Set the list of ciphers to allow when serving TLS. 1093 Use ``""`` for default ciphers. 1094 1095 Default: "" 1096 1097 1098@@UAHL@unbound.conf@tls-ciphersuites@@: *<string with ciphersuites list>* 1099 Set the list of ciphersuites to allow when serving TLS. 1100 This is for newer TLS 1.3 connections. 1101 Use ``""`` for default ciphersuites. 1102 1103 Default: "" 1104 1105 1106@@UAHL@unbound.conf@pad-responses@@: *<yes or no>* 1107 If enabled, TLS serviced queries that contained an EDNS Padding option will 1108 cause responses padded to the closest multiple of the size specified in 1109 :ref:`pad-responses-block-size<unbound.conf.pad-responses-block-size>`. 1110 1111 Default: yes 1112 1113 1114@@UAHL@unbound.conf@pad-responses-block-size@@: *<number>* 1115 The block size with which to pad responses serviced over TLS. 1116 Only responses to padded queries will be padded. 1117 1118 Default: 468 1119 1120 1121@@UAHL@unbound.conf@pad-queries@@: *<yes or no>* 1122 If enabled, all queries sent over TLS upstreams will be padded to the 1123 closest multiple of the size specified in 1124 :ref:`pad-queries-block-size<unbound.conf.pad-queries-block-size>`. 1125 1126 Default: yes 1127 1128 1129@@UAHL@unbound.conf@pad-queries-block-size@@: *<number>* 1130 The block size with which to pad queries sent over TLS upstreams. 1131 1132 Default: 128 1133 1134 1135@@UAHL@unbound.conf@tls-use-sni@@: *<yes or no>* 1136 Enable or disable sending the SNI extension on TLS connections. 1137 1138 .. note:: Changing the value requires a reload. 1139 1140 Default: yes 1141 1142 1143@@UAHL@unbound.conf@https-port@@: *<number>* 1144 The port number on which to provide DNS-over-HTTPS service. 1145 Only interfaces configured with that port number as @number get the HTTPS 1146 service. 1147 1148 Default: 443 1149 1150 1151@@UAHL@unbound.conf@http-endpoint@@: *<endpoint string>* 1152 The HTTP endpoint to provide DNS-over-HTTPS service on. 1153 1154 Default: /dns-query 1155 1156 1157@@UAHL@unbound.conf@http-max-streams@@: *<number of streams>* 1158 Number used in the SETTINGS_MAX_CONCURRENT_STREAMS parameter in the HTTP/2 1159 SETTINGS frame for DNS-over-HTTPS connections. 1160 1161 Default: 100 1162 1163 1164@@UAHL@unbound.conf@http-query-buffer-size@@: *<size in bytes>* 1165 Maximum number of bytes used for all HTTP/2 query buffers combined. 1166 These buffers contain (partial) DNS queries waiting for request stream 1167 completion. 1168 An RST_STREAM frame will be send to streams exceeding this limit. 1169 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes 1170 or gigabytes (1024*1024 bytes in a megabyte). 1171 1172 Default: 4m 1173 1174 1175@@UAHL@unbound.conf@http-response-buffer-size@@: *<size in bytes>* 1176 Maximum number of bytes used for all HTTP/2 response buffers combined. 1177 These buffers contain DNS responses waiting to be written back to the 1178 clients. 1179 An RST_STREAM frame will be send to streams exceeding this limit. 1180 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes 1181 or gigabytes (1024*1024 bytes in a megabyte). 1182 1183 Default: 4m 1184 1185 1186@@UAHL@unbound.conf@http-nodelay@@: *<yes or no>* 1187 Set TCP_NODELAY socket option on sockets used to provide DNS-over-HTTPS 1188 service. 1189 Ignored if the option is not available. 1190 1191 Default: yes 1192 1193 1194@@UAHL@unbound.conf@http-notls-downstream@@: *<yes or no>* 1195 Disable use of TLS for the downstream DNS-over-HTTP connections. 1196 Useful for local back end servers. 1197 1198 Default: no 1199 1200 1201@@UAHL@unbound.conf@proxy-protocol-port@@: *<portnr>* 1202 List port numbers as 1203 :ref:`proxy-protocol-port<unbound.conf.proxy-protocol-port>`, and when 1204 interfaces are defined, eg. with the @port suffix, as this port number, 1205 they support and expect PROXYv2. 1206 1207 In this case the proxy address will only be used for the network 1208 communication and initial ACL (check if the proxy itself is denied/refused 1209 by configuration). 1210 1211 The proxied address (if any) will then be used as the true client address 1212 and will be used where applicable for logging, ACL, DNSTAP, RPZ and IP 1213 ratelimiting. 1214 1215 PROXYv2 is supported for UDP and TCP/TLS listening interfaces. 1216 1217 There is no support for PROXYv2 on a DoH, DoQ or DNSCrypt listening interface. 1218 1219 Can list multiple, each on a new statement. 1220 1221 1222@@UAHL@unbound.conf@quic-port@@: *<number>* 1223 The port number on which to provide DNS-over-QUIC service. 1224 Only interfaces configured with that port number as @number get the QUIC 1225 service. 1226 The interface uses QUIC for the UDP traffic on that port number. 1227 1228 Default: 853 1229 1230 1231@@UAHL@unbound.conf@quic-size@@: *<size in bytes>* 1232 Maximum number of bytes for all QUIC buffers and data combined. 1233 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes 1234 or gigabytes (1024*1024 bytes in a megabyte). 1235 New connections receive connection refused when the limit is exceeded. 1236 New streams are reset when the limit is exceeded. 1237 1238 Default: 8m 1239 1240 1241@@UAHL@unbound.conf@use-systemd@@: *<yes or no>* 1242 Enable or disable systemd socket activation. 1243 1244 Default: no 1245 1246 1247@@UAHL@unbound.conf@do-daemonize@@: *<yes or no>* 1248 Enable or disable whether the Unbound server forks into the background as a 1249 daemon. 1250 Set the value to no when Unbound runs as systemd service. 1251 1252 Default: yes 1253 1254 1255@@UAHL@unbound.conf@tcp-connection-limit@@: *<IP netblock> <limit>* 1256 Allow up to limit simultaneous TCP connections from the given netblock. 1257 When at the limit, further connections are accepted but closed immediately. 1258 This option is experimental at this time. 1259 1260 Default: (disabled) 1261 1262 1263@@UAHL@unbound.conf@access-control@@: *<IP netblock> <action>* 1264 Specify treatment of incoming queries from their originating IP address. 1265 Queries can be allowed to have access to this server that gives DNS 1266 answers, or refused, with other actions possible. 1267 The IP address range can be specified as a netblock, it is possible to give 1268 the statement several times in order to specify the treatment of different 1269 netblocks. 1270 The netblock is given as an IPv4 or IPv6 address with /size appended for a 1271 classless network block. 1272 The most specific netblock match is used, if none match 1273 :ref:`refuse<unbound.conf.access-control.action.refuse>` is used. 1274 The order of the access-control statements therefore does not matter. 1275 The action can be 1276 :ref:`deny<unbound.conf.access-control.action.deny>`, 1277 :ref:`refuse<unbound.conf.access-control.action.refuse>`, 1278 :ref:`allow<unbound.conf.access-control.action.allow>`, 1279 :ref:`allow_setrd<unbound.conf.access-control.action.allow_setrd>`, 1280 :ref:`allow_snoop<unbound.conf.access-control.action.allow_snoop>`, 1281 :ref:`allow_cookie<unbound.conf.access-control.action.allow_cookie>`, 1282 :ref:`deny_non_local<unbound.conf.access-control.action.deny_non_local>` or 1283 :ref:`refuse_non_local<unbound.conf.access-control.action.refuse_non_local>`. 1284 1285 1286 @@UAHL@unbound.conf.access-control.action@deny@@ 1287 Stops queries from hosts from that netblock. 1288 1289 @@UAHL@unbound.conf.access-control.action@refuse@@ 1290 Stops queries too, but sends a DNS rcode REFUSED error message back. 1291 1292 @@UAHL@unbound.conf.access-control.action@allow@@ 1293 Gives access to clients from that netblock. 1294 It gives only access for recursion clients (which is what almost all 1295 clients need). 1296 Non-recursive queries are refused. 1297 1298 The :ref:`allow<unbound.conf.access-control.action.allow>` action does 1299 allow non-recursive queries to access the local-data that is 1300 configured. 1301 The reason is that this does not involve the Unbound server recursive 1302 lookup algorithm, and static data is served in the reply. 1303 This supports normal operations where non-recursive queries are made 1304 for the authoritative data. 1305 For non-recursive queries any replies from the dynamic cache are 1306 refused. 1307 1308 @@UAHL@unbound.conf.access-control.action@allow_setrd@@ 1309 Ignores the recursion desired (RD) bit and treats all requests as if 1310 the recursion desired bit is set. 1311 1312 Note that this behavior violates :rfc:`1034` which states that a name 1313 server should never perform recursive service unless asked via the RD 1314 bit since this interferes with trouble shooting of name servers and 1315 their databases. 1316 This prohibited behavior may be useful if another DNS server must 1317 forward requests for specific zones to a resolver DNS server, but only 1318 supports stub domains and sends queries to the resolver DNS server with 1319 the RD bit cleared. 1320 1321 @@UAHL@unbound.conf.access-control.action@allow_snoop@@ 1322 Gives non-recursive access too. 1323 This gives both recursive and non recursive access. 1324 The name *allow_snoop* refers to cache snooping, a technique to use 1325 non-recursive queries to examine the cache contents (for malicious 1326 acts). 1327 However, non-recursive queries can also be a valuable debugging tool 1328 (when you want to examine the cache contents). 1329 1330 In that case use 1331 :ref:`allow_snoop<unbound.conf.access-control.action.allow_snoop>` for 1332 your administration host. 1333 1334 @@UAHL@unbound.conf.access-control.action@allow_cookie@@ 1335 Allows access only to UDP queries that contain a valid DNS Cookie as 1336 specified in RFC 7873 and RFC 9018, when the 1337 :ref:`answer-cookie<unbound.conf.answer-cookie>` option is enabled. 1338 UDP queries containing only a DNS Client Cookie and no Server Cookie, 1339 or an invalid DNS Cookie, will receive a BADCOOKIE response including a 1340 newly generated DNS Cookie, allowing clients to retry with that DNS 1341 Cookie. 1342 The *allow_cookie* action will also accept requests over stateful 1343 transports, regardless of the presence of an DNS Cookie and regardless 1344 of the :ref:`answer-cookie<unbound.conf.answer-cookie>` setting. 1345 UDP queries without a DNS Cookie receive REFUSED responses with the TC 1346 flag set, that may trigger fall back to TCP for those clients. 1347 1348 @@UAHL@unbound.conf.access-control.action@deny_non_local@@ 1349 The 1350 :ref:`deny_non_local<unbound.conf.access-control.action.deny_non_local>` 1351 action is for hosts that are only allowed to query for the 1352 authoritative :ref:`local-data<unbound.conf.local-data>`, they are not 1353 allowed full recursion but only the static data. 1354 Messages that are disallowed are dropped. 1355 1356 @@UAHL@unbound.conf.access-control.action@refuse_non_local@@ 1357 The 1358 :ref:`refuse_non_local<unbound.conf.access-control.action.refuse_non_local>` 1359 action is for hosts that are only allowed to query for the 1360 authoritative :ref:`local-data<unbound.conf.local-data>`, they are not 1361 allowed full recursion but only the static data. 1362 Messages that are disallowed receive error code REFUSED. 1363 1364 1365 By default only localhost (the 127.0.0.0/8 IP netblock, not the loopback 1366 interface) is implicitly *allowed*, the rest is refused. 1367 The default is *refused*, because that is protocol-friendly. 1368 The DNS protocol is not designed to handle dropped packets due to policy, 1369 and dropping may result in (possibly excessive) retried queries. 1370 1371 1372@@UAHL@unbound.conf@access-control-tag@@: *<IP netblock> "<list of tags>"* 1373 Assign tags to :ref:`access-control<unbound.conf.access-control>` 1374 elements. 1375 Clients using this access control element use localzones that are tagged 1376 with one of these tags. 1377 1378 Tags must be defined in :ref:`define-tag<unbound.conf.define-tag>`. 1379 Enclose list of tags in quotes (``""``) and put spaces between tags. 1380 1381 If :ref:`access-control-tag<unbound.conf.access-control-tag>` is 1382 configured for a netblock that does not have an 1383 :ref:`access-control<unbound.conf.access-control>`, an access-control 1384 element with action :ref:`allow<unbound.conf.access-control.action.allow>` 1385 is configured for this netblock. 1386 1387 1388@@UAHL@unbound.conf@access-control-tag-action@@: *<IP netblock> <tag> <action>* 1389 Set action for particular tag for given access control element. 1390 If you have multiple tag values, the tag used to lookup the action is the 1391 first tag match between 1392 :ref:`access-control-tag<unbound.conf.access-control-tag>` and 1393 :ref:`local-zone-tag<unbound.conf.local-zone-tag>` where "first" comes 1394 from the order of the :ref:`define-tag<unbound.conf.define-tag>` values. 1395 1396 1397@@UAHL@unbound.conf@access-control-tag-data@@: *<IP netblock> <tag> "<resource record string>"* 1398 Set redirect data for particular tag for given access control element. 1399 1400 1401@@UAHL@unbound.conf@access-control-view@@: *<IP netblock> <view name>* 1402 Set view for given access control element. 1403 1404 1405@@UAHL@unbound.conf@interface-action@@: *<ip address or interface name [@port]> <action>* 1406 Similar to :ref:`access-control<unbound.conf.access-control>` but for 1407 interfaces. 1408 1409 The action is the same as the ones defined under 1410 :ref:`access-control<unbound.conf.access-control>`. 1411 1412 Default action for interfaces is 1413 :ref:`refuse<unbound.conf.access-control.action.refuse>`. 1414 By default only localhost (the 127.0.0.0/8 IP netblock, not the loopback 1415 interface) is implicitly allowed through the default 1416 :ref:`access-control<unbound.conf.access-control>` behavior. 1417 This also means that any attempt to use the **interface-\*:** options for 1418 the loopback interface will not work as they will be overridden by the 1419 implicit default "access-control: 127.0.0.0/8 allow" option. 1420 1421 .. note:: 1422 The interface needs to be already specified with 1423 :ref:`interface<unbound.conf.interface>` and that any 1424 **access-control\*:** attribute overrides all **interface-\*:** 1425 attributes for targeted clients. 1426 1427 1428@@UAHL@unbound.conf@interface-tag@@: *<ip address or interface name [@port]> <"list of tags">* 1429 Similar to :ref:`access-control-tag<unbound.conf.access-control-tag>` but 1430 for interfaces. 1431 1432 .. note:: 1433 The interface needs to be already specified with 1434 :ref:`interface<unbound.conf.interface>` and that any 1435 **access-control\*:** attribute overrides all **interface-\*:** 1436 attributes for targeted clients. 1437 1438 1439@@UAHL@unbound.conf@interface-tag-action@@: *<ip address or interface name [@port]> <tag> <action>* 1440 Similar to 1441 :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>` 1442 but for interfaces. 1443 1444 .. note:: 1445 The interface needs to be already specified with 1446 :ref:`interface<unbound.conf.interface>` and that any 1447 **access-control\*:** attribute overrides all **interface-\*:** 1448 attributes for targeted clients. 1449 1450 1451@@UAHL@unbound.conf@interface-tag-data@@: *<ip address or interface name [@port]> <tag> <"resource record string">* 1452 Similar to 1453 :ref:`access-control-tag-data<unbound.conf.access-control-tag-data>` but 1454 for interfaces. 1455 1456 .. note:: 1457 The interface needs to be already specified with 1458 :ref:`interface<unbound.conf.interface>` and that any 1459 **access-control\*:** attribute overrides all **interface-\*:** 1460 attributes for targeted clients. 1461 1462 1463@@UAHL@unbound.conf@interface-view@@: *<ip address or interface name [@port]> <view name>* 1464 Similar to :ref:`access-control-view<unbound.conf.access-control-view>` 1465 but for interfaces. 1466 1467 .. note:: 1468 The interface needs to be already specified with 1469 :ref:`interface<unbound.conf.interface>` and that any 1470 **access-control\*:** attribute overrides all **interface-\*:** 1471 attributes for targeted clients. 1472 1473 1474@@UAHL@unbound.conf@chroot@@: *<directory>* 1475 If :ref:`chroot<unbound.conf.chroot>` is enabled, you should pass the 1476 configfile (from the commandline) as a full path from the original root. 1477 After the chroot has been performed the now defunct portion of the config 1478 file path is removed to be able to reread the config after a reload. 1479 1480 All other file paths (working dir, logfile, roothints, and key files) can 1481 be specified in several ways: as an absolute path relative to the new root, 1482 as a relative path to the working directory, or as an absolute path 1483 relative to the original root. 1484 In the last case the path is adjusted to remove the unused portion. 1485 1486 The pidfile can be either a relative path to the working directory, or an 1487 absolute path relative to the original root. 1488 It is written just prior to chroot and dropping permissions. 1489 This allows the pidfile to be :file:`/var/run/unbound.pid` and the chroot 1490 to be :file:`/var/unbound`, for example. 1491 Note that Unbound is not able to remove the pidfile after termination when 1492 it is located outside of the chroot directory. 1493 1494 Additionally, Unbound may need to access :file:`/dev/urandom` (for entropy) 1495 from inside the chroot. 1496 1497 If given, a *chroot(2)* is done to the given directory. 1498 If you give ``""`` no *chroot(2)* is performed. 1499 1500 Default: @UNBOUND_CHROOT_DIR@ 1501 1502 1503@@UAHL@unbound.conf@username@@: *<name>* 1504 If given, after binding the port the user privileges are dropped. 1505 If you give username: ``""`` no user change is performed. 1506 1507 If this user is not capable of binding the port, reloads (by signal HUP) 1508 will still retain the opened ports. 1509 If you change the port number in the config file, and that new port number 1510 requires privileges, then a reload will fail; a restart is needed. 1511 1512 Default: @UNBOUND_USERNAME@ 1513 1514 1515@@UAHL@unbound.conf@directory@@: *<directory>* 1516 Sets the working directory for the program. 1517 On Windows the string "%EXECUTABLE%" tries to change to the directory that 1518 :command:`unbound.exe` resides in. 1519 If you give a :ref:`server: directory: 1520 \<directory\><unbound.conf.directory>` before 1521 :ref:`include<unbound.conf.include>` file statements then those includes 1522 can be relative to the working directory. 1523 1524 Default: @UNBOUND_RUN_DIR@ 1525 1526 1527@@UAHL@unbound.conf@logfile@@: *<filename>* 1528 If ``""`` is given, logging goes to stderr, or nowhere once daemonized. 1529 The logfile is appended to, in the following format: 1530 1531 .. code-block:: text 1532 1533 [seconds since 1970] unbound[pid:tid]: type: message. 1534 1535 If this option is given, the :ref:`use-syslog<unbound.conf.use-syslog>` 1536 attribute is internally set to ``no``. 1537 1538 The logfile is reopened (for append) when the config file is reread, on 1539 SIGHUP. 1540 1541 Default: "" (disabled) 1542 1543 1544@@UAHL@unbound.conf@use-syslog@@: *<yes or no>* 1545 Sets Unbound to send log messages to the syslogd, using *syslog(3)*. 1546 The log facility LOG_DAEMON is used, with identity "unbound". 1547 The logfile setting is overridden when 1548 :ref:`use-syslog: yes<unbound.conf.use-syslog>` is set. 1549 1550 Default: yes 1551 1552 1553@@UAHL@unbound.conf@log-identity@@: *<string>* 1554 If ``""`` is given, then the name of the executable, usually 1555 "unbound" is used to report to the log. 1556 Enter a string to override it with that, which is useful on systems that 1557 run more than one instance of Unbound, with different configurations, so 1558 that the logs can be easily distinguished against. 1559 1560 Default: "" 1561 1562 1563@@UAHL@unbound.conf@log-time-ascii@@: *<yes or no>* 1564 Sets logfile lines to use a timestamp in UTC ASCII. 1565 No effect if using syslog, in that case syslog formats the timestamp 1566 printed into the log files. 1567 1568 Default: no (prints the seconds since 1970 in brackets) 1569 1570 1571@@UAHL@unbound.conf@log-time-iso@@: *<yes or no>* 1572 Log time in ISO8601 format, if 1573 :ref:`log-time-ascii: yes<unbound.conf.log-time-ascii>` 1574 is also set. 1575 1576 Default: no 1577 1578 1579@@UAHL@unbound.conf@log-queries@@: *<yes or no>* 1580 Prints one line per query to the log, with the log timestamp and IP 1581 address, name, type and class. 1582 Note that it takes time to print these lines which makes the server 1583 (significantly) slower. 1584 Odd (nonprintable) characters in names are printed as ``'?'``. 1585 1586 Default: no 1587 1588 1589@@UAHL@unbound.conf@log-replies@@: *<yes or no>* 1590 Prints one line per reply to the log, with the log timestamp and IP 1591 address, name, type, class, return code, time to resolve, from cache and 1592 response size. 1593 Note that it takes time to print these lines which makes the server 1594 (significantly) slower. 1595 Odd (nonprintable) characters in names are printed as ``'?'``. 1596 1597 Default: no 1598 1599 1600@@UAHL@unbound.conf@log-tag-queryreply@@: *<yes or no>* 1601 Prints the word 'query' and 'reply' with 1602 :ref:`log-queries<unbound.conf.log-queries>` and 1603 :ref:`log-replies<unbound.conf.log-replies>`. 1604 This makes filtering logs easier. 1605 1606 Default: no (backwards compatible) 1607 1608 1609@@UAHL@unbound.conf@log-destaddr@@: *<yes or no>* 1610 Prints the destination address, port and type in the 1611 :ref:`log-replies<unbound.conf.log-replies>` output. 1612 This disambiguates what type of traffic, eg. UDP or TCP, and to what local 1613 port the traffic was sent to. 1614 1615 Default: no 1616 1617 1618@@UAHL@unbound.conf@log-local-actions@@: *<yes or no>* 1619 Print log lines to inform about local zone actions. 1620 These lines are like the :ref:`local-zone type 1621 inform<unbound.conf.local-zone.type.inform>` print outs, but they are also 1622 printed for the other types of local zones. 1623 1624 Default: no 1625 1626 1627@@UAHL@unbound.conf@log-servfail@@: *<yes or no>* 1628 Print log lines that say why queries return SERVFAIL to clients. 1629 This is separate from the verbosity debug logs, much smaller, and printed 1630 at the error level, not the info level of debug info from verbosity. 1631 1632 Default: no 1633 1634 1635@@UAHL@unbound.conf@pidfile@@: *<filename>* 1636 The process id is written to the file. 1637 Default is :file:`"@UNBOUND_PIDFILE@"`. 1638 So, 1639 1640 .. code-block:: text 1641 1642 kill -HUP `cat @UNBOUND_PIDFILE@` 1643 1644 triggers a reload, 1645 1646 .. code-block:: text 1647 1648 kill -TERM `cat @UNBOUND_PIDFILE@` 1649 1650 gracefully terminates. 1651 1652 Default: @UNBOUND_PIDFILE@ 1653 1654 1655@@UAHL@unbound.conf@root-hints@@: *<filename>* 1656 Read the root hints from this file. 1657 Default is nothing, using builtin hints for the IN class. 1658 The file has the format of zone files, with root nameserver names and 1659 addresses only. 1660 The default may become outdated, when servers change, therefore it is good 1661 practice to use a root hints file. 1662 1663 Default: "" 1664 1665 1666@@UAHL@unbound.conf@hide-identity@@: *<yes or no>* 1667 If enabled 'id.server' and 'hostname.bind' queries are REFUSED. 1668 1669 Default: no 1670 1671 1672@@UAHL@unbound.conf@identity@@: *<string>* 1673 Set the identity to report. 1674 If set to ``""``, then the hostname of the server is returned. 1675 1676 Default: "" 1677 1678 1679@@UAHL@unbound.conf@hide-version@@: *<yes or no>* 1680 If enabled 'version.server' and 'version.bind' queries are REFUSED. 1681 1682 Default: no 1683 1684 1685@@UAHL@unbound.conf@version@@: *<string>* 1686 Set the version to report. 1687 If set to ``""``, then the package version is returned. 1688 1689 Default: "" 1690 1691 1692@@UAHL@unbound.conf@hide-http-user-agent@@: *<yes or no>* 1693 If enabled the HTTP header User-Agent is not set. 1694 Use with caution as some webserver configurations may reject HTTP requests 1695 lacking this header. 1696 If needed, it is better to explicitly set the 1697 :ref:`http-user-agent<unbound.conf.http-user-agent>` below. 1698 1699 Default: no 1700 1701 1702@@UAHL@unbound.conf@http-user-agent@@: *<string>* 1703 Set the HTTP User-Agent header for outgoing HTTP requests. 1704 If set to ``""``, then the package name and version are used. 1705 1706 Default: "" 1707 1708 1709@@UAHL@unbound.conf@nsid@@: *<string>* 1710 Add the specified nsid to the EDNS section of the answer when queried with 1711 an NSID EDNS enabled packet. 1712 As a sequence of hex characters or with 'ascii\_' prefix and then an ASCII 1713 string. 1714 1715 Default: (disabled) 1716 1717 1718@@UAHL@unbound.conf@hide-trustanchor@@: *<yes or no>* 1719 If enabled 'trustanchor.unbound' queries are REFUSED. 1720 1721 Default: no 1722 1723 1724@@UAHL@unbound.conf@target-fetch-policy@@: *<"list of numbers">* 1725 Set the target fetch policy used by Unbound to determine if it should fetch 1726 nameserver target addresses opportunistically. 1727 The policy is described per dependency depth. 1728 1729 The number of values determines the maximum dependency depth that Unbound 1730 will pursue in answering a query. 1731 A value of -1 means to fetch all targets opportunistically for that 1732 dependency depth. 1733 A value of 0 means to fetch on demand only. 1734 A positive value fetches that many targets opportunistically. 1735 1736 Enclose the list between quotes (``""``) and put spaces between numbers. 1737 Setting all zeroes, "0 0 0 0 0" gives behaviour closer to that of BIND 9, 1738 while setting "-1 -1 -1 -1 -1" gives behaviour rumoured to be closer to 1739 that of BIND 8. 1740 1741 Default: "3 2 1 0 0" 1742 1743 1744@@UAHL@unbound.conf@harden-short-bufsize@@: *<yes or no>* 1745 Very small EDNS buffer sizes from queries are ignored. 1746 1747 Default: yes (as described in the standard) 1748 1749 1750@@UAHL@unbound.conf@harden-large-queries@@: *<yes or no>* 1751 Very large queries are ignored. 1752 Default is no, since it is legal protocol wise to send these, and could be 1753 necessary for operation if TSIG or EDNS payload is very large. 1754 1755 Default: no 1756 1757 1758@@UAHL@unbound.conf@harden-glue@@: *<yes or no>* 1759 Will trust glue only if it is within the servers authority. 1760 1761 Default: yes 1762 1763 1764@@UAHL@unbound.conf@harden-unverified-glue@@: *<yes or no>* 1765 Will trust only in-zone glue. 1766 Will try to resolve all out of zone (*unverified*) glue. 1767 Will fallback to the original glue if unable to resolve. 1768 1769 Default: no 1770 1771 1772@@UAHL@unbound.conf@harden-dnssec-stripped@@: *<yes or no>* 1773 Require DNSSEC data for trust-anchored zones, if such data is absent, the 1774 zone becomes bogus. 1775 If turned off, and no DNSSEC data is received (or the DNSKEY data fails to 1776 validate), then the zone is made insecure, this behaves like there is no 1777 trust anchor. 1778 You could turn this off if you are sometimes behind an intrusive firewall 1779 (of some sort) that removes DNSSEC data from packets, or a zone changes 1780 from signed to unsigned to badly signed often. 1781 If turned off you run the risk of a downgrade attack that disables security 1782 for a zone. 1783 1784 Default: yes 1785 1786 1787@@UAHL@unbound.conf@harden-below-nxdomain@@: *<yes or no>* 1788 From :rfc:`8020` (with title "NXDOMAIN: There Really Is Nothing 1789 Underneath"), returns NXDOMAIN to queries for a name below another name 1790 that is already known to be NXDOMAIN. 1791 DNSSEC mandates NOERROR for empty nonterminals, hence this is possible. 1792 Very old software might return NXDOMAIN for empty nonterminals (that 1793 usually happen for reverse IP address lookups), and thus may be 1794 incompatible with this. 1795 To try to avoid this only DNSSEC-secure NXDOMAINs are used, because the old 1796 software does not have DNSSEC. 1797 1798 .. note:: 1799 The NXDOMAIN must be secure, this means NSEC3 with optout is 1800 insufficient. 1801 1802 Default: yes 1803 1804 1805@@UAHL@unbound.conf@harden-referral-path@@: *<yes or no>* 1806 Harden the referral path by performing additional queries for 1807 infrastructure data. 1808 Validates the replies if trust anchors are configured and the zones are 1809 signed. 1810 This enforces DNSSEC validation on nameserver NS sets and the nameserver 1811 addresses that are encountered on the referral path to the answer. 1812 Default is off, because it burdens the authority servers, and it is not RFC 1813 standard, and could lead to performance problems because of the extra query 1814 load that is generated. 1815 Experimental option. 1816 If you enable it consider adding more numbers after the 1817 :ref:`target-fetch-policy<unbound.conf.target-fetch-policy>` to increase 1818 the max depth that is checked to. 1819 1820 Default: no 1821 1822 1823@@UAHL@unbound.conf@harden-algo-downgrade@@: *<yes or no>* 1824 Harden against algorithm downgrade when multiple algorithms are advertised 1825 in the DS record. 1826 This works by first choosing only the strongest DS digest type as per 1827 :rfc:`4509` (Unbound treats the highest algorithm as the strongest) and 1828 then expecting signatures from all the advertised signing algorithms from 1829 the chosen DS(es) to be present. 1830 If no, allows any one supported algorithm to validate the zone, even if 1831 other advertised algorithms are broken. 1832 :rfc:`6840` mandates that zone signers must produce zones signed with all 1833 advertised algorithms, but sometimes they do not. 1834 :rfc:`6840` also clarifies that this requirement is not for validators and 1835 validators should accept any single valid path. 1836 It should thus be explicitly noted that this option violates :rfc:`6840` 1837 for DNSSEC validation and should only be used to perform a signature 1838 completeness test to support troubleshooting. 1839 1840 .. warning:: 1841 Using this option may break DNSSEC resolution with non :rfc:`6840` 1842 conforming signers and/or in multi-signer configurations that don't 1843 send all the advertised signatures. 1844 1845 Default: no 1846 1847 1848@@UAHL@unbound.conf@harden-unknown-additional@@: *<yes or no>* 1849 Harden against unknown records in the authority section and additional 1850 section. 1851 If no, such records are copied from the upstream and presented to the 1852 client together with the answer. 1853 If yes, it could hamper future protocol developments that want to add 1854 records. 1855 1856 Default: no 1857 1858 1859@@UAHL@unbound.conf@use-caps-for-id@@: *<yes or no>* 1860 Use 0x20-encoded random bits in the query to foil spoof attempts. 1861 This perturbs the lowercase and uppercase of query names sent to authority 1862 servers and checks if the reply still has the correct casing. 1863 This feature is an experimental implementation of draft dns-0x20. 1864 1865 Default: no 1866 1867 1868@@UAHL@unbound.conf@caps-exempt@@: *<domain>* 1869 Exempt the domain so that it does not receive caps-for-id perturbed 1870 queries. 1871 For domains that do not support 0x20 and also fail with fallback because 1872 they keep sending different answers, like some load balancers. 1873 Can be given multiple times, for different domains. 1874 1875 1876@@UAHL@unbound.conf@caps-whitelist@@: *<domain>* 1877 Alternate syntax for :ref:`caps-exempt<unbound.conf.caps-exempt>`. 1878 1879 1880@@UAHL@unbound.conf@qname-minimisation@@: *<yes or no>* 1881 Send minimum amount of information to upstream servers to enhance privacy. 1882 Only send minimum required labels of the QNAME and set QTYPE to A when 1883 possible. 1884 Best effort approach; full QNAME and original QTYPE will be sent when 1885 upstream replies with a RCODE other than NOERROR, except when receiving 1886 NXDOMAIN from a DNSSEC signed zone. 1887 1888 Default: yes 1889 1890 1891@@UAHL@unbound.conf@qname-minimisation-strict@@: *<yes or no>* 1892 QNAME minimisation in strict mode. 1893 Do not fall-back to sending full QNAME to potentially broken nameservers. 1894 A lot of domains will not be resolvable when this option in enabled. 1895 Only use if you know what you are doing. 1896 This option only has effect when 1897 :ref:`qname-minimisation<unbound.conf.qname-minimisation>` is enabled. 1898 1899 Default: no 1900 1901 1902@@UAHL@unbound.conf@aggressive-nsec@@: *<yes or no>* 1903 Aggressive NSEC uses the DNSSEC NSEC chain to synthesize NXDOMAIN and other 1904 denials, using information from previous NXDOMAINs answers. 1905 It helps to reduce the query rate towards targets that get a very high 1906 nonexistent name lookup rate. 1907 1908 Default: yes 1909 1910 1911@@UAHL@unbound.conf@private-address@@: *<IP address or subnet>* 1912 Give IPv4 of IPv6 addresses or classless subnets. 1913 These are addresses on your private network, and are not allowed to be 1914 returned for public internet names. 1915 Any occurrence of such addresses are removed from DNS answers. 1916 Additionally, the DNSSEC validator may mark the answers bogus. 1917 This protects against so-called DNS Rebinding, where a user browser is 1918 turned into a network proxy, allowing remote access through the browser to 1919 other parts of your private network. 1920 1921 Some names can be allowed to contain your private addresses, by default all 1922 the :ref:`local-data<unbound.conf.local-data>` that you configured is 1923 allowed to, and you can specify additional names using 1924 :ref:`private-domain<unbound.conf.private-domain>`. 1925 No private addresses are enabled by default. 1926 1927 We consider to enable this for the :rfc:`1918` private IP address space by 1928 default in later releases. 1929 That would enable private addresses for ``10.0.0.0/8``, ``172.16.0.0/12``, 1930 ``192.168.0.0/16``, ``169.254.0.0/16``, ``fd00::/8`` and ``fe80::/10``, 1931 since the RFC standards say these addresses should not be visible on the 1932 public internet. 1933 1934 Turning on ``127.0.0.0/8`` would hinder many spamblocklists as they use 1935 that. 1936 Adding ``::ffff:0:0/96`` stops IPv4-mapped IPv6 addresses from bypassing 1937 the filter. 1938 1939 1940@@UAHL@unbound.conf@private-domain@@: *<domain name>* 1941 Allow this domain, and all its subdomains to contain private addresses. 1942 Give multiple times to allow multiple domain names to contain private 1943 addresses. 1944 1945 Default: (none) 1946 1947 1948@@UAHL@unbound.conf@unwanted-reply-threshold@@: *<number>* 1949 If set, a total number of unwanted replies is kept track of in every 1950 thread. 1951 When it reaches the threshold, a defensive action is taken and a warning is 1952 printed to the log. 1953 The defensive action is to clear the rrset and message caches, hopefully 1954 flushing away any poison. 1955 A value of 10 million is suggested. 1956 1957 Default: 0 (disabled) 1958 1959 1960@@UAHL@unbound.conf@do-not-query-address@@: *<IP address>* 1961 Do not query the given IP address. 1962 Can be IPv4 or IPv6. 1963 Append /num to indicate a classless delegation netblock, for example like 1964 ``10.2.3.4/24`` or ``2001::11/64``. 1965 1966 Default: (none) 1967 1968 1969@@UAHL@unbound.conf@do-not-query-localhost@@: *<yes or no>* 1970 If yes, localhost is added to the 1971 :ref:`do-not-query-address<unbound.conf.do-not-query-address>` entries, 1972 both IPv6 ``::1`` and IPv4 ``127.0.0.1/8``. 1973 If no, then localhost can be used to send queries to. 1974 1975 Default: yes 1976 1977 1978@@UAHL@unbound.conf@prefetch@@: *<yes or no>* 1979 If yes, cache hits on message cache elements that are on their last 10 1980 percent of their TTL value trigger a prefetch to keep the cache up to date. 1981 Turning it on gives about 10 percent more traffic and load on the machine, 1982 but popular items do not expire from the cache. 1983 1984 Default: no 1985 1986 1987@@UAHL@unbound.conf@prefetch-key@@: *<yes or no>* 1988 If yes, fetch the DNSKEYs earlier in the validation process, when a DS 1989 record is encountered. 1990 This lowers the latency of requests. 1991 It does use a little more CPU. 1992 Also if the cache is set to 0, it is no use. 1993 1994 Default: no 1995 1996 1997@@UAHL@unbound.conf@deny-any@@: *<yes or no>* 1998 If yes, deny queries of type ANY with an empty response. 1999 If disabled, Unbound responds with a short list of resource records if some 2000 can be found in the cache and makes the upstream type ANY query if there 2001 are none. 2002 2003 Default: no 2004 2005 2006@@UAHL@unbound.conf@rrset-roundrobin@@: *<yes or no>* 2007 If yes, Unbound rotates RRSet order in response (the random number is taken 2008 from the query ID, for speed and thread safety). 2009 2010 Default: yes 2011 2012 2013@@UAHL@unbound.conf@minimal-responses@@: *<yes or no>* 2014 If yes, Unbound does not insert authority/additional sections into response 2015 messages when those sections are not required. 2016 This reduces response size significantly, and may avoid TCP fallback for 2017 some responses which may cause a slight speedup. 2018 The default is yes, even though the DNS protocol RFCs mandate these 2019 sections, and the additional content could save roundtrips for clients that 2020 use the additional content. 2021 However these sections are hardly used by clients. 2022 Enabling prefetch can benefit clients that need the additional content 2023 by trying to keep that content fresh in the cache. 2024 2025 Default: yes 2026 2027 2028@@UAHL@unbound.conf@disable-dnssec-lame-check@@: *<yes or no>* 2029 If yes, disables the DNSSEC lameness check in the iterator. 2030 This check sees if RRSIGs are present in the answer, when DNSSEC is 2031 expected, and retries another authority if RRSIGs are unexpectedly missing. 2032 The validator will insist in RRSIGs for DNSSEC signed domains regardless of 2033 this setting, if a trust anchor is loaded. 2034 2035 Default: no 2036 2037 2038@@UAHL@unbound.conf@module-config@@: *"<module names>"* 2039 Module configuration, a list of module names separated by spaces, surround 2040 the string with quotes (``""``). 2041 The modules can be ``respip``, ``validator``, or ``iterator`` (and possibly 2042 more, see below). 2043 2044 .. note:: 2045 The ordering of the modules is significant, the order decides the order 2046 of processing. 2047 2048 Setting this to just "iterator" will result in a non-validating server. 2049 Setting this to "validator iterator" will turn on DNSSEC validation. 2050 2051 .. note:: 2052 You must also set trust-anchors for validation to be useful. 2053 2054 Adding ``respip`` to the front will cause RPZ processing to be done on all 2055 queries. 2056 2057 Most modules that need to be listed here have to be listed at the beginning 2058 of the line. 2059 2060 The ``subnetcache`` module has to be listed just before the iterator. 2061 2062 The ``python`` module can be listed in different places, it then processes 2063 the output of the module it is just before. 2064 2065 The ``dynlib`` module can be listed pretty much anywhere, it is only a very 2066 thin wrapper that allows dynamic libraries to run in its place. 2067 2068 Default: "validator iterator" 2069 2070 2071@@UAHL@unbound.conf@trust-anchor-file@@: *<filename>* 2072 File with trusted keys for validation. 2073 Both DS and DNSKEY entries can appear in the file. 2074 The format of the file is the standard DNS Zone file format. 2075 2076 Default: "" (no trust anchor file) 2077 2078 2079@@UAHL@unbound.conf@auto-trust-anchor-file@@: *<filename>* 2080 File with trust anchor for one zone, which is tracked with :rfc:`5011` 2081 probes. 2082 The probes are run several times per month, thus the machine must be online 2083 frequently. 2084 The initial file can be one with contents as described in 2085 :ref:`trust-anchor-file<unbound.conf.trust-anchor-file>`. 2086 The file is written to when the anchor is updated, so the Unbound user must 2087 have write permission. 2088 Write permission to the file, but also to the directory it is in (to create 2089 a temporary file, which is necessary to deal with filesystem full events), 2090 it must also be inside the :ref:`chroot<unbound.conf.chroot>` (if that is 2091 used). 2092 2093 Default: "" (no auto trust anchor file) 2094 2095 2096@@UAHL@unbound.conf@trust-anchor@@: *"<Resource Record>"* 2097 A DS or DNSKEY RR for a key to use for validation. 2098 Multiple entries can be given to specify multiple trusted keys, in addition 2099 to the :ref:`trust-anchor-file<unbound.conf.trust-anchor-file>`. 2100 The resource record is entered in the same format as *dig(1)* or *drill(1)* 2101 prints them, the same format as in the zone file. 2102 Has to be on a single line, with ``""`` around it. 2103 A TTL can be specified for ease of cut and paste, but is ignored. 2104 A class can be specified, but class IN is default. 2105 2106 Default: (none) 2107 2108 2109@@UAHL@unbound.conf@trusted-keys-file@@: *<filename>* 2110 File with trusted keys for validation. 2111 Specify more than one file with several entries, one file per entry. 2112 Like :ref:`trust-anchor-file<unbound.conf.trust-anchor-file>` but has a 2113 different file format. 2114 Format is BIND-9 style format, the ``trusted-keys { name flag proto algo 2115 "key"; };`` clauses are read. 2116 It is possible to use wildcards with this statement, the wildcard is 2117 expanded on start and on reload. 2118 2119 Default: "" (no trusted keys file) 2120 2121 2122@@UAHL@unbound.conf@trust-anchor-signaling@@: *<yes or no>* 2123 Send :rfc:`8145` key tag query after trust anchor priming. 2124 2125 Default: yes 2126 2127 2128@@UAHL@unbound.conf@root-key-sentinel@@: *<yes or no>* 2129 Root key trust anchor sentinel. 2130 2131 Default: yes 2132 2133 2134@@UAHL@unbound.conf@domain-insecure@@: *<domain name>* 2135 Sets *<domain name>* to be insecure, DNSSEC chain of trust is ignored 2136 towards the *<domain name>*. 2137 So a trust anchor above the domain name can not make the domain secure with 2138 a DS record, such a DS record is then ignored. 2139 Can be given multiple times to specify multiple domains that are treated as 2140 if unsigned. 2141 If you set trust anchors for the domain they override this setting (and the 2142 domain is secured). 2143 2144 This can be useful if you want to make sure a trust anchor for external 2145 lookups does not affect an (unsigned) internal domain. 2146 A DS record externally can create validation failures for that internal 2147 domain. 2148 2149 Default: (none) 2150 2151 2152@@UAHL@unbound.conf@val-override-date@@: *<rrsig-style date spec>* 2153 .. warning:: Debugging feature! 2154 2155 If enabled by giving a RRSIG style date, that date is used for verifying 2156 RRSIG inception and expiration dates, instead of the current date. 2157 Do not set this unless you are debugging signature inception and 2158 expiration. 2159 The value -1 ignores the date altogether, useful for some special 2160 applications. 2161 2162 Default: 0 (disabled) 2163 2164 2165@@UAHL@unbound.conf@val-sig-skew-min@@: *<seconds>* 2166 Minimum number of seconds of clock skew to apply to validated signatures. 2167 A value of 10% of the signature lifetime (expiration - inception) is used, 2168 capped by this setting. 2169 Default is 3600 (1 hour) which allows for daylight savings differences. 2170 Lower this value for more strict checking of short lived signatures. 2171 2172 Default: 3600 (1 hour) 2173 2174 2175@@UAHL@unbound.conf@val-sig-skew-max@@: *<seconds>* 2176 Maximum number of seconds of clock skew to apply to validated signatures. 2177 A value of 10% of the signature lifetime (expiration - inception) is used, 2178 capped by this setting. 2179 Default is 86400 (24 hours) which allows for timezone setting problems in 2180 stable domains. 2181 Setting both min and max very low disables the clock skew allowances. 2182 Setting both min and max very high makes the validator check the signature 2183 timestamps less strictly. 2184 2185 Default: 86400 (24 hours) 2186 2187 2188@@UAHL@unbound.conf@val-max-restart@@: *<number>* 2189 The maximum number the validator should restart validation with another 2190 authority in case of failed validation. 2191 2192 Default: 5 2193 2194 2195@@UAHL@unbound.conf@val-bogus-ttl@@: *<seconds>* 2196 The time to live for bogus data. 2197 This is data that has failed validation; due to invalid signatures or other 2198 checks. 2199 The TTL from that data cannot be trusted, and this value is used instead. 2200 The time interval prevents repeated revalidation of bogus data. 2201 2202 Default: 60 2203 2204 2205@@UAHL@unbound.conf@val-clean-additional@@: *<yes or no>* 2206 Instruct the validator to remove data from the additional section of secure 2207 messages that are not signed properly. 2208 Messages that are insecure, bogus, indeterminate or unchecked are not 2209 affected. 2210 Use this setting to protect the users that rely on this validator for 2211 authentication from potentially bad data in the additional section. 2212 2213 Default: yes 2214 2215 2216@@UAHL@unbound.conf@val-log-level@@: *<number>* 2217 Have the validator print validation failures to the log. 2218 Regardless of the verbosity setting. 2219 2220 At 1, for every user query that fails a line is printed to the logs. 2221 This way you can monitor what happens with validation. 2222 Use a diagnosis tool, such as dig or drill, to find out why validation is 2223 failing for these queries. 2224 2225 At 2, not only the query that failed is printed but also the reason why 2226 Unbound thought it was wrong and which server sent the faulty data. 2227 2228 Default: 0 (disabled) 2229 2230 2231@@UAHL@unbound.conf@val-permissive-mode@@: *<yes or no>* 2232 Instruct the validator to mark bogus messages as indeterminate. 2233 The security checks are performed, but if the result is bogus (failed 2234 security), the reply is not withheld from the client with SERVFAIL as 2235 usual. 2236 The client receives the bogus data. 2237 For messages that are found to be secure the AD bit is set in replies. 2238 Also logging is performed as for full validation. 2239 2240 Default: no 2241 2242 2243@@UAHL@unbound.conf@ignore-cd-flag@@: *<yes or no>* 2244 Instruct Unbound to ignore the CD flag from clients and refuse to return 2245 bogus answers to them. 2246 Thus, the CD (Checking Disabled) flag does not disable checking any more. 2247 This is useful if legacy (w2008) servers that set the CD flag but cannot 2248 validate DNSSEC themselves are the clients, and then Unbound provides them 2249 with DNSSEC protection. 2250 2251 Default: no 2252 2253 2254@@UAHL@unbound.conf@disable-edns-do@@: *<yes or no>* 2255 Disable the EDNS DO flag in upstream requests. 2256 It breaks DNSSEC validation for Unbound's clients. 2257 This results in the upstream name servers to not include DNSSEC records in 2258 their replies and could be helpful for devices that cannot handle DNSSEC 2259 information. 2260 When the option is enabled, clients that set the DO flag receive no EDNS 2261 record in the response to indicate the lack of support to them. 2262 If this option is enabled but Unbound is already configured for DNSSEC 2263 validation (i.e., the validator module is enabled; default) this option is 2264 implicitly turned off with a warning as to not break DNSSEC validation in 2265 Unbound. 2266 2267 Default: no 2268 2269 2270@@UAHL@unbound.conf@serve-expired@@: *<yes or no>* 2271 If enabled, Unbound attempts to serve old responses from cache with a TTL 2272 of :ref:`serve-expired-reply-ttl<unbound.conf.serve-expired-reply-ttl>` in 2273 the response. 2274 By default the expired answer will be used after a resolution attempt 2275 errored out or is taking more than 2276 :ref:`serve-expired-client-timeout<unbound.conf.serve-expired-client-timeout>` 2277 to resolve. 2278 2279 Default: no 2280 2281 2282@@UAHL@unbound.conf@serve-expired-ttl@@: *<seconds>* 2283 Limit serving of expired responses to configured seconds after expiration. 2284 ``0`` disables the limit. 2285 This option only applies when 2286 :ref:`serve-expired<unbound.conf.serve-expired>` is enabled. 2287 A suggested value per RFC 8767 is between 86400 (1 day) and 259200 (3 days). 2288 The default is 86400. 2289 2290 Default: 86400 2291 2292 2293@@UAHL@unbound.conf@serve-expired-ttl-reset@@: *<yes or no>* 2294 Set the TTL of expired records to the 2295 :ref:`serve-expired-ttl<unbound.conf.serve-expired-ttl>` value after a 2296 failed attempt to retrieve the record from upstream. 2297 This makes sure that the expired records will be served as long as there 2298 are queries for it. 2299 2300 Default: no 2301 2302 2303@@UAHL@unbound.conf@serve-expired-reply-ttl@@: *<seconds>* 2304 TTL value to use when replying with expired data. 2305 If 2306 :ref:`serve-expired-client-timeout<unbound.conf.serve-expired-client-timeout>` 2307 is also used then it is RECOMMENDED to use 30 as the value (:rfc:`8767`). 2308 2309 Default: 30 2310 2311 2312@@UAHL@unbound.conf@serve-expired-client-timeout@@: *<msec>* 2313 Time in milliseconds before replying to the client with expired data. 2314 This essentially enables the serve-stale behavior as specified in 2315 :rfc:`8767` that first tries to resolve before immediately responding with 2316 expired data. 2317 Setting this to ``0`` will disable this behavior and instead serve the 2318 expired record immediately from the cache before attempting to refresh it 2319 via resolution. 2320 2321 Default: 1800 2322 2323 2324@@UAHL@unbound.conf@serve-original-ttl@@: *<yes or no>* 2325 If enabled, Unbound will always return the original TTL as received from 2326 the upstream name server rather than the decrementing TTL as stored in the 2327 cache. 2328 This feature may be useful if Unbound serves as a front-end to a hidden 2329 authoritative name server. 2330 2331 Enabling this feature does not impact cache expiry, it only changes the TTL 2332 Unbound embeds in responses to queries. 2333 2334 .. note:: 2335 Enabling this feature implicitly disables enforcement of the configured 2336 minimum and maximum TTL, as it is assumed users who enable this feature 2337 do not want Unbound to change the TTL obtained from an upstream server. 2338 2339 .. note:: 2340 The values set using :ref:`cache-min-ttl<unbound.conf.cache-min-ttl>` 2341 and :ref:`cache-max-ttl<unbound.conf.cache-max-ttl>` are ignored. 2342 2343 Default: no 2344 2345 2346@@UAHL@unbound.conf@val-nsec3-keysize-iterations@@: <"list of values"> 2347 List of keysize and iteration count values, separated by spaces, surrounded 2348 by quotes. 2349 This determines the maximum allowed NSEC3 iteration count before a message 2350 is simply marked insecure instead of performing the many hashing 2351 iterations. 2352 The list must be in ascending order and have at least one entry. 2353 If you set it to "1024 65535" there is no restriction to NSEC3 iteration 2354 values. 2355 2356 .. note:: 2357 This table must be kept short; a very long list could cause slower 2358 operation. 2359 2360 Default: "1024 150 2048 150 4096 150" 2361 2362 2363@@UAHL@unbound.conf@zonemd-permissive-mode@@: *<yes or no>* 2364 If enabled the ZONEMD verification failures are only logged and do not 2365 cause the zone to be blocked and only return servfail. 2366 Useful for testing out if it works, or if the operator only wants to be 2367 notified of a problem without disrupting service. 2368 2369 Default: no 2370 2371 2372@@UAHL@unbound.conf@add-holddown@@: *<seconds>* 2373 Instruct the 2374 :ref:`auto-trust-anchor-file<unbound.conf.auto-trust-anchor-file>` probe 2375 mechanism for :rfc:`5011` autotrust updates to add new trust anchors only 2376 after they have been visible for this time. 2377 2378 Default: 2592000 (30 days as per the RFC) 2379 2380 2381@@UAHL@unbound.conf@del-holddown@@: *<seconds>* 2382 Instruct the 2383 :ref:`auto-trust-anchor-file<unbound.conf.auto-trust-anchor-file>` probe 2384 mechanism for :rfc:`5011` autotrust updates to remove revoked trust anchors 2385 after they have been kept in the revoked list for this long. 2386 2387 Default: 2592000 (30 days as per the RFC) 2388 2389 2390@@UAHL@unbound.conf@keep-missing@@: *<seconds>* 2391 Instruct the 2392 :ref:`auto-trust-anchor-file<unbound.conf.auto-trust-anchor-file>` probe 2393 mechanism for :rfc:`5011` autotrust updates to remove missing trust anchors 2394 after they have been unseen for this long. 2395 This cleans up the state file if the target zone does not perform trust 2396 anchor revocation, so this makes the auto probe mechanism work with zones 2397 that perform regular (non-5011) rollovers. 2398 The value 0 does not remove missing anchors, as per the RFC. 2399 2400 Default: 31622400 (366 days) 2401 2402 2403@@UAHL@unbound.conf@permit-small-holddown@@: *<yes or no>* 2404 Debug option that allows the autotrust 5011 rollover timers to assume very 2405 small values. 2406 2407 Default: no 2408 2409 2410@@UAHL@unbound.conf@key-cache-size@@: *<number>* 2411 Number of bytes size of the key cache. 2412 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes 2413 or gigabytes (1024*1024 bytes in a megabyte). 2414 2415 Default: 4m 2416 2417 2418@@UAHL@unbound.conf@key-cache-slabs@@: *<number>* 2419 Number of slabs in the key cache. 2420 Slabs reduce lock contention by threads. 2421 Must be set to a power of 2. 2422 Setting (close) to the number of cpus is a fairly good setting. 2423 If left unconfigured, it will be configured automatically to be a power of 2424 2 close to the number of configured threads in multi-threaded environments. 2425 2426 Default: (unconfigured) 2427 2428 2429@@UAHL@unbound.conf@neg-cache-size@@: *<number>* 2430 Number of bytes size of the aggressive negative cache. 2431 A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes 2432 or gigabytes (1024*1024 bytes in a megabyte). 2433 2434 Default: 1m 2435 2436 2437@@UAHL@unbound.conf@unblock-lan-zones@@: *<yes or no>* 2438 If enabled, then for private address space, the reverse lookups are no 2439 longer filtered. 2440 This allows Unbound when running as dns service on a host where it provides 2441 service for that host, to put out all of the queries for the 'lan' 2442 upstream. 2443 When enabled, only localhost, ``127.0.0.1`` reverse and ``::1`` reverse 2444 zones are configured with default local zones. 2445 Disable the option when Unbound is running as a (DHCP-) DNS network 2446 resolver for a group of machines, where such lookups should be filtered 2447 (RFC compliance), this also stops potential data leakage about the local 2448 network to the upstream DNS servers. 2449 2450 Default: no 2451 2452 2453@@UAHL@unbound.conf@insecure-lan-zones@@: *<yes or no>* 2454 If enabled, then reverse lookups in private address space are not 2455 validated. 2456 This is usually required whenever 2457 :ref:`unblock-lan-zones<unbound.conf.unblock-lan-zones>` is used. 2458 2459 Default: no 2460 2461 2462@@UAHL@unbound.conf@local-zone@@: *<zone> <type>* 2463 Configure a local zone. 2464 The type determines the answer to give if there is no match from 2465 :ref:`local-data<unbound.conf.local-data>`. 2466 The types are 2467 :ref:`deny<unbound.conf.local-zone.type.deny>`, 2468 :ref:`refuse<unbound.conf.local-zone.type.refuse>`, 2469 :ref:`static<unbound.conf.local-zone.type.static>`, 2470 :ref:`transparent<unbound.conf.local-zone.type.transparent>`, 2471 :ref:`redirect<unbound.conf.local-zone.type.redirect>`, 2472 :ref:`nodefault<unbound.conf.local-zone.type.nodefault>`, 2473 :ref:`typetransparent<unbound.conf.local-zone.type.typetransparent>`, 2474 :ref:`inform<unbound.conf.local-zone.type.inform>`, 2475 :ref:`inform_deny<unbound.conf.local-zone.type.inform_deny>`, 2476 :ref:`inform_redirect<unbound.conf.local-zone.type.inform_redirect>`, 2477 :ref:`always_transparent<unbound.conf.local-zone.type.always_transparent>`, 2478 :ref:`block_a<unbound.conf.local-zone.type.block_a>`, 2479 :ref:`always_refuse<unbound.conf.local-zone.type.always_refuse>`, 2480 :ref:`always_nxdomain<unbound.conf.local-zone.type.always_nxdomain>`, 2481 :ref:`always_null<unbound.conf.local-zone.type.always_null>`, 2482 :ref:`noview<unbound.conf.local-zone.type.noview>`, 2483 and are explained below. 2484 After that the default settings are listed. 2485 Use :ref:`local-data<unbound.conf.local-data>` to enter data into the 2486 local zone. 2487 Answers for local zones are authoritative DNS answers. 2488 By default the zones are class IN. 2489 2490 If you need more complicated authoritative data, with referrals, 2491 wildcards, CNAME/DNAME support, or DNSSEC authoritative service, 2492 setup a :ref:`stub-zone<unbound.conf.stub>` for it as detailed in the 2493 stub zone section below. 2494 A :ref:`stub-zone<unbound.conf.stub>` can be used to have unbound 2495 send queries to another server, an authoritative server, to fetch the 2496 information. 2497 With a :ref:`forward-zone<unbound.conf.forward>`, unbound sends 2498 queries to a server that is a recursive server to fetch the information. 2499 With an :ref:`auth-zone<unbound.conf.auth>` a zone can be loaded from 2500 file and used, it can be used like a local zone for users downstream, or 2501 the :ref:`auth-zone<unbound.conf.auth>` information can be used to fetch 2502 information from when resolving like it is an upstream server. 2503 The :ref:`forward-zone<unbound.conf.forward>` and 2504 :ref:`auth-zone<unbound.conf.auth>` options are described in their 2505 sections below. 2506 If you want to perform filtering of the information that the users can 2507 fetch, the :ref:`local-zone<unbound.conf.local-zone>` and 2508 :ref:`local-data<unbound.conf.local-data>` statements allow for this, but 2509 also the :ref:`rpz<unbound.conf.rpz>` functionality can be used, described 2510 in the RPZ section. 2511 2512 @@UAHL@unbound.conf.local-zone.type@deny@@ 2513 Do not send an answer, drop the query. 2514 If there is a match from local data, the query is answered. 2515 2516 @@UAHL@unbound.conf.local-zone.type@refuse@@ 2517 Send an error message reply, with rcode REFUSED. 2518 If there is a match from local data, the query is answered. 2519 2520 @@UAHL@unbound.conf.local-zone.type@static@@ 2521 If there is a match from local data, the query is answered. 2522 Otherwise, the query is answered with NODATA or NXDOMAIN. 2523 For a negative answer a SOA is included in the answer if present as 2524 :ref:`local-data<unbound.conf.local-data>` for the zone apex domain. 2525 2526 @@UAHL@unbound.conf.local-zone.type@transparent@@ 2527 If there is a match from :ref:`local-data<unbound.conf.local-data>`, 2528 the query is answered. 2529 Otherwise if the query has a different name, the query is resolved 2530 normally. 2531 If the query is for a name given in 2532 :ref:`local-data<unbound.conf.local-data>` but no such type of data is 2533 given in localdata, then a NOERROR NODATA answer is returned. 2534 If no :ref:`local-zone<unbound.conf.local-zone>` is given 2535 :ref:`local-data<unbound.conf.local-data>` causes a transparent zone 2536 to be created by default. 2537 2538 @@UAHL@unbound.conf.local-zone.type@typetransparent@@ 2539 If there is a match from local data, the query is answered. 2540 If the query is for a different name, or for the same name but for a 2541 different type, the query is resolved normally. 2542 So, similar to 2543 :ref:`transparent<unbound.conf.local-zone.type.transparent>` but types 2544 that are not listed in local data are resolved normally, so if an A 2545 record is in the local data that does not cause a NODATA reply for AAAA 2546 queries. 2547 2548 @@UAHL@unbound.conf.local-zone.type@redirect@@ 2549 The query is answered from the local data for the zone name. 2550 There may be no local data beneath the zone name. 2551 This answers queries for the zone, and all subdomains of the zone with 2552 the local data for the zone. 2553 It can be used to redirect a domain to return a different address 2554 record to the end user, with: 2555 2556 .. code-block:: text 2557 2558 local-zone: "example.com." redirect 2559 local-data: "example.com. A 127.0.0.1" 2560 2561 queries for ``www.example.com`` and ``www.foo.example.com`` are 2562 redirected, so that users with web browsers cannot access sites with 2563 suffix example.com. 2564 2565 @@UAHL@unbound.conf.local-zone.type@inform@@ 2566 The query is answered normally, same as 2567 :ref:`transparent<unbound.conf.local-zone.type.transparent>`. 2568 The client IP address (@portnumber) is printed to the logfile. 2569 The log message is: 2570 2571 .. code-block:: text 2572 2573 timestamp, unbound-pid, info: zonename inform IP@port queryname type class. 2574 2575 This option can be used for normal resolution, but machines looking up 2576 infected names are logged, eg. to run antivirus on them. 2577 2578 @@UAHL@unbound.conf.local-zone.type@inform_deny@@ 2579 The query is dropped, like 2580 :ref:`deny<unbound.conf.local-zone.type.deny>`, and logged, like 2581 :ref:`inform<unbound.conf.local-zone.type.inform>`. 2582 Ie. find infected machines without answering the queries. 2583 2584 @@UAHL@unbound.conf.local-zone.type@inform_redirect@@ 2585 The query is redirected, like 2586 :ref:`redirect<unbound.conf.local-zone.type.redirect>`, and logged, 2587 like :ref:`inform<unbound.conf.local-zone.type.inform>`. 2588 Ie. answer queries with fixed data and also log the machines that ask. 2589 2590 @@UAHL@unbound.conf.local-zone.type@always_transparent@@ 2591 Like :ref:`transparent<unbound.conf.local-zone.type.transparent>`, but 2592 ignores local data and resolves normally. 2593 2594 @@UAHL@unbound.conf.local-zone.type@block_a@@ 2595 Like :ref:`transparent<unbound.conf.local-zone.type.transparent>`, but 2596 ignores local data and resolves normally all query types excluding A. 2597 For A queries it unconditionally returns NODATA. 2598 Useful in cases when there is a need to explicitly force all apps to 2599 use IPv6 protocol and avoid any queries to IPv4. 2600 2601 @@UAHL@unbound.conf.local-zone.type@always_refuse@@ 2602 Like :ref:`refuse<unbound.conf.local-zone.type.refuse>`, but ignores 2603 local data and refuses the query. 2604 2605 @@UAHL@unbound.conf.local-zone.type@always_nxdomain@@ 2606 Like :ref:`static<unbound.conf.local-zone.type.static>`, but ignores 2607 local data and returns NXDOMAIN for the query. 2608 2609 @@UAHL@unbound.conf.local-zone.type@always_nodata@@ 2610 Like :ref:`static<unbound.conf.local-zone.type.static>`, but ignores 2611 local data and returns NODATA for the query. 2612 2613 @@UAHL@unbound.conf.local-zone.type@always_deny@@ 2614 Like :ref:`deny<unbound.conf.local-zone.type.deny>`, but ignores local 2615 data and drops the query. 2616 2617 @@UAHL@unbound.conf.local-zone.type@always_null@@ 2618 Always returns ``0.0.0.0`` or ``::0`` for every name in the zone. 2619 Like :ref:`redirect<unbound.conf.local-zone.type.redirect>` with zero 2620 data for A and AAAA. 2621 Ignores local data in the zone. 2622 Used for some block lists. 2623 2624 @@UAHL@unbound.conf.local-zone.type@noview@@ 2625 Breaks out of that view and moves towards the global local zones for 2626 answer to the query. 2627 If the :ref:`view-first<unbound.conf.view.view-first>` is no, it'll 2628 resolve normally. 2629 If :ref:`view-first<unbound.conf.view.view-first>` is enabled, it'll 2630 break perform that step and check the global answers. 2631 For when the view has view specific overrides but some zone has to be 2632 answered from global local zone contents. 2633 2634 @@UAHL@unbound.conf.local-zone.type@nodefault@@ 2635 Used to turn off default contents for AS112 zones. 2636 The other types also turn off default contents for the zone. 2637 The :ref:`nodefault<unbound.conf.local-zone.type.nodefault>` option has 2638 no other effect than turning off default contents for the given zone. 2639 Use :ref:`nodefault<unbound.conf.local-zone.type.nodefault>` if you use 2640 exactly that zone, if you want to use a subzone, use 2641 :ref:`transparent<unbound.conf.local-zone.type.transparent>`. 2642 2643 The default zones are localhost, reverse ``127.0.0.1`` and ``::1``, the 2644 ``home.arpa``, ``resolver.arpa``, ``service.arpa``, ``onion``, ``test``, 2645 ``invalid`` and the AS112 zones. 2646 The AS112 zones are reverse DNS zones for private use and reserved IP 2647 addresses for which the servers on the internet cannot provide correct 2648 answers. 2649 They are configured by default to give NXDOMAIN (no reverse information) 2650 answers. 2651 2652 The defaults can be turned off by specifying your own 2653 :ref:`local-zone<unbound.conf.local-zone>` of that name, or using the 2654 :ref:`nodefault<unbound.conf.local-zone.type.nodefault>` type. 2655 Below is a list of the default zone contents. 2656 2657 @@UAHL@unbound.conf.local-zone.defaults@localhost@@ 2658 The IPv4 and IPv6 localhost information is given. 2659 NS and SOA records are provided for completeness and to satisfy some 2660 DNS update tools. 2661 Default content: 2662 2663 .. code-block:: text 2664 2665 local-zone: "localhost." redirect 2666 local-data: "localhost. 10800 IN NS localhost." 2667 local-data: "localhost. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" 2668 local-data: "localhost. 10800 IN A 127.0.0.1" 2669 local-data: "localhost. 10800 IN AAAA ::1" 2670 2671 @@UAHL@unbound.conf.local-zone.defaults@reverse IPv4 loopback@@ 2672 Default content: 2673 2674 .. code-block:: text 2675 2676 local-zone: "127.in-addr.arpa." static 2677 local-data: "127.in-addr.arpa. 10800 IN NS localhost." 2678 local-data: "127.in-addr.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" 2679 local-data: "1.0.0.127.in-addr.arpa. 10800 IN PTR localhost." 2680 2681 @@UAHL@unbound.conf.local-zone.defaults@reverse IPv6 loopback@@ 2682 Default content: 2683 2684 .. code-block:: text 2685 2686 local-zone: "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." static 2687 local-data: "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. 10800 IN NS localhost." 2688 local-data: "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. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" 2689 local-data: "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. 10800 IN PTR localhost." 2690 2691 @@UAHL@unbound.conf.local-zone.defaults@home.arpa@@ (:rfc:`8375`) 2692 Default content: 2693 2694 .. code-block:: text 2695 2696 local-zone: "home.arpa." static 2697 local-data: "home.arpa. 10800 IN NS localhost." 2698 local-data: "home.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" 2699 2700 @@UAHL@unbound.conf.local-zone.defaults@resolver.arpa@@ (:rfc:`9462`) 2701 Default content: 2702 2703 .. code-block:: text 2704 2705 local-zone: "resolver.arpa." static 2706 local-data: "resolver.arpa. 10800 IN NS localhost." 2707 local-data: "resolver.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" 2708 2709 @@UAHL@unbound.conf.local-zone.defaults@service.arpa@@ (draft-ietf-dnssd-srp-25) 2710 Default content: 2711 2712 .. code-block:: text 2713 2714 local-zone: "service.arpa." static 2715 local-data: "service.arpa. 10800 IN NS localhost." 2716 local-data: "service.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" 2717 2718 @@UAHL@unbound.conf.local-zone.defaults@onion@@ (:rfc:`7686`) 2719 Default content: 2720 2721 .. code-block:: text 2722 2723 local-zone: "onion." static 2724 local-data: "onion. 10800 IN NS localhost." 2725 local-data: "onion. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" 2726 2727 @@UAHL@unbound.conf.local-zone.defaults@test@@ (:rfc:`6761`) 2728 Default content: 2729 2730 .. code-block:: text 2731 2732 local-zone: "test." static 2733 local-data: "test. 10800 IN NS localhost." 2734 local-data: "test. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" 2735 2736 @@UAHL@unbound.conf.local-zone.defaults@invalid@@ (:rfc:`6761`) 2737 Default content: 2738 2739 .. code-block:: text 2740 2741 local-zone: "invalid." static 2742 local-data: "invalid. 10800 IN NS localhost." 2743 local-data: "invalid. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" 2744 2745 @@UAHL@unbound.conf.local-zone.defaults@reverse local use zones@@ (:rfc:`1918`) 2746 Reverse data for zones ``10.in-addr.arpa``, ``16.172.in-addr.arpa`` to 2747 ``31.172.in-addr.arpa``, ``168.192.in-addr.arpa``. 2748 The :ref:`local-zone<unbound.conf.local-zone>` is set static and as 2749 :ref:`local-data<unbound.conf.local-data>` SOA and NS records are 2750 provided. 2751 2752 @@UAHL@unbound.conf.local-zone.defaults@special-use IPv4 Addresses@@ (:rfc:`3330`) 2753 Reverse data for zones ``0.in-addr.arpa`` (this), ``254.169.in-addr.arpa`` (link-local), 2754 ``2.0.192.in-addr.arpa`` (TEST NET 1), ``100.51.198.in-addr.arpa`` 2755 (TEST NET 2), ``113.0.203.in-addr.arpa`` (TEST NET 3), 2756 ``255.255.255.255.in-addr.arpa`` (broadcast). 2757 And from ``64.100.in-addr.arpa`` to ``127.100.in-addr.arpa`` (Shared 2758 Address Space). 2759 2760 @@UAHL@unbound.conf.local-zone.defaults@reverse IPv6 unspecified@@ (:rfc:`4291`) 2761 Reverse data for zone 2762 ``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.`` 2763 2764 @@UAHL@unbound.conf.local-zone.defaults@reverse IPv6 Locally Assigned Local Addresses@@ (:rfc:`4193`) 2765 Reverse data for zone ``D.F.ip6.arpa``. 2766 2767 @@UAHL@unbound.conf.local-zone.defaults@reverse IPv6 Link Local Addresses@@ (:rfc:`4291`) 2768 Reverse data for zones ``8.E.F.ip6.arpa`` to ``B.E.F.ip6.arpa``. 2769 2770 @@UAHL@unbound.conf.local-zone.defaults@reverse IPv6 Example Prefix@@ 2771 Reverse data for zone ``8.B.D.0.1.0.0.2.ip6.arpa``. 2772 This zone is used for tutorials and examples. 2773 You can remove the block on this zone with: 2774 2775 .. code-block:: text 2776 2777 local-zone: 8.B.D.0.1.0.0.2.ip6.arpa. nodefault 2778 2779 You can also selectively unblock a part of the zone by making that part 2780 transparent with a :ref:`local-zone<unbound.conf.local-zone>` statement. 2781 This also works with the other default zones. 2782 2783 2784@@UAHL@unbound.conf@local-data@@: *"<resource record string>"* 2785 Configure local data, which is served in reply to queries for it. 2786 The query has to match exactly unless you configure the 2787 :ref:`local-zone<unbound.conf.local-zone>` as redirect. 2788 If not matched exactly, the :ref:`local-zone<unbound.conf.local-zone>` 2789 type determines further processing. 2790 If :ref:`local-data<unbound.conf.local-data>` is configured that is not a 2791 subdomain of a :ref:`local-zone<unbound.conf.local-zone>`, a 2792 :ref:`transparent local-zone<unbound.conf.local-zone.type.transparent>` is 2793 configured. 2794 For record types such as TXT, use single quotes, as in: 2795 2796 .. code-block:: text 2797 2798 local-data: 'example. TXT "text"' 2799 2800 .. note:: 2801 If you need more complicated authoritative data, with referrals, 2802 wildcards, CNAME/DNAME support, or DNSSEC authoritative service, setup 2803 a :ref:`stub-zone<unbound.conf.stub>` for it as detailed in the stub 2804 zone section below. 2805 2806 2807@@UAHL@unbound.conf@local-data-ptr@@: *"IPaddr name"* 2808 Configure local data shorthand for a PTR record with the reversed IPv4 or 2809 IPv6 address and the host name. 2810 For example ``"192.0.2.4 www.example.com"``. 2811 TTL can be inserted like this: ``"2001:DB8::4 7200 www.example.com"`` 2812 2813 2814@@UAHL@unbound.conf@local-zone-tag@@: *<zone> <"list of tags">* 2815 Assign tags to local zones. 2816 Tagged localzones will only be applied when the used 2817 :ref:`access-control<unbound.conf.access-control>` element has a matching 2818 tag. 2819 Tags must be defined in :ref:`define-tag<unbound.conf.define-tag>`. 2820 Enclose list of tags in quotes (``""``) and put spaces between tags. 2821 When there are multiple tags it checks if the intersection of the list of 2822 tags for the query and :ref:`local-zone-tag<unbound.conf.local-zone-tag>` 2823 is non-empty. 2824 2825 2826@@UAHL@unbound.conf@local-zone-override@@: *<zone> <IP netblock> <type>* 2827 Override the local zone type for queries from addresses matching netblock. 2828 Use this localzone type, regardless the type configured for the local zone 2829 (both tagged and untagged) and regardless the type configured using 2830 :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>`. 2831 2832 2833@@UAHL@unbound.conf@response-ip@@: *<IP-netblock> <action>* 2834 This requires use of the ``respip`` module. 2835 2836 If the IP address in an AAAA or A RR in the answer section of a response 2837 matches the specified IP netblock, the specified action will apply. 2838 *<action>* has generally the same semantics as that for 2839 :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>`, 2840 but there are some exceptions. 2841 2842 Actions for :ref:`response-ip<unbound.conf.response-ip>` are different 2843 from those for :ref:`local-zone<unbound.conf.local-zone>` in that in case 2844 of the former there is no point of such conditions as "the query matches it 2845 but there is no local data". 2846 Because of this difference, the semantics of 2847 :ref:`response-ip<unbound.conf.response-ip>` actions are modified or 2848 simplified as follows: The *static*, *refuse*, *transparent*, 2849 *typetransparent*, and *nodefault* actions are invalid for *response-ip*. 2850 Using any of these will cause the configuration to be rejected as faulty. 2851 The *deny* action is non-conditional, i.e. it always results in dropping 2852 the corresponding query. 2853 The resolution result before applying the *deny* action is still cached and 2854 can be used for other queries. 2855 2856 2857@@UAHL@unbound.conf@response-ip-data@@: *<IP-netblock> <"resource record string">* 2858 This requires use of the ``respip`` module. 2859 2860 This specifies the action data for 2861 :ref:`response-ip<unbound.conf.response-ip>` with action being to redirect 2862 as specified by *<"resource record string">*. 2863 *<"Resource record string">* is similar to that of 2864 :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>`, 2865 but it must be of either AAAA, A or CNAME types. 2866 If the *<IP-netblock>* is an IPv6/IPv4 prefix, the record must be AAAA/A 2867 respectively, unless it is a CNAME (which can be used for both versions of 2868 IP netblocks). 2869 If it is CNAME there must not be more than one 2870 :ref:`response-ip-data<unbound.conf.response-ip-data>` for the same 2871 *<IP-netblock>*. 2872 Also, CNAME and other types of records must not coexist for the same 2873 *<IP-netblock>*, following the normal rules for CNAME records. 2874 The textual domain name for the CNAME does not have to be explicitly 2875 terminated with a dot (``"."``); the root name is assumed to be the origin 2876 for the name. 2877 2878 2879@@UAHL@unbound.conf@response-ip-tag@@: *<IP-netblock> <"list of tags">* 2880 This requires use of the ``respip`` module. 2881 2882 Assign tags to response *<IP-netblock>*. 2883 If the IP address in an AAAA or A RR in the answer section of a response 2884 matches the specified *<IP-netblock>*, the specified tags are assigned to 2885 the IP address. 2886 Then, if an :ref:`access-control-tag<unbound.conf.access-control-tag>` is 2887 defined for the client and it includes one of the tags for the response IP, 2888 the corresponding 2889 :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>` 2890 will apply. 2891 Tag matching rule is the same as that for 2892 :ref:`access-control-tag<unbound.conf.access-control-tag>` and 2893 :ref:`local-zone<unbound.conf.local-zone>`. 2894 Unlike :ref:`local-zone-tag<unbound.conf.local-zone-tag>`, 2895 :ref:`response-ip-tag<unbound.conf.response-ip-tag>` can be defined for an 2896 *<IP-netblock>* even if no :ref:`response-ip<unbound.conf.response-ip>` is 2897 defined for that netblock. 2898 If multiple :ref:`response-ip-tag<unbound.conf.response-ip-tag>` options 2899 are specified for the same *<IP-netblock>* in different statements, all but 2900 the first will be ignored. 2901 However, this will not be flagged as a configuration error, but the result 2902 is probably not what was intended. 2903 2904 Actions specified in an 2905 :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>` 2906 that has a matching tag with 2907 :ref:`response-ip-tag<unbound.conf.response-ip-tag>` can be those that are 2908 "invalid" for :ref:`response-ip<unbound.conf.response-ip>` listed above, 2909 since 2910 :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>` 2911 can be shared with local zones. 2912 For these actions, if they behave differently depending on whether local 2913 data exists or not in case of local zones, the behavior for 2914 :ref:`response-ip-data<unbound.conf.response-ip-data>` will generally 2915 result in NOERROR/NODATA instead of NXDOMAIN, since the 2916 :ref:`response-ip<unbound.conf.response-ip>` data are inherently type 2917 specific, and non-existence of data does not indicate anything about the 2918 existence or non-existence of the qname itself. 2919 For example, if the matching tag action is static but there is no data for 2920 the corresponding :ref:`response-ip<unbound.conf.response-ip>` 2921 configuration, then the result will be NOERROR/NODATA. 2922 The only case where NXDOMAIN is returned is when an 2923 :ref:`always_nxdomain<unbound.conf.local-zone.type.always_nxdomain>` 2924 action applies. 2925 2926 2927@@UAHL@unbound.conf@ratelimit@@: *<number or 0>* 2928 Enable ratelimiting of queries sent to nameserver for performing recursion. 2929 0 disables the feature. 2930 This option is experimental at this time. 2931 2932 The ratelimit is in queries per second that are allowed. 2933 More queries are turned away with an error (SERVFAIL). 2934 Cached responses are not ratelimited by this setting. 2935 2936 This stops recursive floods, eg. random query names, but not spoofed 2937 reflection floods. 2938 The zone of the query is determined by examining the nameservers for it, 2939 the zone name is used to keep track of the rate. 2940 For example, 1000 may be a suitable value to stop the server from being 2941 overloaded with random names, and keeps unbound from sending traffic to the 2942 nameservers for those zones. 2943 2944 .. note:: Configured forwarders are excluded from ratelimiting. 2945 2946 Default: 0 2947 2948 2949@@UAHL@unbound.conf@ratelimit-size@@: *<memory size>* 2950 Give the size of the data structure in which the current ongoing rates are 2951 kept track in. 2952 In bytes or use m(mega), k(kilo), g(giga). 2953 The ratelimit structure is small, so this data structure likely does not 2954 need to be large. 2955 2956 Default: 4m 2957 2958 2959@@UAHL@unbound.conf@ratelimit-slabs@@: *<number>* 2960 Number of slabs in the ratelimit tracking data structure. 2961 Slabs reduce lock contention by threads. 2962 Must be set to a power of 2. 2963 Setting (close) to the number of cpus is a fairly good setting. 2964 If left unconfigured, it will be configured automatically to be a power of 2965 2 close to the number of configured threads in multi-threaded environments. 2966 2967 Default: (unconfigured) 2968 2969 2970@@UAHL@unbound.conf@ratelimit-factor@@: *<number>* 2971 Set the amount of queries to rate limit when the limit is exceeded. 2972 If set to 0, all queries are dropped for domains where the limit is 2973 exceeded. 2974 If set to another value, 1 in that number is allowed through to complete. 2975 Default is 10, allowing 1/10 traffic to flow normally. 2976 This can make ordinary queries complete (if repeatedly queried for), and 2977 enter the cache, whilst also mitigating the traffic flow by the factor 2978 given. 2979 2980 Default: 10 2981 2982 2983@@UAHL@unbound.conf@ratelimit-backoff@@: *<yes or no>* 2984 If enabled, the ratelimit is treated as a hard failure instead of the 2985 default maximum allowed constant rate. 2986 When the limit is reached, traffic is ratelimited and demand continues to 2987 be kept track of for a 2 second rate window. 2988 No traffic is allowed, except for 2989 :ref:`ratelimit-factor<unbound.conf.ratelimit-factor>`, until demand 2990 decreases below the configured ratelimit for a 2 second rate window. 2991 Useful to set :ref:`ratelimit<unbound.conf.ratelimit>` to a suspicious 2992 rate to aggressively limit unusually high traffic. 2993 2994 Default: no 2995 2996 2997@@UAHL@unbound.conf@ratelimit-for-domain@@: *<domain> <number qps or 0>* 2998 Override the global :ref:`ratelimit<unbound.conf.ratelimit>` for an exact 2999 match domain name with the listed number. 3000 You can give this for any number of names. 3001 For example, for a top-level-domain you may want to have a higher limit 3002 than other names. 3003 A value of 0 will disable ratelimiting for that domain. 3004 3005 3006@@UAHL@unbound.conf@ratelimit-below-domain@@: *<domain> <number qps or 0>* 3007 Override the global :ref:`ratelimit<unbound.conf.ratelimit>` for a domain 3008 name that ends in this name. 3009 You can give this multiple times, it then describes different settings in 3010 different parts of the namespace. 3011 The closest matching suffix is used to determine the qps limit. 3012 The rate for the exact matching domain name is not changed, use 3013 :ref:`ratelimit-for-domain<unbound.conf.ratelimit-for-domain>` to set 3014 that, you might want to use different settings for a top-level-domain and 3015 subdomains. 3016 A value of 0 will disable ratelimiting for domain names that end in this 3017 name. 3018 3019 3020@@UAHL@unbound.conf@ip-ratelimit@@: *<number or 0>* 3021 Enable global ratelimiting of queries accepted per ip address. 3022 This option is experimental at this time. 3023 The ratelimit is in queries per second that are allowed. 3024 More queries are completely dropped and will not receive a reply, SERVFAIL 3025 or otherwise. 3026 IP ratelimiting happens before looking in the cache. 3027 This may be useful for mitigating amplification attacks. 3028 Clients with a valid DNS Cookie will bypass the ratelimit. 3029 If a ratelimit for such clients is still needed, 3030 :ref:`ip-ratelimit-cookie<unbound.conf.ip-ratelimit-cookie>` 3031 can be used instead. 3032 3033 Default: 0 (disabled) 3034 3035 3036@@UAHL@unbound.conf@ip-ratelimit-cookie@@: *<number or 0>* 3037 Enable global ratelimiting of queries accepted per IP address with a valid 3038 DNS Cookie. 3039 This option is experimental at this time. 3040 The ratelimit is in queries per second that are allowed. 3041 More queries are completely dropped and will not receive a reply, SERVFAIL 3042 or otherwise. 3043 IP ratelimiting happens before looking in the cache. 3044 This option could be useful in combination with 3045 :ref:`allow_cookie<unbound.conf.access-control.action.allow_cookie>`, in an 3046 attempt to mitigate other amplification attacks than UDP reflections (e.g., 3047 attacks targeting Unbound itself) which are already handled with DNS 3048 Cookies. 3049 If used, the value is suggested to be higher than 3050 :ref:`ip-ratelimit<unbound.conf.ip-ratelimit>` e.g., tenfold. 3051 3052 Default: 0 (disabled) 3053 3054 3055@@UAHL@unbound.conf@ip-ratelimit-size@@: *<memory size>* 3056 Give the size of the data structure in which the current ongoing rates are 3057 kept track in. 3058 In bytes or use m(mega), k(kilo), g(giga). 3059 The IP ratelimit structure is small, so this data structure likely does not 3060 need to be large. 3061 3062 Default: 4m 3063 3064 3065@@UAHL@unbound.conf@ip-ratelimit-slabs@@: *<number>* 3066 Number of slabs in the ip ratelimit tracking data structure. 3067 Slabs reduce lock contention by threads. 3068 Must be set to a power of 2. 3069 Setting (close) to the number of cpus is a fairly good setting. 3070 If left unconfigured, it will be configured automatically to be a power of 3071 2 close to the number of configured threads in multi-threaded environments. 3072 3073 Default: (unconfigured) 3074 3075 3076@@UAHL@unbound.conf@ip-ratelimit-factor@@: *<number>* 3077 Set the amount of queries to rate limit when the limit is exceeded. 3078 If set to 0, all queries are dropped for addresses where the limit is 3079 exceeded. 3080 If set to another value, 1 in that number is allowed through to complete. 3081 Default is 10, allowing 1/10 traffic to flow normally. 3082 This can make ordinary queries complete (if repeatedly queried for), and 3083 enter the cache, whilst also mitigating the traffic flow by the factor 3084 given. 3085 3086 Default: 10 3087 3088 3089@@UAHL@unbound.conf@ip-ratelimit-backoff@@: *<yes or no>* 3090 If enabled, the rate limit is treated as a hard failure instead of the 3091 default maximum allowed constant rate. 3092 When the limit is reached, traffic is ratelimited and demand continues to 3093 be kept track of for a 2 second rate window. 3094 No traffic is allowed, except for 3095 :ref:`ip-ratelimit-factor<unbound.conf.ip-ratelimit-factor>`, until demand 3096 decreases below the configured ratelimit for a 2 second rate window. 3097 Useful to set :ref:`ip-ratelimit<unbound.conf.ip-ratelimit>` to a 3098 suspicious rate to aggressively limit unusually high traffic. 3099 3100 Default: no 3101 3102 3103@@UAHL@unbound.conf@outbound-msg-retry@@: *<number>* 3104 The number of retries, per upstream nameserver in a delegation, that 3105 Unbound will attempt in case a throwaway response is received. 3106 No response (timeout) contributes to the retry counter. 3107 If a forward/stub zone is used, this is the number of retries per 3108 nameserver in the zone. 3109 3110 Default: 5 3111 3112 3113@@UAHL@unbound.conf@max-sent-count@@: *<number>* 3114 Hard limit on the number of outgoing queries Unbound will make while 3115 resolving a name, making sure large NS sets do not loop. 3116 Results in SERVFAIL when reached. 3117 It resets on query restarts (e.g., CNAME) and referrals. 3118 3119 Default: 32 3120 3121 3122@@UAHL@unbound.conf@max-query-restarts@@: *<number>* 3123 Hard limit on the number of times Unbound is allowed to restart a query 3124 upon encountering a CNAME record. 3125 Results in SERVFAIL when reached. 3126 Changing this value needs caution as it can allow long CNAME chains to be 3127 accepted, where Unbound needs to verify (resolve) each link individually. 3128 3129 Default: 11 3130 3131 3132@@UAHL@unbound.conf@iter-scrub-ns@@: *<number>* 3133 Limit on the number of NS records allowed in an rrset of type NS, from the 3134 iterator scrubber. 3135 This protects the internals of the resolver from overly large NS sets. 3136 3137 Default: 20 3138 3139 3140@@UAHL@unbound.conf@iter-scrub-cname@@: *<number>* 3141 Limit on the number of CNAME, DNAME records in an answer, from the iterator 3142 scrubber. 3143 This protects the internals of the resolver from overly long indirection 3144 chains. 3145 Clips off the remainder of the reply packet at that point. 3146 3147 Default: 11 3148 3149 3150@@UAHL@unbound.conf@max-global-quota@@: *<number>* 3151 Limit on the number of upstream queries sent out for an incoming query and 3152 its subqueries from recursion. 3153 It is not reset during the resolution. 3154 When it is exceeded the query is failed and the lookup process stops. 3155 3156 Default: 200 3157 3158 3159@@UAHL@unbound.conf@fast-server-permil@@: *<number>* 3160 Specify how many times out of 1000 to pick from the set of fastest servers. 3161 0 turns the feature off. 3162 A value of 900 would pick from the fastest servers 90 percent of the time, 3163 and would perform normal exploration of random servers for the remaining 3164 time. 3165 When :ref:`prefetch<unbound.conf.prefetch>` is enabled (or 3166 :ref:`serve-expired<unbound.conf.serve-expired>`), such prefetches are not 3167 sped up, because there is no one waiting for it, and it presents a good 3168 moment to perform server exploration. 3169 The :ref:`fast-server-num<unbound.conf.fast-server-num>` option can be 3170 used to specify the size of the fastest servers set. 3171 3172 Default: 0 3173 3174 3175@@UAHL@unbound.conf@fast-server-num@@: *<number>* 3176 Set the number of servers that should be used for fast server selection. 3177 Only use the fastest specified number of servers with the 3178 :ref:`fast-server-permil<unbound.conf.fast-server-permil>` option, that 3179 turns this on or off. 3180 3181 Default: 3 3182 3183 3184@@UAHL@unbound.conf@answer-cookie@@: *<yes or no>* 3185 If enabled, Unbound will answer to requests containing DNS Cookies as 3186 specified in RFC 7873 and RFC 9018. 3187 3188 Default: no 3189 3190 3191@@UAHL@unbound.conf@cookie-secret@@: *"<128 bit hex string>"* 3192 Server's secret for DNS Cookie generation. 3193 Useful to explicitly set for servers in an anycast deployment that need to 3194 share the secret in order to verify each other's Server Cookies. 3195 An example hex string would be "000102030405060708090a0b0c0d0e0f". 3196 3197 .. note:: 3198 This option is ignored if a 3199 :ref:`cookie-secret-file<unbound.conf.cookie-secret-file>` is present. 3200 In that case the secrets from that file are used in DNS Cookie 3201 calculations. 3202 3203 Default: 128 bits random secret generated at startup time 3204 3205 3206@@UAHL@unbound.conf@cookie-secret-file@@: *<filename>* 3207 File from which the secrets are read used in DNS Cookie calculations. 3208 When this file exists, the secrets in this file are used and the secret 3209 specified by the 3210 :ref:`cookie-secret<unbound.conf.cookie-secret>` option is ignored. 3211 Enable it by setting a filename, like 3212 "/usr/local/etc/unbound_cookiesecrets.txt". 3213 The content of this file must be manipulated with the 3214 :ref:`add_cookie_secret<unbound-control.commands.add_cookie_secret>`, 3215 :ref:`drop_cookie_secret<unbound-control.commands.drop_cookie_secret>` and 3216 :ref:`activate_cookie_secret<unbound-control.commands.activate_cookie_secret>` 3217 commands to the :doc:`unbound-control(8)</manpages/unbound-control>` tool. 3218 Please see that manpage on how to perform a safe cookie secret rollover. 3219 3220 Default: "" (disabled) 3221 3222 3223@@UAHL@unbound.conf@edns-client-string@@: *<IP netblock> <string>* 3224 Include an EDNS0 option containing configured ASCII string in queries with 3225 destination address matching the configured *<IP netblock>*. 3226 This configuration option can be used multiple times. 3227 The most specific match will be used. 3228 3229 3230@@UAHL@unbound.conf@edns-client-string-opcode@@: *<opcode>* 3231 EDNS0 option code for the 3232 :ref:`edns-client-string<unbound.conf.edns-client-string>` option, from 0 3233 to 65535. 3234 A value from the 'Reserved for Local/Experimental' range (65001-65534) 3235 should be used. 3236 3237 Default: 65001 3238 3239 3240@@UAHL@unbound.conf@ede@@: *<yes or no>* 3241 If enabled, Unbound will respond with Extended DNS Error codes 3242 (:rfc:`8914`). 3243 These EDEs provide additional information with a response mainly for, but 3244 not limited to, DNS and DNSSEC errors. 3245 3246 When the :ref:`val-log-level<unbound.conf.val-log-level>` option is also 3247 set to ``2``, responses with Extended DNS Errors concerning DNSSEC failures 3248 will also contain a descriptive text message about the reason for the 3249 failure. 3250 3251 Default: no 3252 3253 3254@@UAHL@unbound.conf@ede-serve-expired@@: *<yes or no>* 3255 If enabled, Unbound will attach an Extended DNS Error (:rfc:`8914`) *Code 3 3256 - Stale Answer* as EDNS0 option to the expired response. 3257 3258 .. note:: 3259 :ref:`ede: yes<unbound.conf.ede>` needs to be set as well for this to 3260 work. 3261 3262 Default: no 3263 3264 3265@@UAHL@unbound.conf@dns-error-reporting@@: *<yes or no>* 3266 If enabled, Unbound will send DNS Error Reports (:rfc:`9567`). 3267 The name servers need to express support by attaching the Report-Channel 3268 EDNS0 option on their replies specifying the reporting agent for the zone. 3269 Any errors encountered during resolution that would result in Unbound 3270 generating an Extended DNS Error (:rfc:`8914`) will be reported to the 3271 zone's reporting agent. 3272 3273 The :ref:`ede<unbound.conf.ede>` option does not need to be enabled for 3274 this to work. 3275 3276 It is advised that the 3277 :ref:`qname-minimisation<unbound.conf.qname-minimisation>` option is also 3278 enabled to increase privacy on the outgoing reports. 3279 3280 Default: no 3281 3282.. _unbound.conf.remote: 3283 3284Remote Control Options 3285^^^^^^^^^^^^^^^^^^^^^^ 3286 3287In the **remote-control:** clause are the declarations for the remote control 3288facility. 3289If this is enabled, the :doc:`unbound-control(8)</manpages/unbound-control>` 3290utility can be used to send commands to the running Unbound server. 3291The server uses these clauses to setup TLSv1 security for the connection. 3292The :doc:`unbound-control(8)</manpages/unbound-control>` utility also reads the 3293**remote-control:** section for options. 3294To setup the correct self-signed certificates use the 3295*unbound-control-setup(8)* utility. 3296 3297 3298@@UAHL@unbound.conf.remote@control-enable@@: *<yes or no>* 3299 The option is used to enable remote control. 3300 If turned off, the server does not listen for control commands. 3301 3302 Default: no 3303 3304 3305@@UAHL@unbound.conf.remote@control-interface@@: *<IP address or interface name or path>* 3306 Give IPv4 or IPv6 addresses or local socket path to listen on for control 3307 commands. 3308 If an interface name is used instead of an IP address, the list of IP 3309 addresses on that interface are used. 3310 3311 By default localhost (``127.0.0.1`` and ``::1``) is listened to. 3312 Use ``0.0.0.0`` and ``::0`` to listen to all interfaces. 3313 If you change this and permissions have been dropped, you must restart the 3314 server for the change to take effect. 3315 3316 If you set it to an absolute path, a unix domain socket is used. 3317 This socket does not use the certificates and keys, so those files need not 3318 be present. 3319 To restrict access, Unbound sets permissions on the file to the user and 3320 group that is configured, the access bits are set to allow the group 3321 members to access the control socket file. 3322 Put users that need to access the socket in the that group. 3323 To restrict access further, create a directory to put the control socket in 3324 and restrict access to that directory. 3325 3326 3327@@UAHL@unbound.conf.remote@control-port@@: *<port number>* 3328 The port number to listen on for IPv4 or IPv6 control interfaces. 3329 3330 .. note:: 3331 If you change this and permissions have been dropped, you must restart 3332 the server for the change to take effect. 3333 3334 Default: 8953 3335 3336 3337@@UAHL@unbound.conf.remote@control-use-cert@@: *<yes or no>* 3338 For localhost 3339 :ref:`control-interface<unbound.conf.remote.control-interface>` you can 3340 disable the use of TLS by setting this option to "no". 3341 For local sockets, TLS is disabled and the value of this option is ignored. 3342 3343 Default: yes 3344 3345 3346@@UAHL@unbound.conf.remote@server-key-file@@: *<private key file>* 3347 Path to the server private key. 3348 This file is generated by the 3349 :doc:`unbound-control-setup(8)</manpages/unbound-control>` utility. 3350 This file is used by the Unbound server, but not by 3351 :doc:`unbound-control(8)</manpages/unbound-control>`. 3352 3353 Default: unbound_server.key 3354 3355 3356@@UAHL@unbound.conf.remote@server-cert-file@@: *<certificate file.pem>* 3357 Path to the server self signed certificate. 3358 This file is generated by the 3359 :doc:`unbound-control-setup(8)</manpages/unbound-control>` utility. 3360 This file is used by the Unbound server, and also by 3361 :doc:`unbound-control(8)</manpages/unbound-control>`. 3362 3363 Default: unbound_server.pem 3364 3365 3366@@UAHL@unbound.conf.remote@control-key-file@@: *<private key file>* 3367 Path to the control client private key. 3368 This file is generated by the 3369 :doc:`unbound-control-setup(8)</manpages/unbound-control>` utility. 3370 This file is used by :doc:`unbound-control(8)</manpages/unbound-control>`. 3371 3372 Default: unbound_control.key 3373 3374 3375@@UAHL@unbound.conf.remote@control-cert-file@@: *<certificate file.pem>* 3376 Path to the control client certificate. 3377 This certificate has to be signed with the server certificate. 3378 This file is generated by the 3379 :doc:`unbound-control-setup(8)</manpages/unbound-control>` utility. 3380 This file is used by :doc:`unbound-control(8)</manpages/unbound-control>`. 3381 3382 Default: unbound_control.pem 3383 3384.. _unbound.conf.stub: 3385 3386Stub Zone Options 3387^^^^^^^^^^^^^^^^^ 3388 3389There may be multiple **stub-zone:** clauses. 3390Each with a :ref:`name<unbound.conf.stub.name>` and zero or more hostnames or 3391IP addresses. 3392For the stub zone this list of nameservers is used. 3393Class IN is assumed. 3394The servers should be authority servers, not recursors; Unbound performs the 3395recursive processing itself for stub zones. 3396 3397The stub zone can be used to configure authoritative data to be used by the 3398resolver that cannot be accessed using the public internet servers. 3399This is useful for company-local data or private zones. 3400Setup an authoritative server on a different host (or different port). 3401Enter a config entry for Unbound with: 3402 3403.. code-block:: text 3404 3405 stub-addr: <ip address of host[@port]> 3406 3407The Unbound resolver can then access the data, without referring to the public 3408internet for it. 3409 3410This setup allows DNSSEC signed zones to be served by that authoritative 3411server, in which case a trusted key entry with the public key can be put in 3412config, so that Unbound can validate the data and set the AD bit on replies for 3413the private zone (authoritative servers do not set the AD bit). 3414This setup makes Unbound capable of answering queries for the private zone, and 3415can even set the AD bit ('authentic'), but the AA ('authoritative') bit is not 3416set on these replies. 3417 3418Consider adding :ref:`server<unbound.conf.server>` statements for 3419:ref:`domain-insecure<unbound.conf.domain-insecure>` and for 3420:ref:`local-zone: \<name\> nodefault<unbound.conf.local-zone.type.nodefault>` 3421for the zone if it is a locally served zone. 3422The insecure clause stops DNSSEC from invalidating the zone. 3423The :ref:`local-zone: nodefault<unbound.conf.local-zone.type.nodefault>` (or 3424:ref:`transparent<unbound.conf.local-zone.type.transparent>`) clause makes the 3425(reverse-) zone bypass Unbound's filtering of :rfc:`1918` zones. 3426 3427 3428@@UAHL@unbound.conf.stub@name@@: *<domain name>* 3429 Name of the stub zone. 3430 This is the full domain name of the zone. 3431 3432 3433@@UAHL@unbound.conf.stub@stub-host@@: *<domain name>* 3434 Name of stub zone nameserver. 3435 Is itself resolved before it is used. 3436 3437 To use a non-default port for DNS communication append ``'@'`` with the 3438 port number. 3439 3440 If TLS is enabled, then you can append a ``'#'`` and a name, then it'll 3441 check the TLS authentication certificates with that name. 3442 3443 If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first. 3444 If only ``'#'`` is used the default port is the configured 3445 :ref:`tls-port<unbound.conf.tls-port>`. 3446 3447 3448@@UAHL@unbound.conf.stub@stub-addr@@: *<IP address>* 3449 IP address of stub zone nameserver. 3450 Can be IPv4 or IPv6. 3451 3452 To use a non-default port for DNS communication append ``'@'`` with the 3453 port number. 3454 3455 If TLS is enabled, then you can append a ``'#'`` and a name, then it'll 3456 check the tls authentication certificates with that name. 3457 3458 If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first. 3459 If only ``'#'`` is used the default port is the configured 3460 :ref:`tls-port<unbound.conf.tls-port>`. 3461 3462 3463@@UAHL@unbound.conf.stub@stub-prime@@: *<yes or no>* 3464 If enabled it performs NS set priming, which is similar to root hints, 3465 where it starts using the list of nameservers currently published by the 3466 zone. 3467 Thus, if the hint list is slightly outdated, the resolver picks up a 3468 correct list online. 3469 3470 Default: no 3471 3472 3473@@UAHL@unbound.conf.stub@stub-first@@: *<yes or no>* 3474 If enabled, a query is attempted without the stub clause if it fails. 3475 The data could not be retrieved and would have caused SERVFAIL because the 3476 servers are unreachable, instead it is tried without this clause. 3477 3478 Default: no 3479 3480 3481@@UAHL@unbound.conf.stub@stub-tls-upstream@@: *<yes or no>* 3482 Enabled or disable whether the queries to this stub use TLS for transport. 3483 3484 Default: no 3485 3486 3487@@UAHL@unbound.conf.stub@stub-ssl-upstream@@: *<yes or no>* 3488 Alternate syntax for 3489 :ref:`stub-tls-upstream<unbound.conf.stub.stub-tls-upstream>`. 3490 3491 3492@@UAHL@unbound.conf.stub@stub-tcp-upstream@@: *<yes or no>* 3493 If it is set to "yes" then upstream queries use TCP only for transport 3494 regardless of global flag :ref:`tcp-upstream<unbound.conf.tcp-upstream>`. 3495 3496 Default: no 3497 3498 3499@@UAHL@unbound.conf.stub@stub-no-cache@@: *<yes or no>* 3500 If enabled, data inside the stub is not cached. 3501 This is useful when you want immediate changes to be visible. 3502 3503 Default: no 3504 3505.. _unbound.conf.forward: 3506 3507Forward Zone Options 3508^^^^^^^^^^^^^^^^^^^^ 3509 3510There may be multiple **forward-zone:** clauses. 3511Each with a :ref:`name<unbound.conf.forward.name>` and zero or more hostnames 3512or IP addresses. 3513For the forward zone this list of nameservers is used to forward the queries 3514to. 3515The servers listed as :ref:`forward-host<unbound.conf.forward.forward-host>` 3516and :ref:`forward-addr<unbound.conf.forward.forward-addr>` have to handle 3517further recursion for the query. 3518Thus, those servers are not authority servers, but are (just like Unbound is) 3519recursive servers too; Unbound does not perform recursion itself for the 3520forward zone, it lets the remote server do it. 3521Class IN is assumed. 3522CNAMEs are chased by Unbound itself, asking the remote server for every name in 3523the indirection chain, to protect the local cache from illegal indirect 3524referenced items. 3525A :ref:`forward-zone<unbound.conf.forward>` entry with name 3526``"."`` and a :ref:`forward-addr<unbound.conf.forward.forward-addr>` target 3527will forward all queries to that other server (unless it can answer from the 3528cache). 3529 3530 3531@@UAHL@unbound.conf.forward@name@@: *<domain name>* 3532 Name of the forward zone. 3533 This is the full domain name of the zone. 3534 3535 3536@@UAHL@unbound.conf.forward@forward-host@@: *<domain name>* 3537 Name of server to forward to. 3538 Is itself resolved before it is used. 3539 3540 To use a non-default port for DNS communication append ``'@'`` with the 3541 port number. 3542 3543 If TLS is enabled, then you can append a ``'#'`` and a name, then it'll 3544 check the TLS authentication certificates with that name. 3545 3546 If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first. 3547 If only ``'#'`` is used the default port is the configured 3548 :ref:`tls-port<unbound.conf.tls-port>`. 3549 3550 3551@@UAHL@unbound.conf.forward@forward-addr@@: *<IP address>* 3552 IP address of server to forward to. 3553 Can be IPv4 or IPv6. 3554 3555 To use a non-default port for DNS communication append ``'@'`` with the 3556 port number. 3557 3558 If TLS is enabled, then you can append a ``'#'`` and a name, then it'll 3559 check the tls authentication certificates with that name. 3560 3561 If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first. 3562 If only ``'#'`` is used the default port is the configured 3563 :ref:`tls-port<unbound.conf.tls-port>`. 3564 3565 At high verbosity it logs the TLS certificate, with TLS enabled. 3566 If you leave out the ``'#'`` and auth name from the 3567 :ref:`forward-addr<unbound.conf.forward.forward-addr>`, any name is 3568 accepted. 3569 The cert must also match a CA from the 3570 :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>`. 3571 3572 3573@@UAHL@unbound.conf.forward@forward-first@@: *<yes or no>* 3574 If a forwarded query is met with a SERVFAIL error, and this option is 3575 enabled, Unbound will fall back to normal recursive resolution for this 3576 query as if no query forwarding had been specified. 3577 3578 Default: no 3579 3580 3581@@UAHL@unbound.conf.forward@forward-tls-upstream@@: *<yes or no>* 3582 Enabled or disable whether the queries to this forwarder use TLS for 3583 transport. 3584 If you enable this, also configure a 3585 :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>` or use 3586 :ref:`tls-win-cert<unbound.conf.tls-win-cert>` to load CA certs, otherwise 3587 the connections cannot be authenticated. 3588 3589 Default: no 3590 3591 3592@@UAHL@unbound.conf.forward@forward-ssl-upstream@@: *<yes or no>* 3593 Alternate syntax for 3594 :ref:`forward-tls-upstream<unbound.conf.forward.forward-tls-upstream>`. 3595 3596 3597@@UAHL@unbound.conf.forward@forward-tcp-upstream@@: *<yes or no>* 3598 If it is set to "yes" then upstream queries use TCP only for transport 3599 regardless of global flag :ref:`tcp-upstream<unbound.conf.tcp-upstream>`. 3600 3601 Default: no 3602 3603 3604@@UAHL@unbound.conf.forward@forward-no-cache@@: *<yes or no>* 3605 If enabled, data inside the forward is not cached. 3606 This is useful when you want immediate changes to be visible. 3607 3608 Default: no 3609 3610.. _unbound.conf.auth: 3611 3612Authority Zone Options 3613^^^^^^^^^^^^^^^^^^^^^^ 3614 3615Authority zones are configured with **auth-zone:**, and each one must have a 3616:ref:`name<unbound.conf.auth.name>`. 3617There can be multiple ones, by listing multiple auth-zone clauses, each with a 3618different name, pertaining to that part of the namespace. 3619The authority zone with the name closest to the name looked up is used. 3620Authority zones can be processed on two distinct, non-exclusive, configurable 3621stages. 3622 3623With :ref:`for-downstream: yes<unbound.conf.auth.for-downstream>` (default), 3624authority zones are processed after **local-zones** and before cache. 3625When used in this manner, Unbound responds like an authority server with no 3626further processing other than returning an answer from the zone contents. 3627A notable example, in this case, is CNAME records which are returned verbatim 3628to downstream clients without further resolution. 3629 3630With :ref:`for-upstream: yes<unbound.conf.auth.for-upstream>` (default), 3631authority zones are processed after the cache lookup, just before going to the 3632network to fetch information for recursion. 3633When used in this manner they provide a local copy of an authority server 3634that speeds up lookups for that data during resolving. 3635 3636If both options are enabled (default), client queries for an authority zone are 3637answered authoritatively from Unbound, while internal queries that require data 3638from the authority zone consult the local zone data instead of going to the 3639network. 3640 3641An interesting configuration is 3642:ref:`for-downstream: no<unbound.conf.auth.for-downstream>`, 3643:ref:`for-upstream: yes<unbound.conf.auth.for-upstream>` 3644that allows for hyperlocal behavior where both client and internal queries 3645consult the local zone data while resolving. 3646In this case, the aforementioned CNAME example will result in a thoroughly 3647resolved answer. 3648 3649Authority zones can be read from zonefile. 3650And can be kept updated via AXFR and IXFR. 3651After update the zonefile is rewritten. 3652The update mechanism uses the SOA timer values and performs SOA UDP queries to 3653detect zone changes. 3654 3655If the update fetch fails, the timers in the SOA record are used to time 3656another fetch attempt. 3657Until the SOA expiry timer is reached. 3658Then the zone is expired. 3659When a zone is expired, queries are SERVFAIL, and any new serial number is 3660accepted from the primary (even if older), and if fallback is enabled, the 3661fallback activates to fetch from the upstream instead of the SERVFAIL. 3662 3663 3664@@UAHL@unbound.conf.auth@name@@: *<zone name>* 3665 Name of the authority zone. 3666 3667 3668@@UAHL@unbound.conf.auth@primary@@: *<IP address or host name>* 3669 Where to download a copy of the zone from, with AXFR and IXFR. 3670 Multiple primaries can be specified. 3671 They are all tried if one fails. 3672 3673 To use a non-default port for DNS communication append ``'@'`` with the 3674 port number. 3675 3676 You can append a ``'#'`` and a name, then AXFR over TLS can be used and the 3677 TLS authentication certificates will be checked with that name. 3678 3679 If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first. 3680 If you point it at another Unbound instance, it would not work because that 3681 does not support AXFR/IXFR for the zone, but if you used 3682 :ref:`url<unbound.conf.auth.url>` to download the zonefile as a text file 3683 from a webserver that would work. 3684 3685 If you specify the hostname, you cannot use the domain from the zonefile, 3686 because it may not have that when retrieving that data, instead use a plain 3687 IP address to avoid a circular dependency on retrieving that IP address. 3688 3689 3690@@UAHL@unbound.conf.auth@master@@: *<IP address or host name>* 3691 Alternate syntax for :ref:`primary<unbound.conf.auth.primary>`. 3692 3693 3694@@UAHL@unbound.conf.auth@url@@: *<URL to zone file>* 3695 Where to download a zonefile for the zone. 3696 With HTTP or HTTPS. 3697 An example for the url is: 3698 3699 .. code-block:: text 3700 3701 http://www.example.com/example.org.zone 3702 3703 Multiple url statements can be given, they are tried in turn. 3704 3705 If only urls are given the SOA refresh timer is used to wait for making new 3706 downloads. 3707 If also primaries are listed, the primaries are first probed with UDP SOA 3708 queries to see if the SOA serial number has changed, reducing the number of 3709 downloads. 3710 If none of the urls work, the primaries are tried with IXFR and AXFR. 3711 3712 For HTTPS, the :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>` and 3713 the hostname from the url are used to authenticate the connection. 3714 3715 If you specify a hostname in the URL, you cannot use the domain from the 3716 zonefile, because it may not have that when retrieving that data, instead 3717 use a plain IP address to avoid a circular dependency on retrieving that IP 3718 address. 3719 3720 Avoid dependencies on name lookups by using a notation like 3721 ``"http://192.0.2.1/unbound-primaries/example.com.zone"``, with an explicit 3722 IP address. 3723 3724 3725@@UAHL@unbound.conf.auth@allow-notify@@: *<IP address or host name or netblockIP/prefix>* 3726 With :ref:`allow-notify<unbound.conf.auth.allow-notify>` you can specify 3727 additional sources of notifies. 3728 When notified, the server attempts to first probe and then zone transfer. 3729 If the notify is from a primary, it first attempts that primary. 3730 Otherwise other primaries are attempted. 3731 If there are no primaries, but only urls, the file is downloaded when 3732 notified. 3733 3734 .. note:: 3735 The primaries from :ref:`primary<unbound.conf.auth.primary>` and 3736 :ref:`url<unbound.conf.auth.url>` statements are allowed notify by 3737 default. 3738 3739 3740@@UAHL@unbound.conf.auth@fallback-enabled@@: *<yes or no>* 3741 If enabled, Unbound falls back to querying the internet as a resolver for 3742 this zone when lookups fail. 3743 For example for DNSSEC validation failures. 3744 3745 Default: no 3746 3747 3748@@UAHL@unbound.conf.auth@for-downstream@@: *<yes or no>* 3749 If enabled, Unbound serves authority responses to downstream clients for 3750 this zone. 3751 This option makes Unbound behave, for the queries with names in this zone, 3752 like one of the authority servers for that zone. 3753 3754 Turn it off if you want Unbound to provide recursion for the zone but have 3755 a local copy of zone data. 3756 3757 If :ref:`for-downstream: no<unbound.conf.auth.for-downstream>` and 3758 :ref:`for-upstream: yes<unbound.conf.auth.for-upstream>` are set, then 3759 Unbound will DNSSEC validate the contents of the zone before serving the 3760 zone contents to clients and store validation results in the cache. 3761 3762 Default: yes 3763 3764 3765 3766@@UAHL@unbound.conf.auth@for-upstream@@: *<yes or no>* 3767 If enabled, Unbound fetches data from this data collection for answering 3768 recursion queries. 3769 Instead of sending queries over the internet to the authority servers for 3770 this zone, it'll fetch the data directly from the zone data. 3771 3772 Turn it on when you want Unbound to provide recursion for downstream 3773 clients, and use the zone data as a local copy to speed up lookups. 3774 3775 Default: yes 3776 3777 3778@@UAHL@unbound.conf.auth@zonemd-check@@: *<yes or no>* 3779 Enable this option to check ZONEMD records in the zone. 3780 The ZONEMD record is a checksum over the zone data. 3781 This includes glue in the zone and data from the zone file, and excludes 3782 comments from the zone file. 3783 When there is a DNSSEC chain of trust, DNSSEC signatures are checked too. 3784 3785 Default: no 3786 3787 3788@@UAHL@unbound.conf.auth@zonemd-reject-absence@@: *<yes or no>* 3789 Enable this option to reject the absence of the ZONEMD record. 3790 Without it, when ZONEMD is not there it is not checked. 3791 3792 It is useful to enable for a non-DNSSEC signed zone where the operator 3793 wants to require the verification of a ZONEMD, hence a missing ZONEMD is a 3794 failure. 3795 3796 The action upon failure is controlled by the 3797 :ref:`zonemd-permissive-mode<unbound.conf.zonemd-permissive-mode>` option, 3798 for log only or also block the zone. 3799 3800 Without the option, absence of a ZONEMD is only a failure when the zone is 3801 DNSSEC signed, and we have a trust anchor, and the DNSSEC verification of 3802 the absence of the ZONEMD fails. 3803 With the option enabled, the absence of a ZONEMD is always a failure, also 3804 for nonDNSSEC signed zones. 3805 3806 Default: no 3807 3808 3809@@UAHL@unbound.conf.auth@zonefile@@: *<filename>* 3810 The filename where the zone is stored. 3811 If not given then no zonefile is used. 3812 If the file does not exist or is empty, Unbound will attempt to fetch zone 3813 data (eg. from the primary servers). 3814 3815.. _unbound.conf.view: 3816 3817View Options 3818^^^^^^^^^^^^ 3819 3820There may be multiple **view:** clauses. 3821Each with a :ref:`name<unbound.conf.view.name>` and zero or more 3822:ref:`local-zone<unbound.conf.view.local-zone>` and 3823:ref:`local-data<unbound.conf.view.local-data>` attributes. 3824Views can also contain :ref:`view-first<unbound.conf.view.view-first>`, 3825:ref:`response-ip<unbound.conf.response-ip>`, 3826:ref:`response-ip-data<unbound.conf.response-ip-data>` and 3827:ref:`local-data-ptr<unbound.conf.view.local-data-ptr>` attributes. 3828View can be mapped to requests by specifying the view name in an 3829:ref:`access-control-view<unbound.conf.access-control-view>` attribute. 3830Options from matching views will override global options. 3831Global options will be used if no matching view is found, or when the matching 3832view does not have the option specified. 3833 3834 3835@@UAHL@unbound.conf.view@name@@: *<view name>* 3836 Name of the view. 3837 Must be unique. 3838 This name is used in the 3839 :ref:`access-control-view<unbound.conf.access-control-view>` attribute. 3840 3841 3842@@UAHL@unbound.conf.view@local-zone@@: *<zone> <type>* 3843 View specific local zone elements. 3844 Has the same types and behaviour as the global 3845 :ref:`local-zone<unbound.conf.local-zone>` elements. 3846 When there is at least one *local-zone:* specified and :ref:`view-first: 3847 no<unbound.conf.view.view-first>` is set, the default local-zones will be 3848 added to this view. 3849 Defaults can be disabled using the nodefault type. 3850 When :ref:`view-first: yes<unbound.conf.view.view-first>` is set or when a 3851 view does not have a :ref:`local-zone<unbound.conf.view.local-zone>`, the 3852 global :ref:`local-zone<unbound.conf.local-zone>` will be used including 3853 it's default zones. 3854 3855 3856@@UAHL@unbound.conf.view@local-data@@: *"<resource record string>"* 3857 View specific local data elements. 3858 Has the same behaviour as the global 3859 :ref:`local-data<unbound.conf.local-data>` elements. 3860 3861 3862@@UAHL@unbound.conf.view@local-data-ptr@@: *"IPaddr name"* 3863 View specific local-data-ptr elements. 3864 Has the same behaviour as the global 3865 :ref:`local-data-ptr<unbound.conf.local-data-ptr>` elements. 3866 3867 3868@@UAHL@unbound.conf.view@view-first@@: *<yes or no>* 3869 If enabled, it attempts to use the global 3870 :ref:`local-zone<unbound.conf.local-zone>` and 3871 :ref:`local-data<unbound.conf.local-data>` if there is no match in the 3872 view specific options. 3873 3874 Default: no 3875 3876Python Module Options 3877^^^^^^^^^^^^^^^^^^^^^ 3878 3879The **python:** clause gives the settings for the *python(1)* script module. 3880This module acts like the iterator and validator modules do, on queries and 3881answers. 3882To enable the script module it has to be compiled into the daemon, and the word 3883``python`` has to be put in the 3884:ref:`module-config<unbound.conf.module-config>` option (usually first, or 3885between the validator and iterator). 3886Multiple instances of the python module are supported by adding the word 3887``python`` more than once. 3888 3889If the :ref:`chroot<unbound.conf.chroot>` option is enabled, you should make 3890sure Python's library directory structure is bind mounted in the new root 3891environment, see *mount(8)*. 3892Also the :ref:`python-script<unbound.conf.python.python-script>` path should 3893be specified as an absolute path relative to the new root, or as a relative 3894path to the working directory. 3895 3896 3897@@UAHL@unbound.conf.python@python-script@@: *<python file>* 3898 The script file to load. 3899 Repeat this option for every python module instance added to the 3900 :ref:`module-config<unbound.conf.module-config>` option. 3901 3902Dynamic Library Module Options 3903^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3904 3905The **dynlib:** clause gives the settings for the ``dynlib`` module. 3906This module is only a very small wrapper that allows dynamic modules to be 3907loaded on runtime instead of being compiled into the application. 3908To enable the dynlib module it has to be compiled into the daemon, and the word 3909``dynlib`` has to be put in the 3910:ref:`module-config<unbound.conf.module-config>` attribute. 3911Multiple instances of dynamic libraries are supported by adding the word 3912``dynlib`` more than once. 3913 3914The :ref:`dynlib-file<unbound.conf.dynlib.dynlib-file>` path should be 3915specified as an absolute path relative to the new path set by 3916:ref:`chroot<unbound.conf.chroot>`, or as a relative path to the working 3917directory. 3918 3919 3920@@UAHL@unbound.conf.dynlib@dynlib-file@@: *<dynlib file>* 3921 The dynamic library file to load. 3922 Repeat this option for every dynlib module instance added to the 3923 :ref:`module-config<unbound.conf.module-config>` option. 3924 3925DNS64 Module Options 3926^^^^^^^^^^^^^^^^^^^^ 3927 3928The ``dns64`` module must be configured in the 3929:ref:`module-config<unbound.conf.module-config>` directive, e.g.: 3930 3931.. code-block:: text 3932 3933 module-config: "dns64 validator iterator" 3934 3935and be compiled into the daemon to be enabled. 3936 3937.. note:: 3938 These settings go in the :ref:`server:<unbound.conf.server>` section. 3939 3940 3941@@UAHL@unbound.conf.dns64@dns64-prefix@@: *<IPv6 prefix>* 3942 This sets the DNS64 prefix to use to synthesize AAAA records with. 3943 It must be /96 or shorter. 3944 3945 Default: 64:ff9b::/96 3946 3947 3948@@UAHL@unbound.conf.dns64@dns64-synthall@@: *<yes or no>* 3949 .. warning:: Debugging feature! 3950 3951 If enabled, synthesize all AAAA records despite the presence of actual AAAA 3952 records. 3953 3954 Default: no 3955 3956 3957@@UAHL@unbound.conf.dns64@dns64-ignore-aaaa@@: *<domain name>* 3958 List domain for which the AAAA records are ignored and the A record is used 3959 by DNS64 processing instead. 3960 Can be entered multiple times, list a new domain for which it applies, one 3961 per line. 3962 Applies also to names underneath the name given. 3963 3964NAT64 Operation 3965^^^^^^^^^^^^^^^ 3966 3967NAT64 operation allows using a NAT64 prefix for outbound requests to IPv4-only 3968servers. 3969It is controlled by two options in the 3970:ref:`server:<unbound.conf.server>` section: 3971 3972 3973@@UAHL@unbound.conf.nat64@do-nat64@@: *<yes or no>* 3974 Use NAT64 to reach IPv4-only servers. 3975 Consider also enabling :ref:`prefer-ip6<unbound.conf.prefer-ip6>` 3976 to prefer native IPv6 connections to nameservers. 3977 3978 Default: no 3979 3980 3981@@UAHL@unbound.conf.nat64@nat64-prefix@@: *<IPv6 prefix>* 3982 Use a specific NAT64 prefix to reach IPv4-only servers. 3983 The prefix length must be one of /32, /40, /48, /56, /64 or /96. 3984 3985 Default: 64:ff9b::/96 (same as :ref:`dns64-prefix<unbound.conf.dns64.dns64-prefix>`) 3986 3987DNSCrypt Options 3988^^^^^^^^^^^^^^^^ 3989 3990The **dnscrypt:** clause gives the settings of the dnscrypt channel. 3991While those options are available, they are only meaningful if Unbound was 3992compiled with ``--enable-dnscrypt``. 3993Currently certificate and secret/public keys cannot be generated by Unbound. 3994You can use dnscrypt-wrapper to generate those: 3995https://github.com/cofyc/dnscrypt-wrapper/blob/master/README.md#usage 3996 3997 3998@@UAHL@unbound.conf.dnscrypt@dnscrypt-enable@@: *<yes or no>* 3999 Whether or not the dnscrypt config should be enabled. 4000 You may define configuration but not activate it. 4001 4002 Default: no 4003 4004 4005@@UAHL@unbound.conf.dnscrypt@dnscrypt-port@@: *<port number>* 4006 On which port should dnscrypt should be activated. 4007 4008 .. note:: 4009 There should be a matching interface option defined in the 4010 :ref:`server:<unbound.conf.server>` section for this port. 4011 4012 4013@@UAHL@unbound.conf.dnscrypt@dnscrypt-provider@@: *<provider name>* 4014 The provider name to use to distribute certificates. 4015 This is of the form: 4016 4017 .. code-block:: text 4018 4019 2.dnscrypt-cert.example.com. 4020 4021 .. important:: The name *MUST* end with a dot. 4022 4023 4024@@UAHL@unbound.conf.dnscrypt@dnscrypt-secret-key@@: *<path to secret key file>* 4025 Path to the time limited secret key file. 4026 This option may be specified multiple times. 4027 4028 4029@@UAHL@unbound.conf.dnscrypt@dnscrypt-provider-cert@@: *<path to cert file>* 4030 Path to the certificate related to the 4031 :ref:`dnscrypt-secret-key<unbound.conf.dnscrypt.dnscrypt-secret-key>`. 4032 This option may be specified multiple times. 4033 4034 4035@@UAHL@unbound.conf.dnscrypt@dnscrypt-provider-cert-rotated@@: *<path to cert file>* 4036 Path to a certificate that we should be able to serve existing connection 4037 from but do not want to advertise over 4038 :ref:`dnscrypt-provider<unbound.conf.dnscrypt.dnscrypt-provider>` 's TXT 4039 record certs distribution. 4040 4041 A typical use case is when rotating certificates, existing clients may 4042 still use the client magic from the old cert in their queries until they 4043 fetch and update the new cert. 4044 Likewise, it would allow one to prime the new cert/key without distributing 4045 the new cert yet, this can be useful when using a network of servers using 4046 anycast and on which the configuration may not get updated at the exact 4047 same time. 4048 4049 By priming the cert, the servers can handle both old and new certs traffic 4050 while distributing only one. 4051 4052 This option may be specified multiple times. 4053 4054 4055@@UAHL@unbound.conf.dnscrypt@dnscrypt-shared-secret-cache-size@@: *<memory size>* 4056 Give the size of the data structure in which the shared secret keys are 4057 kept in. 4058 In bytes or use m(mega), k(kilo), g(giga). 4059 The shared secret cache is used when a same client is making multiple 4060 queries using the same public key. 4061 It saves a substantial amount of CPU. 4062 4063 Default: 4m 4064 4065 4066@@UAHL@unbound.conf.dnscrypt@dnscrypt-shared-secret-cache-slabs@@: *<number>* 4067 Number of slabs in the dnscrypt shared secrets cache. 4068 Slabs reduce lock contention by threads. 4069 Must be set to a power of 2. 4070 Setting (close) to the number of cpus is a fairly good setting. 4071 If left unconfigured, it will be configured automatically to be a power of 4072 2 close to the number of configured threads in multi-threaded environments. 4073 4074 Default: (unconfigured) 4075 4076 4077@@UAHL@unbound.conf.dnscrypt@dnscrypt-nonce-cache-size@@: *<memory size>* 4078 Give the size of the data structure in which the client nonces are kept in. 4079 In bytes or use m(mega), k(kilo), g(giga). 4080 The nonce cache is used to prevent dnscrypt message replaying. 4081 Client nonce should be unique for any pair of client pk/server sk. 4082 4083 Default: 4m 4084 4085 4086@@UAHL@unbound.conf.dnscrypt@dnscrypt-nonce-cache-slabs@@: *<number>* 4087 Number of slabs in the dnscrypt nonce cache. 4088 Slabs reduce lock contention by threads. 4089 Must be set to a power of 2. 4090 Setting (close) to the number of cpus is a fairly good setting. 4091 If left unconfigured, it will be configured automatically to be a power of 4092 2 close to the number of configured threads in multi-threaded environments. 4093 4094 Default: (unconfigured) 4095 4096EDNS Client Subnet Module Options 4097^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4098 4099The ECS module must be configured in the 4100:ref:`module-config<unbound.conf.module-config>` directive, e.g.: 4101 4102.. code-block:: text 4103 4104 module-config: "subnetcache validator iterator" 4105 4106and be compiled into the daemon to be enabled. 4107 4108.. note:: 4109 These settings go in the :ref:`server:<unbound.conf.server>` section. 4110 4111If the destination address is allowed in the configuration Unbound will add the 4112EDNS0 option to the query containing the relevant part of the client's address. 4113When an answer contains the ECS option the response and the option are placed 4114in a specialized cache. 4115If the authority indicated no support, the response is stored in the regular 4116cache. 4117 4118Additionally, when a client includes the option in its queries, Unbound will 4119forward the option when sending the query to addresses that are explicitly 4120allowed in the configuration using 4121:ref:`send-client-subnet<unbound.conf.ecs.send-client-subnet>`. 4122The option will always be forwarded, regardless the allowed addresses, when 4123:ref:`client-subnet-always-forward: yes<unbound.conf.ecs.client-subnet-always-forward>` 4124is set. 4125In this case the lookup in the regular cache is skipped. 4126 4127The maximum size of the ECS cache is controlled by 4128:ref:`msg-cache-size<unbound.conf.msg-cache-size>` in the configuration file. 4129On top of that, for each query only 100 different subnets are allowed to be 4130stored for each address family. 4131Exceeding that number, older entries will be purged from cache. 4132 4133Note that due to the nature of how EDNS Client Subnet works, by segregating the 4134client IP space in order to try and have tailored responses for prefixes of 4135unknown sizes, resolution and cache response performance are impacted as a 4136result. 4137Usage of the subnetcache module should only be enabled in installations that 4138require such functionality where the resolver and the clients belong to 4139different networks. 4140An example of that is an open resolver installation. 4141 4142This module does not interact with the 4143:ref:`serve-expired\*<unbound.conf.serve-expired>` and 4144:ref:`prefetch<unbound.conf.prefetch>` options. 4145 4146 4147@@UAHL@unbound.conf.ecs@send-client-subnet@@: *<IP address>* 4148 Send client source address to this authority. 4149 Append /num to indicate a classless delegation netblock, for example like 4150 ``10.2.3.4/24`` or ``2001::11/64``. 4151 Can be given multiple times. 4152 Authorities not listed will not receive edns-subnet information, unless 4153 domain in query is specified in 4154 :ref:`client-subnet-zone<unbound.conf.ecs.client-subnet-zone>`. 4155 4156 4157@@UAHL@unbound.conf.ecs@client-subnet-zone@@: *<domain>* 4158 Send client source address in queries for this domain and its subdomains. 4159 Can be given multiple times. 4160 Zones not listed will not receive edns-subnet information, unless hosted by 4161 authority specified in 4162 :ref:`send-client-subnet<unbound.conf.ecs.send-client-subnet>`. 4163 4164 4165@@UAHL@unbound.conf.ecs@client-subnet-always-forward@@: *<yes or no>* 4166 Specify whether the ECS address check (configured using 4167 :ref:`send-client-subnet<unbound.conf.ecs.send-client-subnet>`) is applied 4168 for all queries, even if the triggering query contains an ECS record, or 4169 only for queries for which the ECS record is generated using the querier 4170 address (and therefore did not contain ECS data in the client query). 4171 If enabled, the address check is skipped when the client query contains an 4172 ECS record. 4173 And the lookup in the regular cache is skipped. 4174 4175 Default: no 4176 4177 4178@@UAHL@unbound.conf.ecs@max-client-subnet-ipv6@@: *<number>* 4179 Specifies the maximum prefix length of the client source address we are 4180 willing to expose to third parties for IPv6. 4181 4182 Default: 56 4183 4184 4185@@UAHL@unbound.conf.ecs@max-client-subnet-ipv4@@: *<number>* 4186 Specifies the maximum prefix length of the client source address we are 4187 willing to expose to third parties for IPv4. 4188 4189 Default: 24 4190 4191 4192@@UAHL@unbound.conf.ecs@min-client-subnet-ipv6@@: *<number>* 4193 Specifies the minimum prefix length of the IPv6 source mask we are willing 4194 to accept in queries. 4195 Shorter source masks result in REFUSED answers. 4196 Source mask of 0 is always accepted. 4197 4198 Default: 0 4199 4200 4201@@UAHL@unbound.conf.ecs@min-client-subnet-ipv4@@: *<number>* 4202 Specifies the minimum prefix length of the IPv4 source mask we are willing 4203 to accept in queries. 4204 Shorter source masks result in REFUSED answers. 4205 Source mask of 0 is always accepted. 4206 Default: 0 4207 4208 4209@@UAHL@unbound.conf.ecs@max-ecs-tree-size-ipv4@@: *<number>* 4210 Specifies the maximum number of subnets ECS answers kept in the ECS radix 4211 tree. 4212 This number applies for each qname/qclass/qtype tuple. 4213 4214 Default: 100 4215 4216 4217@@UAHL@unbound.conf.ecs@max-ecs-tree-size-ipv6@@: *<number>* 4218 Specifies the maximum number of subnets ECS answers kept in the ECS radix 4219 tree. 4220 This number applies for each qname/qclass/qtype tuple. 4221 4222 Default: 100 4223 4224Opportunistic IPsec Support Module Options 4225^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4226 4227The IPsec module must be configured in the 4228:ref:`module-config<unbound.conf.module-config>` directive, e.g.: 4229 4230.. code-block:: text 4231 4232 module-config: "ipsecmod validator iterator" 4233 4234and be compiled into Unbound by using ``--enable-ipsecmod`` to be enabled. 4235 4236.. note:: 4237 These settings go in the :ref:`server:<unbound.conf.server>` section. 4238 4239When Unbound receives an A/AAAA query that is not in the cache and finds a 4240valid answer, it will withhold returning the answer and instead will generate 4241an IPSECKEY subquery for the same domain name. 4242If an answer was found, Unbound will call an external hook passing the 4243following arguments: 4244 4245QNAME 4246 Domain name of the A/AAAA and IPSECKEY query. 4247 In string format. 4248 4249IPSECKEY TTL 4250 TTL of the IPSECKEY RRset. 4251 4252A/AAAA 4253 String of space separated IP addresses present in the A/AAAA RRset. 4254 The IP addresses are in string format. 4255 4256IPSECKEY 4257 String of space separated IPSECKEY RDATA present in the IPSECKEY RRset. 4258 The IPSECKEY RDATA are in DNS presentation format. 4259 4260The A/AAAA answer is then cached and returned to the client. 4261If the external hook was called the TTL changes to ensure it doesn't surpass 4262:ref:`ipsecmod-max-ttl<unbound.conf.ipsecmod-max-ttl>`. 4263 4264The same procedure is also followed when 4265:ref:`prefetch: yes<unbound.conf.prefetch>` is set, but the A/AAAA answer is 4266given to the client before the hook is called. 4267:ref:`ipsecmod-max-ttl<unbound.conf.ipsecmod-max-ttl>` ensures that the A/AAAA 4268answer given from cache is still relevant for opportunistic IPsec. 4269 4270 4271@@UAHL@unbound.conf@ipsecmod-enabled@@: *<yes or no>* 4272 Specifies whether the IPsec module is enabled or not. 4273 The IPsec module still needs to be defined in the 4274 :ref:`module-config<unbound.conf.module-config>` directive. 4275 This option facilitates turning on/off the module without 4276 restarting/reloading Unbound. 4277 4278 Default: yes 4279 4280 4281@@UAHL@unbound.conf@ipsecmod-hook@@: *<filename>* 4282 Specifies the external hook that Unbound will call with *system(3)*. 4283 The file can be specified as an absolute/relative path. 4284 The file needs the proper permissions to be able to be executed by the same 4285 user that runs Unbound. 4286 It must be present when the IPsec module is defined in the 4287 :ref:`module-config<unbound.conf.module-config>` directive. 4288 4289 4290@@UAHL@unbound.conf@ipsecmod-strict@@: *<yes or no>* 4291 If enabled Unbound requires the external hook to return a success value of 4292 0. 4293 Failing to do so Unbound will reply with SERVFAIL. 4294 The A/AAAA answer will also not be cached. 4295 4296 Default: no 4297 4298 4299@@UAHL@unbound.conf@ipsecmod-max-ttl@@: *<seconds>* 4300 Time to live maximum for A/AAAA cached records after calling the external 4301 hook. 4302 4303 Default: 3600 4304 4305 4306@@UAHL@unbound.conf@ipsecmod-ignore-bogus@@: *<yes or no>* 4307 Specifies the behaviour of Unbound when the IPSECKEY answer is bogus. 4308 If set to yes, the hook will be called and the A/AAAA answer will be 4309 returned to the client. 4310 If set to no, the hook will not be called and the answer to the A/AAAA 4311 query will be SERVFAIL. 4312 Mainly used for testing. 4313 4314 Default: no 4315 4316 4317@@UAHL@unbound.conf@ipsecmod-allow@@: *<domain>* 4318 Allow the IPsec module functionality for the domain so that the module 4319 logic will be executed. 4320 Can be given multiple times, for different domains. 4321 If the option is not specified, all domains are treated as being allowed 4322 (default). 4323 4324 4325@@UAHL@unbound.conf@ipsecmod-whitelist@@: *<domain>* 4326 Alternate syntax for :ref:`ipsecmod-allow<unbound.conf.ipsecmod-allow>`. 4327 4328Cache DB Module Options 4329^^^^^^^^^^^^^^^^^^^^^^^ 4330 4331The Cache DB module must be configured in the 4332:ref:`module-config<unbound.conf.module-config>` directive, e.g.: 4333 4334.. code-block:: text 4335 4336 module-config: "validator cachedb iterator" 4337 4338and be compiled into the daemon with ``--enable-cachedb``. 4339 4340If this module is enabled and configured, the specified backend database works 4341as a second level cache; when Unbound cannot find an answer to a query in its 4342built-in in-memory cache, it consults the specified backend. 4343If it finds a valid answer in the backend, Unbound uses it to respond to the 4344query without performing iterative DNS resolution. 4345If Unbound cannot even find an answer in the backend, it resolves the query as 4346usual, and stores the answer in the backend. 4347 4348This module interacts with the *serve-expired-\** options and will reply with 4349expired data if Unbound is configured for that. 4350 4351If Unbound was built with ``--with-libhiredis`` on a system that has installed 4352the hiredis C client library of Redis, then the ``redis`` backend can be used. 4353This backend communicates with the specified Redis server over a TCP connection 4354to store and retrieve cache data. 4355It can be used as a persistent and/or shared cache backend. 4356 4357.. note:: 4358 Unbound never removes data stored in the Redis server, even if some data 4359 have expired in terms of DNS TTL or the Redis server has cached too much 4360 data; if necessary the Redis server must be configured to limit the cache 4361 size, preferably with some kind of least-recently-used eviction policy. 4362 4363Additionally, the 4364:ref:`redis-expire-records<unbound.conf.cachedb.redis-expire-records>` option 4365can be used in order to set the relative DNS TTL of the message as timeout to 4366the Redis records; keep in mind that some additional memory is used per key and 4367that the expire information is stored as absolute Unix timestamps in Redis 4368(computer time must be stable). 4369 4370This backend uses synchronous communication with the Redis server based on the 4371assumption that the communication is stable and sufficiently fast. 4372The thread waiting for a response from the Redis server cannot handle other DNS 4373queries. 4374Although the backend has the ability to reconnect to the server when the 4375connection is closed unexpectedly and there is a configurable timeout in case 4376the server is overly slow or hangs up, these cases are assumed to be very rare. 4377If connection close or timeout happens too often, Unbound will be effectively 4378unusable with this backend. 4379It's the administrator's responsibility to make the assumption hold. 4380 4381The **cachedb:** clause gives custom settings of the cache DB module. 4382 4383 4384@@UAHL@unbound.conf.cachedb@backend@@: *<backend name>* 4385 Specify the backend database name. 4386 The default database is the in-memory backend named ``testframe``, which, 4387 as the name suggests, is not of any practical use. 4388 Depending on the build-time configuration, ``redis`` backend may also be 4389 used as described above. 4390 4391 Default: testframe 4392 4393 4394@@UAHL@unbound.conf.cachedb@secret-seed@@: *"<secret string>"* 4395 Specify a seed to calculate a hash value from query information. 4396 This value will be used as the key of the corresponding answer for the 4397 backend database and can be customized if the hash should not be 4398 predictable operationally. 4399 If the backend database is shared by multiple Unbound instances, all 4400 instances must use the same secret seed. 4401 4402 Default: "default" 4403 4404 4405@@UAHL@unbound.conf.cachedb@cachedb-no-store@@: *<yes or no>* 4406 If the backend should be read from, but not written to. 4407 This makes this instance not store dns messages in the backend. 4408 But if data is available it is retrieved. 4409 4410 Default: no 4411 4412 4413@@UAHL@unbound.conf.cachedb@cachedb-check-when-serve-expired@@: *<yes or no>* 4414 If enabled, the cachedb is checked before an expired response is returned. 4415 When 4416 :ref:`serve-expired<unbound.conf.serve-expired>` 4417 is enabled, without 4418 :ref:`serve-expired-client-timeout<unbound.conf.serve-expired-client-timeout>` 4419 , it then does not immediately respond with an expired response from cache, 4420 but instead first checks the cachedb for valid contents, and if so returns it. 4421 If the cachedb also has no valid contents, the serve expired response is sent. 4422 If also 4423 :ref:`serve-expired-client-timeout<unbound.conf.serve-expired-client-timeout>` 4424 is enabled, the expired response is delayed until the timeout expires. 4425 Unless the lookup succeeds within the timeout. 4426 4427 Default: yes 4428 4429The following **cachedb:** options are specific to the ``redis`` backend. 4430 4431 4432@@UAHL@unbound.conf.cachedb@redis-server-host@@: *<server address or name>* 4433 The IP (either v6 or v4) address or domain name of the Redis server. 4434 In general an IP address should be specified as otherwise Unbound will have 4435 to resolve the name of the server every time it establishes a connection to 4436 the server. 4437 4438 Default: 127.0.0.1 4439 4440 4441@@UAHL@unbound.conf.cachedb@redis-server-port@@: *<port number>* 4442 The TCP port number of the Redis server. 4443 4444 Default: 6379 4445 4446 4447@@UAHL@unbound.conf.cachedb@redis-server-path@@: *<unix socket path>* 4448 The unix socket path to connect to the Redis server. 4449 Unix sockets may have better throughput than the IP address option. 4450 4451 Default: "" (disabled) 4452 4453 4454@@UAHL@unbound.conf.cachedb@redis-server-password@@: *"<password>"* 4455 The Redis AUTH password to use for the Redis server. 4456 Only relevant if Redis is configured for client password authorisation. 4457 4458 Default: "" (disabled) 4459 4460 4461@@UAHL@unbound.conf.cachedb@redis-timeout@@: *<msec>* 4462 The period until when Unbound waits for a response from the Redis server. 4463 If this timeout expires Unbound closes the connection, treats it as if the 4464 Redis server does not have the requested data, and will try to re-establish 4465 a new connection later. 4466 4467 Default: 100 4468 4469 4470@@UAHL@unbound.conf.cachedb@redis-command-timeout@@: *<msec>* 4471 The timeout to use for Redis commands, in milliseconds. 4472 If ``0``, it uses the 4473 :ref:`redis-timeout<unbound.conf.cachedb.redis-timeout>` 4474 value. 4475 4476 Default: 0 4477 4478 4479@@UAHL@unbound.conf.cachedb@redis-connect-timeout@@: *<msec>* 4480 The timeout to use for Redis connection set up, in milliseconds. 4481 If ``0``, it uses the 4482 :ref:`redis-timeout<unbound.conf.cachedb.redis-timeout>` 4483 value. 4484 4485 Default: 0 4486 4487 4488@@UAHL@unbound.conf.cachedb@redis-expire-records@@: *<yes or no>* 4489 If Redis record expiration is enabled. 4490 If yes, Unbound sets timeout for Redis records so that Redis can evict keys 4491 that have expired automatically. 4492 If Unbound is configured with 4493 :ref:`serve-expired<unbound.conf.serve-expired>` and 4494 :ref:`serve-expired-ttl: 0<unbound.conf.serve-expired-ttl>`, this option is 4495 internally reverted to "no". 4496 4497 .. note:: 4498 Redis "SET ... EX" support is required for this option (Redis >= 2.6.12). 4499 4500 Default: no 4501 4502 4503@@UAHL@unbound.conf.cachedb@redis-logical-db@@: *<logical database index>* 4504 The logical database in Redis to use. 4505 These are databases in the same Redis instance sharing the same 4506 configuration and persisted in the same RDB/AOF file. 4507 If unsure about using this option, Redis documentation 4508 (https://redis.io/commands/select/) suggests not to use a single Redis 4509 instance for multiple unrelated applications. 4510 The default database in Redis is 0 while other logical databases need to be 4511 explicitly SELECT'ed upon connecting. 4512 4513 Default: 0 4514 4515 4516@@UAHL@unbound.conf.cachedb@redis-replica-server-host@@: *<server address or name>* 4517 The IP (either v6 or v4) address or domain name of the Redis server. 4518 In general an IP address should be specified as otherwise Unbound will have 4519 to resolve the name of the server every time it establishes a connection to 4520 the server. 4521 4522 This server is treated as a read-only replica server 4523 (https://redis.io/docs/management/replication/#read-only-replica). 4524 If specified, all Redis read commands will go to this replica server, while 4525 the write commands will go to the 4526 :ref:`redis-server-host<unbound.conf.cachedb.redis-server-host>`. 4527 4528 Default: "" (disabled). 4529 4530 4531@@UAHL@unbound.conf.cachedb@redis-replica-server-port@@: *<port number>* 4532 The TCP port number of the Redis replica server. 4533 4534 Default: 6379 4535 4536 4537@@UAHL@unbound.conf.cachedb@redis-replica-server-path@@: *<unix socket path>* 4538 The unix socket path to connect to the Redis replica server. 4539 Unix sockets may have better throughput than the IP address option. 4540 4541 Default: "" (disabled) 4542 4543 4544@@UAHL@unbound.conf.cachedb@redis-replica-server-password@@: *"<password>"* 4545 The Redis AUTH password to use for the Redis server. 4546 Only relevant if Redis is configured for client password authorisation. 4547 4548 Default: "" (disabled) 4549 4550 4551@@UAHL@unbound.conf.cachedb@redis-replica-timeout@@: *<msec>* 4552 The period until when Unbound waits for a response from the Redis replica 4553 server. 4554 If this timeout expires Unbound closes the connection, treats it as if the 4555 Redis server does not have the requested data, and will try to re-establish 4556 a new connection later. 4557 4558 Default: 100 4559 4560 4561@@UAHL@unbound.conf.cachedb@redis-replica-command-timeout@@: *<msec>* 4562 The timeout to use for Redis replica commands, in milliseconds. 4563 If ``0``, it uses the 4564 :ref:`redis-replica-timeout<unbound.conf.cachedb.redis-replica-timeout>` 4565 value. 4566 4567 Default: 0 4568 4569 4570@@UAHL@unbound.conf.cachedb@redis-replica-connect-timeout@@: *<msec>* 4571 The timeout to use for Redis replica connection set up, in milliseconds. 4572 If ``0``, it uses the 4573 :ref:`redis-replica-timeout<unbound.conf.cachedb.redis-replica-timeout>` 4574 value. 4575 4576 Default: 0 4577 4578 4579@@UAHL@unbound.conf.cachedb@redis-replica-logical-db@@: *<logical database index>* 4580 Same as :ref:`redis-logical-db<unbound.conf.cachedb.redis-logical-db>` but 4581 for the Redis replica server. 4582 4583 Default: 0 4584 4585 4586.. _unbound.conf.dnstap: 4587 4588DNSTAP Logging Options 4589^^^^^^^^^^^^^^^^^^^^^^ 4590 4591DNSTAP support, when compiled in by using ``--enable-dnstap``, is enabled in 4592the **dnstap:** section. 4593This starts an extra thread (when compiled with threading) that writes the log 4594information to the destination. 4595If Unbound is compiled without threading it does not spawn a thread, but 4596connects per-process to the destination. 4597 4598 4599@@UAHL@unbound.conf.dnstap@dnstap-enable@@: *<yes or no>* 4600 If dnstap is enabled. 4601 If yes, it connects to the DNSTAP server and if any of the 4602 *dnstap-log-..-messages:* options is enabled it sends logs for those 4603 messages to the server. 4604 4605 Default: no 4606 4607 4608@@UAHL@unbound.conf.dnstap@dnstap-bidirectional@@: *<yes or no>* 4609 Use frame streams in bidirectional mode to transfer DNSTAP messages. 4610 4611 Default: yes 4612 4613 4614@@UAHL@unbound.conf.dnstap@dnstap-socket-path@@: *<file name>* 4615 Sets the unix socket file name for connecting to the server that is 4616 listening on that socket. 4617 4618 Default: @DNSTAP_SOCKET_PATH@ 4619 4620 4621@@UAHL@unbound.conf.dnstap@dnstap-ip@@: *<IPaddress[@port]>* 4622 If ``""``, the unix socket is used, if set with an IP address (IPv4 or 4623 IPv6) that address is used to connect to the server. 4624 4625 Default: "" 4626 4627 4628@@UAHL@unbound.conf.dnstap@dnstap-tls@@: *<yes or no>* 4629 Set this to use TLS to connect to the server specified in 4630 :ref:`dnstap-ip<unbound.conf.dnstap.dnstap-ip>`. 4631 If set to no, TCP is used to connect to the server. 4632 4633 Default: yes 4634 4635 4636@@UAHL@unbound.conf.dnstap@dnstap-tls-server-name@@: *<name of TLS authentication>* 4637 The TLS server name to authenticate the server with. 4638 Used when :ref:`dnstap-tls: yes<unbound.conf.dnstap.dnstap-tls>` is set. 4639 If ``""`` it is ignored. 4640 4641 Default: "" 4642 4643 4644@@UAHL@unbound.conf.dnstap@dnstap-tls-cert-bundle@@: *<file name of cert bundle>* 4645 The pem file with certs to verify the TLS server certificate. 4646 If ``""`` the server default cert bundle is used, or the windows cert 4647 bundle on windows. 4648 4649 Default: "" 4650 4651 4652@@UAHL@unbound.conf.dnstap@dnstap-tls-client-key-file@@: *<file name>* 4653 The client key file for TLS client authentication. 4654 If ``""`` client authentication is not used. 4655 4656 Default: "" 4657 4658 4659@@UAHL@unbound.conf.dnstap@dnstap-tls-client-cert-file@@: *<file name>* 4660 The client cert file for TLS client authentication. 4661 4662 Default: "" 4663 4664 4665@@UAHL@unbound.conf.dnstap@dnstap-send-identity@@: *<yes or no>* 4666 If enabled, the server identity is included in the log messages. 4667 4668 Default: no 4669 4670 4671@@UAHL@unbound.conf.dnstap@dnstap-send-version@@: *<yes or no>* 4672 If enabled, the server version if included in the log messages. 4673 4674 Default: no 4675 4676 4677@@UAHL@unbound.conf.dnstap@dnstap-identity@@: *<string>* 4678 The identity to send with messages, if ``""`` the hostname is used. 4679 4680 Default: "" 4681 4682 4683@@UAHL@unbound.conf.dnstap@dnstap-version@@: *<string>* 4684 The version to send with messages, if ``""`` the package version is used. 4685 4686 Default: "" 4687 4688 4689@@UAHL@unbound.conf.dnstap@dnstap-sample-rate@@: *<number>* 4690 The sample rate for log of messages, it logs only 1/N messages. 4691 With 0 it is disabled. 4692 This is useful in a high volume environment, where log functionality would 4693 otherwise not be reliable. 4694 For example 10 would spend only 1/10th time on logging, and 100 would only 4695 spend a hundredth of the time on logging. 4696 4697 Default: 0 (disabled) 4698 4699 4700@@UAHL@unbound.conf.dnstap@dnstap-log-resolver-query-messages@@: *<yes or no>* 4701 Enable to log resolver query messages. 4702 These are messages from Unbound to upstream servers. 4703 4704 Default: no 4705 4706 4707@@UAHL@unbound.conf.dnstap@dnstap-log-resolver-response-messages@@: *<yes or no>* 4708 Enable to log resolver response messages. 4709 These are replies from upstream servers to Unbound. 4710 4711 Default: no 4712 4713 4714@@UAHL@unbound.conf.dnstap@dnstap-log-client-query-messages@@: *<yes or no>* 4715 Enable to log client query messages. 4716 These are client queries to Unbound. 4717 4718 Default: no 4719 4720 4721@@UAHL@unbound.conf.dnstap@dnstap-log-client-response-messages@@: *<yes or no>* 4722 Enable to log client response messages. 4723 These are responses from Unbound to clients. 4724 4725 Default: no 4726 4727 4728@@UAHL@unbound.conf.dnstap@dnstap-log-forwarder-query-messages@@: *<yes or no>* 4729 Enable to log forwarder query messages. 4730 4731 Default: no 4732 4733 4734@@UAHL@unbound.conf.dnstap@dnstap-log-forwarder-response-messages@@: *<yes or no>* 4735 Enable to log forwarder response messages. 4736 4737 Default: no 4738 4739.. _unbound.conf.rpz: 4740 4741Response Policy Zone Options 4742^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4743 4744Response Policy Zones are configured with **rpz:**, and each one must have a 4745:ref:`name<unbound.conf.rpz.name>` attribute. 4746There can be multiple ones, by listing multiple RPZ clauses, each with a 4747different name. 4748RPZ clauses are applied in order of configuration and any match from an earlier 4749RPZ zone will terminate the RPZ lookup. 4750Note that a PASSTHRU action is still considered a match. 4751The respip module needs to be added to the 4752:ref:`module-config<unbound.conf.module-config>`, e.g.: 4753 4754.. code-block:: text 4755 4756 module-config: "respip validator iterator" 4757 4758QNAME, Response IP Address, nsdname, nsip and clientip triggers are supported. 4759Supported actions are: NXDOMAIN, NODATA, PASSTHRU, DROP, Local Data, tcp-only 4760and drop. 4761RPZ QNAME triggers are applied after any 4762:ref:`local-zone<unbound.conf.local-zone>` and before any 4763:ref:`auth-zone<unbound.conf.auth>`. 4764 4765The RPZ zone is a regular DNS zone formatted with a SOA start record as usual. 4766The items in the zone are entries, that specify what to act on (the trigger) 4767and what to do (the action). 4768The trigger to act on is recorded in the name, the action to do is recorded as 4769the resource record. 4770The names all end in the zone name, so you could type the trigger names without 4771a trailing dot in the zonefile. 4772 4773An example RPZ record, that answers ``example.com`` with ``NXDOMAIN``: 4774 4775.. code-block:: text 4776 4777 example.com CNAME . 4778 4779The triggers are encoded in the name on the left 4780 4781.. code-block:: text 4782 4783 name query name 4784 netblock.rpz-client-ip client IP address 4785 netblock.rpz-ip response IP address in the answer 4786 name.rpz-nsdname nameserver name 4787 netblock.rpz-nsip nameserver IP address 4788 4789The netblock is written as ``<netblocklen>.<ip address in reverse>``. 4790For IPv6 use ``'zz'`` for ``'::'``. 4791Specify individual addresses with scope length of 32 or 128. 4792For example, ``24.10.100.51.198.rpz-ip`` is ``198.51.100.10/24`` and 4793``32.10.zz.db8.2001.rpz-ip`` is ``2001:db8:0:0:0:0:0:10/32``. 4794 4795The actions are specified with the record on the right 4796 4797.. code-block:: text 4798 4799 CNAME . nxdomain reply 4800 CNAME *. nodata reply 4801 CNAME rpz-passthru. do nothing, allow to continue 4802 CNAME rpz-drop. the query is dropped 4803 CNAME rpz-tcp-only. answer over TCP 4804 A 192.0.2.1 answer with this IP address 4805 4806Other records like AAAA, TXT and other CNAMEs (not rpz-..) can also be used to 4807answer queries with that content. 4808 4809The RPZ zones can be configured in the config file with these settings in the 4810**rpz:** block. 4811 4812 4813@@UAHL@unbound.conf.rpz@name@@: *<zone name>* 4814 Name of the authority zone. 4815 4816 4817@@UAHL@unbound.conf.rpz@primary@@: *<IP address or host name>* 4818 Where to download a copy of the zone from, with AXFR and IXFR. 4819 Multiple primaries can be specified. 4820 They are all tried if one fails. 4821 4822 To use a non-default port for DNS communication append ``'@'`` with the 4823 port number. 4824 4825 You can append a ``'#'`` and a name, then AXFR over TLS can be used and the 4826 TLS authentication certificates will be checked with that name. 4827 4828 If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first. 4829 If you point it at another Unbound instance, it would not work because that 4830 does not support AXFR/IXFR for the zone, but if you used 4831 :ref:`url<unbound.conf.rpz.url>` to download the zonefile as a text file 4832 from a webserver that would work. 4833 4834 If you specify the hostname, you cannot use the domain from the zonefile, 4835 because it may not have that when retrieving that data, instead use a plain 4836 IP address to avoid a circular dependency on retrieving that IP address. 4837 4838 4839@@UAHL@unbound.conf.rpz@master@@: *<IP address or host name>* 4840 Alternate syntax for :ref:`primary<unbound.conf.rpz.primary>`. 4841 4842 4843@@UAHL@unbound.conf.rpz@url@@: *<url to zonefile>* 4844 Where to download a zonefile for the zone. 4845 With HTTP or HTTPS. 4846 An example for the url is: 4847 4848 .. code-block:: text 4849 4850 http://www.example.com/example.org.zone 4851 4852 Multiple url statements can be given, they are tried in turn. 4853 4854 If only urls are given the SOA refresh timer is used to wait for making new 4855 downloads. 4856 If also primaries are listed, the primaries are first probed with UDP SOA 4857 queries to see if the SOA serial number has changed, reducing the number of 4858 downloads. 4859 If none of the URLs work, the primaries are tried with IXFR and AXFR. 4860 4861 For HTTPS, the :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>` and 4862 the hostname from the url are used to authenticate the connection. 4863 4864 4865@@UAHL@unbound.conf.rpz@allow-notify@@: *<IP address or host name or netblockIP/prefix>* 4866 With :ref:`allow-notify<unbound.conf.rpz.allow-notify>` you can specify 4867 additional sources of notifies. 4868 When notified, the server attempts to first probe and then zone transfer. 4869 If the notify is from a primary, it first attempts that primary. 4870 Otherwise other primaries are attempted. 4871 If there are no primaries, but only urls, the file is downloaded when 4872 notified. 4873 4874 .. note:: 4875 The primaries from :ref:`primary<unbound.conf.rpz.primary>` and 4876 :ref:`url<unbound.conf.rpz.url>` statements are allowed notify by 4877 default. 4878 4879 4880@@UAHL@unbound.conf.rpz@zonefile@@: *<filename>* 4881 The filename where the zone is stored. 4882 If not given then no zonefile is used. 4883 If the file does not exist or is empty, Unbound will attempt to fetch zone 4884 data (eg. from the primary servers). 4885 4886 4887@@UAHL@unbound.conf.rpz@rpz-action-override@@: *<action>* 4888 Always use this RPZ action for matching triggers from this zone. 4889 Possible actions are: *nxdomain*, *nodata*, *passthru*, *drop*, *disabled* 4890 and *cname*. 4891 4892 4893@@UAHL@unbound.conf.rpz@rpz-cname-override@@: *<domain>* 4894 The CNAME target domain to use if the cname action is configured for 4895 :ref:`rpz-action-override<unbound.conf.rpz.rpz-action-override>`. 4896 4897 4898@@UAHL@unbound.conf.rpz@rpz-log@@: *<yes or no>* 4899 Log all applied RPZ actions for this RPZ zone. 4900 4901 Default: no 4902 4903 4904@@UAHL@unbound.conf.rpz@rpz-log-name@@: *<name>* 4905 Specify a string to be part of the log line, for easy referencing. 4906 4907 4908@@UAHL@unbound.conf.rpz@rpz-signal-nxdomain-ra@@: *<yes or no>* 4909 Signal when a query is blocked by the RPZ with NXDOMAIN with an unset RA 4910 flag. 4911 This allows certain clients, like dnsmasq, to infer that the domain is 4912 externally blocked. 4913 4914 Default: no 4915 4916 4917@@UAHL@unbound.conf.rpz@for-downstream@@: *<yes or no>* 4918 If enabled the zone is authoritatively answered for and queries for the RPZ 4919 zone information are answered to downstream clients. 4920 This is useful for monitoring scripts, that can then access the SOA 4921 information to check if the RPZ information is up to date. 4922 4923 Default: no 4924 4925 4926@@UAHL@unbound.conf.rpz@tags@@: *"<list of tags>"* 4927 Limit the policies from this RPZ clause to clients with a matching tag. 4928 4929 Tags need to be defined in :ref:`define-tag<unbound.conf.define-tag>` and 4930 can be assigned to client addresses using 4931 :ref:`access-control-tag<unbound.conf.access-control-tag>` or 4932 :ref:`interface-tag<unbound.conf.interface-tag>`. 4933 Enclose list of tags in quotes (``""``) and put spaces between tags. 4934 4935 If no tags are specified the policies from this clause will be applied for 4936 all clients. 4937 4938Memory Control Example 4939---------------------- 4940 4941In the example config settings below memory usage is reduced. 4942Some service levels are lower, notable very large data and a high TCP load are 4943no longer supported. 4944Very large data and high TCP loads are exceptional for the DNS. 4945DNSSEC validation is enabled, just add trust anchors. 4946If you do not have to worry about programs using more than 3 Mb of memory, the 4947below example is not for you. 4948Use the defaults to receive full service, which on BSD-32bit tops out at 30-40 4949Mb after heavy usage. 4950 4951.. code-block:: text 4952 4953 # example settings that reduce memory usage 4954 server: 4955 num-threads: 1 4956 outgoing-num-tcp: 1 # this limits TCP service, uses less buffers. 4957 incoming-num-tcp: 1 4958 outgoing-range: 60 # uses less memory, but less performance. 4959 msg-buffer-size: 8192 # note this limits service, 'no huge stuff'. 4960 msg-cache-size: 100k 4961 msg-cache-slabs: 1 4962 rrset-cache-size: 100k 4963 rrset-cache-slabs: 1 4964 infra-cache-numhosts: 200 4965 infra-cache-slabs: 1 4966 key-cache-size: 100k 4967 key-cache-slabs: 1 4968 neg-cache-size: 10k 4969 num-queries-per-thread: 30 4970 target-fetch-policy: "2 1 0 0 0 0" 4971 harden-large-queries: "yes" 4972 harden-short-bufsize: "yes" 4973 4974Files 4975----- 4976 4977@UNBOUND_RUN_DIR@ 4978 default Unbound working directory. 4979 4980@UNBOUND_CHROOT_DIR@ 4981 default *chroot(2)* location. 4982 4983@ub_conf_file@ 4984 Unbound configuration file. 4985 4986@UNBOUND_PIDFILE@ 4987 default Unbound pidfile with process ID of the running daemon. 4988 4989unbound.log 4990 Unbound log file. 4991 Default is to log to *syslog(3)*. 4992 4993See Also 4994-------- 4995 4996:doc:`unbound(8)</manpages/unbound>`, 4997:doc:`unbound-checkonf(8)</manpages/unbound-checkconf>`. 4998