PowerDNS Recursor New Style (YAML) Settings

Each setting can appear on the command line, prefixed by -- and using the old style name, or in configuration files. Settings on the command line are processed after the file-based settings are processed.

Note

Starting with version 5.0.0, Recursor supports a new YAML syntax for configuration files as described here. If both recursor.conf and recursor.yml files are found in the configuration directory the YAML file is used. A configuration using the old style syntax can be converted to a YAML configuration using the instructions in Conversion of old-style settings to YAML format.

Release 5.0.0 will install a default old-style recursor.conf file.

Starting with version 5.1.0, in the absence of a recursor.yml file, an existing recursor.conf will be processed as YAML, if that fails, it will be processed as old-style configuration. Packages will stop installing an old-style recursor.conf file and start installing a default recursor.conf file containing YAML syntax.

With the release of 5.2.0, the default will be to expect a YAML configuration file and reading of old-style recursor.conf files will have to be enabled specifically by providing a command line option --enable-old-settings.

In a future release support for the “old-style” recursor.conf settings file will be dropped.

Note

Starting with version 5.1.0, the settings originally specified in a Lua config file can also be put in YAML form. The conversion printed by rec_control show-yaml will print these settings if a Lua config file is specified in the config file being converted. You have to choose however: either set Lua settings the old way in the Lua config file, or convert all to YAML. If you are using YAML settings of items originally specified in the Lua config file do not set recursor.lua_config_file anymore. The Recursor will check that you do not mix both configuration methods.

When using YAML style for settings originally found in the Lua config file rec_control reload-lua-config will reload parts of the YAML settings. Refer to the specific setting to learn if it is subject to reloading. Starting with version 5.2.0, the command rec_control reload-yaml can be used (which is an alias for rec_control reload-lua-config).

YAML settings file

Please refer to e.g. https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html for a description of YAML syntax.

A Recursor configuration file has several sections. For example, incoming for settings related to receiving queries and dnssec for settings related to DNSSEC processing.

An example Recursor YAML configuration file looks like:

dnssec:
  log_bogus: true
incoming:
  listen:
    - 0.0.0.0:5301
    - '[::]:5301'
recursor:
  extended_resolution_errors: true
  forward_zones:
    - zone: example.com
      forwarders:
        - 127.0.0.1:5301
outgoing:
  source_address:
    - 0.0.0.0
    - '::'
logging:
  loglevel: 6

Take care when listing IPv6 addresses, as characters used for these are special to YAML. If in doubt, quote any string containing :, !, [ or ] and use (online) tools to check your YAML syntax. Specify an empty sequence using [].

The main setting file is called recursor.yml and will be processed first. This settings file might refer to other files via the recursor.include_dir setting. The next section will describe how settings specified in multiple files are merged.

Merging multiple setting files

If recursor.include_dir is set, all .yml files in it will be processed in alphabetical order, modifying the settings processed so far.

For simple values like a boolean or number setting, a value in the processed file will overwrite an existing setting.

For values of type sequence, the new value will replace the existing value if the existing value is equal to the default or if the new value is marked with the !override tag. Otherwise, the existing value will be extended with the new value by appending the new sequence to the existing.

For example, with the above example recursor.yml and an include directory containing a file extra.yml:

dnssec:
  log_bogus: false
recursor:
  forward_zones:
    - zone: example.net
      forwarders:
        - '::1'
outgoing:
   source_address: !override
     - 0.0.0.0
   dont_query: []

After merging, dnssec.log_bogus will be false, the sequence of recursor.forward_zones will contain 2 zones and the outgoing addresses used will contain one entry, as the extra.yml entry has overwritten the existing one.

outgoing.dont-query has a non-empty sequence as default value. The main recursor.yml did not set it, so before processing extra.yml it had the default value. After processing extra.yml the value will be set to the empty sequence, as existing default values are overwritten by new values.

Warning

The merging process does not process values deeper than the second level. For example if the main recursor.yml specified a forward zone

recursor:
  forward_zones:
    - zone: example.net
      forwarders:
        - '::1'

and another settings file contains

recursor:
  forward_zones:
    - zone: example.net
      forwarders:
      - '::2'

The result will not be a single forward with two IP addresses, but two entries for example.net. It depends on the specific setting how the sequence is processed and interpreted further.

Description of YAML syntax for structured types

Socket Address

A socket address is a string containing either an IP address or and IP address:port combination For example:

some_key: 127.0.0.1
another_key: '[::1]:8080'

Subnet

A subnet is a single IP address or an IP address followed by a slash and a prefix length. If no prefix length is specified, /32 or /128 is assumed, indicating a single IP address. Subnets can also be prefixed with a !, specifying negation. This can be used to deny addresses from a previously allowed range.

For example, allow-from takes a sequence of subnets:

incoming:
  allow_from:
    - '2001:DB8::/32'
    - 128.66.0.0/16
    - '!128.66.1.2'

In this case the address 128.66.1.2 is excluded from the addresses allowed access.

Forward Zone

A forward zone is defined as:

zone: string
forwarders:
  - Socket Address
  - ...
recurse: Boolean, default false (only relevant in a forwarding file)
notify_allowed: Boolean, default false

An example of a forward_zones_file contents, which consists of a sequence of Forward Zone entries:

- zone: example1.com
  forwarders:
    - 127.0.0.1
    - 127.0.0.1:5353
    - '[::1]:53'
- zone: example2.com
  forwarders:
    - '::1'
  recurse: true
  notify_allowed: true

Note

The recurse field is relevant only in a Forward Zone clause in a forwarding file. It has a fixed value in the context of recursor.forward_zones and recursor.forward_zones_recurse.

Starting with version 5.1.0, names can be used if recursor.system_resolver_ttl is set. The names will be resolved using the system resolver and an automatic refresh of the forwarding zones will happen if a name starts resolving to a new address. The refresh is done by performing the equivalent of rec_control reload-zones.

Auth Zone

An auth zone is defined as:

zone: string
file: string

An example of a auth_zones entry, consisting of a sequence of Auth Zone:

recursor:
  auth_zones:
    - zone: example.com
      file: zones/example.com.zone
    - zone: example.net
      file: zones/example.net.zone

Description of YAML syntax corresponding to Lua config items

The YAML settings below were introduced in version 5.1.0 and correspond to their respective Lua settings. Refer to Advanced Configuration Using Lua.

TrustAnchor

As of version 5.1.0, a trust anchor is defined as

name: string
dsrecords: sequence of DS record strings in presentation format

An example of a trustanchors entry, which is a sequence of TrustAnchor:

dnssec:
  trustanchors:
    - name: example.com
      dsrecords:
      - 10000 8 2 a06d44b80b8f1d39a95c0b0d7c65d08458e880409bbc683457104237c7f8ec8d

NegativeTrustAnchor

As of version 5.1.0, a negative trust anchor is defined as

name: string
reason: string

An example of a negative_trustanchors entry, which is a sequence of NegativeTrustAnchor:

dnssec:
  negative_trustanchors:
    - name: example.com
      reason: an example

ProtobufServer

As of version 5.1.0, a protobuf server is defined as

servers: [] Sequence of strings representing SocketAddress
timeout: 2
maxQueuedEntries: 100
reconnectWaitTime: 1
taggedOnly: false
asyncConnect: false
logQueries: true
logResponses: true
exportTypes: [A, AAAA, CNAME] Sequence of QType names
logMappedFrom: false
frame4: false # since 5.5.0
strategy: All # since 5.5.0

Changed in version 5.3.0: The aliases max_queued_entries, reconnect_wait_time, tagged_only, async_connect, log_queries, log_responses, export_types, log_mapped_from have been introduced.

An example of a protobuf_servers entry, which is a sequence of ProtobufServer:

logging:
  protobuf_servers:
    - servers: [127.0.0.1:4578]
      exportTypes: [A, AAAA]
    - servers: ['[2001:DB8::1]':7891]
      logQueries: false
      logResponses: true
      exportTypes: [A]

DNSTapFrameStreamServers

As of version 5.1.0, a dnstap framestream server is defined as

servers: [] Sequence of strings representing SocketAddress or a socket path
logQueries: true
logResponses: true
bufferHint: 0
flushTimeout: 0
inputQueueSize: 0
outputQueueSize: 0
queueNotifyThreshold: 0
reopenInterval: 0

Changed in version 5.3.0: The aliases log_queries, log_responses, buffer_hint, flush_timeout, input_queue_size, output_queue_size, queue_notify_threshold, reopen_interval have been introduced.

An example of a dnstap_framestream_servers entry, which is a sequence of DNSTapFrameStreamServers:

logging:
  dnstap_framestream_servers:
    - servers: [127.0.0.1:2024]
      logQueries: false
      logResponses: true

DNSTapNODFrameStreamServers

As of version 5.1.0, an NOD dnstap framestream server is defined as

servers: [] Sequence of strings representing SocketAddress or a socket path
logNODs: true
logUDRs: false
bufferHint: 0
flushTimeout: 0
inputQueueSize: 0
outputQueueSize: 0
queueNotifyThreshold: 0
reopenInterval: 0

Changed in version 5.3.0: The aliases log_nods, log_udrs, buffer_hint, flush_timeout, input_queue_size, output_queue_size, queue_notify_threshold, reopen_interval have been introduced.

An example of a dnstap_nod_framestream_servers entry, which is a sequence of DNSTapNODFrameStreamServers:

logging:
  dnstap_nop_framestream_servers:
    - servers: [127.0.0.1:2024]
      logNODs: false
      logUDRs: true

SortList

As of version 5.1.0, a sortlist entry is defined as

- key: Subnet
  subnets:
    - subnet: Subnet
      order: number

An example of a sortlists entry, which is a sequence of SortList:

recursor:
  sortlists:
    - key: 198.18.0.0/8
      subnets:
        - subnet: 233.252.0.0/24
          order: 10
    - key: 198.18.1.0/8
      subnets:
        - subnet: 198.18.0.0/16
          order: 20
        - subnet: 203.0.113.0/24
          order: 20

RPZ

As of version 5.1.0, an RPZ entry is defined as

name: name or pathname
addresses: [] Sequence of SocketAddress
defcontent: string
defpol:  Custom, Drop, NXDOMAIN, NODATA Truncate or NoAction
defpolOverrideLocalData: true
defttl: number
extendedErrorCode: number
extendedErrorExtra: string
includeSOA: false
ignoreDuplicates: false
maxTTL: number
policyName: string
tags: Sequence of string
overridesGettag: true
zoneSizeHint: number
tsig:
  name: string
  algo: string
  secret: base64string
refresh: number
maxReceivedMBytes: number
localAddress: IP address
axfrTimeout: number
dumpFile: string
seedFile: string

Changed in version 5.3.0: The aliases defpol_override_local_data, extended_error_code, extended_error_extra, include_soa, ignore_duplicates, policy_name, overriddes_gettag, zone_size_hint, max_received_bytes, local_address, axfr_timeout, dump_file, seed_file have been introduced.

If addresses is empty, the name field specifies the path name of the RPZ; otherwise, the name field defines the name of the RPZ. Starting with version 5.2.0, names instead of IP addresses can be used for addresses if recursor.system_resolver_ttl is set.

