]>
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 | |
84 | ||
85 | - Boolean | |
86 | - Default: no | |
87 | ||
88 | Disallow data modification through the REST API when set. | |
89 | ||
90 | .. _setting-api-logfile: | |
91 | ||
92 | ``api-logfile`` | |
93 | --------------- | |
94 | .. versionadded:: 4.0.0 | |
95 | ||
96 | - Path | |
97 | - Default: unset | |
98 | ||
99 | Location of the server logfile (used by the REST API). | |
100 | ||
101 | .. _setting-auth-can-lower-ttl: | |
102 | ||
103 | ``auth-can-lower-ttl`` | |
104 | ---------------------- | |
105 | - Boolean | |
106 | - Default: no | |
107 | ||
108 | Authoritative zones can transmit a TTL value that is lower than that specified in the parent zone. | |
109 | This is called a 'delegation inconsistency'. | |
110 | 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. | |
111 | This will mean a slight deterioration of performance, and it will not solve any problems, but does make the recursor more standards compliant. | |
112 | Not recommended unless you have to tick an 'RFC 2181 compliant' box. | |
113 | ||
114 | .. _setting-auth-zones: | |
115 | ||
116 | ``auth-zones`` | |
117 | -------------- | |
118 | - Comma separated list of 'zonename=filename' pairs | |
119 | ||
120 | Zones read from these files (in BIND format) are served authoritatively. | |
121 | DNSSEC is not supported. Example: | |
122 | ||
123 | .. code-block:: none | |
124 | ||
125 | auth-zones=example.org=/var/zones/example.org, powerdns.com=/var/zones/powerdns.com | |
126 | ||
127 | .. _setting-carbon-interval: | |
128 | ||
129 | ``carbon-interval`` | |
130 | ------------------- | |
131 | - Integer | |
132 | - Default: 30 | |
133 | ||
134 | If sending carbon updates, this is the interval between them in seconds. | |
135 | See :doc:`metrics`. | |
136 | ||
137 | .. _setting-carbon-ourname: | |
138 | ||
139 | ``carbon-ourname`` | |
140 | ------------------ | |
141 | - String | |
142 | ||
143 | If sending carbon updates, if set, this will override our hostname. | |
144 | Be careful not to include any dots in this setting, unless you know what you are doing. | |
145 | See :ref:`metricscarbon`. | |
146 | ||
147 | .. _setting-carbon-server: | |
148 | ||
149 | ``carbon-server`` | |
150 | ----------------- | |
151 | - IP address | |
152 | ||
153 | 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. | |
154 | You may specify an alternate port by appending :port, for example: ``127.0.0.1:2004``. | |
155 | See :doc:`metrics`. | |
156 | ||
157 | .. _setting-chroot: | |
158 | ||
159 | ``chroot`` | |
160 | ---------- | |
161 | - Path to a Directory | |
162 | ||
163 | If set, chroot to this directory for more security. | |
164 | See :doc:`security` | |
165 | ||
166 | Make sure that ``/dev/log`` is available from within the chroot. | |
167 | Logging will silently fail over time otherwise (on logrotate). | |
168 | ||
169 | When using ``chroot``, all other paths (except for `config-dir`_) set in the configuration are relative to the new root. | |
170 | ||
171 | When using ``chroot`` and the API (`webserver`_), `api-readonly`_ **must** be set and `api-config-dir`_ unset. | |
172 | ||
173 | When running on a system where systemd manages services, ``chroot`` does not work out of the box, as PowerDNS cannot use the ``NOTIFY_SOCKET``. | |
174 | 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). | |
175 | ||
176 | .. _setting-client-tcp-timeout: | |
177 | ||
178 | ``client-tcp-timeout`` | |
179 | ---------------------- | |
180 | - Integer | |
181 | - Default: 2 | |
182 | ||
183 | Time to wait for data from TCP clients. | |
184 | ||
185 | .. _setting-config-dir: | |
186 | ||
187 | ``config-dir`` | |
188 | -------------- | |
189 | - Path | |
190 | ||
191 | Location of configuration directory (``recursor.conf``). | |
192 | Usually ``/etc/powerdns``, but this depends on ``SYSCONFDIR`` during compile-time. | |
193 | ||
194 | .. _setting-config-name: | |
195 | ||
196 | ``config-name`` | |
197 | --------------- | |
198 | - String | |
199 | - Default: unset | |
200 | ||
201 | When running multiple recursors on the same server, read settings from :file:`recursor-{name}.conf`, this will also rename the binary image. | |
202 | ||
48333784 PL |
203 | .. _setting-cpu-map: |
204 | ||
205 | ``cpu-map`` | |
206 | ----------- | |
207 | .. versionadded:: 4.1.0 | |
208 | ||
209 | - String | |
210 | - Default: unset | |
211 | ||
212 | Set CPU affinity for worker threads, asking the scheduler to run those threads on a single CPU, or a set of CPUs. | |
213 | This parameter accepts a space separated list of thread-id=cpu-id, or thread-id=cpu-id-1,cpu-id-2,...,cpu-id-N. | |
214 | For example, to make the worker thread 0 run on CPU id 0 and the worker thread 1 on CPUs 1 and 2:: | |
215 | ||
216 | cpu-map=0=0 1=1,2 | |
217 | ||
218 | The number of worker threads is determined by the :ref:`setting-threads` setting. | |
219 | If :ref:`setting-pdns-distributes-queries` is set, an additional thread is started, assigned the id 0, | |
220 | and is the only one listening on client sockets and accepting queries, distributing them to the other worker threads afterwards. | |
221 | ||
222 | This parameter is only available on OS that provides the `pthread_setaffinity_np()` function. | |
223 | ||
223bb49e PL |
224 | .. _setting-daemon: |
225 | ||
226 | ``daemon`` | |
227 | ---------- | |
228 | - Boolean | |
229 | - Default: no | |
230 | ||
231 | .. versionchanged:: 4.0.0 | |
232 | ||
233 | Default is now "no", was "yes" before. | |
234 | ||
235 | Operate in the background. | |
236 | ||
237 | .. _setting-delegation-only: | |
238 | ||
239 | ``delegation-only`` | |
240 | ------------------- | |
241 | - Domains, comma separated | |
242 | ||
243 | Which domains we only accept delegations from (a Verisign special). | |
244 | ||
245 | .. _setting-disable-packetcache: | |
246 | ||
247 | ``disable-packetcache`` | |
248 | ----------------------- | |
249 | - Boolean | |
250 | - Default: no | |
251 | ||
252 | Turn off the packet cache. Useful when running with Lua scripts that can | |
253 | not be cached. | |
254 | ||
255 | .. _setting-disable-syslog: | |
256 | ||
257 | ``disable-syslog`` | |
258 | ------------------ | |
259 | - Boolean | |
260 | - Default: no | |
261 | ||
262 | Do not log to syslog, only to stdout. | |
263 | Use this setting when running inside a supervisor that handles logging (like systemd). | |
264 | **Note**: do not use this setting in combination with `daemon`_ as all logging will disappear. | |
265 | ||
266 | .. _setting-dnssec: | |
267 | ||
268 | ``dnssec`` | |
269 | ---------- | |
270 | .. versionadded:: 4.0.0 | |
271 | ||
272 | - One of ``off``, ``process-no-validate``, ``process``, ``log-fail``, ``validate``, String | |
273 | - Default: ``process-no-validate`` | |
274 | ||
275 | Set the mode for DNSSEC processing: | |
276 | ||
277 | off | |
278 | ^^^ | |
279 | No DNSSEC processing whatsoever. | |
280 | Ignore DO-bits in queries, don't request any DNSSEC information from authoritative servers. | |
281 | This behaviour is similar to PowerDNS Recursor pre-4.0. | |
282 | ||
283 | process-no-validate | |
284 | ^^^^^^^^^^^^^^^^^^^ | |
285 | Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries. | |
286 | Don't do any validation. | |
287 | ||
288 | process | |
289 | ^^^^^^^ | |
290 | Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries. | |
291 | Do validation for clients that request it (by means of the AD- bit or DO-bit in the query). | |
292 | ||
293 | log-fail | |
294 | ^^^^^^^^ | |
295 | Similar behaviour to ``process``, but validate RRSIGs on responses and log bogus responses. | |
296 | ||
297 | validate | |
298 | ^^^^^^^^ | |
299 | Full blown DNSSEC validation. Send SERVFAIL to clients on bogus responses. | |
300 | ||
301 | .. _setting-dnssec-log-bogus: | |
302 | ||
303 | ``dnssec-log-bogus`` | |
304 | -------------------- | |
305 | - Boolean | |
306 | - Default: no | |
307 | ||
308 | Log every DNSSEC validation failure. | |
309 | **Note**: This is not logged per-query but every time records are validated as Bogus. | |
310 | ||
311 | .. _setting-dont-query: | |
312 | ||
313 | ``dont-query`` | |
314 | -------------- | |
315 | - Netmasks, comma separated | |
316 | - 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 | |
317 | ||
318 | The DNS is a public database, but sometimes contains delegations to private IP addresses, like for example 127.0.0.1. | |
319 | This can have odd effects, depending on your network, and may even be a security risk. | |
320 | Therefore, the PowerDNS Recursor by default does not query private space IP addresses. | |
321 | This setting can be used to expand or reduce the limitations. | |
322 | ||
323 | 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. | |
324 | ||
325 | .. _setting-ecs-ipv4-bits: | |
326 | ||
327 | ``ecs-ipv4-bits`` | |
328 | ----------------- | |
329 | .. versionadded:: 4.1.0 | |
330 | ||
331 | - Integer | |
332 | - Default: 24 | |
333 | ||
334 | Number of bits of client IPv4 address to pass when sending EDNS Client Subnet address information. | |
335 | ||
336 | .. _setting-ecs-ipv6-bits: | |
337 | ||
338 | ``ecs-ipv6-bits`` | |
339 | ----------------- | |
340 | .. versionadded:: 4.1.0 | |
341 | ||
342 | - Integer | |
343 | - Default: 56 | |
344 | ||
345 | Number of bits of client IPv6 address to pass when sending EDNS Client Subnet address information. | |
346 | ||
8a3a3822 RG |
347 | .. _setting-ecs-scope-zero-address: |
348 | ||
349 | ``ecs-scope-zero-address`` | |
350 | -------------------------- | |
351 | .. versionadded:: 4.1.0 | |
352 | ||
353 | - IPv4 or IPv6 Address | |
354 | - Default: empty | |
355 | ||
356 | The IP address sent via EDNS Client Subnet to authoritative servers listed in | |
a5607c95 | 357 | `edns-subnet-whitelist`_ when `use-incoming-edns-subnet`_ is set and the query has |
8a3a3822 | 358 | an ECS source prefix-length set to 0. |
a5607c95 | 359 | The default is to look for the first usable (not an ``any`` one) address in |
8a3a3822 RG |
360 | `query-local-address`_ then `query-local-address6`_. If no suitable address is |
361 | found, the recursor fallbacks to sending 127.0.0.1. | |
362 | ||
223bb49e PL |
363 | .. _setting-edns-outgoing-bufsize: |
364 | ||
365 | ``edns-outgoing-bufsize`` | |
366 | ------------------------- | |
367 | - Integer | |
368 | - Default: 1680 | |
369 | ||
370 | This is the value set for the EDNS0 buffer size in outgoing packets. | |
371 | Lower this if you experience timeouts. | |
372 | ||
373 | .. _setting-edns-subnet-whitelist: | |
374 | ||
375 | ``edns-subnet-whitelist`` | |
376 | ------------------------- | |
377 | - Comma separated list of domain names and netmasks | |
378 | - Default: (none) | |
379 | ||
380 | List of netmasks and domains that :rfc:`EDNS Client Subnet <7871>` should be enabled for in outgoing queries. | |
381 | For example, an EDNS Client Subnet option containing the address of the initial requestor 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. | |
382 | The initial requestor address will be truncated to 24 bits for IPv4 and to 56 bits for IPv6, as recommended in the privacy section of RFC 7871. | |
383 | By default, this option is empty, meaning no EDNS Client Subnet information is sent. | |
384 | ||
385 | .. _setting-entropy-source: | |
386 | ||
387 | ``entropy-source`` | |
388 | ------------------ | |
389 | - Path | |
390 | - Default: /dev/urandom | |
391 | ||
392 | PowerDNS can read entropy from a (hardware) source. | |
393 | This is used for generating random numbers which are very hard to predict. | |
394 | Generally on UNIX platforms, this source will be ``/dev/urandom``, which will always supply random numbers, even if entropy is lacking. | |
395 | Change to ``/dev/random`` if PowerDNS should block waiting for enough entropy to arrive. | |
396 | ||
397 | .. _setting-etc-hosts-file: | |
398 | ||
399 | ``etc-hosts-file`` | |
400 | ------------------ | |
401 | - Path | |
402 | - Default: /etc/hosts | |
403 | ||
404 | The path to the /etc/hosts file, or equivalent. | |
405 | This file can be used to serve data authoritatively using `export-etc-hosts`_. | |
406 | ||
407 | .. _setting-export-etc-hosts: | |
408 | ||
409 | ``export-etc-hosts`` | |
410 | -------------------- | |
411 | - Boolean | |
412 | - Default: no | |
413 | ||
414 | If set, this flag will export the host names and IP addresses mentioned in ``/etc/hosts``. | |
415 | ||
416 | .. _setting-export-etc-hosts-search-suffix: | |
417 | ||
418 | ``export-etc-hosts-search-suffix`` | |
419 | ---------------------------------- | |
420 | - String | |
421 | ||
422 | 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. | |
423 | 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. | |
424 | An entry called 'server1.home' will be stored as 'server1.home', regardless of this setting. | |
425 | ||
426 | .. _setting-forward-zones: | |
427 | ||
428 | ``forward-zones`` | |
429 | ----------------- | |
430 | - 'zonename=IP' pairs, comma separated | |
431 | ||
432 | Queries for zones listed here will be forwarded to the IP address listed. i.e. | |
433 | ||
434 | .. code-block:: none | |
435 | ||
436 | forward-zones=example.org=203.0.113.210, powerdns.com=2001:DB8::BEEF:5 | |
437 | ||
438 | Multiple IP addresses can be specified and port numbers other than 53 can be configured: | |
439 | ||
440 | .. code-block:: none | |
441 | ||
442 | 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 | |
443 | ||
444 | Forwarded queries have the 'recursion desired' bit set to 0, meaning that this setting is intended to forward queries to authoritative servers. | |
445 | ||
446 | **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. | |
447 | To prevent this, add a Negative Trust Anchor (NTA) for this zone in the `lua-config-file`_ with ``addNTA("your.zone", "A comment")``. | |
448 | If this forwarded zone is signed, instead of adding NTA, add the DS record to the `lua-config-file`_. | |
449 | See the :doc:`dnssec` information. | |
450 | ||
451 | .. _setting-forward-zones-file: | |
452 | ||
453 | ``forward-zones-file`` | |
454 | ---------------------- | |
455 | - Path | |
456 | ||
457 | Same as `forward-zones`_, parsed from a file. Only 1 zone is allowed per line, specified as follows: | |
458 | ||
459 | .. code-block:: none | |
460 | ||
461 | example.org=203.0.113.210, 192.0.2.4:5300 | |
462 | ||
463 | Zones prefixed with a '+' are forwarded with the recursion-desired bit set, for which see `forward-zones-recurse`_. | |
464 | Default behaviour without '+' is as with `forward-zones`_. | |
465 | ||
466 | .. versionchanged:: 4.0.0 | |
467 | ||
468 | Comments are allowed, everything behind '#' is ignored. | |
469 | ||
470 | The DNSSEC notes from `forward-zones`_ apply here as well. | |
471 | ||
472 | .. _setting-forward-zones-recurse: | |
473 | ||
474 | ``forward-zones-recurse`` | |
475 | ------------------------- | |
476 | - 'zonename=IP' pairs, comma separated | |
477 | ||
478 | 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. | |
479 | ||
480 | The DNSSEC notes from `forward-zones`_ apply here as well. | |
481 | ||
482 | .. _setting-gettag-needs-edns-options: | |
483 | ||
484 | ``gettag-needs-edns-options`` | |
485 | ----------------------------- | |
486 | .. versionadded:: 4.1.0 | |
487 | ||
488 | - Boolean | |
489 | - Default: no | |
490 | ||
491 | If set, EDNS options in incoming queries are extracted and passed to the :func:`gettag` hook in the ``ednsoptions`` table. | |
492 | ||
493 | .. _setting-hint-file: | |
494 | ||
495 | ``hint-file`` | |
496 | ------------- | |
497 | - Path | |
498 | ||
499 | If set, the root-hints are read from this file. If unset, default root hints are used. | |
500 | ||
501 | .. _setting-include-dir: | |
502 | ||
503 | ``include-dir`` | |
504 | --------------- | |
505 | - Path | |
506 | ||
507 | Directory to scan for additional config files. All files that end with .conf are loaded in order using ``POSIX`` as locale. | |
508 | ||
509 | .. _setting-latency-statistic-size: | |
510 | ||
511 | ``latency-statistic-size`` | |
512 | -------------------------- | |
513 | - Integer | |
514 | - Default: 10000 | |
515 | ||
516 | Indication of how many queries will be averaged to get the average latency reported by the 'qa-latency' metric. | |
517 | ||
518 | .. _setting-local-address: | |
519 | ||
520 | ``local-address`` | |
521 | ----------------- | |
522 | - IP addresses, comma separated | |
523 | - Default: 127.0.0.1 | |
524 | ||
525 | Local IPv4 or IPv6 addresses to bind to. | |
526 | Addresses can also contain port numbers, for IPv4 specify like this: ``192.0.2.4:5300``, for IPv6: ``[::1]:5300``. | |
527 | ||
528 | **Warning**: When binding to wildcard addresses, UNIX semantics mean that answers may not be sent from the address a query was received on. | |
529 | It is highly recommended to bind to explicit addresses. | |
530 | ||
531 | .. _setting-local-port: | |
532 | ||
533 | ``local-port`` | |
534 | -------------- | |
535 | - Integer | |
536 | - Default: 53 | |
537 | ||
538 | Local port to bind to. | |
539 | If an address in `local-address`_ does not have an explicit port, this port is used. | |
540 | ||
b18fa400 PL |
541 | .. _setting-log-timestamp: |
542 | ||
543 | ``log-timestamp`` | |
544 | ----------------- | |
545 | ||
546 | .. versionadded:: 4.1.0 | |
547 | ||
548 | - Bool | |
549 | - Default: yes | |
550 | ||
551 | When printing log lines to stdout, prefix them with timestamps. | |
552 | Disable this if the process supervisor timestamps these lines already. | |
553 | ||
554 | .. note:: | |
555 | The systemd unit file supplied with the source code already disables timestamp printing | |
556 | ||
223bb49e PL |
557 | .. _setting-non-local-bind: |
558 | ||
559 | ``non-local-bind`` | |
560 | ------------------ | |
561 | - Boolean | |
562 | - Default: no | |
563 | ||
564 | Bind to addresses even if one or more of the `local-address`_'s do not exist on this server. | |
565 | Setting this option will enable the needed socket options to allow binding to non-local addresses. | |
566 | 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. | |
567 | ||
568 | .. _setting-loglevel: | |
569 | ||
570 | ``loglevel`` | |
571 | ------------ | |
572 | - Integer between 0 and 9 | |
9afa8662 | 573 | - Default: 6 |
223bb49e PL |
574 | |
575 | Amount of logging. | |
576 | Higher is more, more logging may destroy performance. | |
577 | It is recommended not to set this below 3. | |
578 | ||
579 | .. _setting-log-common-errors: | |
580 | ||
581 | ``log-common-errors`` | |
582 | --------------------- | |
583 | - Boolean | |
584 | - Default: no | |
585 | ||
586 | Some DNS errors occur rather frequently and are no cause for alarm. | |
587 | ||
98d36505 RG |
588 | ``log-rpz-changes`` |
589 | --------------------- | |
590 | .. versionadded:: 4.1.0 | |
591 | ||
592 | - Boolean | |
593 | - Default: no | |
594 | ||
595 | Log additions and removals to RPZ zones at Info (6) level instead of Debug (7). | |
596 | ||
223bb49e PL |
597 | .. _setting-logging-facility: |
598 | ||
599 | ``logging-facility`` | |
600 | -------------------- | |
601 | - Integer | |
602 | ||
603 | If set to a digit, logging is performed under this LOCAL facility. | |
604 | See :ref:`logging`. | |
605 | Do not pass names like 'local0'! | |
606 | ||
607 | .. _setting-lowercase-outgoing: | |
608 | ||
609 | ``lowercase-outgoing`` | |
610 | ---------------------- | |
611 | - Boolean | |
612 | - Default: no | |
613 | ||
614 | Set to true to lowercase the outgoing queries. | |
615 | 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. | |
616 | Broken authoritative servers might give a wrong or broken answer on this encoding. | |
617 | 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. | |
618 | ||
619 | .. _setting-lua-config-file: | |
620 | ||
621 | ``lua-config-file`` | |
622 | ------------------- | |
623 | - Filename | |
624 | ||
625 | If set, and Lua support is compiled in, this will load an additional configuration file for newer features and more complicated setups. | |
626 | See :doc:`lua-config/index` for the options that can be set in this file. | |
627 | ||
628 | .. _setting-lua-dns-script: | |
629 | ||
630 | ``lua-dns-script`` | |
631 | ------------------ | |
632 | - Path | |
633 | - Default: unset | |
634 | ||
635 | Path to a lua file to manipulate the Recursor's answers. See :doc:`lua-scripting/index` for more information. | |
636 | ||
637 | .. _setting-max-cache-entries: | |
638 | ||
639 | ``max-cache-entries`` | |
640 | --------------------- | |
641 | - Integer | |
642 | - Default: 1000000 | |
643 | ||
644 | Maximum number of DNS cache entries. | |
645 | 1 million per thread will generally suffice for most installations. | |
646 | ||
647 | .. _setting-max-cache-ttl: | |
648 | ||
649 | ``max-cache-ttl`` | |
650 | ----------------- | |
651 | - Integer | |
652 | - Default: 86400 | |
653 | ||
654 | Maximum number of seconds to cache an item in the DNS cache, no matter what the original TTL specified. | |
655 | ||
656 | .. versionchanged:: 4.1.0 | |
657 | ||
658 | The minimum value of this setting is 15. i.e. setting this to lower than 15 will make this value 15. | |
659 | ||
660 | .. _setting-max-mthreads: | |
661 | ||
662 | ``max-mthreads`` | |
663 | ---------------- | |
664 | - Integer | |
665 | - Default: 2048 | |
666 | ||
667 | Maximum number of simultaneous MTasker threads. | |
668 | ||
669 | .. _setting-max-packetcache-entries: | |
670 | ||
671 | ``max-packetcache-entries`` | |
672 | --------------------------- | |
673 | - Integer | |
674 | - Default: 500000 | |
675 | ||
676 | Maximum number of Packet Cache entries. | |
677 | 1 million per thread will generally suffice for most installations. | |
678 | ||
679 | .. _setting-max-qperq: | |
680 | ||
681 | ``max-qperq`` | |
682 | ------------- | |
683 | - Integer | |
684 | - Default: 50 | |
685 | ||
686 | The maximum number of outgoing queries that will be sent out during the resolution of a single client query. | |
687 | This is used to limit endlessly chasing CNAME redirections. | |
688 | ||
689 | .. _setting-max-negative-ttl: | |
690 | ||
691 | ``max-negative-ttl`` | |
692 | -------------------- | |
693 | - Integer | |
694 | - Default: 3600 | |
695 | ||
696 | 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. | |
697 | In practice, caches can become saturated with hundreds of thousands of hosts which are tried only once. | |
698 | This setting, which defaults to 3600 seconds, puts a maximum on the amount of time negative entries are cached. | |
699 | ||
700 | .. _setting-max-recursion-depth: | |
701 | ||
702 | ``max-recursion-depth`` | |
703 | ----------------------- | |
704 | - Integer | |
705 | - Default: 40 | |
706 | ||
707 | Total maximum number of internal recursion calls the server may use to answer a single query. | |
708 | 0 means unlimited. | |
709 | The value of `stack-size`_ should be increased together with this one to prevent the stack from overflowing. | |
710 | ||
711 | .. versionchanged:: 4.1.0 | |
712 | ||
713 | Before 4.1.0, this settings was unlimited. | |
714 | ||
715 | .. _setting-max-tcp-clients: | |
716 | ||
717 | ``max-tcp-clients`` | |
718 | ------------------- | |
719 | - Integer | |
720 | - Default: 128 | |
721 | ||
722 | Maximum number of simultaneous incoming TCP connections allowed. | |
723 | ||
724 | .. _setting-max-tcp-per-client: | |
725 | ||
726 | ``max-tcp-per-client`` | |
727 | ---------------------- | |
728 | - Integer | |
729 | - Default: 0 (unlimited) | |
730 | ||
731 | Maximum number of simultaneous incoming TCP connections allowed per client (remote IP address). | |
732 | ||
733 | .. _setting-max-tcp-queries-per-connection: | |
734 | ||
735 | ``max-tcp-queries-per-connection`` | |
736 | ---------------------------------- | |
737 | .. versionadded:: 4.1.0 | |
738 | ||
739 | - Integer | |
740 | - Default: 0 (unlimited) | |
741 | ||
742 | Maximum number of DNS queries in a TCP connection. | |
743 | ||
744 | .. _setting-max-total-msec: | |
745 | ||
746 | ``max-total-msec`` | |
747 | ------------------ | |
748 | - Integer | |
749 | - Default: 7000 | |
750 | ||
751 | Total maximum number of milliseconds of wallclock time the server may use to answer a single query. | |
752 | ||
753 | .. _setting-minimum-ttl-override: | |
754 | ||
755 | ``minimum-ttl-override`` | |
756 | ------------------------ | |
757 | - Integer | |
758 | - Default: 0 (disabled) | |
759 | ||
760 | This setting artificially raises all TTLs to be at least this long. | |
761 | While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers. | |
762 | Can be set at runtime using ``rec_control set-minimum-ttl 3600``. | |
763 | ||
764 | .. _setting-network-timeout: | |
765 | ||
766 | ``network-timeout`` | |
767 | ------------------- | |
768 | - Integer | |
769 | - Default: 1500 | |
770 | ||
771 | Number of milliseconds to wait for a remote authoritative server to respond. | |
772 | ||
773 | .. _setting-nsec3-max-iterations: | |
774 | ||
775 | ``nsec3-max-iterations`` | |
776 | ------------------------ | |
777 | .. versionadded:: 4.1.0 | |
778 | ||
779 | - Integer | |
780 | - Default: 2500 | |
781 | ||
782 | Maximum number of iterations allowed for an NSEC3 record. | |
783 | If an answer containing an NSEC3 record with more iterations is received, its DNSSEC validation status is treated as Insecure. | |
784 | ||
785 | .. _setting-packetcache-ttl: | |
786 | ||
787 | ``packetcache-ttl`` | |
788 | ------------------- | |
789 | - Integer | |
790 | - Default: 3600 | |
791 | ||
792 | Maximum number of seconds to cache an item in the packet cache, no matter what the original TTL specified. | |
793 | ||
794 | .. _setting-packetcache-servfail-ttl: | |
795 | ||
796 | ``packetcache-servfail-ttl`` | |
797 | ---------------------------- | |
798 | - Integer | |
799 | - Default: 60 | |
800 | ||
801 | Maximum number of seconds to cache a 'server failure' answer in the packet cache. | |
802 | ||
803 | .. versionchanged:: 4.0.0 | |
804 | ||
805 | This setting's maximum is capped to `packetcache-ttl`_. | |
806 | i.e. setting ``packetcache-ttl=15`` and keeping ``packetcache-servfail-ttl`` at the default will lower ``packetcache-servfail-ttl`` to ``15``. | |
807 | ||
808 | .. _setting-pdns-distributes-queries: | |
809 | ||
810 | ``pdns-distributes-queries`` | |
811 | ---------------------------- | |
812 | - Boolean | |
813 | ||
814 | If set, PowerDNS will have only 1 thread listening on client sockets, and distribute work by itself over threads. | |
815 | Improves performance on Linux. | |
816 | ||
817 | .. _setting-query-local-address: | |
818 | ||
819 | ``query-local-address`` | |
820 | ----------------------- | |
821 | - IPv4 Address, comma separated | |
822 | - Default: 0.0.0.0 | |
823 | ||
824 | Send out local queries from this address, or addresses, by adding multiple addresses, increased spoofing resilience is achieved. | |
825 | ||
826 | .. _setting-query-local-address6: | |
827 | ||
828 | ``query-local-address6`` | |
829 | ------------------------ | |
830 | - IPv6 addresses, comma separated | |
831 | - Default: unset | |
832 | ||
833 | Send out local IPv6 queries from this address or addresses. | |
834 | Disabled by default, which also disables outgoing IPv6 support. | |
835 | ||
836 | .. _setting-quiet: | |
837 | ||
838 | ``quiet`` | |
839 | --------- | |
840 | - Boolean | |
841 | - Default: yes | |
842 | ||
843 | Don't log queries. | |
844 | ||
845 | .. _setting-reuseport: | |
846 | ||
847 | ``reuseport`` | |
848 | ------------- | |
849 | - Boolean | |
850 | - Default: no | |
851 | ||
852 | If ``SO_REUSEPORT`` support is available, allows multiple processes to open a listening socket on the same port. | |
853 | ||
854 | 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. | |
855 | ||
856 | .. _setting-root-nx-trust: | |
857 | ||
858 | ``root-nx-trust`` | |
859 | ----------------- | |
860 | - Boolean | |
861 | - Default: yes | |
862 | ||
863 | If set, an NXDOMAIN from the root-servers will serve as a blanket NXDOMAIN for the entire TLD the query belonged to. | |
864 | The effect of this is far fewer queries to the root-servers. | |
865 | ||
866 | .. versionchanged:: 4.0.0 | |
867 | ||
868 | Default is 'yes' now, was 'no' before 4.0.0 | |
869 | ||
870 | .. _setting-security-poll-suffix: | |
871 | ||
872 | ``security-poll-suffix`` | |
873 | ------------------------ | |
874 | - String | |
875 | - Default: secpoll.powerdns.com. | |
876 | ||
877 | Domain name from which to query security update notifications. | |
878 | Setting this to an empty string disables secpoll. | |
879 | ||
880 | .. _setting-serve-rfc1918: | |
881 | ||
882 | ``serve-rfc1918`` | |
883 | ----------------- | |
884 | - Boolean | |
885 | - Default: yes | |
886 | ||
887 | 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. | |
888 | Individual parts of these zones can still be loaded or forwarded. | |
889 | ||
890 | .. _setting-server-down-max-fails: | |
891 | ||
892 | ``server-down-max-fails`` | |
893 | ------------------------- | |
894 | - Integer | |
895 | - Default: 64 | |
896 | ||
897 | 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. | |
898 | 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. | |
899 | Even a single response packet will drop the block. | |
900 | ||
901 | .. _setting-server-down-throttle-time: | |
902 | ||
903 | ``server-down-throttle-time`` | |
904 | ----------------------------- | |
905 | - Integer | |
906 | - Default: 60 | |
907 | ||
908 | Throttle a server that has failed to respond `server-down-max-fails`_ times for this many seconds. | |
909 | ||
910 | .. _setting-server-id: | |
911 | ||
912 | ``server-id`` | |
913 | ------------- | |
914 | - String | |
915 | - Default: The hostname of the server | |
916 | ||
917 | The PowerDNS recursor by replies to a query for 'id.server' with its hostname, useful for in clusters. | |
918 | Use this setting to override the answer it gives. | |
919 | ||
920 | Query example (where 192.0.2.14 is your server): | |
921 | ||
922 | .. code-block:: sh | |
923 | ||
924 | dig @192.0.2.14 CHAOS TXT id.server. | |
925 | ||
926 | ``setgid``, ``setuid`` | |
927 | ---------------------- | |
928 | - String | |
929 | - Default: unset | |
930 | ||
931 | PowerDNS can change its user and group id after binding to its socket. | |
932 | Can be used for better :doc:`security <security>`. | |
933 | ||
934 | .. _setting-single-socket: | |
935 | ||
936 | ``single-socket`` | |
937 | ----------------- | |
938 | - Boolean | |
939 | - Default: no | |
940 | ||
941 | Use only a single socket for outgoing queries. | |
942 | ||
943 | .. _setting-snmp-agent: | |
944 | ||
945 | ``snmp-agent`` | |
946 | -------------- | |
947 | .. versionadded:: 4.1.0 | |
948 | ||
949 | - Boolean | |
950 | - Default: no | |
951 | ||
952 | 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. | |
953 | ||
954 | .. _setting-snmp-master-socket: | |
955 | ||
956 | ``snmp-master-socket`` | |
957 | ---------------------- | |
958 | .. versionadded:: 4.1.0 | |
959 | ||
960 | - String | |
961 | - Default: empty | |
962 | ||
963 | If not empty and ``snmp-agent`` is set to true, indicates how PowerDNS should contact the SNMP master to register as an SNMP agent. | |
964 | ||
965 | .. _setting-socket-dir: | |
966 | ||
967 | ``socket-dir`` | |
968 | -------------- | |
969 | - Path | |
970 | ||
971 | Where to store the control socket and pidfile. | |
972 | The default depends on ``LOCALSTATEDIR`` during compile-time (usually ``/var/run`` or ``/run``). | |
973 | ||
974 | When using `chroot`_ the default becomes to ``/``. | |
975 | ||
976 | ``socket-owner``, ``socket-group``, ``socket-mode`` | |
977 | --------------------------------------------------- | |
978 | Owner, group and mode of the controlsocket. | |
979 | Owner and group can be specified by name, mode is in octal. | |
980 | ||
981 | .. _setting-spoof-nearmiss-max: | |
982 | ||
983 | ``spoof-nearmiss-max`` | |
984 | ---------------------- | |
985 | - Integer | |
986 | - Default: 20 | |
987 | ||
988 | If set to non-zero, PowerDNS will assume it is being spoofed after seeing this many answers with the wrong id. | |
989 | ||
990 | .. _setting-stack-size: | |
991 | ||
992 | ``stack-size`` | |
993 | -------------- | |
994 | - Integer | |
995 | - Default: 200000 | |
996 | ||
997 | Size of the stack per thread. | |
998 | ||
999 | .. _setting-statistics-interval: | |
1000 | ||
1001 | ``statistics-interval`` | |
1002 | ----------------------- | |
1003 | .. versionadded:: 4.1.0 | |
1004 | ||
1005 | - Integer | |
1006 | - Default: 1800 | |
1007 | ||
1008 | Interval between logging statistical summary on recursor performance. | |
1009 | Use 0 to disable. | |
1010 | ||
1011 | .. _setting-stats-ringbuffer-entries: | |
1012 | ||
1013 | ``stats-ringbuffer-entries`` | |
1014 | ---------------------------- | |
1015 | - Integer | |
1016 | - Default: 10000 | |
1017 | ||
1018 | Number of entries in the remotes ringbuffer, which keeps statistics on who is querying your server. | |
1019 | Can be read out using ``rec_control top-remotes``. | |
1020 | ||
1021 | .. _setting-tcp-fast-open: | |
1022 | ||
1023 | ``tcp-fast-open`` | |
1024 | ----------------- | |
1025 | .. versionadded:: 4.1.0 | |
1026 | ||
1027 | - Integer | |
1028 | - Default: 0 (Disabled) | |
1029 | ||
1030 | Enable TCP Fast Open support, if available, on the listening sockets. | |
1031 | The numerical value supplied is used as the queue size, 0 meaning disabled. | |
1032 | ||
1033 | .. _setting-threads: | |
1034 | ||
1035 | ``threads`` | |
1036 | ----------- | |
1037 | - Integer | |
1038 | - Default: 2 | |
1039 | ||
1040 | Spawn this number of threads on startup. | |
1041 | ||
1042 | .. _setting-trace: | |
1043 | ||
1044 | ``trace`` | |
1045 | --------- | |
1046 | - Boolean | |
1047 | - Default: no | |
1048 | ||
1049 | If turned on, output impressive heaps of logging. | |
1050 | May destroy performance under load. | |
1051 | ||
1052 | .. _setting-udp-truncation-threshold: | |
1053 | ||
1054 | ``udp-truncation-threshold`` | |
1055 | ---------------------------- | |
1056 | - Integer | |
1057 | - Default: 1680 | |
1058 | ||
1059 | EDNS0 allows for large UDP response datagrams, which can potentially raise performance. | |
1060 | Large responses however also have downsides in terms of reflection attacks. | |
1061 | This setting limits the accepted size. | |
1062 | Maximum value is 65535, but values above 4096 should probably not be attempted. | |
1063 | ||
1064 | .. _setting-use-incoming-edns-subnet: | |
1065 | ||
1066 | ``use-incoming-edns-subnet`` | |
1067 | ---------------------------- | |
1068 | - Boolean | |
1069 | - Default: no | |
1070 | ||
1071 | Whether to process and pass along a received EDNS Client Subnet to authoritative servers. | |
1072 | 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. | |
1073 | ||
1074 | .. _setting-version: | |
1075 | ||
1076 | ``version`` | |
1077 | ----------- | |
1078 | Print version of this binary. Useful for checking which version of the PowerDNS recursor is installed on a system. | |
1079 | ||
1080 | .. _setting-version-string: | |
1081 | ||
1082 | ``version-string`` | |
1083 | ------------------ | |
1084 | - String | |
1085 | - Default: PowerDNS Recursor version number | |
1086 | ||
1087 | By default, PowerDNS replies to the 'version.bind' query with its version number. | |
1088 | Security conscious users may wish to override the reply PowerDNS issues. | |
1089 | ||
1090 | .. _setting-webserver: | |
1091 | ||
1092 | ``webserver`` | |
1093 | ------------- | |
1094 | - Boolean | |
1095 | - Default: no | |
1096 | ||
1097 | Start the webserver (for REST API). | |
1098 | ||
1099 | .. _setting-webserver-address: | |
1100 | ||
1101 | ``webserver-address`` | |
1102 | --------------------- | |
4f66776f | 1103 | - IP Address |
223bb49e PL |
1104 | - Default: 127.0.0.1 |
1105 | ||
1106 | IP address for the webserver to listen on. | |
1107 | ||
1108 | .. _setting-webserver-allow-from: | |
1109 | ||
1110 | ``webserver-allow-from`` | |
1111 | ------------------------ | |
1112 | - IP addresses, comma separated | |
be3e1477 RG |
1113 | - Default: 127.0.0.1,::1 |
1114 | ||
1115 | .. versionchanged:: 4.1.0 | |
1116 | ||
1117 | Default is now 127.0.0.1,::1, was 0.0.0.0,::/0 before. | |
223bb49e PL |
1118 | |
1119 | These subnets are allowed to access the webserver. | |
1120 | ||
1121 | .. _setting-webserver-password: | |
1122 | ||
1123 | ``webserver-password`` | |
1124 | ---------------------- | |
1125 | - String | |
1126 | - Default: unset | |
1127 | ||
1128 | Password required to access the webserver. | |
1129 | ||
1130 | .. _setting-webserver-port: | |
1131 | ||
1132 | ``webserver-port`` | |
1133 | ------------------ | |
1134 | - Integer | |
1135 | - Default: 8082 | |
1136 | ||
1137 | TCP port where the webserver should listen on. | |
1138 | ||
1139 | .. _setting-write-pid: | |
1140 | ||
1141 | ``write-pid`` | |
1142 | ------------- | |
1143 | - Boolean | |
1144 | - Default: yes | |
1145 | ||
1146 | If a PID file should be written to `socket-dir`_ |