From 223bb49ef87feee34af9d1076b55bee81a38b8bc Mon Sep 17 00:00:00 2001 From: Pieter Lexis Date: Thu, 29 Jun 2017 00:04:33 +0200 Subject: [PATCH] Split the Recursor documentation Transform it to restructured text and use Sphinx to build it. --- docs/authoritative/http-api/apispec.rst | 255 ++ .../authoritative/http-api/endpoint-zones.rst | 150 ++ .../http-api/zone-properties.rst | 74 + docs/authoritative/http-api/zonemetadata.rst | 19 + docs/authoritative/security.rst | 49 + docs/common/api/configsetting.rst | 20 + docs/common/api/dataformat.rst | 144 ++ docs/common/api/endpoint-api.rst | 38 + docs/common/api/endpoint-logging.rst | 10 + docs/common/api/endpoint-servers-config.rst | 74 + docs/common/api/endpoint-servers.rst | 12 + docs/common/api/endpoint-statistics.rst | 17 + docs/common/api/server.rst | 35 + docs/common/api/statisticitem.rst | 10 + docs/common/api/zone.rst | 59 + docs/common/favicon.ico | Bin 0 -> 1406 bytes docs/common/powerdns-logo-500px.png | Bin 0 -> 13551 bytes docs/common/secpoll.rst | 69 + docs/common/security-policy.rst | 25 + docs/markdown/recursor/index.md | 2 + docs/markdown/recursor/scripting.md | 4 +- docs/markdown/theme/content.html | 2 +- docs/process-md.sh | 2 + docs/security-advisories/index.rst | 25 + docs/security-advisories/older-than-3.0.rst | 25 + .../powerdns-advisory-2006-01.rst | 39 + .../powerdns-advisory-2006-02.rst | 22 + .../powerdns-advisory-2008-01.rst | 54 + .../powerdns-advisory-2008-02.rst | 30 + .../powerdns-advisory-2008-03.rst | 29 + .../powerdns-advisory-2010-01.rst | 24 + .../powerdns-advisory-2010-02.rst | 23 + .../powerdns-advisory-2012-01.rst | 85 + .../powerdns-advisory-2014-01.rst | 40 + .../powerdns-advisory-2014-02.rst | 39 + .../powerdns-advisory-2015-01.rst | 55 + .../powerdns-advisory-2015-02.rst | 36 + .../powerdns-advisory-2015-03.rst | 40 + .../powerdns-advisory-2016-01.rst | 44 + .../powerdns-advisory-2016-02.rst | 42 + .../powerdns-advisory-2016-03.rst | 35 + .../powerdns-advisory-2016-04.rst | 36 + .../powerdns-advisory-2016-05.rst | 32 + docs/security-advisories/security-policy.rst | 12 + pdns/recursordist/.gitignore | 6 + pdns/recursordist/Makefile.am | 59 +- pdns/recursordist/configure.ac | 2 +- .../contrib}/kv-example-script.lua | 0 .../contrib}/powerdns-example-script.lua | 0 pdns/recursordist/docs/.gitignore | 1 + pdns/recursordist/docs/Makefile | 20 + pdns/recursordist/docs/_static/pdns.css | 1052 ++++++++ .../docs/appendices/compiling.rst | 57 + .../docs/appendices/internals.rst | 430 ++++ pdns/recursordist/docs/changelog/4.0.rst | 570 +++++ pdns/recursordist/docs/changelog/4.1.rst | 51 + pdns/recursordist/docs/changelog/index.rst | 11 + pdns/recursordist/docs/changelog/pre-4.0.rst | 2186 +++++++++++++++++ pdns/recursordist/docs/common | 1 + pdns/recursordist/docs/conf.py | 206 ++ pdns/recursordist/docs/dns64.rst | 27 + pdns/recursordist/docs/dnssec.rst | 171 ++ pdns/recursordist/docs/getting-started.rst | 63 + .../docs/http-api/endpoint-cache.rst | 19 + .../docs/http-api/endpoint-failure.rst | 70 + .../docs/http-api/endpoint-trace.rst | 40 + .../docs/http-api/endpoint-zones.rst | 28 + pdns/recursordist/docs/http-api/index.rst | 66 + pdns/recursordist/docs/http-api/override.rst | 64 + .../docs/http-api/zone-properties.rst | 4 + pdns/recursordist/docs/index.rst | 75 + pdns/recursordist/docs/indexTOC.rst | 25 + pdns/recursordist/docs/lua-config/dnssec.rst | 20 + pdns/recursordist/docs/lua-config/index.rst | 11 + .../recursordist/docs/lua-config/protobuf.rst | 75 + pdns/recursordist/docs/lua-config/rpz.rst | 138 ++ .../recursordist/docs/lua-config/sortlist.rst | 33 + .../docs/lua-scripting/comboaddress.rst | 67 + .../docs/lua-scripting/configure.rst | 22 + .../docs/lua-scripting/dnsname.rst | 104 + .../docs/lua-scripting/dnsrecord.rst | 42 + pdns/recursordist/docs/lua-scripting/dq.rst | 257 ++ .../docs/lua-scripting/functions.rst | 15 + .../recursordist/docs/lua-scripting/hooks.rst | 314 +++ .../recursordist/docs/lua-scripting/index.rst | 28 + .../docs/lua-scripting/logging.rst | 24 + .../docs/lua-scripting/netmask.rst | 93 + .../docs/lua-scripting/statistics.rst | 61 + .../docs/manpages/pdns_recursor.rst | 125 + .../docs/manpages/rec_control.rst | 220 ++ pdns/recursordist/docs/metrics.rst | 433 ++++ pdns/recursordist/docs/performance.rst | 135 + pdns/recursordist/docs/requirements.txt | 7 + pdns/recursordist/docs/running.rst | 96 + .../docs/security-advisories/index.rst | 14 + .../security-advisories/older-than-3.0.rst | 1 + .../powerdns-advisory-2006-01.rst | 1 + .../powerdns-advisory-2006-02.rst | 1 + .../powerdns-advisory-2008-01.rst | 1 + .../powerdns-advisory-2010-01.rst | 1 + .../powerdns-advisory-2010-02.rst | 1 + .../powerdns-advisory-2014-01.rst | 1 + .../powerdns-advisory-2014-02.rst | 1 + .../powerdns-advisory-2015-01.rst | 1 + .../powerdns-advisory-2016-02.rst | 1 + .../powerdns-advisory-2016-04.rst | 1 + pdns/recursordist/docs/security.rst | 39 + pdns/recursordist/docs/settings.rst | 1080 ++++++++ pdns/recursordist/docs/upgrade.rst | 20 + pdns/recursordist/m4/pdns_check_pandoc.m4 | 11 - pdns/recursordist/m4/pdns_check_virtualenv.m4 | 12 + pdns/recursordist/pdns_recursor.1.md | 1 - pdns/recursordist/rec_control.1.md | 1 - 113 files changed, 10620 insertions(+), 30 deletions(-) create mode 100644 docs/authoritative/http-api/apispec.rst create mode 100644 docs/authoritative/http-api/endpoint-zones.rst create mode 100644 docs/authoritative/http-api/zone-properties.rst create mode 100644 docs/authoritative/http-api/zonemetadata.rst create mode 100644 docs/authoritative/security.rst create mode 100644 docs/common/api/configsetting.rst create mode 100644 docs/common/api/dataformat.rst create mode 100644 docs/common/api/endpoint-api.rst create mode 100644 docs/common/api/endpoint-logging.rst create mode 100644 docs/common/api/endpoint-servers-config.rst create mode 100644 docs/common/api/endpoint-servers.rst create mode 100644 docs/common/api/endpoint-statistics.rst create mode 100644 docs/common/api/server.rst create mode 100644 docs/common/api/statisticitem.rst create mode 100644 docs/common/api/zone.rst create mode 100644 docs/common/favicon.ico create mode 100644 docs/common/powerdns-logo-500px.png create mode 100644 docs/common/secpoll.rst create mode 100644 docs/common/security-policy.rst create mode 100644 docs/security-advisories/index.rst create mode 100644 docs/security-advisories/older-than-3.0.rst create mode 100644 docs/security-advisories/powerdns-advisory-2006-01.rst create mode 100644 docs/security-advisories/powerdns-advisory-2006-02.rst create mode 100644 docs/security-advisories/powerdns-advisory-2008-01.rst create mode 100644 docs/security-advisories/powerdns-advisory-2008-02.rst create mode 100644 docs/security-advisories/powerdns-advisory-2008-03.rst create mode 100644 docs/security-advisories/powerdns-advisory-2010-01.rst create mode 100644 docs/security-advisories/powerdns-advisory-2010-02.rst create mode 100644 docs/security-advisories/powerdns-advisory-2012-01.rst create mode 100644 docs/security-advisories/powerdns-advisory-2014-01.rst create mode 100644 docs/security-advisories/powerdns-advisory-2014-02.rst create mode 100644 docs/security-advisories/powerdns-advisory-2015-01.rst create mode 100644 docs/security-advisories/powerdns-advisory-2015-02.rst create mode 100644 docs/security-advisories/powerdns-advisory-2015-03.rst create mode 100644 docs/security-advisories/powerdns-advisory-2016-01.rst create mode 100644 docs/security-advisories/powerdns-advisory-2016-02.rst create mode 100644 docs/security-advisories/powerdns-advisory-2016-03.rst create mode 100644 docs/security-advisories/powerdns-advisory-2016-04.rst create mode 100644 docs/security-advisories/powerdns-advisory-2016-05.rst create mode 100644 docs/security-advisories/security-policy.rst rename pdns/{ => recursordist/contrib}/kv-example-script.lua (100%) rename pdns/{ => recursordist/contrib}/powerdns-example-script.lua (100%) create mode 100644 pdns/recursordist/docs/.gitignore create mode 100644 pdns/recursordist/docs/Makefile create mode 100644 pdns/recursordist/docs/_static/pdns.css create mode 100644 pdns/recursordist/docs/appendices/compiling.rst create mode 100644 pdns/recursordist/docs/appendices/internals.rst create mode 100644 pdns/recursordist/docs/changelog/4.0.rst create mode 100644 pdns/recursordist/docs/changelog/4.1.rst create mode 100644 pdns/recursordist/docs/changelog/index.rst create mode 100644 pdns/recursordist/docs/changelog/pre-4.0.rst create mode 120000 pdns/recursordist/docs/common create mode 100644 pdns/recursordist/docs/conf.py create mode 100644 pdns/recursordist/docs/dns64.rst create mode 100644 pdns/recursordist/docs/dnssec.rst create mode 100644 pdns/recursordist/docs/getting-started.rst create mode 100644 pdns/recursordist/docs/http-api/endpoint-cache.rst create mode 100644 pdns/recursordist/docs/http-api/endpoint-failure.rst create mode 100644 pdns/recursordist/docs/http-api/endpoint-trace.rst create mode 100644 pdns/recursordist/docs/http-api/endpoint-zones.rst create mode 100644 pdns/recursordist/docs/http-api/index.rst create mode 100644 pdns/recursordist/docs/http-api/override.rst create mode 100644 pdns/recursordist/docs/http-api/zone-properties.rst create mode 100644 pdns/recursordist/docs/index.rst create mode 100644 pdns/recursordist/docs/indexTOC.rst create mode 100644 pdns/recursordist/docs/lua-config/dnssec.rst create mode 100644 pdns/recursordist/docs/lua-config/index.rst create mode 100644 pdns/recursordist/docs/lua-config/protobuf.rst create mode 100644 pdns/recursordist/docs/lua-config/rpz.rst create mode 100644 pdns/recursordist/docs/lua-config/sortlist.rst create mode 100644 pdns/recursordist/docs/lua-scripting/comboaddress.rst create mode 100644 pdns/recursordist/docs/lua-scripting/configure.rst create mode 100644 pdns/recursordist/docs/lua-scripting/dnsname.rst create mode 100644 pdns/recursordist/docs/lua-scripting/dnsrecord.rst create mode 100644 pdns/recursordist/docs/lua-scripting/dq.rst create mode 100644 pdns/recursordist/docs/lua-scripting/functions.rst create mode 100644 pdns/recursordist/docs/lua-scripting/hooks.rst create mode 100644 pdns/recursordist/docs/lua-scripting/index.rst create mode 100644 pdns/recursordist/docs/lua-scripting/logging.rst create mode 100644 pdns/recursordist/docs/lua-scripting/netmask.rst create mode 100644 pdns/recursordist/docs/lua-scripting/statistics.rst create mode 100644 pdns/recursordist/docs/manpages/pdns_recursor.rst create mode 100644 pdns/recursordist/docs/manpages/rec_control.rst create mode 100644 pdns/recursordist/docs/metrics.rst create mode 100644 pdns/recursordist/docs/performance.rst create mode 100644 pdns/recursordist/docs/requirements.txt create mode 100644 pdns/recursordist/docs/running.rst create mode 100644 pdns/recursordist/docs/security-advisories/index.rst create mode 120000 pdns/recursordist/docs/security-advisories/older-than-3.0.rst create mode 120000 pdns/recursordist/docs/security-advisories/powerdns-advisory-2006-01.rst create mode 120000 pdns/recursordist/docs/security-advisories/powerdns-advisory-2006-02.rst create mode 120000 pdns/recursordist/docs/security-advisories/powerdns-advisory-2008-01.rst create mode 120000 pdns/recursordist/docs/security-advisories/powerdns-advisory-2010-01.rst create mode 120000 pdns/recursordist/docs/security-advisories/powerdns-advisory-2010-02.rst create mode 120000 pdns/recursordist/docs/security-advisories/powerdns-advisory-2014-01.rst create mode 120000 pdns/recursordist/docs/security-advisories/powerdns-advisory-2014-02.rst create mode 120000 pdns/recursordist/docs/security-advisories/powerdns-advisory-2015-01.rst create mode 120000 pdns/recursordist/docs/security-advisories/powerdns-advisory-2016-02.rst create mode 120000 pdns/recursordist/docs/security-advisories/powerdns-advisory-2016-04.rst create mode 100644 pdns/recursordist/docs/security.rst create mode 100644 pdns/recursordist/docs/settings.rst create mode 100644 pdns/recursordist/docs/upgrade.rst delete mode 100644 pdns/recursordist/m4/pdns_check_pandoc.m4 create mode 100644 pdns/recursordist/m4/pdns_check_virtualenv.m4 delete mode 120000 pdns/recursordist/pdns_recursor.1.md delete mode 120000 pdns/recursordist/rec_control.1.md diff --git a/docs/authoritative/http-api/apispec.rst b/docs/authoritative/http-api/apispec.rst new file mode 100644 index 0000000000..d50cf8a2e3 --- /dev/null +++ b/docs/authoritative/http-api/apispec.rst @@ -0,0 +1,255 @@ +URL: /api/v0/servers/:server\_id/zones/:zone\_name/metadata +----------------------------------------------------------- + +Collection access. + +Allowed methods: ``GET``, ``POST`` + +GET +^^^ + +Returns all metadata entries for the zone. + +POST +^^^^ + +Creates a set of metadata entries of given kind for the zone. + +- existing metadata entries for the zone with the same kind are not + overwritten. + +URL: /api/v1/servers/:server\_id/zones/:zone\_name/metadata/:metadata\_kind +--------------------------------------------------------------------------- + +Allowed methods: ``GET``, ``PUT``, ``DELETE`` + +GET +^^^ + +Returns all metadata entries of a given kind for the zone. + +DELETE +^^^^^^ + +Deletes all metadata entries of a given kind for the zone. + +PUT +^^^ + +Modifies the metadata entries of a given kind for the zone. + +This returns ``200 OK`` on success. + +Cryptokeys +========== + +cryptokey\_resource +------------------- + +:: + + { + "type": "Cryptokey", + "id": , + "active": , + "keytype": , + "dnskey": , + "privatekey": , + "ds": [ , + , + .... ] + } + +Parameters: +''''''''''' + +``id``: read-only. + +``keytype``: ```` is one of the following: ``ksk``, ``zsk``, +``csk``. + +``dnskey``: the DNSKEY for this key + +``ds``: an array with all DSes for this key + +``privatekey``: private key data (in ISC format). + +URL: /api/v1/servers/:server\_id/zones/:zone\_name/cryptokeys +------------------------------------------------------------- + +Allowed methods: ``GET``, ``POST`` + +GET +^^^ + +Returns all public data about cryptokeys, but not ``privatekey``. + +POST +^^^^ + +This method adds a new key to a zone. The key can either be generated or +imported by supplying the content parameter. + +Parameters: +''''''''''' + +- ``content`` : "" ```` (The format used is compatible + with BIND and NSD/LDNS) +- ``keytype`` : "ksk\|zsk" ```` +- ``active``: "true\|false" ```` (If not set the key will not be + active by default) + +If ``content`` == ``null``, the server generates a new key. In this +case, the following additional fields MAY be supplied: + +- ``bits``: number of bits ```` +- ``algo``: ```` (Default: 13/ECDSA) + +Where ```` is one of the supported key algorithms in lowercase OR +the numeric id, see +```the list`` <../authoritative/dnssec.md#supported-algorithms>`__. + +Response: +''''''''' + +- ``422 Unprocessable Entity``: + + - keytype is not ksk\|zsk: + + - ``{"error" : "Invalid keytype 'keytype'"}`` + + - The "algo" is not supported: + + - ``{"error" : "Unknown algorithm: 'algo'"}`` + + - Algo <= 10 and the ``bits`` parameter is not set: + + - ``{"error" : "Creating an algorithm 'algo' key requires the size (in bits) to be passed."}`` + + - The provided bit size is not supported by the selected algorithm: + + - ``{"error" : "The algorithm does not support the given bit size."}`` + + - The ``bits`` parameter is not a positive integer value: + + - ``{"error" : "'bits' must be a positive integer value"}`` + + - If the server can not guess the key size: + + - ``{"error" : "Can not guess key size for algorithm"}`` + + - The key-creation failed: + + - ``{"error" : "Adding key failed, perhaps DNSSEC not enabled in configuration?"}`` + + - The key in ``content`` has the wrong format: + + - ``{"error" : "Key could not be parsed. Make sure your key format is correct."}`` + +- ``201 Created``: + + - Everything was fine: + + - Returns all public data about the new cryptokey. Look at + cryptokey\_resource. + +URL: /api/v1/servers/:server\_id/zones/:zone\_name/cryptokeys/:cryptokey\_id +---------------------------------------------------------------------------- + +Allowed methods: ``GET``, ``PUT``, ``DELETE`` + +GET +^^^ + +Returns all public data about cryptokeys, including ``privatekey``. + +PUT +^^^ + +This method de/activates a key from ``zone_name`` specified by +``cryptokey_id``. + +Parameters: +''''''''''' + +- ``active``: "true\|false" ```` + +Responses: +'''''''''' + +- ``204 No Content``: The key with ``cryptokey_id`` is de/activated. +- ``422 Unprocessable Entity``:   The backend returns false on + de/activation. An error occurred. +   ``{"error": "Could not de/activate Key: :cryptokey_id in Zone: :zone_name"}`` + +DELETE +^^^^^^ + +This method deletes a key from ``zone_name`` specified by +``cryptokey_id``. + +Responses: +'''''''''' + +- ``200 OK``: The Key is gone. +- ``422 Unprocessable Entity``:   The backend failed to remove the key. +   ``{"error": Could not DELETE :cryptokey_id"}`` + +Data searching +============== + +URL: /api/v1/servers/localhost/search-data?q=:search\_term&max=:max\_results +---------------------------------------------------------------------------- + +**Note**: Authoritative only. + +Allowed methods: ``GET`` + +GET +^^^ + +Search the data inside PowerDNS for :search\_term and return at most +:max\_results. This includes zones, records and comments. The ``*`` +character can be used in :search\_term as a wildcard character and the +``?`` character can be used as a wildcard for a single character. + +Response body is an array of one or more of the following objects: + +For a zone: + +:: + + { + "name": "", + "object_type": "zone", + "zone_id": "" + } + +For a record: + +:: + + { + "content": "", + "disabled": , + "name": "", + "object_type": "record", + "ttl": , + "type": "", + "zone": ", + "zone_id": "" + } + +For a comment: + +:: + + { + "object_type": "comment", + "name": "", + "content": "" + "zone": ", + "zone_id": "" + } + + diff --git a/docs/authoritative/http-api/endpoint-zones.rst b/docs/authoritative/http-api/endpoint-zones.rst new file mode 100644 index 0000000000..6f6cf7caee --- /dev/null +++ b/docs/authoritative/http-api/endpoint-zones.rst @@ -0,0 +1,150 @@ +Zones endpoint ``/api/v1/servers/:server_id/zones`` +=================================================== +.. http:get:: /api/v1/servers/:server_id/zones + + Get all zones from the server. + + :query server_id: The name of the server + +.. http:post:: /api/v1/servers/:server_id/zones + + Creates a new domain. + + :query server_id: The name of the server + + **Authoritative Server only:** + + - ``dnssec``, ``nsec3narrow``, ``presigned``, ``nsec3param``, ``active-keys`` are OPTIONAL. + - ``dnssec``, ``nsec3narrow``, ``presigned`` default to ``false``. + + The server MUST create a SOA record. + The created SOA record SHOULD have serial set to the value given as ``serial`` (or 0 if missing), use the nameserver name, email, TTL values as specified in the PowerDNS configuration (``default-soa-name``, ``default-soa-mail``, etc). + These default values can be overridden by supplying a custom SOA record in the records list. + If ``soa_edit_api`` is set, the SOA record is edited according to the SOA-EDIT-API rules before storing it (also applies to custom SOA records). + + **TODO**: ``dnssec``, ``nsec3narrow``, ``nsec3param``, ``presigned`` are not yet implemented. + +.. http:get:: /api/v1/servers/:server_id/zones/:zone_id + + Returns zone information. + + :query server_id: The name of the server + :query zone_id: The id number of the :json:object:`Zone` + +.. http:delete:: /api/v1/servers/:server_id/zones/:zone_id + + Deletes this zone, all attached metadata and rrsets. + + :query server_id: The name of the server + :query zone_id: The id number of the :json:object:`Zone` + +.. http:patch:: /api/v1/servers/:server_id/zones/:zone_id + + .. note:: + + Authoritative only. + + Modifies present RRsets and comments. Returns ``204 No Content`` on success. + + :query server_id: The name of the server + :query zone_id: The id number of the :json:object:`Zone` + + Example client body for PATCH: + + .. code-block:: json + + { "rrsets": + [ + { + "name": "www.example.com.", + "type": "A", + "ttl": 3600, + "changetype": "REPLACE", + "records": + [ + { + "content": "192.0.2.15", + "disabled": false, + "set-ptr": false + } + ], + } + ] + } + + +.. http:put:: /api/v1/servers/:server_id/zones/:zone_id + + .. note:: + + Authoritative only. + + Modifies basic zone data (metadata). + + :query server_id: The name of the server + :query zone_id: The id number of the :json:object:`Zone` + + Allowed fields in client body: all except ``id`` and ``url``. + Returns ``204 No Content`` on success. + + Changing ``name`` renames the zone, as expected. + +.. http:put:: /api/v1/servers/:server_id/zones/:zone_id/notify + + .. note:: + + Authoritative only. + + Send a DNS NOTIFY to all slaves. + + :query server_id: The name of the server + :query zone_id: The id number of the :json:object:`Zone` + + Fails when zone kind is not ``Master`` or ``Slave``, or ``master`` and ``slave`` are disabled in the configuration. + Only works for ``Slave`` if renotify is on. + + Clients MUST NOT send a body. + +.. http:put:: /api/v1/servers/:server_id/zones/:zone_id/axfr-retrieve + + .. note:: + + Authoritative only. + + Retrieves the zone from the master. + + :query server_id: The name of the server + :query zone_id: The id number of the :json:object:`Zone` + + Fails when zone kind is not ``Slave``, or ``slave`` is disabled in PowerDNS configuration. + + +.. http:get:: /api/v1/servers/:server_id/zones/:zone_id/export + + .. note:: + + Authoritative only. + + Returns the zone in AXFR format. + + :query server_id: The name of the server + :query zone_id: The id number of the :json:object:`Zone` + +.. http:get:: /api/v1/servers/:server_id/zones/:zone_id/check + + .. note:: + + Not yet implemented + + Verify zone contents/configuration. + + Return format: + + .. code-block: json + + { + "zone": "", + "errors": ["error message1"], + "warnings": ["warning message1"] + } + diff --git a/docs/authoritative/http-api/zone-properties.rst b/docs/authoritative/http-api/zone-properties.rst new file mode 100644 index 0000000000..6f365c811c --- /dev/null +++ b/docs/authoritative/http-api/zone-properties.rst @@ -0,0 +1,74 @@ + :property integer serial: The SOA serial number + :property integer notified_serial: The SOA serial notifications have been sent out for + :property [str] masters: List of IP addresses configured as a master for this zone ("Slave" type zones only) + :property bool dnssec: Whether or not this zone is DNSSEC signed (inferred from presigned being true XOR presence of at least one cryptokey with active being true) + :property string nsec3param: The NSEC3PARAM record (not implemented) + :property bool nsec3narrow: Whether or not the zone uses NSEC3 narrow (not implemented) + :property bool presigned: Whether or not the zone is pre-signed (not implemented) + :property string soa_edit: The SOA-EDIT metadata item. MAY be set to change the ``SOA-EDIT`` zone setting. + :property string soa_edit_api: The SOA-EDIT-API metadata item + + + +Switching ``dnssec`` to ``true`` (from ``false``) sets up DNSSEC signing +based on the other flags, this includes running the equivalent of +``secure-zone`` and ``rectify-zone``. This also applies to newly created +zones. If ``presigned`` is ``true``, no DNSSEC changes will be made to +the zone or cryptokeys. **Note**: Authoritative only. + +**TODO**: ``dnssec``, ``nsec3narrow``, ``nsec3param``, ``presigned`` are +not yet implemented. + +- ``soa_edit_api`` MAY be set. If it is set, on changes to the contents + of a zone made through the API, the SOA record will be edited + according to the SOA-EDIT-API rules. (Which are the same as the + SOA-EDIT-DNSUPDATE rules.) If not set during zone creation, a + SOA-EDIT-API metadata record is created and set to ``DEFAULT``. (If + this record is removed from the backend, the default behaviour is to + not do any SOA editing based on this setting. This is different from + setting ``DEFAULT``.) **Note**: Authoritative only. + +- ``account`` MAY be set. Its value is defined by local policy. + **Note**: Authoritative only. + +- ``notified_serial``, ``serial`` MUST NOT be sent in client bodies. + **Note**: Authoritative only. + +- ``nameservers`` MAY be sent in client bodies during creation, and + MUST NOT be sent by the server. Simple list of strings of nameserver + names, including the trailing dot. Note: Before 4.0.0, names were + taken without the trailing dot. **Note**: Authoritative only. Not + required for slave zones. + +- ``servers``: list of forwarded-to servers, including port. **Note**: + Recursor only. + +- ``recursion_desired``: for ``Forwarded`` zones, if the RD bit should + be set. **Note**: Authoritative only. + +- ``rrsets``: list of DNS records and comments in the zone. **Note**: + Modifications are supported on Authoritative only. + +Please see the description for ``PATCH`` for details on the fields in +``RRset``, ``Record`` and ``Comment``. + +Notes: +'''''' + +Turning on DNSSEC with custom keys: just create the zone with ``dnssec`` +set to ``false``, and add keys using the cryptokeys REST interface. Have +at least one of them ``active`` set to ``true``. **TODO**: not yet +implemented. + +Changes made through the Zones API will always yield valid zone data, +and the zone will be properly "rectified" (**TODO**: not yet +implemented). If changes are made through other means (e.g. direct +database access), this is not guaranteed to be true and clients SHOULD +trigger rectify. + +Backends might implement additional features (by coincidence or not). +These things are not supported through the API. + +When creating a slave zone, it is recommended to not set any of +``nameservers``, ``records``. + diff --git a/docs/authoritative/http-api/zonemetadata.rst b/docs/authoritative/http-api/zonemetadata.rst new file mode 100644 index 0000000000..8ccfe31f77 --- /dev/null +++ b/docs/authoritative/http-api/zonemetadata.rst @@ -0,0 +1,19 @@ +Zone Metadata +============= + +.. warning:: + + Authoritative Server only. + +.. versionadded:: 4.1.0. + +.. json:object:: Metadata + + Represents zone metadata :doc:`domainmetadata` + + :property string kind: Name of the metadata + :property [string] metadata: Array with all values for this metadata kind. + + Clients MUST NOT modify ``NSEC3PARAM``, ``NSEC3NARROW``, ``PRESIGNED`` and ``LUA-AXFR-SCRIPT`` through this interface. + The server rejects updates to these metadata. + Modifications to custom metadata kinds starting with ``X-`` is allowed as well. diff --git a/docs/authoritative/security.rst b/docs/authoritative/security.rst new file mode 100644 index 0000000000..ac68690a7a --- /dev/null +++ b/docs/authoritative/security.rst @@ -0,0 +1,49 @@ +Security Settings +----------------- +PowerDNS has several options to easily allow it to run more securely. +Most notable are the :ref:`setting-chroot`, :ref:`setting-setuid` and :ref:`setting-setgid` options. + +For additional information on PowerDNS security, PowerDNS security incidents and PowerDNS security policy, see :ref:`securitypolicy`. + +Running as a less privileged identity +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +By specifying :ref:`setting-setuid` and :ref:`setting-setgid`, PowerDNS changes to this identity shortly after binding to the privileged DNS ports. +These options are highly recommended. +It is suggested that a separate identity is created for PowerDNS as the user 'nobody' is in fact quite powerful on most systems. + +Both these parameters can be specified either numerically or as real names. +Set these parameters immediately if they are not set! + +Jailing the process in a chroot +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :ref:`setting-chroot` option secures PowerDNS to its own directory so that even if it should become compromised and under control of external influences, it will have a hard time affecting the rest of the system. + +Even though this will hamper hackers a lot, chroot jails have been known to be broken. + +**Warning**: When chrooting The PowerDNS, take care that backends will be able to get to their files. Many databases need access to a UNIX domain +socket which should live within the chroot. It is often possible to +hardlink such a socket into the chroot dir. + +When running with master or slave support, be aware that many operating +systems need access to specific libraries (often ``/lib/libnss*``) in +order to support resolution of domain names! You can also hardlink +these. + +In addition, make sure that ``/dev/log`` is available from within the chroot. +Logging will silently fail over time otherwise (on logrotate). + +The default PowerDNS configuration is best chrooted to ``./``, which boils down to the configured location of the controlsocket. + +This is achieved by adding the following to pdns.conf: ``chroot=./``, and restarting PowerDNS. + +Security Considerations +----------------------- +In general, make sure that the PowerDNS process is unable to execute commands on your backend database. +Most database backends will only need SELECT privilege. +Take care to not connect to your database as the 'root' or 'sa' user, and configure the chosen user to have very slight privileges. + +Databases empathically do not need to run on the same machine that runs PowerDNS! +In fact, in benchmarks it has been discovered that having a separate database machine actually improves performance. + +Separation will enhance your database security highly. Recommended. + diff --git a/docs/common/api/configsetting.rst b/docs/common/api/configsetting.rst new file mode 100644 index 0000000000..2211dd0892 --- /dev/null +++ b/docs/common/api/configsetting.rst @@ -0,0 +1,20 @@ +ConfigSetting +============= + +.. json:object:: ConfigSetting + + Represents a configuration item (as found in :doc:'../settings') + + :property string type: set to "ConfigSetting" + :property string name: The name of this setting (e.g. 'webserver-port') + :property string value: The value of setting ``name`` + + **Example:** + + .. code-block:: json + + { + "name": "webserver-port", + "type": "ConfigSetting", + "value": "8082" + } diff --git a/docs/common/api/dataformat.rst b/docs/common/api/dataformat.rst new file mode 100644 index 0000000000..a8a892c130 --- /dev/null +++ b/docs/common/api/dataformat.rst @@ -0,0 +1,144 @@ +Data format +=========== + +The API accepts and emits JSON. +The ``Accept:`` header determines the output format. An unknown value or +``*/*`` will cause a ``400 Bad Request``. + +All text is UTF-8 and HTTP headers will reflect this. + +Data types: + +- empty fields: ``null`` but present +- Regex: implementation defined +- Dates: ISO 8601 + +General Collections Interface +----------------------------- + +Collections generally support ``GET`` and ``POST`` with these meanings: + +GET +^^^ + +Retrieve a list of all entries. + +The special ``type`` and ``url`` fields are included in the response +objects: + +- ``type``: name of the resource type +- ``url``: url to the object + +Response format: + +:: + + [ + obj1 + [, further objs] + ] + +Example: + +.. code-block:: json + + [ + { + "type": "AType", + "id": "anid", + "url": "/atype/anid", + "a_field": "a_value" + }, + { + "type": "AType", + "id": "anotherid", + "url": "/atype/anotherid", + "a_field": "another_value" + } + ] + +POST +^^^^ + +Create a new entry. The client has to supply the entry in the request body, in JSON format. +``application/x-www-form-urlencoded`` data MUST NOT be sent. + +Clients SHOULD not send the 'url' field. + +Client body: + +:: + + obj1 + +Example: + +.. code-block:: json + + { + "type": "AType", + "id": "anewid", + "a_field": "anew_value" + } + +REST +---- + +- GET: List/Retrieve. Success reply: ``200 OK`` +- POST: Create. Success reply: ``201 Created``, with new object as body. +- PUT: Update. Success reply: ``200 OK``, with modified object as body. For some operations, ``204 No Content`` is returned instead (and the modified object is not given in the body). +- DELETE: Delete. Success reply: ``200 OK``, no body. + +not-so-REST +----------- + +For interactions that do not directly map onto CRUD, we use these: + +- GET: Query. Success reply: ``200 OK`` +- PUT: Action/Execute. Success reply: ``200 OK`` + +Action/Execute methods return a JSON body of this format: + +.. code-block:: json + + { + "message": "result message" + } + +Authentication +-------------- + +The PowerDNS daemons accept a static API Key, configured with the :ref:`setting-api-key` option, which has to be sent in the ``X-API-Key`` header. + +Errors +------ + +Response code ``4xx`` or ``5xx``, depending on the situation. Never return ``2xx`` for an error! + +- Invalid JSON body from client: ``400 Bad Request`` +- JSON body from client not a hash: ``400 Bad Request`` +- Input validation failed: ``422 Unprocessable Entity`` + +Error responses have a JSON body of this format: + +.. code-block:: json + + { + "error": "short error message", + "errors": [ + { }, + ] + } + +Where ``errors`` is optional, and the contents are error-specific. + +Common Error Causes +^^^^^^^^^^^^^^^^^^^ + +400 Bad Request +~~~~~~~~~~~~~~~ + +1. The client body was not a JSON document, or it could not be parsed, or the root element of the JSON document was not a hash. +2. The client did not send an ``Accept:`` header, or it was set to ``*/*``. +3. For requests that operate on a zone, the ``zone_id`` URL part was invalid. + To get a valid ``zone_id``, list the zones with the ``/api/v1/servers/:server_id/zones`` endpoint. diff --git a/docs/common/api/endpoint-api.rst b/docs/common/api/endpoint-api.rst new file mode 100644 index 0000000000..8cc87626f2 --- /dev/null +++ b/docs/common/api/endpoint-api.rst @@ -0,0 +1,38 @@ +API root endpoints +================== + +.. http:get:: /api + + Version discovery endpoint. + + **Example response:** + + .. sourcecode:: json + + [ + { + "url": "/api/v1", + "version": 1 + } + ] + +.. http:get:: /api/v1 + + APIv1 root endpoint. + Gives some information about the current API. + + Not yet implemented: + + - ``api_features`` + - ``servers_modifiable`` + - ``oauth`` + + **Example response**: + + .. sourcecode:: json + + { + "server_url": "/api/v1/servers{/server}", + "api_features": [] + } + diff --git a/docs/common/api/endpoint-logging.rst b/docs/common/api/endpoint-logging.rst new file mode 100644 index 0000000000..e81b905c29 --- /dev/null +++ b/docs/common/api/endpoint-logging.rst @@ -0,0 +1,10 @@ +Log endpoint +============ + +.. http:get:: /api/v1/servers/:server_id/search-log?q=:search_term + + Query the log, filtered by ``search_term``. + Returns a single JSON object with a single array of strings. + + :query server_id: The name of the server + :query search_term: The string to search for diff --git a/docs/common/api/endpoint-servers-config.rst b/docs/common/api/endpoint-servers-config.rst new file mode 100644 index 0000000000..3fd1f75324 --- /dev/null +++ b/docs/common/api/endpoint-servers-config.rst @@ -0,0 +1,74 @@ +Configuration endpoint +====================== + +.. http:get:: /api/v1/servers/:server_id/config + + Returns all :json:object:`ConfigSetting` for a single server + + :query server_id: The name of the server + +.. http:post:: /api/v1/servers/:server_id/config + + .. note:: + Not implemented + + Creates a new config setting. + This is useful for creating configuration for new backends. + + :query server_id: The name of the server + + +.. http:get:: /api/v1/servers/:server_id/config/:config_setting_name + + Retrieve a single setting + + :query server_id: The name of the server + :query config_setting_name: The name of the setting to retrieve + + .. note:: + only the :ref:`setting-allow-from` configuration setting can be retrieved + +.. http:put:: /api/v1/servers/:server_id/config/:config_setting_name + + Change a single setting + + :query server_id: The name of the server + :query config_setting_name: The name of the setting to change + + .. note:: + only the :ref:`setting-allow-from` configuration setting can be changed + + **Example request** + + .. sourcecode:: http + + PUT /api/v1/servers/localhost/config/allow-from HTTP/1.1 + Host: localhost:8082 + User-Agent: curl/7.54.1 + Accept: application/json + X-Api-Key: secret + Content-Type: application/json + Content-Length: 48 + + { "name": "allow-from", "value": ["127.0.0.0/8"] } + + **Example response** + + .. sourcecode:: http + + HTTP/1.1 200 OK + Access-Control-Allow-Origin: * + Connection: close + Content-Length: 48 + Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline' + Content-Type: application/json + Server: PowerDNS/0.0.g00799130f + X-Content-Type-Options: nosniff + X-Frame-Options: deny + X-Permitted-Cross-Domain-Policies: none + X-Xss-Protection: 1; mode=block + + {"name": "allow-from", "value": ["127.0.0.0/8"]} + + + diff --git a/docs/common/api/endpoint-servers.rst b/docs/common/api/endpoint-servers.rst new file mode 100644 index 0000000000..65a2c7a51f --- /dev/null +++ b/docs/common/api/endpoint-servers.rst @@ -0,0 +1,12 @@ +Server endpoint +=============== + +.. http:get:: /api/v1/servers + + :json:object:`Server` collection access. + +.. http:get:: /api/v1/servers/:server_id + + Returns a single :json:object:`Server` + + :query server_id: The name of the server. diff --git a/docs/common/api/endpoint-statistics.rst b/docs/common/api/endpoint-statistics.rst new file mode 100644 index 0000000000..b7770cb1cd --- /dev/null +++ b/docs/common/api/endpoint-statistics.rst @@ -0,0 +1,17 @@ +Statistics endpoint +=================== + +.. http:get:: /api/v1/servers/:server_id/statistics + + Query PowerDNS internal statistics. + Returns a list of :json:object:`StatisticItem` elements. + + The names and meaning of these items are described :ref:`here `. + + :query server_id: The name of the server + + **Example response:** + + .. code-block:: json + + [{"name": "all-outqueries", "type": "StatisticItem", "value": "341"}, {"name": "answers-slow", "type": "StatisticItem", "value": "0"}, {"name": "answers0-1", "type": "StatisticItem", "value": "0"}, {"name": "answers1-10", "type": "StatisticItem", "value": "0"}, {"name": "answers10-100", "type": "StatisticItem", "value": "0"}, {"name": "answers100-1000", "type": "StatisticItem", "value": "0"}, {"name": "auth4-answers-slow", "type": "StatisticItem", "value": "200"}, {"name": "auth4-answers0-1", "type": "StatisticItem", "value": "13"}, {"name": "auth4-answers1-10", "type": "StatisticItem", "value": "1"}, {"name": "auth4-answers10-100", "type": "StatisticItem", "value": "68"}, {"name": "auth4-answers100-1000", "type": "StatisticItem", "value": "19"}, {"name": "auth6-answers-slow", "type": "StatisticItem", "value": "0"}, {"name": "auth6-answers0-1", "type": "StatisticItem", "value": "0"}, {"name": "auth6-answers1-10", "type": "StatisticItem", "value": "0"}, {"name": "auth6-answers10-100", "type": "StatisticItem", "value": "0"}, {"name": "auth6-answers100-1000", "type": "StatisticItem", "value": "0"}, {"name": "cache-entries", "type": "StatisticItem", "value": "124"}, {"name": "cache-hits", "type": "StatisticItem", "value": "0"}, {"name": "cache-misses", "type": "StatisticItem", "value": "0"}, {"name": "case-mismatches", "type": "StatisticItem", "value": "0"}, {"name": "chain-resends", "type": "StatisticItem", "value": "0"}, {"name": "client-parse-errors", "type": "StatisticItem", "value": "0"}, {"name": "concurrent-queries", "type": "StatisticItem", "value": "1"}, {"name": "dlg-only-drops", "type": "StatisticItem", "value": "0"}, {"name": "dnssec-queries", "type": "StatisticItem", "value": "0"}, {"name": "dnssec-result-bogus", "type": "StatisticItem", "value": "0"}, {"name": "dnssec-result-indeterminate", "type": "StatisticItem", "value": "0"}, {"name": "dnssec-result-insecure", "type": "StatisticItem", "value": "0"}, {"name": "dnssec-result-nta", "type": "StatisticItem", "value": "0"}, {"name": "dnssec-result-secure", "type": "StatisticItem", "value": "9"}, {"name": "dnssec-validations", "type": "StatisticItem", "value": "9"}, {"name": "dont-outqueries", "type": "StatisticItem", "value": "0"}, {"name": "edns-ping-matches", "type": "StatisticItem", "value": "0"}, {"name": "edns-ping-mismatches", "type": "StatisticItem", "value": "0"}, {"name": "failed-host-entries", "type": "StatisticItem", "value": "0"}, {"name": "fd-usage", "type": "StatisticItem", "value": "25"}, {"name": "ignored-packets", "type": "StatisticItem", "value": "0"}, {"name": "ipv6-outqueries", "type": "StatisticItem", "value": "0"}, {"name": "ipv6-questions", "type": "StatisticItem", "value": "0"}, {"name": "malloc-bytes", "type": "StatisticItem", "value": "0"}, {"name": "max-mthread-stack", "type": "StatisticItem", "value": "0"}, {"name": "negcache-entries", "type": "StatisticItem", "value": "1"}, {"name": "no-packet-error", "type": "StatisticItem", "value": "0"}, {"name": "noedns-outqueries", "type": "StatisticItem", "value": "0"}, {"name": "noerror-answers", "type": "StatisticItem", "value": "0"}, {"name": "noping-outqueries", "type": "StatisticItem", "value": "0"}, {"name": "nsset-invalidations", "type": "StatisticItem", "value": "0"}, {"name": "nsspeeds-entries", "type": "StatisticItem", "value": "26"}, {"name": "nxdomain-answers", "type": "StatisticItem", "value": "0"}, {"name": "outgoing-timeouts", "type": "StatisticItem", "value": "200"}, {"name": "outgoing4-timeouts", "type": "StatisticItem", "value": "200"}, {"name": "outgoing6-timeouts", "type": "StatisticItem", "value": "0"}, {"name": "over-capacity-drops", "type": "StatisticItem", "value": "0"}, {"name": "packetcache-entries", "type": "StatisticItem", "value": "0"}, {"name": "packetcache-hits", "type": "StatisticItem", "value": "0"}, {"name": "packetcache-misses", "type": "StatisticItem", "value": "0"}, {"name": "policy-drops", "type": "StatisticItem", "value": "0"}, {"name": "policy-result-custom", "type": "StatisticItem", "value": "0"}, {"name": "policy-result-drop", "type": "StatisticItem", "value": "0"}, {"name": "policy-result-noaction", "type": "StatisticItem", "value": "0"}, {"name": "policy-result-nodata", "type": "StatisticItem", "value": "0"}, {"name": "policy-result-nxdomain", "type": "StatisticItem", "value": "0"}, {"name": "policy-result-truncate", "type": "StatisticItem", "value": "0"}, {"name": "qa-latency", "type": "StatisticItem", "value": "0"}, {"name": "questions", "type": "StatisticItem", "value": "0"}, {"name": "real-memory-usage", "type": "StatisticItem", "value": "3502080"}, {"name": "resource-limits", "type": "StatisticItem", "value": "13"}, {"name": "security-status", "type": "StatisticItem", "value": "0"}, {"name": "server-parse-errors", "type": "StatisticItem", "value": "0"}, {"name": "servfail-answers", "type": "StatisticItem", "value": "0"}, {"name": "spoof-prevents", "type": "StatisticItem", "value": "0"}, {"name": "sys-msec", "type": "StatisticItem", "value": "2613"}, {"name": "tcp-client-overflow", "type": "StatisticItem", "value": "0"}, {"name": "tcp-clients", "type": "StatisticItem", "value": "0"}, {"name": "tcp-outqueries", "type": "StatisticItem", "value": "0"}, {"name": "tcp-questions", "type": "StatisticItem", "value": "0"}, {"name": "throttle-entries", "type": "StatisticItem", "value": "0"}, {"name": "throttled-out", "type": "StatisticItem", "value": "0"}, {"name": "throttled-outqueries", "type": "StatisticItem", "value": "0"}, {"name": "too-old-drops", "type": "StatisticItem", "value": "0"}, {"name": "udp-in-errors", "type": "StatisticItem", "value": "0"}, {"name": "udp-noport-errors", "type": "StatisticItem", "value": "4163"}, {"name": "udp-recvbuf-errors", "type": "StatisticItem", "value": "0"}, {"name": "udp-sndbuf-errors", "type": "StatisticItem", "value": "0"}, {"name": "unauthorized-tcp", "type": "StatisticItem", "value": "0"}, {"name": "unauthorized-udp", "type": "StatisticItem", "value": "0"}, {"name": "unexpected-packets", "type": "StatisticItem", "value": "0"}, {"name": "unreachables", "type": "StatisticItem", "value": "0"}, {"name": "uptime", "type": "StatisticItem", "value": "96590"}, {"name": "user-msec", "type": "StatisticItem", "value": "2012"}] diff --git a/docs/common/api/server.rst b/docs/common/api/server.rst new file mode 100644 index 0000000000..10245939e3 --- /dev/null +++ b/docs/common/api/server.rst @@ -0,0 +1,35 @@ +Server +====== +.. json:object:: Server + + An object representing a single PowerDNS server. + In the built-in API, only one Server exists (called "localhost"). + + pdnsmgrd and pdnscontrol MUST NOT return “localhost”, but SHOULD return + other servers. + + :property string type: Set to "Server" + :property string id: The id of the server, "localhost" + :property string daemon_type: "recursor" for the PowerDNS Recursor and "authoritative" for the Authoritative Server + :property string version: The version of the server software + :property string url: The API endpoint for this server + :property string config_url: The API endpoint for this server's configuration + :property string zones_url: The API endpoint for this server's zones + + **Example**: + + .. code-block:: json + + { + "type": "Server", + "id": "localhost", + "url": "/api/v1/servers/localhost", + "daemon_type": "recursor", + "version": "4.1.0", + "config_url": "/api/v1/servers/localhost/config{/config_setting}", + "zones_url": "/api/v1/servers/localhost/zones{/zone}", + } + + Note: the servers collection is read-only, and the only allowed returned server is read-only as well. + On a pdnscontrol server, the servers collection is read-write, and the returned server resources are read-write as well. + Write permissions may depend on the credentials you have supplied. diff --git a/docs/common/api/statisticitem.rst b/docs/common/api/statisticitem.rst new file mode 100644 index 0000000000..fdc5b650c7 --- /dev/null +++ b/docs/common/api/statisticitem.rst @@ -0,0 +1,10 @@ +StatisticItem +============= + +.. json:object:: StatisticItem + + Represents a single statistic item (as found in :doc:'../metrics') + + :property string type: set to "StatisticItem" + :property string name: The name of this item + :property string value: The value of this item diff --git a/docs/common/api/zone.rst b/docs/common/api/zone.rst new file mode 100644 index 0000000000..6fa1fa1a13 --- /dev/null +++ b/docs/common/api/zone.rst @@ -0,0 +1,59 @@ +Zones in the API +================ + +Zone +---- + +A Zone object represents an authoritative DNS Zone. + +A Resource Record Set (below as "RRset") are all records for a given name and type. + +Comments are per-RRset. + +.. json:object:: Zone + + Represents a configured zone in the PowerDNS server. + + :property string id: Opaque zone id (string), assigned by the Server. Do not interpret. Guaranteed to be safe for embedding in URLs. + :property string name: Name of the zone (e.g. "example.com.") **must** have a trailing dot + :property string type: Set to "Zone" + :property string url: API endpoint for this zone + :property string kind: Zone kind, one of "Native", "Master", "Slave" on the Authoritative Server. One of "Native", "Forwarded" on the Recursor. + :property [RRSet] rrsets: RRSets in this zone + + .. include:: ../../http-api/zone-properties.rst + +RRSet +----- + +.. json:object:: RRSet + + This represents a Resource Record set (all record with the same name and type). + + :property string name: Name for record set (e.g. "www.powerdns.com.") + :property string type: Type of this record (e.g. "A", "PTR", "MX") + :property integer ttl: DNS TTL of the records, in seconds. MUST NOT be included when ``changetype`` is set to "DELETE". + :property string changetype: MUST be added when updating the RRSet. Must be ``REPLACE`` or ``DELETE``. With ``DELETE``, all existing RRs matching ``name`` and ``type`` will be deleted, including all comments. With ``REPLACE``: when ``records`` is present, all existing RRs matching ``name`` and ``type`` will be deleted, and then new records given in ``records`` will be created. If no records are left, any existing comments will be deleted as well. When ``comments`` is present, all existing comments for the RRs matching ``name`` and ``type`` will be deleted, and then new comments given in ``comments`` will be created. + :property [Record] records: All records in this RRSet. When updating Records, this is the list of new records (replacing the old ones). Must be empty when ``changetype`` is set to ``DELETE``. An empty list results in deletion of all records (and comments). + :property [Comment] comments: List of :json:object:`Comment`. Must be empty when ``changetype`` is set to ``DELETE``. An empty list results in deletion of all comments. ``modified_at`` is optional and defaults to the current server time. + +Record +------ + +.. json:object:: Record + + The Record object represents a single record in an :json:object:`RRSet`. + + :property string content: The content of this record + :property bool disabled: Whether or not this record is disabled + :property bool set-ptr: If set to true, the server will find the matching reverse zone and create a PTR there. Existing PTR records are replaced. If no matching reverse :json:object:`Zone`, an error is thrown. Only valid in client bodies, only valid for A and AAAA types. Not returned by the server. + + +Comment +------- + +.. json:object:: Comment + + :property string content: The actual comment + :property string account: Name of an account that added the comment + :property integer modified_at: Timestamp of the last change to the comment diff --git a/docs/common/favicon.ico b/docs/common/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..4b0eae3a4ccb5a5afdc3b424a06a1a1400fabd46 GIT binary patch literal 1406 zc-muNU<5(|0R}M0U}azs1JW8m3=&cRVnzlIh$JHe0wA&1U;oDN|Nno6{^Oq+3U|C` zU~G8I5V+zE!~FAK7~X&X%h0g@Bg6UUzZe`BykbzC@SNfP``--v@Bd&hobiG|u;VF1 z;)Zt&qhJ(_g5eLC7`eF_nYg&QnVERmxLKI^Sb=~`07&rh0|`z}5FbHsvx7)R5W&s^ zBm|jQSOu7w*acWwn7DXYxjC3Pd3YF^82NcPnYh>l1UbOw@xj$&n8%1JFUZ6xz{AeO W&LaRckDrx|gH-yWmFtnl!ZIEy9bAdJHg%EHMqOG6Wrb1Ex0=*xVr=o?hxEzikUxCYXRN8x~r?s zy=U)l-zp*$3SGYAAT@%i&*=~dw#coEk{Ow&ch-ps|_(8(0!?(WWDX=m+hZ0KOhVDDs}b-{}V z0uh6xM1@p6vd?ooeN^|`hqoFhGJIvsWLPprg=N7)QHUW-u)loAz_78U*J}+Fvp*HC zY*DXlC92e@Z1spz)vD3MY*PJVnxt!z1Ocl(A})NNAw`k2(%QH#z_bq2m~D&2v^8Dk zuW5GBmBDrBoBQzH4_Q=6mEiG zg{riPnOUfej7;}`|NY00&|j`v>z!^Gifa}>G$ih*qLS3s*r;OCx>j$%1QRAq0@KeV zO^$}DT#?L#7ZdRM`uZyzmF(52JzMfNbL0p5{jz;3Bwp+2zX0{xzwJ2dQSXdcX zPSVBQ^!hPI!uExjeN{-bZbG0ayy^oQ4;8#KuO-P2t}rlhi2uF0Vf0}@kS^|o^TK0i zmOYafT{yxwl@yp%!MZoW`5bbLf>lEo2X|@_c(;d|K<>Mh7RRq)d*c`;@0iM=@Z;oRO15Ffl!iEL}1eyd@}mbaaGrvDT{K zdoY0;vV1Cb)PpRhL?a-u#bLcv^&S}sC%=UoyE}8TSQ$euC2S*Le6iks-_XFqn6pgC z>!J8vMWx8Z3o%4EfKk7vE9>HPxmG`Kachgwz$-_n<~^&UqoXe7D+k^mKSJ!t$jGiJ zEcynCXO5^r(#L=O$c=42{18GIk%bF0<`O_bX;R=gvL=O!W^qK7z7-(tY1?&ExP_5NhoqEhVM>a4P3C z|K)kHQsb*g0m{UI7E1<#|Lv@VrGUchKM&rK8r@EopOuv<;Naj*c^oi-f_{EIwS|R! zYHDix>NF`$(Ga@-df?NYFP&EfZ{)eef-N>Q!bvIVvL2Il)$cCBQRx1@^}x0ep(37n z>tWjnkV0Zeo$`UnIVv*Wwd+|vO|SdZLW4lBcX={7(E3ZEbj?Oymp?$Md{brFPhonF zv*$gUwW3*>nZ-VIEO=JU+}TM<=uBCY?@~z=?M+&?oC(WOp@T-h`JeXCb#--fvL|00 z@xwBK_shx2&1Gk2|LXF*d8VPI{r>isDpDCKOvIpZCD>*Y83ZB|kN!8ycI4{n%EI2u ziqMY{yUXW-C}V3|O^SoiuzCgp{k`bCY(adp&zlY-e}0b+)uf9(35Nm;2(E<}LXoaq zgo+V2Hdt?SykIsS@-Rrh)A*VI^Z+$>84DT{g39;r-+#Zp`fRm1?yi@Vl<>ps+@Wpt z+qJ^Cy<)LvA!f0f#|B;CWo2cR*jzfc>r9RQNF;~tdEAMb@O`K$pm*Wrv{w=IYeE6$feq$7i-@Ts?k!E9?}HJmz>;iAG&W?Kn4Fga6$m{Ch77|y$FZV z0L5sY!&`fsX@&7y^y}CK?&S3JKVTe~75FQLteWALs_ORI$GX66d2+%9mSNS*b>0Gqx~A zC?i0&a=f4-4D(#vt4WTnI&S*;!EJ~9+V1;IPoUUZJ<(5!Q#m}8{>LS0 zaPoQllaImid3n>Lr@&U^+qin}rVd5$W8Bc5yS7oQx~dj9VyGaJZIXji+_>Q&K!2ES z;{0EYe-FicbuB>YjyL=1$ek0|?fqco_t3e8+5PeU0@b=E$1|Bi*YkAnRqW?7N>ob= z`?ml4q5r{^=|q@tBKgtjsqx(z)EZKRt$$wp^kVvl0EPq6d(zVTRUv-I_EqIo&P&$m|3=#QVmh)g6jc0XOqARO`lU{ixZF=6 zqR8Q0AwUo9bsEj&{`G29_F~qh9MCcB^NQ!(cL}63pq$i*$Ue?ae!EG#U3+2pF~M$9|%B#hHbLfvks>jg6S@_vcfyu>RjsX;{dS zg}*`(zcysxxHhifqrgB^`I`bG_x$$W)~oOC&Ov#(VpKol-+?$Dv&zUcMrU`O7M8?x)FFUB^roPv;kneN`+ui0ne;o)(9b?w}UecxyFXZ~-k zh~V4F;^Jb{91IhJGk=N}U22Sa|A67XTE@laS-}0 zyKdxb7OhO*ih_knEbdMg+hw)59)k<1{%wa5nLXUz&aeb}dU|H}UARQkFR#1l>*vK6 z?s%u`T;BrP-cRXr@AG_I77B>YDa9+lq=ZD+Bha?rJb81I^8}~!1Q->{I)X*Qkf^`n z;h9wE4KK#)ecj=I$CgvB!E_;+0`HCUu2$5DnbCOot~|&2DERe&|6bpbz~b^48RK?s zt_{_Ohy0GiCJ8KF9Et!iNI!uFvq?O%HN|ykA|Hb~O*+^Id}CA?h`-I&%Xr5&NKa2s zI*496!y&dIFT~ppIE6_>hjacl^T&Z;Uq1NC1u$R&e=GsO(J!h&q6>VyuXWRlHcciB zf(Rl==n+tGSo*n=D1d6%?Ki6w?zl;}xo?MMY4+q-?e}?__2k+*jl~_I?tAn1`6LLy zmlFi6cXH-(pg)3KQ3<|gL%-)k5>FyeShEL{S-9RmhGPj-vN;_|>4oF4qQu%v z$5Y$<`vLgl%#l9ct8PDN`2xzXtfVy~Bp7xa*>|dEKN2r;d~}&YZC#78TW?EnBvIm? zSy`dh>-FQKEFk1Buc?ubs(S&5WPv}Akv@mjzkjKin-2pu@YOY|P@HBYA0A1MJAFYC z>bSKi;9x_E%%~vOKBTQE3`Lb9m1dOO0P7NGtO&q9+4fZz7Z>Syv&+kr#8UT!4WlM_>_@zc z0Mc1mTklqcP_-{CEz!80uMTQm#UKNHV4}w;P%UP2_44*_S>Hcr?vezrAU8?4ZzWe% z1QG;#51lUJMty&-X6fLv<-gMXgYPQWbMqlBRXhw>1|2;jw-Cxqi|rcAagX2WQZ-)M zcna1aThL!lB-_;{>Whd`6P9|U&f#%wZ91&zr~-m(F6J1Bv<_%cDE!W2U?EkV?OIFm z9tZkwKMG zX;m{La;Mb+ae$bS(O#1zmJ;x)G6zn4%l-8^$YIB$eq;gJ2)7SnHa0eDwj)Y~T-m5P ze{vXe39HDM2x3tWdej{JzKxVbHq?vU@@bsy3#r-6j(OHSq+k1~*~Y`MgWc^9XDdkw z3~yB$B1#y48qF1C&5QE$f2bJhC@9=!g;|fU5?>*>bu9?feZ!Meq{5)6E!>9+BbRb` zeY|R7gS%?;xGKB_q@P;bUq&X%#lV30Kcs|7Gjwuc#8^g21sAeZi$X5+;Ni?fHYE=b z#anFnebViHsfk?haHJFaQIU9zQ!fB#*hK!XSNA*@ZT+b^Ig{Ftw`=yjF)NWMa3T3* z60uC`mr@kK*{MGJ^ptNo8yXt^7@vvJw6)aHUV;MVf@GCS-i93!L%4DHsL6F49@|(B zz_anACSCH~KdYqNAfx0*SkPGE9CY zG^m1(Por#j(eqU$u=|$1Cz~tku%&~Q2?)yb(YMc}B+1c8d3bn|fdB)5+0CZk%lX?^ z4!Z>cexGz_oOJ+yHtaaiY#*fnq{^I@Yj#nbuY%-g3EVjhzgjjJ)V1-JQ=1E1TwM(TEHB*No(sx73Ty-Xr9Lw< z?Wn#N6BD!M>E`eO`Q05TxW#xXy%xV$91l150I<&j1wi?9ER=M^~4AtJB@ytn2ps#59(9sZARa z-J)0*JKYqqGUkqW@w4?31Z*)zaO8+6&5{^6Rt4;)2si-#z_&L-1qrovbY!Z0#T8S^ z@9EJ)vlTh0{4r?p?OCH*YmosfN(uzRagk@YUBy`KbZ0yyEowBM9xKFk0Wpl{QuO6N z+}&NNU#)L!(04r@WRb}i?*ON4A%vSE9pX$7oP+=e2M4CWcc(i1a@lLo>2*t0R*o)& zq9`H~F`xROEI>4pE5x%6Qj}bTuHZ2HcBC8if6Z8 zaeaNljU|+rlGR`&rf$%X50y+B!};X+_%5&d)y`nloTf0V4un~uobJv!b~EWLQh4+ zB>=(*Ey77y0%Itd6E~cf=fu_cO`B8*bI73&p+mZ)uS_m$h|30(K3iKugL2zgcy6IW z<;9g-cYp{KNX%rv$t&OJ`K7I@#SO^fpN%CMyMT-f z6Zos@dn2a+hfk^Y5sTBF0lyoI4A zHxZZl!15_!Qq;^+&o3CBmDt!*QWh9Ac!jUHO0~2!ZES4TG}$SdsE{>trN97H?=%7B zcK#rN5Hc8w##Iv827#E&CUES{%qR|3Bt%3+7VZuX4jO81-8we{CCmJKXx5?YS8Pxf zj&u-)|BWn+sH&@Xv`>Y)cWzKuG)+!UA~NW8{TUlJ&*AfCHy!i^Ix1Z@Ay<$XH)n=|WYpAl`f4vW5={37I_)1svm_t*yKU z^$L^Fji++aUO<Vr*3wX-m1VfvWXVjX@51GMZ!>m~oX71d zoltep6(A^Rh%l)g6dce0T>XOt`*Mib(Ada&V%bt&9)1V=W)-0mS;%=8DnX`9 z{^Q(r!OB&VCItz5Km`He4c9n|_CZWvW*q&Q=e-$-7cd zuuTwE>T8!MZ_}jE@G>#|@*wNwKHC7OPEvH_?xZ)5ThyL;==tOU{d#MIQm;*1cCxas@ejr>|?%2ULga+<=sYi;ov|LUM= zovMt5UqkzRho87!;X!jHcGU&efn1UAKeVH9;SBc=dyUIs8QF;RWh4@ulBZe991HR7 zlx`YBs2pOL&sdv%m?W{9{#gFk^aPPMWh@xLHwNs8E5n(LTjD5D(nPz?iN%7q%}u>8 zQi)Y=tLy9Q#W=U6r4*JbD(Gax4TXh$InqHr{vUo*PD5N=T+~D!{SwmuVZi@#y?dBp9Tcvpi*VYRp`PofaQ8}sHRoC>6tMdT)W z`sJZg_owBlU8m+UXCwpXwy=m8PE!DPi;&OZ9^{(H0yd{0 zARzVm?1i*X!2JzEr<5oE?@Uiwd1sfbnIqYN3Fc#$=!3~_r6J^@zC-i=G2hNpu9DcA zPGEzENtoK+dos~+89LR%_wWh@d-4XC@ck#IT83wYG+@0I->-$roQB{Xou6jo)%Z^q z-dwDC=+tk}{3MFGbsp^XTcpPQ-C~l4I)&Uh@sB>E?fvD}bX1w;H@w=FbY4Pa^EjqV z2G4IMEVze6{l_jt>*;^w^@^xYyoXYxLSE!JHblMA3xKEHH9A^LM@x*a@&CNK|49(} zn*7DHOB*$@By<1N@RfQ=(^G&BvU%L)rz8UGc?XP`MES89_34oin_XmHv;X zGKme|ToN3jWCza(0s>1k44Kmf=g44*bA$5z*Y;W=rPQdlkmf-b4xA8+i;LGeJnm*y z`n~+8A=r9URTUN6_*T$=oi4bQt>Yr7J+HaDl*e?A{%*}Ij|9Qv^N>|Lv{ zO}WGagXsTq-kNP%ddy@#g)dR)*EwINK)dO&i^!@W)=?RtNK%sh=2g3WH58S2{X&33 zQO2lVM1ZTvsI^t1ujDP2&XL5S3#VB~!gBdcB(oHmiFG9huY*Eb+*&Kl^vj9ju}NTK zwZ`AUpT~^qkbW-2EE>l8@}*1W<8OdWU)M3=>J(J8a$%r0-?K!I-Qw$`{zf=ULk%B@ zcW>r%=@;;D*keq#tjQk9uL4An`m!S0Iw_qX5NO!=;msIF9PnJ?tg+1kN*9XmZ9s)= zm~aC5`1qP?xK!tJY^iR;xLI7OY;A3KK9?FgJ3B)@AIHWbG3$p!11G8=4UbGf>RQ3{ zUkWK#kgA3TEv0;Rx&tIr(JT%=n^p45db=~M(x|nyHG1#c{n`*^u18@IW5lKqN(kz- z=4($#hj9+uOqU9p#iLFrj~3IMwFqo2Vh98pTEdBgX6Z2VE_tuX9-rN}o6_JVahO|E zl5>StHzg9}v&s)0Jd4f$`f~`t`i#Y-@(2P#oX}E_9aM7(urkY@$crwnh_9=Hv6A5? zRoz<}0 z*Pgc!wzn<=!-Y*2@f(q}ybHTcgA$y z`g%@=QR<0b3VCjQo$j+;rgq~5HV2ohZVLoq#3Q1xJqHJ)lnX5hVPTRI=4J(4Wh6en zK{iw+1pJ35%zkkwztWa>lWHc_e)ts;La5w=keLW7r^0<~9+vN-V+Csn5$`rPmoVB6 zNu45T8!X_5QQ{%~&*LdKn-d2i9V0=dWUU612>QiS95^B?y$K`D&O(yX(xu=IhLtQ}8IPx~bkA@pjoOPw1cM7eW_?a8qibSzl2CaG)f zh~S9GlF=jdYLQLN&F4FaDl03KC|I0Nt6P!C3kB_{ppo!rfU=dzM%d%LOUVQw^)qSK z83-+~f8p2SNzc9B-S0gXq@;;YNx?LlKiPHRhTO7TXJtMrxU9h~{pv*q1J(8H&@}H^X zQh<3weine0wI8G-Z~qB4g)x%dnKd;GBvK7G6;4i0p_EluvTACJzk-nY|0FS_oQuGQ z^-DPhw=+5Jh%UF-uDM((t8H!ENWCPYLKF~spVilJY*VoBVB*1idRfnhu7$shp)M1_#XX zsmLoff42_C;f1hN+`csM_QlpEgo4(9+V@xg5`>Cs{o*9m(>Y zn;e{fUg!f15tIhMl-`txC}(-(!o3RB-P!roIO`sVA$%7Zp?~B*nN&@)iS&e-89Hp` z*@Qlf7;$uVK!pH*ydv!!qZBTP_c^I3Tm5+H{a8ycw<`>SMmGCrI0LIe$z6B(fVUMw zKPD+{OI`>5*Jc<5`nA<2!d&+O*)6Dzr?`IIq|1G88_mBhGs zD>m@m%&;6BwACJ`7HdmORp8m7;dx5r&AdC1{$j2bvaW*S znN{0E;7HG1LUwMm@eNotv}cs?r;znL35iT^4PifiZKWl}y$M$&hjGn`zqQjeX?UNm zE{)&+X0Jkf^=>A#6$;7KeJM8$ulFpCHJUCFJWyb8%Aavg)VjAO@H1O<7X-pE_`DaO zohQq|O_VRZEJkRUDcWZ*L4sS3LPe*)PXZ~mLKBkc`O1ZZq9w$!y1Lqk;%m8lS!d#s zf#&hlh$D`42UU6r9>clt=N07|o%RNqTA)$wa~W&~!$SL17ZVWG)YKUG;q=iVBMTQI zF=;!@r?N-20>5Foy1G`$e*{;eH@_Q4uDIUHA!6P)won?Ley=|dYByU>Smv5$hS8oj zNOiBg?kW>doM+EOg=ry3)cRm%n|8l9p4vbRIM78~>wtXsC!;>;6!0rFTLVYayxr1%Yvu3=~VwfKlpY`ls9p#{yAy) z{<%yA?e-Sgx=mNS9D4tDY18;T<*J)FJKnSGmf;kXo0fLyeN+(Ek&(^r!EzKWJcJY$ zbn^p-A^|dKbkDp4m&KAyg$iS<(q?*U3P~6R;^?+6Oqe8nQamRqDd~3p>1?I(-1%T) zy9#-dLrhF;6A&uYtPurm?X2RS9z7jp<-{e(P`_THSdQKwNI`>H5v2_ca~T((*AL95 zvbo}OatM4LHr!);CYnK@ANTie%t_46!NY;Kc3re-9LD?*ml<&j;k@t~lV({^D0sKZ@%leY3>hr?PFRcPeuiHs|}?+?2w3x_Gm!^FhI zOh2-~`qR4ebTcy|!S&S-R#dS9Dw+!eOm5Lkd~C!PFjklLRq8&bXywYqt|_^m%VwMa9h13gwQ`3^HxWF|NMID_p|BLoRhS~Fi zI0+`4;A8pv;&7COPQ&^H2X{&vxZKl`yyi{TuNGk)Qud5l8Jw4m4R~k%p8GB!y#)Dze zHAnyL@9jCT^8(h`ykgU2H`3C=j!JZ$lt3{o7G(DvKp(_+B!Zi%q5#nk=eSk&^JiqU zP;G5(T61gbje1=Y4B)I>8ZoTYOM8)`q$D!Z(r8N$lN@+46t8>x~7Of1Cua1+w^#Lq9nl0lOWlV3P%N0}oBYp5Wc_asTU-6Act{n5Juz51lO>RwsvJWN74GROCg}T*=tylk&!s|vOcdd zv*9KXkCLXMWSEeS%iu{Aaz-24vWetP*2^^r{LB5&0PU{U8$%x=A_fvOSuKnu-Wz%HlU;81-+c`$9Opu_32SL zINB?lEg}nhR9WPk>Z=}7+weqf`(ooLOza7lp9TjzxaBWb3o+8r?AV;W`UyC_K3=7B z9QF9VsQNU8VPIpk`u#=wj)P6DKV>2buM%pWFEM2CEwrJbLDL^V)|;5Ib2mzVEhPkY zn?L!jnsnJWFHk`w@l}Cs1+wW(B&LS$W%JaU-CnK?Dn(Ngm8M8jCFSx(@s~!cl-~y4Z33CZvnVO*VVLi5EWxTp zd(mgyN5bd)#ic-v6$Q(V1fw00;Xw=|EOr8&CP`i_Tp%eqefhZzI21=Tz4{}#-_YaX zV#Cr=x{M0W=1-lF`|Xj^)DAJAf$Hk1iD1pMMH1c_R@ncfG&ItVQZ)2Nt!-^fe8+b2 z?4bWPyo*)&KX9B&o=ADb8@wzlqm<+<`8&ExuOfg~Ll^0B%ycmRXAReKmZH}RMIeOo zv#BZh2K*Ap#=uBUws&+70b_5yRK$DTcb0vR<@@zGc*At9G+`-SAR|MXU6+BZ? zQl`4Px&&=)tE);&#YZJBxj^eKg#f4gIPLdhs}J@>fD(znBtaof2xr1Upr&5u_J8k+ zj`5I@mzQ_g8HkWtS!hRszIyT*2>^#y9aWF(bU9AkyIa=h_)dpKq7OzHls;*u|MLPD z#L$XCDBzc!CJC-BT!8X<2^ZJxaAXI=kYsQjB0+f_G6lFi4i`u zVQ-I3Sy-sUkhZ(Ozh6~$zqh~tlw>)R5xzC^Ukaq--Q67v`vyvpM4a1yx{0LXzd=HP%5$AW)(yLf=0;8Z4CR8qf^rsmOMqJE5MRgWo! zm75E$dU#Zv4g=*;cA`s3Xr4*nh52_v0(xgfk5tvj1J|7J&Ef+3I)+9w$MTL~mID$Vgi9Ys5lje=sJwLC| zRwr)V4IIrD>AI|LDuyus$A*YPT8whs{NxM*3GQ)Ge^;S9gi0_ivykK3KHba*2mP8W zk@0?t58Ouw(34T8Ek12!&dwP&4hW#J`r%&~(vP^oaz) zOwJejVfVdeR6ONg+uv=XK|sx5t%{_)Tq6z^nxV9zy8XYr;@N96F$wv+fKG?W`5vbioG6CJTH@IXar<#37!n zi8O)`QLK)$;ao~&;F?Qq#6KA%f9{eosXi*X{*FO)A~Jcp-rtBo6EBETr5Pmh`1=Ju zFVB)a3mh!qN7}q!Rcf=)W0ea>hAhXPSvnOE{Tl-MB;Ye}qa9BGlhivS)>2*erJA5`uj@?AC0?EPC|o1DtmAH95A@%3GBt(31~wy2 ze)_wSeZvws2sD<#cn220=Xn$%PMQ!O$9JzO@zdlh5K+~uG-q)cizhK~LOoCSOO0oq z@aI@`P=*mO#5|R#We#V5ij0np!BuHB|I{T-AfJ?E3aL!g=XRQx{4Ws<9y9o4DQ!m&ejJx5Il7C7ngF(Z3_nr9i_{LarTEn^?U!N#hO2CWXQqbB zJb@m_j_I>i0mJQb+8-WUNk+xKB(S+49Y2+>EX%<5Za+mKe#Z15A#{SQN&jBxh0 zuLS%Mwx74G)vef2V~a(Etk~RF1INaP39gx*KY!dOJ4{r@DqX@d@gHen`m;{2pu2M) zf$QR#Ms=O2$myoyv~Pdt2wD{#3|X?*Z+-8hgR@2WWi8?_0OXKOwDaM1$=) zgOGmhOWE{3P1-a3SGf-%rgTyeMtIV-pQ??9mAPwutyRo*lrUq}oQ+uj+W=G+h-0GAAz=rS@5{8g z4I?NFbHp0PB+eVI#x4C1!~4RmFWxjLgCo(*1Q#3inG@_GMwpFEy7D1q1H| zaSB*2-pgh330w!KHsU{TvJBCk=DnFH0l1pHDMYYBHPruUT)#z4U7eyy(_|nVwaa6m z-fJeTaQT#rM}%Xpf+9l@Wk9A=)z!6m?AWDr(L$|p<;?r}xNPmB=jDPQr^l})@8?gN zhr6at$xm%+oaXnY)?1??P*l^?eA$)DiBPmc$KKi=OYdDBy7d*_9S}U&xzhz+O;YeG zRNz0B8X`4JYlH-bMSzr+W2(()6+> zJO~VxyyL}p6K8B~aH{qv3Brxu^PT~XM*?9c8sp#kor}&}2D*C`dDk}n2Z=ER@q%MA zw;-$vn91(E)^Qr5PKrQBU1alu@revp=uhTY>GEtmShMd{3+XqMXGW=3|N6N++6;t} zigPrIq*4F(SI;GB1As8%rAwL!E%<3R!p!p<%kuMy^B1i|y1Tn^(x$nb_QJik`$F7$ zzM&ok7E+bW9|xM6nqGX~RBi|1Sa7vF-1(R*%9%{`@i?3+5{6U(s5~(lOkf&kHP8kh zM-l=J|1h^Z@xC=uRed~N$$;zE%z0UDX@H}dH`}S|q9_BCpOm3Jsd1isqWeDsO}|&= zk68Vaw>y0*kb%3wFoN;x$&-IQj9e0zzx$4o!1d9$|Ej@x2w5T4kQ;l#f}dKw7T`DQ z^D{WaTr_81Uw!1Id3=J+k^;1#R#>B$%GM`A_ z#^G_RqQq?9zP@(iNE>yMwStqSP>CP!2D~RFD{K6C6D4YpeEB7bzMd2VDAP>`3k%DR zxVG6ux?yca#WpYDV_yh-V!iRO-mcHV;o*y9qKPY+2nqxf0vV7BsWITB5+p?<2aWm+ zn1X>lGXbbIVEP9^cfpEnYQHsq{*HMBNXm`OGtLc7dtTA{&efiaM==%GfOj&UD#u74fC*SDAxqI$9 z@9KF2_O?i56}s2%fx{-H1F5GNQCogC`vUe0op-hZ^Uc2AY`7=$rE7R$IX6F+H=j}C z3IsNTPW)%E%$BD-x${De8x9gife02RDNv=kIy*Zv(9_d1xILQ9b+N0)HA^?NsXhDizVw|PBYhwsWA`W4=DL|q zexW?8-6Fl=uuI#HRgeC+s`&r^|7BZv7oyi>4~@gDN?IBt?w=;A{zlog;7yux-y#Vy zFMIOsni7l(O1Nqi*)^SxMea#bbjL9LOe)2Gd?b$+#CwNagTbjE_4WlC3L&jDWDX3u vGJ3db7+K_cU7bOy2Fo=eN8z_w>DG55D9(E{c+UxO5U@#!$&1zq8wCCjPnTP~ literal 0 Hc-jL100001 diff --git a/docs/common/secpoll.rst b/docs/common/secpoll.rst new file mode 100644 index 0000000000..48eeb12a59 --- /dev/null +++ b/docs/common/secpoll.rst @@ -0,0 +1,69 @@ +Security Polling +---------------- +PowerDNS products can poll the security status of their respective versions. +This polling, naturally, happens over DNS. +If the result is that a given version has a security problem, the software will report this at level 'Error' during startup, and repeatedly during operations. + +By default, security polling happens on the domain 'secpoll.powerdns.com', but this can be changed with the :ref:`setting-security-poll-suffix`. +If this setting is made empty, no polling will take place. +Organizations wanting to host their own security zones can do so by changing this setting to a domain name under their control. + +To make this easier, the zone used to host secpoll.powerdns.com is available `here `_. + +To enable distributors of PowerDNS to signal that they have backported versions, the PACKAGEVERSION compilation-time macro can be used to set a distributor suffix. + +Details +^^^^^^^ +PowerDNS software sadly sometimes has critical security bugs. +Even though we send out notifications of these via all channels available, we find that not everybody actually find out about our security releases. + +To solve this, PowerDNS software will start polling for security notifications, and log these periodically. +Secondly, the security status of the software will be reported using the built-in metrics. +This allows operators to poll for the PowerDNS security status and alert on it. + +In the implementation of this idea, we have taken the unique role of operating system distributors into account. +Specifically, we can deal with backported security fixes. + +Finally, this feature can be disabled, or operators can have the automated queries point at their own status service. + +Implementation +~~~~~~~~~~~~~~ +PowerDNS software periodically tries to resolve 'auth-x.y.z.security-status.secpoll.powerdns.com|TXT' or 'recursor-x.y.z.security-status.secpoll.powerdns.com'. + +The data returned is in one of the following forms: + +- NXDOMAIN or resolution failure -> 0 +- "1 Ok" -> 1 +- "2 Upgrade recommended for security reasons, see ..." -> 2 +- "3 Upgrade mandatory for security reasons, see ..." -> 3 + +In cases 2 or 3, periodic logging commences. +The metric security-status is set to 2 or 3 respectively. +If at a later date, resolution fails, the security-status is not reset to 1. +It could be lowered however if we discover the security status is less urgent than we thought. + +If resolution fails, and the previous security-status was 1, the new security-status becomes 0 ('no data'). +If the security-status was higher than 1, it will remain that way, and not get set to 0. + +In this way, security-status of 0 really means 'no data', and can not mask a known problem. + +Distributions +~~~~~~~~~~~~~ +Distributions frequently backport security fixes to the PowerDNS versions they ship. +This might lead to a version number that is known to us to be insecure to be secure in reality. + +To solve this issue, PowerDNS can be compiled with a distribution setting which will move the security polls from: 'auth-x.y.z.security-status.secpoll.powerdns.com' to 'auth-x.y.z-n.debian.security-status.secpoll.powerdns.com. + +Note two things, one, there is a separate namespace for debian, and secondly, we use the package version of this release. +This allows us to know that 4.0.1-1 (say) is insecure, but that 4.0.1-2 is not. + +Configuration Details +~~~~~~~~~~~~~~~~~~~~~ +The configuration setting :ref:`setting-security-poll-suffix` is by default set to 'secpoll.powerdns.com'. +If empty, nothing is polled. This can be moved to 'secpoll.yourorganization.com'. + +If compiled with PACKAGEVERSION=3.1.6-abcde.debian, queries will be sent to "auth-3.1.6-abcde.debian.security-status.security-poll-suffix". + +Delegation +~~~~~~~~~~ +If a distribution wants to host its own file with version information, we can delegate dist.security-status.secpoll.powerdns.com to their nameservers directly. diff --git a/docs/common/security-policy.rst b/docs/common/security-policy.rst new file mode 100644 index 0000000000..4c2b364609 --- /dev/null +++ b/docs/common/security-policy.rst @@ -0,0 +1,25 @@ +PowerDNS Security Policy +------------------------ + +If you have a security problem to report, please email us at both security@powerdns.com and ahu@ds9a.nl. +Please do not mail security issues to public lists, nor file a ticket, unless we do not get back to you in a timely manner. +We fully credit reporters of security issues, and respond quickly, but please allow us a reasonable timeframe to coordinate a response. + +We remind PowerDNS users that under the terms of the GNU General Public License, PowerDNS comes with ABSOLUTELY NO WARRANTY. +This license is included in this documentation. + +As of the 9th of September 2016, no actual security problems with PowerDNS Authoritative Server 3.4.10, Recursor 3.6.3, Recursor 3.7.2, or later are known about. +This page will be updated with all bugs which are deemed to be security problems, or could conceivably lead to those. +Any such notifications will also be sent to all `PowerDNS mailing lists `_. + +HackerOne +^^^^^^^^^ +Security issues can also be reported on `our HackerOne page `_ and might fetch a bounty. +Do note that only the PowerDNS software is in scope for the HackerOne program, not our websites or other infrastructure. + +Disclosure Policy +^^^^^^^^^^^^^^^^^ + - Let us know as soon as possible upon discovery of a potential security issue, and we'll make every effort to quickly resolve the issue. + - Provide us a reasonable amount of time to resolve the issue before any disclosure to the public or a third-party. + - We will always credit researchers in our :doc:`../security-advisories/index`. + diff --git a/docs/markdown/recursor/index.md b/docs/markdown/recursor/index.md index 75bd82e3f7..03c146a035 100644 --- a/docs/markdown/recursor/index.md +++ b/docs/markdown/recursor/index.md @@ -3,6 +3,8 @@ The PowerDNS recursor is part of the source tarball of the main PowerDNS distrib The documentation is only for the 4.0 series, users of older versions are urged to upgrade! +**Note**: [Improved documentation](/recursor) for the master version, the upcoming 4.1 release and the 4.0 is available. + ## Notable features: - Uses [MTasker](http://ds9a.nl/mtasker) - Can handle tens of thousands of concurrent questions. A quad Xeon 3GHz has been measured functioning very well at 400000 real life replayed packets per second. diff --git a/docs/markdown/recursor/scripting.md b/docs/markdown/recursor/scripting.md index 71145c03b5..73c1d9490e 100644 --- a/docs/markdown/recursor/scripting.md +++ b/docs/markdown/recursor/scripting.md @@ -456,13 +456,13 @@ This example script queries a simple key/value store over UDP to decide on wheth or not to filter a query: ``` -!!include=../pdns/kv-example-script.lua +!!include=../pdns/recursordist/contrib/kv-example-script.lua ``` ## Example Script ``` -!!include=../pdns/powerdns-example-script.lua +!!include=../pdns/recursordist/contrib/powerdns-example-script.lua ``` ### Dropping all traffic from botnet-infected users diff --git a/docs/markdown/theme/content.html b/docs/markdown/theme/content.html index dc5e5c3ca1..9126274230 100644 --- a/docs/markdown/theme/content.html +++ b/docs/markdown/theme/content.html @@ -6,6 +6,6 @@ {% endif %} -
This document is about PowerDNS 4.X. If you have PowerDNS 3.X, please see the PowerDNS 3.X documentation

+
This document is about PowerDNS 4.0. For other versions, please see the documentation index.

{{ content }} diff --git a/docs/process-md.sh b/docs/process-md.sh index 188dee28dd..c340af5132 100755 --- a/docs/process-md.sh +++ b/docs/process-md.sh @@ -1,5 +1,7 @@ #!/bin/sh -e +set -x + pre() { # Test if there are wrong PR links in the changelog CL_PR_LINKS="$(grep -E '\[#([0-9]+)\]\(.*[0-9]+\)' markdown/changelog.raw.md | grep -v -E '\[#([0-9]+)\]\(.*\1\)' || true)" diff --git a/docs/security-advisories/index.rst b/docs/security-advisories/index.rst new file mode 100644 index 0000000000..cd31f71629 --- /dev/null +++ b/docs/security-advisories/index.rst @@ -0,0 +1,25 @@ +Older security advisories +^^^^^^^^^^^^^^^^^^^^^^^^^ +Version 3.0 of the PowerDNS recursor contains a denial of service bug which can be exploited remotely. +This bug, which we believe to only lead to a crash, has been fixed in 3.0.1. +There are no guarantees however, so an upgrade from 3.0 is highly recommended. + +All versions of PowerDNS before 2.9.21.1 do not respond to certain queries. +This in itself is not a problem, but since the discovery by Dan Kaminsky of a new spoofing technique, this silence for queries PowerDNS considers invalid, within a valid domain, allows attackers more chances to feed *other* resolvers bad data. + +All versions of PowerDNS before 2.9.18 contain the following two bugs, which only apply to installations running with the LDAP backend, or installations providing recursion to a limited range of IP addresses. +If any of these apply to you, an upgrade is highly advised: + +- The LDAP backend did not properly escape all queries, allowing it to + fail and not answer questions. We have not investigated further risks + involved, but we advise LDAP users to update as quickly as possible + (Norbert Sendetzky, Jan de Groot) + +- Questions from clients denied recursion could blank out answers to + clients who are allowed recursion services, temporarily. Reported by + Wilco Baan. This would've made it possible for outsiders to blank out + a domain temporarily to your users. Luckily PowerDNS would send out + SERVFAIL or Refused, and not a denial of a domain's existence. + +All versions of PowerDNS before 2.9.17 are known to suffer from remote denial of service problems which can disrupt operation. +Please upgrade to 2.9.17 as this page will only contain detailed security information from 2.9.17 onwards. diff --git a/docs/security-advisories/older-than-3.0.rst b/docs/security-advisories/older-than-3.0.rst new file mode 100644 index 0000000000..cd31f71629 --- /dev/null +++ b/docs/security-advisories/older-than-3.0.rst @@ -0,0 +1,25 @@ +Older security advisories +^^^^^^^^^^^^^^^^^^^^^^^^^ +Version 3.0 of the PowerDNS recursor contains a denial of service bug which can be exploited remotely. +This bug, which we believe to only lead to a crash, has been fixed in 3.0.1. +There are no guarantees however, so an upgrade from 3.0 is highly recommended. + +All versions of PowerDNS before 2.9.21.1 do not respond to certain queries. +This in itself is not a problem, but since the discovery by Dan Kaminsky of a new spoofing technique, this silence for queries PowerDNS considers invalid, within a valid domain, allows attackers more chances to feed *other* resolvers bad data. + +All versions of PowerDNS before 2.9.18 contain the following two bugs, which only apply to installations running with the LDAP backend, or installations providing recursion to a limited range of IP addresses. +If any of these apply to you, an upgrade is highly advised: + +- The LDAP backend did not properly escape all queries, allowing it to + fail and not answer questions. We have not investigated further risks + involved, but we advise LDAP users to update as quickly as possible + (Norbert Sendetzky, Jan de Groot) + +- Questions from clients denied recursion could blank out answers to + clients who are allowed recursion services, temporarily. Reported by + Wilco Baan. This would've made it possible for outsiders to blank out + a domain temporarily to your users. Luckily PowerDNS would send out + SERVFAIL or Refused, and not a denial of a domain's existence. + +All versions of PowerDNS before 2.9.17 are known to suffer from remote denial of service problems which can disrupt operation. +Please upgrade to 2.9.17 as this page will only contain detailed security information from 2.9.17 onwards. diff --git a/docs/security-advisories/powerdns-advisory-2006-01.rst b/docs/security-advisories/powerdns-advisory-2006-01.rst new file mode 100644 index 0000000000..b72d9531a6 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2006-01.rst @@ -0,0 +1,39 @@ +PowerDNS Security Advisory 2006-01: Malformed TCP queries can lead to a buffer overflow which might be exploitable +------------------------------------------------------------------------------------------------------------------ + +- CVE: CVE-2006-4251 +- Date: 13th of November 2006 +- Affects: PowerDNS Recursor versions 3.1.3 and earlier, on all + operating systems. +- Not affected: No versions of the PowerDNS Authoritative Server + ('pdns\_server') are affected. +- Severity: Critical +- Impact: Potential remote system compromise. +- Exploit: As far as we know, no exploit is available as of 11th of + November 2006. +- Solution: Upgrade to PowerDNS Recursor 3.1.4, or apply the patches + referred below and recompile +- Workaround: Disable TCP access to the Recursor. This will have slight + operational impact, but it is likely that this will not lead to + meaningful degradation of service. Disabling access is best performed + at packet level, either by configuring a firewall, or instructing the + host operating system to drop TCP connections to port 53. + Additionally, exposure can be limited by configuring the + ``allow-from`` setting so only trusted users can query your + nameserver. + +PowerDNS Recursor 3.1.3 and previous miscalculate the length of incoming +TCP DNS queries, and will attempt to read up to 4 gigabytes of query +into a 65535 byte buffer. + +We have not verified if this problem might actually lead to a system +compromise, but are acting on the assumption that it might. + +For distributors, a minimal patch is available on `the PowerDNS +wiki `__. +Additionally, those shipping very old versions of the PowerDNS Recursor +might benefit from this +`patch `__. + +The impact of these and other security problems can be lessened by +considering the advice in FIXME: security-settings. diff --git a/docs/security-advisories/powerdns-advisory-2006-02.rst b/docs/security-advisories/powerdns-advisory-2006-02.rst new file mode 100644 index 0000000000..aa977e93e6 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2006-02.rst @@ -0,0 +1,22 @@ +PowerDNS Security Advisory 2006-02: Zero second CNAME TTLs can make PowerDNS exhaust allocated stack space, and crash +--------------------------------------------------------------------------------------------------------------------- + +- CVE: CVE-2006-4252 +- Date: 13th of November 2006 +- Affects: PowerDNS Recursor versions 3.1.3 and earlier, on all + operating systems. +- Not affected: No versions of the PowerDNS Authoritative Server + ('pdns\_server') are affected. +- Severity: Moderate +- Impact: Denial of service +- Exploit: This problem can be triggered by sending queries for + specifically configured domains +- Solution: Upgrade to PowerDNS Recursor 3.1.4, or apply `commit + 919 `__. +- Workaround: None known. Exposure can be limited by configuring the + **allow-from** setting so only trusted users can query your + nameserver. + +PowerDNS would recurse endlessly on encountering a CNAME loop consisting +entirely of zero second CNAME records, eventually exceeding resources +and crashing. diff --git a/docs/security-advisories/powerdns-advisory-2008-01.rst b/docs/security-advisories/powerdns-advisory-2008-01.rst new file mode 100644 index 0000000000..195b9835f7 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2008-01.rst @@ -0,0 +1,54 @@ +PowerDNS Security Advisory 2008-01: System random generator can be predicted, leading to the potential to 'spoof' PowerDNS Recursor +----------------------------------------------------------------------------------------------------------------------------------- + +- CVE: Not yet assigned +- Date: 31st of March 2008 +- Affects: PowerDNS Recursor versions 3.1.4 and earlier, on most + operating systems +- Not affected: No versions of the PowerDNS Authoritative Server + ('pdns\_server') are affected. +- Severity:Moderate +- Impact: Data manipulation; client redirection +- Exploit: This problem can be triggered by sending queries for + specifically configured domains, sending spoofed answer packets + immediately afterwards. +- Solution: Upgrade to PowerDNS Recursor 3.1.5, or apply changesets + `1159 `__, + `1160 `__ and + `1164 `__. +- Workaround: None known. Exposure can be limited by configuring the + **allow-from** setting so only trusted users can query your + nameserver. + +We would like to thank Amit Klein of Trusteer for bringing a serious +vulnerability to our attention which would enable a smart attacker to +'spoof' previous versions of the PowerDNS Recursor into accepting +possibly malicious data. + +Details can be found on `this Trusteer +page `__. + +This security problem was announced in `this email +message `__. + +It is recommended that all users of the PowerDNS Recursor upgrade to +3.1.5 as soon as practicable, while we simultaneously note that busy +servers are less susceptible to the attack, but not immune. + +The vulnerability is present on all operating systems where the +behaviour of the libc random() function can be predicted based on its +past output. This includes at least all known versions of Linux, as well +as Microsoft Windows, and probably FreeBSD and Solaris. + +The magnitude of this vulnerability depends on internal details of the +system random() generator. For Linux, the mathematics of the random +generator are complex, but well understood and Amit Klein has written +and published a proof of concept that can successfully predict its +output after uninterrupted observation of 40-50 DNS queries. + +Because the observation needs to be uninterrupted, busy PowerDNS +Recursor instances are harder to subvert - other data is highly likely +to be interleaved with traffic generated by an attacker. + +Nevertheless, operators are urged to update at their earliest +convenience. diff --git a/docs/security-advisories/powerdns-advisory-2008-02.rst b/docs/security-advisories/powerdns-advisory-2008-02.rst new file mode 100644 index 0000000000..6ef58dbf1d --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2008-02.rst @@ -0,0 +1,30 @@ +PowerDNS Security Advisory 2008-02: By not responding to certain queries, domains become easier to spoof +-------------------------------------------------------------------------------------------------------- + +- CVE: CVE-2008-3337 +- Date: 6th of August 2008 +- Affects: PowerDNS Authoritative Server 2.9.21 and earlier +- Not affected: No versions of the PowerDNS Recursor ('pdns\_recursor') + are affected. +- Severity: Moderate +- Impact: Data manipulation; client redirection +- Exploit: Domains with servers that drop certain queries can be + spoofed using simpler measures than would usually be required +- Solution: Upgrade to PowerDNS Authoritative Server 2.9.21.1, or apply + `commit + 1239 `__. +- Workaround: None known. + +Brian J. Dowling of Simplicity Communications has discovered a security +implication of the previous PowerDNS behaviour to drop queries it +considers malformed. We are grateful that Brian notified us quickly +about this problem. + +The implication is that while the PowerDNS Authoritative server itself +does not face a security risk because of dropping these malformed +queries, other resolving nameservers run a higher risk of accepting +spoofed answers for domains being hosted by PowerDNS Authoritative +Servers before 2.9.21.1. + +While the dropping of queries does not aid sophisticated spoofing +attempts, it does facilitate simpler attacks. diff --git a/docs/security-advisories/powerdns-advisory-2008-03.rst b/docs/security-advisories/powerdns-advisory-2008-03.rst new file mode 100644 index 0000000000..0b85878e99 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2008-03.rst @@ -0,0 +1,29 @@ +PowerDNS Security Advisory 2008-03: Some PowerDNS Configurations can be forced to restart remotely +-------------------------------------------------------------------------------------------------- + +- CVE: Not yet assigned +- Date: 18th of November 2008 +- Affects: PowerDNS Authoritative Server 2.9.21.1 and earlier +- Not affected: No versions of the PowerDNS Recursor + (``pdns_recursor``) are affected. Versions not running in single + threaded mode (``distributor-threads=1``) are probably not affected. +- Severity: Moderate +- Impact: Denial of Service +- Exploit: Send PowerDNS an CH HINFO query. +- Solution: Upgrade to PowerDNS Authoritative Server 2.9.21.2, or wait + for 2.9.22. +- Workaround: Remove ``distributor-threads=1`` if this is set. + +Daniel Drown discovered that his PowerDNS 2.9.21.1 installation crashed +on receiving a HINFO CH query. In his enthusiasm, he shared his +discovery with the world, forcing a rapid over the weekend release +cycle. + +While we thank Daniel for his discovery, please study our security +policy as outlined in `"Security" <#security>`__ before making +vulnerabilities public. + +It is believed that this issue only impacts PowerDNS Authoritative +Servers operating with ``distributor-threads=1``, but even on other +configurations a database reconnect occurs on receiving a CH HINFO +query. diff --git a/docs/security-advisories/powerdns-advisory-2010-01.rst b/docs/security-advisories/powerdns-advisory-2010-01.rst new file mode 100644 index 0000000000..9133d76967 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2010-01.rst @@ -0,0 +1,24 @@ +PowerDNS Security Advisory 2010-01: PowerDNS Recursor up to and including 3.1.7.1 can be brought down and probably exploited +---------------------------------------------------------------------------------------------------------------------------- + +- CVE: CVE-2009-4009 +- Date: 6th of January 2010 +- Affects: PowerDNS Recursor 3.1.7.1 and earlier +- Not affected: No versions of the PowerDNS Authoritative + ('pdns\_server') are affected. +- Severity: Critical +- Impact: Denial of Service, possible full system compromise +- Exploit: Withheld +- Solution: Upgrade to PowerDNS Recursor 3.1.7.2 or higher +- Workaround: None. The risk of exploitation or denial of service can + be decreased slightly by using the ``allow-from`` setting to only + provide service to known users. The risk of a full system compromise + can be reduced by running with a suitable reduced privilege user and + group settings, and possibly chroot environment. + +Using specially crafted packets, it is possible to force a buffer +overflow in the PowerDNS Recursor, leading to a crash. + +This vulnerability was discovered by a third party that (for now) +prefers not to be named. PowerDNS is very grateful however for their +help in improving PowerDNS security. diff --git a/docs/security-advisories/powerdns-advisory-2010-02.rst b/docs/security-advisories/powerdns-advisory-2010-02.rst new file mode 100644 index 0000000000..b5817d52e5 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2010-02.rst @@ -0,0 +1,23 @@ +PowerDNS Security Advisory 2010-02: PowerDNS Recursor up to and including 3.1.7.1 can be spoofed into accepting bogus data +-------------------------------------------------------------------------------------------------------------------------- + +- CVE: CVE-2009-4010 +- Date: 6th of January 2010 +- Affects: PowerDNS Recursor 3.1.7.1 and earlier +- Not affected: No versions of the PowerDNS Authoritative + ('pdns\_server') are affected. +- Severity: High +- Impact: Using smart techniques, it is possible to fool the PowerDNS + Recursor into accepting unauthorized data +- Exploit: Withheld +- Solution: Upgrade to PowerDNS Recursor 3.1.7.2 or higher +- Workaround: None. + +Using specially crafted zones, it is possible to fool the PowerDNS +Recursor into accepting bogus data. This data might be harmful to your +users. An attacker would be able to divert data from, say, bigbank.com +to an IP address of his choosing. + +This vulnerability was discovered by a third party that (for now) +prefers not to be named. PowerDNS is very grateful however for their +help in improving PowerDNS security. diff --git a/docs/security-advisories/powerdns-advisory-2012-01.rst b/docs/security-advisories/powerdns-advisory-2012-01.rst new file mode 100644 index 0000000000..0c82fd2349 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2012-01.rst @@ -0,0 +1,85 @@ +PowerDNS Security Advisory 2012-01: PowerDNS Authoritative Server can be caused to generate a traffic loop +---------------------------------------------------------------------------------------------------------- + +- CVE: CVE-2012-0206 +- Date: 10th of January 2012 +- Credit: Ray Morris of `BetterCGI.com `__. +- Affects: Most PowerDNS Authoritative Server versions < 3.0.1 (with + the exception of 2.9.22.5 and 2.9.22.6) +- Not affected: No versions of the PowerDNS Recursor ('pdns\_recursor') + are affected. +- Severity: High +- Impact: Using well crafted UDP packets, one or more PowerDNS servers + could be made to enter a tight packet loop, causing temporary denial + of service +- Exploit: Proof of concept +- Risk of system compromise: No +- Solution: Upgrade to PowerDNS Authoritative Server 2.9.22.5 or 3.0.1 +- Workaround: Several, the easiest is setting: ``cache-ttl=0``, which + does have a performance impact. Please see below. + +Affected versions of the PowerDNS Authoritative Server can be made to +respond to DNS responses, thus enabling an attacker to setup a packet +loop between two PowerDNS servers, perpetually answering each other's +answers. In some scenarios, a server could also be made to talk to +itself, achieving the same effect. + +If enough bouncing traffic is generated, this will overwhelm the server +or network and disrupt service. + +As a workaround, if upgrading to a non-affected version is not possible, +several options are available. The issue is caused by the packet-cache, +which can be disabled by setting 'cache-ttl=0', although this does incur +a performance penalty. This can be partially addressed by raising the +query-cache-ttl to a (far) higher value. + +Alternatively, on Linux systems with a working iptables setup, +'responses' sent to the PowerDNS Authoritative Server 'question' address +can be blocked by issuing: + +:: + + iptables -I INPUT -p udp --dst $AUTHIP --dport 53 \! -f -m u32 --u32 "0>>22&0x3C@8>>15&0x01=1" -j DROP + + +If this command is used on a router or firewall, substitute FORWARD for +INPUT. + +To solve this issue, we recommend upgrading to the latest packages +available for your system. Tarballs and new static builds (32/64bit, +RPM/DEB) of 2.9.22.5 and 3.0.1 have been uploaded to `our download +site `__. Kees +Monshouwer has provided updated CentOS/RHEL packages in `his +repository `__. Debian, +Fedora and SuSE should have packages available shortly after this +announcement. + +For those running custom PowerDNS versions, just applying this patch may +be easier: + +:: + + --- pdns/common_startup.cc (revision 2326) + +++ pdns/common_startup.cc (working copy) + @@ -253,7 +253,9 @@ + numreceived4++; + else + numreceived6++; + - + + if(P->d.qr) + + continue; + + + S.ringAccount("queries", P->qdomain+"/"+P->qtype.getName()); + S.ringAccount("remotes",P->getRemote()); + if(logDNSQueries) { + +It should apply cleanly to 3.0 and with little trouble to several older +releases, including 2.9.22 and 2.9.21. + +This bug resurfaced because over time, the check for 'not responding to +responses' moved to the wrong place, allowing certain responses to be +processed anyhow. + +We would like to thank Ray Morris of +`BetterCGI.com `__ for bringing this issue to our +attention and Aki Tuomi for helping us reproduce the problem. diff --git a/docs/security-advisories/powerdns-advisory-2014-01.rst b/docs/security-advisories/powerdns-advisory-2014-01.rst new file mode 100644 index 0000000000..ae99544261 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2014-01.rst @@ -0,0 +1,40 @@ + PowerDNS Security Advisory 2014-01: PowerDNS Recursor 3.6.0 can be crashed remotely +------------------------------------------------------------------------------------ + +- CVE: CVE-2014-3614 +- Date: 10th of September 2014 +- Credit: Dedicated PowerDNS users willing to study a crash that + happens once every few months (thanks) +- Affects: Only PowerDNS Recursor version 3.6.0. +- Not affected: No other versions of PowerDNS Recursor, no versions of + PowerDNS Authoritative Server +- Severity: High +- Impact: Crash +- Exploit: The sequence of packets required is known +- Risk of system compromise: No +- Solution: Upgrade to PowerDNS Recursor 3.6.1 +- Workaround: Restrict service using + ```allow-from`` <../recursor/settings.md#allow-from>`__, install + script that restarts PowerDNS + +Recently, we've discovered that PowerDNS Recursor 3.6.0 (but NOT +earlier) can crash when exposed to a specific sequence of malformed +packets. This sequence happened spontaneously with one of our largest +deployments, and the packets did not appear to have a malicious origin. + +Yet, this crash can be triggered remotely, leading to a denial of +service attack. There appears to be no way to use this crash for system +compromise or stack overflow. + +Upgrading to 3.6.1 solves the issue. + +In addition, if you want to apply a minimal fix to your own tree, it can +be found `here `__ + +As for workarounds, only clients in allow-from are able to trigger the +crash, so this should be limited to your userbase. Secondly, +`this `__ +and +`this `__ +can be used to enable Upstart and Systemd to restart the PowerDNS +Recursor automatically. diff --git a/docs/security-advisories/powerdns-advisory-2014-02.rst b/docs/security-advisories/powerdns-advisory-2014-02.rst new file mode 100644 index 0000000000..e7605ca30e --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2014-02.rst @@ -0,0 +1,39 @@ +PowerDNS Security Advisory 2014-02: PowerDNS Recursor 3.6.1 and earlier can be made to provide bad service +---------------------------------------------------------------------------------------------------------- + +- CVE: CVE-2014-8601 +- Date: 8th of December 2014 +- Credit: Florian Maury (`ANSSI `__) +- Affects: PowerDNS Recursor versions 3.6.1 and earlier +- Not affected: PowerDNS Recursor 3.6.2; no versions of PowerDNS + Authoritative Server +- Severity: High +- Impact: Degraded service +- Exploit: This problem can be triggered by sending queries for + specifically configured domains +- Risk of system compromise: No +- Solution: Upgrade to PowerDNS Recursor 3.6.2 +- Workaround: None known. Exposure can be limited by configuring the + **allow-from** setting so only trusted users can query your + nameserver. + +Recently we released PowerDNS Recursor 3.6.2 with a new feature that +strictly limits the amount of work we'll perform to resolve a single +query. This feature was inspired by performance degradations noted when +resolving domains hosted by 'ezdns.it', which can require thousands of +queries to resolve. + +During the 3.6.2 release process, we were contacted by a government +security agency with news that they had found that all major caching +nameservers, including PowerDNS, could be negatively impacted by +specially configured, hard to resolve domain names. With their +permission, we continued the 3.6.2 release process with the fix for the +issue already in there. + +We recommend that all users upgrade to 3.6.2 if at all possible. +Alternatively, if you want to apply a minimal fix to your own tree, it +can be found `here `__, +including patches for older versions. + +As for workarounds, only clients in allow-from are able to trigger the +degraded service, so this should be limited to your userbase. diff --git a/docs/security-advisories/powerdns-advisory-2015-01.rst b/docs/security-advisories/powerdns-advisory-2015-01.rst new file mode 100644 index 0000000000..c6851248af --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2015-01.rst @@ -0,0 +1,55 @@ +PowerDNS Security Advisory 2015-01: Label decompression bug can cause crashes or CPU spikes +------------------------------------------------------------------------------------------- + +- CVE: CVE-2015-1868 (original), CVE-2015-5470 (update) +- Date: 23rd of April 2015, updated 7th of July 2015 +- Credit: Aki Tuomi, Toshifumi Sakaguchi +- Affects: PowerDNS Recursor versions 3.5 and up; Authoritative Server + 3.2 and up +- Not affected: Recursor 3.6.4; Recursor 3.7.3; Auth 3.3.3; Auth 3.4.5 +- Severity: High +- Impact: Degraded service +- Exploit: This problem can be triggered by sending queries for + specifically configured domains, or by sending specially crafted + query packets +- Risk of system compromise: No +- Solution: Upgrade to any of the non-affected versions +- Workaround: Run your Recursor under a supervisor. Exposure can be + limited by configuring the + ```allow-from`` <../recursor/settings.md#allow-from>`__ setting so + only trusted users can query your nameserver. There is no workaround + for the Authoritative server. + +A bug was discovered in our label decompression code, making it possible +for names to refer to themselves, thus causing a loop during +decompression. On some platforms, this bug can be abused to cause +crashes. On all platforms, this bug can be abused to cause +service-affecting CPU spikes. + +We recommend that all users upgrade to a corrected version if at all +possible. Alternatively, if you want to apply a minimal fix to your own +tree, please `find patches +here `__. + +As for workarounds, for the Recursor: only clients in allow-from are +able to trigger the degraded service, so this should be limited to your +userbase; further, we recommend running your critical services under +supervision such as systemd, supervisord, daemontools, etc. + +There is no workaround for the Authoritative Server. + +We want to thank Aki Tuomi for noticing this in production, and then +digging until he got to the absolute bottom of what at the time appeared +to be a random and spurious failure. + +We want to thank Toshifumi Sakaguchi for further investigation into the +issue after the initial announcement, and for demonstrating to us quite +clearly the CPU spike issues. + +Update 7th of July 2015: Toshifumi Sakaguchi discovered that the +original fix was insufficient in some cases. Updated versions of the +Authoritative Server and Recursor `were +released <../changelog.md#powerdns-recursor-364>`__ on the 9th of June. +Minimal patches are +`available `__. The +insufficient fix was assigned CVE-2015-5470. diff --git a/docs/security-advisories/powerdns-advisory-2015-02.rst b/docs/security-advisories/powerdns-advisory-2015-02.rst new file mode 100644 index 0000000000..2948bcdca4 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2015-02.rst @@ -0,0 +1,36 @@ +PowerDNS Security Advisory 2015-02: Packet parsing bug can cause thread or process abortion +------------------------------------------------------------------------------------------- + +- CVE: CVE-2015-5230 +- Date: 2nd of September 2015 +- Credit: Pyry Hakulinen and Ashish Shukla at Automattic +- Affects: PowerDNS Authoritative Server 3.4.0 through 3.4.5 +- Not affected: PowerDNS Authoritative Server 3.4.6 +- Severity: High +- Impact: Degraded service or Denial of service +- Exploit: This problem can be triggered by sending specially crafted + query packets +- Risk of system compromise: No +- Solution: Upgrade to a non-affected version +- Workaround: Run the Authoritative Server inside a supervisor when + ``distributor-threads`` is set to ``1`` to prevent Denial of Service. + No workaround for the degraded service exists + +A bug was found in our DNS packet parsing/generation code, which, when +exploited, can cause individual threads (disabling service) or whole +processes (allowing a supervisor to restart them) to crash with just one +or a few query packets. + +PowerDNS Authoritative Server 3.4.0-3.4.5 are affected. No other +versions are affected. The PowerDNS Recursor is not affected. + +`PowerDNS Authoritative Server +3.4.6 <../changelog.md#powerdns-authoritative-server-346>`__ contains a +fix to this issue. A minimal patch is `available +here `__. + +This issue is entirely unrelated to `Security Advisory +2015-01 `__/CVE-2015-1868. + +We'd like to thank Pyry Hakulinen and Ashish Shukla at Automattic for +finding and subsequently reporting this bug. diff --git a/docs/security-advisories/powerdns-advisory-2015-03.rst b/docs/security-advisories/powerdns-advisory-2015-03.rst new file mode 100644 index 0000000000..034e3ef5c5 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2015-03.rst @@ -0,0 +1,40 @@ +PowerDNS Security Advisory 2015-03: Packet parsing bug can lead to crashes +-------------------------------------------------------------------------- + +- CVE: CVE-2015-5311 +- Date: November 9th 2015 +- Credit: Christian Hofstaedtler of Deduktiva GmbH +- Affects: PowerDNS Authoritative Server 3.4.4 through 3.4.6 +- Not affected: PowerDNS Authoritative Server 3.3.x and 3.4.7 and up +- Severity: High +- Impact: Degraded service or Denial of service +- Exploit: This problem can be triggered by sending specially crafted + query packets +- Risk of system compromise: No +- Solution: Upgrade to a non-affected version +- Workaround: run the process inside the guardian or inside a + supervisor + +A bug was found using ``afl-fuzz`` in our packet parsing code. This bug, +when exploited, causes an assertion error and consequent termination of +the the ``pdns_server`` process, causing a Denial of Service. + +When the PowerDNS Authoritative Server is run inside the guardian +(``--guardian``), or inside a supervisor like supervisord or systemd, it +will be automatically restarted, limiting the impact to a somewhat +degraded service. + +PowerDNS Authoritative Server 3.4.4 - 3.4.6 are affected. No other +versions are affected. The PowerDNS Recursor is not affected. + +`PowerDNS Authoritative Server +3.4.7 <../changelog.md#powerdns-authoritative-server-347>`__ contains a +fix to this issue. A minimal patch is `available +here `__. + +This issue is unrelated to the issues in our previous two Security +Announcements (`2015-01 `__ and +`2015-02 `__). + +We'd like to thank Christian Hofstaedtler of Deduktiva GmbH for finding +and reporting this issue. diff --git a/docs/security-advisories/powerdns-advisory-2016-01.rst b/docs/security-advisories/powerdns-advisory-2016-01.rst new file mode 100644 index 0000000000..12b3fed428 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2016-01.rst @@ -0,0 +1,44 @@ +PowerDNS Security Advisory 2016-01: Crafted queries can cause unexpected backend load +------------------------------------------------------------------------------------- + +- CVE: CVE-2016-5426, CVE-2016-5427 +- Date: 9th of September 2016 +- Credit: Florian Heinz and Martin Kluge +- Affects: PowerDNS Authoritative Server up to and including 3.4.9 +- Not affected: PowerDNS Authoritative Server 3.4.10, 4.x +- Severity: Medium +- Impact: Degraded service or Denial of service +- Exploit: This problem can be triggered by sending specially crafted + query packets +- Risk of system compromise: No +- Solution: Upgrade to a non-affected version +- Workaround: Run dnsdist with the rules provided below in front of + potentially affected servers, or dimension the backend capacity so + that it can handle the increased load. + +Two issues have been found in PowerDNS Authoritative Server allowing a +remote, unauthenticated attacker to cause an abnormal load on the +PowerDNS backend by sending crafted DNS queries, which might result in a +partial denial of service if the backend becomes overloaded. SQL +backends for example are particularly vulnerable to this kind of +unexpected load if they have not been dimensioned for it. The first +issue is based on the fact that PowerDNS Authoritative Server accepts +queries with a qname's length larger than 255 bytes. This issue has been +assigned CVE-2016-5426. The second issue is based on the fact that +PowerDNS Authoritative Server does not properly handle dot inside +labels. This issue has been assigned CVE-2016-5427. Both issues have +been addressed by this +`commit `__. + +PowerDNS Authoritative Server up to and including 3.4.9 is affected. No +other versions are affected. The PowerDNS Recursor is not affected. + +dnsdist can be used to block crafted queries, using +QNameWireLengthRule() to block queries with a qname larger than 255 +bytes and QNameLabelsCountRule() to block queries with a very large +amount of labels. Please note that restricting the number of labels in a +query might lead to unexpected issues, especially with DNSSEC-enabled +domains. + +We'd like to thank Florian Heinz and Martin Kluge for finding and +subsequently reporting this issue. diff --git a/docs/security-advisories/powerdns-advisory-2016-02.rst b/docs/security-advisories/powerdns-advisory-2016-02.rst new file mode 100644 index 0000000000..db68fc49b9 --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2016-02.rst @@ -0,0 +1,42 @@ +PowerDNS Security Advisory 2016-02: Crafted queries can cause abnormal CPU usage +================================================================================ + + +- CVE: CVE-2016-7068 +- Date: December 15th 2016 +- Credit: Florian Heinz and Martin Kluge +- Affects: PowerDNS Authoritative Server up to and including 3.4.10, + 4.0.1, PowerDNS Recursor up to and including 3.7.3, 4.0.3 +- Not affected: PowerDNS Authoritative Server 3.4.11, 4.0.2 and + PowerDNS Recursor 3.7.4, 4.0.4 +- Severity: Medium +- Impact: Degraded service or Denial of service +- Exploit: This issue can be triggered by sending specially crafted + query packets +- Risk of system compromise: No +- Solution: Upgrade to a non-affected version +- Workaround: Run dnsdist with the rules provided below in front of + potentially affected servers. + +An issue has been found in PowerDNS allowing a remote, unauthenticated +attacker to cause an abnormal CPU usage load on the PowerDNS server by +sending crafted DNS queries, which might result in a partial denial of +service if the system becomes overloaded. This issue is based on the +fact that the PowerDNS server parses all records present in a query +regardless of whether they are needed or even legitimate. A specially +crafted query containing a large number of records can be used to take +advantage of that behaviour. This issue has been assigned CVE-2016-7068. + +PowerDNS Authoritative Server up to and including 3.4.10 and 4.0.1 are +affected. PowerDNS Recursor up to and including 3.7.3 and 4.0.3 are +affected. + +dnsdist can be used to block crafted queries, using +``RecordsCountRule()`` and ``RecordsTypeCountRule()`` to block queries +with crafted records. + +For those unable to upgrade to a new version, a minimal patch is +`available `__ + +We would like to thank Florian Heinz and Martin Kluge for finding and +subsequently reporting this issue. diff --git a/docs/security-advisories/powerdns-advisory-2016-03.rst b/docs/security-advisories/powerdns-advisory-2016-03.rst new file mode 100644 index 0000000000..c97139429f --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2016-03.rst @@ -0,0 +1,35 @@ +PowerDNS Security Advisory 2016-03: Denial of service via the web server +======================================================================== + +- CVE: CVE-2016-7072 +- Date: December 15th 2016 +- Credit: Mongo +- Affects: PowerDNS Authoritative Server up to and including 3.4.10, + 4.0.1 +- Not affected: PowerDNS Authoritative Server 3.4.11, 4.0.2 +- Severity: Medium +- Impact: Degraded service or Denial of service +- Exploit: This issue can be triggered by opening a large number of + simultaneous connections to the web server +- Risk of system compromise: No +- Solution: Upgrade to a non-affected version +- Workaround: Disable the web server, or restrict access to it via a + firewall. + +An issue has been found in PowerDNS Authoritative Server allowing a +remote, unauthenticated attacker to cause a denial of service by opening +a large number of TCP connections to the web server. If the web server +runs out of file descriptors, it triggers an exception and terminates +the whole PowerDNS process. While it's more complicated for an +unauthorized attacker to make the web server run out of file descriptors +since its connection will be closed just after being accepted, it might +still be possible. This issue has been assigned CVE-2016-7072. + +PowerDNS Authoritative Server up to and including 3.4.10 and 4.0.1 are +affected. The PowerDNS Recursor is not affected. + +For those unable to upgrade to a new version, a minimal patch is +`available `__ + +We would like to thank Mongo for finding and subsequently reporting this +issue. diff --git a/docs/security-advisories/powerdns-advisory-2016-04.rst b/docs/security-advisories/powerdns-advisory-2016-04.rst new file mode 100644 index 0000000000..5f5ecccc9c --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2016-04.rst @@ -0,0 +1,36 @@ +PowerDNS Security Advisory 2016-04: Insufficient validation of TSIG signatures +============================================================================== + +- CVE: CVE-2016-7073 CVE-2016-7074 +- Date: December 15th 2016 +- Credit: Mongo +- Affects: PowerDNS Authoritative Server up to and including 3.4.10, + 4.0.1, PowerDNS Recursor from 4.0.0 and up to and including 4.0.3 +- Not affected: PowerDNS Authoritative Server 3.4.11, 4.0.2, PowerDNS + Recursor < 4.0.0, 4.0.4 +- Severity: Medium +- Impact: Zone content alteration +- Exploit: This problem can be triggered by an attacker in position of + man-in-the-middle +- Risk of system compromise: No +- Solution: Upgrade to a non-affected version + +Two issues have been found in PowerDNS Authoritative Server allowing an +attacker in position of man-in-the-middle to alter the content of an +AXFR because of insufficient validation of TSIG signatures. The first +issue is a missing check of the TSIG time and fudge values in +``AXFRRetriever``, leading to a possible replay attack. This issue has +been assigned CVE-2016-7073. The second issue is a missing check that +the TSIG record is the last one, leading to the possibility of parsing +records that are not covered by the TSIG signature. This issue has been +assigned CVE-2016-7074. + +PowerDNS Authoritative Server up to and including 3.4.10 and 4.0.1 are +affected. PowerDNS Recursor from 4.0.0 up to and including 4.0.3 are +affected. + +For those unable to upgrade to a new version, a minimal patch is +`available `__ + +We would like to thank Mongo for finding and subsequently reporting this +issue. diff --git a/docs/security-advisories/powerdns-advisory-2016-05.rst b/docs/security-advisories/powerdns-advisory-2016-05.rst new file mode 100644 index 0000000000..bdc879fcec --- /dev/null +++ b/docs/security-advisories/powerdns-advisory-2016-05.rst @@ -0,0 +1,32 @@ +PowerDNS Security Advisory 2016-05: Crafted zone record can cause a denial of service +===================================================================================== + +- CVE: CVE-2016-2120 +- Date: December 15th 2016 +- Credit: Mathieu Lafon +- Affects: PowerDNS Authoritative Server up to and including 3.4.10, + 4.0.1 +- Not affected: PowerDNS Authoritative Server 3.4.11, 4.0.2 +- Severity: Medium +- Impact: Denial of service +- Exploit: This issue can be triggered by inserting a specially crafted + record in a zone +- Risk of system compromise: No +- Solution: Upgrade to a non-affected version + +An issue has been found in PowerDNS Authoritative Server allowing an +authorized user to crash the server by inserting a specially crafted +record in a zone under their control then sending a DNS query for that +record. The issue is due to an integer overflow when checking if the +content of the record matches the expected size, allowing an attacker to +cause a read past the buffer boundary. This issue has been assigned +CVE-2016-2120. + +PowerDNS Authoritative Server up to and including 3.4.10 and 4.0.1 are +affected. The PowerDNS Recursor is not affected. + +For those unable to upgrade to a new version, a minimal patch is +`available `__ + +We would like to thank Mathieu Lafon for finding and subsequently +reporting this issue. diff --git a/docs/security-advisories/security-policy.rst b/docs/security-advisories/security-policy.rst new file mode 100644 index 0000000000..add80cd112 --- /dev/null +++ b/docs/security-advisories/security-policy.rst @@ -0,0 +1,12 @@ +PowerDNS Security Policy +------------------------ +If you have a security problem to report, please email us at both security@powerdns.com and ahu@ds9a.nl. +Please do not mail security issues to public lists, nor file a ticket, unless we do not get back to you in a timely manner. +We fully credit reporters of security issues, and respond quickly, but please allow us a reasonable timeframe to coordinate a response. + +We remind PowerDNS users that under the terms of the GNU General Public License, PowerDNS comes with ABSOLUTELY NO WARRANTY. +This license is included in this documentation. + +As of the 9th of September 2016, no actual security problems with PowerDNS Authoritative Server 3.4.10, Recursor 3.6.3, Recursor 3.7.2, or later are known about. +This page will be updated with all bugs which are deemed to be security problems, or could conceivably lead to those. +Any such notifications will also be sent to all `PowerDNS mailing lists `_. diff --git a/pdns/recursordist/.gitignore b/pdns/recursordist/.gitignore index 11eb6dc423..b7636f11b6 100644 --- a/pdns/recursordist/.gitignore +++ b/pdns/recursordist/.gitignore @@ -46,3 +46,9 @@ /testrunner.trs /test_libcrypto.log /test_libcrypto.trs +.venv +html-docs +.doctrees +doctrees +latex +PowerDNS-Recursor.pdf diff --git a/pdns/recursordist/Makefile.am b/pdns/recursordist/Makefile.am index 80a84b1881..1cae6f27f1 100644 --- a/pdns/recursordist/Makefile.am +++ b/pdns/recursordist/Makefile.am @@ -54,14 +54,18 @@ EXTRA_DIST = \ mtasker.cc \ mtasker_fcontext.cc mtasker_ucontext.cc \ opensslsigners.hh opensslsigners.cc \ - pdns_recursor.1.md \ portsmplexer.cc \ - rec_control.1.md \ rrd/* \ html incfiles \ test_libcrypto \ pdns-recursor.service.in +dist-hook: + for file in $$(find $(distdir)/docs -type l); do \ + t=`stat -c%N $$file | awk '{print $$NF}' | sed "s/'//g"` ; \ + ln -fs ../$$t $$file; \ + done + sbin_PROGRAMS = pdns_recursor bin_PROGRAMS = rec_control @@ -352,19 +356,48 @@ recursor.conf-dist: pdns_recursor MANPAGES=pdns_recursor.1 \ rec_control.1 -if HAVE_PANDOC - dist_man_MANS=$(MANPAGES) -endif -if HAVE_MANPAGES - dist_man_MANS=$(MANPAGES) -endif +dist_man_MANS=$(MANPAGES) -if HAVE_PANDOC -$(MANPAGES): %: %.md - $(AM_V_GEN)$(PANDOC) -s -t man $< -o $@ -else +if HAVE_VIRTUALENV +if !HAVE_MANPAGES +$(MANPAGES): %.1: docs/manpages/%.rst .venv + .venv/bin/python -msphinx -b man docs . $< +endif # if !HAVE_MANPAGES + +.venv: docs/requirements.txt + virtualenv .venv + .venv/bin/pip install -r docs/requirements.txt + +html-docs: docs/** .venv + .venv/bin/python -msphinx -b html docs html-docs + +latex/PowerDNS-Recursor.pdf: docs/** .venv + .venv/bin/python -msphinx -M latexpdf docs . + +PowerDNS-Recursor.pdf: latex/PowerDNS-Recursor.pdf + mv $< $@ + +html-docs.tar.bz2: html-docs + tar cjf $@ $< + +all-docs: PowerDNS-Recursor.pdf html-docs html-docs.tar.bz2 + +upload-docs: all-docs + rsync -crv --delete --no-p --chmod=g=rwX --exclude '*~' ./html-docs/ web1.powerdns.com:/srv/www/doc.powerdns.com/recursor/ + rsync -crv --no-p --chmod=g=rwX --exclude '*~' ./html-docs.tar.bz2 web1.powerdns.com:/srv/www/doc.powerdns.com/recursor/ + rsync -crv --no-p --chmod=g=rwX --exclude '*~' ./PowerDNS-Recursor.pdf web1.powerdns.com:/srv/www/doc.powerdns.com/recursor/ + +else # if HAVE_VIRTUALENV $(MANPAGES): - echo "You need pandoc to generate the manpages" + echo "You need virtualenv to generate the manpages" + exit 1 + +PowerDNS-Recursor.pdf: + echo "You need virtualenv to generate the PDF" + exit 1 + +html-docs: + echo "You need virtualenv to generate the HTML docs" exit 1 endif diff --git a/pdns/recursordist/configure.ac b/pdns/recursordist/configure.ac index 58b9bb2cc0..6528e7662c 100644 --- a/pdns/recursordist/configure.ac +++ b/pdns/recursordist/configure.ac @@ -155,7 +155,7 @@ PDNS_ENABLE_MALLOC_TRACE PDNS_ENABLE_VALGRIND AX_AVAILABLE_SYSTEMD AM_CONDITIONAL([HAVE_SYSTEMD], [ test x"$systemd" = "xy" ]) -PDNS_CHECK_PANDOC +PDNS_CHECK_VIRTUALENV AC_SUBST(LIBS) diff --git a/pdns/kv-example-script.lua b/pdns/recursordist/contrib/kv-example-script.lua similarity index 100% rename from pdns/kv-example-script.lua rename to pdns/recursordist/contrib/kv-example-script.lua diff --git a/pdns/powerdns-example-script.lua b/pdns/recursordist/contrib/powerdns-example-script.lua similarity index 100% rename from pdns/powerdns-example-script.lua rename to pdns/recursordist/contrib/powerdns-example-script.lua diff --git a/pdns/recursordist/docs/.gitignore b/pdns/recursordist/docs/.gitignore new file mode 100644 index 0000000000..e35d8850c9 --- /dev/null +++ b/pdns/recursordist/docs/.gitignore @@ -0,0 +1 @@ +_build diff --git a/pdns/recursordist/docs/Makefile b/pdns/recursordist/docs/Makefile new file mode 100644 index 0000000000..d3723c3db2 --- /dev/null +++ b/pdns/recursordist/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python -msphinx +SPHINXPROJ = PowerDNSRecursor +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/pdns/recursordist/docs/_static/pdns.css b/pdns/recursordist/docs/_static/pdns.css new file mode 100644 index 0000000000..0a6f10caab --- /dev/null +++ b/pdns/recursordist/docs/_static/pdns.css @@ -0,0 +1,1052 @@ +body { + background-color: #edf0f2; + margin: 0; + padding: 0; + font-family: "Open Sans", Helvetica, Arial, sans-serif; + font-size: 16px; + color: #333; + line-height: 1.5; +} + +#left-column { + float: left; + position: fixed; + height: 100%; + border-right: 1px solid #e0e0e0; + width: 300px; + overflow: auto; + background: #fafafa; +} + +#right-column { + padding: 20px 0; + margin-left: 300px; + background-color: #fff; + max-width: 900px; +} + +a.headerlink { + visibility: hidden; + color: #ddd; + padding: 0 4px; + text-decoration: none; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +h1 > a, h2 > a, h3 > a, h4 > a, h5 > a, h6 > a { + color: #5C7C98; +} + +h1, h2, h3, h4, h5, h6 { + color: black; + font-weight: normal; + padding: 0; + font-family: "Source Serif Pro", "serif"; +} + +h1, h2, h3 { + margin-top: 30px; + margin-bottom: 20px; +} + +h1 { + font-size: 38px; + padding: 10px 10px 10px 45px; + margin: 20px 0 35px -45px; + background-color: aliceblue; + width: calc(100% + 90px); + border-bottom: 1px solid #D8E4EF; +} + +h1 > pre, +h1 > code, +h1 > tt { + font-size: 38px; +} + +h2 { + font-size: 34px; + padding: .2em 0; + border-bottom: 1px solid #ddd; +} + +h2 > pre, +h2 > code, +h2 > tt { + font-size: 34px; +} + +h3 { + margin-top: 35px; + font-size: 28px; +} + +h3 > pre, +h3 > code, +h3 > tt { + font-size: 28px; +} + +h4 { + margin-top: 30px; + font-size: 24px; +} + +h4 > pre, +h4 > code, +h4 > tt { + font-size: 24px; +} + +h5 { + margin-top: 25px; + font-size: 20px; +} + +h5 > pre, +h5 > code, +h5 > tt { + font-size: 20px; +} + +div.clearer { + clear: both; +} + +.container-wrapper { + padding: 0; + position: relative; +} + +div.related { + display: none; +} + +p { + padding: 0; + font-family: inherit; + font-size: inherit; + color: #333; +} + +code, pre, tt { + font-size: 15px; + font-family: Consolas, monospace; +} + +code, tt { + color: #8D1A38; +} + +tt { + padding: 0 2px; +} + +code, pre { + line-height: 23px; + margin: 20px 0; + word-wrap: normal; + background-color: #fff; +} + +pre { + color: #333; + background-color: #fff; + overflow: auto; + border-width: 0 0 0 2px; + border-color: #eee; + border-style: solid; + padding: 14px 0 14px 20px; + padding-right: 0; + margin: 20px 0; +} + +div.highlight { + background-color: white; +} + +a.internal em { + font-style: normal; +} + +dl dd { + margin: 3px 0 10px 30px; +} + +dl.method { + border-bottom: 1px solid #ccc; +} + +.breadcrumb { + font-size: 15px; + margin-bottom: 12px; + background: #fff; +} + +blockquote { + border-width: .1em 0 .1em 0; + border-color: #e5eef2; + border-style: solid; + background-color: #f3f8f9; + color: #000; + margin: 20px 0; + padding: 15px 20px; + font-size: 16px; +} + +/* Sphinx sidebar +-------------------------------------------------- */ + +div.sphinxsidebar { + word-wrap: break-word; +} + +div.sphinxsidebar .panel-default > .panel-heading { + background-image: none; +} + +.sidebar-wrapper { + padding: 0 22px; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + color: #444; + font-size: 20px; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h4 { + font-size: 16px; +} + +div.sphinxsidebar p { + color: #555; + margin: 10px 0; +} + +.sidebar-toc { + font-size: 15px; +} + +div.sphinxsidebar .sidebar-toc ul { + margin: 0 0 4px 0; + list-style-type: none; + color: #000; +} + +div.sphinxsidebar .sidebar-toc a { + font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; + color: #444; + text-decoration: none; +} + +.sidebar-toc > ul { + padding: 0 !important; + list-style-type: none; + margin: 0; +} + +.sidebar-toc ul li a { + display: block; +} + +.sidebar-toc ul li a:hover { + background-color: #428bca; + color: #fff; +} + +.sidebar-toc ul li.current > a, +.sidebar-toc ul li.current > a:hover { + background-color: #e6e6e6; + color: #444; +} + +.sidebar-toc ul li.toctree-l1 a { + padding: 5px 25px; +} + +.sidebar-toc ul li.toctree-l2 a { + padding: 5px 50px; +} + +.sidebar-toc ul li.toctree-l3 a { + padding: 5px 75px; +} + +div.sphinxsidebar ul.want-points { + padding-left: 20px; + margin: 0; +} + +div.sphinxsidebar .sidebar-toc ul ul { + margin: 0; + padding: 0; +} + +.sidebar-localtoc ul { + padding-left: 24px; +} + +div.sphinxsidebar input { + border: 1px solid #ccc; + font-family: Helvetica, arial, freesans, clean, sans-serif; + font-size: 1em; +} + +.margin-top-1em { + margin-top: 1em; +} + +.sidebar-block { + padding: 0; + margin: 14px 0 30px 0; +} + +.sidebar-block h2 { + border-bottom: none; + margin: 0 0 17px 0; + font-size: 14px; + font-family: "Open Sans", Helvetica, Arial, sans-serif; + padding: 0 0 6px 0; + font-weight: bold; + text-transform: uppercase; + color: #606060; +} + +.sidebar-block .bd { + font-size: 16px; +} + +.sphinxsidebar > .sidebar-block:not(:last-child):after { + content: ''; + display:block; + border-top: 1px solid #ccc; + margin: 24px 22px 0 22px; +} + +.text-logo { + font-size: 18px; + text-align: center; + display: block; + padding: 8px; + color: #fff; + font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; + margin: 0 0 20px 0; + font-weight: bold; + background-color: #337ab7; + border-bottom: 1px solid #fff; +} + +.text-logo:hover { + color: #fff; +} + +/* Left-nav search box +-------------------------------------------------- */ + +#main-search form .input-group { + width: 100%; + margin: 0 0 12px 0; + padding: 0; + border: none; +} + +#main-search form .input-group input { + padding: 4px; + width: 100%; + border-radius: 5px; + margin: 0; + font-size: 15px; +} + +.search-page-form { + width: 350px; +} + +/* Two-pane table list +-------------------------------------------------- */ + +.table-bordered>thead>tr>th, +.table-bordered>tbody>tr>th, +.table-bordered>tfoot>tr>th, +.table-bordered>thead>tr>td, +.table-bordered>tbody>tr>td, +.table-bordered>tfoot>tr>td, +table.two-column.table-bordered caption+thead tr:first-child th:first-child, +table.two-column.table-bordered caption+tbody tr:first-child td:first-child, +table.two-column.table-bordered colgroup+thead tr:first-child th:first-child, +table.two-column.table-bordered colgroup+tbody tr:first-child td:first-child, +table.two-column tbody td + border: 0 0 1px 0 solid #eee; + border-left: none; + padding: 8px 4px; + font-size: 16px; +} + +table.two-column { + width: 100%; + border: 0px none !important; + box-shadow: none; +} + +/* Disqus comments styles +-------------------------------------------------- */ + +.comment-container { + margin: 24px auto; +} + +/* Next and previous links +-------------------------------------------------- */ + +.footer-relations { + display: relative; + border-top: 1px solid #ccc; + padding: 12px 45px; + margin-top: 30px; + font-size: 24px; +} + +.rel-spacer { + height: 40px; +} + +/* Footer styling +-------------------------------------------------- */ + +div.footer { + padding: 25px; + font-size: 14px; + color: #888; + text-align: right; + max-width: 1200px; + width: 100%; +} + +div.footer a { + color: #888; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background: url(file.png) no-repeat 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- general index --------------------------------------------------------- */ + +table { + margin-bottom: 20px; +} + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- general body styles --------------------------------------------------- */ + +.body { + padding: 0 45px; +} + +div.body p.caption { + text-align: inherit; +} + +table.field-list { + border: 1px solid #ddd; + border-collapse: collapse; + border-spacing: 0; + width: 100%; +} + +table.field-list td, +table.field-list th { + border: 1px solid #ddd; + padding: 8px; + vertical-align: top; + line-height: 1.4; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #e8e8e8; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; + background-color: #f8f8f8; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- contents-------------------------------------------------------------- */ + +div.topic.contents { + display: inline-block; + border-radius: 3px; + padding: 24px 36px 18px 36px; +} + +div.topic.contents > ul { + padding-left: 20px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +.admonition { + margin: 20px 0; + padding: 20px; + background-color: #fff; + border: 1px solid #eee; + border-left-width: 6px; + border-radius: 3px; +} + +.admonition dt { + font-weight: bold; +} + +.admonition dl { + margin-bottom: 0; +} + +.admonition-title { + margin: 0px 0 5px; + padding: 0; + font-weight: bold; + font-size: 18px; + line-height: 1.1; + font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; +} + +.admonition.danger, +.admonition.error { + border-left-color: #d9534f; +} + +.admonition.danger .admonition-title, +.admonition.error .admonition-title { + color: #d9534f; +} + +.admonition.important, +.admonition.warning, +.admonition.attention, +.admonition.caution { + border-left-color: #f0ad4e; +} + +.admonition.important .admonition-title, +.admonition.warning .admonition-title, +.admonition.attention .admonition-title, +.admonition.caution .admonition-title { + color: #9B581F; +} + +.admonition.note, +.admonition.hint { + border-left-color: #31708f; +} + +.admonition.note .admonition-title, +.admonition.hint .admonition-title { + color: #31708f; +} + +.admonition.tip { + border-left-color: #3c763d; +} + +.admonition.tip .admonition-title { + color: #3c763d; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.admonition tt.xref, div.admonition a tt { + border-bottom: 1px solid #fafafa; +} + +div.admonition p.last { + margin-bottom: 0; +} + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +.highlighted { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.refcount { + color: #060; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +dt:target, .highlight { + background: #FAF3E8; +} + +/* -- code displays --------------------------------------------------------- */ + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +code.descname { + padding: 0px; +} + +code.descclassname { + padding: 0px; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + padding-right: 0.08em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.descname, tt.descclassname { + font-size: 0.95em; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- Theme specific classes - */ + +.overflow-height-500px { + overflow: auto; + height: 500px; +} + +.overflow-height-250px { + overflow: auto; + height: 250px; +} + +/* Toggle mobile view +-------------------------------------------------- */ + +#mobile-toggle { + height: 40px; + width: 100%; + display: none; + padding: 12px; + border-bottom: 1px solid #ccc; + position: fixed; + top: 0; + left: 0; + background-color: #fff; + z-index: 1; +} + +/* Small screen styles +-------------------------------------------------- */ + +@media screen and (max-width: 768px) { + + body { + padding: 0px; + margin: 0px; + background-color: #fff; + } + + h1 { + margin-left: 0; + width: 100%; + padding: 10px; + font-size: 40px; + } + + #left-column { + position: relative; + top: 0; + left: 0; + display: none; + width: 100%; + float: none; + margin: 40px 0 0 0; + } + + .footer-relations { + padding: 12px 0; + } + + #right-column { + margin-left: 0; + margin-top: 0; + padding: 50px 20px 8px 20px; + width: 100%; + float: none; + } + + .document { + position: relative; + padding: 0; + width: 100% + } + + .body { + padding: 0px; + } + + #mobile-toggle { + display: block; + } + + p { + padding: 0; + } +} + +/* Account for when the left column is closed then page is expanded. +-------------------------------------------------- */ + +@media screen and (min-width: 769px) { + #left-column { + display: block !important; + } +} + +/* Syntax highlighting +-------------------------------------------------- */ + +.hll { background-color: #ffffcc } +.c { color: #999988; font-style: italic } /* Comment */ +.err { color: #a61717; background-color: #e3d2d2 } /* Error */ +.k { color: #000000; font-weight: bold } /* Keyword */ +.o { color: #000000; font-weight: bold } /* Operator */ +.cm { color: #999988; font-style: italic } /* Comment.Multiline */ +.cp { color: #999999; font-weight: bold; font-style: italic } /* Comment.Preproc */ +.c1 { color: #999988; font-style: italic } /* Comment.Single */ +.cs { color: #999999; font-weight: bold; font-style: italic } /* Comment.Special */ +.gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */ +.ge { color: #000000; font-style: italic } /* Generic.Emph */ +.gr { color: #aa0000 } /* Generic.Error */ +.gh { color: #999999 } /* Generic.Heading */ +.gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */ +.go { color: #888888 } /* Generic.Output */ +.gp { color: #555555 } /* Generic.Prompt */ +.gs { font-weight: bold } /* Generic.Strong */ +.gu { color: #aaaaaa } /* Generic.Subheading */ +.gt { color: #aa0000 } /* Generic.Traceback */ +.kc { color: #000000; font-weight: bold } /* Keyword.Constant */ +.kd { color: #000000; font-weight: bold } /* Keyword.Declaration */ +.kn { color: #000000; font-weight: bold } /* Keyword.Namespace */ +.kp { color: #000000; font-weight: bold } /* Keyword.Pseudo */ +.kr { color: #000000; font-weight: bold } /* Keyword.Reserved */ +.kt { color: #445588; font-weight: bold } /* Keyword.Type */ +.m { color: #009999 } /* Literal.Number */ +.s { color: #d01040 } /* Literal.String */ +.na { color: #008080 } /* Name.Attribute */ +.nb { color: #0086B3 } /* Name.Builtin */ +.nc { color: #445588; font-weight: bold } /* Name.Class */ +.no { color: #008080 } /* Name.Constant */ +.nd { color: #3c5d5d; font-weight: bold } /* Name.Decorator */ +.ni { color: #800080 } /* Name.Entity */ +.ne { color: #990000; font-weight: bold } /* Name.Exception */ +.nf { color: #990000; font-weight: bold } /* Name.Function */ +.nl { color: #990000; font-weight: bold } /* Name.Label */ +.nn { color: #555555 } /* Name.Namespace */ +.nt { color: #000080 } /* Name.Tag */ +.nv { color: #008080 } /* Name.Variable */ +.ow { color: #000000; font-weight: bold } /* Operator.Word */ +.w { color: #bbbbbb } /* Text.Whitespace */ +.mf { color: #009999 } /* Literal.Number.Float */ +.mh { color: #009999 } /* Literal.Number.Hex */ +.mi { color: #009999 } /* Literal.Number.Integer */ +.mo { color: #009999 } /* Literal.Number.Oct */ +.sb { color: #d01040 } /* Literal.String.Backtick */ +.sc { color: #d01040 } /* Literal.String.Char */ +.sd { color: #d01040 } /* Literal.String.Doc */ +.s2 { color: #d01040 } /* Literal.String.Double */ +.se { color: #d01040 } /* Literal.String.Escape */ +.sh { color: #d01040 } /* Literal.String.Heredoc */ +.si { color: #d01040 } /* Literal.String.Interpol */ +.sx { color: #d01040 } /* Literal.String.Other */ +.sr { color: #009926 } /* Literal.String.Regex */ +.s1 { color: #d01040 } /* Literal.String.Single */ +.ss { color: #990073 } /* Literal.String.Symbol */ +.bp { color: #999999 } /* Name.Builtin.Pseudo */ +.vc { color: #008080 } /* Name.Variable.Class */ +.vg { color: #008080 } /* Name.Variable.Global */ +.vi { color: #008080 } /* Name.Variable.Instance */ +.il { color: #009999 } /* Literal.Number.Integer.Long */ diff --git a/pdns/recursordist/docs/appendices/compiling.rst b/pdns/recursordist/docs/appendices/compiling.rst new file mode 100644 index 0000000000..3af5972b0a --- /dev/null +++ b/pdns/recursordist/docs/appendices/compiling.rst @@ -0,0 +1,57 @@ +Compiling the PowerDNS Recursor +=============================== + +As the PowerDNS Recursor is distributed with a configure script, compiling it is a matter of:: + + tar xf pdns-recursor-$VERSION.tar.bz2 + cd pdns-recursor-$VERSION + ./configure + make + make install + +Dependencies +------------ + +To build the PowerDNS Recursor, a C++ compiler with support for C++ 2011 is required. +This means gcc 4.9 and newer and clang 3.5 and newer. +Furthermore, the Makefiles require GNU make, not BSD make. + +By default, the PowerDNS recursor requires the following libraries and headers: + +* `Boost `_ 1.35 or newer +* `Lua `_ 5.1+ or `LuaJit `_ +* `OpenSSL `_ + +Optional dependencies +--------------------- + +Several options that can be passed to ``./configure`` can enable and disable different features. +These will require additional dependencies + +ed25519 support with libsodium +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The PowerDNS Recursor can link with `libsodium `_ to support ed25519 (DNSSEC algorithm 15). +To detect libsodium, use the ``--enable-libsodium`` configure option. + +ed25519 and ed448 support with libdecaf +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`libdecaf `_ is a library that allows the PowerDNS Recursor to support ed25519 and Ed448 (DNSSEC algorithms 15 and 16). +To detect libsodium, use the ``--enable-libsodium`` configure option. + +Protobuf to emit DNS logs +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The PowerDNS Recursor can log DNS query information over :doc:`Protocol Buffers <../lua-config/protobuf>`. +To enable this functionality, install the `protobuf `_ library and compiler. +The configure script will automatically detect this and bump the Boost version depencency to 1.42. + +To disable building this functionality, use ``--without-protobuf``. + +systemd notify support +^^^^^^^^^^^^^^^^^^^^^^ + +During configure, ``configure`` will attempt to detect the availibility of `systemd or systemd-daemon `_ headers. +To force the use of systemd (and failing configure if the headers do not exist), use ``--enable-systemd``. +To set the directory where the unit files should be installed, use ``--with-systemd=/path/to/unit/dir``. diff --git a/pdns/recursordist/docs/appendices/internals.rst b/pdns/recursordist/docs/appendices/internals.rst new file mode 100644 index 0000000000..2e1517200c --- /dev/null +++ b/pdns/recursordist/docs/appendices/internals.rst @@ -0,0 +1,430 @@ +Internals of the PowerDNS Recursor +================================== + +**Warning**: This section is aimed at programmers wanting to contribute +to the recursor, or to help fix bugs. It is not required reading for a +PowerDNS operator, although it might prove interesting. + +The PowerDNS Recursor consists of very little code, the core DNS logic +is less than a thousand lines. + +This smallness is achieved through the use of some fine infrastructure: +MTasker, MOADNSParser, MPlexer and the C++ Standard Library/Boost. This +page will explain the conceptual relation between these components, and +the route of a packet through the program. + + The PowerDNS Recursor +---------------------- + +The Recursor started out as a tiny project, mostly a technology +demonstration. These days it consists of the core plus 9000 lines of +features. This combined with a need for very high performance has made +the recursor code less accessible than it was. The page you are reading +hopes to rectify this situation. + + Synchronous code using MTasker +------------------------------- + +The original name of the program was **syncres**, which is still +reflected in the file name ``syncres.cc``, and the class SyncRes. This +means that PowerDNS is written naively, with one thread of execution per +query, synchronously waiting for packets, Normally this would lead to +very bad performance (unless running on a computer with very fast +threading, like possibly the Sun CoolThreads family), so PowerDNS +employs `MTasker `__ for very fast userspace +threading. + +MTasker, which was developed separately from PowerDNS, does not provide +a full multithreading system but restricts itself to those features a +nameserver needs. It offers cooperative multitasking, which means there +is no forced preemption of threads. This in turn means that no two +**MThreads** ever really run at the same time. + +This is both good and bad, but mostly good. It means PowerDNS does not +have to think about locking. No two threads will ever be talking to the +DNS cache at the same time, for example. + +It also means that the recursor could block if any operation takes too +long. + +The core interaction with MTasker are the waitEvent() and sendEvent() +functions. These pass around PacketID objects. Everything PowerDNS needs +to wait for is described by a PacketID event, so the name is a bit +misleading. Waiting for a TCP socket to have data available is also +passed via a PacketID, for example. + +The version of MTasker in PowerDNS is newer than that described at the +MTasker site, with a vital difference being that the waitEvent() +structure passes along a copy of the exact PacketID sendEvent() +transmitted. Furthermore, threads can trawl through the list of events +being waited for and modify the respective PacketIDs. This is used for +example with **near miss** packets: packets that appear to answer +questions we asked, but differ in the DNS id. On seeing such a packet, +the recursor trawls through all PacketIDs and if it finds any +nearmisses, it updates the PacketID::nearMisses counter. The actual +PacketID thus lives inside MTasker while any thread is waiting for it. + +MPlexer +------- + +The Recursor uses a separate socket per outgoing query. This has the +important benefit of making spoofing 64000 times harder, and +additionally means that ICMP errors are reported back to the program. In +measurements this appears to happen to one in ten queries, which would +otherwise take a two-second timeout before PowerDNS moves on to another +nameserver. + +However, this means that the program routinely needs to wait on hundreds +or even thousands of sockets. Different operating systems offer various +ways to monitor the state of sockets or more generally, file +descriptors. To abstract out the differing strategies (``select``, +``epoll``, ``kqueue``, ``completion ports``), PowerDNS contains +**MPlexer** classes, all of which descend from the FDMultiplexer class. + +This class is very simple and offers only five important methods: +addReadFD(), addWriteFD(), removeReadFD(), removeWriteFD() and run. + +The arguments to the **add** functions consist of an fd, a callback, and +a boost::any variable that is passed as a reference to the callback. + +This might remind you of the MTasker above, and it is indeed the same +trick: state is stored within the MPlexer. As long as a file descriptor +remains within either the Read or Write active list, its state will +remain stored. + +On arrival of a packet (or more generally, when an FD becomes readable +or writable, which for example might mean a new TCP connection), the +callback is called with the aforementioned reference to its parameter. + +The callback is free to call removeReadFD() or removeWriteFD() to remove +itself from the active list. + +PowerDNS defines such callbacks as newUDPQuestion(), newTCPConnection(), +handleRunningTCPConnection(). + +Finally, the run() method needs to be called whenever the program is +ready for new data. This happens in the main loop in pdns\_recursor.cc. +This loop is what MTasker refers to as **the kernel**. In this loop, any +packets or other MPlexer events get translated either into new MThreads +within MTasker, or into calls to sendEvent(), which in turn wakes up +other MThreads. + +MOADNSParser +------------ + +Yes, this does stand for **the Mother of All DNS Parsers**. And even +that name does not do it justice! The MOADNSParser is the third attempt +I've made at writing DNS packet parser and after two miserable failures, +I think I've finally gotten it right. + +Writing and parsing DNS packets, and the DNS records it contains, +consists of four things: + +1. Parsing a DNS record (from packet) into memory +2. Generating a DNS record from memory (to packet) +3. Writing out memory to user-readable zone format +4. Reading said zone format into memory + +This gets tedious very quickly, as one needs to implement all four +operations for each new record type, and there are dozens of them. + +While writing the MOADNSParser, it was discovered there is a remarkable +symmetry between these four transitions. DNS Records are nearly always +laid out in the same order in memory as in their zone format +representation. And reading is nothing but inverse writing. + +So, the MOADNSParser is built around the notion of a **Conversion**, and +we write all Conversion types once. So we have a Conversion from IP +address in memory to an IP address in a DNS packet, and vice versa. And +we have a Conversion from an IP address in zone format to memory, and +vice versa. + +This in turn means that the entire implementation of the ARecordContent +is as follows (wait for it!) + +:: + + conv.xfrIP(d_ip); + +Through the use of the magic called ``c++ Templates``, this one line +does everything needed to perform the four operations mentioned above. + +At one point, I got really obsessed with PowerDNS memory use. So, how do +we store DNS data in the PowerDNS recursor? I mentioned **memory** above +a lot - this means we could just store the DNSRecordContent objects. +However, this would be wasteful. + +For example, storing the following: + +:: + + www.example.org 3600 IN CNAME outpost.example.org. + +Would duplicate a lot of data. So, what is actually stored is a partial +DNS packet. To store the CNAMEDNSRecordContent that corresponds to the +above, we generate a DNS packet that has **www.example.org IN CNAME** as +its question. Then we add **3600 IN CNAME outpost.example.org**. as its +answer. Then we chop off the question part, and store the rest in the +**www.example.org IN CNAME** key in our cache. + +When we need to retrieve **www.example.org IN CNAME**, the inverse +happens. We find the proper partial packet, prefix it with a question +for **www.example.org IN CNAME**, and expand the resulting packet into +the answer **3600 IN CNAME outpost.example.org.**. + +Why do we go through all these motions? Because of DNS compression, +which allows us to omit the whole **.example.org.** part, saving us 9 +bytes. This is amplified when storing multiple MX records which all look +more or less alike. This optimization is not performed yet though. + +Even without compression, it makes sense as all records are +automatically stored very compactly. + +The PowerDNS recursor only parses a number of **well known record +types** and passes all other information across verbatim - it doesn't +have to know about the content it is serving. + +The C++ Standard Library / Boost +-------------------------------- + +C++ is a powerful language. Perhaps a bit too powerful at times, you can +turn a program into a real freakshow if you so desire. + +PowerDNS generally tries not to go overboard in this respect, but we do +build upon a very advanced part of the `Boost `__ +C++ library: `boost::multi index +container `__. + +This container provides the equivalent of SQL indexes on multiple keys. +It also implements compound keys, which PowerDNS uses as well. + +The main DNS cache is implemented as a multi index container object, +with a compound key on the name and type of a record. Furthermore, the +cache is sequenced, each time a record is accessed it is moved to the +end of the list. When cleanup is performed, we start at the beginning. +New records also get inserted at the end. For DNS correctness, the sort +order of the cache is case insensitive. + +The multi index container appears in other parts of PowerDNS, and +MTasker as well. + + Actual DNS Algorithm +--------------------- + +The DNS RFCs do define the DNS algorithm, but you can't actually +implement it exactly that way, it was written in 1987. + +Also, like what happened to HTML, it is expected that even non-standards +conforming domains work, and a sizable fraction of them is misconfigured +these days. + +Everything begins with SyncRes::beginResolve(), which knows nothing +about sockets, and needs to be passed a domain name, dns type and dns +class which we are interested in. It returns a vector of +DNSResourceRecord objects, ready for writing either into an answer +packet, or for internal use. + +After checking if the query is for any of the hardcoded domains +(localhost, version.bind, id.server), the query is passed to +SyncRes::doResolve, together with two vital parameters: the ``depth`` +and ``beenthere`` set. As the word **recursor** implies, we will need to +recurse for answers. The **depth** parameter documents how deep we've +recursed already. + +The ``beenthere`` set prevents loops. At each step, when a nameserver is +queried, it is added to the ``beenthere`` set. No nameserver in the set +will ever be queried again for the same question in the recursion +process - we know for a fact it won't help us further. This prevents the +process from getting stuck in loops. + +SyncRes::doResolve first checks if there is a CNAME in cache, using +SyncRes::doCNAMECacheCheck, for the domain name and type queried and if +so, changes the query (which is passed by reference) to the domain the +CNAME points to. This is the cause of many DNS problems, a CNAME record +really means **start over with this query**. + +This is followed by a call do SyncRes::doCacheCheck, which consults the +cache for a straight answer to the question (as possibly rerouted by a +CNAME). This function also consults the so called negative cache, but we +won't go into that just yet. + +If this function finds the correct answer, and the answer hasn't expired +yet, it gets returned and we are (almost) done. This happens in 80 to +90% of all queries. Which is good, as what follows is a lot of work. + +To recap: + +1. beginResolve() - entry point, does checks for hardcoded domains +2. doResolve() - start of recursion process, gets passed ``depth`` of 0 + and empty ``beenthere`` set +3. doCNAMECacheCheck() - check if there is a CNAME in cache which would + reroute the query +4. doCacheCheck() - see if cache contains straight answer to possibly + rerouted query. + +If the data we were queried for was in the cache, we are almost done. +One final step, which might as well be optional as nobody benefits from +it, is SyncRes::addCruft. This function does additional processing, +which means that if the query was for the MX record of a domain, we also +add the IP address of the mail exchanger. + +The non-cached case +^^^^^^^^^^^^^^^^^^^ + +This is where things get interesting, because we start out with a nearly +empty cache and have to go out to the net to get answers to fill it. + +The way DNS works, if you don't know the answer to a question, you find +somebody who does. Initially you have no other place to go than the root +servers. This is embodied in the SyncRes::getBestNSNamesFromCache +method, which gets passed the domain we are interested in, as well as +the ``depth`` and ``beenthere`` parameters mentioned earlier. + +From now on, assume our query will be for **``www.powerdns.com.``**. +SyncRes::getBestNSNamesFromCache will first check if there are NS +records in cache for ``www.powerdns.com.``, but there won't be. It then +checks ``powerdns.com. NS``, and while these records do exist on the +internet, the recursor doesn't know about them yet. So, we go on to +check the cache for ``com. NS``, for which the same holds. Finally we +end up checking for ``. NS``, and these we do know about: they are the +root servers and were loaded into PowerDNS on startup. + +So, SyncRes::getBestNSNamesFromCache fills out a set with the **names** +of nameservers it knows about for the **``.``** zone. + +This set, together with the original query **``www.powerdns.com``** gets +passed to SyncRes::doResolveAt. This function can't yet go to work +immediately though, it only knows the names of nameservers it can try. +This is like asking for directions and instead of hearing **take the +third right** you are told **go to 123 Fifth Avenue, and take a right** +- the answer doesn't help you further unless you know where 123 Fifth +Avenue is. + +SyncRes::doResolveAt first shuffles the nameservers both randomly and on +performance order. If it knows a nameserver was fast in the past, it +will get queried first. More about this later. + +Ok, here is the part where things get a bit scary. How does +SyncRes::doResolveAt find the IP address of a nameserver? Well, by +calling SyncRes::getAs (**get A records**), which in turn calls.. +SyncRes::doResolve. Hang on! That's where we came from! Massive +potential for loops here. Well, it turns out that for any domain which +can be resolved, this loop terminates. We do pass the ``beenthere`` set +again, which makes sure we don't keep on asking the same questions to +the same nameservers. + +Ok, SyncRes::getAs will give us the IP addresses of the chosen +root-server, because these IP addresses were loaded on startup. We then +ask these IP addresses (nameservers can have several) for its best +answer for **``www.powerdns.com.``**. This is done using the LWRes class +and specifically LWRes::asyncresolve, which gets passed domain name, +type and IP address. This function interacts with MTasker and MPlexer +above in ways which needn't concern us now. When it returns, the LWRes +object contains the best answers the queried server had for our domain, +which in this case means it tells us about the nameservers of ``com.``, +and their IP addresses. + +All the relevant answers it gives are stored in the cache (or actually, +merged), after which SyncRes::doResolveAt (which we are still in) +evaluates what to do now. + +There are 6 options: + +1. The final answer is in, we are done, return to SyncRes::doResolve and + SyncRes::beginResolve +2. The nameserver we queried tells us the domain we asked for + authoritatively does not exist. In case of the root-servers, this + happens when we query for *``www.powerdns.kom.``* for example, there + is no *``kom.``*. Return to SyncRes::beginResolve, we are done. +3. A lesser form - it tells us it is authoritative for the query we + asked about, but there is no record matching our type. This happens + when querying for the IPv6 address of a host which only has an IPv4 + address. Return to SyncRes::beginResolve, we are done. +4. The nameserver passed us a CNAME to another domain, and we need to + reroute. Go to SyncRes::doResolve for the new domain. +5. The nameserver did not know about the domain, but does know who does, + a *referral*. Stay within doResolveAt and loop to these new + nameservers. +6. The nameserver replied saying *no idea*. This is called a *lame + delegation*. Stay within SyncRes::doResolveAt and try the other + nameservers we have for this domain. + +When not redirected using a CNAME, this function will loop until it has +exhausted all nameservers and all their IP addresses. DNS is +surprisingly resilient that there is often only a single non-broken +nameserver left to answer queries, and we need to be prepared for that. + +This is the whole DNS algorithm in PowerDNS, all in less than 700 lines +of code. It contains a lot of tricky bits though, related to the cache. + +Some of the things we glossed over +---------------------------------- + +Whenever a packet is sent to a remote nameserver, the response time is +stored in the SyncRes::s\_nsSpeeds map, using an exponentially weighted +moving average. This EWMA averages out different response times, and +also makes them decrease over time. This means that a nameserver that +hasn't been queried recently gradually becomes **faster** in the eyes of +PowerDNS, giving it a chance again. + +A timeout is accounted as a 1s response time, which should take that +server out of the running for a while. + +Furthermore, queries are throttled. This means that each query to a +nameserver that has failed is accounted in the ``s_throttle`` object. +Before performing a new query, the query and the nameserver are looked +up via shouldThrottle. If so, the query is assumed to have failed +without even being performed. This saves a lot of network traffic and +makes PowerDNS quick to respond to lame servers. + +It also offers a modicum of protection against birthday attack powered +spoofing attempts, as PowerDNS will not inundate a broken server with +queries. + +The negative query cache we mentioned earlier caches the cases 2 and 3 +in the enumeration above. This data needs to be stored separately, as it +represents **non-data**. Each negcache query entry is the name of the +SOA record that was presented with the evidence of non-existence. This +SOA record is then retrieved from the regular cache, but with the TTL +that originally came with the NXDOMAIN (case 2) or NXRRSET (case 3). + + The Recursor Cache +------------------- + +As mentioned before, the cache stores partial packets. It also stores +not the **Time To Live** of records, but in fact the **Time To Die**. If +the cache contains data, but it is expired, that data should not be +deemed present. This bit of PowerDNS has proven tricky, leading to +deadlocks in the past. + +There are some other very tricky things to deal with. For example, +through a process called **more details**, a domain might have more +nameservers than listed in its parent zone. So, there might only be two +nameservers for ``powerdns.com.`` in the **``com.``** zone, but the +**``powerdns.com``** zone might list more. + +This means that the cache should not, when talking to the **``com.``** +servers later on, overwrite these four nameservers with only the two +copies the **``com.``** servers pass us. + +However, in other cases (like for example for SOA and CNAME records), +new data should overwrite old data. + +Note that PowerDNS deviates from RFC 2181 (section 5.4.1) in this +respect. + + Some small things +------------------ + +The server-side part of PowerDNS (``pdns_recursor.cc``), which listens +to queries by end-users, is fully IPv6 capable using the ComboAddress +class. This class is in fact a union of a ``struct sockaddr_in`` and a +``struct sockaddr_in6``. As long as the ``sin_family`` (or +``sin6_family``) and ``sin_port`` members are in the same place, this +works just fine, allowing us to pass a ComboAddress\*, cast to a +``sockaddr*`` to the socket functions. For convenience, the ComboAddress +also offers a length() method which can be used to indicate the length - +either sizeof(sockaddr\_in) or sizeof(sockaddr\_in6). + +Access to the recursor is governed through the NetmaskGroup class, which +internally contains Netmask, which in turn contain a ComboAddress. diff --git a/pdns/recursordist/docs/changelog/4.0.rst b/pdns/recursordist/docs/changelog/4.0.rst new file mode 100644 index 0000000000..7bbe10ca7b --- /dev/null +++ b/pdns/recursordist/docs/changelog/4.0.rst @@ -0,0 +1,570 @@ +Changelogs for 4.0.x +==================== + +This page has all the changelogs for the PowerDNS Recursor 4.0 release train. + +PowerDNS Recursor 4.0.5 +----------------------- + +Released 13th of June 2017 + +This release adds ed25519 (algorithm 15) support for DNSSEC and adds the +2017 DNSSEC root key. If you do DNSSEC validation, this upgrade is +**mandatory** to continue validating after October 2017. + +Bug fixes +^^^^^^^^^ + +- `commit af76224 `__: + Correctly lowercase the TSIG algorithm name in hash computation, + fixes `#4942 `__ +- `commit 86c4ed0 `__: + Clear the RPZ NS IP table when clearing the policy, this prevents + false positives +- `commit 5e660e9 `__: + Fix cache-only queries against a forward-zone, fixes + `#5211 `__ +- `commit 2875033 `__: + Only delegate if NSes are below apex in auth-zones, fixes + `#4771 `__ +- `commit e7c183d `__: + Remove hardcoding of port 53 for TCP/IP forwarded zones in recursor, + fixes `#4799 `__ +- `commit 5bec36e `__: + Make sure ``labelsToAdd`` is not empty in ``getZoneCuts()`` +- `commit 0f59e05 `__: + Wait until after daemonizing to start the outgoing protobuf thread, + prevents hangs when the protobuf server is not available +- `commit 233e144 `__: + Ensure (re)priming the root never fails +- `commit 3642cb3 `__: + Don't age the root, fixes a regression from 3.x +- `commit 83f9226 `__: + Fix exception when sending a protobuf message for an empty question +- `commit ffdd813 `__: + LuaWrapper: Allow embedded NULs in strings received from Lua +- `commit c5ffd90 `__: + Fix coredumps on illumos/SmartOS, fixes + `#4579 `__ (Roman + Dayneko) +- `commit 651c0e9 `__: + StateHolder: Allocate (and copy if needed) before taking the lock +- `commit 547d68f `__: + SuffixMatchNode: Fix insertion issue for an existing node +- `commit 3ada4e2 `__: + Fix negative port detection for IPv6 addresses on 32-bit systems + +Additions and Enhancements +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- `commit 7705e1c `__: + Add support for RPZ wildcarded target names. Fixes + `#5237 `__ +- `#5165 `__: Speed up RPZ + zone loading and add a ``zoneSizeHint`` parameter to ``rpzFile`` and + ``rpzMaster`` for faster reloads +- `#4794 `__: Make the + RPZ summary consistent (Fixes + `#4342 `__) and log + additions/removals at debug level, not info +- `commit 1909556 `__: + Add the 2017 root key +- `commit abfe671 `__ + and `commit + 7abbb2c `__: Update + Ed25519 `algorithm number and + mnemonic `__ + and hook up to the Recursor (Kees Monshouwer) +- `#5355 `__: Add + ``use-incoming-edns-subnet`` option to process and pass along ECS and + fix some ECS bugs in the process +- `commit dff1a11 `__: + Refuse to start with chroot set in a systemd env (Fixes + `#4848 `__) +- `commit 5a38a56 `__: + Handle exceptions raised by ``closesocket()`` to prevent process + termination +- `#4619 `__: Document + missing ``top-pub-queries`` and ``top-pub-servfail-queries`` commands + for ``rec_control`` (phonedph1) +- `commit 502a850 `__: + IPv6 address for g.root-servers.net added (Kevin Otte) +- `commit 7a2a645 `__: + Log outgoing queries / incoming responses via protobuf + +PowerDNS Recursor 4.0.4 +----------------------- + +Released January 13th 2017 + +The 4.0.4 version of the PowerDNS Recursor fixes PowerDNS Security +Advisories :doc:`2016-02 <../security-advisories/powerdns-advisory-2016-02>` and +:doc:`2016-04 <../security-advisories/powerdns-advisory-2016-04>`. + +Bug fixes +^^^^^^^^^ + +- `commit 658d9e4 `__: + Check TSIG signature on IXFR (Security Advisory + :doc:`2016-04 <../security-advisories/powerdns-advisory-2016-04>`) +- `commit 91acd82 `__: + Don't parse spurious RRs in queries when we don't need them (Security + Advisory :doc:`2016-02 <../security-advisories/powerdns-advisory-2016-02>`) +- `commit 400e28d `__: + Fix incorrect length check in ``DNSName`` when extracting qtype or + qclass +- `commit 2168188 `__: + rec: Wait until after daemonizing to start the RPZ and protobuf + threads +- `commit 3beb3b2 `__: + On (re-)priming, fetch the root NS records +- `commit cfeb109 `__: + rec: Fix src/dest inversion in the protobuf message for TCP queries +- `commit 46a6666 `__: + NSEC3 optout and Bogus insecure forward fixes +- `commit bb437d4 `__: + On RPZ customPolicy, follow the resulting CNAME +- `commit 6b5a8f3 `__: + DNSSEC: don't go bogus on zero configured DSs +- `commit 1fa6e1b `__: + Don't crash on an empty query ring +- `commit bfb7e5d `__: + Set the result to NoError before calling ``preresolve`` + +Additions and Enhancements +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- `commit 7c3398a `__: + Add ``max-recursion-depth`` to limit the number of internal recursion +- `commit 3d59c6f `__: + Fix building with ECDSA support disabled in libcrypto +- `commit 0170a3b `__: + Add requestorId and some comments to the protobuf definition file +- `commit d8cd67b `__: + Make the negcache forwarded zones aware +- `commit 46ccbd6 `__: + Cache records for zones that were delegated to from a forwarded zone +- `commit 5aa64e6 `__, + `commit 5f4242e `__ + and `commit + 0f707cd `__: DNSSEC: + Implement keysearch based on zone-cuts +- `commit ddf6fa5 `__: + rec: Add support for boost::context >= 1.61 +- `commit bb6bd6e `__: + Add ``getRecursorThreadId()`` to Lua, identifying the current thread +- `commit d8baf17 `__: + Handle CNAMEs at the apex of secure zones to other secure zones + +PowerDNS Recursor 4.0.3 +----------------------- + +Released September 6th 2016 + +The 4.0.3 version of the PowerDNS Recursor features many improvements to +the Policy Engine (RPZ) and the Lua bindings to it. We would like to +thank Wim (`42wim `__) for testing and +reporting on the RPZ module. + +Bug fixes +^^^^^^^^^ + +- `#4350 `__: Call + ``gettag()`` for TCP queries +- `#4376 `__: Fix the use + of an uninitialized filtering policy +- `#4381 `__: Parse + query-local-address before lua-config-file +- `#4383 `__: Fix accessing + an empty policyCustom, policyName from Lua +- `#4387 `__: ComboAddress: + don't allow invalid ports +- `#4388 `__: Fix RPZ + default policy not being applied over IXFR +- `#4391 `__: DNSSEC: + Actually follow RFC 7646 §2.1 +- `#4396 `__: Add boost + context ldflags so freebsd builds can find the libs +- `#4402 `__: Ignore NS + records in a RPZ zone received over IXFR +- `#4403 `__: Fix build + with OpenSSL 1.1.0 final +- `#4404 `__: Don't + validate when a Lua hook took the query +- `#4425 `__: Fix a + protobuf regression (requestor/responder mix-up) + +Additions and Enhancements +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- `#4394 `__: Support Boost + 1.61+ fcontext +- `#4402 `__: Add Lua + binding for DNSRecord::d\_place + +PowerDNS Recursor 4.0.2 +----------------------- + +Released August 26th 2016 + +This release fixes a regression in 4.x where CNAME records for DNSSEC +signed domains were not sorted before the final answers, leading to some +clients (notably some versions of Chrome) not being able to extract the +required answer from the packet. This happened exclusively for DNSSEC +signed domains, but the problem happens even for clients not requesting +DNSSEC validation. + +Further fixes and changes can be found below: + +Bug fixes +^^^^^^^^^ + +- `#4264 `__: Set + ``dq.rcode`` before calling postresolve +- `#4294 `__: Honor PIE + flags. +- `#4310 `__: Fix build + with LibreSSL, for which OPENSSL\_VERSION\_NUMBER is irrelevant +- `#4340 `__: Don't shuffle + CNAME records. +- `#4354 `__: Fix + delegation-only + +Additions and enhancements +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- `#4288 `__: Respect the + timeout when connecting to a protobuf server +- `#4300 `__: allow newDN + to take a DNSName in; document missing methods +- `#4301 `__: expose SMN + toString to lua +- `#4318 `__: Anonymize the + protobuf ECS value as well +- `#4324 `__: Allow Lua + access to the result of the Policy Engine decision, skip RPZ, finish + RPZ implementation +- `#4349 `__: Remove unused + ``DNSPacket::d_qlen`` +- `#4351 `__: RPZ: Use + query-local-address(6) by default +- `#4357 `__: Move the root + DNSSEC data to a header file + +PowerDNS Recursor 4.0.1 +----------------------- + +Released July 29th 2016 + +This release has several improvements with regards to DNSSEC validation +and it improves interoperability with DNSSEC clients that expect an +AD-bit on validated data when they query with only the DO-bit set. + +Bug fixes +^^^^^^^^^ + +- `#4119 `__ Improve DNSSEC + record skipping for non dnssec queries (Kees Monshouwer) +- `#4162 `__ Don't validate + zones from the local auth store, go one level down while validating + when there is a CNAME +- `#4187 `__: +- Don't go bogus on islands of security +- Check all possible chains for Insecures +- Don't go Bogus on a CNAME at the apex +- `#4215 `__ RPZ: default + policy should also override local data RRs +- `#4243 `__ Fix a crash + when the next name in a chained query is empty and + ``rec_control current-queries`` is invoked + +Improvements +^^^^^^^^^^^^ + +- `#4056 `__ OpenSSL 1.1.0 + support (Christian Hofstaedtler) +- `#4133 `__ Add limits to + the size of received {A,I}XFR (CVE-2016-6172) +- `#4140 `__ Fix warnings + with gcc on musl-libc (James Taylor) +- `#4160 `__ Also validate + on +DO +- `#4164 `__ Fail to start + when the lua-dns-script does not exist +- `#4168 `__ Add more + Netmask methods for Lua (Aki Tuomi) +- `#4210 `__ Validate + DNSSEC for security polling +- `#4217 `__ Turn on + root-nx-trust by default and log-common-errors=off +- `#4207 `__ Allow for + multiple trust anchors per zone +- `#4242 `__ Fix + compilation warning when building without Protobuf + +PowerDNS Recursor 4.0.0 +----------------------- + +Released July 11th 2016 + +PowerDNS Recursor 4.0.0 is part of `the great 4.x "Spring +Cleaning" `__ +of PowerDNS which lasted through the end of 2015. + +As part of the general cleanup, we did the following: + +- Moved to C++ 2011, a cleaner more powerful version of C++ that has + allowed us to `improve the quality of + implementation `__ + in many places. +- Implemented dedicated infrastructure for dealing with DNS names that + is fully "DNS Native" and needs less escaping and unescaping +- Switched to binary storage of DNS records in all places +- Moved ACLs to a dedicated Netmask Tree +- Implemented a version of + `RCU `__ for + configuration changes +- Instrumented our use of the memory allocator, reduced number of + malloc calls substantially. +- The Lua hook infrastructure was redone using LuaWrapper; old scripts + will no longer work, but new scripts are easier to write under the + new interface. + +In addition to this cleanup, which has many internal benefits and solves +longstanding issues with escaped domain names, 4.0.0 brings the +following major new features: + +- RPZ aka Response Policy Zone support +- IXFR slaving in the PowerDNS Recursor for RPZ +- DNSSEC processing in Recursor (Authoritative has had this for years) +- DNSSEC validation (without NSEC(3) proof validation) +- EDNS Client Subnet support in PowerDNS Recursor (Authoritative has + had this for years) +- Lua asynchronous queries for per-IP/per-domain status +- Caches that can now be wiped per whole zone instead of per name +- Statistics on authoritative server response times (split for IPv4 and + IPv6) +- APIs are no longer marked as 'experimental' and had one final URL + change +- New metric: tcp-answer-bytes to measure DNS TCP/IP bandwidth, and + many other new metrics + +Please be aware that beyond the items listed here, there have been heaps +of tiny changes. As always, please carefully test a new release before +deploying it. + +This release features the following fixes compared to rc1: + +- `#3989 `__ Fix usage of + std::distance() in DNSName::isPartOf() (signed/unsigned comparisons) +- `#4017 `__ Fix building + without Lua. Add ``isTcp`` to ``dq``. +- `#4023 `__ Actually log + on dnssec=log-fail +- `#4028 `__ DNSSEC fixes + (NSEC casing, send DO-bit over TCP, DNSSEC trace additions) +- `#4052 `__ Don't fail + configure on missing fcontext.hpp +- `#4096 `__ Don't call + ``commit()`` if we skipped all the records + +It has the following improvements: + +- `#3400 `__ Enable + building on OpenIndiana +- `#4016 `__ Log protobuf + messages for cache hits. Add policy tags in gettag() +- `#4040 `__ Allow DNSSEC + validation when chrooted +- `#4094 `__ Sort included + html files for improved reproducibility (Christian Hofstaedtler) + +And these additions: + +- `#3981 `__ Import + JavaScript sources for libs shipped with Recursor (Christian + Hofstaedtler) +- `#4012 `__ add tags + support to ProtobufLogger.py +- `#4032 `__ Set the + existing policy tags in ``dq`` for ``{pre,post}resolve`` +- `#4077 `__ Add DNSSEC + validation statistics +- `#4090 `__ Allow + reloading the lua-config-file at runtime +- `#4097 `__ Allow logging + DNSSEC bogus in any mode +- `#4125 `__ Add protobuf + fields for the query's time in the response + +PowerDNS Recursor 4.0.0-rc1 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Released June 9th 2016 + +This first (and hopefully last) Release Candidate contains the finishing +touches to the experimental DNSSEC support by adding (Negative) Trust +Anchor support and fixing a possible issue with DNSSEC and forwarded +domains: + +- `#3910 `__ Add (Negative) + Trust Anchor management +- `#3926 `__ Set +CD on + forwarded recursive queries + +Other changes: + +- `#3941 `__ Ensure + delegations from local auth zones are followed +- `#3924 `__ Add a virtual + hosting unit-file +- `#3929 `__ Set the FDs in + the unit file to a sane value + +Bug fixes: + +- `#3961 `__ Fix building + on EL6 i386 +- `#3957 `__ Add error + reporting when parsing forward-zones(-recurse) (Aki Tuomi) + +PowerDNS Recursor 4.0.0-beta1 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Released May 27th 2016 + +This release fixes a bug in the DNSSEC implementation where a name would +we validated as bogus when talking to non-compliant authoritative +servers: + +- `#3875 `__ Disable DNSSEC + for domain where the auth responds with FORMERR or NOTIMP + +Improvements +^^^^^^^^^^^^ + +- `#3866 `__ Increase max + FDs in systemd unit file +- `#3905 `__ Add a + dnssec=process-no-validate option and make it default + +Bug fixes +^^^^^^^^^ + +- `#3881 `__ Fix the + ``noEdnsOutQueries`` counter +- `#3892 `__ support + ``clock_gettime`` for platforms that require -lrt + +PowerDNS Recursor 4.0.0-alpha3 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Released May 10th 2016 + +This release features several leaps in the correctness and stability of +the DNSSEC implementation. + +Notable changes are: + +- `#3752 `__ Correct + handling of query flags in conformance with `RFC + 6840 `__ + +Bug fixes +^^^^^^^^^ + +- `#3804 `__ Fix a memory + leak in DNSSEC validation +- `#3785 `__ and + `#3390 `__ Correctly + validate insecure delegations +- `#3606 `__ Various DNSSEC + fixes, disabling DNSSEC on forward-zones +- `#3681 `__ Catch + exception with a malformed DNSName in ``rec_control wipe-cache`` +- `#3779 `__, + `#3768 `__, + `#3766 `__, + `#3783 `__ and + `#3789 `__ DNSName and + other hardening improvements + +Improvements +^^^^^^^^^^^^ + +- `#3801 `__ Add missing + Lua rcodes bindings +- `#3587 `__ Update L-Root + addresses + +PowerDNS Recursor 4.0.0-alpha2 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Released March 9th 2016 + +Note that the DNSSEC implementation has several bugs in this release, it +is advised to set ``dnssec=off`` in your recursor.conf. + +This release features many low-level performance fixes. Other notable +changes since 4.0.0-alpha1 are: + +- `#3259 `__, + `#3280 `__ The PowerDNS + Recursor now properly uses GNU autoconf and autotools for building + and installing +- OpenSSL crypto primitives are now used for DNSSEC validation +- `#3313 `__ Implement the + logic we need to generate EDNS MAC fields in dnsdist & read them in + recursor + (`blogpost `__ +- `#3350 `__ Add + lowercase-outgoing feature to Recursor +- `#3410 `__ Recuweb is now + built-in to the daemon +- `#3230 `__ API: drop + JSONP, add web security headers (Christian Hofstaedtler) +- `#3485 `__ Allow multiple + carbon-servers +- `#3427 `__, + `#3479 `__, + `#3472 `__ MTasker + modernization (Andrew Nelless) + +Bug fixes +~~~~~~~~~ + +- `#3444 `__, + `#3442 `__ RPZ IXFR fixes +- `#3448 `__ Remove + edns-subnet-whitelist whitelist pointing to powerdns.com (Christian + Hofstaedtler) +- `#3293 `__ make + asynchronous UDP Lua queries work again in 4.x +- `#3365 `__ Apply rcode + set in UDPQueryResponse callback (Jan Broers) +- `#3244 `__ Fix the + forward zones in the recursor +- `#3135 `__ Use 56 bits + instead of 64 in EDNS Client Subnet option (Winfried Angele) +- `#3527 `__ Make the + recursor counters atomic + +Improvements +~~~~~~~~~~~~ + +- `#3435 `__ Add + ``toStringNoDot`` and ``chopOff`` functions to Lua +- `#3437 `__ Add + ``pdns.now`` timeval struct to recursor Lua +- `#3352 `__ Cache + improvements +- `#3502 `__ Make second + argument to pdnslog optional (Thiago Farina) +- `#3520 `__ Reduce log + level of periodic statistics to notice (Jan Broers) + +PowerDNS Recursor 4.0.0-alpha1 +------------------------------ + +Released December 24th 2015 + diff --git a/pdns/recursordist/docs/changelog/4.1.rst b/pdns/recursordist/docs/changelog/4.1.rst new file mode 100644 index 0000000000..c43285aa92 --- /dev/null +++ b/pdns/recursordist/docs/changelog/4.1.rst @@ -0,0 +1,51 @@ +Changelogs for 4.1.x +==================== + +.. changelog:: + :version: 4.1.0 + + This is the first release of the PowerDNS Recursor in the 4.1 release train. + This release contains several performance and correctness improvements in the EDNS Client subnet area, as well as better DNSSEC processing. + + .. change:: + :tags: New Features + :pullreq: 5138 + :tickets: 5128 + + Add server-side TCP Fast Open support. + This adds a new option :ref:`setting-tcp-fast-open`. + + .. change:: + :tags: New Features + :pullreq: 4569 + + Pass ``tcp`` to :func:`gettag` to allow a script to take different actions whether a query came in over TCP or UDP. + + .. change:: + :tags: New Features + :pullreq: 4569 + + Allow setting the requestor ID field in the :attr:`DNSQuestion ` from all hooks. + + .. change:: + :tags: Improvements, DNSSEC + :pullreq: 5463, 5223 + :tickets: 4994, 4490, 4362, 4254 + + Implement "on-the-fly" DNSSEC processing. + This places the DNSSEC processing alongside the regular recursion, reducing possible cornercases. + + .. change:: + :tags: Improvements + :pullreq: 5063 + :tickets: 2818 + + Implement CNAME wildcards in recursor authoritative component. + + .. change:: + :tags: Bug Fixes + :pullreq: 5078 + :tickets: 4939, 5075 + + Show a useful error when an invalid :ref:`setting-lua-config-file` is configured. + diff --git a/pdns/recursordist/docs/changelog/index.rst b/pdns/recursordist/docs/changelog/index.rst new file mode 100644 index 0000000000..27fd24e1e3 --- /dev/null +++ b/pdns/recursordist/docs/changelog/index.rst @@ -0,0 +1,11 @@ +Changelogs +========== + +The changelogs for the recursor are split between release trains. + +.. toctree:: + :maxdepth: 2 + + 4.1 + 4.0 + pre-4.0 diff --git a/pdns/recursordist/docs/changelog/pre-4.0.rst b/pdns/recursordist/docs/changelog/pre-4.0.rst new file mode 100644 index 0000000000..a900915b04 --- /dev/null +++ b/pdns/recursordist/docs/changelog/pre-4.0.rst @@ -0,0 +1,2186 @@ +Changelogs for all pre 4.0 releases +=================================== + +**Note**: Beyond PowerDNS 2.9.20, the Authoritative Server and Recursor are released separately. +Hence, this changelog starts at version 3.0. + +PowerDNS Recursor 3.6.4 +----------------------- + +Released 9th of June 2015 + +This is a security release fixing :doc:`Security Advisory +2015-01 <../security-advisories/powerdns-advisory-2015-01>` + +Bug fixes: + +- `commit bccd068 `__: + Limit the maximum length of a qname + +PowerDNS Recursor 3.7.3 +----------------------- + +Released 9th of June 2015 + +Bug fixes: + +- `commit 92f7b2b `__: + Limit the maximum length of a qname + +This is a security release fixing :doc:`Security Advisory +2015-01 <../security-advisories/powerdns-advisory-2015-01>` + +Improvements: + +- `commit 46366a5 `__, + `commit f318a7d `__: + pdnssec: check for glue and delegations in parent zones (Kees + Monshouwer) + +PowerDNS Recursor 3.7.2 +----------------------- + +Released 23rd of April, 2015 + +Among other bug fixes and improvements (as listed below), this release +incorporates a fix for CVE-2015-1868, as detailed in :doc:`PowerDNS Security +Advisory 2015-01 <../security-advisories/powerdns-advisory-2015-01>` + +Bug fixes: + +- `commit adb10be `__ + `commit 3ec3e0f `__ + `commit dc02ebf `__ + Fix handling of forward references in label compressed packets; fixes + CVE-2015-1868 +- `commit a7be3f1 `__: + make sure we never call sendmsg with msg\_control!=NULL && + msg\_controllen>0. Fixes `ticket + #2227 `__ +- `commit 9d835ed `__: + Improve robustness of root-nx-trust. + +Improvements: + +- `commit 99c595b `__: + Silence warnings that always occur on FreeBSD (Ruben Kerkhof) + +PowerDNS Recursor 3.6.3 +----------------------- + +Released 23rd of April, 2015 + +The only difference between Recursor 3.6.2 and 3.6.3 is a fix for +CVE-2015-1868, as detailed in :doc:`PowerDNS Security Advisory +2015-01 <../security-advisories/powerdns-advisory-2015-01>` + +PowerDNS Recursor 3.7.0 +----------------------- + +Unreleased, please see the 3.7.1 changelog below. + +PowerDNS Recursor 3.7.1 +----------------------- + +Released February 12th, 2015. + +This version contains a mix of speedups and improvements, the combined +effect of which is vastly improved resilience against traffic spikes and +malicious query overloads. + +Of further note is the massive community contribution, mostly over +Christmas. Especially Ruben Kerkhof, Pieter Lexis, Kees Monshouwer and +Aki Tuomi delivered a lot of love. Thanks! + +Minor changes: + +- Removal of dead code here and there + 04dc6d618734fc630122de4c56dff641ebaf0988 +- Per-qtype response counters are now 64 bit + 297bb6acf7902068693a4aae1443c424d0e8dd52 on 64 bit systems +- Add IPv6 addresses for b and c.root-servers.net hints + efc2595423c9a1be6f2d8f4da25445198ceb8b57 +- Add IP address to logging about terminated queries + 37aa9904d1cc967ba4b5d5e17dbe41485f8cdece +- Improve qtype name logging fab3ed3453e15ae88e29a0e4071b214eb19caad9 + (Aki Tuomi) +- Redefine 'BAD\_NETS' for dont-query based on newer IANA guidance + 12cd44ee0fcde5893f85dccc499bfc35152c5fff (lochiiconnectivity) +- Add documentation links to systemd unit + eb154adfdffa5c78624e2ea98e938d7b5787119e (Ruben Kerkhof) + +Improvements: + +- Upgrade embedded PolarSSL to 1.3.9: + d330a2ea1a93d7675ef680311f8aa0306aeefcf1 +- yahttp upgrade c290975778942ed1082ca66918695a5bd2d6bac4 + c65a57e888ee48eaa948e590c90c51420bffa847 (Aki Tuomi) +- Replace . in hostnames by - for Carbon so as not to confuse Metronome + 46541751ed1c3bc051d78217543d5fc76733e212 +- Manpages got a lot of love and are now built from Markdown (Pieter + Lexis) +- Move to PolarSSL base64 488360551009784ab35c43ee4580e773a2a8a227 + (Kees Monshouwer) +- The quiet=no query logging is now more informative + 461df9d20c560d240285f772c09b3beb89d46daa +- We can finally bind to 0.0.0.0 and :: and guarantee answers from the + correct source b71b60ee73ef3c86f80a2179981eda2e61c4363f +- We use per-packet timestamps to drop ancient traffic in case of + overload b71b60ee73ef3c86f80a2179981eda2e61c4363f, non-Linux + portability in d63f0d83631c41eff203d30b0b7c475a88f1db59 +- Builtin webserver can be queried with the API key in the URL again + c89f8cd022c4a9409b95d22ffa3b03e4e98dc400 +- Ringbuffers are now available via API + c89f8cd022c4a9409b95d22ffa3b03e4e98dc400 +- Lua 5.3 compatibility 59c6fc3e3931ca87d484337daee512e716bc4cf4 (Kees + Monshouwer) +- No longer leave a stale UNIX domain socket around from rec\_control + if the recursor was down 524e4f4d81f4ed9eb218715cbc8a59f0b9868234, + ticket #2061 +- Running with 'quiet=no' would strangely actually prevent debug + messages from being logged f48d7b657ec32517f8bfcada3bfe6353ca313314 +- Webserver now implements CORS for the API + ea89a97e864c43c1cb03f2959ad04c4ebe7580ad, fixing ticket #1984 +- Houskeeping thread would sometimes run multiple times simultaneously, + which worked, but was odd cc59bce675e62e2b9657b42614ce8be3312cae82 + +New features: + +- New ``root-nx-trust`` flag makes PowerDNS generalize NXDOMAIN + responses from the root-servers + 01402d56846a3a61811ebd4e6bc97e53f908e568 +- ``getregisteredname()`` for Lua, which turns 'www.bbc.co.uk' into + 'bbc.co.uk' 8cd4851beb78bc6ab320926fb5cb6a09282016b1 +- Lua preoutquery filter 3457a2a0ec41d3b3aff7640f30008788e1228a6e +- Lua IP-based filter (ipfilter) before parsing packets + 4ea949413c495254acb0bd19335142761c1efc0c +- ``iputils`` class for Lua, to quickly process IP addresses and + netmasks in their native format +- ``getregisteredname`` function for Lua, to find the registered domain + for a given name +- Various new ringbuffers: top-servfail-remotes, + top-largeanswer-remotes, top-servfail-queries + +Speedups: + +- Remove unneeded malloc traffic + 93d4a89096e64d53740790f58fadec56f6a0af14 + 8682c32bc45b6ffa7c0f6da778e1b223ae7f03ce + a903b39cfe7364c56324038264d3db50b8cece87 +- Our nameserver-loop detection carried around a lot of baggage for + complex domain names, plus did not differentiate IPv4 and IPv6 well + enough 891fbf888ccac074e3edc38864641ca774f2f03c +- Prioritize new queries over nameserver responses, improving latency + under query bursts bf3b0cec366c090af000b066267b6f6bbb3a512a +- Remove escaping in case there was nothing to escape + 83b746fd1d94c8742d8bd87a44beb44c154230c7 +- Our logging infrastructure had a lot of locking + d1449e4d073595e1e1581804f121fc90e37158bf +- Reduce logging level of certain common messages, which locked up + synchronously logging systems + 854d44e31c76aa650520e6d462dd3a02b5936f7a +- Add limit on total wall-clock time spent on a query + 9de3e0340fa066d4c59449e1643a1de8c343f8f2 +- Packet cache is now case-insensitive, which increases hitrate + 90974597aadaf1096e3fd0dc450be7422ea591a5 + +Security relevant: + +- Check for PIE, RELRO and stack protector during configure + 8d0354b189c12e1e14f5309d3b49935c17f9eeb0 (Aki Tuomi) +- Testing for support of PIE etc was improved in + b2053c28ccb9609e2ce7bcb6beda83f98a062aa3 and beyond, fixes #2125 + (Ruben Kerkhof) +- Max query-per-query limit (max-qperq) is now configurable + 173d790ead08f67733010ca4c6fc404a040fe699 + +Bugs fixed: + +- IPv6 outgoing queries had a disproportionate effect on our query + load. Fixed in 76f190f2a0877cd79ede2994124c1a58dc69ae49 and beyond. +- rec\_control gave incorrect output on a timeout + 12997e9d800734da51b808767e1e2477244c30eb +- When using the webserver AND having an error in the Lua script, + recursor could crash during startup + 62f0ae62984adadab687c23fe1b287c1f219b2cb +- Hugely long version strings would trip up security polling + 18b7333828a1275ae5f5574a9c8330290d8557ff (Kees Monshouwer) +- The 'remotes' ringbuffer was sized incorrectly + f8f243b01215d6adcb59389f09ef494f1309041f +- Cache sizes had an off-by-one scaling problem, with the wrong number + of entries allocated per thread + f8f243b01215d6adcb59389f09ef494f1309041f +- Our automatic file descriptor limit raising was attempted *after* + setuid, which made it a lot less effective. Found and fixed by Aki + Tuomi a6414fdce9b0ec32c340d1f2eea2254f3fedc1c1 +- Timestamps used for dropping packets were occasionally wrong + 183eb8774e4bc2569f06d5894fec65740f4b70b6 and + 4c4765c104bacc146533217bcc843efb244a8086 (RC2) with thanks to + Winfried for debugging. +- In RC1, our new DoS protection measures would crash the Recursor if + too many root servers were unreachable. + 6a6fb05ad81c519b4002ed1db00f3ed9b7bce6b4. Debugging and testing by + Fusl. + +Various other documentation changes by Christian Hofstaedtler and Ruben +Kerkhof. Lots of improvements all over the place by Kees Monshouwer. + +PowerDNS Recursor 3.6.2 +----------------------- + +**Note**: Version 3.6.2 is a bugfix update to 3.6.1. Released on the +30th of October 2014. + +`Official download page `__ + +A list of changes since 3.6.1 follows. + +- `commit ab14b4f `__: + expedite servfail generation for ezdns-like failures (fully abort + query resolving if we hit more than 50 outqueries). This also + prevents the issue documented in :doc:`PowerDNS Security Advisory + 2014-02 <../security-advisories/powerdns-advisory-2014-02>` (CVE-2014-8601) +- `commit 42025be `__: + PowerDNS now polls the security status of a release at startup and + periodically. More detail on this feature, and how to turn it off, + can be found in `Security + polling `__. +- `commit 5027429 `__: + We did not transmit the right 'local' socket address to Lua for + TCP/IP queries in the recursor. In addition, we would attempt to + lookup a filedescriptor that wasn't there in an unlocked map which + could conceivably lead to crashes. Closes `ticket + 1828 `__, thanks + Winfried for reporting +- `commit 752756c `__: + Sync embedded yahttp copy. API: Replace HTTP Basic auth with static + key in custom header +- `commit 6fdd40d `__: + add missing ``#include `` to rec-channel.hh (this fixes + building on OS X). + +PowerDNS Recursor 3.6.1 +----------------------- + +**Warning**: Version 3.6.1 is a mandatory security upgrade to 3.6.0! +Released on the 10th of September 2014. + +PowerDNS Recursor 3.6.0 could crash with a specific sequence of packets. +For more details, see `the +advisory `__. PowerDNS Recursor +3.6.1 was very well tested, and is in full production already, so it +should be a safe upgrade. + +Downloads +^^^^^^^^^ + +- `Official download page `__ + +In addition to various fixes related to this potential crash, 3.6.1 +fixes a few minor issues and adds a debugging feature: + +- We could not encode IPv6 AAAA records that mapped to IPv4 addresses + in some cases (:ffff.1.2.3.4). Fixed in `commit + c90fcbd `__ , + closing `ticket + 1663 `__. +- Improve systemd startup timing with respect to network availability + (`commit + cf86c6a `__), thanks + to Morten Stevens. +- Realtime telemetry can now be enabled at runtime, for example with + 'rec\_control carbon-server 82.94.213.34 ourname1234'. This ties in + to our existing carbon-server and carbon-ourname settings, but now at + runtime. This specific invocation will make your stats appear + automatically on our `public telemetry + server `__. + +PowerDNS Recursor version 3.6.0 +------------------------------- + +This is a performance, feature and bugfix update to 3.5/3.5.3. It +contains important fixes for slightly broken domain names, which your +users expect to work anyhow. It also brings robust resilience against +certain classes of attacks. + +Downloads +^^^^^^^^^ + +- `Official download page `__ +- `native RHEL5/6 packages from Kees + Monshouwer `__ + +Changes between RC1 and release +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- `commit 30b13ef `__: + do not apply some of our filters to root and gtlds, plus remove some + useless {} +- `commit cc81d90 `__: + fix yahttp copy in dist-recursor for BSD cp +- `commit b798618 `__: + define \_\_APPLE\_USE\_RFC\_3542 during recursor build on Darwin, + fixes `ticket 1449 `__ +- `commit 1d7f863 `__: + Merge pull request `ticket + 1443 `__ from + zeha/recursor-nostrip +- `commit 5cdeede `__: + remove (non-working) [aaaa-]additional-processing flags from the + recursor. Closes `ticket + 1448 `__ +- `commit 984d747 `__: + Support building recursor on kFreeBSD and Hurd +- `commit 79240f1 `__: + Allow not stripping of binaries in recursor's make install +- `commit e9c2ad3 `__: + document pdns.DROP for recursor, add policy-drops metric for it + +New features +^^^^^^^^^^^^ + +- `commit aadceba `__: + Implement minimum-ttl-override config setting, plus runtime + configurability via 'rec\_control set-minimum-ttl'. +- Lots of work on the JSON API, which is exposed via Aki Tuomi's + 'yahttp'. Massive thanks to Christian Hofstaedtler for delivering + this exciting new functionality. Documentation & demo forthcoming, + but code to use it is available `on + GitHub `__. +- Lua modules can now use 'pdnslog(INFO..'), as described in `ticket + 1074 `__, implemented + in `commit + 674a305 `__ +- Adopt any-to-tcp feature to the recursor. Based on a patch by + Winfried Angele. Closes `ticket + 836 `__, `commit + 56b4d21 `__ and + `commit e661a20 `__. +- `commit 2c78bd5 `__: + implement built-in statistics dumper using the 'carbon' protocol, + which is also understood by metronome (our mini-graphite). Use + 'carbon-server', 'carbon-ourname' and 'carbon-interval' settings. +- New setting 'udp-truncation-threshold' to configure from how many + bytes we should truncate. `commit + a09a8ce `__. +- Proper support for CHaos class for CHAOS TXT queries. `commit + c86e1f2 `__, + addition for lua in `commit + f94c53d `__, some + warnings in `commit + 438db54 `__ however. +- Added support for Lua scripts to drop queries w/o further processing. + `commit 0478c54 `__. +- Kevin Holly added qtype statistics to recursor and rec\_control + (get-qtypelist) (`commit + 79332bf `__) +- Add support for include-files in configuration, also reload ACLs and + zones defined in them (`commit + 829849d `__, `commit + 242b90e `__, `commit + 302df81 `__). +- Paulo Anes contributed server-down-max-fails which helps combat + Recursive DNS based amplification attacks. Described in `this + post `__. + Also comes with new metric 'failed-host-entries' in `commit + 406f46f `__. +- `commit 21e7976 `__: + Implement "followCNAMERecords" feature in the Lua hooks. + +Improvements +^^^^^^^^^^^^ + +- `commit 06ea901 `__: + make pdns-distributes-queries use a hash so related queries get sent + to the same thread. Original idea by Winfried Angele. Astoundingly + effective, approximately halves CPU usage! +- `commit b13e737 `__: + --help now writes to stdout instead of stderr. Thanks Winfried + Angele. +- To aid in limiting DoS attacks, when truncating a response, we + actually truncate all the way so only the question remains. Suggested + in `ticket 1092 `__, + code in `commit + add935a `__. +- No longer experimental, the switch 'pdns-distributes-queries' can + improve multi-threaded performance on Linux (various cleanup + commits). +- Update to embedded PolarSSL, plus remove previous AES implementation + and shift to PolarSSL (`commit + e22d9b4 `__, `commit + 990ad9a `__) +- `commit 92c0733 `__ + moves various Lua magic constants into an enum namespace. +- set group and supplementary groups before chroot (`commit + 6ee50ce `__, `ticket + 1198 `__). +- `commit 4e9a20e `__: + raise our socket buffer setting so it no longer generates a warning + about lowering it. +- `commit 4e9a20e `__: + warn about Linux suboptimal IPv6 settings if we detect them. +- SIGUSR2 turns on a 'trace' of all DNS traffic, a second SIGUSR2 now + turns it off again. `commit + 4f217ce `__. +- Various fixes for Lua 5.2. +- `commit 81859ba `__: + No longer attempt to answer questions coming in from port 0, reply + would not reach them anyhow. Thanks to Niels Bakker and 'sid3windr' + for insight & debugging. Closes `ticket + 844 `__. +- `commit b1a2d6c `__: + now, I'm not one to get OCD over things, but that log message about + stats based on 1801 seconds got to me. 1800 now. + +Fixes +^^^^^ + +- 0c9de4fc: stay away from getaddrinfo unless we really can't help it + for ascii ipv6 conversions to binary +- `commit 08f3f63 `__: + fix average latency calculation, closing `ticket + 424 `__. +- `commit 75ba907 `__: + Some of our counters were still 32 bits, now 64. +- `commit 2f22827 `__: + Fix statistics and stability when running with + pdns-distributes-queries. +- `commit 6196f90 `__: + avoid merging old and new additional data, fixes an issue caused by + weird (but probably legal) Akamai behaviour +- `commit 3a8a4d6 `__: + make sure we don't exceed the number of available filedescriptors for + mthreads. Raises performance in case of DoS. See `this + post `__ + for further details. +- `commit 7313fe6 `__: + implement indexed packet cache wiping for recursor, orders of + magnitude faster. Important when reloading all zones, which causes + massive cache cleaning. +- rec\_control get-all would include 'cache-bytes' and + 'packetcache-bytes', which were expensive operations, too expensive + for frequent polling. Removed in `commit + 8e42d27 `__. +- All old workarounds for supporting Windows of the XP era have been + removed. +- Fix issues on S390X based systems which have unsigned characters + (`commit + 916a0fd `__) + + +PowerDNS Recursor version 3.5.3 +------------------------------- + +Released September 17th, 2013 + +This is a bugfix and performance update to 3.5.2. It brings serious +performance improvements for dual stack users. + +Downloads +^^^^^^^^^ + +- `Official download page `__ +- `native RHEL5/6 packages from Kees + Monshouwer `__ + +Changes since 3.5.2 +^^^^^^^^^^^^^^^^^^^ + +- 3.5 replaced our ANY query with A+AAAA for users with IPv6 enabled. + Extensive measurements by Darren Gamble showed that this change had a + non-trivial performance impact. We now do the ANY query like before, + but fall back to the individual A+AAAA queries when necessary. Change + in `commit + 1147a8b `__. +- The IPv6 address for d.root-servers.net was added in `commit + 66cf384 `__, thanks + Ralf van der Enden. +- We now drop packets with a non-zero opcode (i.e. special packets like + DNS UPDATE) earlier on. If the experimental pdns-distributes-queries + flag is enabled, this fix avoids a crash. Normal setups were never + susceptible to this crash. Code in `commit + 35bc40d `__, closes + `ticket 945 `__. +- TXT handling was somewhat improved in `commit + 4b57460 `__, closing + `ticket 795 `__. + +PowerDNS Recursor version 3.5.2 +------------------------------- + +Released June 7th, 2013 + +This is a stability and bugfix update to 3.5.1. It contains important +fixes that improve operation for certain domains. + +Downloads +^^^^^^^^^ + +- `Official download page `__ +- `native RHEL5/6 packages from Kees + Monshouwer `__ + +Changes since 3.5.1 +^^^^^^^^^^^^^^^^^^^ + +- Responses without the QR bit set now get matched up to an outstanding + query, so that resolution can be aborted early instead of waiting for + a timeout. Code in `commit + ee90f02 `__. +- The depth limiter changes in 3.5.1 broke some legal domains with lots + of indirection. Improved in `commit + d393c2d `__. +- Slightly improved logging to aid debugging. Code in `commit + 437824d `__ and + `commit 182005e `__. + +PowerDNS Recursor version 3.5.1 +------------------------------- + +Released May 3rd, 2013 + +This is a stability and bugfix update to 3.5. It contains important +fixes that improve operation for certain domains. + +Downloads +^^^^^^^^^ + +- `Official download page `__ +- `native RHEL5/6 packages from Kees + Monshouwer `__ + +Changes since 3.5 +^^^^^^^^^^^^^^^^^ + +- We now abort earlier while following endless glue or CNAME chains. + Fix in `commit + 02d1742 `__. +- Some unused code would crash certain gcc versions on ARM. Reported by + Morten Stevens, fixed in `commit + 5b188e8 `__. +- The 3.5 fix for `ticket + 731 `__ was too strict, + causing trouble with at least one domain. Reported by Aki Tuomi, + check slightly relaxed in `commit + 4134690 `__. +- Automake/autoconf now use non-deprecated syntax. Reported by Morten + Stevens, change in `commit + ca17ef2 `__. + +PowerDNS Recursor version 3.5 +----------------------------- + +Released April 15th, 2013 + +This is a stability, security and bugfix update to 3.3/3.3.1. It +contains important fixes for slightly broken domain names, which your +users expect to work anyhow. **Note**: Because a semi-sanctioned 3.4-pre +was distributed for a long time, and people have come to call that 3.4, +we are skipping an actual 3.4 release to avoid confusion. + +Downloads +^^^^^^^^^ + +- `Official download page `__ +- `native RHEL5/6 packages from Kees + Monshouwer `__ + +Changes between RC5 and the final 3.5 release +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Winfried Angele reported that restarting a very busy recursor could + lead to crashes. Fixed in r3153, closing `ticket + 735 `__. + +Changes between RC4 and RC5 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Bernd-René Predota of Liberty Global reported that Recursor 3.3 would + treat empty non-AA NOERROR responses as authoritative NXDATA + responses. This bug turned out to be in 3.5-RC4 too. Fixed in `commit + 3146 `__, + related to `ticket + 731 `__. + +Changes between RC3 (unreleased) and RC4 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Winfried Angele spotted, even before release, that `commit + 3132 `__ in + RC3 broke outgoing IPv6 queries. We are grateful for his attention to + detail! Fixed in `commit + 3141 `__. + Changes between RC2 and RC3 (unreleased) +- Use private temp dir when running under systemd, thanks Morten + Stevens and Ruben Kerkhof. Change in `commit + 3105 `__. +- NSD mistakenly compresses labels for RP and other types, violating a + MUST in RFC 3597. Recursor does not decompress these labels, + violating a SHOULD in RFC3597. We now decompress these labels, and + reportedly NSD will stop compressing them. Reported by Jan-Piet Mens, + fixed in `commit + 3109 `__. +- When forwarding to another recursor, we would handle responses to ANY + queries incorrectly. Spotted by Jan-Piet Mens, fixed in `commit + 3116 `__, + closes `ticket 704 `__. +- Our local-nets definition (used as a default for some settings) now + includes the networks from RFC 3927 and RFC 6598. Reported by Maik + Zumstrull, fixed in `commit + 3122 `__. +- The RC1 change to stop using ANY queries to get A+AAAA for name + servers in one go had a 5% performance impact. This impact is + corrected in `commit + 3132 `__. + Thanks to Winfried Angele for measuring and reporting this. Closes + `ticket 710 `__. +- New command 'rec\_control dump-nsspeeds' will dump our NS speeds + (latency) cache. Code in `commit + 3131 `__. + +Changes between RC1 and RC2 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- While Recursor 3.3 was not vulnerable to the specific attack noted in + 'Ghost Domain Names: Revoked Yet Still Resolvable' (more information + at `A New DNS Exploitation Technique: Ghost Domain + Names `__), + further investigation showed that a variant of the attack could work. + This was fixed in `commit + 3085 `__. This + should also close the slightly bogus + `CVE-2012-1193 `__. + Closes `ticket 668 `__. +- The auth-can-lower-ttl flag was removed, as it did not have any + effect in most situations, and thus did not operate as advertised. We + now always comply with the related parts of RFC 2181. Change in + `commit + 3092 `__, + closing `ticket 88 `__. + +New features +^^^^^^^^^^^^ + +- The local zone server now understands wildcards, code in `commit + 2062 `__. +- The Lua postresolve and nodata hooks, that had been distributed as a + '3.3-hooks' snapshot earlier, have been merged. Code in `commit + 2309 `__. +- A new feature, rec\_control trace-regex allows the tracing of lookups + for specific names. Code in `commit + 3044 `__, + `commit + 3073 `__. +- A new setting, export-etc-hosts-search-suffix, adds a configurable + suffix to names imported from /etc/hosts. Code in `commit + 2544 `__, + `commit + 2545 `__. + +Improvements +^^^^^^^^^^^^ + +- We now throttle queries that don't work less aggressively, code in + `commit + 1766 `__. +- Various improvements in tolerance against broken auths, code in + `commit + 1996 `__, + `commit + 2188 `__, + `commit + 3074 `__ + (thanks Winfried). +- Additional processing is now optional, and disabled by default. + Presumably this yields a performance improvement. Change in `commit + 2542 `__. +- rec\_control reload-lua-script now reports errors. Code in `commit + 2627 `__, + closing `ticket 278 `__. +- rec\_control help now lists commands. Code in `commit + 2628 `__. +- rec\_control wipe-cache now also wipes the recursor's packet cache. + Code in `commit + 2880 `__ from + `ticket 333 `__. +- Morten Stevens contributed a systemd file. Import in `commit + 2966 `__, now + part of the recursor tarball. +- `commit + 2990 `__ + updates the address of D.root-servers.net. +- Winfried Angele implemented and documented the ipv6-questions metric. + Merge in `commit + 3034 `__, + closing `ticket 619 `__. +- We no longer use ANY to get A+AAAA for nameservers, because some auth + operators have decided to break ANY lookups. As a bonus, we now track + v4 and v6 latency separately. Change in `commit + 3064 `__. + +Bugs fixed +^^^^^^^^^^ + +- Some unaligned memory access was corrected, code in `commit + 2060 `__, + `commit + 2122 `__, + `commit + 2123 `__, + which would cause problems on UltraSPARC. +- Garbage encountered during reload-acls could cause crashes. Fixed in + `commit + 2323 `__, + closing `ticket 330 `__. +- The recursor would lose its root hints in a very rare situation. + Corrected in `commit + 2380 `__. +- We did not always drop supplemental groups while dropping privileges. + Reported by David Black of Atlassian, fixed in `commit + 2524 `__. +- Cache aging would sometimes get confused when we had a mix of expired + and non-expired records in cache. Spotted and fixed by Winfried + Angele in `commit + 3068 `__, + closing `ticket 438 `__. +- rec\_control reload-acl no longer ignores arguments. Fix in `commit + 3037 `__, + closing `ticket 490 `__. +- Since we re-parse our commandline in rec\_control we've been doubling + the commands on the commandline, causing weird output. Reported by + Winfried Angele. Fixed in `commit + 2992 `__, + closing `ticket 618 `__. + This issue was not present in any officially released versions. +- `commit + 2879 `__ drops + some spurious stderr logging from Lua scripts, and makes sure 'place' + is always valid. +- We would sometimes refuse to resolve domains with just one nameserver + living at the apex. Fixed in `commit + 2817 `__. +- We would sometimes stick RRs in the wrong parts of response packets. + Fixed in `commit + 2625 `__. +- The ACL parser was too liberal, sometimes causing recursors to be + very open. Fixed in `commit + 2629 `__, + closing `ticket 331 `__. +- rec\_control now honours socket-dir from recursor.conf. Fixed in + `commit + 2630 `__. +- When traversing CNAME chains, sometimes we would end up with multiple + SOAs in the result. Fixed in `commit + 2633 `__. + + +Recursor version 3.3.1 +----------------------- + +**Warning**:Unreleased + +Version 3.3.1 contains a small number of important fixes, adds some +memory usage statistics, but no new features. + +- Discovered by John J and Robin J, the PowerDNS Recursor did not + process packets that were truncated in mid-record, and also did not + act on the 'truncated' (TC) flag in that case. This broke a very + small number of domains, most of them served by very old versions of + the PowerDNS Authoritative Server. Fix in `commit + 1740 `__. +- PowerDNS emitted a harmless, but irritating, error message on + receiving certain very short packets. Discovered by Winfried A and + John J, fix in `commit + 1729 `__. +- PowerDNS could crash on startup if configured to provide service on + malformed IPv6 addresses on FreeBSD, or in case when the FreeBSD + kernel was compiled without any form of IPv6 support. Debugged by + Bryan Seitz, fix in `commit + 1727 `__. +- Add max-mthread-stack metric to debug rare crashes. Could be used to + save memory on constrained systems. Implemented in `commit + 1745 `__. +- Add cache-bytes and packetcache-bytes metrics to measure our + 'pre-malloc' memory utilization. Implemented in `commit + 1750 `__. + +Recursor version 3.3 +-------------------- + +Released on the 22nd of September 2010. + +**Warning**: Version 3.3 fixes a number of small but persistent issues, +rounds off our IPv6 %link-level support and adds an important feature +for many users of the Lua scripts. + +In addition, scalability on Solaris 10 is improved. + +Bug fixes +^^^^^^^^^ + +- 'dist-recursor' script was not compatible with pure POSIX /bin/sh, + discovered by Simon Kirby. Fix in `commit + 1545 `__. +- Simon Bedford, Brad Dameron and Laurient Papier discovered relatively + high TCP/IP loads could cause TCP/IP service to shut down over time. + Addressed in commits + `1546 `__, + `1640 `__, + `1652 `__, + `1685 `__, + `1698 `__. + Additional information provided by Zwane Mwaikambo, Nicholas Miell + and Jeff Roberson. Testing by Christian Hofstaedtler and Michael + Renner. +- The PowerDNS Recursor could not read the 'root zone' (this is + something else than the root hints) because of an unquoted TXT + record. This has now been addressed, allowing operators to hardcode + the root zone. This can improve security if the root zone used is + kept up to date. Change in `commit + 1547 `__. +- A return of an old bug, when a domain gets new nameservers, but the + old nameservers continue to contain a copy of the domain, PowerDNS + could get 'stuck' with the old servers. Fixed in `commit + 1548 `__. +- Discovered & reported by Alexander Gall of SWITCH, the Recursor used + to try to resolve 'AXFR' records over UDP. Fix in `commit + 1619 `__. +- The Recursor embedded authoritative server messed up parsing a record + like '@ IN MX 15 @'. Spotted by Aki Tuomi, fix in `commit + 1621 `__. +- The Recursor embedded authoritative server messed up parsing really + really long lines. Spotted by Marco Davids, fix in `commit + 1624 `__, + `commit + 1625 `__. +- Packet cache was not DNS class correct. Spotted by "Robin", fix in + `commit + 1688 `__. +- The packet cache would cache some NXDOMAINs for too long. Solving + this bug exposed an underlying oddity where the initial NXDOMAIN + response had an overly long (untruncated) TTL, whereas all the next + ones would be ok. Solved in `commit + 1679 `__, + closing `ticket 281 `__. + Especially important for RBL operators. Fixed after some nagging by + Alex Broens (thanks). + +Improvements +^^^^^^^^^^^^ + +- The priming of the root now uses more IPv6 addresses. Change in + `commit + 1550 `__, + closes `ticket 287 `__. + Also, the IPv6 address of I.ROOT-SERVERS.NET was added in `commit + 1650 `__. +- The ``rec_control dump-cache`` command now also dumps the 'negative + query' cache. Code in `commit + 1713 `__. +- PowerDNS Recursor can now bind to fe80 IPv6 space with '%eth0' link + selection. Suggested by Darren Gamble, implemented with help from + Niels Bakker. Change in `commit + 1620 `__. +- Solaris on x86 has a long standing bug in port\_getn(), which we now + work around. Spotted by 'Dirk' and 'AS'. Solution suggested by the + Apache runtime library, update in `commit + 1622 `__. +- New runtime statistic: 'tcp-clients' which lists the number of + currently active TCP/IP clients. Code in `commit + 1623 `__. +- Deal better with UltraDNS style CNAME redirects containing SOA + records. Spotted by Andy Fletcher from UKDedicated in `ticket + 303 `__, fix in `commit + 1628 `__. +- The packet cache, which has 'ready to use' packets containing + answers, now artificially ages the ready to use packets. Code in + `commit + 1630 `__. +- Lua scripts can now indicate that certain queries will have + 'variable' answers, which means that the packet cache will not touch + these answers. This is great for overriding some domains for some + users, but not all of them. Use setvariable() in Lua to indicate such + domains. Code in `commit + 1636 `__. +- Add query statistic called 'dont-outqueries', plus add IPv6 address + :: and IPv4 address 0.0.0.0 to the default "dont-query" set, + preventing the Recursor from talking to itself. Code in `commit + 1637 `__. +- Work around a gcc 4.1 bug, still in wide use on common platforms. + Code in `commit + 1653 `__. +- Add 'ARCHFLAGS' to PowerDNS Recursor Makefile, easing 64 bit + compilation on mainly 32 bit platforms (and vice versa). +- Under rare circumstances, querying the Recursor for statistics under + very high load could lead to a crash (although this has never been + observed). Bad code removed & good code unified in `commit + 1675 `__. +- Spotted by Jeff Sipek, the rec\_control manpage did not list the new + get-all command. `commit + 1677 `__. +- On some platforms, it may be better to have PowerDNS itself + distribute queries over threads (instead of leaving it up to the + kernel). This experimental feature can be enabled with the + 'pdns-distributes-queries' setting. Code in `commit + 1678 `__ and + beyond. Speeds up Solaris measurably. +- Cache cleaning code was cleaned up, unified and expanded to cover the + 'negative cache', which used to be cleaned rather bluntly. Code in + `commit + 1702 `__, + further tweaks in `commit + 1712 `__, + spotted by Darren Gamble, Imre Gergely and Christian Kovacic. + +Changes between RC1, RC2 and RC3. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- RC2: Fixed linking on RHEL5/CentOS5, which both ship with a gcc + compiler that claims to support atomic operations, but doesn't. Code + in `commit + 1714 `__. + Spotted by 'Bas' and Imre Gergely. +- RC2: Negative query cache was configured to grow too large, and was + not cleaned efficiently. Code in `commit + 1712 `__, + spotted by Imre Gergely. +- RC3: Root failed to be renewed automatically, relied on fallback to + make this happen. Code in `commit + 1716 `__, + spotted by Detlef Peeters. + +Recursor version 3.2 +-------------------- + +Released on the 7th of March 2010. + +**Warning**: Lua scripts from version 3.1.7.\* are fully compatible with +version 3.2. However, scripts written for development snapshot releases, +are NOT. Please see `Scripting `__ for details! + +The 3.2 release is the first major release of the PowerDNS Recursor in a +long time. Partly this is because 3.1.7.\* functioned very well, and +delivered satisfying performance, partly this is because in order to +really move forward, some heavy lifting had to be done. + +As always, we are grateful for the large PowerDNS community that is +actively involved in improving the quality of our software, be it by +submitting patches, by testing development versions of our software or +helping debug interesting issues. We specifically want to thank Stefan +Schmidt and Florian Weimer, who both over the years have helped +tremendously in keeping PowerDNS fast, stable and secure. + +This version of the PowerDNS Recursor contains a rather novel form of +lock-free multithreading, a situation that comes close to the old +'--fork' trick, but allows the Recursor to fully utilize multiple CPUs, +while delivering unified statistics and operational control. + +In effect, this delivers the best of both worlds: near linear scaling, +with almost no administrative overhead. + +Compared to 'regular multithreading', whereby threads cooperate more +closely, more memory is used, since each thread maintains its own DNS +cache. However, given the economics, and the relatively limited total +amount of memory needed for high performance, this price is well worth +it. + +In practical numbers, over 40,000 queries/second sustained performance +has now been measured by a third party, with a 100.0% packet response +rate. This means that the needs of around 400,000 residential +connections can now be met by a single commodity server. + +In addition to the above, the PowerDNS Recursor is now providing +resolver service for many more Internet users than ever before. This has +brought with it 24/7 Service Level Agreements, and 24/7 operational +monitoring by networking personnel at some of the largest +telecommunications companies in the world. + +In order to facilitate such operation, more statistics are now provided +that allow the visual verification of proper PowerDNS Recursor +operation. As an example of this there are now graphs that plot how many +queries were dropped by the operating system because of a CPU overload, +plus statistics that can be monitored to determine if the PowerDNS +deployment is under a spoofing attack. All in all, this is a large and +important PowerDNS Release, paving the way for further innovation. + +**Note**: This release removes support for the 'fork' multi-processor +option. In addition, the default is now to spawn two threads. This has +been done in such a way that total memory usage will remain identical, +so each thread will use half of the allocated maximum number of cache +entries. + +Changes between RC2 and -release +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- 'Make install' when an existing configuration file contained a 'fork' + statement has been fixed. Spotted by Darren Gamble, code in `commit + 1534 `__. +- Reloading a non-existent allow-from-file caused the control thread to + stop working. Spotted by Imre Gergely, code in `commit + 1532 `__. +- Parser got confused by reading en empty line in auth-forward-zones. + Spotted by Imre Gergely, code in `commit + 1533 `__. +- David Gavarret discovered undocumented and not-working settings to + set the owner, group and access modes of the control socket. Code by + Aki Tuomi and documentation in `commit + 1535 `__. + Fixup in `commit + 1536 `__ for + FreeBSD as found by Ralf van der Enden. +- Tiny improvement possibly solving an issue on Solaris 10's completion + port event multiplexer (`commit + 1537 `__). + +Changes between RC1 and RC2 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Compilation on Solaris 10 has been fixed (various patchlevels had + different issues), code in `commit + 1522 `__. +- Compatibility with CentOS4/RHEL4 has been restored, the gcc and glibc + versions shipped with this distribution contain a Thread Local + Storage bug which we now work around. Thanks to Darren Gamble and + Imre Gergely for debugging this issue, code in `commit + 1527 `__. +- A failed setuid operation, because of misconfiguration, would result + in a crash instead of an error message. Fixed in `commit + 1523 `__. +- Imre Gergely discovered that PowerDNS was doing spurious root + repriming when invalidating nssets. Fixed in `commit + 1531 `__. +- Imre Gergely discovered our rrd graphs had not been changed for the + new multithreaded world, and did not allow scaling beyond 200% cpu + use. In addition, CPU usage graphs did not add up correctly. + Implemented in `commit + 1524 `__. +- Andreas Jakum discovered the description of 'max-packetcache-entries' + and 'forward-zones-recurse' was wrong in the output of '--help' and + '--config'. In addition, some stray backup files made it into the RC1 + release. Addressed in `commit + 1529 `__. Full + release notes follow, including some overlap with the incremental + release notes above. Improvements +- Multithreading, allowing near linear scaling to multiple CPUs or + cores. Configured using 'threads=' (many commits). This also + deprecates the '--fork' option. +- Added ability to read a configuration item of a running PowerDNS + Recursor using 'rec\_control get-parameter' (`commit + 1243 `__), + suggested by Wouter de Jong. +- Added ability to read all statistics in one go of a running PowerDNS + Recursor using 'rec\_control get-all' (`commit + 1496 `__), + suggested by Michael Renner. +- Speedups in packet generation (Commits + `1258 `__, + `1259 `__, + `1262 `__) +- TCP deferred accept() filter is turned on again for slight DoS + protection. Code in `commit + 1414 `__. +- PowerDNS Recursor can now do TCP/IP queries to remote IPv6 addresses + (`commit + 1412 `__). +- Solaris 9 '/dev/poll' support added, Solaris 8 now deprecated. + Changes in `commit + 1421 `__, + `commit + 1422 `__, + `commit + 1424 `__, + `commit + 1413 `__. +- Lua functions can now also see the address \_to\_ which a question + was sent, using getlocaladdress(). Implemented in `commit + 1309 `__ and + `commit + 1315 `__. +- Maximum cache sizes now default to a sensible value. Suggested by + Roel van der Made, implemented in `commit + 1354 `__. +- Domains can now be forwarded to IPv6 addresses too, using either ::1 + syntax or [::1]:25. Thanks to Wijnand Modderman for discovering this + issue, fixed in `commit + 1349 `__. +- Lua scripts can now load libraries at runtime, for example to + calculate md5 hashes. Code by Winfried Angele in `commit + 1405 `__. +- Periodic statistics output now includes average queries per second, + as well as packet cache numbers (`commit + 1493 `__). +- New metrics are available for graphing, plus added to the default + graphs (`commit + 1495 `__, + `commit + 1498 `__, + `commit + 1503 `__) +- Fix errors/crashes on more recent versions of Solaris 10, where the + ports functions could return ENOENT under some circumstances. + Reported and debugged by Jan Gyselinck, fixed in `commit + 1372 `__. + +New features +^^^^^^^^^^^^ + +- Add pdnslog() function for Lua scripts, so errors or other messages + can be logged properly. +- New settings to set the owner, group and access modes of the control + socket (socket-owner, socket-group, socket-mode). Code by Aki Tuomi + and documentation in `commit + 1535 `__. + Fixup in `commit + 1536 `__ for + FreeBSD as found by Ralf van der Enden. +- rec\_control now accepts a --timeout parameter, which can be useful + when reloading huge Lua scripts. Implemented in `commit + 1366 `__. +- Domains can now be forwarded with the 'recursion-desired' bit on or + off, using either **forward-zones-recurse** or by prefixing the name + of a zone with a '+' in **forward-zones-file**. Feature suggested by + Darren Gamble, implemented in `commit + 1451 `__. +- Access control lists can now be reloaded at runtime (implemented in + `commit + 1457 `__). +- PowerDNS Recursor can now use a pool of query-local-addresses to + further increase resilience against spoofing. Suggested by Ad Spelt, + implemented in `commit + 1426 `__. +- PowerDNS Recursor now also has a packet cache, greatly speeding up + operations. Implemented in `commit + 1426 `__, + `commit + 1433 `__ and + further. +- Cache can be limited in how long it maximally stores records, for + BIND compatibility (TTL limiting), by setting **max-cache-ttl**.Idea + by Winfried Angele, implemented in `commit + 1438 `__. +- Cache cleaning turned out to be scanning more of the cache than + necessary for cache maintenance. In addition, far more frequent but + smaller cache cleanups improve responsiveness. Thanks to Winfried + Angele for discovering this issue. (commits + `1501 `__, + `1507 `__) +- Performance graphs enhanced with separate CPU load and cache + effectiveness plots, plus display of various overload situations + (commits + `1503 `__) + +Compiler/Operating system/Library updates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- PowerDNS Recursor can now compile against newer versions of Boost + (verified up to and including 1.42.0). Reported & fixed by Darix in + `commit + 1274 `__. + Further fixes in `commit + 1275 `__, + `commit + 1276 `__, + `commit + 1277 `__, + `commit + 1283 `__. +- Fix compatibility with newer versions of GCC (closes ticket `ticket + 227 `__, spotted by + Ruben Kerkhof, code in `commit + 1345 `__, more + fixes in commit + `1394 `__, + `1416 `__, + `1440 `__). +- Rrdtool update graph is now compatible with FreeBSD out of the box. + Thanks to Bryan Seitz (`commit + 1517 `__). +- Fix up Makefile for older versions of Make (`commit + 1229 `__). +- Solaris compilation improvements (out of the box, no handwork + needed). +- Solaris 9 MTasker compilation fixes, as suggested by John Levon. + Changes in `commit + 1431 `__. + +Bug fixes +^^^^^^^^^ + +- Under rare circumstances, the recursor could crash on 64 bit Linux + systems running glibc 2.7, as found in Debian Lenny. These + circumstances became a lot less rare for the 3.2 release. Discovered + by Andreas Jakum and debugged by #powerdns, fix in `commit + 1519 `__. +- Imre Gergely discovered that PowerDNS was doing spurious root + repriming when invalidating nssets. Fixed in `commit + 1531 `__. +- Configuration parser is now resistant against trailing tabs and other + whitespace (`commit + 1242 `__) +- Fix typo in a Lua error message. Close `ticket + 210 `__, as reported by + Stefan Schmidt (`commit + 1319 `__). +- Profiled-build instructions were broken, discovered & fixes suggested + by Stefan Schmidt. `ticket + 239 `__, fix in `commit + 1462 `__. +- Fix up duplicate SOA from a remote authoritative server from showing + up in our output (`commit + 1475 `__). +- All security fixes from 3.1.7.2 are included. +- Under highly exceptional circumstances on FreeBSD the PowerDNS + Recursor could crash because of a TCP/IP error. Reported and fixed by + Andrei Poelov in `ticket + 192 `__, fixed in + `commit + 1280 `__. +- PowerDNS Recursor can be a root-server again. Error spotted by the + ever vigilant Darren Gamble (ticket + `229 `__), fix in + `commit + 1458 `__. +- Rare TCP/IP errors no longer lead to PowerDNS Recursor logging errors + or becoming confused. Debugged by Josh Berry of Plusnet PLC. Code in + `commit + 1457 `__. +- Do not hammer parent servers in case child zones are misconfigured, + requery at most once every 10 seconds. Reported & investigated by + Stefan Schmidt and Andreas Jakum, fixed in `commit + 1265 `__. +- Properly process answers from remote authoritative servers that send + error answers without including the original question (`commit + 1329 `__, + `commit + 1327 `__). +- No longer spontaneously turn on 'export-etc-hosts' after reloading + zones. Discovered by Paul Cairney, reported in `ticket + 225 `__, addressed in + `commit + 1348 `__. +- Very abrupt server failure of large numbers of high-volume + authoritative servers could trigger an out of memory situation. + Addressed in `commit + 1505 `__. +- Make timeouts for queries to remote authoritative servers + configurable with millisecond granularity. In addition, the old code + turned out to consider the timeout expired when the integral number + of seconds since 1970 increased by 1 - which *on average* is after + 500ms. This might have caused spurious timeouts! New default timeout + is 1500ms. See **network-timeout** setting for more details. Code in + `commit + 1402 `__. + +Recursor version 3.1.7.2 +------------------------ + +Released on the 6th of January 2010. + +This release consist of a number of vital security updates. These +updates address issues that can in all likelihood lead to a full system +compromise. In addition, it is possible for third parties to pollute +your cache with dangerous data, exposing your users to possible harm. + +This version has been well tested, and at the time of this release is +already powering millions of internet connections, and should therefore +be a risk-free upgrade from 3.1.7.1 or any earlier version of the +PowerDNS Recursor. + +All known versions of the PowerDNS Recursor are impacted to a greater or +lesser extent, so an immediate update is advised. + +These vulnerabilities were discovered by a third party that can't yet be +named, but who we thank for their contribution to a more secure PowerDNS +Recursor. + +For more information, see :doc:`PowerDNS Security Advisory +2010-01 <../security-advisories/powerdns-advisory-2010-01>` and :doc:`PowerDNS +Security Advisory 2010-02 <../security-advisories/powerdns-advisory-2010-02>`. + +Recursor version 3.1.7.1 +------------------------ + +Released on the 2nd of August 2009. + +This release consists entirely of fixes for tiny bugs that have been +reported over the past year. In addition, compatibility has been +restored with the latest versions of the gcc compiler and the 'boost' +libraries. + +No features have been added, but some debugging code that very slightly +impacted performance (and polluted the console when operating in the +foreground) has been removed. + +FreeBSD users may want to upgrade because of a very remote chance of +3.1.7 and previous crashing once every few years. For other operators +not currently experiencing problems, there is no reason to upgrade. + +- Improved error messages when parsing zones for authoritative serving + (`commit + 1235 `__). +- Better resilience against whitespace in configuration (changesets + `1237 `__, + `1240 `__, + `1242 `__) +- Slight performance increase (`commit + 1378 `__) +- Fix rare case where timeouts were not being reported to the right + query-thread (`commit + 1260 `__) +- Fix compilation against newer versions of the Boost C++ libraries + (`commit + 1381 `__) +- Close very rare issue with TCP/IP close reporting ECONNRESET on + FreeBSD. Reported by Andrei Poelov in `ticket + 192 `__. +- Silence debugging output (`commit + 1286 `__). +- Fix compilation against newer versions of gcc (`commit + 1384 `__) +- No longer set export-etc-hosts to 'on' on reload-zones. Discovered by + Paul Cairney, closes `ticket + 225 `__. +- Sane default for the maximum cache size in the Recursor, suggested by + Roel van der Made (`commit + 1354 `__). +- No longer exit because of the changed behaviour of the Solaris + 'completion ports' in more recent versions of Solaris. Fix in `commit + 1372 `__, + reported by Jan Gyselinck. + +Recursor version 3.1.7 +---------------------- + +Released the 25th of June 2008. + +This version contains powerful scripting abilities, allowing operators +to modify DNS responses in many interesting ways. Among other things, +these abilities can be used to filter out malware domains, to perform +load balancing, to comply with legal and other requirements and finally, +to implement 'NXDOMAIN' redirection. + +It is hoped that the addition of Lua scripting will enable responsible +DNS modification for those that need it. + +For more details about the Lua scripting, which can be modified, loaded +and unloaded at runtime, see `Scripting `__. Many +thanks are due to the #lua irc channel, for excellent near-realtime Lua +support. In addition, a number of PowerDNS users have been +enthusiastically testing prereleases of the scripting support, and have +found and solved many issues. + +In addition, 3.1.7 fixes a number of bugs + +- In 3.1.5 and 3.1.6, an authoritative server could continue to renew + its authority, even though a domain had been delegated to other + servers in the meantime. + + In the rare cases where this happened, and the old servers were not + shut down, the observed effect is that users were fed outdated data. + Bug spotted and analysed by Darren Gamble, fix in `commit + 1182 `__ and + `commit + 1183 `__. + +- Thanks to long time PowerDNS contributor Stefan Arentz, for the first + time, Mac OS X 10.5 users can compile and run the PowerDNS Recursor! + Patch in `commit + 1185 `__. +- Sten Spans spotted that for outgoing TCP/IP queries, the + **query-local-address** setting was not honored. Fixed in `commit + 1190 `__. +- **rec\_control wipe-cache** now also wipes domains from the negative + cache, hurrying up the expiry of negatively cached records. Suggested + by Simon Kirby, implemented in `commit + 1204 `__. +- When a forwarder server is configured for a domain, using the + **forward-zones** setting, this server IP address was filtered using + the **dont-query** setting, which is generally not what is desired: + the server to which queries are forwarded will often live in private + IP space, and the operator should be trusted to know what he is + doing. Reported and argued by Simon Kirby, fix in `commit + 1211 `__. +- Marcus Rueckert of OpenSUSE reported that very recent gcc versions + emitted a (correct) warning on an overly complicated line in + syncres.cc, fixed in `commit + 1189 `__. +- Stefan Schmidt discovered that the netmask matching code, used by the + new Lua scripts, but also by all other parts of PowerDNS, had + problems with explicit '/32' matches. Fixed in `commit + 1205 `__. + +Recursor version 3.1.6 +---------------------- + +Released on the 1st of May 2008. + +This version fixes two important problems, each on its own important +enough to justify a quick upgrade. + +- Version 3.1.5 had problems resolving several slightly misconfigured + domains, including for a time 'juniper.net'. Nameserver timeouts were + not being processed correctly, leading PowerDNS to not update the + internal clock, which in turn meant that any queries immediately + following an error would time out as well. Because of retries, this + would usually not be a problem except on very busy servers, for + domains with different nameservers at different levels of the + DNS-hierarchy, like 'juniper.net'. + + This issue was fixed rapidly because of the help of + `XS4ALL `__ (Eric Veldhuyzen, Kai Storbeck), + Brad Dameron and Kees Monshouwer. Fix in `commit + 1178 `__. + +- The new high-quality random generator was not used for all random + numbers, especially in source port selection. This means that 3.1.5 + is still a lot more secure than 3.1.4 was, and its algorithms more + secure than most other nameservers, but it also means 3.1.5 is not as + secure as it could be. A quick upgrade is recommended. Discovered by + Thomas Biege of Novell (SUSE), fixed in `commit + 1179 `__. + +Recursor version 3.1.5 +---------------------- + +Released on the 31st of March 2008. + +Much like 3.1.4, this release does not add a lot of major features. +Instead, performance has been improved significantly (estimated at +around 20%), and many rare and not so rare issues were addressed. +Multi-part TXT records now work as expected - the only significant +functional bug found in 15 months. One of the oldest feature requests +was fulfilled: version 3.1.5 can finally forward queries for designated +domains to multiple servers, on differing port numbers if needed. +Previously only one forwarder address was supported. This lack held back +a number of migrations to PowerDNS. + +We would like to thank Amit Klein of Trusteer for bringing a serious +vulnerability to our attention which would enable a smart attacker to +'spoof' previous versions of the PowerDNS Recursor into accepting +possibly malicious data. + +Details can be found on `this Trusteer +page `__. + +It is recommended that all users of the PowerDNS Recursor upgrade to +3.1.5 as soon as practicable, while we simultaneously note that busy +servers are less susceptible to the attack, but not immune. + +The PowerDNS Security Advisory can be found in :doc:`PowerDNS Security +Advisory 2008-01 <../security-advisories/powerdns-advisory-2008-01>`. + +This version can properly benefit from all IPv4 and IPv6 addresses in +use at the root-servers as of early February 2008. In order to implement +this, changes were made to how the Recursor deals internally with A and +AAAA queries for nameservers, see below for more details. + +Additionally, newer releases of the G++ compiler required some fixes +(see `ticket 173 `__). + +This release was made possible by the help of Wichert Akkerman, Winfried +Angele, Arnoud Bakker (Fox-IT), Niels Bakker (no relation!), Leo Baltus +(Nederlandse Publieke Omroep), Marco Davids (SIDN), David Gavarret (Neuf +Cegetel), Peter Gervai, Marcus Goller (UPC), Matti Hiljanen +(Saunalahti/Elisa), Ruben Kerkhof, Alex Kiernan, Amit Klein (Trusteer), +Kenneth Marshall (Rice University), Thomas Rietz, Marcus Rueckert +(OpenSUSE), Augie Schwer (Sonix), Sten Spans (Bit), Stefan Schmidt +(Freenet), Kai Storbeck (xs4all), Alex Trull, Andrew Turnbull (No Wires) +and Aaron Thompson, and many more who filed bugs anonymously, or who we +forgot to mention. + +Security related issues +^^^^^^^^^^^^^^^^^^^^^^^ + +- Amit Klein has informed us that System random generator output can be + predicted based on its past behaviour, allowing a smart attacker to + 'spoof' our nameserver. Full details in :doc:`PowerDNS Security Advisory + 2008-01 <../security-advisories/powerdns-advisory-2008-01>`. +- 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 `pdns\_recursor + settings `__. Implemented in `commit + 923 `__. +- Applied fix for `ticket + 110 `__ ('PowerDNS + should change directory to '/' in chroot), implemented in `commit + 944 `__. + +Performance +^^^^^^^^^^^ + +- The DNS packet writing and parsing infrastructure performance was + improved in several ways, see commits + `925 `__, + `926 `__, + `928 `__, + `931 `__, + `1021 `__, + `1050 `__. +- Remove multithreading overhead from the Recursor (`commit + 999 `__). + +Bug fixes +^^^^^^^^^ + +- Built-in authoritative server now properly derives the TTL from the + SOA record if not specified. Implemented in `commit + 1165 `__. + Additionally, even when TTL was specified for the built-in + authoritative server, it was ignored. Reported by Stefan Schmidt, + closing `ticket 147 `__. +- Empty TXT record components can now be served. Implemented in `commit + 1166 `__, + closing `ticket 178 `__. + Spotted by Matti Hiljanen. +- The Recursor would not properly override old data with new, sometimes + serving old and new data concurrently. Fixed in `commit + 1137 `__. +- SOA records with embedded carriage-return characters are now parsed + correctly. Implemented in `commit + 1167 `__, + closing `ticket 162 `__. +- Some routing conditions could cause UDP connected sockets to generate + an error which PowerDNS did not deal with properly, leading to a + leaked file descriptor. As these run out over time, the recursor + could crash. This would also happen for IPv6 queries on a host with + no IPv6 connectivity. Thanks to Kai of xs4all and Wichert Akkerman + for reporting this issue. Fix in `commit + 1133 `__. +- Empty unknown record types can now be stored without generating a + scary error (`commit + 1129 `__) +- Applied fix for `ticket + 111 `__, `ticket + 112 `__ and `ticket + 153 `__ - large + (multipart) TXT records are now retrieved and served properly. Fix in + `commit + 996 `__. +- Solaris compilation instructions in Recursor documentation were + wrong, leading to an instant crash on startup. Luckily nobody reads + the documentation, except for Marcus Goller who found the error. + Fixed in `commit + 1124 `__. +- On Solaris, finally fix the issue where queries get distributed + strangely over CPUs, or not get distributed at all. Much debugging + and analysing performed by Alex Kiernan, who also supplied fixes. + Implemented in `commit + 1091 `__, + `commit + 1093 `__. +- Various fixes for modern G++ versions, most spotted by Marcus + Rueckert (commits + `964 `__, + `965 `__, + `1028 `__, + `1052 `__), + and Ruben Kerkhof (`commit + 1136 `__, + closing `ticket + 175 `__). +- Recursor would not properly clean up pidfile and control socket, + closing `ticket 120 `__, + code in `commit + 988 `__, + `commit + 1098 `__ (part + of fix by Matti Hiljanen, spotted by Leo Baltus) +- Recursor can now serve multi-line records from its limited + authoritative server (`commit + 1014 `__). +- When parsing zones, the 'm' time specification stands for minutes, + not months! Closing Debian bug 406462 (`commit + 1026 `__) +- Authoritative zone parser did not support '@' in the content of + records. Spotted by Marco Davids, fixed in `commit + 1030 `__. +- Authoritative zone parser could be confused by trailing TABs on + record lines (`commit + 1062 `__). +- EINTR error code could block entire server if received at the wrong + time. Spotted by Arnoud Bakker, fix in `commit + 1059 `__. +- Fix crash on NetBSD on Alpha CPUs, might improve startup behaviour on + empty caches on other architectures as well (`commit + 1061 `__). +- Outbound TCP queries were being performed sub-optimally because of an + interaction with the 'MPlexer'. Fixes in `commit + 1115 `__, + `commit + 1116 `__. + +New features +^^^^^^^^^^^^ + +- Implemented **rec\_control** command **get uptime**, as suggested by + Niels Bakker (`commit + 935 `__). Added + to default rrdtool scripts in `commit + 940 `__. +- The Recursor Authoritative component, meant for having the Recursor + serve some zones authoritatively, now supports $INCLUDE and + $GENERATE. Implemented in `commit + 951 `__ and + `commit + 952 `__, + `commit 967 `__ + (discovered by Thomas Rietz), +- Implemented **forward-zones-file** option in order to support larger + amounts of zones which should be forwarded to another nameserver + (`commit + 963 `__). +- Both **forward-zones** and **forward-zones-file** can now specify + multiple forwarders per domain, implemented in `commit + 1168 `__, + closing `ticket 81 `__. + Additionally, both these settings can also specify non-standard port + numbers, as suggested in ticket `ticket + 122 `__. Patch authored + by Aaron Thompson, with additional work by Augie Schwer. +- Sten Spans contributed **allow-from-file**, implemented in `commit + 1150 `__. This + feature allows the Recursor to read access rules from a (large) file. + +General improvements +^^^^^^^^^^^^^^^^^^^^ + +- Ruben Kerkhof fixed up weird permission bits as well as our SGML + documentation code in `commit + 936 `__ and + `commit + 937 `__. +- Full IPv6 parity. If configured to use IPv6 for outgoing queries + (using **query-local-address6=::0** for example), IPv6 and IPv4 + addresses are finally treated 100% identically, instead of 'mostly'. + This feature is implemented using 'ANY' queries to find A and AAAA + addresses in one query, which is a new approach. Treat with caution. +- Now perform EDNS0 root refreshing queries, so as to benefit from all + returned addresses. Relevant since early February 2008 when the + root-servers started to respond with IPv6 addresses, which made the + default non-EDNS0 maximum packet length reply no longer contain all + records. Implemented in `commit + 1130 `__. + Thanks to dns-operations AT mail.oarc.isc.org for quick suggestions + on how to deal with this change. +- **rec\_control** now has a timeout in case the Recursor does not + respond. Implemented in `commit + 945 `__. +- (Error) messages are now logged with saner priorities (`commit + 955 `__). +- Outbound query IP interface stemmed from 1997 (!) and was in dire + need of a cleanup (`commit + 1117 `__). +- L.ROOT-SERVERS.NET moved (`commit + 1118 `__). + +Recursor version 3.1.4 +---------------------- + +Released the 13th of November 2006. + +This release contains almost no new features, but consists mostly of +minor and major bug fixes. It also addresses two major security issues, +which makes this release a highly recommended upgrade. + +Security issues +^^^^^^^^^^^^^^^ + +- Large TCP questions followed by garbage could cause the recursor to + crash. This critical security issue has been assigned CVE-2006-4251, + and is fixed in `commit + 915 `__. More + information can be found in :doc:`“PowerDNS Security Advisory + 2006-01: Malformed TCP queries can lead to a buffer overflow which + might be exploitable” <../security-advisories/powerdns-advisory-2006-01>`. +- CNAME loops with zero second TTLs could cause crashes in some + conditions. These loops could be constructed by malicious parties, + making this issue a potential denial of service attack. This security + issue has been assigned CVE-2006-4252 and is fixed by `commit + 919 `__. More + information can be found in :doc:`“PowerDNS Security Advisory + 2006-02: Zero second CNAME TTLs can make PowerDNS exhaust allocated + stack space, and crash” <../security-advisories/powerdns-advisory-2006-02>`. + Many thanks to David Gavarret for helping pin down this problem. + +Bugs +^^^^ + +- On certain error conditions, PowerDNS would neglect to close a + socket, which might therefore eventually run out. Spotted by Stefan + Schmidt, fixed in commits + `892 `__, + `897 `__, + `899 `__. +- Some nameservers (including PowerDNS in rare circumstances) emit a + SOA record in the authority section. The recursor mistakenly + interpreted this as an authoritative "NXRRSET". Spotted by Bryan + Seitz, fixed in `commit + 893 `__. +- In some circumstances, PowerDNS could end up with a useless (not + working, or no longer working) set of nameserver records for a + domain. This release contains logic to invalidate such broken NSSETs, + without overloading authoritative servers. This problem had + previously been spotted by Bryan Seitz, 'Cerb' and Darren Gamble. + Invalidations of NSSETs can be plotted using the + "nsset-invalidations" metric, available through **rec\_control get**. + Implemented in `commit + 896 `__ and + `commit + 901 `__. +- PowerDNS could crash while dumping the cache using **rec\_control + dump-cache**. Reported by Wouter of WideXS and Stefan Schmidt and + many others, fixed in `commit + 900 `__. +- Under rare circumstances (depleted TCP buffers), PowerDNS might send + out incomplete questions to remote servers. Additionally, on + big-endian systems (non-Intel and non-AMD generally), sending out + large TCP answers questions would not work at all, and possibly + crash. Brought to our attention by David Gavarret, fixed in `commit + 903 `__. +- The recursor contained the potential for a dead-lock processing an + invalid domain name. It is not known how this might be triggered, but + it has been observed by 'Cerb' on #powerdns. Several dead-locks where + PowerDNS consumed all CPU, but did not answer questions, have been + reported in the past few months. These might be fixed by `commit + 904 `__. +- IPv6 'allow-from' matching had problems with the least significant + bits, sometimes allowing disallowed addresses, but mostly disallowing + allowed addresses. Spotted by Wouter from WideXS, fixed in `commit + 916 `__. + +Improvements +^^^^^^^^^^^^ + +- PowerDNS has support to drop answers from so called 'delegation only' + zones. A statistic ("dlg-only-drops") is now available to plot how + often this happens. Implemented in `commit + 890 `__. +- Hint-file parameter was mistakenly named "hints-file" in the + documentation. Spotted by my Marco Davids, fixed in `commit + 898 `__. +- **rec\_control quit** should be near instantaneous now, as it no + longer meticulously cleans up memory before exiting. Problem spotted + by Darren Gamble, fixed in `commit + 914 `__, + closing `ticket 84 `__. +- init.d script no longer refers to the Recursor as the Authoritative + Server. Spotted by Wouter of WideXS, fixed in `commit + 913 `__. +- A potentially serious warning for users of the GNU C Library version + 2.5 was fixed. Spotted by Marcus Rueckert, fixed in `commit + 920 `__. + +Recursor version 3.1.3 +---------------------- + +Released the 12th of September 2006. + +Compared to 3.1.2, this release again consists of a number of mostly +minor bug fixes, and some slight improvements. + +Many thanks are again due to Darren Gamble who together with his team +has discovered many misconfigured domains that do work with some other +name servers. DNS has long been tolerant of misconfigurations, PowerDNS +intends to uphold that tradition. Almost all of the domains found by +Darren now work as well in PowerDNS as in other name server +implementations. + +Thanks to some recent migrations, this release, or something very close +to it, is powering over 40 million internet connections that we know of. +We appreciate hearing about successful as well as unsuccessful +migrations, please feel free to notify pdns.bd@powerdns.com of your +experiences, good or bad. + +Bug-fixes +^^^^^^^^^ + +- The MThread default stack size was too small, which led to problems, + mostly on 64-bit platforms. This stack size is now configurable using + the **stack-size** setting should our estimate be off. Discovered by + Darren Gamble, Sten Spans and a number of others. Fixed in `commit + 868 `__. +- Plug a small memory leak discovered by Kai and Darren Gamble, fixed + in `commit + 870 `__. +- Switch from the excellent nedmalloc to dlmalloc, based on advice by + the nedmalloc author. Nedmalloc is optimised for multithreaded + operation, whereas the PowerDNS recursor is single threaded. The + version of nedmalloc shipped contained a number of possible bugs, + which are probably resolved by moving to dlmalloc. Some reported + crashes on hitting 2G of allocated memory on 64 bit systems might be + solved by this switch, which should also increase performance. See + `commit 873 `__ + for details. + +Improvements +^^^^^^^^^^^^ + +- The cache is now explicitly aware of the difference between + authoritative and unauthoritative data, allowing it to deal with some + domains that have different data in the parent zone than in the + authoritative zone. Patch in `commit + 867 `__. +- No longer try to parse DNS updates as if they were queries. + Discovered and fixed by Jan Gyselinck, fix in `commit + 871 `__. +- Rebalance logging priorities for less log cluttering and add IP + address to a remote server error message. Noticed and fixed by Jan + Gyselinck (`commit + 877 `__). +- Add **logging-facility** setting, allowing syslog to send PowerDNS + logging to a separate file. Added in `commit + 871 `__. + +Recursor version 3.1.2 +---------------------- + +Released Monday 26th of June 2006. + +Compared to 3.1.1, this release consists almost exclusively of bug-fixes +and speedups. A quick update is recommended, as some of the bugs impact +operators of authoritative zones on the internet. This version has been +tested by some of the largest internet providers on the planet, and is +expected to perform well for everybody. + +Many thanks are due to Darren Gamble, Stefan Schmidt and Bryan Seitz who +all provided excellent feedback based on their large-scale tests of the +recursor. + +Bug-fixes +^^^^^^^^^ + +- Internal authoritative server did not differentiate between + 'NXDOMAIN' and 'NXRRSET', in other words, it would answer 'no such + host' when an AAAA query came in for a domain that did exist, but did + not have an AAAA record. This only affects users with **auth-zones** + configured. Discovered by Bryan Seitz, fixed in `commit + 848 `__. +- ANY queries for hosts where nothing was present in the cache would + not work. This did not cause real problems as ANY queries are not + reliable (by design) for anything other than debugging, but did slow + down the nameserver and cause unnecessary load on remote nameservers. + Fixed in `commit + 854 `__. +- When exceeding the configured maximum amount of TCP sessions, TCP + support would break and the nameserver would waste CPU trying to + accept TCP connections on UDP ports. Noted by Bryan Seitz, fixed in + `commit + 849 `__. +- DNS queries come in two flavours: recursion desired and non-recursion + desired. The latter is not very useful for a recursor, but is + sometimes (erroneously) used by monitoring software or load balancers + to detect nameserver availability. A non-rd query would not only not + recurse, but also not query authoritative zones, which is confusing. + Fixed in `commit + 847 `__. +- Non-standard DNS TCP queries, that did occur however, could drive the + recursor to 100% CPU usage for extended periods of time. This did not + disrupt service immediately, but does waste a lot of CPU, possibly + exhausting resources. Discovered by Bryan Seitz, fixed in `commit + 858 `__, which + is post-3.1.2-rc1. +- The PowerDNS recursor did not honour the rare but standardised 'ANY' + query class (normally 'ANY' refers to the query type, not class), + upsetting the Wildfire Jabber server. Discovered and debugged by + Daniel Nauck, fixed in `commit + 859 `__, which + is post-3.1.2-rc1. +- Everybody's favorite, when starting up under high load, a bogus line + of statistics was sometimes logged. Fixed in `commit + 851 `__. +- Remove some spurious debugging output on dropping a packet by an + unauthorized host. Discovered by Kai. Fixed in `commit + 854 `__. + +Improvements +^^^^^^^^^^^^ + +- Misconfigured domains, with a broken nameserver in the parent zone, + should now work better. Changes motivated and suggested by Darren + Gamble. This makes PowerDNS more compliant with RFC 2181 by making it + prefer authoritative data over non-authoritative data. Implemented in + `commit + 856 `__. +- PowerDNS can now listen on multiple ports, using the + **local-address** setting. Added in `commit + 845 `__. +- A number of speedups which should have a noticeable impact, + implemented in commits + `850 `__, + `852 `__, + `853 `__, + `855 `__ +- The recursor now works around an issue with the Linux kernel 2.6.8, + as shipped by Debian. Fixed by Christof Meerwald in `commit + 860 `__, which + is post 3.1.2-rc1. + +Recursor version 3.1.1 +---------------------- + +Released on the 23rd of May 2006. + +**Warning**: 3.1.1 is identical to 3.1 except for a bug in the packet +chaining code which would mainly manifest itself for IPv6 enabled +Konqueror users with very fast connections to their PowerDNS +installation. However, all 3.1 users are urged to upgrade to 3.1.1. Many +thanks to Alessandro Bono for his quick aid in solving this problem. + +Many thanks are due to the operators of some of the largest internet +access providers in the world, each having many millions of customers, +who have tested the various 3.1 pre-releases for suitability. They have +uncovered and helped fix bugs that could impact us all, but are only +(quickly) noticeable with such vast amounts of DNS traffic. + +After version 3.0.1 has proved to hold up very well under tremendous +loads, 3.1 adds important new features + +- Ability to serve authoritative data from 'BIND' style zone files + (using **auth-zones** statement). +- Ability to forward domains so configured to external servers (using + **forward-zones**). +- Possibility of 'serving' the contents of ``/etc/hosts`` over DNS, + which is very well suited to simple domestic router/DNS setups. + Enabled using **export-etc-hosts**. +- As recommended by recent standards documents, the PowerDNS recursor + is now authoritative for RFC-1918 private IP space zones by default + (suggested by Paul Vixie). +- Full outgoing IPv6 support (off by default) with IPv6 servers getting + equal treatment with IPv4, nameserver addresses are chosen based on + average response speed, irrespective of protocol. +- Initial Windows support, including running as a service ('NET START + "POWERDNS RECURSOR"'). **rec\_channel** is still missing, the rest + should work. Performance appears to be below that of the UNIX + versions, this situation is expected to improve. + +Bug fixes +^^^^^^^^^ + +- No longer send out SRV and MX record priorities as zero on big-endian + platforms (UltraSPARC). Discovered by Eric Sproul, fixed in `commit + 773 `__. +- SRV records need additional processing, especially in an Active + Directory setting. Reported by Kenneth Marshall, fixed in `commit + 774 `__. +- The root-records were not being refreshed, which could lead to + problems under inconceivable conditions. Fixed in `commit + 780 `__. +- Fix resolving domain names for nameservers with multiple IP + addresses, with one of these addresses being lame. Other nameserver + implementations were also unable to resolve these domains, so not a + big bug. Fixed in `commit + 780 `__. +- For a period of 5 minutes after expiring a negative cache entry, the + domain would not be re-cached negatively, leading to a lot of + duplicate outgoing queries for this short period. This fix has raised + the average cache hit rate of the recursor by a few percent. Fixed in + `commit + 783 `__. +- Query throttling was not aggressive enough and not all sorts of + queries were throttled. Implemented in `commit + 786 `__. +- Fix possible crash during startup when parsing empty configuration + lines (`commit + 807 `__). +- Fix possible crash when the first query after wiping a cache entry + was for the just deleted entry. Rare in production servers. Fixed in + `commit + 820 `__. +- Recursor would send out differing TTLs when receiving a + misconfigured, standards violating, RRSET with different TTLs. + Implement fix as mandated by RFC 2181, paragraph 5.2. Reported by + Stephen Harker (`commit + 819 `__). +- The **top-remotes** would list remotes more than once, once per + source port. Discovered by Jorn Ekkelenkamp, fixed in `commit + 827 `__, which + is post 3.1-pre1. +- Default **allow-from** allowed queries from fe80::/16, corrected to + fe80::/10. Spotted by Niels Bakker, fixed in `commit + 829 `__, which + is post 3.1-pre1. +- While PowerDNS blocks failing queries quickly, multiple packets could + briefly be in flight for the same domain and nameserver. This + situation is now explicitly detected and queries are chained to + identical queries already in flight. Fixed in `commit + 833 `__ and + `commit + 834 `__, post + 3.1-pre1. + +Improvements +^^^^^^^^^^^^ + +- ANY queries are now implemented as in other nameserver + implementations, leading to a decrease in outgoing queries. The RFCs + are not very clear on desired behaviour, what is implemented now + saves bandwidth and CPU and brings us in line with existing practice. + Previously ANY queries were not cached by the PowerDNS recursor. + Implemented in `commit + 784 `__. +- **rec\_control** was very sparse in its error reporting, and user + unfriendly as well. Reported by Erik Bos, fixed in `commit + 818 `__ and + `commit + 820 `__. +- IPv6 addresses were printed in a non-standard way, fixed in `commit + 788 `__. +- TTLs of records are now capped at two weeks, `commit + 820 `__. +- **allow-from** IPv4 netmasks now automatically work for IP4-to-IPv6 + mapper IPv4 addresses, which appear when running on the wildcard + **::** IPv6 address. Lack of feature noted by Marcus 'darix' + Rueckert. Fixed in `commit + 826 `__, which + is post 3.1-pre1. +- Errors before daemonizing are now also sent to syslog. Suggested by + Marcus 'darix' Rueckert. Fixed in `commit + 825 `__, which + is post 3.1-pre1. +- When launching without any form of configured network connectivity, + all root-servers would be cached as 'down' for some time. Detect this + special case and treat it as a resource-constraint, which is not + accounted against specific nameservers. Spotted by Seth Arnold, fixed + in `commit + 835 `__, which + is post 3.1-pre1. +- The recursor now does not allow authoritative servers to keep + supplying its own NS records into perpetuity, which causes problems + when a domain is redelegated but the old authoritative servers are + not updated to this effect. Noticed and explained at length by Darren + Gamble of Shaw Communications, addressed by `commit + 837 `__, which + is post 3.1-pre2. +- Some operators may want to follow RFC 2181 paragraph 5.2 and 5.4. + This harms performance and does not solve any real problem, but does + make PowerDNS more compliant. If you want this, enable + **auth-can-lower-ttl**. Implemented in `commit + 838 `__, which + is post 3.1-pre2. + +Recursor version 3.0.1 +---------------------- + +Released 25th of April 2006, +`download `__. + +This release consists of nothing but tiny fixes to 3.0, including one +with security implications. An upgrade is highly recommended. + +- Compilation used both ``cc`` and ``gcc``, leading to the possibility + of compiling with different compiler versions (`commit + 766 `__). +- **rec\_control** would leave files named ``lsockXXXXXX`` around in + the configured socket-dir. Operators may wish to remove these files + from their socket-dir (often ``/var/run``), quite a few might have + accumulated already (`commit + 767 `__). +- Certain malformed packets could crash the recursor. As far as we can + determine these packets could only lead to a crash, but as always, + there are no guarantees. A quick upgrade is highly recommended + (commits + `760 `__, + `761 `__). + Reported by David Gavarret. +- Recursor would not distinguish between NXDOMAIN and NXRRSET (`commit + 756 `__). + Reported and debugged by Jorn Ekkelenkamp. +- Some error messages and trace logging statements were improved + (commits + `756 `__, + `758 `__, + `759 `__). +- stderr was closed during daemonizing, but not dupped to /dev/null, + leading to slight chance of odd behaviour on reporting errors + (`commit + 757 `__) + +Operating system specific fixes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- The stock Debian sarge Linux kernel, 2.6.8, claims to support epoll + but fails at runtime. The epoll self-testing code has been improved, + and PowerDNS will fall back to a select based multiplexer if needed + (`commit + 758 `__) + Reported by Michiel van Es. +- Solaris 8 compilation and runtime issues were addressed. See the + README for details (`commit + 765 `__). + Reported by Juergen Georgi and Kenneth Marshall. +- Solaris 10 x86\_64 compilation issues were addressed (`commit + 755 `__). + Reported and debugged by Eric Sproul. + +Recursor version 3.0 +-------------------- + +Released 20th of April 2006, +`download `__. + +This is the first separate release of the PowerDNS Recursor. There are +many reasons for this, one of the most important ones is that previously +we could only do a release when both the recursor and the authoritative +nameserver were fully tested and in good shape. The split allows us to +release new versions when each part is ready. + +Now for the real news. This version of the PowerDNS recursor powers the +network access of over two million internet connections. Two large +access providers have been running pre-releases of 3.0 for the past few +weeks and results are good. Furthermore, the various pre-releases have +been tested nearly non-stop with DNS traffic replayed at 3000 +queries/second. + +As expected, the 2 million households shook out some very rare bugs. But +even a rare bug happens once in a while when there are this many users. + +We consider this version of the PowerDNS recursor to be the most +advanced resolver publicly available. Given current levels of spam, +phishing and other forms of internet crime we think no recursor should +offer less than the best in spoofing protection. We urge all operators +of resolvers without proper spoofing countermeasures to consider +PowerDNS, as it is a Better Internet Nameserver Daemon. + +A good article on DNS spoofing can be found +`here `__. +Some more information, based on a previous version of PowerDNS, can be +found on the `PowerDNS development +blog `__. + +**Warning**: Because of recent DNS based denial of service attacks, +running an open recursor has become a security risk. Therefore, unless +configured otherwise this version of PowerDNS will only listen on +localhost, which means it does not resolve for hosts on your network. To +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 `pdns\_recursor +settings `__ for details. + +Important new features of the PowerDNS recursor 3.0 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Best spoofing protection and detection we know of. Not only is + spoofing made harder by using a new network address for each query, + PowerDNS detects when an attempt is made to spoof it, and temporarily + ignores the data. For details, see + `Anti-spoofing `__. +- First nameserver to benefit from epoll/kqueue/Solaris completion + ports event reporting framework, for stellar performance. +- Best statistics of any recursing nameserver we know of, see + `Statistics `__. +- Last-recently-used based cache cleanup algorithm, keeping the 'best' + records in memory +- First class Solaris support, built on a 'try and buy' Sun CoolThreads + T 2000. +- Full IPv6 support, implemented natively. +- Access filtering, both for IPv4 and IPv6. +- Experimental SMP support for nearly double performance. See `PowerDNS + Recursor performance `__. + +Many people helped package and test this release. Jorn Ekkelenkamp of +ISP-Services helped find the '8000 SOAs' bug and spotted many other +oddities and `XS4ALL `__ internet funded a lot of +the recent development. Joaquín M López Muñoz of the +boost::multi\_index\_container was again of great help. diff --git a/pdns/recursordist/docs/common b/pdns/recursordist/docs/common new file mode 120000 index 0000000000..b115a64599 --- /dev/null +++ b/pdns/recursordist/docs/common @@ -0,0 +1 @@ +../../../docs/common \ No newline at end of file diff --git a/pdns/recursordist/docs/conf.py b/pdns/recursordist/docs/conf.py new file mode 100644 index 0000000000..6e9ab6b3bf --- /dev/null +++ b/pdns/recursordist/docs/conf.py @@ -0,0 +1,206 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# PowerDNS Recursor documentation build configuration file, created by +# sphinx-quickstart on Wed Jun 28 14:56:44 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) +import guzzle_sphinx_theme + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +#extensions = [] +#extensions = ['redjack.sphinx.lua', 'sphinxcontrib.httpdomain', 'sphinxjsondomain'] +extensions = ['redjack.sphinx.lua', 'sphinxcontrib.httpdomain', 'sphinxjsondomain', + 'sphinxcontrib.fulltoc', 'changelog'] +primary_domain = 'lua' + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'indexTOC' + +# General information about the project. +project = 'PowerDNS Recursor' +copyright = '2017, PowerDNS.COM BV' +author = 'PowerDNS.COM BV' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '4.1' +# The full version, including alpha/beta/rc tags. +release = '4.1.0-alpha0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', + 'http-api/override.rst', + 'common/zonemetadata.rst', + 'common/secpoll.rst'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Changelog Options ---------------------------------------------------- + +changelog_render_ticket = "https://github.com/PowerDNS/pdns/issue/%s" +changelog_render_pullreq = "https://github.com/PowerDNS/pdns/pull/%s" +changelog_render_changeset = "https://github.com/PowerDNS/pdns/commit/%s" + +changelog_sections = ['New Features', 'Improvements', 'Bug Fixes'] +changelog_inner_tag_sort = ['General', 'DNSSEC', 'Protobuf', 'RPZ'] + +changelog_render_tags = False + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme_path = guzzle_sphinx_theme.html_theme_path() +html_theme = 'guzzle_sphinx_theme' + +extensions.append("guzzle_sphinx_theme") + +html_theme_options = { + # Set the name of the project to appear in the sidebar + "project_nav_name": "PowerDNS Recursor", +} +html_favicon = 'common/favicon.ico' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_style = 'pdns.css' + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PowerDNSRecursordoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + 'papersize': 'a4paper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'PowerDNS-Recursor.tex', 'PowerDNS Recursor Documentation', + 'PowerDNS.COM BV', 'manual'), +] + +latex_logo = 'common/powerdns-logo-500px.png' + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('manpages/rec_control', 'rec_control', 'Command line tool to control a running Recursor', [author], 1), + ('manpages/pdns_recursor', 'pdns_recursor', 'The PowerDNS Recursor binary', [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +#texinfo_documents = [ +# (master_doc, 'PowerDNSRecursor', 'PowerDNS Recursor Documentation', +# author, 'PowerDNSRecursor', 'One line description of project.', +# 'Miscellaneous'), +#] + + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] diff --git a/pdns/recursordist/docs/dns64.rst b/pdns/recursordist/docs/dns64.rst new file mode 100644 index 0000000000..2d72f2899b --- /dev/null +++ b/pdns/recursordist/docs/dns64.rst @@ -0,0 +1,27 @@ +DNS64 support +============= + +DNS64, described in :rfc:`6147` is a technology to allow IPv6-only clients to receive special IPv6 addresses that are proxied to IPv4 addresses. +This proxy service is then called NAT64. + +As an example, let's say an IPv6 only client would want to connect to ``www.example.com``, it would request the AAAA records for that name. +However, if ``example.com`` does not actually have an IPv6 address, what we do is 'fake up' an IPv6 address. +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. + +For maximum flexibility, DNS64 support is included in the :doc:`lua-scripting/index`. +This allows for example to hand out custom IPv6 gateway ranges depending on the location of the requestor, enabling the use of NAT64 services close to the user. + +Apart from faking AAAA records, it is also possible to also generate the associated PTR records. +This makes sure that reverse lookup of DNS64-generated IPv6 addresses generate the right name. +The procedure is similar, a request for an IPv6 PTR is converted into one for the corresponding IPv4 address. + +To setup DNS64, with both forward and reverse records, create the following Lua script and save it to a file called ``dns64.lua`` + +.. literalinclude:: ../contrib/dns64.lua + :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 `. + +To enhance DNS64, see the `Lua scripting ` documentation. diff --git a/pdns/recursordist/docs/dnssec.rst b/pdns/recursordist/docs/dnssec.rst new file mode 100644 index 0000000000..110a820413 --- /dev/null +++ b/pdns/recursordist/docs/dnssec.rst @@ -0,0 +1,171 @@ +DNSSEC in the PowerDNS Recursor +=============================== +As of 4.0.0, the PowerDNS Recursor has support for DNSSEC processing and experimental support for DNSSEC validation. + +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``. +In order from least to most processing, these are: + +``off`` +^^^^^^^ +In this mode, **no** DNSSEC processing takes place. +The PowerDNS Recursor will not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the DO and AD bits in queries. +In this mode, the behaviour is equal to the PowerDNS Recursor 3.X. + +``process-no-validate`` +^^^^^^^^^^^^^^^^^^^^^^^ +The default mode. + +In this mode the Recursor acts as a "security aware, non-validating" nameserver, meaning it will set the DO-bit on outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to clients that ask for them (by means of a DO-bit in the query), except for zones provided through the ``auth-zones`` setting. +It will not do any validation in this mode, not even when requested by the client. + +``process`` +^^^^^^^^^^^ +When :ref:`setting-dnssec` 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. + +``log-fail`` +^^^^^^^^^^^^ +In this mode, the recursor will attempt to validate all data it retrieves from authoritative servers, regardless of the client's DNSSEC desires, and will log the validation result. +This mode can be used to determine the extra load and amount of possibly bogus answers before turning on full-blown validation. +Responses to client queries are the same as with `process`_. + +``validate`` +^^^^^^^^^^^^ +The highest mode of DNSSEC processing. +In this mode, all queries will be be validated and will be answered with a SERVFAIL in case of bogus data, regardless of the client's request. + +What, when? +^^^^^^^^^^^ +The descriptions above are a bit terse, here's a table describing different scenarios with regards to the ``dnssec`` mode. + ++--------------+---------+---------------+---------------+---------------+---------------+ +| | ``off`` | ``process-no- | ``process`` | ``log-fail`` | ``validate`` | +| | | validate`` | | | | ++==============+=========+===============+===============+===============+===============+ +| Perform | No | No | Only on +AD | Always (logs | Always | +| validation | | | or +DO from | result) | | +| | | | client | | | ++--------------+---------+---------------+---------------+---------------+---------------+ +| SERVFAIL on | No | No | Only on +AD | Only on +AD | Always | +| bogus | | | or +DO from | or +DO from | | +| | | | client | client | | ++--------------+---------+---------------+---------------+---------------+---------------+ +| AD in | Never | Never | Only on +AD | Only on +AD | Only on +AD | +| response on | | | or +DO from | or +DO from | or +DO from | +| authenticate | | | client | client | client | +| d | | | | | | +| data | | | | | | ++--------------+---------+---------------+---------------+---------------+---------------+ +| RRSIGs/NSECs | No | Yes | Yes | Yes | Yes | +| in answer on | | | | | | +| +DO from | | | | | | +| client | | | | | | ++--------------+---------+---------------+---------------+---------------+---------------+ + +**Note**: the ``dig`` tool sets the AD-bit in the query. +This might lead to unexpected query results when testing. +Set ``+noad`` on the ``dig`` commandline when this is the case. + +Trust Anchor Management +----------------------- +In the PowerDNS Recursor, both positive and negative trust anchors can be configured during startup (from a persistent configuration file) and at runtime (which is volatile). +However, all trust anchors are configurable. + +Trust Anchors +^^^^^^^^^^^^^ +The PowerDNS Recursor ships with the DNSSEC Root key built-in. + +**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:`addDS`. +This function takes 2 arguments: the node in the DNS-tree and the data of the corresponding DS record. + +To e.g. add a trust anchor for the root and powerdns.com, use the following config in the Lua file: + +.. code:: Lua + + addDS('.', "63149 13 1 a59da3f5c1b97fcd5fa2b3b2b0ac91d38a60d33a") -- This is not an ICANN root + addDS('powerdns.com', "44030 8 2 D4C3D5552B8679FAEEBC317E5F048B614B2E5F607DC57F1553182D49 AB2179F7") + +Now (re)start the recursor to load these trust anchors. + +Runtime Configuration of Trust Anchors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To change or add trust anchors at runtime, use the :doc:`manpages/rec_control` 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. + +Adding a trust anchor is done with the ``add-ta`` command: + +:: + + $ rec_control add-ta domain.example 63149 13 1 a59da3f5c1b97fcd5fa2b3b2b0ac91d38a60d33a + Added Trust Anchor for domain.example. with data 63149 13 1 a59da3f5c1b97fcd5fa2b3b2b0ac91d38a60d33a + +To view the currently configured trust anchors, run ``get-tas``: + +:: + + $ rec_control get-tas + Configured Trust Anchors: + . 63149 13 1 a59da3f5c1b97fcd5fa2b3b2b0ac91d38a60d33a + net. 2574 13 1 a5c5acb889a7ba9b5aa5bef2b0ac9fe1565ddaab + +To remove a trust anchor, run ``clear-ta``: + +:: + + $ rec_control clear-ta domain.example + Removed Trust Anchor for subdomain.example + +**Note**: The root trust anchor cannot be removed in this manner. + +.. _ntas: + +Negative Trust Anchors +^^^^^^^^^^^^^^^^^^^^^^ +Negative trust anchors (defined in :rfc:`7646`) can be used to temporarily disable DNSSEC validation for a part of the DNS-tree. +This can be done when e.g. a TLD or high-traffic zone goes bogus. +Note that it is good practice to verify that this is indeed the case and not because of malicious actions. + +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: + +.. code-block:: Lua + + addNTA('example.', "Someone messed up the delegation") + addNTA('powerdns.com') -- No reason given + +Runtime Configuration of Negative Trust Anchors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :doc:`manpages/rec_control` 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()``. + +Adding a negative trust anchor is done with the ``add-nta`` command (that optionally accepts a reason): + +:: + + $ rec_control add-nta domain.example botched keyroll + Added Negative Trust Anchor for domain.example. with reason 'botched keyroll' + +To view the currently configured negative trust anchors, run ``get-ntas``: + +:: + + $ rec_control get-ntas + Configured Negative Trust Anchors: + subdomain.example. Operator failed key-roll + otherdomain.example. DS in parent, no DNSKEY in zone + +To remove negative trust anchor(s), run ``clear-nta``: + +:: + + $ rec_control clear-nta subdomain.example + Removed Negative Trust Anchors for subdomain.example + +``clear-nta`` accepts multiple domain-names and accepts '\*' (beware the shell quoting) to remove all negative trust anchors. diff --git a/pdns/recursordist/docs/getting-started.rst b/pdns/recursordist/docs/getting-started.rst new file mode 100644 index 0000000000..3d6c88e8c7 --- /dev/null +++ b/pdns/recursordist/docs/getting-started.rst @@ -0,0 +1,63 @@ +Getting Started +=============== +The PowerDNS Recursor can be installed on any modern unix-like system and is available in the software repositories for all major Linux distributions and BSDs. + +Installation +------------ +The Recursor is available for many platforms, instructions are provided here for several platforms. + +**note**: PowerDNS itself provides repositories for several Recursor versions for different operating systems. +Checkout `the repositories `_ for more information. + +Debian-based distributions +^^^^^^^^^^^^^^^^^^^^^^^^^^ +On Debian, Ubuntu, Linux Mint and related distributions, running ``apt-get install pdns-recursor`` as root will install the Recursor. + +Enterprise Linux +^^^^^^^^^^^^^^^^ +On RedHat, CentOS and related distributions, ensure that `EPEL `_ is available. +To install the PowerDNS Recursor, run ``yum install pdns-recursor`` as root. + +FreeBSD +^^^^^^^ +On FreeBSD the Recursor is available through the `ports system `_. +Run ``pkg install powerdns-recursor`` as root to install. + +To compile yourself from ports, run ``cd /usr/ports/dns/powerdns-recursor/ && make install clean``. + +From Source +^^^^^^^^^^^ +See :doc:`appendices/compiling` for instructions on how to build the PowerDNS Recursor from source. + +Configuring the Recursor +------------------------ +The configuration file is called ``recursor.conf`` 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. + +Run ``pdns_recursor --no-config --config | grep config-dir`` to find this location on you installation. + +The PowerDNS Recursor listens on the local loopback interface by default, this can be changed with the :ref:`setting-local-address` setting. + +Now access will need to be granted to the Recursor. +The :ref:`setting-allow-from` setting lists the subnets that can communicate with the Recursor. + +An example configuration is shown below. +Change this to match the local infrastructure. + +.. code-block:: none + + local-address=192.0.2.25, 2001:DB8::1:25 + allow-from=192.0.2.0/24, 2001:DB8::1:/64 + +After a restart of the 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. + +The recursor is now ready to be used. +For more options that can be set in ``recursor.conf`` see the :doc:`list of settings `. +Guidance on interaction with the Recursor is documented :doc:`here ` +If dynamic answer generation is needed or policies need to be applied to queries, the :doc:`scripting manual ` will come in handy. + +Using Ansible +------------- +The PowerDNS Recursor can also be installed and configured with `Ansible `_. +There is a `role available `_ from the PowerDNS authors. + diff --git a/pdns/recursordist/docs/http-api/endpoint-cache.rst b/pdns/recursordist/docs/http-api/endpoint-cache.rst new file mode 100644 index 0000000000..7a7848debc --- /dev/null +++ b/pdns/recursordist/docs/http-api/endpoint-cache.rst @@ -0,0 +1,19 @@ +Cache manipulation endpoint +=========================== + +.. http:put:: /api/v1/servers/:server_id/cache/flush?domain=:domain + + Flush the positive, negative and packet cache for a given domain name. + + :query server_id: The name of the server + :query domain: The domainname to flush for + + **Example Response:** + + .. code-block:: json + + { + "count": 10, + "result": "Flushed cache." + } + diff --git a/pdns/recursordist/docs/http-api/endpoint-failure.rst b/pdns/recursordist/docs/http-api/endpoint-failure.rst new file mode 100644 index 0000000000..54ed4b0f22 --- /dev/null +++ b/pdns/recursordist/docs/http-api/endpoint-failure.rst @@ -0,0 +1,70 @@ +Failure logging endpoint +======================== +.. note:: + + Not yet implemented + +.. http:put:: /api/v1/servers/:server_id/failure + + Configure query failure logging. + + :query server_id: The name of the server + + **Example client body:** + + .. code-block:: json + + { + "top-domains": 100, + "domains": ".*\.example\.com$", + } + + :property int top-domains: Number of top resolved domains that are automatically monitored for failures. + :property string domains: A Regex of domains that are additionally monitored for resolve failures. + +.. http:get:: /api/v1/servers/:server_id/failure + + .. note:: + + Not yet implemented + + Retrieve query failure logging and current config. + + **Example response body:** + + .. code-block:: json + + { + "top-domains": 100, + "domains": ".*\.example\.com$", + "log": [ + { + "first_occurred": 1234567890, + "domain": "www.example.net", + "qtype": "A", + "failure": "dnssec-parent-validation-failed", + "failed_parent": "example.com", + "details": "foo bar", + "queried_servers": [ + { + "name": "ns1.example.net", + "address": "192.0.2.53" + }, + ] + }, + ] + } + + :property string failed_parent: The parent domain, this is generally OPTIONAL. + :property string failure_code: Reason of failure. + + - ``dnssec-validation-failed``: DNSSEC Validation failed for this domain. + - ``dnssec-parent-validation-failed``: DNSSEC Validation failed for one of the parent domains. Response MUST contain ``failed_parent``. + - ``nxdomain``: This domain was not present on the authoritative nameservers. + - ``nodata``: ??? + - ``all-servers-unreachable``: All auth nameservers that have been tried did not respond. + - ``parent-unresolvable``: Response MUST contain ``failed_parent``. + - ``refused``: All auth nameservers that have been tried responded with REFUSED. + - ``servfail``: All auth nameservers that have been tried responded with SERVFAIL. + + :property string domain: The domain queried diff --git a/pdns/recursordist/docs/http-api/endpoint-trace.rst b/pdns/recursordist/docs/http-api/endpoint-trace.rst new file mode 100644 index 0000000000..c11040937f --- /dev/null +++ b/pdns/recursordist/docs/http-api/endpoint-trace.rst @@ -0,0 +1,40 @@ +Query Tracing endpoint +====================== + +.. note:: + + Not yet implemented + +.. http:put:: /api/v1/servers/:server_id/trace + + Configure query tracing. + + :query server_id: The name of the server + + **Client body:** + + .. code-block:: json + + { + "domains": "" + } + + Set ``domains`` to ``null`` to turn off tracing. + + +.. http:get:: /api/v1/servers/:server_id/trace + + Retrieve query tracing log and current config. + + :query server_id: The name of the server + + **Response Body:** + + .. code-block:: json + + { + "domains": "", + "log": [ + "" + ] + } diff --git a/pdns/recursordist/docs/http-api/endpoint-zones.rst b/pdns/recursordist/docs/http-api/endpoint-zones.rst new file mode 100644 index 0000000000..00786b0ab6 --- /dev/null +++ b/pdns/recursordist/docs/http-api/endpoint-zones.rst @@ -0,0 +1,28 @@ +Zones endpoint +============== + +.. http:get:: /api/v1/servers/:server_id/zones + + Get all zones from the server. + + :query server_id: The name of the server + +.. http:post:: /api/v1/servers/:server_id/zones + + Creates a new domain. The client body must contain a :json:object:`Zone`. + + :query server_id: The name of the server + +.. http:get:: /api/v1/servers/:server_id/zones/:zone_id + + Returns zone information. + + :query server_id: The name of the server + :query zone_id: The id number of the :json:object:`Zone` + +.. http:delete:: /api/v1/servers/:server_id/zones/:zone_id + + Deletes this zone, all attached metadata and rrsets. + + :query server_id: The name of the server + :query zone_id: The id number of the :json:object:`Zone` diff --git a/pdns/recursordist/docs/http-api/index.rst b/pdns/recursordist/docs/http-api/index.rst new file mode 100644 index 0000000000..8b5ccbba4c --- /dev/null +++ b/pdns/recursordist/docs/http-api/index.rst @@ -0,0 +1,66 @@ +Built-in Webserver and HTTP API +=============================== + +The PowerDNS Recursor features a built-in built-in webserver that exposes a JSON/REST API. +This API allows for controlling several functions and reading statistics. + +The following documents contain the information for the PowerDNS API: + +.. toctree:: + :maxdepth: 1 + + ../common/api/dataformat + ../common/api/server + ../common/api/zone + ../common/api/configsetting + ../common/api/statisticitem + + +Webserver +--------- + +To launch the internal webserver, add a :ref:`setting-webserver` to the configuration file. +This will instruct PowerDNS to start a webserver on localhost at port 8081, without password protection. +Only local users (on the same host) will be able to access the webserver by default, but we still strongly advise the use of a password protection. +The webserver lists a lot of 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 plaintext 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 + +Enabling the API +---------------- + +To enable the API, the webserver and the HTTP API need to be enbaled. +Add these lines to the ``recursor.conf``:: + + webserver=yes + webserver-port=8082 + api-key=changeme + +And restart ``pdns_recursor``, the following examples should start working:: + + curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8082/api/v1/servers/localhost | jq . + curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8082/api/v1/servers/localhost/zones | jq . + +URL Endpoints +------------- + +All API endpoints for the PowerDNS Recursor are documented here: + +.. toctree:: + :maxdepth: 1 + + ../common/api/endpoint-api + ../common/api/endpoint-servers + ../common/api/endpoint-servers-config + ../common/api/endpoint-statistics.rst + endpoint-zones + endpoint-trace + endpoint-cache + ../common/api/endpoint-logging.rst + endpoint-failure diff --git a/pdns/recursordist/docs/http-api/override.rst b/pdns/recursordist/docs/http-api/override.rst new file mode 100644 index 0000000000..785398888a --- /dev/null +++ b/pdns/recursordist/docs/http-api/override.rst @@ -0,0 +1,64 @@ +Data Overrides +============== + +.. note:: + + Overrides are not yet implemented! + +.. json:object: Override + + ``created`` is filled by the Server. + + :: + + { + "type": "Override", + "id": , + "override": "ignore-dnssec", + "domain": "nl", + "until": , + "created": + } + + + { + "type": "Override", + "id": , + "override": "replace", + "domain": "www.cnn.com.", + "rrtype": "AAAA", + "values": ["203.0.113.4", "203.0.113..2"], + "until": , + "created": + } + + **TODO**: what about validation here? + + :: + + { + "type": "Override", + "id": , + "override": "purge", + "domain": "example.net.", + "created": + } + + Clears recursively all cached data ("plain" DNS + DNSSEC) + + **TODO**: should this be stored? (for history) + +.. http:get:: /api/v1/servers/:server_id/overrides + + Collection access. + +.. http:post:: /api/v1/servers/:server_id/overrides + + Override edits + +.. http:get:: /api/v1/servers/:server_id/overrides/:override_id + +.. http:put:: /api/v1/servers/:server_id/overrides/:override_id + +.. http:delete:: /api/v1/servers/:server_id/overrides/:override_id + diff --git a/pdns/recursordist/docs/http-api/zone-properties.rst b/pdns/recursordist/docs/http-api/zone-properties.rst new file mode 100644 index 0000000000..07844128d8 --- /dev/null +++ b/pdns/recursordist/docs/http-api/zone-properties.rst @@ -0,0 +1,4 @@ +The Zone object in the Recursor also supportes these elements: + +:property [str] servers: For zones of type "Forwarded", addresses to send the queries to +:property bool recursion_desired: For zones of type "Forwarded", Whether or not the RD bit should be set in the query diff --git a/pdns/recursordist/docs/index.rst b/pdns/recursordist/docs/index.rst new file mode 100644 index 0000000000..661ded1880 --- /dev/null +++ b/pdns/recursordist/docs/index.rst @@ -0,0 +1,75 @@ +Introduction +============ + +.. image:: common/powerdns-logo-500px.png + :align: center + :alt: PowerDNS Logo + +The PowerDNS Recursor is a high-performance DNS recursor with built-in scripting capabilities. +It is known to power the resolving needs of over 150 million internet connections. + +The documentation is only for the 4.1 series, users of older versions are urged to upgrade! + +Notable features +---------------- + +- Can handle tens of thousands of concurrent questions. A quad Xeon 3GHz has been measured functioning very well at 400000 real life replayed packets per second. +- Relies heavily on Standard C++ Library infrastructure, which makes for little code. +- Powered by a highly modern DNS packet parser that should be resistant against many forms of buffer overflows. +- Best spoofing protection that we know about, involving both source port randomisation and spoofing detection. +- Uses 'connected' UDP sockets which allow the recursor to react quickly to unreachable hosts or hosts for which the server is running, but the nameserver is down. This makes the recursor faster to respond in case of misconfigured domains, which are sadly very frequent. +- Special support for FreeBSD, Linux and Solaris stateful multiplexing (kqueue, epoll, completion ports, /dev/poll). +- Very fast, and contains innovative query-throttling code to save time talking to obsolete or broken nameservers. +- Code is written linearly, sequentially, which means that there are no problems with 'query restart' or anything. +- The algorithm is simple and quite nifty. +- Does DNSSEC validation +- Is highly scriptable in `Lua `_ + +Getting support +--------------- +PowerDNS is an open source program so you may get help from the PowerDNS users' community or from its authors. +You may also help others (please do). + +Public support is available via several different channels: + + * This documentation + * `The mailing list `_ + * ``#powerdns`` on `irc.oftc.net `_ + +The PowerDNS company can provide help or support you in private as well. +For first class and rapid support, please contact powerdns.support@powerdns.com, or see the `.com website `__. + +My information is confidential, must I send it to the mailing list or discuss on IRC? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Yes, we have a support policy called `"Open Source Support: out in the open" `_. + +If you desire privacy, please consider entering a support relationship with us, in which case we invite you to contact powerdns.support.sales@powerdns.com. + +I have a question! +^^^^^^^^^^^^^^^^^^ +This happens, we're here to help! +Read below on how you can get help + +What details should I supply? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Start out with stating what you think should be happening. +Quite often, wrong expectations are the actual problem. +Furthermore, your operating system, which version of PowerDNS you use and where you got it from (RPM, .DEB, tar.bz2). +If you :doc:`compiled ` it yourself, what were the ``./configure`` parameters. + +If possible, supply the actual name of your domain and the IP address of your server(s). + +I found a bug! +^^^^^^^^^^^^^^ +As much as we'd like to think we are perfect, bugs happen. +If you have found a bug, please file a bug report on `GitHub `_. +Please fill in the template and we'll try our best to help you. + +I found a security issue! +^^^^^^^^^^^^^^^^^^^^^^^^^ +Please report this in private, see the :ref:`securitypolicy`. + +I have a good idea for a feature! +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We like to work on new things! +You can file a feature request on `GitHub `_. diff --git a/pdns/recursordist/docs/indexTOC.rst b/pdns/recursordist/docs/indexTOC.rst new file mode 100644 index 0000000000..88df07bbc7 --- /dev/null +++ b/pdns/recursordist/docs/indexTOC.rst @@ -0,0 +1,25 @@ +PowerDNS Recursor +================= + +.. toctree:: + :maxdepth: 3 + :glob: + + index + getting-started + running + performance + metrics + dnssec + lua-config/index + lua-scripting/index + http-api/index + dns64 + security + settings + manpages/* + security-advisories/index + upgrade + changelog/index + appendices/* + diff --git a/pdns/recursordist/docs/lua-config/dnssec.rst b/pdns/recursordist/docs/lua-config/dnssec.rst new file mode 100644 index 0000000000..837f1bddc5 --- /dev/null +++ b/pdns/recursordist/docs/lua-config/dnssec.rst @@ -0,0 +1,20 @@ +Managing DNSSEC Trust Anchors in the Lua Configuration +====================================================== +The DNSSEC Trust Anchors and Negative Trust Anchors must be stored in the Lua Configuration file. +See the :doc:`../dnssec` for all information about DNSSEC in the PowerDNS Recursor. +This page only documents the Lua functions for DNSSEC configuration + +.. function:: addDS(name, dscontent) + + Adds a DS record (Trust Anchor) to the configuration + + :param str name: The name in the DNS tree from where this Trust Anchor should be used + :param str dsrecord: The DS Record content associated with ``name`` + +.. function:: addNTA(name[, reason]) + + Adds a Negative Trust Anchor for ``name`` to the configuration. + Please read :ref:`ntas` for operational information on NTAs. + + :param str name: The name in the DNS tree from where this NTA should be used + :param str reason: An optional comment to add to this NTA diff --git a/pdns/recursordist/docs/lua-config/index.rst b/pdns/recursordist/docs/lua-config/index.rst new file mode 100644 index 0000000000..4899b55dc7 --- /dev/null +++ b/pdns/recursordist/docs/lua-config/index.rst @@ -0,0 +1,11 @@ +Lua Configuration +================= + +Since version 4.0.0, the PowerDNS Recursor supports additional configuration options that have to be loaded through :ref:`setting-lua-config-file`. + +.. toctree:: + + dnssec + sortlist + protobuf + rpz diff --git a/pdns/recursordist/docs/lua-config/protobuf.rst b/pdns/recursordist/docs/lua-config/protobuf.rst new file mode 100644 index 0000000000..33785c24ee --- /dev/null +++ b/pdns/recursordist/docs/lua-config/protobuf.rst @@ -0,0 +1,75 @@ +Logging DNS messages with Protocol Buffers +========================================== +The PowerDNS Recursor has the ability to emit a stream of protocol buffers messages over TCP, containing information about queries, answers and policy decisions. + +Messages contain the IP address of the client initiating the query, the one on which the message was received, whether it was received over UDP or TCP, a timestamp and the qname, qtype and qclass of the question. +In addition, messages related to responses contain the name, type, class and rdata of A, AAAA and CNAME records present in the response, as well as the response code. + +Finally, if a RPZ or custom Lua policy has been applied, response messages also contain the applied policy name and some tags. +This is particularly useful to detect and act on infected hosts. + +The protocol buffers message types can be found in the `dnsmessage.proto `_ file. + +Configuring Protocol Buffer logs +-------------------------------- +Protobuf export to a server is enabled using the ``protobufServer()`` directive: + +.. code-block:: Lua + + protobufServer("192.0.2.1:4242" [[[[[[[, timeout], maxQueuedEntries], reconnectWaitTime], maskV4], maskV6], asyncConnect], taggedOnly]) + +timeout +^^^^^^^ +Time in seconds to wait when sending a message, defaults to 2. + +maxQueuedEntries +^^^^^^^^^^^^^^^^ +How many entries will be kept in memory if the server becomes unreachable, defaults to 100. + +reconnectWaitTime +^^^^^^^^^^^^^^^^^ +How long to wait, in seconds, between two reconnection attempts, defaults to 1. + +maskV4 +^^^^^^ +network mask to apply to the client IPv4 addresses, for anonymization purposes. +The default of 32 means no anonymization. + +maskV6 +^^^^^^ +Same as maskV4, but for IPv6. Defaults to 128. + +taggedOnly +^^^^^^^^^^ +Only entries with a policy or a policy tag set will be sent. + +asyncConnect +^^^^^^^^^^^^ +When set to false (default) the first connection to the server during startup will block up to ``timeout`` seconds, otherwise the connection is done in a separate thread. + +Logging outgoing queries and responses +-------------------------------------- + +While ``protobufServer()`` only exports the queries sent to the recursor from clients, with the corresponding responses, ``outgoingProtobufServer()`` can be used to export outgoing queries sent by the recursor to authoritative servers, along with the corresponding responses. + +.. code-block:: Lua + + outgoingProtobufServer("192.0.2.1:4242" [[[[, timeout], maxQueuedEntries], reconnectWaitTime], asyncConnect]) + +The optional parameters for ``outgoingProtobufServer()`` are: + +timeout +^^^^^^^ +Time in seconds to wait when sending a message, defaults to 2. + +maxQueuedEntries +^^^^^^^^^^^^^^^^ +How many entries will be kept in memory if the server becomes unreachable, defaults to 100. + +reconnectWaitTime +^^^^^^^^^^^^^^^^^ +How long to wait, in seconds, between two reconnection attempts, defaults to 1. + +asyncConnect +^^^^^^^^^^^^ +When set to false (default) the first connection to the server during startup will block up to ``timeout`` seconds, otherwise the connection is done in a separate thread. diff --git a/pdns/recursordist/docs/lua-config/rpz.rst b/pdns/recursordist/docs/lua-config/rpz.rst new file mode 100644 index 0000000000..8bb211a534 --- /dev/null +++ b/pdns/recursordist/docs/lua-config/rpz.rst @@ -0,0 +1,138 @@ +.. _rpz: + +Response Policy Zones (RPZ) +=========================== + +Response Policy Zone is an open standard developed by Paul Vixie (ISC and Farsight) and Vernon Schryver (Rhyolite), to modify DNS responses based on a policy loaded via a zonefile. + +Frequently, Response Policy Zones get to be very large and change quickly, so it is customary to update them over IXFR. +It allows the use of third-party feeds, and near real-time policy updates. + +Configuring RPZ +--------------- +An RPZ can be loaded from file or slaved from a master. To load from file, use for example: + +.. code-block:: Lua + + rpzFile("dblfilename", {defpol=Policy.Custom, defcontent="badserver.example.com"}) + +To slave from a master and start IXFR to get updates, use for example: + +.. code-block:: Lua + + rpzMaster("192.0.2.4", "policy.rpz", {defpol=Policy.Drop}) + +In this example, 'policy.rpz' denotes the name of the zone to query for. + +.. function:: rpzFile(filename, settings) + + Load an RPZ from disk. + + :param str filename: The filename to load + :param {} settings: A table to settings, see below + +.. function:: rpzMaster(address, name, settings) + + Load an RPZ from AXFR and keep retrieving with IXFR. + + :param str address: The IP address to transfer the RPZ from + :param str name: The name of this RPZ + :param {} settings: A table to settings, see below + + +RPZ settings +------------ + +These options can be set in the ``settings`` of both :func:`rpzMaster` and :func:`rpzFile`. + +defpol +^^^^^^ +Default policy: `Policy.Custom`_, `Policy.Drop`_, `Policy.NXDOMAIN`_, `Policy.NODATA`_, `Policy.Truncate`_, `Policy.NoAction`_. + +defcontent +^^^^^^^^^^ +CNAME field to return in case of defpol=Policy.Custom + +defttl +^^^^^^ +the TTL of the CNAME field to be synthesized for the default policy. +The default is to use the zone's TTL, + +maxTTL +^^^^^^ +The maximum TTL value of the synthesized records, overriding a higher value from ``defttl`` or the zone. Default is unlimited. + +.. _rpz-policyName: + +policyName +^^^^^^^^^^ +The name logged as 'appliedPolicy' in :doc:`protobuf ` messages when this policy is applied. + +zoneSizeHint +^^^^^^^^^^^^ +An indication of the number of expected entries in the zone, speeding up the loading of huge zones by reserving space in advance. + +Extra Settings for rzpMaster +---------------------------- +In addition to the settings above the settings for :func:`rpzMaster` may contain: + +tsigname +^^^^^^^^ +The name of the TSIG key to authenticate to the server. +When this is set, `tsigalgo`_ and `tsigsecret`_ must also be set. + +tsigalgo +^^^^^^^^ +The name of the TSIG algorithm (like 'hmac-md5') used + +tsigsecret +^^^^^^^^^^ +Base64 encoded TSIG secret + +refresh +^^^^^^^ +An integer describing the interval between checks for updates. +By default, the RPZ zone's default is used + +maxReceivedMBytes +^^^^^^^^^^^^^^^^^ +The maximum size in megabytes of an AXFR/IXFR update, to prevent resource exhaustion. +The default value of 0 means no restriction. + +localAddress +^^^^^^^^^^^^ +The source IP address to use when transferring the RPZ. +When unset, :ref:`setting-query-local-address` and :ref:`setting-query-local-address6` are used. + +Policy Actions +-------------- + +If no settings are included, the RPZ is taken literally with no overrides applied. +Several Policy Actions exist + +Policy.Custom +^^^^^^^^^^^^^ +Will return a NoError, CNAME answer with the value specified with ``defcontent``, +when looking up the result of this CNAME, RPZ is not taken into account. + +Policy.Drop +^^^^^^^^^^^ +Will simply cause the query to be dropped. + +Policy.NoAction +^^^^^^^^^^^^^^^ +Will continue normal processing of the query. + + +Policy.NODATA +^^^^^^^^^^^^^ +Will return a NoError response with no value in the answer section. + +Policy.NXDOMAIN +^^^^^^^^^^^^^^^ +Will return a response with a NXDomain rcode. + +Policy.Truncate +^^^^^^^^^^^^^^^ +will return a NoError, no answer, truncated response over UDP. +Normal processing will continue over TCP diff --git a/pdns/recursordist/docs/lua-config/sortlist.rst b/pdns/recursordist/docs/lua-config/sortlist.rst new file mode 100644 index 0000000000..ba7fc01bc1 --- /dev/null +++ b/pdns/recursordist/docs/lua-config/sortlist.rst @@ -0,0 +1,33 @@ +Using Sortlist +============== +Sortlist is a complicated feature which allows for the ordering of A and AAAA records in answers to be modified, optionally dependently on who is asking. +Since clients frequently connect to the 'first' IP address they see, this can effectively allow you to make sure that user from, say 10.0.0.0/8 also preferably connect to servers in 10.0.0.0/8. + +The syntax consists of a netmask for which this ordering instruction applies, followed by a set of netmask (groups) which describe the desired ordering. +So an ordering instruction of "1.0.0.0/8", "2.0.0.0/8" will put anything within 1/8 first, and anything in 2/8 second. +Other IP addresses would follow behind the addresses sorted earlier. + +If netmasks are grouped, this means these get equal ordering. + +``addSortList`` +^^^^^^^^^^^^^^^ +``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. + +As an example, the following BIND sortlist: + +.. code-block:: none + + { 17.50.0.0/16; {17.238.240.0/24; 17.138.149.200; + {17.218.242.254; 17.218.252.254;}; 17.38.42.80; + 17.208.240.100; }; }; + +Gets transformed into: + +.. code-block:: Lua + + addSortList("17.50.0.0/16", {"17.238.240.0/24", "17.138.149.200", + {"17.218.242.254", "17.218.252.254"}, "17.38.42.80", + "17.208.240.100" }) + +In other words: each IP address is put within quotes, and are separated by commas instead of semicolons. +For the rest everything is identical. diff --git a/pdns/recursordist/docs/lua-scripting/comboaddress.rst b/pdns/recursordist/docs/lua-scripting/comboaddress.rst new file mode 100644 index 0000000000..68668e4c0d --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/comboaddress.rst @@ -0,0 +1,67 @@ +The ``ComboAddress`` class +========================== + +IP addresses are moved around in a native format, called ComboAddress within PowerDNS. +ComboAddresses can be IPv4 or IPv6, and unless you want to know, you don't need to. + +Make a :class:`ComboAddress` with: + +.. code-block:: Lua + + newCA("::1") + +A :class:`ComboAddress` can be compared against a NetmaskGroup with the :meth:`NetMaskGroup:match` function. + +To compare the address (so not the port) of two ComboAddresses, use :meth:`:equal `: + +.. code-block:: Lua + + a = newCA("[::1]:56") + b = newCA("[::1]:53") + a == b -- false, port mismatch + a:equal(b) -- true + +To convert an address to human-friendly representation, use :meth:`:toString ` or :meth:`:toStringWithPort `. +To get only the port number, use :meth:`:getPort() `. + +.. class:: ComboAddress + + An object representing an IP address and port tuple. + +.. classmethod:: ComboAddress:getPort() -> int + + The portnumber. + +.. classmethod:: ComboAddress:getRaw() -> str + + A bytestring representing the address. + +.. classmethod:: ComboAddress:isIPv4() -> bool + + True if the address is an IPv4 address. + +.. classmethod:: ComboAddress:isIPv6() -> bool + + True if the address is an IPv6 address. + +.. classmethod:: ComboAddress:isMappedIPv4() -> bool + + True if the address is an IPv4 address mapped into an IPv6 one. + +.. classmethod:: ComboAddress:mapToIPv4() -> ??? + + If the address is an IPv4 mapped into an IPv6 one, return the corresponding IPv4 address. + +.. classmethod:: ComboAddress:toString() -> str + + Returns the IP address without the port number as a string. + +.. classmethod:: ComboAddress:toStringWithPort() -> str + + Returns the IP address with the port number as a string. + +.. classmethod:: ComboAddress:truncate(bits) + + Truncate to the supplied number of bits + + :param int bits: The number of bits to truncate to diff --git a/pdns/recursordist/docs/lua-scripting/configure.rst b/pdns/recursordist/docs/lua-scripting/configure.rst new file mode 100644 index 0000000000..d6b7ac2ff6 --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/configure.rst @@ -0,0 +1,22 @@ +Configuring Lua scripts +======================= + +In order to load scripts, the PowerDNS Recursor must have Lua support built in. +The packages distributed from the PowerDNS website have this language enabled, other distributions may differ. +By default, the Recursor's configure script will attempt to detect if Lua is available. + +**note**: Only one script can be loaded at the same time. If you load a different script, the current one will be replaced (safely)! + +If Lua support is available, a script can be configured either via the configuration file, or at runtime via the ``rec_control`` tool. +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. + +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. + +**Note**: It is also possible to precompile scripts using ``luac``, and have PowerDNS load the result. +This means that switching scripts is faster, and also that you'll be informed about syntax errors at compile time. + +Finally, ``rec_control unload-lua-script`` can be used to remove the currently installed script, and revert to unmodified behaviour. diff --git a/pdns/recursordist/docs/lua-scripting/dnsname.rst b/pdns/recursordist/docs/lua-scripting/dnsname.rst new file mode 100644 index 0000000000..9c0ae67601 --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/dnsname.rst @@ -0,0 +1,104 @@ +DNS names and comparing them +============================ + +The PowerDNS Recursor uses a native format for the names it handles. +This native format is exposed to Lua as well. + +The DNSName object +------------------ + +.. class:: DNSName + + A ``DNSName`` object represents a name in the DNS. + It is returned by several functions and has several functions to programmatically interact with it. + +Creating a :class:`DNSName` is done with :func:`newDN()`. +The PowerDNS Recursor will complain loudly if the name is invalid (e.g. too long, dot in the wrong place). + +.. code-block:: lua + + myname = newDN("www.example.com") + print(myname:countLabels()) -- prints "3" + print(myname:wirelength()) -- prints "17" + name2 = newDN(myname) + name2:chopoff() -- returns true, as 'www' was stripped + if myname:isPartOf(name2) then -- prints "it is" + print('it is') + end + +:class:`DNSNames ` can be compared agains each other using the :meth:`:equal ` function or the ``==`` operator. + +.. function:: newDN(name) -> DNSName + + Returns the :class:`DNSName` object of ``name``. + + :param string name: The name to create a DNSName for + +.. classmethod:: DNSName::chopOff() -> bool + + Removes the left-most label and returns ``true``. + ``false`` is returned if no label was removed + +.. classmethod:: DNSName:countLabels() -> int + + Returns the number of DNSLabels in the name + +.. classmethod:: DNSName:isPartOf(name) -> bool + + Returns true if the DNSName is part of the DNS tree of ``name``. + + .. code-block:: Lua + + newDN("www.powerdns.com"):isPartOf(newDN("CoM.")) -- true + + :param DNSName name: The name to check against + +.. classmethod:: DNSName:toString() -> str + DNSName:toStringNoDot() -> str + + Returns a human-readable form of the DNSName. + With or without trailing dot. + +.. classmethod:: DNSName:wirelength -> int + + Returns the length in bytes of the DNSName as it would be on the wire. + +DNS Suffix Match Groups +----------------------- + +The func:`newDS` function creates a "Suffix Match group" that allows fast checking if a :class:`DNSName` is part of a group. +This could e.g. be used to answer questions for known malware domains. +To check e.g. the ``dq.qname`` against a list: + +.. code-block:: Lua + + m = newDS() + m:add({'example.com', 'example.net}) + m:check(dq.qname) -- Would be true is dq.qname is a name in example.com or example.net + +.. function:: newDS() -> DNSSuffixMatchGroup + + Creates a new DNS Suffix Match Group. + +.. class:: DNSSuffixMatchGroup + + This class represents a group of DNS names that can be used to quickly compare a single :class:`DNSName` against. + +.. classmethod:: DNSSuffixMatchGroup::add(domain) + DNSSuffixMatchGroup::add(domains) + + Add one or more domains to the Suffix Match Group. + + :param str domain: A domain name to add + :param {str} domain: A list of Domains to add + +.. classmethod:: DNSSuffixMatchGroup:check(domain) -> bool + + Check ``domain`` against the Suffix Match Group. + Returns true if it is matched, false otherwise. + + :param DNSName domain: The domain name to check + +.. classmethod:: DNSSuffixMatchGroup:toString() -> str + + Returns a string of the set of suffixes matched by the Suffix Match Group diff --git a/pdns/recursordist/docs/lua-scripting/dnsrecord.rst b/pdns/recursordist/docs/lua-scripting/dnsrecord.rst new file mode 100644 index 0000000000..5caa797b13 --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/dnsrecord.rst @@ -0,0 +1,42 @@ +DNS Record +========== + +DNS record objects are returned by :meth:`DNSQuestion:getRecords`. + +.. class:: DNSRecord + + Represents a single DNS record. + +.. attribute:: DNSRecord.name -> DNSName + + The name of the record. + +.. attribute:: DNSRecord.place -> int + + The place where the record is located, + - 1 for the answer section + - 2 for the authority section + - 3 for the additional section + +.. attribute:: DNSRecord.ttl -> int + + The TTL of the record + +.. attribute:: DNSRecord.type -> int + + The type of the record, for example pdns.A + +.. classmethod:: DNSRecord:changeContent(newcontent) + + Replace the record content with ``newcontent``. + The type and class cannot be changed. + + :param str newcontent: The replacing content + +.. classmethod:: DNSRecord:getCA() -> ComboAddress + + If the record type is A or AAAA, a :class:`ComboAddress` representing the content is returned, nil otherwise. + +.. classmethod:: DNSRecord:getContent() -> str + + Return a string representation of the record content. diff --git a/pdns/recursordist/docs/lua-scripting/dq.rst b/pdns/recursordist/docs/lua-scripting/dq.rst new file mode 100644 index 0000000000..4c2f0b4dd5 --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/dq.rst @@ -0,0 +1,257 @@ +The DNSQuestion (``dq``) object +=============================== +Apart from the :func:`ipfilter`-function, all functions work on a ``dq`` (DNSQuestion) object. +This object contains details about the current state of the question. +This state can be modified from the various hooks. + +The DNSQuestion object contains at least the following fields: + +.. class:: DNSQuestion + + An object that contains everything about the current query. + +.. attribute:: DNSQuestion.qname + + :class:`DNSName` of the name this query is for. + +.. attribute:: DNSQuestion.qtype + + Type this query is for as an integer, can be compared against ``pdns.A``, ``pdns.AAAA``. + +.. attribute:: DNSQuestion.rcode + + current DNS Result Code, which can be overridden, including to several magical values + The rcode can be set to pdns.DROP to drop the query. + Other statuses are normal DNS return codes, like ``pdns.NOERROR``, ``pdns.NXDOMAIN`` etc. + +.. attribute:: DNSQuestion.isTcp + + Boolean whether the query have been received over TCP. + +.. attribute:: DNSQuestion.remoteaddr -> ComboAddress + + :class:`ComboAddress` of the requestor. + +.. attribute:: DNSQuestion.localaddr -> ComboAddress + + :class:`ComboAddress` where this query was received on. + +.. attribute:: DNSQuestion.variable + + Boolean which, if set, indicates the recursor should not packet cache this answer. + Honored even when returning false from a hook! + Important when providing answers that vary over time or based on sender details. + +.. attribute:: DNSQuestion.followupFunction + + String that signals the nameserver to take one an additional action: + + - followCNAMERecords: When adding a CNAME to the answer, this tells the recursor to follow that CNAME. See :ref:`CNAME Chain Resolution ` + - getFakeAAAARecords: Get a fake AAAA record, see :doc:`DNS64 <../dns64>` + - getFakePTRRecords: Get a fake PTR record, see :doc:`DNS64 <../dns64>` + - udpQueryResponse: Do a UDP query and call a handler, see :ref:`UDP Query Response ` + +.. attribute:: DNSQuestion.appliedPolicy + + The decision that was made by the policy engine, see :ref:`modifyingpolicydecisions`. + +.. attribute:: DNSQuestion.appliedPolicy.policyName + + A string with the name of the policy. + Set by :ref:`policyName ` in the :func:`rpzFile` and :func:`rpzMaster` configuration items. + It is advised to overwrite this when modifying the :attr:`DNSQuestion.appliedPolicy.policyKind` + +.. attribute:: DNSQuestion.appliedPolicy.policyAction + + The action taken by the engine + +.. attribute:: DNSQuestion.appliedPolicy.policyCustom + + The CNAME content for the ``pdns.policyactions.Custom`` response, a string + +.. attribute:: DNSQuestion.appliedPolicy.policyKind + + The kind of policy response, there are several policy kinds: + + - ``pdns.policykinds.Custom`` will return a NoError, CNAME answer with the value specified in :attr:`DNSQuestion.appliedPolicy.policyCustom` + - ``pdns.policykinds.Drop`` will simply cause the query to be dropped + - ``pdns.policykinds.NoAction`` will continue normal processing of the query + - ``pdns.policykinds.NODATA`` will return a NoError response with no value in the answer section + - ``pdns.policykinds.NXDOMAIN`` will return a response with a NXDomain rcode + - ``pdns.policykinds.Truncate`` will return a NoError, no answer, truncated response over UDP. Normal processing will continue over TCP + +.. attribute:: DNSQuestion.appliedPolicy.policyTTL + + The TTL in seconds for the ``pdns.policyactions.Custom`` response + +.. attribute:: DNSQuestion.wantsRPZ + + A boolean that indicates the use of the Policy Engine. + Can be set to ``false`` in ``prerpz`` to disable RPZ for this query. + +.. attribute:: DNSQuestion.data + + A Lua object reference that is persistent throughout the lifetime of the :class:`DNSQuestion` object for a single query. + It can be used to store custom data. + Most scripts initialise this to an empty table early on so they can store multiple items. + +.. attribute:: DNSQuestion.requestorId str + + .. versionadded:: 4.1.0 + + A string that will be used to set the ``requestorId`` field in :doc:`protobuf <../lua-config/protobuf>` messages. + +.. attribute:: DNSQuestion.udpAnswer -> str + + Answer to the :attr:`udpQuery ` when when using the ``udpQueryResponse`` :attr:`followupFunction `. + Only filled when the call-back function is invoked. + +.. attribute:: DNSQuestion.udpQueryDest -> str + + Destination IP address to send the UDP packet to when using the ``udpQueryResponse`` :attr:`followupFunction ` + +.. attribute:: DNSQuestion.udpQuery -> str + + The content of the UDP payload when using the ``udpQueryResponse`` :attr:`followupFunction ` + +.. attribute:: DNSQuestion.udpCallback -> str + + The name of the callback function that is called when using the ``udpQueryResponse`` :attr:`followupFunction ` when an answer is received. + +It also supports the following methods: + +.. classmethod:: DNSQuestion:addAnswer(type, content, [ttl, name]) + + Add an answer to the record of ``type`` with ``content``. + + :param int type: The type of record to add, can be ``pdns.AAAA`` etc. + :param str content: The content of the record, will be parsed into wireformat based on the ``type`` + :param int ttl: The TTL in seconds for this record + :param ??? name: The name of this record, defaults to :attr:`DNSQuestion.qname` + +.. classmethod:: DNSQuestion:addPolicyTag(tag) + + Add a policy tag. + + :param str tag: The tag to add + +.. classmethod:: DNSQuestion:discardPolicy(policyname) + + Skip the filtering policy (for example RPZ) named ``policyname`` for this query. + This is mostly useful in the ``prerpz`` hook. + + :param str policyname: The name of the policy to ignore. + +.. classmethod:: DNSQuestion:getDH() -> DNSHeader + + Returns the :class:`DNSHeader` of the query or nil. + +.. classmethod:: DNSQuestion:getPolicyTags() -> {str} + + Get the current policy tags as a table of strings. + +.. classmethod:: DNSQuestion:getRecords() -> {DNSRecord} + + Get a table of DNS Records in this DNS Question (or answer by now). + +.. classmethod:: DNSQuestion:setPolicyTags(tags) + + Set the policy tags to ``tags``, overwriting any existing policy tags. + + :param {str} tags: The policy tags + +.. classmethod:: DNSQuestion:setRecords(records) + + After your edits, update the answers of this question + + :param {DNSRecord} records: The records to put in the packet + +.. classmethod:: DNSQuestion:getEDNSFlag(name) -> bool + + Returns true if the EDNS flag with ``name`` is set in the query. + + :param string name: Name of the flag. + +.. classmethod:: DNSQuestion:getEDNSFlags() -> {str} + + Returns a list of strings with all the EDNS flag mnemonics in the query. + +.. classmethod:: DNSQuestion:getEDNSOption(num) -> str + + Get the EDNS Option with number ``num`` as a bytestring. + +.. classmethod:: DNSQuestion:getEDNSOptions() {str: str} + + Get a map of all EDNS Options + +.. classmethod:: DNSQuestion:getEDNSSubnet() -> Netmask + + Returns the netmask specified in the EDNSSubnet option, or empty if there was none. + +.. classmethod:: DNSQuestion:addPolicyTag(tag) + + Add policyTag ``tag`` to the list of policyTags + + :param str tag: The tag to add + +.. classmethod:: DNSQuestion:getPolicyTags() -> {str} + + Get a list the policyTags for this message. + + + +DNSHeader Object +================ + +The DNS header as returned by :meth:`DNSQuestion:getDH()` represents a header of a DNS message. + +.. class:: DNSHeader + + represents a header of a DNS message. + +.. classmethod:: DNSHeader:getRD() -> bool + + The value of the Recursion Desired bit. + +.. classmethod:: DNSHeader:getAA() -> bool + + The value of the Authoritative Answer bit. + +.. classmethod:: DNSHeader:getAD() -> bool + + The value of the Authenticated Data bit. + +.. classmethod:: DNSHeader:getCD() -> bool + + The value of the Checking Disabled bit. + +.. classmethod:: DNSHeader:getTC() -> bool + + The value of the Truncation bit. + +.. classmethod:: DNSHeader:getRCODE() -> int + + The Response Code of the query + +.. classmethod:: DNSHeader:getOPCODE() -> int + + The Operation Code of the query + +.. classmethod:: DNSHeader:getID() -> int + + The ID of the query + +The EDNSOptionView Class +======================== + +.. class:: EDNSOptionView + + An object that represents a single EDNS option + +.. attribute:: EDNSOptionView.size -> int + + The size in bytes of the EDNS option. + +.. classmethod:: EDNSOptionView:getContent() -> str + + Returns a NULL-safe string object of the EDNS option's content diff --git a/pdns/recursordist/docs/lua-scripting/functions.rst b/pdns/recursordist/docs/lua-scripting/functions.rst new file mode 100644 index 0000000000..8026a252d8 --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/functions.rst @@ -0,0 +1,15 @@ +Other functions +=============== + +These are some functions that don't really have a place in one of the other categories. + +.. function:: getregisteredname(name) + + Returns the shortest domain name based on Mozilla's Public Suffix List. + In general it will tell you the 'registered domain' for a given name. + + For example ``getregisteredname('www.powerdns.com')`` returns "powerdns.com" + +.. function:: getRecursorThreadId() -> int + + returns an unsigned integer identifying the thread handling the current request. diff --git a/pdns/recursordist/docs/lua-scripting/hooks.rst b/pdns/recursordist/docs/lua-scripting/hooks.rst new file mode 100644 index 0000000000..2c022806a7 --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/hooks.rst @@ -0,0 +1,314 @@ +Intercepting queries with Lua +============================= +To get a quick start, we have supplied a sample script that showcases all functionality described below. +Please find it `here `_. + +Queries can be intercepted in many places: + +- before any packet parsing begins (:func:`ipfilter`) +- before any filtering policy have been applied (:func:`prerpz`) +- before the resolving logic starts to work (:func:`preresolve`) +- after the resolving process failed to find a correct answer for a domain (:func:`nodata`, :func:`nxdomain`) +- after the whole process is done and an answer is ready for the client (:func:`postresolve`) +- before an outgoing query is made to an authoritative server (:func:`preoutquery`) + +Writing Lua PowerDNS Recursor scripts +------------------------------------- +Addresses and DNS Names are not passed as strings but as native objects. +This allows for easy checking against `Netmasks `_ and `domain sets `_. +It also means that to print such names, the ``:toString`` method must be used (or even ``:toStringWithPort`` for addresses). + +Once a script is loaded, PowerDNS looks for several `functions `_ in the loaded script. +All of these functions are optional. + +If a function returns true, it will indicate that it handled a query. +If it returns false, the Recursor will continue processing unchanged (with one minor exception). + +Interception Functions +---------------------- + +.. function:: ipfilter(remoteip, localip, dh) -> bool + + This hook gets queried immediately after consulting the packet cache, but before parsing the DNS packet. + If this hook returns something else than false, the packet is dropped. + However, because this check is after the packet cache, the IP address might still receive answers that require no packet parsing. + + With this hook, undesired traffic can be dropped rapidly before using precious CPU cycles for parsing. + As an example, to filter all queries coming from 1.2.3.0/24, or with the + AD bit set: + + .. code-block:: Lua + + badips = newNMG() + badips:addMask("1.2.3.0/24") + + function ipfilter(rem, loc, dh) + return badips:match(rem) or dh:getAD() + end + + This hook does not get the full :class:`DNSQuestion` object, since filling out the fields would require packet parsing, which is what we are trying to prevent with this function. + + :param ComboAddress remoteip: The IP(v6) address of the requestor + :param ComboAddress localip: The address on which the query arrived. + :param DNSHeader dh: The DNS Header of the query. + + +.. function:: gettag(remote, ednssubnet, local, qname, qtype, ednsoptions, tcp) -> int + gettag(remote, ednssubnet, local, qname, qtype, ednsoptions) -> int + + .. versionchanged:: 4.1.0 + + The ``tcp`` parameter was added. + + The ``gettag`` function is invoked when the Recursor attempts to discover in which packetcache an answer is available. + + This function must return an integer, which is the tag number of the packetcache. + In addition to this integer, this function can return a table of policy tags. + The resulting tag number can be accessed via :attr:`dq.tag ` in the :func:`preresolve` hook, and the policy tags via :meth:`dq:getPolicyTags() ` in every hook. + + .. versionadded:: 4.1.0 + + It can also return a table whose keys and values are strings to fill the :attr:`DNSQuestion.data` table, as well as a ``requestorId`` value to fill the :attr:`DNSQuestion.requestorId` field. + + The tagged packetcache can e.g. be used to answer queries from cache that have e.g. been filtered for certain IPs (this logic should be implemented in :func:`gettag`). + This ensure that queries are answered quickly compared to setting :attr:`dq.variable ` to true. + In the latter case, repeated queries will pass through the entire Lua script. + + :param ComboAddress remote: The sender's IP address + :param ??? ednssubnet: The EDNS Client subnet that was extracted from the packet + :param ComboAddress local: 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 bool tcp: Added in 4.1.0, a boolean indicating whether the query was received over UDP (false) or TCP (true). + +.. function:: prerpz(dq) + + This hook is called before any filtering policy have been applied, making it possible to completely disable filtering by setting :attr:`dq.wantsRPZ ` to false. + Using the :meth:`dq:discardPolicy() ` function, it is also possible to selectively disable one or more filtering policy, for example RPZ zones, based on the content of the ``dq`` object. + + As an example, to disable the "malware" policy for example.com queries: + + .. code-block:: Lua + + function prerpz(dq) + -- disable the RPZ policy named 'malware' for example.com + if dq.qname:equal('example.com') then + dq:discardPolicy('malware') + end + return false + end + + :param DNSQuestion dq: The DNS question to handle + +.. function:: preresolve(dq) + + This function is called before any DNS resolution is attempted, and if this function indicates it, it can supply a direct answer to the DNS query, overriding the internet. + This is useful to combat botnets, or to disable domains unacceptable to an organization for whatever reason. + + :param DNSQuestion dq: The DNS question to handle + +.. function:: postresolve(dq) + + is called right before returning a response to a client (and, unless :attr:`dq.variable ` is set, to the packet cache too). + It allows inspection and modification of almost any detail in the return packet. + + :param DNSQuestion dq: The DNS question to handle + +.. function:: nxdomain(dq) + + is called after the DNS resolution process has run its course, but ended in an 'NXDOMAIN' situation, indicating that the domain does not exist. + Works entirely like :func:`postresolve`, but saves a trip through Lua for answers which are not NXDOMAIN. + + :param DNSQuestion dq: The DNS question to handle + +.. function:: nodata(dq) + + is just like :func:`nxdomain`, except it gets called when a domain exists, but the requested type does not. + This is where one would implement :doc:`DNS64 <../dns64>`. + + :param DNSQuestion dq: The DNS question to handle + +.. function:: preoutquery(dq) + + This hook is not called in response to a client packet, but fires when the Recursor wants to talk to an authoritative server. + When this hook sets the special result code -3, the whole DNS client query causing this outquery gets dropped. + + However, this function can also return records like :func:`preresolve`. + + :param DNSQuestion dq: The DNS question to handle + +Semantics +^^^^^^^^^ +The functions must return ``true`` if they have taken over the query and wish that the nameserver should not proceed with its regular query-processing. +When a function returns ``false``, the nameserver will process the query normally until a new function is called. + +If a function has taken over a request, it should set an rcode (usually 0), and specify a table with records to be put in the answer section of a packet. +An interesting rcode is NXDOMAIN (3, or ``pdns.NXDOMAIN``), which specifies the non-existence of a domain. + +The :func:`ipfilter` and :func:`preoutquery` hooks are different, in that :func:`ipfilter` can only return a true of false value, and that :func:`preoutquery` can also set rcode -3 to signify that the whole query should be terminated. + +A minimal sample script: + +.. code-block:: Lua + + function nxdomain(dq) + print("Intercepting NXDOMAIN for: ",dq.qname:toString()) + if dq.qtype == pdns.A + then + dq.rcode=0 -- make it a normal answer + dq:addAnswer(pdns.A, "192.168.1.1") + return true + end + return false + end + +**Warning**: Please do NOT use the above sample script in production! +Responsible NXDomain redirection requires more attention to detail. + +Useful 'rcodes' include 0 for "no error", ``pdns.NXDOMAIN`` for "NXDOMAIN", ``pdns.DROP`` to drop the question from further processing. +Such a drop is accounted in the 'policy-drops' metric. + +DNS64 +----- + +The ``getFakeAAAARecords`` and ``getFakePTRRecords`` followupFunctions +can be used to implement DNS64. See `DNS64 support in the PowerDNS +Recursor `__ for more information. + +To get fake AAAA records for DNS64 usage, set dq.followupFunction to +``getFakeAAAARecords``, dq.followupPrefix to e.g. "64:ff9b::" and +dq.followupName to the name you want to synthesize an IPv6 address for. + +For fake reverse (PTR) records, set dq.followupFunction to +``getFakePTRRecords`` and set dq.followupName to the name to look up and +dq.followupPrefix to the same prefix as used with +``getFakeAAAARecords``. + +Follow up actions +----------------- +When modifying queries, it might be needed that the Recursor does some extra work after the function returns. +The :attr:`dq.followupFunction ` can be set in this case. + +.. _cnamechainresolution: + +CNAME chain resolution +^^^^^^^^^^^^^^^^^^^^^^ +It may be useful to return a CNAME record for Lua, and then have the PowerDNS Recursor continue resolving that CNAME. +This can be achieved by setting dq.followupFunction to ``followCNAMERecords`` and dq.followupDomain to "www.powerdns.com". +PowerDNS will do the rest. + +.. _udpqueryresponse: + +UDP Query Response +^^^^^^^^^^^^^^^^^^ +The ``udpQueryResponse`` :attr:`dq.followupFunction ` allows you to query a simple key-value store over UDP asynchronously. + +Several dq variables can be set: + +- :attr:`dq.udpQueryDest `: destination IP address to send the UDP packet to +- :attr:`dq.udpQuery `: The content of the UDP payload +- :attr:`dq.udpCallback `: The name of the callback function that is called when an answer is received + +The callback function must accept the ``dq`` object and can find the response to the UDP query in :attr:`dq.udpAnswer `. + +In this callback function, :attr:`dq.followupFunction ` can be set again to any of the available functions for further processing. + +This example script queries a simple key/value store over UDP to decide on whether or not to filter a query: + +.. literalinclude:: ../../contrib/kv-example-script.lua + :language: Lua + +Example Script +-------------- + +.. literalinclude:: ../../contrib/powerdns-example-script.lua + :language: Lua + +Dropping all traffic from botnet-infected users +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Frequently, DoS attacks are performed where specific IP addresses are attacked, often by queries coming in from open resolvers. +These queries then lead to a lot of queries to 'authoritative servers' which actually often aren't nameservers at all, but just targets of attack. + +The following script will add a requestor's IP address to a blocking set if they've sent a query that caused PowerDNS to attempt to talk to a certain subnet. + +This specific script is, as of January 2015, useful to prevent traffic to ezdns.it related traffic from creating CPU load. +This script requires PowerDNS Recursor 4.x or later. + +.. code-block:: Lua + + lethalgroup=newNMG() + lethalgroup:addMask("192.121.121.0/24") -- touch these nameservers and you die + + function preoutquery(dq) + print("pdns wants to ask "..dq.remoteaddr:toString().." about "..dq.qname:toString().." "..dq.qtype.." on behalf of requestor "..dq.localaddr:toString()) + if(lethalgroup:match(dq.remoteaddr)) + then + print("We matched the group "..lethalgroup:tostring().."!", "killing query dead & adding requestor "..dq.localaddr:toString().." to block list") + dq.rcode = -3 -- "kill" + return true + end + return false + end + +.. _modifyingpolicydecisions: + +Modifying Policy Decisions +-------------------------- +The PowerDNS Recursor has a :doc:`policy engine based on Response Policy Zones (RPZ) <../lua-config/rpz>`. +Starting with version 4.0.1 of the recursor, it is possible to alter this decision inside the Lua hooks. + +If the decision is modified in a Lua hook, ``false`` should be returned, as the query is not actually handled by Lua so the decision is picked up by the Recursor. +The result of the policy decision is checked after :func:`preresolve` and :func:`postresolve`. + +For example, if a decision is set to ``pdns.policykinds.NODATA`` by the policy engine and is unchanged in :func:`preresolve`, the query is replied to with a NODATA response immediately after :func:`preresolve`. + +Example script +^^^^^^^^^^^^^^ + +.. code-block:: Lua + + -- Dont ever block my own domain and IPs + myDomain = newDN("example.com") + + myNetblock = newNMG() + myNetblock:addMasks("192.0.2.0/24") + + function preresolve(dq) + if dq.qname:isPartOf(myDomain) and dq.appliedPolicy.policyKind ~= pdns.policykinds.NoAction then + pdnslog("Not blocking our own domain!") + dq.appliedPolicy.policyKind = pdns.policykinds.NoAction + end + end + + function postresolve(dq) + if dq.appliedPolicy.policyKind ~= pdns.policykinds.NoAction then + local records = dq:getRecords() + for k,v in pairs(records) do + if v.type == pdns.A then + local blockedIP = newCA(v:getContent()) + if myNetblock:match(blockedIP) then + pdnslog("Not blocking our IP space") + dq.appliedPolicy.policyKind = pdns.policykinds.NoAction + end + end + end + end + end + +SNMP Traps +---------- + +PowerDNS Recursor, when compiled with SNMP support, has the ability to +act as a SNMP agent to provide SNMP statistics and to be able to send +traps from Lua. + +For example, to send a custom SNMP trap containing the qname from the +``preresolve`` hook: + +.. code-block:: Lua + + function preresolve(dq) + sendCustomSNMPTrap('Trap from preresolve, qname is '..dq.qname:toString()) + return false + end diff --git a/pdns/recursordist/docs/lua-scripting/index.rst b/pdns/recursordist/docs/lua-scripting/index.rst new file mode 100644 index 0000000000..12448fc8eb --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/index.rst @@ -0,0 +1,28 @@ +Scripting The Recursor +====================== +In the PowerDNS recursor, it is possible to modify resolving behaviour using simple scripts written in the `Lua `_ programming language. + +**Note**: This describes the Lua scripts as supported by 4.x. They are very different than the ones from 3.x, but tend to be faster and more correct. + +These scripts can be used to quickly override dangerous domains, fix things that are wrong, for load balancing or for legal or commercial purposes. +The scripts can also protect you or your users from malicious traffic. + +Lua is extremely fast and lightweight, easily supporting hundreds of thousands of queries per second. +The Lua language is explained very well in the excellent book `Programming in Lua `_. +If you already have programming experience, `Learn Lua in 15 Minutes `_ is a great primer. + +For extra performance, a Just In Time compiled version of Lua called `LuaJIT `_ is supported. + +.. toctree:: + :maxdepth: 2 + + configure + dq + dnsname + dnsrecord + comboaddress + netmask + statistics + logging + hooks + functions diff --git a/pdns/recursordist/docs/lua-scripting/logging.rst b/pdns/recursordist/docs/lua-scripting/logging.rst new file mode 100644 index 0000000000..7591defd00 --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/logging.rst @@ -0,0 +1,24 @@ +Logging from the Lua scripts +============================ +To log messages with the main PowerDNS Recursor process, use :func:`pdnslog`. +:func:`pdnslog` can also write out to a syslog loglevel if specified. +Use ``pdnslog(message, pdns.loglevels.LEVEL)`` with the +correct pdns.loglevels entry. Entries are listed in the following table: + +.. function:: pdnslog(message) + pdnslog(message, level) + + Log ``message` at the Info level if ``level`` is not set. + + :param str msg: The message to log + :param int level: The log level to log at, see below. + + - All - ``pdns.loglevels.All`` + - Alert - ``pdns.loglevels.Alert`` + - Critical - ``pdns.loglevels.Critical`` + - Error - ``pdns.loglevels.Error`` + - Warning - ``pdns.loglevels.Warning`` + - Notice - ``pdns.loglevels.Notice`` + - Info - ``pdns.loglevels.Info`` + - Debug - ``pdns.loglevels.Debug`` + - None - ``pdns.loglevels.None`` diff --git a/pdns/recursordist/docs/lua-scripting/netmask.rst b/pdns/recursordist/docs/lua-scripting/netmask.rst new file mode 100644 index 0000000000..458bb26be4 --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/netmask.rst @@ -0,0 +1,93 @@ +.. _scripting-netmasks: + +Netmasks and NetMaskGroups +========================== + +There are two classes in the PowerDNS Recursor that can be used to match IP addresses against. + +Netmask class +------------- + +.. class:: Netmask + + Represents an IP netmask. + Can be created with + + .. code-block:: Lua + + newNetmask("192.0.2.1/24") + +.. classmethod:: Netmask:empty() -> bool + + True if the netmask doesn't contain a valid address. + +.. classmethod:: Netmask:getBits() -> int + + The number of bits in the address. + +.. classmethod:: Netmask:getNetwork() -> ComboAddress + + Returns a :class:`ComboAddress` representing the network (no mask applied). + +.. classmethod:: Netmask:getMaskedNetwork() -> ComboAddress + + Returns a :class:`ComboAddress` representing the network (truncating according to the mask). + +.. classmethod:: Netmask:isIpv4() -> bool + + True if the netmask is an IPv4 netmask. + +.. classmethod:: Netmask:isIpv6 -> bool + + True if the netmask is an IPv6 netmask. + +.. classmethod:: Netmask:match(address) -> vool + + True if the address passed in address matches + + :param str address: IP Address to match against. + +.. classmethod:: Netmask:toString() -> str + + Returns a human-friendly representation. + +NetMaskGroup class +------------------ + +NetMaskGroups are more powerful than plain Netmasks. + +.. class:: NetMaskGroup + + IP addresses are passed to Lua in native format. + They can be matched against netmasks objects: + + .. code-block:: Lua + + nmg = newNMG() + nmg:addMask("127.0.0.0/8") + nmg:addMasks({"213.244.168.0/24", "130.161.0.0/16"}) + nmg:addMasks(dofile("bad.ips")) -- contains return {"ip1","ip2"..} + + if nmg:match(dq.remoteaddr) then + print("Intercepting query from ", dq.remoteaddr) + end + + Prefixing a mask with ``!`` excludes that mask from matching. + +.. classmethod:: NetMaskGroup:addMask(mask) + + Adds ``mask`` to the NetMaskGroup. + + :param str mask: The mask to add. + +.. classmethod:: NetMaskGroup:addMasks(masks) + + Adds ``masks`` to the NetMaskGroup. + + :param {str} mask: The masks to add. + +.. classmethod:: NetMaskGroup:match(address) -> bool + + Returns true if ``address`` matches any of the masks in the group. + + :param ComboAddress address: The IP addres to match the netmasks against. diff --git a/pdns/recursordist/docs/lua-scripting/statistics.rst b/pdns/recursordist/docs/lua-scripting/statistics.rst new file mode 100644 index 0000000000..1df9201d2e --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/statistics.rst @@ -0,0 +1,61 @@ +Lua Scripting and Statistics +============================ + +The Lua engine can generate metrics and can + +Generating Metrics +------------------ +Custom metrics can be added which will be shown in the output of 'rec_control get-all' and sent to the metrics server over the Carbon protocol. +They will also appear in the JSON HTTP API. + +Create a custom metric with: ``myMetric=getMetric("myspecialmetric")``. + +.. function:: getMetric(name) -> Metric + + Returns the :class:`Metric` object with the name ``name``. + + :param str name: The metric to retrieve + +.. class:: Metric + + Represents a custom metric + +.. classmethod:: Metric::inc() + + Increase metric by 1 + +.. classmethod:: Metric::incBy(amount) + + Increase metric by amount + + :param int amount: + +.. classmethod:: Metric::set(to) + + Set metric to value ``to`` + + :param int to: + +.. classmethod:: Metric::get() -> int + + Get value of metric + +Metrics are shared across all of PowerDNS and are fully atomic and high performance. +A :class:`Metric` object is effectively a pointer to an atomic value. + +Note that metrics live in the same namespace as 'system' metrics. So if you generate one that overlaps with a PowerDNS stock metric, you will get double output and weird results. + +Looking at Statistics +--------------------- +.. versionadded:: 4.1.0 + +Statistics can be retrieved from Lua using the :func:`getStat` call. +For example, to retrieve the number of cache misses: + +.. code-block:: Lua + + cacheMisses = getStat("cache-misses") + +Please be aware that retrieving statistics is a relatively costly operation, and as such should for example not be done for every query. + + diff --git a/pdns/recursordist/docs/manpages/pdns_recursor.rst b/pdns/recursordist/docs/manpages/pdns_recursor.rst new file mode 100644 index 0000000000..21a6db674b --- /dev/null +++ b/pdns/recursordist/docs/manpages/pdns_recursor.rst @@ -0,0 +1,125 @@ +pdns_server manual page +======================= + +Synopsis +-------- +**pdns_recursor** [*OPTION*]... + +Description +----------- +:program:`pdns_recursor` is a high performance, simple and secure recursing +nameserver. It currently powers hundreds of millions internet connections. + +The recursor is configured via a configuration file, but each item in +that file can be overridden on the command line. + +This manpage lists the core set of features needed to get the PowerDNS Recursor +working, for full and up to date details head to ``_. + +Examples +-------- +To listen on 192.0.2.53 and allow the 192.0.2.0/24 subnet to recurse, and run +as in the background, execute:: + + # pdns_recursor --local-address=192.0.2.53 --allow-from=192.0.2.0/24 --daemon + +To stop the recursor by hand, run:: + + # rec_control quit + +However, the recommended way of starting and stopping the recursor is to use +the init.d script or :manpage:`systemctl(1)`. + +Options +------- +For authoritative listing of options, consult the online documentation +at `` + +--allow-from= + If set, only allow these comma separated *networks*, + with network mask to recurse. For example: 192.0.2.0/24,203.0.113.128/25. +--auth-zones= + Where *authzone* is =. + Serve *zonename* from *filename* authoritatively. For example: + ds9a.nl=/var/zones/ds9a.nl,powerdns.com=/var/zones/powerdns.com. +--chroot= + chroot the process to *directory*. +--client-tcp-timeout= + Timeout in seconds when talking to TCP clients. +--config-dir= + Location of configuration directory (recursor.conf), the default + depends on the SYSCONFDIR option at build-time, which is usually + /etc/powerdns. The default can be found with + ``pdns_recursor --config | grep ' config-dir='``. +--daemon + Operate as a daemon. +--delegation-only + Which domains we only accept delegations from (a Verisign special). +--entropy-source= + Read new entropy from *file*, defaults to /dev/urandom. +--export-etc-hosts + If set, this flag will export the hostnames and IP addresses + mentioned in /etc/hosts. +--forward-zones= + Where *forwardzone* is =
. + Queries for *zonename* will be forwarded to *address*. *address* + should be an IP address, not a hostname (to prevent chicken and egg + problems). Example: forward-zones= ds9a.nl=213.244.168.210, + powerdns.com=127.0.0.1. +--forward-zones-file= + Similar to *--forward-zones*, but read the options from *filename*. + *filename* should contain one zone per line, like: + ds9a.nl=213.244.168.210. +--help + Show a summary of options. +--hint-file= + Load root hints from this *filename* +--local-address=
+ Listen on *address*, separated by spaces or commas. +--local-port= + Listen on *port*. +--log-common-errors + If we should log rather common errors. +--max-cache-entries= + Maximum number of entries in the main cache. +--max-negative-ttl= + maximum number of seconds to keep a negative cached entry in memory. +--max-tcp-clients= + Maximum number of simultaneous TCP clients. +--max-tcp-per-client= + If set, maximum number of TCP sessions per client (IP address). +--query-local-address=
+ Use *address* as Source IP address when sending queries. +--query-local-address6=
+ Send out local IPv6 queries from *address*. Disabled by default, + which also disables outgoing IPv6 support. A useful setting is + '::0'. +--quiet + Suppress logging of questions and answers. +--server-id= + Return *text* WHen queried for 'server.id' TXT, defaults to + hostname. +--serve-rfc1918 + On by default, this makes the server authoritatively aware of: + 10.in-addr.arpa, 168.192.in-addr.arpa and 16-31.172.in-addr.arpa, + which saves load on the AS112 servers. Individual parts of these + zones can still be loaded or forwarded. +--setgid= + If set, change group id to *gid* for more security. +--setuid= + If set, change user id to *uid* for more security. +--single-socket + If set, only use a single socket for outgoing queries. +--socket-dir= + The controlsocket will live in *directory*. +--spoof-nearmiss-max= + If non-zero, assume spoofing after this many near misses. +--trace + if we should output heaps of logging. +--version-string= + *text* WILL be reported on version.pdns or version.bind queries. + +See also +-------- +:manpage:`rec_control(1)` +:manpage:`systemctl(1)` diff --git a/pdns/recursordist/docs/manpages/rec_control.rst b/pdns/recursordist/docs/manpages/rec_control.rst new file mode 100644 index 0000000000..c0e5303875 --- /dev/null +++ b/pdns/recursordist/docs/manpages/rec_control.rst @@ -0,0 +1,220 @@ +rec_control manual page +======================= + +Synopsys +-------- + +**rec_control** [*OPTION*]... *COMMAND* [*COMMAND-OPTION*]... + +Description +----------- + +:program:`rec_control` allows the operator to query and control a running +instance of the PowerDNS Recursor. + +:program:`rec_control` talks to the recursor via a the 'controlsocket'. Which +is usually located in ``/var/run`` . The *--socket-dir* or the *--config-dir* +and *--config-name* switches control to which process :program:`rec_control` +connects. + +Examples +-------- +To see if the Recursor is alive, run:: + + # rec_control ping + +To stop the recursor by hand, run:: + + # rec_control quit + +To dump the cache to disk, execute:: + + # rec_control dump-cache /tmp/the-cache + +Options +------- +--help provide this helpful message. +--config-dir= Directory where the recursor.conf lives. +--config-name= Name of the virtual configuration. +--socket-dir= Where the controlsocket will live, please + use **--config-dir** instead. +--socket-pid= When running in SMP mode, pid of **pdns_recursor** to + control. +--timeout= Number of seconds to wait for the remote PowerDNS + Recursor to respond. Set to 0 for infinite. + +Commands +-------- +add-nta *DOMAIN* [*REASON*] + Add a Negative Trust Anchor for *DOMAIN*, suffixed optionally with + *REASON*. + +add-ta *DOMAIN* *DSRECORD* + Add a Trust Anchor for *DOMAIN* with DS record data *DSRECORD*. This adds + the new Trust Anchor to the existing set of Trust Anchors for *DOMAIN*. + +current-queries + Shows the currently active queries. + +clear-nta *DOMAIN*... + Remove Negative Trust Anchor for one or more *DOMAIN*\ s. Set domain to + '*' to remove all NTA's. + +clear-ta [*DOMAIN*]... + Remove Trust Anchor for one or more *DOMAIN*\ s. Note that removing the + root trust anchor is not possible. + +dump-cache *FILENAME* + Dumps the entire cache to *FILENAME*. This file should not exist already, + PowerDNS will refuse to overwrite it. While dumping, the recursor will not + answer questions. + + Typical PowerDNS Recursors run multiple threads, therefore you'll see + duplicate, different entries for the same domains. The negative cache is + also dumped to the same file. The per-thread positive and negative cache + dumps are separated with an appropriate comment. + +dump-edns *FILENAME* + Dumps the EDNS status to the filename mentioned. This file should not exist + already, PowerDNS will refuse to overwrite it. While dumping, the recursor + will not answer questions. + +dump-nsspeeds *FILENAME* + Dumps the nameserver speed statistics to the *FILENAME* mentioned. This + file should not exist already, PowerDNS will refuse to overwrite it. While + dumping, the recursor will not answer questions. Statistics are kept per + thread, and the dumps end up in the same file. + +get *STATISTIC* [*STATISTIC*]... + Retrieve a statistic. For items that can be queried, see + :doc:`../metrics` + +get-all + Retrieve all known statistics. + +get-ntas + Get a list of the currently configured Negative Trust Anchors. + +get-tas + Get a list of the currently configured Trust Anchors. + +get-parameter *KEY* [*KEY*]... + Retrieves the specified configuration parameter(s). + +get-qtypelist + Retrieves QType statistics. Queries from cache aren't being counted yet. + +help + Shows a list of supported commands understood by the running + :program:`pdns_recursor` + +ping + Check if server is alive. + +quit + Request shutdown of the recursor. + +quit-nicely + Request nice shutdown of the recursor. + +reload-acls + Reloads ACLs. + +reload-lua-script [*FILENAME*] + (Re)loads Lua script *FILENAME*. If *FILENAME* is empty, attempt to reload + the currently loaded script. This replaces the script currently loaded. + +reload-lua-config [*FILENAME*] + (Re)loads Lua configuration *FILENAME*. If *FILENAME* is empty, attempt + to reload the currently loaded file. Note that *FILENAME* will be fully + executed, any settings changed at runtime that are not modified in this + file, will still be active. Reloading RPZ, especially by AXFR, can take + some time; during which the recursor will not answer questions. + +reload-zones + Reload authoritative and forward zones. Retains current configuration in + case of errors. + +set-carbon-server *CARBON SERVER* [*CARBON OURNAME*] + Set the carbon-server setting to *CARBON SERVER*. If *CARBON OURNAME* is + not empty, also set the carbon-ourname setting to *CARBON OURNAME*. + +set-dnssec-log-bogus *SETTING* + Set dnssec-log-bogus setting to *SETTING*. Set to 'on' or 'yes' to log + DNSSEC validation failures and to 'no' or 'off' to disable logging these + failures. + +set-minimum-ttl *NUM* + Set minimum-ttl-override to *NUM*. + +top-queries + Shows the top-20 queries. Statistics are over the last + 'stats-ringbuffer-entries' queries. + +top-pub-queries + Shows the top-20 queries grouped by public suffix list. Statistics are over + the last 'stats-ringbuffer-entries' queries. + +top-largeanswer-remotes + Shows the top-20 remote hosts causing large answers. Statistics are over + the last 'stats-ringbuffer-entries' queries. + +top-remotes + Shows the top-20 most active remote hosts. Statistics are over the last + 'stats-ringbuffer-entries' queries. + +top-servfail-queries + Shows the top-20 queries causing servfail responses. Statistics are over + the last 'stats-ringbuffer-entries' queries. + +top-pub-servfail-queries + Shows the top-20 queries causing servfail responses grouped by public + suffix list. Statistics are over the last 'stats-ringbuffer-entries' + queries. + +top-servfail-remotes + Shows the top-20 most active remote hosts causing servfail responses. + Statistics are over the last 'stats-ringbuffer-entries' queries. + +trace-regex *REGEX* + Emit resolution trace for matching queries. Empty regex to disable trace. + + Queries matching this regular expression will generate voluminous tracing + output. Be aware that matches from the packet cache will still not generate + tracing. To unset the regex, pass **trace-regex** without a new regex. + + The regular expression is matched against domain queries terminated with a + '.'. For example the regex 'powerdns\.com$' will not match a query for + 'www.powerdns.com', since the attempted match will be with + 'www.powerdns.com.'. + + In addition, since this is a regular expression, to exclusively match + queries for 'www.powerdns.com', one should escape the dots: + '^www\.powerdns\.com\.$'. + + Multiple matches can be chained with the '|' operator. For example, to + match all queries for Dutch (.nl) and German (.de) domain names, use: + '\.nl\.$|\.de\.$'. + +unload-lua-script + Unloads Lua script if one was loaded. + +version + Report running version. + +wipe-cache *DOMAIN* [*DOMAIN*] [...] + Wipe entries for *DOMAIN* (exact name match) from the cache. This is useful + if, for example, an important server has a new IP address, but the TTL has + not yet expired. Multiple domain names can be passed. + *DOMAIN* can be suffixed with a '$'. to delete the whole tree from the + cache. i.e. 'powerdns.com$' will remove all cached entries under and + including the powerdns.com name. + + **Note**: this command also wipes the negative cache. + + **Warning**: Don't just wipe "www.somedomain.com", its NS records or CNAME + target may still be undesired, so wipe "somedomain.com" as well. + +See also +-------- +:manpage:`pdns_recursor(1)` diff --git a/pdns/recursordist/docs/metrics.rst b/pdns/recursordist/docs/metrics.rst new file mode 100644 index 0000000000..0d7e930432 --- /dev/null +++ b/pdns/recursordist/docs/metrics.rst @@ -0,0 +1,433 @@ +Metrics and Statistics +====================== + +The PowerDNS Recursor collects many statistics about itself. + +Regular Statistics Log +---------------------- +Every half hour or so (configurable with :ref:`setting-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:: + + Feb 10 14:16:03 stats: 125784 questions, 13971 cache entries, 309 negative entries, 84% cache hits, outpacket/query ratio 37%, 12% throttled + +This means that there are 13791 different names cached, which each may have multiple records attached to them. +There are 309 items in the negative cache, items of which it is known that don't exist and won't do so for the near future. +84% of incoming questions could be answered without any additional queries going out to the net. + +The outpacket/query ratio means that on average, 0.37 packets were needed to answer a question. +Initially this ratio may be well over 100% as additional queries may be needed to actually recurse the DNS and figure out the addresses of nameservers. + +Finally, 12% of queries were not performed because identical queries had gone out previously, saving load on servers worldwide. + +.. _metricscarbon: + +Sending metrics to Graphite/Metronome over Carbon +------------------------------------------------- +For carbon/graphite/metronome, we use the following namespace. +Everything starts with 'pdns.', which is then followed by the local hostname. +Thirdly, we add 'recursor' to signify the daemon generating the metrics. +This is then rounded off with the actual name of the metric. As an example: 'pdns.ns1.recursor.questions'. + +Care has been taken to make the sending of statistics as unobtrusive as possible, the daemons will not be hindered by an unreachable carbon server, timeouts or connection refused situations. + +To benefit from our carbon/graphite support, either install Graphite, or use our own lightweight statistics daemon, Metronome, currently available on `GitHub `_. + +To enable sending metrics, set :ref:`setting-carbon-server`, possibly :ref:`setting-carbon-interval` and possibly :ref:`setting-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. + As PowerDNS assumes you know what you are doing if you override your hostname. + +Sending metrics over SNMP +------------------------- +.. versionadded:: 4.1.0 + +The recursor can export statistics over SNMP and send traps from :doc:`Lua `, provided support is compiled into the Recursor and :ref:`setting-snmp-agent` set. + +Getting Metrics from the Recursor +--------------------------------- + +Should Carbon not be the preferred way of receiving metric, several other techniques can be employed to retrieve metrics. + +Using the Webserver +^^^^^^^^^^^^^^^^^^^ +The :doc:`API ` exposes a statistics endpoint at :http:get:`/api/v1/servers/:server_id/statistics`. +This endpoint exports all statistics in a single JSON document. + +Using ``rec_control`` +^^^^^^^^^^^^^^^^^^^^^ +Metrics can also be gathered on the system itself by invoking :doc:`rec_control `:: + + rec_control get-all + +Single statistics can also be retrieved with the ``get`` command, e.g.:: + + rec_control get all-outqueries + +External programs can use this technique to scrape metrics. + +.. _metricnames: + +Gathered Information +-------------------- + +These statistics are gathered. + +It should be noted that answers0-1 + answers1-10 + answers10-100 + answers100-1000 + answers-slow + packetcache-hits + over-capacity-drops + policy-drops = questions. + +Also note that unauthorized-tcp and unauthorized-udp packets do not end up in the 'questions' count. + +all-outqueries +^^^^^^^^^^^^^^ +counts the number of outgoing UDP queries since starting + +answers-slow +^^^^^^^^^^^^ +counts the number of queries answered after 1 second + +answers0-1 +^^^^^^^^^^ +counts the number of queries answered within 1 millisecond + +answers1-10 +^^^^^^^^^^^ +counts the number of queries answered within 10 milliseconds + +answers10-100 +^^^^^^^^^^^^^ +counts the number of queries answered within 100 milliseconds + +answers100-1000 +^^^^^^^^^^^^^^^ +counts the number of queries answered within 1 second + +auth4-answers-slow +^^^^^^^^^^^^^^^^^^ +counts the number of queries answered by auth4s after 1 second (4.0) + +auth4-answers0-1 +^^^^^^^^^^^^^^^^ +counts the number of queries answered by auth4s within 1 millisecond (4.0) + +auth4-answers1-10 +^^^^^^^^^^^^^^^^^ +counts the number of queries answered by auth4s within 10 milliseconds (4.0) + +auth4-answers10-100 +^^^^^^^^^^^^^^^^^^^ +counts the number of queries answered by auth4s within 100 milliseconds (4.0) + +auth4-answers100-1000 +^^^^^^^^^^^^^^^^^^^^^ +counts the number of queries answered by auth4s within 1 second (4.0) + +auth6-answers-slow +^^^^^^^^^^^^^^^^^^ +counts the number of queries answered by auth6s after 1 second (4.0) + +auth6-answers0-1 +^^^^^^^^^^^^^^^^ +counts the number of queries answered by auth6s within 1 millisecond (4.0) + +auth6-answers1-10 +^^^^^^^^^^^^^^^^^ +counts the number of queries answered by auth6s within 10 milliseconds (4.0) + +auth6-answers10-100 +^^^^^^^^^^^^^^^^^^^ +counts the number of queries answered by auth6s within 100 milliseconds (4.0) + +auth6-answers100-1000 +^^^^^^^^^^^^^^^^^^^^^ +counts the number of queries answered by auth6s within 1 second (4.0) + +cache-bytes +^^^^^^^^^^^ +size of the cache in bytes + +cache-entries +^^^^^^^^^^^^^ +shows the number of entries in the cache + +cache-hits +^^^^^^^^^^ +counts the number of cache hits since starting, this does **not** include hits that got answered from the packet-cache + +cache-misses +^^^^^^^^^^^^ +counts the number of cache misses since starting + +case-mismatches +^^^^^^^^^^^^^^^ +counts the number of mismatches in character case since starting + +chain-resends +^^^^^^^^^^^^^ +number of queries chained to existing outstanding query + +client-parse-errors +^^^^^^^^^^^^^^^^^^^ +counts number of client packets that could not be parsed + +concurrent-queries +^^^^^^^^^^^^^^^^^^ +shows the number of MThreads currently running + +dlg-only-drops +^^^^^^^^^^^^^^ +number of records dropped because of :ref:`setting-delegation-only` setting + +dnssec-queries +^^^^^^^^^^^^^^ +number of queries received with the DO bit set + +dnssec-result-bogus +^^^^^^^^^^^^^^^^^^^ +number of DNSSEC validations that had the Bogus state + +dnssec-result-indeterminate +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +number of DNSSEC validations that had the Indeterminate state + +dnssec-result-insecure +^^^^^^^^^^^^^^^^^^^^^^ +number of DNSSEC validations that had the Insecure state + +dnssec-result-nta +^^^^^^^^^^^^^^^^^ +number of DNSSEC validations that had the NTA (negative trust anchor) state + +dnssec-result-secure +^^^^^^^^^^^^^^^^^^^^ +number of DNSSEC validations that had the Secure state + +dnssec-validations +^^^^^^^^^^^^^^^^^^ +number of DNSSEC validations performed + +dont-outqueries +^^^^^^^^^^^^^^^ +number of outgoing queries dropped because of :ref:`setting-dont-query` setting (since 3.3) + +ecs-queries +^^^^^^^^^^^ +number of outgoing queries adorned with an EDNS Client Subnet option (since 4.1) + +ecs-responses +^^^^^^^^^^^^^ +number of responses received from authoritative servers with an EDNS Client Subnet option we used (since 4.1) + +edns-ping-matches +^^^^^^^^^^^^^^^^^ +number of servers that sent a valid EDNS PING response + +edns-ping-mismatches +^^^^^^^^^^^^^^^^^^^^ +number of servers that sent an invalid EDNS PING response + +failed-host-entries +^^^^^^^^^^^^^^^^^^^ +number of servers that failed to resolve + +ignored-packets +^^^^^^^^^^^^^^^ +counts the number of non-query packets received on server sockets that should only get query packets + +ipv6-outqueries +^^^^^^^^^^^^^^^ +number of outgoing queries over IPv6 + +ipv6-questions +^^^^^^^^^^^^^^ +counts all end-user initiated queries with the RD bit set, received over IPv6 UDP + +malloc-bytes +^^^^^^^^^^^^ +returns the number of bytes allocated by the process (broken, always returns 0) + +max-mthread-stack +^^^^^^^^^^^^^^^^^ +maximum amount of thread stack ever used + +negcache-entries +^^^^^^^^^^^^^^^^ +shows the number of entries in the negative answer cache + +no-packet-error +^^^^^^^^^^^^^^^ +number of erroneous received packets + +noedns-outqueries +^^^^^^^^^^^^^^^^^ +number of queries sent out without EDNS + +noerror-answers +^^^^^^^^^^^^^^^ +counts the number of times it answered NOERROR since starting + +noping-outqueries +^^^^^^^^^^^^^^^^^ +number of queries sent out without ENDS PING + +nsset-invalidations +^^^^^^^^^^^^^^^^^^^ +number of times an nsset was dropped because it no longer worked + +nsspeeds-entries +^^^^^^^^^^^^^^^^ +shows the number of entries in the NS speeds map + +nxdomain-answers +^^^^^^^^^^^^^^^^ +counts the number of times it answered NXDOMAIN since starting + +outgoing-timeouts +^^^^^^^^^^^^^^^^^ +counts the number of timeouts on outgoing UDP queries since starting + +outgoing4-timeouts +^^^^^^^^^^^^^^^^^^ +counts the number of timeouts on outgoing UDP IPv4 queries since starting (since 4.0) + +outgoing6-timeouts +^^^^^^^^^^^^^^^^^^ +counts the number of timeouts on outgoing UDP IPv6 queries since starting (since 4.0) + +over-capacity-drops +^^^^^^^^^^^^^^^^^^^ +questions dropped because over maximum concurrent query limit (since 3.2) + +packetcache-bytes +^^^^^^^^^^^^^^^^^ +size of the packet cache in bytes (since 3.3.1) + +packetcache-entries +^^^^^^^^^^^^^^^^^^^ +size of packet cache (since 3.2) + +packetcache-hits +^^^^^^^^^^^^^^^^ +packet cache hits (since 3.2) + +packetcache-misses +^^^^^^^^^^^^^^^^^^ +packet cache misses (since 3.2) + +policy-drops +^^^^^^^^^^^^ +packets dropped because of (Lua) policy decision + +policy-result-noaction +^^^^^^^^^^^^^^^^^^^^^^ +packets that were not actioned upon by the RPZ/filter engine + +policy-result-drop +^^^^^^^^^^^^^^^^^^ +packets that were dropped by the RPZ/filter engine + +policy-result-nxdomain +^^^^^^^^^^^^^^^^^^^^^^ +packets that were replied to with NXDOMAIN by the RPZ/filter engine + +policy-result-nodata +^^^^^^^^^^^^^^^^^^^^ +packets that were replied to with no data by the RPZ/filter engine + +policy-result-truncate +^^^^^^^^^^^^^^^^^^^^^^ +packets that were forced to TCP by the RPZ/filter engine + +policy-result-custom +^^^^^^^^^^^^^^^^^^^^ +packets that were sent a custom answer by the RPZ/filter engine + +qa-latency +^^^^^^^^^^ +shows the current latency average, in microseconds, exponentially weighted over past 'latency-statistic-size' packets + +questions +^^^^^^^^^ +counts all end-user initiated queries with the RD bit set + +resource-limits +^^^^^^^^^^^^^^^ +counts number of queries that could not be performed because of resource limits + +security-status +^^^^^^^^^^^^^^^ +security status based on :ref:`securitypolling` + +server-parse-errors +^^^^^^^^^^^^^^^^^^^ +counts number of server replied packets that could not be parsed + +servfail-answers +^^^^^^^^^^^^^^^^ +counts the number of times it answered SERVFAIL since starting + +spoof-prevents +^^^^^^^^^^^^^^ +number of times PowerDNS considered itself spoofed, and dropped the data + +sys-msec +^^^^^^^^ +number of CPU milliseconds spent in 'system' mode + +tcp-client-overflow +^^^^^^^^^^^^^^^^^^^ +number of times an IP address was denied TCP access because it already had too many connections + +tcp-clients +^^^^^^^^^^^ +counts the number of currently active TCP/IP clients + +tcp-outqueries +^^^^^^^^^^^^^^ +counts the number of outgoing TCP queries since starting + +tcp-questions +^^^^^^^^^^^^^ +counts all incoming TCP queries (since starting) + +throttle-entries +^^^^^^^^^^^^^^^^ +shows the number of entries in the throttle map + +throttled-out +^^^^^^^^^^^^^ +counts the number of throttled outgoing UDP queries since starting + +throttled-outqueries +^^^^^^^^^^^^^^^^^^^^ +idem to throttled-out + +too-old-drops +^^^^^^^^^^^^^ +questions dropped that were too old + +unauthorized-tcp +^^^^^^^^^^^^^^^^ +number of TCP questions denied because of allow-from restrictions + +unauthorized-udp +^^^^^^^^^^^^^^^^ +number of UDP questions denied because of allow-from restrictions + +unexpected-packets +^^^^^^^^^^^^^^^^^^ +number of answers from remote servers that were unexpected (might point to spoofing) + +unreachables +^^^^^^^^^^^^ +number of times nameservers were unreachable since starting + +uptime +^^^^^^ +number of seconds process has been running (since 3.1.5) + +user-msec +^^^^^^^^^ +number of CPU milliseconds spent in 'user' mode diff --git a/pdns/recursordist/docs/performance.rst b/pdns/recursordist/docs/performance.rst new file mode 100644 index 0000000000..01113395d7 --- /dev/null +++ b/pdns/recursordist/docs/performance.rst @@ -0,0 +1,135 @@ +Performance Guide +================= + +To get the best out of the PowerDNS recursor, which is important if you are doing thousands of queries per second, please consider the following. + +A busy server may need hundreds of file descriptors on startup, and deals with spikes better if it has that many available later on. +Linux by default restricts processes to 1024 file descriptors, which should suffice most of the time, but Solaris has a default limit of 256. +This can be raised using the ``ulimit`` command or via the ``LimitNOFILE`` unit directive when ``systemd`` is used. +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 4 million :ref:`setting-max-cache-entries` per thread, 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 (but values above 8 rarely improve performance). + +Threading and distribution of queries +------------------------------------- + +When running with several threads, you can either ask PowerDNS to start a special thread to dispatch the incoming queries to the workers by setting :ref:`setting-pdns-distributes-queries` to true, or let the worker threads handle the incoming queries themselves. +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, but it might become a bottleneck if the incoming queries rate is too high to be handled by a single thread. + +If :ref:`setting-pdns-distributes-queries` is set to false and either ``SO_REUSEPORT`` support is not available or the :ref:`setting-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 true, 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. + +Performance tips +---------------- + +For best PowerDNS Recursor performance, use a recent version of your operating system, since this generally offers the best event multiplexer implementation available (``kqueue``, ``epoll``, ``ports`` or ``/dev/poll``). + +On AMD/Intel hardware, wherever possible, run a 64-bit binary. This delivers a nearly twofold performance increase. +On UltraSPARC, there is no need to run with 64 bits. + +Consider performing a 'profiled build' by building with ``gprof`` support enabled, running the recursor a bit then feed that info into the next build. +This is good for a 20% performance boost in some cases. + +When running with >3000 queries per second, and running Linux versions prior to 2.6.17 on some motherboards, your computer may spend an inordinate amount of time working around an ACPI bug for each call to gettimeofday. +This is solved by rebooting with ``clock=tsc`` or upgrading to a 2.6.17 kernel. +This is relevant if dmesg shows ``Using pmtmr for high-res timesource``. + +Connection tracking and firewalls +--------------------------------- + +A Recursor under high load puts a severe stress on any stateful (connection tracking) firewall, so much so that the firewall may fail. + +Specifically, many Linux distributions run with a connection tracking firewall configured. +For high load operation (thousands of queries/second), It is advised to either turn off iptables completely, or use the ``NOTRACK`` feature to make sure DNS traffic bypasses the connection tracking. + +Sample Linux command lines would be:: + + ## IPv4 + iptables -t raw -I OUTPUT -p udp --dport 53 -j CT --notrack + iptables -t raw -I OUTPUT -p udp --sport 53 -j CT --notrack + iptables -t raw -I PREROUTING -p udp --dport 53 -j CT --notrack + iptables -t raw -I PREROUTING -p udp --sport 53 -j CT --notrack + iptables -I INPUT -p udp --dport 53 -j ACCEPT + iptables -I INPUT -p udp --sport 53 -j ACCEPT + iptables -I OUTPUT -p udp --dport 53 -j ACCEPT + iptables -I OUTPUT -p udp --sport 53 -j ACCEPT + + ## IPv6 + ip6tables -t raw -I OUTPUT -p udp --dport 53 -j CT --notrack + ip6tables -t raw -I OUTPUT -p udp --sport 53 -j CT --notrack + ip6tables -t raw -I PREROUTING -p udp --sport 53 -j CT --notrack + ip6tables -t raw -I PREROUTING -p udp --dport 53 -j CT --notrack + ip6tables -I INPUT -p udp --dport 53 -j ACCEPT + ip6tables -I INPUT -p udp --sport 53 -j ACCEPT + ip6tables -I OUTPUT -p udp --dport 53 -j ACCEPT + ip6tables -I OUTPUT -p udp --sport 53 -j ACCEPT + +When using FirewallD (Centos 7+ / RedHat 7+ / Fedora 21+), connection tracking can be disabled via direct rules. +The settings can be made permanent by using the ``--permanent`` flag:: + + ## IPv4 + firewall-cmd --direct --add-rule ipv4 raw OUTPUT 0 -p udp --dport 53 -j CT --notrack + firewall-cmd --direct --add-rule ipv4 raw OUTPUT 0 -p udp --sport 53 -j CT --notrack + firewall-cmd --direct --add-rule ipv4 raw PREROUTING 0 -p udp --dport 53 -j CT --notrack + firewall-cmd --direct --add-rule ipv4 raw PREROUTING 0 -p udp --sport 53 -j CT --notrack + firewall-cmd --direct --add-rule ipv4 filter INPUT 0 -p udp --dport 53 -j ACCEPT + firewall-cmd --direct --add-rule ipv4 filter INPUT 0 -p udp --sport 53 -j ACCEPT + firewall-cmd --direct --add-rule ipv4 filter OUTPUT 0 -p udp --dport 53 -j ACCEPT + firewall-cmd --direct --add-rule ipv4 filter OUTPUT 0 -p udp --sport 53 -j ACCEPT + + ## IPv6 + firewall-cmd --direct --add-rule ipv6 raw OUTPUT 0 -p udp --dport 53 -j CT --notrack + firewall-cmd --direct --add-rule ipv6 raw OUTPUT 0 -p udp --sport 53 -j CT --notrack + firewall-cmd --direct --add-rule ipv6 raw PREROUTING 0 -p udp --dport 53 -j CT --notrack + firewall-cmd --direct --add-rule ipv6 raw PREROUTING 0 -p udp --sport 53 -j CT --notrack + firewall-cmd --direct --add-rule ipv6 filter INPUT 0 -p udp --dport 53 -j ACCEPT + firewall-cmd --direct --add-rule ipv6 filter INPUT 0 -p udp --sport 53 -j ACCEPT + firewall-cmd --direct --add-rule ipv6 filter OUTPUT 0 -p udp --dport 53 -j ACCEPT + firewall-cmd --direct --add-rule ipv6 filter OUTPUT 0 -p udp --sport 53 -j ACCEPT + +Following the instructions above, you should be able to attain very high query rates. + +Recursor Caches +--------------- + +The PowerDNS Recursor contains a number of caches, or information stores: + +Nameserver speeds cache +^^^^^^^^^^^^^^^^^^^^^^^ + +The "NSSpeeds" cache contains the average latency to all remote authoritative servers. + +Negative cache +^^^^^^^^^^^^^^ + +The "Negcache" contains all domains known not to exist, or record types not to exist for a domain. + +Recursor Cache +^^^^^^^^^^^^^^ + +The Recursor Cache contains all DNS knowledge gathered over time. +This is also knows as a "record cache". + +Packet Cache +^^^^^^^^^^^^ + +The Packet Cache contains previous answers sent to clients. +If a question comes in that matches a previous answer, this is sent back directly. + +The Packet Cache is consulted first, immediately after receiving a packet. +This means that a high hitrate for the Packet Cache automatically lowers the cache hitrate of subsequent caches. + +Measuring performance +--------------------- + +The PowerDNS Recursor exposes many :doc:`metrics ` that can be graphed and monitored. diff --git a/pdns/recursordist/docs/requirements.txt b/pdns/recursordist/docs/requirements.txt new file mode 100644 index 0000000000..3aa0bcdece --- /dev/null +++ b/pdns/recursordist/docs/requirements.txt @@ -0,0 +1,7 @@ +Sphinx>=1.5.0 +git+https://github.com/pieterlexis/sphinx-jsondomain@no-type-links +git+https://github.com/pieterlexis/sphinx-lua@pdns +git+https://github.com/pieterlexis/sphinx-changelog@render-tags +guzzle_sphinx_theme +sphinxcontrib.httpdomain +sphinxcontrib-fulltoc diff --git a/pdns/recursordist/docs/running.rst b/pdns/recursordist/docs/running.rst new file mode 100644 index 0000000000..3c9e322acb --- /dev/null +++ b/pdns/recursordist/docs/running.rst @@ -0,0 +1,96 @@ +Operating the PowerDNS Recursor +=============================== + +.. _logging: + +Logging +------- + +In a production environment, you will want to be able to monitor PowerDNS performance. +Furthermore, PowerDNS can perform a configurable amount of operational logging. + +On modern Linux distributions, the PowerDNS recursor logs to stdout, which is consumed by ``systemd-journald``. +This means that looking into the logs that are produced, `journalctl `_ can be used:: + + # journalctl -u pdns-recursor -n 100 + +Additionally, the Recursor *can* log to syslog on these systems. +Logging to syslog is disabled in the unit file to prevent double logging. +To enable this, create an drop in unit file at ``/etc/systemd/systemd/pdns-recursor.service.d/use-syslog.conf``:: + + [Service] + ExecStart= + ExecStart=/usr/sbin/pdns_recursor --daemon=no --write-pid=no --enable-syslog + +Logging to syslog +^^^^^^^^^^^^^^^^^ +This chapter assumes familiarity with syslog, the unix logging device. +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. +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 ` to 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:: + + local0.info -/var/log/pdns.info + local0.warn -/var/log/pdns.warn + local0.err /var/log/pdns.err + +Where local0.err would store the really important messages. +For performance and disk space reasons, it is advised to audit your ``syslog.conf`` for statements also logging PowerDNS activities. +Many ``syslog.conf``\ s have a ``*.*`` statement to ``/var/log/syslog``, which you may want to remove. + +For performance reasons, be especially certain that no large amounts of synchronous logging take place. +Under Linux, this is indicated by file names not starting with a ``-`` - indicating a synchronous log, which hurts performance. + +Be aware that syslog by default logs messages at the configured priority and higher! +To log only info messages, use ``local0.=info`` + +Cache Management +---------------- +Sometimes a domain fails to resolve due to an error on the domain owner's end, or records for your own domain have updated and you want your users to immediatly see them without waiting for the TTL to expire. +The :doc:`rec_control ` tool can be used to selectively wipe the cache. + +To wipe all records for the exact name 'www.example.com':: + + rec_control wipe-cache www.example.com + +Whole subtrees can we wiped as well, to wipe all cache entries for 'example.com' and everything below it, suffix the name with a '$':: + + rec_control wipe-cache example.com$ + +.. note:: + + When wiping cache entries, matching entries in *all* caches (packet cache, recursor cache, negative cache) are removed. + +When debugging resolving issues, it can be advantagious to have a dump of all the cache entries. +:doc:`rec_control ` can write the caches of all threads to a file:: + + rec_control dump-cache /tmp/cache + +Tracing Queries +--------------- +To investigate failures with resolving resolving certain domain names, the PowerDNS Recursor features a "tracing" infrastructure. +This infrastructure will log every step the 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. + +.. warning:: + + Enabling tracing for all queries on a system with a high query rate can severely performance. + +Tracing can also be enabled at runtime, without restarting the Recursor, for specific domains. +These specific domains can be specified as a regular expression. +This can be done using :doc:`rec_control trace-regex `:: + + rec_control trace-regex '.*\.example.com\.$' + +Will enable tracing for any query *in* the example.com domain (but not example.com itself). diff --git a/pdns/recursordist/docs/security-advisories/index.rst b/pdns/recursordist/docs/security-advisories/index.rst new file mode 100644 index 0000000000..81fb12d58d --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/index.rst @@ -0,0 +1,14 @@ +Security Advisories +=================== +All security advisories for the PowerDNS Recursor are listed here. + +.. toctree:: + :maxdepth: 1 + :glob: + :reversed: + + powerdns-advisory* + +.. include:: older-than-3.0.rst + + diff --git a/pdns/recursordist/docs/security-advisories/older-than-3.0.rst b/pdns/recursordist/docs/security-advisories/older-than-3.0.rst new file mode 120000 index 0000000000..1b4232284a --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/older-than-3.0.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/older-than-3.0.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security-advisories/powerdns-advisory-2006-01.rst b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2006-01.rst new file mode 120000 index 0000000000..76dedd9036 --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2006-01.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/powerdns-advisory-2006-01.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security-advisories/powerdns-advisory-2006-02.rst b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2006-02.rst new file mode 120000 index 0000000000..fa56ea60b8 --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2006-02.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/powerdns-advisory-2006-02.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security-advisories/powerdns-advisory-2008-01.rst b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2008-01.rst new file mode 120000 index 0000000000..004353e79f --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2008-01.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/powerdns-advisory-2008-01.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security-advisories/powerdns-advisory-2010-01.rst b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2010-01.rst new file mode 120000 index 0000000000..80b65b3e49 --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2010-01.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/powerdns-advisory-2010-01.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security-advisories/powerdns-advisory-2010-02.rst b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2010-02.rst new file mode 120000 index 0000000000..48234c9221 --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2010-02.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/powerdns-advisory-2010-02.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security-advisories/powerdns-advisory-2014-01.rst b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2014-01.rst new file mode 120000 index 0000000000..fbbe4bcb32 --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2014-01.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/powerdns-advisory-2014-01.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security-advisories/powerdns-advisory-2014-02.rst b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2014-02.rst new file mode 120000 index 0000000000..585aed6784 --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2014-02.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/powerdns-advisory-2014-02.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security-advisories/powerdns-advisory-2015-01.rst b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2015-01.rst new file mode 120000 index 0000000000..4512302f36 --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2015-01.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/powerdns-advisory-2015-01.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security-advisories/powerdns-advisory-2016-02.rst b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2016-02.rst new file mode 120000 index 0000000000..6f11211100 --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2016-02.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/powerdns-advisory-2016-02.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security-advisories/powerdns-advisory-2016-04.rst b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2016-04.rst new file mode 120000 index 0000000000..ca274c4425 --- /dev/null +++ b/pdns/recursordist/docs/security-advisories/powerdns-advisory-2016-04.rst @@ -0,0 +1 @@ +../../../../docs/security-advisories/powerdns-advisory-2016-04.rst \ No newline at end of file diff --git a/pdns/recursordist/docs/security.rst b/pdns/recursordist/docs/security.rst new file mode 100644 index 0000000000..a6c80527c6 --- /dev/null +++ b/pdns/recursordist/docs/security.rst @@ -0,0 +1,39 @@ +Security of the PowerDNS Recursor +================================= + +For Security Advisories, see the :doc:`dedicated page `. + +.. _securitypolicy: + +.. include:: common/security-policy.rst + +Anti-spoofing +------------- + +The PowerDNS Recursor uses a fresh UDP source port for each outgoing query, making spoofing around 64000 times harder. +This raises the bar from 'easily doable given some time' to 'very hard'. +Under some circumstances, 'some time' has been measured at 2 seconds. +This technique was first used by ``dnscache`` by Dan J. Bernstein and is standardized in :rfc:`5452` + +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`. + +Throttling +---------- + +PowerDNS implements a very simple but effective nameserver. +Care has been taken not to overload remote servers in case of overly active clients. + +This is implemented using the 'throttle'. +This accounts all recent traffic and prevents queries that have been sent out recently from going out again. + +There are three levels of throttling. + +- If a remote server indicates that it is lame for a zone, the exact question won't be repeated in the next 60 seconds. +- After 4 ServFail responses in 60 seconds, the query gets throttled too. +- 5 timeouts in 20 seconds also lead to query suppression. + +.. _securitypolling: + +.. include:: common/secpoll.rst diff --git a/pdns/recursordist/docs/settings.rst b/pdns/recursordist/docs/settings.rst new file mode 100644 index 0000000000..c25b4f899d --- /dev/null +++ b/pdns/recursordist/docs/settings.rst @@ -0,0 +1,1080 @@ +PowerDNS Recursor Settings +========================== +Each setting can appear on the command line, prefixed by '--', or in the configuration file. +The command line overrides the configuration file. + +**Note**: Settings marked as 'Boolean' can either be set to an empty value, which means on, or to 'no' or 'off' which means off. +Anything else means on. + +As an example: + + - ``serve-rfc1918`` on its own means: do serve those zones. + - ``serve-rfc1918=off`` or ``serve-rfc1918=no`` means: do not serve those zones. + - Anything else means: do serve those zones. + +.. _setting-aaaa-additional-processing: + +``aaaa-additional-processing`` +------------------------------ +- Boolean +- Default: No + +If turned on, the recursor will attempt to add AAAA IPv6 records to questions for MX records and NS records. +Can be quite slow as absence of these records in earlier answers does not guarantee their non-existence. +Can double the amount of queries needed. + +.. _setting-allow-from: + +``allow-from`` +-------------- +- IP ranges, separated by commas +- Default: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 + +Netmasks (both IPv4 and IPv6) that are allowed to use the server. +The default allows access only from :rfc:`1918` private IP addresses. +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. + +.. _setting-allow-from-file: + +``allow-from-file`` +------------------- +- Path + +Like `allow-from`_, except reading from file. +Overrides the `allow-from`_ setting. To use this feature, supply one netmask per line, with optional comments preceded by a "#". + +.. _setting-any-to-tcp: + +``any-to-tcp`` +-------------- +- Boolean +- Default: no + +Answer questions for the ANY type on UDP with a truncated packet that refers the remote server to TCP. +Useful for mitigating ANY reflection attacks. + +.. _setting-api-config-dir: + +``api-config-dir`` +------------------ +.. versionadded:: 4.0.0 + +- Path +- Default: unset + +Directory where the REST API stores its configuration and zones. + +.. _setting-api-key: + +``api-key`` +----------- +.. versionadded:: 4.0.0 + +- String +- Default: unset + +Static pre-shared authentication key for access to the REST API. + +.. _setting-api-readonly: + +``api-readonly`` +---------------- +.. versionadded:: 4.0.0 + +- Boolean +- Default: no + +Disallow data modification through the REST API when set. + +.. _setting-api-logfile: + +``api-logfile`` +--------------- +.. versionadded:: 4.0.0 + +- Path +- Default: unset + +Location of the server logfile (used by the REST API). + +.. _setting-auth-can-lower-ttl: + +``auth-can-lower-ttl`` +---------------------- +- Boolean +- Default: no + +Authoritative zones can transmit a TTL value that is lower than that specified in the parent zone. +This is called a 'delegation inconsistency'. +To follow :rfc:`RFC 2181 section 5.2<2181#section-5.2>` and :rfc:`5.4 <2181#section-5.4>` to the letter, enable this feature. +This will mean a slight deterioration of performance, and it will not solve any problems, but does make the recursor more standards compliant. +Not recommended unless you have to tick an 'RFC 2181 compliant' box. + +.. _setting-auth-zones: + +``auth-zones`` +-------------- +- Comma separated list of 'zonename=filename' pairs + +Zones read from these files (in BIND format) are served authoritatively. +DNSSEC is not supported. Example: + +.. code-block:: none + + auth-zones=example.org=/var/zones/example.org, powerdns.com=/var/zones/powerdns.com + +.. _setting-carbon-interval: + +``carbon-interval`` +------------------- +- Integer +- Default: 30 + +If sending carbon updates, this is the interval between them in seconds. +See :doc:`metrics`. + +.. _setting-carbon-ourname: + +``carbon-ourname`` +------------------ +- String + +If sending carbon updates, if set, this will override our hostname. +Be careful not to include any dots in this setting, unless you know what you are doing. +See :ref:`metricscarbon`. + +.. _setting-carbon-server: + +``carbon-server`` +----------------- +- IP address + +If set to an IP or IPv6 address, will send all available metrics to this server via the carbon protocol, which is used by graphite and metronome. +You may specify an alternate port by appending :port, for example: ``127.0.0.1:2004``. +See :doc:`metrics`. + +.. _setting-chroot: + +``chroot`` +---------- +- Path to a Directory + +If set, chroot to this directory for more security. +See :doc:`security` + +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 `config-dir`_) set in the configuration are relative to the new root. + +When using ``chroot`` and the API (`webserver`_), `api-readonly`_ **must** be set and `api-config-dir`_ unset. + +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). + +.. _setting-client-tcp-timeout: + +``client-tcp-timeout`` +---------------------- +- Integer +- Default: 2 + +Time to wait for data from TCP clients. + +.. _setting-config-dir: + +``config-dir`` +-------------- +- Path + +Location of configuration directory (``recursor.conf``). +Usually ``/etc/powerdns``, but this depends on ``SYSCONFDIR`` during compile-time. + +.. _setting-config-name: + +``config-name`` +--------------- +- String +- Default: unset + +When running multiple recursors on the same server, read settings from :file:`recursor-{name}.conf`, this will also rename the binary image. + +.. _setting-daemon: + +``daemon`` +---------- +- Boolean +- Default: no + +.. versionchanged:: 4.0.0 + + Default is now "no", was "yes" before. + +Operate in the background. + +.. _setting-delegation-only: + +``delegation-only`` +------------------- +- Domains, comma separated + +Which domains we only accept delegations from (a Verisign special). + +.. _setting-disable-packetcache: + +``disable-packetcache`` +----------------------- +- Boolean +- Default: no + +Turn off the packet cache. Useful when running with Lua scripts that can +not be cached. + +.. _setting-disable-syslog: + +``disable-syslog`` +------------------ +- Boolean +- Default: no + +Do not log to syslog, only to stdout. +Use this setting when running inside a supervisor that handles logging (like systemd). +**Note**: do not use this setting in combination with `daemon`_ as all logging will disappear. + +.. _setting-dnssec: + +``dnssec`` +---------- +.. versionadded:: 4.0.0 + +- One of ``off``, ``process-no-validate``, ``process``, ``log-fail``, ``validate``, String +- Default: ``process-no-validate`` + +Set the mode for DNSSEC processing: + +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. + +.. _setting-dnssec-log-bogus: + +``dnssec-log-bogus`` +-------------------- +- Boolean +- Default: no + +Log every DNSSEC validation failure. +**Note**: This is not logged per-query but every time records are validated as Bogus. + +.. _setting-dont-query: + +``dont-query`` +-------------- +- Netmasks, comma separated +- 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 + +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 to addresses for zones as configured in any of the settings `forward-zones`_, `forward-zones-file`_ or `forward-zones-recurse`_ are performed regardless of these limitations. + +.. _setting-ecs-ipv4-bits: + +``ecs-ipv4-bits`` +----------------- +.. versionadded:: 4.1.0 + +- Integer +- Default: 24 + +Number of bits of client IPv4 address to pass when sending EDNS Client Subnet address information. + +.. _setting-ecs-ipv6-bits: + +``ecs-ipv6-bits`` +----------------- +.. versionadded:: 4.1.0 + +- Integer +- Default: 56 + +Number of bits of client IPv6 address to pass when sending EDNS Client Subnet address information. + +.. _setting-edns-outgoing-bufsize: + +``edns-outgoing-bufsize`` +------------------------- +- Integer +- Default: 1680 + +This is the value set for the EDNS0 buffer size in outgoing packets. +Lower this if you experience timeouts. + +.. _setting-edns-subnet-whitelist: + +``edns-subnet-whitelist`` +------------------------- +- Comma separated list of domain names and netmasks +- Default: (none) + +List of netmasks and domains that :rfc:`EDNS Client Subnet <7871>` should be enabled for in outgoing queries. +For example, an EDNS Client Subnet option containing the address of the initial requestor 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 and to 56 bits for IPv6, as recommended in the privacy section of RFC 7871. +By default, this option is empty, meaning no EDNS Client Subnet information is sent. + +.. _setting-entropy-source: + +``entropy-source`` +------------------ +- Path +- Default: /dev/urandom + +PowerDNS can read entropy from a (hardware) source. +This is used for generating random numbers which are very hard to predict. +Generally on UNIX platforms, this source will be ``/dev/urandom``, which will always supply random numbers, even if entropy is lacking. +Change to ``/dev/random`` if PowerDNS should block waiting for enough entropy to arrive. + +.. _setting-etc-hosts-file: + +``etc-hosts-file`` +------------------ +- Path +- Default: /etc/hosts + +The path to the /etc/hosts file, or equivalent. +This file can be used to serve data authoritatively using `export-etc-hosts`_. + +.. _setting-export-etc-hosts: + +``export-etc-hosts`` +-------------------- +- Boolean +- Default: no + +If set, this flag will export the host names and IP addresses mentioned in ``/etc/hosts``. + +.. _setting-export-etc-hosts-search-suffix: + +``export-etc-hosts-search-suffix`` +---------------------------------- +- String + +If set, all hostnames in the `export-etc-hosts`_ file are loaded in canonical form, based on this suffix, unless the name contains a '.', in which case the name is unchanged. +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. + +.. _setting-forward-zones: + +``forward-zones`` +----------------- +- 'zonename=IP' pairs, comma separated + +Queries for zones listed here will be forwarded to the IP address listed. i.e. + +.. code-block:: none + + forward-zones=example.org=203.0.113.210, powerdns.com=2001:DB8::BEEF:5 + +Multiple IP addresses can be specified and port numbers other than 53 can be configured: + +.. code-block:: none + + forward-zones=example.org=203.0.113.210:5300;127.0.0.1, powerdns.com=127.0.0.1;198.51.100.10:530;[2001:DB8::1:3]:5300 + +Forwarded queries have the 'recursion desired' bit set to 0, meaning that this setting is intended to forward queries to authoritative servers. + +**IMPORTANT**: When using DNSSEC validation (which is default), forwards to non-delegated (e.g. internal) zones that have a DNSSEC signed parent zone will validate as Bogus. +To prevent this, add a Negative Trust Anchor (NTA) for this zone in the `lua-config-file`_ with ``addNTA("your.zone", "A comment")``. +If this forwarded zone is signed, instead of adding NTA, add the DS record to the `lua-config-file`_. +See the :doc:`dnssec` information. + +.. _setting-forward-zones-file: + +``forward-zones-file`` +---------------------- +- Path + +Same as `forward-zones`_, parsed from a file. Only 1 zone is allowed per line, specified as follows: + +.. code-block:: none + + example.org=203.0.113.210, 192.0.2.4:5300 + +Zones prefixed with a '+' are forwarded with the recursion-desired bit set, for which see `forward-zones-recurse`_. +Default behaviour without '+' is as with `forward-zones`_. + +.. versionchanged:: 4.0.0 + + Comments are allowed, everything behind '#' is ignored. + +The DNSSEC notes from `forward-zones`_ apply here as well. + +.. _setting-forward-zones-recurse: + +``forward-zones-recurse`` +------------------------- +- 'zonename=IP' pairs, comma separated + +Like regular `forward-zones`_, but forwarded queries have the 'recursion desired' bit set to 1, meaning that this setting is intended to forward queries to other recursive servers. + +The DNSSEC notes from `forward-zones`_ apply here as well. + +.. _setting-gettag-needs-edns-options: + +``gettag-needs-edns-options`` +----------------------------- +.. versionadded:: 4.1.0 + +- Boolean +- Default: no + +If set, EDNS options in incoming queries are extracted and passed to the :func:`gettag` hook in the ``ednsoptions`` table. + +.. _setting-hint-file: + +``hint-file`` +------------- +- Path + +If set, the root-hints are read from this file. If unset, default root hints are used. + +.. _setting-include-dir: + +``include-dir`` +--------------- +- Path + +Directory to scan for additional config files. All files that end with .conf are loaded in order using ``POSIX`` as locale. + +.. _setting-latency-statistic-size: + +``latency-statistic-size`` +-------------------------- +- Integer +- Default: 10000 + +Indication of how many queries will be averaged to get the average latency reported by the 'qa-latency' metric. + +.. _setting-local-address: + +``local-address`` +----------------- +- IP addresses, comma separated +- Default: 127.0.0.1 + +Local IPv4 or IPv6 addresses to bind to. +Addresses can also contain port numbers, for IPv4 specify like this: ``192.0.2.4:5300``, for IPv6: ``[::1]:5300``. + +**Warning**: When binding to wildcard addresses, UNIX semantics mean that answers may not be sent from the address a query was received on. +It is highly recommended to bind to explicit addresses. + +.. _setting-local-port: + +``local-port`` +-------------- +- Integer +- Default: 53 + +Local port to bind to. +If an address in `local-address`_ does not have an explicit port, this port is used. + +.. _setting-non-local-bind: + +``non-local-bind`` +------------------ +- Boolean +- Default: no + +Bind to addresses even if one or more of the `local-address`_'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. + +.. _setting-loglevel: + +``loglevel`` +------------ +- Integer between 0 and 9 +- Default: 4 + +Amount of logging. +Higher is more, more logging may destroy performance. +It is recommended not to set this below 3. + +.. _setting-log-common-errors: + +``log-common-errors`` +--------------------- +- Boolean +- Default: no + +Some DNS errors occur rather frequently and are no cause for alarm. + +.. _setting-logging-facility: + +``logging-facility`` +-------------------- +- Integer + +If set to a digit, logging is performed under this LOCAL facility. +See :ref:`logging`. +Do not pass names like 'local0'! + +.. _setting-lowercase-outgoing: + +``lowercase-outgoing`` +---------------------- +- Boolean +- Default: no + +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. + +.. _setting-lua-config-file: + +``lua-config-file`` +------------------- +- Filename + +If set, and Lua support is compiled in, this will load an additional configuration file for newer features and more complicated setups. +See :doc:`lua-config/index` for the options that can be set in this file. + +.. _setting-lua-dns-script: + +``lua-dns-script`` +------------------ +- Path +- Default: unset + +Path to a lua file to manipulate the Recursor's answers. See :doc:`lua-scripting/index` for more information. + +.. _setting-max-cache-entries: + +``max-cache-entries`` +--------------------- +- Integer +- Default: 1000000 + +Maximum number of DNS cache entries. +1 million per thread will generally suffice for most installations. + +.. _setting-max-cache-ttl: + +``max-cache-ttl`` +----------------- +- Integer +- Default: 86400 + +Maximum number of seconds to cache an item in the DNS cache, no matter what the original TTL specified. + +.. versionchanged:: 4.1.0 + + The minimum value of this setting is 15. i.e. setting this to lower than 15 will make this value 15. + +.. _setting-max-mthreads: + +``max-mthreads`` +---------------- +- Integer +- Default: 2048 + +Maximum number of simultaneous MTasker threads. + +.. _setting-max-packetcache-entries: + +``max-packetcache-entries`` +--------------------------- +- Integer +- Default: 500000 + +Maximum number of Packet Cache entries. +1 million per thread will generally suffice for most installations. + +.. _setting-max-qperq: + +``max-qperq`` +------------- +- Integer +- Default: 50 + +The maximum number of outgoing queries that will be sent out during the resolution of a single client query. +This is used to limit endlessly chasing CNAME redirections. + +.. _setting-max-negative-ttl: + +``max-negative-ttl`` +-------------------- +- Integer +- Default: 3600 + +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. + +.. _setting-max-recursion-depth: + +``max-recursion-depth`` +----------------------- +- Integer +- Default: 40 + +Total maximum number of internal recursion calls the server may use to answer a single query. +0 means unlimited. +The value of `stack-size`_ should be increased together with this one to prevent the stack from overflowing. + +.. versionchanged:: 4.1.0 + + Before 4.1.0, this settings was unlimited. + +.. _setting-max-tcp-clients: + +``max-tcp-clients`` +------------------- +- Integer +- Default: 128 + +Maximum number of simultaneous incoming TCP connections allowed. + +.. _setting-max-tcp-per-client: + +``max-tcp-per-client`` +---------------------- +- Integer +- Default: 0 (unlimited) + +Maximum number of simultaneous incoming TCP connections allowed per client (remote IP address). + +.. _setting-max-tcp-queries-per-connection: + +``max-tcp-queries-per-connection`` +---------------------------------- +.. versionadded:: 4.1.0 + +- Integer +- Default: 0 (unlimited) + +Maximum number of DNS queries in a TCP connection. + +.. _setting-max-total-msec: + +``max-total-msec`` +------------------ +- Integer +- Default: 7000 + +Total maximum number of milliseconds of wallclock time the server may use to answer a single query. + +.. _setting-minimum-ttl-override: + +``minimum-ttl-override`` +------------------------ +- Integer +- Default: 0 (disabled) + +This setting artificially raises all TTLs to be at least this long. +While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers. +Can be set at runtime using ``rec_control set-minimum-ttl 3600``. + +.. _setting-network-timeout: + +``network-timeout`` +------------------- +- Integer +- Default: 1500 + +Number of milliseconds to wait for a remote authoritative server to respond. + +.. _setting-nsec3-max-iterations: + +``nsec3-max-iterations`` +------------------------ +.. versionadded:: 4.1.0 + +- Integer +- Default: 2500 + +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. + +.. _setting-packetcache-ttl: + +``packetcache-ttl`` +------------------- +- Integer +- Default: 3600 + +Maximum number of seconds to cache an item in the packet cache, no matter what the original TTL specified. + +.. _setting-packetcache-servfail-ttl: + +``packetcache-servfail-ttl`` +---------------------------- +- Integer +- Default: 60 + +Maximum number of seconds to cache a 'server failure' answer in the packet cache. + +.. versionchanged:: 4.0.0 + + This setting's maximum is capped to `packetcache-ttl`_. + i.e. setting ``packetcache-ttl=15`` and keeping ``packetcache-servfail-ttl`` at the default will lower ``packetcache-servfail-ttl`` to ``15``. + +.. _setting-pdns-distributes-queries: + +``pdns-distributes-queries`` +---------------------------- +- Boolean + +If set, PowerDNS will have only 1 thread listening on client sockets, and distribute work by itself over threads. +Improves performance on Linux. + +.. _setting-query-local-address: + +``query-local-address`` +----------------------- +- IPv4 Address, comma separated +- Default: 0.0.0.0 + +Send out local queries from this address, or addresses, by adding multiple addresses, increased spoofing resilience is achieved. + +.. _setting-query-local-address6: + +``query-local-address6`` +------------------------ +- IPv6 addresses, comma separated +- Default: unset + +Send out local IPv6 queries from this address or addresses. +Disabled by default, which also disables outgoing IPv6 support. + +.. _setting-quiet: + +``quiet`` +--------- +- Boolean +- Default: yes + +Don't log queries. + +.. _setting-reuseport: + +``reuseport`` +------------- +- Boolean +- Default: no + +If ``SO_REUSEPORT`` support is available, allows multiple processes to open a listening socket on the same port. + +Since 4.1.0, when ``pdns-distributes-queries`` is set to false and ``reuseport`` is enabled, every thread will open a separate listening socket to let the kernel distribute the incoming queries, avoiding any thundering herd issue as well as the distributor thread being a bottleneck, thus leading to much higher performance on multi-core boxes. + +.. _setting-root-nx-trust: + +``root-nx-trust`` +----------------- +- Boolean +- Default: yes + +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. + +.. versionchanged:: 4.0.0 + + Default is 'yes' now, was 'no' before 4.0.0 + +.. _setting-security-poll-suffix: + +``security-poll-suffix`` +------------------------ +- String +- Default: secpoll.powerdns.com. + +Domain name from which to query security update notifications. +Setting this to an empty string disables secpoll. + +.. _setting-serve-rfc1918: + +``serve-rfc1918`` +----------------- +- Boolean +- Default: yes + +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. + +.. _setting-server-down-max-fails: + +``server-down-max-fails`` +------------------------- +- Integer +- Default: 64 + +If a server has not responded in any way this many times in a row, no longer send it any queries for `server-down-throttle-time`_ seconds. +Afterwards, we will try a new packet, and if that also gets no response at all, we again throttle for `server-down-throttle-time`_ seconds. +Even a single response packet will drop the block. + +.. _setting-server-down-throttle-time: + +``server-down-throttle-time`` +----------------------------- +- Integer +- Default: 60 + +Throttle a server that has failed to respond `server-down-max-fails`_ times for this many seconds. + +.. _setting-server-id: + +``server-id`` +------------- +- String +- Default: The hostname of the server + +The PowerDNS recursor by replies to a query for 'id.server' with its hostname, useful for in clusters. +Use this setting to override the answer it gives. + +Query example (where 192.0.2.14 is your server): + +.. code-block:: sh + + dig @192.0.2.14 CHAOS TXT id.server. + +``setgid``, ``setuid`` +---------------------- +- String +- Default: unset + +PowerDNS can change its user and group id after binding to its socket. +Can be used for better :doc:`security `. + +.. _setting-single-socket: + +``single-socket`` +----------------- +- Boolean +- Default: no + +Use only a single socket for outgoing queries. + +.. _setting-snmp-agent: + +``snmp-agent`` +-------------- +.. versionadded:: 4.1.0 + +- Boolean +- Default: no + +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. + +.. _setting-snmp-master-socket: + +``snmp-master-socket`` +---------------------- +.. versionadded:: 4.1.0 + +- String +- Default: empty + +If not empty and ``snmp-agent`` is set to true, indicates how PowerDNS should contact the SNMP master to register as an SNMP agent. + +.. _setting-socket-dir: + +``socket-dir`` +-------------- +- Path + +Where to store the control socket and pidfile. +The default depends on ``LOCALSTATEDIR`` during compile-time (usually ``/var/run`` or ``/run``). + +When using `chroot`_ the default becomes to ``/``. + +``socket-owner``, ``socket-group``, ``socket-mode`` +--------------------------------------------------- +Owner, group and mode of the controlsocket. +Owner and group can be specified by name, mode is in octal. + +.. _setting-spoof-nearmiss-max: + +``spoof-nearmiss-max`` +---------------------- +- Integer +- Default: 20 + +If set to non-zero, PowerDNS will assume it is being spoofed after seeing this many answers with the wrong id. + +.. _setting-stack-size: + +``stack-size`` +-------------- +- Integer +- Default: 200000 + +Size of the stack per thread. + +.. _setting-statistics-interval: + +``statistics-interval`` +----------------------- +.. versionadded:: 4.1.0 + +- Integer +- Default: 1800 + +Interval between logging statistical summary on recursor performance. +Use 0 to disable. + +.. _setting-stats-ringbuffer-entries: + +``stats-ringbuffer-entries`` +---------------------------- +- Integer +- Default: 10000 + +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``. + +.. _setting-tcp-fast-open: + +``tcp-fast-open`` +----------------- +.. versionadded:: 4.1.0 + +- Integer +- Default: 0 (Disabled) + +Enable TCP Fast Open support, if available, on the listening sockets. +The numerical value supplied is used as the queue size, 0 meaning disabled. + +.. _setting-threads: + +``threads`` +----------- +- Integer +- Default: 2 + +Spawn this number of threads on startup. + +.. _setting-trace: + +``trace`` +--------- +- Boolean +- Default: no + +If turned on, output impressive heaps of logging. +May destroy performance under load. + +.. _setting-udp-truncation-threshold: + +``udp-truncation-threshold`` +---------------------------- +- Integer +- Default: 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. + +.. _setting-use-incoming-edns-subnet: + +``use-incoming-edns-subnet`` +---------------------------- +- Boolean +- Default: no + +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 `edns-subnet-whitelist`_ and will be truncated if the received scope exceeds `ecs-ipv4-bits`_ for IPv4 or `ecs-ipv6-bits`_ for IPv6. + +.. _setting-version: + +``version`` +----------- +Print version of this binary. Useful for checking which version of the PowerDNS recursor is installed on a system. + +.. _setting-version-string: + +``version-string`` +------------------ +- String +- Default: PowerDNS Recursor version number + +By default, PowerDNS replies to the 'version.bind' query with its version number. +Security conscious users may wish to override the reply PowerDNS issues. + +.. _setting-webserver: + +``webserver`` +------------- +- Boolean +- Default: no + +Start the webserver (for REST API). + +.. _setting-webserver-address: + +``webserver-address`` +--------------------- +- IP Addresses, separated by spaces +- Default: 127.0.0.1 + +IP address for the webserver to listen on. + +.. _setting-webserver-allow-from: + +``webserver-allow-from`` +------------------------ +- IP addresses, comma separated +- Default: 0.0.0.0, ::/0 + +These subnets are allowed to access the webserver. + +.. _setting-webserver-password: + +``webserver-password`` +---------------------- +- String +- Default: unset + +Password required to access the webserver. + +.. _setting-webserver-port: + +``webserver-port`` +------------------ +- Integer +- Default: 8082 + +TCP port where the webserver should listen on. + +.. _setting-write-pid: + +``write-pid`` +------------- +- Boolean +- Default: yes + +If a PID file should be written to `socket-dir`_ diff --git a/pdns/recursordist/docs/upgrade.rst b/pdns/recursordist/docs/upgrade.rst new file mode 100644 index 0000000000..67a5559b63 --- /dev/null +++ b/pdns/recursordist/docs/upgrade.rst @@ -0,0 +1,20 @@ +Upgrade Guide +============= + +Before upgrading, it is advised to read the :doc:`changelog/index`. +When upgrading several versions, please read **all** notes applying to the upgrade. + +4.0.3 to 4.0.4 +-------------- + +One setting has been added to limit the risk of overflowing the stack: + +- :ref:`setting-max-recursion-depth`: defaults to 40 and was unlimited before + +4.0.0 to 4.0.1 +-------------- + +Two settings have changed defaults, these new defaults decrease CPU usage: + +- :ref:`setting-root-nx-trust` changed from "no" to "yes" +- :ref:`setting-log-common-errors` changed from "yes" to "no" diff --git a/pdns/recursordist/m4/pdns_check_pandoc.m4 b/pdns/recursordist/m4/pdns_check_pandoc.m4 deleted file mode 100644 index f2a0af8973..0000000000 --- a/pdns/recursordist/m4/pdns_check_pandoc.m4 +++ /dev/null @@ -1,11 +0,0 @@ -AC_DEFUN([PDNS_CHECK_PANDOC], [ - AC_CHECK_PROG([PANDOC], [pandoc], [pandoc], [no]) - - AS_IF([test "x$PANDOC" = "xno"], [ - AS_IF([test ! -f "$srcdir/pdns_recursor.1"], - [AC_MSG_WARN([pandoc is missing, unable to build manpages.])] - ) - ]) - AM_CONDITIONAL([HAVE_PANDOC], [test "x$PANDOC" != "xno"]) - AM_CONDITIONAL([HAVE_MANPAGES], [test -e "$srcdir/pdns_recursor.1"]) -]) diff --git a/pdns/recursordist/m4/pdns_check_virtualenv.m4 b/pdns/recursordist/m4/pdns_check_virtualenv.m4 new file mode 100644 index 0000000000..8f735b2193 --- /dev/null +++ b/pdns/recursordist/m4/pdns_check_virtualenv.m4 @@ -0,0 +1,12 @@ +AC_DEFUN([PDNS_CHECK_VIRTUALENV], [ + AC_CHECK_PROG([VIRTUALENV], [virtualenv], [virtualenv], [no]) + + AS_IF([test "x$VIRTUALENV" = "xno"], [ + AS_IF([test ! -f "$srcdir/pdns_recursor.1"], + [AC_MSG_WARN([virtualenv is missing, unable to build manpages.])] + ) + ]) + AM_CONDITIONAL([HAVE_VIRTUALENV], [test "x$VIRTUALENV" != "xno"]) + AM_CONDITIONAL([HAVE_MANPAGES], [test -e "$srcdir/pdns_recursor.1"]) +]) + diff --git a/pdns/recursordist/pdns_recursor.1.md b/pdns/recursordist/pdns_recursor.1.md deleted file mode 120000 index f3b634535b..0000000000 --- a/pdns/recursordist/pdns_recursor.1.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/manpages/pdns_recursor.1.md \ No newline at end of file diff --git a/pdns/recursordist/rec_control.1.md b/pdns/recursordist/rec_control.1.md deleted file mode 120000 index d41edc6e78..0000000000 --- a/pdns/recursordist/rec_control.1.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/manpages/rec_control.1.md \ No newline at end of file -- 2.47.2