and wonder 'why is the Recursor using a bufsize of 512? Did we not decide on a Flag Day, all together, that we would use 1232?'
The EDNS buffer size in a DNS packet, generated by side A, tells the recipient of that packet (side B) the maximum packet size that side A will accept from side B.
-So, when the Recursor talks to an Authoritative, the Recursor reports the buffer size the Authoritative is allowed to use to it - usually 1232 (:ref:`setting-edns-outgoing-bufsize`).
+So, when the Recursor talks to an Authoritative, the Recursor reports the buffer size the Authoritative is allowed to use to it - usually 1232 (:ref:`setting-yaml-outgoing.edns_bufsize`).
But the example above is the Recursor responding to a client, and it is telling the client 'from you, I accept packets of up to 512 bytes'.
Or, to say it differently, the Recursor is telling the client that *questions* must fit in 512 bytes.
This is fine for the Recursor - unlike an Authoritative, that might need to handle big UPDATE requests, the Recursor really only answers simple questions from clients, and those always comfortably fit in 512 bytes, because the maximum length of a DNS name is 256 bytes.
-Similarly, the maximum size of a response from the Recursor to a client is governed by the buffer size sent by the client (in ``dig``, you can see that number by doing ``dig +qr``), and the :ref:`setting-udp-truncation-threshold` setting in the Recursor configuration.
+Similarly, the maximum size of a response from the Recursor to a client is governed by the buffer size sent by the client (in ``dig``, you can see that number by doing ``dig +qr``), and the :ref:`setting-yaml-incoming.udp_truncation_threshold` setting in the Recursor configuration.
To see the buffer size the Recursor is sending to authoritatives, you can ask the question below, which gets sent to an authoritative server reporting in a TXT answer record what it saw in the query::
On startup, the :program:`Recursor` uses root hints to resolve the names and addresses of the root name servers and puts the record sets found into the record cache.
This is needed to be able to resolve names, as the recursive algorithm starts at the root (using cached data) and then tries to resolve delegations until it finds the name servers that are authoritative for the domain in question.
-If the :ref:`setting-hint-file` is not set, :program:`Recursor` will use a compiled-in table as root hints.
+If the :ref:`setting-yaml-recursor.hint_file` is not set, :program:`Recursor` will use a compiled-in table as root hints.
-Periodically, based on the :ref:`setting-max-cache-ttl`, the :program:`Recursor` will refetch the root data using data in its cache by doing a `. NS` query.
+Periodically, based on the :ref:`setting-yaml-recordcache.max_ttl`, the :program:`Recursor` will refetch the root data using data in its cache by doing a `. NS` query.
If that does not succeed, it will fall back to using the root hints to fill the cache with root data.
-Prior to version 4.7.0, the period for re-fetching root data was :ref:`setting-max-cache-ttl` divided by 12, with a minimum of 10 seconds.
-Starting with version 4.7.0, the period is adaptive, starting at 80% of :ref:`setting-max-cache-ttl`, reducing the interval on failure.
+Prior to version 4.7.0, the period for re-fetching root data was :ref:`setting-yaml-recordcache.max_ttl` divided by 12, with a minimum of 10 seconds.
+Starting with version 4.7.0, the period is adaptive, starting at 80% of :ref:`setting-yaml-recordcache.max_ttl`, reducing the interval on failure.
The root hints and resolved root data can differ if the root hints are outdated.
As long as at least one root server mentioned in the root hints can be contacted, the periodic refresh will produce the desired record sets corresponding to the current up-to-date root server data.
-Starting with version 4.6.2, if :ref:`setting-hint-file` is set to ``no``, the :program:`Recursor` will not prime the cache with root data obtained from hints, but will still do the periodic refresh.
+Starting with version 4.6.2, if :ref:`setting-yaml-recursor.hint_file` is set to ``no``, the :program:`Recursor` will not prime the cache with root data obtained from hints, but will still do the periodic refresh.
A (recursive) forward configuration is needed to make the periodic refresh work.
-Starting with version 4.9, setting :ref:`setting-hint-file` to ``no-refresh`` disables both the initial reading of the hints and the periodic refresh of cached root data.
+Starting with version 4.9, setting :ref:`setting-yaml-recursor.hint_file` to ``no-refresh`` disables both the initial reading of the hints and the periodic refresh of cached root data.
This prevents :program:`Recursor` from resolving names by itself, so it is only useful in cases where all queries are forwarded.
With versions older than 4.8, there is another detail: after refreshing the root records, the :program:`Recursor` will resolve the ``NS`` records for the top level domain of the root servers.
For example, in the default setup the root name servers are called ``[a-m].root-servers.net``, so the :program:`Recursor` will resolve the name servers of the ``.net`` domain.
This is needed to correctly determine zone cuts to be able to decide if the ``.root-servers.net`` domain is DNSSEC protected. Newer versions solve this by querying the needed information top-down.
-Starting with version 5.0.0, enabling :ref:`setting-allow-no-rd` allows for queries without the recursion desired bit to be answered from cache.
-Older versions of the ``dig`` program provided by ISC do not set the RD bit on the initial ``+trace`` query causing it to sometimes fail to perform a ``+trace`` when asking a freshly restarted :program:`Recursor` despite the :ref:`setting-allow-no-rd` option being set.
+Starting with version 5.0.0, enabling :ref:`setting-yaml-incoming.allow_no_rd` allows for queries without the recursion desired bit to be answered from cache.
+Older versions of the ``dig`` program provided by ISC do not set the RD bit on the initial ``+trace`` query causing it to sometimes fail to perform a ``+trace`` when asking a freshly restarted :program:`Recursor` despite the :ref:`setting-yaml-incoming.allow_no_rd` option being set.
This is because there is a short while after restarting that the cache has no authoritative data on the root, so it will answer with an NODATA (NOERROR and no answer records) in that period for RD=0 queries asking for the root name servers.
For ``dig`` this has been fixed in `BIND 9.15.1 <https://gitlab.isc.org/isc-projects/bind9/-/issues/1028>`_ by setting the RD bit.
using the child specified NS set.
As experience shows, this configuration error is encountered in the
wild often enough to warrant this workaround.
-See :ref:`setting-save-parent-ns-set`.
+See :ref:`setting-yaml-recursor.save_parent_ns_set`.
.. _serve-stale:
This is a mechanism that allows records in the record cache that are expired
but that cannot be refreshed (due to network or authoritative server issues) to be served anyway.
-The :ref:`setting-serve-stale-extensions` determines how many times the records lifetime can be extended.
+The :ref:`setting-yaml-recordcache.serve_stale_extensions` determines how many times the records lifetime can be extended.
Each extension of the lifetime of a record lasts 30s.
A value of 1440 means the maximum extra life time is 30 * 1440 seconds which is 12 hours.
If the original TTL of a record was less than 30s, the original TTLs will be used as extension period.
If that task succeeds, the record will not be served stale anymore, as an up-to-date value is now available.
-If :ref:`setting-serve-stale-extensions` is not zero expired records will be kept in the record cache until the number of records becomes too large.
+If :ref:`setting-yaml-recordcache.serve_stale_extensions` is not zero expired records will be kept in the record cache until the number of records becomes too large.
Cache eviction will then be done on a least-recently-used basis.
When dumping the cache using ``rec_control dump-cache`` the ``ss`` value shows the serve stale extension count.
=============================
This page describes the common entries of the Structured Logging component.
-Currently :ref:`setting-structured-logging-backend` can have these values:
+Currently :ref:`setting-yaml-logging.structured_logging_backend` can have these values:
- The ``default`` text based backend
- The ``systemd-journal`` backend
-----------------------
The default backend uses a text representation of the key-value pairs.
A line is constructed by appending all key-value pairs as ``key="value"``, separated by spaces.
-The output is written by passing the resulting text line to the standard error stream and also to ``syslog`` if :ref:`setting-disable-syslog` is false.
-Depending on the value of :ref:`setting-log-timestamp` a timestamp is prepended to the log line.
+The output is written by passing the resulting text line to the standard error stream and also to ``syslog`` if :ref:`setting-yaml-logging.disable_syslog` is false.
+Depending on the value of :ref:`setting-yaml-logging.timestamp` a timestamp is prepended to the log line.
An example line (including prepended timestamp) looks like this::
+-------------+------------------+--------------------------------------+---------------------------------------+
| ``level`` |``number`` |``"0"`` |The detail level of the log entry, do |
| | | |not confuse with |
-| | | |:ref:`setting-loglevel`. Not actively |
-| | | |used currently. |
+| | | |:ref:`setting-yaml-logging.loglevel`. |
+| | | |Not actively used currently. |
+-------------+------------------+--------------------------------------+---------------------------------------+
| ``prio`` |``enum`` |``"Notice"`` |One of ``Alert=1``, ``Critical=2``, |
| | | |``Error=3``, ``Warning=4``, |
| | | |``Notice=5``, ``Info=6``, |
| | | |``Debug=7``. A log entry will only |
| | | |produced if its ``prio`` is equal or |
-| | | |lower than :ref:`setting-loglevel`. |
+| | | |lower than |
+| | | |:ref:`setting-yaml-logging.loglevel`. |
+-------------+------------------+--------------------------------------+---------------------------------------+
| ``tid`` |``number`` |``"2"`` |The Posix worker thread id that |
| | | |produced the log entry. If not produced|
- The Recursor will by default no longer query private-space
nameservers. This closes a slight security risk and simultaneously
improves performance and stability. For more information, see
- **dont-query** in :ref:`dont-query`. Implemented in `commit
+ **dont-query** in :ref:`setting-dont-query`. Implemented in `commit
923 <http://wiki.powerdns.com/projects/trac/changeset/923>`__.
- Applied fix for `ticket
110 <https://github.com/PowerDNS/pdns/issues/110>`__ ('PowerDNS
fix, configure the **local-address** setting with all addresses you want
to listen on. Additionally, by default service is restricted to RFC 1918
private IP addresses. Use **allow-from** to selectively open up the
-recursor for your own network. See :ref:`allow-from` for details.
+recursor for your own network. See :ref:`setting-allow-from` for details.
Important new features of the PowerDNS recursor 3.0
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
We do this by retrieving the A records for ``www.example.com``, and translating them to AAAA records.
Elsewhere, a NAT64 device listens on these IPv6 addresses, and extracts the IPv4 address from each packet, and proxies it on.
-As of 4.4.0, an efficient implementation is built the recursor and can be enabled via the using the :ref:`dns64-prefix setting <setting-dns64-prefix>`.
+As of 4.4.0, an efficient implementation is built the recursor and can be enabled via the using the :ref:`dns64-prefix setting <setting-yaml-recursor.dns64_prefix>`.
Native DNS64 support
--------------------
To consider native DNS64 processing the following conditions must be met:
-- The :ref:`setting-dns64-prefix` is defined.
+- The :ref:`setting-yaml-recursor.dns64_prefix` is defined.
- A ``nodata`` or ``nxdomain`` Lua hook did not return ``true``.
- The original query type was ``AAAA``.
- The result code of the ``AAAA`` query was not ``NXDomain``.
:language: lua
Where fe80::21b:77ff:0:0 is your "Pref64" translation prefix and the "ip6.arpa" string is the reversed form of this Pref64 address.
-Now ensure your script gets loaded by specifying it with :ref:`lua-dns-script=dns64.lua <setting-lua-dns-script>`.
+Now ensure your script gets loaded by specifying it with :ref:`setting-yaml-recursor.lua_dns_script`.
On our wiki, a user has kindly supplied `an example script with support for multiple prefixes <https://github.com/PowerDNS/pdns/wiki/DNS64-with-multiple-prefixes>`_.
DNSSEC settings
---------------
-The PowerDNS Recursor has 5 different levels of DNSSEC processing, which can be set with the :ref:`setting-dnssec` setting in the ``recursor.conf``.
+The PowerDNS Recursor has 5 different levels of DNSSEC processing, which can be set with the :ref:`setting-yaml-dnssec.validation` setting in the Recursor configuration file.
In order from least to most processing, these are:
``off``
^^^^^^^^^^^
The default mode since PowerDNS Recursor 4.5.0.
-When :ref:`setting-dnssec` is set to ``process`` the behaviour is similar to `process-no-validate`_.
+When :ref:`setting-yaml-dnssec.validation` is set to ``process`` the behaviour is similar to `process-no-validate`_.
However, the recursor will try to validate the data if at least one of the DO or AD bits is set in the query;
in that case, it will set the AD-bit in the response when the data is validated successfully, or send SERVFAIL when the validation comes up bogus.
However, all trust anchors are configurable.
Current trust anchors can be queried from the recursor by sending a query for "trustanchor.server CH TXT".
-This query will (if :ref:`setting-allow-trust-anchor-query` is enabled) return a TXT record per trust-anchor in the format ``"DOMAIN KEYTAG [KEYTAG]..."``.
+This query will (if :ref:`setting-yaml-recursor.allow_trust_anchor_query` is enabled) return a TXT record per trust-anchor in the format ``"DOMAIN KEYTAG [KEYTAG]..."``.
Trust Anchors
^^^^^^^^^^^^^
**Note**: it has no support for :rfc:`5011` key rollover and does not persist a changed root trust anchor to disk.
-Configuring DNSSEC key material must be done in the :ref:`setting-lua-config-file`, using :func:`addTA`.
-This function takes 2 arguments: the node in the DNS-tree and the data of the corresponding DS record.
+Configuring DNSSEC key material can be done in the :ref:`setting-yaml-dnssec.trustanchors`.
+A trust anchor entry defines the node in the DNS-tree and the data of the corresponding DS records.
-To e.g. add a trust anchor for the root and example.com, use the following config in the Lua file:
+To e.g. add a trust anchor for the root and example.com, use the following config:
-.. code:: Lua
+.. code:: yaml
- addTA('.', "63149 13 1 a59da3f5c1b97fcd5fa2b3b2b0ac91d38a60d33a") -- This is not an ICANN root
- addTA('example.com', "44030 8 2 D4C3D5552B8679FAEEBC317E5F048B614B2E5F607DC57F1553182D49 AB2179F7")
+ dnssec:
+ trustanchors:
+ - name: '.'
+ dsrecords:
+ - '63149 13 1 a59da3f5c1b97fcd5fa2b3b2b0ac91d38a60d33a' # This is not an ICANN root
+ - name: example.com
+ dsrecords:
+ - '44030 8 2 D4C3D5552B8679FAEEBC317E5F048B614B2E5F607DC57F1553182D49 AB2179F7'
-For PowerDNS Recursor 4.1.x and below, use the :func:`addDS` function instead.
-
-Now (re)start the recursor to load these trust anchors.
+Now (re)start the recursor to load these trust anchors, or use ``rec_control reload-yaml``.
Reading trust anchors from files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. versionadded:: 4.2.0
-
-It is also possible to read the Trust Anchors from a BIND-style zonefile using the :func:`readTrustAnchorsFromFile` in the :ref:`setting-lua-config-file`.
+It is also possible to read the Trust Anchors from a BIND-style zonefile using the :ref:`setting-yaml-dnssec.trustanchorfile`.
Only the DS and DNSKEY records from this file are read.
This file is (by default) re-read every 24 hours for updates.
Debian and its derivatives ship the ``dns-root-data`` package that contains the DNSSEC root trust anchors in ``/usr/share/dns/root.key``.
-To only use the distribution-provided Trust Anchors, add the following to the :ref:`setting-lua-config-file`:
-
-.. sourcecode:: lua
-
- clearTA() -- Remove built-in trust-anchors
- readTrustAnchorsFromFile("/usr/share/dns/root.key") -- Use these keys
+Set :ref:`setting-yaml-dnssec.trustanchorfile` to this path to use these trust anchors.
+Any root trust anchor in this file will override the built-in root trust anchors.
.. note::
- When using :func:`readTrustAnchorsFromFile`, any runtime changes to Trust Anchors (see below) will be overwritten when the file is refreshed.
- To prevent this, set the ``interval`` parameter to ``0``.
+ When using a trust anchor file, any runtime changes to Trust Anchors (see below) will be overwritten when the file is refreshed.
+ To prevent this, set the :ref:`setting-yaml-dnssec.trustanchorfile_interval` parameter to ``0``.
This will **disable** automatic reloading of the file.
Runtime Configuration of Trust Anchors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To change or add trust anchors at runtime, use the :doc:`manpages/rec_control.1` tool.
These runtime settings are not saved to disk.
-To make them permanent, they should be added to the :ref:`setting-lua-config-file` as described above.
+To make them permanent, they should be added to the settings as described above.
Adding a trust anchor is done with the ``add-ta`` command:
Note that it is good practice to verify that this is indeed the case and not because of malicious actions.
Current negative trust anchors can be queried from the recursor by sending a query for "negativetrustanchor.server CH TXT".
-This query will (if :ref:`setting-allow-trust-anchor-query` is enabled) return a TXT record per negative trust-anchor in the format ``"DOMAIN [REASON]"``.
+This query will (if :ref:`setting-yaml-recursor.allow_trust_anchor_query` is enabled) return a TXT record per negative trust-anchor in the format ``"DOMAIN [REASON]"``.
-To configure a negative trust anchor, use the ``addNTA()`` function in the :ref:`setting-lua-config-file` and restart the recursor.
-This function requires the name of the zone and an optional reason:
+To configure a negative trust anchor, use the :ref:`setting-yaml-dnssec.negative_trustanchors` and restart the recursor.
+The NTA entries require the name of the zone and an optional reason:
-.. code-block:: Lua
+.. code-block:: yaml
- addNTA('example.', "Someone messed up the delegation")
- addNTA('powerdns.com') -- No reason given
+ dnssec:
+ negative_trustanchors:
+ - name: example.com
+ reason: an example
Runtime Configuration of Negative Trust Anchors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :doc:`manpages/rec_control.1` command can be used to manage the negative trust anchors of a running instance.
-These runtime settings are lost when restarting the recursor, more permanent NTAs should be added to the :ref:`setting-lua-config-file` with ``addNTA()``.
+These runtime settings are lost when restarting the recursor, more permanent NTAs should be added to the :ref:`setting-yaml-recursor.lua_config_file` with ``addNTA()`` or to :ref:`setting-yaml-dnssec.negative_trustanchors`.
Adding a negative trust anchor is done with the ``add-nta`` command (that optionally accepts a reason):
Configuring :program:`PowerDNS Recursor`
----------------------------------------
-The configuration file is called ``recursor.conf`` and is located in the ``SYSCONFDIR`` defined at compile-time.
+The configuration file is called ``recursor.conf`` or ``recursor.yml`` and is located in the ``SYSCONFDIR`` defined at compile-time.
This is usually ``/etc/powerdns``, ``/etc/pdns``, ``/etc/pdns-recursor``, ``/usr/local/etc`` or similar.
+Since version 5.0 :program:`Recursor` also supports YAML style settings and since version 5.2 the old style settings format is deprecated.
-Run ``pdns_recursor --config=default | grep config-dir`` to find this location on your installation.
-Many packages provide a default configuration file that sets :ref:`setting-include-dir`.
-Consider putting local ``.conf`` files into this directory, to make it clear which settings were locally modified.
+Run ``pdns_recursor --config=default | grep config_dir`` to find this location on your installation.
+Many packages provide a default configuration file that sets :ref:`setting-yaml-recursor.include_dir`.
+Consider putting local configuration files into this directory, to make it clear which settings were locally modified.
-:program:`Recursor` listens on the local loopback interface by default, this can be changed with the :ref:`setting-local-address` setting.
+:program:`Recursor` listens on the local loopback interface by default, this can be changed with the :ref:`setting-yaml-incoming.listen` setting.
Now access will need to be granted to the :program:`Recursor`.
-The :ref:`setting-allow-from` setting lists the subnets that can communicate with :program:`Recursor`.
+The :ref:`setting-yaml-incoming.allow_from` setting lists the subnets that can communicate with :program:`Recursor`.
An example configuration is shown below.
Change this to match the local infrastructure.
-.. code-block:: none
+.. code-block:: yaml
- local-address=192.0.2.25, 2001:DB8::1:25
- allow-from=192.0.2.0/24, 2001:DB8::1:/64
+ incoming:
+ listen: [192.0.2.25, '2001:DB8::1:25']
+ allow_from: [192.0.2.0/24, '2001:DB8::1:/64']
After a restart of :program:`Recursor`, it will answer queries on 192.0.2.25 and 2001:DB8::1:25, but only for queries with a source address in the 192.0.2.0/24 and 2001:DB8::1:/64 networks.
:program:`Recursor` is now ready to be used.
-For more options that can be set in ``recursor.conf`` see the :doc:`PowerDNS Recursor Settings<settings>`.
+For more options that can be set in the recursor configuration see the :doc:`PowerDNS Recursor Settings<yamlsettings>`.
Guidance on interaction with :program:`Recursor` is documented in :doc:`Operating PowerDNS Recursor<running>`.
If dynamic answer generation is needed or policies need to be applied to queries, the :doc:`Scripting PowerDNS Recursor <lua-scripting/index>` will come in handy.
Change a single setting
.. note::
- Only :ref:`setting-allow-from` and :ref:`setting-allow-notify-from` can be set.
+ Only :ref:`setting-yaml-incoming.allow_from` and :ref:`setting-yaml-incoming.allow_notify_from` can be set.
.. note::
For configuration changes to work :ref:`setting-include-dir` and :ref:`setting-api-config-dir` should have the same value for old-style settings.
Webserver
---------
-To launch the internal webserver, add a :ref:`setting-webserver` to the configuration file.
+To launch the internal webserver, set :ref:`setting-yaml-webservice.webserver` to ``true`` the configuration file.
This will instruct PowerDNS to start a webserver on localhost at port 8081, without password protection.
-By default the webserver listens on localhost, meaning only local users (on the same host) will be able to access the webserver. Since the default ACL before 4.1.0 allows access from everywhere if :ref:`setting-webserver-address` is set to a different value, we strongly advise the use of a password protection.
+By default the webserver listens on localhost, meaning only local users (on the same host) will be able to access the webserver. Since the default ACL before 4.1.0 allows access from everywhere if :ref:`setting-yaml-webservice.address` is set to a different value, we strongly advise the use of a password protection.
The webserver lists a lot of potentially sensitive information about the PowerDNS process, including frequent queries, frequently failing queries, lists of remote hosts sending queries, hosts sending corrupt queries etc.
The webserver does not allow remote management.
The following webserver related configuration items are available:
-* :ref:`setting-webserver`: If set to anything but 'no', a webserver is launched.
-* :ref:`setting-webserver-address`: Address to bind the webserver to. Defaults to 127.0.0.1, which implies that only the local computer is able to connect to the nameserver! To allow remote hosts to connect, change to 0.0.0.0 or the physical IP address of your nameserver.
-* :ref:`setting-webserver-password`: If set, viewers will have to enter this password in order to gain access to the statistics.
-* :ref:`setting-webserver-port`: Port to bind the webserver to.
-* :ref:`setting-webserver-allow-from`: Netmasks that are allowed to connect to the webserver
+* :ref:`setting-yaml-webservice.webserver`: If set to ``yes`` a webserver is launched.
+* :ref:`setting-yaml-webservice.address`: Address to bind the webserver to. Defaults to 127.0.0.1, which implies that only the local computer is able to connect to the nameserver! To allow remote hosts to connect, change to 0.0.0.0 or the physical IP address of your nameserver.
+* :ref:`setting-yaml-webservice.password`: If set, viewers will have to enter this password in order to gain access to the statistics.
+* :ref:`setting-yaml-webservice.port`: Port to bind the webserver to.
+* :ref:`setting-yaml-webservice.allow_from`: Netmasks that are allowed to connect to the webserver
Enabling the API
----------------
To enable the API, the webserver and the HTTP API need to be enabled.
-Add these lines to the ``recursor.conf``::
+Add these lines to the configuration file:
- webserver=yes
- webserver-port=8082
- api-key=changeme
+.. code-block:: yaml
+
+ webservice:
+ webserver: true
+ port: 8082
+ api_key: changeme
And restart ``pdns_recursor``, the following examples should start working::
.. http:get:: /metrics
- Get statistics from Recursor in `Prometheus <https://prometheus.io>`_ format. Uses :ref:`setting-webserver-password` and returned list can be controlled with :ref:`setting-stats-api-blacklist`
+ Get statistics from Recursor in `Prometheus <https://prometheus.io>`_ format. Uses :ref:`setting-yaml-webservice.password` and returned list can be controlled with :ref:`setting-yaml-recursor.stats_api_disabled_list`
**Example request**:
.. sourcecode:: bash
mx2.example.net. 86374 IN AAAA 2001:db8::2
The default is that the Recursor never adds additional records to an answer it sends to the client.
-The default behavior can be changed by using the :func:`addAllowedAdditionalQType` function in the :ref:`setting-lua-config-file`.
+The default behavior can be changed by using the :func:`addAllowedAdditionalQType` function in the :ref:`setting-yaml-recursor.lua_config_file`.
For each query type allowing additional record processing the Recursor has code to determine the target name to add.
The target qtypes to add are configurable as is the mode, specifying how to retrieve the records to add.
Advanced Configuration Using Lua
-================================================================================
+================================
-Since version 4.0.0, the PowerDNS Recursor supports additional configuration options that have to be loaded through :ref:`setting-lua-config-file`.
+:program:`PowerDNS Recursor` supports additional configuration options that can be loaded through :ref:`setting-yaml-recursor.lua_config_file`.
.. toctree::
=========================
Starting with version 4.7.0, the PowerDNS Recursor has the ability to map source IP addresses to alternative addresses, which is for example useful when some clients reach the recursor via a reverse-proxy.
The mapped address is used internally for ACL and similar checks.
-If the :ref:`setting-proxy-protocol-from` is also used, the substitution is done on the source address specified in the proxy protocol header.
+If the :ref:`setting-yaml-incoming.proxy_protocol_from` is also used, the substitution is done on the source address specified in the proxy protocol header.
Depending on context, the incoming address can be
``M equals S`` if no Table Based Proxy Mapping is used.
-``I`` determines if the Proxy Protocol is used (:ref:`setting-proxy-protocol-from`).
+``I`` determines if the Proxy Protocol is used (:ref:`setting-yaml-incoming.proxy_protocol_from`).
``S`` is passed to Lua functions and RPZ processing
-``M`` is used for incoming ACL checking (:ref:`setting-allow-from`) and to determine the ECS processing (:ref:`setting-ecs-add-for`).
+``M`` is used for incoming ACL checking (:ref:`setting-yaml-incoming.allow_from`) and to determine the ECS processing (:ref:`setting-yaml-ecs.add_for`).
An example use:
^^^^^^^^^^^^^^^^^
.. versionadded:: 4.5.0
-An extended error code (:rfc:`8914`) to set on RPZ hits. See :ref:`setting-extended-resolution-errors`.
+An extended error code (:rfc:`8914`) to set on RPZ hits. See :ref:`setting-yaml-recursor.extended_resolution_errors`.
extendedErrorExtra
^^^^^^^^^^^^^^^^^^
.. versionadded:: 4.5.0
-An extended error extra text (:rfc:`8914`) to set on RPZ hits. See :ref:`setting-extended-resolution-errors`.
+An extended error extra text (:rfc:`8914`) to set on RPZ hits. See :ref:`setting-yaml-recursor.extended_resolution_errors`.
includeSOA
^^^^^^^^^^
^^^^^^^
An integer describing the interval in seconds between checks for updates.
By default, the refresh interval mentioned in the RPZ's SOA record is used.
-Since version 5.1.0, if allowed by :ref:`setting-allow-notify-for` and :ref:`setting-allow-notify-from`, a ``notify`` for an RPZ zone will initiate a freshness check.
+Since version 5.1.0, if allowed by :ref:`setting-yaml-incoming.allow_notify_for` and :ref:`setting-yaml-incoming.allow_notify_from`, a ``notify`` for an RPZ zone will initiate a freshness check.
maxReceivedMBytes
^^^^^^^^^^^^^^^^^
localAddress
^^^^^^^^^^^^
The source IP address to use when transferring the RPZ.
-When unset, :ref:`setting-query-local-address` is used.
+When unset, :ref:`setting-yaml-outgoing.source_address` is used.
axfrTimeout
^^^^^^^^^^^
.. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-recursor.sortlists`.
-``addSortList()`` is used in the :ref:`setting-lua-config-file` and is intended to exactly mirror the semantics of the BIND sortlist option, but the syntax is slightly different.
+``addSortList()`` is used in the :ref:`setting-yaml-recursor.lua_config_file` and is intended to exactly mirror the semantics of the BIND sortlist option, but the syntax is slightly different.
As an example, the following BIND sortlist:
Validation consists of two parts: ``DNSSEC`` and ``ZONEMD``.
``ZONEMD`` is described in :rfc:`8976`.
-For the ``DNSSEC`` part, if the global :ref:`setting-dnssec` setting is not ``off`` or ``process-no-validate`` and the `DS` record from the parent zone or trust anchor indicates the zone is ``DNSSEC`` signed, the recursor will validate the ``DNSKEY`` records of the zone.
+For the ``DNSSEC`` part, if the global :ref:`setting-yaml-dnssec.validation` setting is not ``off`` or ``process-no-validate`` and the `DS` record from the parent zone or trust anchor indicates the zone is ``DNSSEC`` signed, the recursor will validate the ``DNSKEY`` records of the zone.
If a ``ZONEMD`` record is present, it will also validate the ``ZONEMD`` record.
If no ``ZONEMD`` is present, the ``NSEC`` or ``NSEC3`` denial of the ``ZONEMD`` record will be validated.
Note that this is not a full validation of the signatures of all records.
localAddress
~~~~~~~~~~~~
The source IP address to use when transferring using the ``axfr`` or ``url`` methods.
-For the ``axfr`` method :ref:`setting-query-local-address` is used by default.
+For the ``axfr`` method :ref:`setting-yaml-outgoing.source_address` is used by default.
The default used for ``url`` method is system dependent.
zonemd
Scripts can be reloaded or unloaded at runtime with no interruption in operations.
If a new script contains syntax errors, the old script remains in force.
-On the command line, or in the configuration file, the setting :ref:`setting-lua-dns-script` can be used to supply a full path to the Lua script.
+On the command line, or in the configuration file, the setting :ref:`setting-yaml-recursor.lua_dns_script` can be used to supply a full path to the Lua script.
At runtime, ``rec_control reload-lua-script`` can be used to either reload the script from its current location, or, when passed a new filename, load one from a new location.
A failure to parse the new script will leave the old script in working order.
.. versionadded:: 4.5.0
- Whether the response will get EDNS Padding. See :ref:`setting-edns-padding-from` and :ref:`setting-edns-padding-mode`.
+ Whether the response will get EDNS Padding. See :ref:`setting-yaml-incoming.edns_padding_from` and :ref:`setting-yaml-incoming.edns_padding_mode`.
.. attribute:: DNSQuestion.extendedErrorCode
.. versionadded:: 4.5.0
- The extended error code, if any. See :ref:`setting-extended-resolution-errors`.
+ The extended error code, if any. See :ref:`setting-yaml-recursor.extended_resolution_errors`.
.. attribute:: DNSQuestion.extendedErrorExtra
.. versionadded:: 4.5.0
- The extended error extra text, as a string, if any. See :ref:`setting-extended-resolution-errors`.
+ The extended error extra text, as a string, if any. See :ref:`setting-yaml-recursor.extended_resolution_errors`.
.. attribute:: DNSQuestion.qname
:param ComboAddress localip: The IP address the query was received on
:param DNSName qname: The domain name the query is for
:param int qtype: The query type of the query
- :param ednsoptions: A table whose keys are EDNS option codes and values are :class:`EDNSOptionView` objects. This table is empty unless the :ref:`setting-gettag-needs-edns-options` option is set.
+ :param ednsoptions: A table whose keys are EDNS option codes and values are :class:`EDNSOptionView` objects. This table is empty unless the :ref:`setting-yaml-incoming.gettag_needs_edns_options` option is set.
:param bool tcp: Added in 4.1.0, a boolean indicating whether the query was received over UDP (false) or TCP (true).
:param proxyprotocolvalues: Added in 4.4.0, a table of :class:`ProxyProtocolValue` objects representing the Type-Length Values received via the Proxy Protocol, if any.
-- Perform here your maintenance
end
-The interval can be configured through the :ref:`setting-lua-maintenance-interval` setting.
+The interval can be configured through the :ref:`setting-yaml-recursor.lua_maintenance_interval` setting.
Regular Statistics Log
----------------------
-Every half hour or so (configurable with :ref:`setting-statistics-interval`, the recursor outputs a line with statistics.
+Every half hour or so (configurable with :ref:`setting-yaml-logging.statistics_interval`, the recursor outputs a line with statistics.
To force the output of statistics, send the process a SIGUSR1. A line of statistics looks like this::
stats: 346362 questions, 7388 cache entries, 1773 negative entries, 18% cache hits
To benefit from our carbon/graphite support, either install Graphite, or use our own lightweight statistics daemon, Metronome, currently available on `GitHub <https://github.com/ahupowerdns/metronome/>`_.
-To enable sending metrics, set :ref:`setting-carbon-server`, possibly :ref:`setting-carbon-interval` and possibly :ref:`setting-carbon-ourname` in the configuration.
+To enable sending metrics, set :ref:`setting-yaml-carbon.server`, possibly :ref:`setting-yaml-carbon.interval` and possibly :ref:`setting-yaml-carbon.ourname` in the configuration.
.. warning::
If your hostname includes dots, they will be replaced by underscores so as not to confuse the namespace.
- If you include dots in :ref:`setting-carbon-ourname`, they will **not** be replaced by underscores.
+ If you include dots in :ref:`setting-yaml-carbon.ourname`, they will **not** be replaced by underscores.
As PowerDNS assumes you know what you are doing if you override your hostname.
Sending metrics over SNMP
-------------------------
-The recursor can export statistics over SNMP and send traps from :doc:`Lua <lua-scripting/index>`, provided support is compiled into the Recursor and :ref:`setting-snmp-agent` set.
+The recursor can export statistics over SNMP and send traps from :doc:`Lua <lua-scripting/index>`, provided support is compiled into the Recursor and :ref:`setting-yaml-snmp.agent` set.
For the details of all values that can be retrieved using SNMP, see the `SNMP MIB <https://github.com/PowerDNS/pdns/blob/master/pdns/recursordist/RECURSOR-MIB.txt>`_.
Therefore, a feature has been developed for the recursor which uses probabilistic data structures (specifically a Stable Bloom Filter (SBF): [http://webdocs.cs.ualberta.ca/~drafiei/papers/DupDet06Sigmod.pdf]). This recursor feature is named "Newly Observed Domain" or "NOD" for short.
-The use of a probabilistic data structure means that the memory and CPU usage for the NOD feature is minimal, however it does mean that there can be false positives (a domain flagged as new when it is not), and false negatives (a domain that is new is not detected). The size of the SBF data structure can be tuned to reduce the FP/FN rate, although it is created with a default size (67108864 cells) that should provide a reasonably low FP/FN rate. To configure a different size use the ``new-domain-db-size`` setting to specify a higher or lower cell count. Each cell consumes 1-bit of RAM (per recursor thread) and 1-byte of disk space.
+The use of a probabilistic data structure means that the memory and CPU usage for the NOD feature is minimal, however it does mean that there can be false positives (a domain flagged as new when it is not), and false negatives (a domain that is new is not detected). The size of the SBF data structure can be tuned to reduce the FP/FN rate, although it is created with a default size (67108864 cells) that should provide a reasonably low FP/FN rate. To configure a different size use the :ref:`setting-yaml-nod.db_size` setting to specify a higher or lower cell count. Each cell consumes 1-bit of RAM (per recursor thread) and 1-byte of disk space.
-NOD is disabled by default, and must be enabled through the use of the following setting in recursor.conf:
+NOD is disabled by default, and must be enabled through the use of the following setting in recursor configuration:
-``new-domain-tracking=yes``
+.. code-block:: yaml
-Once enabled the recursor will keep track of previously seen domains using the SBF data structure, which is periodically persisted to the directory specified in the ``new-domain-history-dir``, which defaults to /var/lib/pdns-recursor/nod.
+ nod:
+ tracking: true
-Administrators may wish to prevent certain domains or subdomains from ever triggering the NOD algorithm, in which case those domains must be added to the ``new-domain-ignore-list`` setting as a comma separated list. No domain (or subdomain of a domain) listed will be considered a newly observed domain. It is also possible to use ``new-domain-ignore-list-file`` to read a file with ignored domains, one domain per line.
+Once enabled the recursor will keep track of previously seen domains using the SBF data structure, which is periodically persisted to the directory specified in the :ref:`setting-yaml-nod.history_dir`, which defaults to /var/lib/pdns-recursor/nod.
+
+Administrators may wish to prevent certain domains or subdomains from ever triggering the NOD algorithm, in which case those domains must be added to the :ref:`setting-yaml-nod.ignore_list` setting. No domain (or subdomain of a domain) listed will be considered a newly observed domain. It is also possible to use :ref:`setting-yaml-nod.ignore_list_file` to read a file with ignored domains, one domain per line.
There are several ways to receive the information about newly observed domains:
Logging
+++++++
-The setting ``new-domain-log`` is enabled by default once the NOD feature is enabled, and will log the newly observed domain to the recursor logfile.
+The setting :ref:`setting-yaml-nod.log` is enabled by default once the NOD feature is enabled, and will log the newly observed domain to the recursor logfile.
DNS Lookup
++++++++++
-The setting ``new-domain-lookup=<base domain>`` will cause the recursor to issue a DNS A record lookup to ``<newly observed domain>.<base domain>``. This can be a suitable method to send NOD data to an offsite or remote partner, however care should be taken to ensure that data is not leaked inadvertently.
-To log NOD information to a dnstap stream, refer to :func:`dnstapNODFrameStreamServer`.
+The setting :ref:`setting-yaml-nod.lookup` will cause the recursor to issue a DNS A record lookup to ``<newly observed domain>.<base domain>``. This can be a suitable method to send NOD data to an offsite or remote partner, however care should be taken to ensure that data is not leaked inadvertently.
+To log NOD information to a dnstap stream, refer to :ref:`setting-yaml-logging.dnstap_nod_framestream_servers`.
Protobuf Logging
++++++++++++++++
-If both NOD and protobuf logging are enabled, then the ``newlyObservedDomain`` field of the protobuf message emitted by the recursor will be set to true. Additionally newly observed domains will be tagged in the protobuf stream using the tag ``pdns-nod`` by default. The setting ``new-domain-pb-tag=<tag>`` can be used to alter the tag.
+If both NOD and protobuf logging are enabled, then the ``newlyObservedDomain`` field of the protobuf message emitted by the recursor will be set to true. Additionally newly observed domains will be tagged in the protobuf stream using the tag ``pdns-nod`` by default. The setting :ref:`setting-yaml-nod.pb_tag` can be used to alter the tag.
.. _Unique Domain Response:
This is because well-behaved domains tend to return fairly stable results to DNS record lookups, and thus domains which don't exhibit this behaviour may be suspicious or may indicate a domain under attack.
-UDR is disabled by default - to enable it, set ``unique-response-tracking=yes`` in recursor.conf.
+UDR is disabled by default - to enable it, set :ref:`setting-yaml-nod.unique_response_tracking` in the recursor configuration.
-The data is persisted to /var/lib/pdns-recursor/udr by default, which can be changed with the setting ``unique-response-history-dir=<new directory>``.
+The data is persisted to /var/lib/pdns-recursor/udr by default, which can be changed with the setting :ref:`setting-yaml-nod.unique_response_history_dir`.
-The SBF (which is maintained separately per recursor thread) cell size defaults to 67108864, which can be changed using the setting ``unique-response-db-size``. The same caveats regarding FPs/FNs apply as for NOD.
+The SBF cell size defaults to 67108864, which can be changed using the setting :ref:`setting-yaml-nod.unique_response_db_size`. The same caveats regarding FPs/FNs apply as for NOD.
-Similarly to NOD, administrators may wish to prevent certain domains or subdomains from ever triggering the UDR algorithm, in which case those domains must be added to the ``udr-ignore-list`` setting as a comma separated list. No domain (or subdomain of a domain) listed will be considered a new unique domain response. It is also possible to use ``udr-ignore-list-file`` to read a file with ignored domains, one domain per line.
+Similarly to NOD, administrators may wish to prevent certain domains or subdomains from ever triggering the UDR algorithm, in which case those domains must be added to the :ref:`setting-yaml-nod.unique_response_ignore_list` setting. No domain (or subdomain of a domain) listed will be considered a new unique domain response. It is also possible to use :ref:`setting-yaml-nod.unique_response_ignore_list_file` to read a file with ignored domains, one domain per line.
Similarly to NOD, unique domain responses can be tracked using several mechanisms:
Logging
+++++++
-The setting ``unique-response-log`` is enabled by default once the NOD feature is enabled, and will log the newly observed domain to the recursor logfile.
-To log UDR information to a dnstap stream, refer to :func:`dnstapNODFrameStreamServer`.
+The setting :ref:`setting-yaml-nod.unique_response_log` is enabled by default once the NOD feature is enabled, and will log the newly observed domain to the recursor logfile.
+To log UDR information to a dnstap stream, refer to :ref:`setting-yaml-logging.dnstap_nod_framestream_servers`.
Protobuf Logging
++++++++++++++++
-If both UDR and protobuf logging are enabled, then unique domain responses will be tagged in the protobuf stream using the tag ``pdns-udr`` by default. The setting ``unique-response-pb-tag=<tag>`` can be used to alter the tag.
+If both UDR and protobuf logging are enabled, then unique domain responses will be tagged in the protobuf stream using the tag ``pdns-udr`` by default. The setting :ref:`setting-yaml-nod.unique_response_pb_tag` can be used to alter the tag.
FreeBSD has a default limit that is high enough for even very heavy duty use.
Limit the size of the caches to a sensible value.
-Cache hit rate does not improve meaningfully beyond a few million :ref:`setting-max-cache-entries`, reducing the memory footprint reduces CPU cache misses.
+Cache hit rate does not improve meaningfully beyond a few million :ref:`setting-yaml-recordcache.max_entries`, reducing the memory footprint reduces CPU cache misses.
See below for more information about the various caches.
When deploying (large scale) IPv6, please be aware some Linux distributions leave IPv6 routing cache tables at very small default values.
Please check and if necessary raise ``sysctl net.ipv6.route.max_size``.
-Set :ref:`setting-threads` to your number of CPU cores minus the number of distributor threads.
+Set :ref:`setting-yaml-recursor.threads` to your number of CPU cores minus the number of distributor threads.
Threading and distribution of queries
-------------------------------------
-When running with several threads, you can either ask PowerDNS to start one or more special threads to dispatch the incoming queries to the workers by setting :ref:`setting-pdns-distributes-queries` to ``yes``, or let the worker threads handle the incoming queries themselves.
+When running with several threads, you can either ask PowerDNS to start one or more special threads to dispatch the incoming queries to the workers by setting :ref:`setting-yaml-incoming.pdns_distributes_queries` to ``yes``, or let the worker threads handle the incoming queries themselves.
The latter is the default since version 4.9.0.
-The dispatch thread enabled by :ref:`setting-pdns-distributes-queries` tries to send the same queries to the same thread to maximize the cache-hit ratio.
-If the incoming query rate is so high that the dispatch thread becomes a bottleneck, you can increase :ref:`setting-distributor-threads` to use more than one.
+The dispatch thread enabled by :ref:`setting-yaml-incoming.pdns_distributes_queries` tries to send the same queries to the same thread to maximize the cache-hit ratio.
+If the incoming query rate is so high that the dispatch thread becomes a bottleneck, you can increase :ref:`setting-yaml-incoming.distributor_threads` to use more than one.
-If :ref:`setting-pdns-distributes-queries` is set to ``no`` and either ``SO_REUSEPORT`` support is not available or the :ref:`setting-reuseport` directive is set to ``no``, all worker threads share the same listening sockets.
+If :ref:`setting-yaml-incoming.pdns_distributes_queries` is set to ``false`` and either ``SO_REUSEPORT`` support is not available or the :ref:`setting-yaml-incoming.reuseport` directive is set to ``false``, all worker threads share the same listening sockets.
This prevents a single thread from having to handle every incoming queries, but can lead to thundering herd issues where all threads are awoken at once when a query arrives.
-If ``SO_REUSEPORT`` support is available and :ref:`setting-reuseport` is set to ``yes``, which is the
+If ``SO_REUSEPORT`` support is available and :ref:`setting-yaml-incoming.reuseport` is set to ``true``, which is the
default since version 4.9.0, separate listening sockets are opened for each worker thread and the query distributions is handled by the kernel, avoiding any thundering herd issue as well as preventing the distributor thread from becoming the bottleneck.
The next section discusses how to determine if the mechanism is working properly.
Imbalance
^^^^^^^^^
-Due to the nature of the distribution method used by the kernel imbalance with the new default settings of :ref:`setting-reuseport` and :ref:`setting-pdns-distributes-queries` may occur if you have very few clients.
+Due to the nature of the distribution method used by the kernel imbalance with the new default settings of :ref:`setting-yaml-incoming.reuseport` and :ref:`setting-yaml-incoming.pdns_distributes_queries` may occur if you have very few clients.
Imbalance can be observed by reading the periodic statistics reported by :program:`Recursor`::
Jun 26 11:06:41 pepper pdns-recursor[10502]: msg="Queries handled by thread" subsystem="stats" level="0" prio="Info" tid="0" ts="1687770401.359" count="7" thread="0"
Non-Linux systems
^^^^^^^^^^^^^^^^^
-On some systems setting :ref:`setting-reuseport` to ``yes`` does not have the desired effect at all.
-If your systems shows great imbalance in the number of queries processed per thread (as reported by the periodic statistics report), try switching :ref:`setting-reuseport` to ``no`` and/or setting :ref:`setting-pdns-distributes-queries` to ``yes``.
+On some systems setting :ref:`setting-yaml-incoming.reuseport` to ``true`` does not have the desired effect at all.
+If your systems shows great imbalance in the number of queries processed per thread (as reported by the periodic statistics report), try switching :ref:`setting-yaml-incoming.reuseport` to ``false`` and/or setting :ref:`setting-yaml-incoming.pdns_distributes_queries` to ``true``.
.. versionadded:: 4.1.0
- The :ref:`setting-cpu-map` parameter can be used to pin worker threads to specific CPUs, in order to keep caches as warm as possible and optimize memory access on NUMA systems.
+ The :ref:`setting-yaml-recursor.cpu_map` parameter can be used to pin worker threads to specific CPUs, in order to keep caches as warm as possible and optimize memory access on NUMA systems.
.. versionadded:: 4.2.0
- The :ref:`setting-distributor-threads` parameter can be used to run more than one distributor thread.
+ The :ref:`setting-yaml-incoming.distributor_threads` parameter can be used to run more than one distributor thread.
.. versionchanged:: 4.9.0
- The :ref:`setting-reuseport` parameter now defaults to ``yes``.
+ The :ref:`setting-yaml-incoming.reuseport` parameter now defaults to ``yes``.
.. versionchanged:: 4.9.0
- The :ref:`setting-pdns-distributes-queries` parameter now defaults to ``no``.
+ The :ref:`setting-yaml-incoming.pdns_distributes_queries` parameter now defaults to ``no``.
MTasker and MThreads
PowerDNS :program:`Recursor` uses a cooperative multitasking in userspace called ``MTasker``, based either on ``boost::context`` if available, or on ``System V ucontexts`` otherwise. For maximum performance, please make sure that your system supports ``boost::context``, as the alternative has been known to be quite slower.
-The maximum number of simultaneous MTasker threads, called ``MThreads``, can be tuned via :ref:`setting-max-mthreads`, as the default value of 2048 might not be enough for large-scale installations.
+The maximum number of simultaneous MTasker threads, called ``MThreads``, can be tuned via :ref:`setting-yaml-recursor.max_mthreads`, as the default value of 2048 might not be enough for large-scale installations.
This setting limits the number of mthreads *per physical (Posix) thread*.
The threads that create mthreads are the distributor and worker threads.
-When a ``MThread`` is started, a new stack is dynamically allocated for it. The size of that stack can be configured via the :ref:`setting-stack-size` parameter, whose default value is 200 kB which should be enough in most cases.
+When a ``MThread`` is started, a new stack is dynamically allocated for it. The size of that stack can be configured via the :ref:`setting-yaml-recursor.stack_size` parameter, whose default value is 200 kB which should be enough in most cases.
-To reduce the cost of allocating a new stack for every query, the recursor can cache a small amount of stacks to make sure that the allocation stays cheap. This can be configured via the :ref:`setting-stack-cache-size` setting.
+To reduce the cost of allocating a new stack for every query, the recursor can cache a small amount of stacks to make sure that the allocation stays cheap. This can be configured via the :ref:`setting-yaml-recursor.stack_cache_size` setting.
This limit is per physical (Posix) thread.
-The only trade-off of enabling this cache is a slightly increased memory consumption, at worst equals to the number of stacks specified by :ref:`setting-stack-cache-size` multiplied by the size of one stack, itself specified via :ref:`setting-stack-size`.
+The only trade-off of enabling this cache is a slightly increased memory consumption, at worst equals to the number of stacks specified by :ref:`setting-yaml-recursor.stack_cache_size` multiplied by the size of one stack, itself specified via :ref:`setting-yaml-recursor.stack_size`.
Linux limits the number of memory mappings a process can allocate by the ``vm.max_map_count`` kernel parameter.
A single ``MThread`` stack can take up to 3 memory mappings.
When a query is received over a TCP connection, first the packet cache is consulted.
If an answer is found it will be returned immediately.
-If no answer is found, the Recursor will process :ref:`setting-max-concurrent-requests-per-tcp-connection` queries per incoming TCP connection concurrently.
+If no answer is found, the Recursor will process :ref:`setting-yaml-incoming.max_concurrent_requests_per_tcp_connection` queries per incoming TCP connection concurrently.
If more than this number of queries is pending for this TCP connection, the remaining queries will stay in the TCP receive buffer to be processed later.
Each of the queries processed will consume an mthread until processing is done.
A response to a query is sent immediately when it becomes available; the response can be sent before other responses to queries that were received earlier by the Recursor.
This is the Out-of-Order feature which greatly enhances performance, as a single slow query does not prevent other queries to be processed.
-Before version 5.0.0, TCP queries are processed by either the distributer thread(s) if :ref:`setting-pdns-distributes-queries` is true, or by worker threads if :ref:`setting-pdns-distributes-queries` is false.
+Before version 5.0.0, TCP queries are processed by either the distributer thread(s) if :ref:`setting-yaml-incoming.pdns_distributes_queries` is true, or by worker threads if :ref:`setting-yaml-incoming.pdns_distributes_queries` is false.
Starting with version 5.0.0, :program:`Recursor` has dedicated thread(s) processing TCP queries.
-The maximum number of mthreads consumed by TCP queries is :ref:`setting-max-tcp-clients` times :ref:`setting-max-concurrent-requests-per-tcp-connection`.
-Before version 5.0.0, if :ref:`setting-pdns-distributes-queries` is false, this number should be (much) lower than :ref:`setting-max-mthreads`, to also allow UDP queries to be handled as these also consume mthreads.
-Note that :ref:`setting-max-mthreads` is a per Posix thread setting.
+The maximum number of mthreads consumed by TCP queries is :ref:`setting-yaml-incoming.max_tcp_clients` times :ref:`setting-yaml-incoming.max_concurrent_requests_per_tcp_connection`.
+Before version 5.0.0, if :ref:`setting-yaml-incoming.pdns_distributes_queries` is false, this number should be (much) lower than :ref:`setting-yaml-recursor.max_mthreads`, to also allow UDP queries to be handled as these also consume mthreads.
+Note that :ref:`setting-yaml-recursor.max_mthreads` is a per Posix thread setting.
This means that the global maximum number of mthreads is (#distributor threads + #worker threads) * max-mthreads.
-If you expect few clients, you can increase :ref:`setting-max-concurrent-requests-per-tcp-connection`, to allow more concurrency per TCP connection.
-If you expect many clients and you have increased :ref:`setting-max-tcp-clients`, reduce :ref:`setting-max-concurrent-requests-per-tcp-connection` number to prevent mthread starvation or increase the maximum number of mthreads.
+If you expect few clients, you can increase :ref:`setting-yaml-incoming.max_concurrent_requests_per_tcp_connection`, to allow more concurrency per TCP connection.
+If you expect many clients and you have increased :ref:`setting-yaml-incoming.max_tcp_clients`, reduce :ref:`setting-yaml-incoming.max_concurrent_requests_per_tcp_connection` number to prevent mthread starvation or increase the maximum number of mthreads.
-To increase the maximum number of concurrent queries consider increasing :ref:`setting-max-mthreads`, but be aware that each active mthread consumes more than 200k of memory.
+To increase the maximum number of concurrent queries consider increasing :ref:`setting-yaml-recursor.max_mthreads`, but be aware that each active mthread consumes more than 200k of memory.
To see the current number of mthreads in use consult the :doc:`metrics` ``concurrent-queries`` metric.
If a query could not be handled due to mthread shortage, the ``over-capacity-drops`` metric is increased.
As an example, if you have typically 200 TCP clients, and the default maximum number of mthreads of 2048, a good number of concurrent requests per TCP connection would be 5. Assuming a worst case packet cache hit ratio, if all 200 TCP clients fill their connections with queries, about half (5 * 200) of the mthreads would be used by incoming TCP queries, leaving the other half for incoming UDP queries.
Note that starting with version 5.0.0, TCP queries are processed by dedicated TCP thread(s), so the sharing of mthreads between UDP and TCP queries no longer applies.
-The total number of incoming TCP connections is limited by :ref:`setting-max-tcp-clients`.
-There is also a per client address limit: :ref:`setting-max-tcp-per-client` to limit the impact of a single client.
+The total number of incoming TCP connections is limited by :ref:`setting-yaml-incoming.max_tcp_clients`.
+There is also a per client address limit: :ref:`setting-yaml-incoming.max_tcp_per_client` to limit the impact of a single client.
Consult the :doc:`metrics` ``tcp-clients`` metric for the current number of TCP connections and the ``tcp-client-overflow`` metric to see if client connection attempts were rejected because there were too many existing connections from a single address.
.. _tcp-fast-open-support:
If you operate an anycast pool of machines, make them share the TCP Fast Open Key by setting the ``net.ipv4.tcp_fastopen_key`` sysctl, otherwise you will create a similar issue some Google servers have.
-To determine a good value for the :ref:`setting-tcp-fast-open` setting, watch the ``TCPFastOpenListenOverflow`` metric.
+To determine a good value for the :ref:`setting-yaml-incoming.tcp_fast_open` setting, watch the ``TCPFastOpenListenOverflow`` metric.
If this value increases often, the value might be too low for your traffic, but note that increasing it will use kernel resources.
Running with a local root zone
}
repeated Event trace = 23;
-Event traces can be enabled by either setting :ref:`setting-event-trace-enabled` or by using the :doc:`rec_control <manpages/rec_control.1>` subcommand ``set-event-trace-enabled``.
+Event traces can be enabled by either setting :ref:`setting-yaml-recursor.event_trace_enabled` or by using the :doc:`rec_control <manpages/rec_control.1>` subcommand ``set-event-trace-enabled``.
An example of a trace (timestamps are relative in nanoseconds) as shown in the logfile:
PowerDNS logs messages with different levels.
The more urgent the message, the lower the 'priority'.
-By default, PowerDNS will only log messages with an urgency of 3 or lower, but this can be changed using the :ref:`setting-loglevel` setting in the configuration file.
+By default, PowerDNS will only log messages with an urgency of 3 or lower, but this can be changed using the :ref:`setting-yaml-logging.loglevel` setting in the configuration file.
Setting it to 0 will eliminate all logging, 9 will log everything.
By default, logging is performed under the 'DAEMON' facility which is shared with lots of other programs.
If you regard nameserving as important, you may want to have it under a dedicated facility so PowerDNS can log to its own files, and not clutter generic files.
For this purpose, syslog knows about 'local' facilities, numbered from LOCAL0 to LOCAL7.
-To move PowerDNS logging to LOCAL0, add :ref:`logging-facility=0 <setting-logging-facility>` to your configuration.
+To move PowerDNS logging to LOCAL0, set :ref:`setting-yaml-logging.facility` to 0 in your configuration.
Furthermore, you may want to have separate files for the differing priorities - preventing lower priority messages from obscuring important ones.
A sample ``syslog.conf`` might be::
To investigate failures with resolving certain domain names, the PowerDNS :program:`Recursor` features a tracing infrastructure.
This infrastructure will log every step the :program:`Recursor` takes to resolve a name and will log all DNSSEC related information as well.
-To enable tracing for all queries, enable the :ref:`setting-trace` setting.
+To enable tracing for all queries, enable the :ref:`setting-yaml-logging.trace` setting.
Trace information will be written to the log.
.. warning::
--------------------------------------
In some cases a tracing provides too much information, and we want to follow what the recursor is doing on a higher level.
-By setting :ref:`setting-quiet` to ``true`` the recursor will produce a log line for each client query received and answered.
+By setting :ref:`setting-yaml-logging.quiet` to ``true`` the recursor will produce a log line for each client query received and answered.
Be aware that this causes overhead and should not be used in a high query-per-second production environment::
Jul 09 09:08:31 msg="Question" subsystem="syncres" level="0" prio="Info" tid="4" ts="1720508911.919" ecs="" mtid="1" proto="udp" qname="www.example.com" qtype="A" remote="127.0.0.1:54573"
In addition, PowerDNS detects when it is being sent too many unexpected answers, and mistrusts a proper answer if found within a clutch of unexpected ones.
-This behaviour can be tuned using the :ref:`setting-spoof-nearmiss-max`.
+This behaviour can be tuned using the :ref:`setting-yaml-recursor.spoof_nearmiss_max`.
Throttling
----------
'lambda': 'doGetCacheBytes',
'ptype': 'gauge',
'desc': 'Size of the cache in bytes',
- 'longdesc': '''Since version 5.3.0 this metric computes a rough estimate of the number of bytes allocated by the record cache. Older versions return a number that cannot be relied upon. Disabled by default, as computing this number is CPU intensive, see :ref:`setting-stats-rec-control-disabled-list`.''',
+ 'longdesc': '''Since version 5.3.0 this metric computes a rough estimate of the number of bytes allocated by the record cache. Older versions return a number that cannot be relied upon. Disabled by default, as computing this number is CPU intensive, see :ref:`setting-yaml-recursor.stats_rec_control_disabled_list`.''',
'snmp': 7,
},
{
'lambda': '[] { return g_packetCache ? g_packetCache->bytes() : 0; }',
'ptype': 'gauge',
'desc': 'Size of the packetcache in bytes',
- 'longdesc': '''Disabled by default, see :ref:`setting-stats-rec-control-disabled-list`. This metric is currently broken, it always is 0.''',
+ 'longdesc': '''Disabled by default, see :ref:`setting-yaml-recursor.stats_rec_control_disabled_list`. This metric is currently broken, it always is 0.''',
'snmp': 11,
},
{
return total;
}''',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-no-valid-dnskey',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusNoValidDNSKEY); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-invalid-denial',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusInvalidDenial); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-unable-to-get-dss',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusUnableToGetDSs); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-unable-to-get-dnskeys',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusUnableToGetDNSKEYs); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-self-signed-ds',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusSelfSignedDS); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-no-rrsig',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusNoRRSIG); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-no-valid-rrsig',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusNoValidRRSIG); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-missing-negative-indication',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusMissingNegativeIndication); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-signature-not-yet-valid',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusSignatureNotYetValid); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-signature-expired',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusSignatureExpired); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-unsupported-dnskey-algo',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusUnsupportedDNSKEYAlgo); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-unsupported-ds-digest-type',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusUnsupportedDSDigestType); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-no-zone-key-bit-set',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusNoZoneKeyBitSet); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-revoked-dnskey',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusRevokedDNSKEY); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-bogus-invalid-dnskey-protocol',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::BogusInvalidDNSKEYProtocol); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-indeterminate',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::Indeterminate); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-nta',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::NTA); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-insecure',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::Insecure); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'x-dnssec-result-secure',
'lambda': '[] { return g_Counters.sum(rec::DNSSECHistogram::xdnssec).at(vState::Secure); }',
'if': '::arg()["x-dnssec-names"].length() > 0',
- 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-x-dnssec-names`.'
+ 'desc': 'Same as corresponding metric without ``x-`` prefix, for names in :ref:`setting-yaml-dnssec.x_dnssec_names`.'
},
{
'name': 'idle-tcpout-connections',
'name': 'cumul-clientanswers-x',
# No lambda
'desc': 'Cumulative counts of answer times of authoritative servers in buckets less than x microseconds.',
- 'longdesc': 'Disabled by default, see :ref:`setting-stats-rec-control-disabled-list`. These metrics are useful for Prometheus and not listed in other outputs by default.',
+ 'longdesc': 'Disabled by default, see :ref:`setting-yaml-recursor.stats_rec_control_disabled_list`. These metrics are useful for Prometheus and not listed in other outputs by default.',
'ptype': 'histogram',
'pname': 'cumul-clientanswers-count', # For cumulative histogram, state the xxx_count name where xxx matches the name in rec_channel_rec
# No SNMP
'name': 'cumul-authanswers-x',
# No lambda
'desc': 'Cumulative counts of answer times to clients in buckets less than x microseconds.',
- 'longdesc': 'Disabled by default, see :ref:`setting-stats-rec-control-disabled-list`. These metrics are useful for Prometheus and not listed in other outputs by default.',
+ 'longdesc': 'Disabled by default, see :ref:`setting-yaml-recursor.stats_rec_control_disabled_list`. These metrics are useful for Prometheus and not listed in other outputs by default.',
'ptype': 'histogram',
'pname': 'cumul-authanswers-count4', # For cumulative histogram, state the xxx_count name where xxx matches the name in rec_channel_rec
# No SNMP
projects / thirdparty / pdns.git / commitdiff
