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.
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.
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.
15 .. _setting-allow-from:
19 - IP ranges, separated by commas
20 - Default: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
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.
27 When the Proxy Protocol is enabled (see `proxy-protocol-from`_), the recursor will check the address of the client IP advertised in the Proxy Protocol header instead of the one of the proxy.
29 .. _setting-allow-from-file:
35 Like `allow-from`_, except reading from file.
36 Overrides the `allow-from`_ setting. To use this feature, supply one netmask per line, with optional comments preceded by a "#".
38 .. _setting-any-to-tcp:
45 Answer questions for the ANY type on UDP with a truncated packet that refers the remote server to TCP.
46 Useful for mitigating ANY reflection attacks.
48 .. _setting-allow-trust-anchor-query:
50 ``allow-trust-anchor-query``
51 ----------------------------
52 .. versionadded:: 4.3.0
57 Allow ``trustanchor.server CH TXT`` and ``negativetrustanchor.server CH TXT`` queries to view the configured :doc:`DNSSEC <dnssec>` (negative) trust anchors.
59 .. _setting-api-config-dir:
63 .. versionadded:: 4.0.0
68 Directory where the REST API stores its configuration and zones.
74 .. versionadded:: 4.0.0
79 Static pre-shared authentication key for access to the REST API.
81 .. _setting-api-readonly:
85 .. versionchanged:: 4.2.0
86 This setting has been removed.
91 Disallow data modification through the REST API when set.
93 .. _setting-api-logfile:
97 .. versionchanged:: 4.2.0
98 This setting has been removed.
103 Location of the server logfile (used by the REST API).
105 .. _setting-auth-can-lower-ttl:
107 ``auth-can-lower-ttl``
108 ----------------------
112 Authoritative zones can transmit a TTL value that is lower than that specified in the parent zone.
113 This is called a 'delegation inconsistency'.
114 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.
115 This will mean a slight deterioration of performance, and it will not solve any problems, but does make the recursor more standards compliant.
116 Not recommended unless you have to tick an 'RFC 2181 compliant' box.
118 .. _setting-auth-zones:
122 - Comma separated list of 'zonename=filename' pairs
124 Zones read from these files (in BIND format) are served authoritatively.
125 DNSSEC is not supported. Example:
129 auth-zones=example.org=/var/zones/example.org, powerdns.com=/var/zones/powerdns.com
131 .. _setting-carbon-interval:
138 If sending carbon updates, this is the interval between them in seconds.
141 .. _setting-carbon-namespace:
145 .. versionadded:: 4.2.0
149 Change the namespace or first string of the metric key. The default is pdns.
151 .. _setting-carbon-ourname:
157 If sending carbon updates, if set, this will override our hostname.
158 Be careful not to include any dots in this setting, unless you know what you are doing.
159 See :ref:`metricscarbon`.
161 .. _setting-carbon-instance:
165 .. versionadded:: 4.2.0
169 Change the instance or third string of the metric key. The default is recursor.
171 .. _setting-carbon-server:
177 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. Moreover you can specify more than one server using a comma delimited list, ex: carbon-server=10.10.10.10,10.10.10.20.
178 You may specify an alternate port by appending :port, for example: ``127.0.0.1:2004``.
185 - Path to a Directory
187 If set, chroot to this directory for more security.
190 Make sure that ``/dev/log`` is available from within the chroot.
191 Logging will silently fail over time otherwise (on logrotate).
193 When using ``chroot``, all other paths (except for `config-dir`_) set in the configuration are relative to the new root.
195 When using ``chroot`` and the API (`webserver`_), `api-readonly`_ **must** be set and `api-config-dir`_ unset.
197 When running on a system where systemd manages services, ``chroot`` does not work out of the box, as PowerDNS cannot use the ``NOTIFY_SOCKET``.
198 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).
200 .. _setting-client-tcp-timeout:
202 ``client-tcp-timeout``
203 ----------------------
207 Time to wait for data from TCP clients.
209 .. _setting-config-dir:
215 Location of configuration directory (``recursor.conf``).
216 Usually ``/etc/powerdns``, but this depends on ``SYSCONFDIR`` during compile-time.
218 .. _setting-config-name:
225 When running multiple recursors on the same server, read settings from :file:`recursor-{name}.conf`, this will also rename the binary image.
231 .. versionadded:: 4.1.0
236 Set CPU affinity for worker threads, asking the scheduler to run those threads on a single CPU, or a set of CPUs.
237 This parameter accepts a space separated list of thread-id=cpu-id, or thread-id=cpu-id-1,cpu-id-2,...,cpu-id-N.
238 For example, to make the worker thread 0 run on CPU id 0 and the worker thread 1 on CPUs 1 and 2::
242 The number of worker threads is determined by the :ref:`setting-threads` setting.
243 If :ref:`setting-pdns-distributes-queries` is set, an additional thread is started, assigned the id 0,
244 and is the only one listening on client sockets and accepting queries, distributing them to the other worker threads afterwards.
246 Starting with version 4.2.0, the thread handling the control channel, the webserver and other internal stuff has been assigned
247 id 0 and more than one distributor thread can be started using the :ref:`setting-distributor-threads` setting, so the distributor
248 threads if any are assigned id 1 and counting, and the other threads follow behind.
250 This parameter is only available on OS that provides the `pthread_setaffinity_np()` function.
259 .. versionchanged:: 4.0.0
261 Default is now "no", was "yes" before.
263 Operate in the background.
265 .. _setting-delegation-only:
269 - Domains, comma separated
271 Which domains we only accept delegations from (a Verisign special).
273 .. _setting-dont-throttle-names:
275 ``dont-throttle-names``
276 ----------------------------
277 .. versionadded:: 4.2.0
279 - Comma separated list of domain-names
282 When an authoritative server does not answer a query or sends a reply the recursor does not like, it is throttled.
283 Any servers' name suffix-matching the supplied names will never be throttled.
286 Most servers on the internet do not respond for a good reason (overloaded or unreachable), ``dont-throttle-names`` could make this load on the upstream server even higher, resulting in further service degradation.
288 .. _setting-dont-throttle-netmasks:
290 ``dont-throttle-netmasks``
291 ----------------------------
292 .. versionadded:: 4.2.0
294 - Comma separated list of netmasks
297 When an authoritative server does not answer a query or sends a reply the recursor does not like, it is throttled.
298 Any servers matching the supplied netmasks will never be throttled.
300 This can come in handy on lossy networks when forwarding, where the same server is configured multiple times (e.g. with ``forward-zones-recurse=example.com=192.0.2.1;192.0.2.1``).
301 By default, the PowerDNS Recursor would throttle the "first" server on a timeout and hence not retry the "second" one.
302 In this case, ``dont-throttle-netmasks`` could be set to ``192.0.2.1``.
305 Most servers on the internet do not respond for a good reason (overloaded or unreachable), ``dont-throttle-netmasks`` could make this load on the upstream server even higher, resulting in further service degradation.
307 .. _setting-disable-packetcache:
309 ``disable-packetcache``
310 -----------------------
314 Turn off the packet cache. Useful when running with Lua scripts that can
317 .. _setting-disable-syslog:
324 Do not log to syslog, only to stdout.
325 Use this setting when running inside a supervisor that handles logging (like systemd).
326 **Note**: do not use this setting in combination with `daemon`_ as all logging will disappear.
328 .. _setting-distribution-load-factor:
330 ``distribution-load-factor``
331 ----------------------------
332 .. versionadded:: 4.1.12
337 If `pdns-distributes-queries`_ is set and this setting is set to another value
338 than 0, the distributor thread will use a bounded load-balancing algorithm while
339 distributing queries to worker threads, making sure that no thread is assigned
340 more queries than distribution-load-factor times the average number of queries
341 currently processed by all the workers.
342 For example, with a value of 1.25, no server should get more than 125 % of the
343 average load. This helps making sure that all the workers have roughly the same
344 share of queries, even if the incoming traffic is very skewed, with a larger
345 number of requests asking for the same qname.
347 .. _setting-distribution-pipe-buffer-size:
349 ``distribution-pipe-buffer-size``
350 ---------------------------------
351 .. versionadded:: 4.2.0
356 Size in bytes of the internal buffer of the pipe used by the distributor to pass incoming queries to a worker thread.
357 Requires support for `F_SETPIPE_SZ` which is present in Linux since 2.6.35. The actual size might be rounded up to
358 a multiple of a page size. 0 means that the OS default size is used.
359 A large buffer might allow the recursor to deal with very short-lived load spikes during which a worker thread gets
360 overloaded, but it will be at the cost of an increased latency.
362 .. _setting-distributor-threads:
364 ``distributor-threads``
365 -----------------------
366 .. versionadded:: 4.2.0
369 - Default: 1 if `pdns-distributes-queries`_ is set, 0 otherwise
371 If `pdns-distributes-queries`_ is set, spawn this number of distributor threads on startup. Distributor threads
372 handle incoming queries and distribute them to other threads based on a hash of the query, to maximize the cache hit
375 .. _setting-dns64-prefix:
379 .. versionadded:: 4.4.0
381 - Netmask, as a string
384 Enable DNS64 (:rfc:`6147`) support using the supplied /96 IPv6 prefix. This will generate 'fake' AAAA records for names
385 with only `A` records, as well as 'fake' PTR records to make sure that reverse lookup of DNS64-generated IPv6 addresses
386 generate the right name.
387 See :doc:`dns64` for more flexible but slower alternatives using Lua.
393 .. versionadded:: 4.0.0
395 - One of ``off``, ``process-no-validate``, ``process``, ``log-fail``, ``validate``, String
396 - Default: ``process-no-validate``
398 Set the mode for DNSSEC processing:
402 No DNSSEC processing whatsoever.
403 Ignore DO-bits in queries, don't request any DNSSEC information from authoritative servers.
404 This behaviour is similar to PowerDNS Recursor pre-4.0.
408 Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries.
409 Don't do any validation.
413 Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries.
414 Do validation for clients that request it (by means of the AD- bit or DO-bit in the query).
418 Similar behaviour to ``process``, but validate RRSIGs on responses and log bogus responses.
422 Full blown DNSSEC validation. Send SERVFAIL to clients on bogus responses.
424 .. _setting-dnssec-log-bogus:
431 Log every DNSSEC validation failure.
432 **Note**: This is not logged per-query but every time records are validated as Bogus.
434 .. _setting-dont-query:
438 - Netmasks, comma separated
439 - 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
441 The DNS is a public database, but sometimes contains delegations to private IP addresses, like for example 127.0.0.1.
442 This can have odd effects, depending on your network, and may even be a security risk.
443 Therefore, the PowerDNS Recursor by default does not query private space IP addresses.
444 This setting can be used to expand or reduce the limitations.
446 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.
448 .. _setting-ecs-add-for:
452 .. versionadded:: 4.2.0
454 - Comma separated list of netmasks
455 - Default: 0.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
457 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.
458 Valid incoming ECS values from `use-incoming-edns-subnet`_ are not replaced.
460 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.
462 This defaults to not using the requestor address inside RFC1918 and similar "private" IP address spaces.
464 .. _setting-ecs-ipv4-bits:
468 .. versionadded:: 4.1.0
473 Number of bits of client IPv4 address to pass when sending EDNS Client Subnet address information.
475 .. _setting-ecs-ipv4-cache-bits:
477 ``ecs-ipv4-cache-bits``
478 -----------------------
479 .. versionadded:: 4.1.12
484 Maximum number of bits of client IPv4 address used by the authoritative server (as indicated by the EDNS Client Subnet scope in the answer) for an answer to be inserted into the query cache. This condition applies in conjunction with ``ecs-cache-limit-ttl``.
485 That is, only if both the limits apply, the record will not be cached.
487 .. _setting-ecs-ipv6-bits:
491 .. versionadded:: 4.1.0
496 Number of bits of client IPv6 address to pass when sending EDNS Client Subnet address information.
498 .. _setting-ecs-ipv6-cache-bits:
500 ``ecs-ipv6-cache-bits``
501 -----------------------
502 .. versionadded:: 4.1.12
507 Maximum number of bits of client IPv6 address used by the authoritative server (as indicated by the EDNS Client Subnet scope in the answer) for an answer to be inserted into the query cache. This condition applies in conjunction with ``ecs-cache-limit-ttl``.
508 That is, only if both the limits apply, the record will not be cached.
510 .. _setting-ecs-minimum-ttl-override:
512 ``ecs-minimum-ttl-override``
513 ----------------------------
515 - Default: 0 (disabled)
517 This setting artificially raises the TTLs of records in the ANSWER section of ECS-specific answers to be at least this long.
518 While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers.
519 Can be set at runtime using ``rec_control set-ecs-minimum-ttl 3600``.
521 .. _setting-ecs-cache-limit-ttl:
523 ``ecs-cache-limit-ttl``
524 -----------------------
525 .. versionadded:: 4.1.12
528 - Default: 0 (disabled)
530 The minimum TTL for an ECS-specific answer to be inserted into the query cache. This condition applies in conjunction with ``ecs-ipv4-cache-bits`` or ``ecs-ipv6-cache-bits``.
531 That is, only if both the limits apply, the record will not be cached.
533 .. _setting-ecs-scope-zero-address:
535 ``ecs-scope-zero-address``
536 --------------------------
537 .. versionadded:: 4.1.0
539 - IPv4 or IPv6 Address
542 The IP address sent via EDNS Client Subnet to authoritative servers listed in
543 `edns-subnet-whitelist`_ when `use-incoming-edns-subnet`_ is set and the query has
544 an ECS source prefix-length set to 0.
545 The default is to look for the first usable (not an ``any`` one) address in
546 `query-local-address`_ then `query-local-address6`_. If no suitable address is
547 found, the recursor fallbacks to sending 127.0.0.1.
549 .. _setting-edns-outgoing-bufsize:
551 ``edns-outgoing-bufsize``
552 -------------------------
553 .. versionchanged:: 4.2.0
554 Before 4.2.0, the default was 1680
561 1232 is the largest number of payload bytes that can fit in the smallest IPv6 packet.
562 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.
564 This is the value set for the EDNS0 buffer size in outgoing packets.
565 Lower this if you experience timeouts.
567 .. _setting-edns-subnet-whitelist:
569 ``edns-subnet-whitelist``
570 -------------------------
571 - Comma separated list of domain names and netmasks
574 List of netmasks and domains that :rfc:`EDNS Client Subnet <7871>` should be enabled for in outgoing queries.
576 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.
577 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.
579 By default, this option is empty, meaning no EDNS Client Subnet information is sent.
581 .. _setting-entropy-source:
586 - Default: /dev/urandom
588 PowerDNS can read entropy from a (hardware) source.
589 This is used for generating random numbers which are very hard to predict.
590 Generally on UNIX platforms, this source will be ``/dev/urandom``, which will always supply random numbers, even if entropy is lacking.
591 Change to ``/dev/random`` if PowerDNS should block waiting for enough entropy to arrive.
593 .. _setting-etc-hosts-file:
598 - Default: /etc/hosts
600 The path to the /etc/hosts file, or equivalent.
601 This file can be used to serve data authoritatively using `export-etc-hosts`_.
603 .. _setting-export-etc-hosts:
610 If set, this flag will export the host names and IP addresses mentioned in ``/etc/hosts``.
612 .. _setting-export-etc-hosts-search-suffix:
614 ``export-etc-hosts-search-suffix``
615 ----------------------------------
618 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.
619 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.
620 An entry called 'server1.home' will be stored as 'server1.home', regardless of this setting.
622 .. _setting-forward-zones:
626 - 'zonename=IP' pairs, comma separated
628 Queries for zones listed here will be forwarded to the IP address listed. i.e.
632 forward-zones=example.org=203.0.113.210, powerdns.com=2001:DB8::BEEF:5
634 Multiple IP addresses can be specified and port numbers other than 53 can be configured:
638 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
640 Forwarded queries have the 'recursion desired' bit set to 0, meaning that this setting is intended to forward queries to authoritative servers.
642 **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.
643 To prevent this, add a Negative Trust Anchor (NTA) for this zone in the `lua-config-file`_ with ``addNTA("your.zone", "A comment")``.
644 If this forwarded zone is signed, instead of adding NTA, add the DS record to the `lua-config-file`_.
645 See the :doc:`dnssec` information.
647 .. _setting-forward-zones-file:
649 ``forward-zones-file``
650 ----------------------
653 Same as `forward-zones`_, parsed from a file. Only 1 zone is allowed per line, specified as follows:
657 example.org=203.0.113.210, 192.0.2.4:5300
659 Zones prefixed with a '+' are forwarded with the recursion-desired bit set, for which see `forward-zones-recurse`_.
660 Default behaviour without '+' is as with `forward-zones`_.
662 .. versionchanged:: 4.0.0
664 Comments are allowed, everything behind '#' is ignored.
666 The DNSSEC notes from `forward-zones`_ apply here as well.
668 .. _setting-forward-zones-recurse:
670 ``forward-zones-recurse``
671 -------------------------
672 - 'zonename=IP' pairs, comma separated
674 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.
676 The DNSSEC notes from `forward-zones`_ apply here as well.
678 .. _setting-gettag-needs-edns-options:
680 ``gettag-needs-edns-options``
681 -----------------------------
682 .. versionadded:: 4.1.0
687 If set, EDNS options in incoming queries are extracted and passed to the :func:`gettag` hook in the ``ednsoptions`` table.
689 .. _setting-hint-file:
695 If set, the root-hints are read from this file. If unset, default root hints are used.
697 .. _setting-include-dir:
703 Directory to scan for additional config files. All files that end with .conf are loaded in order using ``POSIX`` as locale.
705 .. _setting-latency-statistic-size:
707 ``latency-statistic-size``
708 --------------------------
712 Indication of how many queries will be averaged to get the average latency reported by the 'qa-latency' metric.
714 .. _setting-local-address:
718 - IP addresses, comma separated
721 Local IPv4 or IPv6 addresses to bind to.
722 Addresses can also contain port numbers, for IPv4 specify like this: ``192.0.2.4:5300``, for IPv6: ``[::1]:5300``.
724 **Warning**: When binding to wildcard addresses, UNIX semantics mean that answers may not be sent from the address a query was received on.
725 It is highly recommended to bind to explicit addresses.
727 .. _setting-local-port:
734 Local port to bind to.
735 If an address in `local-address`_ does not have an explicit port, this port is used.
737 .. _setting-log-timestamp:
742 .. versionadded:: 4.1.0
747 When printing log lines to stdout, prefix them with timestamps.
748 Disable this if the process supervisor timestamps these lines already.
751 The systemd unit file supplied with the source code already disables timestamp printing
753 .. _setting-non-local-bind:
760 Bind to addresses even if one or more of the `local-address`_'s do not exist on this server.
761 Setting this option will enable the needed socket options to allow binding to non-local addresses.
762 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.
764 .. _setting-loglevel:
768 - Integer between 0 and 9
772 Higher is more, more logging may destroy performance.
773 It is recommended not to set this below 3.
775 .. _setting-log-common-errors:
777 ``log-common-errors``
778 ---------------------
782 Some DNS errors occur rather frequently and are no cause for alarm.
786 .. versionadded:: 4.1.0
791 Log additions and removals to RPZ zones at Info (6) level instead of Debug (7).
793 .. _setting-logging-facility:
799 If set to a digit, logging is performed under this LOCAL facility.
801 Do not pass names like 'local0'!
803 .. _setting-lowercase-outgoing:
805 ``lowercase-outgoing``
806 ----------------------
810 Set to true to lowercase the outgoing queries.
811 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.
812 Broken authoritative servers might give a wrong or broken answer on this encoding.
813 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.
815 .. _setting-lua-config-file:
821 If set, and Lua support is compiled in, this will load an additional configuration file for newer features and more complicated setups.
822 See :doc:`lua-config/index` for the options that can be set in this file.
824 .. _setting-lua-dns-script:
831 Path to a lua file to manipulate the Recursor's answers. See :doc:`lua-scripting/index` for more information.
833 .. _setting-maintenance-interval:
835 ``lua-maintenance-interval``
836 ----------------------------
837 .. versionadded:: 4.2.0
843 The interval between calls to the Lua user defined `maintenance()` function in seconds.
844 See :ref:`hooks-maintenance-callback`
846 .. _setting-max-cache-bogus-ttl:
848 ``max-cache-bogus-ttl``
849 -----------------------
850 .. versionadded:: 4.2.0
855 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.
857 .. _setting-max-cache-entries:
859 ``max-cache-entries``
860 ---------------------
864 Maximum number of DNS cache entries.
865 1 million per thread will generally suffice for most installations.
867 .. _setting-max-cache-ttl:
874 Maximum number of seconds to cache an item in the DNS cache, no matter what the original TTL specified.
876 .. versionchanged:: 4.1.0
878 The minimum value of this setting is 15. i.e. setting this to lower than 15 will make this value 15.
880 .. _setting max-concurrent-requests-per-tcp-connection:
882 ``max-concurrent-requests-per-tcp-connection``
883 ----------------------------------------------
885 .. versionadded:: 4.3.0
890 Maximum number of incoming requests handled concurrently per tcp
891 connection. This number must be larger than 0 and smaller than 65536
892 and also smaller than `max-mthreads`.
894 .. _setting-max-generate-steps:
896 ``max-generate-steps``
897 ----------------------
899 .. versionadded:: 4.3.0
904 Maximum number of steps for a '$GENERATE' directive when parsing a
905 zone file. This is a protection measure to prevent consuming a lot of
906 CPU and memory when untrusted zones are loaded. Default to 0 which
909 .. _setting-max-mthreads:
916 Maximum number of simultaneous MTasker threads.
918 .. _setting-max-packetcache-entries:
920 ``max-packetcache-entries``
921 ---------------------------
925 Maximum number of Packet Cache entries.
926 1 million per thread will generally suffice for most installations.
928 .. _setting-max-qperq:
935 The maximum number of outgoing queries that will be sent out during the resolution of a single client query.
936 This is used to limit endlessly chasing CNAME redirections.
937 If qname-minimization is enabled, the number will be forced to be 100
938 at a minimum to allow for the extra queries qname-minimization generates when the cache is empty.
940 .. _setting-max-ns-address-qperq:
942 ``max-ns-address-qperq``
943 ------------------------
944 .. versionadded:: 4.1.16
945 .. versionadded:: 4.2.2
946 .. versionadded:: 4.3.1
951 The maximum number of outgoing queries with empty replies for
952 resolving nameserver names to addresses we allow during the resolution
953 of a single client query. If IPv6 is enabled, an A and a AAAA query
954 for a name counts as 1. If a zone publishes more than this number of
955 NS records, the limit is further reduced for that zone by lowering
956 it by the number of NS records found above the
957 `max-ns-address-qperq`_ value. The limit wil not be reduced to a
960 .. _setting-max-negative-ttl:
967 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.
968 In practice, caches can become saturated with hundreds of thousands of hosts which are tried only once.
969 This setting, which defaults to 3600 seconds, puts a maximum on the amount of time negative entries are cached.
971 .. _setting-max-recursion-depth:
973 ``max-recursion-depth``
974 -----------------------
978 Total maximum number of internal recursion calls the server may use to answer a single query.
980 The value of `stack-size`_ should be increased together with this one to prevent the stack from overflowing.
982 .. versionchanged:: 4.1.0
984 Before 4.1.0, this settings was unlimited.
986 .. _setting-max-tcp-clients:
993 Maximum number of simultaneous incoming TCP connections allowed.
995 .. _setting-max-tcp-per-client:
997 ``max-tcp-per-client``
998 ----------------------
1000 - Default: 0 (unlimited)
1002 Maximum number of simultaneous incoming TCP connections allowed per client (remote IP address).
1004 .. _setting-max-tcp-queries-per-connection:
1006 ``max-tcp-queries-per-connection``
1007 ----------------------------------
1008 .. versionadded:: 4.1.0
1011 - Default: 0 (unlimited)
1013 Maximum number of DNS queries in a TCP connection.
1015 .. _setting-max-total-msec:
1022 Total maximum number of milliseconds of wallclock time the server may use to answer a single query.
1024 .. _setting-max-udp-queries-per-round:
1026 ``max-udp-queries-per-round``
1027 ----------------------------------
1028 .. versionadded:: 4.1.4
1033 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
1034 neglect scheduling new ``mthreads``, handling responses from authoritative servers or responding to :doc:`rec_control <manpages/rec_control.1>`
1036 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
1037 returning back to normal processing and handling other events.
1039 .. _setting-minimum-ttl-override:
1041 ``minimum-ttl-override``
1042 ------------------------
1044 - Default: 0 (disabled)
1046 This setting artificially raises all TTLs to be at least this long.
1047 While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers.
1048 Can be set at runtime using ``rec_control set-minimum-ttl 3600``.
1050 .. _setting-new-domain-tracking:
1052 ``new-domain-tracking``
1053 -----------------------
1054 .. versionadded:: 4.2.0
1057 - Default: no (disabled)
1059 Whether to track newly observed domains, i.e. never seen before. This
1060 is a probabilistic algorithm, using a stable bloom filter to store
1061 records of previously seen domains. When enabled for the first time,
1062 all domains will appear to be newly observed, so the feature is best
1063 left enabled for e.g. a week or longer before using the results. Note
1064 that this feature is optional and must be enabled at compile-time,
1065 thus it may not be available in all pre-built packages.
1066 If protobuf is enabled and configured, then the newly observed domain
1067 status will appear as a flag in Response messages.
1069 .. _setting-new-domain-log:
1073 .. versionadded:: 4.2.0
1076 - Default: yes (enabled)
1078 If a newly observed domain is detected, log that domain in the
1079 recursor log file. The log line looks something like::
1081 Jul 18 11:31:25 Newly observed domain nod=sdfoijdfio.com
1083 .. _setting-new-domain-lookup:
1085 ``new-domain-lookup``
1086 ---------------------
1087 .. versionadded:: 4.2.0
1090 - Example: nod.powerdns.com
1092 If a domain is specified, then each time a newly observed domain is
1093 detected, the recursor will perform an A record lookup of "<newly
1094 observed domain>.<lookup domain>". For example if 'new-domain-lookup'
1095 is configured as 'nod.powerdns.com', and a new domain 'xyz123.tv' is
1096 detected, then an A record lookup will be made for
1097 'xyz123.tv.nod.powerdns.com'. This feature gives a way to share the
1098 newly observed domain with partners, vendors or security teams. The
1099 result of the DNS lookup will be ignored by the recursor.
1101 .. _setting-new-domain-db-size:
1103 ``new-domain-db-size``
1104 ----------------------
1105 .. versionadded:: 4.2.0
1110 The default size of the stable bloom filter used to store previously
1111 observed domains is 67108864. To change the number of cells, use this
1112 setting. For each cell, the SBF uses 1 bit of memory, and one byte of
1113 disk for the persistent file.
1114 If there are already persistent files saved to disk, this setting will
1115 have no effect unless you remove the existing files.
1117 .. _setting-new-domain-history-dir:
1119 ``new-domain-history-dir``
1120 --------------------------
1121 .. versionadded:: 4.2.0
1125 This setting controls which directory is used to store the on-disk
1126 cache of previously observed domains.
1128 The default depends on ``LOCALSTATEDIR`` when building the software.
1129 Usually this comes down to ``/var/lib/pdns-recursor/nod`` or ``/usr/local/var/lib/pdns-recursor/nod``).
1131 The newly observed domain feature uses a stable bloom filter to store
1132 a history of previously observed domains. The data structure is
1133 synchronized to disk every 10 minutes, and is also initialized from
1134 disk on startup. This ensures that previously observed domains are
1135 preserved across recursor restarts.
1136 If you change the new-domain-db-size setting, you must remove any files
1137 from this directory.
1139 .. _setting-new-domain-whitelist:
1141 ``new-domain-whitelist``
1142 ------------------------
1143 .. versionadded:: 4.2.0
1145 - List of Domain Names, comma separated
1146 - Example: xyz.com, abc.com
1148 This setting is a list of all domains (and implicitly all subdomains)
1149 that will never be considered a new domain. For example, if the domain
1150 'xyz123.tv' is in the list, then 'foo.bar.xyz123.tv' will never be
1151 considered a new domain. One use-case for the whitelist is to never
1152 reveal details of internal subdomains via the new-domain-lookup
1155 .. _setting-new-domain-pb-tag:
1157 ``new-domain-pb-tag``
1158 ---------------------
1159 .. versionadded:: 4.2.0
1164 If protobuf is configured, then this tag will be added to all protobuf response messages when
1165 a new domain is observed.
1167 .. _setting-network-timeout:
1174 Number of milliseconds to wait for a remote authoritative server to respond.
1176 .. _setting-nothing-below-nxdomain:
1178 ``nothing-below-nxdomain``
1179 --------------------------
1180 .. versionadded:: 4.3.0
1182 - One of ``no``, ``dnssec``, ``yes``, String
1183 - Default: ``dnssec``
1185 The type of :rfc:`8020` handling using cached NXDOMAIN responses.
1186 This RFC specifies that NXDOMAIN means that the DNS tree under the denied name MUST be empty.
1187 When an NXDOMAIN exists in the cache for a shorter name than the qname, no lookup is done and an NXDOMAIN is sent to the client.
1189 For instance, when ``foo.example.net`` is negatively cached, any query
1190 matching ``*.foo.example.net`` will be answered with NXDOMAIN directly
1191 without consulting authoritative servers.
1195 No :rfc:`8020` processing is done.
1199 :rfc:`8020` processing is only done using cached NXDOMAIN records that are
1204 :rfc:`8020` processing is done using any non-Bogus NXDOMAIN record
1205 available in the cache.
1207 .. _setting-nsec3-max-iterations:
1209 ``nsec3-max-iterations``
1210 ------------------------
1211 .. versionadded:: 4.1.0
1216 Maximum number of iterations allowed for an NSEC3 record.
1217 If an answer containing an NSEC3 record with more iterations is received, its DNSSEC validation status is treated as Insecure.
1219 .. _setting-packetcache-ttl:
1226 Maximum number of seconds to cache an item in the packet cache, no matter what the original TTL specified.
1228 .. _setting-packetcache-servfail-ttl:
1230 ``packetcache-servfail-ttl``
1231 ----------------------------
1235 Maximum number of seconds to cache a 'server failure' answer in the packet cache.
1237 .. versionchanged:: 4.0.0
1239 This setting's maximum is capped to `packetcache-ttl`_.
1240 i.e. setting ``packetcache-ttl=15`` and keeping ``packetcache-servfail-ttl`` at the default will lower ``packetcache-servfail-ttl`` to ``15``.
1242 .. _setting-pdns-distributes-queries:
1244 ``pdns-distributes-queries``
1245 ----------------------------
1249 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,
1250 maximizing the cache hit ratio. Starting with version 4.2.0, more than one distributing thread can be started using the `distributor-threads`_
1252 Improves performance on Linux.
1254 .. _setting-protobuf-use-kernel-timestamp:
1256 ``protobuf-use-kernel-timestamp``
1257 ---------------------------------
1258 .. versionadded:: 4.2.0
1263 Whether to compute the latency of responses in protobuf messages using the timestamp set by the kernel when the query packet was received (when available), instead of computing it based on the moment we start processing the query.
1265 .. _setting-proxy-protocol-from:
1267 ``proxy-protocol-from``
1268 -----------------------
1269 .. versionadded:: 4.4.0
1271 - IP ranges, separated by commas
1274 Ranges that are required to send a Proxy Protocol version 2 header in front of UDP and TCP queries, to pass the original source and destination addresses and ports to the recursor, as well as custom values.
1275 Queries that are not prefixed with such a header will not be accepted from clients in these ranges. Queries prefixed by headers from clients that are not listed in these ranges will be dropped.
1277 Note that once a Proxy Protocol header has been received, the source address from the proxy header instead of the address of the proxy will be checked against the `allow-from`_ ACL,
1279 .. _setting-proxy-protocol-maximum-size:
1281 ``proxy-protocol-maximum-size``
1282 -------------------------------
1283 .. versionadded:: 4.4.0
1288 The maximum size, in bytes, of a Proxy Protocol payload (header, addresses and ports, and TLV values). Queries with a larger payload will be dropped.
1290 .. _setting-public-suffix-list-file:
1292 ``public-suffix-list-file``
1293 ---------------------------
1294 .. versionadded:: 4.2.0
1299 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.
1301 .. _setting-qname-minimization:
1303 ``qname-minimization``
1304 ----------------------
1305 .. versionadded:: 4.3.0
1310 Enable Query Name Minimization. This implements a relaxed form of Query Name Mimimization as
1311 described in :rfc:`7816`.
1313 .. _setting-query-local-address:
1315 ``query-local-address``
1316 -----------------------
1317 - IPv4 Address, comma separated
1320 Send out local queries from this address, or addresses, by adding multiple addresses, increased spoofing resilience is achieved.
1322 .. _setting-query-local-address6:
1324 ``query-local-address6``
1325 ------------------------
1326 - IPv6 addresses, comma separated
1329 Send out local IPv6 queries from this address or addresses.
1330 Disabled by default, which also disables outgoing IPv6 support.
1341 .. _setting-reuseport:
1348 If ``SO_REUSEPORT`` support is available, allows multiple processes to open a listening socket on the same port.
1350 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.
1360 Specify which random number generator to use. Permissible choices are
1361 - auto - choose automatically
1362 - sodium - Use libsodium ``randombytes_uniform``
1363 - openssl - Use libcrypto ``RAND_bytes``
1364 - getrandom - Use libc getrandom, falls back to urandom if it does not really work
1365 - arc4random - Use BSD ``arc4random_uniform``
1366 - urandom - Use ``/dev/urandom``
1367 - kiss - Use simple settable deterministic RNG. **FOR TESTING PURPOSES ONLY!**
1370 Not all choices are available on all systems.
1372 .. _setting-root-nx-trust:
1379 If set, an NXDOMAIN from the root-servers will serve as a blanket NXDOMAIN for the entire TLD the query belonged to.
1380 The effect of this is far fewer queries to the root-servers.
1382 .. versionchanged:: 4.0.0
1384 Default is 'yes' now, was 'no' before 4.0.0
1386 .. _setting-security-poll-suffix:
1388 ``security-poll-suffix``
1389 ------------------------
1391 - Default: secpoll.powerdns.com.
1393 Domain name from which to query security update notifications.
1394 Setting this to an empty string disables secpoll.
1396 .. _setting-serve-rfc1918:
1403 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.
1404 Individual parts of these zones can still be loaded or forwarded.
1406 .. _setting-server-down-max-fails:
1408 ``server-down-max-fails``
1409 -------------------------
1413 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.
1414 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.
1415 Even a single response packet will drop the block.
1417 .. _setting-server-down-throttle-time:
1419 ``server-down-throttle-time``
1420 -----------------------------
1424 Throttle a server that has failed to respond `server-down-max-fails`_ times for this many seconds.
1426 .. _setting-server-id:
1431 - Default: The hostname of the server
1433 The reply given by The PowerDNS recursor to a query for 'id.server' with its hostname, useful for in clusters.
1434 When a query contains the :rfc:`NSID EDNS0 Option <5001>`, this value is returned in the response as the NSID value.
1436 This setting can be used to override the answer given to these queries.
1437 Set to "disabled" to disable NSID and 'id.server' answers.
1439 Query example (where 192.0.2.14 is your server):
1443 dig @192.0.2.14 CHAOS TXT id.server.
1444 dig @192.0.2.14 example.com IN A +nsid
1446 ``setgid``, ``setuid``
1447 ----------------------
1451 PowerDNS can change its user and group id after binding to its socket.
1452 Can be used for better :doc:`security <security>`.
1454 .. _setting-signature-inception-skew:
1456 ``signature-inception-skew``
1457 ----------------------------------
1458 .. versionadded:: 4.1.5
1463 Allow the signature inception to be off by this number of seconds. Negative values are not allowed.
1465 .. versionchanged:: 4.2.0
1467 Default is now 60, was 0 before.
1469 .. _setting-single-socket:
1476 Use only a single socket for outgoing queries.
1478 .. _setting-snmp-agent:
1482 .. versionadded:: 4.1.0
1487 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.
1489 .. _setting-snmp-master-socket:
1491 ``snmp-master-socket``
1492 ----------------------
1493 .. versionadded:: 4.1.0
1498 If not empty and ``snmp-agent`` is set to true, indicates how PowerDNS should contact the SNMP master to register as an SNMP agent.
1500 .. _setting-socket-dir:
1506 Where to store the control socket and pidfile.
1507 The default depends on ``LOCALSTATEDIR`` or the ``--with-socketdir`` setting when building (usually ``/var/run`` or ``/run``).
1509 When using `chroot`_ the default becomes to ``/``.
1511 ``socket-owner``, ``socket-group``, ``socket-mode``
1512 ---------------------------------------------------
1513 Owner, group and mode of the controlsocket.
1514 Owner and group can be specified by name, mode is in octal.
1516 .. _setting-spoof-nearmiss-max:
1518 ``spoof-nearmiss-max``
1519 ----------------------
1523 If set to non-zero, PowerDNS will assume it is being spoofed after seeing this many answers with the wrong id.
1525 .. _setting-stack-size:
1532 Size of the stack per thread.
1534 .. _setting-statistics-interval:
1536 ``statistics-interval``
1537 -----------------------
1538 .. versionadded:: 4.1.0
1543 Interval between logging statistical summary on recursor performance.
1546 .. _setting-stats-api-blacklist:
1548 ``stats-api-blacklist``
1549 -----------------------
1550 .. versionadded:: 4.2.0
1553 - Default: "cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*"
1555 A list of comma-separated statistic names, that are disabled when retrieving the complete list of statistics via the API for performance reasons.
1556 These statistics can still be retrieved individually by specifically asking for it.
1558 .. _setting-stats-carbon-blacklist:
1560 ``stats-carbon-blacklist``
1561 --------------------------
1562 .. versionadded:: 4.2.0
1565 - Default: "cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*"
1567 A list of comma-separated statistic names, that are prevented from being exported via carbon for performance reasons.
1569 .. _setting-stats-rec-control-blacklist:
1571 ``stats-rec-control-blacklist``
1572 -------------------------------
1573 .. versionadded:: 4.2.0
1576 - Default: "cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*"
1578 A list of comma-separated statistic names, that are disabled when retrieving the complete list of statistics via `rec_control get-all`, for performance reasons.
1579 These statistics can still be retrieved individually.
1581 .. _setting-stats-ringbuffer-entries:
1583 ``stats-ringbuffer-entries``
1584 ----------------------------
1588 Number of entries in the remotes ringbuffer, which keeps statistics on who is querying your server.
1589 Can be read out using ``rec_control top-remotes``.
1591 .. _setting-stats-snmp-blacklist:
1593 ``stats-snmp-blacklist``
1594 ------------------------
1595 .. versionadded:: 4.2.0
1598 - Default: "cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*"
1600 A list of comma-separated statistic names, that are prevented from being exported via SNMP, for performance reasons.
1602 .. _setting-tcp-fast-open:
1606 .. versionadded:: 4.1.0
1609 - Default: 0 (Disabled)
1611 Enable TCP Fast Open support, if available, on the listening sockets.
1612 The numerical value supplied is used as the queue size, 0 meaning disabled.
1614 .. _setting-threads:
1621 Spawn this number of threads on startup.
1630 If turned on, output impressive heaps of logging.
1631 May destroy performance under load.
1633 .. _setting-udp-source-port-min:
1635 ``udp-source-port-min``
1636 -----------------------
1637 .. versionadded:: 4.2.0
1642 This option sets the low limit of UDP port number to bind on.
1644 In combination with `udp-source-port-max`_ it configures the UDP
1645 port range to use. Port numbers are randomized within this range on
1646 initialization, and exceptions can be configured with `udp-source-port-avoid`_
1648 .. _setting-udp-source-port-max:
1650 ``udp-source-port-max``
1651 -----------------------
1652 .. versionadded:: 4.2.0
1657 This option sets the maximum limit of UDP port number to bind on.
1659 See `udp-source-port-min`_.
1661 .. _setting-udp-source-port-avoid:
1663 ``udp-source-port-avoid``
1664 -------------------------
1665 .. versionadded:: 4.2.0
1670 A list of comma-separated UDP port numbers to avoid when binding.
1673 See `udp-source-port-min`_.
1675 .. _setting-udp-truncation-threshold:
1677 ``udp-truncation-threshold``
1678 ----------------------------
1679 .. versionchanged:: 4.2.0
1680 Before 4.2.0, the default was 1680
1685 EDNS0 allows for large UDP response datagrams, which can potentially raise performance.
1686 Large responses however also have downsides in terms of reflection attacks.
1687 This setting limits the accepted size.
1688 Maximum value is 65535, but values above 4096 should probably not be attempted.
1690 To know why 1232, see the note at :ref:`setting-edns-outgoing-bufsize`.
1692 .. _setting-unique-response-tracking:
1694 ``unique-response-tracking``
1695 ----------------------------
1696 .. versionadded:: 4.2.0
1699 - Default: no (disabled)
1701 Whether to track unique DNS responses, i.e. never seen before combinations
1702 of the triplet (query name, query type, RR[rrname, rrtype, rrdata]).
1703 This can be useful for tracking potentially suspicious domains and
1704 behaviour, e.g. DNS fast-flux.
1705 If protobuf is enabled and configured, then the Protobuf Response message
1706 will contain a flag with udr set to true for each RR that is considered
1707 unique, i.e. never seen before.
1708 This feature uses a probabilistic data structure (stable bloom filter) to
1709 track unique responses, which can have false positives as well as false
1710 negatives, thus it is a best-effort feature. Increasing the number of cells
1711 in the SBF using the unique-response-db-size setting can reduce FPs and FNs.
1713 .. _setting-unique-response-log:
1715 ``unique-response-log``
1716 -----------------------
1717 .. versionadded:: 4.2.0
1720 - Default: no (disabled)
1722 Whether to log when a unique response is detected. The log line
1723 looks something like:
1725 Oct 24 12:11:27 Unique response observed: qname=foo.com qtype=A rrtype=AAAA rrname=foo.com rrcontent=1.2.3.4
1727 .. _setting-unique-response-db-size:
1729 ``unique-response-db-size``
1730 ---------------------------
1731 .. versionadded:: 4.2.0
1736 The default size of the stable bloom filter used to store previously
1737 observed responses is 67108864. To change the number of cells, use this
1738 setting. For each cell, the SBF uses 1 bit of memory, and one byte of
1739 disk for the persistent file.
1740 If there are already persistent files saved to disk, this setting will
1741 have no effect unless you remove the existing files.
1743 .. _setting-unique-response-history-dir:
1745 ``unique-response-history-dir``
1746 -------------------------------
1747 .. versionadded:: 4.2.0
1751 This setting controls which directory is used to store the on-disk
1752 cache of previously observed responses.
1754 The default depends on ``LOCALSTATEDIR`` when building the software.
1755 Usually this comes down to ``/var/lib/pdns-recursor/udr`` or ``/usr/local/var/lib/pdns-recursor/udr``).
1757 The newly observed domain feature uses a stable bloom filter to store
1758 a history of previously observed responses. The data structure is
1759 synchronized to disk every 10 minutes, and is also initialized from
1760 disk on startup. This ensures that previously observed responses are
1761 preserved across recursor restarts. If you change the
1762 unique-response-db-size, you must remove any files from this directory.
1764 .. _setting-unique-response-pb-tag:
1766 ``unique-response-pb-tag``
1767 --------------------------
1768 .. versionadded:: 4.2.0
1773 If protobuf is configured, then this tag will be added to all protobuf response messages when
1774 a unique DNS response is observed.
1776 .. _setting-use-incoming-edns-subnet:
1778 ``use-incoming-edns-subnet``
1779 ----------------------------
1783 Whether to process and pass along a received EDNS Client Subnet to authoritative servers.
1784 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.
1786 .. _setting-version:
1790 Print version of this binary. Useful for checking which version of the PowerDNS recursor is installed on a system.
1792 .. _setting-version-string:
1797 - Default: PowerDNS Recursor version number
1799 By default, PowerDNS replies to the 'version.bind' query with its version number.
1800 Security conscious users may wish to override the reply PowerDNS issues.
1802 .. _setting-webserver:
1809 Start the webserver (for REST API).
1811 .. _setting-webserver-address:
1813 ``webserver-address``
1814 ---------------------
1816 - Default: 127.0.0.1
1818 IP address for the webserver to listen on.
1820 .. _setting-webserver-allow-from:
1822 ``webserver-allow-from``
1823 ------------------------
1824 - IP addresses, comma separated
1825 - Default: 127.0.0.1,::1
1827 .. versionchanged:: 4.1.0
1829 Default is now 127.0.0.1,::1, was 0.0.0.0,::/0 before.
1831 These subnets are allowed to access the webserver.
1833 .. _setting-webserver-loglevel:
1835 ``webserver-loglevel``
1836 ----------------------
1837 .. versionadded:: 4.2.0
1839 - String, one of "none", "normal", "detailed"
1841 The amount of logging the webserver must do. "none" means no useful webserver information will be logged.
1842 When set to "normal", the webserver will log a line per request that should be familiar::
1844 [webserver] e235780e-a5cf-415e-9326-9d33383e739e 127.0.0.1:55376 "GET /api/v1/servers/localhost/bla HTTP/1.1" 404 196
1846 When set to "detailed", all information about the request and response are logged::
1848 [webserver] e235780e-a5cf-415e-9326-9d33383e739e Request Details:
1849 [webserver] e235780e-a5cf-415e-9326-9d33383e739e Headers:
1850 [webserver] e235780e-a5cf-415e-9326-9d33383e739e accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
1851 [webserver] e235780e-a5cf-415e-9326-9d33383e739e accept-encoding: gzip, deflate
1852 [webserver] e235780e-a5cf-415e-9326-9d33383e739e accept-language: en-US,en;q=0.5
1853 [webserver] e235780e-a5cf-415e-9326-9d33383e739e connection: keep-alive
1854 [webserver] e235780e-a5cf-415e-9326-9d33383e739e dnt: 1
1855 [webserver] e235780e-a5cf-415e-9326-9d33383e739e host: 127.0.0.1:8081
1856 [webserver] e235780e-a5cf-415e-9326-9d33383e739e upgrade-insecure-requests: 1
1857 [webserver] e235780e-a5cf-415e-9326-9d33383e739e user-agent: Mozilla/5.0 (X11; Linux x86_64; rv:64.0) Gecko/20100101 Firefox/64.0
1858 [webserver] e235780e-a5cf-415e-9326-9d33383e739e No body
1859 [webserver] e235780e-a5cf-415e-9326-9d33383e739e Response details:
1860 [webserver] e235780e-a5cf-415e-9326-9d33383e739e Headers:
1861 [webserver] e235780e-a5cf-415e-9326-9d33383e739e Connection: close
1862 [webserver] e235780e-a5cf-415e-9326-9d33383e739e Content-Length: 49
1863 [webserver] e235780e-a5cf-415e-9326-9d33383e739e Content-Type: text/html; charset=utf-8
1864 [webserver] e235780e-a5cf-415e-9326-9d33383e739e Server: PowerDNS/0.0.15896.0.gaba8bab3ab
1865 [webserver] e235780e-a5cf-415e-9326-9d33383e739e Full body:
1866 [webserver] e235780e-a5cf-415e-9326-9d33383e739e <!html><title>Not Found</title><h1>Not Found</h1>
1867 [webserver] e235780e-a5cf-415e-9326-9d33383e739e 127.0.0.1:55376 "GET /api/v1/servers/localhost/bla HTTP/1.1" 404 196
1869 The value between the hooks is a UUID that is generated for each request. This can be used to find all lines related to a single request.
1872 The webserver logs these line on the NOTICE level. The :ref:`settings-loglevel` seting must be 5 or higher for these lines to end up in the log.
1874 .. _setting-webserver-password:
1876 ``webserver-password``
1877 ----------------------
1881 Password required to access the webserver.
1883 .. _setting-webserver-port:
1890 TCP port where the webserver should listen on.
1892 .. _setting-write-pid:
1899 If a PID file should be written to `socket-dir`_
1901 .. _setting-xpf-allow-from:
1905 .. versionadded:: 4.2.0
1907 - IP ranges, separated by commas
1911 This is an experimental implementation of `draft-bellis-dnsop-xpf <https://datatracker.ietf.org/doc/draft-bellis-dnsop-xpf/>`_.
1913 The server will trust XPF records found in queries sent from those netmasks (both IPv4 and IPv6),
1914 and will adjust queries' source and destination accordingly. This is especially useful when the recursor
1915 is placed behind a proxy like `dnsdist <https://dnsdist.org>`_.
1916 Note that the :ref:`setting-allow-from` setting is still applied to the original source address, and thus access restriction
1917 should be done on the proxy.
1919 .. _setting-xpf-rr-code:
1923 .. versionadded:: 4.2.0
1929 This is an experimental implementation of `draft-bellis-dnsop-xpf <https://datatracker.ietf.org/doc/draft-bellis-dnsop-xpf/>`_.
1931 This option sets the resource record code to use for XPF records, as long as an official code has not been assigned to it.
1932 0 means that XPF is disabled.