Docs (#1943)

* Doc updates

Make the name section fit on one line.
Signed-off-by: Miek Gieben <miek@miek.nl>

* Regen docs
Signed-off-by: Miek Gieben <miek@miek.nl>

man/coredns-debug.7

 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-DEBUG" "7" "June 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-DEBUG" "7" "July 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIdebug\fR \- disables the automatic recovery upon a crash so that you\'ll get a nice stack trace\.
@@ -20,6 +20,28 @@ debug
 .
 .fi
 .
+.P
+Some plugin will debug log DNS messages\. This is done in the following format:
+.
+.IP "" 4
+.
+.nf
+
+debug: 000000 00 0a 01 00 00 01 00 00 00 00 00 01 07 65 78 61
+debug: 000010 6d 70 6c 65 05 6c 6f 63 61 6c 00 00 01 00 01 00
+debug: 000020 00 29 10 00 00 00 80 00 00 00
+debug: 00002a
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Using \fBtext2pcap\fR (part of Wireshark) this can be converted back to binary, with the following command line: \fBtext2pcap \-i 17 \-u 53,53\fR\. Where 17 is the protocol (UDP) and 53 are the ports\. These ports allow wireshark to detect these packets as DNS messages\.
+.
+.P
+Each plugin can decide to dump messages to aid in debugging\.
+.
 .SH "EXAMPLES"
 Disable the ability to recover from crashes and show debug logging:
 .
@@ -34,4 +56,6 @@ Disable the ability to recover from crashes and show debug logging:
 .fi
 .
 .IP "" 0
-
+.
+.SH "ALSO SEE"
+https://www\.wireshark\.org/docs/man\-pages/text2pcap\.html\.

man/coredns-dnstap.7

 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-DNSTAP" "7" "June 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-DNSTAP" "7" "July 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
-\fIdnstap\fR \- enable logging to dnstap
+\fIdnstap\fR \- enable logging to dnstap\.
 .
 .SH "DESCRIPTION"
 dnstap is a flexible, structured binary log format for DNS software: http://dnstap\.info\. With this plugin you make CoreDNS output dnstap logging\.

man/coredns-etcd.7

 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-ETCD" "7" "June 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-ETCD" "7" "July 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
-\fIetcd\fR \- enables reading zone data from an etcd instance\.
+\fIetcd\fR \- enables reading zone data from an etcd version 3 instance\.
 .
 .SH "DESCRIPTION"
-The data in etcd has to be encoded as a message \fIhttps://github\.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service\.go#L26\fR like SkyDNS \fIhttps://github\.com/skynetservices/skydns\fR\. It should also work just like SkyDNS\.
+The data in etcd instance has to be encoded as a message \fIhttps://github\.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service\.go#L26\fR like SkyDNS \fIhttps://github\.com/skynetservices/skydns\fR\. It should also work just like SkyDNS\.
 .
 .P
 The etcd plugin makes extensive use of the proxy plugin to forward and query other servers in the network\.
@@ -26,7 +26,7 @@ etcd [ZONES\.\.\.]
 .IP "" 0
 .
 .P
-The path will default to \fB/skydns\fR the local etcd proxy (http://localhost:2379)\. If no zones are specified the block\'s zone will be used as the zone\.
+The path will default to \fB/skydns\fR the local etcd3 proxy (http://localhost:2379)\. If no zones are specified the block\'s zone will be used as the zone\.
 .
 .P
 If you want to \fBround robin\fR A and AAAA responses look at the \fBloadbalance\fR plugin\.
@@ -83,6 +83,15 @@ three arguments \- path to cert PEM file, path to client private key PEM file, p
 .
 .IP "" 0
 .
+.SH "SPECIAL BEHAVIOUR"
+CoreDNS etcd plugin leverages directory structure to look for related entries\. For example an entry \fB/skydns/test/skydns/mx\fR would have entries like \fB/skydns/test/skydns/mx/a\fR, \fB/skydns/test/skydns/mx/b\fR and so on\. Similarly a directory \fB/skydns/test/skydns/mx1\fR will have all \fBmx1\fR entries\.
+.
+.P
+With etcd3, support for hierarchial keys are dropped \fIhttps://coreos\.com/etcd/docs/latest/learning/api\.html\fR\. This means there are no directories but only flat keys with prefixes in etcd3\. To accomodate lookups, etcdv3 plugin now does a lookup on prefix \fB/skydns/test/skydns/mx/\fR to search for entries like \fB/skydns/test/skydns/mx/a\fR etc, and if there is nothing found on \fB/skydns/test/skydns/mx/\fR, it looks for \fB/skydns/test/skydns/mx\fR to find entries like \fB/skydns/test/skydns/mx1\fR\.
+.
+.P
+This causes two lookups from CoreDNS to etcdv3 in certain cases\.
+.
 .SH "EXAMPLES"
 This is the default SkyDNS setup, with everying specified in full:
 .
@@ -235,6 +244,3 @@ If you would like to use \fBAAAA\fR records for the zone name too, you can set t
 .
 .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\.

man/coredns-loadbalance.7

 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-LOADBALANCE" "7" "June 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-LOADBALANCE" "7" "July 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\.
+\fIloadbalance\fR \- randomize the order of A and AAAA records\.
 .
 .SH "DESCRIPTION"
+The \fIloadbalance\fR will act as a round\-robin DNS loadbalancer by randomizing the order of A and AAAA records in the answer\.
+.
+.P
 See Wikipedia \fIhttps://en\.wikipedia\.org/wiki/Round\-robin_DNS\fR about the pros and cons on this setup\. It will take care to sort any CNAMEs before any address records, because some stub resolver implementations (like glibc) are particular about that\.
 .
 .SH "SYNTAX"
@@ -18,7 +21,7 @@ loadbalance [POLICY]
 .fi
 .
 .IP "\(bu" 4
-\fBPOLICY\fR is how to balance, the default is "round_robin"
+\fBPOLICY\fR is how to balance, the default, and only option, is "round_robin"\.
 .
 .IP "" 0
 .
@@ -31,7 +34,7 @@ Load balance replies coming back from Google Public DNS:
 
 \&\. {
     loadbalance round_robin
-    proxy \. 8\.8\.8\.8 8\.8\.4\.4
+    forward \. 8\.8\.8\.8 8\.8\.4\.4
 }
 .
 .fi

man/coredns-reload.7

 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-RELOAD" "7" "June 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-RELOAD" "7" "July 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
-\fIreload\fR \- allows automatic reload of a changed Corefile
+\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\.

man/coredns-rewrite.7

 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-REWRITE" "7" "June 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-REWRITE" "7" "July 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIrewrite\fR \- performs internal message rewriting\.

man/coredns-whoami.7

 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-WHOAMI" "7" "June 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-WHOAMI" "7" "July 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIwhoami\fR \- returns your resolver\'s local IP address, port and transport\.
 .
 .SH "DESCRIPTION"
-The \fIwhoami\fR plugin is not really that useful, but can be used for having a simple (fast) endpoint to test clients against\. When \fIwhoami\fR returns a response it will have your client\'s IP address the additional section as either an A or AAAA record\.
+The \fIwhoami\fR plugin is not really that useful, but can be used for having a simple (fast) endpoint to test clients against\. When \fIwhoami\fR returns a response it will have your client\'s IP address in the additional section as either an A or AAAA record\.
 .
 .P
 The reply always has an empty answer section\. The port and transport are included in the additional section as a SRV record, transport can be "tcp" or "udp"\.

plugin/dnstap/README.md

@@ -2,7 +2,7 @@
 
 ## Name
 
-*dnstap* - enable logging to dnstap
+*dnstap* - enable logging to dnstap.
 
 ## Description
 

plugin/loadbalance/README.md

@@ -2,14 +2,16 @@
 
 ## Name
 
-*loadbalance* - acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records
- in the answer.
+*loadbalance* - randomize the order of A and AAAA records.
 
 ## Description
+
+The *loadbalance* will act as a round-robin DNS loadbalancer by randomizing the order of A and AAAA
+records in the answer.
  
- See [Wikipedia](https://en.wikipedia.org/wiki/Round-robin_DNS) about the pros and cons on this
- setup. It will take care to sort any CNAMEs before any address records, because some stub resolver
- implementations (like glibc) are particular about that.
+See [Wikipedia](https://en.wikipedia.org/wiki/Round-robin_DNS) about the pros and cons on this
+setup. It will take care to sort any CNAMEs before any address records, because some stub resolver
+implementations (like glibc) are particular about that.
 
 ## Syntax
 
@@ -17,7 +19,7 @@
 loadbalance [POLICY]
 ~~~
 
-* **POLICY** is how to balance, the default is "round_robin"
+* **POLICY** is how to balance, the default, and only option, is "round_robin".
 
 ## Examples
 
@@ -26,6 +28,6 @@ Load balance replies coming back from Google Public DNS:
 ~~~ corefile
 . {
     loadbalance round_robin
-    proxy . 8.8.8.8 8.8.4.4
+    forward . 8.8.8.8 8.8.4.4
 }
 ~~~

plugin/reload/README.md

@@ -2,7 +2,7 @@
 
 ## Name
 
-*reload* - allows automatic reload of a changed Corefile
+*reload* - allows automatic reload of a changed Corefile.
 
 ## Description