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