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:`Netmask`: represents a netmask
22 * :class:`NetmaskGroup`: represents a group of netmasks
23 * :class:`QPSLimiter`: implements a QPS-based filter
24 * :class:`SuffixMatchNode`: represents a group of domain suffixes for rapid testing of membership
25 * :class:`DNSHeader`: represents the header of a DNS packet, see :ref:`DNSHeader`
26 * :class:`ClientState`: sometimes also called Bind or Frontend, represents the addresses and ports dnsdist is listening on
28 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:
32 getServer(0).order=12 -- set order of server 0 to 12
33 getServer(0):addPool("abuse") -- add this server to the abuse pool
35 The ``.`` means ``order`` is a data member, while the ``:`` means ``addPool`` is a member function.
40 .. function:: includeDirectory(path)
42 Include configuration files from ``path``.
44 :param str path: The directory to load configuration files from. Each file must end in ``.conf``.
46 .. function:: reloadAllCertificates()
48 .. versionadded:: 1.4.0
50 Reload all DNSCrypt and TLS certificates, along with their associated keys.
52 .. function:: setSyslogFacility(facility)
54 .. versionadded:: 1.4.0
56 Set the syslog logging facility to ``facility``.
58 :param int facility: The new facility as a numeric value. Defaults to LOG_DAEMON.
63 .. function:: addLocal(address[, options])
65 .. versionadded:: 1.2.0
67 .. versionchanged:: 1.3.0
68 Added ``cpus`` to the options.
70 .. versionchanged:: 1.4.0
71 Removed ``doTCP`` from the options. A listen socket on TCP is always created.
73 Add to the list of listen addresses.
75 :param str address: The IP Address with an optional port to listen on.
76 The default port is 53.
77 :param table options: A table with key: value pairs with listen options.
81 * ``doTCP=true``: bool - Also bind on TCP on ``address``. Removed in 1.4.0.
82 * ``reusePort=false``: bool - Set the ``SO_REUSEPORT`` socket option.
83 * ``tcpFastOpenQueueSize=0``: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.
84 * ``interface=""``: str - Set the network interface to use.
85 * ``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.
89 addLocal('0.0.0.0:5300', { reusePort=true })
91 This will bind to both UDP and TCP on port 5300 with SO_REUSEPORT enabled.
93 .. function:: addLocal(address[[[,do_tcp], so_reuseport], tcp_fast_open_qsize])
97 Add to the list of addresses listened on.
99 :param str address: The IP Address with an optional port to listen on.
100 The default port is 53.
101 :param bool do_tcp: Also bind a TCP port on ``address``, defaults to true.
102 :param bool so_reuseport: Use ``SO_REUSEPORT`` if it is available, defaults to false
103 :param int tcp_fast_open_qsize: The size of the TCP Fast Open queue. Set to a number
104 higher than 0 to enable TCP Fast Open when available.
107 .. function:: addDOHLocal(address, [certFile(s) [, keyFile(s) [, urls [, options]]]])
109 .. versionadded:: 1.4.0
111 .. versionchanged:: 1.5.0
112 ``sendCacheControlHeaders``, ``sessionTimeout``, ``trustForwardedForHeader`` options added.
113 ``url`` now defaults to ``/dns-query`` instead of ``/``
115 Listen on the specified address and TCP port for incoming DNS over HTTPS connections, presenting the specified X.509 certificate.
116 If no certificate (or key) files are specified, listen for incoming DNS over HTTP connections instead.
118 :param str address: The IP Address with an optional port to listen on.
119 The default port is 443.
120 :param str certFile(s): The path to a X.509 certificate file in PEM format, or a list of paths to such files.
121 :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.
122 :param str-or-list urls: A base URL, or a list of base URLs, to accept queries on. Any query with a path under one of these will be treated as a DoH query. The default is /dns-query.
123 :param table options: A table with key: value pairs with listen options.
127 * ``reusePort=false``: bool - Set the ``SO_REUSEPORT`` socket option.
128 * ``tcpFastOpenQueueSize=0``: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.
129 * ``interface=""``: str - Set the network interface to use.
130 * ``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.
131 * ``idleTimeout=30``: int - Set the idle timeout, in seconds.
132 * ``ciphers``: str - The TLS ciphers to use, in OpenSSL format. Ciphers for TLS 1.3 must be specified via ``ciphersTLS13``.
133 * ``ciphersTLS13``: str - The TLS ciphers to use for TLS 1.3, in OpenSSL format.
134 * ``serverTokens``: str - The content of the Server: HTTP header returned by dnsdist. The default is "h2o/dnsdist".
135 * ``customResponseHeaders={}``: table - Set custom HTTP header(s) returned by dnsdist.
136 * ``ocspResponses``: list - List of files containing OCSP responses, in the same order than the certificates and keys, that will be used to provide OCSP stapling responses.
137 * ``minTLSVersion``: str - Minimum version of the TLS protocol to support. Possible values are 'tls1.0', 'tls1.1', 'tls1.2' and 'tls1.3'. Default is to require at least TLS 1.0.
138 * ``numberOfTicketsKeys``: int - The maximum number of tickets keys to keep in memory at the same time. Only one key is marked as active and used to encrypt new tickets while the remaining ones can still be used to decrypt existing tickets after a rotation. Default to 5.
139 * ``ticketKeyFile``: str - The path to a file from where TLS tickets keys should be loaded, to support RFC 5077. These keys should be rotated often and never written to persistent storage to preserve forward secrecy. The default is to generate a random key. dnsdist supports several tickets keys to be able to decrypt existing sessions after the rotation.
140 * ``ticketsKeysRotationDelay``: int - Set the delay before the TLS tickets key is rotated, in seconds. Default is 43200 (12h).
141 * ``sessionTimeout``: int - Set the TLS session lifetime in seconds, this is used both for TLS ticket lifetime and for sessions kept in memory.
142 * ``sessionTickets``: bool - Whether session resumption via session tickets is enabled. Default is true, meaning tickets are enabled.
143 * ``numberOfStoredSessions``: int - The maximum number of sessions kept in memory at the same time. Default is 20480. Setting this value to 0 disables stored session entirely.
144 * ``preferServerCiphers``: bool - Whether to prefer the order of ciphers set by the server instead of the one set by the client. Default is true, meaning that the order of the server is used.
145 * ``keyLogFile``: str - Write the TLS keys in the specified file so that an external program can decrypt TLS exchanges, in the format described in https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format. Note that this feature requires OpenSSL >= 1.1.1.
146 * ``sendCacheControlHeaders``: bool - Whether to parse the response to find the lowest TTL and set a HTTP Cache-Control header accordingly. Default is true.
147 * ``trustForwardedForHeader``: bool - Whether to parse any existing X-Forwarded-For header in the HTTP query and use the right-most value as the client source address and port, for ACL checks, rules, logging and so on. Default is false.
149 .. function:: addTLSLocal(address, certFile(s), keyFile(s) [, options])
151 .. versionadded:: 1.3.0
152 .. versionchanged:: 1.3.1
153 ``certFile(s)`` and ``keyFile(s)`` parameters accept a list of files.
154 ``sessionTickets`` option added.
155 .. versionchanged:: 1.3.3
156 ``numberOfStoredSessions`` option added.
157 .. versionchanged:: 1.4.0
158 ``ciphersTLS13``, ``minTLSVersion``, ``ocspResponses``, ``preferServerCiphers``, ``keyLogFile`` options added.
159 .. versionchanged:: 1.5.0
160 ``sessionTimeout`` option added.
162 Listen on the specified address and TCP port for incoming DNS over TLS connections, presenting the specified X.509 certificate.
164 :param str address: The IP Address with an optional port to listen on.
165 The default port is 853.
166 :param str certFile(s): The path to a X.509 certificate file in PEM format, or a list of paths to such files.
167 :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.
168 :param table options: A table with key: value pairs with listen options.
172 * ``reusePort=false``: bool - Set the ``SO_REUSEPORT`` socket option.
173 * ``tcpFastOpenQueueSize=0``: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.
174 * ``interface=""``: str - Set the network interface to use.
175 * ``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.
176 * ``provider``: str - The TLS library to use between GnuTLS and OpenSSL, if they were available and enabled at compilation time. Default is to use OpenSSL when available.
177 * ``ciphers``: str - The TLS ciphers to use. The exact format depends on the provider used. When the OpenSSL provder is used, ciphers for TLS 1.3 must be specified via ``ciphersTLS13``.
178 * ``ciphersTLS13``: str - The ciphers to use for TLS 1.3, when the OpenSSL provider is used. When the GnuTLS provider is used, ``ciphers`` applies regardless of the TLS protocol and this setting is not used.
179 * ``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.
180 * ``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.
181 * ``ticketsKeysRotationDelay``: int - Set the delay before the TLS tickets key is rotated, in seconds. Default is 43200 (12h).
182 * ``sessionTimeout``: int - Set the TLS session lifetime in seconds, this is used both for TLS ticket lifetime and for sessions kept in memory.
183 * ``sessionTickets``: bool - Whether session resumption via session tickets is enabled. Default is true, meaning tickets are enabled.
184 * ``numberOfStoredSessions``: int - The maximum number of sessions kept in memory at the same time. At this time this is only supported by the OpenSSL provider, as stored sessions are not supported with the GnuTLS one. Default is 20480. Setting this value to 0 disables stored session entirely.
185 * ``ocspResponses``: list - List of files containing OCSP responses, in the same order than the certificates and keys, that will be used to provide OCSP stapling responses.
186 * ``minTLSVersion``: str - Minimum version of the TLS protocol to support. Possible values are 'tls1.0', 'tls1.1', 'tls1.2' and 'tls1.3'. Default is to require at least TLS 1.0. Note that this value is ignored when the GnuTLS provider is in use, and the ``ciphers`` option should be set accordingly instead. For example, 'NORMAL:!VERS-TLS1.0:!VERS-TLS1.1' will disable TLS 1.0 and 1.1.
187 * ``preferServerCiphers``: bool - Whether to prefer the order of ciphers set by the server instead of the one set by the client. Default is true, meaning that the order of the server is used.
188 * ``keyLogFile``: str - Write the TLS keys in the specified file so that an external program can decrypt TLS exchanges, in the format described in https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format. Note that this feature requires OpenSSL >= 1.1.1.
190 .. function:: setLocal(address[, options])
192 .. versionadded:: 1.2.0
194 Remove the list of listen addresses and add a new one.
196 :param str address: The IP Address with an optional port to listen on.
197 The default port is 53.
198 :param table options: A table with key: value pairs with listen options.
200 The options that can be set are the same as :func:`addLocal`.
202 .. function:: setLocal(address[[[,do_tcp], so_reuseport], tcp_fast_open_qsize])
204 .. deprecated:: 1.2.0
206 Remove the list of listen addresses and add a new one.
208 :param str address: The IP Address with an optional port to listen on.
209 The default port is 53.
210 :param bool do_tcp: Also bind a TCP port on ``address``, defaults to true.
211 :param bool so_reuseport: Use ``SO_REUSEPORT`` if it is available, defaults to false
212 :param int tcp_fast_open_qsize: The size of the TCP Fast Open queue. Set to a number
213 higher than 0 to enable TCP Fast Open when available.
216 Control Socket, Console and Webserver
217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
219 .. function:: addConsoleACL(netmask)
221 .. versionadded:: 1.3.0
223 Add a netmask to the existing console ACL, allowing remote clients to connect to the console. Please make sure that encryption
224 has been enabled with :func:`setKey` before doing so. The default is to only allow 127.0.0.1/8 and ::1/128.
226 :param str netmask: A CIDR netmask, e.g. ``"192.0.2.0/24"``. Without a subnetmask, only the specific address is allowed.
228 .. function:: controlSocket(address)
230 Bind to ``addr`` and listen for a connection for the console. Since 1.3.0 only connections from local users are allowed
231 by default, :func:`addConsoleACL` and :func:`setConsoleACL` can be used to enable remote connections. Please make sure
232 that encryption has been enabled with :func:`setKey` before doing so. Enabling encryption is also strongly advised for
233 local connections, since not enabling it allows any local user to connect to the console.
235 :param str address: An IP address with optional port. By default, the port is 5199.
237 .. function:: inClientStartup()
239 Returns true while the console client is parsing the configuration.
241 .. function:: inConfigCheck()
243 .. versionadded:: 1.5.0
245 Returns true while the configuration is being checked, ie when run with ``--check-config``.
247 .. function:: makeKey()
249 Generate and print an encryption key.
251 .. function:: setConsoleConnectionsLogging(enabled)
253 .. versionadded:: 1.2.0
255 Whether to log the opening and closing of console connections.
257 :param bool enabled: Default to true.
259 .. function:: setKey(key)
261 Use ``key`` as shared secret between the client and the server
263 :param str key: An encoded key, as generated by :func:`makeKey`
265 .. function:: setConsoleACL(netmasks)
267 .. versionadded:: 1.3.0
269 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
270 has been enabled with :func:`setKey` before doing so.
272 :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.
274 .. function:: showConsoleACL()
276 Print a list of all netmasks allowed to connect to the console.
278 .. function:: testCrypto()
280 Test the crypto code, will report errors when something is not ok.
282 .. function:: setConsoleOutputMaxMsgSize(size)
284 .. versionadded:: 1.3.3
286 Set the maximum size in bytes of a single console message, default set to 10 MB.
288 :param int size: The new maximum size.
290 Webserver configuration
291 ~~~~~~~~~~~~~~~~~~~~~~~
293 .. function:: webserver(listen_address, password[, apikey[, custom_headers]])
295 Launch the :doc:`../guides/webserver` with statistics and the API.
297 :param str listen_address: The IP address and Port to listen on
298 :param str password: The password required to access the webserver
299 :param str apikey: The key required to access the API
300 :param {[str]=str,...} custom_headers: Allows setting custom headers and removing the defaults
302 .. function:: setAPIWritable(allow [,dir])
304 Allow modifications via the API.
305 Optionally saving these changes to disk.
306 Modifications done via the API will not be written to the configuration by default and will not persist after a reload
308 :param bool allow: Set to true to allow modification through the API
309 :param str dir: A valid directory where the configuration files will be written by the API.
311 .. function:: setWebserverConfig(options)
313 .. versionadded:: 1.3.3
315 Setup webserver configuration. See :func:`webserver`.
317 :param table options: A table with key: value pairs with webserver options.
321 * ``password=newPassword``: string - Changes the API password
322 * ``apiKey=newKey``: string - Changes the API Key (set to an empty string do disable it)
323 * ``custom_headers={[str]=str,...}``: map of string - Allows setting custom headers and removing the defaults.
328 .. function:: addACL(netmask)
330 Add a netmask to the existing ACL controlling which clients can send UDP, TCP, DNS over TLS and DNS over HTTPS queries. See :ref:`ACL` for more information.
332 :param str netmask: A CIDR netmask, e.g. ``"192.0.2.0/24"``. Without a subnetmask, only the specific address is allowed.
334 .. function:: rmACL(netmask)
336 Remove a network from the existing ACL controlling which clients can send UDP, TCP, DNS over TLS and DNS over HTTPS queries. See :ref:`ACL` for more information.
337 This function only removes previously added entries, it does not remove subnets of entries.
339 :param str netmask: A CIDR netmask, e.g. ``"192.0.2.0/24"``. Without a subnetmask, only the specific address is allowed.
343 addACL("192.0.2.0/24") -- for example add subnet to the ACL
344 rmACL("192.0.2.10") -- does NOT work, the ACL is unchanged
345 rmACL("192.0.2.0/24") -- does work, the exact match is removed from the ACL
347 .. function:: setACL(netmasks)
349 Remove the existing ACL and add the netmasks from the table of those allowed to send UDP, TCP, DNS over TLS and DNS over HTTPS queries. See :ref:`ACL` for more information.
351 :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.
353 .. function:: showACL()
355 Print a list of all netmasks allowed to send queries over UDP, TCP, DNS over TLS and DNS over HTTPS. See :ref:`ACL` for more information.
360 .. function:: setECSOverride(bool)
362 When ``useClientSubnet`` in :func:`newServer` is set and dnsdist adds an EDNS Client Subnet Client option to the query, override an existing option already present in the query, if any
364 :param bool: Whether to override an existing EDNS Client Subnet option present in the query. Defaults to false
366 .. function:: setECSSourcePrefixV4(prefix)
368 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
370 :param int prefix: The prefix length
372 .. function:: setECSSourcePrefixV6(prefix)
374 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
376 :param int prefix: The prefix length
381 .. function:: setRingBuffersLockRetries(num)
383 .. versionadded:: 1.3.0
385 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
387 :param int num: The maximum number of attempts. Defaults to 5 if there is more than one shard, 0 otherwise.
389 .. function:: setRingBuffersSize(num [, numberOfShards])
391 .. versionchanged:: 1.3.0
392 ``numberOfShards`` optional parameter added.
394 Set the capacity of the ringbuffers used for live traffic inspection to ``num``, and the number of shards to ``numberOfShards`` if specified.
396 :param int num: The maximum amount of queries to keep in the ringbuffer. Defaults to 10000
397 :param int numberOfShards: the number of shards to use to limit lock contention. Defaults to 1
402 .. function:: newServer(server_string)
403 newServer(server_table)
405 .. versionchanged:: 1.3.0
406 Added ``checkClass``, ``sockets`` and ``checkFunction`` to server_table.
408 .. versionchanged:: 1.4.0
409 Added ``checkInterval``, ``checkTimeout`` and ``rise`` to server_table.
411 .. versionchanged:: 1.5.0
412 Added ``useProxyProtocol`` to server_table.
414 Add a new backend server. Call this function with either a string::
417 "IP:PORT" -- IP and PORT of the backend server
423 address="IP:PORT", -- IP and PORT of the backend server (mandatory)
424 id=STRING, -- Use a pre-defined UUID instead of a random one
425 qps=NUM, -- Limit the number of queries per second to NUM, when using the `firstAvailable` policy
426 order=NUM, -- The order of this server, used by the `leastOutstanding` and `firstAvailable` policies
427 weight=NUM, -- The weight of this server, used by the `wrandom`, `whashed` and `chashed` policies, default: 1
428 -- Supported values are a minimum of 1, and a maximum of 2147483647.
429 pool=STRING|{STRING}, -- The pools this server belongs to (unset or empty string means default pool) as a string or table of strings
430 retries=NUM, -- The number of TCP connection attempts to the backend, for a given query
431 tcpConnectTimeout=NUM, -- The timeout (in seconds) of a TCP connection attempt
432 tcpSendTimeout=NUM, -- The timeout (in seconds) of a TCP write attempt
433 tcpRecvTimeout=NUM, -- The timeout (in seconds) of a TCP read attempt
434 tcpFastOpen=BOOL, -- Whether to enable TCP Fast Open
435 ipBindAddrNoPort=BOOL, -- Whether to enable IP_BIND_ADDRESS_NO_PORT if available, default: true
436 name=STRING, -- The name associated to this backend, for display purpose
437 checkClass=NUM, -- Use NUM as QCLASS in the health-check query, default: DNSClass.IN
438 checkName=STRING, -- Use STRING as QNAME in the health-check query, default: "a.root-servers.net."
439 checkType=STRING, -- Use STRING as QTYPE in the health-check query, default: "A"
440 checkFunction=FUNCTION,-- Use this function to dynamically set the QNAME, QTYPE and QCLASS to use in the health-check query (see :ref:`Healthcheck`)
441 checkTimeout=NUM, -- The timeout (in milliseconds) of a health-check query, default: 1000 (1s)
442 setCD=BOOL, -- Set the CD (Checking Disabled) flag in the health-check query, default: false
443 maxCheckFailures=NUM, -- Allow NUM check failures before declaring the backend down, default: 1
444 checkInterval=NUM -- The time in seconds between health checks
445 mustResolve=BOOL, -- Set to true when the health check MUST return a RCODE different from NXDomain, ServFail and Refused. Default is false, meaning that every RCODE except ServFail is considered valid
446 useClientSubnet=BOOL, -- Add the client's IP address in the EDNS Client Subnet option when forwarding the query to this backend
447 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
448 -- The following formats are supported:
449 -- "address", e.g. "192.0.2.2"
450 -- "interface name", e.g. "eth0"
451 -- "address@interface", e.g. "192.0.2.2@eth0"
452 addXPF=NUM, -- Add the client's IP address and port to the query, along with the original destination address and port,
453 -- 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)
454 sockets=NUM, -- Number of sockets (and thus source ports) used toward the backend server, defaults to a single one
455 disableZeroScope=BOOL, -- Disable the EDNS Client Subnet 'zero scope' feature, which does a cache lookup for an answer valid for all subnets (ECS scope of 0) before adding ECS information to the query and doing the regular lookup. This requires the ``parseECS`` option of the corresponding cache to be set to true
456 rise=NUM, -- Require NUM consecutive successful checks before declaring the backend up, default: 1
457 useProxyProtocol=BOOL -- Add a proxy protocol header to the query, passing along the client's IP address and port along with the original destination address and port. Default is disabled.
460 :param str server_string: A simple IP:PORT string.
461 :param table server_table: A table with at least a 'name' key
463 .. function:: getServer(index) -> Server
465 .. versionchanged:: 1.5.0
466 ``index`` might be an UUID.
468 Get a :class:`Server`
470 :param int or str index: The number of the server (as seen in :func:`showServers`) or its UUID as a string.
471 :returns: The :class:`Server` object or nil
473 .. function:: getServers()
475 Returns a table with all defined servers.
477 .. function:: rmServer(index)
481 .. versionchanged:: 1.5.0
482 ``uuid`` selection added.
484 Remove a backend server.
486 :param int or str index: The number of the server (as seen in :func:`showServers`), its UUID as a string, or a server object.
487 :param Server server: A :class:`Server` object as returned by e.g. :func:`getServer`.
491 A server object returned by :func:`getServer` can be manipulated with these functions.
495 This object represents a backend server. It has several methods.
497 .. method:: Server:addPool(pool)
499 Add this server to a pool.
501 :param str pool: The pool to add the server to
503 .. method:: Server:getName() -> string
505 Get the name of this server.
507 :returns: The name of the server, or an empty string if it does not have one
509 .. method:: Server:getNameWithAddr() -> string
511 Get the name plus IP address and port of the server
513 :returns: A string containing the server name if any plus the server address and port
515 .. method:: Server:getOutstanding() -> int
517 Get the number of outstanding queries for this server.
519 :returns: The number of outstanding queries
521 .. method:: Server:isUp() -> bool
523 Returns the up status of the server
525 :returns: true when the server is up, false otherwise
527 .. method:: Server:rmPool(pool)
529 Removes the server from the named pool
531 :param str pool: The pool to remove the server from
533 .. method:: Server:setAuto([status])
535 .. versionchanged:: 1.3.0
536 ``status`` optional parameter added.
538 Set the server in the default auto state.
539 This will enable health check queries that will set the server ``up`` and ``down`` appropriately.
541 :param bool status: Set the initial status of the server to ``up`` (true) or ``down`` (false) instead of using the last known status
543 .. method:: Server:setQPS(limit)
545 Limit the queries per second for this server.
547 :param int limit: The maximum number of queries per second
549 .. method:: Server:setDown()
551 Set the server in an ``DOWN`` state.
552 The server will not receive queries and the health checks are disabled
554 .. method:: Server:setUp()
556 Set the server in an ``UP`` state.
557 This server will still receive queries and health checks are disabled
559 Apart from the functions, a :class:`Server` object has these attributes:
561 .. attribute:: Server.name
563 The name of the server
565 .. attribute:: Server.upStatus
567 Whether or not this server is up or down
569 .. attribute:: Server.order
571 The order of the server
573 .. attribute:: Server.weight
575 The weight of the server
580 :class:`Server`\ s can be part of any number of pools.
581 Pools are automatically created when a server is added to a pool (with :func:`newServer`), or can be manually created with :func:`addPool`.
583 .. function:: addPool(name) -> ServerPool
585 Returns a :class:`ServerPool`.
587 :param string name: The name of the pool to create
589 .. function:: getPool(name) -> ServerPool
591 Returns a :class:`ServerPool` or nil.
593 :param string name: The name of the pool
595 .. function:: getPoolServers(name) -> [ Server ]
597 Returns a list of :class:`Server`\ s or nil.
599 :param string name: The name of the pool
601 .. function:: showPools()
603 Display the name, associated cache, server policy and associated servers for every pool.
605 .. class:: ServerPool
607 This represents the pool where zero or more servers are part of.
609 .. method:: ServerPool:getCache() -> PacketCache
611 Returns the :class:`PacketCache` for this pool or nil.
613 .. method:: ServerPool:getECS()
615 .. versionadded:: 1.3.0
617 Whether dnsdist will add EDNS Client Subnet information to the query before looking up into the cache,
618 when all servers from this pool are down. For more information see :meth:`ServerPool:setECS`.
620 .. method:: ServerPool:setCache(cache)
622 Adds ``cache`` as the pool's cache.
624 :param PacketCache cache: The new cache to add to the pool
626 .. method:: ServerPool:unsetCache()
628 Removes the cache from this pool.
630 .. method:: ServerPool:setECS()
632 .. versionadded:: 1.3.0
634 Set to true if dnsdist should add EDNS Client Subnet information to the query before looking up into the cache,
635 when all servers from this pool are down. If at least one server is up, the preference of the
636 selected server is used, this parameter is only useful if all the backends in this pool are down
637 and have EDNS Client Subnet enabled, since the queries in the cache will have been inserted with
638 ECS information. Default is false.
643 A Pool can have a packet cache to answer queries directly instead of going to the backend.
644 See :doc:`../guides/cache` for a how to.
646 .. function:: newPacketCache(maxEntries[, maxTTL=86400[, minTTL=0[, temporaryFailureTTL=60[, staleTTL=60[, dontAge=false[, numberOfShards=1[, deferrableInsertLock=true[, maxNegativeTTL=3600[, parseECS=false]]]]]]]) -> PacketCache
648 .. versionchanged:: 1.3.0
649 ``numberOfShards`` and ``deferrableInsertLock`` parameters added.
651 .. versionchanged:: 1.3.1
652 ``maxNegativeTTL`` and ``parseECS`` parameters added.
654 .. deprecated:: 1.4.0
656 Creates a new :class:`PacketCache` with the settings specified.
658 :param int maxEntries: The maximum number of entries in this cache
659 :param int maxTTL: Cap the TTL for records to his number
660 :param int minTTL: Don't cache entries with a TTL lower than this
661 :param int temporaryFailureTTL: On a SERVFAIL or REFUSED from the backend, cache for this amount of seconds
662 :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
663 :param bool dontAge: Don't reduce TTLs when serving from the cache. Use this when :program:`dnsdist` fronts a cluster of authoritative servers
664 :param int numberOfShards: Number of shards to divide the cache into, to reduce lock contention
665 :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
666 :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
667 :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
669 .. function:: newPacketCache(maxEntries, [options]) -> PacketCache
671 .. versionadded:: 1.4.0
673 Creates a new :class:`PacketCache` with the settings specified.
675 :param int maxEntries: The maximum number of entries in this cache
679 * ``deferrableInsertLock=true``: bool - Whether the cache should give up insertion if the lock is held by another thread, or simply wait to get the lock.
680 * ``dontAge=false``: bool - Don't reduce TTLs when serving from the cache. Use this when :program:`dnsdist` fronts a cluster of authoritative servers.
681 * ``keepStaleData=false``: bool - Whether to suspend the removal of expired entries from the cache when there is no backend available in at least one of the pools using this cache.
682 * ``maxNegativeTTL=3600``: int - Cache a NXDomain or NoData answer from the backend for at most this amount of seconds, even if the TTL of the SOA record is higher.
683 * ``maxTTL=86400``: int - Cap the TTL for records to his number.
684 * ``minTTL=0``: int - Don't cache entries with a TTL lower than this.
685 * ``numberOfShards=1``: int - Number of shards to divide the cache into, to reduce lock contention.
686 * ``parseECS=false``: bool - Whether any EDNS Client Subnet option present in the query should be extracted and stored to be able to detect hash collisions involving queries with the same qname, qtype and qclass but a different incoming ECS value. Enabling this option adds a parsing cost and only makes sense if at least one backend might send different responses based on the ECS value, so it's disabled by default. Enabling this option is required for the 'zero scope' option to work
687 * ``staleTTL=60``: int - When the backend servers are not reachable, and global configuration ``setStaleCacheEntriesTTL`` is set appropriately, TTL that will be used when a stale cache entry is returned.
688 * ``temporaryFailureTTL=60``: int - On a SERVFAIL or REFUSED from the backend, cache for this amount of seconds..
690 .. class:: PacketCache
692 Represents a cache that can be part of :class:`ServerPool`.
694 .. method:: PacketCache:dump(fname)
696 .. versionadded:: 1.3.1
698 Dump a summary of the cache entries to a file.
700 :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.
702 .. method:: PacketCache:expunge(n)
704 Remove entries from the cache, leaving at most ``n`` entries
706 :param int n: Number of entries to keep
708 .. method:: PacketCache:expungeByName(name [, qtype=DNSQType.ANY[, suffixMatch=false]])
710 .. versionchanged:: 1.2.0
711 ``suffixMatch`` parameter added.
713 Remove entries matching ``name`` and type from the cache.
715 :param DNSName name: The name to expunge
716 :param int qtype: The type to expunge, can be a pre-defined :ref:`DNSQType`
717 :param bool suffixMatch: When set to true, remove al entries under ``name``
719 .. method:: PacketCache:getStats()
721 .. versionadded:: 1.4.0
723 Return the cache stats (number of entries, hits, misses, deferred lookups, deferred inserts, lookup collisions, insert collisions and TTL too shorts) as a Lua table.
725 .. method:: PacketCache:isFull() -> bool
727 Return true if the cache has reached the maximum number of entries.
729 .. method:: PacketCache:printStats()
731 Print the cache stats (number of entries, hits, misses, deferred lookups, deferred inserts, lookup collisions, insert collisions and TTL too shorts).
733 .. method:: PacketCache:purgeExpired(n)
735 Remove expired entries from the cache until there is at most ``n`` entries remaining in the cache.
737 :param int n: Number of entries to keep
739 .. method:: PacketCache:toString() -> string
741 Return the number of entries in the Packet Cache, and the maximum number of entries
746 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.
748 .. function:: getBind(index) -> ClientState
750 Return a :class:`ClientState` object.
752 :param int index: The object index
754 .. function:: getBindCount()
756 .. versionadded:: 1.5.0
758 Return the number of binds (Do53, DNSCrypt, DoH and DoT).
760 ClientState functions
761 ~~~~~~~~~~~~~~~~~~~~~
763 .. class:: ClientState
765 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.
767 .. method:: ClientState:attachFilter(filter)
769 Attach a BPF filter to this frontend.
771 :param BPFFilter filter: The filter to attach to this frontend
773 .. method:: ClientState:detachFilter()
775 Remove the BPF filter associated to this frontend, if any.
777 .. method:: ClientState:toString() -> string
779 Return the address and port this frontend is listening on.
781 :returns: The address and port this frontend is listening on
783 .. attribute:: ClientState.muted
785 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.
787 Status, Statistics and More
788 ---------------------------
790 .. function:: dumpStats()
792 Print all statistics dnsdist gathers
794 .. function:: getDOHFrontend(idx)
796 .. versionadded:: 1.4.0
798 Return the DOHFrontend object for the DNS over HTTPS bind of index ``idx``.
800 .. function:: getDOHFrontendCount()
802 .. versionadded:: 1.5.0
804 Return the number of DOHFrontend binds.
806 .. function:: getTLSContext(idx)
808 .. versionadded:: 1.3.0
810 Return the TLSContext object for the context of index ``idx``.
812 .. function:: getTLSFrontend(idx)
814 .. versionadded:: 1.3.1
816 Return the TLSFrontend object for the TLS bind of index ``idx``.
818 .. function:: getTLSFrontendCount()
820 .. versionadded:: 1.5.0
822 Return the number of TLSFrontend binds.
824 .. function:: grepq(selector[, num])
825 grepq(selectors[, num])
827 Prints the last ``num`` queries matching ``selector`` or ``selectors``.
831 * a netmask (e.g. '192.0.2.0/24')
832 * a DNS name (e.g. 'dnsdist.org')
833 * a response time (e.g. '100ms')
835 :param str selector: Select queries based on this property.
836 :param {str} selectors: A lua table of selectors. Only queries matching all selectors are shown
837 :param int num: Show a maximum of ``num`` recent queries, default is 10.
839 .. function:: setVerboseHealthChecks(verbose)
841 Set whether health check errors should be logged. This is turned off by default.
843 :param bool verbose: Set to true if you want to enable health check errors logging
845 .. function:: showBinds()
847 Print a list of all the current addresses and ports dnsdist is listening on, also called ``frontends``
849 .. function:: showDOHFrontends()
851 .. versionadded:: 1.4.0
853 Print the list of all availables DNS over HTTPS frontends.
855 .. function:: showDOHResponseCodes()
857 .. versionadded:: 1.4.0
859 Print the HTTP response codes statistics for all availables DNS over HTTPS frontends.
861 .. function:: showResponseLatency()
863 Show a plot of the response time latency distribution
865 .. function:: showServers([options])
867 .. versionchanged:: 1.4.0
868 ``options`` optional parameter added
870 This function shows all backend servers currently configured and some statistics.
871 These statics have the following fields:
873 * ``#`` - The number of the server, can be used as the argument for :func:`getServer`
874 * ``UUID`` - The UUID of the backend. Can be set with the ``id`` option of :func:`newServer`
875 * ``Address`` - The IP address and port of the server
876 * ``State`` - The current state of the server
877 * ``Qps`` - Current number of queries per second
878 * ``Qlim`` - Configured maximum number of queries per second
879 * ``Ord`` - The order number of the server
880 * ``Wt`` - The weight of the server
881 * ``Queries`` - Total amount of queries sent to this server
882 * ``Drops`` - Number of queries that were dropped by this server
883 * ``Drate`` - Number of queries dropped per second by this server
884 * ``Lat`` - The latency of this server in milliseconds
885 * ``Pools`` - The pools this server belongs to
887 :param table options: A table with key: value pairs with display options.
891 * ``showUUIDs=false``: bool - Whether to display the UUIDs, defaults to false.
893 .. function:: showTCPStats()
895 Show some statistics regarding TCP
897 .. function:: showTLSContexts()
899 .. versionadded:: 1.3.0
901 Print the list of all availables DNS over TLS contexts.
903 .. function:: showTLSErrorCounters()
905 .. versionadded:: 1.4.0
907 Display metrics about TLS handshake failures.
909 .. function:: showVersion()
911 Print the version of dnsdist
913 .. function:: topBandwidth([num])
915 Print the top ``num`` clients that consume the most bandwidth.
917 :param int num: Number to show, defaults to 10.
919 .. function:: topClients([num])
921 Print the top ``num`` clients sending the most queries over length of ringbuffer
923 :param int num: Number to show, defaults to 10.
925 .. function:: topQueries([num[, labels]])
927 Print the ``num`` most popular QNAMEs from queries.
928 Optionally grouped by the rightmost ``labels`` DNS labels.
930 :param int num: Number to show, defaults to 10
931 :param int label: Number of labels to cut down to
933 .. function:: topResponses([num[, rcode[, labels]]])
935 Print the ``num`` most seen responses with an RCODE of ``rcode``.
936 Optionally grouped by the rightmost ``labels`` DNS labels.
938 :param int num: Number to show, defaults to 10
939 :param int rcode: :ref:`Response code <DNSRCode>`, defaults to 0 (No Error)
940 :param int label: Number of labels to cut down to
942 .. function:: topSlow([num[, limit[, labels]]])
944 Print the ``num`` slowest queries that are slower than ``limit`` milliseconds.
945 Optionally grouped by the rightmost ``labels`` DNS labels.
947 :param int num: Number to show, defaults to 10
948 :param int limit: Show queries slower than this amount of milliseconds, defaults to 2000
949 :param int label: Number of labels to cut down to
956 .. function:: addDynBlocks(addresses, message[, seconds=10[, action]])
958 .. versionchanged:: 1.2.0
959 ``action`` parameter added.
961 Block a set of addresses with ``message`` for (optionally) a number of seconds.
962 The default number of seconds to block for is 10.
964 :param addresses: set of Addresses as returned by an exceed function
965 :param string message: The message to show next to the blocks
966 :param int seconds: The number of seconds this block to expire
967 :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)
969 Please see the documentation for :func:`setDynBlocksAction` to confirm which actions are supported by the action paramater.
971 .. function:: clearDynBlocks()
973 Remove all current dynamic blocks.
975 .. function:: showDynBlocks()
977 List all dynamic blocks in effect.
979 .. function:: setDynBlocksAction(action)
981 .. versionchanged:: 1.3.3
982 ``DNSAction.NXDomain`` action added.
984 Set which action is performed when a query is blocked.
985 Only DNSAction.Drop (the default), DNSAction.NoOp, DNSAction.NXDomain, DNSAction.Refused, DNSAction.Truncate and DNSAction.NoRecurse are supported.
989 Getting addresses that exceeded parameters
990 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
992 .. function:: exceedServFails(rate, seconds)
994 Get set of addresses that exceed ``rate`` servfails/s over ``seconds`` seconds
996 :param int rate: Number of Servfails per second to exceed
997 :param int seconds: Number of seconds the rate has been exceeded
999 .. function:: exceedNXDOMAINs(rate, seconds)
1001 get set of addresses that exceed ``rate`` NXDOMAIN/s over ``seconds`` seconds
1003 :param int rate: Number of NXDOMAIN per second to exceed
1004 :param int seconds: Number of seconds the rate has been exceeded
1006 .. function:: exceedRespByterate(rate, seconds)
1008 get set of addresses that exceeded ``rate`` bytes/s answers over ``seconds`` seconds
1010 :param int rate: Number of bytes per second to exceed
1011 :param int seconds: Number of seconds the rate has been exceeded
1013 .. function:: exceedQRate(rate, seconds)
1015 Get set of address that exceed ``rate`` queries/s over ``seconds`` seconds
1017 :param int rate: Number of queries per second to exceed
1018 :param int seconds: Number of seconds the rate has been exceeded
1020 .. function:: exceedQTypeRate(type, rate, seconds)
1022 Get set of address that exceed ``rate`` queries/s for queries of QType ``type`` over ``seconds`` seconds
1024 :param int type: QType
1025 :param int rate: Number of QType queries per second to exceed
1026 :param int seconds: Number of seconds the rate has been exceeded
1031 Instead of using several `exceed*()` lines, dnsdist 1.3.0 introduced a new `DynBlockRulesGroup` object
1032 which can be used to group dynamic block rules.
1034 See :doc:`../guides/dynblocks` for more information about the case where using a `DynBlockRulesGroup` might be
1035 faster than the existing rules.
1037 .. function:: dynBlockRulesGroup() -> DynBlockRulesGroup
1039 .. versionadded:: 1.3.0
1041 Creates a new :class:`DynBlockRulesGroup` object.
1043 .. class:: DynBlockRulesGroup
1045 Represents a group of dynamic block rules.
1047 .. method:: DynBlockRulesGroup:setQueryRate(rate, seconds, reason, blockingTime [, action [, warningRate]])
1049 .. versionchanged:: 1.3.3
1050 ``warningRate`` parameter added.
1052 Adds a query rate-limiting rule, equivalent to:
1054 addDynBlocks(exceedQRate(rate, seconds), reason, blockingTime, action)
1057 :param int rate: Number of queries per second to exceed
1058 :param int seconds: Number of seconds the rate has been exceeded
1059 :param string reason: The message to show next to the blocks
1060 :param int blockingTime: The number of seconds this block to expire
1061 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
1062 :param int warningRate: If set to a non-zero value, the rate above which a warning message will be issued and a no-op block inserted
1064 .. method:: DynBlockRulesGroup:setRCodeRate(rcode, rate, seconds, reason, blockingTime [, action [, warningRate]])
1066 .. versionchanged:: 1.3.3
1067 ``warningRate`` parameter added.
1069 Adds a rate-limiting rule for responses of code ``rcode``, equivalent to:
1071 addDynBlocks(exceedServfails(rcode, rate, seconds), reason, blockingTime, action)
1074 :param int rcode: The response code
1075 :param int rate: Number of responses per second to exceed
1076 :param int seconds: Number of seconds the rate has been exceeded
1077 :param string reason: The message to show next to the blocks
1078 :param int blockingTime: The number of seconds this block to expire
1079 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
1080 :param int warningRate: If set to a non-zero value, the rate above which a warning message will be issued and a no-op block inserted
1082 .. method:: DynBlockRulesGroup:setRCodeRatio(rcode, ratio, seconds, reason, blockingTime, minimumNumberOfResponses [, action [, warningRate]])
1084 .. versionadded:: 1.5.0
1086 Adds a rate-limiting rule for the ratio of responses of code ``rcode`` over the total number of responses for a given client.
1088 :param int rcode: The response code
1089 :param int ratio: Ratio of responses per second of the given rcode over the total number of responses for this client to exceed
1090 :param int seconds: Number of seconds the ratio has been exceeded
1091 :param string reason: The message to show next to the blocks
1092 :param int blockingTime: The number of seconds this block to expire
1093 :param int minimumNumberOfResponses: How many total responses is required for this rule to apply
1094 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
1095 :param int warningRatio: If set to a non-zero value, the ratio above which a warning message will be issued and a no-op block inserted
1097 .. method:: DynBlockRulesGroup:setQTypeRate(qtype, rate, seconds, reason, blockingTime [, action [, warningRate]])
1099 .. versionchanged:: 1.3.3
1100 ``warningRate`` parameter added.
1102 Adds a rate-limiting rule for queries of type ``qtype``, equivalent to:
1104 addDynBlocks(exceedQTypeRate(type, rate, seconds), reason, blockingTime, action)
1107 :param int qtype: The qtype
1108 :param int rate: Number of queries per second to exceed
1109 :param int seconds: Number of seconds the rate has been exceeded
1110 :param string reason: The message to show next to the blocks
1111 :param int blockingTime: The number of seconds this block to expire
1112 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
1113 :param int warningRate: If set to a non-zero value, the rate above which a warning message will be issued and a no-op block inserted
1115 .. method:: DynBlockRulesGroup:setResponseByteRate(rate, seconds, reason, blockingTime [, action [, warningRate]])
1117 .. versionchanged:: 1.3.3
1118 ``warningRate`` parameter added.
1120 Adds a bandwidth rate-limiting rule for responses, equivalent to:
1122 addDynBlocks(exceedRespByterate(rate, seconds), reason, blockingTime, action)
1125 :param int rate: Number of bytes per second to exceed
1126 :param int seconds: Number of seconds the rate has been exceeded
1127 :param string reason: The message to show next to the blocks
1128 :param int blockingTime: The number of seconds this block to expire
1129 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
1130 :param int warningRate: If set to a non-zero value, the rate above which a warning message will be issued and a no-op block inserted
1132 .. method:: DynBlockRulesGroup:setSuffixMatchRule(seconds, reason, blockingTime, action , visitor)
1134 .. versionadded:: 1.4.0
1136 Set a Lua visitor function that will be called for each label of every domain seen in queries and responses. The function receives a `StatNode` object representing the stats of the parent, a second one with the stats of the current label and one with the stats of the current node plus all its children.
1137 Note that this function will not be called if a FFI version has been set using :meth:`DynBlockRulesGroup:setSuffixMatchRuleFFI`
1138 If the function returns true, the current label will be blocked according to the `seconds`, `reason`, `blockingTime` and `action` parameters.
1139 Selected domains can be excluded from this processing using the :meth:`DynBlockRulesGroup:excludeDomains` method.
1141 This replaces the existing :func:`addDynBlockSMT` function.
1143 :param int seconds: Number of seconds the rate has been exceeded
1144 :param string reason: The message to show next to the blocks
1145 :param int blockingTime: The number of seconds this block to expire
1146 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
1147 :param function vistitor: The Lua function to call.
1149 .. method:: DynBlockRulesGroup:setSuffixMatchRuleFFI(seconds, reason, blockingTime, action , visitor)
1151 .. versionadded:: 1.4.0
1153 Set a Lua FFI visitor function that will be called for each label of every domain seen in queries and responses. The function receives a `dnsdist_ffi_stat_node_t` object containing the stats of the parent, a second one with the stats of the current label and one with the stats of the current node plus all its children.
1154 If the function returns true, the current label will be blocked according to the `seconds`, `reason`, `blockingTime` and `action` parameters.
1155 Selected domains can be excluded from this processing using the :meth:`DynBlockRulesGroup:excludeDomains` method.
1157 :param int seconds: Number of seconds the rate has been exceeded
1158 :param string reason: The message to show next to the blocks
1159 :param int blockingTime: The number of seconds this block to expire
1160 :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
1161 :param function vistitor: The Lua FFI function to call.
1163 .. method:: DynBlockRulesGroup:apply()
1165 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.
1167 .. method:: DynBlockRulesGroup:setQuiet(quiet)
1169 .. versionadded:: 1.4.0
1171 Set whether newly blocked clients or domains should be logged.
1173 :param bool quiet: True means that insertions will not be logged, false that they will. Default is false.
1175 .. method:: DynBlockRulesGroup:excludeDomains(domains)
1177 .. versionadded:: 1.4.0
1179 Exclude this domain, or list of domains, meaning that no dynamic block will ever be inserted for this domain via :meth:`DynBlockRulesGroup:setSuffixMatchRule` or :meth:`DynBlockRulesGroup:setSuffixMatchRuleFFI`. Default to empty, meaning rules are applied to all domains.
1181 :param str domain: A domain, or list of domains, as strings, like for example "powerdns.com"
1183 .. method:: DynBlockRulesGroup:excludeRange(netmasks)
1185 .. versionadded:: 1.3.1
1187 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.
1189 :param list netmasks: A netmask, or list of netmasks, as strings, like for example "192.0.2.1/24"
1191 .. method:: DynBlockRulesGroup:includeRange(netmasks)
1193 .. versionadded:: 1.3.1
1195 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.
1197 :param list netmasks: A netmask, or list of netmasks, as strings, like for example "192.0.2.1/24"
1199 .. method:: DynBlockRulesGroup:toString()
1201 .. versionadded:: 1.3.1
1203 Return a string describing the rules and range exclusions of this DynBlockRulesGroup.
1210 Represent metrics about a given node, for the visitor functions used with :meth:`DynBlockRulesGroup:setSuffixMatchRul` and :meth:`DynBlockRulesGroup:setSuffixMatchRuleFFI`. Note that some nodes includes the metrics for their children as well as their own.
1212 .. attribute:: StatNode.bytes
1214 The number of bytes for all responses returned for that node.
1216 .. attribute:: StatNode.drops
1218 The number of drops for that node.
1220 .. attribute:: StatNode.fullname
1222 The complete name of that node, ie 'www.powerdns.com'.
1224 .. attribute:: StatNode.labelsCount
1226 The number of labels in that node, for example 3 for 'www.powerdns.com'.
1228 .. attribute:: StatNode.noerrors
1230 The number of No Error answers returned for that node.
1232 .. attribute:: StatNode.nxdomains
1234 The number of NXDomain answers returned for that node.
1236 .. attribute:: StatNode.queries
1238 The number of queries for that node.
1240 .. attribute:: StatNode.servfails
1242 The number of Server Failure answers returned for that node.
1244 .. method:: StatNode:numChildren
1246 The number of children of that node.
1251 A SuffixMatchNode can be used to quickly check whether a given name belongs to a set or not. This is achieved
1252 using an efficient tree structure based on DNS labels, making lookups cheap.
1253 Be careful that Suffix Node matching will match for any sub-domain, regardless of the depth, under the name added to the set. For example,
1254 if 'example.com.' is added to the set, 'www.example.com.' and 'sub.www.example.com.' will match as well.
1255 If you are looking for exact name matching, your might want to consider using a :class:`DNSNameSet` instead.
1257 .. function:: newSuffixMatchNode()
1259 Creates a new :class:`SuffixMatchNode`.
1261 .. class:: SuffixMatchNode
1263 Represent a set of DNS suffixes for quick matching.
1265 .. method:: SuffixMatchNode:add(name)
1267 .. versionchanged:: 1.4.0
1268 This method now accepts strings, lists of DNSNames and lists of strings.
1270 Add a suffix to the current set.
1272 :param DNSName name: The suffix to add to the set.
1273 :param string name: The suffix to add to the set.
1274 :param table name: The suffixes to add to the set. Elements of the table should be of the same type, either DNSName or string.
1276 .. method:: SuffixMatchNode:check(name) -> bool
1278 Return true if the given name is a sub-domain of one of those in the set, and false otherwise.
1280 :param DNSName name: The name to test against the set.
1285 .. function:: maintenance()
1287 If this function exists, it is called every second to so regular tasks.
1288 This can be used for e.g. :doc:`Dynamic Blocks <../guides/dynblocks>`.
1290 .. function:: setAllowEmptyResponse()
1292 .. versionadded:: 1.4.0
1294 Set to true (defaults to false) to allow empty responses (qdcount=0) with a NoError or NXDomain rcode (default) from backends. dnsdist drops these responses by default because it can't match them against the initial query since they don't contain the qname, qtype and qclass, and therefore the risk of collision is much higher than with regular responses.
1296 .. function:: makeIPCipherKey(password) -> string
1298 .. versionadded:: 1.4.0
1300 Hashes the password to generate a 16-byte key that can be used to pseudonymize IP addresses with IP cipher.
1302 .. function:: generateOCSPResponse(pathToServerCertificate, pathToCACertificate, pathToCAPrivateKey, outputFile, numberOfDaysOfValidity, numberOfMinutesOfValidity)
1304 .. versionadded:: 1.4.0
1306 When a local PKI is used to issue the certificate, or for testing purposes, :func:`generateOCSPResponse` can be used to generate an OCSP response file for a certificate, using the certificate and private key of the certification authority that signed that certificate.
1307 The resulting file can be directly used with the :func:`addDOHLocal` or the :func:`addTLSLocal` functions.
1309 :param string pathToServerCertificate: Path to a file containing the certificate used by the server.
1310 :param string pathToCACertificate: Path to a file containing the certificate of the certification authority that was used to sign the server certificate.
1311 :param string pathToCAPrivateKey: Path to a file containing the private key corresponding to the certification authority certificate.
1312 :param string outputFile: Path to a file where the resulting OCSP response will be written to.
1313 :param int numberOfDaysOfValidity: Number of days this OCSP response should be valid.
1314 :param int numberOfMinutesOfValidity: Number of minutes this OCSP response should be valid, in addition to the number of days.
1319 .. class:: DOHFrontend
1321 .. versionadded:: 1.4.0
1323 This object represents an address and port dnsdist is listening on for DNS over HTTPS queries.
1325 .. method:: DOHFrontend:loadTicketsKeys(ticketsKeysFile)
1327 Load new tickets keys from the selected file, replacing the existing ones. These keys should be rotated often and never written to persistent storage to preserve forward secrecy. The default is to generate a random key. dnsdist supports several tickets keys to be able to decrypt existing sessions after the rotation.
1329 :param str ticketsKeysFile: The path to a file from where TLS tickets keys should be loaded.
1331 .. method:: DOHFrontend:reloadCertificates()
1333 Reload the current TLS certificate and key pairs.
1335 .. method:: DOHFrontend:rotateTicketsKey()
1337 Replace the current TLS tickets key by a new random one.
1339 .. method:: DOHFrontend:setResponsesMap(rules)
1341 Set a list of HTTP response rules allowing to intercept HTTP queries very early, before the DNS payload has been processed, and send custom responses including error pages, redirects and static content.
1343 :param list of DOHResponseMapEntry objects rules: A list of DOHResponseMapEntry objects, obtained with :func:`newDOHResponseMapEntry`.
1346 .. function:: newDOHResponseMapEntry(regex, status, content [, headers]) -> DOHResponseMapEntry
1348 .. versionadded:: 1.4.0
1350 Return a DOHResponseMapEntry that can be used with :meth:`DOHFrontend.setResponsesMap`. Every query whose path matches the regular expression supplied in ``regex`` will be immediately answered with a HTTP response.
1351 The status of the HTTP response will be the one supplied by ``status``, and the content set to the one supplied by ``content``, except if the status is a redirection (3xx) in which case the content is expected to be the URL to redirect to.
1353 :param str regex: A regular expression to match the path against.
1354 :param int status: The HTTP code to answer with.
1355 :param str content: The content of the HTTP response, or a URL if the status is a redirection (3xx).
1356 :param table of headers: The custom headers to set for the HTTP response, if any. The default is to use the value of the ``customResponseHeaders`` parameter passed to :func:`addDOHLocal`.
1361 .. class:: TLSContext
1363 .. versionadded:: 1.3.0
1365 This object represents an address and port dnsdist is listening on for DNS over TLS queries.
1367 .. method:: TLSContext:rotateTicketsKey()
1369 Replace the current TLS tickets key by a new random one.
1371 .. method:: TLSContext:loadTicketsKeys(ticketsKeysFile)
1373 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.
1375 :param str ticketsKeysFile: The path to a file from where TLS tickets keys should be loaded.
1380 .. class:: TLSFrontend
1382 .. versionadded:: 1.3.1
1384 This object represents the configuration of a listening frontend for DNS over TLS queries. To each frontend is associated a TLSContext.
1386 .. method:: TLSContext:loadNewCertificatesAndKeys(certFile(s), keyFile(s))
1388 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.
1390 :param str certFile(s): The path to a X.509 certificate file in PEM format, or a list of paths to such files.
1391 :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.
1393 EDNS on Self-generated answers
1394 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1396 There are several mechanisms in dnsdist that turn an existing query into an answer right away,
1397 without reaching out to the backend, including :func:`SpoofAction`, :func:`RCodeAction`, :func:`TCAction`
1398 and returning a response from ``Lua``. Those responses should, according to :rfc:`6891`, contain an ``OPT``
1399 record if the received request had one, which is the case by default and can be disabled using
1400 :func:`setAddEDNSToSelfGeneratedResponses`.
1402 We must, however, provide a responder's maximum payload size in this record, and we can't easily know the
1403 maximum payload size of the actual backend so we need to provide one. The default value is 1500 and can be
1404 overriden using :func:`setPayloadSizeOnSelfGeneratedAnswers`.
1406 .. function:: setAddEDNSToSelfGeneratedResponses(add)
1408 .. versionadded:: 1.3.3
1410 Whether to add EDNS to self-generated responses, provided that the initial query had EDNS.
1412 :param bool add: Whether to add EDNS, default is true.
1414 .. function:: setPayloadSizeOnSelfGeneratedAnswers(payloadSize)
1416 .. versionadded:: 1.3.3
1418 Set the UDP payload size advertised via EDNS on self-generated responses. In accordance with
1419 :rfc:`RFC 6891 <6891#section-6.2.5>`, values lower than 512 will be treated as equal to 512.
1421 :param int payloadSize: The responder's maximum UDP payload size, in bytes. Default is 1500.
1426 PowerDNS products can poll the security status of their respective versions. This polling, naturally,
1427 happens over DNS. If the result is that a given version has a security problem, the software will
1428 report this at level ‘Error’ during startup, and repeatedly during operations, every
1429 :func:`setSecurityPollInterval` seconds.
1431 By default, security polling happens on the domain ‘secpoll.powerdns.com’, but this can be changed with
1432 the :func:`setSecurityPollSuffix` function. If this setting is made empty, no polling will take place.
1433 Organizations wanting to host their own security zones can do so by changing this setting to a domain name
1434 under their control.
1436 To enable distributors of PowerDNS to signal that they have backported versions, the PACKAGEVERSION
1437 compilation-time macro can be used to set a distributor suffix.
1439 .. function:: setSecurityPollInterval(interval)
1441 .. versionadded:: 1.3.3
1443 Set the interval, in seconds, between two security pollings.
1445 :param int interval: The interval, in seconds, between two pollings. Default is 3600.
1447 .. function:: setSecurityPollSuffix(suffix)
1449 .. versionadded:: 1.3.3
1451 Domain name from which to query security update notifications. Setting this to an empty string disables secpoll.
1453 :param string suffix: The suffix to use, default is 'secpoll.powerdns.com.'.