diff --git a/man/coredns-auto.7 b/man/coredns-auto.7
index 2b8fe152e..3829debbb 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-AUTO" "7" "February 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 957705089..9af8150d1 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-AUTOPATH" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIautopath\fR \- allows for server\-side search path completion\.
diff --git a/man/coredns-bind.7 b/man/coredns-bind.7
index 0da85f684..60b878d0b 100644
--- a/man/coredns-bind.7
+++ b/man/coredns-bind.7
@@ -1,24 +1,30 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-BIND" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-BIND" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIbind\fR \- overrides the host to which the server should bind\.
 .
 .SH "DESCRIPTION"
-Normally, the listener binds to the wildcard host\. However, you may force the listener to bind to another IP instead\. This directive accepts only an address, not a port\.
+Normally, the listener binds to the wildcard host\. However, you may want the listener to bind to another IP instead\.
+.
+.P
+If several addresses are provided, a listener will be open on each of the IP provided\.
+.
+.P
+Each address has to be an IP of one of the interfaces of the host\.
 .
 .SH "SYNTAX"
 .
 .nf
 
-bind ADDRESS
+bind ADDRESS  \.\.\.
 .
 .fi
 .
 .P
-\fBADDRESS\fR is the IP address to bind to\.
+\fBADDRESS\fR is an IP address to bind to\. When several addresses are provided a listener will be opened on each of the addresses\.
 .
 .SH "EXAMPLES"
 To make your socket accessible only to that machine, bind to IP 127\.0\.0\.1 (localhost):
