]>
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 | ||
2fe3354d CH |
325 | .. _setting-ecs-add-for: |
326 | ||
327 | ``ecs-add-for`` | |
328 | -------------------------- | |
329 | .. versionadded:: 4.2.0 | |
330 | ||
331 | - Comma separated list of netmasks | |
332 | - 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 | |
333 | ||
9f421b03 | 334 | 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 |
335 | Valid incoming ECS values from `use-incoming-edns-subnet`_ are not replaced. |
336 | ||
9f421b03 CH |
337 | 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. |
338 | ||
2fe3354d CH |
339 | This defaults to not using the requestor address inside RFC1918 and similar "private" IP address spaces. |
340 | ||
223bb49e PL |
341 | .. _setting-ecs-ipv4-bits: |
342 | ||
343 | ``ecs-ipv4-bits`` | |
344 | ----------------- | |
345 | .. versionadded:: 4.1.0 | |
346 | ||
347 | - Integer | |
348 | - Default: 24 | |
349 | ||
350 | Number of bits of client IPv4 address to pass when sending EDNS Client Subnet address information. | |
351 | ||
352 | .. _setting-ecs-ipv6-bits: | |
353 | ||
354 | ``ecs-ipv6-bits`` | |
355 | ----------------- | |
356 | .. versionadded:: 4.1.0 | |
357 | ||
358 | - Integer | |
359 | - Default: 56 | |
360 | ||
361 | Number of bits of client IPv6 address to pass when sending EDNS Client Subnet address information. | |
362 | ||
8a3a3822 RG |
363 | .. _setting-ecs-scope-zero-address: |
364 | ||
365 | ``ecs-scope-zero-address`` | |
366 | -------------------------- | |
367 | .. versionadded:: 4.1.0 | |
368 | ||
369 | - IPv4 or IPv6 Address | |
370 | - Default: empty | |
371 | ||
372 | The IP address sent via EDNS Client Subnet to authoritative servers listed in | |
a5607c95 | 373 | `edns-subnet-whitelist`_ when `use-incoming-edns-subnet`_ is set and the query has |
8a3a3822 | 374 | an ECS source prefix-length set to 0. |
a5607c95 | 375 | The default is to look for the first usable (not an ``any`` one) address in |
8a3a3822 RG |
376 | `query-local-address`_ then `query-local-address6`_. If no suitable address is |
377 | found, the recursor fallbacks to sending 127.0.0.1. | |
378 | ||
223bb49e PL |
379 | .. _setting-edns-outgoing-bufsize: |
380 | ||
381 | ``edns-outgoing-bufsize`` | |
382 | ------------------------- | |
383 | - Integer | |
384 | - Default: 1680 | |
385 | ||
386 | This is the value set for the EDNS0 buffer size in outgoing packets. | |
387 | Lower this if you experience timeouts. | |
388 | ||
389 | .. _setting-edns-subnet-whitelist: | |
390 | ||
391 | ``edns-subnet-whitelist`` | |
392 | ------------------------- | |
393 | - Comma separated list of domain names and netmasks | |
394 | - Default: (none) | |
395 | ||
396 | List of netmasks and domains that :rfc:`EDNS Client Subnet <7871>` should be enabled for in outgoing queries. | |
2fe3354d CH |
397 | |
398 | 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. | |
399 | 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. | |
400 | ||
223bb49e PL |
401 | By default, this option is empty, meaning no EDNS Client Subnet information is sent. |
402 | ||
403 | .. _setting-entropy-source: | |
404 | ||
405 | ``entropy-source`` | |
406 | ------------------ | |
407 | - Path | |
408 | - Default: /dev/urandom | |
409 | ||
410 | PowerDNS can read entropy from a (hardware) source. | |
411 | This is used for generating random numbers which are very hard to predict. | |
412 | Generally on UNIX platforms, this source will be ``/dev/urandom``, which will always supply random numbers, even if entropy is lacking. | |
413 | Change to ``/dev/random`` if PowerDNS should block waiting for enough entropy to arrive. | |
414 | ||
415 | .. _setting-etc-hosts-file: | |
416 | ||
417 | ``etc-hosts-file`` | |
418 | ------------------ | |
419 | - Path | |
420 | - Default: /etc/hosts | |
421 | ||
422 | The path to the /etc/hosts file, or equivalent. | |
423 | This file can be used to serve data authoritatively using `export-etc-hosts`_. | |
424 | ||
425 | .. _setting-export-etc-hosts: | |
426 | ||
427 | ``export-etc-hosts`` | |
428 | -------------------- | |
429 | - Boolean | |
430 | - Default: no | |
431 | ||
432 | If set, this flag will export the host names and IP addresses mentioned in ``/etc/hosts``. | |
433 | ||
434 | .. _setting-export-etc-hosts-search-suffix: | |
435 | ||
436 | ``export-etc-hosts-search-suffix`` | |
437 | ---------------------------------- | |
438 | - String | |
439 | ||
440 | 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. | |
441 | 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. | |
442 | An entry called 'server1.home' will be stored as 'server1.home', regardless of this setting. | |
443 | ||
444 | .. _setting-forward-zones: | |
445 | ||
446 | ``forward-zones`` | |
447 | ----------------- | |
448 | - 'zonename=IP' pairs, comma separated | |
449 | ||
450 | Queries for zones listed here will be forwarded to the IP address listed. i.e. | |
451 | ||
452 | .. code-block:: none | |
453 | ||
454 | forward-zones=example.org=203.0.113.210, powerdns.com=2001:DB8::BEEF:5 | |
455 | ||
456 | Multiple IP addresses can be specified and port numbers other than 53 can be configured: | |
457 | ||
458 | .. code-block:: none | |
459 | ||
460 | 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 | |
461 | ||
462 | Forwarded queries have the 'recursion desired' bit set to 0, meaning that this setting is intended to forward queries to authoritative servers. | |
463 | ||
464 | **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. | |
465 | To prevent this, add a Negative Trust Anchor (NTA) for this zone in the `lua-config-file`_ with ``addNTA("your.zone", "A comment")``. | |
466 | If this forwarded zone is signed, instead of adding NTA, add the DS record to the `lua-config-file`_. | |
467 | See the :doc:`dnssec` information. | |
468 | ||
469 | .. _setting-forward-zones-file: | |
470 | ||
471 | ``forward-zones-file`` | |
472 | ---------------------- | |
473 | - Path | |
474 | ||
475 | Same as `forward-zones`_, parsed from a file. Only 1 zone is allowed per line, specified as follows: | |
476 | ||
477 | .. code-block:: none | |
478 | ||
479 | example.org=203.0.113.210, 192.0.2.4:5300 | |
480 | ||
481 | Zones prefixed with a '+' are forwarded with the recursion-desired bit set, for which see `forward-zones-recurse`_. | |
482 | Default behaviour without '+' is as with `forward-zones`_. | |
483 | ||
484 | .. versionchanged:: 4.0.0 | |
485 | ||
486 | Comments are allowed, everything behind '#' is ignored. | |
487 | ||
488 | The DNSSEC notes from `forward-zones`_ apply here as well. | |
489 | ||
490 | .. _setting-forward-zones-recurse: | |
491 | ||
492 | ``forward-zones-recurse`` | |
493 | ------------------------- | |
494 | - 'zonename=IP' pairs, comma separated | |
495 | ||
496 | 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. | |
497 | ||
498 | The DNSSEC notes from `forward-zones`_ apply here as well. | |
499 | ||
500 | .. _setting-gettag-needs-edns-options: | |
501 | ||
502 | ``gettag-needs-edns-options`` | |
503 | ----------------------------- | |
504 | .. versionadded:: 4.1.0 | |
505 | ||
506 | - Boolean | |
507 | - Default: no | |
508 | ||
509 | If set, EDNS options in incoming queries are extracted and passed to the :func:`gettag` hook in the ``ednsoptions`` table. | |
510 | ||
511 | .. _setting-hint-file: | |
512 | ||
513 | ``hint-file`` | |
514 | ------------- | |
515 | - Path | |
516 | ||
517 | If set, the root-hints are read from this file. If unset, default root hints are used. | |
518 | ||
519 | .. _setting-include-dir: | |
520 | ||
521 | ``include-dir`` | |
522 | --------------- | |
523 | - Path | |
524 | ||
525 | Directory to scan for additional config files. All files that end with .conf are loaded in order using ``POSIX`` as locale. | |
526 | ||
527 | .. _setting-latency-statistic-size: | |
528 | ||
529 | ``latency-statistic-size`` | |
530 | -------------------------- | |
531 | - Integer | |
532 | - Default: 10000 | |
533 | ||
534 | Indication of how many queries will be averaged to get the average latency reported by the 'qa-latency' metric. | |
535 | ||
536 | .. _setting-local-address: | |
537 | ||
538 | ``local-address`` | |
539 | ----------------- | |
540 | - IP addresses, comma separated | |
541 | - Default: 127.0.0.1 | |
542 | ||
543 | Local IPv4 or IPv6 addresses to bind to. | |
544 | Addresses can also contain port numbers, for IPv4 specify like this: ``192.0.2.4:5300``, for IPv6: ``[::1]:5300``. | |
545 | ||
546 | **Warning**: When binding to wildcard addresses, UNIX semantics mean that answers may not be sent from the address a query was received on. | |
547 | It is highly recommended to bind to explicit addresses. | |
548 | ||
549 | .. _setting-local-port: | |
550 | ||
551 | ``local-port`` | |
552 | -------------- | |
553 | - Integer | |
554 | - Default: 53 | |
555 | ||
556 | Local port to bind to. | |
557 | If an address in `local-address`_ does not have an explicit port, this port is used. | |
558 | ||
b18fa400 PL |
559 | .. _setting-log-timestamp: |
560 | ||
561 | ``log-timestamp`` | |
562 | ----------------- | |
563 | ||
564 | .. versionadded:: 4.1.0 | |
565 | ||
566 | - Bool | |
567 | - Default: yes | |
568 | ||
569 | When printing log lines to stdout, prefix them with timestamps. | |
570 | Disable this if the process supervisor timestamps these lines already. | |
571 | ||
572 | .. note:: | |
573 | The systemd unit file supplied with the source code already disables timestamp printing | |
574 | ||
223bb49e PL |
575 | .. _setting-non-local-bind: |
576 | ||
577 | ``non-local-bind`` | |
578 | ------------------ | |
579 | - Boolean | |
580 | - Default: no | |
581 | ||
582 | Bind to addresses even if one or more of the `local-address`_'s do not exist on this server. | |
583 | Setting this option will enable the needed socket options to allow binding to non-local addresses. | |
584 | 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. | |
585 | ||
586 | .. _setting-loglevel: | |
587 | ||
588 | ``loglevel`` | |
589 | ------------ | |
590 | - Integer between 0 and 9 | |
9afa8662 | 591 | - Default: 6 |
223bb49e PL |
592 | |
593 | Amount of logging. | |
594 | Higher is more, more logging may destroy performance. | |
595 | It is recommended not to set this below 3. | |
596 | ||
597 | .. _setting-log-common-errors: | |
598 | ||
599 | ``log-common-errors`` | |
600 | --------------------- | |
601 | - Boolean | |
602 | - Default: no | |
603 | ||
604 | Some DNS errors occur rather frequently and are no cause for alarm. | |
605 | ||
98d36505 RG |
606 | ``log-rpz-changes`` |
607 | --------------------- | |
608 | .. versionadded:: 4.1.0 | |
609 | ||
610 | - Boolean | |
611 | - Default: no | |
612 | ||
613 | Log additions and removals to RPZ zones at Info (6) level instead of Debug (7). | |
614 | ||
223bb49e PL |
615 | .. _setting-logging-facility: |
616 | ||
617 | ``logging-facility`` | |
618 | -------------------- | |
619 | - Integer | |
620 | ||
621 | If set to a digit, logging is performed under this LOCAL facility. | |
622 | See :ref:`logging`. | |
623 | Do not pass names like 'local0'! | |
624 | ||
625 | .. _setting-lowercase-outgoing: | |
626 | ||
627 | ``lowercase-outgoing`` | |
628 | ---------------------- | |
629 | - Boolean | |
630 | - Default: no | |
631 | ||
632 | Set to true to lowercase the outgoing queries. | |
633 | 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. | |
634 | Broken authoritative servers might give a wrong or broken answer on this encoding. | |
635 | 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. | |
636 | ||
637 | .. _setting-lua-config-file: | |
638 | ||
639 | ``lua-config-file`` | |
640 | ------------------- | |
641 | - Filename | |
642 | ||
643 | If set, and Lua support is compiled in, this will load an additional configuration file for newer features and more complicated setups. | |
644 | See :doc:`lua-config/index` for the options that can be set in this file. | |
645 | ||
646 | .. _setting-lua-dns-script: | |
647 | ||
648 | ``lua-dns-script`` | |
649 | ------------------ | |
650 | - Path | |
651 | - Default: unset | |
652 | ||
653 | Path to a lua file to manipulate the Recursor's answers. See :doc:`lua-scripting/index` for more information. | |
654 | ||
655 | .. _setting-max-cache-entries: | |
656 | ||
657 | ``max-cache-entries`` | |
658 | --------------------- | |
659 | - Integer | |
660 | - Default: 1000000 | |
661 | ||
662 | Maximum number of DNS cache entries. | |
663 | 1 million per thread will generally suffice for most installations. | |
664 | ||
665 | .. _setting-max-cache-ttl: | |
666 | ||
667 | ``max-cache-ttl`` | |
668 | ----------------- | |
669 | - Integer | |
670 | - Default: 86400 | |
671 | ||
672 | Maximum number of seconds to cache an item in the DNS cache, no matter what the original TTL specified. | |
673 | ||
674 | .. versionchanged:: 4.1.0 | |
675 | ||
676 | The minimum value of this setting is 15. i.e. setting this to lower than 15 will make this value 15. | |
677 | ||
678 | .. _setting-max-mthreads: | |
679 | ||
680 | ``max-mthreads`` | |
681 | ---------------- | |
682 | - Integer | |
683 | - Default: 2048 | |
684 | ||
685 | Maximum number of simultaneous MTasker threads. | |
686 | ||
687 | .. _setting-max-packetcache-entries: | |
688 | ||
689 | ``max-packetcache-entries`` | |
690 | --------------------------- | |
691 | - Integer | |
692 | - Default: 500000 | |
693 | ||
694 | Maximum number of Packet Cache entries. | |
695 | 1 million per thread will generally suffice for most installations. | |
696 | ||
697 | .. _setting-max-qperq: | |
698 | ||
699 | ``max-qperq`` | |
700 | ------------- | |
701 | - Integer | |
702 | - Default: 50 | |
703 | ||
704 | The maximum number of outgoing queries that will be sent out during the resolution of a single client query. | |
705 | This is used to limit endlessly chasing CNAME redirections. | |
706 | ||
707 | .. _setting-max-negative-ttl: | |
708 | ||
709 | ``max-negative-ttl`` | |
710 | -------------------- | |
711 | - Integer | |
712 | - Default: 3600 | |
713 | ||
714 | 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. | |
715 | In practice, caches can become saturated with hundreds of thousands of hosts which are tried only once. | |
716 | This setting, which defaults to 3600 seconds, puts a maximum on the amount of time negative entries are cached. | |
717 | ||
718 | .. _setting-max-recursion-depth: | |
719 | ||
720 | ``max-recursion-depth`` | |
721 | ----------------------- | |
722 | - Integer | |
723 | - Default: 40 | |
724 | ||
725 | Total maximum number of internal recursion calls the server may use to answer a single query. | |
726 | 0 means unlimited. | |
727 | The value of `stack-size`_ should be increased together with this one to prevent the stack from overflowing. | |
728 | ||
729 | .. versionchanged:: 4.1.0 | |
730 | ||
731 | Before 4.1.0, this settings was unlimited. | |
732 | ||
733 | .. _setting-max-tcp-clients: | |
734 | ||
735 | ``max-tcp-clients`` | |
736 | ------------------- | |
737 | - Integer | |
738 | - Default: 128 | |
739 | ||
740 | Maximum number of simultaneous incoming TCP connections allowed. | |
741 | ||
742 | .. _setting-max-tcp-per-client: | |
743 | ||
744 | ``max-tcp-per-client`` | |
745 | ---------------------- | |
746 | - Integer | |
747 | - Default: 0 (unlimited) | |
748 | ||
749 | Maximum number of simultaneous incoming TCP connections allowed per client (remote IP address). | |
750 | ||
751 | .. _setting-max-tcp-queries-per-connection: | |
752 | ||
753 | ``max-tcp-queries-per-connection`` | |
754 | ---------------------------------- | |
755 | .. versionadded:: 4.1.0 | |
756 | ||
757 | - Integer | |
758 | - Default: 0 (unlimited) | |
759 | ||
760 | Maximum number of DNS queries in a TCP connection. | |
761 | ||
762 | .. _setting-max-total-msec: | |
763 | ||
764 | ``max-total-msec`` | |
765 | ------------------ | |
766 | - Integer | |
767 | - Default: 7000 | |
768 | ||
769 | Total maximum number of milliseconds of wallclock time the server may use to answer a single query. | |
770 | ||
771 | .. _setting-minimum-ttl-override: | |
772 | ||
773 | ``minimum-ttl-override`` | |
774 | ------------------------ | |
775 | - Integer | |
776 | - Default: 0 (disabled) | |
777 | ||
778 | This setting artificially raises all TTLs to be at least this long. | |
779 | While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers. | |
780 | Can be set at runtime using ``rec_control set-minimum-ttl 3600``. | |
781 | ||
782 | .. _setting-network-timeout: | |
783 | ||
784 | ``network-timeout`` | |
785 | ------------------- | |
786 | - Integer | |
787 | - Default: 1500 | |
788 | ||
789 | Number of milliseconds to wait for a remote authoritative server to respond. | |
790 | ||
791 | .. _setting-nsec3-max-iterations: | |
792 | ||
793 | ``nsec3-max-iterations`` | |
794 | ------------------------ | |
795 | .. versionadded:: 4.1.0 | |
796 | ||
797 | - Integer | |
798 | - Default: 2500 | |
799 | ||
800 | Maximum number of iterations allowed for an NSEC3 record. | |
801 | If an answer containing an NSEC3 record with more iterations is received, its DNSSEC validation status is treated as Insecure. | |
802 | ||
803 | .. _setting-packetcache-ttl: | |
804 | ||
805 | ``packetcache-ttl`` | |
806 | ------------------- | |
807 | - Integer | |
808 | - Default: 3600 | |
809 | ||
810 | Maximum number of seconds to cache an item in the packet cache, no matter what the original TTL specified. | |
811 | ||
812 | .. _setting-packetcache-servfail-ttl: | |
813 | ||
814 | ``packetcache-servfail-ttl`` | |
815 | ---------------------------- | |
816 | - Integer | |
817 | - Default: 60 | |
818 | ||
819 | Maximum number of seconds to cache a 'server failure' answer in the packet cache. | |
820 | ||
821 | .. versionchanged:: 4.0.0 | |
822 | ||
823 | This setting's maximum is capped to `packetcache-ttl`_. | |
824 | i.e. setting ``packetcache-ttl=15`` and keeping ``packetcache-servfail-ttl`` at the default will lower ``packetcache-servfail-ttl`` to ``15``. | |
825 | ||
826 | .. _setting-pdns-distributes-queries: | |
827 | ||
828 | ``pdns-distributes-queries`` | |
829 | ---------------------------- | |
830 | - Boolean | |
831 | ||
832 | If set, PowerDNS will have only 1 thread listening on client sockets, and distribute work by itself over threads. | |
833 | Improves performance on Linux. | |
834 | ||
835 | .. _setting-query-local-address: | |
836 | ||
837 | ``query-local-address`` | |
838 | ----------------------- | |
839 | - IPv4 Address, comma separated | |
840 | - Default: 0.0.0.0 | |
841 | ||
842 | Send out local queries from this address, or addresses, by adding multiple addresses, increased spoofing resilience is achieved. | |
843 | ||
844 | .. _setting-query-local-address6: | |
845 | ||
846 | ``query-local-address6`` | |
847 | ------------------------ | |
848 | - IPv6 addresses, comma separated | |
849 | - Default: unset | |
850 | ||
851 | Send out local IPv6 queries from this address or addresses. | |
852 | Disabled by default, which also disables outgoing IPv6 support. | |
853 | ||
854 | .. _setting-quiet: | |
855 | ||
856 | ``quiet`` | |
857 | --------- | |
858 | - Boolean | |
859 | - Default: yes | |
860 | ||
861 | Don't log queries. | |
862 | ||
863 | .. _setting-reuseport: | |
864 | ||
865 | ``reuseport`` | |
866 | ------------- | |
867 | - Boolean | |
868 | - Default: no | |
869 | ||
870 | If ``SO_REUSEPORT`` support is available, allows multiple processes to open a listening socket on the same port. | |
871 | ||
872 | 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. | |
873 | ||
874 | .. _setting-root-nx-trust: | |
875 | ||
876 | ``root-nx-trust`` | |
877 | ----------------- | |
878 | - Boolean | |
879 | - Default: yes | |
880 | ||
881 | If set, an NXDOMAIN from the root-servers will serve as a blanket NXDOMAIN for the entire TLD the query belonged to. | |
882 | The effect of this is far fewer queries to the root-servers. | |
883 | ||
884 | .. versionchanged:: 4.0.0 | |
885 | ||
886 | Default is 'yes' now, was 'no' before 4.0.0 | |
887 | ||
888 | .. _setting-security-poll-suffix: | |
889 | ||
890 | ``security-poll-suffix`` | |
891 | ------------------------ | |
892 | - String | |
893 | - Default: secpoll.powerdns.com. | |
894 | ||
895 | Domain name from which to query security update notifications. | |
896 | Setting this to an empty string disables secpoll. | |
897 | ||
898 | .. _setting-serve-rfc1918: | |
899 | ||
900 | ``serve-rfc1918`` | |
901 | ----------------- | |
902 | - Boolean | |
903 | - Default: yes | |
904 | ||
905 | 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. | |
906 | Individual parts of these zones can still be loaded or forwarded. | |
907 | ||
908 | .. _setting-server-down-max-fails: | |
909 | ||
910 | ``server-down-max-fails`` | |
911 | ------------------------- | |
912 | - Integer | |
913 | - Default: 64 | |
914 | ||
915 | 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. | |
916 | 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. | |
917 | Even a single response packet will drop the block. | |
918 | ||
919 | .. _setting-server-down-throttle-time: | |
920 | ||
921 | ``server-down-throttle-time`` | |
922 | ----------------------------- | |
923 | - Integer | |
924 | - Default: 60 | |
925 | ||
926 | Throttle a server that has failed to respond `server-down-max-fails`_ times for this many seconds. | |
927 | ||
928 | .. _setting-server-id: | |
929 | ||
930 | ``server-id`` | |
931 | ------------- | |
932 | - String | |
933 | - Default: The hostname of the server | |
934 | ||
935 | The PowerDNS recursor by replies to a query for 'id.server' with its hostname, useful for in clusters. | |
936 | Use this setting to override the answer it gives. | |
937 | ||
938 | Query example (where 192.0.2.14 is your server): | |
939 | ||
940 | .. code-block:: sh | |
941 | ||
942 | dig @192.0.2.14 CHAOS TXT id.server. | |
943 | ||
944 | ``setgid``, ``setuid`` | |
945 | ---------------------- | |
946 | - String | |
947 | - Default: unset | |
948 | ||
949 | PowerDNS can change its user and group id after binding to its socket. | |
950 | Can be used for better :doc:`security <security>`. | |
951 | ||
952 | .. _setting-single-socket: | |
953 | ||
954 | ``single-socket`` | |
955 | ----------------- | |
956 | - Boolean | |
957 | - Default: no | |
958 | ||
959 | Use only a single socket for outgoing queries. | |
960 | ||
961 | .. _setting-snmp-agent: | |
962 | ||
963 | ``snmp-agent`` | |
964 | -------------- | |
965 | .. versionadded:: 4.1.0 | |
966 | ||
967 | - Boolean | |
968 | - Default: no | |
969 | ||
970 | 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. | |
971 | ||
972 | .. _setting-snmp-master-socket: | |
973 | ||
974 | ``snmp-master-socket`` | |
975 | ---------------------- | |
976 | .. versionadded:: 4.1.0 | |
977 | ||
978 | - String | |
979 | - Default: empty | |
980 | ||
981 | If not empty and ``snmp-agent`` is set to true, indicates how PowerDNS should contact the SNMP master to register as an SNMP agent. | |
982 | ||
983 | .. _setting-socket-dir: | |
984 | ||
985 | ``socket-dir`` | |
986 | -------------- | |
987 | - Path | |
988 | ||
989 | Where to store the control socket and pidfile. | |
990 | The default depends on ``LOCALSTATEDIR`` during compile-time (usually ``/var/run`` or ``/run``). | |
991 | ||
992 | When using `chroot`_ the default becomes to ``/``. | |
993 | ||
994 | ``socket-owner``, ``socket-group``, ``socket-mode`` | |
995 | --------------------------------------------------- | |
996 | Owner, group and mode of the controlsocket. | |
997 | Owner and group can be specified by name, mode is in octal. | |
998 | ||
999 | .. _setting-spoof-nearmiss-max: | |
1000 | ||
1001 | ``spoof-nearmiss-max`` | |
1002 | ---------------------- | |
1003 | - Integer | |
1004 | - Default: 20 | |
1005 | ||
1006 | If set to non-zero, PowerDNS will assume it is being spoofed after seeing this many answers with the wrong id. | |
1007 | ||
1008 | .. _setting-stack-size: | |
1009 | ||
1010 | ``stack-size`` | |
1011 | -------------- | |
1012 | - Integer | |
1013 | - Default: 200000 | |
1014 | ||
1015 | Size of the stack per thread. | |
1016 | ||
1017 | .. _setting-statistics-interval: | |
1018 | ||
1019 | ``statistics-interval`` | |
1020 | ----------------------- | |
1021 | .. versionadded:: 4.1.0 | |
1022 | ||
1023 | - Integer | |
1024 | - Default: 1800 | |
1025 | ||
1026 | Interval between logging statistical summary on recursor performance. | |
1027 | Use 0 to disable. | |
1028 | ||
1029 | .. _setting-stats-ringbuffer-entries: | |
1030 | ||
1031 | ``stats-ringbuffer-entries`` | |
1032 | ---------------------------- | |
1033 | - Integer | |
1034 | - Default: 10000 | |
1035 | ||
1036 | Number of entries in the remotes ringbuffer, which keeps statistics on who is querying your server. | |
1037 | Can be read out using ``rec_control top-remotes``. | |
1038 | ||
1039 | .. _setting-tcp-fast-open: | |
1040 | ||
1041 | ``tcp-fast-open`` | |
1042 | ----------------- | |
1043 | .. versionadded:: 4.1.0 | |
1044 | ||
1045 | - Integer | |
1046 | - Default: 0 (Disabled) | |
1047 | ||
1048 | Enable TCP Fast Open support, if available, on the listening sockets. | |
1049 | The numerical value supplied is used as the queue size, 0 meaning disabled. | |
1050 | ||
1051 | .. _setting-threads: | |
1052 | ||
1053 | ``threads`` | |
1054 | ----------- | |
1055 | - Integer | |
1056 | - Default: 2 | |
1057 | ||
1058 | Spawn this number of threads on startup. | |
1059 | ||
1060 | .. _setting-trace: | |
1061 | ||
1062 | ``trace`` | |
1063 | --------- | |
1064 | - Boolean | |
1065 | - Default: no | |
1066 | ||
1067 | If turned on, output impressive heaps of logging. | |
1068 | May destroy performance under load. | |
1069 | ||
1070 | .. _setting-udp-truncation-threshold: | |
1071 | ||
1072 | ``udp-truncation-threshold`` | |
1073 | ---------------------------- | |
1074 | - Integer | |
1075 | - Default: 1680 | |
1076 | ||
1077 | EDNS0 allows for large UDP response datagrams, which can potentially raise performance. | |
1078 | Large responses however also have downsides in terms of reflection attacks. | |
1079 | This setting limits the accepted size. | |
1080 | Maximum value is 65535, but values above 4096 should probably not be attempted. | |
1081 | ||
1082 | .. _setting-use-incoming-edns-subnet: | |
1083 | ||
1084 | ``use-incoming-edns-subnet`` | |
1085 | ---------------------------- | |
1086 | - Boolean | |
1087 | - Default: no | |
1088 | ||
1089 | Whether to process and pass along a received EDNS Client Subnet to authoritative servers. | |
1090 | 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. | |
1091 | ||
1092 | .. _setting-version: | |
1093 | ||
1094 | ``version`` | |
1095 | ----------- | |
1096 | Print version of this binary. Useful for checking which version of the PowerDNS recursor is installed on a system. | |
1097 | ||
1098 | .. _setting-version-string: | |
1099 | ||
1100 | ``version-string`` | |
1101 | ------------------ | |
1102 | - String | |
1103 | - Default: PowerDNS Recursor version number | |
1104 | ||
1105 | By default, PowerDNS replies to the 'version.bind' query with its version number. | |
1106 | Security conscious users may wish to override the reply PowerDNS issues. | |
1107 | ||
1108 | .. _setting-webserver: | |
1109 | ||
1110 | ``webserver`` | |
1111 | ------------- | |
1112 | - Boolean | |
1113 | - Default: no | |
1114 | ||
1115 | Start the webserver (for REST API). | |
1116 | ||
1117 | .. _setting-webserver-address: | |
1118 | ||
1119 | ``webserver-address`` | |
1120 | --------------------- | |
4f66776f | 1121 | - IP Address |
223bb49e PL |
1122 | - Default: 127.0.0.1 |
1123 | ||
1124 | IP address for the webserver to listen on. | |
1125 | ||
1126 | .. _setting-webserver-allow-from: | |
1127 | ||
1128 | ``webserver-allow-from`` | |
1129 | ------------------------ | |
1130 | - IP addresses, comma separated | |
be3e1477 RG |
1131 | - Default: 127.0.0.1,::1 |
1132 | ||
1133 | .. versionchanged:: 4.1.0 | |
1134 | ||
1135 | Default is now 127.0.0.1,::1, was 0.0.0.0,::/0 before. | |
223bb49e PL |
1136 | |
1137 | These subnets are allowed to access the webserver. | |
1138 | ||
1139 | .. _setting-webserver-password: | |
1140 | ||
1141 | ``webserver-password`` | |
1142 | ---------------------- | |
1143 | - String | |
1144 | - Default: unset | |
1145 | ||
1146 | Password required to access the webserver. | |
1147 | ||
1148 | .. _setting-webserver-port: | |
1149 | ||
1150 | ``webserver-port`` | |
1151 | ------------------ | |
1152 | - Integer | |
1153 | - Default: 8082 | |
1154 | ||
1155 | TCP port where the webserver should listen on. | |
1156 | ||
1157 | .. _setting-write-pid: | |
1158 | ||
1159 | ``write-pid`` | |
1160 | ------------- | |
1161 | - Boolean | |
1162 | - Default: yes | |
1163 | ||
1164 | If a PID file should be written to `socket-dir`_ | |
5cc8371b RG |
1165 | |
1166 | ``xpf-allow-from`` | |
1167 | ------------- | |
1168 | .. versionadded:: 4.1.0 | |
1169 | ||
1170 | - IP ranges, separated by commas | |
1171 | - Default: empty | |
1172 | ||
1173 | This is an experimental implementation of `draft-bellis-dnsop-xpf`. | |
1174 | The server will trust XPF records found in queries sent from those netmasks (both IPv4 and IPv6), | |
1175 | and will adjust queries' source and destination accordingly. This is especially useful when the recursor | |
1176 | is placed behind a proxy like dnsdist. | |
1177 | Note that the `allow-from`_ setting is still applied to the original source address, and thus access restriction | |
1178 | should be done on the proxy. | |
18f707fa RG |
1179 | |
1180 | ``xpf-option-code`` | |
1181 | ------------- | |
1182 | .. versionadded:: 4.1.0 | |
1183 | ||
1184 | - Integer | |
1185 | - Default: 0 | |
1186 | ||
1187 | This is an experimental implementation of `draft-bellis-dnsop-xpf`. | |
1188 | The option code to use for XPF records, as long as an official code has not been assigned to it. 0 means disabled. |