Configuration Reference¶
This page lists all configuration options for dnsdist.
Note
When an IPv6 IP:PORT combination is needed, the bracketed syntax from RFC 3986 should be used. e.g. “[2001:DB8:14::C0FF:FEE]:5300”.
Functions and Types¶
Within dnsdist several core object types exist:
Server
: generated withnewServer()
, represents a downstream serverComboAddress
: represents an IP address and portDNSName
: represents a domain nameNetmask
: represents a netmaskNetmaskGroup
: represents a group of netmasksQPSLimiter
: implements a QPS-based filterSuffixMatchNode
: represents a group of domain suffixes for rapid testing of membershipDNSHeader
: represents the header of a DNS packet, see DNSHeader (dh) objectClientState
: sometimes also called Bind or Frontend, represents the addresses and ports dnsdist is listening on
The existence of most of these objects can mostly be ignored, unless you plan to write your own hooks and policies, but it helps to understand an expressions like:
getServer(0).order=12 -- set order of server 0 to 12
getServer(0):addPool("abuse") -- add this server to the abuse pool
The .
means order
is a data member, while the :
means addPool
is a member function.
Global configuration¶
-
addCapabilitiesToRetain
(capabilities)¶ New in version 1.7.0.
Accept a Linux capability as a string, or a list of these, to retain after startup so that privileged operations can still be performed at runtime. Keeping
CAP_SYS_ADMIN
on kernel 5.8+ for example allows loading eBPF programs and altering eBPF maps at runtime even if thekernel.unprivileged_bpf_disabled
sysctl is set. Note that this does not grant the capabilities to the process, doing so might be done by running it as root which we don’t advise, or by adding capabilities via the systemd unit file, for example. Please also be aware that switching to a different user via--uid
will still drop all capabilities.
-
includeDirectory
(path)¶ Include configuration files from
path
.Parameters: path (str) – The directory to load configuration files from. Each file must end in .conf
.
-
loadTicketsKey
(key)¶ Load the given TLS tickets key on all compatible frontends (DOH and TLS).
Parameters: key (str) – The new raw TLS tickets key to use.
-
reloadAllCertificates
()¶ New in version 1.4.0.
Reload all DNSCrypt and TLS certificates, along with their associated keys.
-
setSyslogFacility
(facility)¶ New in version 1.4.0.
Changed in version 1.6.0:
facility
can now be a string.Set the syslog logging facility to
facility
.Parameters: or str facility (int) – The new facility as a numeric value (raw value as defined in syslog.h), or as a case-insensitive string (“LOCAL0”, or “daemon”, for example). Defaults to LOG_DAEMON.
Listen Sockets¶
-
addLocal
(address[, options])¶ Changed in version 1.4.0: Removed
doTCP
from the options. A listen socket on TCP is always created.Changed in version 1.5.0: Added
tcpListenQueueSize
parameter.Changed in version 1.6.0: Added
maxInFlight
andmaxConcurrentTCPConnections
parameters.Changed in version 1.9.0: Added the
enableProxyProtocol
parameter, which was alwaystrue
before 1.9.0, and the``xskSocket`` one.Add to the list of listen addresses. Note that for IPv6 link-local addresses, it might be necessary to specify the interface to use:
fe80::1%eth0
. On recent Linux versions specifying the interface via theinterface
parameter should work as well.Parameters: - address (str) – The IP Address with an optional port to listen on. The default port is 53.
- options (table) – A table with key: value pairs with listen options.
Options:
doTCP=true
: bool - Also bind on TCP onaddress
. Removed in 1.4.0.reusePort=false
: bool - Set theSO_REUSEPORT
socket option.tcpFastOpenQueueSize=0
: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.interface=""
: str - Set the network interface to use.cpus={}
: table - Set the CPU affinity for this listener thread, asking the scheduler to run it on a single CPU id, or a set of CPU ids. This parameter is only available if the OS provides the pthread_setaffinity_np() function.tcpListenQueueSize=SOMAXCONN
: int - Set the size of the listen queue. Default isSOMAXCONN
.maxInFlight=0
: int - Maximum number of in-flight queries. The default is 0, which disables out-of-order processing.maxConcurrentTCPConnections=0
: int - Maximum number of concurrent incoming TCP connections. The default is 0 which means unlimited.enableProxyProtocol=true
: str - Whether to expect a proxy protocol v2 header in front of incoming queries coming from an address insetProxyProtocolACL()
. Default istrue
, meaning that queries are expected to have a proxy protocol payload if they come from an address present in thesetProxyProtocolACL()
ACL.xskSocket
:XskSocket
- A socket to enableXSK
/AF_XDP
support for this frontend. See AF_XDP / XSK for more information.
addLocal('0.0.0.0:5300', { reusePort=true })
This will bind to both UDP and TCP on port 5300 with SO_REUSEPORT enabled.
-
addDOHLocal
(address[, certFile(s)[, keyFile(s)[, urls[, options]]]])¶ New in version 1.4.0.
Changed in version 1.5.0:
internalPipeBufferSize
,sendCacheControlHeaders
,sessionTimeout
,trustForwardedForHeader
options added.url
now defaults to/dns-query
instead of/
, and does exact matching instead of accepting sub-paths. AddedtcpListenQueueSize
parameter.Changed in version 1.6.0:
enableRenegotiation
,exactPathMatching
,maxConcurrentTCPConnections
andreleaseBuffers
options added.internalPipeBufferSize
now defaults to 1048576 on Linux.Changed in version 1.8.0:
certFile
now accepts aTLSCertificate
object or a list of such objects (seenewTLSCertificate()
)additionalAddresses
,ignoreTLSConfigurationErrors
andkeepIncomingHeaders
options added.Changed in version 1.9.0:
enableProxyProtocol
,ktls
,library
,proxyProtocolOutsideTLS
,readAhead
,tlsAsyncMode
options added.Listen on the specified address and TCP port for incoming DNS over HTTPS connections, presenting the specified X.509 certificate. See TLS Certificates Management for details about the handling of TLS certificates and keys. If no certificate (or key) files are specified, listen for incoming DNS over HTTP connections instead. More information is available in DNS-over-HTTPS (DoH).
Parameters: - address (str) – The IP Address with an optional port to listen on. The default port is 443.
- certFile(s) (str) – The path to a X.509 certificate file in PEM format, a list of paths to such files, or a
TLSCertificate
object. - keyFile(s) (str) – The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if
certFile
containsTLSCertificate
objects. - urls (str-or-list) – The path part of a URL, or a list of paths, to accept queries on. Any query with a path matching exactly one of these will be treated as a DoH query (sub-paths can be accepted by setting the
exactPathMatching
to false). The default is /dns-query. - options (table) – A table with key: value pairs with listen options.
Options:
reusePort=false
: bool - Set theSO_REUSEPORT
socket option.tcpFastOpenQueueSize=0
: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.interface=""
: str - Set the network interface to use.cpus={}
: table - Set the CPU affinity for this listener thread, asking the scheduler to run it on a single CPU id, or a set of CPU ids. This parameter is only available if the OS provides the pthread_setaffinity_np() function.idleTimeout=30
: int - Set the idle timeout, in seconds.ciphers
: str - The TLS ciphers to use, in OpenSSL format. Ciphers for TLS 1.3 must be specified viaciphersTLS13
.ciphersTLS13
: str - The TLS ciphers to use for TLS 1.3, in OpenSSL format.serverTokens
: str - The content of the Server: HTTP header returned by dnsdist. The default is “h2o/dnsdist” whenh2o
is used, “nghttp2-<version>/dnsdist” whennghttp2
is.customResponseHeaders={}
: table - Set custom HTTP header(s) returned by dnsdist.ocspResponses
: list - List of files containing OCSP responses, in the same order than the certificates and keys, that will be used to provide OCSP stapling responses.minTLSVersion
: str - Minimum version of the TLS protocol to support. Possible values are ‘tls1.0’, ‘tls1.1’, ‘tls1.2’ and ‘tls1.3’. Default is to require at least TLS 1.0.numberOfTicketsKeys
: int - The maximum number of tickets keys to keep in memory at the same time. Only one key is marked as active and used to encrypt new tickets while the remaining ones can still be used to decrypt existing tickets after a rotation. Default to 5.ticketKeyFile
: str - The path to a file from where TLS tickets keys should be loaded, to support RFC 5077. These keys should be rotated often and never written to persistent storage to preserve forward secrecy. The default is to generate a random key. dnsdist supports several tickets keys to be able to decrypt existing sessions after the rotation. See TLS Sessions Management for more information.ticketsKeysRotationDelay
: int - Set the delay before the TLS tickets key is rotated, in seconds. Default is 43200 (12h). A value of 0 disables the automatic rotation, which might be useful whenticketKeyFile
is used.sessionTimeout
: int - Set the TLS session lifetime in seconds, this is used both for TLS ticket lifetime and for sessions kept in memory.sessionTickets
: bool - Whether session resumption via session tickets is enabled. Default is true, meaning tickets are enabled.numberOfStoredSessions
: int - The maximum number of sessions kept in memory at the same time. Default is 20480. Setting this value to 0 disables stored session entirely.preferServerCiphers
: bool - Whether to prefer the order of ciphers set by the server instead of the one set by the client. Default is true, meaning that the order of the server is used. For OpenSSL >= 1.1.1, setting this option also enables the temporary re-prioritization of the ChaCha20-Poly1305 cipher if the client prioritizes it.keyLogFile
: str - Write the TLS keys in the specified file so that an external program can decrypt TLS exchanges, in the format described in https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format. Note that this feature requires OpenSSL >= 1.1.1.sendCacheControlHeaders
: bool - Whether to parse the response to find the lowest TTL and set a HTTP Cache-Control header accordingly. Default is true.trustForwardedForHeader
: bool - Whether to parse any existing X-Forwarded-For header in the HTTP query and use the right-most value as the client source address and port, for ACL checks, rules, logging and so on. Default is false.tcpListenQueueSize=SOMAXCONN
: int - Set the size of the listen queue. Default isSOMAXCONN
.internalPipeBufferSize=0
: int - Set the size in bytes of the internal buffer of the pipes used internally to pass queries and responses between threads. Requires support forF_SETPIPE_SZ
which is present in Linux since 2.6.35. The actual size might be rounded up to a multiple of a page size. 0 means that the OS default size is used. The default value is 0, except on Linux where it is 1048576 since 1.6.0.exactPathMatching=true
: bool - Whether to do exact path matching of the query path against the paths configured inurls
(true, the default since 1.5.0) or to accepts sub-paths (false, and was the default before 1.5.0). This option was introduced in 1.6.0.maxConcurrentTCPConnections=0
: int - Maximum number of concurrent incoming TCP connections. The default is 0 which means unlimited.releaseBuffers=true
: bool - Whether OpenSSL should release its I/O buffers when a connection goes idle, saving roughly 35 kB of memory per connection.enableRenegotiation=false
: bool - Whether secure TLS renegotiation should be enabled. Disabled by default since it increases the attack surface and is seldom used for DNS.keepIncomingHeaders
: bool - Whether to retain the incoming headers in memory, to be able to useHTTPHeaderRule()
orDNSQuestion.getHTTPHeaders()
. Default is false. Before 1.8.0 the headers were always kept in-memory.additionalAddresses
: list - List of additional addresses (with port) to listen on. Using this option instead of creating a new frontend for each address avoids the creation of new thread and Frontend objects, reducing the memory usage. The drawback is that there will be a single set of metrics for all addresses.ignoreTLSConfigurationErrors=false
: bool - Ignore TLS configuration errors (such as invalid certificate path) and just issue a warning instead of aborting the whole processlibrary
: str - Which underlying HTTP2 library should be used, either h2o or nghttp2. Until 1.9.0 only h2o was available, but the use of this library is now deprecated as it is no longer maintained. nghttp2 is the new default since 1.9.0.ktls=false
: bool - Whether to enable the experimental kernel TLS support on Linux, if both the kernel and the OpenSSL library support it. Default is false.tlsAsyncMode=false
: bool - Whether to enable experimental asynchronous TLS I/O operations if thenghttp2
library is used,OpenSSL
is used as the TLS implementation and an asynchronous capable SSL engine (or provider) is loaded. See alsoloadTLSEngine()
orloadTLSProvider()
to load the engine (or provider).readAhead
: bool - When the TLS provider is set to OpenSSL, whether we tell the library to read as many input bytes as possible, which leads to better performance by reducing the number of syscalls. Default is true.proxyProtocolOutsideTLS
: bool - When the use of incoming proxy protocol is enabled, whether the payload is prepended after the start of the TLS session (so inside, meaning it is protected by the TLS layer providing encryption and authentication) or not (outside, meaning it is in clear-text). Default is false which means inside. Note that most third-party software like HAproxy expect the proxy protocol payload to be outside, in clear-text.enableProxyProtocol=true
: bool - Whether to expect a proxy protocol v2 header in front of incoming queries coming from an address insetProxyProtocolACL()
. Default istrue
, meaning that queries are expected to have a proxy protocol payload if they come from an address present in thesetProxyProtocolACL()
ACL.
-
addDOH3Local
(address, certFile(s), keyFile(s)[, options])¶ New in version 1.9.0.
Listen on the specified address and UDP port for incoming DNS over HTTP3 connections, presenting the specified X.509 certificate. See TLS Certificates Management for details about the handling of TLS certificates and keys. More information is available in DNS-over-HTTP/3 (DoH3).
Parameters: - address (str) – The IP Address with an optional port to listen on. The default port is 443.
- certFile(s) (str) – The path to a X.509 certificate file in PEM format, a list of paths to such files, or a
TLSCertificate
object. - keyFile(s) (str) – The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if
certFile
containsTLSCertificate
objects. - options (table) – A table with key: value pairs with listen options.
Options:
reusePort=false
: bool - Set theSO_REUSEPORT
socket option.interface=""
: str - Set the network interface to use.cpus={}
: table - Set the CPU affinity for this listener thread, asking the scheduler to run it on a single CPU id, or a set of CPU ids. This parameter is only available if the OS provides the pthread_setaffinity_np() function.idleTimeout=5
: int - Set the idle timeout, in seconds.internalPipeBufferSize=0
: int - Set the size in bytes of the internal buffer of the pipes used internally to pass queries and responses between threads. Requires support forF_SETPIPE_SZ
which is present in Linux since 2.6.35. The actual size might be rounded up to a multiple of a page size. 0 means that the OS default size is used. The default value is 0, except on Linux where it is 1048576 since 1.6.0.maxInFlight=65535
: int - Maximum number of in-flight queries. The default is 0, which disables out-of-order processing.congestionControlAlgo="reno"
: str - The congestion control algorithm to be chosen betweenreno
,cubic
andbbr
.keyLogFile
: str - Write the TLS keys in the specified file so that an external program can decrypt TLS exchanges, in the format described in https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format.
-
addDOQLocal
(address, certFile(s), keyFile(s)[, options])¶ New in version 1.9.0.
Listen on the specified address and UDP port for incoming DNS over QUIC connections, presenting the specified X.509 certificate. See TLS Certificates Management for details about the handling of TLS certificates and keys. More information is available at DNS-over-QUIC (DoQ).
Parameters: - address (str) – The IP Address with an optional port to listen on. The default port is 853.
- certFile(s) (str) – The path to a X.509 certificate file in PEM format, a list of paths to such files, or a
TLSCertificate
object. - keyFile(s) (str) – The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if
certFile
containsTLSCertificate
objects. - options (table) – A table with key: value pairs with listen options.
Options:
reusePort=false
: bool - Set theSO_REUSEPORT
socket option.interface=""
: str - Set the network interface to use.cpus={}
: table - Set the CPU affinity for this listener thread, asking the scheduler to run it on a single CPU id, or a set of CPU ids. This parameter is only available if the OS provides the pthread_setaffinity_np() function.idleTimeout=5
: int - Set the idle timeout, in seconds.internalPipeBufferSize=0
: int - Set the size in bytes of the internal buffer of the pipes used internally to pass queries and responses between threads. Requires support forF_SETPIPE_SZ
which is present in Linux since 2.6.35. The actual size might be rounded up to a multiple of a page size. 0 means that the OS default size is used. The default value is 0, except on Linux where it is 1048576 since 1.6.0.maxInFlight=65535
: int - Maximum number of in-flight queries. The default is 0, which disables out-of-order processing.congestionControlAlgo="reno"
: str - The congestion control algorithm to be chosen betweenreno
,cubic
andbbr
.keyLogFile
: str - Write the TLS keys in the specified file so that an external program can decrypt TLS exchanges, in the format described in https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format.
-
addTLSLocal
(address, certFile(s), keyFile(s)[, options])¶ Changed in version 1.4.0:
ciphersTLS13
,minTLSVersion
,ocspResponses
,preferServerCiphers
,keyLogFile
options added.Changed in version 1.5.0:
sessionTimeout
andtcpListenQueueSize
options added.Changed in version 1.6.0:
enableRenegotiation
,maxConcurrentTCPConnections
,maxInFlight
andreleaseBuffers
options added.Changed in version 1.8.0:
tlsAsyncMode
option added.Changed in version 1.8.0:
certFile
now accepts aTLSCertificate
object or a list of such objects (seenewTLSCertificate()
).additionalAddresses
,ignoreTLSConfigurationErrors
andktls
options added.Changed in version 1.9.0:
enableProxyProtocol
,readAhead
andproxyProtocolOutsideTLS
options added.Listen on the specified address and TCP port for incoming DNS over TLS connections, presenting the specified X.509 certificate. See TLS Certificates Management for details about the handling of TLS certificates and keys. More information is available at DNS-over-TLS.
Parameters: - address (str) – The IP Address with an optional port to listen on. The default port is 853.
- certFile(s) (str) – The path to a X.509 certificate file in PEM format, a list of paths to such files, or a
TLSCertificate
object. - keyFile(s) (str) – The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if
certFile
containsTLSCertificate
objects. - options (table) – A table with key: value pairs with listen options.
Options:
reusePort=false
: bool - Set theSO_REUSEPORT
socket option.tcpFastOpenQueueSize=0
: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.interface=""
: str - Set the network interface to use.cpus={}
: table - Set the CPU affinity for this listener thread, asking the scheduler to run it on a single CPU id, or a set of CPU ids. This parameter is only available if the OS provides the pthread_setaffinity_np() function.provider
: str - The TLS library to use between GnuTLS and OpenSSL, if they were available and enabled at compilation time. Default is to use OpenSSL when available.ciphers
: str - The TLS ciphers to use. The exact format depends on the provider used. When the OpenSSL provider is used, ciphers for TLS 1.3 must be specified viaciphersTLS13
.ciphersTLS13
: str - The ciphers to use for TLS 1.3, when the OpenSSL provider is used. When the GnuTLS provider is used,ciphers
applies regardless of the TLS protocol and this setting is not used.numberOfTicketsKeys
: int - The maximum number of tickets keys to keep in memory at the same time, if the provider supports it (GnuTLS doesn’t, OpenSSL does). Only one key is marked as active and used to encrypt new tickets while the remaining ones can still be used to decrypt existing tickets after a rotation. Default to 5.ticketKeyFile
: str - The path to a file from where TLS tickets keys should be loaded, to support RFC 5077. These keys should be rotated often and never written to persistent storage to preserve forward secrecy. The default is to generate a random key. The OpenSSL provider supports several tickets keys to be able to decrypt existing sessions after the rotation, while the GnuTLS provider only supports one key. See TLS Sessions Management for more information.ticketsKeysRotationDelay
: int - Set the delay before the TLS tickets key is rotated, in seconds. Default is 43200 (12h). A value of 0 disables the automatic rotation, which might be useful whenticketKeyFile
is used.sessionTimeout
: int - Set the TLS session lifetime in seconds, this is used both for TLS ticket lifetime and for sessions kept in memory.sessionTickets
: bool - Whether session resumption via session tickets is enabled. Default is true, meaning tickets are enabled.numberOfStoredSessions
: int - The maximum number of sessions kept in memory at the same time. At this time this is only supported by the OpenSSL provider, as stored sessions are not supported with the GnuTLS one. Default is 20480. Setting this value to 0 disables stored session entirely.ocspResponses
: list - List of files containing OCSP responses, in the same order than the certificates and keys, that will be used to provide OCSP stapling responses.minTLSVersion
: str - Minimum version of the TLS protocol to support. Possible values are ‘tls1.0’, ‘tls1.1’, ‘tls1.2’ and ‘tls1.3’. Default is to require at least TLS 1.0. Note that this value is ignored when the GnuTLS provider is in use, and theciphers
option should be set accordingly instead. For example, ‘NORMAL:!VERS-TLS1.0:!VERS-TLS1.1’ will disable TLS 1.0 and 1.1.preferServerCiphers
: bool - Whether to prefer the order of ciphers set by the server instead of the one set by the client. Default is true, meaning that the order of the server is used. For OpenSSL >= 1.1.1, setting this option also enables the temporary re-prioritization of the ChaCha20-Poly1305 cipher if the client prioritizes it.keyLogFile
: str - Write the TLS keys in the specified file so that an external program can decrypt TLS exchanges, in the format described in https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format. Note that this feature requires OpenSSL >= 1.1.1.tcpListenQueueSize=SOMAXCONN
: int - Set the size of the listen queue. Default isSOMAXCONN
.maxInFlight=0
: int - Maximum number of in-flight queries. The default is 0, which disables out-of-order processing.maxConcurrentTCPConnections=0
: int - Maximum number of concurrent incoming TCP connections. The default is 0 which means unlimited.releaseBuffers=true
: bool - Whether OpenSSL should release its I/O buffers when a connection goes idle, saving roughly 35 kB of memory per connection.enableRenegotiation=false
: bool - Whether secure TLS renegotiation should be enabled (OpenSSL only, the GnuTLS provider does not support it). Disabled by default since it increases the attack surface and is seldom used for DNS.tlsAsyncMode=false
: bool - Whether to enable experimental asynchronous TLS I/O operations if OpenSSL is used as the TLS implementation and an asynchronous capable SSL engine (or provider) is loaded. See alsoloadTLSEngine()
orloadTLSProvider()
to load the engine (or provider).additionalAddresses
: list - List of additional addresses (with port) to listen on. Using this option instead of creating a new frontend for each address avoids the creation of new thread and Frontend objects, reducing the memory usage. The drawback is that there will be a single set of metrics for all addresses.ignoreTLSConfigurationErrors=false
: bool - Ignore TLS configuration errors (such as invalid certificate path) and just issue a warning instead of aborting the whole processktls=false
: bool - Whether to enable the experimental kernel TLS support on Linux, if both the kernel and the OpenSSL library support it. Default is false.readAhead
: bool - When the TLS provider is set to OpenSSL, whether we tell the library to read as many input bytes as possible, which leads to better performance by reducing the number of syscalls. Default is true.proxyProtocolOutsideTLS
: bool - When the use of incoming proxy protocol is enabled, whether the payload is prepended after the start of the TLS session (so inside, meaning it is protected by the TLS layer providing encryption and authentication) or not (outside, meaning it is in clear-text). Default is false which means inside. Note that most third-party software like HAproxy expect the proxy protocol payload to be outside, in clear-text.enableProxyProtocol=true
: str - Whether to expect a proxy protocol v2 header in front of incoming queries coming from an address insetProxyProtocolACL()
. Default istrue
, meaning that queries are expected to have a proxy protocol payload if they come from an address present in thesetProxyProtocolACL()
ACL.
-
setLocal
(address[, options])¶ Remove the list of listen addresses and add a new one.
Parameters: - address (str) – The IP Address with an optional port to listen on. The default port is 53.
- options (table) – A table with key: value pairs with listen options.
The options that can be set are the same as
addLocal()
.
Control Socket, Console and Webserver¶
-
addConsoleACL
(netmask)¶ 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
setKey()
before doing so. The default is to only allow 127.0.0.1/8 and ::1/128.Parameters: netmask (str) – A CIDR netmask, e.g. "192.0.2.0/24"
. Without a subnetmask, only the specific address is allowed.
-
clearConsoleHistory
()¶ New in version 1.6.0.
Clear the internal (in-memory) buffers of console commands. These buffers are used to provide the
delta()
command and console completion and history, and can end up being quite large when a lot of commands are issued via the console, consuming a noticeable amount of memory.
-
controlSocket
(address)¶ Bind to
addr
and listen for a connection for the console. Since 1.3.0 only connections from local users are allowed by default,addConsoleACL()
andsetConsoleACL()
can be used to enable remote connections. Please make sure that encryption has been enabled withsetKey()
before doing so. Enabling encryption is also strongly advised for local connections, since not enabling it allows any local user to connect to the console.Parameters: address (str) – An IP address with optional port. By default, the port is 5199.
-
delta
()¶ Issuing delta on the console will print the changes to the configuration that have been made since startup.
-
inClientStartup
()¶ Returns true while the console client is parsing the configuration.
-
inConfigCheck
()¶ New in version 1.5.0.
Returns true while the configuration is being checked, ie when run with
--check-config
.
-
makeKey
()¶ Generate and print an encryption key.
-
setConsoleConnectionsLogging
(enabled)¶ Whether to log the opening and closing of console connections.
Parameters: enabled (bool) – Default to true.
-
setConsoleMaximumConcurrentConnections
(max)¶ New in version 1.6.0.
Set the maximum number of concurrent console connections.
Parameters: max (int) – The maximum number of concurrent console connections, or 0 which means an unlimited number. Defaults to 100
-
setKey
(key)¶ Use
key
as shared secret between the client and the serverParameters: key (str) – An encoded key, as generated by makeKey()
-
setConsoleACL
(netmasks)¶ 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
setKey()
before doing so.Parameters: netmasks ({str}) – A table of CIDR netmask, e.g. {"192.0.2.0/24", "2001:DB8:14::/56"}
. Without a subnetmask, only the specific address is allowed.
-
showConsoleACL
()¶ Print a list of all netmasks allowed to connect to the console.
-
testCrypto
()¶ Test the crypto code, will report errors when something is not ok.
-
setConsoleOutputMaxMsgSize
(size)¶ Set the maximum size in bytes of a single console message, default set to 10 MB.
Parameters: size (int) – The new maximum size.
Webserver configuration¶
-
hashPassword
(password[, workFactor])¶ New in version 1.7.0.
Hash the supplied password using a random salt, and returns a string that can be used with
setWebserverConfig()
. For example, to get a hashed version of thetest
password:> hashPassword('test') $scrypt$ln=10,p=1,r=8$RSYJ2QDmdlkNYMyqZF/FWw==$JQTftQCvAXR4Qtrg0lQmvrzgYEo3/PjEeuV4/2Oq1Vg=
The full string can then be used with
setWebserverConfig()
:setWebserverConfig({password="$scrypt$ln=10,p=1,r=8$RSYJ2QDmdlkNYMyqZF/FWw==$JQTftQCvAXR4Qtrg0lQmvrzgYEo3/PjEeuV4/2Oq1Vg=", apiKey="$scrypt$ln=10,p=1,r=8$RSYJ2QDmdlkNYMyqZF/FWw==$JQTftQCvAXR4Qtrg0lQmvrzgYEo3/PjEeuV4/2Oq1Vg=", acl="127.0.0.1/32"})
Parameters: - password (string) – The password to hash
- workFactor (int) – The work factor to use for the hash function (currently scrypt), as a power of two. Default is 1024.
-
webserver
(listen_address[, password[, apikey[, customHeaders[, acl]]]])¶ Changed in version 1.5.0:
acl
optional parameter added.Changed in version 1.6.0: The
password
parameter is now optional. The use of optional parameters is now deprecated. Please usesetWebserverConfig()
instead.Changed in version 1.8.0: The
password
,apikey
,customHeaders
andacl
parameters is no longer supported. Please usesetWebserverConfig()
instead.Launch the Built-in webserver with statistics and the API. Note that the parameters are global, so the parameter from the last
webserver
will override any existing ones. For this reasonsetWebserverConfig()
should be used instead of specifying optional parameters here.Parameters: - listen_address (str) – The IP address and Port to listen on
- password (str) – The password required to access the webserver
- apikey (str) – The key required to access the API
- customHeaders ({[str]=str,...}) – Allows setting custom headers and removing the defaults
- acl (str) – List of netmasks, as a string, that are allowed to open a connection to the web server. Defaults to “127.0.0.1, ::1”. It accepts the same syntax that
NetmaskGroup:addMask()
does
-
setAPIWritable
(allow[, dir])¶ Allow modifications via the API. Optionally saving these changes to disk. Modifications done via the API will not be written to the configuration by default and will not persist after a reload
Parameters: - allow (bool) – Set to true to allow modification through the API
- dir (str) – A valid directory where the configuration files will be written by the API.
-
setWebserverConfig
(options)¶ Changed in version 1.5.0:
acl
optional parameter added.Changed in version 1.6.0:
statsRequireAuthentication
,maxConcurrentConnections
optional parameters added.Changed in version 1.7.0: The optional
password
andapiKey
parameters now accept hashed passwords. The optionalhashPlaintextCredentials
parameter has been added.Changed in version 1.8.0:
apiRequiresAuthentication
,dashboardRequiresAuthentication
optional parameters added.Setup webserver configuration. See
webserver()
.Parameters: options (table) – A table with key: value pairs with webserver options. Options:
password=newPassword
: string - Set the password used to access the internal webserver. Since 1.7.0 the password should be hashed and salted via thehashPassword()
command.apiKey=newKey
: string - Changes the API Key (set to an empty string do disable it). Since 1.7.0 the key should be hashed and salted via thehashPassword()
command.customHeaders={[str]=str,...}
: map of string - Allows setting custom headers and removing the defaults.acl=newACL
: string - List of IP addresses, as a string, that are allowed to open a connection to the web server. Defaults to “127.0.0.1, ::1”.apiRequiresAuthentication
: bool - Whether access to the API (/api endpoints) require a valid API key. Defaults to true.dashboardRequiresAuthentication
: bool - Whether access to the internal dashboard requires a valid password. Defaults to true.statsRequireAuthentication
: bool - Whether access to the statistics (/metrics and /jsonstat endpoints) require a valid password or API key. Defaults to true.maxConcurrentConnections
: int - The maximum number of concurrent web connections, or 0 which means an unlimited number. Defaults to 100.hashPlaintextCredentials
: bool - Whether passwords and API keys provided in plaintext should be hashed during startup, to prevent the plaintext versions from staying in memory. Doing so increases significantly the cost of verifying credentials. Defaults to false.
-
registerWebHandler
(path, handler)¶ Register a function named
handler
that will be called for every query sent to the exactpath
path. The function will receive aWebRequest
object and aWebResponse
object, representing respectively the HTTP request received and the HTTP response to send. For example a handler registered for ‘/foo’ will receive these queries:GET /foo
POST /foo
GET /foo?param=1
But not queries for /foobar or /foo/bar.
A sample handler function could be:
function customHTTPHandler(req, resp) local get = req.getvars local headers = req.headers if req.path ~= '/foo' or req.version ~= 11 or req.method ~= 'GET' or get['param'] ~= '42' or headers['custom'] ~= 'foobar' then resp.status = 500 return end resp.status = 200 resp.body = 'It works!' resp.headers = { ['Foo']='Bar'} end registerWebHandler('/foo', customHTTPHandler)
Parameters: - path (str) – Path to register the handler for.
- handler (function) – The Lua function to register.
-
showWebserverConfig
()¶ New in version 1.7.0.
Show the current webserver configuration. See
webserver()
.
Access Control Lists¶
-
addACL
(netmask)¶ Add a netmask to the existing ACL controlling which clients can send UDP, TCP, DNS over TLS and DNS over HTTPS queries. See Access Control for more information.
Parameters: netmask (str) – A CIDR netmask, e.g. "192.0.2.0/24"
. Without a subnetmask, only the specific address is allowed.
-
rmACL
(netmask)¶ Remove a network from the existing ACL controlling which clients can send UDP, TCP, DNS over TLS and DNS over HTTPS queries. See Access Control for more information. This function only removes previously added entries, it does not remove subnets of entries.
Parameters: netmask (str) – A CIDR netmask, e.g. "192.0.2.0/24"
. Without a subnetmask, only the specific address is allowed.addACL("192.0.2.0/24") -- for example add subnet to the ACL rmACL("192.0.2.10") -- does NOT work, the ACL is unchanged rmACL("192.0.2.0/24") -- does work, the exact match is removed from the ACL
-
setACL
(netmasks)¶ Remove the existing ACL and add the netmasks from the table of those allowed to send UDP, TCP, DNS over TLS and DNS over HTTPS queries. See Access Control for more information.
Parameters: netmasks ({str}) – A table of CIDR netmask, e.g. {"192.0.2.0/24", "2001:DB8:14::/56"}
. Without a subnetmask, only the specific address is allowed.
-
setACLFromFile
(fname)¶ New in version 1.6.0.
Reset the ACL to the list of netmasks from the given file. See Access Control for more information.
Parameters: fname (str) – The path to a file containing a list of netmasks. Empty lines or lines starting with “#” are ignored.
-
setProxyProtocolACL
(netmasks)¶ New in version 1.6.0.
Set the list of netmasks from which a Proxy Protocol header will be required, over UDP, TCP and DNS over TLS. The default is empty. Note that a proxy protocol payload will be required from these clients, regular DNS queries will no longer be accepted if they are not preceded by a proxy protocol payload. Be also aware that, if
setProxyProtocolApplyACLToProxiedClients()
is set (default is false), the general ACL will be applied to the source IP address as seen by dnsdist first, but also to the source IP address provided in the Proxy Protocol header.Parameters: netmasks ({str}) – A table of CIDR netmask, e.g. {"192.0.2.0/24", "2001:DB8:14::/56"}
. Without a subnetmask, only the specific address is allowed.
-
setProxyProtocolApplyACLToProxiedClients
(apply)¶ New in version 1.6.0.
Whether the general ACL should be applied to the source IP address provided in the Proxy Protocol header, in addition to being applied to the source IP address as seen by dnsdist first.
Parameters: apply (bool) – Whether it should be applied or not (default is false).
-
showACL
()¶ Print a list of all netmasks allowed to send queries over UDP, TCP, DNS over TLS and DNS over HTTPS. See Access Control for more information.
EDNS Client Subnet¶
-
setECSOverride
(bool)¶ When
useClientSubnet
innewServer()
is set and dnsdist adds an EDNS Client Subnet Client option to the query, override an existing option already present in the query, if any. Please see Passing the source address to the backend for more information. Note that it’s not recommended to enablesetECSOverride
in front of an authoritative server responding with EDNS Client Subnet information as mismatching data (ECS scopes) can confuse clients and lead to SERVFAIL responses on downstream nameservers.Parameters: bool – Whether to override an existing EDNS Client Subnet option present in the query. Defaults to false
-
setECSSourcePrefixV4
(prefix)¶ When
useClientSubnet
innewServer()
is set and dnsdist adds an EDNS Client Subnet Client option to the query, truncate the requestors IPv4 address toprefix
bitsParameters: prefix (int) – The prefix length
-
setECSSourcePrefixV6
(prefix)¶ When
useClientSubnet
innewServer()
is set and dnsdist adds an EDNS Client Subnet Client option to the query, truncate the requestor’s IPv6 address to bitsParameters: prefix (int) – The prefix length
Ringbuffers¶
-
setRingBuffersLockRetries
(num)¶ Deprecated since version 1.8.0: Deprecated in 1.8.0 in favor of
setRingBuffersOptions()
which provides more options.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
Parameters: num (int) – The maximum number of attempts. Defaults to 5 if there is more than one shard, 0 otherwise.
-
setRingBuffersOptions
(options)¶ New in version 1.8.0.
Set the rings buffers configuration
Parameters: options (table) – A table with key: value pairs with options. Options:
lockRetries
: int - 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. Default to 5 if there is more than one shard, 0 otherwiserecordQueries
: boolean - Whether to record queries in the ring buffers. Default is true. Note thatgrepq()
, several top* commands (topClients()
,topQueries()
, …) and the Dynamic Blocks require this to be enabled.recordResponses
: boolean - Whether to record responses in the ring buffers. Default is true. Note thatgrepq()
, several top* commands (topResponses()
,topSlow()
, …) and the Dynamic Blocks require this to be enabled.
-
setRingBuffersSize
(num[, numberOfShards])¶ Changed in version 1.6.0:
numberOfShards
defaults to 10.Set the capacity of the ringbuffers used for live traffic inspection to
num
, and the number of shards tonumberOfShards
if specified. Increasing the number of entries comes at both a memory cost (around 250 MB for 1 million entries) and a CPU processing cost, so we strongly advise not going over 1 million entries.Parameters: - num (int) – The maximum amount of queries to keep in the ringbuffer. Defaults to 10000
- numberOfShards (int) – the number of shards to use to limit lock contention. Default is 10, used to be 1 before 1.6.0
Servers¶
-
newServer
(server_string)¶ -
newServer
(server_table) Changed in version 1.4.0: Added
checkInterval
,checkTimeout
andrise
to server_table.Changed in version 1.5.0: Added
useProxyProtocol
to server_table.Changed in version 1.6.0: Added
maxInFlight
to server_table.Changed in version 1.7.0: Added
addXForwardedHeaders
,caStore
,checkTCP
,ciphers
,ciphers13
,dohPath
,enableRenegotiation
,releaseBuffers
,subjectName
,tcpOnly
,tls
andvalidateCertificates
to server_table.Changed in version 1.8.0: Added
autoUpgrade
,autoUpgradeDoHKey
,autoUpgradeInterval
,autoUpgradeKeep
,autoUpgradePool
,maxConcurrentTCPConnections
,subjectAddr
,lazyHealthCheckSampleSize
,lazyHealthCheckMinSampleCount
,lazyHealthCheckThreshold
,lazyHealthCheckFailedInterval
,lazyHealthCheckMode
,lazyHealthCheckUseExponentialBackOff
,lazyHealthCheckMaxBackOff
,lazyHealthCheckWhenUpgraded
,healthCheckMode
andktls
to server_table.Changed in version 1.9.0: Added
MACAddr
,proxyProtocolAdvertiseTLS
andxskSockets
to server_table.Changed in version 2.0.0: Removed
addXPF
from server_table.Parameters: - server_string (str) – A simple IP:PORT string.
- server_table (table) – A table with at least an
address
key
Add a new backend server. Call this function with either a string:
newServer( "IP:PORT" -- IP and PORT of the backend server )
or a table:
newServer({ ... })
where the elements in the table can be:
Keyword Type Description address
ip:port
ip
andport
of the backend server (mandatory)id
string
Use a pre-defined UUID instead of a random one qps
number
Limit the number of queries per second to number
, when using the firstAvailable policyorder
number
The order of this server, used by the leastOutstanding and firstAvailable policies weight
number
The weight of this server, used by the wrandom, whashed and chashed policies, default: 1. Supported values are a minimum of 1, and a maximum of 2147483647. pool
string|{string}
The pools this server belongs to (unset or empty string means default pool) as a string or table of strings retries
number
The number of TCP connection attempts to the backend, for a given query tcpConnectTimeout
number
The timeout (in seconds) of a TCP connection attempt tcpSendTimeout
number
The timeout (in seconds) of a TCP write attempt tcpRecvTimeout
number
The timeout (in seconds) of a TCP read attempt tcpFastOpen
bool
Whether to enable TCP Fast Open ipBindAddrNoPort
bool
Whether to enable IP_BIND_ADDRESS_NO_PORT if available, default: true name
string
The name associated to this backend, for display purpose checkClass
number
Use number
as QCLASS in the health-check query, default: DNSClass.INcheckName
string
Use string
as QNAME in the health-check query, default:"a.root-servers.net."
checkType
string
Use string
as QTYPE in the health-check query, default:"A"
checkFunction
function
Use this function to dynamically set the QNAME, QTYPE and QCLASS to use in the health-check query (see Healthcheck) checkTimeout
number
The timeout (in milliseconds) of a health-check query, default: 1000 (1s) setCD
bool
Set the CD (Checking Disabled) flag in the health-check query, default: false maxCheckFailures
number
Allow number
check failures before declaring the backend down, default: 1checkInterval
number
The time in seconds between health checks mustResolve
bool
Set to true when the health check MUST return a RCODE different from NXDomain, ServFail and Refused. Default is false, meaning that every RCODE except ServFail is considered valid useClientSubnet
bool
Add the client’s IP address in the EDNS Client Subnet option when forwarding the query to this backend. Default is false. Please see Passing the source address to the backend for more information source
string
- The source address or interface to use for queries to this backend, by default this is left to the kernel’s address selection.
The following formats are supported:
- address, e.g.
"192.0.2.2"
- interface name, e.g.
"eth0"
- address@interface, e.g.
"192.0.2.2@eth0"
- address, e.g.
sockets
number
Number of UDP sockets (and thus source ports) used toward the backend server, defaults to a single one. Note that for backends which are multithreaded, this setting will have an effect on the number of cores that will be used to process traffic from dnsdist. For example you may want to set ‘sockets’ to a number somewhat higher than the number of worker threads configured in the backend, particularly if the Linux kernel is being used to distribute traffic to multiple threads listening on the same socket (via reuseport). See also setRandomizedOutgoingSockets()
.disableZeroScope
bool
Disable the EDNS Client Subnet EDNS Client Subnet Zero Scope feature, which does a cache lookup for an answer valid for all subnets (ECS scope of 0) before adding ECS information to the query and doing the regular lookup. Default is false. This requires the parseECS
option of the corresponding cache to be set to truerise
number
Require number
consecutive successful checks before declaring the backend up, default: 1useProxyProtocol
bool
Add a proxy protocol header to the query, passing along the client’s IP address and port along with the original destination address and port. Default is disabled. reconnectOnUp
bool
Close and reopen the sockets when a server transits from Down to Up. This helps when an interface is missing when dnsdist is started. Default is disabled. maxInFlight
number
Maximum number of in-flight queries. The default is 0, which disables out-of-order processing. It should only be enabled if the backend does support out-of-order processing. As of 1.6.0, out-of-order processing needs to be enabled on the frontend as well, via addLocal()
and/oraddTLSLocal()
. Note that out-of-order is always enabled on DoH frontends.tcpOnly
bool
Always forward queries to that backend over TCP, never over UDP. Always enabled for TLS backends. Default is false. checkTCP
bool
Whether to do healthcheck queries over TCP, instead of UDP. Always enabled for DNS over TLS backend. Default is false. tls
string
Enable DNS over TLS communications for this backend, or DNS over HTTPS if dohPath
is set, using the TLS provider ("openssl"
or"gnutls"
) passed in parameter. Default is an empty string, which means this backend is used for plain UDP and TCP.caStore
string
Specifies the path to the CA certificate file, in PEM format, to use to check the certificate presented by the backend. Default is an empty string, which means to use the system CA store. Note that this directive is only used if validateCertificates
is set.ciphers
string
The TLS ciphers to use. The exact format depends on the provider used. When the OpenSSL provider is used, ciphers for TLS 1.3 must be specified via ciphersTLS13
.ciphersTLS13
string
The ciphers to use for TLS 1.3, when the OpenSSL provider is used. When the GnuTLS provider is used, ciphers
applies regardless of the TLS protocol and this setting is not used.subjectName
string
The subject name passed in the SNI value of the TLS handshake, and against which to validate the certificate presented by the backend. Default is empty. If set this value supersedes any subjectAddr
one.subjectAddr
string
The subject IP address passed in the SNI value of the TLS handshake, and against which to validate the certificate presented by the backend. Default is empty. validateCertificates
bool
Whether the certificate presented by the backend should be validated against the CA store (see caStore
). Default is true.dohPath
string
Enable DNS over HTTPS communication for this backend, using POST queries to the HTTP host supplied as subjectName
and the HTTP path supplied in this parameter.addXForwardedHeaders
bool
Whether to add X-Forwarded-For, X-Forwarded-Port and X-Forwarded-Proto headers to a DNS over HTTPS backend. releaseBuffers
bool
Whether OpenSSL should release its I/O buffers when a connection goes idle, saving roughly 35 kB of memory per connection. Default to true. enableRenegotiation
bool
Whether secure TLS renegotiation should be enabled. Disabled by default since it increases the attack surface and is seldom used for DNS. autoUpgrade
bool
Whether to use the ‘Discovery of Designated Resolvers’ mechanism to automatically upgrade a Do53 backend to DoT or DoH, depending on the priorities present in the SVCB record returned by the backend. Default to false. autoUpgradeInterval
number
If autoUpgrade
is set, how often to check if an upgrade is available, in seconds. Default is 3600 seconds.autoUpgradeKeep
bool
If autoUpgrade
is set, whether to keep the existing Do53 backend around after an upgrade. Default is false which means the Do53 backend will be replaced by the upgraded one.autoUpgradePool
string
If autoUpgrade
is set, in which pool to place the newly upgraded backend. Default is empty which means the backend is placed in the default pool.autoUpgradeDoHKey
number
If autoUpgrade
is set, the value to use for the SVC key corresponding to the DoH path. Default is 7.maxConcurrentTCPConnections
number
Maximum number of TCP connections to that backend. When that limit is reached, queries routed to that backend that cannot be forwarded over an existing connection will be dropped. Default is 0 which means no limit. healthCheckMode
string
The health-check mode to use: ‘auto’ which sends health-check queries every checkInterval
seconds, ‘up’ which considers that the backend is always available, ‘down’ that it is always not available, and ‘lazy’ which only sends health-check queries after a configurable amount of regular queries have failed (seelazyHealthCheckSampleSize
,lazyHealthCheckMinSampleCount
,lazyHealthCheckThreshold
,lazyHealthCheckFailedInterval
andlazyHealthCheckMode
for more information). Default is ‘auto’. See Healthcheck for a more detailed explanation.lazyHealthCheckFailedInterval
number
The interval, in seconds, between health-check queries in ‘lazy’ mode. Note that when lazyHealthCheckUseExponentialBackOff
is set to true, the interval doubles between every queries. These queries are only sent when a threshold of failing regular queries has been reached, and until the backend is available again. Default is 30 seconds.lazyHealthCheckMinSampleCount
number
The minimum amount of regular queries that should have been recorded before the lazyHealthCheckThreshold
threshold can be applied. Default is 1 which means only one query is needed.lazyHealthCheckMode
string
The ‘lazy’ health-check mode: ‘TimeoutOnly’ means that only timeout and I/O errors of regular queries will be considered for the lazyHealthCheckThreshold
, while ‘TimeoutOrServFail’ will also consider ‘Server Failure’ answers. Default is ‘TimeoutOrServFail’.lazyHealthCheckSampleSize
number
The maximum size of the sample of queries to record and consider for the lazyHealthCheckThreshold
. Default is 100, which means the result (failure or success) of the last 100 queries will be considered.lazyHealthCheckThreshold
number
The threshold, as a percentage, of queries that should fail for the ‘lazy’ health-check to be triggered when healthCheckMode
is set tolazy
. The default is 20 which means 20% of the lastlazyHealthCheckSampleSize
queries should fail for a health-check to be triggered.lazyHealthCheckUseExponentialBackOff
bool
Whether the ‘lazy’ health-check should use an exponential back-off instead of a fixed value, between health-check probes. The default is false which means that after a backend has been moved to the ‘down’ state health-check probes are sent every lazyHealthCheckFailedInterval
seconds. When set to true, the delay between each probe starts atlazyHealthCheckFailedInterval
seconds and double between every probe, capped atlazyHealthCheckMaxBackOff
seconds.lazyHealthCheckMaxBackOff
number
This value, in seconds, caps the time between two health-check queries when lazyHealthCheckUseExponentialBackOff
is set to true. The default is 3600 which means that at most one hour will pass between two health-check queries.lazyHealthCheckWhenUpgraded
bool
Whether the auto-upgraded version of this backend (see autoUpgrade
) should use the lazy health-checking mode. Default is false, which means it will use the regular health-checking mode.ktls
bool
Whether to enable the experimental kernel TLS support on Linux, if both the kernel and the OpenSSL library support it. Default is false. Currently both DoT and DoH backend support this option. proxyProtocolAdvertiseTLS
bool
Whether to set the SSL Proxy Protocol TLV in the proxy protocol payload sent to the backend if the query was received over an encrypted channel (DNSCrypt, DoQ, DoH or DoT). Requires useProxyProtocol=true
. Default is false.xskSockets
array
An array of XskSocket
objects to enableXSK
/AF_XDP
support for this backend. See AF_XDP / XSK for more information.MACAddr
str
When the xskSocket
option is set, this parameter can be used to specify the destination MAC address to use to reach the backend. If this options is not specified, dnsdist will try to get it from the IP of the backend by looking into the system’s MAC address table, but it will fail if the corresponding MAC address is not present.
-
getServer
(index) → Server¶ Changed in version 1.5.0:
index
might be an UUID.Get a
Server
Parameters: or str index (int) – The number of the server (as seen in showServers()
) or its UUID as a string.Returns: The Server
object or nil
-
getServers
()¶ Returns a table with all defined servers.
-
rmServer
(index)¶ -
rmServer
(uuid) -
rmServer
(server) Changed in version 1.5.0:
uuid
selection added.Remove a backend server.
Parameters: - or str index (int) – The number of the server (as seen in
showServers()
), its UUID as a string, or a server object. - server (Server) – A
Server
object as returned by e.g.getServer()
.
- or str index (int) – The number of the server (as seen in
Server Functions¶
A server object returned by getServer()
can be manipulated with these functions.
-
class
Server
¶ This object represents a backend server. It has several methods.
-
:
addPool
(pool)¶ Add this server to a pool.
Parameters: pool (str) – The pool to add the server to
-
:
getLatency
() → double¶ New in version 1.6.0.
Return the average latency of this server over the last 128 UDP queries, in microseconds.
Returns: The number of outstanding queries
-
:
getName
() → string¶ Get the name of this server.
Returns: The name of the server, or an empty string if it does not have one
-
:
getNameWithAddr
() → string¶ Get the name plus IP address and port of the server
Returns: A string containing the server name if any plus the server address and port
-
:
getDrops
() → int¶ New in version 1.6.0.
Get the number of dropped queries for this server.
Returns: The number of dropped queries
-
:
getOutstanding
() → int¶ Get the number of outstanding queries for this server.
Returns: The number of outstanding queries
-
:
isUp
() → bool¶ Returns the up status of the server. Result is based on the administrative status of the server (as set by either
Server:setDown()
orServer:setUp()
). If no administrative status is set (seeServer:setAuto()
), result is based onServer.upStatus
Returns: true when the server is up, false otherwise
-
:
rmPool
(pool)¶ Removes the server from the named pool
Parameters: pool (str) – The pool to remove the server from
-
:
setAuto
([status])¶ Set the server in the default auto state. This will enable health check queries that will set the server
up
anddown
appropriately.Parameters: status (bool) – Set the initial status of the server to up
(true) ordown
(false) instead of using the last known status
-
:
setDown
()¶ Administratively set the server in a
DOWN
state. The server will not receive queries and the health checks are disabled.
-
:
setLazyAuto
([status])¶ New in version 1.8.0.
Set the server in the ‘lazy’ health-check mode. This will enable health check queries, but only after a configurable threshold of failing regular queries has been reached and only for a short time. See Healthcheck for a more detailed explanation.
Parameters: status (bool) – Set the initial status of the server to up
(true) ordown
(false) instead of using the last known status
-
:
setQPS
(limit)¶ Limit the queries per second for this server.
Parameters: limit (int) – The maximum number of queries per second
-
:
setUp
()¶ Administratively set the server in an
UP
state. This server will still receive queries and health checks are disabled
Apart from the functions, a
Server
object has these attributes:-
name
¶ The name of the server
-
upStatus
¶ Whether or not this server is
up
(true) ordown
(false) based on the last known state of health-checks.
-
order
¶ The order of the server
-
weight
¶ The weight of the server
-
Pools¶
Server
s can be part of any number of pools.
Pools are automatically created when a server is added to a pool (with newServer()
), or can be manually created with getPool()
.
Servers that are not assigned to a specific pool get assigned to the default pool that is always present, identified by the empty string ''
.
-
getPool
(name) → ServerPool¶ Returns a
ServerPool
. If the pool does not exist yet, it is created.Parameters: name (string) – The name of the pool
-
getPoolServers
(name) → [ Server ]¶ Returns a list of
Server
s or nil.Parameters: name (string) – The name of the pool
-
getPoolNames
() → [ table of names]¶ New in version 1.8.0.
Returns a table of all pool names
-
showPools
()¶ Display the name, associated cache, server policy and associated servers for every pool.
-
class
ServerPool
¶ This represents the pool where zero or more servers are part of.
-
:
getCache
() → PacketCache¶ Returns the
PacketCache
for this pool or nil.
-
:
getECS
()¶ 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
ServerPool:setECS()
.
-
:
setCache
(cache)¶ Adds
cache
as the pool’s cache.Parameters: cache (PacketCache) – The new cache to add to the pool
-
:
unsetCache
()¶ Removes the cache from this pool.
-
:
setECS
()¶ 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 and have EDNS Client Subnet enabled, since the queries in the cache will have been inserted with ECS information. Default is false.
-
PacketCache¶
A Pool can have a packet cache to answer queries directly instead of going to the backend. See Caching Responses for a how to.
-
newPacketCache
(maxEntries[, maxTTL=86400[, minTTL=0[, temporaryFailureTTL=60[, staleTTL=60[, dontAge=false[, numberOfShards=1[, deferrableInsertLock=true[, maxNegativeTTL=3600[, parseECS=false]]]]]]]) → PacketCache¶ Deprecated since version 1.4.0.
Creates a new
PacketCache
with the settings specified.Parameters: - maxEntries (int) – The maximum number of entries in this cache
- maxTTL (int) – Cap the TTL for records to his number
- minTTL (int) – Don’t cache entries with a TTL lower than this
- temporaryFailureTTL (int) – On a SERVFAIL or REFUSED from the backend, cache for this amount of seconds
- staleTTL (int) – When the backend servers are not reachable, and global configuration
setStaleCacheEntriesTTL
is set appropriately, TTL that will be used when a stale cache entry is returned - dontAge (bool) – Don’t reduce TTLs when serving from the cache. Use this when dnsdist fronts a cluster of authoritative servers
- numberOfShards (int) – Number of shards to divide the cache into, to reduce lock contention
- deferrableInsertLock (bool) – Whether the cache should give up insertion if the lock is held by another thread, or simply wait to get the lock
- maxNegativeTTL (int) – Cache a NXDomain or NoData answer from the backend for at most this amount of seconds, even if the TTL of the SOA record is higher
- parseECS (bool) – Whether any EDNS Client Subnet option present in the query should be extracted and stored to be able to detect hash collisions involving queries with the same qname, qtype and qclass but a different incoming ECS value. Enabling this option adds a parsing cost and only makes sense if at least one backend might send different responses based on the ECS value, so it’s disabled by default
-
newPacketCache
(maxEntries[, options]) → PacketCache New in version 1.4.0.
Changed in version 1.6.0:
cookieHashing
parameter added.numberOfShards
now defaults to 20.Changed in version 1.7.0:
skipOptions
parameter added.Changed in version 1.9.0:
maximumEntrySize
parameter added.Creates a new
PacketCache
with the settings specified.Parameters: maxEntries (int) – The maximum number of entries in this cache Options:
deferrableInsertLock=true
: bool - Whether the cache should give up insertion if the lock is held by another thread, or simply wait to get the lock.dontAge=false
: bool - Don’t reduce TTLs when serving from the cache. Use this when dnsdist fronts a cluster of authoritative servers.keepStaleData=false
: bool - Whether to suspend the removal of expired entries from the cache when there is no backend available in at least one of the pools using this cache.maxNegativeTTL=3600
: int - Cache a NXDomain or NoData answer from the backend for at most this amount of seconds, even if the TTL of the SOA record is higher.maxTTL=86400
: int - Cap the TTL for records to his number.minTTL=0
: int - Don’t cache entries with a TTL lower than this.numberOfShards=20
: int - Number of shards to divide the cache into, to reduce lock contention. Used to be 1 (no shards) before 1.6.0, and is now 20.parseECS=false
: bool - Whether any EDNS Client Subnet option present in the query should be extracted and stored to be able to detect hash collisions involving queries with the same qname, qtype and qclass but a different incoming ECS value. Enabling this option adds a parsing cost and only makes sense if at least one backend might send different responses based on the ECS value, so it’s disabled by default. Enabling this option is required for the EDNS Client Subnet Zero Scope option to workstaleTTL=60
: int - When the backend servers are not reachable, and global configurationsetStaleCacheEntriesTTL
is set appropriately, TTL that will be used when a stale cache entry is returned.temporaryFailureTTL=60
: int - On a SERVFAIL or REFUSED from the backend, cache for this amount of seconds..cookieHashing=false
: bool - If true, EDNS Cookie values will be hashed, resulting in separate entries for different cookies in the packet cache. This is required if the backend is sending answers with EDNS Cookies, otherwise a client might receive an answer with the wrong cookie.skipOptions={}
: Extra list of EDNS option codes to skip when hashing the packet (ifcookieHashing
above is false, EDNS cookie option number will be added to this list internally).maximumEntrySize=4096
: int - The maximum size, in bytes, of a DNS packet that can be inserted into the packet cache. Default is 4096 bytes, which was the fixed size before 1.9.0, and is also a hard limit for UDP responses.
-
class
PacketCache
¶ Represents a cache that can be part of
ServerPool
.-
:
dump
(fname)¶ Dump a summary of the cache entries to a file.
Parameters: fname (str) – 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.
-
:
expunge
(n)¶ Remove entries from the cache, leaving at most
n
entriesParameters: n (int) – Number of entries to keep
-
:
expungeByName
(name[, qtype=DNSQType.ANY[, suffixMatch=false]])¶ Changed in version 1.6.0:
name
can now also be a stringRemove entries matching
name
and type from the cache.Parameters:
-
:
getAddressListByDomain
(domain)¶ New in version 1.8.0.
This method looks up the answers present in the cache for the supplied domain, and returns the list of addresses present in the answer section of these answers (in A records for IPv4 addresses, and AAAA records for IPv6 ones). The addresses are returned as a list of
ComboAddress
objects.Parameters: domain (DNSName) – The domain to look for
-
:
getDomainListByAddress
(addr)¶ New in version 1.8.0.
Return a list of domains, as
DNSName
objects, for which an answer is present in the cache and has a corresponding A record (for IPv4 addresses) or AAAA record (for IPv6 addresses) in the answer section.Parameters: addr (ComboAddress) – The address to look for
-
:
getStats
()¶ New in version 1.4.0.
Return the cache stats (number of entries, hits, misses, deferred lookups, deferred inserts, lookup collisions, insert collisions and TTL too shorts) as a Lua table.
-
:
isFull
() → bool¶ Return true if the cache has reached the maximum number of entries.
-
:
printStats
()¶ Print the cache stats (number of entries, hits, misses, deferred lookups, deferred inserts, lookup collisions, insert collisions and TTL too shorts).
-
:
purgeExpired
(n)¶ Remove expired entries from the cache until there is at most
n
entries remaining in the cache.Parameters: n (int) – Number of entries to keep
-
:
toString
() → string¶ Return the number of entries in the Packet Cache, and the maximum number of entries
-
Client State¶
Also called frontend or bind, the Client State object returned by getBind()
and listed with showBinds()
represents an address and port dnsdist is listening on.
-
getBind
(index) → ClientState¶ Return a
ClientState
object.Parameters: index (int) – The object index
-
getBindCount
()¶ New in version 1.5.0.
Return the number of binds (Do53, DNSCrypt, DoH and DoT).
ClientState functions¶
-
class
ClientState
¶ This object represents an address and port dnsdist is listening on. When
reuseport
is in use, several ClientState objects can be present for the same address and port.-
:
attachFilter
(filter)¶ Attach a BPF filter to this frontend.
Parameters: filter (BPFFilter) – The filter to attach to this frontend
-
:
detachFilter
()¶ Remove the BPF filter associated to this frontend, if any.
-
:
getEffectiveTLSProvider
() → string¶ New in version 1.7.0.
Return the name of the TLS provider actually used.
-
:
getRequestedTLSProvider
() → string¶ New in version 1.7.0.
Return the name of the TLS provider requested in the configuration.
-
:
getType
() → string¶ New in version 1.7.0.
Return the type of the frontend: UDP, UDP (DNSCrypt), TCP, TCP (DNSCrypt), TCP (DNS over TLS) or TCP (DNS over HTTPS).
-
:
toString
() → string¶ Return the address and port this frontend is listening on.
Returns: The address and port this frontend is listening on
-
muted
¶ If set to true, queries received on this frontend will be normally processed and sent to a backend if needed, but no response will be ever be sent to the client over UDP. TCP queries are processed normally and responses sent to the client.
-
Status, Statistics and More¶
-
dumpStats
()¶ Print all statistics dnsdist gathers
-
getDOHFrontend
(idx)¶ New in version 1.4.0.
Return the
DOHFrontend
object for the DNS over HTTPS bind of indexidx
.
-
getDOHFrontendCount
()¶ New in version 1.5.0.
Return the number of
DOHFrontend
binds.
-
getDOH3Frontend
(idx)¶ New in version 1.9.0.
Return the
DOH3Frontend
object for the DNS over HTTP3 bind of indexidx
.
-
getDOH3FrontendCount
()¶ New in version 1.9.0.
Return the number of
DOH3Frontend
binds.
-
getDOQFrontend
(idx)¶ New in version 1.9.0.
Return the
DOQFrontend
object for the DNS over QUIC bind of indexidx
.
-
getDOQFrontendCount
()¶ New in version 1.9.0.
Return the number of
DOQFrontend
binds.
-
getListOfAddressesOfNetworkInterface
(itf)¶ New in version 1.8.0.
Return the list of addresses configured on a given network interface, as strings. This function requires support for
getifaddrs
, which is known to be present on FreeBSD, Linux, and OpenBSD at least.Parameters: itf (str) – The name of the network interface
-
getListOfNetworkInterfaces
()¶ New in version 1.8.0.
Return the list of network interfaces configured on the system, as strings. This function requires support for
getifaddrs
, which is known to be present on FreeBSD, Linux, and OpenBSD at least.
-
getListOfRangesOfNetworkInterface
(itf)¶ New in version 1.8.0.
Return the list of network ranges configured on a given network interface, as strings. This function requires support for
getifaddrs
, which is known to be present on FreeBSD, Linux, and OpenBSD at least.Parameters: itf (str) – The name of the network interface
-
getMACAddress
(ip) → str¶ New in version 1.8.0.
Return the link-level address (MAC) corresponding to the supplied neighbour IP address, if known by the kernel. The link-level address is returned as a raw binary string. An empty string is returned if no matching entry has been found. This function is only implemented on Linux.
Parameters: ip (str) – The IP address, IPv4 or IPv6, to look up the corresponding link-level address for.
-
getOutgoingTLSSessionCacheSize
()¶ New in version 1.7.0.
Return the number of TLS sessions (for outgoing connections) currently cached.
-
getTLSContext
(idx)¶ Return the TLSContext object for the context of index
idx
.
-
getTLSFrontend
(idx)¶ Return the TLSFrontend object for the TLS bind of index
idx
.
-
getTLSFrontendCount
()¶ New in version 1.5.0.
Return the number of TLSFrontend binds.
-
getTopCacheHitResponseRules
([top])¶ New in version 1.6.0.
Return the cache-hit response rules that matched the most.
Parameters: top (int) – How many response rules to return. Default is 10.
-
getTopCacheInsertedResponseRules
([top])¶ New in version 1.8.0.
Return the cache-inserted response rules that matched the most.
Parameters: top (int) – How many response rules to return. Default is 10.
-
getTopResponseRules
([top])¶ New in version 1.6.0.
Return the response rules that matched the most.
Parameters: top (int) – How many response rules to return. Default is 10.
-
getTopRules
([top])¶ New in version 1.6.0.
Return the rules that matched the most.
Parameters: top (int) – How many rules to return. Default is 10.
-
getTopSelfAnsweredRules
([top])¶ New in version 1.6.0.
Return the self-answered rules that matched the most.
Parameters: top (int) – How many rules to return. Default is 10.
-
grepq
(selector[, num[, options]])¶ -
grepq
(selectors[, num[, options]]) Changed in version 1.9.0:
options
optional parameter table added.Prints the last
num
queries and responses matchingselector
orselectors
. Queries and responses are accounted in separate ring buffers, and answers from the packet cache are not stored in the response ring buffer. Therefore, thenum
queries andnum
responses in the output may not always match up.The selector can be:
- a netmask (e.g. ‘192.0.2.0/24’)
- a DNS name (e.g. ‘dnsdist.org’)
- a response time (e.g. ‘100ms’)
Parameters: - selector (str) – Select queries based on this property.
- selectors ({str}) – A lua table of selectors. Only queries matching all selectors are shown
- num (int) – Show a maximum of
num
recent queries+responses. - options (table) – A table with key: value pairs with options described below.
Options:
outputFile=path
: string - Write the output of the command to the supplied file, instead of the standard output.
-
setStructuredLogging
(enable[, options])¶ New in version 1.9.0.
Set whether log messages should be in a structured-logging-like format. This is turned off by default. The resulting format looks like this (when timestamps are enabled via
--log-timestamps
and withlevelPrefix="prio"
andtimeFormat="ISO8601"
):ts="2023-11-06T12:04:58+0100" prio="Info" msg="Added downstream server 127.0.0.1:53"
And with
levelPrefix="level"
andtimeFormat="numeric"
):ts="1699268815.133" level="Info" msg="Added downstream server 127.0.0.1:53"
Parameters: - enable (bool) – Set to true if you want to enable structured logging
- options (table) – A table with key: value pairs with options described below.
Options:
levelPrefix=prefix
: string - Set the prefix for the log level. Default isprio
.timeFormat=format
: string - Set the time format. Supported values areISO8601
andnumeric
. Default isnumeric
.
-
setVerbose
(verbose)¶ New in version 1.8.0.
Set whether log messages issued at the verbose level should be logged. This is turned off by default.
Parameters: verbose (bool) – Set to true if you want to enable verbose logging
-
getVerbose
()¶ New in version 1.8.0.
Get whether log messages issued at the verbose level should be logged. This is turned off by default.
-
setVerboseHealthChecks
(verbose)¶ Set whether health check errors should be logged. This is turned off by default.
Parameters: verbose (bool) – Set to true if you want to enable health check errors logging
-
setVerboseLogDestination
(dest)¶ New in version 1.8.0.
Set a destination file to write the ‘verbose’ log messages to, instead of sending them to syslog and/or the standard output which is the default. Note that these messages will no longer be sent to syslog or the standard output once this option has been set. There is no rotation or file size limit. Only use this feature for debugging under active operator control.
Parameters: dest (str) – The destination file
-
showBinds
()¶ Print a list of all the current addresses and ports dnsdist is listening on, also called
frontends
-
showDOHFrontends
()¶ New in version 1.4.0.
Print the list of all available DNS over HTTPS frontends.
-
showDOH3Frontends
()¶ New in version 1.9.0.
Print the list of all available DNS over HTTP/3 frontends.
-
showDOHResponseCodes
()¶ New in version 1.4.0.
Print the HTTP response codes statistics for all available DNS over HTTPS frontends.
-
showDOQFrontends
()¶ New in version 1.9.0.
Print the list of all available DNS over QUIC frontends.
-
showResponseLatency
()¶ Show a plot of the response time latency distribution
-
showServers
([options])¶ Changed in version 1.4.0:
options
optional parameter addedThis function shows all backend servers currently configured and some statistics. These statistics have the following fields:
#
- The number of the server, can be used as the argument forgetServer()
Name
- The name of the backend, if anyAddress
- The IP address and port of the serverState
- The current state of the serverQps
- Current number of queries per secondQlim
- Configured maximum number of queries per secondOrd
- The order number of the serverWt
- The weight of the serverQueries
- Total amount of queries sent to this serverDrops
- Number of queries that were dropped by this serverDrate
- Number of queries dropped per second by this serverLat
- The latency of this server, for queries forwarded over UDP, in millisecondsOutstanding
- The current number of in-flight queriesPools
- The pools this server belongs toUUID
- The UUID of the backend, only displayed when theshowUUIDs
option is set. Can be set with theid
option ofnewServer()
TCP
- The latency of this server, for queries forwarded over TCP, in milliseconds
Parameters: options (table) – A table with key: value pairs with display options. Options:
showUUIDs=false
: bool - Whether to display the UUIDs, defaults to false.
-
showTCPStats
()¶ Show some statistics regarding TCP
-
showTLSContexts
()¶ Print the list of all available DNS over TLS contexts.
-
showTLSErrorCounters
()¶ New in version 1.4.0.
Display metrics about TLS handshake failures.
-
showVersion
()¶ Print the version of dnsdist
-
topBandwidth
([num])¶ Print the top
num
clients that consume the most bandwidth.Parameters: num (int) – Number to show, defaults to 10.
-
topCacheHitResponseRules
([top[, options]])¶ New in version 1.6.0.
This function shows the cache-hit response rules that matched the most.
Parameters: - top (int) – How many rules to show.
- options (table) – A table with key: value pairs with display options.
Options:
showUUIDs=false
: bool - Whether to display the UUIDs, defaults to false.
-
topCacheInsertedResponseRules
([top[, options]])¶ New in version 1.8.0.
This function shows the cache-inserted response rules that matched the most.
Parameters: - top (int) – How many rules to show.
- options (table) – A table with key: value pairs with display options.
Options:
showUUIDs=false
: bool - Whether to display the UUIDs, defaults to false.
-
topClients
([num])¶ Print the top
num
clients sending the most queries over length of ringbufferParameters: num (int) – Number to show, defaults to 10.
-
topQueries
([num[, labels]])¶ Print the
num
most popular QNAMEs from queries. Optionally grouped by the rightmostlabels
DNS labels.Parameters: - num (int) – Number to show, defaults to 10
- label (int) – Number of labels to cut down to
-
topResponses
([num[, rcode[, labels]]])¶ Print the
num
most seen responses with an RCODE ofrcode
. Optionally grouped by the rightmostlabels
DNS labels.Parameters: - num (int) – Number to show, defaults to 10
- rcode (int) – Response code, defaults to 0 (No Error)
- label (int) – Number of labels to cut down to
-
topResponseRules
([top[, options]])¶ New in version 1.6.0.
This function shows the response rules that matched the most.
Parameters: - top (int) – How many rules to show.
- options (table) – A table with key: value pairs with display options.
Options:
showUUIDs=false
: bool - Whether to display the UUIDs, defaults to false.
-
topRules
([top[, options]])¶ New in version 1.6.0.
This function shows the rules that matched the most.
Parameters: - top (int) – How many rules to show.
- options (table) – A table with key: value pairs with display options.
Options:
showUUIDs=false
: bool - Whether to display the UUIDs, defaults to false.
-
topSelfAnsweredResponseRules
([top[, options]])¶ New in version 1.6.0.
This function shows the self-answered response rules that matched the most.
Parameters: - top (int) – How many rules to show.
- options (table) – A table with key: value pairs with display options.
Options:
showUUIDs=false
: bool - Whether to display the UUIDs, defaults to false.
-
topSlow
([num[, limit[, labels]]])¶ Changed in version 1.9.7: queries that timed out are no longer reported by
topSlow
, seetopTimeouts()
insteadPrint the
num
slowest queries that are slower thanlimit
milliseconds. Optionally grouped by the rightmostlabels
DNS labels.Parameters: - num (int) – Number to show, defaults to 10
- limit (int) – Show queries slower than this amount of milliseconds, defaults to 2000
- label (int) – Number of labels to cut down to
-
topTimeouts
([num[, labels]])¶ New in version 1.9.7.
Print the
num
queries that timed out the most. Optionally grouped by the rightmostlabels
DNS labels.Parameters: - num (int) – Number to show, defaults to 10
- label (int) – Number of labels to cut down to
Dynamic Blocks¶
-
addDynamicBlock
(address, message[, action[, seconds[, clientIPMask[, clientIPPortMask]]]])¶ New in version 1.9.0.
Manually block an IP address or range with
message
for (optionally) a number of seconds. The default number of seconds to block for is 10.Parameters: - address – A
ComboAddress
or string representing an IPv4 or IPv6 address - message (string) – The message to show next to the blocks
- action (int) – The action to take when the dynamic block matches, see DNSAction. (default to DNSAction.None, meaning the one set with
setDynBlocksAction()
is used) - seconds (int) – The number of seconds this block to expire
- clientIPMask (int) – The network mask to apply to the address. Default is 32 for IPv4, 128 for IPv6.
- clientIPPortMask (int) – The port mask to use to specify a range of ports to match, when the clients are behind a CG-NAT.
Please see the documentation for
setDynBlocksAction()
to confirm which actions are supported by the action parameter.- address – A
-
addDynBlocks
(addresses, message[, seconds=10[, action]])¶ Block a set of addresses with
message
for (optionally) a number of seconds. The default number of seconds to block for is 10. Since 1.3.0, the use of a DynBlockRulesGroup is a much more efficient way of doing the same thing.Parameters: - addresses – set of Addresses as returned by an exceed function
- message (string) – The message to show next to the blocks
- seconds (int) – The number of seconds this block to expire
- action (int) – The action to take when the dynamic block matches, see DNSAction. (default to DNSAction.None, meaning the one set with
setDynBlocksAction()
is used)
Please see the documentation for
setDynBlocksAction()
to confirm which actions are supported by the action parameter.
-
clearDynBlocks
()¶ Remove all current dynamic blocks.
-
getDynamicBlocks
()¶ New in version 1.9.0.
Return an associative table of active network-based dynamic blocks. The keys are the network IP or range that are blocked, the value are
DynBlock
objects.
-
getDynamicBlocksSMT
()¶ New in version 1.9.0.
Return an associative table of active domain-based (Suffix Match Tree or SMT) dynamic blocks. The keys are the domains that are blocked, the values are
DynBlock
objects.
-
showDynBlocks
()¶ List all dynamic blocks in effect.
-
setDynBlocksAction
(action)¶ Set which action is performed when a query is blocked. Only DNSAction.Drop (the default), DNSAction.NoOp, DNSAction.NXDomain, DNSAction.Refused, DNSAction.Truncate and DNSAction.NoRecurse are supported.
-
setDynBlocksPurgeInterval
(sec)¶ New in version 1.6.0.
Set at which interval, in seconds, the expired dynamic blocks entries will be effectively removed from the tree. Entries are not applied anymore as soon as they expire, but they remain in the tree for a while for performance reasons. Removing them makes the addition of new entries faster and frees up the memory they use. Setting this value to 0 disable the purging mechanism, so entries will remain in the tree.
Parameters: sec (int) – The interval between two runs of the cleaning algorithm, in seconds. Default is 60 (1 minute), 0 means disabled.
-
class
DynBlock
¶ New in version 1.9.0.
Represent the current state of a dynamic block.
-
blocks
¶ The number of queries blocked.
-
bpf
¶ Whether this block is using eBPF, as a boolean.
-
domain
¶ The domain that is blocked, as a string, for Suffix Match Tree blocks.
-
reason
¶ The reason why this block was inserted, as a string.
-
until
¶ The time (in seconds since Epoch) at which the block will expire.
-
warning
¶ Whether this block is only a warning one (true) or is really enforced (false).
-
Getting addresses that exceeded parameters¶
-
exceedServFails
(rate, seconds)¶ Get set of addresses that exceed
rate
servfails/s overseconds
secondsParameters: - rate (int) – Number of Servfails per second to exceed
- seconds (int) – Number of seconds the rate has been exceeded
-
exceedNXDOMAINs
(rate, seconds)¶ get set of addresses that exceed
rate
NXDOMAIN/s overseconds
secondsParameters: - rate (int) – Number of NXDOMAIN per second to exceed
- seconds (int) – Number of seconds the rate has been exceeded
-
exceedRespByterate
(rate, seconds)¶ get set of addresses that exceeded
rate
bytes/s answers overseconds
secondsParameters: - rate (int) – Number of bytes per second to exceed
- seconds (int) – Number of seconds the rate has been exceeded
-
exceedQRate
(rate, seconds)¶ Get set of address that exceed
rate
queries/s overseconds
secondsParameters: - rate (int) – Number of queries per second to exceed
- seconds (int) – Number of seconds the rate has been exceeded
-
exceedQTypeRate
(type, rate, seconds)¶ Get set of address that exceed
rate
queries/s for queries of QTypetype
overseconds
secondsParameters: - type (int) – QType
- rate (int) – Number of QType queries per second to exceed
- seconds (int) – Number of seconds the rate has been exceeded
DynBlockRulesGroup¶
Instead of using several exceed*() lines, dnsdist 1.3.0 introduced a new DynBlockRulesGroup object which can be used to group dynamic block rules.
See Dynamic Rule Generation for more information about the case where using a DynBlockRulesGroup might be faster than the existing rules.
-
dynBlockRulesGroup
() → DynBlockRulesGroup¶ Creates a new
DynBlockRulesGroup
object.
-
class
DynBlockRulesGroup
¶ Represents a group of dynamic block rules.
-
:
setCacheMissRatio
(ratio, seconds, reason, blockingTime, minimumNumberOfResponses, minimumGlobalCacheHitRatio[, action[, warningRate[, options]]])¶ New in version 1.9.0.
New in version 2.0.0:
options
optional parameter addedAdds a rate-limiting rule for the ratio of cache-misses responses over the total number of responses for a given client. A minimum global cache-hit ratio has to specified to prevent false-positive when the cache is empty.
Parameters: - ratio (float) – Ratio of cache-miss responses per second over the total number of responses for this client to exceed
- seconds (int) – Number of seconds the ratio has been exceeded
- reason (string) – The message to show next to the blocks
- blockingTime (int) – The number of seconds this block to expire
- minimumNumberOfResponses (int) – How many total responses is required for this rule to apply
- minimumGlobalCacheHitRatio (float) – The minimum global cache-hit ratio (over all pools, so
cache-hits / (cache-hits + cache-misses)
) for that rule to be applied. - action (int) – The action to take when the dynamic block matches, see DNSAction. (default to the one set with
setDynBlocksAction()
) - warningRatio (float) – If set to a non-zero value, the ratio above which a warning message will be issued and a no-op block inserted
- options (table) – A table with key: value pairs, see below for supported values.
Options:
tagKey
: str - Ifaction
is set toDNSAction.SetTag
, the name of the tag that will be settagValue
: str - Ifaction
is set toDNSAction.SetTag
, the value of the tag that will be set. Default is an empty string.
-
:
setMasks
(v4, v6, port)¶ New in version 1.7.0.
Set the number of bits to keep in the IP address when inserting a block. The default is 32 for IPv4 and 128 for IPv6, meaning that only the exact address is blocked, but in some scenarios it might make sense to block a whole /64 IPv6 range instead of a single address, for example. It is also possible to take the IPv4 UDP and TCP ports into account, for CGNAT deployments, by setting the number of bits of the port to consider. For example passing 2 as the last parameter, which only makes sense if the previous parameters are respectively 32 and 128, will split a given IP address into four port ranges: 0-16383, 16384-32767, 32768-49151 and 49152-65535.
Parameters: - v4 (int) – Number of bits to keep for IPv4 addresses. Default is 32
- v6 (int) – Number of bits to keep for IPv6 addresses. Default is 128
- port (int) – Number of bits of port to consider over IPv4. Default is 0 meaning that the port is not taken into account
-
:
setQueryRate
(rate, seconds, reason, blockingTime[, action[, warningRate[, options]]])¶ New in version 2.0.0:
options
optional parameter addedAdds a query rate-limiting rule, equivalent to:
` addDynBlocks(exceedQRate(rate, seconds), reason, blockingTime, action) `
Parameters: - rate (int) – Number of queries per second to exceed
- seconds (int) – Number of seconds the rate has been exceeded
- reason (string) – The message to show next to the blocks
- blockingTime (int) – The number of seconds this block to expire
- action (int) – The action to take when the dynamic block matches, see DNSAction. (default to the one set with
setDynBlocksAction()
) - warningRate (int) – If set to a non-zero value, the rate above which a warning message will be issued and a no-op block inserted
- options (table) – A table with key: value pairs, see below for supported values.
Options:
tagKey
: str - Ifaction
is set toDNSAction.SetTag
, the name of the tag that will be settagValue
: str - Ifaction
is set toDNSAction.SetTag
, the value of the tag that will be set. Default is an empty string
-
:
setNewBlockInsertedHook
(hook)¶ New in version 1.9.0.
Set a Lua function that will be called everytime a new dynamic block is inserted. The function receives:
- an integer whose value is 0 if the block is Netmask-based one (Client IP or range) and 1 instead (Domain name suffix)
- the key (Client IP/range or domain suffix) as a string
- the reason of the block as a string
- the action of the block as an integer
- the duration of the block in seconds
- whether this is a warning block (true) or not (false)
-
:
setRCodeRate
(rcode, rate, seconds, reason, blockingTime[, action[, warningRate[, options]]])¶ New in version 2.0.0:
options
optional parameter addedNote
Cache hits are inserted into the in-memory ring buffers since 1.8.0, so they are now considered when computing the rcode rate.
Adds a rate-limiting rule for responses of code
rcode
, equivalent to:` addDynBlocks(exceedServfails(rcode, rate, seconds), reason, blockingTime, action) `
Parameters: - rcode (int) – The response code
- rate (int) – Number of responses per second to exceed
- seconds (int) – Number of seconds the rate has been exceeded
- reason (string) – The message to show next to the blocks
- blockingTime (int) – The number of seconds this block to expire
- action (int) – The action to take when the dynamic block matches, see DNSAction. (default to the one set with
setDynBlocksAction()
) - warningRate (int) – If set to a non-zero value, the rate above which a warning message will be issued and a no-op block inserted
- options (table) – A table with key: value pairs, see below for supported values.
Options:
tagKey
: str - Ifaction
is set toDNSAction.SetTag
, the name of the tag that will be settagValue
: str - Ifaction
is set toDNSAction.SetTag
, the value of the tag that will be set. Default is an empty string
-
:
setRCodeRatio
(rcode, ratio, seconds, reason, blockingTime, minimumNumberOfResponses[, action[, warningRate[, options]]])¶ New in version 1.5.0.
New in version 2.0.0:
options
optional parameter addedNote
Cache hits are inserted into the in-memory ring buffers since 1.8.0, so they are now considered when computing the rcode ratio.
Adds a rate-limiting rule for the ratio of responses of code
rcode
over the total number of responses for a given client.Parameters: - rcode (int) – The response code
- ratio (float) – Ratio of responses per second of the given rcode over the total number of responses for this client to exceed
- seconds (int) – Number of seconds the ratio has been exceeded
- reason (string) – The message to show next to the blocks
- blockingTime (int) – The number of seconds this block to expire
- minimumNumberOfResponses (int) – How many total responses is required for this rule to apply
- action (int) – The action to take when the dynamic block matches, see DNSAction. (default to the one set with
setDynBlocksAction()
) - warningRatio (float) – If set to a non-zero value, the ratio above which a warning message will be issued and a no-op block inserted
- options (table) – A table with key: value pairs, see below for supported values.
Options:
tagKey
: str - Ifaction
is set toDNSAction.SetTag
, the name of the tag that will be settagValue
: str - Ifaction
is set toDNSAction.SetTag
, the value of the tag that will be set. Default is an empty string
-
:
setQTypeRate
(qtype, rate, seconds, reason, blockingTime[, action[, warningRate[, options]]])¶ New in version 2.0.0:
options
optional parameter addedAdds a rate-limiting rule for queries of type
qtype
, equivalent to:` addDynBlocks(exceedQTypeRate(type, rate, seconds), reason, blockingTime, action) `
Parameters: - qtype (int) – The qtype
- rate (int) – Number of queries per second to exceed
- seconds (int) – Number of seconds the rate has been exceeded
- reason (string) – The message to show next to the blocks
- blockingTime (int) – The number of seconds this block to expire
- action (int) – The action to take when the dynamic block matches, see DNSAction. (default to the one set with
setDynBlocksAction()
) - warningRate (int) – If set to a non-zero value, the rate above which a warning message will be issued and a no-op block inserted
- options (table) – A table with key: value pairs, see below for supported values.
Options:
tagKey
: str - Ifaction
is set toDNSAction.SetTag
, the name of the tag that will be settagValue
: str - Ifaction
is set toDNSAction.SetTag
, the value of the tag that will be set. Default is an empty string
-
:
setResponseByteRate
(rate, seconds, reason, blockingTime[, action[, warningRate[, options]]])¶ New in version 2.0.0:
options
optional parameter addedNote
Cache hits are inserted into the in-memory ring buffers since 1.8.0, so they are now considered when computing the bandwidth rate.
Adds a bandwidth rate-limiting rule for responses, equivalent to:
` addDynBlocks(exceedRespByterate(rate, seconds), reason, blockingTime, action) `
Parameters: - rate (int) – Number of bytes per second to exceed
- seconds (int) – Number of seconds the rate has been exceeded
- reason (string) – The message to show next to the blocks
- blockingTime (int) – The number of seconds this block to expire
- action (int) – The action to take when the dynamic block matches, see DNSAction. (default to the one set with
setDynBlocksAction()
) - warningRate (int) – If set to a non-zero value, the rate above which a warning message will be issued and a no-op block inserted
- options (table) – A table with key: value pairs, see below for supported values.
Options:
tagKey
: str - Ifaction
is set toDNSAction.SetTag
, the name of the tag that will be settagValue
: str - Ifaction
is set toDNSAction.SetTag
, the value of the tag that will be set. Default is an empty string
-
:
setSuffixMatchRule
(seconds, reason, blockingTime, action, visitor[, options])¶ New in version 1.4.0.
Changed in version 1.7.0: This visitor function can now optionally return an additional string which will be set as the
reason
for the dynamic block.Changed in version 1.9.0: This visitor function can now optionally return an additional integer which will be set as the
action
for the dynamic block.New in version 2.0.0:
options
optional parameter addedSet a Lua visitor function that will be called for each label of every domain seen in queries and responses. The function receives a
StatNode
object representing the stats of the parent, aStatNodeStats
one with the stats of the current label and a secondStatNodeStats
with the stats of the current node plus all its children. Note that this function will not be called if a FFI version has been set usingDynBlockRulesGroup:setSuffixMatchRuleFFI()
If the function returnstrue
, the current suffix will be added to the block list, meaning that the exact name and all its sub-domains will be blocked according to the seconds, reason, blockingTime and action parameters. Since 1.7.0, the function can return an additional string, in addition to the boolean, which will be set as thereason
for the dynamic block. Selected domains can be excluded from this processing using theDynBlockRulesGroup:excludeDomains()
method.This replaces the existing
addDynBlockSMT()
function.Parameters: - seconds (int) – Number of seconds the rate has been exceeded
- reason (string) – The message to show next to the blocks
- blockingTime (int) – The number of seconds this block to expire
- action (int) – The action to take when the dynamic block matches, see DNSAction. (default to the one set with
setDynBlocksAction()
) - visitor (function) – The Lua function to call.
- options (table) – A table with key: value pairs, see below for supported values.
Options:
tagKey
: str - Ifaction
is set toDNSAction.SetTag
, the name of the tag that will be settagValue
: str - Ifaction
is set toDNSAction.SetTag
, the value of the tag that will be set. Default is an empty string
-
:
setSuffixMatchRuleFFI
(seconds, reason, blockingTime, action, visitor[, options])¶ New in version 1.4.0.
New in version 2.0.0:
options
optional parameter addedSet a Lua FFI visitor function that will be called for each label of every domain seen in queries and responses. The function receives a dnsdist_ffi_stat_node_t object containing the stats of the parent, a second one with the stats of the current label and one with the stats of the current node plus all its children. If the function returns
true
, the current suffix will be added to the block list, meaning that the exact name and all its sub-domains will be blocked according to the seconds, reason, blockingTime and action parameters. Selected domains can be excluded from this processing using theDynBlockRulesGroup:excludeDomains()
method.Parameters: - seconds (int) – Number of seconds the rate has been exceeded
- reason (string) – The message to show next to the blocks
- blockingTime (int) – The number of seconds this block to expire
- action (int) – The action to take when the dynamic block matches, see DNSAction. (default to the one set with
setDynBlocksAction()
) - visitor (function) – The Lua FFI function to call.
- options (table) – A table with key: value pairs, see below for supported values.
Options:
tagKey
: str - Ifaction
is set toDNSAction.SetTag
, the name of the tag that will be settagValue
: str - Ifaction
is set toDNSAction.SetTag
, the value of the tag that will be set. Default is an empty string
-
:
apply
()¶ Walk the in-memory query and response ring buffers and apply the configured rate-limiting rules, adding dynamic blocks when the limits have been exceeded.
-
:
setQuiet
(quiet)¶ New in version 1.4.0.
Set whether newly blocked clients or domains should be logged.
Parameters: quiet (bool) – True means that insertions will not be logged, false that they will. Default is false.
-
:
excludeDomains
(domains)¶ New in version 1.4.0.
Exclude this domain, or list of domains, meaning that no dynamic block will ever be inserted for this domain via
DynBlockRulesGroup:setSuffixMatchRule()
orDynBlockRulesGroup:setSuffixMatchRuleFFI()
. Default to empty, meaning rules are applied to all domains.Parameters: domain (str) – A domain, or list of domains, as strings, like for example “powerdns.com”
-
:
excludeRange
(netmasks)¶ Changed in version 1.6.0: This method now accepts a
NetmaskGroup
object.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
DynBlockRulesGroup:includeRange()
, the more specific entry wins.Parameters: netmasks (list) – A NetmaskGroup
object, or a netmask or list of netmasks as strings, like for example “192.0.2.1/24”
-
:
includeRange
(netmasks)¶ Changed in version 1.6.0: This method now accepts a
NetmaskGroup
object.Include this range, or list of ranges, meaning that rules will be applied to this range. When used in combination with
DynBlockRulesGroup:excludeRange()
, the more specific entry wins.Parameters: netmasks (list) – A NetmaskGroup
object, or a netmask or list of netmasks as strings, like for example “192.0.2.1/24”
-
:
removeRange
(netmasks)¶ New in version 1.8.3.
Remove a previously included or excluded range. The range should be an exact match of the existing entry to remove.
Parameters: netmasks (list) – A NetmaskGroup
object, or a netmask or list of netmasks as strings, like for example “192.0.2.1/24”
-
:
toString
()¶ Return a string describing the rules and range exclusions of this DynBlockRulesGroup.
-
StatNode¶
-
class
StatNode
¶ Represent a given node, for the visitor functions used with
DynBlockRulesGroup:setSuffixMatchRule()
andDynBlockRulesGroup:setSuffixMatchRuleFFI()
.-
fullname
¶ The complete name of that node, ie ‘www.powerdns.com.’.
-
labelsCount
¶ The number of labels in that node, for example 3 for ‘www.powerdns.com.’.
-
:
numChildren
()¶ The number of children of that node.
-
-
class
StatNodeStats
¶ Represent the metrics for a given node, for the visitor functions used with
DynBlockRulesGroup:setSuffixMatchRule()
andDynBlockRulesGroup:setSuffixMatchRuleFFI()
.-
bytes
¶ The number of bytes for all responses returned for that node.
-
drops
¶ The number of drops for that node.
-
noerrors
¶ The number of No Error answers returned for that node.
-
hits
¶ New in version 1.8.0.
The number of cache hits for that node.
-
nxdomains
¶ The number of NXDomain answers returned for that node.
-
queries
¶ The number of queries for that node.
-
servfails
¶ The number of Server Failure answers returned for that node.
-
SuffixMatchNode¶
A SuffixMatchNode can be used to quickly check whether a given name belongs to a set or not. This is achieved
using an efficient tree structure based on DNS labels, making lookups cheap.
Be careful that Suffix Node matching will match for any sub-domain, regardless of the depth, under the name added to the set. For example,
if ‘example.com.’ is added to the set, ‘www.example.com.’ and ‘sub.www.example.com.’ will match as well.
If you are looking for exact name matching, your might want to consider using a DNSNameSet
instead.
-
newSuffixMatchNode
()¶ Creates a new
SuffixMatchNode
.
-
class
SuffixMatchNode
¶ Represent a set of DNS suffixes for quick matching.
-
:
add
(name)¶ Changed in version 1.4.0: This method now accepts strings, lists of DNSNames and lists of strings.
Add a suffix to the current set.
Parameters: - name (table) – The suffix to add to the set.
- name – The suffix to add to the set.
- name – The suffixes to add to the set. Elements of the table should be of the same type, either DNSName or string.
-
:
check
(name) → bool¶ Return true if the given name is a sub-domain of one of those in the set, and false otherwise.
Parameters: name (DNSName) – The name to test against the set.
-
:
getBestMatch
(name) → DNSName¶ New in version 1.8.0.
Returns the best match for the supplied name, or nil if there was no match.
Parameters: name (DNSName) – The name to look up.
-
:
remove
(name)¶ New in version 1.5.0.
Remove a suffix from the current set.
Parameters: - name (table) – The suffix to remove from the set.
- name – The suffix to remove from the set.
- name – The suffixes to remove from the set. Elements of the table should be of the same type, either DNSName or string.
-
Outgoing TLS tickets cache management¶
Since 1.7, dnsdist supports securing the connection toward backends using DNS over TLS. For these connections, it keeps a cache of TLS tickets to be able to resume a TLS session quickly. By default that cache contains up to 20 TLS tickets per-backend, is cleaned up every 60s, and TLS tickets expire if they have not been used after 600 seconds. These values can be set at configuration time via:
-
setOutgoingTLSSessionsCacheMaxTicketsPerBackend
(num)¶ Set the maximum number of TLS tickets to keep, per-backend, to be able to quickly resume outgoing TLS connections to a backend. Keeping more tickets might provide a better TLS session resumption rate if there is a sudden peak of outgoing connections, at the cost of using a bit more memory.
Parameters: num (int) – The number of TLS tickets to keep, per-backend. The default is 20.
-
setOutgoingTLSSessionsCacheCleanupDelay
(delay)¶ Set the number of seconds between two scans of the TLS sessions cache, removing expired tickets and freeing up memory. Decreasing that value will lead to more scans, freeing up memory more quickly but using a bit more CPU doing so.
Parameters: delay (int) – The number of seconds between two scans of the cache. The default is 60.
-
setOutgoingTLSSessionsCacheMaxTicketValidity
(validity)¶ Set the number of seconds that a given TLS ticket can be kept inactive in the TLS sessions cache. After that delay the ticket will be removed during the next cleanup of the cache. Increasing that value might increase the TLS resumption rate if new connections are not often created, but it might also lead to trying to reuse a ticket that the server will consider too old and refuse.
Parameters: validity (int) – The number of seconds a ticket is considered valid. The default is 600, which matches the default lifetime of TLS tickets set by OpenSSL.
Other functions¶
-
addMaintenanceCallback
(callback)¶ New in version 1.10.0.
Register a Lua function to be called as part of the
maintenance
hook, which is executed roughly every second. The function should not block for a long period of time, as it would otherwise delay the execution of the other functions registered for this hook, as well as the execution of themaintenance()
function.Parameters: callback (function) – The function to be called. It takes no parameter and returns no value. function myCallback(hostname, ips) print('called') end addMaintenanceCallback(myCallback)
-
getAddressInfo
(hostname, callback)¶ New in version 1.9.0.
Asynchronously resolve, via the system resolver (using
getaddrinfo()
), the suppliedhostname
to IPv4 and IPv6 addresses (if configured on the host) before invoking the suppliedcallback
function with thehostname
and a list of IPv4 and IPv6 addresses asComboAddress
. For example, to get the addresses of Quad9’s resolver and dynamically add them as backends:function resolveCB(hostname, ips) for _, ip in ipairs(ips) do newServer(ip:toString()) end end getAddressInfo('dns.quad9.net.', resolveCB)
Parameters: - hostname (str) – The hostname to resolve.
- callback (function) – The function to invoke when the name has been resolved.
-
getCurrentTime -> timespec
New in version 1.8.0.
Return the current time, in whole seconds and nanoseconds since epoch.
Returns: A timespec object, see timespec
-
getResolvers
(path)¶ New in version 1.8.0.
This function can be used to get a Lua table of name servers from a file in the resolv.conf format.
Parameters: path (str) – The path to the file, usually /etc/resolv.conf
-
getStatisticsCounters
()¶ This function returns a Lua associative array of metrics, with the metric name as key and the current value of the counter as value.
-
maintenance
()¶ If this function exists, it is called every second to do regular tasks. This can be used for e.g. Dynamic Blocks. See also
addMaintenanceCallback()
.
-
threadmessage
(cmd, dict)¶ New in version 1.8.0.
This function, if it exists, is called when a separate thread (made with
newThread()
) callssubmitToMainThread()
.
-
newThread
(code)¶ New in version 1.8.0.
Spawns a separate thread running the supplied code. Code is supplied as a string, not as a function object. Note that this function does nothing in ‘client’ or ‘config-check’ modes.
-
setTicketsKeyAddedHook
(callback)¶ New in version 1.9.6.
Set a Lua function that will be called everytime a new tickets key is added. The function receives:
- the key content as a string
- the keylen as an integer
See TLS Sessions Management for more information.
-
submitToMainThread
(cmd, dict)¶ New in version 1.8.0.
Must be called from a separate thread (made with
newThread()
), submits data to the main thread by callingthreadmessage()
in it. If nothreadmessage
receiver is present in the main thread,submitToMainThread
logs an error but returns normally.The
cmd
argument is a string. Thedict
argument is a Lua table.
-
setAllowEmptyResponse
()¶ New in version 1.4.0.
Set to true (defaults to false) to allow empty responses (qdcount=0) with a NoError or NXDomain rcode (default) from backends. dnsdist drops these responses by default because it can’t match them against the initial query since they don’t contain the qname, qtype and qclass, and therefore the risk of collision is much higher than with regular responses.
-
setDropEmptyQueries
(drop)¶ New in version 1.6.0.
Set to true (defaults to false) to drop empty queries (qdcount=0) right away, instead of answering with a NotImp rcode. dnsdist used to drop these queries by default because most rules and existing Lua code expects a query to have a qname, qtype and qclass. However RFC 7873 uses these queries to request a server cookie, and RFC 8906 as a conformance test, so answering these queries with NotImp is much better than not answering at all.
Parameters: drop (bool) – Whether to drop these queries (defaults to false)
-
setProxyProtocolMaximumPayloadSize
(size)¶ New in version 1.6.0.
Set the maximum size of a Proxy Protocol payload that dnsdist is willing to accept, in bytes. The default is 512, which is more than enough except for very large TLV data. This setting can’t be set to a value lower than 16 since it would deny of Proxy Protocol headers.
Parameters: size (int) – The maximum size in bytes (default is 512)
-
setTCPFastOpenKey
(key)¶ New in version 1.8.0.
Set the supplied
TCP Fast Open
key on all frontends. This can for example be used to allow all dnsdist instances in an anycast cluster to use the sameTCP Fast Open
key, reducing round-trips.Parameters: key (string) – The format of the key can be found in /proc/sys/net/ipv4/tcp_fastopen_key
-
makeIPCipherKey
(password) → string¶ New in version 1.4.0.
Hashes the password to generate a 16-byte key that can be used to pseudonymize IP addresses with IP cipher.
-
generateOCSPResponse
(pathToServerCertificate, pathToCACertificate, pathToCAPrivateKey, outputFile, numberOfDaysOfValidity, numberOfMinutesOfValidity)¶ New in version 1.4.0.
When a local PKI is used to issue the certificate, or for testing purposes,
generateOCSPResponse()
can be used to generate an OCSP response file for a certificate, using the certificate and private key of the certification authority that signed that certificate. The resulting file can be directly used with theaddDOHLocal()
or theaddTLSLocal()
functions.Parameters: - pathToServerCertificate (string) – Path to a file containing the certificate used by the server.
- pathToCACertificate (string) – Path to a file containing the certificate of the certification authority that was used to sign the server certificate.
- pathToCAPrivateKey (string) – Path to a file containing the private key corresponding to the certification authority certificate.
- outputFile (string) – Path to a file where the resulting OCSP response will be written to.
- numberOfDaysOfValidity (int) – Number of days this OCSP response should be valid.
- numberOfMinutesOfValidity (int) – Number of minutes this OCSP response should be valid, in addition to the number of days.
-
getRingEntries
()¶ New in version 1.8.0.
Return a list of all the entries, queries and responses alike, that are present in the in-memory ring buffers, as
LuaRingEntry
objects.
-
loadTLSEngine
(engineName[, defaultString])¶ New in version 1.8.0.
Load the OpenSSL engine named
engineName
, setting the engine default string todefaultString
if supplied. Engines can be used to accelerate cryptographic operations, like for example Intel QAT. At the moment up to a maximum of 32 loaded engines are supported, and that support is experimental. Some engines might actually degrade performance unless the TLS asynchronous mode of OpenSSL is enabled. To enable it see thetlsAsyncMode
parameter onaddTLSLocal()
andaddDOHLocal()
.Parameters: - engineName (string) – The name of the engine to load.
- defaultString (string) – The default string to pass to the engine. The exact value depends on the engine but represents the algorithms to register with the engine, as a list of comma-separated keywords. For example “RSA,EC,DSA,DH,PKEY,PKEY_CRYPTO,PKEY_ASN1”.
-
loadTLSProvider
(providerName)¶ New in version 1.8.0.
Load the OpenSSL provider named
providerName
. Providers can be used to accelerate cryptographic operations, like for example Intel QAT. At the moment up to a maximum of 32 loaded providers are supported, and that support is experimental. Note thatloadTLSProvider()
is only available when building against OpenSSL version >= 3.0 and with the –enable-tls-provider configure flag on. In other cases,loadTLSEngine()
should be used instead. Some providers might actually degrade performance unless the TLS asynchronous mode of OpenSSL is enabled. To enable it see thetlsAsyncMode
parameter onaddTLSLocal()
andaddDOHLocal()
.Parameters: providerName (string) – The name of the provider to load.
-
newTLSCertificate
(pathToCert[, options])¶ New in version 1.8.0.
Creates a
TLSCertificate
object suited to be used with functions likeaddDOHLocal()
,addDOH3Local()
,addDOQLocal()
andaddTLSLocal()
for TLS certificate configuration.PKCS12
files are only supported by theopenssl
provider, password-protected or not.Parameters: - pathToCert (string) – Path to a file containing the certificate or a
PKCS12
file containing both a certificate and a key. - options (table) – A table with key: value pairs with additional options.
Options:
key="path/to/key"
: string - Path to a file containing the key corresponding to the certificate.password="pass"
: string - Password protecting thePKCS12
file if appropriate.
newTLSCertificate("path/to/pub.crt", {key="path/to/private.pem"}) newTLSCertificate("path/to/domain.p12", {password="passphrase"}) -- use a password protected ``PKCS12`` file
- pathToCert (string) – Path to a file containing the certificate or a
DOHFrontend¶
-
class
DOHFrontend
¶ New in version 1.4.0.
This object represents an address and port dnsdist is listening on for DNS over HTTPS queries.
-
:
getAddressAndPort
() → string¶ New in version 1.7.1.
Return the address and port this frontend is listening on.
-
:
loadNewCertificatesAndKeys
(certFile(s), keyFile(s))¶ New in version 1.6.1.
Changed in version 1.8.0:
certFile
now accepts a TLSCertificate object or a list of such objects (seenewTLSCertificate()
)Parameters: - certFile(s) (str) – The path to a X.509 certificate file in PEM format, a list of paths to such files, or a TLSCertificate object.
- keyFile(s) (str) – The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones. Ignored if
certFile
contains TLSCertificate objects.
-
:
loadTicketsKeys
(ticketsKeysFile)¶ - Load new tickets keys from the selected file, replacing the existing ones. These keys should be rotated often and never written to persistent storage to preserve forward secrecy. The default is to generate a random key. dnsdist supports several tickets keys to be able to decrypt existing sessions after the rotation. See TLS Sessions Management for more information.
Parameters: ticketsKeysFile (str) – The path to a file from where TLS tickets keys should be loaded.
-
:
loadTicketsKey
(key)¶ Load a new TLS tickets key.
Parameters: key (str) – the new raw TLS tickets key to load.
-
:
reloadCertificates
()¶ Reload the current TLS certificate and key pairs.
-
:
rotateTicketsKey
()¶ Replace the current TLS tickets key by a new random one.
-
:
setResponsesMap
(rules)¶ Set a list of HTTP response rules allowing to intercept HTTP queries very early, before the DNS payload has been processed, and send custom responses including error pages, redirects and static content.
Parameters: of DOHResponseMapEntry objects rules (list) – A list of DOHResponseMapEntry objects, obtained with newDOHResponseMapEntry()
.
-
-
newDOHResponseMapEntry
(regex, status, content[, headers]) → DOHResponseMapEntry¶ New in version 1.4.0.
Return a DOHResponseMapEntry that can be used with
DOHFrontend:setResponsesMap()
. Every query whose path is listed in theurls
parameter toaddDOHLocal()
and matches the regular expression supplied inregex
will be immediately answered with a HTTP response. The status of the HTTP response will be the one supplied bystatus
, and the content set to the one supplied bycontent
, except if the status is a redirection (3xx) in which case the content is expected to be the URL to redirect to.Parameters: - regex (str) – A regular expression to match the path against.
- status (int) – The HTTP code to answer with.
- content (str) – The content of the HTTP response, or a URL if the status is a redirection (3xx).
- of headers (table) – The custom headers to set for the HTTP response, if any. The default is to use the value of the
customResponseHeaders
parameter passed toaddDOHLocal()
.
DOH3Frontend¶
DOQFrontend¶
LuaRingEntry¶
-
class
LuaRingEntry
¶ New in version 1.8.0.
This object represents an entry from the in-memory ring buffers, query or response.
-
backend
¶ If this entry is a response, the backend from which it has been received as a ComboAddress.
-
-
LuaRingEntry.
dnsheader
¶ - The DNSHeader (dh) object of this entry.
-
isResponse
¶ Whether this entry is a response (true) or a request (false).
-
macAddress
¶ The MAC address of the client as a string, if available.
-
protocol
¶ The protocol (Do53 UDP, Do53 TCP, DoT, DoH, …) over which this entry was received, as a string.
-
qname
¶ The qname of this entry as a DNSName objects.
-
qtype
¶ The qtype of this entry as an integer.
-
requestor
¶ The requestor (client IP) of this entry as a ComboAddress.
-
size
¶ The size of the DNS payload of that entry, in bytes.
-
-
LuaRingEntry.
usec
¶ The response time (elapsed time between the request was received and the response sent) in milliseconds.
timespec¶
TLSCertificate¶
-
class
TLSCertificate
¶ This object represents a TLS certificate. It can be created with
newTLSCertificate()
and used withaddDOHLocal()
,addDOH3Local()
,addDOQLocal()
andaddTLSLocal()
for TLS certificate configuration. It is mostly useful to deal with password-protectedPKCS12
certificates.
TLSContext¶
-
class
TLSContext
¶ This object represents an address and port dnsdist is listening on for DNS over TLS queries.
-
:
loadTicketsKeys
(ticketsKeysFile)¶ - Load new tickets keys from the selected file, replacing the existing ones. These keys should be rotated often and never written to persistent storage to preserve forward secrecy. The default is to generate a random key. The OpenSSL provider supports several tickets keys to be able to decrypt existing sessions after the rotation, while the GnuTLS provider only supports one key. See TLS Sessions Management for more information.
Parameters: ticketsKeysFile (str) – The path to a file from where TLS tickets keys should be loaded.
-
:
rotateTicketsKey
()¶ Replace the current TLS tickets key by a new random one.
-
TLSFrontend¶
-
class
TLSFrontend
¶ This object represents the configuration of a listening frontend for DNS over TLS queries. To each frontend is associated a TLSContext.
-
:
getAddressAndPort
() → string¶ New in version 1.7.1.
Return the address and port this frontend is listening on.
-
:
loadNewCertificatesAndKeys
(certFile(s), keyFile(s))¶ Create and switch to a new TLS context using the same options than were passed to the corresponding addTLSLocal() directive, but loading new certificates and keys from the selected files, replacing the existing ones.
Parameters: - certFile(s) (str) – The path to a X.509 certificate file in PEM format, or a list of paths to such files.
- keyFile(s) (str) – The path to the private key file corresponding to the certificate, or a list of paths to such files, whose order should match the certFile(s) ones.
-
:
loadTicketsKeys
(ticketsKeysFile)¶
New in version 1.6.0:Load new tickets keys from the selected file, replacing the existing ones. These keys should be rotated often and never written to persistent storage to preserve forward secrecy. The default is to generate a random key. The OpenSSL provider supports several tickets keys to be able to decrypt existing sessions after the rotation, while the GnuTLS provider only supports one key. See TLS Sessions Management for more information.
param str ticketsKeysFile: The path to a file from where TLS tickets keys should be loaded. -
:
loadTicketsKey
(key)¶ - Load a new TLS tickets key.
Parameters: key (str) – the new raw TLS tickets key to load.
-
:
reloadCertificates
()¶
New in version 1.6.0: Reload the current TLS certificate and key pairs.
-
:
rotateTicketsKey
()¶
New in version 1.6.0: Replace the current TLS tickets key by a new random one.
-
EDNS on Self-generated answers¶
There are several mechanisms in dnsdist that turn an existing query into an answer right away,
without reaching out to the backend, including SpoofAction()
, RCodeAction()
, TCAction()
and returning a response from Lua
. Those responses should, according to RFC 6891, contain an OPT
record if the received request had one, which is the case by default and can be disabled using
setAddEDNSToSelfGeneratedResponses()
.
We must, however, provide a responder’s maximum payload size in this record, and we can’t easily know the
maximum payload size of the actual backend so we need to provide one. The default value is 1232 since 1.6.0,
and can be overridden using setPayloadSizeOnSelfGeneratedAnswers()
.
-
setAddEDNSToSelfGeneratedResponses
(add)¶ Whether to add EDNS to self-generated responses, provided that the initial query had EDNS.
Parameters: add (bool) – Whether to add EDNS, default is true.
-
setPayloadSizeOnSelfGeneratedAnswers
(payloadSize)¶ Changed in version 1.6.0: Default value changed from 1500 to 1232.
Set the UDP payload size advertised via EDNS on self-generated responses. In accordance with RFC 6891, values lower than 512 will be treated as equal to 512.
Parameters: payloadSize (int) – The responder’s maximum UDP payload size, in bytes. Default is 1232 since 1.6.0, it was 1500 before.
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, every
setSecurityPollInterval()
seconds.
By default, security polling happens on the domain ‘secpoll.powerdns.com’, but this can be changed with
the setSecurityPollSuffix()
function. 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 enable distributors of PowerDNS to signal that they have backported versions, the PACKAGEVERSION compilation-time macro can be used to set a distributor suffix.
-
setSecurityPollInterval
(interval)¶ Set the interval, in seconds, between two security polls.
Parameters: interval (int) – The interval, in seconds, between two polls. Default is 3600.
-
setSecurityPollSuffix
(suffix)¶ Domain name from which to query security update notifications. Setting this to an empty string disables secpoll.
Parameters: suffix (string) – The suffix to use, default is ‘secpoll.powerdns.com.’.