From 87cb311027b9957b2b5938d38a5a1c0bc08f087a Mon Sep 17 00:00:00 2001 From: Pieter Lexis Date: Mon, 26 Mar 2018 14:49:55 +0200 Subject: [PATCH] dnsdist: Add 1.3.0 changelog --- pdns/dnsdistdist/docs/changelog.rst | 151 ++++++++++++++++++ pdns/dnsdistdist/docs/conf.py | 4 +- pdns/dnsdistdist/docs/guides/dns-over-tls.rst | 12 ++ pdns/dnsdistdist/docs/guides/index.rst | 1 + pdns/dnsdistdist/docs/reference/config.rst | 12 +- pdns/dnsdistdist/docs/reference/dnscrypt.rst | 3 + pdns/dnsdistdist/docs/reference/dnstap.rst | 4 +- pdns/dnsdistdist/docs/reference/tuning.rst | 10 +- pdns/dnsdistdist/docs/rules-actions.rst | 28 +++- 9 files changed, 208 insertions(+), 17 deletions(-) create mode 100644 pdns/dnsdistdist/docs/guides/dns-over-tls.rst diff --git a/pdns/dnsdistdist/docs/changelog.rst b/pdns/dnsdistdist/docs/changelog.rst index b88fbbcb9..9b2336143 100644 --- a/pdns/dnsdistdist/docs/changelog.rst +++ b/pdns/dnsdistdist/docs/changelog.rst @@ -1,6 +1,157 @@ Changelog ========= +.. changelog:: + :version: 1.3.0 + :released: Unreleased + + .. change:: + :tags: Improvements, New Features + :pullreq: 5576, 5860 + :tickets: 5202, 5859 + + Add cache sharding, ``recvmmsg`` and CPU pinning support. + With these, the scalability of :program:`dnsdist` is drastically improved. + + .. change:: + :tags: Improvements + :pullreq: 5970 + + Add burst option to :func:`MaxQPSIPRule` (42wim). + + .. change:: + :tags: Bug Fixes + :pullreq: 5328 + :tickets: 5327 + + Handle SNMP alarms so we can reconnect to the master. + + .. change:: + :tags: New Features + :pullreq: 5625 + + Add an optional `status` parameter to :func:`Server:setAuto`. + + .. change:: + :tags: Bug Fixes + :pullreq: 5597 + :tickets: 5489 + + Fix signed/unsigned comparison warnings on ARM. + + .. change:: + :tags: Improvements + :pullreq: 6022 + + Add Pools, cacheHitResponseRules to the API. + + .. change:: + :tags: New Features + :pullreq: 6072 + + Add :func:`inClientStartup` function. + + .. change:: + :tags: Improvements + :pullreq: 5929 + :tickets: 5748 + + Add a class option to health checks. + + .. change:: + :tags: New Features + :pullreq: 6037 + + Add tag-based routing of queries. + + .. change:: + :tags: New Features + :pullreq: 6117, 6175, 6176, 6177, 6189 + + Add experimental :doc:`DNS-over-TLS ` support. + + .. change:: + :tags: Improvements + :pullreq: 6030 + + Add UUIDs to rules, this allows tracking rules through modifications and moving them around. + + .. change:: + :tags: Bug Fixes + :pullreq: 5770 + + Keep trying if the first connection to the remote logger failed + + .. change:: + :tags: New Features + :pullreq: 5201, 6170 + + Add simple :doc:`dnstap ` support (Justin Valentini, Chris Hofstaedtler). + + .. change:: + :tags: Improvements + :pullreq: 6185 + :tickets: 6182 + + Apply ResponseRules to locally generated answers (Chris Hofstaedtler). + + .. change:: + :tags: Improvements + :pullreq: 6283 + + Report :func:`LuaAction` and :func:`LuaResponseAction` failures in the log and send SERVFAIL instead of not answering the query (Chris Hofstaedtler). + + .. change:: + :tags: Improvements + :pullreq: 6289 + + Unify global statistics accounting (Chris Hofstaedtler). + + .. change:: + :tags: Improvements + :pullreq: 6350, 6366 + + Speed up the processing of large ring buffers. + This change will make :program:`dnsdist` more scalable with a large number of different clients. + + .. change:: + :tags: Improvements + :pullreq: 6363 + :tickets: 6346 + + Make custom :func:`addLuaAction` and :func:`addLuaResponseAction` callback's second return value optional. + + .. change:: + :tags: Improvements + :pullreq: 6327 + + Add "server-up" metric count to Carbon Reporting (Lowell Mower). + + .. change:: + :tags: Improvements + :pullreq: 6045, 6382 + + Add xchacha20 support for :doc:`DNSCrypt `. + + .. change:: + :tags: Improvements + :pullreq: 6317 + + Scalability improvement: Add an option to use several source ports towards a backend. + + .. change:: + :tags: Improvements + :pullreq: 6375 + + Add '?' for providing help() output on ``dnsdist -c`` (Kirill Ponomarev). + + .. change:: + :tags: Improvements + :pullreq: 6190, 6381 + + Replace the Lua mutex with a rw lock to limit contention. + This improves the processing speed and parallelism of the policies. + .. changelog:: :version: 1.2.1 :released: 16th of February 2018 diff --git a/pdns/dnsdistdist/docs/conf.py b/pdns/dnsdistdist/docs/conf.py index 5da5ea95d..7490d0d65 100644 --- a/pdns/dnsdistdist/docs/conf.py +++ b/pdns/dnsdistdist/docs/conf.py @@ -56,9 +56,9 @@ author = 'PowerDNS.COM BV and its contributors' # built documents. # # The short X.Y version. -version = '1.2' +version = '1.3' # The full version, including alpha/beta/rc tags. -release = '1.2.0' +release = '1.3.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/pdns/dnsdistdist/docs/guides/dns-over-tls.rst b/pdns/dnsdistdist/docs/guides/dns-over-tls.rst new file mode 100644 index 000000000..90ab9fab2 --- /dev/null +++ b/pdns/dnsdistdist/docs/guides/dns-over-tls.rst @@ -0,0 +1,12 @@ +DNS-over-TLS +============ + +Since version 1.3.0, :program:`dnsdist` supports experimental DNS-over-TLS support. +To see if the installation supports this, run ``dnsdist --version``. +If the output shows ``dns-over-tls`` with one or more SSL libraries in brackets, DNS-over-TLS is supported. + +Adding a listen port for DNS-over-TLS can be done with the :func:`addTLSLocal` function, e.g.:: + + addTLSLocal('192.0.2.55', '/etc/ssl/certs/example.com.pem', '/etc/ssl/private/example.com.key') + +This will make :program:`dnsdist` listen on 192.0.2.55:853 on TCP and UDP and will use the provided certificate and key to provide the TLS connection. diff --git a/pdns/dnsdistdist/docs/guides/index.rst b/pdns/dnsdistdist/docs/guides/index.rst index c78e58150..4f5cf4b96 100644 --- a/pdns/dnsdistdist/docs/guides/index.rst +++ b/pdns/dnsdistdist/docs/guides/index.rst @@ -13,4 +13,5 @@ These chapters contain several guides and nuggets of information regarding dnsdi serverpools serverselection carbon + dns-over-tls diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst index 254669ee2..4a82a030a 100644 --- a/pdns/dnsdistdist/docs/reference/config.rst +++ b/pdns/dnsdistdist/docs/reference/config.rst @@ -49,6 +49,9 @@ Listen Sockets .. versionadded:: 1.2.0 + .. versionchanged:: 1.3.0 + Added ``cpus`` to the options. + Add to the list of listen addresses. :param str address: The IP Address with an optional port to listen on. @@ -274,7 +277,10 @@ Servers newServer(server_table) .. versionchanged:: 1.3.0 - ``checkFunction`` option added. + - Added ``checkClass`` to server_table. + - Added ``sockets`` to server_table + - Added ``checkFunction`` to server_table + Add a new backend server. Call this function with either a string:: @@ -498,8 +504,8 @@ See :doc:`../guides/cache` for a how to. .. function:: newPacketCache(maxEntries[, maxTTL=86400[, minTTL=0[, temporaryFailureTTL=60[, staleTTL=60[, dontAge=false[, numberOfShards=1[, deferrableInsertLock=true]]]]]]]) -> PacketCache - .. versionchanged:: 1.2.0 - ``numberOfShard`` and ``deferrableInsertLock`` parameters added. + .. versionchanged:: 1.3.0 + ``numberOfShards`` and ``deferrableInsertLock`` parameters added. Creates a new :class:`PacketCache` with the settings specified. diff --git a/pdns/dnsdistdist/docs/reference/dnscrypt.rst b/pdns/dnsdistdist/docs/reference/dnscrypt.rst index c597dbecb..3e689a452 100644 --- a/pdns/dnsdistdist/docs/reference/dnscrypt.rst +++ b/pdns/dnsdistdist/docs/reference/dnscrypt.rst @@ -3,6 +3,9 @@ DNSCrypt objects and functions .. function:: addDNSCryptBind(address, provider, certificate, keyfile[, options]) + .. versionchanged:: 1.3.0 + ``cpus`` option added. + Adds a DNSCrypt listen socket on ``address``. :param string address: The address and port to listen on diff --git a/pdns/dnsdistdist/docs/reference/dnstap.rst b/pdns/dnsdistdist/docs/reference/dnstap.rst index b48626293..08160a137 100644 --- a/pdns/dnsdistdist/docs/reference/dnstap.rst +++ b/pdns/dnsdistdist/docs/reference/dnstap.rst @@ -1,9 +1,11 @@ dnstap Logging Reference ======================== -http://dnstap.info is a flexible, structured binary log format for DNS software. +`dnstap `__ is a flexible, structured binary log format for DNS software. Reader implementations in various languages exist. +:program:`dnsdist` supports dnstap since version 1.3.0. + Canonically, dnstap is sent over a FrameStream socket, either a local AF_UNIX (see :func:`newFrameStreamUnixLogger`) or a TCP/IP socket (see :func:`newFrameStreamTcpLogger`). As an extension, :program:`dnsdist` can send raw dnstap protobuf messages over a :func:`newRemoteLogger`. diff --git a/pdns/dnsdistdist/docs/reference/tuning.rst b/pdns/dnsdistdist/docs/reference/tuning.rst index 8f6d99233..54d568236 100644 --- a/pdns/dnsdistdist/docs/reference/tuning.rst +++ b/pdns/dnsdistdist/docs/reference/tuning.rst @@ -75,13 +75,13 @@ Tuning related functions .. function:: setUDPMultipleMessagesVectorSize(num) - .. versionadded:: 1.2.0 + .. versionadded:: 1.3.0 - Set the maximum number of UDP queries messages to accept in a single `recvmmsg()` call. Only available if the underlying OS - support `recvmmsg()` with the `MSG_WAITFORONE` option. Defaults to 1, which means only query at a time is accepted, using - `recvmsg()` instead of `recvmmsg()`. + Set the maximum number of UDP queries messages to accept in a single ``recvmmsg()`` call. Only available if the underlying OS + support ``recvmmsg()`` with the ``MSG_WAITFORONE`` option. Defaults to 1, which means only query at a time is accepted, using + ``recvmsg()`` instead of ``recvmmsg()``. - :param int num: + :param int num: maximum number of UDP queries to accept .. function:: setUDPTimeout(num) diff --git a/pdns/dnsdistdist/docs/rules-actions.rst b/pdns/dnsdistdist/docs/rules-actions.rst index 4524080b1..4bf8b85b3 100644 --- a/pdns/dnsdistdist/docs/rules-actions.rst +++ b/pdns/dnsdistdist/docs/rules-actions.rst @@ -148,11 +148,14 @@ Rule Generators .. versionchanged:: 1.3.0 Added the optional parameter ``options``. + .. versionchanged:: 1.3.0 + The second argument returned by the ``function`` can be omitted. For earlier releases, simply return an empty string. + Invoke a Lua function that accepts a :class:`DNSQuestion`. This function works similar to using :func:`LuaAction`. The ``function`` should return both a :ref:`DNSAction` and its argument `rule`. The `rule` is used as an argument - of the following :ref:`DNSAction`: `DNSAction.Spoof`, `DNSAction.Pool` and `DNSAction.Delay`. As of version `1.3.0`, you can - omit the argument. For earlier releases, simply return an empty string. If the Lua code fails, ServFail is returned. + of the following :ref:`DNSAction`: `DNSAction.Spoof`, `DNSAction.Pool` and `DNSAction.Delay`. + If the Lua code fails, ServFail is returned. :param DNSRule: match queries based on this rule :param string function: the name of a Lua function @@ -181,11 +184,14 @@ Rule Generators .. versionchanged:: 1.3.0 Added the optional parameter ``options``. + .. versionchanged:: 1.3.0 + The second argument returned by the ``function`` can be omitted. For earlier releases, simply return an empty string. + Invoke a Lua function that accepts a :class:`DNSResponse`. This function works similar to using :func:`LuaResponseAction`. The ``function`` should return both a :ref:`DNSResponseAction` and its argument `rule`. The `rule` is used as an argument - of the `DNSResponseAction.Delay`. As of version `1.3.0`, you can omit the argument (see :func:`addLuaAction`). For earlier - releases, simply return an empty string. If the Lua code fails, ServFail is returned. + of the `DNSResponseAction.Delay`. + If the Lua code fails, ServFail is returned. :param DNSRule: match queries based on this rule :param string function: the name of a Lua function @@ -688,6 +694,8 @@ These ``DNSRule``\ s be one of the following items: .. function:: TagRule(name [, value]) + .. versionadded:: 1.3.0 + Matches question or answer with a tag named ``name`` set. If ``value`` is specified, the existing tag value should match too. :param bool name: The name of the tag that has to be set @@ -775,7 +783,9 @@ The following actions exist. .. function:: DnstapLogAction(identity, logger[, alterFunction]) - Send the the current query to a remote logger as a dnstap message. + .. versionadded:: 1.3.0 + + Send the the current query to a remote logger as a :doc:`dnstap ` message. ``alterFunction`` is a callback, receiving a :class:`DNSQuestion` and a :class:`DnstapMessage`, that can be used to modify the message. :param string identity: Server identity to store in the dnstap message @@ -784,7 +794,9 @@ The following actions exist. .. function:: DnstapLogResponseAction(identity, logger[, alterFunction]) - Send the the current response to a remote logger as a dnstap message. + .. versionadded:: 1.3.0 + + Send the the current response to a remote logger as a :doc:`dnstap ` message. ``alterFunction`` is a callback, receiving a :class:`DNSQuestion` and a :class:`DnstapMessage`, that can be used to modify the message. :param string identity: Server identity to store in the dnstap message @@ -943,6 +955,8 @@ The following actions exist. .. function:: TagAction(name, value) + .. versionadded:: 1.3.0 + Associate a tag named ``name`` with a value of ``value`` to this query, that will be passed on to the response. :param string name: The name of the tag to set @@ -950,6 +964,8 @@ The following actions exist. .. function:: TagResponseAction(name, value) + .. versionadded:: 1.3.0 + Associate a tag named ``name`` with a value of ``value`` to this response. :param string name: The name of the tag to set -- 2.40.0