Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2026-10-24 19:25:43 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve RFC links (#8612)

Browse Source 
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>
This commit is contained in:
Ben Kochie
2026-10-08 10:21:06 +02:00
committed by GitHub
parent 763bdb9b76
commit 311a9915da
60 changed files with 1006 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
man/coredns-forward.7
View File

@@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-FORWARD" 7 "March 2026" "CoreDNS" "CoreDNS Plugins"
.TH "COREDNS-FORWARD" 7 "October 2026" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
@@ -7,8 +7,8 @@
.SH "DESCRIPTION"
.PP
The \fIforward\fP plugin re-uses already opened sockets to the upstreams. It supports UDP, TCP and
DNS-over-TLS and uses in band health checking.
The \fIforward\fP plugin re-uses already opened sockets to the upstreams. It supports UDP, TCP,
DNS-over-TLS, DNS-over-HTTPS and uses in band health checking.
.PP
When it detects an error a health check is performed. This checks runs in a loop, performing each
@@ -40,8 +40,11 @@ forward FROM TO...
that expand to multiple reverse zones are not fully supported; only the first expanded zone is used.
.IP \(bu 4
\fBTO...\fP are the destination endpoints to forward to. The \fBTO\fP syntax allows you to specify
a protocol, \fB\fCtls://9.9.9.9\fR or \fB\fCdns://\fR (or no protocol) for plain DNS. The number of upstreams is
limited to 15.
a protocol, \fB\fCtls://9.9.9.9\fR, \fB\fCquic://94.140.14.14\fR, \fB\fChttps://9.9.9.9\fR (DoH defaults to \fB\fC/dns-query\fR path) or \fB\fCdns://\fR (or no protocol)
for plain DNS. The number of upstreams is limited to 15. In addition to IP addresses and files (like \fB\fC/etc/resolv.conf\fR), \fBTO\fP can also be
a hostname (e.g., \fB\fCmy-dns.svc.cluster.local\fR). Hostnames are resolved to IP addresses at startup and are treated as
absolute DNS names even without a trailing dot; resolver search domains are not applied.
See the \fB\fCresolver\fR option below.
.PP
@@ -60,9 +63,12 @@ forward FROM TO... {
force\_tcp
prefer\_udp
expire DURATION
max\_age DURATION
max\_idle\_conns INTEGER
read\_timeout DURATION
max\_fails INTEGER
max\_connect\_attempts INTEGER
doh\_method GET|POST
tls CERT KEY CA
tls\_servername NAME
policy random|round\_robin|sequential
@@ -71,6 +77,8 @@ forward FROM TO... {
next RCODE\_1 [RCODE\_2] [RCODE\_3...]
failfast\_all\_unhealthy\_upstreams
failover RCODE\_1 [RCODE\_2] [RCODE\_3...]
source\_address IP
resolver IP[:PORT] [IP[:PORT]...]
}
.fi
@@ -86,20 +94,33 @@ Requests that match none of these names will be passed through.
.IP \(bu 4
\fB\fCprefer_udp\fR, try first using UDP even when the request comes in over TCP. If response is truncated
(TC flag set in response) then do another attempt over TCP. In case if both \fB\fCforce_tcp\fR and
\fB\fCprefer_udp\fR options specified the \fB\fCforce_tcp\fR takes precedence.
\fB\fCprefer_udp\fR options specified the \fB\fCforce_tcp\fR takes precedence. These options do not change an
explicitly configured DoT, DoQ, or DoH upstream transport.
.IP \(bu 4
\fB\fCmax_fails\fR is the number of subsequent failed health checks that are needed before considering
an upstream to be down. If 0, the upstream will never be marked as down (nor health checked).
Default is 2.
.IP \(bu 4
\fB\fCmax_connect_attempts\fR caps the total number of upstream connect attempts
performed for a single incoming DNS request. Default value of 0 means no per-request
cap.
performed for a single incoming DNS request. The default cap is twice the number of
configured upstreams, allowing two complete passes when all upstreams are healthy.
Set this to 0 to disable the per-request cap.
.IP \(bu 4
\fB\fCexpire\fR \fBDURATION\fP, expire (cached) connections after this time, the default is 10s.
.IP \(bu 4
\fB\fCmax_age\fR \fBDURATION\fP, stop reusing and replace connections after this total lifetime.
The default is 0, which disables maximum connection age. A non-zero value must not be less than \fB\fCexpire\fR.
.IP \(bu 4
\fB\fCdoh_method\fR \fBGET|POST\fP, whether to use GET or POST http method for DoH requests (defaults to POST).
.IP \(bu 4
\fB\fCmax_idle_conns\fR \fBINTEGER\fP, maximum number of idle connections to cache per upstream for reuse.
Default is 0, which means unlimited.
Default is 0, which means unlimited. DoQ multiplexes streams over one cached connection per upstream.
.IP \(bu 4
\fB\fCread_timeout\fR \fBDURATION\fP, the per-query read timeout applied to each upstream when waiting for a
response. The default is 2s. Increase this if upstreams legitimately take longer than 2s to answer
(for example slow recursive resolutions that would otherwise surface as \fB\fCSERVFAIL\fR/timeouts). Note
that this timeout applies to each upstream individually, so large values reduce the time available
to retry other upstreams within a single query.
.IP \(bu 4
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP \fBCA\fP define the TLS properties for TLS connection. From 0 to 3 arguments can be
provided with the meaning as described below
@@ -117,17 +138,23 @@ The server certificate is verified with the system CAs
The server certificate is verified using the specified CA file
.RE
.IP \(bu 4
\fB\fCtls_servername\fR \fBNAME\fP allows you to set a server name in the TLS configuration; for instance 9.9.9.9
needs this to be set to \fB\fCdns.quad9.net\fR. Using TLS forwarding but not setting \fB\fCtls_servername\fR results in anyone
being able to man-in-the-middle your connection to the DNS server you are forwarding to. Because of this,
it is strongly recommended to set this value when using TLS forwarding.
.PP
Per destination endpoint TLS server name indication is possible in the form of \fB\fCtls://9.9.9.9%dns.quad9.net\fR.
CoreDNS sets the minimum TLS version to TLS 1.2 for DoT and DoH. DoQ uses TLS 1.3 as required by QUIC.
The maximum TLS version, TLS 1.2 cipher suites, and key exchange mechanisms use the Go \fB\fCcrypto/tls\fR defaults.
.IP \(bu 4
\fB\fCtls_servername\fR \fBNAME\fP allows you to set a server name in the TLS configuration; for instance 9.9.9.9
needs this to be set to \fB\fCdns.quad9.net\fR. It is strongly recommended when using DoT, DoQ, or DoH with
an IP address whose certificate identifies a DNS name instead of that IP address.
.PP
Per destination endpoint TLS server name indication is possible in the form of \fB\fCtls://9.9.9.9%dns.quad9.net\fR
or \fB\fCquic://9.9.9.9%dns.quad9.net\fR.
\fB\fCtls_servername\fR must not be specified when using per destination endpoint TLS server name indication
as it would introduce clash between the server name indication spectifications. If destination endpoint
as it would introduce a clash between server name indication specifications. If destination endpoint
is to be reached via a port other than 853 then the port must be appended to the end of the destination
endpoint specifier. In case of port 10853, the above string would be: \fB\fCtls://9.9.9.9%dns.quad9.net:10853\fR.
@@ -166,20 +193,34 @@ As an upper bound for \fBMAX\fP, consider that each concurrent query will use ab
.IP \(bu 4
\fB\fCnext\fR If the \fB\fCRCODE\fR (i.e. \fB\fCNXDOMAIN\fR) is returned by the remote then execute the next plugin. If no next plugin is defined, or the next plugin is not a \fB\fCforward\fR plugin, this setting is ignored
.IP \(bu 4
\fB\fCnext_on_nodata\fR If \fB\fCNOERROR\fR is returned by the remote, but an empty answer section (\fB\fCNODATA\fR) was provided, execute the next \fB\fCforward\fR plugin, if configured.
.IP \(bu 4
\fB\fCfailfast_all_unhealthy_upstreams\fR - determines the handling of requests when all upstream servers are unhealthy and unresponsive to health checks. Enabling this option will immediately return SERVFAIL responses for all requests. By default, requests are sent to a random upstream.
.IP \(bu 4
\fB\fCfailover\fR - By default when a DNS lookup fails to return a DNS response (e.g. timeout), \fIforward\fP will attempt a lookup on the next upstream server. The \fB\fCfailover\fR option will make \fIforward\fP do the same for any response with a response code matching an \fB\fCRCODE\fR ( e.g. \fB\fCSERVFAIL\fR、\fB\fCREFUSED\fR). \fB\fCNOERROR\fR cannot be used. If all upstreams have been tried, the response from the last attempt is returned.
.IP \(bu 4
\fB\fCsource_address\fR \fBIP\fP - set the address to use for all outgoing requests as source address (also health check query). This works reliably when upstream servers are reachable from that address. However, if upstream servers belong to different networks, care must be taken. The selected source address may not be valid for all upstreams, and responses may fail if return routing is not properly configured. In such cases, make sure that upstream servers have a route back to the configured source address.
.IP \(bu 4
\fB\fCresolver\fR \fBIP[:PORT] [IP[:PORT]...]\fP specifies one or more DNS resolver addresses used to resolve hostname-based \fBTO\fP endpoints at startup. If not specified, the system resolver (\fB\fC/etc/resolv.conf\fR) is used. Each address is either a bare IP (IPv4 or IPv6, port 53 assumed) or \fB\fCIP:port\fR. Multiple addresses can be specified for redundancy.
.PP
Also note the TLS config is "global" for the whole forwarding proxy if you need a different
\fB\fCtls_servername\fR for different upstreams you're out of luck.
The client certificate, key, and CA configuration is global for one \fB\fCforward\fR stanza. For DoT and DoQ,
use the \fB\fC%servername\fR endpoint form when upstreams in the same stanza require different TLS server names.
.PP
On each endpoint, the timeouts for communication are set as follows:
.IP \(bu 4
The dial timeout by default is 30s, and can decrease automatically down to 1s based on early results.
The DNS and DoT dial timeout defaults to 30s and can decrease automatically down to 1s based on early results.
The DoQ handshake timeout is 5s.
.IP \(bu 4
DoT connection setup (TCP dial plus TLS handshake) is additionally bounded by the remaining
5s forwarding retry window, or an earlier request deadline. When retries are enabled, each
setup attempt is limited to half of the window available at the start of forwarding (at most
2.5s), so a stalled handshake leaves time to try a fresh connection. With \fB\fCmax_connect_attempts 1\fR,
setup may use the full remaining window. Failed handshakes close the connection; successful
connections remain reusable. These setup limits do not change the DNS exchange read timeout.
.IP \(bu 4
The read timeout is static at 2s.
@@ -215,7 +256,7 @@ number of concurrent queries were at maximum.
.PP
Where \fB\fCto\fR is one of the upstream servers (\fBTO\fP from the config), \fB\fCrcode\fR is the returned RCODE
from the upstream, \fB\fCproto\fR is the transport protocol like \fB\fCudp\fR, \fB\fCtcp\fR, \fB\fCtcp-tls\fR.
from the upstream, \fB\fCproto\fR is the transport protocol like \fB\fCudp\fR, \fB\fCtcp\fR, \fB\fCtcp-tls\fR, \fB\fCquic\fR, \fB\fChttps\fR.
.PP
The following metrics have recently been deprecated:
@@ -356,6 +397,45 @@ service with health checks.
.fi
.RE
.PP
The following example uses DNS-over-QUIC (DoQ). DoQ uses UDP port 853 by default and multiplexes
concurrent queries over separate streams on one QUIC connection. The \fB\fCforward\fR plugin's single-message
exchange path does not support AXFR or IXFR over DoQ; those requests return \fB\fCNOTIMP\fR.
.PP
.RS
.nf
\&. {
forward . quic://94.140.14.14 {
tls\_servername dns.adguard\-dns.com
health\_check 5s
}
cache 30
}
.fi
.RE
.PP
The same configuration but using DNS-over-HTTPS (DoH) protocol. Note that the implementation uses the default \fB\fC/dns-query\fR
path (custom paths are not supported).
.PP
.RS
.nf
\&. {
forward . https://9.9.9.9 {
tls\_servername dns.quad9.net
health\_check 5s
}
cache 30
}
.fi
.RE
.PP
Or configure other domain name for health check requests
@@ -456,8 +536,32 @@ In the following example, if the response from \fB\fC1.2.3.4\fR is \fB\fCSERVFAI
.fi
.RE
.PP
Forward to an upstream identified by hostname, using a specific resolver to look it up:
.PP
.RS
.nf
\&. {
forward . dns.example.local {
resolver 10.0.0.1
}
}
.fi
.RE
.SH "SEE ALSO"
.PP
RFC 7858
\[la]https://tools.ietf.org/html/rfc7858\[ra] for DNS over TLS.
\[la]https://www.rfc-editor.org/info/rfc7858/\[ra] for DNS over TLS.
.PP
RFC 8484
\[la]https://www.rfc-editor.org/info/rfc8484/\[ra] for DNS over HTTPS.
.PP
RFC 9250
\[la]https://www.rfc-editor.org/info/rfc9250/\[ra] for DNS over QUIC.