mirror of
https://github.com/coredns/coredns.git
synced 2025-10-27 16:24:19 -04:00
297 lines
8.9 KiB
Groff
297 lines
8.9 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-FORWARD" 7 "September 2020" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIforward\fP - facilitates proxying DNS messages to upstream resolvers.
|
|
|
|
.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.
|
|
|
|
.PP
|
|
When it detects an error a health check is performed. This checks runs in a loop, performing each
|
|
check at a \fI0.5s\fP interval for as long as the upstream reports unhealthy. Once healthy we stop
|
|
health checking (until the next error). The health checks use a recursive DNS query (\fB\fC. IN NS\fR)
|
|
to get upstream health. Any response that is not a network error (REFUSED, NOTIMPL, SERVFAIL, etc)
|
|
is taken as a healthy upstream. The health check uses the same protocol as specified in \fBTO\fP. If
|
|
\fB\fCmax_fails\fR is set to 0, no checking is performed and upstreams will always be considered healthy.
|
|
|
|
.PP
|
|
When \fIall\fP upstreams are down it assumes health checking as a mechanism has failed and will try to
|
|
connect to a random upstream (which may or may not work).
|
|
|
|
.PP
|
|
This plugin can only be used once per Server Block.
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
In its most basic form, a simple forwarder uses this syntax:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
forward FROM TO...
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBFROM\fP is the base domain to match for the request to be forwarded.
|
|
.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.
|
|
|
|
|
|
.PP
|
|
Multiple upstreams are randomized (see \fB\fCpolicy\fR) on first use. When a healthy proxy returns an error
|
|
during the exchange the next upstream in the list is tried.
|
|
|
|
.PP
|
|
Extra knobs are available with an expanded syntax:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
forward FROM TO... {
|
|
except IGNORED\_NAMES...
|
|
force\_tcp
|
|
prefer\_udp
|
|
expire DURATION
|
|
max\_fails INTEGER
|
|
tls CERT KEY CA
|
|
tls\_servername NAME
|
|
policy random|round\_robin|sequential
|
|
health\_check DURATION [no\_rec]
|
|
max\_concurrent MAX
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBFROM\fP and \fBTO...\fP as above.
|
|
.IP \(bu 4
|
|
\fBIGNORED_NAMES\fP in \fB\fCexcept\fR is a space-separated list of domains to exclude from forwarding.
|
|
Requests that match none of these names will be passed through.
|
|
.IP \(bu 4
|
|
\fB\fCforce_tcp\fR, use TCP even when the request comes in over UDP.
|
|
.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.
|
|
.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\fCexpire\fR \fBDURATION\fP, expire (cached) connections after this time, the default is 10s.
|
|
.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
|
|
|
|
.RS
|
|
.IP \(en 4
|
|
\fB\fCtls\fR - no client authentication is used, and the system CAs are used to verify the server certificate
|
|
.IP \(en 4
|
|
\fB\fCtls\fR \fBCA\fP - no client authentication is used, and the file CA is used to verify the server certificate
|
|
.IP \(en 4
|
|
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP - client authentication is used with the specified cert/key pair.
|
|
The server certificate is verified with the system CAs
|
|
.IP \(en 4
|
|
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP \fBCA\fP - client authentication is used with the specified cert/key pair.
|
|
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. Multiple upstreams are still allowed in this scenario,
|
|
but they have to use the same \fB\fCtls_servername\fR. E.g. mixing 9.9.9.9 (QuadDNS) with 1.1.1.1
|
|
(Cloudflare) will not work.
|
|
.IP \(bu 4
|
|
\fB\fCpolicy\fR specifies the policy to use for selecting upstream servers. The default is \fB\fCrandom\fR.
|
|
|
|
.RS
|
|
.IP \(en 4
|
|
\fB\fCrandom\fR is a policy that implements random upstream selection.
|
|
.IP \(en 4
|
|
\fB\fCround_robin\fR is a policy that selects hosts based on round robin ordering.
|
|
.IP \(en 4
|
|
\fB\fCsequential\fR is a policy that selects hosts based on sequential ordering.
|
|
|
|
.RE
|
|
.IP \(bu 4
|
|
\fB\fChealth_check\fR configure the behaviour of health checking of the upstream servers
|
|
|
|
.RS
|
|
.IP \(en 4
|
|
\fB\fC<duration>\fR - use a different duration for health checking, the default duration is 0.5s.
|
|
.IP \(en 4
|
|
\fB\fCno_rec\fR - optional argument that sets the RecursionDesired-flag of the dns-query used in health checking to \fB\fCfalse\fR.
|
|
The flag is default \fB\fCtrue\fR.
|
|
|
|
.RE
|
|
.IP \(bu 4
|
|
\fB\fCmax_concurrent\fR \fBMAX\fP will limit the number of concurrent queries to \fBMAX\fP. Any new query that would
|
|
raise the number of concurrent queries above the \fBMAX\fP will result in a SERVFAIL response. This
|
|
response does not count as a health failure. When choosing a value for \fBMAX\fP, pick a number
|
|
at least greater than the expected \fIupstream query rate\fP * \fIlatency\fP of the upstream servers.
|
|
As an upper bound for \fBMAX\fP, consider that each concurrent query will use about 2kb of memory.
|
|
|
|
|
|
.PP
|
|
Also note the TLS config is "global" for the whole forwarding proxy if you need a different
|
|
\fB\fCtls-name\fR for different upstreams you're out of luck.
|
|
|
|
.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 100ms based on early results.
|
|
.IP \(bu 4
|
|
The read timeout is static at 2s.
|
|
|
|
|
|
.SH "METRICS"
|
|
.PP
|
|
If monitoring is enabled (via the \fIprometheus\fP plugin) then the following metric are exported:
|
|
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_forward_requests_total{to}\fR - query count per upstream.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_forward_responses_total{to}\fR - Counter of responses received per upstream.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_forward_request_duration_seconds{to}\fR - duration per upstream interaction.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_forward_responses_total{to, rcode}\fR - count of RCODEs per upstream.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_forward_healthcheck_failures_total{to}\fR - number of failed health checks per upstream.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_forward_healthcheck_broken_total{}\fR - counter of when all upstreams are unhealthy,
|
|
and we are randomly (this always uses the \fB\fCrandom\fR policy) spraying to an upstream.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_forward_max_concurrent_rejects_total{}\fR - counter of the number of queries rejected because the
|
|
number of concurrent queries were at maximum.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_forward_conn_cache_hits_total{to, proto}\fR - counter of connection cache hits per upstream and protocol.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_forward_conn_cache_misses_total{to, proto}\fR - counter of connection cache misses per upstream and protocol.
|
|
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.
|
|
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Proxy all requests within \fB\fCexample.org.\fR to a nameserver running on a different port:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
example.org {
|
|
forward . 127.0.0.1:9005
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Load balance all requests between three resolvers, one of which has a IPv6 address.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
forward . 10.0.0.10:53 10.0.0.11:1053 [2003::1]:53
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Forward everything except requests to \fB\fCexample.org\fR
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
forward . 10.0.0.10:1234 {
|
|
except example.org
|
|
}
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Proxy everything except \fB\fCexample.org\fR using the host's \fB\fCresolv.conf\fR's nameservers:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
forward . /etc/resolv.conf {
|
|
except example.org
|
|
}
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Proxy all requests to 9.9.9.9 using the DNS-over-TLS protocol, and cache every answer for up to 30
|
|
seconds. Note the \fB\fCtls_servername\fR is mandatory if you want a working setup, as 9.9.9.9 can't be
|
|
used in the TLS negotiation. Also set the health check duration to 5s to not completely swamp the
|
|
service with health checks.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
forward . tls://9.9.9.9 {
|
|
tls\_servername dns.quad9.net
|
|
health\_check 5s
|
|
}
|
|
cache 30
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Or with multiple upstreams from the same provider
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
forward . tls://1.1.1.1 tls://1.0.0.1 {
|
|
tls\_servername cloudflare\-dns.com
|
|
health\_check 5s
|
|
}
|
|
cache 30
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SH "BUGS"
|
|
.PP
|
|
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.
|
|
|
|
.SH "ALSO SEE"
|
|
.PP
|
|
RFC 7858
|
|
\[la]https://tools.ietf.org/html/rfc7858\[ra] for DNS over TLS.
|
|
|