From e2515fe0e376b41d73d4675d77c7bad096be4502 Mon Sep 17 00:00:00 2001 From: Miek Gieben Date: Fri, 6 Mar 2020 11:11:45 +0000 Subject: [PATCH] doc: regen man-pages (#3725) Mechanical change: make -f Makefile.doc Signed-off-by: Miek Gieben --- man/coredns-cache.7 | 4 ++-- man/coredns-cancel.7 | 3 ++- man/coredns-dnstap.7 | 8 +++---- man/coredns-forward.7 | 43 +++++++++++++++++++++++++++----------- man/coredns-k8s_external.7 | 3 ++- man/coredns-kubernetes.7 | 4 ++-- man/coredns-metrics.7 | 4 ++-- man/coredns-rewrite.7 | 3 ++- man/coredns-secondary.7 | 3 ++- man/coredns-transfer.7 | 6 +++++- 10 files changed, 54 insertions(+), 27 deletions(-) diff --git a/man/coredns-cache.7 b/man/coredns-cache.7 index bf9f738df..f2bc48d5c 100644 --- a/man/coredns-cache.7 +++ b/man/coredns-cache.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.miek.nl -.TH "COREDNS-CACHE" 7 "January 2020" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-CACHE" 7 "March 2020" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -100,7 +100,7 @@ If monitoring is enabled (via the \fIprometheus\fP plugin) then the following me .IP \(bu 4 \fB\fCcoredns_cache_misses_total{server}\fR - Counter of cache misses. .IP \(bu 4 -\fB\fCcoredns_cache_drops_total{server}\fR - Counter of dropped messages. +\fB\fCcoredns_cache_drops_total{server}\fR - Counter of responses excluded from the cache due to request/response question name mismatch. .IP \(bu 4 \fB\fCcoredns_cache_served_stale_total{server}\fR - Counter of requests served from stale cache entries. diff --git a/man/coredns-cancel.7 b/man/coredns-cancel.7 index 3cb6f6292..dc22a35ee 100644 --- a/man/coredns-cancel.7 +++ b/man/coredns-cancel.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.miek.nl -.TH "COREDNS-CANCEL" 7 "December 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-CANCEL" 7 "March 2020" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -19,6 +19,7 @@ A plugin interested in the cancellation status should call \fB\fCplugin.Done()\f context was canceled due to a timeout the plugin should not write anything back to the client and return a value indicating CoreDNS should not either; a zero return value should suffice for that. +.SH "SYNTAX" .PP .RS diff --git a/man/coredns-dnstap.7 b/man/coredns-dnstap.7 index e891614c5..0a5c63102 100644 --- a/man/coredns-dnstap.7 +++ b/man/coredns-dnstap.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.miek.nl -.TH "COREDNS-DNSTAP" 7 "December 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-DNSTAP" 7 "March 2020" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -7,8 +7,8 @@ .SH "DESCRIPTION" .PP -dnstap is a flexible, structured binary log format for DNS software; see http://dnstap.info -\[la]http://dnstap.info\[ra]. With this +dnstap is a flexible, structured binary log format for DNS software; see https://dnstap.info +\[la]https://dnstap.info\[ra]. With this plugin you make CoreDNS output dnstap logging. .PP @@ -141,5 +141,5 @@ func (h Dnstap) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) .SH "SEE ALSO" .PP dnstap.info -\[la]http://dnstap.info\[ra]. +\[la]https://dnstap.info\[ra]. diff --git a/man/coredns-forward.7 b/man/coredns-forward.7 index 5d3c022aa..725f87845 100644 --- a/man/coredns-forward.7 +++ b/man/coredns-forward.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.miek.nl -.TH "COREDNS-FORWARD" 7 "January 2020" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-FORWARD" 7 "March 2020" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -11,12 +11,14 @@ The \fIforward\fP plugin re-uses already opened sockets to the upstreams. It sup DNS-over-TLS and uses in band health checking. .PP -When it detects an error a health check is performed. This checks runs in a loop, every \fI0.5s\fP, for -as long as the upstream reports unhealthy. Once healthy we stop health checking (until the next -error). The health checks use a recursive DNS query (\fB\fC. IN NS\fR) to get upstream health. Any response -that is not a network error (REFUSED, NOTIMPL, SERVFAIL, etc) is taken as a healthy upstream. The -health check uses the same protocol as specified in \fBTO\fP. If \fB\fCmax_fails\fR is set to 0, no checking -is performed and upstreams will always be considered healthy. +When it detects an error a health check is performed. This checks runs in a loop, starting with +a \fI0.5s\fP interval and exponentially backing off with randomized intervals up to \fI15s\fP for as long +as the upstream reports unhealthy. The exponential backoff will reset to \fI0.5s\fP after 2 minutes. +Once healthy we stop health checking (until the next error). The health checks use a recursive +DNS query (\fB\fC. IN NS\fR) to get upstream health. Any response that is not a network error (REFUSED, +NOTIMPL, SERVFAIL, etc) is taken as a healthy upstream. The health check uses the same protocol as +specified in \fBTO\fP. If \fB\fCmax_fails\fR is set to 0, no checking is performed and upstreams will always +be considered healthy. .PP When \fIall\fP upstreams are down it assumes health checking as a mechanism has failed and will try to @@ -66,7 +68,8 @@ forward FROM TO... { tls CERT KEY CA tls\_servername NAME policy random|round\_robin|sequential - health\_check DURATION + health\_check DURATION [no\_rec] + max\_concurrent MAX } .fi @@ -124,7 +127,22 @@ but they have to use the same \fB\fCtls_servername\fR. E.g. mixing 9.9.9.9 (Quad .RE .IP \(bu 4 -\fB\fChealth_check\fR, use a different \fBDURATION\fP for health checking, the default duration is 0.5s. +\fB\fChealth_check\fR configure the behaviour of health checking of the upstream servers + +.RS +.IP \(en 4 +\fB\fC\fR - use a different duration for health checking, the default duration is 0.5s. +.IP \(en 4 +\fB\fCno_rec\fR - optional argument that sets the RecursionDesired-flag of the dns-query used in health checking to \fB\fCfalse\fR. +The flag is default \fB\fCtrue\fR. + +.RE +.IP \(bu 4 +\fB\fCmax_concurrent\fR \fBMAX\fP will limit the number of concurrent queries to \fBMAX\fP. Any new query that would +raise the number of concurrent queries above the \fBMAX\fP will result in a SERVFAIL response. This +response does not count as a health failure. When choosing a value for \fBMAX\fP, pick a number +at least greater than the expected \fIupstream query rate\fP * \fIlatency\fP of the upstream servers. +As an upper bound for \fBMAX\fP, consider that each concurrent query will use about 2kb of memory. .PP @@ -155,12 +173,13 @@ If monitoring is enabled (via the \fIprometheus\fP plugin) then the following me .IP \(bu 4 \fB\fCcoredns_forward_healthcheck_broken_count_total{}\fR - counter of when all upstreams are unhealthy, and we are randomly (this always uses the \fB\fCrandom\fR policy) spraying to an upstream. - - -.PP +.IP \(bu 4 +\fB\fCmax_concurrent_reject_count_total{}\fR - counter of the number of queries rejected because the +number of concurrent queries were at maximum. Where \fB\fCto\fR is one of the upstream servers (\fBTO\fP from the config), \fB\fCrcode\fR is the returned RCODE from the upstream. + .SH "EXAMPLES" .PP Proxy all requests within \fB\fCexample.org.\fR to a nameserver running on a different port: diff --git a/man/coredns-k8s_external.7 b/man/coredns-k8s_external.7 index 5b43fe125..4c685bb2d 100644 --- a/man/coredns-k8s_external.7 +++ b/man/coredns-k8s_external.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.miek.nl -.TH "COREDNS-K8S_EXTERNAL" 7 "December 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-K8S_EXTERNAL" 7 "March 2020" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -82,6 +82,7 @@ k8s\_external [ZONE...] { \fB\fCttl\fR allows you to set a custom \fBTTL\fP for responses. The default is 5 (seconds). +.SH "EXAMPLES" .PP Enable names under \fB\fCexample.org\fR to be resolved to in-cluster DNS addresses. diff --git a/man/coredns-kubernetes.7 b/man/coredns-kubernetes.7 index ffd3f3563..1490f0519 100644 --- a/man/coredns-kubernetes.7 +++ b/man/coredns-kubernetes.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.miek.nl -.TH "COREDNS-KUBERNETES" 7 "January 2020" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-KUBERNETES" 7 "March 2020" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -79,7 +79,7 @@ If this option is omitted all namespaces are exposed \fB\fCnamespace_labels\fR \fBEXPRESSION\fP only expose the records for Kubernetes namespaces that match this label selector. The label selector syntax is described in the Kubernetes User Guide - Labels -\[la]http://kubernetes.io/docs/user-guide/labels/\[ra]. An example that +\[la]https://kubernetes.io/docs/user-guide/labels/\[ra]. An example that only exposes namespaces labeled as "istio-injection=enabled", would use: \fB\fClabels istio-injection=enabled\fR. .IP \(bu 4 diff --git a/man/coredns-metrics.7 b/man/coredns-metrics.7 index ca895cacb..943069f7e 100644 --- a/man/coredns-metrics.7 +++ b/man/coredns-metrics.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.miek.nl -.TH "COREDNS-METRICS" 7 "December 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-METRICS" 7 "March 2020" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -19,7 +19,7 @@ The following metrics are exported: .IP \(bu 4 \fB\fCcoredns_dns_request_count_total{server, zone, proto, family}\fR - total query count. .IP \(bu 4 -\fB\fCcoredns_dns_request_duration_seconds{server, zone}\fR - duration to process each query. +\fB\fCcoredns_dns_request_duration_seconds{server, zone, type}\fR - duration to process each query. .IP \(bu 4 \fB\fCcoredns_dns_request_size_bytes{server, zone, proto}\fR - size of the request in bytes. .IP \(bu 4 diff --git a/man/coredns-rewrite.7 b/man/coredns-rewrite.7 index 0d0ebff7e..8dcea09c5 100644 --- a/man/coredns-rewrite.7 +++ b/man/coredns-rewrite.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.miek.nl -.TH "COREDNS-REWRITE" 7 "January 2020" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-REWRITE" 7 "March 2020" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -61,6 +61,7 @@ will behave as follows: \fB\fCstop\fR will consider the current rule the last rule and will not continue. The default behaviour is \fB\fCstop\fR +.SH "EXAMPLES" .SS "NAME FIELD REWRITES" .PP The \fB\fCrewrite\fR plugin offers the ability to match the name in the question section of diff --git a/man/coredns-secondary.7 b/man/coredns-secondary.7 index 4b01b9a22..f5259c542 100644 --- a/man/coredns-secondary.7 +++ b/man/coredns-secondary.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.miek.nl -.TH "COREDNS-SECONDARY" 7 "January 2020" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-SECONDARY" 7 "March 2020" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -11,6 +11,7 @@ With \fIsecondary\fP you can transfer (via AXFR) a zone from another server. The \fInot committed\fP to disk (a violation of the RFC). This means restarting CoreDNS will cause it to retrieve all secondary zones. +.SH "SYNTAX" .PP .RS diff --git a/man/coredns-transfer.7 b/man/coredns-transfer.7 index c1635a781..d67f58101 100644 --- a/man/coredns-transfer.7 +++ b/man/coredns-transfer.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.miek.nl -.TH "COREDNS-TRANSFER" 7 "January 2020" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-TRANSFER" 7 "March 2020" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -39,3 +39,7 @@ block that serves the same zone, and implements \fB\fCtransfer.Transferer\fR. transfers to all hosts. +.SH "EXAMPLES" +.PP +TODO +