An example of an rpzs entry, which is a sequence of RPZ:

recursor:
  rpzs:
    - name: 'path/to/a/file'
    - name: 'remote.rpz'
      addresses: ['192.168.178.99']
      policyName: mypolicy

ZoneToCache

As of version 5.1.0, a ZoneToCache entry is defined as

zone: zonename
method: One of axfr, url, file
sources: [] Sequence of string, representing IP address, URL or path
timeout: 20
tsig:
  name: name of key
  algo: algorithm
  secret: Base64 encoded secret
refreshPeriod: 86400
retryOnErrorPeriod: 60
maxReceivedMBytes: 0 Zero mean no restriction
localAddress: local IP address to  bind to.
zonemd: One of ignore, validate, require
dnssec: One of ignore, validate, require

Changed in version 5.3.0: The aliases refresh_period, retry_on_error, max_received_mbytes, local_address has been introduced.

An example of an zonetocaches entry, which is a sequence of ZoneToCache:

recordcache:
  zonetocaches:
    - zone: .
      method: url
      sources: ['https://www.example.com/path']
    - zone: example.com
      method: file
      sources: ['dir/example.com.zone']

AllowedAdditionalQType

As of version 5.1.0, an allowed additional qtype entry is defined as:

qtype: string representing a QType
targets: [] Sequence of string representing QType
mode: One of Ignore, CacheOnly, CacheOnlyRequireAuth, ResolveImmediately, ResolveDeferred, default CacheOnlyRequireAuth

An example of an allowed_additional_qtypes entry, which is a sequence of AllowedAdditionalQType:

recursor:
  allowed_additional_qtypes:
  - qtype: MX
    targets: [A, AAAA]
  - qtype: NAPTR
    targets: [A, AAAA, SRV]
    mode: ResolveDeferred

ProxyMapping

As of version 5.1.0, a proxy mapping entry is defined as:

subnet: Subnet
address: IPAddress
domains: [] Sequence of string

An example of an proxymappings entry, which is a sequence of ProxyMapping:

incoming:
  proxymappings:
    - subnet: 192.168.178.0/24
      address: 128.66.1.2
    - subnet: 192.168.179.0/24
      address: 128.66.1.3
      domains:
        - example.com
        - example.net

Description of YAML syntax for additional structured types

ForwardingCatalogZone

As of version 5.2.0, a forwarding catalog zone entry is defined as:

zone: Name of catalog zone
notify_allowed: bool, default false
xfr:
  addresses: [] Sequence of SocketAddress
  zoneSizeHint: number, default not set
  tsig:
    name: string
    algo: string
    secret: base64string
  refresh: number, default not set
  maxReceivedMBytes: number, default not set
  localAddress: IP address, default not set
  axfrTimeout: number, default 20
groups:
- name: optional group name
  forwarders: [] Sequence of SocketAddress
  recurse: bool, default false
  notify_allowed: bool, default false

Changed in version 5.3.0: The aliases zone_size_hint, max_received_bytes, local_address, axfr_timeout have been introduced.

While this setting has no equivalent old-style Lua configuration, it cannot appear together with lua-config-file being set. If you want to use catalog zones to define forwards, you need to convert existing Lua configuration to YAML format.

Names instead of IP addresses can be used for addresses if recursor.system_resolver_ttl is set. An example of a recursor.forwarding_catalog_zones entry, which is a sequence of ForwardingCatalogZone:

recursor:
  forwarding_catalog_zones:
  - zone: 'forward.example'
    xfr:
      addresses: [128.66.1.2]
    groups:
      - forwarders: [192.168.178.1] # default forwarder
      - name: mygroup
        forwarders: [192.168.179.2] # forwarder for catalog zone members in mygroup
        recurse: true
        notify_allowed: true
  - zone: 'forward2.example'
    xfr:
      addresses: [128.66.1.3]
    groups:
      - forwarders: [192.168.178.3] # only default forwarder for 2nd catalog zone

Recursor will transfer the catalog zone from the authoritative server using IXFR (falling back to AXFR if needed) and add forwarding clauses for all members of the catalog zone. The forwarding parameters will be taken from the default group entry (the one without a name) defined in the YAML settings. For catalog zone members in a group, the forwarding parameters will be taken from the group entry with the corresponding name.

The forwarding definitions will be written into a file $api_dir/catzone.$zonename. webservice.api_dir must be defined, the directory must exist and be writable by the Recursor process.

IncomingWSConfig

As of version 5.3.0, an incoming web server configuration is defined as

addresses: [] Sequence of SocketAddress
tls:
  certificates: file containing full certificate chain in PEM format or (since version 5.5.0) a PKCS12 file
  key: file containing private key in PEM format
  password: the password used to decrypt a PKCS12 file (since version 5.5.0)

A webservice.listen section contains a sequence of IncomingWSConfig, for example:

webservice:
  listen:
    - addresses: [127.0.0.1:8083, '[::]:8083']
      tls:
        certificate: fullchain.pem
        key: keyfile.key
    - addresses: [127.0.0.1:8084, '[::]:8084']

If no tls section is present, plaintext http connections are accepted on the listed addresses.

If a tls section is present, clients are required to use https to contact any of the address-port combinations listen in addresses.

If both the certificate and the key fields are set, the values specify unencrypted PEM files. The password field is ignored in that case.

If the key field is not set but the certificate and password fields are set, the listed file is assumed to be an encrypted PKCS12 (also known as pfx) file containing both a key and the certificate chain. The pkcs12 feature is only available starting with version 5.5.0 and if the Rust build environment used is version 1.88 or higher.

At the moment it is not possible to list additional properties of the TLS listener.

OutgoingTLSConfiguration

As of version 5.4.0, an outgoing TLS (DoT) configuration is defined as

name: A name, default not set.
provider: Either 'openssl' (default) or 'gnutls'.
suffixes: A sequence of domain names, default empty.
subnets: A sequence of Subnet strings (no negation supported), default empty.
validate_certificate: Set to true to enforce certificate validation, default false.
ca_store: CA store file containing certificates in PEM format, default is to use the system CA store.
verbose_logging: Whether to log more details on DoT connections, default false.
subject_name: The subject name passed in the SNI value of the TLS handshake, and against which to validate the certificate presented if applicable. Default is to use the nameserver name if available. If set this value supersedes any ``subject_address`` one.
subject_address: The subject IP address passed in the SNI value of the TLS handshake, and against which to validate the certificate presented by the backend. Default is to use the remote IP address if no nameserver name is available.
ciphers: The TLS ciphers to use. The exact format depends on the provider used. When the OpenSSL provider is used, ciphers for TLS 1.3 must be specified via ciphers_tls_13.
ciphers_tls_13: The ciphers to use for TLS 1.3, when the OpenSSL provider is used. When the GnuTLS provider is used, ciphers applies regardless of the TLS protocol and this setting is not used.
# Version 5.5.0 adds the fields below and apply to the OpenSSL provider only
client_certificate: The pathname of a file containing a TLS client certificate (PEM or PKCS12 format).
client_certificate_key: The pathname of a file containing the key corresponding to the client certificate (PEM format).
client_certificate_password: The password to unlock the PKCS12 file.

If both the client_certificate and the client_certificate_key fields are set, the values specify unencrypted PEM files. The client_certificate_password field is ignored in that case.

If the client_certificate_key field is not set but the client_certificate and client_certificate_password fields are set, the listed file is assumed to be an encrypted PKCS12 (also known as pfx) file containing both a key and the certificate chain.

A outgoing.tls_configurations section contains a sequence of OutgoingTLSConfiguration, for example:

outgoing:
  tls_configurations:
  - name: 'DoT with verify'
    suffixes: [powerdns.com]
    validate_certificate: true
  - name: 'Forward to quad1 or quad9'
    subnets: [1.1.1.0/24,9.9.9.9]
    validate_certificate: true
    verbose_logging: true
  - name: 'Forward to google'
    subnets: [8.8.8.8]
    subject_name: dns.google
    validate_certificate: true

The first entry matches on a name server name in powerdns.com, and switches on validation. The second entry matches on a subnet or IP addresses, and enables (IP based) certificate validation and verbose logging. The third entry matches on IP, and switches on validation with the SNI name dns.google.

When looking for an outgoing TLS configuration matching is done against the subnets lists with the remote IP as key. This is typically a forwarding target. If no match is found on IP, a suffix match against the names in the suffixes lists is done using the nameserver name as key. If again no match is found, the default configuration is used, this mean using the openssl provider, no certificate validation and no verbose logging.

OpenTelemetryTraceCondition

As of version 5.4.0, an OpenTelemetry Trace condition is defined as

acls: sequence of string representing subnets, required
qnames: sequence of string representing DNS names
qtypes: a sequence of string representing Query Type names
qid: an integer specifying a Query ID
edns_option_required: bool, default false
traceid_only: bool, default false

A logging.opentelemetry_trace_conditions section contains a sequence of OpenTelemetryTraceCondition, for example:

logging:
  opentelemetry_trace_conditions:
    - acls: [127.0.0.1]
    - acls: [192.168.178.0/24]
      qnames: [a.very.specific.suffix]
      qtypes: ['A', 'AAAA']
      qid: 1234
      edns_option_required: true
      traceid_only: false

See OpenTelemetry Traces for an explanation how to use OpenTelemetry Trace Conditions.

The YAML settings

The notation section.name means that an entry name can appear in the YAML section section. So the entry recordcache.max_ttl will end up in settings file as follows:

recordcache:
  ...
  max_ttl: 3600
  ...

carbon.instance

Added in version 4.2.0.

Change the instance or third string of the metric key. The default is recursor.

carbon.interval

If sending carbon updates, this is the interval between them in seconds. See Metrics and Statistics.

carbon.ns

Added in version 4.2.0.

Change the namespace or first string of the metric key. The default is pdns.

carbon.ourname

If sending carbon updates, if set, this will override our hostname. Be careful not to include any dots in this setting, unless you know what you are doing. See Sending metrics to Graphite/Metronome over Carbon.

carbon.server

  • Sequence of Socket Address (IP or IP:port combinations)

  • Default: []

  • Old style setting: carbon-server

  • Runtime modifiable using rec_control set-carbon-server

Will send all available metrics to these servers via the carbon protocol, which is used by graphite and metronome. See Metrics and Statistics.

dnssec.aggressive_cache_max_nsec3_hash_cost

Added in version 5.0.2.

Added in version 4.9.3.

Added in version 4.8.6.

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.

dnssec.aggressive_cache_min_nsec3_hit_ratio

Added in version 4.9.0.

The limit for which to put NSEC3 records into the aggressive cache. A value of n means that an NSEC3 record is only put into the aggressive cache if the estimated probability of a random name hitting the NSEC3 record is higher than 1/n. A higher n will cause more records to be put into the aggressive cache, e.g. a value of 4000 will cause records to be put in the aggressive cache even if the estimated probability of hitting them is twice as low as would be the case for n=2000. A value of 0 means no NSEC3 records will be put into the aggressive cache.

For large zones the effectiveness of the NSEC3 cache is reduced since each NSEC3 record only covers a randomly distributed subset of all possible names. This setting avoids doing unnecessary work for such large zones.

dnssec.aggressive_nsec_cache_size

