Updates (#1432)

* Enable forward

* Regen all docs

10 files changed, 283 insertions, 99 deletions

diff --git a/man/coredns-auto.7 b/man/coredns-auto.7
index 9d0fce626..2b8fe152e 100644
--- a/man/coredns-auto.7
+++ b/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
 .
diff --git a/man/coredns-autopath.7 b/man/coredns-autopath.7
index e2ae787cb..957705089 100644
--- a/man/coredns-autopath.7
+++ b/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\.
diff --git a/man/coredns-cache.7 b/man/coredns-cache.7
index 25bc48e08..b7d6f1629 100644
--- a/man/coredns-cache.7
+++ b/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:
 .
diff --git a/man/coredns-dnssec.7 b/man/coredns-dnssec.7
index af3d440af..401ae09a8 100644
--- a/man/coredns-dnssec.7
+++ b/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
diff --git a/man/coredns-health.7 b/man/coredns-health.7
index cfd72fd4d..a54d68b64 100644
--- a/man/coredns-health.7
+++ b/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
 
diff --git a/man/coredns-log.7 b/man/coredns-log.7
index 46c69cdff..a398aaa02 100644
--- a/man/coredns-log.7
+++ b/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
 .
diff --git a/man/coredns-metrics.7 b/man/coredns-metrics.7
index 041658bd3..cf22f02f2 100644
--- a/man/coredns-metrics.7
+++ b/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
diff --git a/man/coredns-rewrite.7 b/man/coredns-rewrite.7
index 269b83e74..d793611e9 100644
--- a/man/coredns-rewrite.7
+++ b/man/coredns-rewrite.7
@@ -43,186 +43,293 @@ 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
 .
-.SH "EDNS0 OPTIONS"
-Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request\.
+.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
-\fBreplace\fR will modify any matching (what that means may vary based on EDNS0 type) option with the specified option
+\fBexact\fR (default): on exact match of the name in the question section of a request
 .
 .IP "\(bu" 4
-\fBappend\fR will add the option regardless of what options already exist
+\fBsubstring\fR: on a partial match of the name in the question section of a request
 .
 .IP "\(bu" 4
-\fBset\fR will modify a matching option or add one if none is found
+\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
-Currently supported are \fBEDNS0_LOCAL\fR, \fBEDNS0_NSID\fR and \fBEDNS0_SUBNET\fR\.
-.
-.SS "EDNS0_LOCAL"
-This has two fields, code and data\. A match is defined as having the same code\. Data may be a string or a variable\.
+If the match type is omitted, the \fBexact\fR match type is being assumed\.
 .
-.TP
-A string data can be treated as hex if it starts with \fB0x\fR\. Example:
-
+.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 edns0 local set 0xffee 0x61626364
-    whoami
-}
+rewrite name substring service\.us\-west\-1\.example\.org service\.us\-west\-1\.consul
 .
 .fi
 .
 .IP "" 0
 .
 .P
-rewrites the first local option with code 0xffee, setting the data to "abcd"\. Equivalent:
+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 edns0 local set 0xffee abcd
-}
+rewrite name regex (\.*)\-(us\-west\-1)\e\.example\e\.org {1}\.service\.{2}\.consul
 .
 .fi
 .
 .IP "" 0
 .
-.TP
-A variable data is specified with a pair of curly brackets \fB{}\fR\. Following are the supported variables
-{qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}\.
+.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
-Example:
+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 edns0 local set 0xffee {client_ip}
+rewrite name regex (\.*)\-(us\-west\-1)\e\.coredns\e\.rocks {1}\.service\.{2}\.consul
 .
 .fi
 .
 .IP "" 0
 .
-.SS "EDNS0_NSID"
-This has no fields; it will add an NSID option with an empty string for the NSID\. If the option already exists and the action is \fBreplace\fR or \fBset\fR, then the NSID in the option will be set to the empty string\.
-.
-.SS "EDNS0_SUBNET"
-This has two fields, IPv4 bitmask length and IPv6 bitmask length\. The bitmask length is used to extract the client subnet from the source IP address in the query\.
-.
 .P
-Example:
+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
 
-rewrite edns0 subnet set 24 56
+$ 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
 .
-.IP "\(bu" 4
-If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet\.
+.P
+The above is the mismatch\.
 .
-.IP "\(bu" 4
-If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet\.
+.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 "" 0
+.IP "" 4
 .
