Skip to content

C
Coredns
Commit 34db56a2 authored by Miek Gieben's avatar Miek Gieben Committed by GitHub
Browse files
Options

readme updates (#525)

parent 061b3fc1
Hide whitespace changes
Inline Side-by-side
Showing with 43 additions and 37 deletions
middleware/proxy/README.md
View file @ 34db56a2
......@@ -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
}
~~~
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment