3 Configuration Reference
4 =======================
6 This page lists all configuration options for dnsdist.
10 When an IPv6 IP:PORT combination is needed, the bracketed syntax from :rfc:`RFC 3986 <3986#section-3.2.2>` should be used.
11 e.g. "[2001:DB8:14::C0FF:FEE]:5300".
16 Within dnsdist several core object types exist:
18 * :class:`Server`: generated with :func:`newServer`, represents a downstream server
19 * :class:`ComboAddress`: represents an IP address and port
20 * :class:`DNSName`: represents a domain name
21 * :class:`NetmaskGroup`: represents a group of netmasks
22 * :class:`QPSLimiter`: implements a QPS-based filter
23 * :class:`SuffixMatchNode`: represents a group of domain suffixes for rapid testing of membership
24 * :class:`DNSHeader`: represents the header of a DNS packet, see :ref:`DNSHeader`
25 * :class:`ClientState`: sometimes also called Bind or Frontend, represents the addresses and ports dnsdist is listening on
27 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:
31 getServer(0).order=12 -- set order of server 0 to 12
32 getServer(0):addPool("abuse") -- add this server to the abuse pool
34 The ``.`` means ``order`` is a data member, while the ``:`` means ``addPool`` is a member function.
39 .. function:: includeDirectory(path)
41 Include configuration files from ``path``.
43 :param str path: The directory to load the configuration from
48 .. function:: addLocal(address[, options])
50 .. versionadded:: 1.2.0
52 .. versionchanged:: 1.3.0
53 Added ``cpus`` to the options.
55 Add to the list of listen addresses.
57 :param str address: The IP Address with an optional port to listen on.
58 The default port is 53.
59 :param table options: A table with key: value pairs with listen options.
63 * ``doTCP=true``: bool - Also bind on TCP on ``address``.
64 * ``reusePort=false``: bool - Set the ``SO_REUSEPORT`` socket option.
65 * ``tcpFastOpenSize=0``: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.
66 * ``interface=""``: str - Set the network interface to use.
67 * ``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.
71 addLocal('0.0.0.0:5300', { doTCP=true, reusePort=true })
73 This will bind to both UDP and TCP on port 5300 with SO_REUSEPORT enabled.
75 .. function:: addLocal(address[[[,do_tcp], so_reuseport], tcp_fast_open_qsize])
79 Add to the list of addresses listened on.
81 :param str address: The IP Address with an optional port to listen on.
82 The default port is 53.
83 :param bool do_tcp: Also bind a TCP port on ``address``, defaults to true.
84 :param bool so_reuseport: Use ``SO_REUSEPORT`` if it is available, defaults to false
85 :param int tcp_fast_open_qsize: The size of the TCP Fast Open queue. Set to a number
86 higher than 0 to enable TCP Fast Open when available.
89 .. function:: addTLSLocal(address, certFile(s), keyFile(s) [, options])
91 .. versionadded:: 1.3.0
92 .. versionchanged:: 1.3.1
93 ``certFile(s)`` and ``keyFile(s)`` parameters accept a list of files.
94 ``sessionTickets`` option added.
96 Listen on the specified address and TCP port for incoming DNS over TLS connections, presenting the specified X.509 certificate.
98 :param str address: The IP Address with an optional port to listen on.
99 The default port is 853.
100 :param str certFile(s): The path to a X.509 certificate file in PEM format, or a list of paths to such files.
101 :param str keyFile(s): 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.
102 :param table options: A table with key: value pairs with listen options.
106 * ``doTCP=true``: bool - Also bind on TCP on ``address``.
107 * ``reusePort=false``: bool - Set the ``SO_REUSEPORT`` socket option.
108 * ``tcpFastOpenSize=0``: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.
109 * ``interface=""``: str - Set the network interface to use.
110 * ``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.
111 * ``provider``: str - The TLS library to use between GnuTLS and OpenSSL, if they were available and enabled at compilation time.
112 * ``ciphers``: str - The TLS ciphers to use. The exact format depends on the provider used.
113 * ``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.
114 * ``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.
115 * ``ticketsKeysRotationDelay``: int - Set the delay before the TLS tickets key is rotated, in seconds. Default is 43200 (12h).
116 * ``sessionTickets``: bool - Whether session resumption via session tickets is enabled. Default is true, meaning tickets are enabled.
118 .. function:: setLocal(address[, options])
120 .. versionadded:: 1.2.0
122 Remove the list of listen addresses and add a new one.
124 :param str address: The IP Address with an optional port to listen on.
125 The default port is 53.
126 :param table options: A table with key: value pairs with listen options.
128 The options that can be set are the same as :func:`addLocal`.
130 .. function:: setLocal(address[[[,do_tcp], so_reuseport], tcp_fast_open_qsize])
132 .. deprecated:: 1.2.0
134 Remove the list of listen addresses and add a new one.
136 :param str address: The IP Address with an optional port to listen on.
137 The default port is 53.
138 :param bool do_tcp: Also bind a TCP port on ``address``, defaults to true.
139 :param bool so_reuseport: Use ``SO_REUSEPORT`` if it is available, defaults to false
140 :param int tcp_fast_open_qsize: The size of the TCP Fast Open queue. Set to a number
141 higher than 0 to enable TCP Fast Open when available.
144 Control Socket, Console and Webserver
145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
147 .. function:: addConsoleACL(netmask)
149 .. versionadded:: 1.3.0
151 Add a netmask to the existing console ACL, allowing remote clients to connect to the console. Please make sure that encryption
152 has been enabled with :func:`setKey` before doing so. The default is to only allow 127.0.0.1/8 and ::1/128.
154 :param str netmask: A CIDR netmask, e.g. ``"192.0.2.0/24"``. Without a subnetmask, only the specific address is allowed.
156 .. function:: controlSocket(address)
158 Bind to ``addr`` and listen for a connection for the console. Since 1.3.0 only connections from local users are allowed
159 by default, :func:`addConsoleACL` and :func:`setConsoleACL` can be used to enable remote connections. Please make sure
160 that encryption has been enabled with :func:`setKey` before doing so. Enabling encryption is also strongly advised for
161 local connections, since not enabling it allows any local user to connect to the console.
163 :param str address: An IP address with optional port. By default, the port is 5199.
165 .. function:: inClientStartup()
167 Returns true while the console client is parsing the configuration.
169 .. function:: makeKey()
171 Generate and print an encryption key.
173 .. function:: setConsoleConnectionsLogging(enabled)
175 .. versionadded:: 1.2.0
177 Whether to log the opening and closing of console connections.
179 :param bool enabled: Default to true.
181 .. function:: setKey(key)
183 Use ``key`` as shared secret between the client and the server
185 :param str key: An encoded key, as generated by :func:`makeKey`
187 .. function:: setConsoleACL(netmasks)
189 .. versionadded:: 1.3.0
191 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
192 has been enabled with :func:`setKey` before doing so.
194 :param {str} netmasks: 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.
196 .. function:: showConsoleACL()
198 Print a list of all netmasks allowed to connect to the console.
200 .. function:: testCrypto()
202 Test the crypto code, will report errors when something is not ok.
207 .. function:: webServer(listen_address, password[, apikey[, custom_headers]])
209 Launch the :doc:`../guides/webserver` with statistics and the API.
211 :param str listen_address: The IP address and Port to listen on
212 :param str password: The password required to access the webserver
213 :param str apikey: The key required to access the API
214 :param {[str]=str,...} custom_headers: Allows setting custom headers and removing the defaults
216 .. function:: setAPIWritable(allow [,dir])
218 Allow modifications via the API.
219 Optionally saving these changes to disk.
220 Modifications done via the API will not be written to the configuration by default and will not persist after a reload
222 :param bool allow: Set to true to allow modification through the API
223 :param str dir: A valid directory where the configuration files will be written by the API.
228 .. function:: addACL(netmask)
230 Add a netmask to the existing ACL controlling which clients can send UDP and TCP queries. See :ref:`ACL` for more information.
232 :param str netmask: A CIDR netmask, e.g. ``"192.0.2.0/24"``. Without a subnetmask, only the specific address is allowed.
234 .. function:: setACL(netmasks)
236 Remove the existing ACL and add the netmasks from the table of those allowed to send UDP and TCP queries. See :ref:`ACL` for more information.
238 :param {str} netmasks: 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.
240 .. function:: showACL()
242 Print a list of all netmasks allowed to send queries over UDP and TCP. See :ref:`ACL` for more information.
247 .. function:: setECSSourcePrefixV4(prefix)
249 When ``useClientSubnet`` in :func:`newServer` is set and dnsdist adds an EDNS Client Subnet Client option to the query, truncate the requestors IPv4 address to ``prefix`` bits
251 :param int prefix: The prefix length
253 .. function:: setECSSourcePrefixV6(prefix)
255 When ``useClientSubnet`` in :func:`newServer` is set and dnsdist adds an EDNS Client Subnet Client option to the query, truncate the requestor's IPv6 address to bits
257 :param int prefix: The prefix length
262 .. function:: setRingBuffersLockRetries(num)
263 .. versionadded:: 1.3.0
265 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
267 :param int num: The maximum number of attempts. Defaults to 5 if there are more than one shard, 0 otherwise.
269 .. function:: setRingBuffersSize(num [, numberOfShards])
270 .. versionchanged:: 1.3.0
271 ``numberOfShards`` optional parameter added.
273 Set the capacity of the ringbuffers used for live traffic inspection to ``num``, and the number of shards to ``numberOfShards`` if specified.
275 :param int num: The maximum amount of queries to keep in the ringbuffer. Defaults to 10000
276 :param int numberOfShards: the number of shards to use to limit lock contention. Defaults to 1
281 .. function:: newServer(server_string)
282 newServer(server_table)
284 .. versionchanged:: 1.3.0
285 - Added ``checkClass`` to server_table.
286 - Added ``sockets`` to server_table
287 - Added ``checkFunction`` to server_table
290 Add a new backend server. Call this function with either a string::
293 "IP:PORT" -- IP and PORT of the backend server
299 address="IP:PORT", -- IP and PORT of the backend server (mandatory)
300 qps=NUM, -- Limit the number of queries per second to NUM, when using the `firstAvailable` policy
301 order=NUM, -- The order of this server, used by the `leastOustanding` and `firstAvailable` policies
302 weight=NUM, -- The weight of this server, used by the `wrandom`, `whashed` and `chashed` policies, default: 1
303 -- Supported values are a minimum of 1, and a maximum of 2147483647.
304 pool=STRING|{STRING}, -- The pools this server belongs to (unset or empty string means default pool) as a string or table of strings
305 retries=NUM, -- The number of TCP connection attempts to the backend, for a given query
306 tcpConnectTimeout=NUM, -- The timeout (in seconds) of a TCP connection attempt
307 tcpSendTimeout=NUM, -- The timeout (in seconds) of a TCP write attempt
308 tcpRecvTimeout=NUM, -- The timeout (in seconds) of a TCP read attempt
309 tcpFastOpen=BOOL, -- Whether to enable TCP Fast Open
310 ipBindAddrNoPort=BOOL, -- Whether to enable IP_BIND_ADDRESS_NO_PORT if available, default: true
311 name=STRING, -- The name associated to this backend, for display purpose
312 checkClass=NUM, -- Use NUM as QCLASS in the health-check query, default: DNSClass.IN
313 checkName=STRING, -- Use STRING as QNAME in the health-check query, default: "a.root-servers.net."
314 checkType=STRING, -- Use STRING as QTYPE in the health-check query, default: "A"
315 checkFunction=FUNCTION -- Use this function to dynamically set the QNAME, QTYPE and QCLASS to use in the health-check query (see :ref:`Healthcheck`)
316 setCD=BOOL, -- Set the CD (Checking Disabled) flag in the health-check query, default: false
317 maxCheckFailures=NUM, -- Allow NUM check failures before declaring the backend down, default: 1
318 mustResolve=BOOL, -- Set to true when the health check MUST return a NOERROR RCODE and an answer
319 useClientSubnet=BOOL, -- Add the client's IP address in the EDNS Client Subnet option when forwarding the query to this backend
320 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
321 -- The following formats are supported:
322 -- "address", e.g. "192.0.2.2"
323 -- "interface name", e.g. "eth0"
324 -- "address@interface", e.g. "192.0.2.2@eth0"
325 addXPF=NUM, -- Add the client's IP address and port to the query, along with the original destination address and port,
326 -- 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)
327 sockets=NUM -- Number of sockets (and thus source ports) used toward the backend server, defaults to a single one
330 :param str server_string: A simple IP:PORT string.
331 :param table server_table: A table with at least a 'name' key
333 .. function:: getServer(index) -> Server
335 Get a :class:`Server`
337 :param int index: The number of the server (as seen in :func:`showServers`).
338 :returns: The :class:`Server` object or nil
340 .. function:: getServers()
342 Returns a table with all defined servers.
344 .. function:: rmServer(index)
347 Remove a backend server.
349 :param int index: The number of the server (as seen in :func:`showServers`).
350 :param Server server: A :class:`Server` object as returned by e.g. :func:`getServer`.
354 A server object returned by :func:`getServer` can be manipulated with these functions.
358 This object represents a backend server. It has several methods.
360 .. method:: Server:addPool(pool)
362 Add this server to a pool.
364 :param str pool: The pool to add the server to
366 .. method:: Server:getName() -> string
368 Get the name of this server.
370 :returns: The name of the server, or an empty string if it does not have one
372 .. method:: Server:getNameWithAddr() -> string
374 Get the name plus IP address and port of the server
376 :returns: A string containing the server name if any plus the server address and port
378 .. method:: Server:getOutstanding() -> int
380 Get the number of outstanding queries for this server.
382 :returns: The number of outstanding queries
384 .. method:: Server:isUp() -> bool
386 Returns the up status of the server
388 :returns: true when the server is up, false otherwise
390 .. method:: Server:rmPool(pool)
392 Removes the server from the named pool
394 :param str pool: The pool to remove the server from
396 .. method:: Server:setAuto([status])
398 .. versionchanged:: 1.3.0
399 ``status`` optional parameter added.
401 Set the server in the default auto state.
402 This will enable health check queries that will set the server ``up`` and ``down`` appropriately.
404 :param bool status: Set the initial status of the server to ``up`` (true) or ``down`` (false) instead of using the last known status
406 .. method:: Server:setQPS(limit)
408 Limit the queries per second for this server.
410 :param int limit: The maximum number of queries per second
412 .. method:: Server:setDown()
414 Set the server in an ``DOWN`` state.
415 The server will not receive queries and the health checks are disabled
417 .. method:: Server:setUp()
419 Set the server in an ``UP`` state.
420 This server will still receive queries and health checks are disabled
422 Apart from the functions, a :class:`Server` object has these attributes:
424 .. attribute:: Server.name
426 The name of the server
428 .. attribute:: Server.upStatus
430 Whether or not this server is up or down
432 .. attribute:: Server.order
434 The order of the server
436 .. attribute:: Server.weight
438 The weight of the server
443 :class:`Server`\ s can be part of any number of pools.
444 Pools are automatically created when a server is added to a pool (with :func:`newServer`), or can be manually created with :func:`addPool`.
446 .. function:: addPool(name) -> ServerPool
448 Returns a :class:`ServerPool`.
450 :param string name: The name of the pool to create
452 .. function:: getPool(name) -> ServerPool
454 Returns a :class:`ServerPool` or nil.
456 :param string name: The name of the pool
458 .. function:: rmPool(name)
460 Remove the pool named `name`.
462 :param string name: The name of the pool to remove
464 .. function:: getPoolServers(name) -> [ Server ]
466 Returns a list of :class:`Server`\ s or nil.
468 :param string name: The name of the pool
470 .. class:: ServerPool
472 This represents the pool where zero or more servers are part of.
474 .. method:: ServerPool:getCache() -> PacketCache
476 Returns the :class:`PacketCache` for this pool or nil.
478 .. method:: ServerPool:getECS()
480 .. versionadded:: 1.3.0
482 Whether dnsdist will add EDNS Client Subnet information to the query before looking up into the cache,
483 when all servers from this pool are down. For more information see :meth:`ServerPool:setECS`.
485 .. method:: ServerPool:setCache(cache)
487 Adds ``cache`` as the pool's cache.
489 :param PacketCache cache: The new cache to add to the pool
491 .. method:: ServerPool:unsetCache()
493 Removes the cache from this pool.
495 .. method:: ServerPool:setECS()
497 .. versionadded:: 1.3.0
499 Set to true if dnsdist should add EDNS Client Subnet information to the query before looking up into the cache,
500 when all servers from this pool are down. If at least one server is up, the preference of the
501 selected server is used, this parameter is only useful if all the backends in this pool are down
502 and have EDNS Client Subnet enabled, since the queries in the cache will have been inserted with
503 ECS information. Default is false.
508 A Pool can have a packet cache to answer queries directly in stead of going to the backend.
509 See :doc:`../guides/cache` for a how to.
511 .. function:: newPacketCache(maxEntries[, maxTTL=86400[, minTTL=0[, temporaryFailureTTL=60[, staleTTL=60[, dontAge=false[, numberOfShards=1[, deferrableInsertLock=true[, maxNegativeTTL=3600[, parseECS=false]]]]]]]) -> PacketCache
513 .. versionchanged:: 1.3.0
514 ``numberOfShards`` and ``deferrableInsertLock`` parameters added.
516 .. versionchanged:: 1.3.1
517 ``maxNegativeTTL`` and ``parseECS`` parameters added.
519 Creates a new :class:`PacketCache` with the settings specified.
521 :param int maxEntries: The maximum number of entries in this cache
522 :param int maxTTL: Cap the TTL for records to his number
523 :param int minTTL: Don't cache entries with a TTL lower than this
524 :param int temporaryFailureTTL: On a SERVFAIL or REFUSED from the backend, cache for this amount of seconds
525 :param int staleTTL: 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
526 :param bool dontAge: Don't reduce TTLs when serving from the cache. Use this when :program:`dnsdist` fronts a cluster of authoritative servers
527 :param int numberOfShards: Number of shards to divide the cache into, to reduce lock contention
528 :param bool deferrableInsertLock: Whether the cache should give up insertion if the lock is held by another thread, or simply wait to get the lock
529 :param int maxNegativeTTL: 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
530 :param bool parseECS: 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
532 .. class:: PacketCache
534 Represents a cache that can be part of :class:`ServerPool`.
536 .. method:: PacketCache:dump(fname)
538 .. versionadded:: 1.3.1
540 Dump a summary of the cache entries to a file.
542 :param str fname: The path to a file where the cache summary should be dumped. Note that if the target file already exists, it will not be overwritten.
544 .. method:: PacketCache:expunge(n)
546 Remove entries from the cache, leaving at most ``n`` entries
548 :param int n: Number of entries to keep
550 .. method:: PacketCache:expungeByName(name [, qtype=dnsdist.ANY[, suffixMatch=false]])
552 .. versionchanged:: 1.2.0
553 ``suffixMatch`` parameter added.
555 Remove entries matching ``name`` and type from the cache.
557 :param DNSName name: The name to expunge
558 :param int qtype: The type to expunge
559 :param bool suffixMatch: When set to true, remove al entries under ``name``
561 .. method:: PacketCache:isFull() -> bool
563 Return true if the cache has reached the maximum number of entries.
565 .. method:: PacketCache:printStats()
567 Print the cache stats (hits, misses, deferred lookups and deferred inserts).
569 .. method:: PacketCache:purgeExpired(n)
571 Remove expired entries from the cache until there is at most ``n`` entries remaining in the cache.
573 :param int n: Number of entries to keep
575 .. method:: PacketCache:toString() -> string
577 Return the number of entries in the Packet Cache, and the maximum number of entries
582 Also called frontend or bind, the Client State object returned by :func:`getBind` and listed with :func:`showBinds` represents an address and port dnsdist is listening on.
584 .. function:: getBind(index) -> ClientState
586 Return a :class:`ClientState` object.
588 :param int index: The object index
590 ClientState functions
591 ~~~~~~~~~~~~~~~~~~~~~
593 .. class:: ClientState
595 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.
597 .. method:: ClientState:attachFilter(filter)
599 Attach a BPF filter to this frontend.
601 :param BPFFilter filter: The filter to attach to this frontend
603 .. method:: ClientState:detachFilter()
605 Remove the BPF filter associated to this frontend, if any.
607 .. method:: ClientState:toString() -> string
609 Return the address and port this frontend is listening on.
611 :returns: The address and port this frontend is listening on
613 .. attribute:: ClientState.muted
615 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.
617 Status, Statistics and More
618 ---------------------------
620 .. function:: dumpStats()
622 Print all statistics dnsdist gathers
624 .. function:: getTLSContext(idx)
626 .. versionadded:: 1.3.0
628 Return the TLSContext object for the context of index ``idx``.
630 .. function:: getTLSFrontend(idx)
632 .. versionadded:: 1.3.1
634 Return the TLSFrontend object for the TLS bind of index ``idx``.
636 .. function:: grepq(selector[, num])
637 grepq(selectors[, num])
639 Prints the last ``num`` queries matching ``selector`` or ``selectors``.
643 * a netmask (e.g. '192.0.2.0/24')
644 * a DNS name (e.g. 'dnsdist.org')
645 * a response time (e.g. '100ms')
647 :param str selector: Select queries based on this property.
648 :param {str} selectors: A lua table of selectors. Only queries matching all selectors are shown
649 :param int num: Show a maximum of ``num`` recent queries, default is 10.
651 .. function:: setVerboseHealthChecks(verbose)
653 Set whether health check errors should be logged. This is turned off by default.
655 :param bool verbose: Set to true if you want to enable health check errors logging
657 .. function:: showBinds()
659 Print a list of all the current addresses and ports dnsdist is listening on, also called ``frontends``
661 .. function:: showResponseLatency()
663 Show a plot of the response time latency distribution
665 .. function:: showServers()
667 This function shows all backend servers currently configured and some statistics.
668 These statics have the following fields:
670 * ``#`` - The number of the server, can be used as the argument for :func:`getServer`
671 * ``Address`` - The IP address and port of the server
672 * ``State`` - The current state of the server
673 * ``Qps`` - Current number of queries per second
674 * ``Qlim`` - Configured maximum number of queries per second
675 * ``Ord`` - The order number of the server
676 * ``Wt`` - The weight of the server
677 * ``Queries`` - Total amount of queries sent to this server
678 * ``Drops`` - Number of queries that were dropped by this server
679 * ``Drate`` - Number of queries dropped per second by this server
680 * ``Lat`` - The latency of this server in milliseconds
681 * ``Pools`` - The pools this server belongs to
683 .. function:: showTCPStats()
685 Show some statistics regarding TCP
687 .. function:: showTLSContexts()
689 .. versionadded:: 1.3.0
691 Print the list of all availables DNS over TLS contexts.
693 .. function:: showVersion()
695 Print the version of dnsdist
697 .. function:: topBandwidth([num])
699 Print the top ``num`` clients that consume the most bandwidth.
701 :param int num: Number to show, defaults to 10.
703 .. function:: topClients([num])
705 Print the top ``num`` clients sending the most queries over length of ringbuffer
707 :param int num: Number to show, defaults to 10.
709 .. function:: topQueries([num[, labels]])
711 Print the ``num`` most popular QNAMEs from queries.
712 Optionally grouped by the rightmost ``labels`` DNS labels.
714 :param int num: Number to show, defaults to 10
715 :param int label: Number of labels to cut down to
717 .. function:: topResponses([num[, rcode[, labels]]])
719 Print the ``num`` most seen responses with an RCODE of ``rcode``.
720 Optionally grouped by the rightmost ``labels`` DNS labels.
722 :param int num: Number to show, defaults to 10
723 :param int rcode: :ref:`Response code <DNSRCode>`, defaults to 0 (No Error)
724 :param int label: Number of labels to cut down to
726 .. function:: topSlow([num[, limit[, labels]]])
728 Print the ``num`` slowest queries that are slower than ``limit`` milliseconds.
729 Optionally grouped by the rightmost ``labels`` DNS labels.
731 :param int num: Number to show, defaults to 10
732 :param int limit: Show queries slower than this amount of milliseconds, defaults to 2000
733 :param int label: Number of labels to cut down to
740 .. function:: addDynBlocks(addresses, message[, seconds=10[, action]])
742 .. versionchanged:: 1.2.0
743 ``action`` parameter added.
745 Block a set of addresses with ``message`` for (optionally) a number of seconds.
746 The default number of seconds to block for is 10.
748 :param addresses: set of Addresses as returned by an exceed function
749 :param string message: The message to show next to the blocks
750 :param int seconds: The number of seconds this block to expire
751 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to DNSAction.None, meaning the one set with :func:`setDynBlocksAction` is used)
753 Please see the documentation for :func:`setDynBlocksAction` to confirm which actions are supported by the action paramater.
755 .. function:: clearDynBlocks()
757 Remove all current dynamic blocks.
759 .. function:: showDynBlocks()
761 List all dynamic blocks in effect.
763 .. function:: setDynBlocksAction(action)
765 Set which action is performed when a query is blocked.
766 Only DNSAction.Drop (the default), DNSAction.NoOp, DNSAction.Refused and DNSAction.Truncate are supported.
770 Getting addresses that exceeded parameters
771 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
773 .. function:: exceedServFails(rate, seconds)
775 Get set of addresses that exceed ``rate`` servfails/s over ``seconds`` seconds
777 :param int rate: Number of Servfails per second to exceed
778 :param int seconds: Number of seconds the rate has been exceeded
780 .. function:: exceedNXDOMAINs(rate, seconds)
782 get set of addresses that exceed ``rate`` NXDOMAIN/s over ``seconds`` seconds
784 :param int rate: Number of NXDOMAIN per second to exceed
785 :param int seconds: Number of seconds the rate has been exceeded
787 .. function:: exceedRespByterate(rate, seconds)
789 get set of addresses that exceeded ``rate`` bytes/s answers over ``seconds`` seconds
791 :param int rate: Number of bytes per second to exceed
792 :param int seconds: Number of seconds the rate has been exceeded
794 .. function:: exceedQRate(rate, seconds)
796 Get set of address that exceed ``rate`` queries/s over ``seconds`` seconds
798 :param int rate: Number of queries per second to exceed
799 :param int seconds: Number of seconds the rate has been exceeded
801 .. function:: exceedQTypeRate(type, rate, seconds)
803 Get set of address that exceed ``rate`` queries/s for queries of QType ``type`` over ``seconds`` seconds
805 :param int type: QType
806 :param int rate: Number of QType queries per second to exceed
807 :param int seconds: Number of seconds the rate has been exceeded
812 Instead of using several `exceed*()` lines, dnsdist 1.3.0 introduced a new `DynBlockRulesGroup` object
813 which can be used to group dynamic block rules.
815 See :doc:`../guides/dynblocks` for more information about the case where using a `DynBlockRulesGroup` might be
816 faster than the existing rules.
818 .. function:: dynBlockRulesGroup() -> DynBlockRulesGroup
820 .. versionadded:: 1.3.0
822 Creates a new :class:`DynBlockRulesGroup` object.
824 .. class:: DynBlockRulesGroup
826 Represents a group of dynamic block rules.
828 .. method:: DynBlockRulesGroup:setQueryRate(rate, seconds, reason, blockingTime [, action])
830 Adds a query rate-limiting rule, equivalent to:
832 addDynBlocks(exceedQRate(rate, seconds), reason, blockingTime, action)
835 :param int rate: Number of queries per second to exceed
836 :param int seconds: Number of seconds the rate has been exceeded
837 :param string reason: The message to show next to the blocks
838 :param int blockingTime: The number of seconds this block to expire
839 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
841 .. method:: DynBlockRulesGroup:setRCodeRate(rcode, rate, seconds, reason, blockingTime [, action])
843 Adds a rate-limiting rule for responses of code ``rcode``, equivalent to:
845 addDynBlocks(exceedServfails(rcode, rate, seconds), reason, blockingTime, action)
848 :param int rcode: The response code
849 :param int rate: Number of responses per second to exceed
850 :param int seconds: Number of seconds the rate has been exceeded
851 :param string reason: The message to show next to the blocks
852 :param int blockingTime: The number of seconds this block to expire
853 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
855 .. method:: DynBlockRulesGroup:setQTypeRate(qtype, rate, seconds, reason, blockingTime [, action])
857 Adds a rate-limiting rule for queries of type ``qtype``, equivalent to:
859 addDynBlocks(exceedQTypeRate(type, rate, seconds), reason, blockingTime, action)
862 :param int qtype: The qtype
863 :param int rate: Number of queries per second to exceed
864 :param int seconds: Number of seconds the rate has been exceeded
865 :param string reason: The message to show next to the blocks
866 :param int blockingTime: The number of seconds this block to expire
867 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
869 .. method:: DynBlockRulesGroup:setRespByteRate(rate, seconds, reason, blockingTime [, action])
871 Adds a bandwidth rate-limiting rule for responses, equivalent to:
873 addDynBlocks(exceedRespByterate(rate, seconds), reason, blockingTime, action)
876 :param int rate: Number of bytes per second to exceed
877 :param int seconds: Number of seconds the rate has been exceeded
878 :param string reason: The message to show next to the blocks
879 :param int blockingTime: The number of seconds this block to expire
880 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
882 .. method:: DynBlockRulesGroup:apply()
884 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.
886 .. method:: DynBlockRulesGroup:excludeRange(netmasks)
888 .. versionadded:: 1.3.1
890 Exclude this range, or list of ranges, meaning that no dynamic block will ever be inserted for clients in that range. Default to empty, meaning rules are applied to all ranges. When used in combination with :meth:`DynBlockRulesGroup:includeRange`, the more specific entry wins.
892 :param int netmasks: A netmask, or list of netmasks, as strings, like for example "192.0.2.1/24"
894 .. method:: DynBlockRulesGroup:includeRange(netmasks)
896 .. versionadded:: 1.3.1
898 Include this range, or list of ranges, meaning that rules will be applied to this range. When used in combination with :meth:`DynBlockRulesGroup:excludeRange`, the more specific entry wins.
900 :param int netmasks: A netmask, or list of netmasks, as strings, like for example "192.0.2.1/24"
902 .. method:: DynBlockRulesGroup:toString()
904 .. versionadded:: 1.3.1
906 Return a string describing the rules and range exclusions of this DynBlockRulesGroup.
911 .. function:: maintenance()
913 If this function exists, it is called every second to so regular tasks.
914 This can be used for e.g. :doc:`Dynamic Blocks <../guides/dynblocks>`.
919 .. class:: TLSContext
921 .. versionadded:: 1.3.0
923 This object represents an address and port dnsdist is listening on for DNS over TLS queries.
925 .. method:: TLSContext:rotateTicketsKey()
927 Replace the current TLS tickets key by a new random one.
929 .. method:: TLSContext:loadTicketsKeys(ticketsKeysFile)
931 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.
933 :param str ticketsKeysFile: The path to a file from where TLS tickets keys should be loaded.
938 .. class:: TLSFrontend
940 .. versionadded:: 1.3.1
942 This object represents the configuration of a listening frontend for DNS over TLS queries. To each frontend is associated a TLSContext.
944 .. method:: TLSContext:loadNewCertificatesAndKeys(certFile(s), keyFile(s))
946 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.
948 :param str certFile(s): The path to a X.509 certificate file in PEM format, or a list of paths to such files.
949 :param str keyFile(s): 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.
951 EDNS on Self-generated answers
952 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
954 There are several mechanisms in dnsdist that turn an existing query into an answer right away,
955 without reaching out to the backend, including :func:`SpoofAction`, :func:`RCodeAction`, :func:`TCAction`
956 and returning a response from ``Lua``. Those responses should, according to :rfc:`6891`, contain an ``OPT``
957 record if the received request had one, which is the case by default and can be disabled using
958 :func:`setAddEDNSToSelfGeneratedResponses`.
960 We must, however, provide a responder's maximum payload size in this record, and we can't easily know the
961 maximum payload size of the actual backend so we need to provide one. The default value is 1500 and can be
962 overriden using :func:`setPayloadSizeOnSelfGeneratedAnswers`.
964 .. function:: setAddEDNSToSelfGeneratedResponses(add)
966 .. versionadded:: 1.3.3
968 Whether to add EDNS to self-generated responses, provided that the initial query had EDNS.
970 :param bool add: Whether to add EDNS, default is true.
972 .. function:: setPayloadSizeOnSelfGeneratedAnswers(payloadSize)
974 .. versionadded:: 1.3.3
976 Set the UDP payload size advertised via EDNS on self-generated responses. In accordance with
977 :rfc:`RFC 6891 <6891#section-6.2.5>`, values lower than 512 will be treated as equal to 512.
979 :param int payloadSize: The responder's maximum UDP payload size, in bytes. Default is 1500.