pdns/recursordist/settings/table.py

   1 # This file contains the table used to generate old and new-style settings code
   2 #
   3 # Example:
   4 # {
   5 # 'name' : 'allow_from',
   6 # 'section' : 'incoming',
   7 # 'oldname' : 'allow-from'
   8 # 'type' : LType.ListSubnets,
   9 # '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',
  10 # 'help' : 'If set, only allow these comma separated netmasks to recurse',
  11 # 'doc' : '''
  12 #  '''
  13 # }
  14 #
  15 # See generate.py for a description of the fields.
  16 #
  17 # Sections
  18 # - incoming
  19 # - outgoing
  20 # - packetcache
  21 # - recursor
  22 # - recordcache
  23 # - dnssec
  24 # - webservice
  25 # - carbon
  26 # - ecs
  27 # - logging
  28 # - nod
  29 # - snmp
  30
  31 [
  32     {
  33         'name' : 'aggressive_nsec_cache_size',
  34         'section' : 'dnssec',
  35         'type' : LType.Uint64,
  36         'default' : '100000',
  37         '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',
  38         'doc' : '''
  39 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`.
  40 To use this, DNSSEC processing or validation must be enabled by setting :ref:`setting-dnssec` to ``process``, ``log-fail`` or ``validate``.
  41  ''',
  42         'versionadded': '4.5.0',
  43     },
  44     {
  45         'name' : 'aggressive_cache_min_nsec3_hit_ratio',
  46         'section' : 'dnssec',
  47         'type' : LType.Uint64,
  48         'default' : '2000',
  49         'help' : 'The minimum expected hit ratio to store NSEC3 records into the aggressive cache',
  50         'doc' : '''
  51 The limit for which to put NSEC3 records into the aggressive cache.
  52 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``.
  53 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``.
  54 A value of 0 means no NSEC3 records will be put into the aggressive cache.
  55
  56 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.
  57 This setting avoids doing unnecessary work for such large zones.
  58  ''',
  59         'versionadded' : '4.9.0',
  60     },
  61     {
  62         'name' : 'allow_from',
  63         'section' : 'incoming',
  64         'type' : LType.ListSubnets,
  65         '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',
  66         'help' : 'If set, only allow these comma separated netmasks to recurse',
  67         'doc' : '''
  68 Netmasks (both IPv4 and IPv6) that are allowed to use the server.
  69 The default allows access only from :rfc:`1918` private IP addresses.
  70 An empty value means no checking is done, all clients are allowed.
  71 Due to the aggressive nature of the internet these days, it is highly recommended to not open up the recursor for the entire internet.
  72 Questions from IP addresses not listed here are ignored and do not get an answer.
  73
  74 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.
  75
  76 Note that specifying an IP address without a netmask uses an implicit netmask of /32 or /128.
  77  ''',
  78     },
  79     {
  80         'name' : 'allow_from_file',
  81         'section' : 'incoming',
  82         'type' : LType.String,
  83         'default' : '',
  84         'help' : 'If set, load allowed netmasks from this file',
  85         'doc' : '''
  86 Like :ref:`setting-allow-from`, except reading from file.
  87 Overrides the :ref:`setting-allow-from` setting. To use this feature, supply one netmask per line, with optional comments preceded by a '#'.
  88  ''',
  89         'doc-new' : '''
  90 Like :ref:`setting-allow-from`, except reading a sequence of `Subnet`_ from file.
  91 Overrides the :ref:`setting-allow-from` setting. Example content of th specified file:
  92
  93 .. code-block:: yaml
  94
  95  - 127.0.01
  96  - ::1
  97
  98  ''',
  99     },
 100     {
 101         'name' : 'allow_notify_for',
 102         'section' : 'incoming',
 103         'type' : LType.ListStrings,
 104         'default' : '',
 105         'help' : 'If set, NOTIFY requests for these zones will be allowed',
 106         'doc' : '''
 107 Domain names specified in this list are used to permit incoming
 108 NOTIFY operations to wipe any cache entries that match the domain
 109 name. If this list is empty, all NOTIFY operations will be ignored.
 110  ''',
 111     'versionadded': '4.6.0'
 112     },
 113     {
 114         'name' : 'allow_notify_for_file',
 115         'section' : 'incoming',
 116         'type' : LType.String,
 117         'default' : '',
 118         'help' : 'If set, load NOTIFY-allowed zones from this file',
 119         'doc' : '''
 120 Like :ref:`setting-allow-notify-for`, except reading from file. To use this
 121 feature, supply one domain name per line, with optional comments
 122 preceded by a '#'.
 123
 124 NOTIFY-allowed zones can also be specified using :ref:`setting-forward-zones-file`.
 125  ''',
 126         'doc-new' : '''
 127 Like :ref:`setting-allow-notify-for`, except reading a sequence of names from file. Example contents of specified file:
 128
 129 .. code-block:: yaml
 130
 131  - example.com
 132  - example.org
 133
 134  ''',
 135     'versionadded': '4.6.0'
 136     },
 137     {
 138         'name' : 'allow_notify_from',
 139         'section' : 'incoming',
 140         'type' : LType.ListSubnets,
 141         'default' : '',
 142         'help' : 'If set, NOTIFY requests from these comma separated netmasks will be allowed',
 143         'doc' : '''
 144 Netmasks (both IPv4 and IPv6) that are allowed to issue NOTIFY operations
 145 to the server.  NOTIFY operations from IP addresses not listed here are
 146 ignored and do not get an answer.
 147
 148 When the Proxy Protocol is enabled (see :ref:`setting-proxy-protocol-from`), the
 149 recursor will check the address of the client IP advertised in the
 150 Proxy Protocol header instead of the one of the proxy.
 151
 152 Note that specifying an IP address without a netmask uses an implicit
 153 netmask of /32 or /128.
 154
 155 NOTIFY operations received from a client listed in one of these netmasks
 156 will be accepted and used to wipe any cache entries whose zones match
 157 the zone specified in the NOTIFY operation, but only if that zone (or
 158 one of its parents) is included in :ref:`setting-allow-notify-for`,
 159 :ref:`setting-allow-notify-for-file`, or :ref:`setting-forward-zones-file` with a '^' prefix.
 160  ''',
 161         'doc-new' : '''
 162 Subnets (both IPv4 and IPv6) that are allowed to issue NOTIFY operations
 163 to the server.  NOTIFY operations from IP addresses not listed here are
 164 ignored and do not get an answer.
 165
 166 When the Proxy Protocol is enabled (see :ref:`setting-proxy-protocol-from`), the
 167 recursor will check the address of the client IP advertised in the
 168 Proxy Protocol header instead of the one of the proxy.
 169
 170 Note that specifying an IP address without a netmask uses an implicit
 171 netmask of /32 or /128.
 172
 173 NOTIFY operations received from a client listed in one of these netmasks
 174 will be accepted and used to initiate a freshness check for an RPZ zone or wipe any cache entries whose zones match
 175 the zone specified in the NOTIFY operation, but only if that zone (or
 176 one of its parents) is included in :ref:`setting-allow-notify-for`,
 177 :ref:`setting-allow-notify-for-file`, or :ref:`setting-forward-zones-file` with a ``allow_notify`` set to ``true``.
 178  ''',
 179     'versionadded': '4.6.0'
 180     },
 181     {
 182         'name' : 'allow_notify_from_file',
 183         'section' : 'incoming',
 184         'type' : LType.String,
 185         'default' : '',
 186         'help' : 'If set, load NOTIFY-allowed netmasks from this file',
 187         'doc' : '''
 188 Like :ref:`setting-allow-notify-from`, except reading from file. To use this
 189 feature, supply one netmask per line, with optional comments preceded
 190 by a '#'.
 191  ''',
 192         'doc-new' : '''
 193 Like :ref:`setting-allow-notify-from`, except reading a sequence of `Subnet`_ from file.
 194  ''',
 195     'versionadded': '4.6.0'
 196     },
 197     {
 198         'name' : 'allow_no_rd',
 199         'section' : 'incoming',
 200         'type' : LType.Bool,
 201         'default' : 'false',
 202         'help' : 'Allow \'no recursion desired (RD=0)\' queries.',
 203         'doc' : '''
 204 Allow ``no recursion desired (RD=0) queries`` to query cache contents.
 205 If not set (the default), these queries are answered with rcode ``Refused``.
 206  ''',
 207     'versionadded': '5.0.0'
 208     },
 209     {
 210         'name' : 'any_to_tcp',
 211         'section' : 'recursor',
 212         'type' : LType.Bool,
 213         'default' : 'false',
 214         'help' : 'Answer ANY queries with tc=1, shunting to TCP',
 215         'doc' : '''
 216 Answer questions for the ANY type on UDP with a truncated packet that refers the remote server to TCP.
 217 Useful for mitigating ANY reflection attacks.
 218  ''',
 219     },
 220     {
 221         'name' : 'allow_trust_anchor_query',
 222         'section' : 'recursor',
 223         'type' : LType.Bool,
 224         'default' : 'false',
 225         'help' : 'Allow queries for trustanchor.server CH TXT and negativetrustanchor.server CH TXT',
 226         'doc' : '''
 227 Allow ``trustanchor.server CH TXT`` and ``negativetrustanchor.server CH TXT`` queries to view the configured :doc:`DNSSEC <dnssec>` (negative) trust anchors.
 228  ''',
 229     'versionadded': '4.3.0'
 230     },
 231     {
 232         'name' : 'api_dir',
 233         'section' : 'webservice',
 234         'oldname' : 'api-config-dir',
 235         'type' : LType.String,
 236         'default' : '',
 237         'help' : 'Directory where REST API stores config and zones',
 238         'doc' : '''
 239 Directory where the REST API stores its configuration and zones.
 240 For configuration updates to work, :ref:`setting-include-dir` should have the same value when using old-style settings.
 241 When using YAML settings :ref:`setting-yaml-recursor.include_dir` and :ref:`setting-yaml-webservice.api_dir` must have a different value.
 242  ''',
 243     'versionadded': '4.0.0'
 244      },
 245     {
 246         'name' : 'api_key',
 247         'section' : 'webservice',
 248         'type' : LType.String,
 249         'default' : '',
 250         'help' : 'Static pre-shared authentication key for access to the REST API',
 251         'doc' : '''
 252 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.
 253  ''',
 254         'versionadded': '4.0.0',
 255         'versionchanged': ('4.6.0', 'This setting now accepts a hashed and salted version.')
 256     },
 257     {
 258         'name' : 'auth_zones',
 259         'section' : 'recursor',
 260         'type' : LType.ListAuthZones,
 261         'default' : '',
 262         'help' : 'Zones for which we have authoritative data, comma separated domain=file pairs',
 263         'doc' : '''
 264 Zones read from these files (in BIND format) are served authoritatively (but without the AA bit set in responses).
 265 DNSSEC is not supported. Example:
 266
 267 .. code-block:: none
 268
 269     auth-zones=example.org=/var/zones/example.org, powerdns.com=/var/zones/powerdns.com
 270  ''',
 271         'doc-new' : '''
 272 Zones read from these files (in BIND format) are served authoritatively (but without the AA bit set in responses).
 273 DNSSEC is not supported. Example:
 274
 275 .. code-block:: yaml
 276
 277  recursor:
 278     auth-zones:
 279     - zone: example.org
 280       file: /var/zones/example.org
 281     - zone: powerdns.com
 282       file: /var/zones/powerdns.com
 283  ''',
 284     },
 285     {
 286         'name' : 'interval',
 287         'section' : 'carbon',
 288         'oldname' : 'carbon-interval',
 289         'type' : LType.Uint64,
 290         'default' : '30',
 291         'help' : 'Number of seconds between carbon (graphite) updates',
 292         'doc' : '''
 293 If sending carbon updates, this is the interval between them in seconds.
 294 See :doc:`metrics`.
 295  ''',
 296     },
 297     {
 298         'name' : 'ns',
 299         'section' : 'carbon',
 300         'oldname' : 'carbon-namespace',
 301         'type' : LType.String,
 302         'default' : 'pdns',
 303         'help' : 'If set overwrites the first part of the carbon string',
 304         'doc' : '''
 305 Change the namespace or first string of the metric key. The default is pdns.
 306  ''',
 307     'versionadded': '4.2.0'
 308     },
 309     {
 310         'name' : 'ourname',
 311         'section' : 'carbon',
 312         'oldname' : 'carbon-ourname',
 313         'type' : LType.String,
 314         'default' : '',
 315         'help' : 'If set, overrides our reported hostname for carbon stats',
 316         'doc' : '''
 317 If sending carbon updates, if set, this will override our hostname.
 318 Be careful not to include any dots in this setting, unless you know what you are doing.
 319 See :ref:`metricscarbon`.
 320  ''',
 321     },
 322     {
 323         'name' : 'instance',
 324         'section' : 'carbon',
 325         'oldname' : 'carbon-instance',
 326         'type' : LType.String,
 327         'default' : 'recursor',
 328         'help' : 'If set overwrites the instance name default',
 329         'doc' : '''
 330 Change the instance or third string of the metric key. The default is recursor.
 331  ''',
 332     'versionadded': '4.2.0'
 333     },
 334     {
 335         'name' : 'server',
 336         'section' : 'carbon',
 337         'oldname' : 'carbon-server',
 338         'type' : LType.ListSocketAddresses,
 339         'default' : '',
 340         'help' : 'If set, send metrics in carbon (graphite) format to this server IP address',
 341         'doc' : '''
 342 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.
 343 You may specify an alternate port by appending :port, for example: ``127.0.0.1:2004``.
 344 See :doc:`metrics`.
 345  ''',
 346         'doc-new' : '''
 347 Will send all available metrics to these servers via the carbon protocol, which is used by graphite and metronome.
 348 See :doc:`metrics`.
 349  ''',
 350     },
 351     {
 352         'name' : 'chroot',
 353         'section' : 'recursor',
 354         'type' : LType.String,
 355         'default' : '',
 356         'help' : 'switch to chroot jail',
 357         'doc' : '''
 358 If set, chroot to this directory for more security.
 359 This is not recommended; instead, we recommend containing PowerDNS using operating system features.
 360 We ship systemd unit files with our packages to make this easy.
 361
 362 Make sure that ``/dev/log`` is available from within the chroot.
 363 Logging will silently fail over time otherwise (on logrotate).
 364
 365 When using ``chroot``, all other paths (except for :ref:`setting-config-dir`) set in the configuration are relative to the new root.
 366
 367 When running on a system where systemd manages services, ``chroot`` does not work out of the box, as PowerDNS cannot use the ``NOTIFY_SOCKET``.
 368 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).
 369  ''',
 370     },
 371     {
 372         'name' : 'tcp_timeout',
 373         'section' : 'incoming',
 374         'oldname' : 'client-tcp-timeout',
 375         'type' : LType.Uint64,
 376         'default' : '2',
 377         'help' : 'Timeout in seconds when talking to TCP clients',
 378         'doc' : '''
 379 Time to wait for data from TCP clients.
 380  ''',
 381     },
 382     {
 383         'name' : 'config',
 384         'section' : 'commands',
 385         'type' : LType.Command,
 386         'default' : 'no',
 387         'help' : 'Output blank configuration. You can use --config=check to test the config file and command line arguments.',
 388         'doc' : '''
 389 EMPTY?  '''
 390     },
 391     {
 392         'name' : 'config_dir',
 393         'section' : 'recursor',
 394         'type' : LType.String,
 395         'default' : 'SYSCONFDIR',
 396         'docdefault': 'Determined by distribution',
 397         'help' : 'Location of configuration directory (recursor.conf or recursor.yml)',
 398         'doc' : '''
 399 Location of configuration directory (where ``recursor.conf`` or ``recursor.yml`` is stored).
 400 Usually ``/etc/powerdns``, but this depends on ``SYSCONFDIR`` during compile-time.
 401 Use default or set on command line.
 402  ''',
 403     },
 404     {
 405         'name' : 'config_name',
 406         'section' : 'recursor',
 407         'type' : LType.String,
 408         'default' : '',
 409         'help' : 'Name of this virtual configuration - will rename the binary image',
 410         'doc' : '''
 411 When running multiple recursors on the same server, read settings from :file:`recursor-{name}.conf`, this will also rename the binary image.
 412  ''',
 413     },
 414     {
 415         'name' : 'cpu_map',
 416         'section' : 'recursor',
 417         'type' : LType.String,
 418         'default' : '',
 419         'help' : 'Thread to CPU mapping, space separated thread-id=cpu1,cpu2..cpuN pairs',
 420         'doc' : '''
 421 Set CPU affinity for threads, asking the scheduler to run those threads on a single CPU, or a set of CPUs.
 422 This parameter accepts a space separated list of thread-id=cpu-id, or thread-id=cpu-id-1,cpu-id-2,...,cpu-id-N.
 423 For example, to make the worker thread 0 run on CPU id 0 and the worker thread 1 on CPUs 1 and 2::
 424
 425   cpu-map=0=0 1=1,2
 426
 427 The thread handling the control channel, the webserver and other internal stuff has been assigned id 0, the distributor
 428 threads if any are assigned id 1 and counting, and the worker threads follow behind.
 429 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.
 430
 431 This parameter is only available if the OS provides the ``pthread_setaffinity_np()`` function.
 432
 433 Note that depending on the configuration the Recursor can start more threads.
 434 Typically these threads will sleep most of the time.
 435 These threads cannot be specified in this setting as their thread-ids are left unspecified.
 436  ''',
 437         'doc' : '''
 438 Set CPU affinity for threads, asking the scheduler to run those threads on a single CPU, or a set of CPUs.
 439 This parameter accepts a space separated list of thread-id=cpu-id, or thread-id=cpu-id-1,cpu-id-2,...,cpu-id-N.
 440 For example, to make the worker thread 0 run on CPU id 0 and the worker thread 1 on CPUs 1 and 2:
 441
 442 .. code-block:: yaml
 443
 444   recursor:
 445     cpu_map: 0=0 1=1,2
 446
 447 The thread handling the control channel, the webserver and other internal stuff has been assigned id 0, the distributor
 448 threads if any are assigned id 1 and counting, and the worker threads follow behind.
 449 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.
 450
 451 This parameter is only available if the OS provides the ``pthread_setaffinity_np()`` function.
 452
 453 Note that depending on the configuration the Recursor can start more threads.
 454 Typically these threads will sleep most of the time.
 455 These threads cannot be specified in this setting as their thread-ids are left unspecified.
 456  ''',
 457     },
 458     {
 459         'name' : 'daemon',
 460         'section' : 'recursor',
 461         'type' : LType.Bool,
 462         'default' : 'false',
 463         'help' : 'Operate as a daemon',
 464         'doc' : '''
 465 Operate in the background.
 466  ''',
 467         'versionchanged': ('4.0.0', 'Default is now ``no``, was ``yes`` before.')
 468     },
 469     {
 470         'name' : 'dont_throttle_names',
 471         'section' : 'outgoing',
 472         'type' : LType.ListStrings,
 473         'default' : '',
 474         'help' : 'Do not throttle nameservers with this name or suffix',
 475         'doc' : '''
 476 When an authoritative server does not answer a query or sends a reply the recursor does not like, it is throttled.
 477 Any servers' name suffix-matching the supplied names will never be throttled.
 478
 479 .. warning::
 480   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.
 481  ''',
 482     'versionadded': '4.2.0'
 483     },
 484     {
 485         'name' : 'dont_throttle_netmasks',
 486         'section' : 'outgoing',
 487         'type' : LType.ListSubnets,
 488         'default' : '',
 489         'help' : 'Do not throttle nameservers with this IP netmask',
 490         'doc' : '''
 491 When an authoritative server does not answer a query or sends a reply the recursor does not like, it is throttled.
 492 Any servers matching the supplied netmasks will never be throttled.
 493
 494 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``).
 495 By default, the PowerDNS Recursor would throttle the 'first' server on a timeout and hence not retry the 'second' one.
 496 In this case, ``dont-throttle-netmasks`` could be set to ``192.0.2.1``.
 497
 498 .. warning::
 499   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.
 500  ''',
 501         'doc-new' : '''
 502 When an authoritative server does not answer a query or sends a reply the recursor does not like, it is throttled.
 503 Any servers matching the supplied netmasks will never be throttled.
 504
 505 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 ] } ]``.
 506 By default, the PowerDNS Recursor would throttle the 'first' server on a timeout and hence not retry the 'second' one.
 507 In this case, :ref:`setting-dont-throttle-netmasks` could be set to include ``192.0.2.1``.
 508
 509 .. warning::
 510   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.
 511  ''',
 512     'versionadded': '4.2.0'
 513     },
 514     {
 515         'name' : 'devonly_regression_test_mode',
 516         'section' : 'recursor',
 517         'type' : LType.Bool,
 518         'default' : 'false',
 519         'help' : 'internal use only',
 520         'doc' : 'SKIP',
 521     },
 522     {
 523         'name' : 'disable',
 524         'section' : 'packetcache',
 525         'oldname' : 'disable-packetcache',
 526         'type' : LType.Bool,
 527         'default' : 'false',
 528         'help' : 'Disable packetcache',
 529         'doc' : '''
 530 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.
 531  ''',
 532     },
 533     {
 534         'name' : 'disable_syslog',
 535         'section' : 'logging',
 536         'type' : LType.Bool,
 537         'default' : 'false',
 538         'help' : 'Disable logging to syslog, useful when running inside a supervisor that logs stderr',
 539         'doc' : '''
 540 Do not log to syslog, only to stderr.
 541 Use this setting when running inside a supervisor that handles logging (like systemd).
 542 **Note**: do not use this setting in combination with :ref:`setting-daemon` as all logging will disappear.
 543  ''',
 544     },
 545     {
 546         'name' : 'distribution_load_factor',
 547         'section' : 'incoming',
 548         'type' : LType.Double,
 549         'default' : '0.0',
 550         'help' : 'The load factor used when PowerDNS is distributing queries to worker threads',
 551         'doc' : '''
 552 If :ref:`setting-pdns-distributes-queries` is set and this setting is set to another value
 553 than 0, the distributor thread will use a bounded load-balancing algorithm while
 554 distributing queries to worker threads, making sure that no thread is assigned
 555 more queries than distribution-load-factor times the average number of queries
 556 currently processed by all the workers.
 557 For example, with a value of 1.25, no server should get more than 125 % of the
 558 average load. This helps making sure that all the workers have roughly the same
 559 share of queries, even if the incoming traffic is very skewed, with a larger
 560 number of requests asking for the same qname.
 561  ''',
 562     'versionadded': '4.1.12'
 563     },
 564     {
 565         'name' : 'distribution_pipe_buffer_size',
 566         'section' : 'incoming',
 567         'type' : LType.Uint64,
 568         'default' : '0',
 569         'help' : 'Size in bytes of the internal buffer of the pipe used by the distributor to pass incoming queries to a worker thread',
 570         'doc' : '''
 571 Size in bytes of the internal buffer of the pipe used by the distributor to pass incoming queries to a worker thread.
 572 Requires support for `F_SETPIPE_SZ` which is present in Linux since 2.6.35. The actual size might be rounded up to
 573 a multiple of a page size. 0 means that the OS default size is used.
 574 A large buffer might allow the recursor to deal with very short-lived load spikes during which a worker thread gets
 575 overloaded, but it will be at the cost of an increased latency.
 576  ''',
 577     'versionadded': '4.2.0'
 578     },
 579     {
 580         'name' : 'distributor_threads',
 581         'section' : 'incoming',
 582         'type' : LType.Uint64,
 583         'default' : '0',
 584         'docdefault' : '1 if :ref:`setting-pdns-distributes-queries` is set, 0 otherwise',
 585         'help' : 'Launch this number of distributor threads, distributing queries to other threads',
 586         'doc' : '''
 587 If :ref:`setting-pdns-distributes-queries` is set, spawn this number of distributor threads on startup. Distributor threads
 588 handle incoming queries and distribute them to other threads based on a hash of the query.
 589  ''',
 590     'versionadded': '4.2.0'
 591     },
 592     {
 593         'name' : 'dot_to_auth_names',
 594         'section' : 'outgoing',
 595         'type' : LType.ListStrings,
 596         'default' : '',
 597         'help' : 'Use DoT to authoritative servers with these names or suffixes',
 598         'doc' : '''
 599 Force DoT to the listed authoritative nameservers. For this to work, DoT support has to be compiled in.
 600 Currently, the certificate is not checked for validity in any way.
 601  ''',
 602     'versionadded': '4.6.0'
 603     },
 604     {
 605         'name' : 'dot_to_port_853',
 606         'section' : 'outgoing',
 607         'type' : LType.Bool,
 608         'default' : 'true',
 609         'help' : 'Force DoT connection to target port 853 if DoT compiled in',
 610         'doc' : '''
 611 Enable DoT to forwarders that specify port 853.
 612  ''',
 613     'versionadded': '4.6.0'
 614     },
 615     {
 616         'name' : 'dns64_prefix',
 617         'section' : 'recursor',
 618         'type' : LType.String,
 619         'default' : '',
 620         'help' : 'DNS64 prefix',
 621         'doc' : '''
 622 Enable DNS64 (:rfc:`6147`) support using the supplied /96 IPv6 prefix. This will generate 'fake' ``AAAA`` records for names
 623 with only ``A`` records, as well as 'fake' ``PTR`` records to make sure that reverse lookup of DNS64-generated IPv6 addresses
 624 generate the right name.
 625 See :doc:`dns64` for more flexible but slower alternatives using Lua.
 626  ''',
 627     'versionadded': '4.4.0'
 628     },
 629     {
 630         'name' : 'validation',
 631         'section' : 'dnssec',
 632         'oldname' : 'dnssec',
 633         'type' : LType.String,
 634         'default' : 'process',
 635         'help' : 'DNSSEC mode: off/process-no-validate/process (default)/log-fail/validate',
 636         'doc' : '''
 637 One of ``off``, ``process-no-validate``, ``process``, ``log-fail``, ``validate``
 638
 639 Set the mode for DNSSEC processing, as detailed in :doc:`dnssec`.
 640
 641 ``off``
 642    No DNSSEC processing whatsoever.
 643    Ignore DO-bits in queries, don't request any DNSSEC information from authoritative servers.
 644    This behaviour is similar to PowerDNS Recursor pre-4.0.
 645 ``process-no-validate``
 646    Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries.
 647    Don't do any validation.
 648 ``process``
 649    Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries.
 650    Do validation for clients that request it (by means of the AD- bit or DO-bit in the query).
 651 ``log-fail``
 652    Similar behaviour to ``process``, but validate RRSIGs on responses and log bogus responses.
 653 ``validate``
 654    Full blown DNSSEC validation. Send SERVFAIL to clients on bogus responses.
 655  ''',
 656         'versionadded': '4.0.0',
 657         'versionchanged': ('4.5.0',
 658    'The default changed from ``process-no-validate`` to ``process``')
 659     },
 660     {
 661         'name' : 'disabled_algorithms',
 662         'section' : 'dnssec',
 663         'oldname' : 'dnssec-disabled-algorithms',
 664         'type' : LType.ListStrings,
 665         'default' : '',
 666         'help' : 'List of DNSSEC algorithm numbers that are considered unsupported',
 667         'doc' : '''
 668 A list of DNSSEC algorithm numbers that should be considered disabled.
 669 These algorithms will not be used to validate DNSSEC signatures.
 670 Zones (only) signed with these algorithms will be considered ``Insecure``.
 671
 672 If this setting is empty (the default), :program:`Recursor` will determine which algorithms to disable automatically.
 673 This is done for specific algorithms only, currently algorithms 5 (``RSASHA1``) and 7 (``RSASHA1NSEC3SHA1``).
 674
 675 This is important on systems that have a default strict crypto policy, like RHEL9 derived systems.
 676 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.
 677  ''',
 678     'versionadded': '4.9.0'
 679     },
 680     {
 681         'name' : 'log_bogus',
 682         'section' : 'dnssec',
 683         'oldname' : 'dnssec-log-bogus',
 684         'type' : LType.Bool,
 685         'default' : 'false',
 686         'help' : 'Log DNSSEC bogus validations',
 687         'doc' : '''
 688 Log every DNSSEC validation failure.
 689 **Note**: This is not logged per-query but every time records are validated as Bogus.
 690  ''',
 691     },
 692     {
 693         'name' : 'dont_query',
 694         'section' : 'outgoing',
 695         'type' : LType.ListSubnets,
 696         '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',
 697         'help' : 'If set, do not query these netmasks for DNS data',
 698         'doc' : '''
 699 The DNS is a public database, but sometimes contains delegations to private IP addresses, like for example 127.0.0.1.
 700 This can have odd effects, depending on your network, and may even be a security risk.
 701 Therefore, the PowerDNS Recursor by default does not query private space IP addresses.
 702 This setting can be used to expand or reduce the limitations.
 703
 704 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.
 705  ''',
 706     },
 707     {
 708         'name' : 'add_for',
 709         'section' : 'ecs',
 710         'oldname' : 'ecs-add-for',
 711         'type' : LType.ListSubnets,
 712         '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',
 713         'help' : 'List of client netmasks for which EDNS Client Subnet will be added',
 714         'doc' : '''
 715 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.
 716 Valid incoming ECS values from :ref:`setting-use-incoming-edns-subnet` are not replaced.
 717
 718 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.
 719
 720 This defaults to not using the requestor address inside RFC1918 and similar 'private' IP address spaces.
 721  ''',
 722     'versionadded': '4.2.0'
 723     },
 724     {
 725         'name' : 'ipv4_bits',
 726         'section' : 'ecs',
 727         'oldname' : 'ecs-ipv4-bits',
 728         'type' : LType.Uint64,
 729         'default' : '24',
 730         'help' : 'Number of bits of IPv4 address to pass for EDNS Client Subnet',
 731         'doc' : '''
 732 Number of bits of client IPv4 address to pass when sending EDNS Client Subnet address information.
 733  ''',
 734     'versionadded': '4.1.0'
 735     },
 736     {
 737         'name' : 'ipv4_cache_bits',
 738         'section' : 'ecs',
 739         'oldname' : 'ecs-ipv4-cache-bits',
 740         'type' : LType.Uint64,
 741         'default' : '24',
 742         'help' : 'Maximum number of bits of IPv4 mask to cache ECS response',
 743         'doc' : '''
 744 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``.
 745 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``.
 746  ''',
 747     'versionadded': '4.1.12'
 748     },
 749     {
 750         'name' : 'ipv6_bits',
 751         'section' : 'ecs',
 752         'oldname' : 'ecs-ipv6-bits',
 753         'type' : LType.Uint64,
 754         'default' : '56',
 755         'help' : 'Number of bits of IPv6 address to pass for EDNS Client Subnet',
 756         'doc' : '''
 757 Number of bits of client IPv6 address to pass when sending EDNS Client Subnet address information.
 758  ''',
 759     'versionadded': '4.1.0'
 760     },
 761     {
 762         'name' : 'ipv6_cache_bits',
 763         'section' : 'ecs',
 764         'oldname' : 'ecs-ipv6-cache-bits',
 765         'type' : LType.Uint64,
 766         'default' : '56',
 767         'help' : 'Maximum number of bits of IPv6 mask to cache ECS response',
 768         'doc' : '''
 769 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``.
 770 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``.
 771  ''',
 772     'versionadded': '4.1.12'
 773     },
 774     {
 775         'name' : 'ipv4_never_cache',
 776         'section' : 'ecs',
 777         'oldname' : 'ecs-ipv4-never-cache',
 778         'type' : LType.Bool,
 779         'default' : 'false',
 780         'help' : 'If we should never cache IPv4 ECS responses',
 781         'doc' : '''
 782 When set, never cache replies carrying EDNS IPv4 Client Subnet scope in the record cache.
 783 In this case the decision made by ```ecs-ipv4-cache-bits`` and ``ecs-cache-limit-ttl`` is no longer relevant.
 784  ''',
 785     'versionadded': '4.5.0'
 786     },
 787     {
 788         'name' : 'ipv6_never_cache',
 789         'section' : 'ecs',
 790         'oldname' : 'ecs-ipv6-never-cache',
 791         'type' : LType.Bool,
 792         'default' : 'false',
 793         'help' : 'If we should never cache IPv6 ECS responses',
 794         'doc' : '''
 795 When set, never cache replies carrying EDNS IPv6 Client Subnet scope in the record cache.
 796 In this case the decision made by ```ecs-ipv6-cache-bits`` and ``ecs-cache-limit-ttl`` is no longer relevant.
 797  ''',
 798     'versionadded': '4.5.0'
 799     },
 800     {
 801         'name' : 'minimum_ttl_override',
 802         'section' : 'ecs',
 803         'oldname' : 'ecs-minimum-ttl-override',
 804         'type' : LType.Uint64,
 805         'default' : '1',
 806         'help' : 'The minimum TTL for records in ECS-specific answers',
 807         'doc' : '''
 808 This setting artificially raises the TTLs of records in the ANSWER section of ECS-specific answers to be at least this long.
 809 Setting this to a value greater than 1 technically is an RFC violation, but might improve performance a lot.
 810 Using a value of 0 impacts performance of TTL 0 records greatly, since it forces the recursor to contact
 811 authoritative servers every time a client requests them.
 812 Can be set at runtime using ``rec_control set-ecs-minimum-ttl 3600``.
 813  ''',
 814         'versionchanged': ('4.5.0', 'Old versions used default 0.')
 815     },
 816     {
 817         'name' : 'cache_limit_ttl',
 818         'section' : 'ecs',
 819         'oldname' : 'ecs-cache-limit-ttl',
 820         'type' : LType.Uint64,
 821         'default' : '0',
 822         'help' : 'Minimum TTL to cache ECS response',
 823         'doc' : '''
 824 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``.
 825 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``.
 826  ''',
 827     'versionadded': '4.1.12'
 828     },
 829     {
 830         'name' : 'scope_zero_address',
 831         'section' : 'ecs',
 832         'oldname' : 'ecs-scope-zero-address',
 833         'type' : LType.String,
 834         'default' : '',
 835         'help' : 'Address to send to allow-listed authoritative servers for incoming queries with ECS prefix-length source of 0',
 836         'doc' : '''
 837 The IP address sent via EDNS Client Subnet to authoritative servers listed in
 838 :ref:`setting-edns-subnet-allow-list` when :ref:`setting-use-incoming-edns-subnet` is set and the query has
 839 an ECS source prefix-length set to 0.
 840 The default is to look for the first usable (not an ``any`` one) address in
 841 :ref:`setting-query-local-address` (starting with IPv4). If no suitable address is
 842 found, the recursor fallbacks to sending 127.0.0.1.
 843  ''',
 844     'versionadded': '4.1.0'
 845     },
 846     {
 847         'name' : 'edns_bufsize',
 848         'section' : 'outgoing',
 849         'oldname' : 'edns-outgoing-bufsize',
 850         'type' : LType.Uint64,
 851         'default' : '1232',
 852         'help' : 'Outgoing EDNS buffer size',
 853         'doc' : '''
 854 .. note:: Why 1232?
 855
 856   1232 is the largest number of payload bytes that can fit in the smallest IPv6 packet.
 857   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.
 858
 859 This is the value set for the EDNS0 buffer size in outgoing packets.
 860 Lower this if you experience timeouts.
 861  ''',
 862      'versionchanged': ('4.2.0', 'Before 4.2.0, the default was 1680')
 863     },
 864     {
 865         'name' : 'edns_padding_from',
 866         'section' : 'incoming',
 867         'type' : LType.ListSubnets,
 868         'default' : '',
 869         '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',
 870         'doc' : '''
 871 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.
 872  ''',
 873         'versionadded' : '4.5.0',
 874         'versionchanged' : ('5.0.4', 'YAML settings only: previously this was defined as a string instead of a sequence')
 875     },
 876     {
 877         'name' : 'edns_padding_mode',
 878         'section' : 'incoming',
 879         'type' : LType.String,
 880         'default' : 'padded-queries-only',
 881         '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',
 882         'doc' : '''
 883 One of ``always``, ``padded-queries-only``.
 884 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).
 885 In both modes, padding will only be added to responses for queries coming from :ref:`setting-edns-padding-from` sources.
 886  ''',
 887     'versionadded': '4.5.0'
 888     },
 889     {
 890         'name' : 'edns_padding',
 891         'section' : 'outgoing',
 892         'oldname' : 'edns-padding-out',
 893         'type' : LType.Bool,
 894         'default' : 'true',
 895         'help' : 'Whether to add EDNS padding to outgoing DoT messages',
 896         'doc' : '''
 897 Whether to add EDNS padding to outgoing DoT queries.
 898  ''',
 899     'versionadded': '4.8.0'
 900     },
 901     {
 902         'name' : 'edns_padding_tag',
 903         'section' : 'incoming',
 904         'type' : LType.Uint64,
 905         'default' : '7830',
 906         'help' : 'Packetcache tag associated to responses sent with EDNS padding, to prevent sending these to clients for which padding is not enabled.',
 907         'doc' : '''
 908 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
 909 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.
 910  ''',
 911     'versionadded': '4.5.0'
 912     },
 913     {
 914         'name' : 'edns_subnet_whitelist',
 915         'section' : 'outgoing',
 916         'type' : LType.String,
 917         'default' : '',
 918         'help' : 'List of netmasks and domains that we should enable EDNS subnet for (deprecated)',
 919         'doc' : '',
 920         'deprecated': ('4.5.0', 'Use :ref:`setting-edns-subnet-allow-list`.'),
 921         'skip-yaml': True,
 922     },
 923     {
 924         'name' : 'edns_subnet_allow_list',
 925         'section' : 'outgoing',
 926         'type' : LType.ListStrings,
 927         'default' : '',
 928         'help' : 'List of netmasks and domains that we should enable EDNS subnet for',
 929         'doc' : '''
 930 List of netmasks and domains that :rfc:`EDNS Client Subnet <7871>` should be enabled for in outgoing queries.
 931
 932 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.
 933 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.
 934
 935
 936 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.
 937
 938 By default, this option is empty, meaning no EDNS Client Subnet information is sent.
 939  ''',
 940     'versionadded': '4.5.0'
 941     },
 942     {
 943         'name' : 'entropy_source',
 944         'section' : 'recursor',
 945         'type' : LType.String,
 946         'default' : '/dev/urandom',
 947         'help' : 'If set, read entropy from this file',
 948         'doc' : '''
 949 PowerDNS can read entropy from a (hardware) source.
 950 This is used for generating random numbers which are very hard to predict.
 951 Generally on UNIX platforms, this source will be ``/dev/urandom``, which will always supply random numbers, even if entropy is lacking.
 952 Change to ``/dev/random`` if PowerDNS should block waiting for enough entropy to arrive.
 953  ''',
 954         'skip-yaml': True,
 955         'versionchanged': ('4.9.0', 'This setting is no longer used.'),
 956     },
 957     {
 958         'name' : 'etc_hosts_file',
 959         'section' : 'recursor',
 960         'type' : LType.String,
 961         'default' : '/etc/hosts',
 962         'help' : 'Path to \'hosts\' file',
 963         'doc' : '''
 964 The path to the /etc/hosts file, or equivalent.
 965 This file can be used to serve data authoritatively using :ref:`setting-export-etc-hosts`.
 966  ''',
 967     },
 968     {
 969         'name' : 'event_trace_enabled',
 970         'section' : 'recursor',
 971         'type' : LType.Uint64,
 972         'default' : '0',
 973         'help' : 'If set, event traces are collected and send out via protobuf logging (1), logfile (2) or both(3)',
 974         'doc' : '''
 975 Enable the recording and logging of ref:`event traces`. This is an experimental feature and subject to change.
 976 Possible values are 0: (disabled), 1 (add information to protobuf logging messages) and 2 (write to log) and 3 (both).
 977  ''',
 978     'versionadded': '4.6.0'
 979     },
 980     {
 981         'name' : 'export_etc_hosts',
 982         'section' : 'recursor',
 983         'type' : LType.Bool,
 984         'default' : 'false',
 985         'help' : 'If we should serve up contents from /etc/hosts',
 986         'doc' : '''
 987 If set, this flag will export the host names and IP addresses mentioned in ``/etc/hosts``.
 988  ''',
 989     },
 990     {
 991         'name' : 'export_etc_hosts_search_suffix',
 992         'section' : 'recursor',
 993         'type' : LType.String,
 994         'default' : '',
 995         'help' : 'Also serve up the contents of /etc/hosts with this suffix',
 996         'doc' : '''
 997 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.
 998 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.
 999 An entry called 'server1.home' will be stored as 'server1.home', regardless of this setting.
1000  ''',
1001     },
1002     {
1003         'name' : 'extended_resolution_errors',
1004         'section' : 'recursor',
1005         'type' : LType.Bool,
1006         'default' : 'true',
1007         'help' : 'If set, send an EDNS Extended Error extension on resolution failures, like DNSSEC validation errors',
1008         'doc' : '''
1009 If set, the recursor will add an EDNS Extended Error (:rfc:`8914`) to responses when resolution failed, like DNSSEC validation errors, explaining the reason it failed. This setting is not needed to allow setting custom error codes from Lua or from a RPZ hit.
1010  ''',
1011         'versionadded': '4.5.0',
1012         'versionchanged': ('5.0.0', 'Default changed to enabled, previously it was disabled.'),
1013     },
1014     {
1015         'name' : 'forward_zones',
1016         'section' : 'recursor',
1017         'type' : LType.ListForwardZones,
1018         'default' : '',
1019         'help' : 'Zones for which we forward queries, comma separated domain=ip pairs',
1020         'doc' : '''
1021 Queries for zones listed here will be forwarded to the IP address listed. i.e.
1022
1023 .. code-block:: none
1024
1025     forward-zones=example.org=203.0.113.210, powerdns.com=2001:DB8::BEEF:5
1026
1027 Multiple IP addresses can be specified and port numbers other than 53 can be configured:
1028
1029 .. code-block:: none
1030
1031     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
1032
1033 Forwarded queries have the ``recursion desired (RD)`` bit set to ``0``, meaning that this setting is intended to forward queries to authoritative servers.
1034 If an ``NS`` record set for a subzone of the forwarded zone is learned, that record set will be used to determine addresses for name servers of the subzone.
1035 This allows e.g. a forward to a local authoritative server holding a copy of the root zone, delegations received from that server will work.
1036
1037 **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.
1038 To prevent this, add a Negative Trust Anchor (NTA) for this zone in the :ref:`setting-lua-config-file` with ``addNTA('your.zone', 'A comment')``.
1039 If this forwarded zone is signed, instead of adding NTA, add the DS record to the :ref:`setting-lua-config-file`.
1040 See the :doc:`dnssec` information.
1041  ''',
1042         'doc-new' : '''
1043 Queries for zones listed here will be forwarded to the IP address listed. i.e.
1044
1045 .. code-block:: yaml
1046
1047  recursor:
1048     forward-zones:
1049       - zone: example.org
1050         forwarders:
1051         - 203.0.113.210
1052       - zone: powerdns.com
1053         forwarders:
1054         - 2001:DB8::BEEF:5
1055
1056 Multiple IP addresses can be specified and port numbers other than 53 can be configured:
1057
1058 .. code-block:: yaml
1059
1060   recursor:
1061     forward-zones:
1062     - zone: example.org
1063       forwarders:
1064       - 203.0.113.210:5300
1065       - 127.0.0.1
1066     - zone: powerdns.com
1067       forwarders:
1068       - 127.0.0.1
1069       - 198.51.100.10:530
1070       - '[2001:DB8::1:3]:5300'
1071
1072 Forwarded queries have the ``recursion desired (RD)`` bit set to ``0``, meaning that this setting is intended to forward queries to authoritative servers.
1073 If an ``NS`` record set for a subzone of the forwarded zone is learned, that record set will be used to determine addresses for name servers of the subzone.
1074 This allows e.g. a forward to a local authoritative server holding a copy of the root zone, delegations received from that server will work.
1075
1076 **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.
1077 To prevent this, add a Negative Trust Anchor (NTA) for this zone in the :ref:`setting-lua-config-file` with ``addNTA('your.zone', 'A comment')``.
1078 If this forwarded zone is signed, instead of adding NTA, add the DS record to the :ref:`setting-lua-config-file`.
1079 See the :doc:`dnssec` information.
1080  ''',
1081     },
1082     {
1083         'name' : 'forward_zones_file',
1084         'section' : 'recursor',
1085         'type' : LType.String,
1086         'default' : '',
1087         'help' : 'File with (+)domain=ip pairs for forwarding',
1088         'doc' : '''
1089 Same as :ref:`setting-forward-zones`, parsed from a file. Only 1 zone is allowed per line, specified as follows:
1090
1091 .. code-block:: none
1092
1093     example.org=203.0.113.210, 192.0.2.4:5300
1094
1095 Zones prefixed with a ``+`` are treated as with
1096 :ref:`setting-forward-zones-recurse`.  Default behaviour without ``+`` is as with
1097 :ref:`setting-forward-zones`.
1098
1099 The DNSSEC notes from :ref:`setting-forward-zones` apply here as well.
1100  ''',
1101     'doc-new' : '''
1102         Same as :ref:`setting-forward-zones`, parsed from a file as a sequence of `ZoneForward`.
1103
1104 .. code-block:: yaml
1105
1106   - zone: example1.com
1107     forwarders:
1108     - 127.0.0.1
1109     - 127.0.0.1:5353
1110     - '[::1]53'
1111   - zone: example2.com
1112     forwarders:
1113     - ::1
1114     recurse: true
1115     notify_allowed: true
1116
1117 The DNSSEC notes from :ref:`setting-forward-zones` apply here as well.
1118  ''',
1119      'versionchanged': [('4.0.0', '(Old style settings only) Comments are allowed, everything behind ``#`` is ignored.'),
1120                         ('4.6.0', '(Old style settings only) Zones prefixed with a ``^`` are added to the :ref:`setting-allow-notify-for` list. Both prefix characters can be used if desired, in any order.')],
1121     },
1122     {
1123         'name' : 'forward_zones_recurse',
1124         'section' : 'recursor',
1125         'type' : LType.ListForwardZones,
1126         'default' : '',
1127         'help' : 'Zones for which we forward queries with recursion bit, comma separated domain=ip pairs',
1128         'doc' : '''
1129 Like regular :ref:`setting-forward-zones`, but forwarded queries have the ``recursion desired (RD)`` bit set to ``1``, meaning that this setting is intended to forward queries to other recursive servers.
1130 In contrast to regular forwarding, the rule that delegations of the forwarded subzones are respected is not active.
1131 This is because we rely on the forwarder to resolve the query fully.
1132
1133 See :ref:`setting-forward-zones` for additional options (such as supplying multiple recursive servers) and an important note about DNSSEC.
1134  ''',
1135     },
1136     {
1137         'name' : 'gettag_needs_edns_options',
1138         'section' : 'incoming',
1139         'type' : LType.Bool,
1140         'default' : 'false',
1141         'help' : 'If EDNS Options should be extracted before calling the gettag() hook',
1142         'doc' : '''
1143 If set, EDNS options in incoming queries are extracted and passed to the :func:`gettag` hook in the ``ednsoptions`` table.
1144  ''',
1145     'versionadded': '4.1.0'
1146     },
1147     {
1148         'name' : 'help',
1149         'section' : 'commands',
1150         'type' : LType.Command,
1151         'default' : 'no',
1152         'help' : 'Provide a helpful message',
1153         'doc' : '''
1154 EMPTY?  '''
1155     },
1156     {
1157         'name' : 'hint_file',
1158         'section' : 'recursor',
1159         'type' : LType.String,
1160         'default' : '',
1161         'help' : 'If set, load root hints from this file',
1162         'doc' : '''
1163 If set, the root-hints are read from this file. If empty, the default built-in root hints are used.
1164
1165 In some special cases, processing the root hints is not needed, for example when forwarding all queries to another recursor.
1166 For these special cases, it is possible to disable the processing of root hints by setting the value to ``no`` or ``no-refresh``.
1167 See :ref:`handling-of-root-hints` for more information on root hints handling.
1168  ''',
1169         'versionchanged': [('4.6.2', 'Introduced the value ``no`` to disable root-hints processing.'),
1170                            ('4.9.0', 'Introduced the value ``no-refresh`` to disable both root-hints processing and periodic refresh of the cached root `NS` records.')]
1171     },
1172     {
1173         'name' : 'ignore_unknown_settings',
1174         'section' : 'recursor',
1175         'type' : LType.ListStrings,
1176         'default' : '',
1177         'help' : 'Configuration settings to ignore if they are unknown',
1178         'doc' : '''
1179 Names of settings to be ignored while parsing configuration files, if the setting
1180 name is unknown to PowerDNS.
1181
1182 Useful during upgrade testing.
1183  ''',
1184     },
1185     {
1186         'name' : 'include_dir',
1187         'section' : 'recursor',
1188         'type' : LType.String,
1189         'default' : '',
1190         'help' : 'Include *.conf files from this directory',
1191         'doc' : '''
1192 Directory to scan for additional config files. All files that end with .conf are loaded in order using ``POSIX`` as locale.
1193  ''',
1194     },
1195     {
1196         'name' : 'latency_statistic_size',
1197         'section' : 'recursor',
1198         'type' : LType.Uint64,
1199         'default' : '10000',
1200         'help' : 'Number of latency values to calculate the qa-latency average',
1201         'doc' : '''
1202 Indication of how many queries will be averaged to get the average latency reported by the 'qa-latency' metric.
1203  ''',
1204     },
1205     {
1206         'name' : 'listen',
1207         'section' : 'incoming',
1208         'oldname' : 'local-address',
1209         'type' : LType.ListSocketAddresses,
1210         'default' : '127.0.0.1',
1211         'help' : 'IP addresses to listen on, separated by spaces or commas. Also accepts ports.',
1212         'doc' : '''
1213 Local IP addresses to which we bind. Each address specified can
1214 include a port number; if no port is included then the
1215 :ref:`setting-local-port` port will be used for that address. If a
1216 port number is specified, it must be separated from the address with a
1217 ':'; for an IPv6 address the address must be enclosed in square
1218 brackets.
1219
1220 Examples::
1221
1222   local-address=127.0.0.1 ::1
1223   local-address=0.0.0.0:5353
1224   local-address=[::]:8053
1225   local-address=127.0.0.1:53, [::1]:5353
1226  ''',
1227         'doc-new' : '''
1228 Local IP addresses to which we bind. Each address specified can
1229 include a port number; if no port is included then the
1230 :ref:`setting-local-port` port will be used for that address. If a
1231 port number is specified, it must be separated from the address with a
1232 ':'; for an IPv6 address the address must be enclosed in square
1233 brackets.
1234
1235 Example:
1236
1237 .. code-block:: yaml
1238
1239   incoming:
1240     listen:
1241       - 127.0.0.1
1242       - listen: '[::1]:5353'
1243       - listen: '::'
1244  ''',
1245     },
1246     {
1247         'name' : 'port',
1248         'section' : 'incoming',
1249         'oldname' : 'local-port',
1250         'type' : LType.Uint64,
1251         'default' : '53',
1252         'help' : 'port to listen on',
1253         'doc' : '''
1254 Local port to bind to.
1255 If an address in :ref:`setting-local-address` does not have an explicit port, this port is used.
1256  ''',
1257     },
1258     {
1259         'name' : 'timestamp',
1260         'section' : 'logging',
1261         'oldname' : 'log-timestamp',
1262         'type' : LType.Bool,
1263         'default' : 'true',
1264         'help' : 'Print timestamps in log lines, useful to disable when running with a tool that timestamps stderr already',
1265         'doc' : '''
1266
1267  ''',
1268     },
1269     {
1270         'name' : 'non_local_bind',
1271         'section' : 'incoming',
1272         'type' : LType.Bool,
1273         'default' : 'false',
1274         'help' : 'Enable binding to non-local addresses by using FREEBIND / BINDANY socket options',
1275         'doc' : '''
1276 Bind to addresses even if one or more of the :ref:`setting-local-address`'s do not exist on this server.
1277 Setting this option will enable the needed socket options to allow binding to non-local addresses.
1278 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.
1279  ''',
1280     },
1281     {
1282         'name' : 'loglevel',
1283         'section' : 'logging',
1284         'type' : LType.Uint64,
1285         'default' : '6',
1286         'help' : 'Amount of logging. Higher is more. Do not set below 3',
1287         'doc' : '''
1288 Amount of logging. The higher the number, the more lines logged.
1289 Corresponds to ``syslog`` level values (e.g. 0 = ``emergency``, 1 = ``alert``, 2 = ``critical``, 3 = ``error``, 4 = ``warning``, 5 = ``notice``, 6 = ``info``, 7 = ``debug``).
1290 Each level includes itself plus the lower levels before it.
1291 Not recommended to set this below 3.
1292 If :ref:`setting-quiet` is ``no/false``, :ref:`setting-loglevel` will be minimally set to ``6 (info)``.
1293  ''',
1294         'versionchanged': ('5.0.0', 'Previous version would not allow setting a level below ``3 (error)``.')
1295     },
1296     {
1297         'name' : 'common_errors',
1298         'section' : 'logging',
1299         'oldname' : 'log-common-errors',
1300         'type' : LType.Bool,
1301         'default' : 'false',
1302         'help' : 'If we should log rather common errors',
1303         'doc' : '''
1304 Some DNS errors occur rather frequently and are no cause for alarm.
1305  ''',
1306     },
1307     {
1308         'name' : 'rpz_changes',
1309         'section' : 'logging',
1310         'oldname' : 'log-rpz-changes',
1311         'type' : LType.Bool,
1312         'default' : 'false',
1313         'help' : 'Log additions and removals to RPZ zones at Info level',
1314         'doc' : '''
1315 Log additions and removals to RPZ zones at Info (6) level instead of Debug (7).
1316  ''',
1317     'versionadded': '4.1.0'
1318     },
1319     {
1320         'name' : 'facility',
1321         'section' : 'logging',
1322         'oldname' : 'logging-facility',
1323         'type' : LType.String,
1324         'default' : '',
1325         'help' : 'Facility to log messages as. 0 corresponds to local0',
1326         'doc' : '''
1327 If set to a digit, logging is performed under this LOCAL facility.
1328 See :ref:`logging`.
1329 Do not pass names like 'local0'!
1330  ''',
1331     },
1332     {
1333         'name' : 'lowercase',
1334         'section' : 'outgoing',
1335         'oldname' : 'lowercase-outgoing',
1336         'type' : LType.Bool,
1337         'default' : 'false',
1338         'help' : 'Force outgoing questions to lowercase',
1339         'doc' : '''
1340 Set to true to lowercase the outgoing queries.
1341 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.
1342 Broken authoritative servers might give a wrong or broken answer on this encoding.
1343 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.
1344  ''',
1345     },
1346     {
1347         'name' : 'lua_config_file',
1348         'section' : 'recursor',
1349         'type' : LType.String,
1350         'default' : '',
1351         'help' : 'More powerful configuration options',
1352         'doc' : '''
1353 If set, and Lua support is compiled in, this will load an additional configuration file for newer features and more complicated setups.
1354 See :doc:`lua-config/index` for the options that can be set in this file.
1355  ''',
1356     },
1357     {
1358         'name' : 'lua_dns_script',
1359         'section' : 'recursor',
1360         'type' : LType.String,
1361         'default' : '',
1362         'help' : 'Filename containing an optional Lua script that will be used to modify dns answers',
1363         'doc' : '''
1364 Path to a lua file to manipulate the Recursor's answers. See :doc:`lua-scripting/index` for more information.
1365  ''',
1366     },
1367     {
1368         'name' : 'lua_maintenance_interval',
1369         'section' : 'recursor',
1370         'type' : LType.Uint64,
1371         'default' : '1',
1372         'help' : 'Number of seconds between calls to the lua user defined maintenance() function',
1373         'doc' : '''
1374 The interval between calls to the Lua user defined `maintenance()` function in seconds.
1375 See :ref:`hooks-maintenance-callback`
1376  ''',
1377     'versionadded': '4.2.0'
1378     },
1379     {
1380         'name' : 'max_busy_dot_probes',
1381         'section' : 'outgoing',
1382         'type' : LType.Uint64,
1383         'default' : '0',
1384         'help' : 'Maximum number of concurrent DoT probes',
1385         'doc' : '''
1386 Limit the maximum number of simultaneous DoT probes the Recursor will schedule.
1387 The default value 0 means no DoT probes are scheduled.
1388
1389 DoT probes are used to check if an authoritative server's IP address supports DoT.
1390 If the probe determines an IP address supports DoT, the Recursor will use DoT to contact it for subsequent queries until a failure occurs.
1391 After a failure, the Recursor will stop using DoT for that specific IP address for a while.
1392 The results of probes are remembered and can be viewed by the ``rec_control dump-dot-probe-map`` command.
1393 If the maximum number of pending probes is reached, no probes will be scheduled, even if no DoT status is known for an address.
1394 If the result of a probe is not yet available, the Recursor will contact the authoritative server in the regular way, unless an authoritative server is configured to be contacted over DoT always using :ref:`setting-dot-to-auth-names`.
1395 In that case no probe will be scheduled.
1396
1397 .. note::
1398   DoT probing is an experimental feature.
1399   Please test thoroughly to determine if it is suitable in your specific production environment before enabling.
1400  ''',
1401     'versionadded': '4.7.0'
1402     },
1403     {
1404         'name' : 'max_cache_bogus_ttl',
1405         'section' : 'recordcache',
1406         'type' : LType.Uint64,
1407         'default' : '3600',
1408         'help' : 'maximum number of seconds to keep a Bogus (positive or negative) cached entry in memory',
1409         'doc' : '''
1410 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.
1411  ''',
1412     'versionadded': '4.2.0'
1413     },
1414     {
1415         'name' : 'max_entries',
1416         'section' : 'recordcache',
1417         'oldname' : 'max-cache-entries',
1418         'type' : LType.Uint64,
1419         'default' : '1000000',
1420         'help' : 'If set, maximum number of entries in the main cache',
1421         'doc' : '''
1422 Maximum number of DNS record cache entries, shared by all threads since 4.4.0.
1423 Each entry associates a name and type with a record set.
1424 The size of the negative cache is 10% of this number.
1425  ''',
1426     },
1427     {
1428         'name' : 'max_ttl',
1429         'section' : 'recordcache',
1430         'oldname' : 'max-cache-ttl',
1431         'type' : LType.Uint64,
1432         'default' : '86400',
1433         'help' : 'maximum number of seconds to keep a cached entry in memory',
1434         'doc' : '''
1435 Maximum number of seconds to cache an item in the DNS cache, no matter what the original TTL specified.
1436 This value also controls the refresh period of cached root data.
1437 See :ref:`handling-of-root-hints` for more information on this.
1438  ''',
1439      'versionchanged': ('4.1.0', 'The minimum value of this setting is 15. i.e. setting this to lower than 15 will make this value 15.')
1440     },
1441     {
1442         'name' : 'max_concurrent_requests_per_tcp_connection',
1443         'section' : 'incoming',
1444         'type' : LType.Uint64,
1445         'default' : '10',
1446         'help' : 'Maximum number of requests handled concurrently per TCP connection',
1447         'doc' : '''
1448 Maximum number of incoming requests handled concurrently per tcp
1449 connection. This number must be larger than 0 and smaller than 65536
1450 and also smaller than `max-mthreads`.
1451  ''',
1452     'versionadded': '4.3.0'
1453     },
1454     {
1455         'name' : 'max_include_depth',
1456         'section' : 'recursor',
1457         'type' : LType.Uint64,
1458         'default' : '20',
1459         'help' : 'Maximum nested $INCLUDE depth when loading a zone from a file',
1460         'doc' : '''
1461 Maximum number of nested ``$INCLUDE`` directives while processing a zone file.
1462 Zero mean no ``$INCLUDE`` directives will be accepted.
1463  ''',
1464     'versionadded': '4.6.0'
1465     },
1466     {
1467         'name' : 'max_generate_steps',
1468         'section' : 'recursor',
1469         'type' : LType.Uint64,
1470         'default' : '0',
1471         'help' : 'Maximum number of $GENERATE steps when loading a zone from a file',
1472         'doc' : '''
1473 Maximum number of steps for a '$GENERATE' directive when parsing a
1474 zone file. This is a protection measure to prevent consuming a lot of
1475 CPU and memory when untrusted zones are loaded. Default to 0 which
1476 means unlimited.
1477  ''',
1478     'versionadded': '4.3.0'
1479     },
1480     {
1481         'name' : 'max_mthreads',
1482         'section' : 'recursor',
1483         'type' : LType.Uint64,
1484         'default' : '2048',
1485         'help' : 'Maximum number of simultaneous Mtasker threads',
1486         'doc' : '''
1487 Maximum number of simultaneous MTasker threads.
1488  ''',
1489     },
1490     {
1491         'name' : 'max_entries',
1492         'section' : 'packetcache',
1493         'oldname' : 'max-packetcache-entries',
1494         'type' : LType.Uint64,
1495         'default' : '500000',
1496         'help' : 'maximum number of entries to keep in the packetcache',
1497         'doc' : '''
1498 Maximum number of Packet Cache entries. Sharded and shared by all threads since 4.9.0.
1499 ''',
1500     },
1501     {
1502         'name' : 'max_qperq',
1503         'section' : 'outgoing',
1504         'type' : LType.Uint64,
1505         'default' : '50',
1506         'help' : 'Maximum outgoing queries per query',
1507         'doc' : '''
1508 The maximum number of outgoing queries that will be sent out during the resolution of a single client query.
1509 This is used to avoid cycles resolving names.
1510  ''',
1511         'versionchanged': ('5.1.0', 'The default used to be 60, with an extra allowance if qname minimization was enabled. Having better algorithms allows for a lower default limit.'),
1512     },
1513     {
1514         'name' : 'max_ns_address_qperq',
1515         'section' : 'outgoing',
1516         'type' : LType.Uint64,
1517         'default' : '10',
1518         'help' : 'Maximum outgoing NS address queries per query',
1519         'doc' : '''
1520 The maximum number of outgoing queries with empty replies for
1521 resolving nameserver names to addresses we allow during the resolution
1522 of a single client query. If IPv6 is enabled, an A and a AAAA query
1523 for a name counts as 1. If a zone publishes more than this number of
1524 NS records, the limit is further reduced for that zone by lowering
1525 it by the number of NS records found above the
1526 :ref:`setting-max-ns-address-qperq` value. The limit wil not be reduced to a
1527 number lower than 5.
1528  ''',
1529     'versionadded' : ['4.1.16', '4.2.2', '4.3.1']
1530     },
1531     {
1532         'name' : 'max_ns_per_resolve',
1533         'section' : 'outgoing',
1534         'type' : LType.Uint64,
1535         'default' : '13',
1536         'help' : 'Maximum number of NS records to consider to resolve a name, 0 is no limit',
1537         'doc' : '''
1538 The maximum number of NS records that will be considered to select a nameserver to contact to resolve a name.
1539 If a zone has more than :ref:`setting-max-ns-per-resolve` NS records, a random sample of this size will be used.
1540 If :ref:`setting-max-ns-per-resolve` is zero, no limit applies.
1541  ''',
1542     'versionadded': ['4.8.0', '4.7.3', '4.6.4', '4.5.11']
1543     },
1544     {
1545         'name' : 'max_negative_ttl',
1546         'section' : 'recordcache',
1547         'type' : LType.Uint64,
1548         'default' : '3600',
1549         'help' : 'maximum number of seconds to keep a negative cached entry in memory',
1550         'doc' : '''
1551 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.
1552 In practice, caches can become saturated with hundreds of thousands of hosts which are tried only once.
1553 This setting, which defaults to 3600 seconds, puts a maximum on the amount of time negative entries are cached.
1554  ''',
1555     },
1556     {
1557         'name' : 'max_recursion_depth',
1558         'section' : 'recursor',
1559         'type' : LType.Uint64,
1560         'default' : '16',
1561         'help' : 'Maximum number of internal recursion calls per query, 0 for unlimited',
1562         'doc' : '''
1563 Total maximum number of internal recursion calls the server may use to answer a single query.
1564 0 means unlimited.
1565 The value of :ref:`setting-stack-size` should be increased together with this one to prevent the stack from overflowing.
1566 If :ref:`setting-qname-minimization` is enabled, the fallback code in case of a failing resolve is allowed an additional `max-recursion-depth/2`.
1567  ''',
1568      'versionchanged': [('4.1.0', 'Before 4.1.0, this settings was unlimited.'),
1569                         ('4.9.0', "Before 4.9.0 this setting's default was 40 and the limit on ``CNAME`` chains (fixed at 16) acted as a bound on he recursion depth.")]
1570     },
1571     {
1572         'name' : 'max_tcp_clients',
1573         'section' : 'incoming',
1574         'type' : LType.Uint64,
1575         'default' : '128',
1576         'help' : 'Maximum number of simultaneous TCP clients',
1577         'doc' : '''
1578 Maximum number of simultaneous incoming TCP connections allowed.
1579  ''',
1580     },
1581     {
1582         'name' : 'max_tcp_per_client',
1583         'section' : 'incoming',
1584         'type' : LType.Uint64,
1585         'default' : '0',
1586         'help' : 'If set, maximum number of TCP sessions per client (IP address)',
1587         'doc' : '''
1588 Maximum number of simultaneous incoming TCP connections allowed per client (remote IP address).
1589  0 means unlimited.
1590  ''',
1591     },
1592     {
1593         'name' : 'max_tcp_queries_per_connection',
1594         'section' : 'incoming',
1595         'type' : LType.Uint64,
1596         'default' : '0',
1597         'help' : 'If set, maximum number of TCP queries in a TCP connection',
1598         'doc' : '''
1599 Maximum number of DNS queries in a TCP connection.
1600 0 means unlimited.
1601  ''',
1602     'versionadded': '4.1.0'
1603     },
1604     {
1605         'name' : 'max_total_msec',
1606         'section' : 'recursor',
1607         'type' : LType.Uint64,
1608         'default' : '7000',
1609         'help' : 'Maximum total wall-clock time per query in milliseconds, 0 for unlimited',
1610         'doc' : '''
1611 Total maximum number of milliseconds of wallclock time the server may use to answer a single query.
1612 0 means unlimited.
1613  ''',
1614     },
1615     {
1616         'name' : 'max_udp_queries_per_round',
1617         'section' : 'incoming',
1618         'type' : LType.Uint64,
1619         'default' : '10000',
1620         'help' : 'Maximum number of UDP queries processed per recvmsg() round, before returning back to normal processing',
1621         'doc' : '''
1622 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
1623 neglect scheduling new ``mthreads``, handling responses from authoritative servers or responding to :doc:`rec_control <manpages/rec_control.1>`
1624 requests.
1625 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
1626 returning back to normal processing and handling other events.
1627  ''',
1628     'versionadded': '4.1.4'
1629     },
1630     {
1631         'name' : 'minimum_ttl_override',
1632         'section' : 'recursor',
1633         'type' : LType.Uint64,
1634         'default' : '1',
1635         'help' : 'The minimum TTL',
1636         'doc' : '''
1637 This setting artificially raises all TTLs to be at least this long.
1638 Setting this to a value greater than 1 technically is an RFC violation, but might improve performance a lot.
1639 Using a value of 0 impacts performance of TTL 0 records greatly, since it forces the recursor to contact
1640 authoritative servers each time a client requests them.
1641 Can be set at runtime using ``rec_control set-minimum-ttl 3600``.
1642  ''',
1643      'versionchanged': ('4.5.0', 'Old versions used default 0.')
1644     },
1645     {
1646         'name' : 'tracking',
1647         'section' : 'nod',
1648         'oldname' : 'new-domain-tracking',
1649         'type' : LType.Bool,
1650         'default' : 'false',
1651         'help' : 'Track newly observed domains (i.e. never seen before).',
1652         'doc' : '''
1653 Whether to track newly observed domains, i.e. never seen before. This
1654 is a probabilistic algorithm, using a stable bloom filter to store
1655 records of previously seen domains. When enabled for the first time,
1656 all domains will appear to be newly observed, so the feature is best
1657 left enabled for e.g. a week or longer before using the results. Note
1658 that this feature is optional and must be enabled at compile-time,
1659 thus it may not be available in all pre-built packages.
1660 If protobuf is enabled and configured, then the newly observed domain
1661 status will appear as a flag in Response messages.
1662  ''',
1663     'versionadded': '4.2.0'
1664     },
1665     {
1666         'name' : 'log',
1667         'section' : 'nod',
1668         'oldname' : 'new-domain-log',
1669         'type' : LType.Bool,
1670         'default' : 'true',
1671         'help' : 'Log newly observed domains.',
1672         'doc' : '''
1673 If a newly observed domain is detected, log that domain in the
1674 recursor log file. The log line looks something like::
1675
1676  Jul 18 11:31:25 Newly observed domain nod=sdfoijdfio.com
1677  ''',
1678     'versionadded': '4.2.0'
1679     },
1680     {
1681         'name' : 'lookup',
1682         'section' : 'nod',
1683         'oldname' : 'new-domain-lookup',
1684         'type' : LType.String,
1685         'default' : '',
1686         'help' : 'Perform a DNS lookup newly observed domains as a subdomain of the configured domain',
1687         'doc' : '''
1688 If a domain is specified, then each time a newly observed domain is
1689 detected, the recursor will perform an A record lookup of '<newly
1690 observed domain>.<lookup domain>'. For example if 'new-domain-lookup'
1691 is configured as 'nod.powerdns.com', and a new domain 'xyz123.tv' is
1692 detected, then an A record lookup will be made for
1693 'xyz123.tv.nod.powerdns.com'. This feature gives a way to share the
1694 newly observed domain with partners, vendors or security teams. The
1695 result of the DNS lookup will be ignored by the recursor.
1696  ''',
1697     'versionadded': '4.2.0'
1698     },
1699     {
1700         'name' : 'db_size',
1701         'section' : 'nod',
1702         'oldname' : 'new-domain-db-size',
1703         'type' : LType.Uint64,
1704         'default' : '67108864',
1705         'help' : 'Size of the DB used to track new domains in terms of number of cells. Defaults to 67108864',
1706         'doc' : '''
1707 The default size of the stable bloom filter used to store previously
1708 observed domains is 67108864. To change the number of cells, use this
1709 setting. For each cell, the SBF uses 1 bit of memory, and one byte of
1710 disk for the persistent file.
1711 If there are already persistent files saved to disk, this setting will
1712 have no effect unless you remove the existing files.
1713  ''',
1714     'versionadded': '4.2.0'
1715     },
1716     {
1717         'name' : 'history_dir',
1718         'section' : 'nod',
1719         'oldname' : 'new-domain-history-dir',
1720         'type' : LType.String,
1721         'default' : 'NODCACHEDIRNOD',
1722         'docdefault': 'Determined by distribution',
1723         'help' : 'Persist new domain tracking data here to persist between restarts',
1724         'doc' : '''
1725 This setting controls which directory is used to store the on-disk
1726 cache of previously observed domains.
1727
1728 The default depends on ``LOCALSTATEDIR`` when building the software.
1729 Usually this comes down to ``/var/lib/pdns-recursor/nod`` or ``/usr/local/var/lib/pdns-recursor/nod``).
1730
1731 The newly observed domain feature uses a stable bloom filter to store
1732 a history of previously observed domains. The data structure is
1733 synchronized to disk every 10 minutes, and is also initialized from
1734 disk on startup. This ensures that previously observed domains are
1735 preserved across recursor restarts.
1736 If you change the new-domain-db-size setting, you must remove any files
1737 from this directory.
1738  ''',
1739     'versionadded': '4.2.0'
1740     },
1741     {
1742         'name' : 'db_snapshot_interval',
1743         'section' : 'nod',
1744         'oldname' : 'new-domain-db-snapshot-interval',
1745         'type' : LType.Uint64,
1746         'default' : '600',
1747         'help' : 'Interval (in seconds) to write the NOD and UDR DB snapshots',
1748         'doc' : '''
1749 Interval (in seconds) to write the NOD and UDR DB snapshots.
1750 Set to zero to disable snapshot writing.',
1751  ''',
1752         'versionadded': '5.1.0'
1753     },
1754     {
1755         'name' : 'whitelist',
1756         'section' : 'nod',
1757         'oldname' : 'new-domain-whitelist',
1758         'type' : LType.String,
1759         'default' : '',
1760         'help' : 'List of domains (and implicitly all subdomains) which will never be considered a new domain (deprecated)',
1761         'doc' : '',
1762         'versionadded': '4.2.0',
1763         'deprecated': ('4.5.0', 'Use :ref:`setting-new-domain-ignore-list`.'),
1764         'skip-yaml': True,
1765     },
1766     {
1767         'name' : 'ignore_list',
1768         'section' : 'nod',
1769         'oldname' : 'new-domain-ignore-list',
1770         'type' : LType.ListStrings,
1771         'default' : '',
1772         'help' : 'List of domains (and implicitly all subdomains) which will never be considered a new domain',
1773         'doc' : '''
1774 This setting is a list of all domains (and implicitly all subdomains)
1775 that will never be considered a new domain. For example, if the domain
1776 'xyz123.tv' is in the list, then 'foo.bar.xyz123.tv' will never be
1777 considered a new domain. One use-case for the ignore list is to never
1778 reveal details of internal subdomains via the new-domain-lookup
1779 feature.
1780  ''',
1781     'versionadded': '4.5.0'
1782     },
1783     {
1784         'name' : 'pb_tag',
1785         'section' : 'nod',
1786         'oldname' : 'new-domain-pb-tag',
1787         'type' : LType.String,
1788         'default' : 'pdns-nod',
1789         'help' : 'If protobuf is configured, the tag to use for messages containing newly observed domains. Defaults to \'pdns-nod\'',
1790         'doc' : '''
1791 If protobuf is configured, then this tag will be added to all protobuf response messages when
1792 a new domain is observed.
1793  ''',
1794     'versionadded': '4.2.0'
1795     },
1796     {
1797         'name' : 'network_timeout',
1798         'section' : 'outgoing',
1799         'type' : LType.Uint64,
1800         'default' : '1500',
1801         'help' : 'Wait this number of milliseconds for network i/o',
1802         'doc' : '''
1803 Number of milliseconds to wait for a remote authoritative server to respond.
1804  ''',
1805     },
1806     {
1807         'name' : 'no_shuffle',
1808         'section' : 'recursor',
1809         'type' : LType.Bool,
1810         'default' : 'false',
1811         'help' : 'Don\'t change',
1812         'doc' : 'SKIP',
1813         'skip-yaml': True,
1814     },
1815     {
1816         'name' : 'non_resolving_ns_max_fails',
1817         'section' : 'outgoing',
1818         'type' : LType.Uint64,
1819         'default' : '5',
1820         'help' : 'Number of failed address resolves of a nameserver to start throttling it, 0 is disabled',
1821         'doc' : '''
1822 Number of failed address resolves of a nameserver name to start throttling it, 0 is disabled.
1823 Nameservers matching :ref:`setting-dont-throttle-names` will not be throttled.
1824  ''',
1825     'versionadded': '4.5.0'
1826     },
1827     {
1828         'name' : 'non_resolving_ns_throttle_time',
1829         'section' : 'outgoing',
1830         'type' : LType.Uint64,
1831         'default' : '60',
1832         'help' : 'Number of seconds to throttle a nameserver with a name failing to resolve',
1833         'doc' : '''
1834 Number of seconds to throttle a nameserver with a name failing to resolve.
1835  ''',
1836     'versionadded': '4.5.0'
1837     },
1838     {
1839         'name' : 'nothing_below_nxdomain',
1840         'section' : 'recursor',
1841         'type' : LType.String,
1842         'default' : 'dnssec',
1843         'help' : 'When an NXDOMAIN exists in cache for a name with fewer labels than the qname, send NXDOMAIN without doing a lookup (see RFC 8020)',
1844         'doc' : '''
1845 - One of ``no``, ``dnssec``, ``yes``.
1846
1847 The type of :rfc:`8020` handling using cached NXDOMAIN responses.
1848 This RFC specifies that NXDOMAIN means that the DNS tree under the denied name MUST be empty.
1849 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.
1850
1851 For instance, when ``foo.example.net`` is negatively cached, any query
1852 matching ``*.foo.example.net`` will be answered with NXDOMAIN directly
1853 without consulting authoritative servers.
1854
1855 ``no``
1856   No :rfc:`8020` processing is done.
1857
1858 ``dnssec``
1859   :rfc:`8020` processing is only done using cached NXDOMAIN records that are
1860   DNSSEC validated.
1861
1862 ``yes``
1863   :rfc:`8020` processing is done using any non-Bogus NXDOMAIN record
1864   available in the cache.
1865  ''',
1866     'versionadded': '4.3.0'
1867     },
1868     {
1869         'name' : 'nsec3_max_iterations',
1870         'section' : 'dnssec',
1871         'type' : LType.Uint64,
1872         'default' : '50',
1873         'help' : 'Maximum number of iterations allowed for an NSEC3 record',
1874         'doc' : '''
1875 Maximum number of iterations allowed for an NSEC3 record.
1876 If an answer containing an NSEC3 record with more iterations is received, its DNSSEC validation status is treated as ``Insecure``.
1877  ''',
1878         'versionadded': '4.1.0',
1879         'versionchanged': [('4.5.2', 'Default is now 150, was 2500 before.'),
1880                            ('5.0.0', 'Default is now 50, was 150 before.')]
1881     },
1882     {
1883         'name' : 'max_rrsigs_per_record',
1884         'section' : 'dnssec',
1885         'type' : LType.Uint64,
1886         'default' : '2',
1887         'help' : 'Maximum number of RRSIGs to consider when validating a given record',
1888         'doc' : '''
1889 Maximum number of RRSIGs we are willing to cryptographically check when validating a given record. Expired or not yet incepted RRSIGs do not count toward to this limit.
1890  ''',
1891         'versionadded': ['5.0.2', '4.9.3', '4.8.6'],
1892     },
1893     {
1894         'name' : 'max_nsec3s_per_record',
1895         'section' : 'dnssec',
1896         'type' : LType.Uint64,
1897         'default' : '10',
1898         'help' : 'Maximum number of NSEC3s to consider when validating a given denial of existence',
1899         'doc' : '''
1900 Maximum number of NSEC3s to consider when validating a given denial of existence.
1901  ''',
1902         'versionadded': ['5.0.2', '4.9.3', '4.8.6'],
1903     },
1904     {
1905         'name' : 'max_signature_validations_per_query',
1906         'section' : 'dnssec',
1907         'type' : LType.Uint64,
1908         'default' : '30',
1909         'help' : 'Maximum number of RRSIG signatures we are willing to validate per incoming query',
1910         'doc' : '''
1911 Maximum number of RRSIG signatures we are willing to validate per incoming query.
1912  ''',
1913         'versionadded': ['5.0.2', '4.9.3', '4.8.6'],
1914     },
1915     {
1916         'name' : 'max_nsec3_hash_computations_per_query',
1917         'section' : 'dnssec',
1918         'type' : LType.Uint64,
1919         'default' : '600',
1920         'help' : 'Maximum number of NSEC3 hashes that we are willing to compute during DNSSEC validation, per incoming query',
1921         'doc' : '''
1922 Maximum number of NSEC3 hashes that we are willing to compute during DNSSEC validation, per incoming query.
1923  ''',
1924         'versionadded': ['5.0.2', '4.9.3', '4.8.6'],
1925     },
1926     {
1927         'name' : 'aggressive_cache_max_nsec3_hash_cost',
1928         'section' : 'dnssec',
1929         'type' : LType.Uint64,
1930         'default' : '150',
1931         'help' : 'Maximum estimated NSEC3 cost for a given query to consider aggressive use of the NSEC3 cache',
1932         'doc' : '''
1933 Maximum estimated NSEC3 cost for a given query to consider aggressive use of the NSEC3 cache. The cost is estimated based on a heuristic taking the zone's NSEC3 salt and iterations parameters into account, as well at the number of labels of the requested name. For example a query for a name like a.b.c.d.e.f.example.com. in an example.com zone. secured with NSEC3 and 10 iterations (NSEC3 iterations count of 9) and an empty salt will have an estimated worst-case cost of 10 (iterations) * 6 (number of labels) = 60. The aggressive NSEC cache is an optimization to reduce the number of queries to authoritative servers, which is especially useful when a zone is under pseudo-random subdomain attack, and we want to skip it the zone parameters make it expensive.
1934 ''',
1935         'versionadded': ['5.0.2', '4.9.3', '4.8.6'],
1936     },
1937     {
1938         'name' : 'max_ds_per_zone',
1939         'section' : 'dnssec',
1940         'type' : LType.Uint64,
1941         'default' : '8',
1942         'help' : 'Maximum number of DS records to consider per zone',
1943         'doc' : '''
1944 Maximum number of DS records to consider when validating records inside a zone..
1945  ''',
1946         'versionadded': ['5.0.2', '4.9.3', '4.8.6'],
1947     },
1948     {
1949         'name' : 'max_dnskeys',
1950         'section' : 'dnssec',
1951         'type' : LType.Uint64,
1952         'default' : '2',
1953         'help' : 'Maximum number of DNSKEYs with the same algorithm and tag to consider when validating a given record',
1954         'doc' : '''
1955 Maximum number of DNSKEYs with the same algorithm and tag to consider when validating a given record. Setting this value to 1 effectively denies DNSKEY tag collisions in a zone.
1956  ''',
1957         'versionadded': ['5.0.2', '4.9.3', '4.8.6'],
1958     },
1959     {
1960         'name' : 'ttl',
1961         'section' : 'packetcache',
1962         'oldname' : 'packetcache-ttl',
1963         'type' : LType.Uint64,
1964         'default' : '86400',
1965         'help' : 'maximum number of seconds to keep a cached entry in packetcache',
1966         'doc' : '''
1967 Maximum number of seconds to cache an item in the packet cache, no matter what the original TTL specified.
1968  ''',
1969         'versionchanged': ('4.9.0', 'The default was changed from 3600 (1 hour) to 86400 (24 hours).')
1970     },
1971     {
1972         'name' : 'negative_ttl',
1973         'section' : 'packetcache',
1974         'oldname' : 'packetcache-negative-ttl',
1975         'type' : LType.Uint64,
1976         'default' : '60',
1977         'help' : 'maximum number of seconds to keep a cached NxDomain or NoData entry in packetcache',
1978         'doc' : '''
1979 Maximum number of seconds to cache an ``NxDomain`` or ``NoData`` answer in the packetcache.
1980 This setting's maximum is capped to :ref:`setting-packetcache-ttl`.
1981 i.e. setting ``packetcache-ttl=15`` and keeping ``packetcache-negative-ttl`` at the default will lower ``packetcache-negative-ttl`` to ``15``.
1982  ''',
1983     'versionadded': '4.9.0'
1984     },
1985     {
1986         'name' : 'servfail_ttl',
1987         'section' : 'packetcache',
1988         'oldname' : 'packetcache-servfail-ttl',
1989         'type' : LType.Uint64,
1990         'default' : '60',
1991         'help' : 'maximum number of seconds to keep a cached servfail entry in packetcache',
1992         'doc' : '''
1993 Maximum number of seconds to cache an answer indicating a failure to resolve in the packet cache.
1994 Before version 4.6.0 only ``ServFail`` answers were considered as such. Starting with 4.6.0, all responses with a code other than ``NoError`` and ``NXDomain``, or without records in the answer and authority sections, are considered as a failure to resolve.
1995 Since 4.9.0, negative answers are handled separately from resolving failures.
1996  ''',
1997         'doc-rst' : '''
1998         'versionchanged': ('4.0.0', "This setting's maximum is capped to :ref:`setting-packetcache-ttl`.
1999     i.e. setting ``packetcache-ttl=15`` and keeping ``packetcache-servfail-ttl`` at the default will lower ``packetcache-servfail-ttl`` to ``15``.")
2000  '''
2001     },
2002     {
2003         'name' : 'shards',
2004         'section' : 'packetcache',
2005         'oldname' : 'packetcache-shards',
2006         'type' : LType.Uint64,
2007         'default' : '1024',
2008         'help' : 'Number of shards in the packet cache',
2009         'doc' : '''
2010 Sets the number of shards in the packet cache. If you have high contention as reported by ``packetcache-contented/packetcache-acquired``,
2011 you can try to enlarge this value or run with fewer threads.
2012  ''',
2013     'versionadded': '4.9.0'
2014     },
2015     {
2016         'name' : 'pdns_distributes_queries',
2017         'section' : 'incoming',
2018         'type' : LType.Bool,
2019         'default' : 'false',
2020         'help' : 'If PowerDNS itself should distribute queries over threads',
2021         'doc' : '''
2022 If set, PowerDNS will use distinct threads to listen to client sockets and distribute that work to worker-threads using a hash of the query.
2023 This feature should maximize the cache hit ratio on versions before 4.9.0.
2024 To use more than one thread set :ref:`setting-distributor-threads` in version 4.2.0 or newer.
2025 Enabling should improve performance on systems where :ref:`setting-reuseport` does not have the effect of
2026 balancing the queries evenly over multiple worker threads.
2027  ''',
2028      'versionchanged': ('4.9.0', 'Default changed to ``no``, previously it was ``yes``.')
2029     },
2030     {
2031         'name' : 'processes',
2032         'section' : 'recursor',
2033         'type' : LType.Uint64,
2034         'default' : '1',
2035         'help' : 'Launch this number of processes (EXPERIMENTAL, DO NOT CHANGE)',
2036         'doc' : '''SKIP''',
2037         'skip-yaml': True,
2038     },
2039     {
2040         'name' : 'protobuf_use_kernel_timestamp',
2041         'section' : 'logging',
2042         'type' : LType.Bool,
2043         'default' : 'false',
2044         'help' : 'Compute the latency of queries in protobuf messages by using the timestamp set by the kernel when the query was received (when available)',
2045         'doc' : '''
2046 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.
2047  ''',
2048     'versionadded': '4.2.0'
2049     },
2050     {
2051         'name' : 'proxy_protocol_from',
2052         'section' : 'incoming',
2053         'type' : LType.ListSubnets,
2054         'default' : '',
2055         'help' : 'A Proxy Protocol header is required from these subnets',
2056         'doc' : '''
2057 Ranges that are required to send a Proxy Protocol version 2 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.
2058 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.
2059
2060 Note that once a Proxy Protocol header has been received, the source address from the proxy header instead of the address of the proxy will be checked against the :ref:`setting-allow-from` ACL.
2061
2062 The dnsdist docs have `more information about the PROXY protocol <https://dnsdist.org/advanced/passing-source-address.html#proxy-protocol>`_.
2063  ''',
2064         'versionadded' : '4.4.0',
2065         'versionchanged' : ('5.0.4', 'YAML settings only: previously this was defined as a string instead of a sequence')
2066     },
2067     {
2068         'name' : 'proxy_protocol_exceptions',
2069         'section' : 'incoming',
2070         'type' : LType.ListSocketAddresses,
2071         'default' : '',
2072         'help' : 'A Proxy Protocol header should not be used for these listen addresses.',
2073         'doc' : '''
2074 If set, clients sending from an address in :ref:`setting-proxy-protocol-from` to a address:port listed here are excluded from using the Proxy Protocol.
2075 If no port is specified, port 53 is assumed.
2076 This is typically used to provide an easy to use address and port to send debug queries to.
2077  ''',
2078         'versionadded' : '5.1.0',
2079     },
2080     {
2081         'name' : 'proxy_protocol_maximum_size',
2082         'section' : 'incoming',
2083         'type' : LType.Uint64,
2084         'default' : '512',
2085         'help' : 'The maximum size of a proxy protocol payload, including the TLV values',
2086         'doc' : '''
2087 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.
2088  ''',
2089     'versionadded': '4.4.0'
2090     },
2091     {
2092         'name' : 'public_suffix_list_file',
2093         'section' : 'recursor',
2094         'type' : LType.String,
2095         'default' : '',
2096         'help' : 'Path to the Public Suffix List file, if any',
2097         'doc' : '''
2098 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.
2099  ''',
2100     'versionadded': '4.2.0'
2101     },
2102     {
2103         'name' : 'qname_minimization',
2104         'section' : 'recursor',
2105         'type' : LType.Bool,
2106         'default' : 'true',
2107         'help' : 'Use Query Name Minimization',
2108         'doc' : '''
2109 Enable Query Name Minimization. This implements a relaxed form of Query Name Mimimization as
2110 described in :rfc:`9156`.
2111  ''',
2112     'versionadded': '4.3.0'
2113     },
2114     {
2115         'name' : 'qname_max_minimize_count',
2116         'section' : 'recursor',
2117         'type' : LType.Uint64,
2118         'default' : '10',
2119         'help' : 'RFC9156 max minimize count',
2120         'doc' : '''
2121 ``Max minimize count`` parameter, described in :rfc:`9156`. This is the maximum number of iterations
2122 of the Query Name Minimization Algorithm.
2123  ''',
2124     'versionadded': '5.0.0'
2125     },
2126     {
2127         'name' : 'qname_minimize_one_label',
2128         'section' : 'recursor',
2129         'type' : LType.Uint64,
2130         'default' : '4',
2131         'help' : 'RFC9156 minimize one label parameter',
2132         'doc' : '''
2133 ``Minimize one label`` parameter, described in :rfc:`9156`.
2134 The value for the number of iterations of the Query Name Minimization Algorithm that should only have one label appended.
2135 This value has precedence over :ref:`setting-qname-max-minimize-count`.
2136  ''',
2137     'versionadded': '5.0.0'
2138     },
2139     {
2140         'name' : 'source_address',
2141         'section' : 'outgoing',
2142         'oldname' : 'query-local-address',
2143         'type' : LType.ListSubnets,
2144         'default' : '0.0.0.0',
2145         'help' : 'Source IP address for sending queries',
2146         'doc' : '''
2147 Send out local queries from this address, or addresses. By adding multiple
2148 addresses, increased spoofing resilience is achieved. When no address of a certain
2149 address family is configured, there are *no* queries sent with that address family.
2150 In the default configuration this means that IPv6 is not used for outgoing queries.
2151  ''',
2152      'versionchanged': ('4.4.0', 'IPv6 addresses can be set with this option as well.')
2153     },
2154     {
2155         'name' : 'quiet',
2156         'section' : 'logging',
2157         'type' : LType.Bool,
2158         'default' : 'true',
2159         'help' : 'Suppress logging of questions and answers',
2160         'doc' : '''
2161 Don't log queries.
2162  ''',
2163     },
2164     {
2165         'name' : 'locked_ttl_perc',
2166         'section' : 'recordcache',
2167         'oldname' : 'record-cache-locked-ttl-perc',
2168         'type' : LType.Uint64,
2169         'default' : '0',
2170         'help' : 'Replace records in record cache only after this % of original TTL has passed',
2171         'doc' : '''
2172 Replace record sets in the record cache only after this percentage of the original TTL has passed.
2173 The PowerDNS Recursor already has several mechanisms to protect against spoofing attempts.
2174 This adds an extra layer of protection---as it limits the window of time cache updates are accepted---at the cost of a less efficient record cache.
2175
2176 The default value of 0 means no extra locking occurs.
2177 When non-zero, record sets received (e.g. in the Additional Section) will not replace existing record sets in the record cache until the given percentage of the original TTL has expired.
2178 A value of 100 means only expired record sets will be replaced.
2179
2180 There are a few cases where records will be replaced anyway:
2181
2182 - Record sets that are expired will always be replaced.
2183 - Authoritative record sets will replace unauthoritative record sets unless DNSSEC validation of the new record set failed.
2184 - If the new record set belongs to a DNSSEC-secure zone and successfully passed validation it will replace an existing entry.
2185 - Record sets produced by :ref:`setting-refresh-on-ttl-perc` tasks will also replace existing record sets.
2186  ''',
2187     'versionadded': '4.8.0'
2188     },
2189     {
2190         'name' : 'shards',
2191         'section' : 'recordcache',
2192         'oldname' : 'record-cache-shards',
2193         'type' : LType.Uint64,
2194         'default' : '1024',
2195         'help' : 'Number of shards in the record cache',
2196         'doc' : '''
2197 Sets the number of shards in the record cache. If you have high
2198 contention as reported by
2199 ``record-cache-contented/record-cache-acquired``, you can try to
2200 enlarge this value or run with fewer threads.
2201  ''',
2202     'versionadded': '4.4.0'
2203     },
2204     {
2205         'name' : 'refresh_on_ttl_perc',
2206         'section' : 'recordcache',
2207         'type' : LType.Uint64,
2208         'default' : '0',
2209         'help' : 'If a record is requested from the cache and only this % of original TTL remains, refetch',
2210         'doc' : '''
2211 Sets the 'refresh almost expired' percentage of the record cache. Whenever a record is fetched from the packet or record cache
2212 and only ``refresh-on-ttl-perc`` percent or less of its original TTL is left, a task is queued to refetch the name/type combination to
2213 update the record cache. In most cases this causes future queries to always see a non-expired record cache entry.
2214 A typical value is 10. If the value is zero, this functionality is disabled.
2215  ''',
2216     'versionadded': '4.5.0'
2217     },
2218     {
2219         'name' : 'reuseport',
2220         'section' : 'incoming',
2221         'type' : LType.Bool,
2222         'default' : 'true',
2223         'help' : 'Enable SO_REUSEPORT allowing multiple recursors processes to listen to 1 address',
2224         'doc' : '''
2225 If ``SO_REUSEPORT`` support is available, allows multiple threads and processes to open listening sockets for the same port.
2226
2227 Since 4.1.0, when :ref:`setting-pdns-distributes-queries` is disabled and :ref:`setting-reuseport` is enabled, every worker-thread will open a separate listening socket to let the kernel distribute the incoming queries instead of running a distributor thread (which could otherwise be a bottleneck) and avoiding thundering herd issues, thus leading to much higher performance on multi-core boxes.
2228  ''',
2229      'versionchanged': ('4.9.0', 'The default is changed to ``yes``, previously it was ``no``. If ``SO_REUSEPORT`` support is not available, the setting defaults to ``no``.')
2230     },
2231     {
2232         'name' : 'rng',
2233         'section' : 'recursor',
2234         'type' : LType.String,
2235         'default' : 'auto',
2236         'help' : 'Specify random number generator to use. Valid values are auto,sodium,openssl,getrandom,arc4random,urandom.',
2237         'doc' : '''
2238 - String
2239 - Default: auto
2240
2241 Specify which random number generator to use. Permissible choices are
2242  - auto - choose automatically
2243  - sodium - Use libsodium ``randombytes_uniform``
2244  - openssl - Use libcrypto ``RAND_bytes``
2245  - getrandom - Use libc getrandom, falls back to urandom if it does not really work
2246  - arc4random - Use BSD ``arc4random_uniform``
2247  - urandom - Use ``/dev/urandom``
2248  - kiss - Use simple settable deterministic RNG. **FOR TESTING PURPOSES ONLY!**
2249  ''',
2250         'skip-yaml': True,
2251         'versionchanged': ('4.9.0', 'This setting is no longer used.')
2252     },
2253     {
2254         'name' : 'root_nx_trust',
2255         'section' : 'recursor',
2256         'type' : LType.Bool,
2257         'default' : 'true',
2258         'help' : 'If set, believe that an NXDOMAIN from the root means the TLD does not exist',
2259         'doc' : '''
2260 If set, an NXDOMAIN from the root-servers will serve as a blanket NXDOMAIN for the entire TLD the query belonged to.
2261 The effect of this is far fewer queries to the root-servers.
2262  ''',
2263      'versionchanged': ('4.0.0', "Default is ``yes`` now, was ``no`` before 4.0.0")
2264     },
2265     {
2266         'name' : 'save_parent_ns_set',
2267         'section' : 'recursor',
2268         'type' : LType.Bool,
2269         'default' : 'true',
2270         'help' : 'Save parent NS set to be used if child NS set fails',
2271         'doc' : '''
2272 If set, a parent (non-authoritative) ``NS`` set is saved if it contains more entries than a newly encountered child (authoritative) ``NS`` set for the same domain.
2273 The saved parent ``NS`` set is tried if resolution using the child ``NS`` set fails.
2274  ''',
2275     'versionadded': '4.7.0'
2276     },
2277     {
2278         'name' : 'security_poll_suffix',
2279         'section' : 'recursor',
2280         'type' : LType.String,
2281         'default' : 'secpoll.powerdns.com.',
2282         'help' : 'Domain name from which to query security update notifications',
2283         'doc' : '''
2284 Domain name from which to query security update notifications.
2285 Setting this to an empty string disables secpoll.
2286  ''',
2287     },
2288     {
2289         'name' : 'serve_rfc1918',
2290         'section' : 'recursor',
2291         'type' : LType.Bool,
2292         'default' : 'true',
2293         'help' : 'If we should be authoritative for RFC 1918 private IP space',
2294         'doc' : '''
2295 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.
2296 Individual parts of these zones can still be loaded or forwarded.
2297  ''',
2298     },
2299     {
2300         'name' : 'serve_stale_extensions',
2301         'section' : 'recordcache',
2302         'type' : LType.Uint64,
2303         'default' : '0',
2304         'help' : 'Number of times a record\'s ttl is extended by 30s to be served stale',
2305         'doc' : '''
2306 Maximum number of times an expired record's TTL is extended by 30s when serving stale.
2307 Extension only occurs if a record cannot be refreshed.
2308 A value of 0 means the ``Serve Stale`` mechanism is not used.
2309 To allow records becoming stale to be served for an hour, use a value of 120.
2310 See :ref:`serve-stale` for a description of the Serve Stale mechanism.
2311  ''',
2312     'versionadded': '4.8.0'
2313     },
2314     {
2315         'name' : 'server_down_max_fails',
2316         'section' : 'outgoing',
2317         'type' : LType.Uint64,
2318         'default' : '64',
2319         'help' : 'Maximum number of consecutive timeouts (and unreachables) to mark a server as down ( 0 => disabled )',
2320         'doc' : '''
2321 If a server has not responded in any way this many times in a row, no longer send it any queries for :ref:`setting-server-down-throttle-time` seconds.
2322 Afterwards, we will try a new packet, and if that also gets no response at all, we again throttle for :ref:`setting-server-down-throttle-time` seconds.
2323 Even a single response packet will drop the block.
2324  ''',
2325     },
2326     {
2327         'name' : 'server_down_throttle_time',
2328         'section' : 'outgoing',
2329         'type' : LType.Uint64,
2330         'default' : '60',
2331         'help' : 'Number of seconds to throttle all queries to a server after being marked as down',
2332         'doc' : '''
2333 Throttle a server that has failed to respond :ref:`setting-server-down-max-fails` times for this many seconds.
2334  ''',
2335     },
2336     {
2337         'name' : 'bypass_server_throttling_probability',
2338         'section' : 'outgoing',
2339         'type' : LType.Uint64,
2340         'default' : '25',
2341         'help' : 'Determines the probability of a server marked down to be used anyway',
2342         'doc' : '''
2343 This setting determines the probability of a server marked down to be used anyway.
2344 A value of ``n`` means that the chance of a server marked down still being used after it wins speed selection is is ``1/n``.
2345 If this setting is zero throttled servers will never be selected to be used anyway.
2346         ''',
2347         'versionadded': '5.0.0'
2348     },
2349     {
2350         'name' : 'server_id',
2351         'section' : 'recursor',
2352         'type' : LType.String,
2353         'default' : RUNTIME,
2354         'help' : 'Returned when queried for \'id.server\' TXT or NSID, defaults to hostname, set custom or \'disabled\'',
2355         'doc' : '''
2356 The reply given by The PowerDNS recursor to a query for 'id.server' with its hostname, useful for in clusters.
2357 When a query contains the :rfc:`NSID EDNS0 Option <5001>`, this value is returned in the response as the NSID value.
2358
2359 This setting can be used to override the answer given to these queries.
2360 Set to 'disabled' to disable NSID and 'id.server' answers.
2361
2362 Query example (where 192.0.2.14 is your server):
2363
2364 .. code-block:: sh
2365
2366     dig @192.0.2.14 CHAOS TXT id.server.
2367     dig @192.0.2.14 example.com IN A +nsid
2368  ''',
2369     },
2370     {
2371         'name' : 'setgid',
2372         'section' : 'recursor',
2373         'type' : LType.String,
2374         'default' : '',
2375         'help' : 'If set, change group id to this gid for more security',
2376         'doc' : '''
2377 PowerDNS can change its user and group id after binding to its socket.
2378 Can be used for better :doc:`security <security>`.
2379  '''
2380     },
2381     {
2382         'name' : 'setuid',
2383         'section' : 'recursor',
2384         'type' : LType.String,
2385         'default' : '',
2386         'help' : 'If set, change user id to this uid for more security',
2387         'doc' : '''
2388 PowerDNS can change its user and group id after binding to its socket.
2389 Can be used for better :doc:`security <security>`.
2390  '''
2391     },
2392     {
2393         'name' : 'signature_inception_skew',
2394         'section' : 'dnssec',
2395         'type' : LType.Uint64,
2396         'default' : '60',
2397         'help' : 'Allow the signature inception to be off by this number of seconds',
2398         'doc' : '''
2399 Allow the signature inception to be off by this number of seconds. Negative values are not allowed.
2400  ''',
2401         'versionadded': '4.1.5',
2402         'versionchanged': ('4.2.0', 'Default is now 60, was 0 before.')
2403     },
2404     {
2405         'name' : 'single_socket',
2406         'section' : 'outgoing',
2407         'type' : LType.Bool,
2408         'default' : 'false',
2409         'help' : 'If set, only use a single socket for outgoing queries',
2410         'doc' : '''
2411 Use only a single socket for outgoing queries.
2412  ''',
2413     },
2414     {
2415         'name' : 'agent',
2416         'section' : 'snmp',
2417         'oldname' : 'snmp-agent',
2418         'type' : LType.Bool,
2419         'default' : 'false',
2420         'help' : 'If set, register as an SNMP agent',
2421         'doc' : '''
2422 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.
2423  ''',
2424     'versionadded': '4.1.0'
2425     },
2426     {
2427         'name' : 'master_socket',
2428         'section' : 'snmp',
2429         'oldname' : 'snmp-master-socket',
2430         'type' : LType.String,
2431         'default' : '',
2432         'help' : 'If set and snmp-agent is set, the socket to use to register to the SNMP daemon (deprecated)',
2433         'doc' : '''
2434  ''',
2435         'versionadded': '4.1.0',
2436         'deprecated': ('4.5.0', 'Use :ref:`setting-snmp-daemon-socket`.'),
2437         'skip-yaml': True,
2438     },
2439     {
2440         'name' : 'daemon_socket',
2441         'section' : 'snmp',
2442         'oldname' : 'snmp-daemon-socket',
2443         'type' : LType.String,
2444         'default' : '',
2445         'help' : 'If set and snmp-agent is set, the socket to use to register to the SNMP daemon',
2446         'doc' : '''
2447 If not empty and ``snmp-agent`` is set to true, indicates how PowerDNS should contact the SNMP daemon to register as an SNMP agent.
2448  ''',
2449     'versionadded': '4.5.0'
2450     },
2451     {
2452         'name' : 'soa_minimum_ttl',
2453         'section' : 'recursor',
2454         'type' : LType.Uint64,
2455         'default' : '0',
2456         'help' : 'Don\'t change',
2457         'doc' : '''SKIP''',
2458         'skip-yaml': True,
2459     },
2460     {
2461         'name' : 'socket_dir',
2462         'section' : 'recursor',
2463         'type' : LType.String,
2464         'default' : '',
2465         'help' : 'Where the controlsocket will live, /var/run/pdns-recursor when unset and not chrooted',
2466         'doc' : '''
2467 Where to store the control socket and pidfile.
2468 The default depends on ``LOCALSTATEDIR`` or the ``--with-socketdir`` setting when building (usually ``/var/run`` or ``/run``).
2469
2470 When using :ref:`setting-chroot` the default becomes ``/``.
2471 The default value is overruled by the ``RUNTIME_DIRECTORY`` environment variable when that variable has a value (e.g. under systemd).
2472  ''',
2473     },
2474     {
2475         'name' : 'socket_group',
2476         'section' : 'recursor',
2477         'type' : LType.String,
2478         'default' : '',
2479         'help' : 'Group of socket',
2480         'doc' : '''
2481 Group and mode of the controlsocket.
2482 Owner and group can be specified by name, mode is in octal.
2483 '''
2484     },
2485     {
2486         'name' : 'socket_mode',
2487         'section' : 'recursor',
2488         'type' : LType.String,
2489         'default' : '',
2490         'help' : 'Permissions for socket',
2491         'doc' : '''
2492 Mode of the controlsocket.
2493 Owner and group can be specified by name, mode is in octal.
2494  '''
2495     },
2496     {
2497         'name' : 'socket_owner',
2498         'section' : 'recursor',
2499         'type' : LType.String,
2500         'default' : '',
2501         'help' : 'Owner of socket',
2502         'doc' : '''
2503 Owner of the controlsocket.
2504 Owner and group can be specified by name, mode is in octal.
2505  '''
2506     },
2507     {
2508         'name' : 'spoof_nearmiss_max',
2509         'section' : 'recursor',
2510         'type' : LType.Uint64,
2511         'default' : '1',
2512         'help' : 'If non-zero, assume spoofing after this many near misses',
2513         'doc' : '''
2514 If set to non-zero, PowerDNS will assume it is being spoofed after seeing this many answers with the wrong id.
2515  ''',
2516      'versionchanged': ('4.5.0', 'Older versions used 20 as the default value.')
2517     },
2518     {
2519         'name' : 'stack_cache_size',
2520         'section' : 'recursor',
2521         'type' : LType.Uint64,
2522         'default' : '100',
2523         'help' : 'Size of the stack cache, per mthread',
2524         'doc' : '''
2525 Maximum number of mthread stacks that can be cached for later reuse, per thread. Caching these stacks reduces the CPU load at the cost of a slightly higher memory usage, each cached stack consuming `stack-size` bytes of memory.
2526 It makes no sense to cache more stacks than the value of `max-mthreads`, since there will never be more stacks than that in use at a given time.
2527  ''',
2528     'versionadded': '4.9.0'
2529     },
2530     {
2531         'name' : 'stack_size',
2532         'section' : 'recursor',
2533         'type' : LType.Uint64,
2534         'default' : '200000',
2535         'help' : 'stack size per mthread',
2536         'doc' : '''
2537 Size in bytes of the stack of each mthread.
2538  ''',
2539     },
2540     {
2541         'name' : 'statistics_interval',
2542         'section' : 'logging',
2543         'type' : LType.Uint64,
2544         'default' : '1800',
2545         'help' : 'Number of seconds between printing of recursor statistics, 0 to disable',
2546         'doc' : '''
2547 Interval between logging statistical summary on recursor performance.
2548 Use 0 to disable.
2549  ''',
2550     'versionadded': '4.1.0'
2551     },
2552     {
2553         'name' : 'stats_api_blacklist',
2554         'section' : 'recursor',
2555         'type' : LType.ListStrings,
2556         'default' : 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-1, ecs-v4-response-bits-2, ecs-v4-response-bits-3, ecs-v4-response-bits-4, ecs-v4-response-bits-5, ecs-v4-response-bits-6, ecs-v4-response-bits-7, ecs-v4-response-bits-8, ecs-v4-response-bits-9, ecs-v4-response-bits-10, ecs-v4-response-bits-11, ecs-v4-response-bits-12, ecs-v4-response-bits-13, ecs-v4-response-bits-14, ecs-v4-response-bits-15, ecs-v4-response-bits-16, ecs-v4-response-bits-17, ecs-v4-response-bits-18, ecs-v4-response-bits-19, ecs-v4-response-bits-20, ecs-v4-response-bits-21, ecs-v4-response-bits-22, ecs-v4-response-bits-23, ecs-v4-response-bits-24, ecs-v4-response-bits-25, ecs-v4-response-bits-26, ecs-v4-response-bits-27, ecs-v4-response-bits-28, ecs-v4-response-bits-29, ecs-v4-response-bits-30, ecs-v4-response-bits-31, ecs-v4-response-bits-32, ecs-v6-response-bits-1, ecs-v6-response-bits-2, ecs-v6-response-bits-3, ecs-v6-response-bits-4, ecs-v6-response-bits-5, ecs-v6-response-bits-6, ecs-v6-response-bits-7, ecs-v6-response-bits-8, ecs-v6-response-bits-9, ecs-v6-response-bits-10, ecs-v6-response-bits-11, ecs-v6-response-bits-12, ecs-v6-response-bits-13, ecs-v6-response-bits-14, ecs-v6-response-bits-15, ecs-v6-response-bits-16, ecs-v6-response-bits-17, ecs-v6-response-bits-18, ecs-v6-response-bits-19, ecs-v6-response-bits-20, ecs-v6-response-bits-21, ecs-v6-response-bits-22, ecs-v6-response-bits-23, ecs-v6-response-bits-24, ecs-v6-response-bits-25, ecs-v6-response-bits-26, ecs-v6-response-bits-27, ecs-v6-response-bits-28, ecs-v6-response-bits-29, ecs-v6-response-bits-30, ecs-v6-response-bits-31, ecs-v6-response-bits-32, ecs-v6-response-bits-33, ecs-v6-response-bits-34, ecs-v6-response-bits-35, ecs-v6-response-bits-36, ecs-v6-response-bits-37, ecs-v6-response-bits-38, ecs-v6-response-bits-39, ecs-v6-response-bits-40, ecs-v6-response-bits-41, ecs-v6-response-bits-42, ecs-v6-response-bits-43, ecs-v6-response-bits-44, ecs-v6-response-bits-45, ecs-v6-response-bits-46, ecs-v6-response-bits-47, ecs-v6-response-bits-48, ecs-v6-response-bits-49, ecs-v6-response-bits-50, ecs-v6-response-bits-51, ecs-v6-response-bits-52, ecs-v6-response-bits-53, ecs-v6-response-bits-54, ecs-v6-response-bits-55, ecs-v6-response-bits-56, ecs-v6-response-bits-57, ecs-v6-response-bits-58, ecs-v6-response-bits-59, ecs-v6-response-bits-60, ecs-v6-response-bits-61, ecs-v6-response-bits-62, ecs-v6-response-bits-63, ecs-v6-response-bits-64, ecs-v6-response-bits-65, ecs-v6-response-bits-66, ecs-v6-response-bits-67, ecs-v6-response-bits-68, ecs-v6-response-bits-69, ecs-v6-response-bits-70, ecs-v6-response-bits-71, ecs-v6-response-bits-72, ecs-v6-response-bits-73, ecs-v6-response-bits-74, ecs-v6-response-bits-75, ecs-v6-response-bits-76, ecs-v6-response-bits-77, ecs-v6-response-bits-78, ecs-v6-response-bits-79, ecs-v6-response-bits-80, ecs-v6-response-bits-81, ecs-v6-response-bits-82, ecs-v6-response-bits-83, ecs-v6-response-bits-84, ecs-v6-response-bits-85, ecs-v6-response-bits-86, ecs-v6-response-bits-87, ecs-v6-response-bits-88, ecs-v6-response-bits-89, ecs-v6-response-bits-90, ecs-v6-response-bits-91, ecs-v6-response-bits-92, ecs-v6-response-bits-93, ecs-v6-response-bits-94, ecs-v6-response-bits-95, ecs-v6-response-bits-96, ecs-v6-response-bits-97, ecs-v6-response-bits-98, ecs-v6-response-bits-99, ecs-v6-response-bits-100, ecs-v6-response-bits-101, ecs-v6-response-bits-102, ecs-v6-response-bits-103, ecs-v6-response-bits-104, ecs-v6-response-bits-105, ecs-v6-response-bits-106, ecs-v6-response-bits-107, ecs-v6-response-bits-108, ecs-v6-response-bits-109, ecs-v6-response-bits-110, ecs-v6-response-bits-111, ecs-v6-response-bits-112, ecs-v6-response-bits-113, ecs-v6-response-bits-114, ecs-v6-response-bits-115, ecs-v6-response-bits-116, ecs-v6-response-bits-117, ecs-v6-response-bits-118, ecs-v6-response-bits-119, ecs-v6-response-bits-120, ecs-v6-response-bits-121, ecs-v6-response-bits-122, ecs-v6-response-bits-123, ecs-v6-response-bits-124, ecs-v6-response-bits-125, ecs-v6-response-bits-126, ecs-v6-response-bits-127, ecs-v6-response-bits-128',
2557         'help' : 'List of statistics that are disabled when retrieving the complete list of statistics via the API (deprecated)',
2558         'docdefault': '',
2559         'doc' : '',
2560         'versionadded': '4.2.0',
2561         'deprecated': ('4.5.0', 'Use :ref:`setting-stats-api-disabled-list`.'),
2562         'skip-yaml': True,
2563     },
2564     {
2565         'name' : 'stats_api_disabled_list',
2566         'section' : 'recursor',
2567         'type' : LType.ListStrings,
2568         'default' : 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-1, ecs-v4-response-bits-2, ecs-v4-response-bits-3, ecs-v4-response-bits-4, ecs-v4-response-bits-5, ecs-v4-response-bits-6, ecs-v4-response-bits-7, ecs-v4-response-bits-8, ecs-v4-response-bits-9, ecs-v4-response-bits-10, ecs-v4-response-bits-11, ecs-v4-response-bits-12, ecs-v4-response-bits-13, ecs-v4-response-bits-14, ecs-v4-response-bits-15, ecs-v4-response-bits-16, ecs-v4-response-bits-17, ecs-v4-response-bits-18, ecs-v4-response-bits-19, ecs-v4-response-bits-20, ecs-v4-response-bits-21, ecs-v4-response-bits-22, ecs-v4-response-bits-23, ecs-v4-response-bits-24, ecs-v4-response-bits-25, ecs-v4-response-bits-26, ecs-v4-response-bits-27, ecs-v4-response-bits-28, ecs-v4-response-bits-29, ecs-v4-response-bits-30, ecs-v4-response-bits-31, ecs-v4-response-bits-32, ecs-v6-response-bits-1, ecs-v6-response-bits-2, ecs-v6-response-bits-3, ecs-v6-response-bits-4, ecs-v6-response-bits-5, ecs-v6-response-bits-6, ecs-v6-response-bits-7, ecs-v6-response-bits-8, ecs-v6-response-bits-9, ecs-v6-response-bits-10, ecs-v6-response-bits-11, ecs-v6-response-bits-12, ecs-v6-response-bits-13, ecs-v6-response-bits-14, ecs-v6-response-bits-15, ecs-v6-response-bits-16, ecs-v6-response-bits-17, ecs-v6-response-bits-18, ecs-v6-response-bits-19, ecs-v6-response-bits-20, ecs-v6-response-bits-21, ecs-v6-response-bits-22, ecs-v6-response-bits-23, ecs-v6-response-bits-24, ecs-v6-response-bits-25, ecs-v6-response-bits-26, ecs-v6-response-bits-27, ecs-v6-response-bits-28, ecs-v6-response-bits-29, ecs-v6-response-bits-30, ecs-v6-response-bits-31, ecs-v6-response-bits-32, ecs-v6-response-bits-33, ecs-v6-response-bits-34, ecs-v6-response-bits-35, ecs-v6-response-bits-36, ecs-v6-response-bits-37, ecs-v6-response-bits-38, ecs-v6-response-bits-39, ecs-v6-response-bits-40, ecs-v6-response-bits-41, ecs-v6-response-bits-42, ecs-v6-response-bits-43, ecs-v6-response-bits-44, ecs-v6-response-bits-45, ecs-v6-response-bits-46, ecs-v6-response-bits-47, ecs-v6-response-bits-48, ecs-v6-response-bits-49, ecs-v6-response-bits-50, ecs-v6-response-bits-51, ecs-v6-response-bits-52, ecs-v6-response-bits-53, ecs-v6-response-bits-54, ecs-v6-response-bits-55, ecs-v6-response-bits-56, ecs-v6-response-bits-57, ecs-v6-response-bits-58, ecs-v6-response-bits-59, ecs-v6-response-bits-60, ecs-v6-response-bits-61, ecs-v6-response-bits-62, ecs-v6-response-bits-63, ecs-v6-response-bits-64, ecs-v6-response-bits-65, ecs-v6-response-bits-66, ecs-v6-response-bits-67, ecs-v6-response-bits-68, ecs-v6-response-bits-69, ecs-v6-response-bits-70, ecs-v6-response-bits-71, ecs-v6-response-bits-72, ecs-v6-response-bits-73, ecs-v6-response-bits-74, ecs-v6-response-bits-75, ecs-v6-response-bits-76, ecs-v6-response-bits-77, ecs-v6-response-bits-78, ecs-v6-response-bits-79, ecs-v6-response-bits-80, ecs-v6-response-bits-81, ecs-v6-response-bits-82, ecs-v6-response-bits-83, ecs-v6-response-bits-84, ecs-v6-response-bits-85, ecs-v6-response-bits-86, ecs-v6-response-bits-87, ecs-v6-response-bits-88, ecs-v6-response-bits-89, ecs-v6-response-bits-90, ecs-v6-response-bits-91, ecs-v6-response-bits-92, ecs-v6-response-bits-93, ecs-v6-response-bits-94, ecs-v6-response-bits-95, ecs-v6-response-bits-96, ecs-v6-response-bits-97, ecs-v6-response-bits-98, ecs-v6-response-bits-99, ecs-v6-response-bits-100, ecs-v6-response-bits-101, ecs-v6-response-bits-102, ecs-v6-response-bits-103, ecs-v6-response-bits-104, ecs-v6-response-bits-105, ecs-v6-response-bits-106, ecs-v6-response-bits-107, ecs-v6-response-bits-108, ecs-v6-response-bits-109, ecs-v6-response-bits-110, ecs-v6-response-bits-111, ecs-v6-response-bits-112, ecs-v6-response-bits-113, ecs-v6-response-bits-114, ecs-v6-response-bits-115, ecs-v6-response-bits-116, ecs-v6-response-bits-117, ecs-v6-response-bits-118, ecs-v6-response-bits-119, ecs-v6-response-bits-120, ecs-v6-response-bits-121, ecs-v6-response-bits-122, ecs-v6-response-bits-123, ecs-v6-response-bits-124, ecs-v6-response-bits-125, ecs-v6-response-bits-126, ecs-v6-response-bits-127, ecs-v6-response-bits-128',
2569         'docdefault': 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-\\*, ecs-v6-response-bits-\\*',
2570         'help' : 'List of statistics that are disabled when retrieving the complete list of statistics via the API',
2571         'doc' : '''
2572 A list of comma-separated statistic names, that are disabled when retrieving the complete list of statistics via the API for performance reasons.
2573 These statistics can still be retrieved individually by specifically asking for it.
2574  ''',
2575         'doc-new' : '''
2576 A sequence of statistic names, that are disabled when retrieving the complete list of statistics via the API for performance reasons.
2577 These statistics can still be retrieved individually by specifically asking for it.
2578  ''',
2579     'versionadded': '4.5.0'
2580     },
2581     {
2582         'name' : 'stats_carbon_blacklist',
2583         'section' : 'recursor',
2584         'type' : LType.ListStrings,
2585         'default' : 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-1, ecs-v4-response-bits-2, ecs-v4-response-bits-3, ecs-v4-response-bits-4, ecs-v4-response-bits-5, ecs-v4-response-bits-6, ecs-v4-response-bits-7, ecs-v4-response-bits-8, ecs-v4-response-bits-9, ecs-v4-response-bits-10, ecs-v4-response-bits-11, ecs-v4-response-bits-12, ecs-v4-response-bits-13, ecs-v4-response-bits-14, ecs-v4-response-bits-15, ecs-v4-response-bits-16, ecs-v4-response-bits-17, ecs-v4-response-bits-18, ecs-v4-response-bits-19, ecs-v4-response-bits-20, ecs-v4-response-bits-21, ecs-v4-response-bits-22, ecs-v4-response-bits-23, ecs-v4-response-bits-24, ecs-v4-response-bits-25, ecs-v4-response-bits-26, ecs-v4-response-bits-27, ecs-v4-response-bits-28, ecs-v4-response-bits-29, ecs-v4-response-bits-30, ecs-v4-response-bits-31, ecs-v4-response-bits-32, ecs-v6-response-bits-1, ecs-v6-response-bits-2, ecs-v6-response-bits-3, ecs-v6-response-bits-4, ecs-v6-response-bits-5, ecs-v6-response-bits-6, ecs-v6-response-bits-7, ecs-v6-response-bits-8, ecs-v6-response-bits-9, ecs-v6-response-bits-10, ecs-v6-response-bits-11, ecs-v6-response-bits-12, ecs-v6-response-bits-13, ecs-v6-response-bits-14, ecs-v6-response-bits-15, ecs-v6-response-bits-16, ecs-v6-response-bits-17, ecs-v6-response-bits-18, ecs-v6-response-bits-19, ecs-v6-response-bits-20, ecs-v6-response-bits-21, ecs-v6-response-bits-22, ecs-v6-response-bits-23, ecs-v6-response-bits-24, ecs-v6-response-bits-25, ecs-v6-response-bits-26, ecs-v6-response-bits-27, ecs-v6-response-bits-28, ecs-v6-response-bits-29, ecs-v6-response-bits-30, ecs-v6-response-bits-31, ecs-v6-response-bits-32, ecs-v6-response-bits-33, ecs-v6-response-bits-34, ecs-v6-response-bits-35, ecs-v6-response-bits-36, ecs-v6-response-bits-37, ecs-v6-response-bits-38, ecs-v6-response-bits-39, ecs-v6-response-bits-40, ecs-v6-response-bits-41, ecs-v6-response-bits-42, ecs-v6-response-bits-43, ecs-v6-response-bits-44, ecs-v6-response-bits-45, ecs-v6-response-bits-46, ecs-v6-response-bits-47, ecs-v6-response-bits-48, ecs-v6-response-bits-49, ecs-v6-response-bits-50, ecs-v6-response-bits-51, ecs-v6-response-bits-52, ecs-v6-response-bits-53, ecs-v6-response-bits-54, ecs-v6-response-bits-55, ecs-v6-response-bits-56, ecs-v6-response-bits-57, ecs-v6-response-bits-58, ecs-v6-response-bits-59, ecs-v6-response-bits-60, ecs-v6-response-bits-61, ecs-v6-response-bits-62, ecs-v6-response-bits-63, ecs-v6-response-bits-64, ecs-v6-response-bits-65, ecs-v6-response-bits-66, ecs-v6-response-bits-67, ecs-v6-response-bits-68, ecs-v6-response-bits-69, ecs-v6-response-bits-70, ecs-v6-response-bits-71, ecs-v6-response-bits-72, ecs-v6-response-bits-73, ecs-v6-response-bits-74, ecs-v6-response-bits-75, ecs-v6-response-bits-76, ecs-v6-response-bits-77, ecs-v6-response-bits-78, ecs-v6-response-bits-79, ecs-v6-response-bits-80, ecs-v6-response-bits-81, ecs-v6-response-bits-82, ecs-v6-response-bits-83, ecs-v6-response-bits-84, ecs-v6-response-bits-85, ecs-v6-response-bits-86, ecs-v6-response-bits-87, ecs-v6-response-bits-88, ecs-v6-response-bits-89, ecs-v6-response-bits-90, ecs-v6-response-bits-91, ecs-v6-response-bits-92, ecs-v6-response-bits-93, ecs-v6-response-bits-94, ecs-v6-response-bits-95, ecs-v6-response-bits-96, ecs-v6-response-bits-97, ecs-v6-response-bits-98, ecs-v6-response-bits-99, ecs-v6-response-bits-100, ecs-v6-response-bits-101, ecs-v6-response-bits-102, ecs-v6-response-bits-103, ecs-v6-response-bits-104, ecs-v6-response-bits-105, ecs-v6-response-bits-106, ecs-v6-response-bits-107, ecs-v6-response-bits-108, ecs-v6-response-bits-109, ecs-v6-response-bits-110, ecs-v6-response-bits-111, ecs-v6-response-bits-112, ecs-v6-response-bits-113, ecs-v6-response-bits-114, ecs-v6-response-bits-115, ecs-v6-response-bits-116, ecs-v6-response-bits-117, ecs-v6-response-bits-118, ecs-v6-response-bits-119, ecs-v6-response-bits-120, ecs-v6-response-bits-121, ecs-v6-response-bits-122, ecs-v6-response-bits-123, ecs-v6-response-bits-124, ecs-v6-response-bits-125, ecs-v6-response-bits-126, ecs-v6-response-bits-127, ecs-v6-response-bits-128, cumul-clientanswers, cumul-authanswers, policy-hits, proxy-mapping-total, remote-logger-count',
2586         'docdefault': '',
2587         'help' : 'List of statistics that are prevented from being exported via Carbon (deprecated)',
2588         'doc' : '',
2589         'versionadded': '4.2.0',
2590         'deprecated': ('4.5.0', 'Use :ref:`setting-stats-carbon-disabled-list`.'),
2591         'skip-yaml': True,
2592     },
2593     {
2594         'name' : 'stats_carbon_disabled_list',
2595         'section' : 'recursor',
2596         'type' : LType.ListStrings,
2597         'default' : 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-1, ecs-v4-response-bits-2, ecs-v4-response-bits-3, ecs-v4-response-bits-4, ecs-v4-response-bits-5, ecs-v4-response-bits-6, ecs-v4-response-bits-7, ecs-v4-response-bits-8, ecs-v4-response-bits-9, ecs-v4-response-bits-10, ecs-v4-response-bits-11, ecs-v4-response-bits-12, ecs-v4-response-bits-13, ecs-v4-response-bits-14, ecs-v4-response-bits-15, ecs-v4-response-bits-16, ecs-v4-response-bits-17, ecs-v4-response-bits-18, ecs-v4-response-bits-19, ecs-v4-response-bits-20, ecs-v4-response-bits-21, ecs-v4-response-bits-22, ecs-v4-response-bits-23, ecs-v4-response-bits-24, ecs-v4-response-bits-25, ecs-v4-response-bits-26, ecs-v4-response-bits-27, ecs-v4-response-bits-28, ecs-v4-response-bits-29, ecs-v4-response-bits-30, ecs-v4-response-bits-31, ecs-v4-response-bits-32, ecs-v6-response-bits-1, ecs-v6-response-bits-2, ecs-v6-response-bits-3, ecs-v6-response-bits-4, ecs-v6-response-bits-5, ecs-v6-response-bits-6, ecs-v6-response-bits-7, ecs-v6-response-bits-8, ecs-v6-response-bits-9, ecs-v6-response-bits-10, ecs-v6-response-bits-11, ecs-v6-response-bits-12, ecs-v6-response-bits-13, ecs-v6-response-bits-14, ecs-v6-response-bits-15, ecs-v6-response-bits-16, ecs-v6-response-bits-17, ecs-v6-response-bits-18, ecs-v6-response-bits-19, ecs-v6-response-bits-20, ecs-v6-response-bits-21, ecs-v6-response-bits-22, ecs-v6-response-bits-23, ecs-v6-response-bits-24, ecs-v6-response-bits-25, ecs-v6-response-bits-26, ecs-v6-response-bits-27, ecs-v6-response-bits-28, ecs-v6-response-bits-29, ecs-v6-response-bits-30, ecs-v6-response-bits-31, ecs-v6-response-bits-32, ecs-v6-response-bits-33, ecs-v6-response-bits-34, ecs-v6-response-bits-35, ecs-v6-response-bits-36, ecs-v6-response-bits-37, ecs-v6-response-bits-38, ecs-v6-response-bits-39, ecs-v6-response-bits-40, ecs-v6-response-bits-41, ecs-v6-response-bits-42, ecs-v6-response-bits-43, ecs-v6-response-bits-44, ecs-v6-response-bits-45, ecs-v6-response-bits-46, ecs-v6-response-bits-47, ecs-v6-response-bits-48, ecs-v6-response-bits-49, ecs-v6-response-bits-50, ecs-v6-response-bits-51, ecs-v6-response-bits-52, ecs-v6-response-bits-53, ecs-v6-response-bits-54, ecs-v6-response-bits-55, ecs-v6-response-bits-56, ecs-v6-response-bits-57, ecs-v6-response-bits-58, ecs-v6-response-bits-59, ecs-v6-response-bits-60, ecs-v6-response-bits-61, ecs-v6-response-bits-62, ecs-v6-response-bits-63, ecs-v6-response-bits-64, ecs-v6-response-bits-65, ecs-v6-response-bits-66, ecs-v6-response-bits-67, ecs-v6-response-bits-68, ecs-v6-response-bits-69, ecs-v6-response-bits-70, ecs-v6-response-bits-71, ecs-v6-response-bits-72, ecs-v6-response-bits-73, ecs-v6-response-bits-74, ecs-v6-response-bits-75, ecs-v6-response-bits-76, ecs-v6-response-bits-77, ecs-v6-response-bits-78, ecs-v6-response-bits-79, ecs-v6-response-bits-80, ecs-v6-response-bits-81, ecs-v6-response-bits-82, ecs-v6-response-bits-83, ecs-v6-response-bits-84, ecs-v6-response-bits-85, ecs-v6-response-bits-86, ecs-v6-response-bits-87, ecs-v6-response-bits-88, ecs-v6-response-bits-89, ecs-v6-response-bits-90, ecs-v6-response-bits-91, ecs-v6-response-bits-92, ecs-v6-response-bits-93, ecs-v6-response-bits-94, ecs-v6-response-bits-95, ecs-v6-response-bits-96, ecs-v6-response-bits-97, ecs-v6-response-bits-98, ecs-v6-response-bits-99, ecs-v6-response-bits-100, ecs-v6-response-bits-101, ecs-v6-response-bits-102, ecs-v6-response-bits-103, ecs-v6-response-bits-104, ecs-v6-response-bits-105, ecs-v6-response-bits-106, ecs-v6-response-bits-107, ecs-v6-response-bits-108, ecs-v6-response-bits-109, ecs-v6-response-bits-110, ecs-v6-response-bits-111, ecs-v6-response-bits-112, ecs-v6-response-bits-113, ecs-v6-response-bits-114, ecs-v6-response-bits-115, ecs-v6-response-bits-116, ecs-v6-response-bits-117, ecs-v6-response-bits-118, ecs-v6-response-bits-119, ecs-v6-response-bits-120, ecs-v6-response-bits-121, ecs-v6-response-bits-122, ecs-v6-response-bits-123, ecs-v6-response-bits-124, ecs-v6-response-bits-125, ecs-v6-response-bits-126, ecs-v6-response-bits-127, ecs-v6-response-bits-128, cumul-clientanswers, cumul-authanswers, policy-hits, proxy-mapping-total, remote-logger-count',
2598         'docdefault': 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-\\*, ecs-v6-response-bits-\\*, cumul-answers-\\*, cumul-auth4answers-\\*, cumul-auth6answers-\\*',
2599         'help' : 'List of statistics that are prevented from being exported via Carbon',
2600         'doc' : '''
2601 A list of comma-separated statistic names, that are prevented from being exported via carbon for performance reasons.
2602  ''',
2603         'doc-new' : '''
2604 A sequence of statistic names, that are prevented from being exported via carbon for performance reasons.
2605  ''',
2606     'versionadded': '4.5.0'
2607     },
2608     {
2609         'name' : 'stats_rec_control_blacklist',
2610         'section' : 'recursor',
2611         'type' : LType.ListStrings,
2612         'default' : 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-1, ecs-v4-response-bits-2, ecs-v4-response-bits-3, ecs-v4-response-bits-4, ecs-v4-response-bits-5, ecs-v4-response-bits-6, ecs-v4-response-bits-7, ecs-v4-response-bits-8, ecs-v4-response-bits-9, ecs-v4-response-bits-10, ecs-v4-response-bits-11, ecs-v4-response-bits-12, ecs-v4-response-bits-13, ecs-v4-response-bits-14, ecs-v4-response-bits-15, ecs-v4-response-bits-16, ecs-v4-response-bits-17, ecs-v4-response-bits-18, ecs-v4-response-bits-19, ecs-v4-response-bits-20, ecs-v4-response-bits-21, ecs-v4-response-bits-22, ecs-v4-response-bits-23, ecs-v4-response-bits-24, ecs-v4-response-bits-25, ecs-v4-response-bits-26, ecs-v4-response-bits-27, ecs-v4-response-bits-28, ecs-v4-response-bits-29, ecs-v4-response-bits-30, ecs-v4-response-bits-31, ecs-v4-response-bits-32, ecs-v6-response-bits-1, ecs-v6-response-bits-2, ecs-v6-response-bits-3, ecs-v6-response-bits-4, ecs-v6-response-bits-5, ecs-v6-response-bits-6, ecs-v6-response-bits-7, ecs-v6-response-bits-8, ecs-v6-response-bits-9, ecs-v6-response-bits-10, ecs-v6-response-bits-11, ecs-v6-response-bits-12, ecs-v6-response-bits-13, ecs-v6-response-bits-14, ecs-v6-response-bits-15, ecs-v6-response-bits-16, ecs-v6-response-bits-17, ecs-v6-response-bits-18, ecs-v6-response-bits-19, ecs-v6-response-bits-20, ecs-v6-response-bits-21, ecs-v6-response-bits-22, ecs-v6-response-bits-23, ecs-v6-response-bits-24, ecs-v6-response-bits-25, ecs-v6-response-bits-26, ecs-v6-response-bits-27, ecs-v6-response-bits-28, ecs-v6-response-bits-29, ecs-v6-response-bits-30, ecs-v6-response-bits-31, ecs-v6-response-bits-32, ecs-v6-response-bits-33, ecs-v6-response-bits-34, ecs-v6-response-bits-35, ecs-v6-response-bits-36, ecs-v6-response-bits-37, ecs-v6-response-bits-38, ecs-v6-response-bits-39, ecs-v6-response-bits-40, ecs-v6-response-bits-41, ecs-v6-response-bits-42, ecs-v6-response-bits-43, ecs-v6-response-bits-44, ecs-v6-response-bits-45, ecs-v6-response-bits-46, ecs-v6-response-bits-47, ecs-v6-response-bits-48, ecs-v6-response-bits-49, ecs-v6-response-bits-50, ecs-v6-response-bits-51, ecs-v6-response-bits-52, ecs-v6-response-bits-53, ecs-v6-response-bits-54, ecs-v6-response-bits-55, ecs-v6-response-bits-56, ecs-v6-response-bits-57, ecs-v6-response-bits-58, ecs-v6-response-bits-59, ecs-v6-response-bits-60, ecs-v6-response-bits-61, ecs-v6-response-bits-62, ecs-v6-response-bits-63, ecs-v6-response-bits-64, ecs-v6-response-bits-65, ecs-v6-response-bits-66, ecs-v6-response-bits-67, ecs-v6-response-bits-68, ecs-v6-response-bits-69, ecs-v6-response-bits-70, ecs-v6-response-bits-71, ecs-v6-response-bits-72, ecs-v6-response-bits-73, ecs-v6-response-bits-74, ecs-v6-response-bits-75, ecs-v6-response-bits-76, ecs-v6-response-bits-77, ecs-v6-response-bits-78, ecs-v6-response-bits-79, ecs-v6-response-bits-80, ecs-v6-response-bits-81, ecs-v6-response-bits-82, ecs-v6-response-bits-83, ecs-v6-response-bits-84, ecs-v6-response-bits-85, ecs-v6-response-bits-86, ecs-v6-response-bits-87, ecs-v6-response-bits-88, ecs-v6-response-bits-89, ecs-v6-response-bits-90, ecs-v6-response-bits-91, ecs-v6-response-bits-92, ecs-v6-response-bits-93, ecs-v6-response-bits-94, ecs-v6-response-bits-95, ecs-v6-response-bits-96, ecs-v6-response-bits-97, ecs-v6-response-bits-98, ecs-v6-response-bits-99, ecs-v6-response-bits-100, ecs-v6-response-bits-101, ecs-v6-response-bits-102, ecs-v6-response-bits-103, ecs-v6-response-bits-104, ecs-v6-response-bits-105, ecs-v6-response-bits-106, ecs-v6-response-bits-107, ecs-v6-response-bits-108, ecs-v6-response-bits-109, ecs-v6-response-bits-110, ecs-v6-response-bits-111, ecs-v6-response-bits-112, ecs-v6-response-bits-113, ecs-v6-response-bits-114, ecs-v6-response-bits-115, ecs-v6-response-bits-116, ecs-v6-response-bits-117, ecs-v6-response-bits-118, ecs-v6-response-bits-119, ecs-v6-response-bits-120, ecs-v6-response-bits-121, ecs-v6-response-bits-122, ecs-v6-response-bits-123, ecs-v6-response-bits-124, ecs-v6-response-bits-125, ecs-v6-response-bits-126, ecs-v6-response-bits-127, ecs-v6-response-bits-128, cumul-clientanswers, cumul-authanswers, policy-hits, proxy-mapping-total, remote-logger-count',
2613         'docdefault': '',
2614         'help' : 'List of statistics that are prevented from being exported via rec_control get-all (deprecated)',
2615         'doc' : '',
2616         'versionadded': '4.2.0',
2617         'deprecated': ('4.5.0', 'Use :ref:`setting-stats-rec-control-disabled-list`.'),
2618         'skip-yaml': True,
2619     },
2620     {
2621         'name' : 'stats_rec_control_disabled_list',
2622         'section' : 'recursor',
2623         'type' : LType.ListStrings,
2624         'default' : 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-1, ecs-v4-response-bits-2, ecs-v4-response-bits-3, ecs-v4-response-bits-4, ecs-v4-response-bits-5, ecs-v4-response-bits-6, ecs-v4-response-bits-7, ecs-v4-response-bits-8, ecs-v4-response-bits-9, ecs-v4-response-bits-10, ecs-v4-response-bits-11, ecs-v4-response-bits-12, ecs-v4-response-bits-13, ecs-v4-response-bits-14, ecs-v4-response-bits-15, ecs-v4-response-bits-16, ecs-v4-response-bits-17, ecs-v4-response-bits-18, ecs-v4-response-bits-19, ecs-v4-response-bits-20, ecs-v4-response-bits-21, ecs-v4-response-bits-22, ecs-v4-response-bits-23, ecs-v4-response-bits-24, ecs-v4-response-bits-25, ecs-v4-response-bits-26, ecs-v4-response-bits-27, ecs-v4-response-bits-28, ecs-v4-response-bits-29, ecs-v4-response-bits-30, ecs-v4-response-bits-31, ecs-v4-response-bits-32, ecs-v6-response-bits-1, ecs-v6-response-bits-2, ecs-v6-response-bits-3, ecs-v6-response-bits-4, ecs-v6-response-bits-5, ecs-v6-response-bits-6, ecs-v6-response-bits-7, ecs-v6-response-bits-8, ecs-v6-response-bits-9, ecs-v6-response-bits-10, ecs-v6-response-bits-11, ecs-v6-response-bits-12, ecs-v6-response-bits-13, ecs-v6-response-bits-14, ecs-v6-response-bits-15, ecs-v6-response-bits-16, ecs-v6-response-bits-17, ecs-v6-response-bits-18, ecs-v6-response-bits-19, ecs-v6-response-bits-20, ecs-v6-response-bits-21, ecs-v6-response-bits-22, ecs-v6-response-bits-23, ecs-v6-response-bits-24, ecs-v6-response-bits-25, ecs-v6-response-bits-26, ecs-v6-response-bits-27, ecs-v6-response-bits-28, ecs-v6-response-bits-29, ecs-v6-response-bits-30, ecs-v6-response-bits-31, ecs-v6-response-bits-32, ecs-v6-response-bits-33, ecs-v6-response-bits-34, ecs-v6-response-bits-35, ecs-v6-response-bits-36, ecs-v6-response-bits-37, ecs-v6-response-bits-38, ecs-v6-response-bits-39, ecs-v6-response-bits-40, ecs-v6-response-bits-41, ecs-v6-response-bits-42, ecs-v6-response-bits-43, ecs-v6-response-bits-44, ecs-v6-response-bits-45, ecs-v6-response-bits-46, ecs-v6-response-bits-47, ecs-v6-response-bits-48, ecs-v6-response-bits-49, ecs-v6-response-bits-50, ecs-v6-response-bits-51, ecs-v6-response-bits-52, ecs-v6-response-bits-53, ecs-v6-response-bits-54, ecs-v6-response-bits-55, ecs-v6-response-bits-56, ecs-v6-response-bits-57, ecs-v6-response-bits-58, ecs-v6-response-bits-59, ecs-v6-response-bits-60, ecs-v6-response-bits-61, ecs-v6-response-bits-62, ecs-v6-response-bits-63, ecs-v6-response-bits-64, ecs-v6-response-bits-65, ecs-v6-response-bits-66, ecs-v6-response-bits-67, ecs-v6-response-bits-68, ecs-v6-response-bits-69, ecs-v6-response-bits-70, ecs-v6-response-bits-71, ecs-v6-response-bits-72, ecs-v6-response-bits-73, ecs-v6-response-bits-74, ecs-v6-response-bits-75, ecs-v6-response-bits-76, ecs-v6-response-bits-77, ecs-v6-response-bits-78, ecs-v6-response-bits-79, ecs-v6-response-bits-80, ecs-v6-response-bits-81, ecs-v6-response-bits-82, ecs-v6-response-bits-83, ecs-v6-response-bits-84, ecs-v6-response-bits-85, ecs-v6-response-bits-86, ecs-v6-response-bits-87, ecs-v6-response-bits-88, ecs-v6-response-bits-89, ecs-v6-response-bits-90, ecs-v6-response-bits-91, ecs-v6-response-bits-92, ecs-v6-response-bits-93, ecs-v6-response-bits-94, ecs-v6-response-bits-95, ecs-v6-response-bits-96, ecs-v6-response-bits-97, ecs-v6-response-bits-98, ecs-v6-response-bits-99, ecs-v6-response-bits-100, ecs-v6-response-bits-101, ecs-v6-response-bits-102, ecs-v6-response-bits-103, ecs-v6-response-bits-104, ecs-v6-response-bits-105, ecs-v6-response-bits-106, ecs-v6-response-bits-107, ecs-v6-response-bits-108, ecs-v6-response-bits-109, ecs-v6-response-bits-110, ecs-v6-response-bits-111, ecs-v6-response-bits-112, ecs-v6-response-bits-113, ecs-v6-response-bits-114, ecs-v6-response-bits-115, ecs-v6-response-bits-116, ecs-v6-response-bits-117, ecs-v6-response-bits-118, ecs-v6-response-bits-119, ecs-v6-response-bits-120, ecs-v6-response-bits-121, ecs-v6-response-bits-122, ecs-v6-response-bits-123, ecs-v6-response-bits-124, ecs-v6-response-bits-125, ecs-v6-response-bits-126, ecs-v6-response-bits-127, ecs-v6-response-bits-128, cumul-clientanswers, cumul-authanswers, policy-hits, proxy-mapping-total, remote-logger-count',
2625         'docdefault': 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-\\*, ecs-v6-response-bits-\\*, cumul-answers-\\*, cumul-auth4answers-\\*, cumul-auth6answers-\\*',
2626         'help' : 'List of statistics that are prevented from being exported via rec_control get-all',
2627         'doc' : '''
2628 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.
2629 These statistics can still be retrieved individually.
2630  ''',
2631         'doc-new' : '''
2632 A sequence of statistic names, that are disabled when retrieving the complete list of statistics via `rec_control get-all`, for performance reasons.
2633 These statistics can still be retrieved individually.
2634  ''',
2635     'versionadded': '4.5.0'
2636     },
2637     {
2638         'name' : 'stats_ringbuffer_entries',
2639         'section' : 'recursor',
2640         'type' : LType.Uint64,
2641         'default' : '10000',
2642         'help' : 'maximum number of packets to store statistics for',
2643         'doc' : '''
2644 Number of entries in the remotes ringbuffer, which keeps statistics on who is querying your server.
2645 Can be read out using ``rec_control top-remotes``.
2646  ''',
2647     },
2648     {
2649         'name' : 'stats_snmp_blacklist',
2650         'section' : 'recursor',
2651         'type' : LType.ListStrings,
2652         'default' : 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-1, ecs-v4-response-bits-2, ecs-v4-response-bits-3, ecs-v4-response-bits-4, ecs-v4-response-bits-5, ecs-v4-response-bits-6, ecs-v4-response-bits-7, ecs-v4-response-bits-8, ecs-v4-response-bits-9, ecs-v4-response-bits-10, ecs-v4-response-bits-11, ecs-v4-response-bits-12, ecs-v4-response-bits-13, ecs-v4-response-bits-14, ecs-v4-response-bits-15, ecs-v4-response-bits-16, ecs-v4-response-bits-17, ecs-v4-response-bits-18, ecs-v4-response-bits-19, ecs-v4-response-bits-20, ecs-v4-response-bits-21, ecs-v4-response-bits-22, ecs-v4-response-bits-23, ecs-v4-response-bits-24, ecs-v4-response-bits-25, ecs-v4-response-bits-26, ecs-v4-response-bits-27, ecs-v4-response-bits-28, ecs-v4-response-bits-29, ecs-v4-response-bits-30, ecs-v4-response-bits-31, ecs-v4-response-bits-32, ecs-v6-response-bits-1, ecs-v6-response-bits-2, ecs-v6-response-bits-3, ecs-v6-response-bits-4, ecs-v6-response-bits-5, ecs-v6-response-bits-6, ecs-v6-response-bits-7, ecs-v6-response-bits-8, ecs-v6-response-bits-9, ecs-v6-response-bits-10, ecs-v6-response-bits-11, ecs-v6-response-bits-12, ecs-v6-response-bits-13, ecs-v6-response-bits-14, ecs-v6-response-bits-15, ecs-v6-response-bits-16, ecs-v6-response-bits-17, ecs-v6-response-bits-18, ecs-v6-response-bits-19, ecs-v6-response-bits-20, ecs-v6-response-bits-21, ecs-v6-response-bits-22, ecs-v6-response-bits-23, ecs-v6-response-bits-24, ecs-v6-response-bits-25, ecs-v6-response-bits-26, ecs-v6-response-bits-27, ecs-v6-response-bits-28, ecs-v6-response-bits-29, ecs-v6-response-bits-30, ecs-v6-response-bits-31, ecs-v6-response-bits-32, ecs-v6-response-bits-33, ecs-v6-response-bits-34, ecs-v6-response-bits-35, ecs-v6-response-bits-36, ecs-v6-response-bits-37, ecs-v6-response-bits-38, ecs-v6-response-bits-39, ecs-v6-response-bits-40, ecs-v6-response-bits-41, ecs-v6-response-bits-42, ecs-v6-response-bits-43, ecs-v6-response-bits-44, ecs-v6-response-bits-45, ecs-v6-response-bits-46, ecs-v6-response-bits-47, ecs-v6-response-bits-48, ecs-v6-response-bits-49, ecs-v6-response-bits-50, ecs-v6-response-bits-51, ecs-v6-response-bits-52, ecs-v6-response-bits-53, ecs-v6-response-bits-54, ecs-v6-response-bits-55, ecs-v6-response-bits-56, ecs-v6-response-bits-57, ecs-v6-response-bits-58, ecs-v6-response-bits-59, ecs-v6-response-bits-60, ecs-v6-response-bits-61, ecs-v6-response-bits-62, ecs-v6-response-bits-63, ecs-v6-response-bits-64, ecs-v6-response-bits-65, ecs-v6-response-bits-66, ecs-v6-response-bits-67, ecs-v6-response-bits-68, ecs-v6-response-bits-69, ecs-v6-response-bits-70, ecs-v6-response-bits-71, ecs-v6-response-bits-72, ecs-v6-response-bits-73, ecs-v6-response-bits-74, ecs-v6-response-bits-75, ecs-v6-response-bits-76, ecs-v6-response-bits-77, ecs-v6-response-bits-78, ecs-v6-response-bits-79, ecs-v6-response-bits-80, ecs-v6-response-bits-81, ecs-v6-response-bits-82, ecs-v6-response-bits-83, ecs-v6-response-bits-84, ecs-v6-response-bits-85, ecs-v6-response-bits-86, ecs-v6-response-bits-87, ecs-v6-response-bits-88, ecs-v6-response-bits-89, ecs-v6-response-bits-90, ecs-v6-response-bits-91, ecs-v6-response-bits-92, ecs-v6-response-bits-93, ecs-v6-response-bits-94, ecs-v6-response-bits-95, ecs-v6-response-bits-96, ecs-v6-response-bits-97, ecs-v6-response-bits-98, ecs-v6-response-bits-99, ecs-v6-response-bits-100, ecs-v6-response-bits-101, ecs-v6-response-bits-102, ecs-v6-response-bits-103, ecs-v6-response-bits-104, ecs-v6-response-bits-105, ecs-v6-response-bits-106, ecs-v6-response-bits-107, ecs-v6-response-bits-108, ecs-v6-response-bits-109, ecs-v6-response-bits-110, ecs-v6-response-bits-111, ecs-v6-response-bits-112, ecs-v6-response-bits-113, ecs-v6-response-bits-114, ecs-v6-response-bits-115, ecs-v6-response-bits-116, ecs-v6-response-bits-117, ecs-v6-response-bits-118, ecs-v6-response-bits-119, ecs-v6-response-bits-120, ecs-v6-response-bits-121, ecs-v6-response-bits-122, ecs-v6-response-bits-123, ecs-v6-response-bits-124, ecs-v6-response-bits-125, ecs-v6-response-bits-126, ecs-v6-response-bits-127, ecs-v6-response-bits-128, cumul-clientanswers, cumul-authanswers, policy-hits, proxy-mapping-total, remote-logger-count',
2653         'docdefault': '',
2654         'help' : 'List of statistics that are prevented from being exported via SNMP (deprecated)',
2655         'doc' : '',
2656         'versionadded': '4.2.0',
2657         'deprecated': ('4.5.0', 'Use :ref:`setting-stats-snmp-disabled-list`.'),
2658         'skip-yaml': True,
2659     },
2660     {
2661         'name' : 'stats_snmp_disabled_list',
2662         'section' : 'recursor',
2663         'type' : LType.ListStrings,
2664         'default' : 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-1, ecs-v4-response-bits-2, ecs-v4-response-bits-3, ecs-v4-response-bits-4, ecs-v4-response-bits-5, ecs-v4-response-bits-6, ecs-v4-response-bits-7, ecs-v4-response-bits-8, ecs-v4-response-bits-9, ecs-v4-response-bits-10, ecs-v4-response-bits-11, ecs-v4-response-bits-12, ecs-v4-response-bits-13, ecs-v4-response-bits-14, ecs-v4-response-bits-15, ecs-v4-response-bits-16, ecs-v4-response-bits-17, ecs-v4-response-bits-18, ecs-v4-response-bits-19, ecs-v4-response-bits-20, ecs-v4-response-bits-21, ecs-v4-response-bits-22, ecs-v4-response-bits-23, ecs-v4-response-bits-24, ecs-v4-response-bits-25, ecs-v4-response-bits-26, ecs-v4-response-bits-27, ecs-v4-response-bits-28, ecs-v4-response-bits-29, ecs-v4-response-bits-30, ecs-v4-response-bits-31, ecs-v4-response-bits-32, ecs-v6-response-bits-1, ecs-v6-response-bits-2, ecs-v6-response-bits-3, ecs-v6-response-bits-4, ecs-v6-response-bits-5, ecs-v6-response-bits-6, ecs-v6-response-bits-7, ecs-v6-response-bits-8, ecs-v6-response-bits-9, ecs-v6-response-bits-10, ecs-v6-response-bits-11, ecs-v6-response-bits-12, ecs-v6-response-bits-13, ecs-v6-response-bits-14, ecs-v6-response-bits-15, ecs-v6-response-bits-16, ecs-v6-response-bits-17, ecs-v6-response-bits-18, ecs-v6-response-bits-19, ecs-v6-response-bits-20, ecs-v6-response-bits-21, ecs-v6-response-bits-22, ecs-v6-response-bits-23, ecs-v6-response-bits-24, ecs-v6-response-bits-25, ecs-v6-response-bits-26, ecs-v6-response-bits-27, ecs-v6-response-bits-28, ecs-v6-response-bits-29, ecs-v6-response-bits-30, ecs-v6-response-bits-31, ecs-v6-response-bits-32, ecs-v6-response-bits-33, ecs-v6-response-bits-34, ecs-v6-response-bits-35, ecs-v6-response-bits-36, ecs-v6-response-bits-37, ecs-v6-response-bits-38, ecs-v6-response-bits-39, ecs-v6-response-bits-40, ecs-v6-response-bits-41, ecs-v6-response-bits-42, ecs-v6-response-bits-43, ecs-v6-response-bits-44, ecs-v6-response-bits-45, ecs-v6-response-bits-46, ecs-v6-response-bits-47, ecs-v6-response-bits-48, ecs-v6-response-bits-49, ecs-v6-response-bits-50, ecs-v6-response-bits-51, ecs-v6-response-bits-52, ecs-v6-response-bits-53, ecs-v6-response-bits-54, ecs-v6-response-bits-55, ecs-v6-response-bits-56, ecs-v6-response-bits-57, ecs-v6-response-bits-58, ecs-v6-response-bits-59, ecs-v6-response-bits-60, ecs-v6-response-bits-61, ecs-v6-response-bits-62, ecs-v6-response-bits-63, ecs-v6-response-bits-64, ecs-v6-response-bits-65, ecs-v6-response-bits-66, ecs-v6-response-bits-67, ecs-v6-response-bits-68, ecs-v6-response-bits-69, ecs-v6-response-bits-70, ecs-v6-response-bits-71, ecs-v6-response-bits-72, ecs-v6-response-bits-73, ecs-v6-response-bits-74, ecs-v6-response-bits-75, ecs-v6-response-bits-76, ecs-v6-response-bits-77, ecs-v6-response-bits-78, ecs-v6-response-bits-79, ecs-v6-response-bits-80, ecs-v6-response-bits-81, ecs-v6-response-bits-82, ecs-v6-response-bits-83, ecs-v6-response-bits-84, ecs-v6-response-bits-85, ecs-v6-response-bits-86, ecs-v6-response-bits-87, ecs-v6-response-bits-88, ecs-v6-response-bits-89, ecs-v6-response-bits-90, ecs-v6-response-bits-91, ecs-v6-response-bits-92, ecs-v6-response-bits-93, ecs-v6-response-bits-94, ecs-v6-response-bits-95, ecs-v6-response-bits-96, ecs-v6-response-bits-97, ecs-v6-response-bits-98, ecs-v6-response-bits-99, ecs-v6-response-bits-100, ecs-v6-response-bits-101, ecs-v6-response-bits-102, ecs-v6-response-bits-103, ecs-v6-response-bits-104, ecs-v6-response-bits-105, ecs-v6-response-bits-106, ecs-v6-response-bits-107, ecs-v6-response-bits-108, ecs-v6-response-bits-109, ecs-v6-response-bits-110, ecs-v6-response-bits-111, ecs-v6-response-bits-112, ecs-v6-response-bits-113, ecs-v6-response-bits-114, ecs-v6-response-bits-115, ecs-v6-response-bits-116, ecs-v6-response-bits-117, ecs-v6-response-bits-118, ecs-v6-response-bits-119, ecs-v6-response-bits-120, ecs-v6-response-bits-121, ecs-v6-response-bits-122, ecs-v6-response-bits-123, ecs-v6-response-bits-124, ecs-v6-response-bits-125, ecs-v6-response-bits-126, ecs-v6-response-bits-127, ecs-v6-response-bits-128, cumul-clientanswers, cumul-authanswers, policy-hits, proxy-mapping-total, remote-logger-count',
2665         'docdefault': 'cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-\\*, ecs-v6-response-bits-\\*',
2666         'help' : 'List of statistics that are prevented from being exported via SNMP',
2667         'doc' : '''
2668 A list of comma-separated statistic names, that are prevented from being exported via SNMP, for performance reasons.
2669  ''',
2670         'doc-new' : '''
2671 A sequence of statistic names, that are prevented from being exported via SNMP, for performance reasons.
2672  ''',
2673     'versionadded': '4.5.0'
2674     },
2675     {
2676         'name' : 'structured_logging',
2677         'section' : 'logging',
2678         'type' : LType.Bool,
2679         'default' : 'true',
2680         'help' : 'Prefer structured logging',
2681         'doc' : '''
2682 Prefer structured logging when both an old style and a structured log messages is available.
2683  ''',
2684         'versionadded': '4.6.0',
2685         'versionchanged': ('5.0.0', 'Disabling structured logging is deprecated'),
2686         'versionchanged': ('5.1.0', 'Disabling structured logging is not supported'),
2687     },
2688     {
2689         'name' : 'structured_logging_backend',
2690         'section' : 'logging',
2691         'type' : LType.String,
2692         'default' : 'default',
2693         'help' : 'Structured logging backend',
2694         'doc' : '''
2695 The backend used for structured logging output.
2696 This setting must be set on the command line (``--structured-logging-backend=...``) to be effective.
2697 Available backends are:
2698
2699 - ``default``: use the traditional logging system to output structured logging information.
2700 - ``systemd-journal``: use systemd-journal.
2701   When using this backend, provide ``-o verbose`` or simular output option to ``journalctl`` to view the full information.
2702 - ``json``: JSON objects are written to the standard error stream.
2703
2704 See :doc:`appendices/structuredlogging` for more details.
2705  ''',
2706         'versionadded': '4.8.0',
2707         'versionchanged': ('5.1.0', 'The JSON backend was added')
2708     },
2709     {
2710         'name' : 'tcp_fast_open',
2711         'section' : 'incoming',
2712         'type' : LType.Uint64,
2713         'default' : '0',
2714         'help' : 'Enable TCP Fast Open support on the listening sockets, using the supplied numerical value as the queue size',
2715         'doc' : '''
2716 Enable TCP Fast Open support, if available, on the listening sockets.
2717 The numerical value supplied is used as the queue size, 0 meaning disabled. See :ref:`tcp-fast-open-support`.
2718  ''',
2719     'versionadded': '4.1.0'
2720     },
2721     {
2722         'name' : 'tcp_fast_open_connect',
2723         'section' : 'outgoing',
2724         'type' : LType.Bool,
2725         'default' : 'false',
2726         'help' : 'Enable TCP Fast Open support on outgoing sockets',
2727         'doc' : '''
2728 Enable TCP Fast Open Connect support, if available, on the outgoing connections to authoritative servers. See :ref:`tcp-fast-open-support`.
2729  ''',
2730     'versionadded': '4.5.0'
2731     },
2732     {
2733         'name' : 'tcp_max_idle_ms',
2734         'section' : 'outgoing',
2735         'oldname' : 'tcp-out-max-idle-ms',
2736         'type' : LType.Uint64,
2737         'default' : '10000',
2738         'help' : 'Time TCP/DoT connections are left idle in milliseconds or 0 if no limit',
2739         'doc' : '''
2740 Time outgoing TCP/DoT connections are left idle in milliseconds or 0 if no limit. After having been idle for this time, the connection is eligible for closing.
2741  ''',
2742     'versionadded': '4.6.0'
2743     },
2744     {
2745         'name' : 'tcp_max_idle_per_auth',
2746         'section' : 'outgoing',
2747         'oldname' : 'tcp-out-max-idle-per-auth',
2748         'type' : LType.Uint64,
2749         'default' : '10',
2750         'help' : 'Maximum number of idle TCP/DoT connections to a specific IP per thread, 0 means do not keep idle connections open',
2751         'doc' : '''
2752 Maximum number of idle outgoing TCP/DoT connections to a specific IP per thread, 0 means do not keep idle connections open.
2753  ''',
2754     'versionadded': '4.6.0'
2755     },
2756     {
2757         'name' : 'tcp_max_queries',
2758         'section' : 'outgoing',
2759         'oldname' : 'tcp-out-max-queries',
2760         'type' : LType.Uint64,
2761         'default' : '0',
2762         'help' : 'Maximum total number of queries per TCP/DoT connection, 0 means no limit',
2763         'doc' : '''
2764 Maximum total number of queries per outgoing TCP/DoT connection, 0 means no limit. After this number of queries, the connection is
2765 closed and a new one will be created if needed.
2766  ''',
2767     },
2768     {
2769         'name' : 'tcp_max_idle_per_thread',
2770         'section' : 'outgoing',
2771         'oldname' : 'tcp-out-max-idle-per-thread',
2772         'type' : LType.Uint64,
2773         'default' : '100',
2774         'help' : 'Maximum number of idle TCP/DoT connections per thread',
2775         'doc' : '''
2776 Maximum number of idle outgoing TCP/DoT connections per thread, 0 means do not keep idle connections open.
2777  ''',
2778     'versionadded': '4.6.0'
2779     },
2780     {
2781         'name' : 'threads',
2782         'section' : 'recursor',
2783         'type' : LType.Uint64,
2784         'default' : '2',
2785         'help' : 'Launch this number of threads',
2786         'doc' : '''
2787 Spawn this number of threads on startup.
2788  ''',
2789     },
2790     {
2791         'name' : 'tcp_threads',
2792         'section' : 'recursor',
2793         'type' : LType.Uint64,
2794         'default' : '1',
2795         'help' : 'Launch this number of threads listening for and processing TCP queries',
2796         'doc' : '''
2797 Spawn this number of TCP processing threads on startup.
2798  ''',
2799         'versionadded': '5.0.0'
2800     },
2801     {
2802         'name' : 'trace',
2803         'section' : 'logging',
2804         'type' : LType.String,
2805         'default' : 'no',
2806         'help' : 'if we should output heaps of logging. set to \'fail\' to only log failing domains',
2807         'doc' : '''
2808 One of ``no``, ``yes`` or ``fail``.
2809 If turned on, output impressive heaps of logging.
2810 May destroy performance under load.
2811 To log only queries resulting in a ``ServFail`` answer from the resolving process, this value can be set to ``fail``, but note that the performance impact is still large.
2812 Also note that queries that do produce a result but with a failing DNSSEC validation are not written to the log
2813  ''',
2814     },
2815     {
2816         'name' : 'udp_source_port_min',
2817         'section' : 'outgoing',
2818         'type' : LType.Uint64,
2819         'default' : '1024',
2820         'help' : 'Minimum UDP port to bind on',
2821         'doc' : '''
2822 This option sets the low limit of UDP port number to bind on.
2823
2824 In combination with :ref:`setting-udp-source-port-max` it configures the UDP
2825 port range to use. Port numbers are randomized within this range on
2826 initialization, and exceptions can be configured with :ref:`setting-udp-source-port-avoid`
2827  ''',
2828     'versionadded': '4.2.0'
2829     },
2830     {
2831         'name' : 'udp_source_port_max',
2832         'section' : 'outgoing',
2833         'type' : LType.Uint64,
2834         'default' : '65535',
2835         'help' : 'Maximum UDP port to bind on',
2836         'doc' : '''
2837 This option sets the maximum limit of UDP port number to bind on.
2838
2839 See :ref:`setting-udp-source-port-min`.
2840  ''',
2841     'versionadded': '4.2.0'
2842     },
2843     {
2844         'name' : 'udp_source_port_avoid',
2845         'section' : 'outgoing',
2846         'type' : LType.ListStrings,
2847         'default' : '11211',
2848         'help' : 'List of comma separated UDP port number to avoid',
2849         'doc' : '''
2850 A list of comma-separated UDP port numbers to avoid when binding.
2851 Ex: `5300,11211`
2852
2853 See :ref:`setting-udp-source-port-min`.
2854  ''',
2855         'doc-new' : '''
2856 A sequence of UDP port numbers to avoid when binding. For example:
2857
2858 .. code-block:: yaml
2859
2860  outgoing:
2861    udp_source_port_avoid:
2862    - 5300
2863    - 11211
2864
2865 See :ref:`setting-udp-source-port-min`.
2866  ''',
2867     'versionadded': '4.2.0'
2868     },
2869     {
2870         'name' : 'udp_truncation_threshold',
2871         'section' : 'incoming',
2872         'type' : LType.Uint64,
2873         'default' : '1232',
2874         'help' : 'Maximum UDP response size before we truncate',
2875         'doc' : '''
2876 EDNS0 allows for large UDP response datagrams, which can potentially raise performance.
2877 Large responses however also have downsides in terms of reflection attacks.
2878 This setting limits the accepted size.
2879 Maximum value is 65535, but values above 4096 should probably not be attempted.
2880
2881 To know why 1232, see the note at :ref:`setting-edns-outgoing-bufsize`.
2882  ''',
2883         'versionchanged': ('4.2.0', 'Before 4.2.0, the default was 1680.')
2884     },
2885     {
2886         'name' : 'unique_response_tracking',
2887         'section' : 'nod',
2888         'type' : LType.Bool,
2889         'default' : 'false',
2890         'help' : 'Track unique responses (tuple of query name, type and RR).',
2891         'doc' : '''
2892 Whether to track unique DNS responses, i.e. never seen before combinations
2893 of the triplet (query name, query type, RR[rrname, rrtype, rrdata]).
2894 This can be useful for tracking potentially suspicious domains and
2895 behaviour, e.g. DNS fast-flux.
2896 If protobuf is enabled and configured, then the Protobuf Response message
2897 will contain a flag with udr set to true for each RR that is considered
2898 unique, i.e. never seen before.
2899 This feature uses a probabilistic data structure (stable bloom filter) to
2900 track unique responses, which can have false positives as well as false
2901 negatives, thus it is a best-effort feature. Increasing the number of cells
2902 in the SBF using the unique-response-db-size setting can reduce FPs and FNs.
2903  ''',
2904     'versionadded': '4.2.0'
2905     },
2906     {
2907         'name' : 'unique_response_log',
2908         'section' : 'nod',
2909         'type' : LType.Bool,
2910         'default' : 'true',
2911         'help' : 'Log unique responses',
2912         'doc' : '''
2913 Whether to log when a unique response is detected. The log line
2914 looks something like:
2915
2916 Oct 24 12:11:27 Unique response observed: qname=foo.com qtype=A rrtype=AAAA rrname=foo.com rrcontent=1.2.3.4
2917  ''',
2918     'versionadded': '4.2.0'
2919     },
2920     {
2921         'name' : 'unique_response_db_size',
2922         'section' : 'nod',
2923         'type' : LType.Uint64,
2924         'default' : '67108864',
2925         'help' : 'Size of the DB used to track unique responses in terms of number of cells. Defaults to 67108864',
2926         'doc' : '''
2927 The default size of the stable bloom filter used to store previously
2928 observed responses is 67108864. To change the number of cells, use this
2929 setting. For each cell, the SBF uses 1 bit of memory, and one byte of
2930 disk for the persistent file.
2931 If there are already persistent files saved to disk, this setting will
2932 have no effect unless you remove the existing files.
2933  ''',
2934     'versionadded': '4.2.0'
2935     },
2936     {
2937         'name' : 'unique_response_history_dir',
2938         'section' : 'nod',
2939         'type' : LType.String,
2940         'default' : 'NODCACHEDIRUDR',
2941         'docdefault': 'Determined by distribution',
2942         'help' : 'Persist unique response tracking data here to persist between restarts',
2943         'doc' : '''
2944 This setting controls which directory is used to store the on-disk
2945 cache of previously observed responses.
2946
2947 The default depends on ``LOCALSTATEDIR`` when building the software.
2948 Usually this comes down to ``/var/lib/pdns-recursor/udr`` or ``/usr/local/var/lib/pdns-recursor/udr``).
2949
2950 The newly observed domain feature uses a stable bloom filter to store
2951 a history of previously observed responses. The data structure is
2952 synchronized to disk every 10 minutes, and is also initialized from
2953 disk on startup. This ensures that previously observed responses are
2954 preserved across recursor restarts. If you change the
2955 unique-response-db-size, you must remove any files from this directory.
2956  ''',
2957     'versionadded': '4.2.0'
2958     },
2959     {
2960         'name' : 'unique_response_pb_tag',
2961         'section' : 'nod',
2962         'type' : LType.String,
2963         'default' : 'pdns-udr',
2964         'help' : 'If protobuf is configured, the tag to use for messages containing unique DNS responses. Defaults to \'pdns-udr\'',
2965         'doc' : '''
2966 If protobuf is configured, then this tag will be added to all protobuf response messages when
2967 a unique DNS response is observed.
2968  ''',
2969     'versionadded': '4.2.0'
2970     },
2971     {
2972         'name' : 'use_incoming_edns_subnet',
2973         'section' : 'incoming',
2974         'type' : LType.Bool,
2975         'default' : 'false',
2976         'help' : 'Pass along received EDNS Client Subnet information',
2977         'doc' : '''
2978 Whether to process and pass along a received EDNS Client Subnet to authoritative servers.
2979 The ECS information will only be sent for netmasks and domains listed in :ref:`setting-edns-subnet-allow-list` and will be truncated if the received scope exceeds :ref:`setting-ecs-ipv4-bits` for IPv4 or :ref:`setting-ecs-ipv6-bits` for IPv6.
2980  ''',
2981     },
2982     {
2983         'name' : 'version',
2984         'section' : 'commands',
2985         'type' : LType.Command,
2986         'default' : 'no',
2987         'help' : 'Print version string',
2988         'doc' : '''
2989 Print version of this binary. Useful for checking which version of the PowerDNS recursor is installed on a system.
2990  ''',
2991     },
2992     {
2993         'name' : 'version_string',
2994         'section' : 'recursor',
2995         'type' : LType.String,
2996         'default' : RUNTIME,
2997         'help' : 'string reported on version.pdns or version.bind',
2998         'doc' : '''
2999 By default, PowerDNS replies to the 'version.bind' query with its version number.
3000 Security conscious users may wish to override the reply PowerDNS issues.
3001  ''',
3002     },
3003     {
3004         'name' : 'webserver',
3005         'section' : 'webservice',
3006         'type' : LType.Bool,
3007         'default' : 'false',
3008         'help' : 'Start a webserver (for REST API)',
3009         'doc' : '''
3010 Start the webserver (for REST API).
3011  ''',
3012     },
3013     {
3014         'name' : 'address',
3015         'section' : 'webservice',
3016         'oldname' : 'webserver-address',
3017         'type' : LType.String,
3018         'default' : '127.0.0.1',
3019         'help' : 'IP Address of webserver to listen on',
3020         'doc' : '''
3021 IP address for the webserver to listen on.
3022  ''',
3023     },
3024     {
3025         'name' : 'allow_from',
3026         'section' : 'webservice',
3027         'oldname' : 'webserver-allow-from',
3028         'type' : LType.ListSubnets,
3029         'default' : '127.0.0.1, ::1',
3030         'help' : 'Webserver access is only allowed from these subnets',
3031         'doc' : '''
3032 These IPs and subnets are allowed to access the webserver. Note that
3033 specifying an IP address without a netmask uses an implicit netmask
3034 of /32 or /128.
3035  ''',
3036         'versionchanged': ('4.1.0', 'Default is now 127.0.0.1,::1, was 0.0.0.0/0,::/0 before.')
3037     },
3038     {
3039         'name' : 'hash_plaintext_credentials',
3040         'section' : 'webservice',
3041         'oldname': 'webserver-hash-plaintext-credentials',
3042         'type' : LType.Bool,
3043         'default' : 'false',
3044         'help' : 'Whether to hash passwords and api keys supplied in plaintext, to prevent keeping the plaintext version in memory at runtime',
3045         'doc' : '''
3046 Whether passwords and API keys supplied in the configuration as plaintext should be hashed during startup, to prevent the plaintext versions from staying in memory. Doing so increases significantly the cost of verifying credentials and is thus disabled by default.
3047 Note that this option only applies to credentials stored in the configuration as plaintext, but hashed credentials are supported without enabling this option.
3048  ''',
3049     'versionadded': '4.6.0'
3050     },
3051     {
3052         'name' : 'loglevel',
3053         'section' : 'webservice',
3054         'oldname' : 'webserver-loglevel',
3055         'type' : LType.String,
3056         'default' : 'normal',
3057         'help' : 'Amount of logging in the webserver (none, normal, detailed)',
3058         'doc' : '''
3059 One of ``none``, ``normal``, ``detailed``.
3060 The amount of logging the webserver must do. 'none' means no useful webserver information will be logged.
3061 When set to 'normal', the webserver will log a line per request that should be familiar::
3062
3063   [webserver] e235780e-a5cf-415e-9326-9d33383e739e 127.0.0.1:55376 'GET /api/v1/servers/localhost/bla HTTP/1.1' 404 196
3064
3065 When set to 'detailed', all information about the request and response are logged::
3066
3067   [webserver] e235780e-a5cf-415e-9326-9d33383e739e Request Details:
3068   [webserver] e235780e-a5cf-415e-9326-9d33383e739e  Headers:
3069   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
3070   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   accept-encoding: gzip, deflate
3071   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   accept-language: en-US,en;q=0.5
3072   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   connection: keep-alive
3073   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   dnt: 1
3074   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   host: 127.0.0.1:8081
3075   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   upgrade-insecure-requests: 1
3076   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   user-agent: Mozilla/5.0 (X11; Linux x86_64; rv:64.0) Gecko/20100101 Firefox/64.0
3077   [webserver] e235780e-a5cf-415e-9326-9d33383e739e  No body
3078   [webserver] e235780e-a5cf-415e-9326-9d33383e739e Response details:
3079   [webserver] e235780e-a5cf-415e-9326-9d33383e739e  Headers:
3080   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Connection: close
3081   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Content-Length: 49
3082   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Content-Type: text/html; charset=utf-8
3083   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Server: PowerDNS/0.0.15896.0.gaba8bab3ab
3084   [webserver] e235780e-a5cf-415e-9326-9d33383e739e  Full body:
3085   [webserver] e235780e-a5cf-415e-9326-9d33383e739e   <!html><title>Not Found</title><h1>Not Found</h1>
3086   [webserver] e235780e-a5cf-415e-9326-9d33383e739e 127.0.0.1:55376 'GET /api/v1/servers/localhost/bla HTTP/1.1' 404 196
3087
3088 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.
3089
3090 .. note::
3091   The webserver logs these line on the NOTICE level. The :ref:`setting-loglevel` seting must be 5 or higher for these lines to end up in the log.
3092  ''',
3093     'versionadded': '4.2.0'
3094     },
3095     {
3096         'name' : 'password',
3097         'section' : 'webservice',
3098         'oldname' : 'webserver-password',
3099         'type' : LType.String,
3100         'default' : '',
3101         'help' : 'Password required for accessing the webserver',
3102         'doc' : '''
3103 Password required to access the webserver. Since 4.6.0 the password can be hashed and salted using ``rec_control hash-password`` instead of being present in the configuration in plaintext, but the plaintext version is still supported.
3104  ''',
3105         'versionchanged': ('4.6.0', 'This setting now accepts a hashed and salted version.')
3106     },
3107     {
3108         'name' : 'port',
3109         'section' : 'webservice',
3110         'type' : LType.Uint64,
3111         'oldname': 'webserver-port',
3112         'default' : '8082',
3113         'help' : 'Port of webserver to listen on',
3114         'doc' : '''
3115 TCP port where the webserver should listen on.
3116  ''',
3117     },
3118     {
3119         'name' : 'write_pid',
3120         'section' : 'recursor',
3121         'type' : LType.Bool,
3122         'default' : 'true',
3123         'help' : 'Write a PID file',
3124         'doc' : '''
3125 If a PID file should be written to :ref:`setting-socket-dir`
3126  ''',
3127     },
3128     {
3129         'name' : 'x_dnssec_names',
3130         'section' : 'dnssec',
3131         'type' : LType.ListStrings,
3132         'default' : '',
3133         'help' : 'Collect DNSSEC statistics for names or suffixes in this list in separate x-dnssec counters',
3134         'doc' : '''
3135 List of names whose DNSSEC validation metrics will be counted in a separate set of metrics that start
3136 with ``x-dnssec-result-``.
3137 The names are suffix-matched.
3138 This can be used to not count known failing (test) name validations in the ordinary DNSSEC metrics.
3139  ''',
3140     'versionadded': '4.5.0'
3141     },
3142     {
3143         'name' : 'system_resolver_ttl',
3144         'section' : 'recursor',
3145         'type' : LType.Uint64,
3146         'default' : '0',
3147         'help' : 'Set TTL of system resolver feature, 0 (default) is disabled',
3148         'doc' : '''
3149 Sets TTL in seconds of the system resolver feature.
3150 If not equal to zero names can be used for forwarding targets.
3151 The names will be resolved by the system resolver configured in the OS.
3152
3153 The TTL is used as a time to live to see if the names used in forwarding resolve to a different address than before.
3154 If the TTL is expired, a re-resolve will be done by the next iteration of the check function;
3155 if a change is detected, the recursor performs an equivalent of ``rec_control reload-zones``.
3156
3157 Make sure the recursor itself is not used by the system resolver! Default is 0 (not enabled).
3158 A suggested value is 60.
3159 ''',
3160     'versionadded': '5.1.0'
3161     },
3162     {
3163         'name' : 'system_resolver_interval',
3164         'section' : 'recursor',
3165         'type' : LType.Uint64,
3166         'default' : '0',
3167         'help' : 'Set interval (in seconds) of the re-resolve checks of system resolver subsystem.',
3168         'doc' : '''
3169 Sets the check interval (in seconds) of the system resolver feature.
3170 All names known by the system resolver subsystem are periodically checked for changing values.
3171
3172 If the TTL of a name has expired, it is checked by re-resolving it.
3173 if a change is detected, the recursor performs an equivalent of ``rec_control reload-zones``.
3174
3175 This settings sets the interval between the checks.
3176 If set to zero (the default), the value :ref:`setting-system-resolver-ttl` is used.
3177 ''',
3178     'versionadded': '5.1.0'
3179     },
3180     {
3181         'name' : 'system_resolver_self_resolve_check',
3182         'section' : 'recursor',
3183         'type' : LType.Bool,
3184         'default' : 'true',
3185         'help' : 'Check for potential self-resolve, default enabled.',
3186         'doc' : '''
3187 Warn on potential self-resolve.
3188 If this check draws the wrong conclusion, you can disable it.
3189 ''',
3190     'versionadded': '5.1.0'
3191     },
3192 ]