pdns/recursordist/docs/settings.rst

   1 PowerDNS Recursor Settings
   2 ==========================
   3 Each setting can appear on the command line, prefixed by '--', or in the configuration file.
   4 The command line overrides the configuration file.
   5
   6 **Note**: Settings marked as 'Boolean' can either be set to an empty value, which means on, or to 'no' or 'off' which means off.
   7 Anything else means on.
   8
   9 As an example:
  10
  11  - ``serve-rfc1918`` on its own means: do serve those zones.
  12  - ``serve-rfc1918=off`` or ``serve-rfc1918=no`` means: do not serve those zones.
  13  - Anything else means: do serve those zones.
  14
  15 .. _setting-allow-from:
  16
  17 ``allow-from``
  18 --------------
  19 -  IP ranges, separated by commas
  20 -  Default: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
  21
  22 Netmasks (both IPv4 and IPv6) that are allowed to use the server.
  23 The default allows access only from :rfc:`1918` private IP addresses.
  24 Due to the aggressive nature of the internet these days, it is highly recommended to not open up the recursor for the entire internet.
  25 Questions from IP addresses not listed here are ignored and do not get an answer.
  26
  27 .. _setting-allow-from-file:
  28
  29 ``allow-from-file``
  30 -------------------
  31 -  Path
  32
  33 Like `allow-from`_, except reading from file.
  34 Overrides the `allow-from`_ setting. To use this feature, supply one netmask per line, with optional comments preceded by a "#".
  35
  36 .. _setting-any-to-tcp:
  37
  38 ``any-to-tcp``
  39 --------------
  40 -  Boolean
  41 -  Default: no
  42
  43 Answer questions for the ANY type on UDP with a truncated packet that refers the remote server to TCP.
  44 Useful for mitigating ANY reflection attacks.
  45
  46 .. _setting-api-config-dir:
  47
  48 ``api-config-dir``
  49 ------------------
  50 .. versionadded:: 4.0.0
  51
  52 -  Path
  53 -  Default: unset
  54
  55 Directory where the REST API stores its configuration and zones.
  56
  57 .. _setting-api-key:
  58
  59 ``api-key``
  60 -----------
  61 .. versionadded:: 4.0.0
  62
  63 -  String
  64 -  Default: unset
  65
  66 Static pre-shared authentication key for access to the REST API.
  67
  68 .. _setting-api-readonly:
  69
  70 ``api-readonly``
  71 ----------------
  72 .. versionchanged:: 4.2.0
  73   This setting has been removed.
  74
  75 -  Boolean
  76 -  Default: no
  77
  78 Disallow data modification through the REST API when set.
  79
  80 .. _setting-api-logfile:
  81
  82 ``api-logfile``
  83 ---------------
  84 .. versionchanged:: 4.2.0
  85   This setting has been removed.
  86
  87 -  Path
  88 -  Default: unset
  89
  90 Location of the server logfile (used by the REST API).
  91
  92 .. _setting-auth-can-lower-ttl:
  93
  94 ``auth-can-lower-ttl``
  95 ----------------------
  96 -  Boolean
  97 -  Default: no
  98
  99 Authoritative zones can transmit a TTL value that is lower than that specified in the parent zone.
 100 This is called a 'delegation inconsistency'.
 101 To follow :rfc:`RFC 2181 section 5.2<2181#section-5.2>` and :rfc:`5.4 <2181#section-5.4>` to the letter, enable this feature.
 102 This will mean a slight deterioration of performance, and it will not solve any problems, but does make the recursor more standards compliant.
 103 Not recommended unless you have to tick an 'RFC 2181 compliant' box.
 104
 105 .. _setting-auth-zones:
 106
 107 ``auth-zones``
 108 --------------
 109 -  Comma separated list of 'zonename=filename' pairs
 110
 111 Zones read from these files (in BIND format) are served authoritatively.
 112 DNSSEC is not supported. Example:
 113
 114 .. code-block:: none
 115
 116     auth-zones=example.org=/var/zones/example.org, powerdns.com=/var/zones/powerdns.com
 117
 118 .. _setting-carbon-interval:
 119
 120 ``carbon-interval``
 121 -------------------
 122 -  Integer
 123 -  Default: 30
 124
 125 If sending carbon updates, this is the interval between them in seconds.
 126 See :doc:`metrics`.
 127
 128 .. _setting-carbon-namespace:
 129
 130 ``carbon-namespace``
 131 --------------------
 132 .. versionadded:: 4.2.0
 133
 134 -  String
 135
 136 Change the namespace or first string of the metric key. The default is pdns.
 137
 138 .. _setting-carbon-ourname:
 139
 140 ``carbon-ourname``
 141 ------------------
 142 -  String
 143
 144 If sending carbon updates, if set, this will override our hostname.
 145 Be careful not to include any dots in this setting, unless you know what you are doing.
 146 See :ref:`metricscarbon`.
 147
 148 .. _setting-carbon-instance:
 149
 150 ``carbon-instance``
 151 --------------------
 152 .. versionadded:: 4.2.0
 153
 154 -  String
 155
 156 Change the instance or third string of the metric key. The default is recursor.
 157
 158 .. _setting-carbon-server:
 159
 160 ``carbon-server``
 161 -----------------
 162 -  IP address
 163
 164 If set to an IP or IPv6 address, will send all available metrics to this server via the carbon protocol, which is used by graphite and metronome.
 165 You may specify an alternate port by appending :port, for example: ``127.0.0.1:2004``.
 166 See :doc:`metrics`.
 167
 168 .. _setting-chroot:
 169
 170 ``chroot``
 171 ----------
 172 -  Path to a Directory
 173
 174 If set, chroot to this directory for more security.
 175 See :doc:`security`
 176
 177 Make sure that ``/dev/log`` is available from within the chroot.
 178 Logging will silently fail over time otherwise (on logrotate).
 179
 180 When using ``chroot``, all other paths (except for `config-dir`_) set in the configuration are relative to the new root.
 181
 182 When using ``chroot`` and the API (`webserver`_), `api-readonly`_ **must** be set and `api-config-dir`_ unset.
 183
 184 When running on a system where systemd manages services, ``chroot`` does not work out of the box, as PowerDNS cannot use the ``NOTIFY_SOCKET``.
 185 Either do not ``chroot`` on these systems or set the 'Type' of this service to 'simple' instead of 'notify' (refer to the systemd documentation on how to modify unit-files).
 186
 187 .. _setting-client-tcp-timeout:
 188
 189 ``client-tcp-timeout``
 190 ----------------------
 191 -  Integer
 192 -  Default: 2
 193
 194 Time to wait for data from TCP clients.
 195
 196 .. _setting-config-dir:
 197
 198 ``config-dir``
 199 --------------
 200 -  Path
 201
 202 Location of configuration directory (``recursor.conf``).
 203 Usually ``/etc/powerdns``, but this depends on ``SYSCONFDIR`` during compile-time.
 204
 205 .. _setting-config-name:
 206
 207 ``config-name``
 208 ---------------
 209 -  String
 210 -  Default: unset
 211
 212 When running multiple recursors on the same server, read settings from :file:`recursor-{name}.conf`, this will also rename the binary image.
 213
 214 .. _setting-cpu-map:
 215
 216 ``cpu-map``
 217 -----------
 218 .. versionadded:: 4.1.0
 219
 220 - String
 221 - Default: unset
 222
 223 Set CPU affinity for worker threads, asking the scheduler to run those threads on a single CPU, or a set of CPUs.
 224 This parameter accepts a space separated list of thread-id=cpu-id, or thread-id=cpu-id-1,cpu-id-2,...,cpu-id-N.
 225 For example, to make the worker thread 0 run on CPU id 0 and the worker thread 1 on CPUs 1 and 2::
 226
 227   cpu-map=0=0 1=1,2
 228
 229 The number of worker threads is determined by the :ref:`setting-threads` setting.
 230 If :ref:`setting-pdns-distributes-queries` is set, an additional thread is started, assigned the id 0,
 231 and is the only one listening on client sockets and accepting queries, distributing them to the other worker threads afterwards.
 232
 233 Starting with version 4.2.0, the thread handling the control channel, the webserver and other internal stuff has been assigned
 234 id 0 and more than one distributor thread can be started using the :ref:`setting-distributor-threads` setting, so the distributor
 235 threads if any are assigned id 1 and counting, and the other threads follow behind.
 236
 237 This parameter is only available on OS that provides the `pthread_setaffinity_np()` function.
 238
 239 .. _setting-daemon:
 240
 241 ``daemon``
 242 ----------
 243 -  Boolean
 244 -  Default: no
 245
 246 .. versionchanged:: 4.0.0
 247
 248     Default is now "no", was "yes" before.
 249
 250 Operate in the background.
 251
 252 .. _setting-delegation-only:
 253
 254 ``delegation-only``
 255 -------------------
 256 -  Domains, comma separated
 257
 258 Which domains we only accept delegations from (a Verisign special).
 259
 260 .. _setting-disable-packetcache:
 261
 262 ``disable-packetcache``
 263 -----------------------
 264 -  Boolean
 265 -  Default: no
 266
 267 Turn off the packet cache. Useful when running with Lua scripts that can
 268 not be cached.
 269
 270 .. _setting-disable-syslog:
 271
 272 ``disable-syslog``
 273 ------------------
 274 -  Boolean
 275 -  Default: no
 276
 277 Do not log to syslog, only to stdout.
 278 Use this setting when running inside a supervisor that handles logging (like systemd).
 279 **Note**: do not use this setting in combination with `daemon`_ as all logging will disappear.
 280
 281 .. _setting-distributor-threads:
 282
 283 ``distributor-threads``
 284 -----------------------
 285 .. versionadded:: 4.2.0
 286
 287 -  Integer
 288 -  Default: 1 if `pdns-distributes-queries`_ is set, 0 otherwise
 289
 290 If `pdns-distributes-queries`_ is set, spawn this number of distributor threads on startup. Distributor threads
 291 handle incoming queries and distribute them to other threads based on a hash of the query, to maximize the cache hit
 292 ratio.
 293
 294 .. _setting-dnssec:
 295
 296 ``dnssec``
 297 ----------
 298 .. versionadded:: 4.0.0
 299
 300 -  One of ``off``, ``process-no-validate``, ``process``, ``log-fail``, ``validate``, String
 301 -  Default: ``process-no-validate``
 302
 303 Set the mode for DNSSEC processing:
 304
 305 off
 306 ^^^
 307 No DNSSEC processing whatsoever.
 308 Ignore DO-bits in queries, don't request any DNSSEC information from authoritative servers.
 309 This behaviour is similar to PowerDNS Recursor pre-4.0.
 310
 311 process-no-validate
 312 ^^^^^^^^^^^^^^^^^^^
 313 Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries.
 314 Don't do any validation.
 315
 316 process
 317 ^^^^^^^
 318 Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries.
 319 Do validation for clients that request it (by means of the AD- bit or DO-bit in the query).
 320
 321 log-fail
 322 ^^^^^^^^
 323 Similar behaviour to ``process``, but validate RRSIGs on responses and log bogus responses.
 324
 325 validate
 326 ^^^^^^^^
 327 Full blown DNSSEC validation. Send SERVFAIL to clients on bogus responses.
 328
 329 .. _setting-dnssec-log-bogus:
 330
 331 ``dnssec-log-bogus``
 332 --------------------
 333 -  Boolean
 334 -  Default: no
 335
 336 Log every DNSSEC validation failure.
 337 **Note**: This is not logged per-query but every time records are validated as Bogus.
 338
 339 .. _setting-dont-query:
 340
 341 ``dont-query``
 342 --------------
 343 -  Netmasks, comma separated
 344 -  Default: 127.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10, 169.254.0.0/16, 192.168.0.0/16, 172.16.0.0/12, ::1/128, fc00::/7, fe80::/10, 0.0.0.0/8, 192.0.0.0/24, 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 240.0.0.0/4, ::/96, ::ffff:0:0/96, 100::/64, 2001:db8::/32
 345
 346 The DNS is a public database, but sometimes contains delegations to private IP addresses, like for example 127.0.0.1.
 347 This can have odd effects, depending on your network, and may even be a security risk.
 348 Therefore, the PowerDNS Recursor by default does not query private space IP addresses.
 349 This setting can be used to expand or reduce the limitations.
 350
 351 Queries to addresses for zones as configured in any of the settings `forward-zones`_, `forward-zones-file`_ or `forward-zones-recurse`_ are performed regardless of these limitations.
 352
 353 .. _setting-ecs-add-for:
 354
 355 ``ecs-add-for``
 356 ---------------
 357 .. versionadded:: 4.2.0
 358
 359 -  Comma separated list of netmasks
 360 -  Default: 0.0.0.0/0, ::, !127.0.0.0/8, !10.0.0.0/8, !100.64.0.0/10, !169.254.0.0/16, !192.168.0.0/16, !172.16.0.0/12, !::1/128, !fc00::/7, !fe80::/10
 361
 362 List of requestor netmasks for which the requestor IP Address should be used as the :rfc:`EDNS Client Subnet <7871>` for outgoing queries. Outgoing queries for requestors that do not match this list will use the `ecs-scope-zero-address`_ instead.
 363 Valid incoming ECS values from `use-incoming-edns-subnet`_ are not replaced.
 364
 365 Regardless of the value of this setting, ECS values are only sent for outgoing queries matching the conditions in the `edns-subnet-whitelist`_ setting. This setting only controls the actual value being sent.
 366
 367 This defaults to not using the requestor address inside RFC1918 and similar "private" IP address spaces.
 368
 369 .. _setting-ecs-ipv4-bits:
 370
 371 ``ecs-ipv4-bits``
 372 -----------------
 373 .. versionadded:: 4.1.0
 374
 375 -  Integer
 376 -  Default: 24
 377
 378 Number of bits of client IPv4 address to pass when sending EDNS Client Subnet address information.
 379
 380 .. _setting-ecs-ipv6-bits:
 381
 382 ``ecs-ipv6-bits``
 383 -----------------
 384 .. versionadded:: 4.1.0
 385
 386 -  Integer
 387 -  Default: 56
 388
 389 Number of bits of client IPv6 address to pass when sending EDNS Client Subnet address information.
 390
 391 .. _setting-ecs-scope-zero-address:
 392
 393 ``ecs-scope-zero-address``
 394 --------------------------
 395 .. versionadded:: 4.1.0
 396
 397 - IPv4 or IPv6 Address
 398 - Default: empty
 399
 400 The IP address sent via EDNS Client Subnet to authoritative servers listed in
 401 `edns-subnet-whitelist`_ when `use-incoming-edns-subnet`_ is set and the query has
 402 an ECS source prefix-length set to 0.
 403 The default is to look for the first usable (not an ``any`` one) address in
 404 `query-local-address`_ then `query-local-address6`_. If no suitable address is
 405 found, the recursor fallbacks to sending 127.0.0.1.
 406
 407 .. _setting-edns-outgoing-bufsize:
 408
 409 ``edns-outgoing-bufsize``
 410 -------------------------
 411 .. versionchanged:: 4.2.0
 412   Before 4.2.0, the default was 1680
 413
 414 -  Integer
 415 -  Default: 1232
 416
 417 .. note:: Why 1232?
 418
 419   1232 is the largest number of payload bytes that can fit in the smallest IPv6 packet.
 420   IPv6 has a minimum MTU of 1280 bytes (:rfc:`RFC 8200, section 5 <8200#section-5>`), minus 40 bytes for the IPv6 header, minus 8 bytes for the UDP header gives 1232, the maximum payload size for the DNS response.
 421
 422 This is the value set for the EDNS0 buffer size in outgoing packets.
 423 Lower this if you experience timeouts.
 424
 425 .. _setting-edns-subnet-whitelist:
 426
 427 ``edns-subnet-whitelist``
 428 -------------------------
 429 -  Comma separated list of domain names and netmasks
 430 -  Default: (none)
 431
 432 List of netmasks and domains that :rfc:`EDNS Client Subnet <7871>` should be enabled for in outgoing queries.
 433
 434 For example, an EDNS Client Subnet option containing the address of the initial requestor (but see `ecs-add-for`_) will be added to an outgoing query sent to server 192.0.2.1 for domain X if 192.0.2.1 matches one of the supplied netmasks, or if X matches one of the supplied domains.
 435 The initial requestor address will be truncated to 24 bits for IPv4 (see `ecs-ipv4-bits`_) and to 56 bits for IPv6 (see `ecs-ipv6-bits`_), as recommended in the privacy section of RFC 7871.
 436
 437 By default, this option is empty, meaning no EDNS Client Subnet information is sent.
 438
 439 .. _setting-entropy-source:
 440
 441 ``entropy-source``
 442 ------------------
 443 -  Path
 444 -  Default: /dev/urandom
 445
 446 PowerDNS can read entropy from a (hardware) source.
 447 This is used for generating random numbers which are very hard to predict.
 448 Generally on UNIX platforms, this source will be ``/dev/urandom``, which will always supply random numbers, even if entropy is lacking.
 449 Change to ``/dev/random`` if PowerDNS should block waiting for enough entropy to arrive.
 450
 451 .. _setting-etc-hosts-file:
 452
 453 ``etc-hosts-file``
 454 ------------------
 455 -  Path
 456 -  Default: /etc/hosts
 457
 458 The path to the /etc/hosts file, or equivalent.
 459 This file can be used to serve data authoritatively using `export-etc-hosts`_.
 460
 461 .. _setting-export-etc-hosts:
 462
 463 ``export-etc-hosts``
 464 --------------------
 465 -  Boolean
 466 -  Default: no
 467
 468 If set, this flag will export the host names and IP addresses mentioned in ``/etc/hosts``.
 469
 470 .. _setting-export-etc-hosts-search-suffix:
 471
 472 ``export-etc-hosts-search-suffix``
 473 ----------------------------------
 474 -  String
 475
 476 If set, all hostnames in the `export-etc-hosts`_ file are loaded in canonical form, based on this suffix, unless the name contains a '.', in which case the name is unchanged.
 477 So an entry called 'pc' with ``export-etc-hosts-search-suffix='home.com'`` will lead to the generation of 'pc.home.com' within the recursor.
 478 An entry called 'server1.home' will be stored as 'server1.home', regardless of this setting.
 479
 480 .. _setting-forward-zones:
 481
 482 ``forward-zones``
 483 -----------------
 484 -  'zonename=IP' pairs, comma separated
 485
 486 Queries for zones listed here will be forwarded to the IP address listed. i.e.
 487
 488 .. code-block:: none
 489
 490     forward-zones=example.org=203.0.113.210, powerdns.com=2001:DB8::BEEF:5
 491
 492 Multiple IP addresses can be specified and port numbers other than 53 can be configured:
 493
 494 .. code-block:: none
 495
 496     forward-zones=example.org=203.0.113.210:5300;127.0.0.1, powerdns.com=127.0.0.1;198.51.100.10:530;[2001:DB8::1:3]:5300
 497
 498 Forwarded queries have the 'recursion desired' bit set to 0, meaning that this setting is intended to forward queries to authoritative servers.
 499
 500 **IMPORTANT**: When using DNSSEC validation (which is default), forwards to non-delegated (e.g. internal) zones that have a DNSSEC signed parent zone will validate as Bogus.
 501 To prevent this, add a Negative Trust Anchor (NTA) for this zone in the `lua-config-file`_ with ``addNTA("your.zone", "A comment")``.
 502 If this forwarded zone is signed, instead of adding NTA, add the DS record to the `lua-config-file`_.
 503 See the :doc:`dnssec` information.
 504
 505 .. _setting-forward-zones-file:
 506
 507 ``forward-zones-file``
 508 ----------------------
 509 -  Path
 510
 511 Same as `forward-zones`_, parsed from a file. Only 1 zone is allowed per line, specified as follows:
 512
 513 .. code-block:: none
 514
 515     example.org=203.0.113.210, 192.0.2.4:5300
 516
 517 Zones prefixed with a '+' are forwarded with the recursion-desired bit set, for which see `forward-zones-recurse`_.
 518 Default behaviour without '+' is as with `forward-zones`_.
 519
 520 .. versionchanged:: 4.0.0
 521
 522   Comments are allowed, everything behind '#' is ignored.
 523
 524 The DNSSEC notes from `forward-zones`_ apply here as well.
 525
 526 .. _setting-forward-zones-recurse:
 527
 528 ``forward-zones-recurse``
 529 -------------------------
 530 -  'zonename=IP' pairs, comma separated
 531
 532 Like regular `forward-zones`_, but forwarded queries have the 'recursion desired' bit set to 1, meaning that this setting is intended to forward queries to other recursive servers.
 533
 534 The DNSSEC notes from `forward-zones`_ apply here as well.
 535
 536 .. _setting-gettag-needs-edns-options:
 537
 538 ``gettag-needs-edns-options``
 539 -----------------------------
 540 .. versionadded:: 4.1.0
 541
 542 -  Boolean
 543 -  Default: no
 544
 545 If set, EDNS options in incoming queries are extracted and passed to the :func:`gettag` hook in the ``ednsoptions`` table.
 546
 547 .. _setting-hint-file:
 548
 549 ``hint-file``
 550 -------------
 551 -  Path
 552
 553 If set, the root-hints are read from this file. If unset, default root hints are used.
 554
 555 .. _setting-include-dir:
 556
 557 ``include-dir``
 558 ---------------
 559 -  Path
 560
 561 Directory to scan for additional config files. All files that end with .conf are loaded in order using ``POSIX`` as locale.
 562
 563 .. _setting-latency-statistic-size:
 564
 565 ``latency-statistic-size``
 566 --------------------------
 567 -  Integer
 568 -  Default: 10000
 569
 570 Indication of how many queries will be averaged to get the average latency reported by the 'qa-latency' metric.
 571
 572 .. _setting-local-address:
 573
 574 ``local-address``
 575 -----------------
 576 -  IP addresses, comma separated
 577 -  Default: 127.0.0.1
 578
 579 Local IPv4 or IPv6 addresses to bind to.
 580 Addresses can also contain port numbers, for IPv4 specify like this: ``192.0.2.4:5300``, for IPv6: ``[::1]:5300``.
 581
 582 **Warning**: When binding to wildcard addresses, UNIX semantics mean that answers may not be sent from the address a query was received on.
 583 It is highly recommended to bind to explicit addresses.
 584
 585 .. _setting-local-port:
 586
 587 ``local-port``
 588 --------------
 589 -  Integer
 590 -  Default: 53
 591
 592 Local port to bind to.
 593 If an address in `local-address`_ does not have an explicit port, this port is used.
 594
 595 .. _setting-log-timestamp:
 596
 597 ``log-timestamp``
 598 -----------------
 599
 600 .. versionadded:: 4.1.0
 601
 602 - Bool
 603 - Default: yes
 604
 605 When printing log lines to stdout, prefix them with timestamps.
 606 Disable this if the process supervisor timestamps these lines already.
 607
 608 .. note::
 609   The systemd unit file supplied with the source code already disables timestamp printing
 610
 611 .. _setting-non-local-bind:
 612
 613 ``non-local-bind``
 614 ------------------
 615 -  Boolean
 616 -  Default: no
 617
 618 Bind to addresses even if one or more of the `local-address`_'s do not exist on this server.
 619 Setting this option will enable the needed socket options to allow binding to non-local addresses.
 620 This feature is intended to facilitate ip-failover setups, but it may also mask configuration issues and for this reason it is disabled by default.
 621
 622 .. _setting-loglevel:
 623
 624 ``loglevel``
 625 ------------
 626 -  Integer between 0 and 9
 627 -  Default: 6
 628
 629 Amount of logging.
 630 Higher is more, more logging may destroy performance.
 631 It is recommended not to set this below 3.
 632
 633 .. _setting-log-common-errors:
 634
 635 ``log-common-errors``
 636 ---------------------
 637 -  Boolean
 638 -  Default: no
 639
 640 Some DNS errors occur rather frequently and are no cause for alarm.
 641
 642 ``log-rpz-changes``
 643 -------------------
 644 .. versionadded:: 4.1.0
 645
 646 -  Boolean
 647 -  Default: no
 648
 649 Log additions and removals to RPZ zones at Info (6) level instead of Debug (7).
 650
 651 .. _setting-logging-facility:
 652
 653 ``logging-facility``
 654 --------------------
 655 -  Integer
 656
 657 If set to a digit, logging is performed under this LOCAL facility.
 658 See :ref:`logging`.
 659 Do not pass names like 'local0'!
 660
 661 .. _setting-lowercase-outgoing:
 662
 663 ``lowercase-outgoing``
 664 ----------------------
 665 -  Boolean
 666 -  Default: no
 667
 668 Set to true to lowercase the outgoing queries.
 669 When set to 'no' (the default) a query from a client using mixed case in the DNS labels (such as a user entering mixed-case names or `draft-vixie-dnsext-dns0x20-00 <http://tools.ietf.org/html/draft-vixie-dnsext-dns0x20-00>`_), PowerDNS preserves the case of the query.
 670 Broken authoritative servers might give a wrong or broken answer on this encoding.
 671 Setting ``lowercase-outgoing`` to 'yes' makes the PowerDNS Recursor lowercase all the labels in the query to the authoritative servers, but still return the proper case to the client requesting.
 672
 673 .. _setting-lua-config-file:
 674
 675 ``lua-config-file``
 676 -------------------
 677 -  Filename
 678
 679 If set, and Lua support is compiled in, this will load an additional configuration file for newer features and more complicated setups.
 680 See :doc:`lua-config/index` for the options that can be set in this file.
 681
 682 .. _setting-lua-dns-script:
 683
 684 ``lua-dns-script``
 685 ------------------
 686 -  Path
 687 -  Default: unset
 688
 689 Path to a lua file to manipulate the Recursor's answers. See :doc:`lua-scripting/index` for more information.
 690
 691 .. _setting-maintenance-interval:
 692
 693 ``lua-maintenance-interval``
 694 ----------------------------
 695 .. versionadded:: 4.1.4
 696
 697 -  Integer
 698 -  Default: 1
 699
 700
 701 The interval between calls to the Lua user defined `maintenance()` function in seconds.
 702 See :ref:`hooks-maintenance-callback`
 703
 704 .. _setting-max-cache-bogus-ttl:
 705
 706 ``max-cache-bogus-ttl``
 707 -----------------------
 708 .. versionadded:: 4.2.0
 709
 710 -  Integer
 711 -  Default: 3600
 712
 713 Maximum number of seconds to cache an item in the DNS cache (negative or positive) if its DNSSEC validation failed, no matter what the original TTL specified, to reduce the impact of a broken domain.
 714
 715 .. _setting-max-cache-entries:
 716
 717 ``max-cache-entries``
 718 ---------------------
 719 -  Integer
 720 -  Default: 1000000
 721
 722 Maximum number of DNS cache entries.
 723 1 million per thread will generally suffice for most installations.
 724
 725 .. _setting-max-cache-ttl:
 726
 727 ``max-cache-ttl``
 728 -----------------
 729 -  Integer
 730 -  Default: 86400
 731
 732 Maximum number of seconds to cache an item in the DNS cache, no matter what the original TTL specified.
 733
 734 .. versionchanged:: 4.1.0
 735
 736     The minimum value of this setting is 15. i.e. setting this to lower than 15 will make this value 15.
 737
 738 .. _setting-max-mthreads:
 739
 740 ``max-mthreads``
 741 ----------------
 742 -  Integer
 743 -  Default: 2048
 744
 745 Maximum number of simultaneous MTasker threads.
 746
 747 .. _setting-max-packetcache-entries:
 748
 749 ``max-packetcache-entries``
 750 ---------------------------
 751 -  Integer
 752 -  Default: 500000
 753
 754 Maximum number of Packet Cache entries.
 755 1 million per thread will generally suffice for most installations.
 756
 757 .. _setting-max-qperq:
 758
 759 ``max-qperq``
 760 -------------
 761 -  Integer
 762 -  Default: 50
 763
 764 The maximum number of outgoing queries that will be sent out during the resolution of a single client query.
 765 This is used to limit endlessly chasing CNAME redirections.
 766
 767 .. _setting-max-negative-ttl:
 768
 769 ``max-negative-ttl``
 770 --------------------
 771 -  Integer
 772 -  Default: 3600
 773
 774 A query for which there is authoritatively no answer is cached to quickly deny a record's existence later on, without putting a heavy load on the remote server.
 775 In practice, caches can become saturated with hundreds of thousands of hosts which are tried only once.
 776 This setting, which defaults to 3600 seconds, puts a maximum on the amount of time negative entries are cached.
 777
 778 .. _setting-max-recursion-depth:
 779
 780 ``max-recursion-depth``
 781 -----------------------
 782 -  Integer
 783 -  Default: 40
 784
 785 Total maximum number of internal recursion calls the server may use to answer a single query.
 786 0 means unlimited.
 787 The value of `stack-size`_ should be increased together with this one to prevent the stack from overflowing.
 788
 789 .. versionchanged:: 4.1.0
 790
 791     Before 4.1.0, this settings was unlimited.
 792
 793 .. _setting-max-tcp-clients:
 794
 795 ``max-tcp-clients``
 796 -------------------
 797 -  Integer
 798 -  Default: 128
 799
 800 Maximum number of simultaneous incoming TCP connections allowed.
 801
 802 .. _setting-max-tcp-per-client:
 803
 804 ``max-tcp-per-client``
 805 ----------------------
 806 -  Integer
 807 -  Default: 0 (unlimited)
 808
 809 Maximum number of simultaneous incoming TCP connections allowed per client (remote IP address).
 810
 811 .. _setting-max-tcp-queries-per-connection:
 812
 813 ``max-tcp-queries-per-connection``
 814 ----------------------------------
 815 .. versionadded:: 4.1.0
 816
 817 -  Integer
 818 -  Default: 0 (unlimited)
 819
 820 Maximum number of DNS queries in a TCP connection.
 821
 822 .. _setting-max-total-msec:
 823
 824 ``max-total-msec``
 825 ------------------
 826 -  Integer
 827 -  Default: 7000
 828
 829 Total maximum number of milliseconds of wallclock time the server may use to answer a single query.
 830
 831 .. _setting-max-udp-queries-per-round:
 832
 833 ``max-udp-queries-per-round``
 834 ----------------------------------
 835 .. versionadded:: 4.1.4
 836
 837 -  Integer
 838 -  Default: 10000
 839
 840 Under heavy load the recursor might be busy processing incoming UDP queries for a long while before there is no more of these, and might therefore
 841 neglect scheduling new ``mthreads``, handling responses from authoritative servers or responding to :doc:`rec_control <manpages/rec_control.1>`
 842 requests.
 843 This setting caps the maximum number of incoming UDP DNS queries processed in a single round of looping on ``recvmsg()`` after being woken up by the multiplexer, before
 844 returning back to normal processing and handling other events.
 845
 846 .. _setting-minimum-ttl-override:
 847
 848 ``minimum-ttl-override``
 849 ------------------------
 850 -  Integer
 851 -  Default: 0 (disabled)
 852
 853 This setting artificially raises all TTLs to be at least this long.
 854 While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers.
 855 Can be set at runtime using ``rec_control set-minimum-ttl 3600``.
 856
 857 .. _setting-new-domain-tracking:
 858
 859 ``new-domain-tracking``
 860 -----------------------
 861 .. versionadded:: 4.2.0
 862
 863 - Boolean
 864 - Default: no (disabled)
 865
 866 Whether to track newly observed domains, i.e. never seen before. This
 867 is a probablistic algorithm, using a stable bloom filter to store
 868 records of previously seen domains. When enabled for the first time,
 869 all domains will appear to be newly observed, so the feature is best
 870 left enabled for e.g. a week or longer before using the results. Note
 871 that this feature is optional and must be enabled at compile-time,
 872 thus it may not be available in all pre-built packages.
 873 If protobuf is enabled and configured, then the newly observed domain
 874 status will appear as a flag in Response messages.
 875
 876 .. _setting-new-domain-log:
 877
 878 ``new-domain-log``
 879 ------------------
 880 .. versionadded:: 4.2.0
 881
 882 - Boolean
 883 - Default: yes (enabled)
 884
 885 If a newly observed domain is detected, log that domain in the
 886 recursor log file. The log line looks something like::
 887
 888   Jul 18 11:31:25 Newly observed domain nod=sdfoijdfio.com
 889
 890 .. _setting-new-domain-lookup:
 891
 892 ``new-domain-lookup``
 893 ---------------------
 894 .. versionadded:: 4.2.0
 895
 896 - Domain Name
 897 - Example: nod.powerdns.com
 898
 899 If a domain is specified, then each time a newly observed domain is
 900 detected, the recursor will perform an A record lookup of "<newly
 901 observed domain>.<lookup domain>". For example if 'new-domain-lookup'
 902 is configured as 'nod.powerdns.com', and a new domain 'xyz123.tv' is
 903 detected, then an A record lookup will be made for
 904 'xyz123.tv.nod.powerdns.com'. This feature gives a way to share the
 905 newly observed domain with partners, vendors or security teams. The
 906 result of the DNS lookup will be ignored by the recursor.
 907
 908 .. _setting-new-domain-db-size:
 909
 910 ``new-domain-db-size``
 911 ----------------------
 912 .. versionadded:: 4.2.0
 913
 914 - Integer
 915 - Example: 67108864
 916
 917 The default size of the stable bloom filter used to store previously
 918 observed domains is 67108864. To change the number of cells, use this
 919 setting. For each cell, the SBF uses 1 bit of memory, and one byte of
 920 disk for the persistent file.
 921 If there are already persistent files saved to disk, this setting will
 922 have no effect unless you remove the existing files.
 923
 924 .. _setting-new-domain-history-dir:
 925
 926 ``new-domain-history-dir``
 927 --------------------------
 928 .. versionadded:: 4.2.0
 929
 930 - Path
 931
 932 This setting controls which directory is used to store the on-disk
 933 cache of previously observed domains.
 934
 935 The default depends on ``LOCALSTATEDIR`` when building the software.
 936 Usually this comes down to ``/var/lib/pdns-recursor/nod`` or ``/usr/local/var/lib/pdns-recursor/nod``).
 937
 938 The newly observed domain feature uses a stable bloom filter to store
 939 a history of previously observed domains. The data structure is
 940 synchronized to disk every 10 minutes, and is also initialized from
 941 disk on startup. This ensures that previously observed domains are
 942 preserved across recursor restarts.
 943 If you change the new-domain-db-size setting, you must remove any files
 944 from this directory.
 945
 946 .. _setting-new-domain-whitelist:
 947
 948 ``new-domain-whitelist``
 949 ------------------------
 950 .. versionadded:: 4.2.0
 951
 952 - List of Domain Names, comma separated
 953 - Example: xyz.com, abc.com
 954
 955 This setting is a list of all domains (and implicitly all subdomains)
 956 that will never be considered a new domain. For example, if the domain
 957 'xyz123.tv' is in the list, then 'foo.bar.xyz123.tv' will never be
 958 considered a new domain. One use-case for the whitelist is to never
 959 reveal details of internal subdomains via the new-domain-lookup
 960 feature.
 961
 962 .. _setting-new-domain-pb-tag:
 963
 964 ``new-domain-pb-tag``
 965 ---------------------
 966 .. versionadded:: 4.2.0
 967
 968 - String
 969 - Default: pnds-nod
 970
 971 If protobuf is configured, then this tag will be added to all protobuf response messages when
 972 a new domain is observed.
 973
 974 .. _setting-network-timeout:
 975
 976 ``network-timeout``
 977 -------------------
 978 -  Integer
 979 -  Default: 1500
 980
 981 Number of milliseconds to wait for a remote authoritative server to respond.
 982
 983 .. _setting-nsec3-max-iterations:
 984
 985 ``nsec3-max-iterations``
 986 ------------------------
 987 .. versionadded:: 4.1.0
 988
 989 -  Integer
 990 -  Default: 2500
 991
 992 Maximum number of iterations allowed for an NSEC3 record.
 993 If an answer containing an NSEC3 record with more iterations is received, its DNSSEC validation status is treated as Insecure.
 994
 995 .. _setting-packetcache-ttl:
 996
 997 ``packetcache-ttl``
 998 -------------------
 999 -  Integer
