[thirdparty/pdns.git] / pdns / dnsdistdist / docs / reference / tuning.rst

Tuning related functions
========================

.. function:: setDoHDownstreamCleanupInterval(interval)

  .. versionadded:: 1.7.0

  Set how often, in seconds, the outgoing DoH connections to backends of a given worker thread are scanned to expunge the ones that are no longer usable. The default is 60 so once per minute and per worker thread.

  :param int interval: The interval in seconds.

.. function:: setDoHDownstreamMaxIdleTime(max)

  .. versionadded:: 1.7.0

  Set how long, in seconds, an outgoing DoH connection to a backend might stay idle before being closed. The default is 300 so 5 minutes.

  :param int max: The maximum time in seconds.

.. function:: setMaxIdleDoHConnectionsPerDownstream(max)

  .. versionadded:: 1.7.0

  Set the maximum number of inactive DoH connections to a backend cached by each DoH worker thread. These connections can be reused when a new query comes in, instead of having to establish a new connection. dnsdist regularly checks whether the other end has closed any cached connection, closing them in that case.

  :param int max: The maximum number of inactive connections to keep. Default is 10, so 10 connections per backend and per DoH worker thread.

.. function:: setMaxCachedTCPConnectionsPerDownstream(max)

  .. versionadded:: 1.6.0

  Set the maximum number of inactive TCP connections to a backend cached by each TCP worker thread. These connections can be reused when a new query comes in, instead of having to establish a new connection. dnsdist regularly checks whether the other end has closed any cached connection, closing them in that case.

  :param int max: The maximum number of inactive connections to keep. Default is 10, so 10 connections per backend and per TCP worker thread.

.. function:: setMaxTCPClientThreads(num)

  .. versionchanged:: 1.6.0
    Before 1.6.0 the default value was 10.
  .. versionchanged:: 1.7.0
    The default value has been set back to 10.

  Set the maximum of TCP client threads, handling TCP connections. Before 1.4.0 a TCP thread could only handle a single incoming TCP connection at a time, while after 1.4.0 it can handle a larger number of them simultaneously.

  Note that before 1.6.0 the TCP worker threads were created at runtime, adding a new thread when the existing ones seemed to struggle with the load, until the maximum number of threads had been reached. Starting with 1.6.0 the configured number of worker threads are immediately created at startup.

  In 1.6.0 the default value was at least 10 TCP workers, but could be more if there is more than 10 TCP listeners (added via :func:`addDNSCryptBind`, :func:`addLocal`, or :func:`addTLSLocal`). In that last case there would have been as many TCP workers as TCP listeners. This led to issues in setups with a large number of TCP listeners and was therefore reverted back to 10 in 1.7.0.

  :param int num: The number of TCP worker threads.

.. function:: setMaxTCPConnectionDuration(num)

  Set the maximum duration of an incoming TCP connection, in seconds. 0 (the default) means unlimited

  :param int num:

.. function:: setMaxTCPConnectionsPerClient(num)

  Set the maximum number of TCP connections per client. 0 (the default) means unlimited

  :param int num:

.. function:: setMaxTCPQueriesPerConnection(num)

  Set the maximum number of queries in an incoming TCP connection. 0 (the default) means unlimited

  :param int num:

.. function:: setMaxTCPQueuedConnections(num)

  .. versionchanged:: 1.6.0
    Before 1.6.0 the default value was 1000 on all systems.

  Set the maximum number of TCP connections queued (waiting to be picked up by a client thread), defaults to 1000 (10000 on Linux since 1.6.0). 0 means unlimited

  :param int num:

.. function:: setMaxUDPOutstanding(num)

  .. versionchanged:: 1.4.0
    Before 1.4.0 the default value was 10240

  Set the maximum number of outstanding UDP queries to a given backend server. This can only be set at configuration time and defaults to 65535 (10240 before 1.4.0)

  :param int num:

.. function:: setCacheCleaningDelay(num)

  Set the interval in seconds between two runs of the cache cleaning algorithm, removing expired entries. Default is every 60s

  :param int num:

.. function:: setCacheCleaningPercentage(num)

  Set the percentage of the cache that the cache cleaning algorithm will try to free by removing expired entries. By default (100), all expired entries are removed

  :param int num:

.. function:: setOutgoingDoHWorkerThreads(num)

  .. versionadded:: 1.7.0

  Set the number of worker threads to use for outgoing DoH. That number defaults to 0 but is automatically raised to 1 when DoH is enabled on at least one backend.

.. function:: setStaleCacheEntriesTTL(num)

  Allows using cache entries expired for at most n seconds when no backend available to answer for a query

  :param int num:

.. function:: setTCPDownstreamCleanupInterval(interval)

  .. versionadded:: 1.6.0

  Set how often, in seconds, the outgoing TCP connections to backends of a given worker thread are scanned to expunge the ones that are no longer usable. The default is 60 so once per minute and per worker thread.

  :param int interval: The interval in seconds.

.. function:: setDoHDownstreamMaxIdleTime(max)

  .. versionadded:: 1.7.0

  Set how long, in seconds, an outgoing DoH connection to a backend might stay idle before being closed. The default is 300 so 5 minutes.

  :param int max: The maximum time in seconds.


.. function:: setRandomizedIdsOverUDP(val)

  .. versionadded:: 1.8.0

  Setting this parameter to true (default is false) will randomize the IDs in outgoing UDP queries, at a small performance cost, ignoring the :func:`setMaxUDPOutstanding`
  value. This is only useful if the path between dnsdist and the backend is not trusted and the 'TCP-only', DNS over TLS or DNS over HTTPS transports cannot be used.
  See also :func:`setRandomizedOutgoingSockets`.
  The default is to use a linearly increasing counter from 0 to 65535, wrapping back to 0 when necessary.

.. function:: setRandomizedOutgoingSockets(val):

  .. versionadded:: 1.8.0

  Setting this parameter to true (default is false) will randomize the outgoing socket used when forwarding a query to a backend.
  The default is to use a round-robin mechanism to select the outgoing socket.
  This requires configuring the backend to use more than one outgoing socket via the ``sockets`` parameter of :func:`newServer`
  to be of any use, and only makes sense if the path between dnsdist and the backend is not trusted and the 'TCP-only', DNS over
  TLS or DNS over HTTPS transports cannot be used.
  See also :func:`setRandomizedIdsOverUDP`.

.. function:: setTCPInternalPipeBufferSize(size)

  .. versionadded:: 1.6.0

  Set the size in bytes of the internal buffer of the pipes used internally to distribute connections to TCP (and DoT) workers threads. Requires support for ``F_SETPIPE_SZ`` which is present in Linux since 2.6.35. The actual size might be rounded up to a multiple of a page size. 0 means that the OS default size is used. The default value is 0, except on Linux where it is 1048576 since 1.6.0.

  :param int size: The size in bytes.

.. function:: setTCPUseSinglePipe(val)

  .. deprecated:: 1.6.0

  Whether the incoming TCP connections should be put into a single queue instead of using per-thread queues. Defaults to false. That option was useful before 1.4.0 when a single TCP connection could block a TCP worker thread, but should not be used in recent versions where the per-thread queues model avoids waking up all idle workers when a new connection arrives. This option will be removed in 1.7.0.

  :param bool val:

.. function:: setTCPRecvTimeout(num)

  Set the read timeout on TCP connections from the client, in seconds

  :param int num:

.. function:: setTCPSendTimeout(num)

  Set the write timeout on TCP connections from the client, in seconds

  :param int num:

.. function:: setUDPMultipleMessagesVectorSize(num)

  Set the maximum number of UDP queries messages to accept in a single ``recvmmsg()`` call. Only available if the underlying OS
  support ``recvmmsg()`` with the ``MSG_WAITFORONE`` option. Defaults to 1, which means only query at a time is accepted, using
  ``recvmsg()`` instead of ``recvmmsg()``.

  :param int num: maximum number of UDP queries to accept

