generate doc for 1.1.3 (#1832)

35 files changed, 197 insertions, 81 deletions

diff --git a/man/coredns-auto.7 b/man/coredns-auto.7
index 98d8f1b01..d84dd4e07 100644
--- a/man/coredns-auto.7
+++ b/man/coredns-auto.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-AUTO" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-AUTO" "7" "May 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\.
diff --git a/man/coredns-autopath.7 b/man/coredns-autopath.7
index 9af8150d1..7fc381296 100644
--- a/man/coredns-autopath.7
+++ b/man/coredns-autopath.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-AUTOPATH" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-AUTOPATH" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIautopath\fR \- allows for server\-side search path completion\.
@@ -32,10 +32,13 @@ If a plugin implements the \fBAutoPather\fR interface then it can be used\.
 If monitoring is enabled (via the \fIprometheus\fR directive) then the following metric is exported:
 .
 .IP "\(bu" 4
-\fBcoredns_autopath_success_count_total{}\fR \- counter of successfully autopath\-ed queries\.
+\fBcoredns_autopath_success_count_total{server}\fR \- counter of successfully autopath\-ed queries\.
 .
 .IP "" 0
 .
+.P
+The \fBserver\fR label is explained in the \fImetrics\fR plugin documentation\.
+.
 .SH "EXAMPLES"
 .
 .nf
diff --git a/man/coredns-bind.7 b/man/coredns-bind.7
index dcbb7a442..354f1b914 100644
--- a/man/coredns-bind.7
+++ b/man/coredns-bind.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-BIND" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-BIND" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIbind\fR \- overrides the host to which the server should bind\.
diff --git a/man/coredns-cache.7 b/man/coredns-cache.7
index d05054b23..c963d4133 100644
--- a/man/coredns-cache.7
+++ b/man/coredns-cache.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-CACHE" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-CACHE" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIcache\fR \- enables a frontend cache\.
@@ -72,24 +72,21 @@ Eviction is done per shard \- i\.e\. when a shard reaches capacity, items are ev
 If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
 .
 .IP "\(bu" 4
-\fBcoredns_cache_size{type}\fR \- Total elements in the cache by cache type\.
+\fBcoredns_cache_size{server, type}\fR \- Total elements in the cache by cache type\.
 .
 .IP "\(bu" 4
-\fBcoredns_cache_capacity{type}\fR \- Total capacity of the cache by cache type\.
+\fBcoredns_cache_hits_total{server, type}\fR \- Counter of cache hits by cache type\.
 .
 .IP "\(bu" 4
-\fBcoredns_cache_hits_total{type}\fR \- Counter of cache hits by cache type\.
+\fBcoredns_cache_misses_total{server}\fR \- Counter of cache misses\.
 .
 .IP "\(bu" 4
-\fBcoredns_cache_misses_total{}\fR \- Counter of cache misses\.
-.
-.IP "\(bu" 4
-\fBcoredns_cache_drops_total{}\fR \- Counter of dropped messages\.
+\fBcoredns_cache_drops_total{server}\fR \- Counter of dropped messages\.
 .
 .IP "" 0
 .
 .P
-Cache types are either "denial" or "success"\.
+Cache types are either "denial" or "success"\. \fBServer\fR is the server handling the request, see the metrics plugin for documentation\.
 .
 .SH "EXAMPLES"
 Enable caching for all zones, but cap everything to a TTL of 10 seconds:
diff --git a/man/coredns-chaos.7 b/man/coredns-chaos.7
index 0619e769d..fe294411e 100644
--- a/man/coredns-chaos.7
+++ b/man/coredns-chaos.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-CHAOS" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-CHAOS" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIchaos\fR \- allows for responding to TXT queries in the CH class\.
diff --git a/man/coredns-debug.7 b/man/coredns-debug.7
index 8995f5416..0c4345a9d 100644
--- a/man/coredns-debug.7
+++ b/man/coredns-debug.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-DEBUG" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-DEBUG" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIdebug\fR \- disables the automatic recovery upon a crash so that you\'ll get a nice stack trace\.
diff --git a/man/coredns-dnssec.7 b/man/coredns-dnssec.7
index 9a897ae35..cbb6e744a 100644
--- a/man/coredns-dnssec.7
+++ b/man/coredns-dnssec.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-DNSSEC" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-DNSSEC" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIdnssec\fR \- enable on\-the\-fly DNSSEC signing of served data\.
@@ -56,19 +56,19 @@ generated private key \fBKexample\.org+013+45330\.private\fR
 If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
 .
 .IP "\(bu" 4
-\fBcoredns_dnssec_cache_size{type}\fR \- total elements in the cache, type is "signature"\.
+\fBcoredns_dnssec_cache_size{server, type}\fR \- total elements in the cache, type is "signature"\.
 .
 .IP "\(bu" 4
-\fBcoredns_dnssec_cache_capacity{type}\fR \- total capacity of the cache, type is "signature"\.
+\fBcoredns_dnssec_cache_hits_total{server}\fR \- Counter of cache hits\.
 .
 .IP "\(bu" 4
-\fBcoredns_dnssec_cache_hits_total{}\fR \- Counter of cache hits\.
-.
-.IP "\(bu" 4
-\fBcoredns_dnssec_cache_misses_total{}\fR \- Counter of cache misses\.
+\fBcoredns_dnssec_cache_misses_total{server}\fR \- Counter of cache misses\.
 .
 .IP "" 0
 .
+.P
+The label \fBserver\fR indicated the server handling the request, see the \fImetrics\fR plugin for details\.
+.
 .SH "EXAMPLES"
 Sign responses for \fBexample\.org\fR with the key "Kexample\.org\.+013+45330\.key"\.
 .
diff --git a/man/coredns-dnstap.7 b/man/coredns-dnstap.7
index 913f70606..9b627e6d1 100644
--- a/man/coredns-dnstap.7
+++ b/man/coredns-dnstap.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-DNSTAP" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-DNSTAP" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIdnstap\fR \- enable logging to dnstap
diff --git a/man/coredns-erratic.7 b/man/coredns-erratic.7
index d427b3d12..d8c36c513 100644
--- a/man/coredns-erratic.7
+++ b/man/coredns-erratic.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-ERRATIC" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-ERRATIC" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIerratic\fR \- a plugin useful for testing client behavior\.
diff --git a/man/coredns-errors.7 b/man/coredns-errors.7
index 82ee12e0d..cc67c74f5 100644
--- a/man/coredns-errors.7
+++ b/man/coredns-errors.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-ERRORS" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-ERRORS" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIerrors\fR \- enable error logging\.
diff --git a/man/coredns-etcd.7 b/man/coredns-etcd.7
index 5a78adcfa..ee65d92af 100644
--- a/man/coredns-etcd.7
+++ b/man/coredns-etcd.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-ETCD" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-ETCD" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIetcd\fR \- enables reading zone data from an etcd instance\.
@@ -185,5 +185,56 @@ reverse\.skydns\.local\.
 .
 .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:
+.
+.IP "" 4
+.
+.nf
+
+% curl \-XPUT http://127\.0\.0\.1:2379/v2/keys/skydns/local/skydns/dns/apex \-d value=\'{"host":"1\.1\.1\.1","ttl":"60"}\'
+.
+.fi
+.
+.IP "" 0
+.
+.P
+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 ~~~
+.
 .SH "BUGS"
 Only the etcdv2 protocol is supported\.
diff --git a/man/coredns-federation.7 b/man/coredns-federation.7
index d6a2f523a..8d23cae90 100644
--- a/man/coredns-federation.7
+++ b/man/coredns-federation.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-FEDERATION" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-FEDERATION" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIfederation\fR \- enables federated queries to be resolved via the kubernetes plugin\.
diff --git a/man/coredns-file.7 b/man/coredns-file.7
index ee097761a..47418f1bd 100644
--- a/man/coredns-file.7
+++ b/man/coredns-file.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-FILE" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-FILE" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIfile\fR \- enables serving zone data from an RFC 1035\-style master file\.
diff --git a/man/coredns-forward.7 b/man/coredns-forward.7
index 7326be695..ac29637fb 100644
--- a/man/coredns-forward.7
+++ b/man/coredns-forward.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-FORWARD" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-FORWARD" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \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
 .P
 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"
 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
 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:
+Proxy all requests within \fBexample\.org\.\fR to a nameserver running on a different port:
 .
 .IP "" 4
 .
@@ -221,7 +224,7 @@ Proxy all requests to 9\.9\.9\.9 using the DNS\-over\-TLS protocol, and cache ev
 .IP "" 0
 .
 .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"
 RFC 7858 \fIhttps://tools\.ietf\.org/html/rfc7858\fR for DNS over TLS\.
diff --git a/man/coredns-health.7 b/man/coredns-health.7
index a42431de0..23ec1d933 100644
--- a/man/coredns-health.7
+++ b/man/coredns-health.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-HEALTH" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-HEALTH" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIhealth\fR \- enables a health check endpoint\.
@@ -61,6 +61,23 @@ net {
 .
 .IP "" 0
 .
+.P
+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"
 Any plugin that implements the Healther interface will be used to report health\.
 .
@@ -106,4 +123,6 @@ Set a lameduck duration of 1 second:
 .fi
 .
 .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\.
diff --git a/man/coredns-hosts.7 b/man/coredns-hosts.7
index 6951d8213..8a2f7f8a5 100644
--- a/man/coredns-hosts.7
+++ b/man/coredns-hosts.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-HOSTS" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-HOSTS" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIhosts\fR \- enables serving zone data from a \fB/etc/hosts\fR style file\.
diff --git a/man/coredns-kubernetes.7 b/man/coredns-kubernetes.7
index f63139d11..660d70b13 100644
--- a/man/coredns-kubernetes.7
+++ b/man/coredns-kubernetes.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-KUBERNETES" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-KUBERNETES" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIkubernetes\fR \- enables the reading zone data from a Kubernetes cluster\.
@@ -43,6 +43,7 @@ kubernetes [ZONES\.\.\.] {
     endpoint_pod_names
     upstream [ADDRESS\.\.\.]
     ttl TTL
+    transfer to ADDRESS\.\.\.
     fallthrough [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\.
 .
 .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\.
 .
+.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\.
+.
 .IP "" 0
 .
 .SH "HEALTH"
diff --git a/man/coredns-loadbalance.7 b/man/coredns-loadbalance.7
index 1c4f41f92..07ec73c10 100644
--- a/man/coredns-loadbalance.7
+++ b/man/coredns-loadbalance.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-LOADBALANCE" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-LOADBALANCE" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIloadbalance\fR \- acts as a round\-robin DNS loadbalancer by randomizing the order of A and AAAA records in the answer\.
diff --git a/man/coredns-log.7 b/man/coredns-log.7
index 76601b0f9..234668e35 100644
--- a/man/coredns-log.7
+++ b/man/coredns-log.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-LOG" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-LOG" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIlog\fR \- enables query logging to standard output\.
diff --git a/man/coredns-metrics.7 b/man/coredns-metrics.7
index ab1564b21..4678f2d46 100644
--- a/man/coredns-metrics.7
+++ b/man/coredns-metrics.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-METRICS" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-METRICS" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIprometheus\fR \- enables Prometheus \fIhttps://prometheus\.io/\fR metrics\.
@@ -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\.
 .
 .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\.
 .
 .IP "\(bu" 4
@@ -109,4 +112,4 @@ Or via an enviroment variable (this is supported throughout the Corefile): \fBex
 .IP "" 0
 .
 .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\.
diff --git a/man/coredns-nsid.7 b/man/coredns-nsid.7
index 048858b13..3947a1d7a 100644
--- a/man/coredns-nsid.7
+++ b/man/coredns-nsid.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-NSID" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-NSID" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fInsid\fR \- adds an identifier of this server to each reply\.
diff --git a/man/coredns-pprof.7 b/man/coredns-pprof.7
index c83b4f050..00d4ab612 100644
--- a/man/coredns-pprof.7
+++ b/man/coredns-pprof.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-PPROF" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-PPROF" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIpprof\fR \- publishes runtime profiling data at endpoints under \fB/debug/pprof\fR\.
@@ -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\.
 .
 .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
 This plugin can only be used once per Server Block\.
@@ -42,6 +42,9 @@ Enable pprof endpoints:
 .IP "" 0
 .
 .P
+And use the pprof tool to get statistics: \fBgo tool pprof http://localhost:6053\fR\.
+.
+.P
 Listen on an alternate address:
 .
 .IP "" 4
diff --git a/man/coredns-proxy.7 b/man/coredns-proxy.7
index 0b059e192..f035f978a 100644
--- a/man/coredns-proxy.7
+++ b/man/coredns-proxy.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-PROXY" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-PROXY" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIproxy\fR \- facilitates both a basic reverse proxy and a robust load balancer\.
@@ -225,7 +225,7 @@ Proxy everything except \fBexample\.org\fR using the host\'s \fBresolv\.conf\fR\
 
 \&\. {
     proxy \. /etc/resolv\.conf {
-        except miek\.nl example\.org
+        except example\.org
     }
 }
 .
diff --git a/man/coredns-reload.7 b/man/coredns-reload.7
index b11fc1ed9..a6d44e937 100644
--- a/man/coredns-reload.7
+++ b/man/coredns-reload.7
@@ -1,12 +1,15 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-RELOAD" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-RELOAD" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIreload\fR \- allows automatic reload of a changed Corefile
 .
 .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\.
 .
 .P
diff --git a/man/coredns-reverse.7 b/man/coredns-reverse.7
index 1f0dc3521..827bf0553 100644
--- a/man/coredns-reverse.7
+++ b/man/coredns-reverse.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-REVERSE" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-REVERSE" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIreverse\fR \- allows for dynamic responses to PTR and the related A/AAAA requests\.
diff --git a/man/coredns-rewrite.7 b/man/coredns-rewrite.7
index 0b6f59b60..400ee2d8f 100644
--- a/man/coredns-rewrite.7
+++ b/man/coredns-rewrite.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-REWRITE" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-REWRITE" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIrewrite\fR \- performs internal message rewriting\.
@@ -10,35 +10,36 @@
 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"
+A simplified/easy to digest syntax for \fIrewrite\fR is\.\.\. ~~~ rewrite [continue|stop] FIELD FROM TO ~~~
 .
-.nf
-
-rewrite [continue|stop] FIELD FROM TO
+.IP "\(bu" 4
+\fBFIELD\fR indicates what part of the request/response is being re\-written\.
 .
-.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
-\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
-\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
-\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
-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\.
+.IP "" 0
+
 .
-.P
-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\.
+.IP "\(bu" 4
+\fBFROM\fR is the name or type to match
 .
-.P
-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\.
+.IP "\(bu" 4
+\fBTO\fR is the destination name or type to rewrite to
 .
-.P
-When the FIELD is \fBedns0\fR an EDNS0 option can be appended to the request as described below\.
+.IP "" 0
 .
 .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
@@ -222,7 +223,7 @@ ftp\-us\-west\-1\.coredns\.rocks\. 0    IN A    10\.30\.30\.30
 .IP "" 0
 .
 .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
 .
@@ -237,6 +238,22 @@ rewrite [continue|stop] {
 .
 .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"
 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
 If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet\.
 .
 .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\.
diff --git a/man/coredns-root.7 b/man/coredns-root.7
index e3bddd12c..bfce08839 100644
--- a/man/coredns-root.7
+++ b/man/coredns-root.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-ROOT" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-ROOT" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIroot\fR \- simply specifies the root of where to find (zone) files\.
diff --git a/man/coredns-route53.7 b/man/coredns-route53.7
index f271183dc..c2b468c32 100644
--- a/man/coredns-route53.7
+++ b/man/coredns-route53.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-ROUTE53" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-ROUTE53" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIroute53\fR \- enables serving zone data from AWS route53\.
diff --git a/man/coredns-secondary.7 b/man/coredns-secondary.7
index 774f0787f..de33575b6 100644
--- a/man/coredns-secondary.7
+++ b/man/coredns-secondary.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-SECONDARY" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-SECONDARY" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIsecondary\fR \- enables serving a zone retrieved from a primary server\.
diff --git a/man/coredns-template.7 b/man/coredns-template.7
index f962e41c0..3ee650664 100644
--- a/man/coredns-template.7
+++ b/man/coredns-template.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-TEMPLATE" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-TEMPLATE" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \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
 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\.
+\fBcoredns_template_matches_total{server, 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\.
+\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
-\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
 .
 .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\.
 .
 .SH "EXAMPLES"
 .
diff --git a/man/coredns-tls.7 b/man/coredns-tls.7
index 5ac113213..20aeb0d71 100644
--- a/man/coredns-tls.7
+++ b/man/coredns-tls.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-TLS" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-TLS" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \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
 .
 .nf
 
-tls CERT KEY CA
+tls CERT KEY [CA]
 .
 .fi
 .
+.P
+Parameter CA is optional\. If not set, system CAs can be used to verify the client certificate
+.
 .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\.
 .
diff --git a/man/coredns-trace.7 b/man/coredns-trace.7
index d9a3b5390..24421ca2c 100644
--- a/man/coredns-trace.7
+++ b/man/coredns-trace.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-TRACE" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-TRACE" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fItrace\fR \- enables OpenTracing\-based tracing of DNS requests as they go through the plugin chain\.
diff --git a/man/coredns-whoami.7 b/man/coredns-whoami.7
index 6732cb288..1d10e1ba7 100644
--- a/man/coredns-whoami.7
+++ b/man/coredns-whoami.7
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-WHOAMI" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-WHOAMI" "7" "May 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIwhoami\fR \- returns your resolver\'s local IP address, port and transport\.
@@ -68,4 +68,6 @@ _udp\.example\.org\.       0       IN      SRV     0 0 40212
 .fi
 .
 .IP "" 0
-
+.
+.SH "SEE ALSO"
+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\.
diff --git a/man/coredns.1 b/man/coredns.1
index 8d544f4fa..95814f87d 100644
--- a/man/coredns.1
+++ b/man/coredns.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS" "1" "January 2018" "CoreDNS" "CoreDNS"
+.TH "COREDNS" "1" "May 2018" "CoreDNS" "CoreDNS"
 .
 .SH "NAME"
 \fBcoredns\fR
@@ -56,4 +56,4 @@ CoreDNS Authors\.
 Apache License 2\.0
 .
 .SH "SEE ALSO"
-Corefile(5) corendns\-debug(7) corendns\-dnssec(7) corendns\-health(7) corendns\-log(7) corendns\-file(7) corendns\-nsid(7) corendns\-auto(7) corendns\-erratic(7) corendns\-chaos(7) corendns\-dnstap(7) corendns\-pprof(7) corendns\-tls(7) corendns\-loadbalance(7) corendns\-cache(7) corendns\-root(7) corendns\-whoami(7) corendns\-bind(7) corendns\-hosts(7) corendns\-template(7) corendns\-proxy(7) corendns\-autopath(7) corendns\-kubernetes(7) corendns\-secondary(7) corendns\-reverse(7) corendns\-errors(7) corendns\-metrics(7) corendns\-rewrite(7) corendns\-federation(7) corendns\-etcd(7) corendns\-trace(7)\.
+Corefile(5) corendns\-erratic(7) corendns\-hosts(7) corendns\-dnssec(7) corendns\-health(7) corendns\-file(7) corendns\-root(7) corendns\-auto(7) corendns\-dnstap(7) corendns\-pprof(7) corendns\-tls(7) corendns\-loadbalance(7) corendns\-cache(7) corendns\-whoami(7) corendns\-bind(7) corendns\-chaos(7) corendns\-template(7) corendns\-proxy(7) corendns\-autopath(7) corendns\-log(7) corendns\-kubernetes(7) corendns\-forward(7) corendns\-debug(7) corendns\-nsid(7) corendns\-secondary(7) corendns\-route53(7) corendns\-reverse(7) corendns\-errors(7) corendns\-metrics(7) corendns\-reload(7) corendns\-rewrite(7) corendns\-federation(7) corendns\-etcd(7) corendns\-trace(7)\.
diff --git a/man/corefile.5 b/man/corefile.5
index a5f546b1d..caca32544 100644
--- a/man/corefile.5
+++ b/man/corefile.5
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREFILE" "5" "January 2018" "CoreDNS" "CoreDNS"
+.TH "COREFILE" "5" "May 2018" "CoreDNS" "CoreDNS"
 .
 .SH "NAME"
 \fBcorefile\fR