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 <guides/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 <reference/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 <guides/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
# 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.
--- /dev/null
+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.
serverpools
serverselection
carbon
+ dns-over-tls
.. 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.
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::
.. 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.
.. 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
dnstap Logging Reference
========================
-http://dnstap.info is a flexible, structured binary log format for DNS software.
+`dnstap <http://dnstap.info>`__ 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`.
.. 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)
.. 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
.. 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
.. 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
.. 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 <reference/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
.. 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 <reference/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
.. 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
.. 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
projects / pdns / commitdiff