timeouts

timeouts

Name

timeouts - allows you to configure the supported server read, write and idle timeouts for the TCP, TLS, DoH and DoQ servers, and the maximum number of queries served on a single TCP or TLS connection.

Description

CoreDNS is configured with sensible timeouts for server connections by default. However in some cases for example where CoreDNS is serving over a slow mobile data connection the default timeouts are not optimal.

Additionally some routers hold open connections when using DNS over TLS or DNS over HTTPS. Allowing a longer idle timeout helps performance and reduces issues with such routers.

The timeouts "plugin" allows you to configure CoreDNS server read, write and idle timeouts, and the maximum number of queries CoreDNS will serve on a single TCP or TLS connection before closing it.

Syntax

timeouts {
	read DURATION
	write DURATION
	idle DURATION
	maxtcpqueries MAXIMUM
}

For any timeouts that are not provided, default values are used which may vary depending on the server type. At least one option must be specified otherwise the entire timeouts block should be omitted.

• maxtcpqueries sets the maximum number of queries served on a single TCP or TLS connection before CoreDNS closes it. MAXIMUM must be a positive integer, or -1 to allow an unlimited number of queries per connection (the default). Long-lived connections that serve an unlimited number of queries can cause uneven load distribution across CoreDNS replicas that sit behind a connection-based load balancer, since new queries keep reusing the same connection instead of establishing a new one. Setting a bound, e.g. maxtcpqueries 128, forces clients to periodically reconnect, which allows the load balancer to redistribute load.

The configured timeouts apply where the selected server transport supports them. TCP, TLS and DoH servers use the read, write and idle timeouts. DoQ servers use the read timeout to bound receiving a query on an opened QUIC stream, and the idle timeout to bound idle QUIC connections.

Examples

Start a DNS-over-TLS server that picks up incoming DNS-over-TLS queries on port 5553 and uses the nameservers defined in /etc/resolv.conf to resolve the query. This proxy path uses plain old DNS. A 10 second read timeout, 20 second write timeout and a 60 second idle timeout have been configured.

tls://.:5553 {
	tls cert.pem key.pem ca.pem
	timeouts {
		read 10s
		write 20s
		idle 60s
	}
	forward . /etc/resolv.conf
}

Start a DNS-over-HTTPS server that is similar to the previous example. Only the read timeout has been configured for 1 minute.

https://. {
	tls cert.pem key.pem ca.pem
	timeouts {
		read 1m
	}
	forward . /etc/resolv.conf
}

Start a DNS-over-QUIC server that has a 10 second read timeout for receiving a query on an opened stream and the idle timeout set to two minutes.

quic://.:853 {
	tls cert.pem key.pem ca.pem
	timeouts {
		read 10s
		idle 2m
	}
	forward . /etc/resolv.conf
}

Start a standard TCP/UDP server on port 1053. A read and write timeout has been configured. The timeouts are only applied to the TCP side of the server.

.:1053 {
	timeouts {
		read 15s
		write 30s
	}
	forward . /etc/resolv.conf
}

Start a standard TCP/UDP server that closes a TCP connection after it has served 128 queries, to help spread load evenly across replicas sitting behind a connection-based load balancer.

. {
	timeouts {
		maxtcpqueries 128
	}
	forward . /etc/resolv.conf
}