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

Documentation updates (#340)

Browse source
This commit is contained in:
Miek Gieben 2016-10-18 07:47:18 +01:00 • committed by GitHub
parent a6b033a936
commit 89a2912c87
2 changed files with 41 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
README.md
View file

@ -16,22 +16,24 @@ are able to do what you want with your DNS data. And if not: write some middlewa
Currently CoreDNS is able to: Currently CoreDNS is able to:
* Serve zone data from a file; both DNSSEC (NSEC only) and DNS are supported (middleware/file). * Serve zone data from a file; both DNSSEC (NSEC only) and DNS are supported (*file*).
* Retrieve zone data from primaries, i.e., act as a secondary server (AXFR only) (middleware/secondary). * Retrieve zone data from primaries, i.e., act as a secondary server (AXFR only) (*secondary*).
* Sign zone data on-the-fly (middleware/dnssec). * Sign zone data on-the-fly (*dnssec*).
* Load balancing of responses (middleware/loadbalance). * Load balancing of responses (*loadbalance*).
* Allow for zone transfers, i.e., act as a primary server (middleware/file). * Allow for zone transfers, i.e., act as a primary server (*file*).
* Caching (middleware/cache). * Automatically load zone files from disk (*auto*)
* Health checking (middleware/health). * Caching (*cache*).
* Health checking endpoint (*health*).
* Use etcd as a backend, i.e., a 101.5% replacement for * Use etcd as a backend, i.e., a 101.5% replacement for
[SkyDNS](https://github.com/skynetservices/skydns) (middleware/etcd). [SkyDNS](https://github.com/skynetservices/skydns) (*etcd*).
* Use k8s (kubernetes) as a backend (middleware/kubernetes). * Use k8s (kubernetes) as a backend (*kubernetes*).
* Serve as a proxy to forward queries to some other (recursive) nameserver (middleware/proxy). * Serve as a proxy to forward queries to some other (recursive) nameserver (*proxy*).
* Rewrite queries (qtype, qclass and qname) (middleware/rewrite). * Provide metrics (by using Prometheus) (*metrics*).
* Provide metrics (by using Prometheus) (middleware/metrics). * Provide query (*log*) and error (*error*) logging.
* Provide Logging (middleware/log). * Support the CH class: `version.bind` and friends (*chaos*).
* Support the CH class: `version.bind` and friends (middleware/chaos). * Profiling support (*pprof*).
* Profiling support (middleware/pprof). * Rewrite queries (qtype, qclass and qname) (*rewrite*).
* Echo back the IP address, transport and port number used (*whoami*).
Each of the middlewares has a README.md of its own. Each of the middlewares has a README.md of its own.
@ -45,11 +47,11 @@ things fast and to reduce the memory usage.
All in all, CoreDNS should be able to provide you with enough functionality to replace parts of BIND All in all, CoreDNS should be able to provide you with enough functionality to replace parts of BIND
9, Knot, NSD or PowerDNS and SkyDNS. Most documentation is in the source and some blog articles can 9, Knot, NSD or PowerDNS and SkyDNS. Most documentation is in the source and some blog articles can
be [found here](https://miek.nl/tags/coredns/). If you do want to use CoreDNS in production, please be [found here](https://blog.coredns.io). If you do want to use CoreDNS in production, please
let us know and how we can help. let us know and how we can help.
<https://caddyserver.com/> is also full of examples on how to structure a Corefile (renamed from <https://caddyserver.com/> is also full of examples on how to structure a Corefile (renamed from
Caddyfile when I forked it). Caddyfile when forked).
## Compilation ## Compilation
@ -67,17 +69,29 @@ This should yield a `coredns` binary.
## Examples ## Examples
When starting CoreDNS without any configuration, it loads the `whoami` middleware and starts When starting CoreDNS without any configuration, it loads the `whoami` middleware and starts
listening on port 2053, it should show the following: listening on port 53 (override with `-dns.port`), it should show the following:
~~~ txt ~~~ txt
.:2053 .:53
2016/09/18 09:20:50 [INFO] CoreDNS-001 2016/09/18 09:20:50 [INFO] CoreDNS-001
CoreDNS-001 CoreDNS-001
~~~ ~~~
Any query send to port 2053 should return some information; your sending address, port and protocol Any query send to port 53 should return some information; your sending address, port and protocol
used. used.
If you have a Corefile without a port number specified it will, by default, use port 53, but you
can override the port with the `-dns.port` flag:
~~~ txt
.: {
proxy . 8.8.8.8:53
log stdout
}
~~~
`./coredns -dns.port 1053`, runs the server on port 1053.
Start a simple proxy, you'll need to be root to start listening on port 53. Start a simple proxy, you'll need to be root to start listening on port 53.
`Corefile` contains: `Corefile` contains:

9
middleware.md
View file

@ -33,7 +33,12 @@ something has been written to the client (by the middleware).
TODO(miek): text here on how to hook up middleware. TODO(miek): text here on how to hook up middleware.
# Documentation ## Metrics
When exporting metrics the *Namespace* should be `middleware.Namespace` (="coredns"), and the
*Subsystem* should be the name of the middleware.
## Documentation
Each middleware should have a README.md explaining what the middleware does and how it is Each middleware should have a README.md explaining what the middleware does and how it is
configured. The file should have the following layout: configured. The file should have the following layout:
@ -44,7 +49,7 @@ configured. The file should have the following layout:
More sections are of course possible. More sections are of course possible.
## Style ### Style
We use the Unix manual page style: We use the Unix manual page style: