mirror of
https://github.com/coredns/coredns.git
synced 2026-10-09 03:55:21 -04:00
311a9915da
The `tools.ietf.org` site now redirects to `www.rfc-editor.org`. * Update various URLs to the new site. * Make links to `www.rfc-editor.org` consistent. Signed-off-by: SuperQ <superq@gmail.com>
163 lines
3.8 KiB
Groff
163 lines
3.8 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-TIMEOUTS" 7 "October 2026" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fItimeouts\fP - 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.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
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.
|
|
|
|
.PP
|
|
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.
|
|
|
|
.PP
|
|
The \fItimeouts\fP "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.
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
timeouts {
|
|
read DURATION
|
|
write DURATION
|
|
idle DURATION
|
|
maxtcpqueries MAXIMUM
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
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.
|
|
|
|
.IP \(bu 4
|
|
\fB\fCmaxtcpqueries\fR sets the maximum number of queries served on a single TCP or
|
|
TLS connection before CoreDNS closes it. \fBMAXIMUM\fP must be a positive
|
|
integer, or \fB\fC-1\fR 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.
|
|
\fB\fCmaxtcpqueries 128\fR, forces clients to periodically reconnect, which allows
|
|
the load balancer to redistribute load.
|
|
|
|
|
|
.PP
|
|
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.
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Start a DNS-over-TLS server that picks up incoming DNS-over-TLS queries on port
|
|
5553 and uses the nameservers defined in \fB\fC/etc/resolv.conf\fR 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.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
tls://.:5553 {
|
|
tls cert.pem key.pem ca.pem
|
|
timeouts {
|
|
read 10s
|
|
write 20s
|
|
idle 60s
|
|
}
|
|
forward . /etc/resolv.conf
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Start a DNS-over-HTTPS server that is similar to the previous example. Only the
|
|
read timeout has been configured for 1 minute.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
https://. {
|
|
tls cert.pem key.pem ca.pem
|
|
timeouts {
|
|
read 1m
|
|
}
|
|
forward . /etc/resolv.conf
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
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.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
quic://.:853 {
|
|
tls cert.pem key.pem ca.pem
|
|
timeouts {
|
|
read 10s
|
|
idle 2m
|
|
}
|
|
forward . /etc/resolv.conf
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
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.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&.:1053 {
|
|
timeouts {
|
|
read 15s
|
|
write 30s
|
|
}
|
|
forward . /etc/resolv.conf
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
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.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
timeouts {
|
|
maxtcpqueries 128
|
|
}
|
|
forward . /etc/resolv.conf
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|