diff --git a/content/explugins/proxy.md b/content/explugins/proxy.md new file mode 100644 index 0000000..a0a0e6e --- /dev/null +++ b/content/explugins/proxy.md @@ -0,0 +1,165 @@ ++++ +title = "proxy" +description = "*proxy* - basic proxy and a robust load balancer." +weight = 27 +tags = [ "plugin", "proxy" ] +categories = [ "plugin", "external" ] +date = "2019-03-03T14:11:50.604581" +repo = "https://github.com/coredns/proxy" +home = "https://github.com/coredns/proxy/blob/master/README.md" ++++ + +## Description + +The proxy has support for multiple backends. The load balancing features include multiple policies, +health checks, and failovers. If all hosts fail their health check the proxy plugin will fail +back to randomly selecting a target and sending packets to it. + +## Syntax + +In its most basic form, a simple reverse proxy uses this syntax: + +~~~ +proxy FROM TO +~~~ + +* **FROM** is the base domain to match for the request to be proxied. +* **TO** is the destination endpoint to proxy to. + +However, advanced features including load balancing can be utilized with an expanded syntax: + +~~~ +proxy FROM TO... { + policy random|least_conn|round_robin|sequential + fail_timeout DURATION + max_fails INTEGER + health_check PATH:PORT [DURATION] + except IGNORED_NAMES... + spray + protocol [dns [force_tcp]|grpc [insecure|CACERT|KEY CERT|KEY CERT CACERT]] +} +~~~ + +* **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, round_robin or sequential. 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 2 seconds ("2s"). +* `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 marked healthy for double the healthcheck duration. If it doesn't, + it is marked as unhealthy and no requests are routed to it. If this option is not provided then + health checks are disabled. The default duration is 4 seconds ("4s"). +* **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. The `grpc` option will talk to a server that has implemented + the [DnsService](https://github.com/coredns/coredns/blob/master/pb/dns.proto). + +## Policies + +There are four load-balancing policies available: + +* `random` (default) - Randomly select a backend +* `least_conn` - Select the backend with the fewest active connections +* `round_robin` - Select the backend in round-robin fashion +* `sequential` - Select the first available backend looking by order of declaration from left to right +* `first` - Deprecated. Use sequential instead + + +All polices implement randomly spraying packets to backend hosts when *no healthy* hosts are +available. This is to preempt the case where the healthchecking (as a mechanism) fails. + +## Upstream Protocols + +`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. + +`grpc` +: extra 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). + * **CACERT** - No client authentication is used, and the file **CACERT** is used to verify the server certificate. + * **KEY** **CERT** - Client authentication is used with the specified key/cert pair. The server + certificate is verified with the system CAs. + * **KEY** **CERT** **CACERT** - Client authentication is used with the specified key/cert pair. The + server certificate is verified using the **CACERT** file. + +## Metrics + +If monitoring is enabled (via the *prometheus* directive) then the following metric is exported: + +* `coredns_proxy_request_duration_seconds{server, proto, proto_proxy, family, to}` - duration per + upstream interaction. +* `coredns_proxy_request_count_total{server, proto, proto_proxy, family, to}` - query count per + upstream. + +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 documentation in the metrics plugin. + +## Examples + +Proxy all requests within example.org. to a backend system: + +~~~ +proxy example.org 127.0.0.1:9005 +~~~ + +Load-balance all requests between three backends (using random policy): + +~~~ corefile +. { + proxy . 10.0.0.10:53 10.0.0.11:1053 10.0.0.12 +} +~~~ + +Same as above, but round-robin style: + +~~~ corefile +. { + proxy . 10.0.0.10:53 10.0.0.11:1053 10.0.0.12 { + policy round_robin + } +} +~~~ + +With health checks and proxy headers to pass hostname, IP, and scheme upstream: + +~~~ corefile +. { + proxy . 10.0.0.11:53 10.0.0.11:53 10.0.0.12:53 { + policy round_robin + health_check /health:8080 + } +} +~~~ + +Proxy everything except requests to miek.nl or example.org + +~~~ +. { + proxy . 10.0.0.10:1234 { + except miek.nl example.org + } +} +~~~ + +Proxy everything except `example.org` using the host's `resolv.conf`'s nameservers: + +~~~ corefile +. { + proxy . /etc/resolv.conf { + except example.org + } +} +~~~ diff --git a/content/plugins/reverse.md b/content/plugins/reverse.md deleted file mode 100644 index 297b2fe..0000000 --- a/content/plugins/reverse.md +++ /dev/null @@ -1,99 +0,0 @@ -+++ -title = "reverse" -description = "*reverse* allows for dynamic responses to PTR and the related A/AAAA requests." -weight = 25 -tags = [ "plugin", "reverse" ] -categories = [ "plugin" ] -date = "2018-05-24T08:47:52.448648" -+++ - -## Description - -If a request matches a regular expression (see Template Syntax below) this plugin will generate a -response. This is only done for "address" records (PTR, A and AAAA). - -## Syntax - -~~~ -reverse NETWORK... { - hostname TEMPLATE - [ttl TTL] - [fallthrough [ZONES...]] - [wildcard] -~~~ - -* **NETWORK** one or more CIDR formatted networks to respond on. -* `hostname` injects the IP and zone to a template for the hostname. Defaults to "ip-{IP}.{zone[1]}". See below for template. -* `ttl` defaults to 60 -* `fallthrough` if zone matches and no record can be generated, pass request to the next plugin. - If **[ZONES...]** is omitted, then fallthrough happens for all zones for which the plugin - is authoritative. If specific zones are listed (for example `in-addr.arpa` and `ip6.arpa`), then only - queries for those zones will be subject to fallthrough. -* `wildcard` allows matches to catch all subdomains as well. - -### Template Syntax - -The template for the hostname is used for generating the PTR for a reverse lookup and matching the -forward lookup back to an IP. - -#### `{ip}` - -The `{ip}` symbol is **required** to make reverse work. -For IPv4 lookups the IP is directly extracted -With IPv6 lookups the ":" is removed, and any zero ranged are expanded, e.g., -"ffff::ffff" results in "ffff000000000000000000000000ffff" - -#### `{zone[i]}` - -The `{zone[i]}` symbol is **optional** and can be replaced by a fixed (zone) string. -The zone will be matched by the zones listed in *this* configuration stanza. -`i` needs to be replaced with the index of the configured listener zones, starting with 1. - -## Examples - -~~~ corefile -arpa compute.internal { - # proxy unmatched requests - proxy . 8.8.8.8 - - # answer requests for IPs in this network - # PTR 1.0.32.10.in-addr.arpa. 3600 ip-10.0.32.1.compute.internal. - # A ip-10.0.32.1.compute.internal. 3600 10.0.32.1 - # v6 is also possible - # PTR 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.0.d.f.ip6.arpa. 3600 ip-fd010000000000000000000000000001.compute.internal. - # AAAA ip-fd010000000000000000000000000001.compute.internal. 3600 fd01::1 - reverse 10.32.0.0/16 fd01::/16 { - # template of the ip injection to hostname, zone resolved to compute.internal. - hostname ip-{ip}.{zone[2]} - - ttl 3600 - - # Forward unanswered or unmatched requests to proxy - # without this flag, requesting A/AAAA records on compute.internal. will end here. - fallthrough - } -} -~~~ - - -~~~ corefile -32.10.in-addr.arpa.arpa arpa.company.org { - - reverse 10.32.0.0/16 { - # template of the ip injection to hostname, zone resolved to arpa.company.org. - hostname "ip-{ip}.v4.{zone[2]}" - - ttl 3600 - - # fallthrough is not required, v4.arpa.company.org. will be only answered here - } - - # cidr closer to the ip wins, so we can overwrite the "default" - reverse 10.32.2.0/24 { - # its also possible to set fix domain suffix - hostname ip-{ip}.fix.arpa.company.org. - - ttl 3600 - } -} -~~~