diff options
36 files changed, 423 insertions, 286 deletions
diff --git a/man/coredns-any.7 b/man/coredns-any.7 new file mode 100644 index 000000000..6d8f795da --- /dev/null +++ b/man/coredns-any.7 @@ -0,0 +1,53 @@ +.\" Generated by Mmark Markdown Processer - mmark.nl +.TH "COREDNS-ANY" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" + +.SH "NAME" +.PP +\fIany\fP - give a minimal response to ANY queries. + +.SH "DESCRIPTION" +.PP +\fIany\fP basically blocks ANY queries by responding to them with a short HINFO reply. See RFC +8482 +\[la]https://tools.ietf.org/html/rfc8482\[ra] for details. + +.SH "SYNTAX" +.PP +.RS + +.nf +any + +.fi +.RE + +.SH "EXAMPLES" +.PP +.RS + +.nf +example.org { + whoami + any +} + +.fi +.RE + +.PP +A \fB\fCdig +nocmd ANY example.org +noall +answer\fR now returns: + +.PP +.RS + +.nf +example.org. 8482 IN HINFO "ANY obsoleted" "See RFC 8482" + +.fi +.RE + +.SH "ALSO SEE" +.PP +RFC 8482 +\[la]https://tools.ietf.org/html/rfc8482\[ra]. + diff --git a/man/coredns-auto.7 b/man/coredns-auto.7 index 828767d98..67d246cf7 100644 --- a/man/coredns-auto.7 +++ b/man/coredns-auto.7 @@ -1,18 +1,18 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-AUTO" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-AUTO" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIauto\fP - enables serving zone data from an RFC 1035-style master file, which is automatically picked up from disk. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The \fIauto\fP plugin is used for an "old-style" DNS server. It serves from a preloaded file that exists on disk. If the zone file contains signatures (i.e. is signed, i.e. using DNSSEC) correct DNSSEC answers are returned. Only NSEC is supported! If you use this setup \fIyou\fP are responsible for re-signing the zonefile. New or changed zones are automatically picked up from disk. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -72,7 +72,7 @@ even though the directive might only receive queries for a specific zone. I.e: Will happily pick up a zone for \fB\fCexample.COM\fR, except it will never be queried, because the \fIauto\fP directive only is authoritative for \fB\fCexample.ORG\fR. -.SH EXAMPLES +.SH "EXAMPLES" .PP Load \fB\fCorg\fR domains from \fB\fC/etc/coredns/zones/org\fR and allow transfers to the internet, but send notifies to 10.240.1.1 diff --git a/man/coredns-autopath.7 b/man/coredns-autopath.7 index db54bcc57..9150dce02 100644 --- a/man/coredns-autopath.7 +++ b/man/coredns-autopath.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-AUTOPATH" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-AUTOPATH" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIautopath\fP - allows for server-side search path completion. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP If it sees a query that matches the first element of the configured search path, \fIautopath\fP will follow the chain of search path elements and return the first reply that is not NXDOMAIN. On any @@ -13,7 +13,7 @@ failures, the original reply is returned. Because \fIautopath\fP returns a reply the original question it will add a CNAME that points from the original name (with the search path element in it) to the name of this answer. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -34,7 +34,7 @@ query) to retrieve the search list it should use. .PP If a plugin implements the \fB\fCAutoPather\fR interface then it can be used. -.SH METRICS +.SH "METRICS" .PP If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric is exported: @@ -45,7 +45,7 @@ If monitoring is enabled (via the \fIprometheus\fP directive) then the following .PP The \fB\fCserver\fR label is explained in the \fImetrics\fP plugin documentation. -.SH EXAMPLES +.SH "EXAMPLES" .PP .RS @@ -71,7 +71,7 @@ autopath @kubernetes .PP Use the search path dynamically retrieved from the \fIkubernetes\fP plugin. -.SH KNOWN ISSUES +.SH "KNOWN ISSUES" .PP In Kubernetes, \fIautopath\fP is not compatible with pods running from Windows nodes. diff --git a/man/coredns-bind.7 b/man/coredns-bind.7 index cffaac026..67fbeec5c 100644 --- a/man/coredns-bind.7 +++ b/man/coredns-bind.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-BIND" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-BIND" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIbind\fP - overrides the host to which the server should bind. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP Normally, the listener binds to the wildcard host. However, you may want the listener to bind to another IP instead. @@ -16,7 +16,7 @@ If several addresses are provided, a listener will be open on each of the IP pro .PP Each address has to be an IP of one of the interfaces of the host. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -30,7 +30,7 @@ bind ADDRESS ... \fBADDRESS\fP is an IP address to bind to. When several addresses are provided a listener will be opened on each of the addresses. -.SH EXAMPLES +.SH "EXAMPLES" .PP To make your socket accessible only to that machine, bind to IP 127.0.0.1 (localhost): diff --git a/man/coredns-cache.7 b/man/coredns-cache.7 index 42323a654..4388d8beb 100644 --- a/man/coredns-cache.7 +++ b/man/coredns-cache.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-CACHE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-CACHE" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIcache\fP - enables a frontend cache. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP With \fIcache\fP enabled, all records except zone transfers and metadata records will be cached for up to 3600s. Caching is mostly useful in a scenario when fetching data from the backend (upstream, @@ -14,7 +14,7 @@ database, etc.) is expensive. .PP This plugin can only be used once per Server Block. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -72,7 +72,7 @@ which defaults to \fB\fC10%\fR, or latest 1 second before TTL expiration. Values Note the percent sign is mandatory. \fBPERCENTAGE\fP is treated as an \fB\fCint\fR. -.SH CAPACITY AND EVICTION +.SH "CAPACITY AND EVICTION" .PP If \fBCAPACITY\fP \fIis not\fP specified, the default cache size is 9984 per cache. The minimum allowed cache size is 1024. If \fBCAPACITY\fP \fIis\fP specified, the actual cache size used will be rounded down to the nearest number divisible by 256 (so all shards are equal in size). @@ -83,7 +83,7 @@ Since shards don't fill up perfectly evenly, evictions will occur before the ent Each shard capacity is equal to the total cache size / number of shards (256). Eviction is random, not TTL based. Entries with 0 TTL will remain in the cache until randomly evicted when the shard reaches capacity. -.SH METRICS +.SH "METRICS" .PP If monitoring is enabled (via the \fIprometheus\fP directive) then the following metrics are exported: @@ -101,7 +101,7 @@ If monitoring is enabled (via the \fIprometheus\fP directive) then the following Cache types are either "denial" or "success". \fB\fCServer\fR is the server handling the request, see the metrics plugin for documentation. -.SH EXAMPLES +.SH "EXAMPLES" .PP Enable caching for all zones, but cap everything to a TTL of 10 seconds: diff --git a/man/coredns-cancel.7 b/man/coredns-cancel.7 index 9ceeff451..2c6f095c3 100644 --- a/man/coredns-cancel.7 +++ b/man/coredns-cancel.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-CANCEL" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-CANCEL" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIcancel\fP - a plugin that cancels a request's context after 5001 milliseconds. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The \fIcancel\fP plugin creates a canceling context for each request. It adds a timeout that gets triggered after 5001 milliseconds. @@ -32,7 +32,7 @@ cancel [TIMEOUT] \fBTIMEOUT\fP allows setting a custom timeout. The default timeout is 5001 milliseconds (\fB\fC5001 ms\fR) -.SH EXAMPLES +.SH "EXAMPLES" .PP .RS @@ -60,7 +60,7 @@ Or with a custom timeout: .fi .RE -.SH ALSO SEE +.SH "ALSO SEE" .PP The Go documentation for the context package. diff --git a/man/coredns-chaos.7 b/man/coredns-chaos.7 index fca9a7620..31d2655a2 100644 --- a/man/coredns-chaos.7 +++ b/man/coredns-chaos.7 @@ -1,16 +1,16 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-CHAOS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-CHAOS" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIchaos\fP - allows for responding to TXT queries in the CH class. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP This is useful for retrieving version or author information from the server by querying a TXT record for a special domainname in the CH class. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -31,7 +31,7 @@ Note that you have to make sure that this plugin will get actual queries for the following zones: \fB\fCversion.bind\fR, \fB\fCversion.server\fR, \fB\fCauthors.bind\fR, \fB\fChostname.bind\fR and \fB\fCid.server\fR. -.SH EXAMPLES +.SH "EXAMPLES" .PP Specify all the zones in full. diff --git a/man/coredns-debug.7 b/man/coredns-debug.7 index cf21cb102..7880e9fe4 100644 --- a/man/coredns-debug.7 +++ b/man/coredns-debug.7 @@ -1,20 +1,20 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-DEBUG" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-DEBUG" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIdebug\fP - disables the automatic recovery upon a crash so that you'll get a nice stack trace. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP -Normally CoreDNS will recover from panics, using \fIdebug\fP inhibits this. The main use of \fIdebug\fP is -to help testing. A side effect of using \fIdebug\fP is that \fB\fClog.Debug\fR and \fB\fClog.Debugf\fR will be printed -to standard output. +Normally CoreDNS will recover from panics; using \fIdebug\fP inhibits this. The main use of \fIdebug\fP is +to help in testing. A side effect of using \fIdebug\fP is that \fB\fClog.Debug\fR and \fB\fClog.Debugf\fR messages +will be printed to standard output. .PP -Note that the \fIerrors\fP plugin (if loaded) will also set a \fB\fCrecover\fR negating this setting. +Note that the \fIerrors\fP plugin (if loaded) will also set a \fB\fCrecover\fR, negating this setting. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -25,7 +25,7 @@ debug .RE .PP -Some plugin will debug log DNS messages. This is done in the following format: +Some plugins will send debug log DNS messages. This is done in the following format: .PP .RS @@ -40,14 +40,14 @@ debug: 00002a .RE .PP -Using \fB\fCtext2pcap\fR (part of Wireshark) this can be converted back to binary, with the following -command line: \fB\fCtext2pcap -i 17 -u 53,53\fR. Where 17 is the protocol (UDP) and 53 are the ports. These -ports allow wireshark to detect these packets as DNS messages. +Using \fB\fCtext2pcap\fR (part of Wireshark), this can be converted back to binary, with the following +command line: \fB\fCtext2pcap -i 17 -u 53,53\fR, where 17 is the protocol (UDP) and 53 are the ports. These +ports allow Wireshark to detect these packets as DNS messages. .PP -Each plugin can decide to dump messages to aid in debugging. +Each plugin can decide whether to dump messages to aid in debugging. -.SH EXAMPLES +.SH "EXAMPLES" .PP Disable the ability to recover from crashes and show debug logging: @@ -62,7 +62,7 @@ Disable the ability to recover from crashes and show debug logging: .fi .RE -.SH ALSO SEE +.SH "ALSO SEE" .PP https://www.wireshark.org/docs/man-pages/text2pcap.html \[la]https://www.wireshark.org/docs/man-pages/text2pcap.html\[ra]. diff --git a/man/coredns-dnssec.7 b/man/coredns-dnssec.7 index d3c6a050b..012afb6d1 100644 --- a/man/coredns-dnssec.7 +++ b/man/coredns-dnssec.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-DNSSEC" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-DNSSEC" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIdnssec\fP - enable on-the-fly DNSSEC signing of served data. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP With \fIdnssec\fP any reply that doesn't (or can't) do DNSSEC will get signed on the fly. Authenticated denial of existence is implemented with NSEC black lies. Using ECDSA as an algorithm is preferred as @@ -14,7 +14,7 @@ this leads to smaller signatures (compared to RSA). NSEC3 is \fInot\fP supported .PP This plugin can only be used once per Server Block. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -67,7 +67,7 @@ generated private key \fB\fCKexample.org+013+45330.private\fR RRSIGs. The default for \fBCAPACITY\fP is 10000. -.SH METRICS +.SH "METRICS" .PP If monitoring is enabled (via the \fIprometheus\fP directive) then the following metrics are exported: @@ -82,7 +82,7 @@ If monitoring is enabled (via the \fIprometheus\fP directive) then the following .PP The label \fB\fCserver\fR indicated the server handling the request, see the \fImetrics\fP plugin for details. -.SH EXAMPLES +.SH "EXAMPLES" .PP Sign responses for \fB\fCexample.org\fR with the key "Kexample.org.+013+45330.key". diff --git a/man/coredns-dnstap.7 b/man/coredns-dnstap.7 index 7165b9f41..1477199e9 100644 --- a/man/coredns-dnstap.7 +++ b/man/coredns-dnstap.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-DNSTAP" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-DNSTAP" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIdnstap\fP - enable logging to dnstap. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP dnstap is a flexible, structured binary log format for DNS software: http://dnstap.info \[la]http://dnstap.info\[ra]. With this @@ -15,7 +15,7 @@ plugin you make CoreDNS output dnstap logging. Note that there is an internal buffer, so expect at least 13 requests before the server sends its dnstap messages to the socket. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -31,7 +31,7 @@ dnstap SOCKET [full] \fB\fCfull\fR to include the wire-format DNS message. -.SH EXAMPLES +.SH "EXAMPLES" .PP Log information about client requests and responses to \fI/tmp/dnstap.sock\fP. @@ -68,7 +68,7 @@ dnstap tcp://127.0.0.1:6000 full .fi .RE -.SH COMMAND LINE TOOL +.SH "COMMAND LINE TOOL" .PP Dnstap has a command line tool that can be used to inspect the logging. The tool can be found at Github: https://github.com/dnstap/golang-dnstap @@ -110,7 +110,7 @@ $ dnstap \-l 127.0.0.1:6000 .fi .RE -.SH USING DNSTAP IN YOUR PLUGIN +.SH "USING DNSTAP IN YOUR PLUGIN" .PP .RS @@ -138,7 +138,7 @@ func (h Dnstap) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) .fi .RE -.SH SEE ALSO +.SH "SEE ALSO" .PP dnstap.info \[la]http://dnstap.info\[ra]. diff --git a/man/coredns-erratic.7 b/man/coredns-erratic.7 index 4af47b009..06be9b3d7 100644 --- a/man/coredns-erratic.7 +++ b/man/coredns-erratic.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-ERRATIC" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-ERRATIC" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIerratic\fP - a plugin useful for testing client behavior. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP \fIerratic\fP returns a static response to all queries, but the responses can be delayed, dropped or truncated. The \fIerratic\fP plugin will respond to every A or AAAA query. For any other type it will return @@ -20,7 +20,7 @@ AXFR request it will respond with a small zone transfer. \fIerratic\fP can also be used in conjunction with the \fIautopath\fP plugin. This is mostly to aid in testing. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -46,11 +46,11 @@ the default for \fBDURATION\fP is 100ms. .PP In case of a zone transfer and truncate the final SOA record \fIisn't\fP added to the response. -.SH READY +.SH "READY" .PP This plugin reports readiness to the ready plugin. -.SH EXAMPLES +.SH "EXAMPLES" .PP .RS @@ -128,7 +128,7 @@ Drop every second query. .fi .RE -.SH ALSO SEE +.SH "ALSO SEE" .PP RFC 3849 \[la]https://tools.ietf.org/html/rfc3849\[ra] and diff --git a/man/coredns-errors.7 b/man/coredns-errors.7 index 8829c0d2a..e148d5f1b 100644 --- a/man/coredns-errors.7 +++ b/man/coredns-errors.7 @@ -1,18 +1,18 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-ERRORS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-ERRORS" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIerrors\fP - enable error logging. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP Any errors encountered during the query processing will be printed to standard output. The errors of particular type can be consolidated and printed once per some period of time. .PP This plugin can only be used once per Server Block. -.SH SYNTAX +.SH "SYNTAX" .PP The basic syntax is: @@ -57,7 +57,7 @@ Multiple \fB\fCconsolidate\fR options with different \fBDURATION\fP and \fBREGEX .PP For better performance, it's recommended to use the \fB\fC^\fR or \fB\fC$\fR metacharacters in regular expression when filtering error messages by prefix or suffix, e.g. \fB\fC^failed to .*\fR, or \fB\fC.* timeout$\fR. -.SH EXAMPLES +.SH "EXAMPLES" .PP Use the \fIwhoami\fP to respond to queries and Log errors to standard output. diff --git a/man/coredns-file.7 b/man/coredns-file.7 index d4a8e7e6d..5359a649d 100644 --- a/man/coredns-file.7 +++ b/man/coredns-file.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-FILE" 7 "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-FILE" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -50,7 +50,7 @@ file DBFILE [ZONES... ] { \fB\fCtransfer\fR enables zone transfers. It may be specified multiples times. \fB\fCTo\fR or \fB\fCfrom\fR signals the direction. \fBADDRESS\fP must be denoted in CIDR notation (e.g., 127.0.0.1/32) or just as plain addresses. The special wildcard \fB\fC*\fR means: the entire internet (only valid for 'transfer to'). -When an address is specified a notify message will be send whenever the zone is reloaded. +When an address is specified a notify message will be sent whenever the zone is reloaded. .IP \(bu 4 \fB\fCreload\fR interval to perform a reload of the zone if the SOA version changes. Default is one minute. Value of \fB\fC0\fR means to not scan for changes and reload. For example, \fB\fC30s\fR checks the zonefile every 30 seconds @@ -97,3 +97,49 @@ Or use a single zone file for multiple zones: .fi .RE +.PP +Note that if you have a configuration like the following you may run into a problem of the origin +not being correctly recognized: + +.PP +.RS + +.nf +\&. { + file db.example.org +} + +.fi +.RE + +.PP +We omit the origin for the file \fB\fCdb.example.org\fR, so this references the zone in the server block, +which, in this case, is the root zone. Any contents of \fB\fCdb.example.org\fR will then read with that +origin set; this may or may not do what you want. +It's better to be explicit here and specify the correct origin. This can be done in two ways: + +.PP +.RS + +.nf +\&. { + file db.example.org example.org +} + +.fi +.RE + +.PP +Or + +.PP +.RS + +.nf +example.org { + file db.example.org +} + +.fi +.RE + diff --git a/man/coredns-forward.7 b/man/coredns-forward.7 index 647b48e79..baf4e87b7 100644 --- a/man/coredns-forward.7 +++ b/man/coredns-forward.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-FORWARD" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-FORWARD" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIforward\fP - facilitates proxying DNS messages to upstream resolvers. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The \fIforward\fP plugin re-uses already opened sockets to the upstreams. It supports UDP, TCP and DNS-over-TLS and uses in band health checking. @@ -25,7 +25,7 @@ connect to a random upstream (which may or may not work). .PP This plugin can only be used once per Server Block. -.SH SYNTAX +.SH "SYNTAX" .PP In its most basic form, a simple forwarder uses this syntax: @@ -140,7 +140,7 @@ dialTimeout by default is 30 sec, and can decrease automatically down to 100ms readTimeout by default is 2 sec, and can decrease automatically down to 200ms -.SH METRICS +.SH "METRICS" .PP If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric are exported: @@ -164,7 +164,7 @@ Where \fB\fCto\fR is one of the upstream servers (\fBTO\fP from the config), \fB the incoming query ("tcp" or "udp"), and family the transport family ("1" for IPv4, and "2" for IPv6). -.SH EXAMPLES +.SH "EXAMPLES" .PP Proxy all requests within \fB\fCexample.org.\fR to a nameserver running on a different port: @@ -264,12 +264,12 @@ Or with multiple upstreams from the same provider .fi .RE -.SH BUGS +.SH "BUGS" .PP The TLS config is global for the whole forwarding proxy if you need a different \fB\fCtls_servername\fR for different upstreams you're out of luck. -.SH ALSO SEE +.SH "ALSO SEE" .PP RFC 7858 \[la]https://tools.ietf.org/html/rfc7858\[ra] for DNS over TLS. diff --git a/man/coredns-grpc.7 b/man/coredns-grpc.7 index ce1d5a0b8..29d9a4a9e 100644 --- a/man/coredns-grpc.7 +++ b/man/coredns-grpc.7 @@ -1,18 +1,18 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-GRPC" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-GRPC" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIgrpc\fP - facilitates proxying DNS messages to upstream resolvers via gRPC protocol. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The \fIgrpc\fP plugin supports gRPC and TLS. .PP This plugin can only be used once per Server Block. -.SH SYNTAX +.SH "SYNTAX" .PP In its most basic form: @@ -88,7 +88,7 @@ but they have to use the same \fB\fCtls_servername\fR. E.g. mixing 9.9.9.9 (Quad Also note the TLS config is "global" for the whole grpc proxy if you need a different \fB\fCtls-name\fR for different upstreams you're out of luck. -.SH METRICS +.SH "METRICS" .PP If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric are exported: @@ -101,7 +101,7 @@ If monitoring is enabled (via the \fIprometheus\fP directive) then the following and we are randomly (this always uses the \fB\fCrandom\fR policy) spraying to an upstream. -.SH EXAMPLES +.SH "EXAMPLES" .PP Proxy all requests within \fB\fCexample.org.\fR to a nameserver running on a different port: @@ -198,7 +198,7 @@ Or with multiple upstreams from the same provider .fi .RE -.SH BUGS +.SH "BUGS" .PP The TLS config is global for the whole grpc proxy if you need a different \fB\fCtls_servername\fR for different upstreams you're out of luck. diff --git a/man/coredns-health.7 b/man/coredns-health.7 index 47eee8671..8a114089c 100644 --- a/man/coredns-health.7 +++ b/man/coredns-health.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-HEALTH" 7 "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-HEALTH" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -7,7 +7,7 @@ .SH "DESCRIPTION" .PP -Enabled process wide health endpoint. When CoreDNS is up and running this returns a 200 OK http +Enabled process wide health endpoint. When CoreDNS is up and running this returns a 200 OK HTTP status code. The health is exported, by default, on port 8080/health . .SH "SYNTAX" @@ -113,10 +113,3 @@ Set a lameduck duration of 1 second: .fi .RE -.SH "BUGS" -.PP -When reloading, the health handler is stopped before the new server instance is started. If that -new server fails to start, then the initial server instance is still available and DNS queries still -served, but health handler stays down. Health will not reply HTTP request until a successful reload -or a complete restart of CoreDNS. - diff --git a/man/coredns-hosts.7 b/man/coredns-hosts.7 index 089aeae7c..93ad19d3b 100644 --- a/man/coredns-hosts.7 +++ b/man/coredns-hosts.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-HOSTS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-HOSTS" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIhosts\fP - enables serving zone data from a \fB\fC/etc/hosts\fR style file. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The hosts plugin is useful for serving zones from a \fB\fC/etc/hosts\fR file. It serves from a preloaded file that exists on disk. It checks the file for changes and updates the zones accordingly. This @@ -19,9 +19,9 @@ Should the file be deleted, any inlined content will continue to be served. When .PP This plugin can only be used once per Server Block. -.SH THE HOSTS FILE +.SH "THE HOSTS FILE" .PP -Commonly the entries are of the from \fB\fCIP_address canonical_hostname [aliases...]\fR as explained by the hosts(5) man page. +Commonly the entries are of the form \fB\fCIP_address canonical_hostname [aliases...]\fR as explained by the hosts(5) man page. .PP Examples: @@ -39,11 +39,11 @@ fdfc:a744:27b5:3b0e::1 example.com example .fi .RE -.SS PTR RECORDS +.SS "PTR RECORDS" .PP PTR records for reverse lookups are generated automatically by CoreDNS (based on the hosts file entries) and cannot be created manually. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -83,7 +83,7 @@ is authoritative. If specific zones are listed (for example \fB\fCin-addr.arpa\f queries for those zones will be subject to fallthrough. -.SH EXAMPLES +.SH "EXAMPLES" .PP Load \fB\fC/etc/hosts\fR file. @@ -146,7 +146,7 @@ Load hosts file inlined in Corefile. .fi .RE -.SH SEE ALSO +.SH "SEE ALSO" .PP The form of the entries in the \fB\fC/etc/hosts\fR file are based on IETF RFC 952 \[la]https://tools.ietf.org/html/rfc952\[ra] which was updated by IETF RFC 1123 diff --git a/man/coredns-import.7 b/man/coredns-import.7 index 8d7768da4..cc4ab58d4 100644 --- a/man/coredns-import.7 +++ b/man/coredns-import.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-IMPORT" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-IMPORT" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIimport\fP - include files or reference snippets from a Corefile. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The \fIimport\fP plugin can be used to include files into the main configuration. Another use it to reference predefined snippets. Both can help to avoid some duplication. @@ -14,7 +14,7 @@ reference predefined snippets. Both can help to avoid some duplication. This is a unique directive in that \fIimport\fP can appear outside of a server block. In other words, it can appear at the top of a Corefile where an address would normally be. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -29,13 +29,13 @@ import PATTERN this line, as if that file's contents appeared here to begin with. -.SH FILES +.SH "FILES" .PP You can use \fIimport\fP to include a file or files. This file's location is relative to the Corefile's location. It is an error if a specific file cannot be found, but an empty glob pattern is not an error. -.SH SNIPPETS +.SH "SNIPPETS" .PP You can define snippets to be reused later in your Corefile by defining a block with a single-token label surrounded by parentheses: @@ -63,7 +63,7 @@ import mysnippet .fi .RE -.SH EXAMPLES +.SH "EXAMPLES" .PP Import a shared configuration: @@ -104,7 +104,7 @@ import ../zones/* .fi .RE -.SH ALSO SEE +.SH "ALSO SEE" .PP See corefile(5). diff --git a/man/coredns-k8s_external.7 b/man/coredns-k8s_external.7 index c939b7d52..220b9b908 100644 --- a/man/coredns-k8s_external.7 +++ b/man/coredns-k8s_external.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-K8S_EXTERNAL" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-K8S_EXTERNAL" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIk8s_external\fP - resolve load balancer and external IPs from outside kubernetes clusters. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP This plugin allows an additional zone to resolve the external IP address(es) of a Kubernetes service. This plugin is only useful if the \fIkubernetes\fP plugin is also loaded. @@ -46,7 +46,7 @@ CoreDNS service. The \fIk8s_external\fP plugin handles the subdomain \fB\fCdns\fR and the apex of the zone by itself, all other queries are resolved to addresses in the cluster. -.SH SYNTAX +.SH "SYNTAX" .PP .RS diff --git a/man/coredns-kubernetes.7 b/man/coredns-kubernetes.7 index 00a33aa6a..9b71d0b8e 100644 --- a/man/coredns-kubernetes.7 +++ b/man/coredns-kubernetes.7 @@ -1,5 +1,5 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-KUBERNETES" 7 "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-KUBERNETES" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP @@ -324,3 +324,26 @@ For example, wildcards can be used to resolve all Endpoints for a Service as \fB .PP This response can be randomized using the \fB\fCloadbalance\fR plugin +.SH "METADATA" +.PP +The kubernetes plugin will publish the following metadata, if the \fImetadata\fP +plugin is also enabled: + +.IP \(bu 4 +kubernetes/endpoint: the endpoint name in the query +.IP \(bu 4 +kubernetes/kind: the resource kind (pod or svc) in the query +.IP \(bu 4 +kubernetes/namespace: the namespace in the query +.IP \(bu 4 +kubernetes/port-name: the port name in an SRV query +.IP \(bu 4 +kubernetes/protocol: the protocol in an SRV query +.IP \(bu 4 +kubernetes/service: the service name in the query +.IP \(bu 4 +kubernetes/client-namespace: the client pod's namespace, if \fB\fCpods verified\fR mode is enabled +.IP \(bu 4 +kubernetes/client-pod-name: the client pod's name, if \fB\fCpods verified\fR mode is enabled + + diff --git a/man/coredns-loadbalance.7 b/man/coredns-loadbalance.7 index 875db74f3..f10d44d49 100644 --- a/man/coredns-loadbalance.7 +++ b/man/coredns-loadbalance.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-LOADBALANCE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-LOADBALANCE" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIloadbalance\fP - randomize the order of A, AAAA and MX records. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The \fIloadbalance\fP will act as a round-robin DNS loadbalancer by randomizing the order of A, AAAA, and MX records in the answer. @@ -16,7 +16,7 @@ See Wikipedia setup. It will take care to sort any CNAMEs before any address records, because some stub resolver implementations (like glibc) are particular about that. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -30,7 +30,7 @@ loadbalance [POLICY] \fBPOLICY\fP is how to balance, the default, and only option, is "round_robin". -.SH EXAMPLES +.SH "EXAMPLES" .PP Load balance replies coming back from Google Public DNS: diff --git a/man/coredns-log.7 b/man/coredns-log.7 index e39b46800..4c5c8be68 100644 --- a/man/coredns-log.7 +++ b/man/coredns-log.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-LOG" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-LOG" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIlog\fP - enables query logging to standard output. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP By just using \fIlog\fP you dump all queries (and parts for the reply) on standard output. Options exist to tweak the output a little. The date/time prefix on log lines is RFC3339 formatted with @@ -14,7 +14,7 @@ milliseconds. .PP Note that for busy servers logging will incur a performance hit. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -85,7 +85,7 @@ logged whatever we mix together with "all". .PP If no class is specified, it defaults to \fIall\fP. -.SH LOG FORMAT +.SH "LOG FORMAT" .PP You can specify a custom log format with any placeholder values. Log supports both request and response placeholders. diff --git a/man/coredns-loop.7 b/man/coredns-loop.7 index e5d1d8cc1..353ff081a 100644 --- a/man/coredns-loop.7 +++ b/man/coredns-loop.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-LOOP" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-LOOP" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIloop\fP - detect simple forwarding loops and halt the server. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The \fIloop\fP plugin will send a random probe query to ourselves and will then keep track of how many times we see it. If we see it more than twice, we assume CoreDNS has seen a forwarding loop and we halt the process. @@ -18,7 +18,7 @@ death. .PP The query sent is \fB\fC<random number>.<random number>.zone\fR with type set to HINFO. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -28,7 +28,7 @@ loop .fi .RE -.SH EXAMPLES +.SH "EXAMPLES" .PP Start a server on the default port and load the \fIloop\fP and \fIforward\fP plugins. The \fIforward\fP plugin forwards to it self. @@ -57,7 +57,7 @@ plugin/loop: Loop (127.0.0.1:55953 \-> :1053) detected for zone ".", see https:/ .fi .RE -.SH LIMITATIONS +.SH "LIMITATIONS" .PP This plugin only attempts to find simple static forwarding loops at start up time. To detect a loop, the following must be true: @@ -68,7 +68,7 @@ the loop must be present at start up time. the loop must occur for the \fB\fCHINFO\fR query type. -.SH TROUBLESHOOTING +.SH "TROUBLESHOOTING" .PP When CoreDNS logs contain the message \fB\fCLoop ... detected ...\fR, this means that the \fB\fCloop\fR detection plugin has detected an infinite forwarding loop in one of the upstream DNS servers. This is a fatal @@ -90,7 +90,7 @@ in which the loop was detected. Make sure that they are not forwarding to a loc to another DNS server that is forwarding requests back to CoreDNS. If \fB\fCforward\fR is using a file (e.g. \fB\fC/etc/resolv.conf\fR), make sure that file does not contain local addresses. -.SS TROUBLESHOOTING LOOPS IN KUBERNETES CLUSTERS +.SS "TROUBLESHOOTING LOOPS IN KUBERNETES CLUSTERS" .PP When a CoreDNS Pod deployed in Kubernetes detects a loop, the CoreDNS Pod will start to "CrashLoopBackOff". This is because Kubernetes will try to restart the Pod every time CoreDNS detects the loop and exits. @@ -108,7 +108,7 @@ requests to itself. There are many ways to work around this issue, some are listed here: .IP \(bu 4 -Add the following to \fB\fCkubelet\fR: \fB\fC--resolv-conf <path-to-your-real-resolv-conf-file>\fR. Your "real" +Add the following to your \fB\fCkubelet\fR config yaml: \fB\fCresolvConf: <path-to-your-real-resolv-conf-file>\fR (or via command line flag \fB\fC--resolv-conf\fR deprecated in 1.10). Your "real" \fB\fCresolv.conf\fR is the one that contains the actual IPs of your upstream servers, and no local/loopback address. This flag tells \fB\fCkubelet\fR to pass an alternate \fB\fCresolv.conf\fR to Pods. For systems using \fB\fCsystemd-resolved\fR, \fB\fC/run/systemd/resolve/resolv.conf\fR is typically the location of the "real" \fB\fCresolv.conf\fR, diff --git a/man/coredns-metadata.7 b/man/coredns-metadata.7 index edf22f705..8341e146a 100644 --- a/man/coredns-metadata.7 +++ b/man/coredns-metadata.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-METADATA" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-METADATA" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fImetadata\fP - enable a meta data collector. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP By enabling \fImetadata\fP any plugin that implements metadata.Provider interface @@ -28,7 +28,7 @@ plugin enforces is that the labels contains a slash. See the documentation for The value stored is a string. The empty string signals "no meta data". See the documentation for \fB\fCmetadata.ValueFunc\fR on how to retrieve this. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -42,7 +42,7 @@ metadata [ZONES... ] \fBZONES\fP zones metadata should be invoked for. -.SH PLUGINS +.SH "PLUGINS" .PP \fB\fCmetadata.Provider\fR interface needs to be implemented by each plugin willing to provide metadata information for other plugins. It will be called by metadata and gather the information from all @@ -51,11 +51,11 @@ plugins in context. .PP Note: this method should work quickly, because it is called for every request. -.SH EXAMPLES +.SH "EXAMPLES" .PP The \fIrewrite\fP plugin uses meta data to rewrite requests. -.SH ALSO SEE +.SH "ALSO SEE" .PP The Provider interface \[la]https://godoc.org/github.com/coredns/coredns/plugin/metadata#Provider\[ra] and diff --git a/man/coredns-metrics.7 b/man/coredns-metrics.7 index c84480acd..057c60f99 100644 --- a/man/coredns-metrics.7 +++ b/man/coredns-metrics.7 @@ -1,12 +1,12 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-METRICS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-METRICS" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIprometheus\fP - enables Prometheus \[la]https://prometheus.io/\[ra] metrics. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP With \fIprometheus\fP you export metrics from CoreDNS and any plugin that has them. The default location for the metrics is \fB\fClocalhost:9153\fR. The metrics path is fixed to \fB\fC/metrics\fR. @@ -63,7 +63,7 @@ name "dropped" (without a closing dot - this is never a valid domain name). .PP This plugin can only be used once per Server Block. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -80,7 +80,7 @@ For each zone that you want to see metrics for. It optionally takes a bind address to which the metrics are exported; the default listens on \fB\fClocalhost:9153\fR. The metrics path is fixed to \fB\fC/metrics\fR. -.SH EXAMPLES +.SH "EXAMPLES" .PP Use an alternative listening address: @@ -110,7 +110,7 @@ then: .fi .RE -.SH BUGS +.SH "BUGS" .PP When reloading, the Prometheus handler is stopped before the new server instance is started. If that new server fails to start, then the initial server instance is still available and DNS queries still served, diff --git a/man/coredns-nsid.7 b/man/coredns-nsid.7 index 9f679ee15..d22b18af2 100644 --- a/man/coredns-nsid.7 +++ b/man/coredns-nsid.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-NSID" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-NSID" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fInsid\fP - adds an identifier of this server to each reply. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP This plugin implements RFC 5001 \[la]https://tools.ietf.org/html/rfc5001\[ra] and adds an EDNS0 OPT @@ -15,7 +15,7 @@ see which server was responsible for generating the reply and for debugging. .PP This plugin can only be used once per Server Block. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -31,7 +31,7 @@ nsid [DATA] .PP If \fBDATA\fP is not given, the host's name is used. -.SH EXAMPLES +.SH "EXAMPLES" .PP Enable nsid: @@ -71,7 +71,7 @@ And now a client with NSID support will see an OPT record with the NSID option: .fi .RE -.SH ALSO SEE +.SH "ALSO SEE" .PP RFC 5001 \[la]https://tools.ietf.org/html/rfc5001\[ra] diff --git a/man/coredns-pprof.7 b/man/coredns-pprof.7 index c842710ab..f5ef12858 100644 --- a/man/coredns-pprof.7 +++ b/man/coredns-pprof.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-PPROF" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-PPROF" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIpprof\fP - publishes runtime profiling data at endpoints under \fB\fC/debug/pprof\fR. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP You can visit \fB\fC/debug/pprof\fR on your site for an index of the available endpoints. By default it will listen on localhost:6053. @@ -17,7 +17,7 @@ you use pprof on a live server, consider restricting access or enabling it only .PP This plugin can only be used once per Server Block. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -53,7 +53,7 @@ runtime.SetBlockProfileRate profiling entails. -.SH EXAMPLES +.SH "EXAMPLES" .PP Enable a pprof endpoint: @@ -101,7 +101,7 @@ Listen on an all addresses on port 6060, and enable block profiling .fi .RE -.SH ALSO SEE +.SH "ALSO SEE" .PP See Go's pprof documentation \[la]https://golang.org/pkg/net/http/pprof/\[ra] and Profiling Go diff --git a/man/coredns-ready.7 b/man/coredns-ready.7 index 7e709c077..e0d36358f 100644 --- a/man/coredns-ready.7 +++ b/man/coredns-ready.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-READY" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-READY" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIready\fP - enables a readiness check HTTP endpoint. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP By enabling \fIready\fP an HTTP endpoint on port 8181 will return 200 OK, when all plugins that are able to signal readiness have done so. If some are not ready yet the endpoint will return a 503 with the @@ -14,9 +14,11 @@ will not be queried again. .PP Each Server Block that enables the \fIready\fP plugin will have the plugins \fIin that server block\fP -report readiness into the /ready endpoint that runs on the same port. +report readiness into the /ready endpoint that runs on the same port. This also means that the +\fIsame\fP plugin with different configurations (in potentialy \fIdifferent\fP Server Blocks) will have +their readiness reported as the union of their respective readinesses. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -29,14 +31,14 @@ ready [ADDRESS] .PP \fIready\fP optionally takes an address; the default is \fB\fC:8181\fR. The path is fixed to \fB\fC/ready\fR. The readiness endpoint returns a 200 response code and the word "OK" when this server is ready. It -returns a 503 otherwise. +returns a 503 otherwise \fIand\fP the list of plugins that are not ready. -.SH PLUGINS +.SH "PLUGINS" .PP Any plugin wanting to signal readiness will need to implement the \fB\fCready.Readiness\fR interface by implementing a method \fB\fCReady() bool\fR that returns true when the plugin is ready and false otherwise. -.SH EXAMPLES +.SH "EXAMPLES" .PP Let \fIready\fP report readiness for both the \fB\fC.\fR and \fB\fCexample.org\fR servers (assuming the \fIwhois\fP plugin also exports readiness): diff --git a/man/coredns-reload.7 b/man/coredns-reload.7 index 79ca87861..e8aca54eb 100644 --- a/man/coredns-reload.7 +++ b/man/coredns-reload.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-RELOAD" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-RELOAD" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIreload\fP - allows automatic reload of a changed Corefile. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP This plugin allows automatic reload of a changed \fICorefile\fP. To enable automatic reloading of \fIzone file\fP changes, use the \fB\fCauto\fR plugin. @@ -38,7 +38,7 @@ Jitter is re-calculated whenever the Corefile is reloaded. .PP This plugin can only be used once per Server Block. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -61,7 +61,7 @@ Minimal value for \fBINTERVAL\fP is 2s, and for \fBJITTER\fP is 1s If \fBJITTER\fP is more than half of \fBINTERVAL\fP, it will be set to half of \fBINTERVAL\fP -.SH EXAMPLES +.SH "EXAMPLES" .PP Check with the default intervals: @@ -92,7 +92,7 @@ Check every 10 seconds (jitter is automatically set to 10 / 2 = 5 in this case): .fi .RE -.SH BUGS +.SH "BUGS" .PP The reload happens without data loss (i.e. DNS queries keep flowing), but there is a corner case where the reload fails, and you loose functionality. Consider the following Corefile: @@ -134,7 +134,7 @@ In general be careful with assigning new port and expecting reload to work fully Also any \fB\fCimport\fR statement is not discovered by this plugin. This means if any of these imported files changes the \fIreload\fP plugin is ignorant of that fact. -.SH ALSO SEE +.SH "ALSO SEE" .PP See coredns-import(7) and corefile(5). diff --git a/man/coredns-rewrite.7 b/man/coredns-rewrite.7 index ea0ecd481..d3adccce4 100644 --- a/man/coredns-rewrite.7 +++ b/man/coredns-rewrite.7 @@ -1,18 +1,18 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-REWRITE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-REWRITE" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIrewrite\fP - performs internal message rewriting. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP Rewrites are invisible to the client. There are simple rewrites (fast) and complex rewrites (slower), but they're powerful enough to accommodate most dynamic back-end applications. -.SH SYNTAX +.SH "SYNTAX" .PP -A simplified/easy to digest syntax for \fIrewrite\fP is... +A simplified/easy-to-digest syntax for \fIrewrite\fP is... .PP .RS @@ -28,10 +28,10 @@ rewrite [continue|stop] FIELD [FROM TO|FROM TTL] .RS .IP \(en 4 -\fB\fCtype\fR - the type field of the request will be rewritten. FROM/TO must be a DNS record type (\fB\fCA\fR, \fB\fCMX\fR, etc); +\fB\fCtype\fR - the type field of the request will be rewritten. FROM/TO must be a DNS record type (\fB\fCA\fR, \fB\fCMX\fR, etc.); e.g., to rewrite ANY queries to HINFO, use \fB\fCrewrite type ANY HINFO\fR. .IP \(en 4 -\fB\fCclass\fR - the class of the message will be rewritten. FROM/TO must be a DNS class type (\fB\fCIN\fR, \fB\fCCH\fR, or \fB\fCHS\fR) e.g., to rewrite CH queries to IN use \fB\fCrewrite class CH IN\fR. +\fB\fCclass\fR - the class of the message will be rewritten. FROM/TO must be a DNS class type (\fB\fCIN\fR, \fB\fCCH\fR, or \fB\fCHS\fR); e.g., to rewrite CH queries to IN use \fB\fCrewrite class CH IN\fR. .IP \(en 4 \fB\fCname\fR - the query name in the \fIrequest\fP is rewritten; by default this is a full match of the name, e.g., \fB\fCrewrite name example.net example.org\fR. Other match types are supported, see the \fBName Field Rewrites\fP section below. @@ -52,21 +52,24 @@ name, e.g., \fB\fCrewrite name example.net example.org\fR. Other match types are .PP -If you specify multiple rules and an incoming query matches on multiple rules, the rewrite -will behave as following -* \fB\fCcontinue\fR will continue apply the next rule in the rule list. -* \fB\fCstop\fR will consider the current rule is the last rule and will not continue. Default behaviour -for not specifying this rule processing mode is \fB\fCstop\fR +If you specify multiple rules and an incoming query matches multiple rules, the rewrite +will behave as follows: -.SS NAME FIELD REWRITES +.IP \(bu 4 +\fB\fCcontinue\fR will continue applying the next rule in the rule list. +.IP \(bu 4 +\fB\fCstop\fR will consider the current rule the last rule and will not continue. The default behaviour is \fB\fCstop\fR + + +.SS "NAME FIELD REWRITES" .PP -The \fB\fCrewrite\fR plugin offers the ability to match on the name in the question section of -a DNS request. The match could be exact, substring, or based on a prefix, suffix, or regular -expression. If the newly used name is not a legal domain name the plugin returns an error to the +The \fB\fCrewrite\fR plugin offers the ability to match the name in the question section of +a DNS request. The match could be exact, a substring match, or based on a prefix, suffix, or regular +expression. If the newly used name is not a legal domain name, the plugin returns an error to the client. .PP -The syntax for the name re-writing is as follows: +The syntax for name rewriting is as follows: .PP .RS @@ -78,10 +81,10 @@ rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING .RE .PP -The match type, i.e. \fB\fCexact\fR, \fB\fCsubstring\fR, etc., triggers re-write: +The match type, e.g., \fB\fCexact\fR, \fB\fCsubstring\fR, etc., triggers rewrite: .IP \(bu 4 -\fBexact\fP (default): on exact match of the name in the question section of a request +\fBexact\fP (default): on an exact match of the name in the question section of a request .IP \(bu 4 \fBsubstring\fP: on a partial match of the name in the question section of a request .IP \(bu 4 @@ -93,11 +96,11 @@ The match type, i.e. \fB\fCexact\fR, \fB\fCsubstring\fR, etc., triggers re-write .PP -If the match type is omitted, the \fB\fCexact\fR match type is being assumed. +If the match type is omitted, the \fB\fCexact\fR match type is assumed. .PP -The following instruction allows re-writing the name in the query that -contains \fB\fCservice.us-west-1.example.org\fR substring. +The following instruction allows rewriting names in the query that +contain the substring \fB\fCservice.us-west-1.example.org\fR: .PP .RS @@ -114,12 +117,12 @@ Thus: .IP \(bu 4 Incoming Request Name: \fB\fCftp.service.us-west-1.example.org\fR .IP \(bu 4 -Re-written Request Name: \fB\fCftp.service.us-west-1.consul\fR +Rewritten Request Name: \fB\fCftp.service.us-west-1.consul\fR .PP -The following instruction uses regular expressions. The name in a request -matching \fB\fC(.*)-(us-west-1)\.example\.org\fR regular expression is being replaces with +The following instruction uses regular expressions. Names in requests +matching the regular expression \fB\fC(.*)-(us-west-1)\.example\.org\fR are replaced with \fB\fC{1}.service.{2}.consul\fR, where \fB\fC{1}\fR and \fB\fC{2}\fR are regular expression match groups. .PP @@ -137,7 +140,7 @@ Thus: .IP \(bu 4 Incoming Request Name: \fB\fCftp-us-west-1.example.org\fR .IP \(bu 4 -Re-written Request Name: \fB\fCftp.service.us-west-1.consul\fR +Rewritten Request Name: \fB\fCftp.service.us-west-1.consul\fR .PP @@ -152,11 +155,11 @@ rewrite name suffix .schmoogle.com. .google.com. .fi .RE -.SS RESPONSE REWRITES +.SS "RESPONSE REWRITES" .PP -When re-writing incoming DNS requests' names, CoreDNS re-writes the \fB\fCQUESTION SECTION\fR -section of the requests. It may be necessary to re-write the \fB\fCANSWER SECTION\fR of the -requests, because some DNS resolvers would treat the mismatch between \fB\fCQUESTION SECTION\fR +When rewriting incoming DNS requests' names, CoreDNS re-writes the \fB\fCQUESTION SECTION\fR +section of the requests. It may be necessary to rewrite the \fB\fCANSWER SECTION\fR of the +requests, because some DNS resolvers treat mismatches between the \fB\fCQUESTION SECTION\fR and \fB\fCANSWER SECTION\fR as a man-in-the-middle attack (MITM). .PP @@ -173,9 +176,9 @@ rewrite name regex (.*)\-(us\-west\-1)\\.coredns\\.rocks {1}.service.{2}.consul .RE .PP -CoreDNS instance re-wrote the request to \fB\fCftp-us-west-1.coredns.rocks\fR with +CoreDNS rewrote the request from \fB\fCftp-us-west-1.coredns.rocks\fR to \fB\fCftp.service.us-west-1.consul\fR and ultimately resolved it to 3 records. -The resolved records, see \fB\fCANSWER SECTION\fR, were not from \fB\fCcoredns.rocks\fR, but +The resolved records, in the \fB\fCANSWER SECTION\fR below, were not from \fB\fCcoredns.rocks\fR, but rather from \fB\fCservice.us-west-1.consul\fR. .PP @@ -203,11 +206,11 @@ ftp.service.us\-west\-1.consul. 0 IN A 10.30.30.30 .RE .PP -The above is the mismatch. +The above is a mismatch between the question asked and the answer provided. .PP -The following configuration snippet allows for the re-writing of the -\fB\fCANSWER SECTION\fR, provided that the \fB\fCQUESTION SECTION\fR was re-written: +The following configuration snippet allows for rewriting of the +\fB\fCANSWER SECTION\fR, provided that the \fB\fCQUESTION SECTION\fR was rewritten: .PP .RS @@ -264,14 +267,14 @@ rewrite [continue|stop] { .RE .PP -Note that the above syntax is strict. For response rewrites only \fB\fCname\fR +Note that the above syntax is strict. For response rewrites, only \fB\fCname\fR rules are allowed to match the question section, and only by match type -\fB\fCregex\fR. The answer rewrite must be after the name, as ordered in the +\fB\fCregex\fR. The answer rewrite must be after the name, as in the syntax example. There must only be two lines (a \fB\fCname\fR followed by an -\fB\fCanswer\fR) in the brackets, additional rules are not supported. +\fB\fCanswer\fR) in the brackets; additional rules are not supported. .PP -An alternate syntax for the rewrite of DNS request and response is as +An alternate syntax for rewriting a DNS request and response is as follows: .PP @@ -284,8 +287,8 @@ rewrite [continue|stop] name regex STRING STRING answer name STRING STRING .RE .PP -When using \fB\fCexact\fR name rewrite rules, answer gets re-written automatically, -and there is no need defining \fB\fCanswer name\fR instruction. The below rule +When using \fB\fCexact\fR name rewrite rules, the answer gets rewritten automatically, +and there is no need to define \fB\fCanswer name\fR. The rule below rewrites the name in a request from \fB\fCRED\fR to \fB\fCBLUE\fR, and subsequently rewrites the name in a corresponding response from \fB\fCBLUE\fR to \fB\fCRED\fR. The client in the request would see only \fB\fCRED\fR and no \fB\fCBLUE\fR. @@ -299,11 +302,11 @@ rewrite [continue|stop] name exact RED BLUE .fi .RE -.SS TTL FIELD REWRITES +.SS "TTL FIELD REWRITES" .PP -At times, the need for rewriting TTL value could arise. For example, a DNS server -may prevent caching by setting TTL as low as zero (\fB\fC0\fR). An administrator -may want to increase the TTL to prevent caching, e.g. to 15 seconds. +At times, the need to rewrite a TTL value could arise. For example, a DNS server +may not cache records with a TTL of zero (\fB\fC0\fR). An administrator +may want to increase the TTL to ensure it is cached, e.g., by increasing it to 15 seconds. .PP In the below example, the TTL in the answers for \fB\fCcoredns.rocks\fR domain are @@ -321,8 +324,8 @@ being set to \fB\fC15\fR: .RE .PP -By the same token, an administrator may use this feature to force caching by -setting TTL value really low. +By the same token, an administrator may use this feature to prevent or limit caching by +setting the TTL value really low. .PP The syntax for the TTL rewrite rule is as follows. The meaning of @@ -337,9 +340,9 @@ rewrite [continue|stop] ttl [exact|prefix|suffix|substring|regex] STRING SECONDS .fi .RE -.SH EDNS0 OPTIONS +.SH "EDNS0 OPTIONS" .PP -Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request. +Using the FIELD edns0, you can set, append, or replace specific EDNS0 options in the request. .IP \(bu 4 \fB\fCreplace\fR will modify any "matching" option with the specified option. The criteria for "matching" varies based on EDNS0 type. @@ -352,12 +355,12 @@ Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the .PP Currently supported are \fB\fCEDNS0_LOCAL\fR, \fB\fCEDNS0_NSID\fR and \fB\fCEDNS0_SUBNET\fR. -.SS EDNS0_LOCAL +.SS "EDNS0_LOCAL" .PP This has two fields, code and data. A match is defined as having the same code. Data may be a string or a variable. .IP \(bu 4 -A string data can be treated as hex if it starts with \fB\fC0x\fR. Example: +A string data is treated as hex if it starts with \fB\fC0x\fR. Example: .PP @@ -373,7 +376,7 @@ A string data can be treated as hex if it starts with \fB\fC0x\fR. Example: .RE .PP -rewrites the first local option with code 0xffee, setting the data to "abcd". Equivalent: +rewrites the first local option with code 0xffee, setting the data to "abcd". This is equivalent to: .PP .RS @@ -391,8 +394,8 @@ A variable data is specified with a pair of curly brackets \fB\fC{}\fR. Followin {qname}, {qtype}, {client\fIip}, {client\fPport}, {protocol}, {server\fIip}, {server\fPport}. .IP \(bu 4 If the metadata plugin is enabled, then labels are supported as variables if they are presented within curly brackets. -the variable data will be filled with the value associated with that label. If that label is not provided, -the variable will be silently substitute by an empty string. +The variable data will be replaced with the value associated with that label. If that label is not provided, +the variable will be silently substituted with an empty string. .PP @@ -421,12 +424,12 @@ rewrite edns0 local set 0xffee {some\-plugin/some\-label} .fi .RE -.SS EDNS0_NSID +.SS "EDNS0_NSID" .PP This has no fields; it will add an NSID option with an empty string for the NSID. If the option already exists and the action is \fB\fCreplace\fR or \fB\fCset\fR, then the NSID in the option will be set to the empty string. -.SS EDNS0_SUBNET +.SS "EDNS0_SUBNET" .PP This has two fields, IPv4 bitmask length and IPv6 bitmask length. The bitmask length is used to extract the client subnet from the source IP address in the query. @@ -444,12 +447,12 @@ rewrite edns0 subnet set 24 56 .RE .IP \(bu 4 -If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet. +If the query's source IP address is an IPv4 address, the first 24 bits in the IP will be the network subnet. .IP \(bu 4 -If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet. +If the query's source IP address is an IPv6 address, the first 56 bits in the IP will be the network subnet. -.SH FULL SYNTAX +.SH "FULL SYNTAX" .PP The full plugin usage syntax is harder to digest... @@ -463,5 +466,5 @@ rewrite [continue|stop] {type|class|edns0|name [exact|prefix|suffix|substring|re .RE .PP -The syntax above doesn't cover the multi line block option for specifying a name request+response rewrite rule described in the \fBResponse Rewrite\fP section. +The syntax above doesn't cover the multi-line block option for specifying a name request+response rewrite rule described in the \fBResponse Rewrite\fP section. diff --git a/man/coredns-root.7 b/man/coredns-root.7 index 86cb1e178..9c4ee7707 100644 --- a/man/coredns-root.7 +++ b/man/coredns-root.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-ROOT" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-ROOT" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIroot\fP - simply specifies the root of where to find (zone) files. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The default root is the current working directory of CoreDNS. The \fIroot\fP plugin allows you to change this. A relative root path is relative to the current working directory. @@ -13,7 +13,7 @@ this. A relative root path is relative to the current working directory. .PP This plugin can only be used once per Server Block. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -26,7 +26,7 @@ root PATH .PP \fBPATH\fP is the directory to set as CoreDNS' root. -.SH EXAMPLES +.SH "EXAMPLES" .PP Serve zone data (when the \fIfile\fP plugin is used) from \fB\fC/etc/coredns/zones\fR: diff --git a/man/coredns-secondary.7 b/man/coredns-secondary.7 index df5c869d4..82da717a7 100644 --- a/man/coredns-secondary.7 +++ b/man/coredns-secondary.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-SECONDARY" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-SECONDARY" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIsecondary\fP - enables serving a zone retrieved from a primary server. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP With \fIsecondary\fP you can transfer (via AXFR) a zone from another server. The retrieved zone is \fInot committed\fP to disk (a violation of the RFC). This means restarting CoreDNS will cause it to @@ -57,7 +57,7 @@ When a zone is due to be refreshed (Refresh timer fires) a random jitter of 5 se applied, before fetching. In the case of retry this will be 2 seconds. If there are any errors during the transfer the transfer fails; this will be logged. -.SH EXAMPLES +.SH "EXAMPLES" .PP Transfer \fB\fCexample.org\fR from 10.0.1.1, and if that fails try 10.1.2.1. @@ -92,7 +92,7 @@ Or re-export the retrieved zone to other secondaries. .fi .RE -.SH BUGS +.SH "BUGS" .PP Only AXFR is supported and the retrieved zone is not committed to disk. diff --git a/man/coredns-template.7 b/man/coredns-template.7 index b183fd24d..eea407b9e 100644 --- a/man/coredns-template.7 +++ b/man/coredns-template.7 @@ -1,15 +1,15 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-TEMPLATE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-TEMPLATE" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fItemplate\fP - allows for dynamic responses based on the incoming query. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The \fItemplate\fP plugin allows you to dynamically respond to queries by just writing a (Go) template. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -58,7 +58,7 @@ At least one \fB\fCanswer\fR or \fB\fCrcode\fR directive is needed (e.g. \fB\fCr Also see \[la]#also-see\[ra] contains an additional reading list. -.SH TEMPLATES +.SH "TEMPLATES" .PP Each resource record is a full-featured Go template \[la]https://golang.org/pkg/text/template/\[ra] with the following predefined data @@ -91,7 +91,7 @@ The output of the template must be a RFC 1035 Caddy) while \fB\fC{{ $var }}\fR will work. See Bugs \[la]#bugs\[ra] and corefile(5). -.SH METRICS +.SH "METRICS" .PP If monitoring is enabled (via the \fIprometheus\fP directive) then the following metrics are exported: @@ -107,8 +107,8 @@ If monitoring is enabled (via the \fIprometheus\fP directive) then the following Both failure cases indicate a problem with the template configuration. The \fB\fCserver\fR label indicates the server incrementing the metric, see the \fImetrics\fP plugin for details. -.SH EXAMPLES -.SS RESOLVE EVERYTHING TO NXDOMAIN +.SH "EXAMPLES" +.SS "RESOLVE EVERYTHING TO NXDOMAIN" .PP The most simplistic template is @@ -133,7 +133,7 @@ All queries will be answered (no \fB\fCfallthrough\fR) The answer is always NXDOMAIN -.SS RESOLVE .INVALID AS NXDOMAIN +.SS "RESOLVE .INVALID AS NXDOMAIN" .PP The \fB\fC.invalid\fR domain is a reserved TLD (see RFC 2606 Reserved Top Level DNS Names \[la]https://tools.ietf.org/html/rfc2606#section-2\[ra]) to indicate invalid domains. @@ -164,7 +164,7 @@ Querying \fB\fC.invalid\fR in the \fB\fCCH\fR class will also cause a NXDOMAIN/S The default regex is \fB\fC.*\fR -.SS BLOCK INVALID SEARCH DOMAIN COMPLETIONS +.SS "BLOCK INVALID SEARCH DOMAIN COMPLETIONS" .PP Imagine you run \fB\fCexample.com\fR with a datacenter \fB\fCdc1.example.com\fR. The datacenter domain is part of the DNS search domain. @@ -212,7 +212,7 @@ A more verbose regex based equivalent would be .PP The regex-based version can do more complex matching/templating while zone-based templating is easier to read and use. -.SS RESOLVE A/PTR FOR .EXAMPLE +.SS "RESOLVE A/PTR FOR .EXAMPLE" .PP .RS @@ -252,7 +252,7 @@ Having templates to map certain PTR/A pairs is a common pattern. .PP Fallthrough is needed for mixed domains where only some responses are templated. -.SS RESOLVE MULTIPLE IP PATTERNS +.SS "RESOLVE MULTIPLE IP PATTERNS" .PP .RS @@ -274,7 +274,7 @@ Fallthrough is needed for mixed domains where only some responses are templated. .PP Named capture groups can be used to template one response for multiple patterns. -.SS RESOLVE A AND MX RECORDS FOR IP TEMPLATES IN .EXAMPLE +.SS "RESOLVE A AND MX RECORDS FOR IP TEMPLATES IN .EXAMPLE" .PP .RS @@ -298,7 +298,7 @@ Named capture groups can be used to template one response for multiple patterns. .fi .RE -.SS ADDING AUTHORITATIVE NAMESERVERS TO THE RESPONSE +.SS "ADDING AUTHORITATIVE NAMESERVERS TO THE RESPONSE" .PP .RS @@ -330,7 +330,7 @@ Named capture groups can be used to template one response for multiple patterns. .fi .RE -.SH ALSO SEE +.SH "ALSO SEE" .IP \(bu 4 Go regexp \[la]https://golang.org/pkg/regexp/\[ra] for details about the regex implementation @@ -346,7 +346,7 @@ Go template \[la]https://golang.org/pkg/text/template/\[ra] for the template language reference -.SH BUGS +.SH "BUGS" .PP CoreDNS supports caddyfile environment variables \[la]https://caddyserver.com/docs/caddyfile#env\[ra] diff --git a/man/coredns-tls.7 b/man/coredns-tls.7 index 2a8c01218..5674afca6 100644 --- a/man/coredns-tls.7 +++ b/man/coredns-tls.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-TLS" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-TLS" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fItls\fP - allows you to configure the server certificates for the TLS and gRPC servers. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP CoreDNS supports queries that are encrypted using TLS (DNS over Transport Layer Security, RFC 7858) or are using gRPC (https://grpc.io/ @@ -20,7 +20,7 @@ DNS-over-TLS and DNS-over-gRPC. If the \fB\fCtls\fR directive is omitted, then n The gRPC protobuffer is defined in \fB\fCpb/dns.proto\fR. It defines the proto as a simple wrapper for the wire data of a DNS message. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -33,7 +33,24 @@ tls CERT KEY [CA] .PP Parameter CA is optional. If not set, system CAs can be used to verify the client certificate -.SH EXAMPLES +.PP +.RS + +.nf +tls CERT KEY [CA] { + client\_auth nocert|request|require|verify\_if\_given|require\_and\_verify +} + +.fi +.RE + +.PP +If client\fIauth option is specified, it controls the client authentication policy. +The option value corresponds to the ClientAuthType values of the Go tls package +\[la]https://golang.org/pkg/crypto/tls/#ClientAuthType\[ra]: NoClientCert, RequestClientCert, RequireAnyClientCert, VerifyClientCertIfGiven, and RequireAndVerifyClientCert, respectively. +The default is "nocert". Note that it makes no sense to specify parameter CA unless this option is set to verify\fPif\fIgiven or require\fPand_verify. + +.SH "EXAMPLES" .PP Start a DNS-over-TLS server that picks up incoming DNS-over-TLS queries on port 5553 and uses the nameservers defined in \fB\fC/etc/resolv.conf\fR to resolve the query. This proxy path uses plain old DNS. @@ -70,7 +87,7 @@ grpc://. { Only Knot DNS' \fB\fCkdig\fR supports DNS-over-TLS queries, no command line client supports gRPC making debugging these transports harder than it should be. -.SH ALSO SEE +.SH "ALSO SEE" .PP RFC 7858 and https://grpc.io \[la]https://grpc.io\[ra]. diff --git a/man/coredns-trace.7 b/man/coredns-trace.7 index 78f66d377..265b43069 100644 --- a/man/coredns-trace.7 +++ b/man/coredns-trace.7 @@ -1,15 +1,15 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-TRACE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-TRACE" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fItrace\fP - enables OpenTracing-based tracing of DNS requests as they go through the plugin chain. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP With \fItrace\fP you enable OpenTracing of how a request flows through CoreDNS. -.SH SYNTAX +.SH "SYNTAX" .PP The simplest form is just: @@ -59,7 +59,7 @@ Default is \fB\fCcoredns\fR. \fB\fCclient_server\fR will enable the \fB\fCClientServerSameSpan\fR OpenTracing feature. -.SH ZIPKIN +.SH "ZIPKIN" .PP You can run Zipkin on a Docker host like this: @@ -72,7 +72,7 @@ docker run \-d \-p 9411:9411 openzipkin/zipkin .fi .RE -.SH EXAMPLES +.SH "EXAMPLES" .PP Use an alternative Zipkin address: diff --git a/man/coredns-whoami.7 b/man/coredns-whoami.7 index d952ddba9..692700573 100644 --- a/man/coredns-whoami.7 +++ b/man/coredns-whoami.7 @@ -1,11 +1,11 @@ .\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-WHOAMI" "7" "April 2019" "CoreDNS" "CoreDNS Plugins" +.TH "COREDNS-WHOAMI" 7 "June 2019" "CoreDNS" "CoreDNS Plugins" -.SH NAME +.SH "NAME" .PP \fIwhoami\fP - returns your resolver's local IP address, port and transport. -.SH DESCRIPTION +.SH "DESCRIPTION" .PP The \fIwhoami\fP plugin is not really that useful, but can be used for having a simple (fast) endpoint to test clients against. When \fIwhoami\fP returns a response it will have your client's IP address in @@ -32,7 +32,7 @@ If CoreDNS can't find a Corefile on startup this is the \fIdefault\fP plugin tha it can be used to check that CoreDNS is responding to queries. Other than that this plugin is of limited use in production. -.SH SYNTAX +.SH "SYNTAX" .PP .RS @@ -42,7 +42,7 @@ whoami .fi .RE -.SH EXAMPLES +.SH "EXAMPLES" .PP Start a server on the default port and load the \fIwhoami\fP plugin. @@ -74,7 +74,7 @@ example.org. 0 IN A 10.240.0.1 .fi .RE -.SH SEE ALSO +.SH "SEE ALSO" .PP Read the blog post \[la]https://coredns.io/2017/03/01/how-to-add-plugins-to-coredns/\[ra] on how this plugin is built, or explore the source code |