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 with newServer(), represents a downstream server
  • ComboAddress: represents an IP address and port
  • DNSName: represents a domain name
  • NetmaskGroup: represents a group of netmasks
  • QPSLimiter: implements a QPS-based filter
  • SuffixMatchNode: represents a group of domain suffixes for rapid testing of membership
  • DNSHeader: represents the header of a DNS packet, see DNSHeader (dh) object
  • ClientState: 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

includeDirectory(path)

Include configuration files from path.

Parameters:path (str) – The directory to load the configuration from

Listen Sockets

addLocal(address[, options])

New in version 1.2.0.

Changed in version 1.3.0: Added cpus to the options.

Add to the list of listen addresses.

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 on address.
  • reusePort=false: bool - Set the SO_REUSEPORT socket option.
  • tcpFastOpenSize=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.
addLocal('0.0.0.0:5300', { doTCP=true, reusePort=true })

This will bind to both UDP and TCP on port 5300 with SO_REUSEPORT enabled.

addLocal(address[[[, do_tcp], so_reuseport], tcp_fast_open_qsize])

Deprecated since version 1.2.0.

Add to the list of addresses listened on.

Parameters:
  • address (str) – The IP Address with an optional port to listen on. The default port is 53.
  • do_tcp (bool) – Also bind a TCP port on address, defaults to true.
  • so_reuseport (bool) – Use SO_REUSEPORT if it is available, defaults to false
  • tcp_fast_open_qsize (int) – The size of the TCP Fast Open queue. Set to a number higher than 0 to enable TCP Fast Open when available. Default is 0.
addTLSLocal(address, certFile(s), keyFile(s)[, options])

New in version 1.3.0.

Changed in version 1.3.1: certFile(s) and keyFile(s) parameters accept a list of files. sessionTickets option added.

Listen on the specified address and TCP port for incoming DNS over TLS connections, presenting the specified X.509 certificate.

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, 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.
  • options (table) – A table with key: value pairs with listen options.

Options:

  • doTCP=true: bool - Also bind on TCP on address.
  • reusePort=false: bool - Set the SO_REUSEPORT socket option.
  • tcpFastOpenSize=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.
  • ciphers: str - The TLS ciphers to use. The exact format depends on the provider 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.
  • ticketsKeysRotationDelay: int - Set the delay before the TLS tickets key is rotated, in seconds. Default is 43200 (12h).
  • sessionTickets: bool - Whether session resumption via session tickets is enabled. Default is true, meaning tickets are enabled.
setLocal(address[, options])

New in version 1.2.0.

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().

setLocal(address[[[, do_tcp], so_reuseport], tcp_fast_open_qsize])

Deprecated since version 1.2.0.

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.
  • do_tcp (bool) – Also bind a TCP port on address, defaults to true.
  • so_reuseport (bool) – Use SO_REUSEPORT if it is available, defaults to false
  • tcp_fast_open_qsize (int) – The size of the TCP Fast Open queue. Set to a number higher than 0 to enable TCP Fast Open when available. Default is 0.

Control Socket, Console and Webserver

addConsoleACL(netmask)

New in version 1.3.0.

Add a netmask to the existing console ACL, allowing remote clients to connect to the console. Please make sure that encryption has been enabled with 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.
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() and setConsoleACL() can be used to enable remote connections. Please make sure that encryption has been enabled with setKey() 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.
inClientStartup()

Returns true while the console client is parsing the configuration.

makeKey()

Generate and print an encryption key.

setConsoleConnectionsLogging(enabled)

New in version 1.2.0.

Whether to log the opening and closing of console connections.

Parameters:enabled (bool) – Default to true.
setKey(key)

Use key as shared secret between the client and the server

Parameters:key (str) – An encoded key, as generated by makeKey()
setConsoleACL(netmasks)

New in version 1.3.0.

Remove the existing console ACL and add the netmasks from the table, allowing remote clients to connect to the console. Please make sure that encryption has been enabled with 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.

Webserver

webServer(listen_address, password[, apikey[, custom_headers]])

Launch the Built-in webserver with statistics and the API.

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
  • custom_headers ({[str]=str,...}) – Allows setting custom headers and removing the defaults
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.

Access Control Lists

addACL(netmask)

Add a netmask to the existing ACL controlling which clients can send UDP and TCP 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.
setACL(netmasks)

Remove the existing ACL and add the netmasks from the table of those allowed to send UDP and TCP 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.
showACL()

Print a list of all netmasks allowed to send queries over UDP and TCP. See Access Control for more information.

EDNS Client Subnet

setECSSourcePrefixV4(prefix)

When useClientSubnet in newServer() is set and dnsdist adds an EDNS Client Subnet Client option to the query, truncate the requestors IPv4 address to prefix bits

Parameters:prefix (int) – The prefix length
setECSSourcePrefixV6(prefix)

