doc update (#1140)

* doc update Go through all README and fix mistakes, extend example and let more corefile snippets be test for validity. * Cant use spefic addr in test
2025-10-30 17:53:21 -04:00 · 2017-10-10 09:39:35 +02:00
parent 7c6ba3fcbd
commit 427aed6f5b
17 changed files with 112 additions and 88 deletions
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ the same model: it chains plugins.
 CoreDNS is a [Cloud Native Computing Foundation](https://cncf.io) inception level project.

 CoreDNS is the successor to [SkyDNS](https://github.com/skynetservices/skydns). SkyDNS is a thin
-layer that exposes services in etcd in the DNS. CoreDNS builds on this idea and is a generic DNS
+layer that exposes services in etcd in the DNS. CoreDNS builds on this idea and is a **generic** DNS
 server that can talk to multiple backends (etcd, kubernetes, etc.).

 CoreDNS aims to be a fast and flexible DNS server. The keyword here is *flexible*: with CoreDNS you
@@ -43,7 +43,8 @@ Currently CoreDNS is able to:
 * Rewrite queries (qtype, qclass and qname) (*rewrite*).
 * Echo back the IP address, transport and port number used (*whoami*).

-Each of the plugins has a README.md of its own.
+Each of the plugins has a README.md of its own, see [coredns.io/plugins](https://coredns.io/plugins)
+for all in-tree plugins.

 ## Status

@@ -54,9 +55,8 @@ here](https://coredns.io). If you do want to use CoreDNS in production, please l

 ## Compilation

-CoreDNS (as a servertype plugin for Caddy) has a dependency on Caddy, but this is not different than
-any other Go dependency. If you have the source of CoreDNS checked out in the appropriate place in
-your `GOPATH`, get all dependencies:
+If you have the source of CoreDNS checked out in the appropriate place in your `GOPATH`, get all
+dependencies:

    go get ./...

@@ -82,7 +82,8 @@ The above command alone will have `coredns` binary generated.

 ## Examples

-When starting CoreDNS without any configuration, it loads the `whoami` plugin and starts
+When starting CoreDNS without any configuration, it loads the
+[*whoami*](https://coredns.io/plugins/whoami) plugin and starts
 listening on port 53 (override with `-dns.port`), it should show the following:

 ~~~ txt
@@ -147,9 +148,9 @@ nameserver *and* rewrite ANY queries to HINFO.

 IP addresses are also allowed. They are automatically converted to reverse zones:

-~~~ txt
+~~~ corefile
 10.0.0.0/24 {
-    # ...
+    whoami
 }
 ~~~
 Means you are authoritative for `0.0.10.in-addr.arpa.`.
@@ -160,9 +161,9 @@ dot: `10.0.0.0/24.` as this also stops the conversion.

 Listening on TLS and for gRPC? Use:

-~~~ txt
+~~~ corefile
 tls://example.org grpc://example.org {
-    # ...
+    whoami
 }
 ~~~

--- a/plugin/auto/README.md
+++ b/plugin/auto/README.md
@@ -37,9 +37,11 @@ are used.
 All directives from the *file* plugin are supported. Note that *auto* will load all zones found,
 even though the directive might only receive queries for a specific zone. I.e:

-~~~
-auto example.org {
-    directory /etc/coredns/zones
+~~~ corefile
+. {
+    auto example.org {
+        directory /etc/coredns/zones
+    }
 }
 ~~~
 Will happily pick up a zone for `example.COM`, except it will never be queried, because the *auto*
--- a/plugin/autopath/README.md
+++ b/plugin/autopath/README.md
@@ -11,7 +11,7 @@ element in it) to the name of this answer.
 ## Syntax

 ~~~
-autopath [ZONE..] RESOLV-CONF
+autopath [ZONE...] RESOLV-CONF
 ~~~

 * **ZONES** zones *autopath* should be authoritative for.
--- a/plugin/cache/README.md
+++ b/plugin/cache/README.md
@@ -10,7 +10,7 @@ cache [TTL] [ZONES...]

 * **TTL** max TTL in seconds. If not specified, the maximum TTL will be used which is 3600 for
    noerror responses and 1800 for denial of existence ones.
-    Setting a TTL of 300 *cache 300* would cache the record up to 300 seconds.
+    Setting a TTL of 300: `cache 300` would cache the record up to 300 seconds.
 * **ZONES** zones it should cache for. If empty, the zones from the configuration block are used.

 Each element in the cache is cached according to its TTL (with **TTL** as the max).
@@ -45,10 +45,10 @@ The minimum TTL allowed on resource records is 5 seconds.

 If monitoring is enabled (via the *prometheus* directive) then the following metrics are exported:

-* coredns_cache_size{type} - Total elements in the cache by cache type.
-* coredns_cache_capacity{type} - Total capacity of the cache by cache type.
-* coredns_cache_hits_total{type} - Counter of cache hits by cache type.
-* coredns_cache_misses_total - Counter of cache misses.
+* `coredns_cache_size{type}` - Total elements in the cache by cache type.
+* `coredns_cache_capacity{type}` - Total capacity of the cache by cache type.
+* `coredns_cache_hits_total{type}` - Counter of cache hits by cache type.
+* `coredns_cache_misses_total{}` - Counter of cache misses.

 Cache types are either "denial" or "success".

@@ -56,8 +56,11 @@ Cache types are either "denial" or "success".

 Enable caching for all zones, but cap everything to a TTL of 10 seconds:

-~~~
-cache 10
+~~~ corefile
+. {
+    cache 10
+    whoami
+}
 ~~~

 Proxy to Google Public DNS and only cache responses for example.org (or below).
--- a/plugin/debug/README.md
+++ b/plugin/debug/README.md
@@ -2,8 +2,8 @@

 *debug* disables the automatic recovery upon a CoreDNS crash so that you'll get a nice stack trace.

-Note that the *errors* plugin (if loaded) will also set a `recover` negating this setting.
-The main use of *debug* is to help testing.
+Note that the *errors* plugin (if loaded) will also set a `recover` negating this setting. The main
+use of *debug* is to help testing.

 ## Syntax

--- a/plugin/dnssec/README.md
+++ b/plugin/dnssec/README.md
@@ -17,33 +17,31 @@ Authenticated denial of existence is implemented with NSEC black lies. Using ECD
 is preferred as this leads to smaller signatures (compared to RSA). NSEC3 is *not* supported.

 If multiple *dnssec* plugins are specified in the same zone, the last one specified will be
-used ( see [bugs](#bugs) ).
+used (See [bugs](#bugs)).

-* `ZONES` zones that should be signed. If empty, the zones from the configuration block
+* **ZONES** zones that should be signed. If empty, the zones from the configuration block
    are used.

-* `key file` indicates that key file(s) should be read from disk. When multiple keys are specified, RRsets
+* `key file` indicates that **KEY** file(s) should be read from disk. When multiple keys are specified, RRsets
  will be signed with all keys. Generating a key can be done with `dnssec-keygen`: `dnssec-keygen -a
  ECDSAP256SHA256 <zonename>`. A key created for zone *A* can be safely used for zone *B*. The name of the
  key file can be specified as one of the following formats

    * basename of the generated key `Kexample.org+013+45330`
-
    * generated public key `Kexample.org+013+45330.key`
-
    * generated private key `Kexample.org+013+45330.private`

 * `cache_capacity` indicates the capacity of the cache. The dnssec plugin uses a cache to store
-  RRSIGs. The default capacity is 10000.
+  RRSIGs. The default for **CAPACITY** is 10000.

 ## Metrics

 If monitoring is enabled (via the *prometheus* directive) then the following metrics are exported:

-* coredns_dnssec_cache_size{type} - total elements in the cache, type is "signature".
-* coredns_dnssec_cache_capacity{type} - total capacity of the cache, type is "signature".
-* coredns_dnssec_cache_hits_total - Counter of cache hits.
-* coredns_dnssec_cache_misses_total - Counter of cache misses.
+* `coredns_dnssec_cache_size{type}` - total elements in the cache, type is "signature".
+* `coredns_dnssec_cache_capacity{type}` - total capacity of the cache, type is "signature".
+* `coredns_dnssec_cache_hits_total{}` - Counter of cache hits.
+* `coredns_dnssec_cache_misses_total{}` - Counter of cache misses.

 ## Examples

--- a/plugin/dnstap/README.md
+++ b/plugin/dnstap/README.md
@@ -36,26 +36,26 @@ dnstap tcp://127.0.0.1:6000 full
 ## Dnstap command line tool

 ~~~ sh
-go get github.com/dnstap/golang-dnstap
-cd $GOPATH/src/github.com/dnstap/golang-dnstap/dnstap
-go build
-./dnstap
+% go get github.com/dnstap/golang-dnstap
+% cd $GOPATH/src/github.com/dnstap/golang-dnstap/dnstap
+% go build
+% ./dnstap
 ~~~

 The following command listens on the given socket and decodes messages to stdout.

 ~~~ sh
-dnstap -u /tmp/dnstap.sock
+% dnstap -u /tmp/dnstap.sock
 ~~~

 The following command listens on the given socket and saves message payloads to a binary dnstap-format log file.

 ~~~ sh
-dnstap -u /tmp/dnstap.sock -w /tmp/test.dnstap
+% dnstap -u /tmp/dnstap.sock -w /tmp/test.dnstap
 ~~~

 Listen for dnstap messages on port 6000.

 ~~~ sh
-dnstap -l 127.0.0.1:6000
+% dnstap -l 127.0.0.1:6000
 ~~~
--- a/plugin/etcd/README.md
+++ b/plugin/etcd/README.md
@@ -4,8 +4,8 @@
 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.

-The etcd plugin makes extensive use of the proxy plugin to forward and query other servers
-in the network.
+The etcd plugin makes extensive use of the proxy plugin to forward and query other servers in the
+network.

 ## Syntax

@@ -15,8 +15,8 @@ etcd [ZONES...]

 * **ZONES** zones etcd should be authoritative for.

-The path will default to `/skydns` 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 `/skydns` the local etcd proxy (http://localhost:2379). If no zones are
+specified the block's zone will be used as the zone.

 If you want to `round robin` A and AAAA responses look at the `loadbalance` plugin.

@@ -103,7 +103,7 @@ Next you'll need to populate the zone with reverse records, here we add a revers

 Querying with dig:

-~~~
+~~~ sh
 % dig @localhost -x 10.0.0.127 +short
-reverse.atoom.net.
+reverse.skydns.local.
 ~~~
--- a/plugin/health/README.md
+++ b/plugin/health/README.md
@@ -18,6 +18,8 @@ supports health checks has a section "Health" in their README.

 Run another health endpoint on http://localhost:8091.

-~~~
-health localhost:8091
+~~~ corefile
+. {
+    health localhost:8091
+}
 ~~~
--- a/plugin/hosts/README.md
+++ b/plugin/hosts/README.md
@@ -29,8 +29,10 @@ hosts [FILE [ZONES...]] {

 Load `/etc/hosts` file.

-~~~
-hosts
+~~~ corefile
+. {
+    hosts
+}
 ~~~

 Load `example.hosts` file in the current directory.
--- a/plugin/kubernetes/README.md
+++ b/plugin/kubernetes/README.md
@@ -36,6 +36,7 @@ kubernetes [ZONES...] {
    fallthrough
 }
 ```
+
 * `resyncperiod` specifies the Kubernetes data API **DURATION** period.
 * `endpoint` specifies the **URL** for a remove k8s API endpoint.
   If omitted, it will connect to k8s in-cluster using the cluster service account.
--- a/plugin/loadbalance/README.md
+++ b/plugin/loadbalance/README.md
@@ -17,6 +17,11 @@ loadbalance [POLICY]

 ## Examples

-~~~
-loadbalance round_robin
+Load balance replies coming back from Google Public DNS:
+
+~~~ corefile
+. {
+    loadbalance round_robin
+    proxy . 8.8.8.8 8.8.4.4
+}
 ~~~
--- a/plugin/log/README.md
+++ b/plugin/log/README.md
@@ -11,23 +11,22 @@ log
 * With no arguments, a query log entry is written to *stdout* in the common log format for all requests

 ~~~ txt
-log FILE
+log [stdout]
 ~~~

-* **FILE** is the log file to create (or append to). The *only* valid name for **FILE** is *stdout*.
+Or if you want/need slightly more control:

 ~~~ txt
-log [NAME] FILE [FORMAT]
+log [NAME] stdout [FORMAT]
 ~~~

 * `NAME` is the name to match in order to be logged
-* `FILE` is the log file (again only *stdout* is allowed here).
 * `FORMAT` is the log format to use (default is Common Log Format)

 You can further specify the class of responses that get logged:

 ~~~ txt
-log [NAME] FILE [FORMAT] {
+log [NAME] stdout [FORMAT] {
    class [success|denial|error|all]
 }
 ~~~
@@ -43,11 +42,6 @@ classes have the following meaning:

 If no class is specified, it defaults to *all*.

-## Log File
-
-The "log file" can only be *stdout*. CoreDNS expects another service to pick up this output and deal
-with it, i.e. journald when using systemd or Docker's logging capabilities.
-
 ## Log Format

 You can specify a custom log format with any placeholder values. Log supports both request and
@@ -83,20 +77,27 @@ The default Common Log Format is:

 Log all requests to stdout

-~~~
-log stdout
+~~~ corefile
+. {
+    log
+    whoami
+}
 ~~~

 Custom log format, for all zones (`.`)

-~~~
-log . stdout "{proto} Request: {name} {type} {>id}"
+~~~ corefile
+. {
+    log . stdout "{proto} Request: {name} {type} {>id}"
+}
 ~~~

 Only log denials for example.org (and below to a file)

-~~~
-log example.org stdout {
-    class denial
+~~~ corefile
+. {
+    log example.org stdout {
+        class denial
+    }
 }
 ~~~
--- a/plugin/metrics/README.md
+++ b/plugin/metrics/README.md
@@ -5,13 +5,13 @@
 The default location for the metrics is `localhost:9153`. The metrics path is fixed to `/metrics`.
 The following metrics are exported:

-* coredns_dns_request_count_total{zone, proto, family}
-* coredns_dns_request_duration_milliseconds{zone}
-* coredns_dns_request_size_bytes{zone, proto}
-* coredns_dns_request_do_count_total{zone}
-* coredns_dns_request_type_count_total{zone, type}
-* coredns_dns_response_size_bytes{zone, proto}
-* coredns_dns_response_rcode_count_total{zone, rcode}
+* `coredns_dns_request_count_total{zone, proto, family}` - total query count.
+* `coredns_dns_request_duration_milliseconds{zone}` - duration to process each query.
+* `coredns_dns_request_size_bytes{zone, proto}` - size of the request in bytes.
+* `coredns_dns_request_do_count_total{zone}` -  queries that have the DO bit set
+* `coredns_dns_request_type_count_total{zone, type}` - counter of queries per zone and type.
+* `coredns_dns_response_size_bytes{zone, proto}` - response size in bytes.
+* `coredns_dns_response_rcode_count_total{zone, rcode}` - response per zone and rcode.

 Each counter has a label `zone` which is the zonename used for the request/response.

@@ -27,7 +27,6 @@ Extra labels used are:
 If monitoring is enabled, queries that do not enter the plugin chain are exported under the fake
 name "dropped" (without a closing dot - this is never a valid domain name).

-
 ## Syntax

 ~~~
--- a/plugin/pprof/README.md
+++ b/plugin/pprof/README.md
@@ -6,7 +6,7 @@ You can visit `/debug/pprof` on your site for an index of the available endpoint
 will listen on localhost:6053.

 > This is a debugging tool. Certain requests (such as collecting execution traces) can be slow. If
-> you use pprof on a live site, consider restricting access or enabling it only temporarily.
+> you use pprof on a live server, consider restricting access or enabling it only temporarily.

 For more information, please see [Go's pprof
 documentation](https://golang.org/pkg/net/http/pprof/) and read
@@ -25,12 +25,14 @@ If not specified, ADDRESS defaults to localhost:6053.
 Enable pprof endpoints:

 ~~~
-pprof
+. {
+    pprof
+}
 ~~~

 Listen on an alternate address:

-~~~
+~~~ txt
 . {
    pprof 10.9.8.7:6060
 }
@@ -38,6 +40,8 @@ Listen on an alternate address:

 Listen on an all addresses on port 6060:

-~~~
-pprof :6060
+~~~ txt
+. {
+    pprof :6060
+}
 ~~~
--- a/plugin/rewrite/README.md
+++ b/plugin/rewrite/README.md
@@ -48,14 +48,19 @@ This has two fields, code and data. A match is defined as having the same code.

 * A string data can be treated as hex if it starts with `0x`. Example:

-~~~
-rewrite edns0 local set 0xffee 0x61626364
+~~~ corefile
+. {
+    rewrite edns0 local set 0xffee 0x61626364
+    whoami
+}
 ~~~

 rewrites the first local option with code 0xffee, setting the data to "abcd". Equivalent:

-~~~
-rewrite edns0 local set 0xffee abcd
+~~~ corefile
+. {
+    rewrite edns0 local set 0xffee abcd
+}
 ~~~

 * A variable data is specified with a pair of curly brackets `{}`. Following are the supported variables:
@@ -86,9 +91,8 @@ length is used to extract the client subnet from the source IP address in the qu
 Example:

 ~~~
-   rewrite edns0 subnet set 24 56
+rewrite edns0 subnet set 24 56
 ~~~

 * If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet.
 * If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet.
-
--- a/plugin/whoami/README.md
+++ b/plugin/whoami/README.md
@@ -3,6 +3,8 @@
 *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.

+When CoreDNS can find a Corefile to load, this is the default plugin it loads.
+
 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".