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

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.

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 - Sets the network interface to use
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.
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

controlSocket(address)

Bind to addr and listen for a connection for the console

Parameters:address (str) – An IP address with optional port. By default, the port is 5199.
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()
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

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.

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.

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

setRingBuffersSize(num)

Set the capacity of the ringbuffers used for live traffic inspection to num

Parameters:num (int) – The maximum amount of queries to keep in the ringbuffer. Defaults to 10000

Servers

newServer(server_string)
newServer(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
  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
  name=STRING,           -- The name associated to this backend, for display purpose
  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"
  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: false
  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"
})
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.

classmethod Server:addPool(pool)

Add this server to a pool.

Parameters:pool (str) – The pool to add the server to
classmethod Server:getName() → string

Get the name of this server.

Returns:The name of the server, or an empty string if it does not have one
classmethod Server: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
classmethod Server:getOutstanding() → int

Get the number of outstanding queries for this server.

Returns:The number of outstanding queries
classmethod Server:isUp() → bool

Returns the up status of the server

Returns:true when the server is up, false otherwise
classmethod Server:rmPool(pool)

Removes the server from the named pool

Parameters:pool (str) – The pool to remove the server from
classmethod Server:setAuto()

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

classmethod Server:setQPS(limit)

Limit the queries per second for this server.

Parameters:limit (int) – The maximum number of queries per second
classmethod Server:setDown()

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

classmethod Server:setUp()

Set the server in an UP state. This server will still receive queries and health checks are disabled

Attributes

Server.name

The name of the server

Server.upStatus

Whether or not this server is up or down

Server.order

The order of the server

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.

classmethod ServerPool:getCache() → PacketCache

Returns the PacketCache for this pool or nil.

classmethod ServerPool:setCache(cache)

Adds cache as the pool’s cache.

Parameters:cache (PacketCache) – The new cache to add to the pool
classmethod ServerPool:unsetCache()

Removes the cache from this pool.

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

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
class PacketCache

Represents a cache that can be part of ServerPool.

classmethod PacketCache:expunge(n)

Remove entries from the cache, leaving at most n entries

Parameters:n (int) – Number of entries to keep
classmethod PacketCache: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
classmethod PacketCache:isFull() → bool

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

classmethod PacketCache:printStats()

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

classmethod PacketCache: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
classmethod PacketCache:toString() → string

Return the number of entries in the Packet Cache, and the maximum number of entries

Status, Statistics and More

dumpStats()

Print all statistics dnsdist gathers

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

Print a list of all allowed netmasks.

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

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 or rcode. Optionally grouped by the rightmost labels DNS labels.

Parameters:
  • num (int) – Number to show, defaults to 10
  • rcode (int) – Response code (e.g. 0=NO Error, 2=ServFail, 3=ServFail), defaults to 0
  • 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 the one set with setDynBlocksAction())
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.Refused and DNSAction.Truncate are supported.

addBPFFilterDynBlocks(addresses, filter[, seconds])

Block the set of addresses using the supplied BPF Filter, for seconds seconds (10 by default)

Parameters:
  • addresses – A set of addresses as returned by the exceed functions.
  • filter – and EBPF filter
  • seconds (int) – Number of seconds to block for

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

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.