Run go genenerate (#1506)
Forward still wasn't right; run make -f Makefile.doc, as well for good measure.
This commit is contained in:
Miek Gieben
GitHub
parent
74a9d28f1b
commit
864f502356
3 changed files with 227 additions and 3 deletions
|
|
@ -17,6 +17,7 @@ import (
|
|||
_ "github.com/coredns/coredns/plugin/etcd"
|
||||
_ "github.com/coredns/coredns/plugin/federation"
|
||||
_ "github.com/coredns/coredns/plugin/file"
|
||||
_ "github.com/coredns/coredns/plugin/forward"
|
||||
_ "github.com/coredns/coredns/plugin/health"
|
||||
_ "github.com/coredns/coredns/plugin/hosts"
|
||||
_ "github.com/coredns/coredns/plugin/kubernetes"
|
||||
|
|
@ -36,7 +37,6 @@ import (
|
|||
_ "github.com/coredns/coredns/plugin/tls"
|
||||
_ "github.com/coredns/coredns/plugin/trace"
|
||||
_ "github.com/coredns/coredns/plugin/whoami"
|
||||
_ "github.com/coredns/forward"
|
||||
_ "github.com/mholt/caddy/onevent"
|
||||
_ "github.com/mholt/caddy/startupshutdown"
|
||||
)
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-ETCD" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.TH "COREDNS\-ETCD" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIetcd\fR \- enables reading zone data from an etcd instance\.
|
||||
|
|
@ -58,7 +58,7 @@ etcd [ZONES\.\.\.] {
|
|||
\fBPATH\fR the path inside etcd\. Defaults to "/skydns"\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBENDPOINT\fR the etcd endpoints\. Defaults to "http://localhost:2397"\.
|
||||
\fBENDPOINT\fR the etcd endpoints\. Defaults to "http://localhost:2379"\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBupstream\fR upstream resolvers to be used resolve external names found in etcd (think CNAMEs) pointing to external names\. If you want CoreDNS to act as a proxy for clients, you\'ll need to add the proxy plugin\. \fBADDRESS\fR can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\.
|
||||
|
|
|
|||
224
man/coredns-forward.7
Normal file
224
man/coredns-forward.7
Normal file
|
|
@ -0,0 +1,224 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-FORWARD" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIforward\fR facilitates proxying DNS messages to upstream resolvers\.
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
The \fIforward\fR plugin is generally faster (~30+%) than \fIproxy\fR as it re\-uses already opened sockets to the upstreams\. It supports UDP, TCP and DNS\-over\-TLS and uses inband health checking that is enabled by default\. When \fIall\fR upstreams are down it assumes healtchecking as a mechanism has failed and will try to connect to a random upstream (which may or may not work)\.
|
||||
.
|
||||
.SH "SYNTAX"
|
||||
In its most basic form, a simple forwarder uses this syntax:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
forward FROM TO\.\.\.
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBFROM\fR is the base domain to match for the request to be forwarded\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBTO\.\.\.\fR are the destination endpoints to forward to\. The \fBTO\fR syntax allows you to specify a protocol, \fBtls://9\.9\.9\.9\fR or \fBdns://\fR for plain DNS\. The number of upstreams is limited to 15\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
The health checks are done every \fI0\.5s\fR\. After \fItwo\fR failed checks the upstream is considered unhealthy\. The health checks use a recursive DNS query (\fB\. IN NS\fR) to get upstream health\. Any response that is not an error (REFUSED, NOTIMPL, SERVFAIL, etc) is taken as a healthy upstream\. The health check uses the same protocol as specific in the \fBTO\fR\. On startup each upstream is marked unhealthy until it passes a health check\. A 0 duration will disable any health checks\.
|
||||
.
|
||||
.P
|
||||
Multiple upstreams are randomized (default policy) on first use\. When a healthy proxy returns an error during the exchange the next upstream in the list is tried\.
|
||||
.
|
||||
.P
|
||||
Extra knobs are available with an expanded syntax:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
forward FROM TO\.\.\. {
|
||||
except IGNORED_NAMES\.\.\.
|
||||
force_tcp
|
||||
health_check DURATION
|
||||
expire DURATION
|
||||
max_fails INTEGER
|
||||
tls CERT KEY CA
|
||||
tls_servername NAME
|
||||
policy random|round_robin
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBFROM\fR and \fBTO\.\.\.\fR as above\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBIGNORED_NAMES\fR in \fBexcept\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
|
||||
\fBforce_tcp\fR, use TCP even when the request comes in over UDP\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBhealth_checks\fR, use a different \fBDURATION\fR for health checking, the default duration is 0\.5s\. A value of 0 disables the health checks completely\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBmax_fails\fR is the number of subsequent failed health checks that are needed before considering a backend to be down\. If 0, the backend will never be marked as down\. Default is 2\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBexpire\fR \fBDURATION\fR, expire (cached) connections after this time, the default is 10s\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCA\fR define the TLS properties for TLS; if you leave this out the system\'s configuration will be used\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls_servername\fR \fBNAME\fR allows you to set a server name in the TLS configuration; for instance 9\.9\.9\.9 needs this to be set to \fBdns\.quad9\.net\fR\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBpolicy\fR specifies the policy to use for selecting upstream servers\. The default is \fBrandom\fR\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
The upstream selection is done via random (default policy) selection\. If the socket for this client isn\'t known \fIforward\fR will randomly choose one\. If this turns out to be unhealthy, the next one is tried\. If \fIall\fR hosts are down, we assume health checking is broken and select a \fIrandom\fR upstream to try\.
|
||||
.
|
||||
.P
|
||||
Also note the TLS config is "global" for the whole forwarding proxy if you need a different \fBtls\-name\fR for different upstreams you\'re out of luck\.
|
||||
.
|
||||
.SH "METRICS"
|
||||
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metric are exported:
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_forward_request_duration_seconds{to}\fR \- duration per upstream interaction\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_forward_request_count_total{to}\fR \- query count per upstream\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_forward_response_rcode_total{to, rcode}\fR \- count of RCODEs per upstream\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_forward_healthcheck_failure_count_total{to}\fR \- number of failed health checks per upstream\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_forward_healthcheck_broken_count_total{}\fR \- counter of when all upstreams are unhealthy, and we are randomly spraying to a target\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_forward_socket_count_total{to}\fR \- number of cached sockets per upstream\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Where \fBto\fR is one of the upstream servers (\fBTO\fR from the config), \fBproto\fR is the protocol used by the incoming query ("tcp" or "udp"), and family the transport family ("1" for IPv4, and "2" for IPv6)\.
|
||||
.
|
||||
.SH "EXAMPLES"
|
||||
Proxy all requests within example\.org\. to a nameserver running on a different port:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
example\.org {
|
||||
forward \. 127\.0\.0\.1:9005
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Load balance all requests between three resolvers, one of which has a IPv6 address\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
forward \. 10\.0\.0\.10:53 10\.0\.0\.11:1053 [2003::1]:53
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Forward everything except requests to \fBexample\.org\fR
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
forward \. 10\.0\.0\.10:1234 {
|
||||
except example\.org
|
||||
}
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Proxy everything except \fBexample\.org\fR using the host\'s \fBresolv\.conf\fR\'s nameservers:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
forward \. /etc/resolv\.conf {
|
||||
except example\.org
|
||||
}
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Forward to a IPv6 host:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
forward \. [::1]:1053
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Proxy all requests to 9\.9\.9\.9 using the DNS\-over\-TLS protocol, and cache every answer for up to 30 seconds\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
forward \. tls://9\.9\.9\.9 {
|
||||
tls_servername dns\.quad9\.net
|
||||
health_check 5s
|
||||
}
|
||||
cache 30
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "BUGS"
|
||||
The TLS config is global for the whole forwarding proxy if you need a different \fBtls\-name\fR for different upstreams you\'re out of luck\.
|
||||
.
|
||||
.SH "ALSO SEE"
|
||||
RFC 7858 \fIhttps://tools\.ietf\.org/html/rfc7858\fR for DNS over TLS\.
|
||||
Loading…
Add table
Reference in a new issue