1000 -  Default: 3600
1001
1002 Maximum number of seconds to cache an item in the packet cache, no matter what the original TTL specified.
1003
1004 .. _setting-packetcache-servfail-ttl:
1005
1006 ``packetcache-servfail-ttl``
1007 ----------------------------
1008 -  Integer
1009 -  Default: 60
1010
1011 Maximum number of seconds to cache a 'server failure' answer in the packet cache.
1012
1013 .. versionchanged:: 4.0.0
1014
1015     This setting's maximum is capped to `packetcache-ttl`_.
1016     i.e. setting ``packetcache-ttl=15`` and keeping ``packetcache-servfail-ttl`` at the default will lower ``packetcache-servfail-ttl`` to ``15``.
1017
1018 .. _setting-pdns-distributes-queries:
1019
1020 ``pdns-distributes-queries``
1021 ----------------------------
1022 -  Boolean
1023 -  Default: yes
1024
1025 If set, PowerDNS will have only 1 thread listening on client sockets, and distribute work by itself over threads by using a hash of the query,
1026 maximizing the cache hit ratio. Starting with version 4.2.0, more than one distributing thread can be started using the `distributor-threads`_
1027 setting.
1028 Improves performance on Linux.
1029
1030 .. _settting-public-suffix-list-file:
1031
1032 ``public-suffix-list-file``
1033 ---------------------------
1034 .. versionadded:: 4.2.0
1035
1036 - Path
1037 - Default: unset
1038
1039 Path to the Public Suffix List file, if any. If set, PowerDNS will try to load the Public Suffix List from this file instead of using the built-in list. The PSL is used to group the queries by relevant domain names when displaying the top queries.
1040
1041 .. _setting-query-local-address:
1042
1043 ``query-local-address``
1044 -----------------------
1045 -  IPv4 Address, comma separated
1046 -  Default: 0.0.0.0
1047
1048 Send out local queries from this address, or addresses, by adding multiple addresses, increased spoofing resilience is achieved.
1049
1050 .. _setting-query-local-address6:
1051
1052 ``query-local-address6``
1053 ------------------------
1054 -  IPv6 addresses, comma separated
1055 -  Default: unset
1056
1057 Send out local IPv6 queries from this address or addresses.
1058 Disabled by default, which also disables outgoing IPv6 support.
1059
1060 .. _setting-quiet:
1061
1062 ``quiet``
1063 ---------
1064 -  Boolean
1065 -  Default: yes
1066
1067 Don't log queries.
1068
1069 .. _setting-reuseport:
1070
1071 ``reuseport``
1072 -------------
1073 -  Boolean
1074 -  Default: no
1075
1076 If ``SO_REUSEPORT`` support is available, allows multiple processes to open a listening socket on the same port.
1077
1078 Since 4.1.0, when ``pdns-distributes-queries`` is set to false and ``reuseport`` is enabled, every thread will open a separate listening socket to let the kernel distribute the incoming queries, avoiding any thundering herd issue as well as the distributor thread being a bottleneck, thus leading to much higher performance on multi-core boxes.
1079
1080 .. _setting-rng:
1081
1082 ``rng``
1083 -------
1084
1085 - String
1086 - Default: auto
1087
1088 Specify which random number generator to use. Permissible choises are
1089  - auto - choose automatically
1090  - sodium - Use libsodium ``randombytes_uniform``
1091  - openssl - Use libcrypto ``RAND_bytes``
1092  - getrandom - Use libc getrandom, falls back to urandom if it does not really work
1093  - arc4random - Use BSD ``arc4random_uniform``
1094  - urandom - Use ``/dev/urandom``
1095  - kiss - Use simple settable deterministic RNG. **FOR TESTING PURPOSES ONLY!**
1096
1097 .. note::
1098   Not all choises are available on all systems.
1099
1100 .. _setting-root-nx-trust:
1101
1102 ``root-nx-trust``
1103 -----------------
1104 -  Boolean
1105 -  Default: yes
1106
1107 If set, an NXDOMAIN from the root-servers will serve as a blanket NXDOMAIN for the entire TLD the query belonged to.
1108 The effect of this is far fewer queries to the root-servers.
1109
1110 .. versionchanged:: 4.0.0
1111
1112     Default is 'yes' now, was 'no' before 4.0.0
1113
1114 .. _setting-security-poll-suffix:
1115
1116 ``security-poll-suffix``
1117 ------------------------
1118 -  String
1119 -  Default: secpoll.powerdns.com.
1120
1121 Domain name from which to query security update notifications.
1122 Setting this to an empty string disables secpoll.
1123
1124 .. _setting-serve-rfc1918:
1125
1126 ``serve-rfc1918``
1127 -----------------
1128 -  Boolean
1129 -  Default: yes
1130
1131 This makes the server authoritatively aware of: ``10.in-addr.arpa``, ``168.192.in-addr.arpa``, ``16-31.172.in-addr.arpa``, which saves load on the AS112 servers.
1132 Individual parts of these zones can still be loaded or forwarded.
1133
1134 .. _setting-server-down-max-fails:
1135
1136 ``server-down-max-fails``
1137 -------------------------
1138 -  Integer
1139 -  Default: 64
1140
1141 If a server has not responded in any way this many times in a row, no longer send it any queries for `server-down-throttle-time`_ seconds.
1142 Afterwards, we will try a new packet, and if that also gets no response at all, we again throttle for `server-down-throttle-time`_ seconds.
1143 Even a single response packet will drop the block.
1144
1145 .. _setting-server-down-throttle-time:
1146
1147 ``server-down-throttle-time``
1148 -----------------------------
1149 -  Integer
1150 -  Default: 60
1151
1152 Throttle a server that has failed to respond `server-down-max-fails`_ times for this many seconds.
1153
1154 .. _setting-server-id:
1155
1156 ``server-id``
1157 -------------
1158 -  String
1159 -  Default: The hostname of the server
1160
1161 The reply given by The PowerDNS recursor to a query for 'id.server' with its hostname, useful for in clusters.
1162 When a query contains the :rfc:`NSID EDNS0 Option <5001>`, this value is returned in the response as the NSID value.
1163
1164 This setting can be used to override the answer given to these queries.
1165 Set to "disabled" to disable NSID and 'id.server' answers.
1166
1167 Query example (where 192.0.2.14 is your server):
1168
1169 .. code-block:: sh
1170
1171     dig @192.0.2.14 CHAOS TXT id.server.
1172     dig @192.0.2.14 example.com IN A +nsid
1173
1174 ``setgid``, ``setuid``
1175 ----------------------
1176 -  String
1177 -  Default: unset
1178
1179 PowerDNS can change its user and group id after binding to its socket.
1180 Can be used for better :doc:`security <security>`.
1181
1182 .. _setting-signature-inception-skew:
1183
1184 ``signature-inception-skew``
1185 ----------------------------------
1186 .. versionadded:: 4.1.5
1187
1188 -  Integer
1189 -  Default: 60
1190
1191 Allow the signature inception to be off by this number of seconds. Negative values are not allowed.
1192
1193 .. versionchanged:: 4.2.0
1194
1195     Default is now 60, was 0 before.
1196
1197 .. _setting-single-socket:
1198
1199 ``single-socket``
1200 -----------------
1201 -  Boolean
1202 -  Default: no
1203
1204 Use only a single socket for outgoing queries.
1205
1206 .. _setting-snmp-agent:
1207
1208 ``snmp-agent``
1209 --------------
1210 .. versionadded:: 4.1.0
1211
1212 -  Boolean
1213 -  Default: no
1214
1215 If set to true and PowerDNS has been compiled with SNMP support, it will register as an SNMP agent to provide statistics and be able to send traps.
1216
1217 .. _setting-snmp-master-socket:
1218
1219 ``snmp-master-socket``
1220 ----------------------
1221 .. versionadded:: 4.1.0
1222
1223 -  String
1224 -  Default: empty
1225
1226 If not empty and ``snmp-agent`` is set to true, indicates how PowerDNS should contact the SNMP master to register as an SNMP agent.
1227
1228 .. _setting-socket-dir:
1229
1230 ``socket-dir``
1231 --------------
1232 -  Path
1233
1234 Where to store the control socket and pidfile.
1235 The default depends on ``LOCALSTATEDIR`` or the ``--with-socketdir`` setting when building (usually ``/var/run`` or ``/run``).
1236
1237 When using `chroot`_ the default becomes to ``/``.
1238
1239 ``socket-owner``, ``socket-group``, ``socket-mode``
1240 ---------------------------------------------------
1241 Owner, group and mode of the controlsocket.
1242 Owner and group can be specified by name, mode is in octal.
1243
1244 .. _setting-spoof-nearmiss-max:
1245
1246 ``spoof-nearmiss-max``
1247 ----------------------
1248 -  Integer
1249 -  Default: 20
1250
1251 If set to non-zero, PowerDNS will assume it is being spoofed after seeing this many answers with the wrong id.
1252
1253 .. _setting-stack-size:
1254
1255 ``stack-size``
1256 --------------
1257 -  Integer
1258 -  Default: 200000
1259
1260 Size of the stack per thread.
1261
1262 .. _setting-statistics-interval:
1263
1264 ``statistics-interval``
1265 -----------------------
1266 .. versionadded:: 4.1.0
1267
1268 -  Integer
1269 -  Default: 1800
1270
1271 Interval between logging statistical summary on recursor performance.
1272 Use 0 to disable.
1273
1274 .. _setting-stats-ringbuffer-entries:
1275
1276 ``stats-ringbuffer-entries``
1277 ----------------------------
1278 -  Integer
1279 -  Default: 10000
1280
1281 Number of entries in the remotes ringbuffer, which keeps statistics on who is querying your server.
1282 Can be read out using ``rec_control top-remotes``.
1283
1284 .. _setting-tcp-fast-open:
1285
1286 ``tcp-fast-open``
1287 -----------------
1288 .. versionadded:: 4.1.0
1289
1290 -  Integer
1291 -  Default: 0 (Disabled)
1292
1293 Enable TCP Fast Open support, if available, on the listening sockets.
1294 The numerical value supplied is used as the queue size, 0 meaning disabled.
1295
1296 .. _setting-threads:
1297
1298 ``threads``
1299 -----------
1300 -  Integer
1301 -  Default: 2
1302
1303 Spawn this number of threads on startup.
1304
1305 .. _setting-trace:
1306
1307 ``trace``
1308 ---------
1309 -  Boolean
1310 -  Default: no
1311
1312 If turned on, output impressive heaps of logging.
1313 May destroy performance under load.
1314
1315 .. _setting-udp-source-port-min:
1316
1317 ``udp-source-port-min``
1318 -----------------------
1319 .. versionadded:: 4.2.0
1320
1321 -  Integer
1322 -  Default: 1024
1323
1324 This option sets the low limit of UDP port number to bind on.
1325
1326 In combination with `udp-source-port-max`_ it configures the UDP
1327 port range to use. Port numbers are randomized within this range on
1328 initialization, and exceptions can be configured with `udp-source-port-avoid`_
1329
1330 .. _setting-udp-source-port-max:
1331
1332 ``udp-source-port-max``
1333 -----------------------
1334 .. versionadded:: 4.2.0
1335
1336 -  Integer
1337 -  Default: 65535
1338
1339 This option sets the maximum limit of UDP port number to bind on.
1340
1341 See `udp-source-port-min`_.
1342
1343 .. _setting-udp-source-port-avoid:
1344
1345 ``udp-source-port-avoid``
1346 -------------------------
1347 .. versionadded:: 4.2.0
1348
1349 -  String
1350 -  Default: 11211
1351
1352 A list of comma-separated UDP port numbers to avoid when binding.
1353 Ex: `5300,11211`
1354
1355 See `udp-source-port-min`_.
1356
1357 .. _setting-udp-truncation-threshold:
1358
1359 ``udp-truncation-threshold``
1360 ----------------------------
1361 .. versionchanged:: 4.2.0
1362   Before 4.2.0, the default was 1680
1363
1364 -  Integer
1365 -  Default: 1232
1366
1367 EDNS0 allows for large UDP response datagrams, which can potentially raise performance.
1368 Large responses however also have downsides in terms of reflection attacks.
1369 This setting limits the accepted size.
1370 Maximum value is 65535, but values above 4096 should probably not be attempted.
1371
1372 To know why 1232, see the note at :ref:`setting-edns-outgoing-bufsize`.
1373
1374 .. _setting-unique-response-tracking:
1375
1376 ``unique-response-tracking``
1377 ----------------------------
1378 .. versionadded:: 4.2.0
1379
1380 - Boolean
1381 - Default: no (disabled)
1382
1383 Whether to track unique DNS responses, i.e. never seen before combinations
1384 of the triplet (query name, query type, RR[rrname, rrtype, rrdata]).
1385 This can be useful for tracking potentially suspicious domains and
1386 behaviour, e.g. DNS fast-flux.
1387 If protobuf is enabled and configured, then the Protobuf Response message
1388 will contain a flag with udr set to true for each RR that is considered
1389 unique, i.e. never seen before.
1390 This feature uses a probabilistic data structure (stable bloom filter) to
1391 track unique responses, which can have false positives as well as false
1392 negatives, thus it is a best-effort feature. Increasing the number of cells
1393 in the SBF using the unique-response-db-size setting can reduce FPs and FNs.
1394
1395 .. _setting-unique-response-log:
1396
1397 ``unique-response-log``
1398 -----------------------
1399 .. versionadded:: 4.2.0
1400
1401 - Boolean
1402 - Default: no (disabled)
1403
1404 Whether to log when a unique response is detected. The log line
1405 looks something like:
1406
1407 Oct 24 12:11:27 Unique response observed: qname=foo.com qtype=A rrtype=AAAA rrname=foo.com rrcontent=1.2.3.4
1408
1409 .. _setting-unique-response-db-size:
1410
1411 ``unique-response-db-size``
1412 ---------------------------
1413 .. versionadded:: 4.2.0
1414
1415 - Integer
1416 - Example: 67108864
1417
1418 The default size of the stable bloom filter used to store previously
1419 observed responses is 67108864. To change the number of cells, use this
1420 setting. For each cell, the SBF uses 1 bit of memory, and one byte of
1421 disk for the persistent file.
1422 If there are already persistent files saved to disk, this setting will
1423 have no effect unless you remove the existing files.
1424
1425 .. _setting-unique-response-history-dir:
1426
1427 ``unique-response-history-dir``
1428 -------------------------------
1429 .. versionadded:: 4.2.0
1430
1431 - Path
1432
1433 This setting controls which directory is used to store the on-disk
1434 cache of previously observed responses.
1435
1436 The default depends on ``LOCALSTATEDIR`` when building the software.
1437 Usually this comes down to ``/var/lib/pdns-recursor/udr`` or ``/usr/local/var/lib/pdns-recursor/udr``).
1438
1439 The newly observed domain feature uses a stable bloom filter to store
1440 a history of previously observed responses. The data structure is
1441 synchronized to disk every 10 minutes, and is also initialized from
1442 disk on startup. This ensures that previously observed responses are
1443 preserved across recursor restarts. If you change the
1444 unique-response-db-size, you must remove any files from this directory.
1445
1446 .. _setting-unique-response-pb-tag:
1447
1448 ``unique-response-pb-tag``
1449 --------------------------
1450 .. versionadded:: 4.2.0
1451
1452 - String
1453 - Default: pnds-udr
1454
1455 If protobuf is configured, then this tag will be added to all protobuf response messages when
1456 a unique DNS response is observed.
1457
1458 .. _setting-use-incoming-edns-subnet:
1459
1460 ``use-incoming-edns-subnet``
1461 ----------------------------
1462 -  Boolean
1463 -  Default: no
1464
1465 Whether to process and pass along a received EDNS Client Subnet to authoritative servers.
1466 The ECS information will only be sent for netmasks and domains listed in `edns-subnet-whitelist`_ and will be truncated if the received scope exceeds `ecs-ipv4-bits`_ for IPv4 or `ecs-ipv6-bits`_ for IPv6.
1467
1468 .. _setting-version:
1469
1470 ``version``
1471 -----------
1472 Print version of this binary. Useful for checking which version of the PowerDNS recursor is installed on a system.
1473
1474 .. _setting-version-string:
1475
1476 ``version-string``
1477 ------------------
1478 -  String
1479 -  Default: PowerDNS Recursor version number
1480
1481 By default, PowerDNS replies to the 'version.bind' query with its version number.
1482 Security conscious users may wish to override the reply PowerDNS issues.
1483
1484 .. _setting-webserver:
1485
1486 ``webserver``
1487 -------------
1488 -  Boolean
1489 -  Default: no
1490
1491 Start the webserver (for REST API).
1492
1493 .. _setting-webserver-address:
1494
1495 ``webserver-address``
1496 ---------------------
1497 -  IP Address
1498 -  Default: 127.0.0.1
1499
1500 IP address for the webserver to listen on.
1501
1502 .. _setting-webserver-allow-from:
1503
1504 ``webserver-allow-from``
1505 ------------------------
1506 -  IP addresses, comma separated
1507 -  Default: 127.0.0.1,::1
1508
1509 .. versionchanged:: 4.1.0
1510
1511     Default is now 127.0.0.1,::1, was 0.0.0.0,::/0 before.
1512
1513 These subnets are allowed to access the webserver.
1514
1515 .. _setting-webserver-password:
1516
1517 ``webserver-password``
1518 ----------------------
1519 -  String
1520 -  Default: unset
1521
1522 Password required to access the webserver.
1523
1524 .. _setting-webserver-port:
1525
1526 ``webserver-port``
1527 ------------------
1528 -  Integer
1529 -  Default: 8082
1530
1531 TCP port where the webserver should listen on.
1532
1533 .. _setting-write-pid:
1534
1535 ``write-pid``
1536 -------------
1537 -  Boolean
1538 -  Default: yes
1539
1540 If a PID file should be written to `socket-dir`_
1541
1542 .. _setting-xpf-allow-from:
1543
1544 ``xpf-allow-from``
1545 ------------------
1546 .. versionadded:: 4.2.0
1547
1548 -  IP ranges, separated by commas
1549 -  Default: empty
1550
1551 .. note::
1552   This is an experimental implementation of `draft-bellis-dnsop-xpf <https://datatracker.ietf.org/doc/draft-bellis-dnsop-xpf/>`_.
1553
1554 The server will trust XPF records found in queries sent from those netmasks (both IPv4 and IPv6),
1555 and will adjust queries' source and destination accordingly. This is especially useful when the recursor
1556 is placed behind a proxy like `dnsdist <https://dnsdist.org>`_.
1557 Note that the ref:`setting-allow-from` setting is still applied to the original source address, and thus access restriction
1558 should be done on the proxy.
1559
1560 .. _setting-xpf-rr-code:
1561
1562 ``xpf-rr-code``
1563 ---------------
1564 .. versionadded:: 4.2.0
1565
1566 -  Integer
1567 -  Default: 0
1568
1569 .. note::
1570   This is an experimental implementation of `draft-bellis-dnsop-xpf <https://datatracker.ietf.org/doc/draft-bellis-dnsop-xpf/>`_.
1571
1572 This option sets the resource record code to use for XPF records, as long as an official code has not been assigned to it.
1573 0 means that XPF is disabled.