readme updates (#525)

middleware/proxy/README.md

@@ -31,17 +31,29 @@ proxy FROM TO... {
 ~~~
 
 * **FROM** is the name to match for the request to be proxied.
-* **TO** is the destination endpoint to proxy to. At least one is required, but multiple may be specified. To may be an IP:Port pair, or may reference a file in resolv.conf format
-* `policy` is the load balancing policy to use; applies only with multiple backends. May be one of random, least_conn, or round_robin. Default is random.
-* `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 domains to exclude from proxying. Requests that match none of these names will be passed through.
-* `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** must be `dns.google.com`. The `grpc` option will talk to a server that has implemented the DnsService defined
-  in https://github.com/miekg/coredns/middleware/proxy/pb/dns.proto.
+* **TO** is the destination endpoint to proxy to. At least one is required, but multiple may be
+  specified. **TO** may be an IP:Port pair, or may reference a file in resolv.conf format
+* `policy` is the load balancing policy to use; applies only with multiple backends. May be one of
+  random, least_conn, or round_robin. Default is random.
+* `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** in `except` is a space-separated list of domains to exclude from proxying.
+  Requests that match none of these names will be passed through.
+* `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
+  the [DnsService](https://github.com/miekg/coredns/middleware/proxy/pb/dns.proto).
+  An out-of-tree middleware that implements the server side of this can be found at
+  [here](https://github.com/infobloxopen/coredns-grpc).
 
 ## Policies
 
@@ -67,32 +79,18 @@ payload over HTTPS). Note that with `https_google` the entire transport is encry
 
   Debug queries are enabled by default and currently there is no way to turn them off. When CoreDNS
   receives a debug query (i.e. the name is prefixed with `o-o.debug.`) a TXT record with Comment
-  from `dns.google.com` is added. Note this is not always set, but sometimes you'll see:
-
-  `dig @localhost -p 1053 mx o-o.debug.example.org`:
-
-~~~ txt
-;; OPT PSEUDOSECTION:
-; EDNS: version: 0, flags:; udp: 4096
-;; QUESTION SECTION:
-;o-o.debug.example.org.		IN	MX
-
-;; AUTHORITY SECTION:
-example.org.		1799	IN	SOA	sns.dns.icann.org. noc.dns.icann.org. 2016110711 7200 3600 1209600 3600
-
-;; ADDITIONAL SECTION:
-.			0	CH	TXT	"Response from 199.43.133.53"
-~~~
+  from `dns.google.com` is added. Note this is not always set.
 * `grpc`: options are used to control how the TLS connection is made to the gRPC server.
   * None - No client authentication is used, and the system CAs are used to verify the server certificate.
   * `insecure` - TLS is not used, the connection is made in plaintext (not good in production).
   * CA-PEM - No client authentication is used, and the file CA-PEM is used to verify the server certificate.
-  * KEY-PEM CERT-PEM - Client authentication is used with the specified key/cert pair. The server certificate is verified
-    with the system CAs.
-  * KEY-PEM CERT-PEM CA-PEM - Client authentication is used with the specified key/cert pair. The server certificate is
-    verified using the CA-PEM file.
+  * KEY-PEM CERT-PEM - Client authentication is used with the specified key/cert pair. The server
+    certificate is verified with the system CAs.
+  * KEY-PEM CERT-PEM CA-PEM - Client authentication is used with the specified key/cert pair. The
+    server certificate is verified using the CA-PEM file.
 
-  An out-of-tree middleware that implements the server side of this can be found at https://github.com/infobloxopen/coredns-grpc.
+  An out-of-tree middleware that implements the server side of this can be found at
+  [here](https://github.com/infobloxopen/coredns-grpc).
 
 ## Metrics
 
@@ -100,8 +98,8 @@ If monitoring is enabled (via the *prometheus* directive) then the following met
 
 * coredns_proxy_request_count_total{proto, proxy_proto, from}
 
-Where `proxy_proto` is the protocol used (`dns`, or `https_google`) and `from` is **FROM** specified in
-the config, `proto` is the protocol used by the incoming query ("tcp" or "udp").
+Where `proxy_proto` is the protocol used (`dns`, `grpc`, or `https_google`) and `from` is **FROM**
+specified in the config, `proto` is the protocol used by the incoming query ("tcp" or "udp").
 
 ## Examples
 
@@ -158,10 +156,18 @@ proxy example.org 1.2.3.4:53 {
 }
 ~~~
 
-Proxy everything, and re-lookup `dns.google.com` every 300 seconds using 8.8.8.8:53.
+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`.
 
 ~~~
-proxy . 1.2.3.4:53 {
-    protocol https_google bootstrap 8.8.8.8:53
+. {
+    proxy . 1.2.3.4:53 {
+        execpt example.org
+        protocol https_google
+    }
+}
+
+example.org {
+    proxy . 8.8.8.8:53
 }
 ~~~