Added in version 4.5.0.

  • Integer

  • Default: 100000

  • Old style setting: aggressive-nsec-cache-size

  • Runtime modifiable using rec_control set-max-aggr-nsec-cache-size

The number of records to cache in the aggressive cache. If set to a value greater than 0, the recursor will cache NSEC and NSEC3 records to generate negative answers, as defined in RFC 8198. To use this, DNSSEC processing or validation must be enabled by setting dnssec.validation to process, log-fail or validate.

dnssec.disabled_algorithms

Added in version 4.9.0.

A list of DNSSEC algorithm numbers that should be considered disabled. These algorithms will not be used to validate DNSSEC signatures. Zones (only) signed with these algorithms will be considered Insecure.

If this setting is empty (the default), Recursor will determine which algorithms to disable automatically. This is done for specific algorithms only, currently algorithms 5 (RSASHA1) and 7 (RSASHA1NSEC3SHA1).

This is important on systems that have a default strict crypto policy, like RHEL9 derived systems. On such systems not disabling some algorithms (or changing the security policy) will make affected zones to be considered Bogus as using these algorithms fails.

dnssec.log_bogus

  • Boolean

  • Default: false

  • Old style setting: dnssec-log-bogus

  • Runtime modifiable using rec_control set-dnssec-log-bogus

Log every DNSSEC validation failure. Note: This is not logged per-query but every time records are validated as Bogus.

dnssec.max_dnskeys

Added in version 5.0.2.

Added in version 4.9.3.

Added in version 4.8.6.

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.

dnssec.max_ds_per_zone

Added in version 5.0.2.

Added in version 4.9.3.

Added in version 4.8.6.

Maximum number of DS records to consider when validating records inside a zone.

dnssec.max_nsec3_hash_computations_per_query

Added in version 5.0.2.

Added in version 4.9.3.

Added in version 4.8.6.

Maximum number of NSEC3 hashes that we are willing to compute during DNSSEC validation, per incoming query.

dnssec.max_nsec3s_per_record

Added in version 5.0.2.

Added in version 4.9.3.

Added in version 4.8.6.

Maximum number of NSEC3s to consider when validating a given denial of existence.

dnssec.max_rrsigs_per_record

Added in version 5.0.2.

Added in version 4.9.3.

Added in version 4.8.6.

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.

dnssec.max_signature_validations_per_query

Added in version 5.0.2.

Added in version 4.9.3.

Added in version 4.8.6.

Maximum number of RRSIG signatures we are willing to validate per incoming query.

dnssec.negative_trustanchors

Added in version 5.1.0.

Sequence of negative trust anchors.

dnssec.nsec3_max_iterations

Added in version 4.1.0.

Changed in version 4.5.2: Default is now 150, was 2500 before.

Changed in version 5.0.0: Default is now 50, was 150 before.

Maximum number of iterations allowed for an NSEC3 record. If an answer containing an NSEC3 record with more iterations is received, its DNSSEC validation status is treated as Insecure.

dnssec.signature_inception_skew

Added in version 4.1.5.

Changed in version 4.2.0: Default is now 60, was 0 before.

Allow the signature inception to be off by this number of seconds. Negative values are not allowed.

dnssec.trustanchorfile

Added in version 5.1.0.

A path to a zone file to read trust anchors from. This can be used to read distribution provided trust anchors, as for instance /usr/share/dns/root.key from Debian’s dns-root-data package.

dnssec.trustanchorfile_interval

Added in version 5.1.0.

Interval (in hours) to re-read the trustanchorfile. Zero disables periodic re-reads.

dnssec.trustanchors

Added in version 5.1.0.

dnssec:
  - name: .
    dsrecords:
      - 20326 8 2 e06d44b80b8f1d39a95c0b0d7c65d08458e880409bbc683457104237c7f8ec8d
      - 38696 8 2 683d2d0acb8c9b712a1948b27f741219298d0a450d612c483af444a4c0fb2b16

Sequence of trust anchors. If the sequence contains an entry for the root zone, the default root zone trust anchor is not included. If a zone appears multiple times, the entries in dsrecords are merged.

dnssec.validation

Added in version 4.0.0.

Changed in version 4.5.0: The default changed from process-no-validate to process

  • String

  • Default: process

  • Old style setting: dnssec

One of off, process-no-validate, process, log-fail, validate

Set the mode for DNSSEC processing, as detailed in DNSSEC in the PowerDNS Recursor.

off

No DNSSEC processing whatsoever. Ignore DO-bits in queries, don’t request any DNSSEC information from authoritative servers. This behaviour is similar to PowerDNS Recursor pre-4.0.

process-no-validate

Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries. Don’t do any validation.

process

Respond with DNSSEC records to clients that ask for it, set the DO bit on all outgoing queries. Do validation for clients that request it (by means of the AD- bit or DO-bit in the query).

log-fail

Similar behaviour to process, but validate RRSIGs on responses and log bogus responses.

validate

Full blown DNSSEC validation. Send SERVFAIL to clients on bogus responses.

dnssec.x_dnssec_names

Added in version 4.5.0.

List of names whose DNSSEC validation metrics will be counted in a separate set of metrics that start with x-dnssec-result-. The names are suffix-matched. This can be used to not count known failing (test) name validations in the ordinary DNSSEC metrics.

ecs.add_for

Added in version 4.2.0.

  • Sequence of Subnet (IP addresses or subnets, negation supported)

  • 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']

  • Old style setting: ecs-add-for

List of requestor netmasks for which the requestor IP Address should be used as the EDNS Client Subnet for outgoing queries. Outgoing queries for requestors that do not match this list will use the ecs.scope_zero_address instead. Valid incoming ECS values from incoming.use_incoming_edns_subnet are not replaced.

Regardless of the value of this setting, ECS values are only sent for outgoing queries matching the conditions in the outgoing.edns_subnet_allow_list setting. This setting only controls the actual value being sent.

This defaults to not using the requestor address inside RFC1918 and similar ‘private’ IP address spaces.

ecs.cache_limit_ttl

Added in version 4.1.12.

The minimum TTL for an ECS-specific answer to be inserted into the record cache. This condition applies in conjunction with ecs-ipv4-cache-bits or ecs-ipv6-cache-bits. That is, only if both the limits apply, the record will not be cached. This decision can be overridden by ecs-ipv4-never-cache and ecs-ipv6-never-cache.

ecs.ipv4_bits

Added in version 4.1.0.

Number of bits of client IPv4 address to pass when sending EDNS Client Subnet address information.

ecs.ipv4_cache_bits

Added in version 4.1.12.

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 record cache. This condition applies in conjunction with ecs-cache-limit-ttl. That is, only if both the limits apply, the record will not be cached. This decision can be overridden by ecs-ipv4-never-cache and ecs-ipv6-never-cache.

ecs.ipv4_never_cache

Added in version 4.5.0.

When set, never cache replies carrying EDNS IPv4 Client Subnet scope in the record cache. In this case the decision made by ecs-ipv4-cache-bits and ecs-cache-limit-ttl is no longer relevant.

ecs.ipv6_bits

Added in version 4.1.0.

Number of bits of client IPv6 address to pass when sending EDNS Client Subnet address information.

ecs.ipv6_cache_bits

Added in version 4.1.12.

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 record cache. This condition applies in conjunction with ecs-cache-limit-ttl. That is, only if both the limits apply, the record will not be cached. This decision can be overridden by ecs-ipv4-never-cache and ecs-ipv6-never-cache.

ecs.ipv6_never_cache

Added in version 4.5.0.

When set, never cache replies carrying EDNS IPv6 Client Subnet scope in the record cache. In this case the decision made by ecs-ipv6-cache-bits and ecs-cache-limit-ttl is no longer relevant.

ecs.minimum_ttl_override

Changed in version 4.5.0: Old versions used default 0.

  • Integer

  • Default: 1

  • Old style setting: ecs-minimum-ttl-override

  • Runtime modifiable using rec_control set-ecs-minimum-ttl

This setting artificially raises the TTLs of records in the ANSWER section of ECS-specific answers to be at least this long. Setting this to a value greater than 1 technically is an RFC violation, but might improve performance a lot. Using a value of 0 impacts performance of TTL 0 records greatly, since it forces the recursor to contact authoritative servers every time a client requests them.

ecs.scope_zero_address

Added in version 4.1.0.

The IP address sent via EDNS Client Subnet to authoritative servers listed in outgoing.edns_subnet_allow_list when incoming.use_incoming_edns_subnet is set and the query has an ECS source prefix-length set to 0. The default is to look for the first usable (not an any one) address in outgoing.source_address (starting with IPv4). If no suitable address is found, the recursor fallbacks to sending 127.0.0.1.

incoming.allow_from

  • Sequence of Subnet (IP addresses or subnets, negation supported)

  • 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']

  • Old style setting: allow-from

  • Runtime modifiable using rec_control reload-acls

Netmasks (both IPv4 and IPv6) that are allowed to use the server. The default allows access only from RFC 1918 private IP addresses. An empty value means no checking is done, all clients are allowed. Due to the aggressive nature of the internet these days, it is highly recommended to not open up the recursor for the entire internet. Questions from IP addresses not listed here are ignored and do not get an answer.

When the Proxy Protocol is enabled (see incoming.proxy_protocol_from), the recursor will check the address of the client IP advertised in the Proxy Protocol header instead of the one of the proxy.

Note that specifying an IP address without a netmask uses an implicit netmask of /32 or /128.

incoming.allow_from_file

  • String

  • Default: (empty)

  • Old style setting: allow-from-file

  • Runtime modifiable using rec_control reload-acls

Like incoming.allow_from, except reading a sequence of Subnet from file. Overrides the incoming.allow_from setting. Example content of th specified file:

- 127.0.0.1
- ::1

incoming.allow_no_rd

Added in version 5.0.0.

  • Boolean

  • Default: false

  • Old style setting: allow-no-rd

Allow no recursion desired (RD=0) queries to query cache contents. If not set (the default), these queries are answered with rcode Refused.

incoming.allow_notify_for

Added in version 4.6.0.

  • Sequence of strings

  • Default: []

  • Old style setting: allow-notify-for

  • Runtime modifiable using rec_control reload-acls

Domain names specified in this list are used to permit incoming NOTIFY operations to wipe any cache entries that match the domain name. If this list is empty, all NOTIFY operations will be ignored. Matching is done using suffix matching, it is allowed to NOTIFY a subdomain of a listed domain.

incoming.allow_notify_for_file

Added in version 4.6.0.

  • String

  • Default: (empty)

  • Old style setting: allow-notify-for-file

  • Runtime modifiable using rec_control reload-acls

Like incoming.allow_notify_for, except reading a sequence of names from file. Example contents of specified file:

- example.com
- example.org

incoming.allow_notify_from

Added in version 4.6.0.

  • Sequence of Subnet (IP addresses or subnets, negation supported)

  • Default: []

  • Old style setting: allow-notify-from

  • Runtime modifiable using rec_control reload-acls

Subnets (both IPv4 and IPv6) that are allowed to issue NOTIFY operations to the server. NOTIFY operations from IP addresses not listed here are ignored and do not get an answer.

When the Proxy Protocol is enabled (see incoming.proxy_protocol_from), the recursor will check the address of the client IP advertised in the Proxy Protocol header instead of the one of the proxy.

Note that specifying an IP address without a netmask uses an implicit netmask of /32 or /128.

NOTIFY operations received from a client listed in one of these netmasks will be accepted and used to initiate a freshness check for an RPZ zone or wipe any cache entries whose zones match the zone specified in the NOTIFY operation, but only if that zone (or one of its parents) is included in incoming.allow_notify_for, incoming.allow_notify_for_file, or recursor.forward_zones_file with a allow_notify set to true.

incoming.allow_notify_from_file

Added in version 4.6.0.

  • String

  • Default: (empty)

  • Old style setting: allow-notify-from-file

  • Runtime modifiable using rec_control reload-acls

Like incoming.allow_notify_from, except reading a sequence of Subnet from file.

incoming.distribution_load_factor

Added in version 4.1.12.

If incoming.pdns_distributes_queries is set and this setting is set to another value than 0, the distributor thread will use a bounded load-balancing algorithm while distributing queries to worker threads, making sure that no thread is assigned more queries than distribution-load-factor times the average number of queries currently processed by all the workers. For example, with a value of 1.25, no server should get more than 125 % of the average load. This helps making sure that all the workers have roughly the same share of queries, even if the incoming traffic is very skewed, with a larger number of requests asking for the same qname.

incoming.distribution_pipe_buffer_size

Added in version 4.2.0.

Size in bytes of the internal buffer of the pipe used by the distributor to pass incoming queries to a worker thread. Requires support for F_SETPIPE_SZ which is present in Linux since 2.6.35. The actual size might be rounded up to a multiple of a page size. 0 means that the OS default size is used. A large buffer might allow the recursor to deal with very short-lived load spikes during which a worker thread gets overloaded, but it will be at the cost of an increased latency.

incoming.distributor_threads

Added in version 4.2.0.

If incoming.pdns_distributes_queries is set, spawn this number of distributor threads on startup. Distributor threads handle incoming queries and distribute them to other threads based on a hash of the query.

incoming.edns_padding_from

Added in version 4.5.0.

Changed in version 5.0.5: YAML settings only: previously this was defined as a string instead of a sequence

  • Sequence of Subnet (IP addresses or subnets, negation supported)

  • Default: []

  • Old style setting: edns-padding-from

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 incoming.edns_padding_mode applies.

incoming.edns_padding_mode

Added in version 4.5.0.

One of always, padded-queries-only. Whether to add EDNS padding to all responses (always) or only to responses for queries containing the EDNS padding option (padded-queries-only, the default). In both modes, padding will only be added to responses for queries coming from incoming.edns_padding_from sources.

incoming.edns_padding_tag

Added in version 4.5.0.

The packetcache tag to use for padded responses, to prevent a client not allowed by the incoming.edns_padding_from list to be served a cached answer generated for an allowed one. This effectively divides the packet cache in two when incoming.edns_padding_from is used. Note that this will not override a tag set from one of the Lua hooks.

incoming.gettag_needs_edns_options

Added in version 4.1.0.

If set, EDNS options in incoming queries are extracted and passed to the gettag() hook in the ednsoptions table.

incoming.listen

Changed in version 5.3.0: ::1 was added to the list

Local IP addresses to which we bind. Each address specified can include a port number; if no port is included then the incoming.port port will be used for that address. If a port number is specified, it must be separated from the address with a ‘:’; for an IPv6 address the address must be enclosed in square brackets.

Example:

incoming:
  listen:
    - 127.0.0.1
    - '[::1]:5353'
    - '::'

incoming.max_concurrent_requests_per_tcp_connection

Added in version 4.3.0.

Maximum number of incoming requests handled concurrently per tcp connection. This number must be larger than 0 and smaller than 65536 and also smaller than max-mthreads.

incoming.max_tcp_clients

Changed in version 5.2.0: Before 5.2.0 the default was 128.

Maximum number of simultaneous incoming TCP connections allowed.

incoming.max_tcp_per_client

Maximum number of simultaneous incoming TCP connections allowed per client (remote IP address). 0 means unlimited.

incoming.max_tcp_queries_per_connection

Added in version 4.1.0.

Maximum number of DNS queries in a TCP connection. 0 means unlimited.

incoming.max_udp_queries_per_round

Added in version 4.1.4.

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 neglect scheduling new mthreads, handling responses from authoritative servers or responding to rec_control requests. 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 returning back to normal processing and handling other events.

incoming.non_local_bind

Bind to addresses even if one or more of the incoming.listen’s do not exist on this server. Setting this option will enable the needed socket options to allow binding to non-local addresses. 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.

incoming.pdns_distributes_queries

Changed in version 4.9.0: Default changed to no, previously it was yes.

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. This feature should maximize the cache hit ratio on versions before 4.9.0. To use more than one thread set incoming.distributor_threads in version 4.2.0 or newer. Enabling should improve performance on systems where incoming.reuseport does not have the effect of balancing the queries evenly over multiple worker threads.

incoming.port

  • Integer

  • Default: 53

  • Old style setting: local-port

Local port to bind to. If an address in incoming.listen does not have an explicit port, this port is used.

incoming.proxy_protocol_exceptions

Added in version 5.1.0.

Changed in version 5.3.0: rec_control reload-acls reloads this setting

If set, clients sending from an address in incoming.proxy_protocol_from to an address:port listed here are excluded from using the Proxy Protocol. If no port is specified, port 53 is assumed. This is typically used to provide an easy to use address and port to send debug queries to.

incoming.proxy_protocol_from

Added in version 4.4.0.

Changed in version 5.0.5: YAML settings only: previously this was defined as a string instead of a sequence

Changed in version 5.3.0: rec_control reload-acls reloads this setting

  • Sequence of Subnet (IP addresses or subnets, negation supported)

  • Default: []

  • Old style setting: proxy-protocol-from

  • Runtime modifiable using rec_control reload-acls (since 5.3.0)

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. 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.

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 incoming.allow_from ACL.

The dnsdist docs have more information about the PROXY protocol.

incoming.proxy_protocol_maximum_size

Added in version 4.4.0.

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.

incoming.proxymappings

Added in version 5.1.0.

Sequence of ProxyMapping

incoming.reuseport

Changed in version 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.

  • Boolean

  • Default: true

  • Old style setting: reuseport

If SO_REUSEPORT support is available, allows multiple threads and processes to open listening sockets for the same port.

Since 4.1.0, when incoming.pdns_distributes_queries is disabled and incoming.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.

incoming.tcp_fast_open

Added in version 4.1.0.

Enable TCP Fast Open support, if available, on the listening sockets. The numerical value supplied is used as the queue size, 0 meaning disabled. See TCP Fast Open Support.

incoming.tcp_timeout

Time to wait for data from TCP clients.

incoming.udp_truncation_threshold

Changed in version 4.2.0: Before 4.2.0, the default was 1680.

EDNS0 allows for large UDP response datagrams, which can potentially raise performance. Large responses however also have downsides in terms of reflection attacks. This setting limits the accepted size. Maximum value is 65535, but values above 4096 should probably not be attempted.

To know why 1232, see the note at outgoing.edns_bufsize.

incoming.use_incoming_edns_subnet

Whether to process and pass along a received EDNS Client Subnet to authoritative servers. The ECS information will only be sent for netmasks and domains listed in outgoing.edns_subnet_allow_list and will be truncated if the received scope exceeds ecs.ipv4_bits for IPv4 or ecs.ipv6_bits for IPv6.

logging.common_errors

Some DNS errors occur rather frequently and are no cause for alarm.

logging.disable_syslog

Do not log to syslog, only to stderr. Use this setting when running inside a supervisor that handles logging (like systemd). Note: do not use this setting in combination with recursor.daemon as all logging will disappear.

logging.dnstap_framestream_servers

Added in version 5.1.0.

Sequence of dnstap servers. Currently the maximum size of this list is one.

logging.dnstap_nod_framestream_servers

Added in version 5.1.0.

Sequence of NOD dnstap servers. Currently the maximum size of this list is one.

logging.facility

If set to a digit, logging is performed under this LOCAL facility. See Logging. Do not pass names like ‘local0’!

logging.loglevel

Changed in version 5.0.0: Previous version would not allow setting a level below 3 (error).

  • Integer

  • Default: 6

  • Old style setting: loglevel

Amount of logging. The higher the number, the more lines logged. Corresponds to syslog level values (e.g. 0 = emergency, 1 = alert, 2 = critical, 3 = error, 4 = warning, 5 = notice, 6 = info, 7 = debug). Each level includes itself plus the lower levels before it. Not recommended to set this below 3. If logging.quiet is no/false, logging.loglevel will be minimally set to 6 (info).

logging.opentelemetry_trace_conditions

Added in version 5.4.0.

  • Sequence of OpenTelemetryTraceCondition

  • Default: []

  • No equivalent old style setting

  • Runtime modifiable using rec_control reload-lua-config, since 5.2.0: reload-yaml

List of conditions specifying when to generate OpenTelemetry Traces.

logging.outgoing_protobuf_servers

Added in version 5.1.0.

Sequence of outgoing protobuf servers. Currently the maximum size of this list is one.

logging.protobuf_mask_v4

Added in version 5.1.0.

Network mask to apply to the client IPv4 addresses, for anonymization purposes. The default of 32 means no anonymization.

logging.protobuf_mask_v6

Added in version 5.1.0.

Network mask to apply to the client IPv6 addresses, for anonymization purposes. The default of 128 means no anonymization.

logging.protobuf_servers

Added in version 5.1.0.

Sequence of outgoing protobuf servers. Currently the maximum size of this list is one.

logging.protobuf_use_kernel_timestamp

Added in version 4.2.0.

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.

logging.quiet

  • Boolean

  • Default: true

  • Old style setting: quiet

Don’t log queries.

logging.rpz_changes

Added in version 4.1.0.

Log additions and removals to RPZ zones at Info (6) level instead of Debug (7).

logging.statistics_interval

Added in version 4.1.0.

Interval between logging statistical summary on recursor performance. Use 0 to disable.

logging.structured_logging

Added in version 4.6.0.

Changed in version 5.0.0: Disabling structured logging is deprecated

Changed in version 5.1.0: Disabling structured logging is not supported

Prefer structured logging when both an old style and a structured log message are available.

logging.structured_logging_backend

Added in version 4.8.0.

Changed in version 5.1.0: The JSON backend was added

The backend used for structured logging output. This setting must be set on the command line (--structured-logging-backend=...) to be effective. Available backends are:

  • default: use the traditional logging system to output structured logging information.

  • systemd-journal: use systemd-journal. When using this backend, provide -o verbose or simular output option to journalctl to view the full information.

  • json: JSON objects are written to the standard error stream.

See Structured Logging Dictionary for more details.

logging.timestamp

logging.trace

  • String

  • Default: no

  • Old style setting: trace

One of no, yes or fail. If turned on, output impressive heaps of logging. May destroy performance under load. 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. Also note that queries that do produce a result but with a failing DNSSEC validation are not written to the log

nod.db_size

Added in version 4.2.0.