When useClientSubnet in newServer() is set and dnsdist adds an EDNS Client Subnet Client option to the query, truncate the requestor’s IPv6 address to bits

Parameters:prefix (int) – The prefix length

Ringbuffers

setRingBuffersLockRetries(num)
.. versionadded:: 1.3.0

Set the number of shards to attempt to lock without blocking before giving up and simply blocking while waiting for the next shard to be available

Parameters:num (int) – The maximum number of attempts. Defaults to 5 if there are more than one shard, 0 otherwise.
setRingBuffersSize(num[, numberOfShards])
.. versionchanged:: 1.3.0
``numberOfShards`` optional parameter added.

Set the capacity of the ringbuffers used for live traffic inspection to num, and the number of shards to numberOfShards if specified.

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. Defaults to 1

Servers

newServer(server_string)
newServer(server_table)

Changed in version 1.3.0: - Added checkClass to server_table. - Added sockets to server_table - Added checkFunction to server_table

Add a new backend server. Call this function with either a string:

newServer(
  "IP:PORT" -- IP and PORT of the backend server
)

or a table:

newServer({
  address="IP:PORT",     -- IP and PORT of the backend server (mandatory)
  qps=NUM,               -- Limit the number of queries per second to NUM, when using the `firstAvailable` policy
  order=NUM,             -- The order of this server, used by the `leastOustanding` and `firstAvailable` policies
  weight=NUM,            -- The weight of this server, used by the `wrandom` and `whashed` 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=NUM,           -- The number of TCP connection attempts to the backend, for a given query
  tcpConnectTimeout=NUM, -- The timeout (in seconds) of a TCP connection attempt
  tcpSendTimeout=NUM,    -- The timeout (in seconds) of a TCP write attempt
  tcpRecvTimeout=NUM,    -- 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=NUM,        -- Use NUM as QCLASS in the health-check query, default: DNSClass.IN
  checkName=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 :ref:`Healthcheck`)
  setCD=BOOL,            -- Set the CD (Checking Disabled) flag in the health-check query, default: false
  maxCheckFailures=NUM,  -- Allow NUM check failures before declaring the backend down, default: 1
  mustResolve=BOOL,      -- Set to true when the health check MUST return a NOERROR RCODE and an answer
  useClientSubnet=BOOL,  -- Add the client's IP address in the EDNS Client Subnet option when forwarding the query to this backend
  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"
  addXPF=NUM,            -- Add the client's IP address and port to the query, along with the original destination address and port,
                         -- using the experimental XPF record from `draft-bellis-dnsop-xpf <https://datatracker.ietf.org/doc/draft-bellis-dnsop-xpf/>`_ and the specified option code. Default is disabled (0)
  sockets=NUM            -- Number of sockets (and thus source ports) used toward the backend server, defaults to a single one
})
Parameters:
  • server_string (str) – A simple IP:PORT string.
  • server_table (table) – A table with at least a ‘name’ key
getServer(index) → Server

Get a Server

Parameters:index (int) – The number of the server (as seen in showServers()).
Returns:The Server object or nil
getServers()

Returns a table with all defined servers.

rmServer(index)
rmServer(server)

Remove a backend server.

Parameters:

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
: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
: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

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])

Changed in version 1.3.0: status optional parameter added.

Set the server in the default auto state. This will enable health check queries that will set the server up and down appropriately.

