Tip

This is the documentation for the v21.03 version. Looking for the documentation of the latest version? Have a look here.

Cache & Performance Tuning

port outgoing range <n>:

Sets the number of source ports Unbound may use per thread to connect when making outbound queries to upstream servers. A larger number of ports provides protection against spoofing. Default value varies by platform. A large number of ports yields better performance but it also consumes more host resources.

edns reassembly size <s>:

Number to advertise as the EDNS reassembly buffer size, in bytes. This value is sent in queries and must not be set larger than the default message buffer size, 65552. The default value is 4096, which is recommended by RFC. May be set lower to alleviate problems with fragmentation resulting in timeouts. If the default value is too large, try 1472, or 512 in extreme cases. Avoid setting that low as it will cause many queries to fall back to TCP which can negatively impact performance.

host cache num-hosts <num>:

Number of hosts to hold in the cache, defaults to 10000. Larger caches can result in increased performance but consume more host resources.

host cache slabs <s>:

Number of slabs in the host cache. Larger numbers help prevent lock contention by threads when performing cache operations. The value is a power of 2, between 0..10

host cache ttl <t>:

The amount of time, in seconds, that entries in the host cache are kept. Default value is 900 seconds.

enable key prefetch:

When enabled, Unbound will start fetching DNSKEYS when it sees a DS record instead of waiting until later in the process. Prefetching keys will consume more CPU, but reduces latency. The default is disabled.

key cache slabs <s>:

Number of slabs in the key cache. Larger numbers help prevent lock contention by threads when performing key cache operations. The value is a power of 2, between 0..10. Setting to a number close to the number of CPUs/cores in the host is best.

enable message prefetch:

Prefetch message cache items before they expire to keep entries in the cache updated. When enabled, Unbound will consume approximately 10% more throughput and CPU time but it will keep popular items primed in the cache for better client performance. Disabled by default.

message cache size <s>:

Size of the message cache, in bytes. The message cache stores DNS meta-information such as message formats. Default value is 4 MB.

message cache slabs <s>:

Number of slabs in the message cache. Larger numbers help prevent lock contention by threads when performing message cache operations. The value is a power of 2, between 0..10. Setting to a number close to the number of CPUs/cores in the host is best.

rrset cache size <s>:

Size of the RRset cache, in bytes. The RRset cache stores resource records. Default value is 4 MB.

rrset cache slabs <s>:

Number of slabs in the RRset cache. Larger numbers help prevent lock contention by threads when performing RRset cache operations. The value is a power of 2, between 0..10. Setting to a number close to the number of CPUs/cores in the host is best.

rrset-message cache ttl maximum <max>:

Maximum time that values in the RRset and message caches are kept in the cache, specified in seconds. The default value is 86400 (1 day). When set lower, Unbound will be forced to query for data more often, but it will also ignore very large TTLs in DNS responses.

rrset-message cache ttl minimum <max>:

Minimum time that values in the RRset and message caches are kept in the cache, specified in seconds. The default value is 0, which honors the TTL specified in the DNS response. Higher values may ignore the TTL set by the response, which means a record may be out of sync with the source, but it also prevents queries from being repeated frequently when a very low TTL is set by the domain.

socket receive-buffer size <s>:

SO_RCVBUF socket receive buffer size for incoming queries on the listening port(s). Larger values result in less drops during spikes in activity. The default is 0 which uses the system default value. Cannot be set higher than the maximum value for the operating system, such as the one shown in the net.core.rmem_max sysctl OID.

tcp buffers incoming <n>:

Number of incoming TCP buffers that Unbound will allocate per thread. Larger values can handle higher loads, but will consume more resources. The default value is 10. A value of 0 will disable acceptance of TCP queries.

tcp buffers outgoing <n>:

Number of outgoing TCP buffers that Unbound will allocate per thread. Larger values can handle higher loads, but will consume more resources. The default value is 10. A value of 0 will disable TCP queries to authoritative DNS servers.

thread num-queries <n>:

Number of queries serviced by each thread simultaneously. If more queries arrive and there is no room to answer them, the new queries will be dropped, unless older/slower queries can be dropped by using the jostle timeout. Default varies by platform but is typically 512 or 1024.

thread num-threads <n>:

Number of threads created by Unbound for serving clients. Defaults to one thread per CPU/core. To disable threading, set to 1.

enable serve-expired:

When enabled, Unbound will immediately serve answers to clients using expired cache entries if they exist. Unbound still performs the query and will update the cache with the result. This can result in faster, but potentially incorrect, answers for client queries. Default is disabled.