# 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

~~~ txt
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
}
~~~
