Using systemd
-------------
-.. versionadded:: 1.3.0
On systems with systemd, instance services can be used.
To create a dnsdist service named ``foo``, create a ``dnsdist-foo.conf`` in ``SYSCONFDIR``, then run ``systemctl enable dnsdist@foo.service`` and ``systemctl start dnsdist@foo.service``.
Runtime-modifiable IP address sets
==================================
-.. versionadded:: 1.2.0
-
From within :func:`maintenance` or other places, we may find that certain IP
addresses must be treated differently for a certain time.
``chashed``
~~~~~~~~~~~
-.. versionadded: 1.3.3
-
``chashed`` is a consistent hashing distribution policy. Identical questions with identical hashes will be distributed to the same servers. But unlike the ``whashed`` policy, this distribution will keep consistent over time. Adding or removing servers will only remap a small part of the queries.
Increasing the weight of servers to a value larger than the default is required to get a good distribution of queries. Small values like 100 or 1000 should be enough to get a correct distribution.
.. function:: addLocal(address[, options])
- .. versionadded:: 1.2.0
-
.. versionchanged:: 1.3.0
Added ``cpus`` to the options.
.. function:: addTLSLocal(address, certFile(s), keyFile(s) [, options])
- .. versionadded:: 1.3.0
.. versionchanged:: 1.3.1
``certFile(s)`` and ``keyFile(s)`` parameters accept a list of files.
``sessionTickets`` option added.
.. function:: setLocal(address[, options])
- .. versionadded:: 1.2.0
-
Remove the list of listen addresses and add a new one.
:param str address: The IP Address with an optional port to listen on.
.. function:: addConsoleACL(netmask)
- .. versionadded:: 1.3.0
-
Add a netmask to the existing console ACL, allowing remote clients to connect to the console. Please make sure that encryption
has been enabled with :func:`setKey` before doing so. The default is to only allow 127.0.0.1/8 and ::1/128.
.. function:: setConsoleConnectionsLogging(enabled)
- .. versionadded:: 1.2.0
-
Whether to log the opening and closing of console connections.
:param bool enabled: Default to true.
.. function:: setConsoleACL(netmasks)
- .. versionadded:: 1.3.0
-
Remove the existing console ACL and add the netmasks from the table, allowing remote clients to connect to the console. Please make sure that encryption
has been enabled with :func:`setKey` before doing so.
.. function:: setConsoleOutputMaxMsgSize(size)
- .. versionadded:: 1.3.3
-
Set the maximum size in bytes of a single console message, default set to 10 MB.
:param int size: The new maximum size.
.. function:: setWebserverConfig(options)
- .. versionadded:: 1.3.3
-
.. versionchanged:: 1.5.0
``acl`` optional parameter added.
.. function:: setRingBuffersLockRetries(num)
- .. versionadded:: 1.3.0
-
Set the number of shards to attempt to lock without blocking before giving up and simply blocking while waiting for the next shard to be available
:param int num: The maximum number of attempts. Defaults to 5 if there is more than one shard, 0 otherwise.
.. method:: ServerPool:getECS()
- .. versionadded:: 1.3.0
-
Whether dnsdist will add EDNS Client Subnet information to the query before looking up into the cache,
when all servers from this pool are down. For more information see :meth:`ServerPool:setECS`.
.. method:: ServerPool:setECS()
- .. versionadded:: 1.3.0
-
Set to true if dnsdist should add EDNS Client Subnet information to the query before looking up into the cache,
when all servers from this pool are down. If at least one server is up, the preference of the
selected server is used, this parameter is only useful if all the backends in this pool are down
.. method:: PacketCache:dump(fname)
- .. versionadded:: 1.3.1
-
Dump a summary of the cache entries to a file.
:param str fname: The path to a file where the cache summary should be dumped. Note that if the target file already exists, it will not be overwritten.
.. function:: getTLSContext(idx)
- .. versionadded:: 1.3.0
-
Return the TLSContext object for the context of index ``idx``.
.. function:: getTLSFrontend(idx)
- .. versionadded:: 1.3.1
-
Return the TLSFrontend object for the TLS bind of index ``idx``.
.. function:: getTLSFrontendCount()
.. function:: showTLSContexts()
- .. versionadded:: 1.3.0
-
Print the list of all availables DNS over TLS contexts.
.. function:: showTLSErrorCounters()
.. function:: dynBlockRulesGroup() -> DynBlockRulesGroup
- .. versionadded:: 1.3.0
-
Creates a new :class:`DynBlockRulesGroup` object.
.. class:: DynBlockRulesGroup
.. method:: DynBlockRulesGroup:excludeRange(netmasks)
- .. versionadded:: 1.3.1
-
.. versionchanged:: 1.6.0
This method now accepts a :class:`NetmaskGroup` object.
.. method:: DynBlockRulesGroup:includeRange(netmasks)
- .. versionadded:: 1.3.1
-
.. versionchanged:: 1.6.0
This method now accepts a :class:`NetmaskGroup` object.
.. method:: DynBlockRulesGroup:toString()
- .. versionadded:: 1.3.1
-
Return a string describing the rules and range exclusions of this DynBlockRulesGroup.
StatNode
.. class:: TLSContext
- .. versionadded:: 1.3.0
-
This object represents an address and port dnsdist is listening on for DNS over TLS queries.
.. method:: TLSContext:rotateTicketsKey()
.. class:: TLSFrontend
- .. versionadded:: 1.3.1
-
This object represents the configuration of a listening frontend for DNS over TLS queries. To each frontend is associated a TLSContext.
.. method:: TLSContext:loadNewCertificatesAndKeys(certFile(s), keyFile(s))
.. function:: setAddEDNSToSelfGeneratedResponses(add)
- .. versionadded:: 1.3.3
-
Whether to add EDNS to self-generated responses, provided that the initial query had EDNS.
:param bool add: Whether to add EDNS, default is true.
.. function:: setPayloadSizeOnSelfGeneratedAnswers(payloadSize)
- .. versionadded:: 1.3.3
-
.. versionchanged:: 1.6.0
Default value changed from 1500 to 1232.
.. function:: setSecurityPollInterval(interval)
- .. versionadded:: 1.3.3
-
Set the interval, in seconds, between two security pollings.
:param int interval: The interval, in seconds, between two pollings. Default is 3600.
.. function:: setSecurityPollSuffix(suffix)
- .. versionadded:: 1.3.3
-
Domain name from which to query security update notifications. Setting this to an empty string disables secpoll.
:param string suffix: The suffix to use, default is 'secpoll.powerdns.com.'.
.. method:: DNSCryptContext:addNewCertificate(cert, key[, active])
- .. versionadded:: 1.3.0
-
Add a new certificate to the the given context. Active certificates are advertised to
clients, inactive ones are not.
.. method:: DNSCryptContext:getCertificate(index) -> DNSCryptCert
- .. versionadded:: 1.3.0
-
Return the certificate with index `index`.
:param int index: The index of the certificate, starting at 0
.. method:: DNSCryptContext:getCertificatePair(index) -> DNSCryptCertificatePair
- .. versionadded:: 1.3.0
-
Return the certificate pair with index `index`.
:param int index: The index of the certificate, starting at 0
.. method:: DNSCryptContext:getCertificatePair(index) -> table of DNSCryptCertificatePair
- .. versionadded:: 1.3.0
-
Return a table of certificate pairs.
.. method:: DNSCryptContext:getProviderName() -> string
.. method:: DNSCryptContext:markActive(serial)
- .. versionadded:: 1.3.0
-
Mark the certificate with serial `serial` as active, meaning it will be advertised to clients.
:param int serial: The serial of the number to mark as active
.. method:: DNSCryptContext:markInactive(serial)
- .. versionadded:: 1.3.0
-
Mark the certificate with serial `serial` as inactive, meaning it will not be advertised
to clients but can still be used to answer queries tied to this certificate.
.. method:: DNSCryptContext:printCertificates()
- .. versionadded:: 1.3.0
-
Print all the certificates.
.. method:: DNSCryptContext:removeInactiveCertificate(serial)
- .. versionadded:: 1.3.0
-
Remove the certificate with serial `serial`. It will not be possible to answer queries tied
to this certificate, so it should have been marked as inactive for a certain time before that.
Active certificates should be marked as inactive before they can be removed.
.. method:: DNSName:chopOff() -> bool
- .. versionadded:: 1.2.0
-
Removes the left-most label and returns ``true``.
``false`` is returned if no label was removed
.. method:: DNSQuestion:getDO() -> bool
- .. versionadded:: 1.2.0
-
Get the value of the DNSSEC OK bit.
:returns: true if the DO bit was set, false otherwise
.. method:: DNSQuestion:getEDNSOptions() -> table
- .. versionadded:: 1.3.3
-
Return the list of EDNS Options, if any.
:returns: A table of EDNSOptionView objects, indexed on the ECS Option code
.. method:: DNSQuestion:getTag(key) -> string
- .. versionadded:: 1.2.0
-
Get the value of a tag stored into the DNSQuestion object.
:param string key: The tag's key
.. method:: DNSQuestion:getTagArray() -> table
- .. versionadded:: 1.2.0
-
Get all the tags stored into the DNSQuestion object.
:returns: A table of tags, using strings as keys and values
.. method:: DNSQuestion:sendTrap(reason)
- .. versionadded:: 1.2.0
-
Send an SNMP trap.
:param string reason: An optional string describing the reason why this trap was sent
.. method:: DNSQuestion:setTag(key, value)
- .. versionadded:: 1.2.0
-
Set a tag into the DNSQuestion object.
:param string key: The tag's key
.. method:: DNSQuestion:setTagArray(tags)
- .. versionadded:: 1.2.0
-
Set an array of tags into the DNSQuestion object.
:param table tags: A table of tags, using strings as keys and values
.. class:: EDNSOptionView
- .. versionadded:: 1.3.3
-
An object that represents the values of a single EDNS option received in a query.
.. method:: EDNSOptionView:count()
.. method:: DynBPFFilter:excludeRange(netmasks)
- .. versionadded:: 1.3.3
-
Exclude this range, or list of ranges, meaning that no dynamic block will ever be inserted for clients in that range. Default to empty, meaning rules are applied to all ranges. When used in combination with :meth:`DynBPFFilter:includeRange`, the more specific entry wins.
:param int netmasks: A netmask, or list of netmasks, as strings, like for example "192.0.2.1/24"
.. method:: DynBPFFilter:includeRange(netmasks)
- .. versionadded:: 1.3.3
-
Include this range, or list of ranges, meaning that rules will be applied to this range. When used in combination with :meth:`DynBPFFilter:excludeRange`, the more specific entry wins.
:param int netmasks: A netmask, or list of netmasks, as strings, like for example "192.0.2.1/24"
.. method:: DNSDistProtoBufMessage:addResponseRR(name, type, class, ttl, blob)
- .. versionadded:: 1.2.0
-
Add a response RR to the protobuf message.
:param string name: The RR name.
.. method:: DNSDistProtoBufMessage:setProtobufResponseType(sec, usec)
- .. versionadded:: 1.2.0
-
Change the protobuf response type from a query to a response, and optionally set the query time.
:param int sec: Optional query time in seconds.
.. method:: DNSDistProtoBufMessage:setServerIdentity(id)
- .. versionadded:: 1.3.3
-
Set the server identify field.
:param string id: The server ID
.. method:: DNSDistProtoBufMessage:setTag(value)
- .. versionadded:: 1.2.0
-
Add a tag to the list of tags.
:param string value: The tag value
.. method:: DNSDistProtoBufMessage:setTagArray(valueList)
- .. versionadded:: 1.2.0
-
Add a list of tags.
:param table tags: A list of tags as strings
SNMP reporting
==============
-.. versionadded:: 1.2.0
-
-
.. function:: snmpAgent(enableTraps [, daemonSocket])
Enable SNMP support.
.. function:: setUDPMultipleMessagesVectorSize(num)
- .. 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()``.
.. function:: addCacheHitResponseAction(DNSRule, action [, options])
- .. versionadded:: 1.2.0
-
.. versionchanged:: 1.3.0
Added the optional parameter ``options``.
.. function:: mvCacheHitResponseRule(from, to)
- .. versionadded:: 1.2.0
-
Move cache hit response rule ``from`` to a position where it is in front of ``to``.
``to`` can be one larger than the largest rule, in which case the rule will be moved to the last position.
.. function:: rmCacheHitResponseRule(id)
- .. versionadded:: 1.2.0
-
.. versionchanged:: 1.3.0
``id`` can now be an UUID.
.. function:: showCacheHitResponseRules([options])
- .. versionadded:: 1.2.0
-
.. versionchanged:: 1.3.0
``options`` optional parameter added
.. function:: topCacheHitResponseRule()
- .. versionadded:: 1.2.0
-
.. versionchanged:: 1.6.0
Replaced by :func:`mvCacheHitResponseRuleToTop`
.. function:: addSelfAnsweredResponseAction(DNSRule, action [, options])
- .. versionadded:: 1.3.0
-
.. versionchanged:: 1.6.0
Added ``name`` to the ``options``.
.. function:: mvSelfAnsweredResponseRule(from, to)
- .. versionadded:: 1.3.0
-
Move self answered response rule ``from`` to a position where it is in front of ``to``.
``to`` can be one larger than the largest rule, in which case the rule will be moved to the last position.
.. function:: rmSelfAnsweredResponseRule(id)
- .. versionadded:: 1.3.0
-
.. versionchanged:: 1.6.0
``id`` can now be a string representing the name of the rule.
.. function:: showSelfAnsweredResponseRules([options])
- .. versionadded:: 1.3.0
-
Show all defined self answered response rules, optionally displaying their UUIDs.
:param table options: A table with key: value pairs with display options.
.. function:: topSelfAnsweredResponseRule()
- .. versionadded:: 1.3.0
-
.. versionchanged:: 1.6.0
Replaced by :func:`mvSelfAnsweredResponseRuleToTop`
* A list of :class:`DNSName`\ s
* A (compounded) ``Rule``
-.. versionadded:: 1.2.0
- A DNSRule can also be a :class:`DNSName` or a list of these
-
.. function:: AllRule()
Matches all traffic
.. function:: ProbaRule(probability)
- .. versionadded:: 1.3.0
-
Matches queries with a given probability. 1.0 means "always"
:param double probability: Probability of a match
.. function:: QNameRule(qname)
- .. versionadded:: 1.2.0
-
Matches queries with the specified qname exactly.
:param string qname: Qname to match
.. function:: RDRule()
- .. versionadded:: 1.2.0
-
Matches queries with the RD flag set.
.. function:: RegexRule(regex)
.. 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:: PoolAvailableRule(poolname)
- .. versionadded:: 1.3.3
-
Check whether a pool has any servers available to handle queries
.. code-block:: Lua
.. function:: DnstapLogAction(identity, logger[, alterFunction])
- .. 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.
Subsequent rules are processed after this action.
.. function:: DnstapLogResponseAction(identity, logger[, alterFunction])
- .. 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.
Subsequent rules are processed after this action.
.. function:: SetECSAction(v4 [, v6])
- .. versionadded:: 1.3.1
-
Set the ECS prefix and prefix length sent to backends to an arbitrary value.
If both IPv4 and IPv6 masks are supplied the IPv4 one will be used for IPv4 clients
and the IPv6 one for IPv6 clients. Otherwise the first mask is used for both, and
.. function:: TagAction(name, value)
- .. versionadded:: 1.3.0
-
.. deprecated:: 1.6.0
-
- This function has been deprecated in 1.6.0, please use :func:`SetTagAction` instead.
+ This function has been deprecated in 1.6.0, please use :func:`SetTagAction` instead.
Associate a tag named ``name`` with a value of ``value`` to this query, that will be passed on to the response.
Subsequent rules are processed after this action.
.. function:: TagResponseAction(name, value)
- .. versionadded:: 1.3.0
-
.. deprecated:: 1.6.0
-
- This function has been deprecated in 1.6.0, please use :func:`SetTagResponseAction` instead.
+ This function has been deprecated in 1.6.0, please use :func:`SetTagResponseAction` instead.
Associate a tag named ``name`` with a value of ``value`` to this response.
Subsequent rules are processed after this action.
security-status
---------------
-.. versionadded:: 1.3.4
-
The security status of :program:`dnsdist`. This is regularly polled.
* 0 = Unknown status or unreleased version
projects / thirdparty / pdns.git / commitdiff
