update docs

2018-06-20 06:44:17 +00:00 · 2018-06-20 06:44:17 +00:00 · 78d114fe98
parent 530a61caf7
commit 78d114fe98
33 changed files with 76 additions and 91 deletions
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
--- a/content/plugins/auto.md
+++ b/content/plugins/auto.md
@ -4,7 +4,7 @@ description = "*auto* enables serving zone data from an RFC 1035-style master fi
 weight = 1
 tags = [ "plugin", "auto" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.442416"
+date = "2018-06-20T06:43:55.261676"
 +++

 ## Description
--- a/content/plugins/autopath.md
+++ b/content/plugins/autopath.md
@ -4,7 +4,7 @@ description = "*autopath* allows for server-side search path completion."
 weight = 2
 tags = [ "plugin", "autopath" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.442833"
+date = "2018-06-20T06:43:55.262235"
 +++

 ## Description
--- a/content/plugins/bind.md
+++ b/content/plugins/bind.md
@ -4,7 +4,7 @@ description = "*bind* overrides the host to which the server should bind."
 weight = 3
 tags = [ "plugin", "bind" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.443129"
+date = "2018-06-20T06:43:55.262713"
 +++

 ## Description
--- a/content/plugins/cache.md
+++ b/content/plugins/cache.md
@ -4,7 +4,7 @@ description = "*cache* enables a frontend cache."
 weight = 4
 tags = [ "plugin", "cache" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.443392"
+date = "2018-06-20T06:43:55.263150"
 +++

 ## Description
--- a/content/plugins/chaos.md
+++ b/content/plugins/chaos.md
@ -4,7 +4,7 @@ description = "*chaos* allows for responding to TXT queries in the CH class."
 weight = 5
 tags = [ "plugin", "chaos" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.443658"
+date = "2018-06-20T06:43:55.263606"
 +++

 ## Description
--- a/content/plugins/debug.md
+++ b/content/plugins/debug.md
@ -4,7 +4,7 @@ description = "*debug* disables the automatic recovery upon a crash so that you'
 weight = 6
 tags = [ "plugin", "debug" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.443851"
+date = "2018-06-20T06:43:55.264001"
 +++

 ## Description
--- a/content/plugins/dnssec.md
+++ b/content/plugins/dnssec.md
@ -4,7 +4,7 @@ description = "*dnssec* enable on-the-fly DNSSEC signing of served data."
 weight = 7
 tags = [ "plugin", "dnssec" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.444092"
+date = "2018-06-20T06:43:55.264444"
 +++

 ## Description
--- a/content/plugins/dnstap.md
+++ b/content/plugins/dnstap.md
@ -4,7 +4,7 @@ description = "*dnstap* enable logging to dnstap"
 weight = 8
 tags = [ "plugin", "dnstap" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.444315"
+date = "2018-06-20T06:43:55.264879"
 +++

 ## Description
--- a/content/plugins/erratic.md
+++ b/content/plugins/erratic.md
@ -4,7 +4,7 @@ description = "*erratic* a plugin useful for testing client behavior."
 weight = 9
 tags = [ "plugin", "erratic" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.444539"
+date = "2018-06-20T06:43:55.265306"
 +++

 ## Description
--- a/content/plugins/errors.md
+++ b/content/plugins/errors.md
@ -4,7 +4,7 @@ description = "*errors* enable error logging."
 weight = 10
 tags = [ "plugin", "errors" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.444723"
+date = "2018-06-20T06:43:55.265681"
 +++

 ## Description
--- a/content/plugins/etcd.md
+++ b/content/plugins/etcd.md
@ -4,7 +4,7 @@ description = "*etcd* enables reading zone data from an etcd instance."
 weight = 11
 tags = [ "plugin", "etcd" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.445007"
+date = "2018-06-20T06:43:55.266156"
 +++

 ## Description
--- a/content/plugins/federation.md
+++ b/content/plugins/federation.md
@ -4,7 +4,7 @@ description = "*federation* enables federated queries to be resolved via the kub
 weight = 12
 tags = [ "plugin", "federation" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.445261"
+date = "2018-06-20T06:43:55.266602"
 +++

 ## Description
--- a/content/plugins/file.md
+++ b/content/plugins/file.md
@ -4,7 +4,7 @@ description = "*file* enables serving zone data from an RFC 1035-style master fi
 weight = 13
 tags = [ "plugin", "file" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.445474"
+date = "2018-06-20T06:43:55.266994"
 +++

 ## Description
--- a/content/plugins/forward.md
+++ b/content/plugins/forward.md
@ -4,7 +4,7 @@ description = "*forward* facilitates proxying DNS messages to upstream resolvers
 weight = 14
 tags = [ "plugin", "forward" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.445723"
+date = "2018-06-20T06:43:55.267443"
 +++

 ## Description
@ -85,6 +85,10 @@ forward FROM TO... {
 Also note the TLS config is "global" for the whole forwarding proxy if you need a different
 `tls-name` for different upstreams you're out of luck.

+On each endpoint, the timeouts of the communication are set by default and automatically tuned depending early results.
+- dialTimeout by default is 30 sec, and can decrease automatically down to 100ms
+- readTimeout by default is 2 sec, and can decrease automatically down to 10ms
+
 ## Metrics

 If monitoring is enabled (via the *prometheus* directive) then the following metric are exported:
--- a/content/plugins/health.md
+++ b/content/plugins/health.md
@ -4,7 +4,7 @@ description = "*health* enables a health check endpoint."
 weight = 15
 tags = [ "plugin", "health" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.445949"
+date = "2018-06-20T06:43:55.267872"
 +++

 ## Description
--- a/content/plugins/hosts.md
+++ b/content/plugins/hosts.md
@ -4,18 +4,38 @@ description = "*hosts* enables serving zone data from a `/etc/hosts` style file.
 weight = 16
 tags = [ "plugin", "hosts" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.446188"
+date = "2018-06-20T06:43:55.268277"
 +++

 ## Description

-The hosts plugin is useful for serving zones from a /etc/hosts file. It serves from a preloaded
+The hosts plugin is useful for serving zones from a `/etc/hosts` file. It serves from a preloaded
 file that exists on disk. It checks the file for changes and updates the zones accordingly. This
 plugin only supports A, AAAA, and PTR records. The hosts plugin can be used with readily
 available hosts files that block access to advertising servers.

 This plugin can only be used once per Server Block.

+## The hosts file
+
+Commonly the entries are of the from `IP_address canonical_hostname [aliases...]` as explained by the hosts(5) man page.
+
+Examples:
+
+~~~
+# The following lines are desirable for IPv4 capable hosts
+127.0.0.1       localhost
+192.168.1.10    example.com            example
+
+# The following lines are desirable for IPv6 capable hosts
+::1                     localhost ip6-localhost ip6-loopback
+fdfc:a744:27b5:3b0e::1  example.com example
+~~~
+
+### PTR records
+
+PTR records for reverse lookups are generated automatically by CoreDNS (based on the hosts file entries) and cannot be created manually. 
+
 ## Syntax

 ~~~
@ -77,3 +97,7 @@ Load hosts file inlined in Corefile.
    }
 }
 ~~~
+
+## See also
+
+The form of the entries in the `/etc/hosts` file are based on IETF [RFC 952](https://tools.ietf.org/html/rfc952) which was updated by IETF [RFC 1123](https://tools.ietf.org/html/rfc1123).
--- a/content/plugins/kubernetes.md
+++ b/content/plugins/kubernetes.md
@ -4,7 +4,7 @@ description = "*kubernetes* enables the reading zone data from a Kubernetes clus
 weight = 17
 tags = [ "plugin", "kubernetes" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.446513"
+date = "2018-06-20T06:43:55.268802"
 +++

 ## Description
--- a/content/plugins/loadbalance.md
+++ b/content/plugins/loadbalance.md
@ -4,7 +4,7 @@ description = "*loadbalance* acts as a round-robin DNS loadbalancer by randomizi
 weight = 18
 tags = [ "plugin", "loadbalance" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.446777"
+date = "2018-06-20T06:43:55.269245"
 +++
 in the answer.

--- a/content/plugins/log.md
+++ b/content/plugins/log.md
@ -4,7 +4,7 @@ description = "*log* enables query logging to standard output."
 weight = 19
 tags = [ "plugin", "log" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.447045"
+date = "2018-06-20T06:43:55.269699"
 +++

 ## Description
--- a/content/plugins/metrics.md
+++ b/content/plugins/metrics.md
@ -4,7 +4,7 @@ description = "*prometheus* enables [Prometheus](https://prometheus.io/) metrics
 weight = 20
 tags = [ "plugin", "metrics" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.447286"
+date = "2018-06-20T06:43:55.270095"
 +++

 ## Description
--- a/content/plugins/nsid.md
+++ b/content/plugins/nsid.md
@ -4,7 +4,7 @@ description = "*nsid* adds an identifier of this server to each reply."
 weight = 21
 tags = [ "plugin", "nsid" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.447546"
+date = "2018-06-20T06:43:55.270515"
 +++

 ## Description
--- a/content/plugins/pprof.md
+++ b/content/plugins/pprof.md
@ -4,7 +4,7 @@ description = "*pprof* publishes runtime profiling data at endpoints under `/deb
 weight = 22
 tags = [ "plugin", "pprof" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.447810"
+date = "2018-06-20T06:43:55.270968"
 +++

 ## Description
--- a/content/plugins/proxy.md
+++ b/content/plugins/proxy.md
@ -4,7 +4,7 @@ description = "*proxy* facilitates both a basic reverse proxy and a robust load
 weight = 23
 tags = [ "plugin", "proxy" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.448106"
+date = "2018-06-20T06:43:55.271471"
 +++

 ## Description
@ -34,7 +34,7 @@ proxy FROM TO... {
    health_check PATH:PORT [DURATION]
    except IGNORED_NAMES...
    spray
-    protocol [dns [force_tcp]|https_google [bootstrap ADDRESS...]|grpc [insecure|CACERT|KEY CERT|KEY CERT CACERT]]
+    protocol [dns [force_tcp]|grpc [insecure|CACERT|KEY CERT|KEY CERT CACERT]]
 }
 ~~~

@ -57,8 +57,7 @@ proxy FROM TO... {
 * `spray` when all backends are unhealthy, randomly pick one to send the traffic to. (This is
  a failsafe.)
 * `protocol` specifies what protocol to use to speak to an upstream, `dns` (the default) is plain
-  old DNS, and `https_google` uses `https://dns.google.com` and speaks a JSON DNS dialect. Note when
-  using this **TO** will be ignored. The `grpc` option will talk to a server that has implemented
+  old DNS. The `grpc` option will talk to a server that has implemented
  the [DnsService](https://github.com/coredns/coredns/blob/master/pb/dns.proto).

 ## Policies
@ -76,10 +75,6 @@ available. This is to preeempt the case where the healthchecking (as a mechanism

 ## Upstream Protocols

-Currently `protocol` supports `dns` (i.e., standard DNS over UDP/TCP) and `https_google` (JSON
-payload over HTTPS). Note that with `https_google` the entire transport is encrypted. Only *you* and
-*Google* can see your DNS activity.
-
 `dns`
 :   uses the standard DNS exchange. You can pass `force_tcp` to make sure that the proxied connection is performed
    over TCP, regardless of the inbound request's protocol.
@ -95,13 +90,6 @@ payload over HTTPS). Note that with `https_google` the entire transport is encry
  * **KEY** **CERT** **CACERT** - Client authentication is used with the specified key/cert pair. The
     server certificate is verified using the **CACERT** file.

-`https_google`
-:    bootstrap **ADDRESS...** is used to (re-)resolve `dns.google.com`.
-
-    This happens every 300s. If not specified the default is used: 8.8.8.8:53/8.8.4.4:53.
-    Note that **TO** is *ignored* when `https_google` is used, as its upstream is defined as `dns.google.com`.
-
-
 ## Metrics

 If monitoring is enabled (via the *prometheus* directive) then the following metric is exported:
@ -111,7 +99,7 @@ If monitoring is enabled (via the *prometheus* directive) then the following met
 * `coredns_proxy_request_count_total{server, proto, proto_proxy, family, to}` - query count per
  upstream.

-Where `proxy_proto` is the protocol used (`dns`, `grpc`, or `https_google`) and `to` is **TO**
+Where `proxy_proto` is the protocol used (`dns` or `grpc`) and `to` is **TO**
 specified in the config, `proto` is the protocol used by the incoming query ("tcp" or "udp"), family
 the transport family ("1" for IPv4, and "2" for IPv6). `Server` is the server responsible for the
 request (and metric). See the documention in the metrics plugin.
@ -172,34 +160,3 @@ Proxy everything except `example.org` using the host's `resolv.conf`'s nameserve
    }
 }
 ~~~
-
-Proxy all requests within `example.org` to Google's `dns.google.com`.
-
-~~~ corefile
-. {
-    proxy example.org 1.2.3.4:53 {
-        protocol https_google
-    }
-}
-~~~
-
-Proxy everything with HTTPS to `dns.google.com`, except `example.org`. Then have another proxy in
-another stanza that uses plain DNS to resolve names under `example.org`.
-
-~~~ corefile
-. {
-    proxy . 1.2.3.4:53 {
-        except example.org
-        protocol https_google
-    }
-}
-
-example.org {
-    proxy . 8.8.8.8:53
-}
-~~~
-
-## Bugs
-
-When using the `google_https` protocol the health checking will health check the wrong endpoint.
-See <https://github.com/coredns/coredns/issues/1202> for some background.
--- a/content/plugins/reload.md
+++ b/content/plugins/reload.md
@ -4,7 +4,7 @@ description = "*reload* allows automatic reload of a changed Corefile"
 weight = 24
 tags = [ "plugin", "reload" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.448362"
+date = "2018-06-20T06:43:55.271880"
 +++

 ## Description
--- a/content/plugins/rewrite.md
+++ b/content/plugins/rewrite.md
@ -1,10 +1,10 @@
 +++
 title = "rewrite"
 description = "*rewrite* performs internal message rewriting."
-weight = 26
+weight = 25
 tags = [ "plugin", "rewrite" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.448976"
+date = "2018-06-20T06:43:55.272407"
 +++

 ## Description
@ -182,8 +182,8 @@ rewrite [continue|stop] name regex STRING STRING answer name STRING STRING

 Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request.

-* `replace` will modify any matching (what that means may vary based on EDNS0 type) option with the specified option
-* `append` will add the option regardless of what options already exist
+* `replace` will modify any "matching" option with the specified option. The criteria for "matching" varies based on EDNS0 type.
+* `append` will add the option only if no matching option exists
 * `set` will modify a matching option or add one if none is found

 Currently supported are `EDNS0_LOCAL`, `EDNS0_NSID` and `EDNS0_SUBNET`.
--- a/content/plugins/root.md
+++ b/content/plugins/root.md
@ -1,10 +1,10 @@
 +++
 title = "root"
 description = "*root* simply specifies the root of where to find (zone) files."
-weight = 27
+weight = 26
 tags = [ "plugin", "root" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.449187"
+date = "2018-06-20T06:43:55.272806"
 +++

 ## Description
--- a/content/plugins/route53.md
+++ b/content/plugins/route53.md
@ -1,10 +1,10 @@
 +++
 title = "route53"
 description = "*route53* enables serving zone data from AWS route53."
-weight = 28
+weight = 27
 tags = [ "plugin", "route53" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.449410"
+date = "2018-06-20T06:43:55.273223"
 +++

 ## Description
--- a/content/plugins/secondary.md
+++ b/content/plugins/secondary.md
@ -1,10 +1,10 @@
 +++
 title = "secondary"
 description = "*secondary* enables serving a zone retrieved from a primary server."
-weight = 29
+weight = 28
 tags = [ "plugin", "secondary" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.449662"
+date = "2018-06-20T06:43:55.273669"
 +++

 ## Description
--- a/content/plugins/template.md
+++ b/content/plugins/template.md
@ -1,10 +1,10 @@
 +++
 title = "template"
 description = "*template* allows for dynamic responses based on the incoming query."
-weight = 30
+weight = 29
 tags = [ "plugin", "template" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.450010"
+date = "2018-06-20T06:43:55.274202"
 +++

 ## Description
@ -94,7 +94,7 @@ The most simplistic template is

 ### Resolve .invalid as NXDOMAIN

-The `.invalid` domain is a reserved TLD (see [RFC-2606 Reserved Top Level DNS Names](https://tools.ietf.org/html/rfc2606#section-2)) to indicate invalid domains.
+The `.invalid` domain is a reserved TLD (see [RFC 2606 Reserved Top Level DNS Names](https://tools.ietf.org/html/rfc2606#section-2)) to indicate invalid domains.

 ~~~ corefile
 . {
@ -249,7 +249,7 @@ Named capture groups can be used to template one response for multiple patterns.

 * [Go regexp](https://golang.org/pkg/regexp/) for details about the regex implementation
 * [RE2 syntax reference](https://github.com/google/re2/wiki/Syntax) for details about the regex syntax
-* [RFC-1034](https://tools.ietf.org/html/rfc1034#section-3.6.1) and [RFC 1035](https://tools.ietf.org/html/rfc1035#section-5) for the resource record format
+* [RFC 1034](https://tools.ietf.org/html/rfc1034#section-3.6.1) and [RFC 1035](https://tools.ietf.org/html/rfc1035#section-5) for the resource record format
 * [Go template](https://golang.org/pkg/text/template/) for the template language reference

 ## Bugs
--- a/content/plugins/tls.md
+++ b/content/plugins/tls.md
@ -1,10 +1,10 @@
 +++
 title = "tls"
 description = "*tls* allows you to configure the server certificates for the TLS and gRPC servers."
-weight = 31
+weight = 30
 tags = [ "plugin", "tls" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.450277"
+date = "2018-06-20T06:43:55.274696"
 +++

 ## Description
--- a/content/plugins/trace.md
+++ b/content/plugins/trace.md
@ -1,10 +1,10 @@
 +++
 title = "trace"
 description = "*trace* enables OpenTracing-based tracing of DNS requests as they go through the plugin chain."
-weight = 32
+weight = 31
 tags = [ "plugin", "trace" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.450556"
+date = "2018-06-20T06:43:55.275109"
 +++

 ## Description
--- a/content/plugins/whoami.md
+++ b/content/plugins/whoami.md
@ -1,10 +1,10 @@
 +++
 title = "whoami"
 description = "*whoami* returns your resolver's local IP address, port and transport."
-weight = 33
+weight = 32
 tags = [ "plugin", "whoami" ]
 categories = [ "plugin" ]
-date = "2018-05-24T08:47:52.450894"
+date = "2018-06-20T06:43:55.275493"
 +++

 ## Description