Parameters:status (bool) – Set the initial status of the server to up (true) or down (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
:setDown()

Set the server in an DOWN state. The server will not receive queries and the health checks are disabled

:setUp()

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 or down

order

The order of the server

weight

The weight of the server

Pools

Servers 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 addPool().

addPool(name) → ServerPool

Returns a ServerPool.

Parameters:name (string) – The name of the pool to create
getPool(name) → ServerPool

Returns a ServerPool or nil.

Parameters:name (string) – The name of the pool
rmPool(name)
Remove the pool named name.
Parameters:name (string) – The name of the pool to remove
getPoolServers(name) → [ Server ]

Returns a list of Servers or nil.

Parameters:name (string) – The name of the 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()

New in version 1.3.0.

Whether dnsdist will add EDNS Client Subnet information to the query before looking up into the cache, when all servers from this pool are down. For more information see 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()

New in version 1.3.0.

Set to true if dnsdist should add EDNS Client Subnet information to the query before looking up into the cache, when all servers from this pool are down. If at least one server is up, the preference of the selected server is used, this parameter is only useful if all the backends in this pool are down 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 in stead 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

Changed in version 1.3.0: numberOfShards and deferrableInsertLock parameters added.

Changed in version 1.3.1: maxNegativeTTL and ``parseECS` parameters added.

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, send responses if the cache entry is expired at most this amount of seconds
  • 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 (bool) – 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
class PacketCache

Represents a cache that can be part of ServerPool.

:dump(fname)

New in version 1.3.1.

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 entries

Parameters:n (int) – Number of entries to keep
:expungeByName(name[, qtype=dnsdist.ANY[, suffixMatch=false]])

Changed in version 1.2.0: suffixMatch parameter added.

Remove entries matching name and type from the cache.

Parameters:
  • name (DNSName) – The name to expunge
  • qtype (int) – The type to expunge
  • suffixMatch (bool) – When set to true, remove al entries under name
:isFull() → bool

Return true if the cache has reached the maximum number of entries.

:printStats()

Print the cache stats (hits, misses, deferred lookups and deferred inserts).

: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

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.

: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

getTLSContext(idx)

New in version 1.3.0.

Return the TLSContext object for the context of index idx.

getTLSFrontend(idx)

New in version 1.3.1.

Return the TLSFrontend object for the TLS bind of index idx.

grepq(selector[, num])
grepq(selectors[, num])

Prints the last num queries matching selector or selectors.

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, default is 10.
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
showBinds()

Print a list of all the current addresses and ports dnsdist is listening on, also called frontends

showResponseLatency()

Show a plot of the response time latency distribution

showServers()

This function shows all backend servers currently configured and some statistics. These statics have the following fields:

  • # - The number of the server, can be used as the argument for getServer()
  • Address - The IP address and port of the server
  • State - The current state of the server
  • Qps - Current number of queries per second
  • Qlim - Configured maximum number of queries per second
  • Ord - The order number of the server
  • Wt - The weight of the server
  • Queries - Total amount of queries sent to this server
  • Drops - Number of queries that were dropped by this server
  • Drate - Number of queries dropped per second by this server
  • Lat - The latency of this server in milliseconds
  • Pools - The pools this server belongs to
showTCPStats()

Show some statistics regarding TCP

showTLSContexts()

New in version 1.3.0.

Print the list of all availables DNS over TLS contexts.

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.
topClients([num])

Print the top num clients sending the most queries over length of ringbuffer

Parameters:num (int) – Number to show, defaults to 10.
topQueries([num[, labels]])

Print the num most popular QNAMEs from queries. Optionally grouped by the rightmost labels 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 of rcode. Optionally grouped by the rightmost labels 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
topSlow([num[, limit[, labels]]])

Print the num slowest queries that are slower than limit milliseconds. Optionally grouped by the rightmost labels 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

Dynamic Blocks

addDynBlocks(addresses, message[, seconds=10[, action]])

Changed in version 1.2.0: action parameter added.

Block a set of addresses with message for (optionally) a number of seconds. The default number of seconds to block for is 10.

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 here. (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 paramater.

clearDynBlocks()

Remove all current dynamic blocks.

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.Refused and DNSAction.Truncate are supported.

Getting addresses that exceeded parameters

exceedServFails(rate, seconds)

Get set of addresses that exceed rate servfails/s over seconds seconds

Parameters:
  • 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 over seconds seconds

Parameters:
  • 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 over seconds seconds

Parameters:
  • 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 over seconds seconds

Parameters:
  • 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 QType type over seconds seconds

Parameters:
  • 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

New in version 1.3.0.

Creates a new DynBlockRulesGroup object.

class DynBlockRulesGroup

Represents a group of dynamic block rules.

:setQueryRate(rate, seconds, reason, blockingTime[, action])

Adds 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 here. (default to the one set with setDynBlocksAction())
:setRCodeRate(rcode, rate, seconds, reason, blockingTime[, action])

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 here. (default to the one set with setDynBlocksAction())
:setQTypeRate(qtype, rate, seconds, reason, blockingTime[, action])

Adds 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 here. (default to the one set with setDynBlocksAction())
:setRespByteRate(rate, seconds, reason, blockingTime[, action])

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 here. (default to the one set with setDynBlocksAction())
: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.

:excludeRange(netmasks)

New in version 1.3.1.

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 (int) – A netmask, or list of netmasks, as strings, like for example “192.0.2.1/24”
:includeRange(netmasks)

New in version 1.3.1.

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 (int) – A netmask, or list of netmasks, as strings, like for example “192.0.2.1/24”
:toString()

New in version 1.3.1.

Return a string describing the rules and range exclusions of this DynBlockRulesGroup.

Other functions

maintenance()

If this function exists, it is called every second to so regular tasks. This can be used for e.g. Dynamic Blocks.

TLSContext

class TLSContext

New in version 1.3.0.

This object represents an address and port dnsdist is listening on for DNS over TLS queries.

:rotateTicketsKey()

Replace the current TLS tickets key by a new random one.

: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.
Parameters:ticketsKeysFile (str) – The path to a file from where TLS tickets keys should be loaded.

TLSFrontend

class TLSFrontend

New in version 1.3.1.

This object represents the configuration of a listening frontend for DNS over TLS queries. To each frontend is associated a TLSContext.

TLSContext: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.