The default size of the stable bloom filter used to store previously observed domains is 67108864. To change the number of cells, use this setting. For each cell, the SBF uses 1 bit of memory, and one byte of disk for the persistent file. If there are already persistent files saved to disk, this setting will have no effect unless you remove the existing files.

nod.db_snapshot_interval

Added in version 5.1.0.

Interval (in seconds) to write the NOD and UDR DB snapshots. Set to zero to disable snapshot writing.’,

nod.history_dir

Added in version 4.2.0.

This setting controls which directory is used to store the on-disk cache of previously observed domains.

The default depends on LOCALSTATEDIR when building the software. Usually this comes down to /var/lib/pdns-recursor/nod or /usr/local/var/lib/pdns-recursor/nod).

The newly observed domain feature uses a stable bloom filter to store a history of previously observed domains. The data structure is synchronized to disk every 10 minutes, and is also initialized from disk on startup. This ensures that previously observed domains are preserved across recursor restarts. If you change the new-domain-db-size setting, you must remove any files from this directory.

nod.ignore_list

Added in version 4.5.0.

This setting is a list of all domains (and implicitly all subdomains) that will never be considered a new domain. For example, if the domain ‘example.com’ is in the list, then ‘foo.bar.example.com’ will never be considered a new domain. One use-case for the ignore list is to never reveal details of internal subdomains via the new-domain-lookup feature.

nod.ignore_list_file

Added in version 5.1.0.

Path to a file with a list of domains. File should have one domain per line, with no extra characters or comments. See nod.ignore_list.

nod.log

Added in version 4.2.0.

If a newly observed domain is detected, log that domain in the recursor log file. The log line looks something like:

Jul 18 11:31:25 Newly observed domain nod=sdfoijdfio.com

nod.lookup

Added in version 4.2.0.

If a domain is specified, then each time a newly observed domain is detected, the recursor will perform an A record lookup of ‘<newly observed domain>.<lookup domain>’. For example if ‘new-domain-lookup’ is configured as ‘nod.powerdns.com’, and a new domain ‘example.com’ is detected, then an A record lookup will be made for ‘example.com.nod.powerdns.com’. This feature gives a way to share the newly observed domain with partners, vendors or security teams. The result of the DNS lookup will be ignored by the recursor.

nod.pb_tag

Added in version 4.2.0.

If protobuf is configured, then this tag will be added to all protobuf response messages when a new domain is observed.

nod.tracking

Added in version 4.2.0.

Whether to track newly observed domains, i.e. never seen before. This is a probabilistic algorithm, using a stable bloom filter to store records of previously seen domains. When enabled for the first time, all domains will appear to be newly observed, so the feature is best left enabled for e.g. a week or longer before using the results. Note that this feature is optional and must be enabled at compile-time, thus it may not be available in all pre-built packages. If protobuf is enabled and configured, then the newly observed domain status will appear as a flag in Response messages.

nod.unique_response_db_size

Added in version 4.2.0.

The default size of the stable bloom filter used to store previously observed responses is 67108864. To change the number of cells, use this setting. For each cell, the SBF uses 1 bit of memory, and one byte of disk for the persistent file. If there are already persistent files saved to disk, this setting will have no effect unless you remove the existing files.

nod.unique_response_history_dir

Added in version 4.2.0.

This setting controls which directory is used to store the on-disk cache of previously observed responses.

The default depends on LOCALSTATEDIR when building the software. Usually this comes down to /var/lib/pdns-recursor/udr or /usr/local/var/lib/pdns-recursor/udr).

The newly observed domain feature uses a stable bloom filter to store a history of previously observed responses. The data structure is synchronized to disk every 10 minutes, and is also initialized from disk on startup. This ensures that previously observed responses are preserved across recursor restarts. If you change the unique-response-db-size, you must remove any files from this directory.

nod.unique_response_ignore_list

Added in version 5.1.0.

This setting is a list of all domains (and implicitly all subdomains) that will never be considered for new unique domain responses. For example, if the domain ‘example.com’ is in the list, then ‘foo.bar.example.com’ will never be considered for a new unique domain response.

nod.unique_response_ignore_list_file

Added in version 5.1.0.

Path to a file with a list of domains. File should have one domain per line, with no extra characters or comments. See nod.unique_response_ignore_list.

nod.unique_response_log

Added in version 4.2.0.

Whether to log when a unique response is detected. The log line looks something like:

Oct 24 12:11:27 Unique response observed: qname=foo.com qtype=A rrtype=AAAA rrname=foo.com rrcontent=1.2.3.4

nod.unique_response_pb_tag

Added in version 4.2.0.

If protobuf is configured, then this tag will be added to all protobuf response messages when a unique DNS response is observed.

nod.unique_response_tracking

Added in version 4.2.0.

Whether to track unique DNS responses, i.e. never seen before combinations of the triplet (query name, query type, RR[rrname, rrtype, rrdata]). This can be useful for tracking potentially suspicious domains and behaviour, e.g. DNS fast-flux. If protobuf is enabled and configured, then the Protobuf Response message will contain a flag with udr set to true for each RR that is considered unique, i.e. never seen before. This feature uses a probabilistic data structure (stable bloom filter) to track unique responses, which can have false positives as well as false negatives, thus it is a best-effort feature. Increasing the number of cells in the SBF using the unique-response-db-size setting can reduce FPs and FNs.

outgoing.any_to_tcp

Added in version 5.4.0.

Send out requests with qtype ANY using TCP.

outgoing.bypass_server_throttling_probability

Added in version 5.0.0.

This setting determines the probability of a server marked down to be used anyway. 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. If this setting is zero throttled servers will never be selected to be used anyway.

outgoing.cookies

Added in version 5.4.0.

Enable DNS cookies (RFC 7873, RFC 9018) when contacting authoritative servers or forwarders.

outgoing.cookies_unsupported

Added in version 5.4.0.

Addresses of servers that do not properly support DNS cookies (RFC 7873, RFC 9018). Recursor will not even try to probe these servers for cookie support. If no port is specified port 53 is used.

outgoing.dont_query

  • Sequence of Subnet (IP addresses or subnets, negation supported)

  • 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']

  • Old style setting: dont-query

The DNS is a public database, but sometimes contains delegations to private IP addresses, like for example 127.0.0.1. This can have odd effects, depending on your network, and may even be a security risk. Therefore, the PowerDNS Recursor by default does not query private space IP addresses. This setting can be used to expand or reduce the limitations.

Queries for names in forward zones and to addresses as configured in any of the settings recursor.forward_zones, recursor.forward_zones_file or recursor.forward_zones_recurse are performed regardless of these limitations. However, if NS records are learned from recursor.forward_zones and the IP addresses of the nameservers learned in that way are included in outgoing.dont_query, lookups relying on these nameservers will fail with SERVFAIL.

outgoing.dont_throttle_names

Added in version 4.2.0.

  • Sequence of strings

  • Default: []

  • Old style setting: dont-throttle-names

  • Runtime modifiable using rec_control add-dont-throttle-names, clear-dont-throttle-names

When an authoritative server does not answer a query or sends a reply that the recursor does not like, it is throttled. Any servers’ name suffix-matching the supplied names will never be throttled.

Warning

Most servers on the internet do not respond for a good reason (overloaded or unreachable), dont-throttle-names could make this load on the upstream server even higher, resulting in further service degradation.

outgoing.dont_throttle_netmasks

Added in version 4.2.0.

  • Sequence of Subnet (IP addresses or subnets, negation supported)

  • Default: []

  • Old style setting: dont-throttle-netmasks

  • Runtime modifiable using rec_control rec_control add-dont-throttle-netmasks, rec_control clear-dont-throttle-netmask

When an authoritative server does not answer a query or sends a reply that the recursor does not like, it is throttled. Any servers matching the supplied netmasks will never be throttled.

This can come in handy on lossy networks when forwarding, where the same server is configured multiple times (e.g. with forward_zones_recurse: [ {zone: example.com, forwarders: [ 192.0.2.1, 192.0.2.1 ] } ]. By default, the PowerDNS Recursor would throttle the ‘first’ server on a timeout and hence not retry the ‘second’ one. In this case, outgoing.dont_throttle_netmasks could be set to include 192.0.2.1.

Warning

Most servers on the internet do not respond for a good reason (overloaded or unreachable), dont-throttle-netmasks could make this load on the upstream server even higher, resulting in further service degradation.

outgoing.dot_to_auth_names

Added in version 4.6.0.

Force DoT to the listed authoritative nameservers. For this to work, DoT support has to be compiled in. Currently, the certificate is not checked for validity in any way.

outgoing.dot_to_port_853

Added in version 4.6.0.

Enable DoT to forwarders that specify port 853.

outgoing.edns_bufsize

Changed in version 4.2.0: Before 4.2.0, the default was 1680

Note

Why 1232?

1232 is the largest number of payload bytes that can fit in the smallest IPv6 packet. IPv6 has a minimum MTU of 1280 bytes (RFC 8200, section 5), minus 40 bytes for the IPv6 header, minus 8 bytes for the UDP header gives 1232, the maximum payload size for the DNS response.

This is the value set for the EDNS0 buffer size in outgoing packets. Lower this if you experience timeouts.

outgoing.edns_padding

Added in version 4.8.0.

Whether to add EDNS padding to outgoing DoT queries.

outgoing.edns_subnet_allow_list

Added in version 4.5.0.

List of netmasks and domains that EDNS Client Subnet should be enabled for in outgoing queries.

For example, an EDNS Client Subnet option containing the address of the initial requestor (but see ecs.add_for) will be added to an outgoing query sent to server 192.0.2.1 for domain X if 192.0.2.1 matches one of the supplied netmasks, or if X matches one of the supplied domains. The initial requestor address will be truncated to 24 bits for IPv4 (see ecs.ipv4_bits) and to 56 bits for IPv6 (see ecs.ipv6_bits), as recommended in the privacy section of RFC 7871.

Note that this setting describes the destination of outgoing queries, not the sources of incoming queries, nor the subnets described in the EDNS Client Subnet option.

By default, this option is empty, meaning no EDNS Client Subnet information is sent.

outgoing.edns_subnet_harden

Added in version 5.2.4.

Added in version 5.1.6.

Added in version 5.0.12.

Do more strict checking or EDNS Client Subnet information returned by authoritative servers. Answers missing ECS information will be ignored and followed up by an ECS-less query.

outgoing.lowercase

Set to true to lowercase the outgoing queries. 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), PowerDNS preserves the case of the query. Broken authoritative servers might give a wrong or broken answer on this encoding. 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.

outgoing.max_busy_dot_probes

Added in version 4.7.0.

Limit the maximum number of simultaneous DoT probes the Recursor will schedule. The default value 0 means no DoT probes are scheduled.

DoT probes are used to check if an authoritative server’s IP address supports DoT. If the probe determines an IP address supports DoT, the Recursor will use DoT to contact it for subsequent queries until a failure occurs. After a failure, the Recursor will stop using DoT for that specific IP address for a while. The results of probes are remembered and can be viewed by the rec_control dump-dot-probe-map command. If the maximum number of pending probes is reached, no probes will be scheduled, even if no DoT status is known for an address. 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 outgoing.dot_to_auth_names. In that case no probe will be scheduled.

Note

DoT probing is an experimental feature. Please test thoroughly to determine if it is suitable in your specific production environment before enabling.

