Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2025-12-06 10:25:10 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #229 from cricketliu/master

Browse Source 
Some grammatical fixes to various README.md files
This commit is contained in:
Miek Gieben
2016-08-22 22:35:33 +01:00
committed by GitHub
parent 5318e1084b af6ebb7cd9
commit 7ac8ce952d
13 changed files with 78 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@@ -1,47 +1,47 @@
# CoreDNS
CoreDNS is DNS server that started as a fork of [Caddy](https://github.com/mholt/caddy/). It has the
same model: it chains middleware. In fact to similar that CoreDNS is now a server type plugin for
CAddy, i.e. you'll need Caddy to compile CoreDNS.
CoreDNS is a DNS server that started as a fork of [Caddy](https://github.com/mholt/caddy/). It has the
same model: it chains middleware. In fact it's so similar that CoreDNS is now a server type plugin for
Caddy, i.e., you'll need Caddy to compile CoreDNS.
CoreDNS is the successor of [SkyDNS](https://github.com/skynetservices/skydns). SkyDNS is a thin
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
server that can talk to multiple backends (etcd, consul, kubernetes, etc.).
CoreDNS aims to be a fast and flexible DNS server. The keyword here is *flexible*, with CoreDNS you
are able to do what you want with your DNS data. And if not: write a middleware!
CoreDNS aims to be a fast and flexible DNS server. The keyword here is *flexible*: with CoreDNS you
are able to do what you want with your DNS data. And if not: write some middleware!
Currently CoreDNS is able to:
* Serve zone data from a file, both DNSSEC (NSEC only) and DNS is supported (middleware/file).
* Retrieve zone data from primaries, i.e. act as a secondary server (AXFR only) (middleware/secondary).
* Serve zone data from a file; both DNSSEC (NSEC only) and DNS are supported (middleware/file).
* Retrieve zone data from primaries, i.e., act as a secondary server (AXFR only) (middleware/secondary).
* Sign zone data on-the-fly (middleware/dnssec).
* Loadbalancing of responses (middleware/loadbalance).
* Allow for zone transfers, i.e. act as a primary server (middleware/file).
* Load balancing of responses (middleware/loadbalance).
* Allow for zone transfers, i.e., act as a primary server (middleware/file).
* Caching (middleware/cache).
* Health checking (middleware/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).
* Use k8s (kubernetes) as a backend (middleware/kubernetes).
* Serve as a proxy to forward queries to some other (recursive) nameserver (middleware/proxy).
* Rewrite queries (both qtype, qclass and qname) (middleware/rewrite).
* Rewrite queries (qtype, qclass and qname) (middleware/rewrite).
* Provide metrics (by using Prometheus) (middleware/metrics).
* Provide Logging (middleware/log).
* Has support for the CH class: `version.bind` and friends (middleware/chaos).
* Support the CH class: `version.bind` and friends (middleware/chaos).
* Profiling support (middleware/pprof).
Each of the middlewares has a README.md of their own.
Each of the middlewares has a README.md of its own.
## Status
I'm using CoreDNS is my primary, authoritative, nameserver for my domains (`miek.nl`, `atoom.net`
and a few others). CoreDNS should be stable enough to provide you with a good DNS(SEC) service.
and a few others). CoreDNS should be stable enough to provide you with good DNS(SEC) service.
There are still few [issues](https://github.com/miekg/coredns/issues), and work is ongoing on making
things fast and reduce the memory usage.
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
BIND9, Knot, NSD or PowerDNS and SkyDNS.
BIND 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 let us
know and how we can help.
@@ -52,7 +52,7 @@ Caddyfile when I forked it).
## Compilation
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
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.
You have the source of CoreDNS, this should preferably be downloaded under your `$GOPATH`. Get all
@@ -60,13 +60,13 @@ dependencies:
go get ./...
Then, execute `go generate`, this will patch Caddy to add CoreDNS (and remove the HTTP server
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
Should yield a `coredns` binary.
This should yield a `coredns` binary.
## Examples
@@ -82,10 +82,10 @@ Start a simple proxy, you'll need to be root to start listening on port 53.
~~~
Just start CoreDNS: `./coredns`.
And then just query on that port (53), the query should be forwarded to 8.8.8.8 and the response
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 `example.org` on port 1053, errors and logging to stdout. Allow zone
Serve the (NSEC) DNSSEC-signed `example.org` on port 1053, with errors and logging sent to stdout. Allow zone
transfers to everybody, but specically mention 1 IP address so that CoreDNS can send notifies to it.
~~~ txt

14
middleware/cache/README.md vendored
View File

@@ -8,24 +8,24 @@
cache [ttl] [zones...]
~~~
* `ttl` max TTL in seconds, if not specified the TTL of the reply (SOA minimum or minimum TTL in the
* `ttl` max TTL in seconds. If not specified, the TTL of the reply (SOA minimum or minimum TTL in the
answer section) will be used.
* `zones` zones it should should cache for. If empty the zones from the configuration block are used.
* `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, for the negative cache the SOA's MinTTL
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
A cache mostly makes sense with a middleware that is potentially slow (e.g., a proxy that retrieves an
answer), or to minimize backend queries for middleware like etcd. Using a cache with the file
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 extra metrics are added:
If monitoring is enabled (via the `prometheus` directive) then the following extra metrics are added:
* coredns_cache_hit_count_total, and
* coredns_cache_miss_count_total
They both work on a per zone basis and just count the hit and miss counts for each query.
They both work on a per-zone basis and just count the hit and miss counts for each query.
## Examples

6
middleware/chaos/README.md
View File

@@ -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.
The `chaos` middleware allows CoreDNS to respond to TXT queries in the CH class.
This is 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.
chaos [version] [authors...]
~~~
* `version` the version to return, defaults to CoreDNS-<version>, if not set.
* `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

10
middleware/dnssec/README.md
View File

@@ -8,18 +8,18 @@
dnssec [zones...]
~~~
* `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.
If keys are not specified (see below) a key is generated and used for all signing operations. The
DNSSEC signing will treat this key a CSK (common signing key) forgoing the ZSK/KSK split. All
If keys are not specified (see below), a key is generated and used for all signing operations. The
DNSSEC signing will treat this key a CSK (common signing key), forgoing the ZSK/KSK split. All
signing operations are done online. 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).
A signing key can be specified by using the `key` directive.
WARNING: when a key is generated there is currently no way to extract any key material from CoreDNS,
WARNING: when a key is generated there is currently no way to extract any key material from CoreDNS, as
this key only lives in memory. See issue <https://github.com/miekg/coredns/issues/211>.
TODO(miek): think about key rollovers.
@@ -31,7 +31,7 @@ dnssec [zones... ] {
}
~~~
* `key file` indicates key file(s) should be read from disk. When multiple keys are specified, RRset
* `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*.

6
middleware/errors/README.md
View File

@@ -2,7 +2,7 @@
`errors` allows you to set custom error pages and enable error logging.
By default, error responses (HTTP status >= 400) are not logged and the client receives a plaintext error message.
Using an error log, the text of each error will be recorded so you can determine what is going wrong without exposing those details to the clients. With error pages, you can present custom error messages and instruct your visitor what to do.
Using an error log, the text of each error will be recorded so you can determine what is going wrong without exposing those details to the clients. With error pages, you can present custom error messages and instruct your visitor with what to do.
## Syntax
@@ -11,7 +11,7 @@ Using an error log, the text of each error will be recorded so you can determine
errors [logfile]
~~~
* `logfile` is the path to the error log file to create (or append to), relative to the current working directory. It can also be stdout or stderr to write to the console, syslog to write to the system log (except on Windows), or visible to write the error (including full stack trace, if applicable) to the response. Writing errors to the response is NOT advised except in local debug situations. Default is stderr.
* `logfile` is the path to the error log file to create (or append to), relative to the current working directory. It can also be stdout or stderr to write to the console, syslog to write to the system log (except on Windows), or visible to write the error (including full stack trace, if applicable) to the response. Writing errors to the response is NOT advised except in local debug situations. The default is stderr.
The above syntax will simply enable error reporting on the server. To specify custom error pages, open a block:
~~~
@@ -20,7 +20,7 @@ errors {
}
~~~
* `what` can only `log`.
* `what` can only be `log`.
* `where` is the path to the log file (as described above) and you can enable rotation to manage the log files.
## Examples

20
middleware/etcd/README.md
View File

@@ -1,6 +1,6 @@
# etcd
`etcd` enabled reading zone data from an etcd instance. The data in etcd has to be encoded as
`etcd` enables reading zone data from an etcd instance. 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.
@@ -31,16 +31,16 @@ etcd [zones...] {
}
~~~
* `stubzones` enable the stub zones feature. The stubzone is *only* done in the etcd tree located
* `stubzones` enables the stub zones feature. The stubzone is *only* done in the etcd tree located
under the *first* zone specified.
* `path` the path inside etcd, defaults to "/skydns".
* `endpoint` the etcd endpoints, default to "http://localhost:2397".
* `upstream` upstream resolvers to be used resolve external names found in etcd, think CNAMEs
pointing to external names. If you want CoreDNS to act as a proxy for clients you'll need to add
* `path` the path inside etcd. Defaults to "/skydns".
* `endpoint` the etcd endpoints. Defaults to "http://localhost:2397".
* `upstream` upstream resolvers to be used resolve external names found in etcd (think CNAMEs)
pointing to external names. If you want CoreDNS to act as a proxy for clients, you'll need to add
the proxy middleware.
* `tls` followed the cert, key and the CA's cert filenames.
* `debug` allow debug queries. Prefix the name with `o-o.debug.` to retrieve extra information in the
additional section of the reply in the form of text records.
additional section of the reply in the form of TXT records.
## Examples
@@ -65,11 +65,11 @@ This is the default SkyDNS setup, with everying specified in full:
Reverse zones are supported. You need to make CoreDNS aware of the fact that you are also
authoritative for the reverse. For instance if you want to add the reverse for 10.0.0.0/24, you'll
need to add the zone `10.in-addr.arpa` to the list of zones (the fun starts with reverse IPv6 zones
in the ip6.arpa domain). Showing a snippet of a Corefile:
need to add the zone `0.0.10.in-addr.arpa` to the list of zones. (The fun starts with IPv6 reverse zones
in the ip6.arpa domain.) Showing a snippet of a Corefile:
~~~
etcd skydns.local 10.in-addr.arpa {
etcd skydns.local 0.0.10.in-addr.arpa {
stubzones
...
~~~

8
middleware/file/README.md
View File

@@ -1,8 +1,8 @@
# file
`file` enables serving zone data from a RFC-1035 styled file.
`file` enables serving zone data from an RFC 1035-style master file.
The file middleware is used for "old-style" DNS server. It serves from a preloaded file that exists
The file middleware is used for an "old-style" DNS server. It serves from a preloaded file that exists
on disk.
## Syntax
@@ -12,7 +12,7 @@ file dbfile [zones...]
~~~
* `dbfile` the database file to read and parse.
* `zones` zones it should be authoritative for. If empty the zones from the configuration block
* `zones` zones it should be authoritative for. If empty, the zones from the configuration block
are used.
If you want to round robin A and AAAA responses look at the `loadbalance` middleware.
@@ -30,7 +30,7 @@ file dbfile [zones... ] {
* `transfer` enables zone transfers. It may be specified multiples times. *To* or *from* signals
the direction. Addresses must be denoted in CIDR notation (127.0.0.1/32 etc.) or just as plain
address. The special wildcard "*" means: the entire internet (only valid for 'transfer to').
addresses. The special wildcard "*" means: the entire internet (only valid for 'transfer to').
* `no_reload` by default CoreDNS will reload a zone from disk whenever it detects a change to the
file. This option disables that behavior.

4
middleware/health/README.md
View File

@@ -13,8 +13,8 @@ Caddy bug](https://github.com/mholt/caddy/issues/675).
health
~~~
It optionally takes an address, the default is `:8080`. The health path is fixed to `/health`. It
will just return "OK", when CoreDNS is healthy.
Optionally takes an address; the default is `:8080`. The health path is fixed to `/health`. It
will just return "OK" when CoreDNS is healthy.
This middleware only needs to be enabled once.

16
middleware/kubernetes/README.md
View File

@@ -46,7 +46,7 @@ This is the default kubernetes setup, with everything specified in full:
# Only expose the k8s namespace "demo"
namespaces demo
# Only expose the records for kubernetes objects
# that matches this label selector. The label
# that match this label selector. The label
# selector syntax is described in the kubernetes
# API documentation: http://kubernetes.io/docs/user-guide/labels/
# Example selector below only exposes objects tagged as
@@ -54,7 +54,7 @@ This is the default kubernetes setup, with everything specified in full:
labels environment in (staging, qa),application=nginx
}
# Perform DNS response caching for the coredns.local zone
# Cache timeout is provided by the integer in seconds
# Cache timeout is specified by an integer in seconds
#cache 180 coredns.local
}
~~~
@@ -63,7 +63,7 @@ Defaults:
* If the `namespaces` keyword is omitted, all kubernetes namespaces are exposed.
* If the `template` keyword is omitted, the default template of "{service}.{namespace}.{zone}" is used.
* If the `resyncperiod` keyword is omitted, the default resync period is 5 minutes.
* The `labels` keyword is only used when filtering of results based on kubernetes label selector syntax
* The `labels` keyword is only used when filtering results based on kubernetes label selector syntax
is required. The label selector syntax is described in the kubernetes API documentation at:
http://kubernetes.io/docs/user-guide/labels/
@@ -127,7 +127,7 @@ The command to launch CoreDNS is:
$ ./coredns -conf conf/k8sCoreFile
~~~
In a separate terminal a dns query can be issued using dig:
In a separate terminal a DNS query can be issued using dig:
~~~
$ dig @localhost mynginx.demo.coredns.local
@@ -179,8 +179,8 @@ For example:
endpoint http://localhost:8080
}
# Perform DNS response caching for the coredns.local zone
# Cache timeout is provided by the integer argument in seconds
# This works for the kubernetes middleware.)
# Cache timeout is specified by an integer argument in seconds
# (This works for the kubernetes middleware.)
#cache 20 coredns.local
#cache 160 coredns.local
}
@@ -188,7 +188,7 @@ For example:
### Internal IP or External IP?
* Should the Corefile configuration allow control over whether the internal IP or external IP is exposed?
* If the Corefile configuration allows control over internal IP or external IP, then the config should allow users to control the precidence.
* If the Corefile configuration allows control over internal IP or external IP, then the config should allow users to control the precedence.
For example a service "myservice" running in namespace "mynamespace" with internal IP "10.0.0.100" and external IP "1.2.3.4".
@@ -206,7 +206,7 @@ This example could be published as:
### Wildcards
Publishing DNS records for singleton services isn't very interesting. Service
names are unique within a k8s namespace therefore multiple services will be
names are unique within a k8s namespace, therefore multiple services will be
commonly run with a structured naming scheme.
For example, running multiple nginx services under the names:

5
middleware/loadbalance/README.md
View File

@@ -1,11 +1,10 @@
# loadbalance
`loadbalance` acts as a round-robin DNS loadbalancer by randomizing A and AAAA records in the
message. See [Wikipedia](https://en.wikipedia.org/wiki/Round-robin_DNS) about the pros and cons
`loadbalance` acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records in the answer. 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
implementation (like glibc) can't handle that.
implementations (like glibc) are particular about that.
## Syntax

6
middleware/log/README.md
View File

@@ -1,6 +1,6 @@
# log
`log` enables request logging. The request log is also known from some vernaculars as an access log.
`log` enables request logging. The request log is also known in some vernacular as an access log.
## Syntax
@@ -8,7 +8,7 @@
log
~~~
* With no arguments, an query log is written to query.log in the common log format for all requests
* With no arguments, a query log entry is written to query.log in the common log format for all requests
(base name = .).
~~~
@@ -40,7 +40,7 @@ The following place holders are supported:
* `{type}`: qtype of the request.
* `{name}`: qname of the request.
* `{class}`: class of the request.
* `{class}`: qclass of the request.
* `{proto}`: protocol used (tcp or udp).
* `{when}`: time of the query.
* `{remote}`: client's IP address.

6
middleware/metrics/README.md
View File

@@ -21,12 +21,12 @@ Extra labels used are:
* `proto` which holds the transport of the response ("udp" or "tcp")
* The address family (`family`) of the transport (1 = IP (IP version 4), 2 = IP6 (IP version 6)).
* `type` which old the query type, it holds the most common ones (A, AAAA, MX, SOA, CNAME, PTR, TXT,
* `type` which holds the query type. It holds most common types (A, AAAA, MX, SOA, CNAME, PTR, TXT,
NS, SRV, DS, DNSKEY, RRSIG, NSEC, NSEC3, IXFR, AXFR and ANY) and "other" which lumps together all
other types.
* The `response_rcode_count_total` has an extra label `rcode` which holds the rcode of the response.
If monitoring is enabled queries that do not enter the middleware chain are exported under the fake
If monitoring is enabled, queries that do not enter the middleware chain are exported under the fake
domain "dropped" (without a closing dot).
Restarting CoreDNS will stop the monitoring. This is a bug. Also [this upstream
@@ -40,7 +40,7 @@ prometheus
For each zone that you want to see metrics for.
It optionally takes an address where the metrics are exported, the default
It optionally takes an address to which the metrics are exported; the default
is `localhost:9153`. The metrics path is fixed to `/metrics`.
## Examples

12
middleware/proxy/README.md
View File

@@ -2,7 +2,7 @@
`proxy` facilitates both a basic reverse proxy and a robust load balancer. The proxy has support for
multiple backends and adding custom headers. The load balancing features include multiple policies,
health checks, and failovers. If all hosts fails their health check the proxy middleware will fail
health checks, and failovers. If all hosts fail their health check the proxy middleware will fail
back to randomly selecting a target and sending packets to it.
## Syntax
@@ -35,15 +35,15 @@ proxy from to... {
* `fail_timeout` specifies how long to consider a backend as down after it has failed. While it is down, requests will not be routed to that backend. A backend is "down" if CoreDNS fails to communicate with it. The default value is 10 seconds ("10s").
* `max_fails` is the number of failures within fail_timeout that are needed before considering a backend to be down. If 0, the backend will never be marked as down. Default is 1.
* `health_check` will check path (on port) on each backend. If a backend returns a status code of 200-399, then that backend is healthy. If it doesn't, the backend is marked as unhealthy for duration and no requests are routed to it. If this option is not provided then health checks are disabled. The default duration is 10 seconds ("10s").
* `ignored_names...` is a space-separated list of paths to exclude from proxying. Requests that match any of these paths will be passed thru.
* `spray` when all backends are unhealth randomly pick one to send the traffic to (this is a failsafe).
* `ignored_names...` is a space-separated list of paths to exclude from proxying. Requests that match any of these paths will be passed through.
* `spray` when all backends are unhealthy, randomly pick one to send the traffic to. (This is a failsafe.)
## Policies
There are three load balancing policies available:
There are three load-balancing policies available:
* *random* (default) - Randomly select a backend
* *least_conn* - Select backend with the fewest active connections
* *round_robin* - Select backend in round-robin fashion
* *least_conn* - Select the backend with the fewest active connections
* *round_robin* - Select the backend in round-robin fashion
All polices implement randomly spraying packets to backend hosts when *no healthy* hosts are
available. This is to preeempt the case where the healthchecking (as a mechanism) fails.