.. function:: setUDPSocketBufferSize(recv, send)

  .. versionadded:: 1.7.0

  Set the size of the receive (``SO_RCVBUF``) and send (``SO_SNDBUF``) buffers for incoming UDP sockets. On Linux the default
  values correspond to ``net.core.rmem_default`` and ``net.core.wmem_default`` , and the maximum values are restricted
  by ``net.core.rmem_max`` and ``net.core.wmem_max``.

  :param int recv: ``SO_RCVBUF`` value. Default is 0, meaning the system value will be kept.
  :param int send: ``SO_SNDBUF`` value. Default is 0, meaning the system value will be kept.

.. function:: setUDPTimeout(num)

  Set the maximum time dnsdist will wait for a response from a backend over UDP, in seconds. Defaults to 2

  :param int num:
Commit	Line	Data
20d81666 PL	1	Tuning related functions
	2	========================
	3
767f5514 RG	4	.. function:: setDoHDownstreamCleanupInterval(interval)
	5
	6	.. versionadded:: 1.7.0
	7
	8	Set how often, in seconds, the outgoing DoH connections to backends of a given worker thread are scanned to expunge the ones that are no longer usable. The default is 60 so once per minute and per worker thread.
70f9051e	9
767f5514 RG	10	:param int interval: The interval in seconds.
	11
	12	.. function:: setDoHDownstreamMaxIdleTime(max)
	13
	14	.. versionadded:: 1.7.0
	15
	16	Set how long, in seconds, an outgoing DoH connection to a backend might stay idle before being closed. The default is 300 so 5 minutes.
	17
	18	:param int max: The maximum time in seconds.
	19
54a9a226	20	.. function:: setMaxIdleDoHConnectionsPerDownstream(max)
767f5514 RG	21
	22	.. versionadded:: 1.7.0
	23
	24	Set the maximum number of inactive DoH connections to a backend cached by each DoH worker thread. These connections can be reused when a new query comes in, instead of having to establish a new connection. dnsdist regularly checks whether the other end has closed any cached connection, closing them in that case.
	25
	26	:param int max: The maximum number of inactive connections to keep. Default is 10, so 10 connections per backend and per DoH worker thread.
	27
6d26db15 RG	28	.. function:: setMaxCachedTCPConnectionsPerDownstream(max)
	29
	30	.. versionadded:: 1.6.0
	31
	32	Set the maximum number of inactive TCP connections to a backend cached by each TCP worker thread. These connections can be reused when a new query comes in, instead of having to establish a new connection. dnsdist regularly checks whether the other end has closed any cached connection, closing them in that case.
	33
	34	:param int max: The maximum number of inactive connections to keep. Default is 10, so 10 connections per backend and per TCP worker thread.
	35
20d81666 PL	36	.. function:: setMaxTCPClientThreads(num)
20d81666 PL	37
90e4fcd8 RG	38	.. versionchanged:: 1.6.0
90e4fcd8 RG	39	Before 1.6.0 the default value was 10.
9f63d026	40	.. versionchanged:: 1.7.0
9fea3fcd	41	The default value has been set back to 10.
90e4fcd8	42
0f129b3e	43	Set the maximum of TCP client threads, handling TCP connections. Before 1.4.0 a TCP thread could only handle a single incoming TCP connection at a time, while after 1.4.0 it can handle a larger number of them simultaneously.
9fea3fcd	44
90e4fcd8	45	Note that before 1.6.0 the TCP worker threads were created at runtime, adding a new thread when the existing ones seemed to struggle with the load, until the maximum number of threads had been reached. Starting with 1.6.0 the configured number of worker threads are immediately created at startup.
20d81666	46
9f63d026	47	In 1.6.0 the default value was at least 10 TCP workers, but could be more if there is more than 10 TCP listeners (added via :func:`addDNSCryptBind`, :func:`addLocal`, or :func:`addTLSLocal`). In that last case there would have been as many TCP workers as TCP listeners. This led to issues in setups with a large number of TCP listeners and was therefore reverted back to 10 in 1.7.0.
9fea3fcd RG	48
9fea3fcd RG	49	:param int num: The number of TCP worker threads.
20d81666 PL	50
	51	.. function:: setMaxTCPConnectionDuration(num)
	52
	53	Set the maximum duration of an incoming TCP connection, in seconds. 0 (the default) means unlimited
	54
	55	:param int num:
	56
	57	.. function:: setMaxTCPConnectionsPerClient(num)
	58
	59	Set the maximum number of TCP connections per client. 0 (the default) means unlimited
	60
	61	:param int num:
	62
	63	.. function:: setMaxTCPQueriesPerConnection(num)
	64
	65	Set the maximum number of queries in an incoming TCP connection. 0 (the default) means unlimited
	66
	67	:param int num:
	68
	69	.. function:: setMaxTCPQueuedConnections(num)
	70
