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