outgoing.max_bytesperq

Added in version 5.1.10.

Added in version 5.2.8.

Added in version 5.3.5.

The maximum number of cumulative bytes that will be accepted during the resolution of a single client query. This is useful to limit amplification attacks.

outgoing.max_ns_address_qperq

Added in version 4.1.16.

Added in version 4.2.2.

Added in version 4.3.1.

The maximum number of outgoing queries with empty replies for resolving nameserver names to addresses we allow during the resolution of a single client query. If IPv6 is enabled, an A and a AAAA query for a name counts as 1. If a zone publishes more than this number of NS records, the limit is further reduced for that zone by lowering it by the number of NS records found above the outgoing.max_ns_address_qperq value. The limit will not be reduced to a number lower than 5.

outgoing.max_ns_per_resolve

Added in version 4.8.0.

Added in version 4.7.3.

Added in version 4.6.4.

Added in version 4.5.11.

The maximum number of NS records that will be considered to select a nameserver to contact to resolve a name. If a zone has more than outgoing.max_ns_per_resolve NS records, a random sample of this size will be used. If outgoing.max_ns_per_resolve is zero, no limit applies.

outgoing.max_qperq

Changed in version 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.

  • Integer

  • Default: 50

  • Old style setting: max-qperq

The maximum number of outgoing queries that will be sent out during the resolution of a single client query. This is used to avoid cycles resolving names.

outgoing.network_timeout

Number of milliseconds to wait for a remote authoritative server to respond. If the number of concurrent requests is high, the :program:Recursor uses a lower value.

outgoing.non_resolving_ns_max_fails

Added in version 4.5.0.

Number of failed address resolves of a nameserver name to start throttling it, 0 is disabled. Nameservers matching outgoing.dont_throttle_names will not be throttled.

outgoing.non_resolving_ns_throttle_time

Added in version 4.5.0.

Number of seconds to throttle a nameserver with a name failing to resolve.

outgoing.server_down_max_fails

If a server has not responded in any way this many times in a row, no longer send it any queries for outgoing.server_down_throttle_time seconds. Afterwards, we will try a new packet, and if that also gets no response at all, we again throttle for outgoing.server_down_throttle_time seconds. Even a single response packet will drop the block.

outgoing.server_down_throttle_time

Throttle a server that has failed to respond outgoing.server_down_max_fails times for this many seconds.

outgoing.single_socket

Use only a single socket for outgoing queries.

outgoing.source_address

Changed in version 4.4.0: IPv6 addresses can be set with this option as well.

Note

While subnets and their negations are mentioned as accepted, the handling of subnets has not been implemented yet. Only individual IP addresses can be listed.

Send out local queries from this address, or addresses. By adding multiple addresses, increased spoofing resilience is achieved. When no address of a certain address family is configured, there are no queries sent with that address family. In the default configuration this means that IPv6 is not used for outgoing queries.

outgoing.tcp_fast_open_connect

Added in version 4.5.0.

Enable TCP Fast Open Connect support, if available, on the outgoing connections to authoritative servers. See TCP Fast Open Support.

outgoing.tcp_max_idle_ms

Added in version 4.6.0.

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.

outgoing.tcp_max_idle_per_auth

Added in version 4.6.0.

Maximum number of idle outgoing TCP/DoT connections to a specific IP per thread, 0 means do not keep idle connections open.

outgoing.tcp_max_idle_per_thread

Added in version 4.6.0.

Maximum number of idle outgoing TCP/DoT connections per thread, 0 means do not keep idle connections open.

outgoing.tcp_max_queries

Maximum total number of queries per outgoing TCP/DoT connection, 0 means no limit. After this number of queries, the connection is closed and a new one will be created if needed.

outgoing.tls_configurations

Added in version 5.4.0.

  • Sequence of OutgoingTLSConfiguration

  • Default: []

  • No equivalent old style setting

  • Runtime modifiable using rec_control reload-lua-config, since 5.2.0: reload-yaml

Configurations used for outgoing DoT connections. A DoT connection is matched against the subnets lists (using the remote IP) and if that does not provide a match, the nameserver name is matched against the suffixes lists. When a match is found, the corresponding DoT configuration is used.

outgoing.udp_source_port_avoid

Added in version 4.2.0.

Changed in version 5.2.0: port 4791 was added to the default list

A sequence of UDP port numbers to avoid when binding. For example:

outgoing:
  udp_source_port_avoid:
    - 4791
    - 5300
    - 11211

See outgoing.udp_source_port_min.

outgoing.udp_source_port_max

Added in version 4.2.0.

This option sets the maximum limit of UDP port number to bind on.

See outgoing.udp_source_port_min.

outgoing.udp_source_port_min

Added in version 4.2.0.

This option sets the low limit of UDP port number to bind on.

In combination with outgoing.udp_source_port_max it configures the UDP port range to use. Port numbers are randomized within this range on initialization, and exceptions can be configured with outgoing.udp_source_port_avoid

packetcache.disable

Turn off the packet cache. Useful when running with Lua scripts that modify answers in such a way they cannot be cached, though individual answer caching can be controlled from Lua as well.

packetcache.max_entries

  • Integer

  • Default: 500000

  • Old style setting: max-packetcache-entries

  • Runtime modifiable using rec_control set-max-packetcache-entries

Maximum number of Packet Cache entries. Sharded and shared by all threads since 4.9.0.

packetcache.max_entry_size

Added in version 5.1.10.

Added in version 5.2.8.

Added in version 5.3.5.

Maximum size of packets stored in the packet cache. Packets larger than this number will not be stored. Zero means no limit.

packetcache.negative_ttl

Added in version 4.9.0.

Maximum number of seconds to cache an NxDomain or NoData (a NoError response without answer records) answer in the packetcache. This setting’s maximum is capped to packetcache.ttl. i.e. setting packetcache.ttl to 15 and keeping packetcache.negative_ttl at the default will lower the used value of packetcache.negative_ttl to 15.

packetcache.servfail_ttl

Maximum number of seconds to cache an answer indicating a failure to resolve in the packet cache. Before version 4.6.0 only ServFail answers were considered as such. 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. This setting’s maximum is capped to packetcache.ttl. Setting packetcache.ttl to 15 and keeping packetcache.servfail_ttl at the default will lower the used value of packetcache.servfail_ttl to 15. Since 4.9.0, negative answers are handled separately from resolving failures.

packetcache.shards

Added in version 4.9.0.

Sets the number of shards in the packet cache. If you have high contention as reported by packetcache-contented/packetcache-acquired, you can try to enlarge this value or run with fewer threads.

packetcache.ttl

Changed in version 4.9.0: The default was changed from 3600 (1 hour) to 86400 (24 hours).

Maximum number of seconds to cache an item in the packet cache, no matter what the original TTL specified.

recordcache.limit_qtype_any

Added in version 4.9.9.

Added in version 5.0.9.

Added in version 5.1.2.

Limit answers to ANY queries constructed from the record cache in size. Trying to retrieve more than recordcache.max_rrset_size records will result in a ServFail’,

recordcache.locked_ttl_perc

Added in version 4.8.0.

Replace record sets in the record cache only after this percentage of the original TTL has passed. The PowerDNS Recursor already has several mechanisms to protect against spoofing attempts. 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.

The default value of 0 means no extra locking occurs. 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. A value of 100 means only expired record sets will be replaced.

There are a few cases where records will be replaced anyway:

  • Record sets that are expired will always be replaced.

  • Authoritative record sets will replace unauthoritative record sets unless DNSSEC validation of the new record set failed.

  • If the new record set belongs to a DNSSEC-secure zone and successfully passed validation it will replace an existing entry.

  • Record sets produced by recordcache.refresh_on_ttl_perc tasks will also replace existing record sets.

recordcache.max_cache_bogus_ttl

Added in version 4.2.0.

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.

recordcache.max_entries

  • Integer

  • Default: 1000000

  • Old style setting: max-cache-entries

  • Runtime modifiable using rec_control set-max-cache-entries

Maximum number of DNS record cache entries, shared by all threads since 4.4.0. Each entry associates a name and type with a record set. The size of the negative cache is 10% of this number.

recordcache.max_entry_size

Added in version 5.1.10.

Added in version 5.2.8.

Added in version 5.3.5.

Maximum size of storage used by a single record cache entry. Entries larger than this number will not be stored. Zero means no limit.

recordcache.max_negative_ttl

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. In practice, caches can become saturated with hundreds of thousands of hosts which are tried only once. This setting, which defaults to 3600 seconds, puts a maximum on the amount of time negative entries are cached.

recordcache.max_rrset_size

Added in version 4.9.9.

Added in version 5.0.9.

Added in version 5.1.2.

Maximum size of RRSets in cache. Trying to retrieve larger RRSets will result in a ServFail.’,

recordcache.max_ttl

Changed in version 4.1.0: The minimum value of this setting is 15. i.e. setting this to lower than 15 will make this value 15.

Maximum number of seconds to cache an item in the DNS cache, no matter what the original TTL specified. This value also controls the refresh period of cached root data. See Handling of root hints for more information on this.

recordcache.refresh_on_ttl_perc

Added in version 4.5.0.

Sets the ‘refresh almost expired’ percentage of the record cache. Whenever a record is fetched from the packet or record cache 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 update the record cache. In most cases this causes future queries to always see a non-expired record cache entry. A typical value is 10. If the value is zero, this functionality is disabled.

recordcache.serve_stale_extensions

Added in version 4.8.0.

Maximum number of times an expired record’s TTL is extended by 30s when serving stale. Extension only occurs if a record cannot be refreshed. A value of 0 means the Serve Stale mechanism is not used. To allow records becoming stale to be served for an hour, use a value of 120. See Serve Stale for a description of the Serve Stale mechanism.

recordcache.shards

Added in version 4.4.0.

Sets the number of shards in the record cache. If you have high contention as reported by record-cache-contented/record-cache-acquired, you can try to enlarge this value or run with fewer threads.

recordcache.zonetocaches

Added in version 5.1.0.

  • Sequence of ZoneToCache

  • Default: []

  • Equivalent Lua config in Zone to Cache

  • Runtime modifiable using rec_control reload-lua-config, since 5.2.0: reload-yaml

Sequence of ZoneToCache entries

recursor.allow_trust_anchor_query

Added in version 4.3.0.

Allow trustanchor.server CH TXT and negativetrustanchor.server CH TXT queries to view the configured DNSSEC (negative) trust anchors.

recursor.allowed_additional_qtypes

Added in version 5.1.0.

Sequence of AllowedAdditionalQType

recursor.any_to_tcp

Changed in version 5.4.0: Default is enabled now, was disabled before 5.4.0

  • Boolean

  • Default: true

  • Old style setting: any-to-tcp

Answer questions for the ANY type on UDP with a truncated packet that refers the remote client to TCP. Useful for mitigating ANY reflection attacks.

recursor.auth_zones

  • Sequence of Auth Zone

  • Default: []

  • Old style setting: auth-zones

  • Runtime modifiable using rec_control reload-zones

Zones read from these files (in BIND format) are served authoritatively (but without the AA bit set in responses). DNSSEC is not supported. Example:

