forked from PowerDNS/pdns
/
table.py
3115 lines (2995 loc) · 161 KB
/
table.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# This file contains the table used to generate old and new-style settings code
#
# Example:
# {
# 'name' : 'allow_from',
# 'section' : 'incoming',
# 'oldname' : 'allow-from'
# 'type' : LType.ListSubnets,
# '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',
# 'help' : 'If set, only allow these comma separated netmasks to recurse',
# 'doc' : '''
# '''
# }
#
# See generate.py for a description of the fields.
#
# Sections
# - incoming
# - outgoing
# - packetcache
# - recursor
# - recordcache
# - dnssec
# - webservice
# - carbon
# - ecs
# - logging
# - nod
# - snmp
[
{
'name' : 'aggressive_nsec_cache_size',
'section' : 'dnssec',
'type' : LType.Uint64,
'default' : '100000',
'help' : 'The number of records to cache in the aggressive cache. If set to a value greater than 0, and DNSSEC processing or validation is enabled, the recursor will cache NSEC and NSEC3 records to generate negative answers, as defined in rfc8198',
'doc' : '''
The number of records to cache in the aggressive cache. If set to a value greater than 0, the recursor will cache NSEC and NSEC3 records to generate negative answers, as defined in :rfc:`8198`.
To use this, DNSSEC processing or validation must be enabled by setting :ref:`setting-dnssec` to ``process``, ``log-fail`` or ``validate``.
''',
'versionadded': '4.5.0',
},
{
'name' : 'aggressive_cache_min_nsec3_hit_ratio',
'section' : 'dnssec',
'type' : LType.Uint64,
'default' : '2000',
'help' : 'The minimum expected hit ratio to store NSEC3 records into the aggressive cache',
'doc' : '''
The limit for which to put NSEC3 records into the aggressive cache.
A value of ``n`` means that an NSEC3 record is only put into the aggressive cache if the estimated probability of a random name hitting the NSEC3 record is higher than ``1/n``.
A higher ``n`` will cause more records to be put into the aggressive cache, e.g. a value of 4000 will cause records to be put in the aggressive cache even if the estimated probability of hitting them is twice as low as would be the case for ``n=2000``.
A value of 0 means no NSEC3 records will be put into the aggressive cache.
For large zones the effectiveness of the NSEC3 cache is reduced since each NSEC3 record only covers a randomly distributed subset of all possible names.
This setting avoids doing unnecessary work for such large zones.
''',
'versionadded' : '4.9.0',
},
{
'name' : 'allow_from',
'section' : 'incoming',
'type' : LType.ListSubnets,
'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',
'help' : 'If set, only allow these comma separated netmasks to recurse',
'doc' : '''
Netmasks (both IPv4 and IPv6) that are allowed to use the server.
The default allows access only from :rfc:`1918` private IP addresses.
An empty value means no checking is done, all clients are allowed.
Due to the aggressive nature of the internet these days, it is highly recommended to not open up the recursor for the entire internet.
Questions from IP addresses not listed here are ignored and do not get an answer.
When the Proxy Protocol is enabled (see :ref:`setting-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.
Note that specifying an IP address without a netmask uses an implicit netmask of /32 or /128.
''',
},
{
'name' : 'allow_from_file',
'section' : 'incoming',
'type' : LType.String,
'default' : '',
'help' : 'If set, load allowed netmasks from this file',
'doc' : '''
Like :ref:`setting-allow-from`, except reading from file.
Overrides the :ref:`setting-allow-from` setting. To use this feature, supply one netmask per line, with optional comments preceded by a '#'.
''',
'doc-new' : '''
Like :ref:`setting-allow-from`, except reading a sequence of `Subnet`_ from file.
Overrides the :ref:`setting-allow-from` setting. Example content of th specified file:
.. code-block:: yaml
- 127.0.01
- ::1
''',
},
{
'name' : 'allow_notify_for',
'section' : 'incoming',
'type' : LType.ListStrings,
'default' : '',
'help' : 'If set, NOTIFY requests for these zones will be allowed',
'doc' : '''
Domain names specified in this list are used to permit incoming
NOTIFY operations to wipe any cache entries that match the domain
name. If this list is empty, all NOTIFY operations will be ignored.
''',
'versionadded': '4.6.0'
},
{
'name' : 'allow_notify_for_file',
'section' : 'incoming',
'type' : LType.String,
'default' : '',
'help' : 'If set, load NOTIFY-allowed zones from this file',
'doc' : '''
Like :ref:`setting-allow-notify-for`, except reading from file. To use this
feature, supply one domain name per line, with optional comments
preceded by a '#'.
NOTIFY-allowed zones can also be specified using :ref:`setting-forward-zones-file`.
''',
'doc-new' : '''
Like :ref:`setting-allow-notify-for`, except reading a sequence of names from file. Example contents of specified file:
.. code-block:: yaml
- example.com
- example.org
''',
'versionadded': '4.6.0'
},
{
'name' : 'allow_notify_from',
'section' : 'incoming',
'type' : LType.ListSubnets,
'default' : '',
'help' : 'If set, NOTIFY requests from these comma separated netmasks will be allowed',
'doc' : '''
Netmasks (both IPv4 and IPv6) that are allowed to issue NOTIFY operations
to the server. NOTIFY operations from IP addresses not listed here are
ignored and do not get an answer.
When the Proxy Protocol is enabled (see :ref:`setting-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.
Note that specifying an IP address without a netmask uses an implicit
netmask of /32 or /128.
NOTIFY operations received from a client listed in one of these netmasks
will be accepted and used to wipe any cache entries whose zones match
the zone specified in the NOTIFY operation, but only if that zone (or
one of its parents) is included in :ref:`setting-allow-notify-for`,
:ref:`setting-allow-notify-for-file`, or :ref:`setting-forward-zones-file` with a '^' prefix.
''',
'doc-new' : '''
Subnets (both IPv4 and IPv6) that are allowed to issue NOTIFY operations
to the server. NOTIFY operations from IP addresses not listed here are
ignored and do not get an answer.
When the Proxy Protocol is enabled (see :ref:`setting-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.
Note that specifying an IP address without a netmask uses an implicit
netmask of /32 or /128.
NOTIFY operations received from a client listed in one of these netmasks
will be accepted and used to initiate a freshness check for an RPZ zone or wipe any cache entries whose zones match
the zone specified in the NOTIFY operation, but only if that zone (or
one of its parents) is included in :ref:`setting-allow-notify-for`,
:ref:`setting-allow-notify-for-file`, or :ref:`setting-forward-zones-file` with a ``allow_notify`` set to ``true``.
''',
'versionadded': '4.6.0'
},
{
'name' : 'allow_notify_from_file',
'section' : 'incoming',
'type' : LType.String,
'default' : '',
'help' : 'If set, load NOTIFY-allowed netmasks from this file',
'doc' : '''
Like :ref:`setting-allow-notify-from`, except reading from file. To use this
feature, supply one netmask per line, with optional comments preceded
by a '#'.
''',
'doc-new' : '''
Like :ref:`setting-allow-notify-from`, except reading a sequence of `Subnet`_ from file.
''',
'versionadded': '4.6.0'
},
{
'name' : 'allow_no_rd',
'section' : 'incoming',
'type' : LType.Bool,
'default' : 'false',
'help' : 'Allow \'no recursion desired (RD=0)\' queries.',
'doc' : '''
Allow ``no recursion desired (RD=0) queries`` to query cache contents.
If not set (the default), these queries are answered with rcode ``Refused``.
''',
'versionadded': '5.0.0'
},
{
'name' : 'any_to_tcp',
'section' : 'recursor',
'type' : LType.Bool,
'default' : 'false',
'help' : 'Answer ANY queries with tc=1, shunting to TCP',
'doc' : '''
Answer questions for the ANY type on UDP with a truncated packet that refers the remote server to TCP.
Useful for mitigating ANY reflection attacks.
''',
},
{
'name' : 'allow_trust_anchor_query',
'section' : 'recursor',
'type' : LType.Bool,
'default' : 'false',
'help' : 'Allow queries for trustanchor.server CH TXT and negativetrustanchor.server CH TXT',
'doc' : '''
Allow ``trustanchor.server CH TXT`` and ``negativetrustanchor.server CH TXT`` queries to view the configured :doc:`DNSSEC <dnssec>` (negative) trust anchors.
''',
'versionadded': '4.3.0'
},
{
'name' : 'api_dir',
'section' : 'webservice',
'oldname' : 'api-config-dir',
'type' : LType.String,
'default' : '',
'help' : 'Directory where REST API stores config and zones',
'doc' : '''
Directory where the REST API stores its configuration and zones.
For configuration updates to work, :ref:`setting-include-dir` should have the same value when using old-style settings.
When using YAML settings :ref:`setting-yaml-recursor.include_dir` and :ref:`setting-yaml-webservice.api_dir` must have a different value.
''',
'versionadded': '4.0.0'
},
{
'name' : 'api_key',
'section' : 'webservice',
'type' : LType.String,
'default' : '',
'help' : 'Static pre-shared authentication key for access to the REST API',
'doc' : '''
Static pre-shared authentication key for access to the REST API. Since 4.6.0 the key can be hashed and salted using ``rec_control hash-password`` instead of being stored in the configuration in plaintext, but the plaintext version is still supported.
''',
'versionadded': '4.0.0',
'versionchanged': ('4.6.0', 'This setting now accepts a hashed and salted version.')
},
{
'name' : 'auth_zones',
'section' : 'recursor',
'type' : LType.ListAuthZones,
'default' : '',
'help' : 'Zones for which we have authoritative data, comma separated domain=file pairs',
'doc' : '''
Zones read from these files (in BIND format) are served authoritatively (but without the AA bit set in responses).
DNSSEC is not supported. Example:
.. code-block:: none
auth-zones=example.org=/var/zones/example.org, powerdns.com=/var/zones/powerdns.com
''',
'doc-new' : '''
Zones read from these files (in BIND format) are served authoritatively (but without the AA bit set in responses).
DNSSEC is not supported. Example:
.. code-block:: yaml
recursor:
auth-zones:
- zone: example.org
file: /var/zones/example.org
- zone: powerdns.com
file: /var/zones/powerdns.com
''',
},
{
'name' : 'interval',
'section' : 'carbon',
'oldname' : 'carbon-interval',
'type' : LType.Uint64,
'default' : '30',
'help' : 'Number of seconds between carbon (graphite) updates',
'doc' : '''
If sending carbon updates, this is the interval between them in seconds.
See :doc:`metrics`.
''',
},
{
'name' : 'ns',
'section' : 'carbon',
'oldname' : 'carbon-namespace',
'type' : LType.String,
'default' : 'pdns',
'help' : 'If set overwrites the first part of the carbon string',
'doc' : '''
Change the namespace or first string of the metric key. The default is pdns.
''',
'versionadded': '4.2.0'
},
{
'name' : 'ourname',
'section' : 'carbon',
'oldname' : 'carbon-ourname',
'type' : LType.String,
'default' : '',
'help' : 'If set, overrides our reported hostname for carbon stats',
'doc' : '''
If sending carbon updates, if set, this will override our hostname.
Be careful not to include any dots in this setting, unless you know what you are doing.
See :ref:`metricscarbon`.
''',
},
{
'name' : 'instance',
'section' : 'carbon',
'oldname' : 'carbon-instance',
'type' : LType.String,
'default' : 'recursor',
'help' : 'If set overwrites the instance name default',
'doc' : '''
Change the instance or third string of the metric key. The default is recursor.
''',
'versionadded': '4.2.0'
},
{
'name' : 'server',
'section' : 'carbon',
'oldname' : 'carbon-server',
'type' : LType.ListSocketAddresses,
'default' : '',
'help' : 'If set, send metrics in carbon (graphite) format to this server IP address',
'doc' : '''
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.
You may specify an alternate port by appending :port, for example: ``127.0.0.1:2004``.
See :doc:`metrics`.
''',
'doc-new' : '''
Will send all available metrics to these servers via the carbon protocol, which is used by graphite and metronome.
See :doc:`metrics`.
''',
},
{
'name' : 'chroot',
'section' : 'recursor',
'type' : LType.String,
'default' : '',
'help' : 'switch to chroot jail',
'doc' : '''
If set, chroot to this directory for more security.
This is not recommended; instead, we recommend containing PowerDNS using operating system features.
We ship systemd unit files with our packages to make this easy.
Make sure that ``/dev/log`` is available from within the chroot.
Logging will silently fail over time otherwise (on logrotate).
When using ``chroot``, all other paths (except for :ref:`setting-config-dir`) set in the configuration are relative to the new root.
When running on a system where systemd manages services, ``chroot`` does not work out of the box, as PowerDNS cannot use the ``NOTIFY_SOCKET``.
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).
''',
},
{
'name' : 'tcp_timeout',
'section' : 'incoming',
'oldname' : 'client-tcp-timeout',
'type' : LType.Uint64,
'default' : '2',
'help' : 'Timeout in seconds when talking to TCP clients',
'doc' : '''
Time to wait for data from TCP clients.
''',
},
{
'name' : 'config',
'section' : 'commands',
'type' : LType.Command,
'default' : 'no',
'help' : 'Output blank configuration. You can use --config=check to test the config file and command line arguments.',
'doc' : '''
EMPTY? '''
},
{
'name' : 'config_dir',
'section' : 'recursor',
'type' : LType.String,
'default' : 'SYSCONFDIR',
'docdefault': 'Determined by distribution',
'help' : 'Location of configuration directory (recursor.conf or recursor.yml)',
'doc' : '''
Location of configuration directory (where ``recursor.conf`` or ``recursor.yml`` is stored).
Usually ``/etc/powerdns``, but this depends on ``SYSCONFDIR`` during compile-time.
Use default or set on command line.
''',
},
{
'name' : 'config_name',
'section' : 'recursor',
'type' : LType.String,
'default' : '',
'help' : 'Name of this virtual configuration - will rename the binary image',
'doc' : '''
When running multiple recursors on the same server, read settings from :file:`recursor-{name}.conf`, this will also rename the binary image.
''',
},
{
'name' : 'cpu_map',
'section' : 'recursor',
'type' : LType.String,
'default' : '',
'help' : 'Thread to CPU mapping, space separated thread-id=cpu1,cpu2..cpuN pairs',
'doc' : '''
Set CPU affinity for threads, asking the scheduler to run those threads on a single CPU, or a set of CPUs.
This parameter accepts a space separated list of thread-id=cpu-id, or thread-id=cpu-id-1,cpu-id-2,...,cpu-id-N.
For example, to make the worker thread 0 run on CPU id 0 and the worker thread 1 on CPUs 1 and 2::
cpu-map=0=0 1=1,2
The thread handling the control channel, the webserver and other internal stuff has been assigned id 0, the distributor
threads if any are assigned id 1 and counting, and the worker threads follow behind.
The number of distributor threads is determined by :ref:`setting-distributor-threads`, the number of worker threads is determined by the :ref:`setting-threads` setting.
This parameter is only available if the OS provides the ``pthread_setaffinity_np()`` function.
Note that depending on the configuration the Recursor can start more threads.
Typically these threads will sleep most of the time.
These threads cannot be specified in this setting as their thread-ids are left unspecified.
''',
'doc' : '''
Set CPU affinity for threads, asking the scheduler to run those threads on a single CPU, or a set of CPUs.
This parameter accepts a space separated list of thread-id=cpu-id, or thread-id=cpu-id-1,cpu-id-2,...,cpu-id-N.
For example, to make the worker thread 0 run on CPU id 0 and the worker thread 1 on CPUs 1 and 2:
.. code-block:: yaml
recursor:
cpu_map: 0=0 1=1,2
The thread handling the control channel, the webserver and other internal stuff has been assigned id 0, the distributor
threads if any are assigned id 1 and counting, and the worker threads follow behind.
The number of distributor threads is determined by :ref:`setting-distributor-threads`, the number of worker threads is determined by the :ref:`setting-threads` setting.
This parameter is only available if the OS provides the ``pthread_setaffinity_np()`` function.
Note that depending on the configuration the Recursor can start more threads.
Typically these threads will sleep most of the time.
These threads cannot be specified in this setting as their thread-ids are left unspecified.
''',
},
{
'name' : 'daemon',
'section' : 'recursor',
'type' : LType.Bool,
'default' : 'false',
'help' : 'Operate as a daemon',
'doc' : '''
Operate in the background.
''',
'versionchanged': ('4.0.0', 'Default is now ``no``, was ``yes`` before.')
},
{
'name' : 'dont_throttle_names',
'section' : 'outgoing',
'type' : LType.ListStrings,
'default' : '',
'help' : 'Do not throttle nameservers with this name or suffix',
'doc' : '''
When an authoritative server does not answer a query or sends a reply the recursor does not like, it is throttled.
Any servers' name suffix-matching the supplied names will never be throttled.
.. warning::
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.
''',
'versionadded': '4.2.0'
},
{
'name' : 'dont_throttle_netmasks',
'section' : 'outgoing',
'type' : LType.ListSubnets,
'default' : '',
'help' : 'Do not throttle nameservers with this IP netmask',
'doc' : '''
When an authoritative server does not answer a query or sends a reply the recursor does not like, it is throttled.
Any servers matching the supplied netmasks will never be throttled.
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``).
By default, the PowerDNS Recursor would throttle the 'first' server on a timeout and hence not retry the 'second' one.
In this case, ``dont-throttle-netmasks`` could be set to ``192.0.2.1``.
.. warning::
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.
''',
'doc-new' : '''
When an authoritative server does not answer a query or sends a reply the recursor does not like, it is throttled.
Any servers matching the supplied netmasks will never be throttled.
This can come in handy on lossy networks when forwarding, where the same server is configured multiple times (e.g. with ``forward_zones_recurse: [ {zone: example.com, forwarders: [ 192.0.2.1, 192.0.2.1 ] } ]``.
By default, the PowerDNS Recursor would throttle the 'first' server on a timeout and hence not retry the 'second' one.
In this case, :ref:`setting-dont-throttle-netmasks` could be set to include ``192.0.2.1``.
.. warning::
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.
''',
'versionadded': '4.2.0'
},
{
'name' : 'devonly_regression_test_mode',
'section' : 'recursor',
'type' : LType.Bool,
'default' : 'false',
'help' : 'internal use only',
'doc' : 'SKIP',
},
{
'name' : 'disable',
'section' : 'packetcache',
'oldname' : 'disable-packetcache',
'type' : LType.Bool,
'default' : 'false',
'help' : 'Disable packetcache',
'doc' : '''
Turn off the packet cache. Useful when running with Lua scripts that cannot be cached, though individual query caching can be controlled from Lua as well.
''',
},
{
'name' : 'disable_syslog',
'section' : 'logging',
'type' : LType.Bool,
'default' : 'false',
'help' : 'Disable logging to syslog, useful when running inside a supervisor that logs stderr',
'doc' : '''
Do not log to syslog, only to stderr.
Use this setting when running inside a supervisor that handles logging (like systemd).
**Note**: do not use this setting in combination with :ref:`setting-daemon` as all logging will disappear.
''',
},
{
'name' : 'distribution_load_factor',
'section' : 'incoming',
'type' : LType.Double,
'default' : '0.0',
'help' : 'The load factor used when PowerDNS is distributing queries to worker threads',
'doc' : '''
If :ref:`setting-pdns-distributes-queries` is set and this setting is set to another value
than 0, the distributor thread will use a bounded load-balancing algorithm while
distributing queries to worker threads, making sure that no thread is assigned
more queries than distribution-load-factor times the average number of queries
currently processed by all the workers.
For example, with a value of 1.25, no server should get more than 125 % of the
average load. This helps making sure that all the workers have roughly the same
share of queries, even if the incoming traffic is very skewed, with a larger
number of requests asking for the same qname.
''',
'versionadded': '4.1.12'
},
{
'name' : 'distribution_pipe_buffer_size',
'section' : 'incoming',
'type' : LType.Uint64,
'default' : '0',
'help' : 'Size in bytes of the internal buffer of the pipe used by the distributor to pass incoming queries to a worker thread',
'doc' : '''
Size in bytes of the internal buffer of the pipe used by the distributor to pass incoming queries to a worker thread.
Requires support for `F_SETPIPE_SZ` which is present in Linux since 2.6.35. The actual size might be rounded up to
a multiple of a page size. 0 means that the OS default size is used.
A large buffer might allow the recursor to deal with very short-lived load spikes during which a worker thread gets
overloaded, but it will be at the cost of an increased latency.
''',
'versionadded': '4.2.0'
},
{
'name' : 'distributor_threads',
'section' : 'incoming',
'type' : LType.Uint64,
'default' : '0',
'docdefault' : '1 if :ref:`setting-pdns-distributes-queries` is set, 0 otherwise',
'help' : 'Launch this number of distributor threads, distributing queries to other threads',
'doc' : '''
If :ref:`setting-pdns-distributes-queries` is set, spawn this number of distributor threads on startup. Distributor threads
handle incoming queries and distribute them to other threads based on a hash of the query.
''',
'versionadded': '4.2.0'
},
{
'name' : 'dot_to_auth_names',
'section' : 'outgoing',
'type' : LType.ListStrings,
'default' : '',
'help' : 'Use DoT to authoritative servers with these names or suffixes',
'doc' : '''
Force DoT to the listed authoritative nameservers. For this to work, DoT support has to be compiled in.
Currently, the certificate is not checked for validity in any way.
''',
'versionadded': '4.6.0'
},
{
'name' : 'dot_to_port_853',
'section' : 'outgoing',
'type' : LType.Bool,
'default' : 'true',
'help' : 'Force DoT connection to target port 853 if DoT compiled in',
'doc' : '''
Enable DoT to forwarders that specify port 853.
''',
'versionadded': '4.6.0'
},
{
'name' : 'dns64_prefix',
'section' : 'recursor',
'type' : LType.String,
'default' : '',
'help' : 'DNS64 prefix',
'doc' : '''
Enable DNS64 (:rfc:`6147`) support using the supplied /96 IPv6 prefix. This will generate 'fake' ``AAAA`` records for names
with only ``A`` records, as well as 'fake' ``PTR`` records to make sure that reverse lookup of DNS64-generated IPv6 addresses
generate the right name.
See :doc:`dns64` for more flexible but slower alternatives using Lua.
''',
'versionadded': '4.4.0'
},
{
'name' : 'validation',
'section' : 'dnssec',
'oldname' : 'dnssec',
'type' : LType.String,
'default' : 'process',
'help' : 'DNSSEC mode: off/process-no-validate/process (default)/log-fail/validate',
'doc' : '''
One of ``off``, ``process-no-validate``, ``process``, ``log-fail``, ``validate``
Set the mode for DNSSEC processing, as detailed in :doc:`dnssec`.
``off``
No DNSSEC processing whatsoever.
Ignore DO-bits in queries, don't request any DNSSEC information from authoritative servers.
This behaviour is similar to PowerDNS Recursor pre-4.0.
``process-no-validate``
Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries.
Don't do any validation.
``process``
Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries.
Do validation for clients that request it (by means of the AD- bit or DO-bit in the query).
``log-fail``
Similar behaviour to ``process``, but validate RRSIGs on responses and log bogus responses.
``validate``
Full blown DNSSEC validation. Send SERVFAIL to clients on bogus responses.
''',
'versionadded': '4.0.0',
'versionchanged': ('4.5.0',
'The default changed from ``process-no-validate`` to ``process``')
},
{
'name' : 'disabled_algorithms',
'section' : 'dnssec',
'oldname' : 'dnssec-disabled-algorithms',
'type' : LType.ListStrings,
'default' : '',
'help' : 'List of DNSSEC algorithm numbers that are considered unsupported',
'doc' : '''
A list of DNSSEC algorithm numbers that should be considered disabled.
These algorithms will not be used to validate DNSSEC signatures.
Zones (only) signed with these algorithms will be considered ``Insecure``.
If this setting is empty (the default), :program:`Recursor` will determine which algorithms to disable automatically.
This is done for specific algorithms only, currently algorithms 5 (``RSASHA1``) and 7 (``RSASHA1NSEC3SHA1``).
This is important on systems that have a default strict crypto policy, like RHEL9 derived systems.
On such systems not disabling some algorithms (or changing the security policy) will make affected zones to be considered ``Bogus`` as using these algorithms fails.
''',
'versionadded': '4.9.0'
},
{
'name' : 'log_bogus',
'section' : 'dnssec',
'oldname' : 'dnssec-log-bogus',
'type' : LType.Bool,
'default' : 'false',
'help' : 'Log DNSSEC bogus validations',
'doc' : '''
Log every DNSSEC validation failure.
**Note**: This is not logged per-query but every time records are validated as Bogus.
''',
},
{
'name' : 'dont_query',
'section' : 'outgoing',
'type' : LType.ListSubnets,
'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',
'help' : 'If set, do not query these netmasks for DNS data',
'doc' : '''
The DNS is a public database, but sometimes contains delegations to private IP addresses, like for example 127.0.0.1.
This can have odd effects, depending on your network, and may even be a security risk.
Therefore, the PowerDNS Recursor by default does not query private space IP addresses.
This setting can be used to expand or reduce the limitations.
Queries for names in forward zones and to addresses as configured in any of the settings :ref:`setting-forward-zones`, :ref:`setting-forward-zones-file` or :ref:`setting-forward-zones-recurse` are performed regardless of these limitations.
''',
},
{
'name' : 'add_for',
'section' : 'ecs',
'oldname' : 'ecs-add-for',
'type' : LType.ListSubnets,
'default' : '0.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',
'help' : 'List of client netmasks for which EDNS Client Subnet will be added',
'doc' : '''
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 :ref:`setting-ecs-scope-zero-address` instead.
Valid incoming ECS values from :ref:`setting-use-incoming-edns-subnet` are not replaced.
Regardless of the value of this setting, ECS values are only sent for outgoing queries matching the conditions in the :ref:`setting-edns-subnet-allow-list` setting. This setting only controls the actual value being sent.
This defaults to not using the requestor address inside RFC1918 and similar 'private' IP address spaces.
''',
'versionadded': '4.2.0'
},
{
'name' : 'ipv4_bits',
'section' : 'ecs',
'oldname' : 'ecs-ipv4-bits',
'type' : LType.Uint64,
'default' : '24',
'help' : 'Number of bits of IPv4 address to pass for EDNS Client Subnet',
'doc' : '''
Number of bits of client IPv4 address to pass when sending EDNS Client Subnet address information.
''',
'versionadded': '4.1.0'
},
{
'name' : 'ipv4_cache_bits',
'section' : 'ecs',
'oldname' : 'ecs-ipv4-cache-bits',
'type' : LType.Uint64,
'default' : '24',
'help' : 'Maximum number of bits of IPv4 mask to cache ECS response',
'doc' : '''
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``.
That is, only if both the limits apply, the record will not be cached. This decision can be overridden by ``ecs-ipv4-never-cache`` and ``ecs-ipv6-never-cache``.
''',
'versionadded': '4.1.12'
},
{
'name' : 'ipv6_bits',
'section' : 'ecs',
'oldname' : 'ecs-ipv6-bits',
'type' : LType.Uint64,
'default' : '56',
'help' : 'Number of bits of IPv6 address to pass for EDNS Client Subnet',
'doc' : '''
Number of bits of client IPv6 address to pass when sending EDNS Client Subnet address information.
''',
'versionadded': '4.1.0'
},
{
'name' : 'ipv6_cache_bits',
'section' : 'ecs',
'oldname' : 'ecs-ipv6-cache-bits',
'type' : LType.Uint64,
'default' : '56',
'help' : 'Maximum number of bits of IPv6 mask to cache ECS response',
'doc' : '''
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``.
That is, only if both the limits apply, the record will not be cached. This decision can be overridden by ``ecs-ipv4-never-cache`` and ``ecs-ipv6-never-cache``.
''',
'versionadded': '4.1.12'
},
{
'name' : 'ipv4_never_cache',
'section' : 'ecs',
'oldname' : 'ecs-ipv4-never-cache',
'type' : LType.Bool,
'default' : 'false',
'help' : 'If we should never cache IPv4 ECS responses',
'doc' : '''
When set, never cache replies carrying EDNS IPv4 Client Subnet scope in the record cache.
In this case the decision made by ```ecs-ipv4-cache-bits`` and ``ecs-cache-limit-ttl`` is no longer relevant.
''',
'versionadded': '4.5.0'
},
{
'name' : 'ipv6_never_cache',
'section' : 'ecs',
'oldname' : 'ecs-ipv6-never-cache',
'type' : LType.Bool,
'default' : 'false',
'help' : 'If we should never cache IPv6 ECS responses',
'doc' : '''
When set, never cache replies carrying EDNS IPv6 Client Subnet scope in the record cache.
In this case the decision made by ```ecs-ipv6-cache-bits`` and ``ecs-cache-limit-ttl`` is no longer relevant.
''',
'versionadded': '4.5.0'
},
{
'name' : 'minimum_ttl_override',
'section' : 'ecs',
'oldname' : 'ecs-minimum-ttl-override',
'type' : LType.Uint64,
'default' : '1',
'help' : 'The minimum TTL for records in ECS-specific answers',
'doc' : '''
This setting artificially raises the TTLs of records in the ANSWER section of ECS-specific answers to be at least this long.
Setting this to a value greater than 1 technically is an RFC violation, but might improve performance a lot.
Using a value of 0 impacts performance of TTL 0 records greatly, since it forces the recursor to contact
authoritative servers every time a client requests them.
Can be set at runtime using ``rec_control set-ecs-minimum-ttl 3600``.
''',
'versionchanged': ('4.5.0', 'Old versions used default 0.')
},
{
'name' : 'cache_limit_ttl',
'section' : 'ecs',
'oldname' : 'ecs-cache-limit-ttl',
'type' : LType.Uint64,
'default' : '0',
'help' : 'Minimum TTL to cache ECS response',
'doc' : '''
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``.
That is, only if both the limits apply, the record will not be cached. This decision can be overridden by ``ecs-ipv4-never-cache`` and ``ecs-ipv6-never-cache``.
''',
'versionadded': '4.1.12'
},
{
'name' : 'scope_zero_address',
'section' : 'ecs',
'oldname' : 'ecs-scope-zero-address',
'type' : LType.String,
'default' : '',
'help' : 'Address to send to allow-listed authoritative servers for incoming queries with ECS prefix-length source of 0',
'doc' : '''
The IP address sent via EDNS Client Subnet to authoritative servers listed in
:ref:`setting-edns-subnet-allow-list` when :ref:`setting-use-incoming-edns-subnet` is set and the query has
an ECS source prefix-length set to 0.
The default is to look for the first usable (not an ``any`` one) address in
:ref:`setting-query-local-address` (starting with IPv4). If no suitable address is
found, the recursor fallbacks to sending 127.0.0.1.
''',
'versionadded': '4.1.0'
},
{
'name' : 'edns_bufsize',
'section' : 'outgoing',
'oldname' : 'edns-outgoing-bufsize',
'type' : LType.Uint64,
'default' : '1232',
'help' : 'Outgoing EDNS buffer size',
'doc' : '''
.. note:: Why 1232?
1232 is the largest number of payload bytes that can fit in the smallest IPv6 packet.
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.
This is the value set for the EDNS0 buffer size in outgoing packets.
Lower this if you experience timeouts.
''',
'versionchanged': ('4.2.0', 'Before 4.2.0, the default was 1680')
},
{
'name' : 'edns_padding_from',
'section' : 'incoming',
'type' : LType.ListSubnets,
'default' : '',
'help' : 'List of netmasks (proxy IP in case of proxy-protocol presence, client IP otherwise) for which EDNS padding will be enabled in responses, provided that \'edns-padding-mode\' applies',
'doc' : '''
List of netmasks (proxy IP in case of proxy-protocol presence, client IP otherwise) for which EDNS padding will be enabled in responses, provided that :ref:`setting-edns-padding-mode` applies.
''',
'versionadded' : '4.5.0',
'versionchanged' : ('5.0.4', 'YAML settings only: previously this was defined as a string instead of a sequence')
},
{
'name' : 'edns_padding_mode',
'section' : 'incoming',
'type' : LType.String,
'default' : 'padded-queries-only',
'help' : 'Whether to add EDNS padding to all responses (\'always\') or only to responses for queries containing the EDNS padding option (\'padded-queries-only\', the default). In both modes, padding will only be added to responses for queries coming from \'setting-edns-padding-from\' sources',
'doc' : '''
One of ``always``, ``padded-queries-only``.
Whether to add EDNS padding to all responses (``always``) or only to responses for queries containing the EDNS padding option (``padded-queries-only``, the default).
In both modes, padding will only be added to responses for queries coming from :ref:`setting-edns-padding-from` sources.
''',
'versionadded': '4.5.0'
},
{
'name' : 'edns_padding',
'section' : 'outgoing',
'oldname' : 'edns-padding-out',
'type' : LType.Bool,
'default' : 'true',
'help' : 'Whether to add EDNS padding to outgoing DoT messages',
'doc' : '''
Whether to add EDNS padding to outgoing DoT queries.
''',
'versionadded': '4.8.0'
},
{
'name' : 'edns_padding_tag',
'section' : 'incoming',
'type' : LType.Uint64,
'default' : '7830',
'help' : 'Packetcache tag associated to responses sent with EDNS padding, to prevent sending these to clients for which padding is not enabled.',
'doc' : '''
The packetcache tag to use for padded responses, to prevent a client not allowed by the :ref::`setting-edns-padding-from` list to be served a cached answer generated for an allowed one. This
effectively divides the packet cache in two when :ref:`setting-edns-padding-from` is used. Note that this will not override a tag set from one of the ``Lua`` hooks.
''',
'versionadded': '4.5.0'
},
{
'name' : 'edns_subnet_whitelist',
'section' : 'outgoing',
'type' : LType.String,
'default' : '',
'help' : 'List of netmasks and domains that we should enable EDNS subnet for (deprecated)',
'doc' : '',
'deprecated': ('4.5.0', 'Use :ref:`setting-edns-subnet-allow-list`.'),
'skip-yaml': True,
},
{
'name' : 'edns_subnet_allow_list',
'section' : 'outgoing',
'type' : LType.ListStrings,
'default' : '',
'help' : 'List of netmasks and domains that we should enable EDNS subnet for',
'doc' : '''
List of netmasks and domains that :rfc:`EDNS Client Subnet <7871>` should be enabled for in outgoing queries.
For example, an EDNS Client Subnet option containing the address of the initial requestor (but see :ref:`setting-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.
The initial requestor address will be truncated to 24 bits for IPv4 (see :ref:`setting-ecs-ipv4-bits`) and to 56 bits for IPv6 (see :ref:`setting-ecs-ipv6-bits`), as recommended in the privacy section of RFC 7871.
Note that this setting describes the destination of outgoing queries, not the sources of incoming queries, nor the subnets described in the EDNS Client Subnet option.
By default, this option is empty, meaning no EDNS Client Subnet information is sent.
''',
'versionadded': '4.5.0'
},
{
'name' : 'entropy_source',
'section' : 'recursor',
'type' : LType.String,
'default' : '/dev/urandom',
'help' : 'If set, read entropy from this file',
'doc' : '''
PowerDNS can read entropy from a (hardware) source.
This is used for generating random numbers which are very hard to predict.
Generally on UNIX platforms, this source will be ``/dev/urandom``, which will always supply random numbers, even if entropy is lacking.
Change to ``/dev/random`` if PowerDNS should block waiting for enough entropy to arrive.
''',
'skip-yaml': True,
'versionchanged': ('4.9.0', 'This setting is no longer used.'),
},
{
'name' : 'etc_hosts_file',
'section' : 'recursor',
'type' : LType.String,
'default' : '/etc/hosts',
'help' : 'Path to \'hosts\' file',
'doc' : '''
The path to the /etc/hosts file, or equivalent.
This file can be used to serve data authoritatively using :ref:`setting-export-etc-hosts`.
''',
},
{
'name' : 'event_trace_enabled',
'section' : 'recursor',
'type' : LType.Uint64,
'default' : '0',
'help' : 'If set, event traces are collected and send out via protobuf logging (1), logfile (2) or both(3)',
'doc' : '''
Enable the recording and logging of ref:`event traces`. This is an experimental feature and subject to change.
Possible values are 0: (disabled), 1 (add information to protobuf logging messages) and 2 (write to log) and 3 (both).
''',
'versionadded': '4.6.0'
},
{
'name' : 'export_etc_hosts',
'section' : 'recursor',
'type' : LType.Bool,
'default' : 'false',
'help' : 'If we should serve up contents from /etc/hosts',
'doc' : '''
If set, this flag will export the host names and IP addresses mentioned in ``/etc/hosts``.
''',
},
{
'name' : 'export_etc_hosts_search_suffix',
'section' : 'recursor',
'type' : LType.String,
'default' : '',
'help' : 'Also serve up the contents of /etc/hosts with this suffix',
'doc' : '''
If set, all hostnames in the :ref:`setting-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.
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.
An entry called 'server1.home' will be stored as 'server1.home', regardless of this setting.
''',