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