@@ -34,4 +40,35 @@ To make your socket accessible only to that machine, bind to IP 127\.0\.0\.1 (lo
 .fi
 .
 .IP "" 0
+.
+.P
+To allow processing DNS requests only local host on both IPv4 and IPv6 stacks, use the syntax:
+.
+.IP "" 4
+.
+.nf
+
+\&\. {
+    bind 127\.0\.0\.1 ::1
+}
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If the configuration comes up with several \fIbind\fR directives, all addresses are consolidated together: The following sample is equivalent to the preceding:
+.
+.IP "" 4
+.
+.nf
+
+\&\. {
+    bind 127\.0\.0\.1
+    bind ::1
+}
+.
+.fi
+.
+.IP "" 0
 
diff --git a/man/coredns-cache.7 b/man/coredns-cache.7
index b7d6f1629..b70c44415 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-CACHE" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIcache\fR \- enables a frontend cache\.
diff --git a/man/coredns-chaos.7 b/man/coredns-chaos.7
index 974bf1705..6a323d039 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-CHAOS" "7" "February 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 6f9fe8d38..41585343e 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-DEBUG" "7" "February 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 401ae09a8..db2b522d8 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-DNSSEC" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIdnssec\fR \- enable on\-the\-fly DNSSEC signing of served data\.
diff --git a/man/coredns-dnstap.7 b/man/coredns-dnstap.7
index 7247e6931..d87042078 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-DNSTAP" "7" "February 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 1d3ef0fcf..b5238f34e 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-ERRATIC" "7" "February 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 66b0a1ed2..5ed14c754 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-ERRORS" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIerrors\fR \- enable error logging\.
diff --git a/man/coredns-etcd.7 b/man/coredns-etcd.7
index 8a9fb48e7..d43bc4666 100644
--- a/man/coredns-etcd.7
+++ b/man/coredns-etcd.7
@@ -40,7 +40,7 @@ etcd [ZONES\.\.\.] {
     fallthrough [ZONES\.\.\.]
     path PATH
     endpoint ENDPOINT\.\.\.
-    upstream ADDRESS\.\.\.
+    upstream [ADDRESS\.\.\.]
     tls CERT KEY CACERT
 }
 .
@@ -61,7 +61,7 @@ etcd [ZONES\.\.\.] {
 \fBENDPOINT\fR the etcd endpoints\. Defaults to "http://localhost:2379"\.
 .
 .IP "\(bu" 4
-\fBupstream\fR upstream resolvers to be used resolve external names found in etcd (think CNAMEs) pointing to external names\. If you want CoreDNS to act as a proxy for clients, you\'ll need to add the proxy plugin\. \fBADDRESS\fR can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\.
+\fBupstream\fR upstream resolvers to be used resolve external names found in etcd (think CNAMEs) pointing to external names\. If you want CoreDNS to act as a proxy for clients, you\'ll need to add the proxy plugin\. If no \fBADDRESS\fR is given, CoreDNS will resolve CNAMEs against itself\. \fBADDRESS\fR can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\.
 .
 .IP "\(bu" 4
 \fBtls\fR followed by:
diff --git a/man/coredns-federation.7 b/man/coredns-federation.7
index c172ce9f8..9a74d05d7 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-FEDERATION" "7" "February 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 4daca2bfe..33e4d2f02 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-FILE" "7" "February 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 6db914a03..90ae6bf44 100644
--- a/man/coredns-forward.7
+++ b/man/coredns-forward.7
@@ -7,7 +7,13 @@
 \fIforward\fR facilitates proxying DNS messages to upstream resolvers\.
 .
 .SH "DESCRIPTION"
-The \fIforward\fR plugin is generally faster (~30+%) than \fIproxy\fR as it re\-uses already opened sockets to the upstreams\. It supports UDP, TCP and DNS\-over\-TLS and uses inband health checking that is enabled by default\. When \fIall\fR upstreams are down it assumes healtchecking as a mechanism has failed and will try to connect to a random upstream (which may or may not work)\.
+The \fIforward\fR plugin re\-uses already opened sockets to the upstreams\. It supports UDP, TCP and DNS\-over\-TLS and uses in band health checking\.
+.
+.P
+When it detects an error a health check is performed\. This checks runs in a loop, every \fI0\.5s\fR, for as long as the upstream reports unhealthy\. Once healthy we stop health checking (until the next error)\. The health checks use a recursive DNS query (\fB\. IN NS\fR) to get upstream health\. Any response that is not a network error (REFUSED, NOTIMPL, SERVFAIL, etc) is taken as a healthy upstream\. The health check uses the same protocol as specified in \fBTO\fR\. If \fBmax_fails\fR is set to 0, no checking is performed and upstreams will always be considered healthy\.
+.
+.P
+When \fIall\fR upstreams are down it assumes health checking as a mechanism has failed and will try to connect to a random upstream (which may or may not work)\.
 .
 .SH "SYNTAX"
 In its most basic form, a simple forwarder uses this syntax:
@@ -26,15 +32,12 @@ forward FROM TO\.\.\.
 \fBFROM\fR is the base domain to match for the request to be forwarded\.
 .
 .IP "\(bu" 4
-\fBTO\.\.\.\fR are the destination endpoints to forward to\. The \fBTO\fR syntax allows you to specify a protocol, \fBtls://9\.9\.9\.9\fR or \fBdns://\fR for plain DNS\. The number of upstreams is limited to 15\.
+\fBTO\.\.\.\fR are the destination endpoints to forward to\. The \fBTO\fR syntax allows you to specify a protocol, \fBtls://9\.9\.9\.9\fR or \fBdns://\fR (or no protocol) for plain DNS\. The number of upstreams is limited to 15\.
 .
 .IP "" 0
 .
 .P
-The health checks are done every \fI0\.5s\fR\. After \fItwo\fR failed checks the upstream is considered unhealthy\. The health checks use a recursive DNS query (\fB\. IN NS\fR) to get upstream health\. Any response that is not an error (REFUSED, NOTIMPL, SERVFAIL, etc) is taken as a healthy upstream\. The health check uses the same protocol as specific in the \fBTO\fR\. On startup each upstream is marked unhealthy until it passes a health check\. A 0 duration will disable any health checks\.
-.
-.P
-Multiple upstreams are randomized (default policy) on first use\. When a healthy proxy returns an error during the exchange the next upstream in the list is tried\.
+Multiple upstreams are randomized (see \fBpolicy\fR) on first use\. When a healthy proxy returns an error during the exchange the next upstream in the list is tried\.
 .
 .P
 Extra knobs are available with an expanded syntax:
@@ -46,12 +49,12 @@ Extra knobs are available with an expanded syntax:
 forward FROM TO\.\.\. {
     except IGNORED_NAMES\.\.\.
     force_tcp
-    health_check DURATION
     expire DURATION
     max_fails INTEGER
     tls CERT KEY CA
     tls_servername NAME
     policy random|round_robin
+    health_checks DURATION
 }
 .
 .fi
@@ -68,10 +71,7 @@ forward FROM TO\.\.\. {
 \fBforce_tcp\fR, use TCP even when the request comes in over UDP\.
 .
 .IP "\(bu" 4
-\fBhealth_checks\fR, use a different \fBDURATION\fR for health checking, the default duration is 0\.5s\. A value of 0 disables the health checks completely\.
-.
-.IP "\(bu" 4
-\fBmax_fails\fR is the number of subsequent failed health checks that are needed before considering a backend to be down\. If 0, the backend will never be marked as down\. Default is 2\.
+\fBmax_fails\fR is the number of subsequent failed health checks that are needed before considering an upstream to be down\. If 0, the upstream will never be marked as down (nor health checked)\. Default is 2\.
 .
 .IP "\(bu" 4
 \fBexpire\fR \fBDURATION\fR, expire (cached) connections after this time, the default is 10s\.
@@ -85,10 +85,10 @@ forward FROM TO\.\.\. {
 .IP "\(bu" 4
 \fBpolicy\fR specifies the policy to use for selecting upstream servers\. The default is \fBrandom\fR\.
 .
-.IP "" 0
+.IP "\(bu" 4
+\fBhealth_checks\fR, use a different \fBDURATION\fR for health checking, the default duration is 0\.5s\.
 .
-.P
-The upstream selection is done via random (default policy) selection\. If the socket for this client isn\'t known \fIforward\fR will randomly choose one\. If this turns out to be unhealthy, the next one is tried\. If \fIall\fR hosts are down, we assume health checking is broken and select a \fIrandom\fR upstream to try\.
+.IP "" 0
 .
 .P
 Also note the TLS config is "global" for the whole forwarding proxy if you need a different \fBtls\-name\fR for different upstreams you\'re out of luck\.
@@ -109,7 +109,7 @@ If monitoring is enabled (via the \fIprometheus\fR directive) then the following
 \fBcoredns_forward_healthcheck_failure_count_total{to}\fR \- number of failed health checks per upstream\.
 .
 .IP "\(bu" 4
-\fBcoredns_forward_healthcheck_broken_count_total{}\fR \- counter of when all upstreams are unhealthy, and we are randomly spraying to a target\.
+\fBcoredns_forward_healthcheck_broken_count_total{}\fR \- counter of when all upstreams are unhealthy, and we are randomly (this always uses the \fBrandom\fR policy) spraying to an upstream\.
 .
 .IP "\(bu" 4
 \fBcoredns_forward_socket_count_total{to}\fR \- number of cached sockets per upstream\.
@@ -184,22 +184,7 @@ Proxy everything except \fBexample\.org\fR using the host\'s \fBresolv\.conf\fR\
 .IP "" 0
 .
 .P
-Forward to a IPv6 host:
-.
-.IP "" 4
-.
-.nf
-
-\&\. {
-    forward \. [::1]:1053
-}
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Proxy all requests to 9\.9\.9\.9 using the DNS\-over\-TLS protocol, and cache every answer for up to 30 seconds\.
+Proxy all requests to 9\.9\.9\.9 using the DNS\-over\-TLS protocol, and cache every answer for up to 30 seconds\. Note the \fBtls_servername\fR is mandatory if you want a working setup, as 9\.9\.9\.9 can\'t be used in the TLS negotiation\. Also set the health check duration to 5s to not completely swamp the service with health checks\.
 .
 .IP "" 4
 .
@@ -218,7 +203,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\-name\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_serveraame\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 a54d68b64..548dcfe5d 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-HEALTH" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIhealth\fR \- enables a health check endpoint\.
diff --git a/man/coredns-hosts.7 b/man/coredns-hosts.7
index da981bcdf..aa722f1fe 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-HOSTS" "7" "February 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 147aadc79..647e459fe 100644
--- a/man/coredns-kubernetes.7
+++ b/man/coredns-kubernetes.7
@@ -13,7 +13,7 @@ It implements the Kubernetes DNS\-Based Service Discovery Specification \fIhttps
 CoreDNS running the kubernetes plugin can be used as a replacement of kube\-dns in a kubernetes cluster\. See the deployment \fIhttps://github\.com/coredns/deployment\fR repository for details on how to deploy CoreDNS in Kubernetes \fIhttps://github\.com/coredns/deployment/tree/master/kubernetes\fR\.
 .
 .P
-stubDomains \fIhttp://blog\.kubernetes\.io/2017/04/configuring\-private\-dns\-zones\-upstream\-nameservers\-kubernetes\.html\fR are implemented via the \fIproxy\fR plugin\.
+stubDomains and upstreamNameservers \fIhttp://blog\.kubernetes\.io/2017/04/configuring\-private\-dns\-zones\-upstream\-nameservers\-kubernetes\.html\fR are implemented via the \fIproxy\fR plugin and kubernetes \fIupstream\fR\. See example below\.
 .
 .SH "SYNTAX"
 .
@@ -38,7 +38,7 @@ kubernetes [ZONES\.\.\.] {
     labels EXPRESSION
     pods POD\-MODE
     endpoint_pod_names
-    upstream ADDRESS\.\.\.
+    upstream [ADDRESS\.\.\.]
     ttl TTL
     fallthrough [ZONES\.\.\.]
 }
@@ -81,7 +81,7 @@ kubernetes [ZONES\.\.\.] {
 \fBendpoint_pod_names\fR uses the pod name of the pod targeted by the endpoint as the endpoint name in A records, e\.g\. \fBendpoint\-name\.my\-service\.namespace\.svc\.cluster\.local\. in A 1\.2\.3\.4\fR By default, the endpoint\-name name selection is as follows: Use the hostname of the endpoint, or if hostname is not set, use the dashed form of the endpoint IP address (e\.g\. \fB1\-2\-3\-4\.my\-service\.namespace\.svc\.cluster\.local\.\fR) If this directive is included, then name selection for endpoints changes as follows: Use the hostname of the endpoint, or if hostname is not set, use the pod name of the pod targeted by the endpoint\. If there is no pod targeted by the endpoint, use the dashed IP address form\.
 .
 .IP "\(bu" 4
-\fBupstream\fR \fBADDRESS [ADDRESS\.\.\.]\fR defines the upstream resolvers used for resolving services that point to external hosts (External Services)\. \fBADDRESS\fR can be an IP, an IP:port, or a path to a file structured like resolv\.conf\.
+\fBupstream\fR [\fBADDRESS\fR\.\.\.] defines the upstream resolvers used for resolving services that point to external hosts (aka External Services aka CNAMEs)\. If no \fBADDRESS\fR is given, CoreDNS will resolve External Services against itself\. \fBADDRESS\fR can be an IP, an IP:port, or a path to a file structured like resolv\.conf\.
 .
 .IP "\(bu" 4
 \fBttl\fR allows you to set a custom TTL for responses\. The default (and allowed minimum) is to use 5 seconds, the maximum is capped at 3600 seconds\.
@@ -143,23 +143,18 @@ kubernetes cluster\.local {
 .
 .IP "" 0
 .
-.P
-Here we use the \fIproxy\fR plugin to implement stubDomains that forwards \fBexample\.org\fR and \fBexample\.com\fR to another nameserver\.
+.SH "STUBDOMAINS AND UPSTREAMNAMESERVERS"
+Here we use the \fIproxy\fR plugin to implement a stubDomain that forwards \fBexample\.local\fR to the nameserver \fB10\.100\.0\.10:53\fR\. The \fIupstream\fR option in kubernetes means that ExternalName services (CNAMEs) will be resolved using the respective proxy\. Also configured is an upstreamNameserver \fB8\.8\.8\.8:53\fR that will be used for resolving names that do not fall in \fBcluster\.local\fR or \fBexample\.local\fR\.
 .
 .IP "" 4
 .
 .nf
 
-cluster\.local {
-    kubernetes {
-        endpoint https://k8s\-endpoint:8443
-        tls cert key cacert
+\&\.:53 {
+    kubernetes cluster\.local {
+        upstream
     }
-}
-example\.org {
-    proxy \. 8\.8\.8\.8:53
-}
-example\.com {
+    proxy example\.local 10\.100\.0\.10:53
     proxy \. 8\.8\.8\.8:53
 }
 .
@@ -167,6 +162,22 @@ example\.com {
 .
 .IP "" 0
 .
+.P
+The configuration above represents the following Kube\-DNS stubDomains and upstreamNameservers configuration\.
+.
+.IP "" 4
+.
+.nf
+
+  stubDomains: |
+    {“example\.local”: [“10\.100\.0\.10:53”]}
+  upstreamNameservers: |
+    [“8\.8\.8\.8:53”]
+.
+.fi
+.
+.IP "" 0
+.
 .SH "AUTOPATH"
 The \fIkubernetes\fR plugin can be used in conjunction with the \fIautopath\fR plugin\. Using this feature enables server\-side domain search path completion in kubernetes clusters\. Note: \fBpods\fR must be set to \fBverified\fR for this to function properly\.
 .
@@ -194,10 +205,8 @@ The \fIkubernetes\fR plugin can be used in conjunction with the \fIfederation\fR
 
 cluster\.local {
     federation {
-        fallthrough
         prod prod\.example\.org
         staging staging\.example\.org
-
     }
     kubernetes
 }
diff --git a/man/coredns-loadbalance.7 b/man/coredns-loadbalance.7
index ec1e9da98..9726dc7d0 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-LOADBALANCE" "7" "February 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 a398aaa02..d6f8c29e6 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-LOG" "7" "February 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 cf22f02f2..184c2b9e2 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-METRICS" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIprometheus\fR \- enables Prometheus \fIhttps://prometheus\.io/\fR metrics\.
diff --git a/man/coredns-nsid.7 b/man/coredns-nsid.7
index 049306fd0..c41e2ac98 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-NSID" "7" "February 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 a7ef70a91..377573b82 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-PPROF" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIpprof\fR \- publishes runtime profiling data at endpoints under \fB/debug/pprof\fR\.
diff --git a/man/coredns-proxy.7 b/man/coredns-proxy.7
index 9f1a785ed..4c03678f5 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-PROXY" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIproxy\fR \- facilitates both a basic reverse proxy and a robust load balancer\.
diff --git a/man/coredns-reverse.7 b/man/coredns-reverse.7
index fc5793819..bb6e480ac 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-REVERSE" "7" "February 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 d793611e9..e174ebc50 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-REWRITE" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIrewrite\fR \- performs internal message rewriting\.
diff --git a/man/coredns-root.7 b/man/coredns-root.7
index 2a86d85da..7dcb9c5ab 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-ROOT" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIroot\fR \- simply specifies the root of where to find (zone) files\.
diff --git a/man/coredns-secondary.7 b/man/coredns-secondary.7
index eed20513d..b7fbb9030 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-SECONDARY" "7" "February 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 fdc083118..35ef15cde 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-TEMPLATE" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fItemplate\fR \- allows for dynamic responses based on the incoming query\.
diff --git a/man/coredns-tls.7 b/man/coredns-tls.7
index fddb1d9f7..d232ed30b 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-TLS" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fItls\fR \- allows you to configure the server certificates for the TLS and gRPC servers\.
diff --git a/man/coredns-trace.7 b/man/coredns-trace.7
index 2c94ee712..97ca9645d 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-TRACE" "7" "February 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 191f4100b..175e80a9b 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" "January 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-WHOAMI" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIwhoami\fR \- returns your resolver\'s local IP address, port and transport\.