Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2026-04-08 21:15:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): regenerate man pages (#7971)

Browse Source
This commit is contained in:
Ville Vesilehto
2026-03-27 05:35:09 +02:00
committed by GitHub
parent 49b18b8af6
commit 0132ad86b5
60 changed files with 2110 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

191
man/coredns-forward.7
View File

@@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-FORWARD" 7 "March 2021" "CoreDNS" "CoreDNS Plugins"
.TH "COREDNS-FORWARD" 7 "March 2026" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
@@ -22,9 +22,6 @@ is taken as a healthy upstream. The health check uses the same protocol as speci
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:
@@ -39,7 +36,8 @@ forward FROM TO...
.RE
.IP \(bu 4
\fBFROM\fP is the base domain to match for the request to be forwarded.
\fBFROM\fP is the base domain to match for the request to be forwarded. Domains using CIDR notation
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
@@ -62,12 +60,17 @@ forward FROM TO... {
force\_tcp
prefer\_udp
expire DURATION
max\_idle\_conns INTEGER
max\_fails INTEGER
max\_connect\_attempts INTEGER
tls CERT KEY CA
tls\_servername NAME
policy random|round\_robin|sequential
health\_check DURATION [no\_rec]
health\_check DURATION [no\_rec] [domain FQDN]
max\_concurrent MAX
next RCODE\_1 [RCODE\_2] [RCODE\_3...]
failfast\_all\_unhealthy\_upstreams
failover RCODE\_1 [RCODE\_2] [RCODE\_3...]
}
.fi
@@ -89,8 +92,15 @@ Requests that match none of these names will be passed through.
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.
.IP \(bu 4
\fB\fCexpire\fR \fBDURATION\fP, expire (cached) connections after this time, the default is 10s.
.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.
.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
@@ -109,9 +119,18 @@ 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.
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.
\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
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.
.IP \(bu 4
\fB\fCpolicy\fR specifies the policy to use for selecting upstream servers. The default is \fB\fCrandom\fR.
@@ -133,6 +152,9 @@ but they have to use the same \fB\fCtls_servername\fR. E.g. mixing 9.9.9.9 (Quad
.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.
.IP \(en 4
\fB\fCdomain FQDN\fR - set the domain name used for health checks to \fBFQDN\fP.
If not configured, the domain name used for health checks is \fB\fC.\fR.
.RE
.IP \(bu 4
@@ -141,17 +163,23 @@ raise the number of concurrent queries above the \fBMAX\fP will result in a REFU
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.
.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\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.
.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.
\fB\fCtls_servername\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.
The dial timeout by default is 30s, and can decrease automatically down to 1s based on early results.
.IP \(bu 4
The read timeout is static at 2s.
@@ -170,28 +198,35 @@ plugin is also enabled:
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, rcode, type}\fR - duration per upstream, RCODE, type
.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,
\fB\fCcoredns_forward_healthcheck_broken_total{}\fR - count 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
\fB\fCcoredns_forward_max_concurrent_rejects_total{}\fR - count 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.
\fB\fCcoredns_proxy_request_duration_seconds{proxy_name="forward", to, rcode}\fR - histogram per upstream, RCODE
.IP \(bu 4
\fB\fCcoredns_forward_conn_cache_misses_total{to, proto}\fR - counter of connection cache misses per upstream and protocol.
\fB\fCcoredns_proxy_healthcheck_failures_total{proxy_name="forward", to, rcode}\fR- count of failed health checks per upstream.
.IP \(bu 4
\fB\fCcoredns_proxy_conn_cache_hits_total{proxy_name="forward", to, proto}\fR- count of connection cache hits per upstream and protocol.
.IP \(bu 4
\fB\fCcoredns_proxy_conn_cache_misses_total{proxy_name="forward", to, proto}\fR - count of connection cache misses per upstream and protocol.
.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.
.PP
The following metrics have recently been deprecated:
* \fB\fCcoredns_forward_healthcheck_failures_total{to, rcode}\fR
* Can be replaced with \fB\fCcoredns_proxy_healthcheck_failures_total{proxy_name="forward", to, rcode}\fR
* \fB\fCcoredns_forward_requests_total{to}\fR
* Can be replaced with \fB\fCsum(coredns_proxy_request_duration_seconds_count{proxy_name="forward", to})\fR
* \fB\fCcoredns_forward_responses_total{to, rcode}\fR
* Can be replaced with \fB\fCcoredns_proxy_request_duration_seconds_count{proxy_name="forward", to, rcode}\fR
* \fB\fCcoredns_forward_request_duration_seconds{to, rcode}\fR
* Can be replaced with \fB\fCcoredns_proxy_request_duration_seconds{proxy_name="forward", to, rcode}\fR
.SH "EXAMPLES"
.PP
@@ -208,6 +243,52 @@ example.org {
.fi
.RE
.PP
Send all requests within \fB\fClab.example.local.\fR to \fB\fC10.20.0.1\fR, all requests within \fB\fCexample.local.\fR (and not in
\fB\fClab.example.local.\fR) to \fB\fC10.0.0.1\fR, all others requests to the servers defined in \fB\fC/etc/resolv.conf\fR, and
caches results. Note that a CoreDNS server configured with multiple \fIforward\fP plugins in a server block will evaluate those
forward plugins in the order they are listed when serving a request. Therefore, subdomains should be
placed before parent domains otherwise subdomain requests will be forwarded to the parent domain's upstream.
Accordingly, in this example \fB\fClab.example.local\fR is before \fB\fCexample.local\fR, and \fB\fCexample.local\fR is before \fB\fC.\fR.
.PP
.RS
.nf
\&. {
cache
forward lab.example.local 10.20.0.1
forward example.local 10.0.0.1
forward . /etc/resolv.conf
}
.fi
.RE
.PP
The example above is almost equivalent to the following example, except that example below defines three separate plugin
chains (and thus 3 separate instances of \fIcache\fP).
.PP
.RS
.nf
lab.example.local {
cache
forward . 10.20.0.1
}
example.local {
cache
forward . 10.0.0.1
}
\&. {
cache
forward . /etc/resolv.conf
}
.fi
.RE
.PP
Load balance all requests between three resolvers, one of which has a IPv6 address.
@@ -275,6 +356,24 @@ service with health checks.
.fi
.RE
.PP
Or configure other domain name for health check requests
.PP
.RS
.nf
\&. {
forward . tls://9.9.9.9 {
tls\_servername dns.quad9.net
health\_check 5s domain example.org
}
cache 30
}
.fi
.RE
.PP
Or with multiple upstreams from the same provider
@@ -305,13 +404,13 @@ Or when you have multiple DoT upstreams with different \fB\fCtls_servername\fRs,
}
\&.:5301 {
forward . 8.8.8.8 8.8.4.4 {
forward . tls://8.8.8.8 tls://8.8.4.4 {
tls\_servername dns.google
}
}
\&.:5302 {
forward . 1.1.1.1 1.0.0.1 {
forward . tls://1.1.1.1 tls://1.0.0.1 {
tls\_servername cloudflare\-dns.com
}
}
@@ -319,6 +418,44 @@ Or when you have multiple DoT upstreams with different \fB\fCtls_servername\fRs,
.fi
.RE
.PP
The following would try 1.2.3.4 first. If the response is \fB\fCNXDOMAIN\fR, try 5.6.7.8. If the response from 5.6.7.8 is \fB\fCNXDOMAIN\fR, try 9.0.1.2.
.PP
.RS
.nf
\&. {
forward . 1.2.3.4 {
next NXDOMAIN
}
forward . 5.6.7.8 {
next NXDOMAIN
}
forward . 9.0.1.2 {
}
}
.fi
.RE
.PP
In the following example, if the response from \fB\fC1.2.3.4\fR is \fB\fCSERVFAIL\fR or \fB\fCREFUSED\fR, it will try \fB\fC5.6.7.8\fR. If the response from \fB\fC5.6.7.8\fR is \fB\fCSERVFAIL\fR or \fB\fCREFUSED\fR, it will try \fB\fC9.0.1.2\fR.
.PP
.RS
.nf
\&. {
forward . 1.2.3.4 5.6.7.8 9.0.1.2 {
policy sequential
failover SERVFAIL REFUSED
}
}
.fi
.RE
.SH "SEE ALSO"
.PP
RFC 7858