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

readme updates (#525)

Browse Source
This commit is contained in:
Miek Gieben
2017-02-15 08:03:14 +00:00
committed by GitHub
parent 061b3fc1bd
commit 34db56a22e
1 changed files with 43 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
middleware/proxy/README.md
View File

@@ -31,17 +31,29 @@ proxy FROM TO... {
~~~ ~~~
* **FROM** is the name to match for the request to be proxied. * **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 * **TO** is the destination endpoint to proxy to. At least one is required, but multiple may be
* `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. specified. **TO** may be an IP:Port pair, or may reference a file in resolv.conf format
* `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"). * `policy` is the load balancing policy to use; applies only with multiple backends. May be one of
* `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. random, least_conn, or round_robin. Default is random.
* `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"). * `fail_timeout` specifies how long to consider a backend as down after it has failed. While it is
* **IGNORED_NAMES** is a space-separated list of domains to exclude from proxying. Requests that match none of these names will be passed through. down, requests will not be routed to that backend. A backend is "down" if CoreDNS fails to
* `spray` when all backends are unhealthy, randomly pick one to send the traffic to. (This is a failsafe.) communicate with it. The default value is 10 seconds ("10s").
* `protocol` specifies what protocol to use to speak to an upstream, `dns` (the default) is plain old DNS, and * `max_fails` is the number of failures within fail_timeout that are needed before considering
`https_google` uses `https://dns.google.com` and speaks a JSON DNS dialect. Note when using this a backend to be down. If 0, the backend will never be marked as down. Default is 1.
**TO** must be `dns.google.com`. The `grpc` option will talk to a server that has implemented the DnsService defined * `health_check` will check path (on port) on each backend. If a backend returns a status code of
in https://github.com/miekg/coredns/middleware/proxy/pb/dns.proto. 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 ## 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 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 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: from `dns.google.com` is added. Note this is not always set.
`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"
~~~
* `grpc`: options are used to control how the TLS connection is made to the gRPC server. * `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. * 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). * `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. * 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 * KEY-PEM CERT-PEM - Client authentication is used with the specified key/cert pair. The server
with the system CAs. 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 * KEY-PEM CERT-PEM CA-PEM - Client authentication is used with the specified key/cert pair. The
verified using the CA-PEM file. 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 ## 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} * 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 Where `proxy_proto` is the protocol used (`dns`, `grpc`, or `https_google`) and `from` is **FROM**
the config, `proto` is the protocol used by the incoming query ("tcp" or "udp"). specified in the config, `proto` is the protocol used by the incoming query ("tcp" or "udp").
## Examples ## 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
} }
~~~ ~~~