Updates (#1432)

* Enable forward

* Regen all docs

core/dnsserver/zdirectives.go

@@ -38,6 +38,7 @@ var Directives = []string{
 	"auto",
 	"secondary",
 	"etcd",
+	"forward",
 	"proxy",
 	"erratic",
 	"whoami",

core/plugin/zplugin.go

@@ -35,6 +35,7 @@ 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"
 )

man/coredns-auto.7

@@ -4,10 +4,10 @@
 .TH "COREDNS\-AUTO" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
-\fIauto\fR \- enables serving zone data from an RFC 1035\-style master file which is automatically picked up from disk\.
+\fIauto\fR \- enables serving zone data from an RFC 1035\-style master file, which is automatically picked up from disk\.
 .
 .SH "DESCRIPTION"
-The \fIauto\fR plugin is used for an "old\-style" DNS server\. It serves from a preloaded file that exists on disk\. If the zone file contains signatures (i\.e\. is signed, i\.e\. DNSSEC) correct DNSSEC answers are returned\. Only NSEC is supported! If you use this setup \fIyou\fR are responsible for resigning the zonefile\. New zones or changed zone are automatically picked up from disk\.
+The \fIauto\fR plugin is used for an "old\-style" DNS server\. It serves from a preloaded file that exists on disk\. If the zone file contains signatures (i\.e\. is signed, i\.e\. using DNSSEC) correct DNSSEC answers are returned\. Only NSEC is supported! If you use this setup \fIyou\fR are responsible for re\-signing the zonefile\. New or changed zones are automatically picked up from disk\.
 .
 .SH "SYNTAX"
 .
@@ -25,13 +25,13 @@ auto [ZONES\.\.\.] {
 \fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block are used\.
 .
 .IP "\(bu" 4
-\fBdirectory\fR loads zones from the speficied \fBDIR\fR\. If a file name matches \fBREGEXP\fR it will be used to extract the origin\. \fBORIGIN_TEMPLATE\fR will be used as a template for the origin\. Strings like \fB{<number>}\fR are replaced with the respective matches in the file name, i\.e\. \fB{1}\fR is the first match, \fB{2}\fR is the second, etc\.\. The default is: \fBdb\e\.(\.*) {1}\fR e\.g\. from a file with the name \fBdb\.example\.com\fR, the extracted origin will be \fBexample\.com\fR\. \fBTIMEOUT\fR specifies how often CoreDNS should scan the directory, the default is every 60 seconds\. This value is in seconds\. The minimum value is 1 second\.
+\fBdirectory\fR loads zones from the speficied \fBDIR\fR\. If a file name matches \fBREGEXP\fR it will be used to extract the origin\. \fBORIGIN_TEMPLATE\fR will be used as a template for the origin\. Strings like \fB{<number>}\fR are replaced with the respective matches in the file name, e\.g\. \fB{1}\fR is the first match, \fB{2}\fR is the second\. The default is: \fBdb\e\.(\.*) {1}\fR i\.e\. from a file with the name \fBdb\.example\.com\fR, the extracted origin will be \fBexample\.com\fR\. \fBTIMEOUT\fR specifies how often CoreDNS should scan the directory; the default is every 60 seconds\. This value is in seconds\. The minimum value is 1 second\.
 .
 .IP "\(bu" 4
 \fBno_reload\fR by default CoreDNS will try to reload a zone every minute and reloads if the SOA\'s serial has changed\. This option disables that behavior\.
 .
 .IP "\(bu" 4
-\fBupstream\fR defines upstream resolvers to be used resolve external names found (think CNAMEs) pointing to external names\. \fBADDRESS\fR can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\.
+\fBupstream\fR defines upstream resolvers to be used resolve external names found (think CNAMEs) pointing to external names\. \fBADDRESS\fR can be an IP address, an IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\.
 .
 .IP "" 0
 .

man/coredns-autopath.7

@@ -4,10 +4,10 @@
 .TH "COREDNS\-AUTOPATH" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
-\fIautopath\fR \- allows for server side search path completion\.
+\fIautopath\fR \- allows for server\-side search path completion\.
 .
 .SH "DESCRIPTION"
-If it sees a query that matches the first element of the configured search path, \fIautopath\fR will follow the chain of search path elements and returns the first reply that is not NXDOMAIN\. On any failures the original reply is returned\. Because \fIautopath\fR returns a reply for a name that wasn\'t the original question it will add a CNAME that points from the original name (with the search path element in it) to the name of this answer\.
+If it sees a query that matches the first element of the configured search path, \fIautopath\fR will follow the chain of search path elements and return the first reply that is not NXDOMAIN\. On any failures, the original reply is returned\. Because \fIautopath\fR returns a reply for a name that wasn\'t the original question it will add a CNAME that points from the original name (with the search path element in it) to the name of this answer\.
 .
 .SH "SYNTAX"
 .
@@ -58,4 +58,4 @@ autopath @kubernetes
 .IP "" 0
 .
 .P
-Use the search path dynamically retrieved from the kubernetes plugin\.
+Use the search path dynamically retrieved from the \fIkubernetes\fR plugin\.

man/coredns-cache.7

@@ -7,7 +7,7 @@
 \fIcache\fR \- enables a frontend cache\.
 .
 .SH "DESCRIPTION"
-With \fIcache\fR enabled all records except zone transfers and metadata records will be cached for up to 3600s\. Caching is mostly useful in a scenario when fetching data from the backend (upstream, database, etc\.) is expensive\.
+With \fIcache\fR enabled, all records except zone transfers and metadata records will be cached for up to 3600s\. Caching is mostly useful in a scenario when fetching data from the backend (upstream, database, etc\.) is expensive\.
 .
 .SH "SYNTAX"
 .
@@ -18,7 +18,7 @@ cache [TTL] [ZONES\.\.\.]
 .fi
 .
 .IP "\(bu" 4
-\fBTTL\fR max TTL in seconds\. If not specified, the maximum TTL will be used which is 3600 for noerror responses and 1800 for denial of existence ones\. Setting a TTL of 300: \fBcache 300\fR would cache the record up to 300 seconds\.
+\fBTTL\fR max TTL in seconds\. If not specified, the maximum TTL will be used, which is 3600 for noerror responses and 1800 for denial of existence ones\. Setting a TTL of 300: \fBcache 300\fR would cache records up to 300 seconds\.
 .
 .IP "\(bu" 4
 \fBZONES\fR zones it should cache for\. If empty, the zones from the configuration block are used\.
@@ -49,19 +49,16 @@ cache [TTL] [ZONES\.\.\.] {
 \fBTTL\fR and \fBZONES\fR as above\.
 .
 .IP "\(bu" 4
-\fBsuccess\fR, override the settings for caching successful responses, \fBCAPACITY\fR indicates the maximum number of packets we cache before we start evicting (\fIrandomly\fR)\. \fBTTL\fR overrides the cache maximum TTL\.
+\fBsuccess\fR, override the settings for caching successful responses\. \fBCAPACITY\fR indicates the maximum number of packets we cache before we start evicting (\fIrandomly\fR)\. \fBTTL\fR overrides the cache maximum TTL\.
 .
 .IP "\(bu" 4
-\fBdenial\fR, override the settings for caching denial of existence responses, \fBCAPACITY\fR indicates the maximum number of packets we cache before we start evicting (LRU)\. \fBTTL\fR overrides the cache maximum TTL\. There is a third category (\fBerror\fR) but those responses are never cached\.
+\fBdenial\fR, override the settings for caching denial of existence responses\. \fBCAPACITY\fR indicates the maximum number of packets we cache before we start evicting (LRU)\. \fBTTL\fR overrides the cache maximum TTL\. There is a third category (\fBerror\fR) but those responses are never cached\.
 .
 .IP "\(bu" 4
-\fBprefetch\fR, will prefetch popular items when they are about to be expunged from the cache\. Popular means \fBAMOUNT\fR queries have been seen no gaps of \fBDURATION\fR or more between them\. \fBDURATION\fR defaults to 1m\. Prefetching will happen when the TTL drops below \fBPERCENTAGE\fR, which defaults to \fB10%\fR\. Values should be in the range \fB[10%, 90%]\fR\. Note the percent sign is mandatory\. \fBPERCENTAGE\fR is treated as an \fBint\fR\.
+\fBprefetch\fR will prefetch popular items when they are about to be expunged from the cache\. Popular means \fBAMOUNT\fR queries have been seen with no gaps of \fBDURATION\fR or more between them\. \fBDURATION\fR defaults to 1m\. Prefetching will happen when the TTL drops below \fBPERCENTAGE\fR, which defaults to \fB10%\fR, or latest 1 second before TTL expiration\. Values should be in the range \fB[10%, 90%]\fR\. Note the percent sign is mandatory\. \fBPERCENTAGE\fR is treated as an \fBint\fR\.
 .
 .IP "" 0
 .
-.P
-The minimum TTL allowed on resource records is 5 seconds\.
-.
 .SH "METRICS"
 If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
 .

man/coredns-dnssec.7

@@ -7,7 +7,7 @@
 \fIdnssec\fR \- enable on\-the\-fly DNSSEC signing of served data\.
 .
 .SH "DESCRIPTION"
-With \fIdnssec\fR any reply that doesn\'t (or can\'t) do DNSSEC will get signed on\-the\-fly\. Authenticated denial of existence is implemented with NSEC black lies\. Using ECDSA as an algorithm is preferred as this leads to smaller signatures (compared to RSA)\. NSEC3 is \fInot\fR supported\.
+With \fIdnssec\fR any reply that doesn\'t (or can\'t) do DNSSEC will get signed on the fly\. Authenticated denial of existence is implemented with NSEC black lies\. Using ECDSA as an algorithm is preferred as this leads to smaller signatures (compared to RSA)\. NSEC3 is \fInot\fR supported\.
 .
 .SH "SYNTAX"
 .
@@ -21,7 +21,7 @@ dnssec [ZONES\.\.\. ] {
 .fi
 .
 .P
-The specified key is used for all signing operations\. The DNSSEC signing will treat this key a CSK (common signing key), forgoing the ZSK/KSK split\. All signing operations are done online\. Authenticated denial of existence is implemented with NSEC black lies\. Using ECDSA as an algorithm is preferred as this leads to smaller signatures (compared to RSA)\. NSEC3 is \fInot\fR supported\.
+The specified key is used for all signing operations\. The DNSSEC signing will treat this key as a CSK (common signing key), forgoing the ZSK/KSK split\. All signing operations are done online\. Authenticated denial of existence is implemented with NSEC black lies\. Using ECDSA as an algorithm is preferred as this leads to smaller signatures (compared to RSA)\. NSEC3 is \fInot\fR supported\.
 .
 .P
 If multiple \fIdnssec\fR plugins are specified in the same zone, the last one specified will be used (See \fIbugs\fR)\.
@@ -30,7 +30,7 @@ If multiple \fIdnssec\fR plugins are specified in the same zone, the last one sp
 \fBZONES\fR zones that should be signed\. If empty, the zones from the configuration block are used\.
 .
 .IP "\(bu" 4
-\fBkey file\fR indicates that \fBKEY\fR file(s) should be read from disk\. When multiple keys are specified, RRsets will be signed with all keys\. Generating a key can be done with \fBdnssec\-keygen\fR: \fBdnssec\-keygen \-a ECDSAP256SHA256 <zonename>\fR\. A key created for zone \fIA\fR can be safely used for zone \fIB\fR\. The name of the key file can be specified as one of the following formats
+\fBkey file\fR indicates that \fBKEY\fR file(s) should be read from disk\. When multiple keys are specified, RRsets will be signed with all keys\. Generating a key can be done with \fBdnssec\-keygen\fR: \fBdnssec\-keygen \-a ECDSAP256SHA256 <zonename>\fR\. A key created for zone \fIA\fR can be safely used for zone \fIB\fR\. The name of the key file can be specified in one of the following formats
 .
 .IP "\(bu" 4
 basename of the generated key \fBKexample\.org+013+45330\fR

man/coredns-health.7

@@ -20,6 +20,26 @@ health [ADDRESS]
 .P
 Optionally takes an address; the default is \fB:8080\fR\. The health path is fixed to \fB/health\fR\. The health endpoint returns a 200 response code and the word "OK" when CoreDNS is healthy\. It returns a 503\. \fIhealth\fR periodically (1s) polls plugin that exports health information\. If any of the plugin signals that it is unhealthy, the server will go unhealthy too\. Each plugin that supports health checks has a section "Health" in their README\.
 .
+.P
+More options can be set with this extended syntax:
+.
+.IP "" 4
+.
+.nf
+
+health [ADDRESS] {
+    lameduck DURATION
+}
+.
+.fi
+.
+.IP "" 0
+.
+.IP "\(bu" 4
+Where \fBlameduck\fR will make the process unhealthy then \fIwait\fR for \fBDURATION\fR before the process shuts down\.
+.
+.IP "" 0
+.
 .SH "PLUGINS"
 Any plugin that implements the Healther interface will be used to report health\.
 .
@@ -45,4 +65,21 @@ Run another health endpoint on http://localhost:8091\.
 .fi
 .
 .IP "" 0
+.
+.P
+Set a lameduck duration of 1 second:
+.
+.IP "" 4
+.
+.nf
+
+\&\. {
+    health localhost:8091 {
+        lameduck 1s
+    }
+}
+.
+.fi
+.
+.IP "" 0
 

man/coredns-log.7

@@ -144,7 +144,7 @@ The default Common Log Format is:
 .
 .nf
 
-`{remote} \- [{when}] "{type} {class} {name} {proto} {size} {>do} {>bufsize}" {rcode} {>rflags} {rsize} {duration}`
+`{remote} \- [{when}] {>id} "{type} {class} {name} {proto} {size} {>do} {>bufsize}" {rcode} {>rflags} {rsize} {duration}`
 .
 .fi
 .

man/coredns-metrics.7

@@ -10,6 +10,9 @@
 With \fIprometheus\fR you export metrics from CoreDNS and any plugin that has them\. The default location for the metrics is \fBlocalhost:9153\fR\. The metrics path is fixed to \fB/metrics\fR\. The following metrics are exported:
 .
 .IP "\(bu" 4
+\fBcoredns_build_info{version, revision, goversion}\fR \- info about CoreDNS itself\.
+.
+.IP "\(bu" 4
 \fBcoredns_dns_request_count_total{zone, proto, family}\fR \- total query count\.
 .
 .IP "\(bu" 4

man/coredns-rewrite.7

@@ -43,6 +43,200 @@ When the FIELD is \fBedns0\fR an EDNS0 option can be appended to the request as
 .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
 .
+.SS "NAME FIELD REWRITES"
+The \fBrewrite\fR plugin offers the ability to match on the name in the question section of a DNS request\. The match could be exact, substring, or based on a prefix, suffix, or regular expression\.
+.
+.P
+The syntax for the name re\-writing is as follows:
+.
+.IP "" 4
+.
+.nf
+
+rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The match type, i\.e\. \fBexact\fR, \fBsubstring\fR, etc\., triggers re\-write:
+.
+.IP "\(bu" 4
+\fBexact\fR (default): on exact match of the name in the question section of a request
+.
+.IP "\(bu" 4
+\fBsubstring\fR: on a partial match of the name in the question section of a request
+.
+.IP "\(bu" 4
+\fBprefix\fR: when the name begins with the matching string
+.
+.IP "\(bu" 4
+\fBsuffix\fR: when the name ends with the matching string
+.
+.IP "\(bu" 4
+\fBregex\fR: when the name in the question section of a request matches a regular expression
+.
+.IP "" 0
+.
+.P
+If the match type is omitted, the \fBexact\fR match type is being assumed\.
+.
+.P
+The following instruction allows re\-writing the name in the query that contains \fBservice\.us\-west\-1\.example\.org\fR substring\.
+.
+.IP "" 4
+.
+.nf
+
+rewrite name substring service\.us\-west\-1\.example\.org service\.us\-west\-1\.consul
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Thus:
+.
+.IP "\(bu" 4
+Incoming Request Name: \fBftp\.service\.us\-west\-1\.example\.org\fR
+.
+.IP "\(bu" 4
+Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
+.
+.IP "" 0
+.
+.P
+The following instruction uses regular expressions\. The name in a request matching \fB(\.*)\-(us\-west\-1)\e\.example\e\.org\fR regular expression is being replaces with \fB{1}\.service\.{2}\.consul\fR, where \fB{1}\fR and \fB{2}\fR are regular expression match groups\.
+.
+.IP "" 4
+.
+.nf
+
+rewrite name regex (\.*)\-(us\-west\-1)\e\.example\e\.org {1}\.service\.{2}\.consul
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Thus:
+.
+.IP "\(bu" 4
+Incoming Request Name: \fBftp\-us\-west\-1\.example\.org\fR
+.
+.IP "\(bu" 4
+Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
+.
+.IP "" 0
+.
+.SS "RESPONSE REWRITES"
+When re\-writing incoming DNS requests\' names, CoreDNS re\-writes the \fBQUESTION SECTION\fR section of the requests\. It may be necessary to re\-write the \fBANSWER SECTION\fR of the requests, because some DNS resolvers would treat the mismatch between \fBQUESTION SECTION\fR and \fBANSWER SECTION\fR as a man\-in\-the\-middle attack (MITM)\.
+.
+.P
+For example, a user tries to resolve \fBftp\-us\-west\-1\.coredns\.rocks\fR\. The CoreDNS configuration file has the following rule:
+.
+.IP "" 4
+.
+.nf
+
+rewrite name regex (\.*)\-(us\-west\-1)\e\.coredns\e\.rocks {1}\.service\.{2}\.consul
+.
+.fi
+.
+.IP "" 0
+.
+.P
+CoreDNS instance re\-wrote the request to \fBftp\-us\-west\-1\.coredns\.rocks\fR with \fBftp\.service\.us\-west\-1\.consul\fR and ultimately resolved it to 3 records\. The resolved records, see \fBANSWER SECTION\fR, were not from \fBcoredns\.rocks\fR, but rather from \fBservice\.us\-west\-1\.consul\fR\.
+.
+.IP "" 4
+.
+.nf
+
+$ dig @10\.1\.1\.1 ftp\-us\-west\-1\.coredns\.rocks
+
+; <<>> DiG 9\.8\.3\-P1 <<>> @10\.1\.1\.1 ftp\-us\-west\-1\.coredns\.rocks
+; (1 server found)
+;; global options: +cmd
+;; Got answer:
+;; \->>HEADER<<\- opcode: QUERY, status: NOERROR, id: 8619
+;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0
+
+;; QUESTION SECTION:
+;ftp\-us\-west\-1\.coredns\.rocks\. IN A
+
+;; ANSWER SECTION:
+ftp\.service\.us\-west\-1\.consul\. 0    IN A    10\.10\.10\.10
+ftp\.service\.us\-west\-1\.consul\. 0    IN A    10\.20\.20\.20
+ftp\.service\.us\-west\-1\.consul\. 0    IN A    10\.30\.30\.30
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The above is the mismatch\.
+.
+.P
+The following configuration snippet allows for the re\-writing of the \fBANSWER SECTION\fR, provided that the \fBQUESTION SECTION\fR was re\-written:
+.
+.IP "" 4
+.
+.nf
+
+    rewrite stop {
+        name regex (\.*)\-(us\-west\-1)\e\.coredns\e\.rocks {1}\.service\.{2}\.consul
+        answer name (\.*)\e\.service\e\.(us\-west\-1)\e\.consul {1}\-{2}\.coredns\.rocks
+    }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Now, the \fBANSWER SECTION\fR matches the \fBQUESTION SECTION\fR:
+.
+.IP "" 4
+.
+.nf
+
+$ dig @10\.1\.1\.1 ftp\-us\-west\-1\.coredns\.rocks
+
+; <<>> DiG 9\.8\.3\-P1 <<>> @10\.1\.1\.1 ftp\-us\-west\-1\.coredns\.rocks
+; (1 server found)
+;; global options: +cmd
+;; Got answer:
+;; \->>HEADER<<\- opcode: QUERY, status: NOERROR, id: 8619
+;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0
+
+;; QUESTION SECTION:
+;ftp\-us\-west\-1\.coredns\.rocks\. IN A
+
+;; ANSWER SECTION:
+ftp\-us\-west\-1\.coredns\.rocks\. 0    IN A    10\.10\.10\.10
+ftp\-us\-west\-1\.coredns\.rocks\. 0    IN A    10\.20\.20\.20
+ftp\-us\-west\-1\.coredns\.rocks\. 0    IN A    10\.30\.30\.30
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The syntax for the response 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"
 Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request\.
 .
@@ -138,91 +332,4 @@ 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\.
 .
 .IP "" 0
-.
-.SS "NAME FIELD REWRITES"
-The \fBrewrite\fR plugin offers the ability to match on the name in the question section of a DNS request\. The match could be exact, substring, or based on a prefix, suffix, or regular expression\.
-.
-.P
-The syntax for the name re\-writing is as follows:
-.
-.IP "" 4
-.
-.nf
-
-rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
-.
-.fi
-.
-.IP "" 0
-.
-.P
-The match type, i\.e\. \fBexact\fR, \fBsubstring\fR, etc\., triggers re\-write:
-.
-.IP "\(bu" 4
-\fBexact\fR (default): on exact match of the name in the question section of a request
-.
-.IP "\(bu" 4
-\fBsubstring\fR: on a partial match of the name in the question section of a request
-.
-.IP "\(bu" 4
-\fBprefix\fR: when the name begins with the matching string
-.
-.IP "\(bu" 4
-\fBsuffix\fR: when the name ends with the matching string
-.
-.IP "\(bu" 4
-\fBregex\fR: when the name in the question section of a request matches a regular expression
-.
-.IP "" 0
-.
-.P
-If the match type is omitted, the \fBexact\fR match type is being assumed\.
-.
-.P
-The following instruction allows re\-writing the name in the query that contains \fBservice\.us\-west\-1\.example\.org\fR substring\.
-.
-.IP "" 4
-.
-.nf
-
-rewrite name substring service\.us\-west\-1\.example\.org service\.us\-west\-1\.consul
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Thus:
-.
-.IP "\(bu" 4
-Incoming Request Name: \fBftp\.service\.us\-west\-1\.example\.org\fR
-.
-.IP "\(bu" 4
-Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
-.
-.IP "" 0
-.
-.P
-The following instruction uses regular expressions\. The name in a request matching \fB(\.*)\-(us\-west\-1)\e\.example\e\.org\fR regular expression is being replaces with \fB{1}\.service\.{2}\.consul\fR, where \fB{1}\fR and \fB{2}\fR are regular expression match groups\.
-.
-.IP "" 4
-.
-.nf
-
-rewrite name regex (\.*)\-(us\-west\-1)\e\.example\e\.org {1}\.service\.{2}\.consul
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Thus:
-.
-.IP "\(bu" 4
-Incoming Request Name: \fBftp\-us\-west\-1\.example\.org\fR
-.
-.IP "\(bu" 4
-Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
-.
-.IP "" 0
 

man/coredns-secondary.7

@@ -52,6 +52,9 @@ secondary [zones\.\.\.] {
 .
 .IP "" 0
 .
+.P
+When a zone is due to be refreshed (Refresh timer fires) a random jitter of 5 seconds is applied, before fetching\. In the case of retry this will be 2 seconds\. If there are any errors during the transfer the transfer fails; this will be logged\.
+.
 .SH "EXAMPLES"
 Transfer \fBexample\.org\fR from 10\.0\.1\.1, and if that fails try 10\.1\.2\.1\.
 .

man/coredns-template.7

@@ -7,7 +7,7 @@
 \fItemplate\fR \- allows for dynamic responses based on the incoming query\.
 .
 .SH "DESCRIPTION"
-The \fItemplate\fR plugin allows you to dynamically repond to queries by just writing a (Go) template\.
+The \fItemplate\fR plugin allows you to dynamically respond to queries by just writing a (Go) template\.
 .
 .SH "SYNTAX"
 .
@@ -38,13 +38,13 @@ template CLASS TYPE [ZONE\.\.\.] {
 \fBREGEX\fR Go regexp \fIhttps://golang\.org/pkg/regexp/\fR that are matched against the incoming question name\. Specifying no regex matches everything (default: \fB\.*\fR)\. First matching regex wins\.
 .
 .IP "\(bu" 4
-\fBanswer|additional|authority\fR \fBRR\fR A RFC 1035 \fIhttps://tools\.ietf\.org/html/rfc1035#section\-5\fR style resource record fragment build by a Go template \fIhttps://golang\.org/pkg/text/template/\fR that contains the reply\.
+\fBanswer|additional|authority\fR \fBRR\fR A RFC 1035 \fIhttps://tools\.ietf\.org/html/rfc1035#section\-5\fR style resource record fragment built by a Go template \fIhttps://golang\.org/pkg/text/template/\fR that contains the reply\.
 .
 .IP "\(bu" 4
 \fBrcode\fR \fBCODE\fR A response code (\fBNXDOMAIN, SERVFAIL, \.\.\.\fR)\. The default is \fBSUCCESS\fR\.
 .
 .IP "\(bu" 4
-\fBfallthrough\fR Continue with the next plugin if the zone matched but no regex did not match\. 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 Continue with the next plugin if the zone matched but no regex matched\. 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 "" 0
 .
@@ -55,16 +55,53 @@ At least one \fBanswer\fR or \fBrcode\fR directive is needed (e\.g\. \fBrcode NX
 \fIAlso see\fR contains an additional reading list\.
 .
 .SH "TEMPLATES"
-Each resource record is a full\-featured Go template \fIhttps://golang\.org/pkg/text/template/\fR with the following predefined data * \fB\.Zone\fR the matched zone string (e\.g\. \fBexample\.\fR)\. * \fB\.Name\fR the query name, as a string (lowercased)\. * \fB\.Class\fR the query class (usually \fBIN\fR)\. * \fB\.Type\fR the RR type requested (e\.g\. \fBPTR\fR)\. * \fB\.Match\fR an array of all matches\. \fBindex \.Match 0\fR refers to the whole match\. * \fB\.Group\fR a map of the named capture groups\. * \fB\.Message\fR the complete incoming DNS message\. * \fB\.Question\fR the matched question section\.
+Each resource record is a full\-featured Go template \fIhttps://golang\.org/pkg/text/template/\fR with the following predefined data
+.
+.IP "\(bu" 4
+\fB\.Zone\fR the matched zone string (e\.g\. \fBexample\.\fR)\.
+.
+.IP "\(bu" 4
+\fB\.Name\fR the query name, as a string (lowercased)\.
+.
+.IP "\(bu" 4
+\fB\.Class\fR the query class (usually \fBIN\fR)\.
+.
+.IP "\(bu" 4
+\fB\.Type\fR the RR type requested (e\.g\. \fBPTR\fR)\.
+.
+.IP "\(bu" 4
+\fB\.Match\fR an array of all matches\. \fBindex \.Match 0\fR refers to the whole match\.
+.
+.IP "\(bu" 4
+\fB\.Group\fR a map of the named capture groups\.
+.
+.IP "\(bu" 4
+\fB\.Message\fR the complete incoming DNS message\.
+.
+.IP "\(bu" 4
+\fB\.Question\fR the matched question section\.
+.
+.IP "" 0
 .
 .P
-The output of the template must be a RFC 1035 \fIhttps://tools\.ietf\.org/html/rfc1035\fR style resource record line (commonly refered to as a "zone file")\.
+The output of the template must be a RFC 1035 \fIhttps://tools\.ietf\.org/html/rfc1035\fR style resource record (commonly referred to as a "zone file")\.
 .
 .P
 \fBWARNING\fR there is a syntactical problem with Go templates and CoreDNS config files\. Expressions like \fB{{$var}}\fR will be interpreted as a reference to an environment variable by CoreDNS (and Caddy) while \fB{{ $var }}\fR will work\. See \fIBugs\fR and corefile(5)\.
 .
 .SH "METRICS"
-If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported: \- \fBcoredns_template_matches_total{regex}\fR the total number of matched requests by regex\. \- \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_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\.
+If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
+.
+.IP "\(bu" 4
+\fBcoredns_template_matches_total{regex}\fR the total number of matched requests by regex\.
+.
+.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\.
+.
+.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\.
+.
+.IP "" 0
 .
 .P
 Both failure cases indicate a problem with the template configuration\.
@@ -111,7 +148,7 @@ The \fB\.invalid\fR domain is a reserved TLD (see RFC\-2606 Reserved Top Level D
 
     template ANY ANY invalid {
       rcode NXDOMAIN
-      answer "invalid\. 60 {{ \.Class }} SOA a\.invalid\. b\.invalid\. (1 60 60 60 60)"
+      authority "invalid\. 60 {{ \.Class }} SOA ns\.invalid\. hostmaster\.invalid\. (1 60 60 60 60)"
     }
 }
 .
@@ -123,10 +160,10 @@ The \fB\.invalid\fR domain is a reserved TLD (see RFC\-2606 Reserved Top Level D
 A query to \.invalid will result in NXDOMAIN (rcode)
 .
 .IP "2." 4
-A dummy SOA record is send to hand out a TTL of 60s for caching
+A dummy SOA record is sent to hand out a TTL of 60s for caching purposes
 .
 .IP "3." 4
-Querying \fB\.invalid\fR of \fBCH\fR will also cause a NXDOMAIN/SOA response
+Querying \fB\.invalid\fR in the \fBCH\fR class will also cause a NXDOMAIN/SOA response
 .
 .IP "4." 4
 The default regex is \fB\.*\fR
@@ -134,7 +171,7 @@ The default regex is \fB\.*\fR
 .IP "" 0
 .
 .SS "BLOCK INVALID SEARCH DOMAIN COMPLETIONS"
-Imagine you run \fBexample\.com\fR with a datacenter \fBdc1\.example\.com\fR\. The datacenter domain is part of the DNS search domain\. However \fBsomething\.example\.com\.dc1\.example\.com\fR would indicates a fully qualified domain name (\fBsomething\.example\.com\fR) that inadvertely has the default domain or search path (\fBdc1\.example\.com\fR) added\.
+Imagine you run \fBexample\.com\fR with a datacenter \fBdc1\.example\.com\fR\. The datacenter domain is part of the DNS search domain\. However \fBsomething\.example\.com\.dc1\.example\.com\fR would indicate a fully qualified domain name (\fBsomething\.example\.com\fR) that inadvertently has the default domain or search path (\fBdc1\.example\.com\fR) added\.
 .
 .IP "" 4
 .
@@ -145,7 +182,7 @@ Imagine you run \fBexample\.com\fR with a datacenter \fBdc1\.example\.com\fR\. T
 
     template IN ANY example\.com\.dc1\.example\.com {
       rcode NXDOMAIN
-      answer "{{ \.Zone }} 60 IN SOA a\.{{ \.Zone }} b\.{{ \.Zone }} (1 60 60 60 60)"
+      authority "{{ \.Zone }} 60 IN SOA ns\.example\.com hostmaster\.example\.com (1 60 60 60 60)"
     }
 }
 .
@@ -164,9 +201,9 @@ A more verbose regex based equivalent would be
     proxy \. 8\.8\.8\.8
 
     template IN ANY example\.com {
-      match "(example\.com\.dc1\.example\.com)$"
+      match "example\e\.com\e\.(dc1\e\.example\e\.com\e\.)$"
       rcode NXDOMAIN
-      answer "{{ index \.Match 1 }} 60 IN SOA a\.{{ index \.Match 1 }} b\.{{ index \.Match 1 }} (1 60 60 60 60)"
+      authority "{{ index \.Match 1 }} 60 IN SOA ns\.{{ index \.Match 1 }} hostmaster\.{{ index \.Match 1 }} (1 60 60 60 60)"
       fallthrough
     }
 }
@@ -176,7 +213,7 @@ A more verbose regex based equivalent would be
 .IP "" 0
 .
 .P
-The regex based version can do more complex matching/templating while zone based templating is easier to read and use\.
+The regex\-based version can do more complex matching/templating while zone\-based templating is easier to read and use\.
 .
 .SS "RESOLVE A/PTR FOR \.EXAMPLE"
 .
@@ -204,10 +241,10 @@ The regex based version can do more complex matching/templating while zone based
 .fi
 .
 .P
-An IPv4 address consists of 4 bytes, \fBa\.b\.c\.d\fR\. Named groups make it less error prone to reverse the ip in the PTR case\. Try to use named groups to explain what your regex and template are doing\.
+An IPv4 address consists of 4 bytes, \fBa\.b\.c\.d\fR\. Named groups make it less error\-prone to reverse the IP address in the PTR case\. Try to use named groups to explain what your regex and template are doing\.
 .
 .P
-Note that the A record is actually a wildcard, any subdomain of the ip will resolve to the ip\.
+Note that the A record is actually a wildcard: any subdomain of the IP address will resolve to the IP address\.
 .
 .P
 Having templates to map certain PTR/A pairs is a common pattern\.