Run make -f Makefile.doc (#1705)
Remove trailing white space from proxy/README.md
This commit is contained in:
Miek Gieben
GitHub
parent
19a1ef48f2
commit
61726b3721
9 changed files with 110 additions and 30 deletions
|
|
@ -1,7 +1,7 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-CACHE" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.TH "COREDNS\-CACHE" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIcache\fR \- enables a frontend cache\.
|
||||
|
|
@ -29,7 +29,7 @@ cache [TTL] [ZONES\.\.\.]
|
|||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Each element in the cache is cached according to its TTL (with \fBTTL\fR as the max)\. For the negative cache, the SOA\'s MinTTL value is used\. A cache can contain up to 10,000 items by default\. A TTL of zero is not allowed\.
|
||||
Each element in the cache is cached according to its TTL (with \fBTTL\fR as the max)\. For the negative cache, the SOA\'s MinTTL value is used\. A TTL of zero is not allowed\. A cache is divided into 256 shards, each holding up to 512 items by default \- for a total size of 256 * 512 = 131,072 items\.
|
||||
.
|
||||
.P
|
||||
If you want more control:
|
||||
|
|
@ -62,6 +62,12 @@ cache [TTL] [ZONES\.\.\.] {
|
|||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "CAPACITY AND EVICTION"
|
||||
When specifying \fBCAPACITY\fR, the minimum cache capacity is 131,072\. Specifying a lower value will be ignored\. Specifying a \fBCAPACITY\fR of zero does not disable the cache\.
|
||||
.
|
||||
.P
|
||||
Eviction is done per shard \- i\.e\. when a shard reaches capacity, items are evicted from that shard\. Since shards don\'t fill up perfectly evenly, evictions will occur before the entire cache reaches full capacity\. Each shard capacity is equal to the total cache size / number of shards (256)\.
|
||||
.
|
||||
.SH "METRICS"
|
||||
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
|
||||
.
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-DEBUG" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.TH "COREDNS\-DEBUG" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIdebug\fR \- disables the automatic recovery upon a crash so that you\'ll get a nice stack trace\.
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
Normally CoreDNS will recover from panics, using \fIdebug\fR inhibits this\. The main use of \fIdebug\fR is to help testing\.
|
||||
Normally CoreDNS will recover from panics, using \fIdebug\fR inhibits this\. The main use of \fIdebug\fR is to help testing\. A side effect of using \fIdebug\fR is that \fBlog\.Debug\fR and \fBlog\.Debugf\fR will be printed to standard output\.
|
||||
.
|
||||
.P
|
||||
Note that the \fIerrors\fR plugin (if loaded) will also set a \fBrecover\fR negating this setting\.
|
||||
|
|
@ -21,7 +21,7 @@ debug
|
|||
.fi
|
||||
.
|
||||
.SH "EXAMPLES"
|
||||
Disable the ability to recover from crashes:
|
||||
Disable the ability to recover from crashes and show debug logging:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-FORWARD" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.TH "COREDNS\-FORWARD" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIforward\fR \- facilitates proxying DNS messages to upstream resolvers\.
|
||||
|
|
@ -80,7 +80,21 @@ forward FROM TO\.\.\. {
|
|||
\fBexpire\fR \fBDURATION\fR, expire (cached) connections after this time, the default is 10s\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCA\fR define the TLS properties for TLS; if you leave this out the system\'s configuration will be used\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \- no client authentication is used, and the system CAs are used to verify the server certificate
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \fBCA\fR \- no client authentication is used, and the file CA is used to verify the server certificate
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \fBCERT\fR \fBKEY\fR \- client authentication is used with the specified cert/key pair\. The server certificate is verified with the system CAs
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCA\fR \- client authentication is used with the specified cert/key pair\. The server certificate is verified using the specified CA file
|
||||
.
|
||||
.IP "" 0
|
||||
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls_servername\fR \fBNAME\fR allows you to set a server name in the TLS configuration; for instance 9\.9\.9\.9 needs this to be set to \fBdns\.quad9\.net\fR\.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-LOG" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.TH "COREDNS\-LOG" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIlog\fR \- enables query logging to standard output\.
|
||||
|
|
@ -47,22 +47,27 @@ log [NAME] [FORMAT]
|
|||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
You can further specify the class of responses that get logged:
|
||||
You can further specify the classes of responses that get logged:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
log [NAME] [FORMAT] {
|
||||
class [success|denial|error|all]
|
||||
class CLASSES\.\.\.
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBCLASSES\fR is a space\-separated list of classes of responses that should be logged
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Here \fBsuccess\fR \fBdenial\fR and \fBerror\fR denotes the class of responses that should be logged\. The classes have the following meaning:
|
||||
The classes of responses have the following meaning:
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBsuccess\fR: successful response
|
||||
|
|
@ -74,7 +79,7 @@ Here \fBsuccess\fR \fBdenial\fR and \fBerror\fR denotes the class of responses t
|
|||
\fBerror\fR: SERVFAIL, NOTIMP, REFUSED, etc\. Anything that indicates the remote server is not willing to resolve the request\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBall\fR: the default \- nothing is specified\.
|
||||
\fBall\fR: the default \- nothing is specified\. Using of this class means that all messages will be logged whatever we mix together with "all"\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
|
|
@ -197,4 +202,56 @@ Only log denials for example\.org (and below to a file)
|
|||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Log all queries which were not resolved successfully
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
log \. {
|
||||
class denial error
|
||||
}
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Log all queries on which we did not get errors
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
log \. {
|
||||
class denial success
|
||||
}
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Also the multiple statements can be OR\-ed, for example, we can rewrite the above case as following:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
log \. {
|
||||
class denial
|
||||
class success
|
||||
}
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-METRICS" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.TH "COREDNS\-METRICS" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIprometheus\fR \- enables Prometheus \fIhttps://prometheus\.io/\fR metrics\.
|
||||
|
|
@ -13,25 +13,25 @@ With \fIprometheus\fR you export metrics from CoreDNS and any plugin that has th
|
|||
\fBcoredns_build_info{version, revision, goversion}\fR \- info about CoreDNS itself\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_dns_request_count_total{zone, proto, family}\fR \- total query count\.
|
||||
\fBcoredns_dns_request_count_total{server, zone, proto, family}\fR \- total query count\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_dns_request_duration_seconds{zone}\fR \- duration to process each query\.
|
||||
\fBcoredns_dns_request_duration_seconds{server, zone}\fR \- duration to process each query\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_dns_request_size_bytes{zone, proto}\fR \- size of the request in bytes\.
|
||||
\fBcoredns_dns_request_size_bytes{server, zone, proto}\fR \- size of the request in bytes\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_dns_request_do_count_total{zone}\fR \- queries that have the DO bit set
|
||||
\fBcoredns_dns_request_do_count_total{server, zone}\fR \- queries that have the DO bit set
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_dns_request_type_count_total{zone, type}\fR \- counter of queries per zone and type\.
|
||||
\fBcoredns_dns_request_type_count_total{server, zone, type}\fR \- counter of queries per zone and type\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_dns_response_size_bytes{zone, proto}\fR \- response size in bytes\.
|
||||
\fBcoredns_dns_response_size_bytes{server, zone, proto}\fR \- response size in bytes\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_dns_response_rcode_count_total{zone, rcode}\fR \- response per zone and rcode\.
|
||||
\fBcoredns_dns_response_rcode_count_total{server, zone, rcode}\fR \- response per zone and rcode\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
|
|
@ -42,6 +42,9 @@ Each counter has a label \fBzone\fR which is the zonename used for the request/r
|
|||
Extra labels used are:
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBserver\fR is identifying the server responsible for the request\. This is a string formatted as the server\'s listening address: \fB<scheme>://[<bind>]:<port>\fR\. I\.e\. for a "normal" DNS server this is \fBdns://:53\fR\. If you are using the \fIbind\fR plugin an IP address is included, e\.g\.: \fBdns://127\.0\.0\.53:53\fR\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBproto\fR which holds the transport of the response ("udp" or "tcp")
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-PROXY" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.TH "COREDNS\-PROXY" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIproxy\fR \- facilitates both a basic reverse proxy and a robust load balancer\.
|
||||
|
|
@ -38,7 +38,7 @@ However, advanced features including load balancing can be utilized with an expa
|
|||
.nf
|
||||
|
||||
proxy FROM TO\.\.\. {
|
||||
policy random|least_conn|round_robin|first
|
||||
policy random|least_conn|round_robin|sequential
|
||||
fail_timeout DURATION
|
||||
max_fails INTEGER
|
||||
health_check PATH:PORT [DURATION]
|
||||
|
|
@ -58,7 +58,7 @@ proxy FROM TO\.\.\. {
|
|||
\fBTO\fR is the destination endpoint to proxy to\. At least one is required, but multiple may be specified\. \fBTO\fR may be an IP:Port pair, or may reference a file in resolv\.conf format
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBpolicy\fR is the load balancing policy to use; applies only with multiple backends\. May be one of random, least_conn, round_robin or first\. Default is random\.
|
||||
\fBpolicy\fR 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\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBfail_timeout\fR 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")\.
|
||||
|
|
@ -81,7 +81,7 @@ proxy FROM TO\.\.\. {
|
|||
.IP "" 0
|
||||
.
|
||||
.SH "POLICIES"
|
||||
There are three load\-balancing policies available: * \fBrandom\fR (default) \- Randomly select a backend * \fBleast_conn\fR \- Select the backend with the fewest active connections * \fBround_robin\fR \- Select the backend in round\-robin fashion
|
||||
There are four load\-balancing policies available: * \fBrandom\fR (default) \- Randomly select a backend * \fBleast_conn\fR \- Select the backend with the fewest active connections * \fBround_robin\fR \- Select the backend in round\-robin fashion * \fBsequential\fR \- Select the first available backend looking by order of declaration from left to right * \fBfirst\fR \- Deprecated\. Use sequential instead
|
||||
.
|
||||
.P
|
||||
All polices implement randomly spraying packets to backend hosts when \fIno healthy\fR hosts are available\. This is to preeempt the case where the healthchecking (as a mechanism) fails\.
|
||||
|
|
@ -126,15 +126,15 @@ This happens every 300s\. If not specified the default is used: 8\.8\.8\.8:53/8\
|
|||
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metric is exported:
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_proxy_request_duration_seconds{proto, proto_proxy, family, to}\fR \- duration per upstream interaction\.
|
||||
\fBcoredns_proxy_request_duration_seconds{server, proto, proto_proxy, family, to}\fR \- duration per upstream interaction\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_proxy_request_count_total{proto, proto_proxy, family, to}\fR \- query count per upstream\.
|
||||
\fBcoredns_proxy_request_count_total{server, proto, proto_proxy, family, to}\fR \- query count per upstream\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Where \fBproxy_proto\fR is the protocol used (\fBdns\fR, \fBgrpc\fR, or \fBhttps_google\fR) and \fBto\fR is \fBTO\fR specified in the config, \fBproto\fR is the protocol used by the incoming query ("tcp" or "udp")\. and family the transport family ("1" for IPv4, and "2" for IPv6)\.
|
||||
Where \fBproxy_proto\fR is the protocol used (\fBdns\fR, \fBgrpc\fR, or \fBhttps_google\fR) and \fBto\fR is \fBTO\fR specified in the config, \fBproto\fR is the protocol used by the incoming query ("tcp" or "udp"), family the transport family ("1" for IPv4, and "2" for IPv6)\. \fBServer\fR is the server responsible for the request (and metric)\. See the documention in the metrics plugin\.
|
||||
.
|
||||
.SH "EXAMPLES"
|
||||
Proxy all requests within example\.org\. to a backend system:
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-RELOAD" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.TH "COREDNS\-RELOAD" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIreload\fR \- allows automatic reload of a changed Corefile
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-TRACE" "7" "March 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.TH "COREDNS\-TRACE" "7" "April 2018" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fItrace\fR \- enables OpenTracing\-based tracing of DNS requests as they go through the plugin chain\.
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ proxy FROM TO... {
|
|||
* **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.
|
||||
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").
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue