TrueCloudLab/coredns
16
0
Fork 2
Code Issues Pull requests 4 Projects Releases Packages Wiki Activity Actions

doc update (#1140)

Browse source 
* 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
This commit is contained in:
Miek Gieben 2017-10-10 09:39:35 +02:00 • committed by GitHub
parent 7c6ba3fcbd
commit 427aed6f5b
17 changed files with 112 additions and 88 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
README.md
View file

@ -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
}
~~~

8
plugin/auto/README.md
View file

@ -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*

2
plugin/autopath/README.md
View file

@ -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.

17
plugin/cache/README.md vendored
View file

@ -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).

4
plugin/debug/README.md
View file

@ -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

18
plugin/dnssec/README.md
View file

@ -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

14
plugin/dnstap/README.md
View file

@ -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
~~~

12
plugin/etcd/README.md
View file

@ -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.
~~~

6
plugin/health/README.md
View file

@ -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
}
~~~

6
plugin/hosts/README.md
View file

@ -29,8 +29,10 @@ hosts [FILE [ZONES...]] {
Load `/etc/hosts` file.
~~~
hosts
~~~ corefile
. {
hosts
}
~~~
Load `example.hosts` file in the current directory.

1
plugin/kubernetes/README.md
View file

@ -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.

9
plugin/loadbalance/README.md
View file

@ -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
}
~~~

35
plugin/log/README.md
View file

@ -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
}
}
~~~

15
plugin/metrics/README.md
View file

@ -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
~~~

14
plugin/pprof/README.md
View file

@ -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
}
~~~

16
plugin/rewrite/README.md
View file

@ -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.

2
plugin/whoami/README.md
View file

@ -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".