-.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\.
+.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
-The syntax for the name re\-writing is as follows:
+Now, the \fBANSWER SECTION\fR matches the \fBQUESTION SECTION\fR:
 .
 .IP "" 4
 .
 .nf
 
-rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
+$ 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 match type, i\.e\. \fBexact\fR, \fBsubstring\fR, etc\., triggers re\-write:
+The syntax for the response of DNS request and response is as follows:
 .
-.IP "\(bu" 4
-\fBexact\fR (default): on exact match of the name in the question section of a request
+.IP "" 4
 .
-.IP "\(bu" 4
-\fBsubstring\fR: on a partial match of the name in the question section of a request
+.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\.
 .
 .IP "\(bu" 4
-\fBprefix\fR: when the name begins with the matching string
+\fBreplace\fR will modify any matching (what that means may vary based on EDNS0 type) option with the specified option
 .
 .IP "\(bu" 4
-\fBsuffix\fR: when the name ends with the matching string
+\fBappend\fR will add the option regardless of what options already exist
 .
 .IP "\(bu" 4
-\fBregex\fR: when the name in the question section of a request matches a regular expression
+\fBset\fR will modify a matching option or add one if none is found
 .
 .IP "" 0
 .
 .P
-If the match type is omitted, the \fBexact\fR match type is being assumed\.
+Currently supported are \fBEDNS0_LOCAL\fR, \fBEDNS0_NSID\fR and \fBEDNS0_SUBNET\fR\.
 .
-.P
-The following instruction allows re\-writing the name in the query that contains \fBservice\.us\-west\-1\.example\.org\fR substring\.
+.SS "EDNS0_LOCAL"
+This has two fields, code and data\. A match is defined as having the same code\. Data may be a string or a variable\.
+.
+.TP
+A string data can be treated as hex if it starts with \fB0x\fR\. Example:
+
 .
 .IP "" 4
 .
 .nf
 
-rewrite name substring service\.us\-west\-1\.example\.org service\.us\-west\-1\.consul
+\&\. {
+    rewrite edns0 local set 0xffee 0x61626364
+    whoami
+}
 .
 .fi
 .
 .IP "" 0
 .
 .P
-Thus:
+rewrites the first local option with code 0xffee, setting the data to "abcd"\. Equivalent:
 .
-.IP "\(bu" 4
-Incoming Request Name: \fBftp\.service\.us\-west\-1\.example\.org\fR
+.IP "" 4
 .
-.IP "\(bu" 4
-Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
+.nf
+
+\&\. {
+    rewrite edns0 local set 0xffee abcd
+}
+.
+.fi
 .
 .IP "" 0
 .
+.TP
+A variable data is specified with a pair of curly brackets \fB{}\fR\. Following are the supported variables
+{qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}\.
+.
 .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\.
+Example:
 .
 .IP "" 4
 .
 .nf
 
-rewrite name regex (\.*)\-(us\-west\-1)\e\.example\e\.org {1}\.service\.{2}\.consul
+rewrite edns0 local set 0xffee {client_ip}
 .
 .fi
 .
 .IP "" 0
 .
+.SS "EDNS0_NSID"
+This has no fields; it will add an NSID option with an empty string for the NSID\. If the option already exists and the action is \fBreplace\fR or \fBset\fR, then the NSID in the option will be set to the empty string\.
+.
+.SS "EDNS0_SUBNET"
+This has two fields, IPv4 bitmask length and IPv6 bitmask length\. The bitmask length is used to extract the client subnet from the source IP address in the query\.
+.
 .P
-Thus:
+Example:
+.
+.IP "" 4
+.
+.nf
+
+rewrite edns0 subnet set 24 56
+.
+.fi
+.
+.IP "" 0
 .
 .IP "\(bu" 4
-Incoming Request Name: \fBftp\-us\-west\-1\.example\.org\fR
+If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet\.
 .
 .IP "\(bu" 4
-Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
+If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet\.
 .
 .IP "" 0
 
diff --git a/man/coredns-secondary.7 b/man/coredns-secondary.7
index 7020be5c3..eed20513d 100644
--- a/man/coredns-secondary.7
+++ b/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\.
 .
diff --git a/man/coredns-template.7 b/man/coredns-template.7
index a3d2ce955..fdc083118 100644
--- a/man/coredns-template.7
+++ b/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\.