recursor:
  auth_zones:
    - zone: example.org
      file: /var/zones/example.org
    - zone: powerdns.com
      file: /var/zones/powerdns.com

recursor.chroot

  • String

  • Default: (empty)

  • Old style setting: chroot

If set, chroot to this directory for more security. This is not recommended; instead, we recommend containing PowerDNS using operating system features. We ship systemd unit files with our packages to make this easy.

Make sure that /dev/log is available from within the chroot. Logging will silently fail over time otherwise (on logrotate).

When using chroot, all other paths (except for recursor.config_dir) set in the configuration are relative to the new root.

When running on a system where systemd manages services, chroot does not work out of the box, as PowerDNS cannot use the NOTIFY_SOCKET. Either do not chroot on these systems or set the ‘Type’ of this service to ‘simple’ instead of ‘notify’ (refer to the systemd documentation on how to modify unit-files).

recursor.config_dir

  • String

  • Default: Determined by distribution

  • Old style setting: config-dir

Location of configuration directory (where recursor.conf or recursor.yml is stored). Usually /etc/powerdns, but this depends on SYSCONFDIR during compile-time. Use default or set on command line.

recursor.config_name

  • String

  • Default: (empty)

  • Old style setting: config-name

When running multiple recursors on the same server, read settings from recursor-name.conf, this will also rename the binary image.

recursor.cpu_map

  • String

  • Default: (empty)

  • Old style setting: cpu-map

Set CPU affinity for threads, asking the scheduler to run those threads on a single CPU, or a set of CPUs. This parameter accepts a space separated list of thread-id=cpu-id, or thread-id=cpu-id-1,cpu-id-2,…,cpu-id-N. For example, to make the worker thread 0 run on CPU id 0 and the worker thread 1 on CPUs 1 and 2:

recursor:
  cpu_map: 0=0 1=1,2

The thread handling the control channel, the webserver and other internal stuff has been assigned id 0, the distributor threads if any are assigned id 1 and counting, and the worker threads follow behind. The number of distributor threads is determined by incoming.distributor_threads, the number of worker threads is determined by the recursor.threads setting.

This parameter is only available if the OS provides the pthread_setaffinity_np() function.

Note that, depending on the configuration, the Recursor can start more threads. Typically these threads will sleep most of the time. These threads cannot be specified in this setting as their thread-ids are left unspecified.

recursor.daemon

Changed in version 4.0.0: Default is now no, was yes before.

  • Boolean

  • Default: false

  • Old style setting: daemon

Operate in the background.

recursor.dns64_prefix

Added in version 4.4.0.

Enable DNS64 (RFC 6147) support using the supplied /96 IPv6 prefix. This will generate ‘fake’ AAAA records for names with only A records, as well as ‘fake’ PTR records to make sure that reverse lookup of DNS64-generated IPv6 addresses generate the right name. See DNS64 support for more flexible but slower alternatives using Lua.

recursor.etc_hosts_file

The path to the /etc/hosts file, or equivalent. This file can be used to serve data authoritatively using recursor.export_etc_hosts.

recursor.event_trace_enabled

Added in version 4.6.0.

Changed in version 5.3.0: A value to generate OpenTelemetry Trace data was added

  • Integer

  • Default: 0

  • Old style setting: event-trace-enabled

  • Runtime modifiable using rec_control set-event-trace-enabled

Enable the recording and logging of ref:event traces. This is an experimental feature and subject to change. Possible values are 0: (disabled), 1 (add information to protobuf logging messages), 2 (write to log), 4 (output OpenTelemetry Trace data in protobuf logging messages, since version 5.3.0). Values can be added to get multiple types of logging simultaneously. For example, 6 means: write to log and output OpenTelemetry Trace data in the protobuf stream.

recursor.export_etc_hosts

If set, this flag will export the host names and IP addresses mentioned in /etc/hosts.

recursor.export_etc_hosts_search_suffix

If set, all hostnames in the recursor.export_etc_hosts file are loaded in canonical form, based on this suffix, unless the name contains a ‘.’, in which case the name is unchanged. So an entry called ‘pc’ with export-etc-hosts-search-suffix='home.com' will lead to the generation of ‘pc.home.com’ within the recursor. An entry called ‘server1.home’ will be stored as ‘server1.home’, regardless of this setting.

recursor.extended_resolution_errors

Added in version 4.5.0.

Changed in version 5.0.0: Default changed to enabled, previously it was disabled.

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.

recursor.forward_zones

Changed in version 5.2.0: Zones having notify_allowed set will be added to incoming.allow_notify_for.

Queries for zones listed here will be forwarded to the IP address listed. i.e.

recursor:
  forward_zones:
    - zone: example.org
      forwarders:
      - 203.0.113.210
    - zone: powerdns.com
      forwarders:
      - 2001:DB8::BEEF:5

Multiple IP addresses can be specified and port numbers other than 53 can be configured:

recursor:
  forward_zones:
    - zone: example.org
      forwarders:
        - 203.0.113.210:5300
        - 127.0.0.1
    - zone: powerdns.com
      forwarders:
        - 127.0.0.1
        - 198.51.100.10:530
        - '[2001:DB8::1:3]:5300'

Forwarded queries have the recursion desired (RD) bit set to 0, meaning that this setting is intended to forward queries to authoritative servers. 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. 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. To forward to a recursive resolver use recursor.forward_zones_recurse.

Warning

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. To prevent this, add a Negative Trust Anchor (NTA) for this zone in the recursor.lua_config_file with addNTA(). If this forwarded zone is signed, instead of adding NTA, add the DS record to the recursor.lua_config_file using addTA(). See the DNSSEC in the PowerDNS Recursor information. When using trust anchors listed in a YAML settings file, use the dnssec.trustanchors and dnssec.negative_trustanchors clauses.

Note

The recurse field of a Forward Zone is fixed to false in the context of recursor.forward_zones.

Note

When an NS record for a subzone is learned and the IP address for that nameserver is included in the IP ranges in outgoing.dont_query, SERVFAIL is returned.

recursor.forward_zones_file

Changed in version 4.0.0: (Old style settings only) Comments are allowed, everything behind # is ignored.

Changed in version 4.6.0: (Old style settings only) Zones prefixed with a ^ are added to the allow-notify-for list. Both prefix characters can be used if desired, in any order.

  • String

  • Default: (empty)

  • Old style setting: forward-zones-file

  • Runtime modifiable using rec_control reload-zones

Same as recursor.forward_zones, parsed from a file as a sequence of Forward Zone.

The filename MUST end in .yml for the content to be parsed as YAML.

- zone: example1.com
  forwarders:
    - 127.0.0.1
    - 127.0.0.1:5353
    - '[::1]:53'
- zone: example2.com
  forwarders:
    - ::1
  recurse: true
  notify_allowed: true

The DNSSEC notes from recursor.forward_zones apply here as well.

recursor.forward_zones_recurse

Like regular recursor.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 resolvers. In contrast to regular forwarding, the rule that delegations of the forwarded subzones are respected is not active. This is because we rely on the forwarder to resolve the query fully.

Note

The recurse field of a Forward Zone is fixed to true in the context of recursor.forward_zones_recurse.

See recursor.forward_zones for additional options (such as supplying multiple recursive servers) and an important note about DNSSEC.

recursor.forwarding_catalog_zones

Added in version 5.2.0.

  • Sequence of ForwardingCatalogZone

  • Default: []

  • No equivalent old style setting

  • Runtime modifiable using rec_control reload-lua-config, since 5.2.0: reload-yaml

Sequence of ForwardingCatalogZone. This setting cannot be combined with recursor.lua_config_file.

recursor.hint_file

Changed in version 4.6.2: Introduced the value no to disable root-hints processing.

Changed in version 4.9.0: Introduced the value no-refresh to disable both root-hints processing and periodic refresh of the cached root NS records.

  • String

  • Default: (empty)

  • Old style setting: hint-file

If set, the root-hints are read from this file. If empty, the default built-in root hints are used.

In some special cases, processing the root hints is not needed, for example when forwarding all queries to another recursor. For these special cases, it is possible to disable the processing of root hints by setting the value to no or no-refresh. See Handling of root hints for more information on root hints handling.

recursor.ignore_unknown_settings

Names of settings to be ignored while parsing configuration files, if the setting name is unknown to PowerDNS.

Useful during upgrade testing.

recursor.include_dir

  • String

  • Default: (empty)

  • Old style setting: include-dir

Directory to scan for additional config files. All files that end with .yml are loaded in order using POSIX as locale.

recursor.latency_statistic_size

Indication of how many queries will be averaged to get the average latency reported by the ‘qa-latency’ metric.

recursor.lua_config_file

If set, and Lua support is compiled in, this will load an additional configuration file for newer features and more complicated setups. See Advanced Configuration Using Lua for the options that can be set in this file.

recursor.lua_dns_script

Path to a lua file to manipulate the Recursor’s answers. See Scripting PowerDNS Recursor for more information.

recursor.lua_global_include_dir

When creating a Lua context, all *.lua files in the directory are loaded into the Lua context.

recursor.lua_maintenance_interval

Added in version 4.2.0.

The interval between calls to the Lua user defined maintenance() function in seconds. See Maintenance callback

recursor.lua_start_stop_script

Added in version 5.2.0.

  • String

  • Default: (empty)

  • No equivalent old-style setting

