\fIetcd\fR \- enables reading zone data from an etcd instance\.
\fIetcd\fR \- enables reading zone data from an etcd instance\.
...
@@ -185,5 +185,56 @@ reverse\.skydns\.local\.
...
@@ -185,5 +185,56 @@ reverse\.skydns\.local\.
.
.
.IP "" 0
.IP "" 0
.
.
.SS "ZONE NAME AS A RECORD"
The zone name itself can be used A record\. This behavior can be achieved by writing special entries to the ETCD path of your zone\. If your zone is named \fBskydns\.local\fR for example, you can create an \fBA\fR record for this zone as follows:
If you query the zone name itself, you will receive the created \fBA\fR record:
.
.IP "" 4
.
.nf
% dig +short skydns\.local @localhost
1\.1\.1\.1
.
.fi
.
.IP "" 0
.
.P
If you would like to use DNS RR for the zone name, you can set the following: ~~~ % curl \-XPUT http://127\.0\.0\.1:2379/v2/keys/skydns/local/skydns/dns/apex/x1 \-d value=\'{"host":"1\.1\.1\.1","ttl":"60"}\' % curl \-XPUT http://127\.0\.0\.1:2379/v2/keys/skydns/local/skydns/dns/apex/x2 \-d value=\'{"host":"1\.1\.1\.2","ttl":"60"}\' ~~~
.
.P
If you query the zone name now, you will get the following response:
.
.IP "" 4
.
.nf
dig +short skydns\.local @localhost
1\.1\.1\.1
1\.1\.1\.2
.
.fi
.
.IP "" 0
.
.P
If you would like to use \fBAAAA\fR records for the zone name too, you can set the following: ~~~ % curl \-XPUT http://127\.0\.0\.1:2379/v2/keys/skydns/local/skydns/dns/apex/x3 \-d value=\'{"host":"2003::8:1","ttl":"60"}\' % curl \-XPUT http://127\.0\.0\.1:2379/v2/keys/skydns/local/skydns/dns/apex/x4 \-d value=\'{"host":"2003::8:2","ttl":"60"}\' ~~~
.
.P
If you query the zone name now for \fBAAAA\fR now, you will get the following response: ~~~ sh dig +short skydns\.local AAAA @localhost 2003::8:1 2003::8:2 ~~~
\fIforward\fR \- facilitates proxying DNS messages to upstream resolvers\.
\fIforward\fR \- facilitates proxying DNS messages to upstream resolvers\.
...
@@ -18,6 +18,9 @@ When \fIall\fR upstreams are down it assumes health checking as a mechanism has
...
@@ -18,6 +18,9 @@ When \fIall\fR upstreams are down it assumes health checking as a mechanism has
.P
.P
This plugin can only be used once per Server Block\.
This plugin can only be used once per Server Block\.
.
.
.P
How does \fIforward\fR relate to \fIproxy\fR? This plugin is the "new" version of \fIproxy\fR and is faster because it re\-uses connections to the upstreams\. It also does in\-band health checks \- using DNS instead of HTTP\. Since it is newer it has a little less (production) mileage on it\.
.
.SH "SYNTAX"
.SH "SYNTAX"
In its most basic form, a simple forwarder uses this syntax:
In its most basic form, a simple forwarder uses this syntax:
.
.
...
@@ -138,7 +141,7 @@ If monitoring is enabled (via the \fIprometheus\fR directive) then the following
...
@@ -138,7 +141,7 @@ If monitoring is enabled (via the \fIprometheus\fR directive) then the following
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)\.
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"
.SH "EXAMPLES"
Proxy all requests within example\.org\. to a nameserver running on a different port:
Proxy all requests within \fBexample\.org\.\fR to a nameserver running on a different port:
.
.
.IP "" 4
.IP "" 4
.
.
...
@@ -221,7 +224,7 @@ Proxy all requests to 9\.9\.9\.9 using the DNS\-over\-TLS protocol, and cache ev
...
@@ -221,7 +224,7 @@ Proxy all requests to 9\.9\.9\.9 using the DNS\-over\-TLS protocol, and cache ev
.IP "" 0
.IP "" 0
.
.
.SH "BUGS"
.SH "BUGS"
The TLS config is global for the whole forwarding proxy if you need a different \fBtls_serveraame\fR for different upstreams you\'re out of luck\.
The TLS config is global for the whole forwarding proxy if you need a different \fBtls_servername\fR for different upstreams you\'re out of luck\.
.
.
.SH "ALSO SEE"
.SH "ALSO SEE"
RFC 7858 \fIhttps://tools\.ietf\.org/html/rfc7858\fR for DNS over TLS\.
RFC 7858 \fIhttps://tools\.ietf\.org/html/rfc7858\fR for DNS over TLS\.
Note that if you format this in one server block you will get an error on startup, that the second server can\'t setup the health plugin (on the same port)\.
.
.IP "" 4
.
.nf
com net {
whoami
erratic
health :8080
}
.
.fi
.
.IP "" 0
.
.SH "PLUGINS"
.SH "PLUGINS"
Any plugin that implements the Healther interface will be used to report health\.
Any plugin that implements the Healther interface will be used to report health\.
.
.
...
@@ -106,4 +123,6 @@ Set a lameduck duration of 1 second:
...
@@ -106,4 +123,6 @@ Set a lameduck duration of 1 second:
.fi
.fi
.
.
.IP "" 0
.IP "" 0
.
.SH "BUGS"
When reloading, the Health handler is stopped before the new server instance is started\. If that new server fails to start, then the initial server instance is still available and DNS queries still served, but Health handler stays down\. Health will not reply HTTP request until a successful reload or a complete restart of CoreDNS\.
\fIkubernetes\fR \- enables the reading zone data from a Kubernetes cluster\.
\fIkubernetes\fR \- enables the reading zone data from a Kubernetes cluster\.
...
@@ -43,6 +43,7 @@ kubernetes [ZONES\.\.\.] {
...
@@ -43,6 +43,7 @@ kubernetes [ZONES\.\.\.] {
endpoint_pod_names
endpoint_pod_names
upstream [ADDRESS\.\.\.]
upstream [ADDRESS\.\.\.]
ttl TTL
ttl TTL
transfer to ADDRESS\.\.\.
fallthrough [ZONES\.\.\.]
fallthrough [ZONES\.\.\.]
}
}
.
.
...
@@ -93,8 +94,14 @@ kubernetes [ZONES\.\.\.] {
...
@@ -93,8 +94,14 @@ kubernetes [ZONES\.\.\.] {
\fBnoendpoints\fR will turn off the serving of endpoint records by disabling the watch on endpoints\. All endpoint queries and headless service queries will result in an NXDOMAIN\.
\fBnoendpoints\fR will turn off the serving of endpoint records by disabling the watch on endpoints\. All endpoint queries and headless service queries will result in an NXDOMAIN\.
.
.
.IP "\(bu" 4
.IP "\(bu" 4
\fBtransfer\fR enables zone transfers\. It may be specified multiples times\. \fBTo\fR signals the direction (only \fBto\fR is alllow)\. \fBADDRESS\fR must be denoted in CIDR notation (127\.0\.0\.1/32 etc\.) or just as plain addresses\. The special wildcard \fB*\fR means: the entire internet\. Sending DNS notifies is not supported\.
.
.IP "\(bu" 4
\fBfallthrough\fR \fB[ZONES\.\.\.]\fR If a query for a record in the zones for which the plugin is authoritative results in NXDOMAIN, normally that is what the response will be\. However, if you specify this option, the query will instead be passed on down the plugin chain, which can include another plugin to handle the query\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
\fBfallthrough\fR \fB[ZONES\.\.\.]\fR If a query for a record in the zones for which the plugin is authoritative results in NXDOMAIN, normally that is what the response will be\. However, if you specify this option, the query will instead be passed on down the plugin chain, which can include another plugin to handle the query\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.
.IP "\(bu" 4
\fBignore empty_service\fR return NXDOMAIN for services without any ready endpoint addresses (e\.g\. ready pods)\. This allows the querying pod to continue searching for the service in the search path\. The search path could, for example, include another kubernetes cluster\.
@@ -13,6 +13,9 @@ With \fIprometheus\fR you export metrics from CoreDNS and any plugin that has th
...
@@ -13,6 +13,9 @@ With \fIprometheus\fR you export metrics from CoreDNS and any plugin that has th
\fBcoredns_build_info{version, revision, goversion}\fR \- info about CoreDNS itself\.
\fBcoredns_build_info{version, revision, goversion}\fR \- info about CoreDNS itself\.
.
.
.IP "\(bu" 4
.IP "\(bu" 4
\fBcoredns_panic_count_total{}\fR \- total number of panics\.
.
.IP "\(bu" 4
\fBcoredns_dns_request_count_total{server, zone, proto, family}\fR \- total query count\.
\fBcoredns_dns_request_count_total{server, zone, proto, family}\fR \- total query count\.
.
.
.IP "\(bu" 4
.IP "\(bu" 4
...
@@ -109,4 +112,4 @@ Or via an enviroment variable (this is supported throughout the Corefile): \fBex
...
@@ -109,4 +112,4 @@ Or via an enviroment variable (this is supported throughout the Corefile): \fBex
.IP "" 0
.IP "" 0
.
.
.SH "BUGS"
.SH "BUGS"
When reloading, we keep the handler running, meaning that any changes to the handler\'s address aren\'t picked up\. You\'ll need to restart CoreDNS for that to happen\.
When reloading, the Prometheus handler is stopped before the new server instance is started\. If that new server fails to start, then the initial server instance is still available and DNS queries still served, but Prometheus handler stays down\. Prometheus will not reply HTTP request until a successful reload or a complete restart of CoreDNS\.
\fIpprof\fR \- publishes runtime profiling data at endpoints under \fB/debug/pprof\fR\.
\fIpprof\fR \- publishes runtime profiling data at endpoints under \fB/debug/pprof\fR\.
...
@@ -10,7 +10,7 @@
...
@@ -10,7 +10,7 @@
You can visit \fB/debug/pprof\fR on your site for an index of the available endpoints\. By default it will listen on localhost:6053\.
You can visit \fB/debug/pprof\fR on your site for an index of the available endpoints\. By default it will listen on localhost:6053\.
.
.
.P
.P
For more information, please see Go\'s pprof documentation \fIhttps://golang\.org/pkg/net/http/pprof/\fR and read Profiling Go Programs \fIhttps://blog\.golang\.org/profiling\-go\-programs\fR\.
This is a debugging tool\. Certain requests (such as collecting execution traces) can be slow\. If you use pprof on a live server, consider restricting access or enabling it only temporarily\.
.
.
.P
.P
This plugin can only be used once per Server Block\.
This plugin can only be used once per Server Block\.
...
@@ -42,6 +42,9 @@ Enable pprof endpoints:
...
@@ -42,6 +42,9 @@ Enable pprof endpoints:
.IP "" 0
.IP "" 0
.
.
.P
.P
And use the pprof tool to get statistics: \fBgo tool pprof http://localhost:6053\fR\.
\fIreload\fR \- allows automatic reload of a changed Corefile
\fIreload\fR \- allows automatic reload of a changed Corefile
.
.
.SH "DESCRIPTION"
.SH "DESCRIPTION"
This plugin allows automatic reload of a changed \fICorefile\fR\. To enable automatic reloading of \fIzone file\fR changes, use the \fBauto\fR plugin\.
.
.P
This plugin periodically checks if the Corefile has changed by reading it and calculating its MD5 checksum\. If the file has changed, it reloads CoreDNS with the new Corefile\. This eliminates the need to send a SIGHUP or SIGUSR1 after changing the Corefile\.
This plugin periodically checks if the Corefile has changed by reading it and calculating its MD5 checksum\. If the file has changed, it reloads CoreDNS with the new Corefile\. This eliminates the need to send a SIGHUP or SIGUSR1 after changing the Corefile\.
Rewrites are invisible to the client\. There are simple rewrites (fast) and complex rewrites (slower), but they\'re powerful enough to accommodate most dynamic back\-end applications\.
Rewrites are invisible to the client\. There are simple rewrites (fast) and complex rewrites (slower), but they\'re powerful enough to accommodate most dynamic back\-end applications\.
.
.
.SH "SYNTAX"
.SH "SYNTAX"
A simplified/easy to digest syntax for \fIrewrite\fR is\.\.\. ~~~ rewrite [continue|stop] FIELD FROM TO ~~~
.
.
.nf
.IP "\(bu" 4
\fBFIELD\fR indicates what part of the request/response is being re\-written\.
rewrite [continue|stop] FIELD FROM TO
.
.
.fi
.IP "\(bu" 4
\fBtype\fR \- the type field of the request will be rewritten\. FROM/TO must be a DNS record type (\fBA\fR, \fBMX\fR, etc); e\.g\., to rewrite ANY queries to HINFO, use \fBrewrite type ANY HINFO\fR\.
.
.
.IP "\(bu" 4
.IP "\(bu" 4
\fBFIELD\fR is (\fBtype\fR, \fBclass\fR, \fBname\fR, \.\.\.)
\fBclass\fR \- the class of the message will be rewritten\. FROM/TO must be a DNS class type (\fBIN\fR, \fBCH\fR, or \fBHS\fR) e\.g\., to rewrite CH queries to IN use \fBrewrite class CH IN\fR\.
.
.
.IP "\(bu" 4
.IP "\(bu" 4
\fBFROM\fR is the exact name of type to match
\fBname\fR \- the query name in the \fIrequest\fR is rewritten; by default this is a full match of the name, e\.g\., \fBrewrite name miek\.nl example\.org\fR\. Other match types are supported, see the \fBName Field Rewrites\fR section below\.
.
.
.IP "\(bu" 4
.IP "\(bu" 4
\fBTO\fR is the destination name or type to rewrite to
\fBanswer name\fR \- the query name in the \fIresponse\fR is rewritten\. This option has special restrictions and requirements, in particular it must always combined with a \fBname\fR rewrite\. See below in the \fBResponse Rewrites\fR section\.
.
.
.IP "" 0
.IP "\(bu" 4
\fBedns0\fR \- an EDNS0 option can be appended to the request as described below in the \fBEDNS0 Options\fR section\.
.
.
.P
.IP "" 0
When the FIELD is \fBtype\fR and FROM is (\fBA\fR, \fBMX\fR, etc\.), the type of the message will be rewritten; e\.g\., to rewrite ANY queries to HINFO, use \fBrewrite type ANY HINFO\fR\.
.
.
.P
.IP "\(bu" 4
When the FIELD is \fBclass\fR and FROM is (\fBIN\fR, \fBCH\fR, or \fBHS\fR) the class of the message will be rewritten; e\.g\., to rewrite CH queries to IN use \fBrewrite class CH IN\fR\.
\fBFROM\fR is the name or type to match
.
.
.P
.IP "\(bu" 4
When the FIELD is \fBname\fR the query name in the message is rewritten; this needs to be a full match of the name, e\.g\., \fBrewrite name miek\.nl example\.org\fR\.
\fBTO\fR is the destination name or type to rewrite to
.
.
.P
.IP "" 0
When the FIELD is \fBedns0\fR an EDNS0 option can be appended to the request as described below\.
.
.
.P
.P
If you specify multiple rules and an incoming query matches on multiple rules, the rewrite will behave as following * \fBcontinue\fR will continue apply the next rule in the rule list\. * \fBstop\fR will consider the current rule is the last rule and will not continue\. Default behaviour for not specifying this rule processing mode is \fBstop\fR
If you specify multiple rules and an incoming query matches on multiple rules, the rewrite will behave as following * \fBcontinue\fR will continue apply the next rule in the rule list\. * \fBstop\fR will consider the current rule is the last rule and will not continue\. Default behaviour for not specifying this rule processing mode is \fBstop\fR
...
@@ -222,7 +223,7 @@ ftp\-us\-west\-1\.coredns\.rocks\. 0 IN A 10\.30\.30\.30
...
@@ -222,7 +223,7 @@ ftp\-us\-west\-1\.coredns\.rocks\. 0 IN A 10\.30\.30\.30
.IP "" 0
.IP "" 0
.
.
.P
.P
The syntax for the response of DNS request and response is as follows:
The syntax for the rewrite of DNS request and response is as follows:
.
.
.IP "" 4
.IP "" 4
.
.
...
@@ -237,6 +238,22 @@ rewrite [continue|stop] {
...
@@ -237,6 +238,22 @@ rewrite [continue|stop] {
.
.
.IP "" 0
.IP "" 0
.
.
.P
Note that the above syntax is strict\. For response rewrites only \fBname\fR rules are allowed to match the question section, and only by match type \fBregex\fR\. The answer rewrite must be after the name, as ordered in the syntax example\. There must only be two lines (a \fBname\fR follwed by an \fBanswer\fR) in the brackets, additional rules are not supported\.
.
.P
An alternate syntax for the rewrite of DNS request and response is as follows:
.
.IP "" 4
.
.nf
rewrite [continue|stop] name regex STRING STRING answer name STRING STRING
.
.fi
.
.IP "" 0
.
.SH "EDNS0 OPTIONS"
.SH "EDNS0 OPTIONS"
Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request\.
Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request\.
.
.
...
@@ -332,4 +349,9 @@ If the query has source IP as IPv4, the first 24 bits in the IP will be the netw
...
@@ -332,4 +349,9 @@ If the query has source IP as IPv4, the first 24 bits in the IP will be the netw
If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet\.
If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet\.
.
.
.IP "" 0
.IP "" 0
.
.SH "FULL SYNTAX"
The full plugin usage syntax is harder to digest\.\.\. ~~~ rewrite [continue|stop] {type|class|edns0|name [exact|prefix|suffix|substring|regex [FROM TO answer name]]} FROM TO ~~~
.
.P
The syntax above doesn\'t cover the multi line block option for specifying a name request+response rewrite rule described in the \fBResponse Rewrite\fR section\.
\fItemplate\fR \- allows for dynamic responses based on the incoming query\.
\fItemplate\fR \- allows for dynamic responses based on the incoming query\.
...
@@ -97,18 +97,18 @@ The output of the template must be a RFC 1035 \fIhttps://tools\.ietf\.org/html/r
...
@@ -97,18 +97,18 @@ The output of the template must be a RFC 1035 \fIhttps://tools\.ietf\.org/html/r
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
.
.
.IP "\(bu" 4
.IP "\(bu" 4
\fBcoredns_template_matches_total{regex}\fR the total number of matched requests by regex\.
\fBcoredns_template_matches_total{server, regex}\fR the total number of matched requests by regex\.
.
.
.IP "\(bu" 4
.IP "\(bu" 4
\fBcoredns_template_template_failures_total{regex,section,template}\fR the number of times the Go templating failed\. Regex, section and template label values can be used to map the error back to the config file\.
\fBcoredns_template_template_failures_total{server, regex,section,template}\fR the number of times the Go templating failed\. Regex, section and template label values can be used to map the error back to the config file\.
.
.
.IP "\(bu" 4
.IP "\(bu" 4
\fBcoredns_template_rr_failures_total{regex,section,template}\fR the number of times the templated resource record was invalid and could not be parsed\. Regex, section and template label values can be used to map the error back to the config file\.
\fBcoredns_template_rr_failures_total{server, regex,section,template}\fR the number of times the templated resource record was invalid and could not be parsed\. Regex, section and template label values can be used to map the error back to the config file\.
.
.
.IP "" 0
.IP "" 0
.
.
.P
.P
Both failure cases indicate a problem with the template configuration\.
Both failure cases indicate a problem with the template configuration\. The \fBserver\fR label indicates the server incrementing the metric, see the \fImetrics\fR plugin for details\.
\fItls\fR \- allows you to configure the server certificates for the TLS and gRPC servers\.
\fItls\fR \- allows you to configure the server certificates for the TLS and gRPC servers\.
...
@@ -22,10 +22,13 @@ The gRPC protobuffer is defined in \fBpb/dns\.proto\fR\. It defines the proto as
...
@@ -22,10 +22,13 @@ The gRPC protobuffer is defined in \fBpb/dns\.proto\fR\. It defines the proto as
.
.
.nf
.nf
tls CERT KEY CA
tls CERT KEY [CA]
.
.
.fi
.fi
.
.
.P
Parameter CA is optional\. If not set, system CAs can be used to verify the client certificate
.
.SH "EXAMPLES"
.SH "EXAMPLES"
Start a DNS\-over\-TLS server that picks up incoming DNS\-over\-TLS queries on port 5553 and uses the nameservers defined in \fB/etc/resolv\.conf\fR to resolve the query\. This proxy path uses plain old DNS\.
Start a DNS\-over\-TLS server that picks up incoming DNS\-over\-TLS queries on port 5553 and uses the nameservers defined in \fB/etc/resolv\.conf\fR to resolve the query\. This proxy path uses plain old DNS\.
Read the blog post \fIhttps://coredns\.io/2017/03/01/how\-to\-add\-plugins\-to\-coredns/\fR on how this plugin is built, or explore the source code \fIhttps://github\.com/coredns/coredns/blob/master/plugin/whoami/\fR\.
@@ -17,12 +17,14 @@ rewrite [continue|stop] FIELD FROM TO
...
@@ -17,12 +17,14 @@ rewrite [continue|stop] FIELD FROM TO
~~~
~~~
***FIELD** indicates what part of the request/response is being re-written.
***FIELD** indicates what part of the request/response is being re-written.
*`type` - the type field of the request will be rewritten. FROM/TO must be a DNS record type (`A`, `MX`, etc);
*`type` - the type field of the request will be rewritten. FROM/TO must be a DNS record type (`A`, `MX`, etc);
e.g., to rewrite ANY queries to HINFO, use `rewrite type ANY HINFO`.
e.g., to rewrite ANY queries to HINFO, use `rewrite type ANY HINFO`.
*`class` - the class of the message will be rewritten. FROM/TO must be a DNS class type (`IN`, `CH`, or `HS`) e.g., to rewrite CH queries to IN use `rewrite class CH IN`.
*`class` - the class of the message will be rewritten. FROM/TO must be a DNS class type (`IN`, `CH`, or `HS`) e.g., to rewrite CH queries to IN use `rewrite class CH IN`.
*`name` - the query name in the _request_ is rewritten; by default this is a full match of the name, e.g., `rewrite name miek.nl example.org`. Other match types are supported, see the **Name Field Rewrites** section below.
*`name` - the query name in the _request_ is rewritten; by default this is a full match of the name, e.g., `rewrite name miek.nl example.org`. Other match types are supported, see the **Name Field Rewrites** section below.
*`answer name` - the query name in the _response_ is rewritten. This option has special restrictions and requirements, in particular it must always combined with a `name` rewrite. See below in the **Response Rewrites** section.
*`answer name` - the query name in the _response_ is rewritten. This option has special restrictions and requirements, in particular it must always combined with a `name` rewrite. See below in the **Response Rewrites** section.
*`edns0` - an EDNS0 option can be appended to the request as described below in the **EDNS0 Options** section.
*`edns0` - an EDNS0 option can be appended to the request as described below in the **EDNS0 Options** section.
***FROM** is the name or type to match
***FROM** is the name or type to match
***TO** is the destination name or type to rewrite to
***TO** is the destination name or type to rewrite to
The syntax above doesn't cover the multi line block option for specifying a name request+response rewrite rule described in the **Response Rewrite** section.
The syntax above doesn't cover the multi line block option for specifying a name request+response rewrite rule described in the **Response Rewrite** section.