69e66563 RG	71	.. versionchanged:: 1.6.0
	72	Before 1.6.0 the default value was 1000 on all systems.
	73
	74	Set the maximum number of TCP connections queued (waiting to be picked up by a client thread), defaults to 1000 (10000 on Linux since 1.6.0). 0 means unlimited
20d81666 PL	75
	76	:param int num:
	77
	78	.. function:: setMaxUDPOutstanding(num)
d5de1498	79
3b203c83 RG	80	.. versionchanged:: 1.4.0
3b203c83 RG	81	Before 1.4.0 the default value was 10240
20d81666	82
3b203c83	83	Set the maximum number of outstanding UDP queries to a given backend server. This can only be set at configuration time and defaults to 65535 (10240 before 1.4.0)
20d81666 PL	84
	85	:param int num:
	86
	87	.. function:: setCacheCleaningDelay(num)
	88
7a17c611	89	Set the interval in seconds between two runs of the cache cleaning algorithm, removing expired entries. Default is every 60s
20d81666 PL	90
	91	:param int num:
	92
	93	.. function:: setCacheCleaningPercentage(num)
	94
	95	Set the percentage of the cache that the cache cleaning algorithm will try to free by removing expired entries. By default (100), all expired entries are removed
	96
	97	:param int num:
	98
168ef594 RG	99	.. function:: setOutgoingDoHWorkerThreads(num)
	100
	101	.. versionadded:: 1.7.0
	102
	103	Set the number of worker threads to use for outgoing DoH. That number defaults to 0 but is automatically raised to 1 when DoH is enabled on at least one backend.
	104
20d81666 PL	105	.. function:: setStaleCacheEntriesTTL(num)
	106
	107	Allows using cache entries expired for at most n seconds when no backend available to answer for a query
	108
	109	:param int num:
	110
767f5514 RG	111	.. function:: setTCPDownstreamCleanupInterval(interval)
	112
	113	.. versionadded:: 1.6.0
	114
	115	Set how often, in seconds, the outgoing TCP connections to backends of a given worker thread are scanned to expunge the ones that are no longer usable. The default is 60 so once per minute and per worker thread.
	116
	117	:param int interval: The interval in seconds.
	118
	119	.. function:: setDoHDownstreamMaxIdleTime(max)
	120
	121	.. versionadded:: 1.7.0
	122
	123	Set how long, in seconds, an outgoing DoH connection to a backend might stay idle before being closed. The default is 300 so 5 minutes.
	124
	125	:param int max: The maximum time in seconds.
	126
	127
46297422 RG	128	.. function:: setRandomizedIdsOverUDP(val)
	129
	130	.. versionadded:: 1.8.0
	131
7686bce9 RG	132	Setting this parameter to true (default is false) will randomize the IDs in outgoing UDP queries, at a small performance cost, ignoring the :func:`setMaxUDPOutstanding`
7686bce9 RG	133	value. This is only useful if the path between dnsdist and the backend is not trusted and the 'TCP-only', DNS over TLS or DNS over HTTPS transports cannot be used.
46297422	134	See also :func:`setRandomizedOutgoingSockets`.
9f266153	135	The default is to use a linearly increasing counter from 0 to 65535, wrapping back to 0 when necessary.
46297422 RG	136
	137	.. function:: setRandomizedOutgoingSockets(val):
	138
	139	.. versionadded:: 1.8.0
	140
	141	Setting this parameter to true (default is false) will randomize the outgoing socket used when forwarding a query to a backend.
