Doc updates

Remove miek.nl in favor of example.org and other smaller cleanups.

4 files changed, 31 insertions, 26 deletions

diff --git a/README.md b/README.md
index 47824aeb2..f21dbcb59 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,8 @@ Currently CoreDNS is able to:
 * Has support for the CH class: `version.bind` and friends (middleware/chaos).
 * Profiling support (middleware/pprof).
 
+Each of the middlewares has a README.md of their own.
+
 ## Status
 
 I'm using CoreDNS is my primary, authoritative, nameserver for my domains (`miek.nl`, `atoom.net`
@@ -49,7 +51,7 @@ Caddyfile when I forked it).
 
 ## Compilation
 
-CoreDNS (as a servertype plugin for Caddy) has a hard dependency on Caddy - this is *almost* like
+CoreDNS (as a servertype plugin for Caddy) has a dependency on Caddy - this is *almost* like
 the normal Go dependencies, but with a small twist, caddy (the source) need to know that CoreDNS
 exists and for this we need to add 1 line `_ "github.com/miekg/coredns/core"` to file in caddy.
 
@@ -58,8 +60,8 @@ dependencies:
 
     go get ./...
 
-Then, execute `go generate`, this will patch Caddy to add CoreDNS, and then `go build` as you would
-normally do:
+Then, execute `go generate`, this will patch Caddy to add CoreDNS (and remove the HTTP server
+plugin), and then `go build` as you would normally do:
 
     go generate
     go build
@@ -68,34 +70,36 @@ Should yield a `coredns` binary.
 
 ## Examples
 
-Start a simple proxy:
+Start a simple proxy, you'll need to be root to start listening on port 53.
 
 `Corefile` contains:
 
 ~~~ txt
-.:1053 {
+.:53 {
     proxy . 8.8.8.8:53
+    log stdout
 }
 ~~~
 
 Just start CoreDNS: `./coredns`.
-And then just query on that port (1053), the query should be forwarded to 8.8.8.8 and the response
-will be returned.
+And then just query on that port (53), the query should be forwarded to 8.8.8.8 and the response
+will be returned. Each query should also show up in the log.
 
-Serve the (NSEC) DNSSEC signed `miek.nl` on port 1053, errors and logging to stdout. Allow zone
-transfers to everybody.
+Serve the (NSEC) DNSSEC signed `example.org` on port 1053, errors and logging to stdout. Allow zone
+transfers to everybody, but specically mention 1 IP address so that CoreDNS can send notifies to it.
 
 ~~~ txt
-miek.nl:1053 {
-    file /var/lib/bind/miek.nl.signed {
+example.org:1053 {
+    file /var/lib/coredns/example.org.signed {
         transfer to *
+        transfer to 2001:500:8f::53
     }
     errors stdout
     log stdout
 }
 ~~~
 
-Serve `miek.nl` on port 1053, but forward everything that does *not* match `miek.nl` to a recursive
+Serve `example.org` on port 1053, but forward everything that does *not* match `example.org` to a recursive
 nameserver *and* rewrite ANY queries to HINFO.
 
 ~~~ txt
@@ -103,22 +107,23 @@ nameserver *and* rewrite ANY queries to HINFO.
     rewrite ANY HINFO
     proxy . 8.8.8.8:53
 
-    file /var/lib/bind/miek.nl.signed miek.nl {
+    file /var/lib/coredns/example.org.signed example.org {
         transfer to *
+        transfer to 2001:500:8f::53
     }
     errors stdout
     log stdout
 }
 ~~~
 
-All the above examples are possible with the *current* CoreDNS.
 
-## What remains to be done
+## What Remains To Be Done
 
 * Optimizations.
 * Load testing.
 * The [issues](https://github.com/miekg/coredns/issues).
 
+
 ## Blog and Contact
 
 Website: <https://coredns.io>
@@ -127,15 +132,15 @@ Docs: <https://miek.nl/tags/coredns/>
 Github: <https://github.com/miekg/coredns>
 
 
-## Systemd service file
+## Systemd Service File
 
 Use this as a systemd service file. It defaults to a coredns wich a homedir of /home/coredns
-and the binary lives in /opt/bin:
+and the binary lives in /opt/bin and the config in `/etc/coredns/Corefile`:
 
 ~~~ txt
 [Unit]
 Description=CoreDNS DNS server
-Documentation=https://miek.nl/tags/coredns
+Documentation=https://coredns.io
 After=network.target
 
 [Service]
diff --git a/middleware/cache/README.md b/middleware/cache/README.md
index 5a6964ce8..187fc0ff3 100644
--- a/middleware/cache/README.md
+++ b/middleware/cache/README.md
@@ -12,17 +12,16 @@ cache [ttl] [zones...]
   answer section) will be used.
 * `zones` zones it should should cache for. If empty the zones from the configuration block are used.
 
-
 Each element in the cache is cached according to its TTL, for the negative cache the SOA's MinTTL
 value is used.
 
 A cache mostly makes sense with a middleware that is potentially slow, i.e. a proxy that retrieves
 answer, or to minimize backend queries for middleware like etcd. Using a cache with the file
-middleware essentially doubles the memory load with no concealable increase of query speed.
+middleware essentially doubles the memory load with no conceivable increase of query speed.
 
 The minimum TTL allowed on resource records is 5 seconds.
 
-If monitoring is enabled (`prometheus` directive) then the following metrics are added:
+If monitoring is enabled (`prometheus` directive) then the following extra metrics are added:
 * coredns_cache_hit_count_total, and
 * coredns_cache_miss_count_total
 
@@ -38,7 +37,7 @@ Enable caching for all zones, but cap everything to a TTL of 10 seconds.
 
 ~~~
 proxy . 8.8.8.8:53
-cache miek.nl
+cache example.org
 ~~~
 
-Proxy to Google Public DNS and only cache responses for miek.nl (or below).
+Proxy to Google Public DNS and only cache responses for example.org (or below).
diff --git a/middleware/chaos/README.md b/middleware/chaos/README.md
index 82c4ae4dd..7cc211268 100644
--- a/middleware/chaos/README.md
+++ b/middleware/chaos/README.md
@@ -1,7 +1,7 @@
 # chaos
 
 The `chaos` middleware allows CoreDNS to response to TXT queries in CH class.
-Useful for retrieving version or author information from the server. If 
+Useful for retrieving version or author information from the server.
 
 ## Syntax
 
@@ -9,7 +9,7 @@ Useful for retrieving version or author information from the server. If
 chaos [version] [authors...]
 ~~~
 
-* `version` the version to return, defaults to CoreDNS.
+* `version` the version to return, defaults to CoreDNS-<version>, if not set.
 * `authors` what authors to return. No default.
 
 Note that you have to make sure that this middleware will get actual queries for the
diff --git a/middleware/loadbalance/README.md b/middleware/loadbalance/README.md
index 5c381135d..4d8f25a8e 100644
--- a/middleware/loadbalance/README.md
+++ b/middleware/loadbalance/README.md
@@ -4,7 +4,8 @@
 message. 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.
+It will take care to sort any CNAMEs before any address records, because some stub resolver
+implementation (like glibc) can't handle that.
 
 ## Syntax