Load this Lua script on startup and shutdown and run the Lua function on_recursor_start on startup and the Lua function on_recursor_stop on a nice shutdown (using rec_control quit-nicely of the Recursor process.

recursor.max_chain_length

Added in version 5.1.0.

The maximum number of queries that can be attached to an outgoing request chain. Attaching requests to a chain saves on outgoing queries, but the processing of a chain when the reply to the outgoing query comes in might result in a large outgoing traffic spike. Reducing the maximum chain length mitigates this. If this value is zero, no maximum is enforced, though the maximum number of mthreads (recursor.max_mthreads) also limits the chain length.

recursor.max_cnames_followed

Added in version 5.1.0.

Maximum length of a CNAME chain. If a CNAME chain exceeds this length, a ServFail answer will be returned. Previously, this limit was fixed at 10.

recursor.max_generate_steps

Added in version 4.3.0.

Maximum number of steps for a ‘$GENERATE’ directive when parsing a zone file. This is a protection measure to prevent consuming a lot of CPU and memory when untrusted zones are loaded. Default to 0 which means unlimited.

recursor.max_include_depth

Added in version 4.6.0.

Maximum number of nested $INCLUDE directives while processing a zone file. Zero mean no $INCLUDE directives will be accepted.

recursor.max_mthreads

Maximum number of simultaneous MTasker threads, per worker thread.

recursor.max_recursion_depth

Changed in version 4.1.0: Before 4.1.0, this settings was unlimited.

Changed in version 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.

Total maximum number of internal recursion calls the server may use to answer a single query. 0 means unlimited. The value of recursor.stack_size should be increased together with this one to prevent the stack from overflowing. If recursor.qname_minimization is enabled, the fallback code in case of a failing resolve is allowed an additional max-recursion-depth/2.

recursor.max_total_msec

Total maximum number of milliseconds of wallclock time the server may use to answer a single query. 0 means unlimited.

recursor.minimum_ttl_override

Changed in version 4.5.0: Old versions used default 0.

  • Integer

  • Default: 1

  • Old style setting: minimum-ttl-override

  • Runtime modifiable using rec_control set-minimum-ttl

This setting artificially raises all TTLs to be at least this long. Setting this to a value greater than 1 technically is an RFC violation, but might improve performance a lot. Using a value of 0 impacts performance of TTL 0 records greatly, since it forces the recursor to contact authoritative servers each time a client requests them.

recursor.nothing_below_nxdomain

Added in version 4.3.0.

The type of RFC 8020 handling using cached NXDOMAIN responses. This RFC specifies that NXDOMAIN means that the DNS tree under the denied name MUST be empty. 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.

For instance, when foo.example.net is negatively cached, any query matching *.foo.example.net will be answered with NXDOMAIN directly without consulting authoritative servers.

no

No RFC 8020 processing is done.

dnssec

RFC 8020 processing is only done using cached NXDOMAIN records that are DNSSEC validated.

yes

RFC 8020 processing is done using any non-Bogus NXDOMAIN record available in the cache.

recursor.public_suffix_list_file

Added in version 4.2.0.

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.

recursor.qname_max_minimize_count

Added in version 5.0.0.

Max minimize count parameter, described in RFC 9156. This is the maximum number of iterations of the Query Name Minimization Algorithm.

recursor.qname_minimization

Added in version 4.3.0.

Enable Query Name Minimization. This implements a relaxed form of Query Name Mimimization as described in RFC 9156.

recursor.qname_minimize_one_label

Added in version 5.0.0.

Minimize one label parameter, described in RFC 9156. The value for the number of iterations of the Query Name Minimization Algorithm that should only have one label appended. This value has precedence over recursor.qname_max_minimize_count.

recursor.root_nx_trust

Changed in version 4.0.0: Default is yes now, was no before 4.0.0

If set, an NXDOMAIN from the root-servers will serve as a blanket NXDOMAIN for the entire TLD the query belonged to. The effect of this is far fewer queries to the root-servers.

recursor.rpzs

Added in version 5.1.0.

  • Sequence of RPZ

  • Default: []

  • Equivalent Lua config in Response Policy Zones (RPZ)

  • Runtime modifiable using rec_control reload-lua-config, since 5.2.0: reload-yaml

Sequence of RPZ entries.

recursor.save_parent_ns_set

Added in version 4.7.0.

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. The saved parent NS set is tried if resolution using the child NS set fails.

recursor.security_poll_suffix

Domain name from which to query security update notifications. Setting this to an empty string disables secpoll.

recursor.serve_rfc1918

  • Boolean

  • Default: true

  • Old style setting: serve-rfc1918

  • Runtime modifiable using rec_control reload-zones

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. Individual parts of these zones can still be loaded or forwarded.

recursor.serve_rfc6303

Added in version 5.1.3.

Added in version 5.2.0.

  • Boolean

  • Default: true

  • Old style setting: serve-rfc6303

  • Runtime modifiable using rec_control reload-zones

This makes the server authoritatively aware of the zones in RFC 6303 not covered by RFC 1918. Individual parts of these zones can still be loaded or forwarded. recursor.serve_rfc1918 must be enabled for this option to take effect.

recursor.server_id

  • String

  • Default: *runtime determined*

  • Old style setting: server-id

The reply given by The PowerDNS recursor to a query for ‘id.server’ with its hostname, useful for in clusters. When a query contains the NSID EDNS0 Option, this value is returned in the response as the NSID value.

This setting can be used to override the answer given to these queries. Set to ‘disabled’ to disable NSID and ‘id.server’ answers.

Query example (where 192.0.2.14 is your server):

dig @192.0.2.14 CHAOS TXT id.server.
dig @192.0.2.14 example.com IN A +nsid

recursor.setgid

  • String

  • Default: (empty)

  • Old style setting: setgid

PowerDNS can change its user and group id after binding to its socket. Can be used for better security.

recursor.setuid

  • String

  • Default: (empty)

  • Old style setting: setuid

PowerDNS can change its user and group id after binding to its socket. Can be used for better security.

recursor.socket_dir

  • String

  • Default: (empty)

  • Old style setting: socket-dir

Where to store the control socket and pidfile. The default depends on LOCALSTATEDIR or the --with-socketdir setting when building (usually /var/run or /run).

When using recursor.chroot the default becomes /. The default value is overruled by the RUNTIME_DIRECTORY environment variable when that variable has a value (e.g. under systemd).

recursor.socket_group

Group and mode of the controlsocket. Owner and group can be specified by name, mode is in octal.

recursor.socket_mode

  • String

  • Default: (empty)

  • Old style setting: socket-mode

Mode of the controlsocket. Owner and group can be specified by name, mode is in octal.

recursor.socket_owner

Owner of the controlsocket. Owner and group can be specified by name, mode is in octal.

recursor.sortlists

Added in version 5.1.0.

Sequence of sort lists.

recursor.spoof_nearmiss_max

Changed in version 4.5.0: Older versions used 20 as the default value.

If set to non-zero, PowerDNS will assume it is being subjected to a spoofing attack after seeing this many answers with the wrong id.

recursor.stack_cache_size

Added in version 4.9.0.

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. 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.

recursor.stack_size

  • Integer

  • Default: 200000

  • Old style setting: stack-size

Size in bytes of the stack of each mthread.

recursor.stats_api_disabled_list

Added in version 4.5.0.

  • Sequence of strings

  • Default: cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*

  • Old style setting: stats-api-disabled-list

A sequence of statistic names, that are disabled when retrieving the complete list of statistics via the API for performance reasons. These statistics can still be retrieved individually by specifically asking for it.

recursor.stats_carbon_disabled_list

Added in version 4.5.0.

  • Sequence of strings

  • Default: cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*, cumul-answers-*, cumul-auth4answers-*, cumul-auth6answers-*

  • Old style setting: stats-carbon-disabled-list

A sequence of statistic names, that are prevented from being exported via carbon for performance reasons.

recursor.stats_rec_control_disabled_list

Added in version 4.5.0.

  • Sequence of strings

  • Default: cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*, cumul-answers-*, cumul-auth4answers-*, cumul-auth6answers-*

  • Old style setting: stats-rec-control-disabled-list

A sequence of statistic names, that are disabled when retrieving the complete list of statistics via rec_control get-all, for performance reasons. These statistics can still be retrieved individually.

recursor.stats_ringbuffer_entries

Number of entries in the remotes ringbuffer, which keeps statistics on who is querying your server. Can be read out using rec_control top-remotes.

recursor.stats_snmp_disabled_list

Added in version 4.5.0.

  • Sequence of strings

  • Default: cache-bytes, packetcache-bytes, special-memory-usage, ecs-v4-response-bits-*, ecs-v6-response-bits-*

  • Old style setting: stats-snmp-disabled-list

A sequence of statistic names, that are prevented from being exported via SNMP, for performance reasons.

recursor.system_resolver_interval

Added in version 5.1.0.

Sets the check interval (in seconds) of the system resolver feature. All names known by the system resolver subsystem are periodically checked for changing values.

If the TTL of a name has expired, it is checked by re-resolving it. if a change is detected, the recursor performs an equivalent of rec_control reload-zones.

This settings sets the interval between the checks. If set to zero (the default), the value recursor.system_resolver_ttl is used.

recursor.system_resolver_self_resolve_check

Added in version 5.1.0.

Warn on potential self-resolve. If this check draws the wrong conclusion, you can disable it.

recursor.system_resolver_ttl

Added in version 5.1.0.

Sets TTL in seconds of the system resolver feature. If not equal to zero names can be used for forwarding targets. The names will be resolved by the system resolver configured in the OS.

The TTL is used as a time to live to see if the names used in forwarding resolve to a different address than before. If the TTL is expired, a re-resolve will be done by the next iteration of the check function; if a change is detected, the recursor performs an equivalent of rec_control reload-zones.

Make sure the recursor itself is not used by the system resolver! Default is 0 (not enabled). A suggested value is 60.

recursor.tcp_threads

Added in version 5.0.0.

Spawn this number of TCP processing threads on startup.

recursor.threads

  • Integer

  • Default: 2

  • Old style setting: threads

Spawn this number of threads on startup.

recursor.version_string

  • String

  • Default: *runtime determined*

  • Old style setting: version-string

By default, PowerDNS replies to the ‘version.bind’ query with its version number. Security conscious users may wish to override the reply PowerDNS issues.

recursor.write_pid

  • Boolean

  • Default: true

  • Old style setting: write-pid

If a PID file should be written to recursor.socket_dir

snmp.agent

Added in version 4.1.0.

  • Boolean

  • Default: false

  • Old style setting: snmp-agent

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.

snmp.daemon_socket

Added in version 4.5.0.

If not empty and snmp-agent is set to true, indicates how PowerDNS should contact the SNMP daemon to register as an SNMP agent.

webservice.address

IP address for the webserver to listen on. This field is ignored if webservice.listen is set.

webservice.allow_from

Changed in version 4.1.0: Default is now 127.0.0.1,::1, was 0.0.0.0/0,::/0 before.

  • Sequence of Subnet (IP addresses or subnets, negation supported)

  • Default: [127.0.0.1, '::1']

  • Old style setting: webserver-allow-from

These IPs and subnets are allowed to access the webserver. Note that specifying an IP address without a netmask uses an implicit netmask of /32 or /128.

webservice.api_dir

Added in version 4.0.0.

Directory where the REST API stores its configuration and zones. For configuration updates to work, recursor.include_dir should have the same value when using old-style settings. When using YAML settings recursor.include_dir and webservice.api_dir must have a different value.

webservice.api_key

Added in version 4.0.0.

Changed in version 4.6.0: This setting now accepts a hashed and salted version.

  • String

  • Default: (empty)

  • Old style setting: api-key

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.

webservice.hash_plaintext_credentials

Added in version 4.6.0.

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. Note that this option only applies to credentials stored in the configuration as plaintext, but hashed credentials are supported without enabling this option.

webservice.listen

Added in version 5.3.0.

IP addresses and associated attributes for the webserver to listen on. If this setting has a non-default value, webservice.address and webservice.port will be ignored. Note multiple listen addresses can be configured and https is supported as well, in contrast to earlier (pre 5.3.0) versions.

webservice.loglevel

Added in version 4.2.0.

One of none, normal, detailed. The amount of logging the webserver must do. none means no useful webserver information will be logged. When set to normal, the webserver will log a line per request:

Feb 03 14:54:00 msg="Request" subsystem="webserver" level="0" prio="Notice" tid="0" ts="1738590840.208" HTTPVersion="HTTP/1.1" method="GET" remote="[::1]:49880" respsize="5418" status="200" uniqueid="a31a280d-29de-4db8-828f-edc862eb8653" urlpath="/"

When set to detailed, all available information about the request and response is logged.

Note

The webserver logs these line on the NOTICE level. The logging.loglevel setting must be 5 or higher for these lines to end up in the log.

webservice.password

Changed in version 4.6.0: This setting now accepts a hashed and salted version.

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.

webservice.port

TCP port where the webserver should listen on. This field is ignored if webservice.listen is set.

webservice.webserver

  • Boolean

  • Default: false

  • Old style setting: webserver

Start the webserver (for REST API).