pdns/dnsdistdist/docs/reference/config.rst

   1 .. highlight:: lua
   2
   3 Configuration Reference
   4 =======================
   5
   6 This page lists all configuration options for dnsdist.
   7
   8 .. note::
   9
  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".
  12
  13 Functions and Types
  14 -------------------
  15
  16 Within dnsdist several core object types exist:
  17
  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
  26
  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:
  28
  29 .. code-block:: lua
  30
  31   getServer(0).order=12         -- set order of server 0 to 12
  32   getServer(0):addPool("abuse") -- add this server to the abuse pool
  33
  34 The ``.`` means ``order`` is a data member, while the ``:`` means ``addPool`` is a member function.
  35
  36 Global configuration
  37 --------------------
  38
  39 .. function:: includeDirectory(path)
  40
  41   Include configuration files from ``path``.
  42
  43   :param str path: The directory to load configuration files from. Each file must end in ``.conf``.
  44
  45 .. function:: reloadAllCertificates()
  46
  47   .. versionadded:: 1.4.0
  48
  49   Reload all DNSCrypt and TLS certificates, along with their associated keys.
  50
  51 .. function:: setSyslogFacility(facility)
  52
  53   .. versionadded:: 1.4.0
  54
  55   Set the syslog logging facility to ``facility``.
  56
  57   :param int facility: The new facility as a numeric value. Defaults to LOG_DAEMON.
  58
  59 Listen Sockets
  60 ~~~~~~~~~~~~~~
  61
  62 .. function:: addLocal(address[, options])
  63
  64   .. versionadded:: 1.2.0
  65
  66   .. versionchanged:: 1.3.0
  67     Added ``cpus`` to the options.
  68
  69   .. versionchanged:: 1.4.0
  70     Removed ``doTCP`` from the options. A listen socket on TCP is always created.
  71
  72   Add to the list of listen addresses.
  73
  74   :param str address: The IP Address with an optional port to listen on.
  75                       The default port is 53.
  76   :param table options: A table with key: value pairs with listen options.
  77
  78   Options:
  79
  80   * ``doTCP=true``: bool - Also bind on TCP on ``address``. Removed in 1.4.0.
  81   * ``reusePort=false``: bool - Set the ``SO_REUSEPORT`` socket option.
  82   * ``tcpFastOpenQueueSize=0``: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.
  83   * ``interface=""``: str - Set the network interface to use.
  84   * ``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.
  85
  86   .. code-block:: lua
  87
  88     addLocal('0.0.0.0:5300', { reusePort=true })
  89
  90   This will bind to both UDP and TCP on port 5300 with SO_REUSEPORT enabled.
  91
  92 .. function:: addLocal(address[[[,do_tcp], so_reuseport], tcp_fast_open_qsize])
  93
  94   .. deprecated:: 1.2.0
  95
  96   Add to the list of addresses listened on.
  97
  98   :param str address: The IP Address with an optional port to listen on.
  99                       The default port is 53.
 100   :param bool do_tcp: Also bind a TCP port on ``address``, defaults to true.
 101   :param bool so_reuseport: Use ``SO_REUSEPORT`` if it is available, defaults to false
 102   :param int tcp_fast_open_qsize: The size of the TCP Fast Open queue. Set to a number
 103                                   higher than 0 to enable TCP Fast Open when available.
 104                                   Default is 0.
 105
 106 .. function:: addDOHLocal(address, [certFile(s) [, keyFile(s) [, urls [, options]]]])
 107
 108   .. versionadded:: 1.4.0
 109
 110   Listen on the specified address and TCP port for incoming DNS over HTTPS connections, presenting the specified X.509 certificate.
 111   If no certificate (or key) files are specified, listen for incoming DNS over HTTP connections instead.
 112
 113   :param str address: The IP Address with an optional port to listen on.
 114                       The default port is 443.
 115   :param str certFile(s): The path to a X.509 certificate file in PEM format, or a list of paths to such files.
 116   :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.
 117   :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 /.
 118   :param table options: A table with key: value pairs with listen options.
 119
 120   Options:
 121
 122   * ``reusePort=false``: bool - Set the ``SO_REUSEPORT`` socket option.
 123   * ``tcpFastOpenQueueSize=0``: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.
 124   * ``interface=""``: str - Set the network interface to use.
 125   * ``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.
 126   * ``idleTimeout=30``: int - Set the idle timeout, in seconds.
 127   * ``ciphers``: str - The TLS ciphers to use, in OpenSSL format. Ciphers for TLS 1.3 must be specified via ``ciphersTLS13``.
 128   * ``ciphersTLS13``: str - The TLS ciphers to use for TLS 1.3, in OpenSSL format.
 129   * ``serverTokens``: str - The content of the Server: HTTP header returned by dnsdist. The default is "h2o/dnsdist".
 130   * ``customResponseHeaders={}``: table - Set custom HTTP header(s) returned by dnsdist.
 131   * ``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.
 132   * ``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.
 133   * ``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.
 134   * ``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.
 135   * ``ticketsKeysRotationDelay``: int - Set the delay before the TLS tickets key is rotated, in seconds. Default is 43200 (12h).
 136   * ``sessionTickets``: bool - Whether session resumption via session tickets is enabled. Default is true, meaning tickets are enabled.
 137   * ``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.
 138
 139 .. function:: addTLSLocal(address, certFile(s), keyFile(s) [, options])
 140
 141   .. versionadded:: 1.3.0
 142   .. versionchanged:: 1.3.1
 143     ``certFile(s)`` and ``keyFile(s)`` parameters accept a list of files.
 144     ``sessionTickets`` option added.
 145   .. versionchanged:: 1.3.3
 146     ``numberOfStoredSessions`` option added.
 147   .. versionchanged:: 1.4.0
 148     ``ciphersTLS13``, ``minTLSVersion`` and ``ocspResponses`` options added.
 149
 150   Listen on the specified address and TCP port for incoming DNS over TLS connections, presenting the specified X.509 certificate.
 151
 152   :param str address: The IP Address with an optional port to listen on.
 153                       The default port is 853.
 154   :param str certFile(s): The path to a X.509 certificate file in PEM format, or a list of paths to such files.
 155   :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.
 156   :param table options: A table with key: value pairs with listen options.
 157
 158   Options:
 159
 160   * ``reusePort=false``: bool - Set the ``SO_REUSEPORT`` socket option.
 161   * ``tcpFastOpenQueueSize=0``: int - Set the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0.
 162   * ``interface=""``: str - Set the network interface to use.
 163   * ``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.
 164   * ``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.
 165   * ``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``.
 166   * ``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.
 167   * ``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.
 168   * ``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.
 169   * ``ticketsKeysRotationDelay``: int - Set the delay before the TLS tickets key is rotated, in seconds. Default is 43200 (12h).
 170   * ``sessionTickets``: bool - Whether session resumption via session tickets is enabled. Default is true, meaning tickets are enabled.
 171   * ``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.
 172   * ``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.
 173   * ``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.
 174
 175 .. function:: setLocal(address[, options])
 176
 177   .. versionadded:: 1.2.0
 178
 179   Remove the list of listen addresses and add a new one.
 180
 181   :param str address: The IP Address with an optional port to listen on.
 182                       The default port is 53.
 183   :param table options: A table with key: value pairs with listen options.
 184
 185   The options that can be set are the same as :func:`addLocal`.
 186
 187 .. function:: setLocal(address[[[,do_tcp], so_reuseport], tcp_fast_open_qsize])
 188
 189   .. deprecated:: 1.2.0
 190
 191   Remove the list of listen addresses and add a new one.
 192
 193   :param str address: The IP Address with an optional port to listen on.
 194                       The default port is 53.
 195   :param bool do_tcp: Also bind a TCP port on ``address``, defaults to true.
 196   :param bool so_reuseport: Use ``SO_REUSEPORT`` if it is available, defaults to false
 197   :param int tcp_fast_open_qsize: The size of the TCP Fast Open queue. Set to a number
 198                                   higher than 0 to enable TCP Fast Open when available.
 199                                   Default is 0.
 200
 201 Control Socket, Console and Webserver
 202 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 203
 204 .. function:: addConsoleACL(netmask)
 205
 206   .. versionadded:: 1.3.0
 207
 208   Add a netmask to the existing console ACL, allowing remote clients to connect to the console. Please make sure that encryption
 209   has been enabled with :func:`setKey` before doing so. The default is to only allow 127.0.0.1/8 and ::1/128.
 210
 211   :param str netmask: A CIDR netmask, e.g. ``"192.0.2.0/24"``. Without a subnetmask, only the specific address is allowed.
 212
 213 .. function:: controlSocket(address)
 214
 215   Bind to ``addr`` and listen for a connection for the console. Since 1.3.0 only connections from local users are allowed
 216   by default, :func:`addConsoleACL` and :func:`setConsoleACL` can be used to enable remote connections. Please make sure
 217   that encryption has been enabled with :func:`setKey` before doing so. Enabling encryption is also strongly advised for
 218   local connections, since not enabling it allows any local user to connect to the console.
 219
 220   :param str address: An IP address with optional port. By default, the port is 5199.
 221
 222 .. function:: inClientStartup()
 223
 224   Returns true while the console client is parsing the configuration.
 225
 226 .. function:: makeKey()
 227
 228   Generate and print an encryption key.
 229
 230 .. function:: setConsoleConnectionsLogging(enabled)
 231
 232   .. versionadded:: 1.2.0
 233
 234   Whether to log the opening and closing of console connections.
 235
 236   :param bool enabled: Default to true.
 237
 238 .. function:: setKey(key)
 239
 240   Use ``key`` as shared secret between the client and the server
 241
 242   :param str key: An encoded key, as generated by :func:`makeKey`
 243
 244 .. function:: setConsoleACL(netmasks)
 245
 246   .. versionadded:: 1.3.0
 247
 248   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
 249   has been enabled with :func:`setKey` before doing so.
 250
 251   :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.
 252
 253 .. function:: showConsoleACL()
 254
 255   Print a list of all netmasks allowed to connect to the console.
 256
 257 .. function:: testCrypto()
 258
 259   Test the crypto code, will report errors when something is not ok.
 260
 261 .. function:: setConsoleOutputMaxMsgSize(size)
 262
 263   .. versionadded:: 1.3.3
 264
 265   Set the maximum size in bytes of a single console message, default set to 10 MB.
 266
 267   :param int size: The new maximum size.
 268
 269 Webserver configuration
 270 ~~~~~~~~~~~~~~~~~~~~~~~
 271
 272 .. function:: webserver(listen_address, password[, apikey[, custom_headers]])
 273
 274   Launch the :doc:`../guides/webserver` with statistics and the API.
 275
 276   :param str listen_address: The IP address and Port to listen on
 277   :param str password: The password required to access the webserver
 278   :param str apikey: The key required to access the API
 279   :param {[str]=str,...} custom_headers: Allows setting custom headers and removing the defaults
 280
 281 .. function:: setAPIWritable(allow [,dir])
 282
 283   Allow modifications via the API.
 284   Optionally saving these changes to disk.
 285   Modifications done via the API will not be written to the configuration by default and will not persist after a reload
 286
 287   :param bool allow: Set to true to allow modification through the API
 288   :param str dir: A valid directory where the configuration files will be written by the API.
 289
 290 .. function:: setWebserverConfig(options)
 291
 292   .. versionadded:: 1.3.3
 293
 294   Setup webserver configuration. See :func:`webserver`.
 295
 296   :param table options: A table with key: value pairs with webserver options.
 297
 298   Options:
 299
 300   * ``password=newPassword``: string - Changes the API password
 301   * ``apikey=newKey``: string - Changes the API Key (set to an empty string do disable it)
 302   * ``custom_headers={[str]=str,...}``: map of string - Allows setting custom headers and removing the defaults.
 303
 304 Access Control Lists
 305 ~~~~~~~~~~~~~~~~~~~~
 306
 307 .. function:: addACL(netmask)
 308
 309   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.
 310
 311   :param str netmask: A CIDR netmask, e.g. ``"192.0.2.0/24"``. Without a subnetmask, only the specific address is allowed.
 312
 313 .. function:: setACL(netmasks)
 314
 315   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.
 316
 317   :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.
 318
 319 .. function:: showACL()
 320
 321   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.
 322
 323 EDNS Client Subnet
 324 ~~~~~~~~~~~~~~~~~~
 325
 326 .. function:: setECSOverride(bool)
 327
 328   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
 329
 330   :param bool: Whether to override an existing EDNS Client Subnet option present in the query. Defaults to false
 331
 332 .. function:: setECSSourcePrefixV4(prefix)
 333
 334   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
 335
 336   :param int prefix: The prefix length
 337
 338 .. function:: setECSSourcePrefixV6(prefix)
 339
 340   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
 341
 342   :param int prefix: The prefix length
 343
 344 Ringbuffers
 345 ~~~~~~~~~~~
 346
 347 .. function:: setRingBuffersLockRetries(num)
 348
 349   .. versionadded:: 1.3.0
 350
 351   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
 352
 353   :param int num: The maximum number of attempts. Defaults to 5 if there is more than one shard, 0 otherwise.
 354
 355 .. function:: setRingBuffersSize(num [, numberOfShards])
 356
 357   .. versionchanged:: 1.3.0
 358     ``numberOfShards`` optional parameter added.
 359
 360   Set the capacity of the ringbuffers used for live traffic inspection to ``num``, and the number of shards to ``numberOfShards`` if specified.
 361
 362   :param int num: The maximum amount of queries to keep in the ringbuffer. Defaults to 10000
 363   :param int numberOfShards: the number of shards to use to limit lock contention. Defaults to 1
 364
 365 Servers
 366 -------
 367
 368 .. function:: newServer(server_string)
 369               newServer(server_table)
 370
 371   .. versionchanged:: 1.3.0
 372     Added ``checkClass``, ``sockets`` and ``checkFunction`` to server_table.
 373
 374   .. versionchanged:: 1.4.0
 375     Added ``checkInterval``, ``checkTimeout`` and ``rise`` to server_table.
 376
 377   Add a new backend server. Call this function with either a string::
 378
 379     newServer(
 380       "IP:PORT" -- IP and PORT of the backend server
 381     )
 382
 383   or a table::
 384
 385     newServer({
 386       address="IP:PORT",     -- IP and PORT of the backend server (mandatory)
 387       id=STRING,             -- Use a pre-defined UUID instead of a random one
 388       qps=NUM,               -- Limit the number of queries per second to NUM, when using the `firstAvailable` policy
 389       order=NUM,             -- The order of this server, used by the `leastOutstanding` and `firstAvailable` policies
 390       weight=NUM,            -- The weight of this server, used by the `wrandom`, `whashed` and `chashed` policies, default: 1
 391                              -- Supported values are a minimum of 1, and a maximum of 2147483647.
 392       pool=STRING|{STRING},  -- The pools this server belongs to (unset or empty string means default pool) as a string or table of strings
 393       retries=NUM,           -- The number of TCP connection attempts to the backend, for a given query
 394       tcpConnectTimeout=NUM, -- The timeout (in seconds) of a TCP connection attempt
 395       tcpSendTimeout=NUM,    -- The timeout (in seconds) of a TCP write attempt
 396       tcpRecvTimeout=NUM,    -- The timeout (in seconds) of a TCP read attempt
 397       tcpFastOpen=BOOL,      -- Whether to enable TCP Fast Open
 398       ipBindAddrNoPort=BOOL, -- Whether to enable IP_BIND_ADDRESS_NO_PORT if available, default: true
 399       name=STRING,           -- The name associated to this backend, for display purpose
 400       checkClass=NUM,        -- Use NUM as QCLASS in the health-check query, default: DNSClass.IN
 401       checkName=STRING,      -- Use STRING as QNAME in the health-check query, default: "a.root-servers.net."
 402       checkType=STRING,      -- Use STRING as QTYPE in the health-check query, default: "A"
 403       checkFunction=FUNCTION,-- Use this function to dynamically set the QNAME, QTYPE and QCLASS to use in the health-check query (see :ref:`Healthcheck`)
 404       checkTimeout=NUM,      -- The timeout (in milliseconds) of a health-check query, default: 1000 (1s)
 405       setCD=BOOL,            -- Set the CD (Checking Disabled) flag in the health-check query, default: false
 406       maxCheckFailures=NUM,  -- Allow NUM check failures before declaring the backend down, default: 1
 407       checkInterval=NUM      -- The time in seconds between health checks
 408       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
 409       useClientSubnet=BOOL,  -- Add the client's IP address in the EDNS Client Subnet option when forwarding the query to this backend
 410       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
 411                              -- The following formats are supported:
 412                              --   "address", e.g. "192.0.2.2"
 413                              --   "interface name", e.g. "eth0"
 414                              --   "address@interface", e.g. "192.0.2.2@eth0"
 415       addXPF=NUM,            -- Add the client's IP address and port to the query, along with the original destination address and port,
 416                              -- 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)
 417       sockets=NUM,           -- Number of sockets (and thus source ports) used toward the backend server, defaults to a single one
 418       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
 419       rise=NUM               -- Require NUM consecutive successful checks before declaring the backend up, default: 1
 420     })
 421
 422   :param str server_string: A simple IP:PORT string.
 423   :param table server_table: A table with at least a 'name' key
 424
 425 .. function:: getServer(index) -> Server
 426
 427   Get a :class:`Server`
 428
 429   :param int index: The number of the server (as seen in :func:`showServers`).
 430   :returns:  The :class:`Server` object or nil
 431
 432 .. function:: getServers()
 433
 434   Returns a table with all defined servers.
 435
 436 .. function:: rmServer(index)
 437               rmServer(server)
 438
 439   Remove a backend server.
 440
 441   :param int index: The number of the server (as seen in :func:`showServers`).
 442   :param Server server: A :class:`Server` object as returned by e.g. :func:`getServer`.
 443
 444 Server Functions
 445 ~~~~~~~~~~~~~~~~
 446 A server object returned by :func:`getServer` can be manipulated with these functions.
 447
 448 .. class:: Server
 449
 450   This object represents a backend server. It has several methods.
 451
 452   .. method:: Server:addPool(pool)
 453
 454     Add this server to a pool.
 455
 456     :param str pool: The pool to add the server to
 457
 458   .. method:: Server:getName() -> string
 459
 460     Get the name of this server.
 461
 462     :returns: The name of the server, or an empty string if it does not have one
 463
 464   .. method:: Server:getNameWithAddr() -> string
 465
 466     Get the name plus IP address and port of the server
 467
 468     :returns: A string containing the server name if any plus the server address and port
 469
 470   .. method:: Server:getOutstanding() -> int
 471
 472     Get the number of outstanding queries for this server.
 473
 474     :returns: The number of outstanding queries
 475
 476   .. method:: Server:isUp() -> bool
 477
 478     Returns the up status of the server
 479
 480     :returns: true when the server is up, false otherwise
 481
 482   .. method:: Server:rmPool(pool)
 483
 484     Removes the server from the named pool
 485
 486     :param str pool: The pool to remove the server from
 487
 488   .. method:: Server:setAuto([status])
 489
 490     .. versionchanged:: 1.3.0
 491         ``status`` optional parameter added.
 492
 493     Set the server in the default auto state.
 494     This will enable health check queries that will set the server ``up`` and ``down`` appropriately.
 495
 496     :param bool status: Set the initial status of the server to ``up`` (true) or ``down`` (false) instead of using the last known status
 497
 498   .. method:: Server:setQPS(limit)
 499
 500     Limit the queries per second for this server.
 501
 502     :param int limit: The maximum number of queries per second
 503
 504   .. method:: Server:setDown()
 505
 506     Set the server in an ``DOWN`` state.
 507     The server will not receive queries and the health checks are disabled
 508
 509   .. method:: Server:setUp()
 510
 511     Set the server in an ``UP`` state.
 512     This server will still receive queries and health checks are disabled
 513
 514   Apart from the functions, a :class:`Server` object has these attributes:
 515
 516   .. attribute:: Server.name
 517
 518     The name of the server
 519
 520   .. attribute:: Server.upStatus
 521
 522     Whether or not this server is up or down
 523
 524   .. attribute:: Server.order
 525
 526     The order of the server
 527
 528   .. attribute:: Server.weight
 529
 530     The weight of the server
 531
 532 Pools
 533 -----
 534
 535 :class:`Server`\ s can be part of any number of pools.
 536 Pools are automatically created when a server is added to a pool (with :func:`newServer`), or can be manually created with :func:`addPool`.
 537
 538 .. function:: addPool(name) -> ServerPool
 539
 540   Returns a :class:`ServerPool`.
 541
 542   :param string name: The name of the pool to create
 543
 544 .. function:: getPool(name) -> ServerPool
 545
 546   Returns a :class:`ServerPool` or nil.
 547
 548   :param string name: The name of the pool
 549
 550 .. function:: getPoolServers(name) -> [ Server ]
 551
 552   Returns a list of :class:`Server`\ s or nil.
 553
 554   :param string name: The name of the pool
 555
 556 .. function:: showPools()
 557
 558    Display the name, associated cache, server policy and associated servers for every pool.
 559
 560 .. class:: ServerPool
 561
 562   This represents the pool where zero or more servers are part of.
 563
 564   .. method:: ServerPool:getCache() -> PacketCache
 565
 566     Returns the :class:`PacketCache` for this pool or nil.
 567
 568   .. method:: ServerPool:getECS()
 569
 570     .. versionadded:: 1.3.0
 571
 572     Whether dnsdist will add EDNS Client Subnet information to the query before looking up into the cache,
 573     when all servers from this pool are down. For more information see :meth:`ServerPool:setECS`.
 574
 575   .. method:: ServerPool:setCache(cache)
 576
 577     Adds ``cache`` as the pool's cache.
 578
 579     :param PacketCache cache: The new cache to add to the pool
 580
 581   .. method:: ServerPool:unsetCache()
 582
 583     Removes the cache from this pool.
 584
 585   .. method:: ServerPool:setECS()
 586
 587     .. versionadded:: 1.3.0
 588
 589     Set to true if dnsdist should add EDNS Client Subnet information to the query before looking up into the cache,
 590     when all servers from this pool are down. If at least one server is up, the preference of the
 591     selected server is used, this parameter is only useful if all the backends in this pool are down
 592     and have EDNS Client Subnet enabled, since the queries in the cache will have been inserted with
 593     ECS information. Default is false.
 594
 595 PacketCache
 596 ~~~~~~~~~~~
 597
 598 A Pool can have a packet cache to answer queries directly instead of going to the backend.
 599 See :doc:`../guides/cache` for a how to.
 600
 601 .. function:: newPacketCache(maxEntries[, maxTTL=86400[, minTTL=0[, temporaryFailureTTL=60[, staleTTL=60[, dontAge=false[, numberOfShards=1[, deferrableInsertLock=true[, maxNegativeTTL=3600[, parseECS=false]]]]]]]) -> PacketCache
 602
 603   .. versionchanged:: 1.3.0
 604     ``numberOfShards`` and ``deferrableInsertLock`` parameters added.
 605
 606   .. versionchanged:: 1.3.1
 607     ``maxNegativeTTL`` and ``parseECS`` parameters added.
 608
 609   .. deprecated:: 1.4.0
 610
 611   Creates a new :class:`PacketCache` with the settings specified.
 612
 613   :param int maxEntries: The maximum number of entries in this cache
 614   :param int maxTTL: Cap the TTL for records to his number
 615   :param int minTTL: Don't cache entries with a TTL lower than this
 616   :param int temporaryFailureTTL: On a SERVFAIL or REFUSED from the backend, cache for this amount of seconds
 617   :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
 618   :param bool dontAge: Don't reduce TTLs when serving from the cache. Use this when :program:`dnsdist` fronts a cluster of authoritative servers
 619   :param int numberOfShards: Number of shards to divide the cache into, to reduce lock contention
 620   :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
 621   :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
 622   :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
 623
 624 .. function:: newPacketCache(maxEntries, [options]) -> PacketCache
 625
 626   .. versionadded:: 1.4.0
 627
 628   Creates a new :class:`PacketCache` with the settings specified.
 629
 630   :param int maxEntries: The maximum number of entries in this cache
 631
 632   Options:
 633
 634   * ``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.
 635   * ``dontAge=false``: bool - Don't reduce TTLs when serving from the cache. Use this when :program:`dnsdist` fronts a cluster of authoritative servers.
 636   * ``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.
 637   * ``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.
 638   * ``maxTTL=86400``: int - Cap the TTL for records to his number.
 639   * ``minTTL=0``: int - Don't cache entries with a TTL lower than this.
 640   * ``numberOfShards=1``: int - Number of shards to divide the cache into, to reduce lock contention.
 641   * ``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.
 642   * ``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.
 643   * ``temporaryFailureTTL=60``: int - On a SERVFAIL or REFUSED from the backend, cache for this amount of seconds..
 644
 645 .. class:: PacketCache
 646
 647   Represents a cache that can be part of :class:`ServerPool`.
 648
 649   .. method:: PacketCache:dump(fname)
 650
 651     .. versionadded:: 1.3.1
 652
 653     Dump a summary of the cache entries to a file.
 654
 655     :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.
 656
 657   .. method:: PacketCache:expunge(n)
 658
 659     Remove entries from the cache, leaving at most ``n`` entries
 660
 661     :param int n: Number of entries to keep
 662
 663   .. method:: PacketCache:expungeByName(name [, qtype=DNSQType.ANY[, suffixMatch=false]])
 664
 665     .. versionchanged:: 1.2.0
 666       ``suffixMatch`` parameter added.
 667
 668     Remove entries matching ``name`` and type from the cache.
 669
 670     :param DNSName name: The name to expunge
 671     :param int qtype: The type to expunge, can be a pre-defined :ref:`DNSQType`
 672     :param bool suffixMatch: When set to true, remove al entries under ``name``
 673
 674   .. method:: PacketCache:getStats()
 675
 676     .. versionadded:: 1.4.0
 677
 678     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.
 679
 680   .. method:: PacketCache:isFull() -> bool
 681
 682     Return true if the cache has reached the maximum number of entries.
 683
 684   .. method:: PacketCache:printStats()
 685
 686     Print the cache stats (number of entries, hits, misses, deferred lookups, deferred inserts, lookup collisions, insert collisions and TTL too shorts).
 687
 688   .. method:: PacketCache:purgeExpired(n)
 689
 690     Remove expired entries from the cache until there is at most ``n`` entries remaining in the cache.
 691
 692     :param int n: Number of entries to keep
 693
 694   .. method:: PacketCache:toString() -> string
 695
 696     Return the number of entries in the Packet Cache, and the maximum number of entries
 697
 698 Client State
 699 ------------
 700
 701 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.
 702
 703 .. function:: getBind(index) -> ClientState
 704
 705   Return a :class:`ClientState` object.
 706
 707   :param int index: The object index
 708
 709 ClientState functions
 710 ~~~~~~~~~~~~~~~~~~~~~
 711
 712 .. class:: ClientState
 713
 714   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.
 715
 716   .. method:: ClientState:attachFilter(filter)
 717
 718      Attach a BPF filter to this frontend.
 719
 720      :param BPFFilter filter: The filter to attach to this frontend
 721
 722   .. method:: ClientState:detachFilter()
 723
 724      Remove the BPF filter associated to this frontend, if any.
 725
 726   .. method:: ClientState:toString() -> string
 727
 728     Return the address and port this frontend is listening on.
 729
 730     :returns: The address and port this frontend is listening on
 731
 732   .. attribute:: ClientState.muted
 733
 734     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.
 735
 736 Status, Statistics and More
 737 ---------------------------
 738
 739 .. function:: dumpStats()
 740
 741   Print all statistics dnsdist gathers
 742
 743 .. function:: getDOHFrontend(idx)
 744
 745   .. versionadded:: 1.4.0
 746
 747   Return the DOHFrontend object for the DNS over HTTPS bind of index ``idx``.
 748
 749 .. function:: getTLSContext(idx)
 750
 751   .. versionadded:: 1.3.0
 752
 753   Return the TLSContext object for the context of index ``idx``.
 754
 755 .. function:: getTLSFrontend(idx)
 756
 757   .. versionadded:: 1.3.1
 758
 759   Return the TLSFrontend object for the TLS bind of index ``idx``.
 760
 761 .. function:: grepq(selector[, num])
 762               grepq(selectors[, num])
 763
 764   Prints the last ``num`` queries matching ``selector`` or ``selectors``.
 765
 766   The selector can be:
 767
 768   * a netmask (e.g. '192.0.2.0/24')
 769   * a DNS name (e.g. 'dnsdist.org')
 770   * a response time (e.g. '100ms')
 771
 772   :param str selector: Select queries based on this property.
 773   :param {str} selectors: A lua table of selectors. Only queries matching all selectors are shown
 774   :param int num: Show a maximum of ``num`` recent queries, default is 10.
 775
 776 .. function:: setVerboseHealthChecks(verbose)
 777
 778   Set whether health check errors should be logged. This is turned off by default.
 779
 780   :param bool verbose: Set to true if you want to enable health check errors logging
 781
 782 .. function:: showBinds()
 783
 784   Print a list of all the current addresses and ports dnsdist is listening on, also called ``frontends``
 785
 786 .. function:: showDOHFrontends()
 787
 788   .. versionadded:: 1.4.0
 789
 790   Print the list of all availables DNS over HTTPS frontends.
 791
 792 .. function:: showDOHResponseCodes()
 793
 794   .. versionadded:: 1.4.0
 795
 796   Print the HTTP response codes statistics for all availables DNS over HTTPS frontends.
 797
 798 .. function:: showResponseLatency()
 799
 800   Show a plot of the response time latency distribution
 801
 802 .. function:: showServers([options])
 803
 804   .. versionchanged:: 1.4.0
 805     ``options`` optional parameter added
 806
 807   This function shows all backend servers currently configured and some statistics.
 808   These statics have the following fields:
 809
 810   * ``#`` - The number of the server, can be used as the argument for :func:`getServer`
 811   * ``UUID`` - The UUID of the backend. Can be set with the ``id`` option of :func:`newServer`
 812   * ``Address`` - The IP address and port of the server
 813   * ``State`` - The current state of the server
 814   * ``Qps`` - Current number of queries per second
 815   * ``Qlim`` - Configured maximum number of queries per second
 816   * ``Ord`` - The order number of the server
 817   * ``Wt`` - The weight of the server
 818   * ``Queries`` - Total amount of queries sent to this server
 819   * ``Drops`` - Number of queries that were dropped by this server
 820   * ``Drate`` - Number of queries dropped per second by this server
 821   * ``Lat`` - The latency of this server in milliseconds
 822   * ``Pools`` - The pools this server belongs to
 823
 824   :param table options: A table with key: value pairs with display options.
 825
 826   Options:
 827
 828   * ``showUUIDs=false``: bool - Whether to display the UUIDs, defaults to false.
 829
 830 .. function:: showTCPStats()
 831
 832   Show some statistics regarding TCP
 833
 834 .. function:: showTLSContexts()
 835
 836   .. versionadded:: 1.3.0
 837
 838   Print the list of all availables DNS over TLS contexts.
 839
 840 .. function:: showVersion()
 841
 842   Print the version of dnsdist
 843
 844 .. function:: topBandwidth([num])
 845
 846   Print the top ``num`` clients that consume the most bandwidth.
 847
 848   :param int num: Number to show, defaults to 10.
 849
 850 .. function:: topClients([num])
 851
 852   Print the top ``num`` clients sending the most queries over length of ringbuffer
 853
 854   :param int num: Number to show, defaults to 10.
 855
 856 .. function:: topQueries([num[, labels]])
 857
 858   Print the ``num`` most popular QNAMEs from queries.
 859   Optionally grouped by the rightmost ``labels`` DNS labels.
 860
 861   :param int num: Number to show, defaults to 10
 862   :param int label: Number of labels to cut down to
 863
 864 .. function:: topResponses([num[, rcode[, labels]]])
 865
 866   Print the ``num`` most seen responses with an RCODE of ``rcode``.
 867   Optionally grouped by the rightmost ``labels`` DNS labels.
 868
 869   :param int num: Number to show, defaults to 10
 870   :param int rcode: :ref:`Response code <DNSRCode>`, defaults to 0 (No Error)
 871   :param int label: Number of labels to cut down to
 872
 873 .. function:: topSlow([num[, limit[, labels]]])
 874
 875   Print the ``num`` slowest queries that are slower than ``limit`` milliseconds.
 876   Optionally grouped by the rightmost ``labels`` DNS labels.
 877
 878   :param int num: Number to show, defaults to 10
 879   :param int limit: Show queries slower than this amount of milliseconds, defaults to 2000
 880   :param int label: Number of labels to cut down to
 881
 882 .. _dynblocksref:
 883
 884 Dynamic Blocks
 885 --------------
 886
 887 .. function:: addDynBlocks(addresses, message[, seconds=10[, action]])
 888
 889   .. versionchanged:: 1.2.0
 890     ``action`` parameter added.
 891
 892   Block a set of addresses with ``message`` for (optionally) a number of seconds.
 893   The default number of seconds to block for is 10.
 894
 895   :param addresses: set of Addresses as returned by an exceed function
 896   :param string message: The message to show next to the blocks
 897   :param int seconds: The number of seconds this block to expire
 898   :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)
 899
 900   Please see the documentation for :func:`setDynBlocksAction` to confirm which actions are supported by the action paramater.
 901
 902 .. function:: clearDynBlocks()
 903
 904   Remove all current dynamic blocks.
 905
 906 .. function:: showDynBlocks()
 907
 908   List all dynamic blocks in effect.
 909
 910 .. function:: setDynBlocksAction(action)
 911
 912   .. versionchanged:: 1.3.3
 913     ``DNSAction.NXDomain`` action added.
 914
 915   Set which action is performed when a query is blocked.
 916   Only DNSAction.Drop (the default), DNSAction.NoOp, DNSAction.NXDomain, DNSAction.Refused, DNSAction.Truncate and DNSAction.NoRecurse are supported.
 917
 918 .. _exceedfuncs:
 919
 920 Getting addresses that exceeded parameters
 921 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 922
 923 .. function:: exceedServFails(rate, seconds)
 924
 925   Get set of addresses that exceed ``rate`` servfails/s over ``seconds`` seconds
 926
 927   :param int rate: Number of Servfails per second to exceed
 928   :param int seconds: Number of seconds the rate has been exceeded
 929
 930 .. function:: exceedNXDOMAINs(rate, seconds)
 931
 932   get set of addresses that exceed ``rate`` NXDOMAIN/s over ``seconds`` seconds
 933
 934   :param int rate: Number of NXDOMAIN per second to exceed
 935   :param int seconds: Number of seconds the rate has been exceeded
 936
 937 .. function:: exceedRespByterate(rate, seconds)
 938
 939   get set of addresses that exceeded ``rate`` bytes/s answers over ``seconds`` seconds
 940
 941   :param int rate: Number of bytes per second to exceed
 942   :param int seconds: Number of seconds the rate has been exceeded
 943
 944 .. function:: exceedQRate(rate, seconds)
 945
 946   Get set of address that exceed ``rate`` queries/s over ``seconds`` seconds
 947
 948   :param int rate: Number of queries per second to exceed
 949   :param int seconds: Number of seconds the rate has been exceeded
 950
 951 .. function:: exceedQTypeRate(type, rate, seconds)
 952
 953   Get set of address that exceed ``rate`` queries/s for queries of QType ``type`` over ``seconds`` seconds
 954
 955   :param int type: QType
 956   :param int rate: Number of QType queries per second to exceed
 957   :param int seconds: Number of seconds the rate has been exceeded
 958
 959 DynBlockRulesGroup
 960 ~~~~~~~~~~~~~~~~~~
 961
 962 Instead of using several `exceed*()` lines, dnsdist 1.3.0 introduced a new `DynBlockRulesGroup` object
 963 which can be used to group dynamic block rules.
 964
 965 See :doc:`../guides/dynblocks` for more information about the case where using a `DynBlockRulesGroup` might be
 966 faster than the existing rules.
 967
 968 .. function:: dynBlockRulesGroup() -> DynBlockRulesGroup
 969
 970   .. versionadded:: 1.3.0
 971
 972   Creates a new :class:`DynBlockRulesGroup` object.
 973
 974 .. class:: DynBlockRulesGroup
 975
 976   Represents a group of dynamic block rules.
 977
 978   .. method:: DynBlockRulesGroup:setQueryRate(rate, seconds, reason, blockingTime [, action [, warningRate]])
 979
 980     .. versionchanged:: 1.3.3
 981         ``warningRate`` parameter added.
 982
 983     Adds a query rate-limiting rule, equivalent to:
 984     ```
 985     addDynBlocks(exceedQRate(rate, seconds), reason, blockingTime, action)
 986     ```
 987
 988     :param int rate: Number of queries per second to exceed
 989     :param int seconds: Number of seconds the rate has been exceeded
 990     :param string reason: The message to show next to the blocks
 991     :param int blockingTime: The number of seconds this block to expire
 992     :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
 993     :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
 994
 995   .. method:: DynBlockRulesGroup:setRCodeRate(rcode, rate, seconds, reason, blockingTime [, action [, warningRate]])
 996
 997     .. versionchanged:: 1.3.3
 998         ``warningRate`` parameter added.
 999
1000     Adds a rate-limiting rule for responses of code ``rcode``, equivalent to:
1001     ```
1002     addDynBlocks(exceedServfails(rcode, rate, seconds), reason, blockingTime, action)
1003     ```
1004
1005     :param int rcode: The response code
1006     :param int rate: Number of responses per second to exceed
1007     :param int seconds: Number of seconds the rate has been exceeded
1008     :param string reason: The message to show next to the blocks
1009     :param int blockingTime: The number of seconds this block to expire
1010     :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
1011     :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
1012
1013   .. method:: DynBlockRulesGroup:setQTypeRate(qtype, rate, seconds, reason, blockingTime [, action [, warningRate]])
1014
1015     .. versionchanged:: 1.3.3
1016         ``warningRate`` parameter added.
1017
1018     Adds a rate-limiting rule for queries of type ``qtype``, equivalent to:
1019     ```
1020     addDynBlocks(exceedQTypeRate(type, rate, seconds), reason, blockingTime, action)
1021     ```
1022
1023     :param int qtype: The qtype
1024     :param int rate: Number of queries per second to exceed
1025     :param int seconds: Number of seconds the rate has been exceeded
1026     :param string reason: The message to show next to the blocks
1027     :param int blockingTime: The number of seconds this block to expire
1028     :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
1029     :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
1030
1031   .. method:: DynBlockRulesGroup:setResponseByteRate(rate, seconds, reason, blockingTime [, action [, warningRate]])
1032
1033     .. versionchanged:: 1.3.3
1034         ``warningRate`` parameter added.
1035
1036     Adds a bandwidth rate-limiting rule for responses, equivalent to:
1037     ```
1038     addDynBlocks(exceedRespByterate(rate, seconds), reason, blockingTime, action)
1039     ```
1040
1041     :param int rate: Number of bytes per second to exceed
1042     :param int seconds: Number of seconds the rate has been exceeded
1043     :param string reason: The message to show next to the blocks
1044     :param int blockingTime: The number of seconds this block to expire
1045     :param int action: The action to take when the dynamic block matches, see :ref:`here <DNSAction>`. (default to the one set with :func:`setDynBlocksAction`)
1046     :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
1047
1048   .. method:: DynBlockRulesGroup:apply()
1049
1050     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.
1051
1052   .. method:: DynBlockRulesGroup:setQuiet(quiet)
1053
1054     .. versionadded:: 1.4.0
1055
1056     Set whether newly blocked clients or domains should be logged.
1057
1058     :param bool quiet: True means that insertions will not be logged, false that they will. Default is false.
1059
1060   .. method:: DynBlockRulesGroup:excludeRange(netmasks)
1061
1062     .. versionadded:: 1.3.1
1063
1064     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.
1065
1066     :param int netmasks: A netmask, or list of netmasks, as strings, like for example "192.0.2.1/24"
1067
1068   .. method:: DynBlockRulesGroup:includeRange(netmasks)
1069
1070     .. versionadded:: 1.3.1
1071
1072     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.
1073
1074     :param int netmasks: A netmask, or list of netmasks, as strings, like for example "192.0.2.1/24"
1075
1076   .. method:: DynBlockRulesGroup:toString()
1077
1078     .. versionadded:: 1.3.1
1079
1080     Return a string describing the rules and range exclusions of this DynBlockRulesGroup.
1081
1082 SuffixMatchNode
1083 ~~~~~~~~~~~~~~~
1084
1085 A SuffixMatchNode can be used to quickly check whether a given name belongs to a set or not. This is achieved
1086 using an efficient tree structure based on DNS labels, making lookups cheap.
1087 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,
1088 if 'example.com.' is added to the set, 'www.example.com.' and 'sub.www.example.com.' will match as well.
1089 If you are looking for exact name matching, your might want to consider using a :class:`DNSNameSet` instead.
1090
1091 .. function:: newSuffixMatchNode()
1092
1093   Creates a new :class:`SuffixMatchNode`.
1094
1095 .. class:: SuffixMatchNode
1096
1097   Represent a set of DNS suffixes for quick matching.
1098
1099   .. method:: SuffixMatchNode:add(name)
1100     .. versionchanged:: 1.4.0
1101       This method now accepts strings, lists of DNSNames and lists of strings.
1102
1103     Add a suffix to the current set.
1104
1105     :param DNSName name: The suffix to add to the set.
1106     :param string name: The suffix to add to the set.
1107     :param table name: The suffixes to add to the set. Elements of the table should be of the same type, either DNSName or string.
1108
1109   .. method:: SuffixMatchNode:check(name) -> bool
1110
1111     Return true if the given name is a sub-domain of one of those in the set, and false otherwise.
1112
1113     :param DNSName name: The name to test against the set.
1114
1115 Other functions
1116 ---------------
1117
1118 .. function:: maintenance()
1119
1120   If this function exists, it is called every second to so regular tasks.
1121   This can be used for e.g. :doc:`Dynamic Blocks <../guides/dynblocks>`.
1122
1123 .. function:: setAllowEmptyResponse()
1124
1125   .. versionadded:: 1.4.0
1126
1127   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.
1128
1129 .. function:: makeIPCipherKey(password) -> string
1130
1131   .. versionadded:: 1.4.0
1132
1133   Hashes the password to generate a 16-byte key that can be used to pseudonymize IP addresses with IP cipher.
1134
1135 .. function:: generateOCSPResponse(pathToServerCertificate, pathToCACertificate, pathToCAPrivateKey, outputFile, numberOfDaysOfValidity, numberOfMinutesOfValidity)
1136
1137   .. versionadded:: 1.4.0
1138
1139   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.
1140   The resulting file can be directly used with the :func:`addDOHLocal` or the :func:`addTLSLocal` functions.
1141
1142   :param string pathToServerCertificate: Path to a file containing the certificate used by the server.
1143   :param string pathToCACertificate: Path to a file containing the certificate of the certification authority that was used to sign the server certificate.
1144   :param string pathToCAPrivateKey: Path to a file containing the private key corresponding to the certification authority certificate.
1145   :param string outputFile: Path to a file where the resulting OCSP response will be written to.
1146   :param int numberOfDaysOfValidity: Number of days this OCSP response should be valid.
1147   :param int numberOfMinutesOfValidity: Number of minutes this OCSP response should be valid, in addition to the number of days.
1148
1149 DOHFrontend
1150 ~~~~~~~~~~~
1151
1152 .. class:: DOHFrontend
1153
1154   .. versionadded:: 1.4.0
1155
1156   This object represents an address and port dnsdist is listening on for DNS over HTTPS queries.
1157
1158   .. method:: DOHFrontend:loadTicketsKeys(ticketsKeysFile)
1159
1160      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.
1161
1162     :param str ticketsKeysFile: The path to a file from where TLS tickets keys should be loaded.
1163
1164   .. method:: DOHFrontend:reloadCertificates()
1165
1166      Reload the current TLS certificate and key pairs.
1167
1168   .. method:: DOHFrontend:rotateTicketsKey()
1169
1170      Replace the current TLS tickets key by a new random one.
1171
1172   .. method:: DOHFrontend:setResponsesMap(rules)
1173
1174      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.
1175
1176      :param list of DOHResponseMapEntry objects rules: A list of DOHResponseMapEntry objects, obtained with :func:`newDOHResponseMapEntry`.
1177
1178
1179 .. function:: newDOHResponseMapEntry(regex, status, content [, headers]) -> DOHResponseMapEntry
1180
1181   .. versionadded:: 1.4.0
1182
1183   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.
1184   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.
1185
1186   :param str regex: A regular expression to match the path against.
1187   :param int status: The HTTP code to answer with.
1188   :param str content: The content of the HTTP response, or a URL if the status is a redirection (3xx).
1189   :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`.
1190
1191 TLSContext
1192 ~~~~~~~~~~
1193
1194 .. class:: TLSContext
1195
1196   .. versionadded:: 1.3.0
1197
1198   This object represents an address and port dnsdist is listening on for DNS over TLS queries.
1199
1200   .. method:: TLSContext:rotateTicketsKey()
1201
1202      Replace the current TLS tickets key by a new random one.
1203
1204   .. method:: TLSContext:loadTicketsKeys(ticketsKeysFile)
1205
1206      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.
1207
1208     :param str ticketsKeysFile: The path to a file from where TLS tickets keys should be loaded.
1209
1210 TLSFrontend
1211 ~~~~~~~~~~~
1212
1213 .. class:: TLSFrontend
1214
1215   .. versionadded:: 1.3.1
1216
1217   This object represents the configuration of a listening frontend for DNS over TLS queries. To each frontend is associated a TLSContext.
1218
1219   .. method:: TLSContext:loadNewCertificatesAndKeys(certFile(s), keyFile(s))
1220
1221      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.
1222
1223   :param str certFile(s): The path to a X.509 certificate file in PEM format, or a list of paths to such files.
1224   :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.
1225
1226 EDNS on Self-generated answers
1227 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1228
1229 There are several mechanisms in dnsdist that turn an existing query into an answer right away,
1230 without reaching out to the backend, including :func:`SpoofAction`, :func:`RCodeAction`, :func:`TCAction`
1231 and returning a response from ``Lua``. Those responses should, according to :rfc:`6891`, contain an ``OPT``
1232 record if the received request had one, which is the case by default and can be disabled using
1233 :func:`setAddEDNSToSelfGeneratedResponses`.
1234
1235 We must, however, provide a responder's maximum payload size in this record, and we can't easily know the
1236 maximum payload size of the actual backend so we need to provide one. The default value is 1500 and can be
1237 overriden using :func:`setPayloadSizeOnSelfGeneratedAnswers`.
1238
1239 .. function:: setAddEDNSToSelfGeneratedResponses(add)
1240
1241   .. versionadded:: 1.3.3
1242
1243   Whether to add EDNS to self-generated responses, provided that the initial query had EDNS.
1244
1245   :param bool add: Whether to add EDNS, default is true.
1246
1247 .. function:: setPayloadSizeOnSelfGeneratedAnswers(payloadSize)
1248
1249   .. versionadded:: 1.3.3
1250
1251   Set the UDP payload size advertised via EDNS on self-generated responses. In accordance with
1252   :rfc:`RFC 6891 <6891#section-6.2.5>`, values lower than 512 will be treated as equal to 512.
1253
1254   :param int payloadSize: The responder's maximum UDP payload size, in bytes. Default is 1500.
1255
1256 Security Polling
1257 ~~~~~~~~~~~~~~~~
1258
1259 PowerDNS products can poll the security status of their respective versions. This polling, naturally,
1260 happens over DNS. If the result is that a given version has a security problem, the software will
1261 report this at level ‘Error’ during startup, and repeatedly during operations, every
1262 :func:`setSecurityPollInterval` seconds.
1263
1264 By default, security polling happens on the domain ‘secpoll.powerdns.com’, but this can be changed with
1265 the :func:`setSecurityPollSuffix` function. If this setting is made empty, no polling will take place.
1266 Organizations wanting to host their own security zones can do so by changing this setting to a domain name
1267 under their control.
1268
1269 To enable distributors of PowerDNS to signal that they have backported versions, the PACKAGEVERSION
1270 compilation-time macro can be used to set a distributor suffix.
1271
1272 .. function:: setSecurityPollInterval(interval)
1273
1274   .. versionadded:: 1.3.3
1275
1276   Set the interval, in seconds, between two security pollings.
1277
1278   :param int interval: The interval, in seconds, between two pollings. Default is 3600.
1279
1280 .. function:: setSecurityPollSuffix(suffix)
1281
1282   .. versionadded:: 1.3.3
1283
1284   Domain name from which to query security update notifications. Setting this to an empty string disables secpoll.
1285
1286   :param string suffix: The suffix to use, default is 'secpoll.powerdns.com.'.