Manual pages (#1346)

* Add manual pages

Generate manual pages from the README and extend README with Name and
Description sections.

The generation requires 'ronn' which may not be available. Just check in
all generated manual pages.

plugin/auto/README.md

@@ -1,7 +1,10 @@
 # auto
 
-*auto* enables serving zone data from an RFC 1035-style master file which is automatically picked
-up from disk.
+## Name
+
+*auto* - enables serving zone data from an RFC 1035-style master file which is automatically picked up from disk.
+
+## Description
 
 The *auto* 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

plugin/autopath/README.md

@@ -1,6 +1,10 @@
 # autopath
 
-*autopath* allows for server side search path completion.
+## Name
+
+*autopath* - allows for server side search path completion.
+
+## Description
 
 If it sees a query that matches the first element of the configured search path, *autopath* will
 follow the chain of search path elements and returns the first reply that is not NXDOMAIN. On any

plugin/bind/README.md

@@ -1,6 +1,10 @@
 # bind
 
-*bind* overrides the host to which the server should bind.
+## Name
+
+*bind* - overrides the host to which the server should bind.
+
+## 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.

plugin/cache/README.md

@@ -1,6 +1,14 @@
 # cache
 
-*cache* enables a frontend cache. It will cache all records except zone transfers and metadata records.
+## Name
+
+*cache* - enables a frontend cache.
+
+## Description
+
+With *cache* 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.
 
 ## Syntax
 

plugin/chaos/README.md

@@ -1,8 +1,13 @@
 # chaos
 
-*chaos* allows for responding to TXT queries in the CH class.
+## Name
 
-This is useful for retrieving version or author information from the server.
+*chaos* - allows for responding to TXT queries in the CH class.
+
+## Description
+
+This is useful for retrieving version or author information from the server by querying a TXT record
+for a special domainname in the CH class.
 
 ## Syntax
 

plugin/debug/README.md

@@ -1,9 +1,15 @@
 # debug
 
-*debug* disables the automatic recovery upon a crash so that you'll get a nice stack trace.
+## Name
 
-Note that the *errors* plugin (if loaded) will also set a `recover` negating this setting. The main
-use of *debug* is to help testing.
+*debug* - disables the automatic recovery upon a crash so that you'll get a nice stack trace.
+
+## Description
+
+Normally CoreDNS will recover from panics, using *debug* inhibits this. The main use of *debug* is
+to help testing.
+
+Note that the *errors* plugin (if loaded) will also set a `recover` negating this setting. 
 
 ## Syntax
 

plugin/dnssec/README.md

@@ -1,6 +1,14 @@
 # dnssec
 
-*dnssec* enables on-the-fly DNSSEC signing of served data.
+## Name
+
+*dnssec* - enable on-the-fly DNSSEC signing of served data.
+
+## Description
+
+With *dnssec* 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 *not* supported.
 
 ## Syntax
 

plugin/dnstap/README.md

@@ -1,8 +1,16 @@
 # dnstap
 
-*dnstap* enables logging to dnstap, a flexible, structured binary log format for DNS software: http://dnstap.info.
+## Name
 
-There is a buffer, expect at least 13 requests before the server sends its dnstap messages to the socket.
+*dnstap* - enable logging to dnstap
+
+## Description
+
+dnstap is a flexible, structured binary log format for DNS software: http://dnstap.info. With this
+plugin you make CoreDNS output dnstap logging.
+
+Note that there is an internal buffer, so expect at least 13 requests before the server sends its
+dnstap messages to the socket.
 
 ## Syntax
 
@@ -33,14 +41,10 @@ Log to a remote endpoint.
 dnstap tcp://127.0.0.1:6000 full
 ~~~
 
-## Dnstap command line tool
+## Command Line Tool
 
-~~~ sh
-% go get github.com/dnstap/golang-dnstap
-% cd $GOPATH/src/github.com/dnstap/golang-dnstap/dnstap
-% go build
-% ./dnstap
-~~~
+Dnstap has a command line tool that can be used to inspect the logging. The tool can be found
+at Github: <https://github.com/dnstap/golang-dnstap>. It's written in Go.
 
 The following command listens on the given socket and decodes messages to stdout.
 
@@ -59,3 +63,7 @@ Listen for dnstap messages on port 6000.
 ~~~ sh
 % dnstap -l 127.0.0.1:6000
 ~~~
+
+# See Also
+
+[dnstap.info](http://dnstap.info).

plugin/erratic/README.md

@@ -1,8 +1,12 @@
 # erratic
 
-*erratic* is a plugin useful for testing client behavior.
+## Name
 
-It returns a static response to all queries, but the responses can be delayed, dropped or truncated.
+*erratic* - a plugin useful for testing client behavior.
+
+## Description
+
+*erratic* returns a static response to all queries, but the responses can be delayed, dropped or truncated.
 The *erratic* plugin will respond to every A or AAAA query. For any other type it will return
 a SERVFAIL response. The reply for A will return 192.0.2.53 (see RFC 5737), for AAAA it returns
 2001:DB8::53 (see RFC 3849).

plugin/errors/README.md

@@ -1,6 +1,10 @@
 # errors
 
-*errors* enables error logging.
+## Name
+
+*errors* - enable error logging.
+
+## Description
 
 Any errors encountered during the query processing will be printed to standard output.
 

plugin/etcd/README.md

@@ -1,6 +1,12 @@
 # etcd
 
-*etcd* enables reading zone data from an etcd instance. The data in etcd has to be encoded as
+## Name
+
+*etcd* - enables reading zone data from an etcd instance.
+
+## Description
+
+The data in etcd has to be encoded as
 a [message](https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26)
 like [SkyDNS](https://github.com/skynetservices/skydns). It should also work just like SkyDNS.
 
@@ -41,10 +47,13 @@ etcd [ZONES...] {
   the proxy plugin. **ADDRESS** can be an IP address, and IP:port or a string pointing to a file
   that is structured as /etc/resolv.conf.
 * `tls` followed by:
-  * no arguments, if the server certificate is signed by a system-installed CA and no client cert is needed
-  * a single argument that is the CA PEM file, if the server cert is not signed by a system CA and no client cert is needed
-  * two arguments - path to cert PEM file, the path to private key PEM file - if the server certificate is signed by a system-installed CA and a client certificate is needed
-  * three arguments - path to cert PEM file, path to client private key PEM file, path to CA PEM file - if the server certificate is not signed by a system-installed CA and client certificate is needed
+
+    * no arguments, if the server certificate is signed by a system-installed CA and no client cert is needed
+    * a single argument that is the CA PEM file, if the server cert is not signed by a system CA and no client cert is needed
+    * two arguments - path to cert PEM file, the path to private key PEM file - if the server certificate is signed by a system-installed CA and a client certificate is needed
+    * three arguments - path to cert PEM file, path to client private key PEM file, path to CA PEM
+      file - if the server certificate is not signed by a system-installed CA and client certificate
+      is needed.
 
 ## Examples
 
@@ -114,3 +123,7 @@ Querying with dig:
 % dig @localhost -x 10.0.0.127 +short
 reverse.skydns.local.
 ~~~
+
+# Bugs
+
+Only the etcdv2 protocol is supported.

plugin/federation/README.md

@@ -1,7 +1,13 @@
 # federation
 
-*federation* enables
-[federated](https://kubernetes.io/docs/tasks/federation/federation-service-discovery/) queries to be
+## Name
+
+*federation* - enables federated queries to be resolved via the kubernetes plugin.
+
+## Description
+
+Enabling this plugin allows
+[Federated](https://kubernetes.io/docs/tasks/federation/federation-service-discovery/) queries to be
 resolved via the kubernetes plugin.
 
 Enabling *federation* without also having *kubernetes* is a noop.
@@ -11,6 +17,7 @@ Enabling *federation* without also having *kubernetes* is a noop.
 ~~~
 federation [ZONES...] {
     NAME DOMAIN
+}
 ~~~
 
 * Each **NAME** and **DOMAIN** defines federation membership. One entry for each. A duplicate

plugin/file/README.md

@@ -1,6 +1,10 @@
 # file
 
-*file* enables serving zone data from an RFC 1035-style master file.
+## Name
+
+*file* - enables serving zone data from an RFC 1035-style master file.
+
+## Description
 
 The file 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

plugin/health/README.md

@@ -1,8 +1,13 @@
 # health
 
-*health* enables a simple health check endpoint.
+## Name
 
-By default, it listens on port 8080.
+*health* - enables a health check endpoint.
+
+## Description
+
+By enabling *health* any plugin that implements it will be queried for it's health. The combined
+health is exported, by default, on port 8080/health .
 
 ## Syntax
 

plugin/hosts/README.md

@@ -1,6 +1,10 @@
 # hosts
 
-*hosts* enables serving zone data from a `/etc/hosts` style file.
+## Name
+
+*hosts* - enables serving zone data from a `/etc/hosts` style file.
+
+## Description
 
 The hosts plugin is useful for serving zones from a /etc/hosts file. It serves from a preloaded
 file that exists on disk. It checks the file for changes and updates the zones accordingly. This

plugin/kubernetes/README.md

@@ -1,6 +1,10 @@
 # kubernetes
 
-The *kubernetes* plugin enables the reading zone data from a Kubernetes cluster.
+## Name
+
+*kubernetes* - enables the reading zone data from a Kubernetes cluster.
+
+## Description
 
 It implements the [Kubernetes DNS-Based Service Discovery
 Specification](https://github.com/kubernetes/dns/blob/master/docs/specification.md).
@@ -66,15 +70,15 @@ kubernetes [ZONES...] {
      option requires substantially more memory than in insecure mode, since it will maintain a watch
      on all pods.
 
-* `endpoint_pod_names` uses the pod name of the pod targeted by the endpoint as 
+* `endpoint_pod_names` uses the pod name of the pod targeted by the endpoint as
    the endpoint name in A records, e.g.
    `endpoint-name.my-service.namespace.svc.cluster.local. in A 1.2.3.4`
-   By default, the endpoint-name name selection is as follows: Use the hostname 
+   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. `1-2-3-4.my-service.namespace.svc.cluster.local.`)
    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 
+   pod name of the pod targeted by the endpoint. If there is no pod targeted by
    the endpoint, use the dashed IP address form.
 * `upstream` **ADDRESS [ADDRESS...]** defines the upstream resolvers used for resolving services
   that point to external hosts (External Services).  **ADDRESS** can be an IP, an IP:port, or a path
@@ -174,11 +178,8 @@ feature enables serving federated domains from the kubernetes clusters.
 Some query labels accept a wildcard value to match any value.  If a label is a valid wildcard (\*,
 or the word "any"), then that label will match all values.  The labels that accept wildcards are:
 
- * _service_ in an `A` record request: _service_.namespace.svc.zone.
-   * e.g. `*.ns.svc.myzone.local`
- * _namespace_ in an `A` record request: service._namespace_.svc.zone.
-   * e.g. `nginx.*.svc.myzone.local`
- * _port and/or protocol_ in an `SRV` request: __port_.__protocol_.service.namespace.svc.zone.
-   * e.g. `_http.*.service.ns.svc.`
- * multiple wild cards are allowed in a single query.
-   * e.g. `A` Request `*.*.svc.zone.` or `SRV` request `*.*.*.*.svc.zone.`
+ * _service_ in an `A` record request: _service_.namespace.svc.zone, e.g. `*.ns.svc.myzone.local`
+ * _namespace_ in an `A` record request: service._namespace_.svc.zone, e.g. `nginx.*.svc.myzone.local`
+ * _port and/or protocol_ in an `SRV` request: __port_.__protocol_.service.namespace.svc.zone.,
+   e.g. `_http.*.service.ns.svc.`
+ * multiple wild cards are allowed in a single query, e.g. `A` Request `*.*.svc.zone.` or `SRV` request `*.*.*.*.svc.zone.`

plugin/loadbalance/README.md

@@ -1,7 +1,11 @@
 # loadbalance
 
-*loadbalance* acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records
+## Name
+
+*loadbalance* - acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records
  in the answer.
+
+## Description
  
  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

plugin/log/README.md

@@ -1,6 +1,15 @@
 # log
 
-*log* enables query logging to standard output.
+## Name
+
+*log* - enables query logging to standard output.
+
+## Description
+
+By just using *log* you dump all queries (and parts for the reply) on standard output. Options exist
+to tweak the output a little.
+
+Note that for busy servers this will incur a performance hit.
 
 ## Syntax
 

plugin/metrics/README.md

@@ -1,7 +1,12 @@
 # prometheus
 
-*prometheus* enables [Prometheus](https://prometheus.io/) metrics.
+## Name
 
+*prometheus* - enables [Prometheus](https://prometheus.io/) metrics.
+
+## Description
+
+With *prometheus* you export metrics from CoreDNS and any plugin that has them.
 The default location for the metrics is `localhost:9153`. The metrics path is fixed to `/metrics`.
 The following metrics are exported:
 

plugin/nsid/README.md

@@ -1,6 +1,10 @@
 # nsid
 
-*nsid* adds an identifier of this server to each reply.
+## Name
+
+*nsid* - adds an identifier of this server to each reply.
+
+## Description
 
 This plugin implements RFC 5001 and adds an EDNS0 OPT resource record to replies that uniquely
 identify the server. This is useful in anycast setups to see which server was responsible for

plugin/pprof/README.md

@@ -1,6 +1,10 @@
 # pprof
 
-*pprof* publishes runtime profiling data at endpoints under `/debug/pprof`.
+## Name
+
+*pprof* - publishes runtime profiling data at endpoints under `/debug/pprof`.
+
+## Description
 
 You can visit `/debug/pprof` on your site for an index of the available endpoints. By default it
 will listen on localhost:6053.
@@ -45,3 +49,8 @@ Listen on an all addresses on port 6060:
     pprof :6060
 }
 ~~~
+
+# Also See
+
+See [Go's pprof documentation](https://golang.org/pkg/net/http/pprof/) and [Profiling Go
+Programs](https://blog.golang.org/profiling-go-programs).

plugin/proxy/README.md

@@ -1,6 +1,10 @@
 # proxy
 
-*proxy* facilitates both a basic reverse proxy and a robust load balancer.
+## Name
+
+*proxy* - facilitates both a basic reverse proxy and a robust load balancer.
+
+## Description
 
 The proxy has support for multiple backends. The load balancing features include multiple policies,
 health checks, and failovers. If all hosts fail their health check the proxy plugin will fail
@@ -72,28 +76,30 @@ Currently `protocol` supports `dns` (i.e., standard DNS over UDP/TCP) and `https
 payload over HTTPS). Note that with `https_google` the entire transport is encrypted. Only *you* and
 *Google* can see your DNS activity.
 
-* `dns`: uses the standard DNS exchange. You can pass `force_tcp` to make sure that the proxied connection is performed
-  over TCP, regardless of the inbound request's protocol.
-* `https_google`: bootstrap **ADDRESS...** is used to (re-)resolve `dns.google.com` to an address to
-  connect to. This happens every 300s. If not specified the default is used: 8.8.8.8:53/8.8.4.4:53.
-  Note that **TO** is *ignored* when `https_google` is used, as its upstream is defined as
-  `dns.google.com`.
+`dns`
+:   uses the standard DNS exchange. You can pass `force_tcp` to make sure that the proxied connection is performed
+    over TCP, regardless of the inbound request's protocol.
+
+`grpc`
+:   extra options are used to control how the TLS connection is made to the gRPC server.
 
-  Debug queries are enabled by default and currently there is no way to turn them off. When CoreDNS
-  receives a debug query (i.e. the name is prefixed with `o-o.debug.`) a TXT record with Comment
-  from `dns.google.com` is added. Note this is not always set.
-* `grpc`: options are used to control how the TLS connection is made to the gRPC server.
   * None - No client authentication is used, and the system CAs are used to verify the server certificate.
   * `insecure` - TLS is not used, the connection is made in plaintext (not good in production).
   * **CACERT** - No client authentication is used, and the file **CACERT** is used to verify the server certificate.
   * **KEY** **CERT** - Client authentication is used with the specified key/cert pair. The server
-    certificate is verified with the system CAs.
+     certificate is verified with the system CAs.
   * **KEY** **CERT** **CACERT** - Client authentication is used with the specified key/cert pair. The
-    server certificate is verified using the **CACERT** file.
-
+     server certificate is verified using the **CACERT** file.
   An out-of-tree plugin that implements the server side of this can be found at
   [here](https://github.com/infobloxopen/coredns-grpc).
 
+`https_google`
+:    bootstrap **ADDRESS...** is used to (re-)resolve `dns.google.com`.
+
+    This happens every 300s. If not specified the default is used: 8.8.8.8:53/8.8.4.4:53.
+    Note that **TO** is *ignored* when `https_google` is used, as its upstream is defined as `dns.google.com`.
+
+
 ## Metrics
 
 If monitoring is enabled (via the *prometheus* directive) then the following metric is exported:

plugin/reverse/README.md

@@ -1,6 +1,13 @@
 # reverse
 
-*reverse* allows for dynamic responses to PTR and the related A/AAAA requests.
+## Name
+
+*reverse* - allows for dynamic responses to PTR and the related A/AAAA requests.
+
+## Description
+
+If a request matches a regular expression (see Template Syntax below) this plugin will generate a
+response. This is only done for "address" records (PTR, A and AAAA).
 
 ## Syntax
 

plugin/rewrite/README.md

@@ -1,6 +1,10 @@
 # rewrite
 
-*rewrite* performs internal message rewriting.
+## Name
+
+*rewrite* - performs internal message rewriting.
+
+## Description
 
 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.
@@ -28,7 +32,7 @@ When the FIELD is `edns0` an EDNS0 option can be appended to the request as desc
 
 If you specify multiple rules and an incoming query matches on multiple rules, the rewrite
 will behave as following
-* `continue` will continue apply the next rule in the rule list. 
+* `continue` will continue apply the next rule in the rule list.
 * `stop` will consider the current rule is the last rule and will not continue.  Default behaviour
 for not specifying this rule processing mode is `stop`
 
@@ -42,9 +46,9 @@ Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the
 
 Currently supported are `EDNS0_LOCAL`, `EDNS0_NSID` and `EDNS0_SUBNET`.
 
-### `EDNS0_LOCAL`
+### 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.  
+This has two fields, code and data. A match is defined as having the same code. Data may be a string or a variable.
 
 * A string data can be treated as hex if it starts with `0x`. Example:
 
@@ -64,13 +68,7 @@ rewrites the first local option with code 0xffee, setting the data to "abcd". Eq
 ~~~
 
 * A variable data is specified with a pair of curly brackets `{}`. Following are the supported variables:
-    * {qname}
-    * {qtype}
-    * {client_ip}
-    * {client_port}
-    * {protocol}
-    * {server_ip}
-    * {server_port}
+  {qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}.
 
 Example:
 
@@ -78,15 +76,15 @@ Example:
 rewrite edns0 local set 0xffee {client_ip}
 ~~~
 
-### `EDNS0_NSID`
+### 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 `replace` or `set`, then the NSID in the option will be set to the empty string.
 
-### `EDNS0_SUBNET`
+### 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. 
+length is used to extract the client subnet from the source IP address in the query.
 
 Example:
 
@@ -109,7 +107,7 @@ The syntax for the name re-writing is as follows:
 rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
 ```
 
-The match type, i.e. `exact`, `substring`, etc., triggers re-write: 
+The match type, i.e. `exact`, `substring`, etc., triggers re-write:
 
 * **exact** (default): on exact match of the name in the question section of a request
 * **substring**: on a partial match of the name in the question section of a request
@@ -127,6 +125,7 @@ rewrite name substring service.us-west-1.example.org service.us-west-1.consul
 ```
 
 Thus:
+
 * Incoming Request Name: `ftp.service.us-west-1.example.org`
 * Re-written Request Name: `ftp.service.us-west-1.consul`
 
@@ -139,5 +138,6 @@ rewrite name regex (.*)-(us-west-1)\.example\.org {1}.service.{2}.consul
 ```
 
 Thus:
+
 * Incoming Request Name: `ftp-us-west-1.example.org`
 * Re-written Request Name: `ftp.service.us-west-1.consul`

plugin/root/README.md

@@ -1,9 +1,13 @@
 # root
 
-*root* simply specifies the root of where to find (zone) files.
+## Name
 
-The default root is the current working directory of CoreDNS. A relative root path is relative to
-the current working directory.
+*root* - simply specifies the root of where to find (zone) files.
+
+## Description
+
+The default root is the current working directory of CoreDNS. The *root* plugin allows you to change
+this. A relative root path is relative to the current working directory.
 
 ## Syntax
 

plugin/secondary/README.md

@@ -1,8 +1,14 @@
 # secondary
 
-*secondary* enables serving a zone retrieved from a primary server.
+## Name
 
-## Syntax
+*secondary* - enables serving a zone retrieved from a primary server.
+
+## Description
+
+With *secondary* you can transfer (via AXFR) a zone from another server. The retrieved zone is
+*not committed* to disk (a violation of the RFC). This means restarting CoreDNS will cause it to
+ retrieve all secondary zones.
 
 ~~~
 secondary [ZONES...]
@@ -52,3 +58,7 @@ Or re-export the retrieved zone to other secondaries.
     }
 }
 ~~~
+
+# Bugs
+
+Only AXFR is supported and the retrieved zone is not committed to disk.

plugin/tls/README.md

@@ -1,7 +1,10 @@
 # tls
 
-*tls* allows you to configure the server certificates for the TLS and gRPC servers.
-For other types of servers it is ignored.
+## Name
+
+*tls* - allows you to configure the server certificates for the TLS and gRPC servers.
+
+## Description
 
 CoreDNS supports queries that are encrypted using TLS (DNS over Transport Layer Security, RFC 7858)
 or are using gRPC (https://grpc.io/, not an IETF standard). Normally DNS traffic isn't encrypted at

plugin/trace/README.md

@@ -1,6 +1,12 @@
 # trace
 
-*trace* enables OpenTracing-based tracing of DNS requests as they go through the plugin chain.
+## Name
+
+*trace* - enables OpenTracing-based tracing of DNS requests as they go through the plugin chain.
+
+## Description
+
+With *trace* you enable OpenTracing of how a request flows through CoreDNS.
 
 ## Syntax
 

plugin/whoami/README.md

@@ -1,9 +1,14 @@
 # whoami
 
-*whoami* returns your resolver's local IP address, port and transport. Your IP address is returned
- in the additional section as either an A or AAAA record.
+## Name
 
-When CoreDNS can not find a Corefile to load, this is the default plugin it loads.
+*whoami* - returns your resolver's local IP address, port and transport. 
+
+## Description
+
+The *whoami* plugin is not really that useful, but can be used for having a simple (fast) endpoint
+to test clients against. When *whoami* returns a response it will have your client's IP address the
+additional section as either an A or AAAA record.
 
 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".
@@ -12,12 +17,12 @@ section as a SRV record, transport can be "tcp" or "udp".
 ._<transport>.qname. 0 IN SRV 0 0 <port> .
 ~~~
 
-If CoreDNS can't find a Corefile on startup this is the *default* plugin that gets loaded. As
-such it can be used to check that CoreDNS is responding to queries. Other than that this plugin
-is of limited use in production.
-
 The *whoami* plugin will respond to every A or AAAA query, regardless of the query name.
 
+If CoreDNS can't find a Corefile on startup this is the _default_ plugin that gets loaded. As such
+it can be used to check that CoreDNS is responding to queries. Other than that this plugin is of
+limited use in production.
+
 ## Syntax
 
 ~~~ txt