pdns/dnsdistdist/docs/reference/tuning.rst

   1 Tuning related functions
   2 ========================
   3
   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.
   9   :param int interval: The interval in seconds.
  10
  11 .. function:: setDoHDownstreamMaxIdleTime(max)
  12
  13   .. versionadded:: 1.7.0
  14
  15   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.
  16
  17   :param int max: The maximum time in seconds.
  18
  19 .. function:: setMaxIdleDoHConnectionsPerDownstream(max)
  20
  21   .. versionadded:: 1.7.0
  22
  23   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.
  24
  25   :param int max: The maximum number of inactive connections to keep. Default is 10, so 10 connections per backend and per DoH worker thread.
  26
  27 .. function:: setMaxCachedTCPConnectionsPerDownstream(max)
  28
  29   .. versionadded:: 1.6.0
  30
  31   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.
  32
  33   :param int max: The maximum number of inactive connections to keep. Default is 10, so 10 connections per backend and per TCP worker thread.
  34
  35 .. function:: setMaxTCPClientThreads(num)
  36
  37   .. versionchanged:: 1.6.0
  38     Before 1.6.0 the default value was 10.
  39   .. versionchanged:: 1.7.0
  40     The default value has been set back to 10.
  41
  42   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.
  43
  44   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.
  45
  46   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.
  47
  48   :param int num: The number of TCP worker threads.
  49
  50 .. function:: setMaxTCPConnectionDuration(num)
  51
  52   Set the maximum duration of an incoming TCP connection, in seconds. 0 (the default) means unlimited
  53
  54   :param int num:
  55
  56 .. function:: setMaxTCPConnectionsPerClient(num)
  57
  58   Set the maximum number of TCP connections per client. 0 (the default) means unlimited
  59
  60   :param int num:
  61
  62 .. function:: setMaxTCPQueriesPerConnection(num)
  63
  64   Set the maximum number of queries in an incoming TCP connection. 0 (the default) means unlimited
  65
  66   :param int num:
  67
  68 .. function:: setMaxTCPQueuedConnections(num)
  69
  70   .. versionchanged:: 1.6.0
  71     Before 1.6.0 the default value was 1000 on all systems.
  72
  73   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
  74
  75   :param int num:
  76
  77 .. function:: setMaxUDPOutstanding(num)
  78
  79   .. versionchanged:: 1.4.0
  80     Before 1.4.0 the default value was 10240
  81
  82   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)
  83
  84   :param int num:
  85
  86 .. function:: setCacheCleaningDelay(num)
  87
  88   Set the interval in seconds between two runs of the cache cleaning algorithm, removing expired entries. Default is every 60s
  89
  90   :param int num:
  91
  92 .. function:: setCacheCleaningPercentage(num)
  93
  94   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
  95
  96   :param int num:
  97
  98 .. function:: setOutgoingDoHWorkerThreads(num)
  99
 100   .. versionadded:: 1.7.0
 101
 102   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.
 103
 104 .. function:: setStaleCacheEntriesTTL(num)
 105
 106   Allows using cache entries expired for at most n seconds when no backend available to answer for a query
 107
 108   :param int num:
 109
 110 .. function:: setTCPDownstreamCleanupInterval(interval)
 111
 112   .. versionadded:: 1.6.0
 113
 114   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.
 115
 116   :param int interval: The interval in seconds.
 117
 118 .. function:: setDoHDownstreamMaxIdleTime(max)
 119
 120   .. versionadded:: 1.7.0
 121
 122   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.
 123
 124   :param int max: The maximum time in seconds.
 125
 126
 127 .. function:: setRandomizedIdsOverUDP(val)
 128
 129   .. versionadded:: 1.8.0
 130
 131   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`
 132   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.
 133   See also :func:`setRandomizedOutgoingSockets`.
 134   The default is to use a linearly increasing counter from 0 to 65535, wrapping back to 0 when necessary.
 135
 136 .. function:: setRandomizedOutgoingSockets(val):
 137
 138   .. versionadded:: 1.8.0
 139
 140   Setting this parameter to true (default is false) will randomize the outgoing socket used when forwarding a query to a backend.
 141   The default is to use a round-robin mechanism to select the outgoing socket.
 142   This requires configuring the backend to use more than one outgoing socket via the ``sockets`` parameter of :func:`newServer`
 143   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
 144   TLS or DNS over HTTPS transports cannot be used.
 145   See also :func:`setRandomizedIdsOverUDP`.
 146
 147 .. function:: setTCPInternalPipeBufferSize(size)
 148
 149   .. versionadded:: 1.6.0
 150
 151   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.
 152
 153   :param int size: The size in bytes.
 154
 155 .. function:: setTCPUseSinglePipe(val)
 156
 157   .. deprecated:: 1.6.0
 158
 159   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.
 160
 161   :param bool val:
 162
 163 .. function:: setTCPRecvTimeout(num)
 164
 165   Set the read timeout on TCP connections from the client, in seconds
 166
 167   :param int num:
 168
 169 .. function:: setTCPSendTimeout(num)
 170
 171   Set the write timeout on TCP connections from the client, in seconds
 172
 173   :param int num:
 174
 175 .. function:: setUDPMultipleMessagesVectorSize(num)
 176
 177   Set the maximum number of UDP queries messages to accept in a single ``recvmmsg()`` call. Only available if the underlying OS
 178   support ``recvmmsg()`` with the ``MSG_WAITFORONE`` option. Defaults to 1, which means only query at a time is accepted, using
 179   ``recvmsg()`` instead of ``recvmmsg()``.
 180
 181   :param int num: maximum number of UDP queries to accept
 182
 183 .. function:: setUDPSocketBufferSize(recv, send)
 184
 185   .. versionadded:: 1.7.0
 186
 187   Set the size of the receive (``SO_RCVBUF``) and send (``SO_SNDBUF``) buffers for incoming UDP sockets. On Linux the default
 188   values correspond to ``net.core.rmem_default`` and ``net.core.wmem_default`` , and the maximum values are restricted
 189   by ``net.core.rmem_max`` and ``net.core.wmem_max``.
 190
 191   :param int recv: ``SO_RCVBUF`` value. Default is 0, meaning the system value will be kept.
 192   :param int send: ``SO_SNDBUF`` value. Default is 0, meaning the system value will be kept.
 193
 194 .. function:: setUDPTimeout(num)
 195
 196   Set the maximum time dnsdist will wait for a response from a backend over UDP, in seconds. Defaults to 2
 197
 198   :param int num: