Merge pull request #229 from cricketliu/master

Some grammatical fixes to various README.md files

README.md

@@ -1,47 +1,47 @@
 # CoreDNS
 
-CoreDNS is DNS server that started as a fork of [Caddy](https://github.com/mholt/caddy/). It has the
+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 to similar that CoreDNS is now a server type plugin for
+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.
+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
+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!
+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).
+* 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).
+* 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).
+* Load balancing of responses (middleware/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 (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

middleware/cache/README.md

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

middleware/chaos/README.md

@@ -1,7 +1,7 @@
 # chaos
 
-The `chaos` middleware allows CoreDNS to response to TXT queries in CH class.
+The `chaos` middleware allows CoreDNS to respond to TXT queries in the CH class.
-Useful for retrieving version or author information from the server.
+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

middleware/dnssec/README.md

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

middleware/errors/README.md

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

middleware/etcd/README.md

@@ -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".
+* `path` the path inside etcd. Defaults to "/skydns".
-* `endpoint` the etcd endpoints, default to "http://localhost:2397".
+* `endpoint` the etcd endpoints. Defaults to "http://localhost:2397".
-* `upstream` upstream resolvers to be used resolve external names found in etcd, think CNAMEs
+* `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
+  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
+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:
+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
     ...
 ~~~

middleware/file/README.md

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

middleware/health/README.md

@@ -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
+Optionally takes an address; the default is `:8080`. The health path is fixed to `/health`. It
-will just return "OK", when CoreDNS is healthy.
+will just return "OK" when CoreDNS is healthy.
 
 This middleware only needs to be enabled once.
 

middleware/kubernetes/README.md

@@ -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
+        # Cache timeout is specified by an integer argument in seconds
-        # This works for the kubernetes middleware.)
+        # (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:

middleware/loadbalance/README.md

@@ -1,11 +1,10 @@
 # loadbalance
 
-`loadbalance` acts as a round-robin DNS loadbalancer by randomizing A and AAAA records in the
+`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
-message. 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
 

middleware/log/README.md

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

middleware/metrics/README.md

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

middleware/proxy/README.md

@@ -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.
+* `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 unhealth randomly pick one to send the traffic to (this is a failsafe).
+* `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
+* *least_conn* - Select the backend with the fewest active connections
-* *round_robin* - Select backend in round-robin fashion
+* *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.