9f266153	142	The default is to use a round-robin mechanism to select the outgoing socket.
46297422 RG	143	This requires configuring the backend to use more than one outgoing socket via the ``sockets`` parameter of :func:`newServer`
	144	to be of any use, and only makes sense if the path between dnsdist and the backend is not trusted and the 'TCP-only', DNS over
	145	TLS or DNS over HTTPS transports cannot be used.
	146	See also :func:`setRandomizedIdsOverUDP`.
	147
4ce513a4 RG	148	.. function:: setTCPInternalPipeBufferSize(size)
	149
	150	.. versionadded:: 1.6.0
	151
69e66563	152	Set the size in bytes of the internal buffer of the pipes used internally to distribute connections to TCP (and DoT) workers threads. Requires support for ``F_SETPIPE_SZ`` which is present in Linux since 2.6.35. The actual size might be rounded up to a multiple of a page size. 0 means that the OS default size is used. The default value is 0, except on Linux where it is 1048576 since 1.6.0.
4ce513a4 RG	153
	154	:param int size: The size in bytes.
	155
20d81666 PL	156	.. function:: setTCPUseSinglePipe(val)
20d81666 PL	157
3e695055 RG	158	.. deprecated:: 1.6.0
3e695055 RG	159
aafe00a3	160	Whether the incoming TCP connections should be put into a single queue instead of using per-thread queues. Defaults to false. That option was useful before 1.4.0 when a single TCP connection could block a TCP worker thread, but should not be used in recent versions where the per-thread queues model avoids waking up all idle workers when a new connection arrives. This option will be removed in 1.7.0.
20d81666 PL	161
	162	:param bool val:
	163
	164	.. function:: setTCPRecvTimeout(num)
	165
	166	Set the read timeout on TCP connections from the client, in seconds
	167
	168	:param int num:
	169
	170	.. function:: setTCPSendTimeout(num)
	171
	172	Set the write timeout on TCP connections from the client, in seconds
	173
	174	:param int num:
	175
4bc167b8 RG	176	.. function:: setUDPMultipleMessagesVectorSize(num)
4bc167b8 RG	177
87cb3110 PL	178	Set the maximum number of UDP queries messages to accept in a single ``recvmmsg()`` call. Only available if the underlying OS
	179	support ``recvmmsg()`` with the ``MSG_WAITFORONE`` option. Defaults to 1, which means only query at a time is accepted, using
	180	``recvmsg()`` instead of ``recvmmsg()``.
4bc167b8	181
87cb3110	182	:param int num: maximum number of UDP queries to accept
4bc167b8	183
2ad23378 RG	184	.. function:: setUDPSocketBufferSize(recv, send)
	185
	186	.. versionadded:: 1.7.0
	187
c633c7d9 RG	188	Set the size of the receive (``SO_RCVBUF``) and send (``SO_SNDBUF``) buffers for incoming UDP sockets. On Linux the default
	189	values correspond to ``net.core.rmem_default`` and ``net.core.wmem_default`` , and the maximum values are restricted
	190	by ``net.core.rmem_max`` and ``net.core.wmem_max``.
2ad23378	191
c633c7d9 RG	192	:param int recv: ``SO_RCVBUF`` value. Default is 0, meaning the system value will be kept.
c633c7d9 RG	193	:param int send: ``SO_SNDBUF`` value. Default is 0, meaning the system value will be kept.
2ad23378	194
20d81666 PL	195	.. function:: setUDPTimeout(num)
20d81666 PL	196
4bc167b8	197	Set the maximum time dnsdist will wait for a response from a backend over UDP, in seconds. Defaults to 2
20d81666 PL	198
20d81666 PL	199	:param int num: