]>
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 | ||
223bb49e PL |
15 | .. _setting-allow-from: |
16 | ||
17 | ``allow-from`` | |
18 | -------------- | |
19 | - IP ranges, separated by commas | |
20 | - Default: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 | |
21 | ||
22 | Netmasks (both IPv4 and IPv6) that are allowed to use the server. | |
23 | The default allows access only from :rfc:`1918` private IP addresses. | |
24 | Due to the aggressive nature of the internet these days, it is highly recommended to not open up the recursor for the entire internet. | |
25 | Questions from IP addresses not listed here are ignored and do not get an answer. | |
26 | ||
ea201fc1 RG |
27 | When the Proxy Protocol is enabled (see `proxy-protocol-from`_), the recursor will check the address of the client IP advertised in the Proxy Protocol header instead of the one of the proxy. |
28 | ||
223bb49e PL |
29 | .. _setting-allow-from-file: |
30 | ||
31 | ``allow-from-file`` | |
32 | ------------------- | |
33 | - Path | |
34 | ||
35 | Like `allow-from`_, except reading from file. | |
36 | Overrides the `allow-from`_ setting. To use this feature, supply one netmask per line, with optional comments preceded by a "#". | |
37 | ||
38 | .. _setting-any-to-tcp: | |
39 | ||
40 | ``any-to-tcp`` | |
41 | -------------- | |
42 | - Boolean | |
43 | - Default: no | |
44 | ||
45 | Answer questions for the ANY type on UDP with a truncated packet that refers the remote server to TCP. | |
46 | Useful for mitigating ANY reflection attacks. | |
47 | ||
c1d92d73 PL |
48 | .. _setting-allow-trust-anchor-query: |
49 | ||
50 | ``allow-trust-anchor-query`` | |
51 | ---------------------------- | |
a8208151 | 52 | .. versionadded:: 4.3.0 |
c1d92d73 PL |
53 | |
54 | - Boolean | |
a8208151 | 55 | - Default: no |
c1d92d73 | 56 | |
0b7de4d7 | 57 | Allow ``trustanchor.server CH TXT`` and ``negativetrustanchor.server CH TXT`` queries to view the configured :doc:`DNSSEC <dnssec>` (negative) trust anchors. |
c1d92d73 | 58 | |
223bb49e PL |
59 | .. _setting-api-config-dir: |
60 | ||
61 | ``api-config-dir`` | |
62 | ------------------ | |
63 | .. versionadded:: 4.0.0 | |
64 | ||
65 | - Path | |
66 | - Default: unset | |
67 | ||
68 | Directory where the REST API stores its configuration and zones. | |
69 | ||
70 | .. _setting-api-key: | |
71 | ||
72 | ``api-key`` | |
73 | ----------- | |
74 | .. versionadded:: 4.0.0 | |
75 | ||
76 | - String | |
77 | - Default: unset | |
78 | ||
79 | Static pre-shared authentication key for access to the REST API. | |
80 | ||
81 | .. _setting-api-readonly: | |
82 | ||
83 | ``api-readonly`` | |
84 | ---------------- | |
e1483a72 CH |
85 | .. versionchanged:: 4.2.0 |
86 | This setting has been removed. | |
223bb49e PL |
87 | |
88 | - Boolean | |
89 | - Default: no | |
90 | ||
91 | Disallow data modification through the REST API when set. | |
92 | ||
93 | .. _setting-api-logfile: | |
94 | ||
95 | ``api-logfile`` | |
96 | --------------- | |
b49b4f2f PD |
97 | .. versionchanged:: 4.2.0 |
98 | This setting has been removed. | |
223bb49e PL |
99 | |
100 | - Path | |
101 | - Default: unset | |
102 | ||
103 | Location of the server logfile (used by the REST API). | |
104 | ||
105 | .. _setting-auth-can-lower-ttl: | |
106 | ||
107 | ``auth-can-lower-ttl`` | |
108 | ---------------------- | |
109 | - Boolean | |
110 | - Default: no | |
111 | ||
112 | Authoritative zones can transmit a TTL value that is lower than that specified in the parent zone. | |
113 | This is called a 'delegation inconsistency'. | |
114 | To follow :rfc:`RFC 2181 section 5.2<2181#section-5.2>` and :rfc:`5.4 <2181#section-5.4>` to the letter, enable this feature. | |
115 | This will mean a slight deterioration of performance, and it will not solve any problems, but does make the recursor more standards compliant. | |
116 | Not recommended unless you have to tick an 'RFC 2181 compliant' box. | |
117 | ||
118 | .. _setting-auth-zones: | |
119 | ||
120 | ``auth-zones`` | |
121 | -------------- | |
122 | - Comma separated list of 'zonename=filename' pairs | |
123 | ||
124 | Zones read from these files (in BIND format) are served authoritatively. | |
125 | DNSSEC is not supported. Example: | |
126 | ||
127 | .. code-block:: none | |
128 | ||
129 | auth-zones=example.org=/var/zones/example.org, powerdns.com=/var/zones/powerdns.com | |
130 | ||
131 | .. _setting-carbon-interval: | |
132 | ||
133 | ``carbon-interval`` | |
134 | ------------------- | |
135 | - Integer | |
136 | - Default: 30 | |
137 | ||
138 | If sending carbon updates, this is the interval between them in seconds. | |
139 | See :doc:`metrics`. | |
140 | ||
b0d4aa0b G |
141 | .. _setting-carbon-namespace: |
142 | ||
143 | ``carbon-namespace`` | |
144 | -------------------- | |
7dd919af G |
145 | .. versionadded:: 4.2.0 |
146 | ||
b0d4aa0b G |
147 | - String |
148 | ||
149 | Change the namespace or first string of the metric key. The default is pdns. | |
150 | ||
223bb49e PL |
151 | .. _setting-carbon-ourname: |
152 | ||
153 | ``carbon-ourname`` | |
154 | ------------------ | |
155 | - String | |
156 | ||
157 | If sending carbon updates, if set, this will override our hostname. | |
158 | Be careful not to include any dots in this setting, unless you know what you are doing. | |
159 | See :ref:`metricscarbon`. | |
160 | ||
b0d4aa0b G |
161 | .. _setting-carbon-instance: |
162 | ||
163 | ``carbon-instance`` | |
164 | -------------------- | |
7dd919af G |
165 | .. versionadded:: 4.2.0 |
166 | ||
b0d4aa0b G |
167 | - String |
168 | ||
169 | Change the instance or third string of the metric key. The default is recursor. | |
170 | ||
223bb49e PL |
171 | .. _setting-carbon-server: |
172 | ||
173 | ``carbon-server`` | |
174 | ----------------- | |
175 | - IP address | |
176 | ||
fd47d762 | 177 | If set to an IP or IPv6 address, will send all available metrics to this server via the carbon protocol, which is used by graphite and metronome. Moreover you can specify more than one server using a comma delimited list, ex: carbon-server=10.10.10.10,10.10.10.20. |
223bb49e PL |
178 | You may specify an alternate port by appending :port, for example: ``127.0.0.1:2004``. |
179 | See :doc:`metrics`. | |
180 | ||
181 | .. _setting-chroot: | |
182 | ||
183 | ``chroot`` | |
184 | ---------- | |
185 | - Path to a Directory | |
186 | ||
187 | If set, chroot to this directory for more security. | |
188 | See :doc:`security` | |
189 | ||
190 | Make sure that ``/dev/log`` is available from within the chroot. | |
191 | Logging will silently fail over time otherwise (on logrotate). | |
192 | ||
193 | When using ``chroot``, all other paths (except for `config-dir`_) set in the configuration are relative to the new root. | |
194 | ||
195 | When using ``chroot`` and the API (`webserver`_), `api-readonly`_ **must** be set and `api-config-dir`_ unset. | |
196 | ||
197 | When running on a system where systemd manages services, ``chroot`` does not work out of the box, as PowerDNS cannot use the ``NOTIFY_SOCKET``. | |
198 | Either do not ``chroot`` on these systems or set the 'Type' of this service to 'simple' instead of 'notify' (refer to the systemd documentation on how to modify unit-files). | |
199 | ||
200 | .. _setting-client-tcp-timeout: | |
201 | ||
202 | ``client-tcp-timeout`` | |
203 | ---------------------- | |
204 | - Integer | |
205 | - Default: 2 | |
206 | ||
207 | Time to wait for data from TCP clients. | |
208 | ||
209 | .. _setting-config-dir: | |
210 | ||
211 | ``config-dir`` | |
212 | -------------- | |
213 | - Path | |
214 | ||
215 | Location of configuration directory (``recursor.conf``). | |
216 | Usually ``/etc/powerdns``, but this depends on ``SYSCONFDIR`` during compile-time. | |
217 | ||
218 | .. _setting-config-name: | |
219 | ||
220 | ``config-name`` | |
221 | --------------- | |
222 | - String | |
223 | - Default: unset | |
224 | ||
225 | When running multiple recursors on the same server, read settings from :file:`recursor-{name}.conf`, this will also rename the binary image. | |
226 | ||
48333784 PL |
227 | .. _setting-cpu-map: |
228 | ||
229 | ``cpu-map`` | |
230 | ----------- | |
231 | .. versionadded:: 4.1.0 | |
232 | ||
233 | - String | |
234 | - Default: unset | |
235 | ||
236 | Set CPU affinity for worker threads, asking the scheduler to run those threads on a single CPU, or a set of CPUs. | |
237 | This parameter accepts a space separated list of thread-id=cpu-id, or thread-id=cpu-id-1,cpu-id-2,...,cpu-id-N. | |
238 | For example, to make the worker thread 0 run on CPU id 0 and the worker thread 1 on CPUs 1 and 2:: | |
239 | ||
240 | cpu-map=0=0 1=1,2 | |
241 | ||
242 | The number of worker threads is determined by the :ref:`setting-threads` setting. | |
243 | If :ref:`setting-pdns-distributes-queries` is set, an additional thread is started, assigned the id 0, | |
244 | and is the only one listening on client sockets and accepting queries, distributing them to the other worker threads afterwards. | |
245 | ||
b243ca3b RG |
246 | Starting with version 4.2.0, the thread handling the control channel, the webserver and other internal stuff has been assigned |
247 | id 0 and more than one distributor thread can be started using the :ref:`setting-distributor-threads` setting, so the distributor | |
248 | threads if any are assigned id 1 and counting, and the other threads follow behind. | |
249 | ||
48333784 PL |
250 | This parameter is only available on OS that provides the `pthread_setaffinity_np()` function. |
251 | ||
223bb49e PL |
252 | .. _setting-daemon: |
253 | ||
254 | ``daemon`` | |
255 | ---------- | |
256 | - Boolean | |
257 | - Default: no | |
258 | ||
259 | .. versionchanged:: 4.0.0 | |
260 | ||
261 | Default is now "no", was "yes" before. | |
262 | ||
263 | Operate in the background. | |
264 | ||
265 | .. _setting-delegation-only: | |
266 | ||
267 | ``delegation-only`` | |
268 | ------------------- | |
269 | - Domains, comma separated | |
270 | ||
271 | Which domains we only accept delegations from (a Verisign special). | |
272 | ||
559b6c93 PL |
273 | .. _setting-dont-throttle-names: |
274 | ||
275 | ``dont-throttle-names`` | |
276 | ---------------------------- | |
277 | .. versionadded:: 4.2.0 | |
278 | ||
279 | - Comma separated list of domain-names | |
280 | - Default: (empty) | |
281 | ||
74bf380c | 282 | When an authoritative server does not answer a query or sends a reply the recursor does not like, it is throttled. |
559b6c93 PL |
283 | Any servers' name suffix-matching the supplied names will never be throttled. |
284 | ||
285 | .. warning:: | |
b907c813 | 286 | Most servers on the internet do not respond for a good reason (overloaded or unreachable), ``dont-throttle-names`` could make this load on the upstream server even higher, resulting in further service degradation. |
559b6c93 PL |
287 | |
288 | .. _setting-dont-throttle-netmasks: | |
289 | ||
290 | ``dont-throttle-netmasks`` | |
291 | ---------------------------- | |
292 | .. versionadded:: 4.2.0 | |
293 | ||
294 | - Comma separated list of netmasks | |
295 | - Default: (empty) | |
296 | ||
5e13f0b6 | 297 | When an authoritative server does not answer a query or sends a reply the recursor does not like, it is throttled. |
559b6c93 PL |
298 | Any servers matching the supplied netmasks will never be throttled. |
299 | ||
300 | This can come in handy on lossy networks when forwarding, where the same server is configured multiple times (e.g. with ``forward-zones-recurse=example.com=192.0.2.1;192.0.2.1``). | |
301 | By default, the PowerDNS Recursor would throttle the "first" server on a timeout and hence not retry the "second" one. | |
302 | In this case, ``dont-throttle-netmasks`` could be set to ``192.0.2.1``. | |
303 | ||
304 | .. warning:: | |
74b2d7e0 | 305 | Most servers on the internet do not respond for a good reason (overloaded or unreachable), ``dont-throttle-netmasks`` could make this load on the upstream server even higher, resulting in further service degradation. |
559b6c93 | 306 | |
223bb49e PL |
307 | .. _setting-disable-packetcache: |
308 | ||
309 | ``disable-packetcache`` | |
310 | ----------------------- | |
311 | - Boolean | |
312 | - Default: no | |
313 | ||
314 | Turn off the packet cache. Useful when running with Lua scripts that can | |
315 | not be cached. | |
316 | ||
317 | .. _setting-disable-syslog: | |
318 | ||
319 | ``disable-syslog`` | |
320 | ------------------ | |
321 | - Boolean | |
322 | - Default: no | |
323 | ||
324 | Do not log to syslog, only to stdout. | |
325 | Use this setting when running inside a supervisor that handles logging (like systemd). | |
326 | **Note**: do not use this setting in combination with `daemon`_ as all logging will disappear. | |
327 | ||
144040be RG |
328 | .. _setting-distribution-load-factor: |
329 | ||
330 | ``distribution-load-factor`` | |
331 | ---------------------------- | |
332 | .. versionadded:: 4.1.12 | |
333 | ||
334 | - Double | |
335 | - Default: 0.0 | |
336 | ||
337 | If `pdns-distributes-queries`_ is set and this setting is set to another value | |
338 | than 0, the distributor thread will use a bounded load-balancing algorithm while | |
339 | distributing queries to worker threads, making sure that no thread is assigned | |
340 | more queries than distribution-load-factor times the average number of queries | |
341 | currently processed by all the workers. | |
342 | For example, with a value of 1.25, no server should get more than 125 % of the | |
343 | average load. This helps making sure that all the workers have roughly the same | |
344 | share of queries, even if the incoming traffic is very skewed, with a larger | |
345 | number of requests asking for the same qname. | |
346 | ||
ee271fc4 RG |
347 | .. _setting-distribution-pipe-buffer-size: |
348 | ||
349 | ``distribution-pipe-buffer-size`` | |
350 | --------------------------------- | |
351 | .. versionadded:: 4.2.0 | |
352 | ||
353 | - Integer | |
354 | - Default: 0 | |
355 | ||
356 | Size in bytes of the internal buffer of the pipe used by the distributor to pass incoming queries to a worker thread. | |
357 | Requires support for `F_SETPIPE_SZ` which is present in Linux since 2.6.35. The actual size might be rounded up to | |
358 | a multiple of a page size. 0 means that the OS default size is used. | |
359 | A large buffer might allow the recursor to deal with very short-lived load spikes during which a worker thread gets | |
360 | overloaded, but it will be at the cost of an increased latency. | |
361 | ||
b243ca3b RG |
362 | .. _setting-distributor-threads: |
363 | ||
364 | ``distributor-threads`` | |
c8dbb9f7 | 365 | ----------------------- |
b243ca3b RG |
366 | .. versionadded:: 4.2.0 |
367 | ||
368 | - Integer | |
369 | - Default: 1 if `pdns-distributes-queries`_ is set, 0 otherwise | |
370 | ||
371 | If `pdns-distributes-queries`_ is set, spawn this number of distributor threads on startup. Distributor threads | |
372 | handle incoming queries and distribute them to other threads based on a hash of the query, to maximize the cache hit | |
373 | ratio. | |
374 | ||
223bb49e PL |
375 | .. _setting-dnssec: |
376 | ||
377 | ``dnssec`` | |
378 | ---------- | |
379 | .. versionadded:: 4.0.0 | |
380 | ||
381 | - One of ``off``, ``process-no-validate``, ``process``, ``log-fail``, ``validate``, String | |
382 | - Default: ``process-no-validate`` | |
383 | ||
384 | Set the mode for DNSSEC processing: | |
385 | ||
386 | off | |
387 | ^^^ | |
388 | No DNSSEC processing whatsoever. | |
389 | Ignore DO-bits in queries, don't request any DNSSEC information from authoritative servers. | |
390 | This behaviour is similar to PowerDNS Recursor pre-4.0. | |
391 | ||
392 | process-no-validate | |
393 | ^^^^^^^^^^^^^^^^^^^ | |
394 | Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries. | |
395 | Don't do any validation. | |
396 | ||
397 | process | |
398 | ^^^^^^^ | |
399 | Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries. | |
400 | Do validation for clients that request it (by means of the AD- bit or DO-bit in the query). | |
401 | ||
402 | log-fail | |
403 | ^^^^^^^^ | |
404 | Similar behaviour to ``process``, but validate RRSIGs on responses and log bogus responses. | |
405 | ||
406 | validate | |
407 | ^^^^^^^^ | |
408 | Full blown DNSSEC validation. Send SERVFAIL to clients on bogus responses. | |
409 | ||
410 | .. _setting-dnssec-log-bogus: | |
411 | ||
412 | ``dnssec-log-bogus`` | |
413 | -------------------- | |
414 | - Boolean | |
415 | - Default: no | |
416 | ||
417 | Log every DNSSEC validation failure. | |
418 | **Note**: This is not logged per-query but every time records are validated as Bogus. | |
419 | ||
420 | .. _setting-dont-query: | |
421 | ||
422 | ``dont-query`` | |
423 | -------------- | |
424 | - Netmasks, comma separated | |
425 | - 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 | |
426 | ||
427 | The DNS is a public database, but sometimes contains delegations to private IP addresses, like for example 127.0.0.1. | |
428 | This can have odd effects, depending on your network, and may even be a security risk. | |
429 | Therefore, the PowerDNS Recursor by default does not query private space IP addresses. | |
430 | This setting can be used to expand or reduce the limitations. | |
431 | ||
432 | 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. | |
433 | ||
2fe3354d CH |
434 | .. _setting-ecs-add-for: |
435 | ||
436 | ``ecs-add-for`` | |
c8dbb9f7 | 437 | --------------- |
2fe3354d CH |
438 | .. versionadded:: 4.2.0 |
439 | ||
440 | - Comma separated list of netmasks | |
441 | - 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 | |
442 | ||
9f421b03 | 443 | 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 |
444 | Valid incoming ECS values from `use-incoming-edns-subnet`_ are not replaced. |
445 | ||
9f421b03 CH |
446 | 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. |
447 | ||
2fe3354d CH |
448 | This defaults to not using the requestor address inside RFC1918 and similar "private" IP address spaces. |
449 | ||
223bb49e PL |
450 | .. _setting-ecs-ipv4-bits: |
451 | ||
452 | ``ecs-ipv4-bits`` | |
453 | ----------------- | |
454 | .. versionadded:: 4.1.0 | |
455 | ||
456 | - Integer | |
457 | - Default: 24 | |
458 | ||
459 | Number of bits of client IPv4 address to pass when sending EDNS Client Subnet address information. | |
460 | ||
216dc60a RG |
461 | .. _setting-ecs-ipv4-cache-bits: |
462 | ||
463 | ``ecs-ipv4-cache-bits`` | |
e4c13fec | 464 | ----------------------- |
216dc60a RG |
465 | .. versionadded:: 4.1.12 |
466 | ||
467 | - Integer | |
468 | - Default: 24 | |
469 | ||
42f41804 OM |
470 | Maximum number of bits of client IPv4 address used by the authoritative server (as indicated by the EDNS Client Subnet scope in the answer) for an answer to be inserted into the query cache. This condition applies in conjunction with ``ecs-cache-limit-ttl``. |
471 | That is, only if both the limits apply, the record will not be cached. | |
216dc60a | 472 | |
223bb49e PL |
473 | .. _setting-ecs-ipv6-bits: |
474 | ||
475 | ``ecs-ipv6-bits`` | |
476 | ----------------- | |
477 | .. versionadded:: 4.1.0 | |
478 | ||
479 | - Integer | |
480 | - Default: 56 | |
481 | ||
482 | Number of bits of client IPv6 address to pass when sending EDNS Client Subnet address information. | |
483 | ||
216dc60a RG |
484 | .. _setting-ecs-ipv6-cache-bits: |
485 | ||
486 | ``ecs-ipv6-cache-bits`` | |
e4c13fec | 487 | ----------------------- |
216dc60a RG |
488 | .. versionadded:: 4.1.12 |
489 | ||
490 | - Integer | |
491 | - Default: 56 | |
492 | ||
42f41804 OM |
493 | Maximum number of bits of client IPv6 address used by the authoritative server (as indicated by the EDNS Client Subnet scope in the answer) for an answer to be inserted into the query cache. This condition applies in conjunction with ``ecs-cache-limit-ttl``. |
494 | That is, only if both the limits apply, the record will not be cached. | |
216dc60a | 495 | |
5cf4b2e7 RG |
496 | .. _setting-ecs-minimum-ttl-override: |
497 | ||
498 | ``ecs-minimum-ttl-override`` | |
499 | ---------------------------- | |
500 | - Integer | |
501 | - Default: 0 (disabled) | |
502 | ||
503 | This setting artificially raises the TTLs of records in the ANSWER section of ECS-specific answers to be at least this long. | |
504 | While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers. | |
505 | Can be set at runtime using ``rec_control set-ecs-minimum-ttl 3600``. | |
506 | ||
ed9019c9 OM |
507 | .. _setting-ecs-cache-limit-ttl: |
508 | ||
509 | ``ecs-cache-limit-ttl`` | |
510 | ----------------------- | |
2cbe6a45 OM |
511 | .. versionadded:: 4.1.12 |
512 | ||
ed9019c9 OM |
513 | - Integer |
514 | - Default: 0 (disabled) | |
515 | ||
73d9bf3a | 516 | The minimum TTL for an ECS-specific answer to be inserted into the query cache. This condition applies in conjunction with ``ecs-ipv4-cache-bits`` or ``ecs-ipv6-cache-bits``. |
42f41804 | 517 | That is, only if both the limits apply, the record will not be cached. |
ed9019c9 | 518 | |
8a3a3822 RG |
519 | .. _setting-ecs-scope-zero-address: |
520 | ||
521 | ``ecs-scope-zero-address`` | |
522 | -------------------------- | |
523 | .. versionadded:: 4.1.0 | |
524 | ||
525 | - IPv4 or IPv6 Address | |
526 | - Default: empty | |
527 | ||
528 | The IP address sent via EDNS Client Subnet to authoritative servers listed in | |
a5607c95 | 529 | `edns-subnet-whitelist`_ when `use-incoming-edns-subnet`_ is set and the query has |
8a3a3822 | 530 | an ECS source prefix-length set to 0. |
a5607c95 | 531 | The default is to look for the first usable (not an ``any`` one) address in |
8a3a3822 RG |
532 | `query-local-address`_ then `query-local-address6`_. If no suitable address is |
533 | found, the recursor fallbacks to sending 127.0.0.1. | |
534 | ||
223bb49e PL |
535 | .. _setting-edns-outgoing-bufsize: |
536 | ||
537 | ``edns-outgoing-bufsize`` | |
538 | ------------------------- | |
54c36063 PL |
539 | .. versionchanged:: 4.2.0 |
540 | Before 4.2.0, the default was 1680 | |
541 | ||
223bb49e | 542 | - Integer |
54c36063 PL |
543 | - Default: 1232 |
544 | ||
545 | .. note:: Why 1232? | |
546 | ||
547 | 1232 is the largest number of payload bytes that can fit in the smallest IPv6 packet. | |
fdda1fb7 | 548 | 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 |
549 | |
550 | This is the value set for the EDNS0 buffer size in outgoing packets. | |
551 | Lower this if you experience timeouts. | |
552 | ||
553 | .. _setting-edns-subnet-whitelist: | |
554 | ||
555 | ``edns-subnet-whitelist`` | |
556 | ------------------------- | |
557 | - Comma separated list of domain names and netmasks | |
558 | - Default: (none) | |
559 | ||
560 | List of netmasks and domains that :rfc:`EDNS Client Subnet <7871>` should be enabled for in outgoing queries. | |
2fe3354d CH |
561 | |
562 | 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. | |
563 | 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. | |
564 | ||
223bb49e PL |
565 | By default, this option is empty, meaning no EDNS Client Subnet information is sent. |
566 | ||
567 | .. _setting-entropy-source: | |
568 | ||
569 | ``entropy-source`` | |
570 | ------------------ | |
571 | - Path | |
572 | - Default: /dev/urandom | |
573 | ||
574 | PowerDNS can read entropy from a (hardware) source. | |
575 | This is used for generating random numbers which are very hard to predict. | |
576 | Generally on UNIX platforms, this source will be ``/dev/urandom``, which will always supply random numbers, even if entropy is lacking. | |
577 | Change to ``/dev/random`` if PowerDNS should block waiting for enough entropy to arrive. | |
578 | ||
579 | .. _setting-etc-hosts-file: | |
580 | ||
581 | ``etc-hosts-file`` | |
582 | ------------------ | |
583 | - Path | |
584 | - Default: /etc/hosts | |
585 | ||
586 | The path to the /etc/hosts file, or equivalent. | |
587 | This file can be used to serve data authoritatively using `export-etc-hosts`_. | |
588 | ||
589 | .. _setting-export-etc-hosts: | |
590 | ||
591 | ``export-etc-hosts`` | |
592 | -------------------- | |
593 | - Boolean | |
594 | - Default: no | |
595 | ||
596 | If set, this flag will export the host names and IP addresses mentioned in ``/etc/hosts``. | |
597 | ||
598 | .. _setting-export-etc-hosts-search-suffix: | |
599 | ||
600 | ``export-etc-hosts-search-suffix`` | |
601 | ---------------------------------- | |
602 | - String | |
603 | ||
604 | 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. | |
605 | 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. | |
606 | An entry called 'server1.home' will be stored as 'server1.home', regardless of this setting. | |
607 | ||
608 | .. _setting-forward-zones: | |
609 | ||
610 | ``forward-zones`` | |
611 | ----------------- | |
612 | - 'zonename=IP' pairs, comma separated | |
613 | ||
fd47d762 | 614 | Queries for zones listed here will be forwarded to the IP address listed. i.e. |
223bb49e PL |
615 | |
616 | .. code-block:: none | |
617 | ||
618 | forward-zones=example.org=203.0.113.210, powerdns.com=2001:DB8::BEEF:5 | |
619 | ||
620 | Multiple IP addresses can be specified and port numbers other than 53 can be configured: | |
621 | ||
622 | .. code-block:: none | |
623 | ||
624 | 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 | |
625 | ||
626 | Forwarded queries have the 'recursion desired' bit set to 0, meaning that this setting is intended to forward queries to authoritative servers. | |
627 | ||
628 | **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. | |
629 | To prevent this, add a Negative Trust Anchor (NTA) for this zone in the `lua-config-file`_ with ``addNTA("your.zone", "A comment")``. | |
630 | If this forwarded zone is signed, instead of adding NTA, add the DS record to the `lua-config-file`_. | |
631 | See the :doc:`dnssec` information. | |
632 | ||
633 | .. _setting-forward-zones-file: | |
634 | ||
635 | ``forward-zones-file`` | |
636 | ---------------------- | |
637 | - Path | |
638 | ||
639 | Same as `forward-zones`_, parsed from a file. Only 1 zone is allowed per line, specified as follows: | |
640 | ||
641 | .. code-block:: none | |
642 | ||
643 | example.org=203.0.113.210, 192.0.2.4:5300 | |
644 | ||
645 | Zones prefixed with a '+' are forwarded with the recursion-desired bit set, for which see `forward-zones-recurse`_. | |
646 | Default behaviour without '+' is as with `forward-zones`_. | |
647 | ||
648 | .. versionchanged:: 4.0.0 | |
649 | ||
650 | Comments are allowed, everything behind '#' is ignored. | |
651 | ||
652 | The DNSSEC notes from `forward-zones`_ apply here as well. | |
653 | ||
654 | .. _setting-forward-zones-recurse: | |
655 | ||
656 | ``forward-zones-recurse`` | |
657 | ------------------------- | |
658 | - 'zonename=IP' pairs, comma separated | |
659 | ||
660 | 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. | |
661 | ||
662 | The DNSSEC notes from `forward-zones`_ apply here as well. | |
663 | ||
664 | .. _setting-gettag-needs-edns-options: | |
665 | ||
666 | ``gettag-needs-edns-options`` | |
667 | ----------------------------- | |
668 | .. versionadded:: 4.1.0 | |
669 | ||
670 | - Boolean | |
671 | - Default: no | |
672 | ||
673 | If set, EDNS options in incoming queries are extracted and passed to the :func:`gettag` hook in the ``ednsoptions`` table. | |
674 | ||
675 | .. _setting-hint-file: | |
676 | ||
677 | ``hint-file`` | |
678 | ------------- | |
679 | - Path | |
680 | ||
681 | If set, the root-hints are read from this file. If unset, default root hints are used. | |
682 | ||
683 | .. _setting-include-dir: | |
684 | ||
685 | ``include-dir`` | |
686 | --------------- | |
687 | - Path | |
688 | ||
689 | Directory to scan for additional config files. All files that end with .conf are loaded in order using ``POSIX`` as locale. | |
690 | ||
691 | .. _setting-latency-statistic-size: | |
692 | ||
693 | ``latency-statistic-size`` | |
694 | -------------------------- | |
695 | - Integer | |
696 | - Default: 10000 | |
697 | ||
698 | Indication of how many queries will be averaged to get the average latency reported by the 'qa-latency' metric. | |
699 | ||
700 | .. _setting-local-address: | |
701 | ||
702 | ``local-address`` | |
703 | ----------------- | |
704 | - IP addresses, comma separated | |
705 | - Default: 127.0.0.1 | |
706 | ||
707 | Local IPv4 or IPv6 addresses to bind to. | |
708 | Addresses can also contain port numbers, for IPv4 specify like this: ``192.0.2.4:5300``, for IPv6: ``[::1]:5300``. | |
709 | ||
710 | **Warning**: When binding to wildcard addresses, UNIX semantics mean that answers may not be sent from the address a query was received on. | |
711 | It is highly recommended to bind to explicit addresses. | |
712 | ||
713 | .. _setting-local-port: | |
714 | ||
715 | ``local-port`` | |
716 | -------------- | |
717 | - Integer | |
718 | - Default: 53 | |
719 | ||
720 | Local port to bind to. | |
721 | If an address in `local-address`_ does not have an explicit port, this port is used. | |
722 | ||
b18fa400 PL |
723 | .. _setting-log-timestamp: |
724 | ||
725 | ``log-timestamp`` | |
726 | ----------------- | |
727 | ||
728 | .. versionadded:: 4.1.0 | |
729 | ||
730 | - Bool | |
731 | - Default: yes | |
732 | ||
733 | When printing log lines to stdout, prefix them with timestamps. | |
734 | Disable this if the process supervisor timestamps these lines already. | |
735 | ||
736 | .. note:: | |
737 | The systemd unit file supplied with the source code already disables timestamp printing | |
738 | ||
223bb49e PL |
739 | .. _setting-non-local-bind: |
740 | ||
741 | ``non-local-bind`` | |
742 | ------------------ | |
743 | - Boolean | |
744 | - Default: no | |
745 | ||
746 | Bind to addresses even if one or more of the `local-address`_'s do not exist on this server. | |
747 | Setting this option will enable the needed socket options to allow binding to non-local addresses. | |
748 | 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. | |
749 | ||
750 | .. _setting-loglevel: | |
751 | ||
752 | ``loglevel`` | |
753 | ------------ | |
754 | - Integer between 0 and 9 | |
9afa8662 | 755 | - Default: 6 |
223bb49e PL |
756 | |
757 | Amount of logging. | |
758 | Higher is more, more logging may destroy performance. | |
759 | It is recommended not to set this below 3. | |
760 | ||
761 | .. _setting-log-common-errors: | |
762 | ||
763 | ``log-common-errors`` | |
764 | --------------------- | |
765 | - Boolean | |
766 | - Default: no | |
767 | ||
768 | Some DNS errors occur rather frequently and are no cause for alarm. | |
769 | ||
98d36505 | 770 | ``log-rpz-changes`` |
c8dbb9f7 | 771 | ------------------- |
98d36505 RG |
772 | .. versionadded:: 4.1.0 |
773 | ||
774 | - Boolean | |
775 | - Default: no | |
776 | ||
777 | Log additions and removals to RPZ zones at Info (6) level instead of Debug (7). | |
778 | ||
223bb49e PL |
779 | .. _setting-logging-facility: |
780 | ||
781 | ``logging-facility`` | |
782 | -------------------- | |
783 | - Integer | |
784 | ||
785 | If set to a digit, logging is performed under this LOCAL facility. | |
786 | See :ref:`logging`. | |
787 | Do not pass names like 'local0'! | |
788 | ||
789 | .. _setting-lowercase-outgoing: | |
790 | ||
791 | ``lowercase-outgoing`` | |
792 | ---------------------- | |
793 | - Boolean | |
794 | - Default: no | |
795 | ||
796 | Set to true to lowercase the outgoing queries. | |
797 | 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. | |
798 | Broken authoritative servers might give a wrong or broken answer on this encoding. | |
799 | 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. | |
800 | ||
801 | .. _setting-lua-config-file: | |
802 | ||
803 | ``lua-config-file`` | |
804 | ------------------- | |
805 | - Filename | |
806 | ||
807 | If set, and Lua support is compiled in, this will load an additional configuration file for newer features and more complicated setups. | |
808 | See :doc:`lua-config/index` for the options that can be set in this file. | |
809 | ||
810 | .. _setting-lua-dns-script: | |
811 | ||
812 | ``lua-dns-script`` | |
813 | ------------------ | |
814 | - Path | |
815 | - Default: unset | |
816 | ||
817 | Path to a lua file to manipulate the Recursor's answers. See :doc:`lua-scripting/index` for more information. | |
818 | ||
a2f87dd1 CHB |
819 | .. _setting-maintenance-interval: |
820 | ||
821 | ``lua-maintenance-interval`` | |
c8dbb9f7 | 822 | ---------------------------- |
2a9a7388 | 823 | .. versionadded:: 4.2.0 |
a2f87dd1 CHB |
824 | |
825 | - Integer | |
826 | - Default: 1 | |
827 | ||
828 | ||
829 | The interval between calls to the Lua user defined `maintenance()` function in seconds. | |
830 | See :ref:`hooks-maintenance-callback` | |
831 | ||
b9473937 RG |
832 | .. _setting-max-cache-bogus-ttl: |
833 | ||
834 | ``max-cache-bogus-ttl`` | |
835 | ----------------------- | |
836 | .. versionadded:: 4.2.0 | |
837 | ||
838 | - Integer | |
839 | - Default: 3600 | |
840 | ||
841 | Maximum number of seconds to cache an item in the DNS cache (negative or positive) if its DNSSEC validation failed, no matter what the original TTL specified, to reduce the impact of a broken domain. | |
842 | ||
223bb49e PL |
843 | .. _setting-max-cache-entries: |
844 | ||
845 | ``max-cache-entries`` | |
846 | --------------------- | |
847 | - Integer | |
848 | - Default: 1000000 | |
849 | ||
850 | Maximum number of DNS cache entries. | |
851 | 1 million per thread will generally suffice for most installations. | |
852 | ||
853 | .. _setting-max-cache-ttl: | |
854 | ||
855 | ``max-cache-ttl`` | |
856 | ----------------- | |
857 | - Integer | |
858 | - Default: 86400 | |
859 | ||
860 | Maximum number of seconds to cache an item in the DNS cache, no matter what the original TTL specified. | |
861 | ||
862 | .. versionchanged:: 4.1.0 | |
863 | ||
864 | The minimum value of this setting is 15. i.e. setting this to lower than 15 will make this value 15. | |
865 | ||
87ff2287 OM |
866 | .. _setting max-concurrent-requests-per-tcp-connection: |
867 | ||
868 | ``max-concurrent-requests-per-tcp-connection`` | |
4dbb3795 | 869 | ---------------------------------------------- |
122d1322 OM |
870 | |
871 | .. versionadded:: 4.3.0 | |
872 | ||
87ff2287 OM |
873 | - Integer |
874 | - Default: 10 | |
875 | ||
c51c551e OM |
876 | Maximum number of incoming requests handled concurrently per tcp |
877 | connection. This number must be larger than 0 and smaller than 65536 | |
878 | and also smaller than `max-mthreads`. | |
879 | ||
ba3d53d1 RG |
880 | .. _setting-max-generate-steps: |
881 | ||
882 | ``max-generate-steps`` | |
883 | ---------------------- | |
884 | ||
885 | .. versionadded:: 4.3.0 | |
886 | ||
887 | - Integer | |
888 | - Default: 0 | |
889 | ||
890 | Maximum number of steps for a '$GENERATE' directive when parsing a | |
891 | zone file. This is a protection measure to prevent consuming a lot of | |
892 | CPU and memory when untrusted zones are loaded. Default to 0 which | |
893 | means unlimited. | |
87ff2287 | 894 | |
223bb49e PL |
895 | .. _setting-max-mthreads: |
896 | ||
897 | ``max-mthreads`` | |
898 | ---------------- | |
899 | - Integer | |
900 | - Default: 2048 | |
901 | ||
902 | Maximum number of simultaneous MTasker threads. | |
903 | ||
904 | .. _setting-max-packetcache-entries: | |
905 | ||
906 | ``max-packetcache-entries`` | |
907 | --------------------------- | |
908 | - Integer | |
909 | - Default: 500000 | |
910 | ||
911 | Maximum number of Packet Cache entries. | |
912 | 1 million per thread will generally suffice for most installations. | |
913 | ||
914 | .. _setting-max-qperq: | |
915 | ||
916 | ``max-qperq`` | |
917 | ------------- | |
918 | - Integer | |
409b8398 | 919 | - Default: 60 |
223bb49e PL |
920 | |
921 | The maximum number of outgoing queries that will be sent out during the resolution of a single client query. | |
922 | This is used to limit endlessly chasing CNAME redirections. | |
edea1bf7 OM |
923 | If qname-minimization is enabled, the number will be forced to be 100 |
924 | at a minimum to allow for the extra queries qname-minimization generates when the cache is empty. | |
223bb49e PL |
925 | |
926 | .. _setting-max-negative-ttl: | |
927 | ||
928 | ``max-negative-ttl`` | |
929 | -------------------- | |
930 | - Integer | |
931 | - Default: 3600 | |
932 | ||
933 | 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. | |
934 | In practice, caches can become saturated with hundreds of thousands of hosts which are tried only once. | |
935 | This setting, which defaults to 3600 seconds, puts a maximum on the amount of time negative entries are cached. | |
936 | ||
937 | .. _setting-max-recursion-depth: | |
938 | ||
939 | ``max-recursion-depth`` | |
940 | ----------------------- | |
941 | - Integer | |
942 | - Default: 40 | |
943 | ||
944 | Total maximum number of internal recursion calls the server may use to answer a single query. | |
945 | 0 means unlimited. | |
946 | The value of `stack-size`_ should be increased together with this one to prevent the stack from overflowing. | |
947 | ||
948 | .. versionchanged:: 4.1.0 | |
949 | ||
950 | Before 4.1.0, this settings was unlimited. | |
951 | ||
952 | .. _setting-max-tcp-clients: | |
953 | ||
954 | ``max-tcp-clients`` | |
955 | ------------------- | |
956 | - Integer | |
957 | - Default: 128 | |
958 | ||
959 | Maximum number of simultaneous incoming TCP connections allowed. | |
960 | ||
961 | .. _setting-max-tcp-per-client: | |
962 | ||
963 | ``max-tcp-per-client`` | |
964 | ---------------------- | |
965 | - Integer | |
966 | - Default: 0 (unlimited) | |
967 | ||
968 | Maximum number of simultaneous incoming TCP connections allowed per client (remote IP address). | |
969 | ||
970 | .. _setting-max-tcp-queries-per-connection: | |
971 | ||
972 | ``max-tcp-queries-per-connection`` | |
973 | ---------------------------------- | |
974 | .. versionadded:: 4.1.0 | |
975 | ||
976 | - Integer | |
977 | - Default: 0 (unlimited) | |
978 | ||
979 | Maximum number of DNS queries in a TCP connection. | |
980 | ||
981 | .. _setting-max-total-msec: | |
982 | ||
983 | ``max-total-msec`` | |
984 | ------------------ | |
985 | - Integer | |
986 | - Default: 7000 | |
987 | ||
988 | Total maximum number of milliseconds of wallclock time the server may use to answer a single query. | |
989 | ||
a5886e6a RG |
990 | .. _setting-max-udp-queries-per-round: |
991 | ||
992 | ``max-udp-queries-per-round`` | |
993 | ---------------------------------- | |
0a4c1ecf | 994 | .. versionadded:: 4.1.4 |
a5886e6a RG |
995 | |
996 | - Integer | |
997 | - Default: 10000 | |
998 | ||
78227847 RG |
999 | 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 |
1000 | neglect scheduling new ``mthreads``, handling responses from authoritative servers or responding to :doc:`rec_control <manpages/rec_control.1>` | |
1001 | requests. | |
1002 | 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 | |
1003 | returning back to normal processing and handling other events. | |
a5886e6a | 1004 | |
223bb49e PL |
1005 | .. _setting-minimum-ttl-override: |
1006 | ||
1007 | ``minimum-ttl-override`` | |
1008 | ------------------------ | |
1009 | - Integer | |
1010 | - Default: 0 (disabled) | |
1011 | ||
1012 | This setting artificially raises all TTLs to be at least this long. | |
1013 | While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers. | |
1014 | Can be set at runtime using ``rec_control set-minimum-ttl 3600``. | |
1015 | ||
af1377b7 NC |
1016 | .. _setting-new-domain-tracking: |
1017 | ||
1018 | ``new-domain-tracking`` | |
1019 | ----------------------- | |
a0ce6b10 PL |
1020 | .. versionadded:: 4.2.0 |
1021 | ||
af1377b7 NC |
1022 | - Boolean |
1023 | - Default: no (disabled) | |
1024 | ||
1025 | Whether to track newly observed domains, i.e. never seen before. This | |
1026 | is a probablistic algorithm, using a stable bloom filter to store | |
1027 | records of previously seen domains. When enabled for the first time, | |
1028 | all domains will appear to be newly observed, so the feature is best | |
1029 | left enabled for e.g. a week or longer before using the results. Note | |
1030 | that this feature is optional and must be enabled at compile-time, | |
1031 | thus it may not be available in all pre-built packages. | |
5a9ec46b NC |
1032 | If protobuf is enabled and configured, then the newly observed domain |
1033 | status will appear as a flag in Response messages. | |
af1377b7 NC |
1034 | |
1035 | .. _setting-new-domain-log: | |
1036 | ||
1037 | ``new-domain-log`` | |
1038 | ------------------ | |
a0ce6b10 PL |
1039 | .. versionadded:: 4.2.0 |
1040 | ||
af1377b7 NC |
1041 | - Boolean |
1042 | - Default: yes (enabled) | |
1043 | ||
1044 | If a newly observed domain is detected, log that domain in the | |
a0ce6b10 | 1045 | recursor log file. The log line looks something like:: |
af1377b7 | 1046 | |
a0ce6b10 | 1047 | Jul 18 11:31:25 Newly observed domain nod=sdfoijdfio.com |
af1377b7 NC |
1048 | |
1049 | .. _setting-new-domain-lookup: | |
1050 | ||
1051 | ``new-domain-lookup`` | |
1052 | --------------------- | |
a0ce6b10 PL |
1053 | .. versionadded:: 4.2.0 |
1054 | ||
af1377b7 NC |
1055 | - Domain Name |
1056 | - Example: nod.powerdns.com | |
1057 | ||
1058 | If a domain is specified, then each time a newly observed domain is | |
1059 | detected, the recursor will perform an A record lookup of "<newly | |
1060 | observed domain>.<lookup domain>". For example if 'new-domain-lookup' | |
1061 | is configured as 'nod.powerdns.com', and a new domain 'xyz123.tv' is | |
1062 | detected, then an A record lookup will be made for | |
1063 | 'xyz123.tv.nod.powerdns.com'. This feature gives a way to share the | |
1064 | newly observed domain with partners, vendors or security teams. The | |
1065 | result of the DNS lookup will be ignored by the recursor. | |
1066 | ||
5a9ec46b NC |
1067 | .. _setting-new-domain-db-size: |
1068 | ||
1069 | ``new-domain-db-size`` | |
a0ce6b10 PL |
1070 | ---------------------- |
1071 | .. versionadded:: 4.2.0 | |
1072 | ||
5a9ec46b NC |
1073 | - Integer |
1074 | - Example: 67108864 | |
1075 | ||
1076 | The default size of the stable bloom filter used to store previously | |
1077 | observed domains is 67108864. To change the number of cells, use this | |
1078 | setting. For each cell, the SBF uses 1 bit of memory, and one byte of | |
1079 | disk for the persistent file. | |
fd47d762 | 1080 | If there are already persistent files saved to disk, this setting will |
5a9ec46b NC |
1081 | have no effect unless you remove the existing files. |
1082 | ||
af1377b7 NC |
1083 | .. _setting-new-domain-history-dir: |
1084 | ||
1085 | ``new-domain-history-dir`` | |
1086 | -------------------------- | |
a0ce6b10 PL |
1087 | .. versionadded:: 4.2.0 |
1088 | ||
af1377b7 | 1089 | - Path |
af1377b7 NC |
1090 | |
1091 | This setting controls which directory is used to store the on-disk | |
1092 | cache of previously observed domains. | |
1093 | ||
a0ce6b10 PL |
1094 | The default depends on ``LOCALSTATEDIR`` when building the software. |
1095 | Usually this comes down to ``/var/lib/pdns-recursor/nod`` or ``/usr/local/var/lib/pdns-recursor/nod``). | |
1096 | ||
af1377b7 NC |
1097 | The newly observed domain feature uses a stable bloom filter to store |
1098 | a history of previously observed domains. The data structure is | |
5a9ec46b | 1099 | synchronized to disk every 10 minutes, and is also initialized from |
af1377b7 NC |
1100 | disk on startup. This ensures that previously observed domains are |
1101 | preserved across recursor restarts. | |
fd47d762 | 1102 | If you change the new-domain-db-size setting, you must remove any files |
5a9ec46b | 1103 | from this directory. |
af1377b7 NC |
1104 | |
1105 | .. _setting-new-domain-whitelist: | |
1106 | ||
1107 | ``new-domain-whitelist`` | |
1108 | ------------------------ | |
a0ce6b10 PL |
1109 | .. versionadded:: 4.2.0 |
1110 | ||
af1377b7 NC |
1111 | - List of Domain Names, comma separated |
1112 | - Example: xyz.com, abc.com | |
1113 | ||
1114 | This setting is a list of all domains (and implicitly all subdomains) | |
1115 | that will never be considered a new domain. For example, if the domain | |
1116 | 'xyz123.tv' is in the list, then 'foo.bar.xyz123.tv' will never be | |
1117 | considered a new domain. One use-case for the whitelist is to never | |
1118 | reveal details of internal subdomains via the new-domain-lookup | |
1119 | feature. | |
1120 | ||
27afebfd NC |
1121 | .. _setting-new-domain-pb-tag: |
1122 | ||
1123 | ``new-domain-pb-tag`` | |
5a9ec46b | 1124 | --------------------- |
a0ce6b10 | 1125 | .. versionadded:: 4.2.0 |
27afebfd | 1126 | |
27afebfd | 1127 | - String |
a0ce6b10 | 1128 | - Default: pnds-nod |
27afebfd NC |
1129 | |
1130 | If protobuf is configured, then this tag will be added to all protobuf response messages when | |
fd47d762 | 1131 | a new domain is observed. |
27afebfd | 1132 | |
223bb49e PL |
1133 | .. _setting-network-timeout: |
1134 | ||
1135 | ``network-timeout`` | |
1136 | ------------------- | |
1137 | - Integer | |
1138 | - Default: 1500 | |
1139 | ||
1140 | Number of milliseconds to wait for a remote authoritative server to respond. | |
1141 | ||
157647ec PL |
1142 | .. _setting-nothing-below-nxdomain: |
1143 | ||
1144 | ``nothing-below-nxdomain`` | |
1145 | -------------------------- | |
1146 | .. versionadded:: 4.3.0 | |
1147 | ||
9e28746d OM |
1148 | - One of ``no``, ``dnssec``, ``yes``, String |
1149 | - Default: ``dnssec`` | |
157647ec | 1150 | |
ba186b98 | 1151 | The type of :rfc:`8020` handling using cached NXDOMAIN responses. |
157647ec PL |
1152 | This RFC specifies that NXDOMAIN means that the DNS tree under the denied name MUST be empty. |
1153 | When an NXDOMAIN exists in the cache for a shorter name than the qname, no lookup is done and an NXDOMAIN is sent to the client. | |
1154 | ||
9e28746d OM |
1155 | For instance, when ``foo.example.net`` is negatively cached, any query |
1156 | matching ``*.foo.example.net`` will be answered with NXDOMAIN directly | |
1157 | without consulting authoritative servers. | |
1158 | ||
1159 | no | |
23711b60 | 1160 | ^^ |
9e28746d OM |
1161 | No :rfc:`8020` processing is done. |
1162 | ||
1163 | dnssec | |
23711b60 | 1164 | ^^^^^^ |
ba186b98 | 1165 | :rfc:`8020` processing is only done using cached NXDOMAIN records that are |
9e28746d OM |
1166 | DNSSEC validated. |
1167 | ||
1168 | yes | |
23711b60 | 1169 | ^^^ |
ba186b98 | 1170 | :rfc:`8020` processing is done using any non-Bogus NXDOMAIN record |
9e28746d | 1171 | available in the cache. |
157647ec | 1172 | |
223bb49e PL |
1173 | .. _setting-nsec3-max-iterations: |
1174 | ||
1175 | ``nsec3-max-iterations`` | |
1176 | ------------------------ | |
1177 | .. versionadded:: 4.1.0 | |
1178 | ||
1179 | - Integer | |
1180 | - Default: 2500 | |
1181 | ||
1182 | Maximum number of iterations allowed for an NSEC3 record. | |
1183 | If an answer containing an NSEC3 record with more iterations is received, its DNSSEC validation status is treated as Insecure. | |
1184 | ||
1185 | .. _setting-packetcache-ttl: | |
1186 | ||
1187 | ``packetcache-ttl`` | |
1188 | ------------------- | |
1189 | - Integer | |
1190 | - Default: 3600 | |
1191 | ||
1192 | Maximum number of seconds to cache an item in the packet cache, no matter what the original TTL specified. | |
1193 | ||
1194 | .. _setting-packetcache-servfail-ttl: | |
1195 | ||
1196 | ``packetcache-servfail-ttl`` | |
1197 | ---------------------------- | |
1198 | - Integer | |
1199 | - Default: 60 | |
1200 | ||
1201 | Maximum number of seconds to cache a 'server failure' answer in the packet cache. | |
1202 | ||
1203 | .. versionchanged:: 4.0.0 | |
1204 | ||
1205 | This setting's maximum is capped to `packetcache-ttl`_. | |
1206 | i.e. setting ``packetcache-ttl=15`` and keeping ``packetcache-servfail-ttl`` at the default will lower ``packetcache-servfail-ttl`` to ``15``. | |
1207 | ||
1208 | .. _setting-pdns-distributes-queries: | |
1209 | ||
1210 | ``pdns-distributes-queries`` | |
1211 | ---------------------------- | |
1212 | - Boolean | |
9bb80182 | 1213 | - Default: yes |
223bb49e | 1214 | |
b243ca3b RG |
1215 | 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, |
1216 | maximizing the cache hit ratio. Starting with version 4.2.0, more than one distributing thread can be started using the `distributor-threads`_ | |
1217 | setting. | |
223bb49e PL |
1218 | Improves performance on Linux. |
1219 | ||
0dd5b728 | 1220 | .. _setting-protobuf-use-kernel-timestamp: |
c29d820c RG |
1221 | |
1222 | ``protobuf-use-kernel-timestamp`` | |
e4c13fec | 1223 | --------------------------------- |
c29d820c RG |
1224 | .. versionadded:: 4.2.0 |
1225 | ||
1226 | - Boolean | |
1227 | - Default: false | |
1228 | ||
1229 | Whether to compute the latency of responses in protobuf messages using the timestamp set by the kernel when the query packet was received (when available), instead of computing it based on the moment we start processing the query. | |
1230 | ||
d14a6965 RG |
1231 | .. _setting-proxy-protocol-from: |
1232 | ||
1233 | ``proxy-protocol-from`` | |
1234 | ----------------------- | |
1235 | .. versionadded:: 4.4.0 | |
1236 | ||
1237 | - IP ranges, separated by commas | |
1238 | - Default: empty | |
1239 | ||
ea201fc1 | 1240 | Ranges that are required to send a Proxy Protocol header in front of UDP and TCP queries, to pass the original source and destination addresses and ports to the recursor, as well as custom values. |
cb9ae80f | 1241 | Queries that are not prefixed with such a header will not be accepted from clients in these ranges. Queries prefixed by headers from clients that are not listed in these ranges will be dropped. |
ea201fc1 RG |
1242 | |
1243 | Note that once a Proxy Protocol header has been received, the original source address will be checked against the `allow-from`_ ACL, instead of the address of the proxy. | |
d14a6965 RG |
1244 | |
1245 | .. _setting-proxy-protocol-maximum-size: | |
1246 | ||
1247 | ``proxy-protocol-maximum-size`` | |
1248 | ------------------------------- | |
1249 | .. versionadded:: 4.4.0 | |
1250 | ||
1251 | - Integer | |
1252 | - Default: 512 | |
1253 | ||
1254 | The maximum size, in bytes, of a Proxy Protocol payload (header, addresses and ports, and TLV values). Queries with a larger payload will be dropped. | |
1255 | ||
0dd5b728 | 1256 | .. _setting-public-suffix-list-file: |
d6f3fcfa RG |
1257 | |
1258 | ``public-suffix-list-file`` | |
1259 | --------------------------- | |
1260 | .. versionadded:: 4.2.0 | |
1261 | ||
1262 | - Path | |
1263 | - Default: unset | |
1264 | ||
1265 | 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. | |
1266 | ||
116d1288 OM |
1267 | .. _setting-qname-minimization: |
1268 | ||
1269 | ``qname-minimization`` | |
1270 | ---------------------- | |
1271 | .. versionadded:: 4.3.0 | |
e4c13fec | 1272 | |
116d1288 | 1273 | - Boolean |
8949a3e0 | 1274 | - Default: yes |
116d1288 | 1275 | |
2af7d2c2 | 1276 | Enable Query Name Minimization. This implements a relaxed form of Query Name Mimimization as |
3fcf2c9e | 1277 | described in :rfc:`7816`. |
116d1288 | 1278 | |
223bb49e PL |
1279 | .. _setting-query-local-address: |
1280 | ||
1281 | ``query-local-address`` | |
1282 | ----------------------- | |
1283 | - IPv4 Address, comma separated | |
1284 | - Default: 0.0.0.0 | |
1285 | ||
1286 | Send out local queries from this address, or addresses, by adding multiple addresses, increased spoofing resilience is achieved. | |
1287 | ||
1288 | .. _setting-query-local-address6: | |
1289 | ||
1290 | ``query-local-address6`` | |
1291 | ------------------------ | |
1292 | - IPv6 addresses, comma separated | |
1293 | - Default: unset | |
1294 | ||
1295 | Send out local IPv6 queries from this address or addresses. | |
1296 | Disabled by default, which also disables outgoing IPv6 support. | |
1297 | ||
1298 | .. _setting-quiet: | |
1299 | ||
1300 | ``quiet`` | |
1301 | --------- | |
1302 | - Boolean | |
1303 | - Default: yes | |
1304 | ||
1305 | Don't log queries. | |
1306 | ||
1307 | .. _setting-reuseport: | |
1308 | ||
1309 | ``reuseport`` | |
1310 | ------------- | |
1311 | - Boolean | |
1312 | - Default: no | |
1313 | ||
1314 | If ``SO_REUSEPORT`` support is available, allows multiple processes to open a listening socket on the same port. | |
1315 | ||
1316 | 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. | |
1317 | ||
e97cb679 | 1318 | .. _setting-rng: |
be512fa0 | 1319 | |
e97cb679 AT |
1320 | ``rng`` |
1321 | ------- | |
1322 | ||
1323 | - String | |
1324 | - Default: auto | |
1325 | ||
1326 | Specify which random number generator to use. Permissible choises are | |
1327 | - auto - choose automatically | |
1328 | - sodium - Use libsodium ``randombytes_uniform`` | |
1329 | - openssl - Use libcrypto ``RAND_bytes`` | |
1330 | - getrandom - Use libc getrandom, falls back to urandom if it does not really work | |
1331 | - arc4random - Use BSD ``arc4random_uniform`` | |
1332 | - urandom - Use ``/dev/urandom`` | |
1333 | - kiss - Use simple settable deterministic RNG. **FOR TESTING PURPOSES ONLY!** | |
1334 | ||
1335 | .. note:: | |
1336 | Not all choises are available on all systems. | |
1337 | ||
223bb49e PL |
1338 | .. _setting-root-nx-trust: |
1339 | ||
1340 | ``root-nx-trust`` | |
1341 | ----------------- | |
1342 | - Boolean | |
1343 | - Default: yes | |
1344 | ||
1345 | If set, an NXDOMAIN from the root-servers will serve as a blanket NXDOMAIN for the entire TLD the query belonged to. | |
1346 | The effect of this is far fewer queries to the root-servers. | |
1347 | ||
1348 | .. versionchanged:: 4.0.0 | |
1349 | ||
1350 | Default is 'yes' now, was 'no' before 4.0.0 | |
1351 | ||
1352 | .. _setting-security-poll-suffix: | |
1353 | ||
1354 | ``security-poll-suffix`` | |
1355 | ------------------------ | |
1356 | - String | |
1357 | - Default: secpoll.powerdns.com. | |
1358 | ||
1359 | Domain name from which to query security update notifications. | |
1360 | Setting this to an empty string disables secpoll. | |
1361 | ||
1362 | .. _setting-serve-rfc1918: | |
1363 | ||
1364 | ``serve-rfc1918`` | |
1365 | ----------------- | |
1366 | - Boolean | |
1367 | - Default: yes | |
1368 | ||
1369 | 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. | |
1370 | Individual parts of these zones can still be loaded or forwarded. | |
1371 | ||
1372 | .. _setting-server-down-max-fails: | |
1373 | ||
1374 | ``server-down-max-fails`` | |
1375 | ------------------------- | |
1376 | - Integer | |
1377 | - Default: 64 | |
1378 | ||
1379 | 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. | |
1380 | 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. | |
1381 | Even a single response packet will drop the block. | |
1382 | ||
1383 | .. _setting-server-down-throttle-time: | |
1384 | ||
1385 | ``server-down-throttle-time`` | |
1386 | ----------------------------- | |
1387 | - Integer | |
1388 | - Default: 60 | |
1389 | ||
1390 | Throttle a server that has failed to respond `server-down-max-fails`_ times for this many seconds. | |
1391 | ||
1392 | .. _setting-server-id: | |
1393 | ||
1394 | ``server-id`` | |
1395 | ------------- | |
1396 | - String | |
1397 | - Default: The hostname of the server | |
1398 | ||
725d5249 | 1399 | The reply given by The PowerDNS recursor to a query for 'id.server' with its hostname, useful for in clusters. |
c8dbb9f7 | 1400 | When a query contains the :rfc:`NSID EDNS0 Option <5001>`, this value is returned in the response as the NSID value. |
725d5249 PL |
1401 | |
1402 | This setting can be used to override the answer given to these queries. | |
1403 | Set to "disabled" to disable NSID and 'id.server' answers. | |
223bb49e PL |
1404 | |
1405 | Query example (where 192.0.2.14 is your server): | |
1406 | ||
1407 | .. code-block:: sh | |
1408 | ||
1409 | dig @192.0.2.14 CHAOS TXT id.server. | |
725d5249 | 1410 | dig @192.0.2.14 example.com IN A +nsid |
223bb49e PL |
1411 | |
1412 | ``setgid``, ``setuid`` | |
1413 | ---------------------- | |
1414 | - String | |
1415 | - Default: unset | |
1416 | ||
1417 | PowerDNS can change its user and group id after binding to its socket. | |
1418 | Can be used for better :doc:`security <security>`. | |
1419 | ||
9a3ab3e4 KM |
1420 | .. _setting-signature-inception-skew: |
1421 | ||
1422 | ``signature-inception-skew`` | |
1423 | ---------------------------------- | |
3a81cc73 KM |
1424 | .. versionadded:: 4.1.5 |
1425 | ||
9a3ab3e4 KM |
1426 | - Integer |
1427 | - Default: 60 | |
1428 | ||
ffa248e4 KM |
1429 | Allow the signature inception to be off by this number of seconds. Negative values are not allowed. |
1430 | ||
1431 | .. versionchanged:: 4.2.0 | |
1432 | ||
1433 | Default is now 60, was 0 before. | |
9a3ab3e4 | 1434 | |
223bb49e PL |
1435 | .. _setting-single-socket: |
1436 | ||
1437 | ``single-socket`` | |
1438 | ----------------- | |
1439 | - Boolean | |
1440 | - Default: no | |
1441 | ||
1442 | Use only a single socket for outgoing queries. | |
1443 | ||
1444 | .. _setting-snmp-agent: | |
1445 | ||
1446 | ``snmp-agent`` | |
1447 | -------------- | |
1448 | .. versionadded:: 4.1.0 | |
1449 | ||
1450 | - Boolean | |
1451 | - Default: no | |
1452 | ||
1453 | 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. | |
1454 | ||
1455 | .. _setting-snmp-master-socket: | |
1456 | ||
1457 | ``snmp-master-socket`` | |
1458 | ---------------------- | |
1459 | .. versionadded:: 4.1.0 | |
1460 | ||
1461 | - String | |
1462 | - Default: empty | |
1463 | ||
1464 | If not empty and ``snmp-agent`` is set to true, indicates how PowerDNS should contact the SNMP master to register as an SNMP agent. | |
1465 | ||
1466 | .. _setting-socket-dir: | |
1467 | ||
1468 | ``socket-dir`` | |
1469 | -------------- | |
1470 | - Path | |
1471 | ||
1472 | Where to store the control socket and pidfile. | |
a0ce6b10 | 1473 | The default depends on ``LOCALSTATEDIR`` or the ``--with-socketdir`` setting when building (usually ``/var/run`` or ``/run``). |
223bb49e PL |
1474 | |
1475 | When using `chroot`_ the default becomes to ``/``. | |
1476 | ||
1477 | ``socket-owner``, ``socket-group``, ``socket-mode`` | |
1478 | --------------------------------------------------- | |
1479 | Owner, group and mode of the controlsocket. | |
1480 | Owner and group can be specified by name, mode is in octal. | |
1481 | ||
1482 | .. _setting-spoof-nearmiss-max: | |
1483 | ||
1484 | ``spoof-nearmiss-max`` | |
1485 | ---------------------- | |
1486 | - Integer | |
1487 | - Default: 20 | |
1488 | ||
1489 | If set to non-zero, PowerDNS will assume it is being spoofed after seeing this many answers with the wrong id. | |
1490 | ||
1491 | .. _setting-stack-size: | |
1492 | ||
1493 | ``stack-size`` | |
1494 | -------------- | |
1495 | - Integer | |
1496 | - Default: 200000 | |
1497 | ||
1498 | Size of the stack per thread. | |
1499 | ||
1500 | .. _setting-statistics-interval: | |
1501 | ||
1502 | ``statistics-interval`` | |
1503 | ----------------------- | |
1504 | .. versionadded:: 4.1.0 | |
1505 | ||
1506 | - Integer | |
1507 | - Default: 1800 | |
1508 | ||
1509 | Interval between logging statistical summary on recursor performance. | |
1510 | Use 0 to disable. | |
1511 | ||
563517f3 RG |
1512 | .. _setting-stats-api-blacklist: |
1513 | ||
1514 | ``stats-api-blacklist`` | |
1515 | ----------------------- | |
1516 | .. versionadded:: 4.2.0 | |
1517 | ||
1518 | - String | |
5801b55c | 1519 | - Default: "cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*" |
563517f3 RG |
1520 | |
1521 | A list of comma-separated statistic names, that are disabled when retrieving the complete list of statistics via the API for performance reasons. | |
1522 | These statistics can still be retrieved individually by specifically asking for it. | |
1523 | ||
1524 | .. _setting-stats-carbon-blacklist: | |
1525 | ||
1526 | ``stats-carbon-blacklist`` | |
1527 | -------------------------- | |
1528 | .. versionadded:: 4.2.0 | |
1529 | ||
1530 | - String | |
5801b55c | 1531 | - Default: "cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*" |
563517f3 RG |
1532 | |
1533 | A list of comma-separated statistic names, that are prevented from being exported via carbon for performance reasons. | |
1534 | ||
1535 | .. _setting-stats-rec-control-blacklist: | |
1536 | ||
1537 | ``stats-rec-control-blacklist`` | |
1538 | ------------------------------- | |
1539 | .. versionadded:: 4.2.0 | |
1540 | ||
1541 | - String | |
5801b55c | 1542 | - Default: "cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*" |
563517f3 RG |
1543 | |
1544 | A list of comma-separated statistic names, that are disabled when retrieving the complete list of statistics via `rec_control get-all`, for performance reasons. | |
1545 | These statistics can still be retrieved individually. | |
1546 | ||
223bb49e PL |
1547 | .. _setting-stats-ringbuffer-entries: |
1548 | ||
1549 | ``stats-ringbuffer-entries`` | |
1550 | ---------------------------- | |
1551 | - Integer | |
1552 | - Default: 10000 | |
1553 | ||
1554 | Number of entries in the remotes ringbuffer, which keeps statistics on who is querying your server. | |
1555 | Can be read out using ``rec_control top-remotes``. | |
1556 | ||
563517f3 RG |
1557 | .. _setting-stats-snmp-blacklist: |
1558 | ||
1559 | ``stats-snmp-blacklist`` | |
1560 | ------------------------ | |
1561 | .. versionadded:: 4.2.0 | |
1562 | ||
1563 | - String | |
5801b55c | 1564 | - Default: "cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*" |
563517f3 RG |
1565 | |
1566 | A list of comma-separated statistic names, that are prevented from being exported via SNMP, for performance reasons. | |
1567 | ||
223bb49e PL |
1568 | .. _setting-tcp-fast-open: |
1569 | ||
1570 | ``tcp-fast-open`` | |
1571 | ----------------- | |
1572 | .. versionadded:: 4.1.0 | |
1573 | ||
1574 | - Integer | |
1575 | - Default: 0 (Disabled) | |
1576 | ||
1577 | Enable TCP Fast Open support, if available, on the listening sockets. | |
1578 | The numerical value supplied is used as the queue size, 0 meaning disabled. | |
1579 | ||
1580 | .. _setting-threads: | |
1581 | ||
1582 | ``threads`` | |
1583 | ----------- | |
1584 | - Integer | |
1585 | - Default: 2 | |
1586 | ||
1587 | Spawn this number of threads on startup. | |
1588 | ||
1589 | .. _setting-trace: | |
1590 | ||
1591 | ``trace`` | |
1592 | --------- | |
1593 | - Boolean | |
1594 | - Default: no | |
1595 | ||
1596 | If turned on, output impressive heaps of logging. | |
1597 | May destroy performance under load. | |
1598 | ||
b47026fd CHB |
1599 | .. _setting-udp-source-port-min: |
1600 | ||
1601 | ``udp-source-port-min`` | |
1602 | ----------------------- | |
1603 | .. versionadded:: 4.2.0 | |
1604 | ||
1605 | - Integer | |
58da9034 | 1606 | - Default: 1024 |
b47026fd CHB |
1607 | |
1608 | This option sets the low limit of UDP port number to bind on. | |
1609 | ||
1610 | In combination with `udp-source-port-max`_ it configures the UDP | |
1611 | port range to use. Port numbers are randomized within this range on | |
1612 | initialization, and exceptions can be configured with `udp-source-port-avoid`_ | |
1613 | ||
1614 | .. _setting-udp-source-port-max: | |
1615 | ||
1616 | ``udp-source-port-max`` | |
1617 | ----------------------- | |
1618 | .. versionadded:: 4.2.0 | |
1619 | ||
1620 | - Integer | |
1621 | - Default: 65535 | |
1622 | ||
1623 | This option sets the maximum limit of UDP port number to bind on. | |
1624 | ||
1625 | See `udp-source-port-min`_. | |
1626 | ||
1627 | .. _setting-udp-source-port-avoid: | |
1628 | ||
1629 | ``udp-source-port-avoid`` | |
1630 | ------------------------- | |
1631 | .. versionadded:: 4.2.0 | |
1632 | ||
1633 | - String | |
1634 | - Default: 11211 | |
1635 | ||
1636 | A list of comma-separated UDP port numbers to avoid when binding. | |
1637 | Ex: `5300,11211` | |
1638 | ||
1639 | See `udp-source-port-min`_. | |
1640 | ||
223bb49e PL |
1641 | .. _setting-udp-truncation-threshold: |
1642 | ||
1643 | ``udp-truncation-threshold`` | |
1644 | ---------------------------- | |
54c36063 PL |
1645 | .. versionchanged:: 4.2.0 |
1646 | Before 4.2.0, the default was 1680 | |
1647 | ||
223bb49e | 1648 | - Integer |
54c36063 | 1649 | - Default: 1232 |
223bb49e PL |
1650 | |
1651 | EDNS0 allows for large UDP response datagrams, which can potentially raise performance. | |
1652 | Large responses however also have downsides in terms of reflection attacks. | |
1653 | This setting limits the accepted size. | |
1654 | Maximum value is 65535, but values above 4096 should probably not be attempted. | |
1655 | ||
54c36063 PL |
1656 | To know why 1232, see the note at :ref:`setting-edns-outgoing-bufsize`. |
1657 | ||
a0ce6b10 PL |
1658 | .. _setting-unique-response-tracking: |
1659 | ||
1660 | ``unique-response-tracking`` | |
1661 | ---------------------------- | |
1662 | .. versionadded:: 4.2.0 | |
1663 | ||
1664 | - Boolean | |
1665 | - Default: no (disabled) | |
1666 | ||
1667 | Whether to track unique DNS responses, i.e. never seen before combinations | |
1668 | of the triplet (query name, query type, RR[rrname, rrtype, rrdata]). | |
fd47d762 | 1669 | This can be useful for tracking potentially suspicious domains and |
a0ce6b10 PL |
1670 | behaviour, e.g. DNS fast-flux. |
1671 | If protobuf is enabled and configured, then the Protobuf Response message | |
1672 | will contain a flag with udr set to true for each RR that is considered | |
1673 | unique, i.e. never seen before. | |
1674 | This feature uses a probabilistic data structure (stable bloom filter) to | |
1675 | track unique responses, which can have false positives as well as false | |
1676 | negatives, thus it is a best-effort feature. Increasing the number of cells | |
1677 | in the SBF using the unique-response-db-size setting can reduce FPs and FNs. | |
1678 | ||
1679 | .. _setting-unique-response-log: | |
1680 | ||
1681 | ``unique-response-log`` | |
1682 | ----------------------- | |
1683 | .. versionadded:: 4.2.0 | |
1684 | ||
1685 | - Boolean | |
1686 | - Default: no (disabled) | |
1687 | ||
1688 | Whether to log when a unique response is detected. The log line | |
1689 | looks something like: | |
1690 | ||
1691 | Oct 24 12:11:27 Unique response observed: qname=foo.com qtype=A rrtype=AAAA rrname=foo.com rrcontent=1.2.3.4 | |
1692 | ||
1693 | .. _setting-unique-response-db-size: | |
1694 | ||
1695 | ``unique-response-db-size`` | |
1696 | --------------------------- | |
1697 | .. versionadded:: 4.2.0 | |
1698 | ||
1699 | - Integer | |
1700 | - Example: 67108864 | |
1701 | ||
1702 | The default size of the stable bloom filter used to store previously | |
1703 | observed responses is 67108864. To change the number of cells, use this | |
1704 | setting. For each cell, the SBF uses 1 bit of memory, and one byte of | |
1705 | disk for the persistent file. | |
fd47d762 | 1706 | If there are already persistent files saved to disk, this setting will |
a0ce6b10 PL |
1707 | have no effect unless you remove the existing files. |
1708 | ||
1709 | .. _setting-unique-response-history-dir: | |
1710 | ||
1711 | ``unique-response-history-dir`` | |
1712 | ------------------------------- | |
1713 | .. versionadded:: 4.2.0 | |
1714 | ||
1715 | - Path | |
1716 | ||
1717 | This setting controls which directory is used to store the on-disk | |
1718 | cache of previously observed responses. | |
1719 | ||
1720 | The default depends on ``LOCALSTATEDIR`` when building the software. | |
1721 | Usually this comes down to ``/var/lib/pdns-recursor/udr`` or ``/usr/local/var/lib/pdns-recursor/udr``). | |
1722 | ||
1723 | The newly observed domain feature uses a stable bloom filter to store | |
1724 | a history of previously observed responses. The data structure is | |
1725 | synchronized to disk every 10 minutes, and is also initialized from | |
1726 | disk on startup. This ensures that previously observed responses are | |
fd47d762 | 1727 | preserved across recursor restarts. If you change the |
a0ce6b10 PL |
1728 | unique-response-db-size, you must remove any files from this directory. |
1729 | ||
1730 | .. _setting-unique-response-pb-tag: | |
1731 | ||
1732 | ``unique-response-pb-tag`` | |
1733 | -------------------------- | |
1734 | .. versionadded:: 4.2.0 | |
1735 | ||
1736 | - String | |
1737 | - Default: pnds-udr | |
1738 | ||
1739 | If protobuf is configured, then this tag will be added to all protobuf response messages when | |
fd47d762 | 1740 | a unique DNS response is observed. |
a0ce6b10 | 1741 | |
223bb49e PL |
1742 | .. _setting-use-incoming-edns-subnet: |
1743 | ||
1744 | ``use-incoming-edns-subnet`` | |
1745 | ---------------------------- | |
1746 | - Boolean | |
1747 | - Default: no | |
1748 | ||
1749 | Whether to process and pass along a received EDNS Client Subnet to authoritative servers. | |
1750 | 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. | |
1751 | ||
1752 | .. _setting-version: | |
1753 | ||
1754 | ``version`` | |
1755 | ----------- | |
1756 | Print version of this binary. Useful for checking which version of the PowerDNS recursor is installed on a system. | |
1757 | ||
1758 | .. _setting-version-string: | |
1759 | ||
1760 | ``version-string`` | |
1761 | ------------------ | |
1762 | - String | |
1763 | - Default: PowerDNS Recursor version number | |
1764 | ||
1765 | By default, PowerDNS replies to the 'version.bind' query with its version number. | |
1766 | Security conscious users may wish to override the reply PowerDNS issues. | |
1767 | ||
1768 | .. _setting-webserver: | |
1769 | ||
1770 | ``webserver`` | |
1771 | ------------- | |
1772 | - Boolean | |
1773 | - Default: no | |
1774 | ||
1775 | Start the webserver (for REST API). | |
1776 | ||
1777 | .. _setting-webserver-address: | |
1778 | ||
1779 | ``webserver-address`` | |
1780 | --------------------- | |
4f66776f | 1781 | - IP Address |
223bb49e PL |
1782 | - Default: 127.0.0.1 |
1783 | ||
1784 | IP address for the webserver to listen on. | |
1785 | ||
1786 | .. _setting-webserver-allow-from: | |
1787 | ||
1788 | ``webserver-allow-from`` | |
1789 | ------------------------ | |
1790 | - IP addresses, comma separated | |
be3e1477 RG |
1791 | - Default: 127.0.0.1,::1 |
1792 | ||
1793 | .. versionchanged:: 4.1.0 | |
1794 | ||
1795 | Default is now 127.0.0.1,::1, was 0.0.0.0,::/0 before. | |
223bb49e PL |
1796 | |
1797 | These subnets are allowed to access the webserver. | |
1798 | ||
a0badc0b PL |
1799 | .. _setting-webserver-loglevel: |
1800 | ||
1801 | ``webserver-loglevel`` | |
1802 | ---------------------- | |
1803 | .. versionadded:: 4.2.0 | |
1804 | ||
1805 | - String, one of "none", "normal", "detailed" | |
1806 | ||
1807 | The amount of logging the webserver must do. "none" means no useful webserver information will be logged. | |
1808 | When set to "normal", the webserver will log a line per request that should be familiar:: | |
1809 | ||
1810 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e 127.0.0.1:55376 "GET /api/v1/servers/localhost/bla HTTP/1.1" 404 196 | |
1811 | ||
1812 | When set to "detailed", all information about the request and response are logged:: | |
1813 | ||
1814 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e Request Details: | |
1815 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e Headers: | |
1816 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 | |
1817 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e accept-encoding: gzip, deflate | |
1818 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e accept-language: en-US,en;q=0.5 | |
1819 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e connection: keep-alive | |
1820 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e dnt: 1 | |
1821 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e host: 127.0.0.1:8081 | |
1822 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e upgrade-insecure-requests: 1 | |
1823 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e user-agent: Mozilla/5.0 (X11; Linux x86_64; rv:64.0) Gecko/20100101 Firefox/64.0 | |
1824 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e No body | |
1825 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e Response details: | |
1826 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e Headers: | |
1827 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e Connection: close | |
1828 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e Content-Length: 49 | |
1829 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e Content-Type: text/html; charset=utf-8 | |
1830 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e Server: PowerDNS/0.0.15896.0.gaba8bab3ab | |
1831 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e Full body: | |
1832 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e <!html><title>Not Found</title><h1>Not Found</h1> | |
1833 | [webserver] e235780e-a5cf-415e-9326-9d33383e739e 127.0.0.1:55376 "GET /api/v1/servers/localhost/bla HTTP/1.1" 404 196 | |
1834 | ||
1835 | The value between the hooks is a UUID that is generated for each request. This can be used to find all lines related to a single request. | |
1836 | ||
1837 | .. note:: | |
1838 | The webserver logs these line on the NOTICE level. The :ref:`settings-loglevel` seting must be 5 or higher for these lines to end up in the log. | |
1839 | ||
223bb49e PL |
1840 | .. _setting-webserver-password: |
1841 | ||
1842 | ``webserver-password`` | |
1843 | ---------------------- | |
1844 | - String | |
1845 | - Default: unset | |
1846 | ||
1847 | Password required to access the webserver. | |
1848 | ||
1849 | .. _setting-webserver-port: | |
1850 | ||
1851 | ``webserver-port`` | |
1852 | ------------------ | |
1853 | - Integer | |
1854 | - Default: 8082 | |
1855 | ||
1856 | TCP port where the webserver should listen on. | |
1857 | ||
1858 | .. _setting-write-pid: | |
1859 | ||
1860 | ``write-pid`` | |
1861 | ------------- | |
1862 | - Boolean | |
1863 | - Default: yes | |
1864 | ||
1865 | If a PID file should be written to `socket-dir`_ | |
5cc8371b | 1866 | |
59cb4a79 PL |
1867 | .. _setting-xpf-allow-from: |
1868 | ||
5cc8371b | 1869 | ``xpf-allow-from`` |
59cb4a79 PL |
1870 | ------------------ |
1871 | .. versionadded:: 4.2.0 | |
5cc8371b RG |
1872 | |
1873 | - IP ranges, separated by commas | |
1874 | - Default: empty | |
1875 | ||
59cb4a79 PL |
1876 | .. note:: |
1877 | This is an experimental implementation of `draft-bellis-dnsop-xpf <https://datatracker.ietf.org/doc/draft-bellis-dnsop-xpf/>`_. | |
1878 | ||
5cc8371b RG |
1879 | The server will trust XPF records found in queries sent from those netmasks (both IPv4 and IPv6), |
1880 | and will adjust queries' source and destination accordingly. This is especially useful when the recursor | |
59cb4a79 | 1881 | is placed behind a proxy like `dnsdist <https://dnsdist.org>`_. |
4e031caf | 1882 | Note that the :ref:`setting-allow-from` setting is still applied to the original source address, and thus access restriction |
5cc8371b | 1883 | should be done on the proxy. |
18f707fa | 1884 | |
59cb4a79 PL |
1885 | .. _setting-xpf-rr-code: |
1886 | ||
1887 | ``xpf-rr-code`` | |
c8dbb9f7 | 1888 | --------------- |
59cb4a79 | 1889 | .. versionadded:: 4.2.0 |
18f707fa RG |
1890 | |
1891 | - Integer | |
1892 | - Default: 0 | |
1893 | ||
59cb4a79 PL |
1894 | .. note:: |
1895 | This is an experimental implementation of `draft-bellis-dnsop-xpf <https://datatracker.ietf.org/doc/draft-bellis-dnsop-xpf/>`_. | |
1896 | ||
1897 | This option sets the resource record code to use for XPF records, as long as an official code has not been assigned to it. | |
1898 | 0 means that XPF is disabled. |