Skip to content

C
Coredns
Commit 58221f55 authored by Miek Gieben's avatar Miek Gieben Committed by GitHub
Browse files
Options

Manual pages (#1346) 

* Add manual pages

Generate manual pages from the README and extend README with Name and
Description sections.

The generation requires 'ronn' which may not be available. Just check in
all generated manual pages.
parent 0600f8c0
Hide whitespace changes
Inline Side-by-side
Showing with 3398 additions and 98 deletions
Makefile.doc 0 → 100644
View file @ 58221f55
ORG:=organization=CoreDNS
RONN:=ronn -r
PLUGINS:=$(wildcard plugin/*/README.md)
READMES:=$(subst plugin/,,$(PLUGINS))
READMES:=$(subst /README.md,,$(READMES))
PLUGINS:=$(subst plugin/,corendns-,$(PLUGINS))
PLUGINS:=$(subst /README.md,(7),$(PLUGINS))
all: man/coredns.1 plugins
man/coredns.1: coredns.1.md
sed -e 's/^\(#.*\)/\U\1/' $< > $@.md
sed -i -e "s/@@PLUGINS@@/$(PLUGINS)/" $@.md
$(RONN) --$(ORG) --manual='CoreDNS' $@.md
rm $@.md
.PHONY: plugins
plugins:
for README in $(READMES); do \
$(MAKE) -f Makefile.doc man/coredns-$$README.7; \
done
man/coredns-%.7: plugin/%/README.md
sed -e 's/^\(#.*\)/\U\1/' $< > $@.md
$(RONN) --$(ORG) --manual='CoreDNS plugins' $@.md
rm $@.md
PHONY: clean
clean:
rm -f man/*
coredns.1.md 0 → 100644
View file @ 58221f55
## Name
*coredns* - plugable DNS nameserver optimized for service discovery.
## Synopsis
*coredns* *[OPTION]*...
## Description
CoreDNS is a DNS server that chains plugins. Each plugin handles a DNS feature, like rewriting
queries, kubernetes service discovery or just exporting metrics. There are many other plugins,
each described on <https://coredns.io/plugins> and there respective manual pages.
When started with no options CoreDNS will looks for a file names `Corefile` in the current
directory, if found it will parse its contents and start up accordingly. If no `Corefile` is found
it will start with the *whoami* plugin (coredns-whoami(7)) and start listening on port 53 (unless
overriden with `-dns.port`).
Available options:
**-conf** **FILE**
: specificy Corefile to load.
**-cpu** **CAP**
: specify maximum CPU capacity in percent.
**-dns.port** **PORT**
: override default port to listen on.
**-pidfile** **FILE**
: write PID to **FILE**.
**-plugins**
: list all plugins and quit.
**-quiet**
: don't print any version and port information on startup.
**-version**
: show version and quit.
## Authors
CoreDNS Authors.
## Copyright
Apache License 2.0
## See Also
Corefile(7) @@PLUGINS@@.
man/coredns-auto.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-AUTO" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIauto\fR \- enables serving zone data from an RFC 1035\-style master file which is automatically picked up from disk\.
.
.SH "DESCRIPTION"
The \fIauto\fR 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\. DNSSEC) correct DNSSEC answers are returned\. Only NSEC is supported! If you use this setup \fIyou\fR are responsible for resigning the zonefile\. New zones or changed zone are automatically picked up from disk\.
.
.SH "SYNTAX"
.
.nf
auto [ZONES\.\.\.] {
directory DIR [REGEXP ORIGIN_TEMPLATE [TIMEOUT]]
no_reload
upstream ADDRESS\.\.\.
}
.
.fi
.
.P
\fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block are used\.
.
.IP "\(bu" 4
\fBdirectory\fR loads zones from the speficied \fBDIR\fR\. If a file name matches \fBREGEXP\fR it will be used to extract the origin\. \fBORIGIN_TEMPLATE\fR will be used as a template for the origin\. Strings like \fB{<number>}\fR are replaced with the respective matches in the file name, i\.e\. \fB{1}\fR is the first match, \fB{2}\fR is the second, etc\.\. The default is: \fBdb\e\.(\.*) {1}\fR e\.g\. from a file with the name \fBdb\.example\.com\fR, the extracted origin will be \fBexample\.com\fR\. \fBTIMEOUT\fR specifies how often CoreDNS should scan the directory, the default is every 60 seconds\. This value is in seconds\. The minimum value is 1 second\.
.
.IP "\(bu" 4
\fBno_reload\fR by default CoreDNS will try to reload a zone every minute and reloads if the SOA\'s serial has changed\. This option disables that behavior\.
.
.IP "\(bu" 4
\fBupstream\fR defines upstream resolvers to be used resolve external names found (think CNAMEs) pointing to external names\. \fBADDRESS\fR can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\.
.
.IP "" 0
.
.P
All directives from the \fIfile\fR plugin are supported\. Note that \fIauto\fR will load all zones found, even though the directive might only receive queries for a specific zone\. I\.e:
.
.IP "" 4
.
.nf
\&\. {
auto example\.org {
directory /etc/coredns/zones
}
}
.
.fi
.
.IP "" 0
.
.P
Will happily pick up a zone for \fBexample\.COM\fR, except it will never be queried, because the \fIauto\fR directive only is authoritative for \fBexample\.ORG\fR\.
.
.SH "EXAMPLES"
Load \fBorg\fR domains from \fB/etc/coredns/zones/org\fR and allow transfers to the internet, but send notifies to 10\.240\.1\.1
.
.IP "" 4
.
.nf
\&\. {
auto org {
directory /etc/coredns/zones/org
transfer to *
transfer to 10\.240\.1\.1
}
}
.
.fi
.
.IP "" 0
.
.P
Load \fBorg\fR domains from \fB/etc/coredns/zones/org\fR and looks for file names as \fBwww\.db\.example\.org\fR, where \fBexample\.org\fR is the origin\. Scan every 45 seconds\.
.
.IP "" 4
.
.nf
org {
auto {
directory /etc/coredns/zones/org www\e\.db\e\.(\.*) {1} 45
}
}
.
.fi
.
.IP "" 0
man/coredns-autopath.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-AUTOPATH" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIautopath\fR \- allows for server side search path completion\.
.
.SH "DESCRIPTION"
If it sees a query that matches the first element of the configured search path, \fIautopath\fR will follow the chain of search path elements and returns the first reply that is not NXDOMAIN\. On any failures the original reply is returned\. Because \fIautopath\fR returns a reply for a name that wasn\'t 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"
.
.nf
autopath [ZONE\.\.\.] RESOLV\-CONF
.
.fi
.
.IP "\(bu" 4
\fBZONES\fR zones \fIautopath\fR should be authoritative for\.
.
.IP "\(bu" 4
\fBRESOLV\-CONF\fR points to a \fBresolv\.conf\fR like file or uses a special syntax to point to another plugin\. For instance \fB@kubernetes\fR, will call out to the kubernetes plugin (for each query) to retrieve the search list it should use\.
.
.IP "" 0
.
.P
If a plugin implements the \fBAutoPather\fR interface then it can be used\.
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metric is exported:
.
.IP "\(bu" 4
\fBcoredns_autopath_success_count_total{}\fR \- counter of successfully autopath\-ed queries\.
.
.IP "" 0
.
.SH "EXAMPLES"
.
.nf
autopath my\-resolv\.conf
.
.fi
.
.P
Use \fBmy\-resolv\.conf\fR as the file to get the search path from\. This file only needs so have one line: \fBsearch domain1 domain2 \.\.\.\fR
.
.IP "" 4
.
.nf
autopath @kubernetes
.
.fi
.
.IP "" 0
.
.P
Use the search path dynamically retrieved from the kubernetes plugin\.
man/coredns-bind.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-BIND" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIbind\fR \- overrides the host to which the server should bind\.
.
.SH "DESCRIPTION"
Normally, the listener binds to the wildcard host\. However, you may force the listener to bind to another IP instead\. This directive accepts only an address, not a port\.
.
.SH "SYNTAX"
.
.nf
bind ADDRESS
.
.fi
.
.P
\fBADDRESS\fR is the IP address to bind to\.
.
.SH "EXAMPLES"
To make your socket accessible only to that machine, bind to IP 127\.0\.0\.1 (localhost):
.
.IP "" 4
.
.nf
\&\. {
bind 127\.0\.0\.1
}
.
.fi
.
.IP "" 0
man/coredns-cache.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-CACHE" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIcache\fR \- enables a frontend cache\.
.
.SH "DESCRIPTION"
With \fIcache\fR 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, database, etc\.) is expensive\.
.
.SH "SYNTAX"
.
.nf
cache [TTL] [ZONES\.\.\.]
.
.fi
.
.IP "\(bu" 4
\fBTTL\fR max TTL in seconds\. If not specified, the maximum TTL will be used which is 3600 for noerror responses and 1800 for denial of existence ones\. Setting a TTL of 300: \fBcache 300\fR would cache the record up to 300 seconds\.
.
.IP "\(bu" 4
\fBZONES\fR zones it should cache for\. If empty, the zones from the configuration block are used\.
.
.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\.
.
.P
If you want more control:
.
.IP "" 4
.
.nf
cache [TTL] [ZONES\.\.\.] {
success CAPACITY [TTL]
denial CAPACITY [TTL]
prefetch AMOUNT [[DURATION] [PERCENTAGE%]]
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBTTL\fR and \fBZONES\fR as above\.
.
.IP "\(bu" 4
\fBsuccess\fR, override the settings for caching successful responses, \fBCAPACITY\fR indicates the maximum number of packets we cache before we start evicting (\fIrandomly\fR)\. \fBTTL\fR overrides the cache maximum TTL\.
.
.IP "\(bu" 4
\fBdenial\fR, override the settings for caching denial of existence responses, \fBCAPACITY\fR indicates the maximum number of packets we cache before we start evicting (LRU)\. \fBTTL\fR overrides the cache maximum TTL\. There is a third category (\fBerror\fR) but those responses are never cached\.
.
.IP "\(bu" 4
\fBprefetch\fR, will prefetch popular items when they are about to be expunged from the cache\. Popular means \fBAMOUNT\fR queries have been seen no gaps of \fBDURATION\fR or more between them\. \fBDURATION\fR defaults to 1m\. Prefetching will happen when the TTL drops below \fBPERCENTAGE\fR, which defaults to \fB10%\fR\. Values should be in the range \fB[10%, 90%]\fR\. Note the percent sign is mandatory\. \fBPERCENTAGE\fR is treated as an \fBint\fR\.
.
.IP "" 0
.
.P
The minimum TTL allowed on resource records is 5 seconds\.
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
.
.IP "\(bu" 4
\fBcoredns_cache_size{type}\fR \- Total elements in the cache by cache type\.
.
.IP "\(bu" 4
\fBcoredns_cache_capacity{type}\fR \- Total capacity of the cache by cache type\.
.
.IP "\(bu" 4
\fBcoredns_cache_hits_total{type}\fR \- Counter of cache hits by cache type\.
.
.IP "\(bu" 4
\fBcoredns_cache_misses_total{}\fR \- Counter of cache misses\.
.
.IP "" 0
.
.P
Cache types are either "denial" or "success"\.
.
.SH "EXAMPLES"
Enable caching for all zones, but cap everything to a TTL of 10 seconds:
.
.IP "" 4
.
.nf
\&\. {
cache 10
whoami
}
.
.fi
.
.IP "" 0
.
.P
Proxy to Google Public DNS and only cache responses for example\.org (or below)\.
.
.IP "" 4
.
.nf
\&\. {
proxy \. 8\.8\.8\.8:53
cache example\.org
}
.
.fi
.
.IP "" 0
man/coredns-chaos.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-CHAOS" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIchaos\fR \- allows for responding to TXT queries in the CH class\.
.
.SH "DESCRIPTION"
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"
.
.nf
chaos [VERSION] [AUTHORS\.\.\.]
.
.fi
.
.IP "\(bu" 4
\fBVERSION\fR is the version to return\. Defaults to \fBCoreDNS\-<version>\fR, if not set\.
.
.IP "\(bu" 4
\fBAUTHORS\fR is what authors to return\. No default\.
.
.IP "" 0
.
.P
Note that you have to make sure that this plugin will get actual queries for the following zones: \fBversion\.bind\fR, \fBversion\.server\fR, \fBauthors\.bind\fR, \fBhostname\.bind\fR and \fBid\.server\fR\.
.
.SH "EXAMPLES"
Specify all the zones in full\.
.
.IP "" 4
.
.nf
version\.bind version\.server authors\.bind hostname\.bind id\.server {
chaos CoreDNS\-001 info@coredns\.io
}
.
.fi
.
.IP "" 0
.
.P
Or just default to \fB\.\fR:
.
.IP "" 4
.
.nf
\&\. {
chaos CoreDNS\-001 info@coredns\.io
}
.
.fi
.
.IP "" 0
.
.P
And test with \fBdig\fR:
.
.IP "" 4
.
.nf
% dig @localhost CH TXT version\.bind
\.\.\.
;; ANSWER SECTION:
version\.bind\. 0 CH TXT "CoreDNS\-001"
\.\.\.
.
.fi
.
.IP "" 0
man/coredns-debug.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-DEBUG" "7" "January 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\.
.
.P
Note that the \fIerrors\fR plugin (if loaded) will also set a \fBrecover\fR negating this setting\.
.
.SH "SYNTAX"
.
.nf
debug
.
.fi
.
.SH "EXAMPLES"
Disable the ability to recover from crashes:
.
.IP "" 4
.
.nf
\&\. {
debug
}
.
.fi
.
.IP "" 0
man/coredns-dnssec.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-DNSSEC" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIdnssec\fR \- enable on\-the\-fly DNSSEC signing of served data\.
.
.SH "DESCRIPTION"
With \fIdnssec\fR 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 this leads to smaller signatures (compared to RSA)\. NSEC3 is \fInot\fR supported\.
.
.SH "SYNTAX"
.
.nf
dnssec [ZONES\.\.\. ] {
key file KEY\.\.\.
cache_capacity CAPACITY
}
.
.fi
.
.P
The specified key is used for all signing operations\. The DNSSEC signing will treat this key a CSK (common signing key), forgoing the ZSK/KSK split\. All signing operations are done online\. Authenticated denial of existence is implemented with NSEC black lies\. Using ECDSA as an algorithm is preferred as this leads to smaller signatures (compared to RSA)\. NSEC3 is \fInot\fR supported\.
.
.P
If multiple \fIdnssec\fR plugins are specified in the same zone, the last one specified will be used (See \fIbugs\fR)\.
.
.IP "\(bu" 4
\fBZONES\fR zones that should be signed\. If empty, the zones from the configuration block are used\.
.
.IP "\(bu" 4
\fBkey file\fR indicates that \fBKEY\fR file(s) should be read from disk\. When multiple keys are specified, RRsets will be signed with all keys\. Generating a key can be done with \fBdnssec\-keygen\fR: \fBdnssec\-keygen \-a ECDSAP256SHA256 <zonename>\fR\. A key created for zone \fIA\fR can be safely used for zone \fIB\fR\. The name of the key file can be specified as one of the following formats
.
.IP "\(bu" 4
basename of the generated key \fBKexample\.org+013+45330\fR
.
.IP "\(bu" 4
generated public key \fBKexample\.org+013+45330\.key\fR
.
.IP "\(bu" 4
generated private key \fBKexample\.org+013+45330\.private\fR
.
.IP "" 0
.
.IP "\(bu" 4
\fBcache_capacity\fR indicates the capacity of the cache\. The dnssec plugin uses a cache to store RRSIGs\. The default for \fBCAPACITY\fR is 10000\.
.
.IP "" 0
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported:
.
.IP "\(bu" 4
\fBcoredns_dnssec_cache_size{type}\fR \- total elements in the cache, type is "signature"\.
.
.IP "\(bu" 4
\fBcoredns_dnssec_cache_capacity{type}\fR \- total capacity of the cache, type is "signature"\.
.
.IP "\(bu" 4
\fBcoredns_dnssec_cache_hits_total{}\fR \- Counter of cache hits\.
.
.IP "\(bu" 4
\fBcoredns_dnssec_cache_misses_total{}\fR \- Counter of cache misses\.
.
.IP "" 0
.
.SH "EXAMPLES"
Sign responses for \fBexample\.org\fR with the key "Kexample\.org\.+013+45330\.key"\.
.
.IP "" 4
.
.nf
example\.org {
dnssec {
key file Kexample\.org\.+013+45330
}
whoami
}
.
.fi
.
.IP "" 0
.
.P
Sign responses for a kubernetes zone with the key "Kcluster\.local+013+45129\.key"\.
.
.IP "" 4
.
.nf
cluster\.local {
kubernetes
dnssec {
key file Kcluster\.local+013+45129
}
}
.
.fi
.
.IP "" 0
.
.SH "BUGS"
Multiple \fIdnssec\fR plugins inside one server stanza will silently overwrite earlier ones, here \fBexample\.org\fR will overwrite the one for \fBcluster\.local\fR\.
.
.IP "" 4
.
.nf
\&\. {
kubernetes cluster\.local
dnssec cluster\.local {
key file Kcluster\.local+013+45129
}
dnssec example\.org {
key file Kexample\.org\.+013+45330
}
}
.
.fi
.
.IP "" 0
man/coredns-dnstap.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-DNSTAP" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIdnstap\fR \- enable logging to dnstap
.
.SH "DESCRIPTION"
dnstap is a flexible, structured binary log format for DNS software: http://dnstap\.info\. With this plugin you make CoreDNS output dnstap logging\.
.
.P
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"
.
.nf
dnstap SOCKET [full]
.
.fi
.
.IP "\(bu" 4
\fBSOCKET\fR is the socket path supplied to the dnstap command line tool\.
.
.IP "\(bu" 4
\fBfull\fR to include the wire\-format DNS message\.
.
.IP "" 0
.
.SH "EXAMPLES"
Log information about client requests and responses to \fI/tmp/dnstap\.sock\fR\.
.
.IP "" 4
.
.nf
dnstap /tmp/dnstap\.sock
.
.fi
.
.IP "" 0
.
.P
Log information including the wire\-format DNS message about client requests and responses to \fI/tmp/dnstap\.sock\fR\.
.
.IP "" 4
.
.nf
dnstap unix:///tmp/dnstap\.sock full
.
.fi
.
.IP "" 0
.
.P
Log to a remote endpoint\.
.
.IP "" 4
.
.nf
dnstap tcp://127\.0\.0\.1:6000 full
.
.fi
.
.IP "" 0
.
.SH "COMMAND LINE TOOL"
Dnstap has a command line tool that can be used to inspect the logging\. The tool can be found at Github: \fIhttps://github\.com/dnstap/golang\-dnstap\fR\. It\'s written in Go\.
.
.P
The following command listens on the given socket and decodes messages to stdout\.
.
.IP "" 4
.
.nf
% dnstap \-u /tmp/dnstap\.sock
.
.fi
.
.IP "" 0
.
.P
The following command listens on the given socket and saves message payloads to a binary dnstap\-format log file\.
.
.IP "" 4
.
.nf
% dnstap \-u /tmp/dnstap\.sock \-w /tmp/test\.dnstap
.
.fi
.
.IP "" 0
.
.P
Listen for dnstap messages on port 6000\.
.
.IP "" 4
.
.nf
% dnstap \-l 127\.0\.0\.1:6000
.
.fi
.
.IP "" 0
dnstap\.info \fIhttp://dnstap\.info\fR\.
man/coredns-erratic.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ERRATIC" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIerratic\fR \- a plugin useful for testing client behavior\.
.
.SH "DESCRIPTION"
\fIerratic\fR returns a static response to all queries, but the responses can be delayed, dropped or truncated\. The \fIerratic\fR plugin will respond to every A or AAAA query\. For any other type it will return a SERVFAIL response\. The reply for A will return 192\.0\.2\.53 (see RFC 5737), for AAAA it returns 2001:DB8::53 (see RFC 3849)\.
.
.P
\fIerratic\fR can also be used in conjunction with the \fIautopath\fR plugin\. This is mostly to aid in testing\.
.
.SH "SYNTAX"
.
.nf
erratic {
drop [AMOUNT]
truncate [AMOUNT]
delay [AMOUNT [DURATION]]
}
.
.fi
.
.IP "\(bu" 4
\fBdrop\fR: drop 1 per \fBAMOUNT\fR of queries, the default is 2\.
.
.IP "\(bu" 4
\fBtruncate\fR: truncate 1 per \fBAMOUNT\fR of queries, the default is 2\.
.
.IP "\(bu" 4
\fBdelay\fR: delay 1 per \fBAMOUNT\fR of queries for \fBDURATION\fR, the default for \fBAMOUNT\fR is 2 and the default for \fBDURATION\fR is 100ms\.
.
.IP "" 0
.
.SH "HEALTH"
This plugin implements dynamic health checking\. For every dropped query it turns unhealthy\.
.
.SH "EXAMPLES"
.
.nf
\&\. {
erratic {
drop 3
}
}
.
.fi
.
.P
Or even shorter if the defaults suits you\. Note this only drops queries, it does not delay them\.
.
.IP "" 4
.
.nf
\&\. {
erratic
}
.
.fi
.
.IP "" 0
.
.P
Delay 1 in 3 queries for 50ms
.
.IP "" 4
.
.nf
\&\. {
erratic {
delay 3 50ms
}
}
.
.fi
.
.IP "" 0
.
.P
Delay 1 in 3 and truncate 1 in 5\.
.
.IP "" 4
.
.nf
\&\. {
erratic {
delay 3 5ms
truncate 5
}
}
.
.fi
.
.IP "" 0
.
.P
Drop every second query\.
.
.IP "" 4
.
.nf
\&\. {
erratic {
drop 2
truncate 2
}
}
.
.fi
.
.IP "" 0
man/coredns-errors.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ERRORS" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIerrors\fR \- enable error logging\.
.
.SH "DESCRIPTION"
Any errors encountered during the query processing will be printed to standard output\.
.
.SH "SYNTAX"
.
.nf
errors
.
.fi
.
.SH "EXAMPLES"
Use the \fIwhoami\fR to respond to queries and Log errors to standard output\.
.
.IP "" 4
.
.nf
\&\. {
whoami
errors
}
.
.fi
.
.IP "" 0
man/coredns-etcd.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ETCD" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIetcd\fR \- enables reading zone data from an etcd instance\.
.
.SH "DESCRIPTION"
The data in etcd has to be encoded as a message \fIhttps://github\.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service\.go#L26\fR like SkyDNS \fIhttps://github\.com/skynetservices/skydns\fR\. It should also work just like SkyDNS\.
.
.P
The etcd plugin makes extensive use of the proxy plugin to forward and query other servers in the network\.
.
.SH "SYNTAX"
.
.nf
etcd [ZONES\.\.\.]
.
.fi
.
.IP "\(bu" 4
\fBZONES\fR zones etcd should be authoritative for\.
.
.IP "" 0
.
.P
The path will default to \fB/skydns\fR the local etcd proxy (http://localhost:2379)\. If no zones are specified the block\'s zone will be used as the zone\.
.
.P
If you want to \fBround robin\fR A and AAAA responses look at the \fBloadbalance\fR plugin\.
.
.IP "" 4
.
.nf
etcd [ZONES\.\.\.] {
stubzones
fallthrough
path PATH
endpoint ENDPOINT\.\.\.
upstream ADDRESS\.\.\.
tls CERT KEY CACERT
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBstubzones\fR enables the stub zones feature\. The stubzone is \fIonly\fR done in the etcd tree located under the \fIfirst\fR zone specified\.
.
.IP "\(bu" 4
\fBfallthrough\fR If zone matches but no record can be generated, pass request to the next plugin\.
.
.IP "\(bu" 4
\fBPATH\fR the path inside etcd\. Defaults to "/skydns"\.
.
.IP "\(bu" 4
\fBENDPOINT\fR the etcd endpoints\. Defaults to "http://localhost:2397"\.
.
.IP "\(bu" 4
\fBupstream\fR upstream resolvers to be used resolve external names found in etcd (think CNAMEs) pointing to external names\. If you want CoreDNS to act as a proxy for clients, you\'ll need to add the proxy plugin\. \fBADDRESS\fR can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\.
.
.IP "\(bu" 4
\fBtls\fR followed by:
.
.IP "\(bu" 4
no arguments, if the server certificate is signed by a system\-installed CA and no client cert is needed
.
.IP "\(bu" 4
a single argument that is the CA PEM file, if the server cert is not signed by a system CA and no client cert is needed
.
.IP "\(bu" 4
two arguments \- path to cert PEM file, the path to private key PEM file \- if the server certificate is signed by a system\-installed CA and a client certificate is needed
.
.IP "\(bu" 4
three arguments \- path to cert PEM file, path to client private key PEM file, path to CA PEM file \- if the server certificate is not signed by a system\-installed CA and client certificate is needed\.
.
.IP "" 0
.
.IP "" 0
.
.SH "EXAMPLES"
This is the default SkyDNS setup, with everying specified in full:
.
.IP "" 4
.
.nf
\&\. {
etcd skydns\.local {
stubzones
path /skydns
endpoint http://localhost:2379
upstream 8\.8\.8\.8:53 8\.8\.4\.4:53
}
prometheus
cache 160 skydns\.local
loadbalance
proxy \. 8\.8\.8\.8:53 8\.8\.4\.4:53
}
.
.fi
.
.IP "" 0
.
.P
Or a setup where we use \fB/etc/resolv\.conf\fR as the basis for the proxy and the upstream when resolving external pointing CNAMEs\.
.
.IP "" 4
.
.nf
\&\. {
etcd skydns\.local {
path /skydns
upstream /etc/resolv\.conf
}
cache 160 skydns\.local
proxy \. /etc/resolv\.conf
}
.
.fi
.
.IP "" 0
.
.P
Multiple endpoints are supported as well\.
.
.IP "" 4
.
.nf
etcd skydns\.local {
endpoint http://localhost:2379 http://localhost:4001
\.\.\.
.
.fi
.
.IP "" 0
.
.SS "REVERSE ZONES"
Reverse zones are supported\. You need to make CoreDNS aware of the fact that you are also authoritative for the reverse\. For instance if you want to add the reverse for 10\.0\.0\.0/24, you\'ll need to add the zone \fB0\.0\.10\.in\-addr\.arpa\fR to the list of zones\. Showing a snippet of a Corefile:
.
.IP "" 4
.
.nf
etcd skydns\.local 10\.0\.0\.0/24 {
stubzones
\.\.\.
.
.fi
.
.IP "" 0
.
.P
Next you\'ll need to populate the zone with reverse records, here we add a reverse for 10\.0\.0\.127 pointing to reverse\.skydns\.local\.
.
.IP "" 4
.
.nf
% curl \-XPUT http://127\.0\.0\.1:4001/v2/keys/skydns/arpa/in\-addr/10/0/0/127 \e
\-d value=\'{"host":"reverse\.skydns\.local\."}\'
.
.fi
.
.IP "" 0
.
.P
Querying with dig:
.
.IP "" 4
.
.nf
% dig @localhost \-x 10\.0\.0\.127 +short
reverse\.skydns\.local\.
.
.fi
.
.IP "" 0
Only the etcdv2 protocol is supported\.
man/coredns-federation.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-FEDERATION" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIfederation\fR \- enables federated \fIhttps://kubernetes\.io/docs/tasks/federation/federation\-service\-discovery/\fR queries to be resolved via the kubernetes plugin\.
.
.SH "DESCRIPTION"
Enabling \fIfederation\fR without also having \fIkubernetes\fR is a noop\.
.
.SH "SYNTAX"
.
.nf
federation [ZONES\.\.\.] {
NAME DOMAIN
}
.
.fi
.
.IP "\(bu" 4
Each \fBNAME\fR and \fBDOMAIN\fR defines federation membership\. One entry for each\. A duplicate \fBNAME\fR will silently overwrite any previous value\.
.
.IP "" 0
.
.SH "EXAMPLES"
Here we handle all service requests in the \fBprod\fR and \fBstage\fR federations\.
.
.IP "" 4
.
.nf
\&\. {
kubernetes cluster\.local
federation cluster\.local {
prod prod\.feddomain\.com
staging staging\.feddomain\.com
}
}
.
.fi
.
.IP "" 0
.
.P
Or slightly shorter:
.
.IP "" 4
.
.nf
cluster\.local {
kubernetes
federation {
prod prod\.feddomain\.com
staging staging\.feddomain\.com
}
}
.
.fi
.
.IP "" 0
man/coredns-file.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-FILE" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIfile\fR \- enables serving zone data from an RFC 1035\-style master file\.
.
.SH "DESCRIPTION"
The file 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\. DNSSEC) correct DNSSEC answers are returned\. Only NSEC is supported! If you use this setup \fIyou\fR are responsible for resigning the zonefile\.
.
.SH "SYNTAX"
.
.nf
file DBFILE [ZONES\.\.\.]
.
.fi
.
.IP "\(bu" 4
\fBDBFILE\fR the database file to read and parse\. If the path is relative the path from the \fIroot\fR directive will be prepended to it\.
.
.IP "\(bu" 4
\fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block are used\.
.
.IP "" 0
.
.P
If you want to round robin A and AAAA responses look at the \fIloadbalance\fR plugin\.
.
.IP "" 4
.
.nf
file DBFILE [ZONES\.\.\. ] {
transfer to ADDRESS\.\.\.
no_reload
upstream ADDRESS\.\.\.
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBtransfer\fR enables zone transfers\. It may be specified multiples times\. \fBTo\fR or \fBfrom\fR signals the direction\. \fBADDRESS\fR must be denoted in CIDR notation (127\.0\.0\.1/32 etc\.) or just as plain addresses\. The special wildcard \fB*\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\.
.
.IP "\(bu" 4
\fBno_reload\fR by default CoreDNS will try to reload a zone every minute and reloads if the SOA\'s serial has changed\. This option disables that behavior\.
.
.IP "\(bu" 4
\fBupstream\fR defines upstream resolvers to be used resolve external names found (think CNAMEs) pointing to external names\. This is only really useful when CoreDNS is configured as a proxy, for normal authoritative serving you don\'t need \fIor\fR want to use this\. \fBADDRESS\fR can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\.
.
.IP "" 0
.
.SH "EXAMPLES"
Load the \fBexample\.org\fR zone from \fBexample\.org\.signed\fR and allow transfers to the internet, but send notifies to 10\.240\.1\.1
.
.IP "" 4
.
.nf
example\.org {
file example\.org\.signed {
transfer to *
transfer to 10\.240\.1\.1
}
}
.
.fi
.
.IP "" 0
.
.P
Or use a single zone file for multiple zones:
.
.IP "" 4
.
.nf
\&\. {
file example\.org\.signed example\.org example\.net {
transfer to *
transfer to 10\.240\.1\.1
}
}
.
.fi
.
.IP "" 0
man/coredns-health.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-HEALTH" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIhealth\fR \- enables a health check endpoint\.
.
.SH "DESCRIPTION"
By enabling \fIhealth\fR any plugin that implements it will be queried for it\'s health\. The combined health is exported, by default, on port 8080/health \.
.
.SH "SYNTAX"
.
.nf
health [ADDRESS]
.
.fi
.
.P
Optionally takes an address; the default is \fB:8080\fR\. The health path is fixed to \fB/health\fR\. The health endpoint returns a 200 response code and the word "OK" when CoreDNS is healthy\. It returns a 503\. \fIhealth\fR periodically (1s) polls plugin that exports health information\. If any of the plugin signals that it is unhealthy, the server will go unhealthy too\. Each plugin that supports health checks has a section "Health" in their README\.
.
.SH "PLUGINS"
Any plugin that implements the Healther interface will be used to report health\.
.
.SH "EXAMPLES"
Run another health endpoint on http://localhost:8091\.
.
.IP "" 4
.
.nf
\&\. {
health localhost:8091
}
.
.fi
.
.IP "" 0
man/coredns-hosts.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-HOSTS" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIhosts\fR \- enables serving zone data from a \fB/etc/hosts\fR style file\.
.
.SH "DESCRIPTION"
The hosts plugin is useful for serving zones from a /etc/hosts file\. It serves from a preloaded file that exists on disk\. It checks the file for changes and updates the zones accordingly\. This plugin only supports A, AAAA, and PTR records\. The hosts plugin can be used with readily available hosts files that block access to advertising servers\.
.
.SH "SYNTAX"
.
.nf
hosts [FILE [ZONES\.\.\.]] {
[INLINE]
fallthrough
}
.
.fi
.
.IP "\(bu" 4
\fBFILE\fR the hosts file to read and parse\. If the path is relative the path from the \fIroot\fR directive will be prepended to it\. Defaults to /etc/hosts if omitted\. We scan the file for changes every 5 seconds\.
.
.IP "\(bu" 4
\fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block are used\.
.
.IP "\(bu" 4
\fBINLINE\fR the hosts file contents inlined in Corefile\. If there are any lines before fallthrough then all of them will be treated as the additional content for hosts file\. The specified hosts file path will still be read but entries will be overrided\.
.
.IP "\(bu" 4
\fBfallthrough\fR If zone matches and no record can be generated, pass request to the next plugin\.
.
.IP "" 0
.
.SH "EXAMPLES"
Load \fB/etc/hosts\fR file\.
.
.IP "" 4
.
.nf
\&\. {
hosts
}
.
.fi
.
.IP "" 0
.
.P
Load \fBexample\.hosts\fR file in the current directory\.
.
.IP "" 4
.
.nf
hosts example\.hosts
.
.fi
.
.IP "" 0
.
.P
Load example\.hosts file and only serve example\.org and example\.net from it and fall through to the next plugin if query doesn\'t match\.
.
.IP "" 4
.
.nf
hosts example\.hosts example\.org example\.net {
fallthrough
}
.
.fi
.
.IP "" 0
.
.P
Load hosts file inlined in Corefile\.
.
.IP "" 4
.
.nf
hosts example\.hosts example\.org {
10\.0\.0\.1 example\.org
fallthrough
}
.
.fi
.
.IP "" 0
man/coredns-kubernetes.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-KUBERNETES" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIkubernetes\fR \- enables the reading zone data from a Kubernetes cluster\.
.
.SH "DESCRIPTION"
It implements the Kubernetes DNS\-Based Service Discovery Specification \fIhttps://github\.com/kubernetes/dns/blob/master/docs/specification\.md\fR\.
.
.P
CoreDNS running the kubernetes plugin can be used as a replacement of kube\-dns in a kubernetes cluster\. See the deployment \fIhttps://github\.com/coredns/deployment\fR repository for details on how to deploy CoreDNS in Kubernetes \fIhttps://github\.com/coredns/deployment/tree/master/kubernetes\fR\.
.
.P
stubDomains \fIhttp://blog\.kubernetes\.io/2017/04/configuring\-private\-dns\-zones\-upstream\-nameservers\-kubernetes\.html\fR are implemented via the \fIproxy\fR plugin\.
.
.SH "SYNTAX"
.
.nf
kubernetes [ZONES\.\.\.]
.
.fi
.
.P
With only the directive specified, the \fIkubernetes\fR plugin will default to the zone specified in the server\'s block\. It will handle all queries in that zone and connect to Kubernetes in\-cluster\. It will not provide PTR records for services, or A records for pods\. If \fBZONES\fR is used it specifies all the zones the plugin should be authoritative for\.
.
.IP "" 4
.
.nf
kubernetes [ZONES\.\.\.] {
resyncperiod DURATION
endpoint URL
tls CERT KEY CACERT
namespaces NAMESPACE\.\.\.
labels EXPRESSION
pods POD\-MODE
endpoint_pod_names
upstream ADDRESS\.\.\.
ttl TTL
fallthrough
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBresyncperiod\fR specifies the Kubernetes data API \fBDURATION\fR period\.
.
.IP "\(bu" 4
\fBendpoint\fR specifies the \fBURL\fR for a remote k8s API endpoint\. If omitted, it will connect to k8s in\-cluster using the cluster service account\. Multiple k8s API endpoints could be specified, separated by \fB,\fRs, e\.g\. \fBendpoint http://k8s\-endpoint1:8080,http://k8s\-endpoint2:8080\fR\. CoreDNS will automatically perform a healthcheck and proxy to the healthy k8s API endpoint\.
.
.IP "\(bu" 4
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCACERT\fR are the TLS cert, key and the CA cert file names for remote k8s connection\. This option is ignored if connecting in\-cluster (i\.e\. endpoint is not specified)\.
.
.IP "\(bu" 4
\fBnamespaces\fR \fBNAMESPACE [NAMESPACE\.\.\.]\fR, only exposes the k8s namespaces listed\. If this option is omitted all namespaces are exposed
.
.IP "\(bu" 4
\fBlabels\fR \fBEXPRESSION\fR only exposes the records for Kubernetes objects that match this label selector\. The label selector syntax is described in the Kubernetes User Guide \- Labels \fIhttp://kubernetes\.io/docs/user\-guide/labels/\fR\. An example that only exposes objects labeled as "application=nginx" in the "staging" or "qa" environments, would use: \fBlabels environment in (staging, qa),application=nginx\fR\.
.
.IP "\(bu" 4
\fBpods\fR \fBPOD\-MODE\fR sets the mode for handling IP\-based pod A records, e\.g\. \fB1\-2\-3\-4\.ns\.pod\.cluster\.local\. in A 1\.2\.3\.4\fR\. This option is provided to facilitate use of SSL certs when connecting directly to pods\. Valid values for \fBPOD\-MODE\fR:
.
.IP "\(bu" 4
\fBdisabled\fR: Default\. Do not process pod requests, always returning \fBNXDOMAIN\fR
.
.IP "\(bu" 4
\fBinsecure\fR: Always return an A record with IP from request (without checking k8s)\. This option is is vulnerable to abuse if used maliciously in conjunction with wildcard SSL certs\. This option is provided for backward compatibility with kube\-dns\.
.
.IP "\(bu" 4
\fBverified\fR: Return an A record if there exists a pod in same namespace with matching IP\. This option requires substantially more memory than in insecure mode, since it will maintain a watch on all pods\.
.
.IP "" 0
.
.IP "\(bu" 4
\fBendpoint_pod_names\fR uses the pod name of the pod targeted by the endpoint as the endpoint name in A records, e\.g\. \fBendpoint\-name\.my\-service\.namespace\.svc\.cluster\.local\. in A 1\.2\.3\.4\fR By default, the endpoint\-name name selection is as follows: Use the hostname of the endpoint, or if hostname is not set, use the dashed form of the endpoint IP address (e\.g\. \fB1\-2\-3\-4\.my\-service\.namespace\.svc\.cluster\.local\.\fR) If this directive is included, then name selection for endpoints changes as follows: Use the hostname of the endpoint, or if hostname is not set, use the pod name of the pod targeted by the endpoint\. If there is no pod targeted by the endpoint, use the dashed IP address form\.
.
.IP "\(bu" 4
\fBupstream\fR \fBADDRESS [ADDRESS\.\.\.]\fR defines the upstream resolvers used for resolving services that point to external hosts (External Services)\. \fBADDRESS\fR can be an IP, an IP:port, or a path to a file structured like resolv\.conf\.
.
.IP "\(bu" 4
\fBttl\fR allows you to set a custom TTL for responses\. The default (and allowed minimum) is to use 5 seconds, the maximum is capped at 3600 seconds\.
.
.IP "\(bu" 4
\fBfallthrough\fR If a query for a record in the cluster zone results in NXDOMAIN, normally that is what the response will be\. However, if you specify this option, the query will instead be passed on down the plugin chain, which can include another plugin to handle the query\.
.
.IP "" 0
.
.SH "HEALTH"
This plugin implements dynamic health checking\. Currently this is limited to reporting healthy when the API has synced\.
.
.SH "EXAMPLES"
Handle all queries in the \fBcluster\.local\fR zone\. Connect to Kubernetes in\-cluster\. Also handle all \fBin\-addr\.arpa\fR \fBPTR\fR requests for \fB10\.0\.0\.0/17\fR \. Verify the existence of pods when answering pod requests\. Resolve upstream records against \fB10\.102\.3\.10\fR\. Note we show the entire server block here:
.
.IP "" 4
.
.nf
10\.0\.0\.0/17 cluster\.local {
kubernetes {
pods verified
upstream 10\.102\.3\.10:53
}
}
.
.fi
.
.IP "" 0
.
.P
Or you can selectively expose some namespaces:
.
.IP "" 4
.
.nf
kubernetes cluster\.local {
namespaces test staging
}
.
.fi
.
.IP "" 0
.
.P
Connect to Kubernetes with CoreDNS running outside the cluster:
.
.IP "" 4
.
.nf
kubernetes cluster\.local {
endpoint https://k8s\-endpoint:8443
tls cert key cacert
}
.
.fi
.
.IP "" 0
.
.P
Here we use the \fIproxy\fR plugin to implement stubDomains that forwards \fBexample\.org\fR and \fBexample\.com\fR to another nameserver\.
.
.IP "" 4
.
.nf
cluster\.local {
kubernetes {
endpoint https://k8s\-endpoint:8443
tls cert key cacert
}
}
example\.org {
proxy \. 8\.8\.8\.8:53
}
example\.com {
proxy \. 8\.8\.8\.8:53
}
.
.fi
.
.IP "" 0
.
.SH "AUTOPATH"
The \fIkubernetes\fR plugin can be used in conjunction with the \fIautopath\fR plugin\. Using this feature enables server\-side domain search path completion in kubernetes clusters\. Note: \fBpods\fR must be set to \fBverified\fR for this to function properly\.
.
.IP "" 4
.
.nf
cluster\.local {
autopath @kubernetes
kubernetes {
pods verified
}
}
.
.fi
.
.IP "" 0
.
.SH "FEDERATION"
The \fIkubernetes\fR plugin can be used in conjunction with the \fIfederation\fR plugin\. Using this feature enables serving federated domains from the kubernetes clusters\.
.
.IP "" 4
.
.nf
cluster\.local {
federation {
fallthrough
prod prod\.example\.org
staging staging\.example\.org
}
kubernetes
}
.
.fi
.
.IP "" 0
.
.SH "WILDCARDS"
Some query labels accept a wildcard value to match any value\. If a label is a valid wildcard (*, or the word "any"), then that label will match all values\. The labels that accept wildcards are:
.
.IP "\(bu" 4
\fIservice\fR in an \fBA\fR record request: \fIservice\fR\.namespace\.svc\.zone, e\.g\. \fB*\.ns\.svc\.myzone\.local\fR
.
.IP "\(bu" 4
\fInamespace\fR in an \fBA\fR record request: service\.\fInamespace\fR\.svc\.zone, e\.g\. \fBnginx\.*\.svc\.myzone\.local\fR
.
.IP "\(bu" 4
\fIport and/or protocol\fR in an \fBSRV\fR request: \fBport_\.\fRprotocol_\.service\.namespace\.svc\.zone\., e\.g\. \fB_http\.*\.service\.ns\.svc\.\fR
.
.IP "\(bu" 4
multiple wild cards are allowed in a single query, e\.g\. \fBA\fR Request \fB*\.*\.svc\.zone\.\fR or \fBSRV\fR request \fB*\.*\.*\.*\.svc\.zone\.\fR
.
.IP "" 0
man/coredns-loadbalance.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-LOADBALANCE" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIloadbalance\fR \- acts as a round\-robin DNS loadbalancer by randomizing the order of A and AAAA records in the answer\.
.
.SH "DESCRIPTION"
See Wikipedia \fIhttps://en\.wikipedia\.org/wiki/Round\-robin_DNS\fR about the pros and cons on this 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"
.
.nf
loadbalance [POLICY]
.
.fi
.
.IP "\(bu" 4
\fBPOLICY\fR is how to balance, the default is "round_robin"
.
.IP "" 0
.
.SH "EXAMPLES"
Load balance replies coming back from Google Public DNS:
.
.IP "" 4
.
.nf
\&\. {
loadbalance round_robin
proxy \. 8\.8\.8\.8 8\.8\.4\.4
}
.
.fi
.
.IP "" 0
man/coredns-log.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-LOG" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIlog\fR enables query logging to standard output\.
.
.SH "DESCRIPTION"
By just using \fIlog\fR you dump all queries (and parts for the reply) on standard output\. Options exist to tweak the output a little\.
.
.P
Note that for busy servers this will incur a performance hit\.
.
.SH "SYNTAX"
.
.nf
log
.
.fi
.
.IP "\(bu" 4
With no arguments, a query log entry is written to \fIstdout\fR in the common log format for all requests
.
.IP "" 0
.
.P
Or if you want/need slightly more control:
.
.IP "" 4
.
.nf
log [NAME] [FORMAT]
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBNAME\fR is the name to match in order to be logged
.
.IP "\(bu" 4
\fBFORMAT\fR is the log format to use (default is Common Log Format)
.
.IP "" 0
.
.P
You can further specify the class of responses that get logged:
.
.IP "" 4
.
.nf
log [NAME] [FORMAT] {
class [success|denial|error|all]
}
.
.fi
.
.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:
.
.IP "\(bu" 4
\fBsuccess\fR: successful response
.
.IP "\(bu" 4
\fBdenial\fR: either NXDOMAIN or NODATA (name exists, type does not)
.
.IP "\(bu" 4
\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\.
.
.IP "" 0
.
.P
If no class is specified, it defaults to \fIall\fR\.
.
.SH "LOG FORMAT"
You can specify a custom log format with any placeholder values\. Log supports both request and response placeholders\.
.
.P
The following place holders are supported:
.
.IP "\(bu" 4
\fB{type}\fR: qtype of the request
.
.IP "\(bu" 4
\fB{name}\fR: qname of the request
.
.IP "\(bu" 4
\fB{class}\fR: qclass of the request
.
.IP "\(bu" 4
\fB{proto}\fR: protocol used (tcp or udp)
.
.IP "\(bu" 4
\fB{when}\fR: time of the query
.
.IP "\(bu" 4
\fB{remote}\fR: client\'s IP address
.
.IP "\(bu" 4
\fB{size}\fR: request size in bytes
.
.IP "\(bu" 4
\fB{port}\fR: client\'s port
.
.IP "\(bu" 4
\fB{duration}\fR: response duration
.
.IP "\(bu" 4
\fB{rcode}\fR: response RCODE
.
.IP "\(bu" 4
\fB{rsize}\fR: response size
.
.IP "\(bu" 4
\fB{>rflags}\fR: response flags, each set flag will be displayed, e\.g\. "aa, tc"\. This includes the qr bit as well\.
.
.IP "\(bu" 4
\fB{>bufsize}\fR: the EDNS0 buffer size advertised in the query
.
.IP "\(bu" 4
\fB{>do}\fR: is the EDNS0 DO (DNSSEC OK) bit set in the query
.
.IP "\(bu" 4
\fB{>id}\fR: query ID
.
.IP "\(bu" 4
\fB{>opcode}\fR: query OPCODE
.
.IP "" 0
.
.P
The default Common Log Format is:
.
.IP "" 4
.
.nf
`{remote} \- [{when}] "{type} {class} {name} {proto} {size} {>do} {>bufsize}" {rcode} {>rflags} {rsize} {duration}`
.
.fi
.
.IP "" 0
.
.SH "EXAMPLES"
Log all requests to stdout
.
.IP "" 4
.
.nf
\&\. {
log
whoami
}
.
.fi
.
.IP "" 0
.
.P
Custom log format, for all zones (\fB\.\fR)
.
.IP "" 4
.
.nf
\&\. {
log \. "{proto} Request: {name} {type} {>id}"
}
.
.fi
.
.IP "" 0
.
.P
Only log denials for example\.org (and below to a file)
.
.IP "" 4
.
.nf
\&\. {
log example\.org {
class denial
}
}
.
.fi
.
.IP "" 0
man/coredns-metrics.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-METRICS" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIprometheus\fR \- enables Prometheus \fIhttps://prometheus\.io/\fR metrics\.
.
.SH "DESCRIPTION"
With \fIprometheus\fR you export metrics from CoreDNS and any plugin that has them\. The default location for the metrics is \fBlocalhost:9153\fR\. The metrics path is fixed to \fB/metrics\fR\. The following metrics are exported:
.
.IP "\(bu" 4
\fBcoredns_dns_request_count_total{zone, proto, family}\fR \- total query count\.
.
.IP "\(bu" 4
\fBcoredns_dns_request_duration_seconds{zone}\fR \- duration to process each query\.
.
.IP "\(bu" 4
\fBcoredns_dns_request_size_bytes{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
.
.IP "\(bu" 4
\fBcoredns_dns_request_type_count_total{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\.
.
.IP "\(bu" 4
\fBcoredns_dns_response_rcode_count_total{zone, rcode}\fR \- response per zone and rcode\.
.
.IP "" 0
.
.P
Each counter has a label \fBzone\fR which is the zonename used for the request/response\.
.
.P
Extra labels used are:
.
.IP "\(bu" 4
\fBproto\fR which holds the transport of the response ("udp" or "tcp")
.
.IP "\(bu" 4
The address family (\fBfamily\fR) of the transport (1 = IP (IP version 4), 2 = IP6 (IP version 6))\.
.
.IP "\(bu" 4
\fBtype\fR which holds the query type\. It holds most common types (A, AAAA, MX, SOA, CNAME, PTR, TXT, NS, SRV, DS, DNSKEY, RRSIG, NSEC, NSEC3, IXFR, AXFR and ANY) and "other" which lumps together all other types\.
.
.IP "\(bu" 4
The \fBresponse_rcode_count_total\fR has an extra label \fBrcode\fR which holds the rcode of the response\.
.
.IP "" 0
.
.P
If monitoring is enabled, queries that do not enter the plugin chain are exported under the fake name "dropped" (without a closing dot \- this is never a valid domain name)\.
.
.SH "SYNTAX"
.
.nf
prometheus [ADDRESS]
.
.fi
.
.P
For each zone that you want to see metrics for\.
.
.P
It optionally takes an address to which the metrics are exported; the default is \fBlocalhost:9153\fR\. The metrics path is fixed to \fB/metrics\fR\.
.
.SH "EXAMPLES"
Use an alternative address:
.
.IP "" 4
.
.nf
\&\. {
prometheus localhost:9253
}
.
.fi
.
.IP "" 0
.
.P
Or via an enviroment variable (this is supported throughout the Corefile): \fBexport PORT=9253\fR, and then:
.
.IP "" 4
.
.nf
\&\. {
prometheus localhost:{$PORT}
}
.
.fi
.
.IP "" 0
When reloading, we keep the handler running, meaning that any changes to the handler\'s address aren\'t picked up\. You\'ll need to restart CoreDNS for that to happen\.
man/coredns-nsid.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-NSID" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fInsid\fR \- adds an identifier of this server to each reply\.
.
.SH "DESCRIPTION"
This plugin implements RFC 5001 and adds an EDNS0 OPT resource record to replies that uniquely identify the server\. This is useful in anycast setups to see which server was responsible for generating the reply and for debugging\.
.
.SH "SYNTAX"
.
.nf
nsid [DATA]
.
.fi
.
.P
\fBDATA\fR is the string to use in the nsid record\.
.
.P
If \fBDATA\fR is not given, the host\'s name is used\.
.
.SH "EXAMPLES"
Enable nsid:
.
.IP "" 4
.
.nf
\&\. {
whoami
nsid Use The Force
}
.
.fi
.
.IP "" 0
.
.P
And now a client with NSID support will see an OPT record with the NSID option:
.
.IP "" 4
.
.nf
% dig +nsid @localhost a whoami\.example\.org
;; Got answer:
;; \->>HEADER<<\- opcode: QUERY, status: NOERROR, id: 46880
;; flags: qr aa rd; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 3
\.\.\.\.
; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
; NSID: 55 73 65 20 54 68 65 20 46 6f 72 63 65 ("Use The Force")
;; QUESTION SECTION:
;whoami\.example\.org\. IN A
.
.fi
.
.IP "" 0
man/coredns-pprof.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-PPROF" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIpprof\fR \- publishes runtime profiling data at endpoints under \fB/debug/pprof\fR\.
.
.SH "DESCRIPTION"
You can visit \fB/debug/pprof\fR on your site for an index of the available endpoints\. By default it will listen on localhost:6053\.
.
.P
For more information, please see Go\'s pprof documentation \fIhttps://golang\.org/pkg/net/http/pprof/\fR and read Profiling Go Programs \fIhttps://blog\.golang\.org/profiling\-go\-programs\fR\.
.
.SH "SYNTAX"
.
.nf
pprof [ADDRESS]
.
.fi
.
.P
If not specified, ADDRESS defaults to localhost:6053\.
.
.SH "EXAMPLES"
Enable pprof endpoints:
.
.IP "" 4
.
.nf
\&\. {
pprof
}
.
.fi
.
.IP "" 0
.
.P
Listen on an alternate address:
.
.IP "" 4
.
.nf
\&\. {
pprof 10\.9\.8\.7:6060
}
.
.fi
.
.IP "" 0
.
.P
Listen on an all addresses on port 6060:
.
.IP "" 4
.
.nf
\&\. {
pprof :6060
}
.
.fi
.
.IP "" 0
See Go\'s pprof documentation \fIhttps://golang\.org/pkg/net/http/pprof/\fR and Profiling Go Programs \fIhttps://blog\.golang\.org/profiling\-go\-programs\fR\.
man/coredns-proxy.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-PROXY" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIproxy\fR \- facilitates both a basic reverse proxy and a robust load balancer\.
.
.SH "DESCRIPTION"
The proxy has support for multiple backends\. The load balancing features include multiple policies, health checks, and failovers\. If all hosts fail their health check the proxy plugin will fail back to randomly selecting a target and sending packets to it\.
.
.SH "SYNTAX"
In its most basic form, a simple reverse proxy uses this syntax:
.
.IP "" 4
.
.nf
proxy FROM TO
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBFROM\fR is the base domain to match for the request to be proxied\.
.
.IP "\(bu" 4
\fBTO\fR is the destination endpoint to proxy to\.
.
.IP "" 0
.
.P
However, advanced features including load balancing can be utilized with an expanded syntax:
.
.IP "" 4
.
.nf
proxy FROM TO\.\.\. {
policy random|least_conn|round_robin
fail_timeout DURATION
max_fails INTEGER
health_check PATH:PORT [DURATION]
except IGNORED_NAMES\.\.\.
spray
protocol [dns [force_tcp]|https_google [bootstrap ADDRESS\.\.\.]|grpc [insecure|CACERT|KEY CERT|KEY CERT CACERT]]
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBFROM\fR is the name to match for the request to be proxied\.
.
.IP "\(bu" 4
\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, or round_robin\. 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")\.
.
.IP "\(bu" 4
\fBmax_fails\fR is the number of failures within fail_timeout that are needed before considering a backend to be down\. If 0, the backend will never be marked as down\. Default is 1\.
.
.IP "\(bu" 4
\fBhealth_check\fR will check \fBPATH\fR (on \fBPORT\fR) on each backend\. If a backend returns a status code of 200\-399, then that backend is marked healthy for double the healthcheck duration\. If it doesn\'t, it is marked as unhealthy and no requests are routed to it\. If this option is not provided then health checks are disabled\. The default duration is 4 seconds ("4s")\.
.
.IP "\(bu" 4
\fBIGNORED_NAMES\fR in \fBexcept\fR is a space\-separated list of domains to exclude from proxying\. Requests that match none of these names will be passed through\.
.
.IP "\(bu" 4
\fBspray\fR when all backends are unhealthy, randomly pick one to send the traffic to\. (This is a failsafe\.)
.
.IP "\(bu" 4
\fBprotocol\fR specifies what protocol to use to speak to an upstream, \fBdns\fR (the default) is plain old DNS, and \fBhttps_google\fR uses \fBhttps://dns\.google\.com\fR and speaks a JSON DNS dialect\. Note when using this \fBTO\fR will be ignored\. The \fBgrpc\fR option will talk to a server that has implemented the DnsService \fIhttps://github\.com/coredns/coredns/pb/dns\.proto\fR\. An out\-of\-tree plugin that implements the server side of this can be found at here \fIhttps://github\.com/infobloxopen/coredns\-grpc\fR\.
.
.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
.
.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\.
.
.SH "UPSTREAM PROTOCOLS"
Currently \fBprotocol\fR supports \fBdns\fR (i\.e\., standard DNS over UDP/TCP) and \fBhttps_google\fR (JSON payload over HTTPS)\. Note that with \fBhttps_google\fR the entire transport is encrypted\. Only \fIyou\fR and \fIGoogle\fR can see your DNS activity\.
.
.TP
\fBdns\fR
uses the standard DNS exchange\. You can pass \fBforce_tcp\fR to make sure that the proxied connection is performed over TCP, regardless of the inbound request\'s protocol\.
.
.TP
\fBgrpc\fR
extra options are used to control how the TLS connection is made to the gRPC server\.
.
.IP "\(bu" 4
None \- No client authentication is used, and the system CAs are used to verify the server certificate\.
.
.IP "\(bu" 4
\fBinsecure\fR \- TLS is not used, the connection is made in plaintext (not good in production)\.
.
.IP "\(bu" 4
\fBCACERT\fR \- No client authentication is used, and the file \fBCACERT\fR is used to verify the server certificate\.
.
.IP "\(bu" 4
\fBKEY\fR \fBCERT\fR \- Client authentication is used with the specified key/cert pair\. The server certificate is verified with the system CAs\.
.
.IP "\(bu" 4
\fBKEY\fR \fBCERT\fR \fBCACERT\fR \- Client authentication is used with the specified key/cert pair\. The server certificate is verified using the \fBCACERT\fR file\. An out\-of\-tree plugin that implements the server side of this can be found at here \fIhttps://github\.com/infobloxopen/coredns\-grpc\fR\.
.
.IP "" 0
.
.TP
\fBhttps_google\fR
bootstrap \fBADDRESS\.\.\.\fR is used to (re\-)resolve \fBdns\.google\.com\fR\.
.
.IP
This happens every 300s\. If not specified the default is used: 8\.8\.8\.8:53/8\.8\.4\.4:53\. Note that \fBTO\fR is \fIignored\fR when \fBhttps_google\fR is used, as its upstream is defined as \fBdns\.google\.com\fR\.
.
.SH "METRICS"
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\.
.
.IP "\(bu" 4
\fBcoredns_proxy_request_count_total{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)\.
.
.SH "EXAMPLES"
Proxy all requests within example\.org\. to a backend system:
.
.IP "" 4
.
.nf
proxy example\.org 127\.0\.0\.1:9005
.
.fi
.
.IP "" 0
.
.P
Load\-balance all requests between three backends (using random policy):
.
.IP "" 4
.
.nf
\&\. {
proxy \. 10\.0\.0\.10:53 10\.0\.0\.11:1053 10\.0\.0\.12
}
.
.fi
.
.IP "" 0
.
.P
Same as above, but round\-robin style:
.
.IP "" 4
.
.nf
\&\. {
proxy \. 10\.0\.0\.10:53 10\.0\.0\.11:1053 10\.0\.0\.12 {
policy round_robin
}
}
.
.fi
.
.IP "" 0
.
.P
With health checks and proxy headers to pass hostname, IP, and scheme upstream:
.
.IP "" 4
.
.nf
\&\. {
proxy \. 10\.0\.0\.11:53 10\.0\.0\.11:53 10\.0\.0\.12:53 {
policy round_robin
health_check /health:8080
}
}
.
.fi
.
.IP "" 0
.
.P
Proxy everything except requests to miek\.nl or example\.org
.
.IP "" 4
.
.nf
\&\. {
proxy \. 10\.0\.0\.10:1234 {
except miek\.nl example\.org
}
}
.
.fi
.
.IP "" 0
.
.P
Proxy everything except \fBexample\.org\fR using the host\'s \fBresolv\.conf\fR\'s nameservers:
.
.IP "" 4
.
.nf
\&\. {
proxy \. /etc/resolv\.conf {
except miek\.nl example\.org
}
}
.
.fi
.
.IP "" 0
.
.P
Proxy all requests within \fBexample\.org\fR to Google\'s \fBdns\.google\.com\fR\.
.
.IP "" 4
.
.nf
\&\. {
proxy example\.org 1\.2\.3\.4:53 {
protocol https_google
}
}
.
.fi
.
.IP "" 0
.
.P
Proxy everything with HTTPS to \fBdns\.google\.com\fR, except \fBexample\.org\fR\. Then have another proxy in another stanza that uses plain DNS to resolve names under \fBexample\.org\fR\.
.
.IP "" 4
.
.nf
\&\. {
proxy \. 1\.2\.3\.4:53 {
except example\.org
protocol https_google
}
}
example\.org {
proxy \. 8\.8\.8\.8:53
}
.
.fi
.
.IP "" 0
When using the \fBgoogle_https\fR protocol the health checking will health check the wrong endpoint\. See \fIhttps://github\.com/coredns/coredns/issues/1202\fR for some background\.
man/coredns-reverse.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-REVERSE" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIreverse\fR \- allows for dynamic responses to PTR and the related A/AAAA requests\.
.
.SH "DESCRIPTION"
If a request matches a regular expression (see Template Syntax below) this plugin will generate a response\. This is only done for "address" records (PTR, A and AAAA)\.
.
.SH "SYNTAX"
.
.nf
reverse NETWORK\.\.\. {
hostname TEMPLATE
[ttl TTL]
[fallthrough]
[wildcard]
.
.fi
.
.IP "\(bu" 4
\fBNETWORK\fR one or more CIDR formatted networks to respond on\.
.
.IP "\(bu" 4
\fBhostname\fR injects the IP and zone to a template for the hostname\. Defaults to "ip\-{IP}\.{zone[1]}"\. See below for template\.
.
.IP "\(bu" 4
\fBttl\fR defaults to 60
.
.IP "\(bu" 4
\fBfallthrough\fR if zone matches and no record can be generated, pass request to the next plugin\.
.
.IP "\(bu" 4
\fBwildcard\fR allows matches to catch all subdomains as well\.
.
.IP "" 0
.
.SS "TEMPLATE SYNTAX"
The template for the hostname is used for generating the PTR for a reverse lookup and matching the forward lookup back to an IP\.
.
.P
The \fB{ip}\fR symbol is \fBrequired\fR to make reverse work\. For IPv4 lookups the IP is directly extracted With IPv6 lookups the ":" is removed, and any zero ranged are expanded, e\.g\., "ffff::ffff" results in "ffff000000000000000000000000ffff"
.
.P
The \fB{zone[i]}\fR symbol is \fBoptional\fR and can be replaced by a fixed (zone) string\. The zone will be matched by the zones listed in \fIthis\fR configuration stanza\. \fBi\fR needs to be replaced with the index of the configured listener zones, starting with 1\.
.
.SH "EXAMPLES"
.
.nf
arpa compute\.internal {
# proxy unmatched requests
proxy \. 8\.8\.8\.8
# answer requests for IPs in this network
# PTR 1\.0\.32\.10\.in\-addr\.arpa\. 3600 ip\-10\.0\.32\.1\.compute\.internal\.
# A ip\-10\.0\.32\.1\.compute\.internal\. 3600 10\.0\.32\.1
# v6 is also possible
# PTR 1\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.0\.1\.0\.d\.f\.ip6\.arpa\. 3600 ip\-fd010000000000000000000000000001\.compute\.internal\.
# AAAA ip\-fd010000000000000000000000000001\.compute\.internal\. 3600 fd01::1
reverse 10\.32\.0\.0/16 fd01::/16 {
# template of the ip injection to hostname, zone resolved to compute\.internal\.
hostname ip\-{ip}\.{zone[2]}
ttl 3600
# Forward unanswered or unmatched requests to proxy
# without this flag, requesting A/AAAA records on compute\.internal\. will end here\.
fallthrough
}
}
.
.fi
.
.IP "" 4
.
.nf
32\.10\.in\-addr\.arpa\.arpa arpa\.company\.org {
reverse 10\.32\.0\.0/16 {
# template of the ip injection to hostname, zone resolved to arpa\.company\.org\.
hostname "ip\-{ip}\.v4\.{zone[2]}"
ttl 3600
# fallthrough is not required, v4\.arpa\.company\.org\. will be only answered here
}
# cidr closer to the ip wins, so we can overwrite the "default"
reverse 10\.32\.2\.0/24 {
# its also possible to set fix domain suffix
hostname ip\-{ip}\.fix\.arpa\.company\.org\.
ttl 3600
}
}
.
.fi
.
.IP "" 0
man/coredns-rewrite.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-REWRITE" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIrewrite\fR \- performs internal message rewriting\.
.
.SH "DESCRIPTION"
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"
.
.nf
rewrite [continue|stop] FIELD FROM TO
.
.fi
.
.IP "\(bu" 4
\fBFIELD\fR is (\fBtype\fR, \fBclass\fR, \fBname\fR, \.\.\.)
.
.IP "\(bu" 4
\fBFROM\fR is the exact name of type to match
.
.IP "\(bu" 4
\fBTO\fR is the destination name or type to rewrite to
.
.IP "" 0
.
.P
When the FIELD is \fBtype\fR and FROM is (\fBA\fR, \fBMX\fR, etc\.), the type of the message will be rewritten; e\.g\., to rewrite ANY queries to HINFO, use \fBrewrite type ANY HINFO\fR\.
.
.P
When the FIELD is \fBclass\fR and FROM is (\fBIN\fR, \fBCH\fR, or \fBHS\fR) the class of the message will be rewritten; e\.g\., to rewrite CH queries to IN use \fBrewrite class CH IN\fR\.
.
.P
When the FIELD is \fBname\fR the query name in the message is rewritten; this needs to be a full match of the name, e\.g\., \fBrewrite name miek\.nl example\.org\fR\.
.
.P
When the FIELD is \fBedns0\fR an EDNS0 option can be appended to the request as described below\.
.
.P
If you specify multiple rules and an incoming query matches on multiple rules, the rewrite will behave as following * \fBcontinue\fR will continue apply the next rule in the rule list\. * \fBstop\fR will consider the current rule is the last rule and will not continue\. Default behaviour for not specifying this rule processing mode is \fBstop\fR
.
.SH "EDNS0 OPTIONS"
Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request\.
.
.IP "\(bu" 4
\fBreplace\fR will modify any matching (what that means may vary based on EDNS0 type) option with the specified option
.
.IP "\(bu" 4
\fBappend\fR will add the option regardless of what options already exist
.
.IP "\(bu" 4
\fBset\fR will modify a matching option or add one if none is found
.
.IP "" 0
.
.P
Currently supported are \fBEDNS0_LOCAL\fR, \fBEDNS0_NSID\fR and \fBEDNS0_SUBNET\fR\.
.
.SS "EDNS0_LOCAL"
This has two fields, code and data\. A match is defined as having the same code\. Data may be a string or a variable\.
.
.TP
A string data can be treated as hex if it starts with \fB0x\fR\. Example:
.
.IP "" 4
.
.nf
\&\. {
rewrite edns0 local set 0xffee 0x61626364
whoami
}
.
.fi
.
.IP "" 0
.
.P
rewrites the first local option with code 0xffee, setting the data to "abcd"\. Equivalent:
.
.IP "" 4
.
.nf
\&\. {
rewrite edns0 local set 0xffee abcd
}
.
.fi
.
.IP "" 0
.
.TP
A variable data is specified with a pair of curly brackets \fB{}\fR\. Following are the supported variables
{qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}\.
.
.P
Example:
.
.IP "" 4
.
.nf
rewrite edns0 local set 0xffee {client_ip}
.
.fi
.
.IP "" 0
.
.SS "EDNS0_NSID"
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 \fBreplace\fR or \fBset\fR, then the NSID in the option will be set to the empty string\.
.
.SS "EDNS0_SUBNET"
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\.
.
.P
Example:
.
.IP "" 4
.
.nf
rewrite edns0 subnet set 24 56
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
If the query has source IP as IPv4, 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\.
.
.IP "" 0
.
.SS "NAME FIELD REWRITES"
The \fBrewrite\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\.
.
.P
The syntax for the name re\-writing is as follows:
.
.IP "" 4
.
.nf
rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
.
.fi
.
.IP "" 0
.
.P
The match type, i\.e\. \fBexact\fR, \fBsubstring\fR, etc\., triggers re\-write:
.
.IP "\(bu" 4
\fBexact\fR (default): on exact match of the name in the question section of a request
.
.IP "\(bu" 4
\fBsubstring\fR: on a partial match of the name in the question section of a request
.
.IP "\(bu" 4
\fBprefix\fR: when the name begins with the matching string
.
.IP "\(bu" 4
\fBsuffix\fR: when the name ends with the matching string
.
.IP "\(bu" 4
\fBregex\fR: when the name in the question section of a request matches a regular expression
.
.IP "" 0
.
.P
If the match type is omitted, the \fBexact\fR match type is being assumed\.
.
.P
The following instruction allows re\-writing the name in the query that contains \fBservice\.us\-west\-1\.example\.org\fR substring\.
.
.IP "" 4
.
.nf
rewrite name substring service\.us\-west\-1\.example\.org service\.us\-west\-1\.consul
.
.fi
.
.IP "" 0
.
.P
Thus:
.
.IP "\(bu" 4
Incoming Request Name: \fBftp\.service\.us\-west\-1\.example\.org\fR
.
.IP "\(bu" 4
Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
.
.IP "" 0
.
.P
The following instruction uses regular expressions\. The name in a request matching \fB(\.*)\-(us\-west\-1)\e\.example\e\.org\fR regular expression is being replaces with \fB{1}\.service\.{2}\.consul\fR, where \fB{1}\fR and \fB{2}\fR are regular expression match groups\.
.
.IP "" 4
.
.nf
rewrite name regex (\.*)\-(us\-west\-1)\e\.example\e\.org {1}\.service\.{2}\.consul
.
.fi
.
.IP "" 0
.
.P
Thus:
.
.IP "\(bu" 4
Incoming Request Name: \fBftp\-us\-west\-1\.example\.org\fR
.
.IP "\(bu" 4
Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
.
.IP "" 0
man/coredns-root.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-ROOT" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIroot\fR \- simply specifies the root of where to find (zone) files\.
.
.SH "DESCRIPTION"
The default root is the current working directory of CoreDNS\. The \fIroot\fR plugin allows you to change this\. A relative root path is relative to the current working directory\.
.
.SH "SYNTAX"
.
.nf
root PATH
.
.fi
.
.P
\fBPATH\fR is the directory to set as CoreDNS\' root\.
.
.SH "EXAMPLES"
Serve zone data (when the \fIfile\fR plugin is used) from \fB/etc/coredns/zones\fR:
.
.IP "" 4
.
.nf
\&\. {
root /etc/coredns/zones
}
.
.fi
.
.IP "" 0
man/coredns-secondary.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-SECONDARY" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIsecondary\fR \- enables serving a zone retrieved from a primary server\.
.
.SH "DESCRIPTION"
With \fIsecondary\fR you can transfer (via AXFR) a zone from another server\. The retrieved zone is \fInot committed\fR to disk (a violation of the RFC)\. This means restarting CoreDNS will cause it to retrieve all secondary zones\.
.
.IP "" 4
.
.nf
secondary [ZONES\.\.\.]
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBZONES\fR zones it should be authoritative for\. If empty, the zones from the configuration block are used\. Note that without a remote address to \fIget\fR the zone from, the above is not that useful\.
.
.IP "" 0
.
.P
A working syntax would be:
.
.IP "" 4
.
.nf
secondary [zones\.\.\.] {
transfer from ADDRESS
transfer to ADDRESS
upstream ADDRESS\.\.\.
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBtransfer from\fR specifies from which address to fetch the zone\. It can be specified multiple times; if one does not work, another will be tried\.
.
.IP "\(bu" 4
\fBtransfer to\fR can be enabled to allow this secondary zone to be transferred again\.
.
.IP "\(bu" 4
\fBupstream\fR defines upstream resolvers to be used resolve external names found (think CNAMEs) pointing to external names\. This is only really useful when CoreDNS is configured as a proxy, for normal authoritative serving you don\'t need \fIor\fR want to use this\. \fBADDRESS\fR can be an IP address, and IP:port or a string pointing to a file that is structured as /etc/resolv\.conf\.
.
.IP "" 0
.
.SH "EXAMPLES"
Transfer \fBexample\.org\fR from 10\.0\.1\.1, and if that fails try 10\.1\.2\.1\.
.
.IP "" 4
.
.nf
example\.org {
secondary {
transfer from 10\.0\.1\.1
transfer from 10\.1\.2\.1
}
}
.
.fi
.
.IP "" 0
.
.P
Or re\-export the retrieved zone to other secondaries\.
.
.IP "" 4
.
.nf
\&\. {
secondary example\.net {
transfer from 10\.1\.2\.1
transfer to *
}
}
.
.fi
.
.IP "" 0
Only AXFR is supported and the retrieved zone is not committed to disk\.
man/coredns-tls.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-TLS" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fItls\fR \- allows you to configure the server certificates for the TLS and gRPC servers\.
.
.SH "DESCRIPTION"
CoreDNS supports queries that are encrypted using TLS (DNS over Transport Layer Security, RFC 7858) or are using gRPC (https://grpc\.io/, not an IETF standard)\. Normally DNS traffic isn\'t encrypted at all (DNSSEC only signs resource records)\.
.
.P
The \fIproxy\fR plugin also support gRPC (\fBprotocol gRPC\fR), meaning you can chain CoreDNS servers using this protocol\.
.
.P
The \fItls\fR "plugin" allows you to configure the cryptographic keys that are needed for both DNS\-over\-TLS and DNS\-over\-gRPC\. If the \fBtls\fR directive is omitted, then no encryption takes place\.
.
.P
The gRPC protobuffer is defined in \fBpb/dns\.proto\fR\. It defines the proto as a simple wrapper for the wire data of a DNS message\.
.
.SH "SYNTAX"
.
.nf
tls CERT KEY CA
.
.fi
.
.SH "EXAMPLES"
Start a DNS\-over\-TLS server that picks up incoming DNS\-over\-TLS queries on port 5553 and uses the nameservers defined in \fB/etc/resolv\.conf\fR to resolve the query\. This proxy path uses plain old DNS\.
.
.IP "" 4
.
.nf
tls://\.:5553 {
tls cert\.pem key\.pem ca\.pem
proxy \. /etc/resolv\.conf
}
.
.fi
.
.IP "" 0
.
.P
Start a DNS\-over\-gRPC server that is similar to the previous example, but using DNS\-over\-gRPC for incoming queries\.
.
.IP "" 4
.
.nf
grpc://\. {
tls cert\.pem key\.pem ca\.pem
proxy \. /etc/resolv\.conf
}
.
.fi
.
.IP "" 0
.
.P
Only Knot DNS\' \fBkdig\fR supports DNS\-over\-TLS queries, no command line client supports gRPC making debugging these transports harder than it should be\.
.
.SH "ALSO SEE"
RFC 7858 and https://grpc\.io\.
man/coredns-trace.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-TRACE" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fItrace\fR \- enables OpenTracing\-based tracing of DNS requests as they go through the plugin chain\.
.
.SH "DESCRIPTION"
With \fItrace\fR you enable OpenTracing of how a request flows through CoreDNS\.
.
.SH "SYNTAX"
The simplest form is just:
.
.IP "" 4
.
.nf
trace [ENDPOINT\-TYPE] [ENDPOINT]
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBENDPOINT\-TYPE\fR is the type of tracing destination\. Currently only \fBzipkin\fR is supported and that is what it defaults to\.
.
.IP "\(bu" 4
\fBENDPOINT\fR is the tracing destination, and defaults to \fBlocalhost:9411\fR\. For Zipkin, if ENDPOINT does not begin with \fBhttp\fR, then it will be transformed to \fBhttp://ENDPOINT/api/v1/spans\fR\.
.
.IP "" 0
.
.P
With this form, all queries will be traced\.
.
.P
Additional features can be enabled with this syntax:
.
.IP "" 4
.
.nf
trace [ENDPOINT\-TYPE] [ENDPOINT] {
every AMOUNT
service NAME
client_server
}
.
.fi
.
.IP "" 0
.
.IP "\(bu" 4
\fBevery\fR \fBAMOUNT\fR will only trace one query of each AMOUNT queries\. For example, to trace 1 in every 100 queries, use AMOUNT of 100\. The default is 1\.
.
.IP "\(bu" 4
\fBservice\fR \fBNAME\fR allows you to specify the service name reported to the tracing server\. Default is \fBcoredns\fR\.
.
.IP "\(bu" 4
\fBclient_server\fR will enable the \fBClientServerSameSpan\fR OpenTracing feature\.
.
.IP "" 0
.
.SH "ZIPKIN"
You can run Zipkin on a Docker host like this:
.
.IP "" 4
.
.nf
docker run \-d \-p 9411:9411 openzipkin/zipkin
.
.fi
.
.IP "" 0
.
.SH "EXAMPLES"
Use an alternative Zipkin address:
.
.IP "" 4
.
.nf
trace tracinghost:9253
.
.fi
.
.IP "" 0
.
.P
or
.
.IP "" 4
.
.nf
\&\. {
trace zipkin tracinghost:9253
}
.
.fi
.
.IP "" 0
.
.P
If for some reason you are using an API reverse proxy or something and need to remap the standard Zipkin URL you can do something like:
.
.IP "" 4
.
.nf
trace http://tracinghost:9411/zipkin/api/v1/spans
.
.fi
.
.IP "" 0
.
.P
Trace one query every 10000 queries, rename the service, and enable same span:
.
.IP "" 4
.
.nf
trace tracinghost:9411 {
every 10000
service dnsproxy
client_server
}
.
.fi
.
.IP "" 0
man/coredns-whoami.7 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-WHOAMI" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fIwhoami\fR \- returns your resolver\'s local IP address, port and transport\.
.
.SH "DESCRIPTION"
The \fIwhoami\fR plugin is not really that useful, but can be used for having a simple (fast) endpoint to test clients against\. When \fIwhoami\fR returns a response it will have your client\'s IP address the additional section as either an A or AAAA record\.
.
.P
The reply always has an empty answer section\. The port and transport are included in the additional section as a SRV record, transport can be "tcp" or "udp"\.
.
.IP "" 4
.
.nf
\&\._<transport>\.qname\. 0 IN SRV 0 0 <port> \.
.
.fi
.
.IP "" 0
.
.P
The \fIwhoami\fR plugin will respond to every A or AAAA query, regardless of the query name\.
.
.P
If CoreDNS can\'t find a Corefile on startup this is the \fIdefault\fR plugin that gets loaded\. As such 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"
.
.nf
whoami
.
.fi
.
.SH "EXAMPLES"
Start a server on the default port and load the \fIwhoami\fR plugin\.
.
.IP "" 4
.
.nf
\&\. {
whoami
}
.
.fi
.
.IP "" 0
.
.P
When queried for "example\.org A", CoreDNS will respond with:
.
.IP "" 4
.
.nf
;; QUESTION SECTION:
;example\.org\. IN A
;; ADDITIONAL SECTION:
example\.org\. 0 IN A 10\.240\.0\.1
_udp\.example\.org\. 0 IN SRV 0 0 40212
.
.fi
.
.IP "" 0
man/coredns.1 0 → 100644
View file @ 58221f55
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS" "1" "January 2018" "CoreDNS" "CoreDNS"
.
.SH "NAME"
\fBcoredns\fR
.
.SH "NAME"
\fIcoredns\fR \- plugable DNS nameserver optimized for service discovery\.
.
.SH "SYNOPSIS"
\fIcoredns\fR \fI[OPTION]\fR\.\.\.
.
.SH "DESCRIPTION"
CoreDNS is a DNS server that chains plugins\. Each plugin handles a DNS feature, like rewriting queries, kubernetes service discovery or just exporting metrics\. There are many other plugins, each described on \fIhttps://coredns\.io/plugins\fR and there respective manual pages\.
.
.P
When started with no options CoreDNS will looks for a file names \fBCorefile\fR in the current directory, if found it will parse its contents and start up accordingly\. If no \fBCorefile\fR is found it will start with the \fIwhoami\fR plugin (coredns\-whoami(7)) and start listening on port 53 (unless overriden with \fB\-dns\.port\fR)\.
.
.P
Available options:
.
.TP
\fB\-conf\fR \fBFILE\fR
specificy Corefile to load\.
.
.TP
\fB\-cpu\fR \fBCAP\fR
specify maximum CPU capacity in percent\.
.
.TP
\fB\-dns\.port\fR \fBPORT\fR
override default port to listen on\.
.
.TP
\fB\-pidfile\fR \fBFILE\fR
write PID to \fBFILE\fR\.
.
.TP
\fB\-plugins\fR
list all plugins and quit\.
.
.TP
\fB\-quiet\fR
don\'t print any version and port information on startup\.
.
.TP
\fB\-version\fR
show version and quit\.
.
.SH "AUTHORS"
CoreDNS Authors\.
.
.SH "COPYRIGHT"
Apache License 2\.0
.
.SH "SEE ALSO"
Corefile(7) corendns\-debug(7) corendns\-dnssec(7) corendns\-health(7) corendns\-log(7) corendns\-file(7) corendns\-nsid(7) corendns\-autopath(7) corendns\-auto(7) corendns\-erratic(7) corendns\-chaos(7) corendns\-dnstap(7) corendns\-pprof(7) corendns\-tls(7) corendns\-loadbalance(7) corendns\-cache(7) corendns\-root(7) corendns\-whoami(7) corendns\-bind(7) corendns\-hosts(7) corendns\-proxy(7) corendns\-kubernetes(7) corendns\-secondary(7) corendns\-reverse(7) corendns\-errors(7) corendns\-metrics(7) corendns\-rewrite(7) corendns\-federation(7) corendns\-etcd(7) corendns\-trace(7)\.
plugin.md
View file @ 58221f55
...@@ -20,7 +20,10 @@ Each plugin should have a README.md explaining what the plugin does and how it i ...@@ -20,7 +20,10 @@ Each plugin should have a README.md explaining what the plugin does and how it i
file should have the following layout: file should have the following layout:
* Title: use the plugin's name * Title: use the plugin's name
* Subsection titled: "Syntax" * Subsection titled: "Named"
with *PLUGIN* - one line description.
* Subsection titled: "Description" has a longer description.
* Subsection titled: "Syntax", syntax and supported directives.
* Subsection titled: "Examples" * Subsection titled: "Examples"
More sections are of course possible. More sections are of course possible.
......
plugin/auto/README.md
View file @ 58221f55
# auto # auto
*auto* enables serving zone data from an RFC 1035-style master file which is automatically picked ## Name
up from disk.
*auto* - enables serving zone data from an RFC 1035-style master file which is automatically picked up from disk.
## Description
The *auto* plugin is used for an "old-style" DNS server. It serves from a preloaded file that exists The *auto* 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. DNSSEC) correct DNSSEC answers on disk. If the zone file contains signatures (i.e. is signed, i.e. DNSSEC) correct DNSSEC answers
......
plugin/autopath/README.md
View file @ 58221f55
# autopath # autopath
*autopath* allows for server side search path completion. ## Name
*autopath* - allows for server side search path completion.
## Description
If it sees a query that matches the first element of the configured search path, *autopath* will If it sees a query that matches the first element of the configured search path, *autopath* will
follow the chain of search path elements and returns the first reply that is not NXDOMAIN. On any follow the chain of search path elements and returns the first reply that is not NXDOMAIN. On any
......
plugin/bind/README.md
View file @ 58221f55
# bind # bind
*bind* overrides the host to which the server should bind. ## Name
*bind* - overrides the host to which the server should bind.
## Description
Normally, the listener binds to the wildcard host. However, you may force the listener to bind to Normally, the listener binds to the wildcard host. However, you may force the listener to bind to
another IP instead. This directive accepts only an address, not a port. another IP instead. This directive accepts only an address, not a port.
......
plugin/cache/README.md
View file @ 58221f55
# cache # cache
*cache* enables a frontend cache. It will cache all records except zone transfers and metadata records. ## Name
*cache* - enables a frontend cache.
## Description
With *cache* 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,
database, etc.) is expensive.
## Syntax ## Syntax
......
plugin/chaos/README.md
View file @ 58221f55
# chaos # chaos
*chaos* allows for responding to TXT queries in the CH class. ## Name
This is useful for retrieving version or author information from the server. *chaos* - allows for responding to TXT queries in the CH class.
## Description
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.
## Syntax ## Syntax
......
plugin/debug/README.md
View file @ 58221f55
# debug # debug
*debug* disables the automatic recovery upon a crash so that you'll get a nice stack trace. ## Name
Note that the *errors* plugin (if loaded) will also set a `recover` negating this setting. The main *debug* - disables the automatic recovery upon a crash so that you'll get a nice stack trace.
use of *debug* is to help testing.
## Description
Normally CoreDNS will recover from panics, using *debug* inhibits this. The main use of *debug* is
to help testing.
Note that the *errors* plugin (if loaded) will also set a `recover` negating this setting.
## Syntax ## Syntax
......
plugin/dnssec/README.md
View file @ 58221f55
# dnssec # dnssec
*dnssec* enables on-the-fly DNSSEC signing of served data. ## Name
*dnssec* - enable on-the-fly DNSSEC signing of served data.
## Description
With *dnssec* 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
this leads to smaller signatures (compared to RSA). NSEC3 is *not* supported.
## Syntax ## Syntax
......
plugin/dnstap/README.md
View file @ 58221f55
# dnstap # dnstap
*dnstap* enables logging to dnstap, a flexible, structured binary log format for DNS software: http://dnstap.info. ## Name
There is a buffer, expect at least 13 requests before the server sends its dnstap messages to the socket. *dnstap* - enable logging to dnstap
## Description
dnstap is a flexible, structured binary log format for DNS software: http://dnstap.info. With this
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.
## Syntax ## Syntax
...@@ -33,14 +41,10 @@ Log to a remote endpoint. ...@@ -33,14 +41,10 @@ Log to a remote endpoint.
dnstap tcp://127.0.0.1:6000 full dnstap tcp://127.0.0.1:6000 full
~~~ ~~~
## Dnstap command line tool ## Command Line Tool
~~~ sh Dnstap has a command line tool that can be used to inspect the logging. The tool can be found
% go get github.com/dnstap/golang-dnstap at Github: <https://github.com/dnstap/golang-dnstap>. It's written in Go.
% cd $GOPATH/src/github.com/dnstap/golang-dnstap/dnstap
% go build
% ./dnstap
~~~
The following command listens on the given socket and decodes messages to stdout. The following command listens on the given socket and decodes messages to stdout.
...@@ -59,3 +63,7 @@ Listen for dnstap messages on port 6000. ...@@ -59,3 +63,7 @@ Listen for dnstap messages on port 6000.
~~~ sh ~~~ sh
% dnstap -l 127.0.0.1:6000 % dnstap -l 127.0.0.1:6000
~~~ ~~~
# See Also
[dnstap.info](http://dnstap.info).
plugin/erratic/README.md
View file @ 58221f55
# erratic # erratic
*erratic* is a plugin useful for testing client behavior. ## Name
It returns a static response to all queries, but the responses can be delayed, dropped or truncated. *erratic* - a plugin useful for testing client behavior.
## Description
*erratic* returns a static response to all queries, but the responses can be delayed, dropped or truncated.
The *erratic* plugin will respond to every A or AAAA query. For any other type it will return The *erratic* plugin will respond to every A or AAAA query. For any other type it will return
a SERVFAIL response. The reply for A will return 192.0.2.53 (see RFC 5737), for AAAA it returns a SERVFAIL response. The reply for A will return 192.0.2.53 (see RFC 5737), for AAAA it returns
2001:DB8::53 (see RFC 3849). 2001:DB8::53 (see RFC 3849).
......
plugin/errors/README.md
View file @ 58221f55
# errors # errors
*errors* enables error logging. ## Name
*errors* - enable error logging.
## Description
Any errors encountered during the query processing will be printed to standard output. Any errors encountered during the query processing will be printed to standard output.
......
plugin/etcd/README.md
View file @ 58221f55
# etcd # etcd
*etcd* enables reading zone data from an etcd instance. The data in etcd has to be encoded as ## Name
*etcd* - enables reading zone data from an etcd instance.
## Description
The data in etcd has to be encoded as
a [message](https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26) a [message](https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26)
like [SkyDNS](https://github.com/skynetservices/skydns). It should also work just like SkyDNS. like [SkyDNS](https://github.com/skynetservices/skydns). It should also work just like SkyDNS.
...@@ -41,10 +47,13 @@ etcd [ZONES...] { ...@@ -41,10 +47,13 @@ etcd [ZONES...] {
the proxy plugin. **ADDRESS** can be an IP address, and IP:port or a string pointing to a file the proxy plugin. **ADDRESS** can be an IP address, and IP:port or a string pointing to a file
that is structured as /etc/resolv.conf. that is structured as /etc/resolv.conf.
* `tls` followed by: * `tls` followed by:
* no arguments, if the server certificate is signed by a system-installed CA and no client cert is needed
* a single argument that is the CA PEM file, if the server cert is not signed by a system CA and no client cert is needed * no arguments, if the server certificate is signed by a system-installed CA and no client cert is needed
* two arguments - path to cert PEM file, the path to private key PEM file - if the server certificate is signed by a system-installed CA and a client certificate is needed * a single argument that is the CA PEM file, if the server cert is not signed by a system CA and no client cert is needed
* three arguments - path to cert PEM file, path to client private key PEM file, path to CA PEM file - if the server certificate is not signed by a system-installed CA and client certificate is needed * two arguments - path to cert PEM file, the path to private key PEM file - if the server certificate is signed by a system-installed CA and a client certificate is needed
* three arguments - path to cert PEM file, path to client private key PEM file, path to CA PEM
file - if the server certificate is not signed by a system-installed CA and client certificate
is needed.
## Examples ## Examples
...@@ -114,3 +123,7 @@ Querying with dig: ...@@ -114,3 +123,7 @@ Querying with dig:
% dig @localhost -x 10.0.0.127 +short % dig @localhost -x 10.0.0.127 +short
reverse.skydns.local. reverse.skydns.local.
~~~ ~~~
# Bugs
Only the etcdv2 protocol is supported.
plugin/federation/README.md
View file @ 58221f55
# federation # federation
*federation* enables ## Name
[federated](https://kubernetes.io/docs/tasks/federation/federation-service-discovery/) queries to be
*federation* - enables federated queries to be resolved via the kubernetes plugin.
## Description
Enabling this plugin allows
[Federated](https://kubernetes.io/docs/tasks/federation/federation-service-discovery/) queries to be
resolved via the kubernetes plugin. resolved via the kubernetes plugin.
Enabling *federation* without also having *kubernetes* is a noop. Enabling *federation* without also having *kubernetes* is a noop.
...@@ -11,6 +17,7 @@ Enabling *federation* without also having *kubernetes* is a noop. ...@@ -11,6 +17,7 @@ Enabling *federation* without also having *kubernetes* is a noop.
~~~ ~~~
federation [ZONES...] { federation [ZONES...] {
NAME DOMAIN NAME DOMAIN
}
~~~ ~~~
* Each **NAME** and **DOMAIN** defines federation membership. One entry for each. A duplicate * Each **NAME** and **DOMAIN** defines federation membership. One entry for each. A duplicate
......
plugin/file/README.md
View file @ 58221f55
# file # file
*file* enables serving zone data from an RFC 1035-style master file. ## Name
*file* - enables serving zone data from an RFC 1035-style master file.
## Description
The file plugin is used for an "old-style" DNS server. It serves from a preloaded file that exists The file 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. DNSSEC) correct DNSSEC answers on disk. If the zone file contains signatures (i.e. is signed, i.e. DNSSEC) correct DNSSEC answers
......
plugin/health/README.md
View file @ 58221f55
# health # health
*health* enables a simple health check endpoint. ## Name
By default, it listens on port 8080. *health* - enables a health check endpoint.
## Description
By enabling *health* any plugin that implements it will be queried for it's health. The combined
health is exported, by default, on port 8080/health .
## Syntax ## Syntax
......
plugin/hosts/README.md
View file @ 58221f55
# hosts # hosts
*hosts* enables serving zone data from a `/etc/hosts` style file. ## Name
*hosts* - enables serving zone data from a `/etc/hosts` style file.
## Description
The hosts plugin is useful for serving zones from a /etc/hosts file. It serves from a preloaded The hosts plugin is useful for serving zones from a /etc/hosts file. It serves from a preloaded
file that exists on disk. It checks the file for changes and updates the zones accordingly. This file that exists on disk. It checks the file for changes and updates the zones accordingly. This
......
plugin/kubernetes/README.md
View file @ 58221f55
# kubernetes # kubernetes
The *kubernetes* plugin enables the reading zone data from a Kubernetes cluster. ## Name
*kubernetes* - enables the reading zone data from a Kubernetes cluster.
## Description
It implements the [Kubernetes DNS-Based Service Discovery It implements the [Kubernetes DNS-Based Service Discovery
Specification](https://github.com/kubernetes/dns/blob/master/docs/specification.md). Specification](https://github.com/kubernetes/dns/blob/master/docs/specification.md).
...@@ -66,15 +70,15 @@ kubernetes [ZONES...] { ...@@ -66,15 +70,15 @@ kubernetes [ZONES...] {
option requires substantially more memory than in insecure mode, since it will maintain a watch option requires substantially more memory than in insecure mode, since it will maintain a watch
on all pods. on all pods.
* `endpoint_pod_names` uses the pod name of the pod targeted by the endpoint as * `endpoint_pod_names` uses the pod name of the pod targeted by the endpoint as
the endpoint name in A records, e.g. the endpoint name in A records, e.g.
`endpoint-name.my-service.namespace.svc.cluster.local. in A 1.2.3.4` `endpoint-name.my-service.namespace.svc.cluster.local. in A 1.2.3.4`
By default, the endpoint-name name selection is as follows: Use the hostname By default, the endpoint-name name selection is as follows: Use the hostname
of the endpoint, or if hostname is not set, use the dashed form of the endpoint of the endpoint, or if hostname is not set, use the dashed form of the endpoint
IP address (e.g. `1-2-3-4.my-service.namespace.svc.cluster.local.`) IP address (e.g. `1-2-3-4.my-service.namespace.svc.cluster.local.`)
If this directive is included, then name selection for endpoints changes as If this directive is included, then name selection for endpoints changes as
follows: Use the hostname of the endpoint, or if hostname is not set, use the follows: Use the hostname of the endpoint, or if hostname is not set, use the
pod name of the pod targeted by the endpoint. If there is no pod targeted by pod name of the pod targeted by the endpoint. If there is no pod targeted by
the endpoint, use the dashed IP address form. the endpoint, use the dashed IP address form.
* `upstream` **ADDRESS [ADDRESS...]** defines the upstream resolvers used for resolving services * `upstream` **ADDRESS [ADDRESS...]** defines the upstream resolvers used for resolving services
that point to external hosts (External Services). **ADDRESS** can be an IP, an IP:port, or a path that point to external hosts (External Services). **ADDRESS** can be an IP, an IP:port, or a path
...@@ -174,11 +178,8 @@ feature enables serving federated domains from the kubernetes clusters. ...@@ -174,11 +178,8 @@ feature enables serving federated domains from the kubernetes clusters.
Some query labels accept a wildcard value to match any value. If a label is a valid wildcard (\*, Some query labels accept a wildcard value to match any value. If a label is a valid wildcard (\*,
or the word "any"), then that label will match all values. The labels that accept wildcards are: or the word "any"), then that label will match all values. The labels that accept wildcards are:
* _service_ in an `A` record request: _service_.namespace.svc.zone. * _service_ in an `A` record request: _service_.namespace.svc.zone, e.g. `*.ns.svc.myzone.local`
* e.g. `*.ns.svc.myzone.local` * _namespace_ in an `A` record request: service._namespace_.svc.zone, e.g. `nginx.*.svc.myzone.local`
* _namespace_ in an `A` record request: service._namespace_.svc.zone. * _port and/or protocol_ in an `SRV` request: __port_.__protocol_.service.namespace.svc.zone.,
* e.g. `nginx.*.svc.myzone.local` e.g. `_http.*.service.ns.svc.`
* _port and/or protocol_ in an `SRV` request: __port_.__protocol_.service.namespace.svc.zone. * multiple wild cards are allowed in a single query, e.g. `A` Request `*.*.svc.zone.` or `SRV` request `*.*.*.*.svc.zone.`
* e.g. `_http.*.service.ns.svc.`
* multiple wild cards are allowed in a single query.
* e.g. `A` Request `*.*.svc.zone.` or `SRV` request `*.*.*.*.svc.zone.`
plugin/loadbalance/README.md
View file @ 58221f55
# loadbalance # loadbalance
*loadbalance* acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records ## Name
*loadbalance* - acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records
in the answer. in the answer.
## Description
See [Wikipedia](https://en.wikipedia.org/wiki/Round-robin_DNS) about the pros and cons on this See [Wikipedia](https://en.wikipedia.org/wiki/Round-robin_DNS) about the pros and cons on this
setup. It will take care to sort any CNAMEs before any address records, because some stub resolver setup. It will take care to sort any CNAMEs before any address records, because some stub resolver
......
plugin/log/README.md
View file @ 58221f55
# log # log
*log* enables query logging to standard output. ## Name
*log* - enables query logging to standard output.
## Description
By just using *log* you dump all queries (and parts for the reply) on standard output. Options exist
to tweak the output a little.
Note that for busy servers this will incur a performance hit.
## Syntax ## Syntax
......
plugin/metrics/README.md
View file @ 58221f55
# prometheus # prometheus
*prometheus* enables [Prometheus](https://prometheus.io/) metrics. ## Name
*prometheus* - enables [Prometheus](https://prometheus.io/) metrics.
## Description
With *prometheus* you export metrics from CoreDNS and any plugin that has them.
The default location for the metrics is `localhost:9153`. The metrics path is fixed to `/metrics`. The default location for the metrics is `localhost:9153`. The metrics path is fixed to `/metrics`.
The following metrics are exported: The following metrics are exported:
......
plugin/nsid/README.md
View file @ 58221f55
# nsid # nsid
*nsid* adds an identifier of this server to each reply. ## Name
*nsid* - adds an identifier of this server to each reply.
## Description
This plugin implements RFC 5001 and adds an EDNS0 OPT resource record to replies that uniquely This plugin implements RFC 5001 and adds an EDNS0 OPT resource record to replies that uniquely
identify the server. This is useful in anycast setups to see which server was responsible for identify the server. This is useful in anycast setups to see which server was responsible for
......
plugin/pprof/README.md
View file @ 58221f55
# pprof # pprof
*pprof* publishes runtime profiling data at endpoints under `/debug/pprof`. ## Name
*pprof* - publishes runtime profiling data at endpoints under `/debug/pprof`.
## Description
You can visit `/debug/pprof` on your site for an index of the available endpoints. By default it You can visit `/debug/pprof` on your site for an index of the available endpoints. By default it
will listen on localhost:6053. will listen on localhost:6053.
...@@ -45,3 +49,8 @@ Listen on an all addresses on port 6060: ...@@ -45,3 +49,8 @@ Listen on an all addresses on port 6060:
pprof :6060 pprof :6060
} }
~~~ ~~~
# Also See
See [Go's pprof documentation](https://golang.org/pkg/net/http/pprof/) and [Profiling Go
Programs](https://blog.golang.org/profiling-go-programs).
plugin/proxy/README.md
View file @ 58221f55
# proxy # proxy
*proxy* facilitates both a basic reverse proxy and a robust load balancer. ## Name
*proxy* - facilitates both a basic reverse proxy and a robust load balancer.
## Description
The proxy has support for multiple backends. The load balancing features include multiple policies, The proxy has support for multiple backends. The load balancing features include multiple policies,
health checks, and failovers. If all hosts fail their health check the proxy plugin will fail health checks, and failovers. If all hosts fail their health check the proxy plugin will fail
...@@ -72,28 +76,30 @@ Currently `protocol` supports `dns` (i.e., standard DNS over UDP/TCP) and `https ...@@ -72,28 +76,30 @@ Currently `protocol` supports `dns` (i.e., standard DNS over UDP/TCP) and `https
payload over HTTPS). Note that with `https_google` the entire transport is encrypted. Only *you* and payload over HTTPS). Note that with `https_google` the entire transport is encrypted. Only *you* and
*Google* can see your DNS activity. *Google* can see your DNS activity.
* `dns`: uses the standard DNS exchange. You can pass `force_tcp` to make sure that the proxied connection is performed `dns`
over TCP, regardless of the inbound request's protocol. : uses the standard DNS exchange. You can pass `force_tcp` to make sure that the proxied connection is performed
* `https_google`: bootstrap **ADDRESS...** is used to (re-)resolve `dns.google.com` to an address to over TCP, regardless of the inbound request's protocol.
connect to. This happens every 300s. If not specified the default is used: 8.8.8.8:53/8.8.4.4:53.
Note that **TO** is *ignored* when `https_google` is used, as its upstream is defined as `grpc`
`dns.google.com`. : extra options are used to control how the TLS connection is made to the gRPC server.
Debug queries are enabled by default and currently there is no way to turn them off. When CoreDNS
receives a debug query (i.e. the name is prefixed with `o-o.debug.`) a TXT record with Comment
from `dns.google.com` is added. Note this is not always set.
* `grpc`: options are used to control how the TLS connection is made to the gRPC server.
* None - No client authentication is used, and the system CAs are used to verify the server certificate. * None - No client authentication is used, and the system CAs are used to verify the server certificate.
* `insecure` - TLS is not used, the connection is made in plaintext (not good in production). * `insecure` - TLS is not used, the connection is made in plaintext (not good in production).
* **CACERT** - No client authentication is used, and the file **CACERT** is used to verify the server certificate. * **CACERT** - No client authentication is used, and the file **CACERT** is used to verify the server certificate.
* **KEY** **CERT** - Client authentication is used with the specified key/cert pair. The server * **KEY** **CERT** - Client authentication is used with the specified key/cert pair. The server
certificate is verified with the system CAs. certificate is verified with the system CAs.
* **KEY** **CERT** **CACERT** - Client authentication is used with the specified key/cert pair. The * **KEY** **CERT** **CACERT** - Client authentication is used with the specified key/cert pair. The
server certificate is verified using the **CACERT** file. server certificate is verified using the **CACERT** file.
An out-of-tree plugin that implements the server side of this can be found at An out-of-tree plugin that implements the server side of this can be found at
[here](https://github.com/infobloxopen/coredns-grpc). [here](https://github.com/infobloxopen/coredns-grpc).
`https_google`
: bootstrap **ADDRESS...** is used to (re-)resolve `dns.google.com`.
This happens every 300s. If not specified the default is used: 8.8.8.8:53/8.8.4.4:53.
Note that **TO** is *ignored* when `https_google` is used, as its upstream is defined as `dns.google.com`.
## Metrics ## Metrics
If monitoring is enabled (via the *prometheus* directive) then the following metric is exported: If monitoring is enabled (via the *prometheus* directive) then the following metric is exported:
......
plugin/reverse/README.md
View file @ 58221f55
# reverse # reverse
*reverse* allows for dynamic responses to PTR and the related A/AAAA requests. ## Name
*reverse* - allows for dynamic responses to PTR and the related A/AAAA requests.
## Description
If a request matches a regular expression (see Template Syntax below) this plugin will generate a
response. This is only done for "address" records (PTR, A and AAAA).
## Syntax ## Syntax
......
plugin/rewrite/README.md
View file @ 58221f55
# rewrite # rewrite
*rewrite* performs internal message rewriting. ## Name
*rewrite* - performs internal message rewriting.
## Description
Rewrites are invisible to the client. There are simple rewrites (fast) and complex rewrites 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. (slower), but they're powerful enough to accommodate most dynamic back-end applications.
...@@ -28,7 +32,7 @@ When the FIELD is `edns0` an EDNS0 option can be appended to the request as desc ...@@ -28,7 +32,7 @@ When the FIELD is `edns0` an EDNS0 option can be appended to the request as desc
If you specify multiple rules and an incoming query matches on multiple rules, the rewrite If you specify multiple rules and an incoming query matches on multiple rules, the rewrite
will behave as following will behave as following
* `continue` will continue apply the next rule in the rule list. * `continue` will continue apply the next rule in the rule list.
* `stop` will consider the current rule is the last rule and will not continue. Default behaviour * `stop` will consider the current rule is the last rule and will not continue. Default behaviour
for not specifying this rule processing mode is `stop` for not specifying this rule processing mode is `stop`
...@@ -42,9 +46,9 @@ Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the ...@@ -42,9 +46,9 @@ Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the
Currently supported are `EDNS0_LOCAL`, `EDNS0_NSID` and `EDNS0_SUBNET`. Currently supported are `EDNS0_LOCAL`, `EDNS0_NSID` and `EDNS0_SUBNET`.
### `EDNS0_LOCAL` ### EDNS0_LOCAL
This has two fields, code and data. A match is defined as having the same code. Data may be a string or a variable. This has two fields, code and data. A match is defined as having the same code. Data may be a string or a variable.
* A string data can be treated as hex if it starts with `0x`. Example: * A string data can be treated as hex if it starts with `0x`. Example:
...@@ -64,13 +68,7 @@ rewrites the first local option with code 0xffee, setting the data to "abcd". Eq ...@@ -64,13 +68,7 @@ rewrites the first local option with code 0xffee, setting the data to "abcd". Eq
~~~ ~~~
* A variable data is specified with a pair of curly brackets `{}`. Following are the supported variables: * A variable data is specified with a pair of curly brackets `{}`. Following are the supported variables:
* {qname} {qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}.
* {qtype}
* {client_ip}
* {client_port}
* {protocol}
* {server_ip}
* {server_port}
Example: Example:
...@@ -78,15 +76,15 @@ Example: ...@@ -78,15 +76,15 @@ Example:
rewrite edns0 local set 0xffee {client_ip} rewrite edns0 local set 0xffee {client_ip}
~~~ ~~~
### `EDNS0_NSID` ### EDNS0_NSID
This has no fields; it will add an NSID option with an empty string for the NSID. If the option already exists 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 `replace` or `set`, then the NSID in the option will be set to the empty string. and the action is `replace` or `set`, then the NSID in the option will be set to the empty string.
### `EDNS0_SUBNET` ### EDNS0_SUBNET
This has two fields, IPv4 bitmask length and IPv6 bitmask length. The bitmask 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. length is used to extract the client subnet from the source IP address in the query.
Example: Example:
...@@ -109,7 +107,7 @@ The syntax for the name re-writing is as follows: ...@@ -109,7 +107,7 @@ The syntax for the name re-writing is as follows:
rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
``` ```
The match type, i.e. `exact`, `substring`, etc., triggers re-write: The match type, i.e. `exact`, `substring`, etc., triggers re-write:
* **exact** (default): on exact match of the name in the question section of a request * **exact** (default): on exact match of the name in the question section of a request
* **substring**: on a partial match of the name in the question section of a request * **substring**: on a partial match of the name in the question section of a request
...@@ -127,6 +125,7 @@ rewrite name substring service.us-west-1.example.org service.us-west-1.consul ...@@ -127,6 +125,7 @@ rewrite name substring service.us-west-1.example.org service.us-west-1.consul
``` ```
Thus: Thus:
* Incoming Request Name: `ftp.service.us-west-1.example.org` * Incoming Request Name: `ftp.service.us-west-1.example.org`
* Re-written Request Name: `ftp.service.us-west-1.consul` * Re-written Request Name: `ftp.service.us-west-1.consul`
...@@ -139,5 +138,6 @@ rewrite name regex (.*)-(us-west-1)\.example\.org {1}.service.{2}.consul ...@@ -139,5 +138,6 @@ rewrite name regex (.*)-(us-west-1)\.example\.org {1}.service.{2}.consul
``` ```
Thus: Thus:
* Incoming Request Name: `ftp-us-west-1.example.org` * Incoming Request Name: `ftp-us-west-1.example.org`
* Re-written Request Name: `ftp.service.us-west-1.consul` * Re-written Request Name: `ftp.service.us-west-1.consul`
plugin/root/README.md
View file @ 58221f55
# root # root
*root* simply specifies the root of where to find (zone) files. ## Name
The default root is the current working directory of CoreDNS. A relative root path is relative to *root* - simply specifies the root of where to find (zone) files.
the current working directory.
## Description
The default root is the current working directory of CoreDNS. The *root* plugin allows you to change
this. A relative root path is relative to the current working directory.
## Syntax ## Syntax
......
plugin/secondary/README.md
View file @ 58221f55
# secondary # secondary
*secondary* enables serving a zone retrieved from a primary server. ## Name
## Syntax *secondary* - enables serving a zone retrieved from a primary server.
## Description
With *secondary* you can transfer (via AXFR) a zone from another server. The retrieved zone is
*not committed* to disk (a violation of the RFC). This means restarting CoreDNS will cause it to
retrieve all secondary zones.
~~~ ~~~
secondary [ZONES...] secondary [ZONES...]
...@@ -52,3 +58,7 @@ Or re-export the retrieved zone to other secondaries. ...@@ -52,3 +58,7 @@ Or re-export the retrieved zone to other secondaries.
} }
} }
~~~ ~~~
# Bugs
Only AXFR is supported and the retrieved zone is not committed to disk.
plugin/tls/README.md
View file @ 58221f55
# tls # tls
*tls* allows you to configure the server certificates for the TLS and gRPC servers. ## Name
For other types of servers it is ignored.
*tls* - allows you to configure the server certificates for the TLS and gRPC servers.
## Description
CoreDNS supports queries that are encrypted using TLS (DNS over Transport Layer Security, RFC 7858) CoreDNS supports queries that are encrypted using TLS (DNS over Transport Layer Security, RFC 7858)
or are using gRPC (https://grpc.io/, not an IETF standard). Normally DNS traffic isn't encrypted at or are using gRPC (https://grpc.io/, not an IETF standard). Normally DNS traffic isn't encrypted at
......
plugin/trace/README.md
View file @ 58221f55
# trace # trace
*trace* enables OpenTracing-based tracing of DNS requests as they go through the plugin chain. ## Name
*trace* - enables OpenTracing-based tracing of DNS requests as they go through the plugin chain.
## Description
With *trace* you enable OpenTracing of how a request flows through CoreDNS.
## Syntax ## Syntax
......
plugin/whoami/README.md
View file @ 58221f55
# whoami # whoami
*whoami* returns your resolver's local IP address, port and transport. Your IP address is returned ## Name
in the additional section as either an A or AAAA record.
When CoreDNS can not find a Corefile to load, this is the default plugin it loads. *whoami* - returns your resolver's local IP address, port and transport.
## Description
The *whoami* plugin is not really that useful, but can be used for having a simple (fast) endpoint
to test clients against. When *whoami* returns a response it will have your client's IP address the
additional section as either an A or AAAA record.
The reply always has an empty answer section. The port and transport are included in the additional The reply always has an empty answer section. The port and transport are included in the additional
section as a SRV record, transport can be "tcp" or "udp". section as a SRV record, transport can be "tcp" or "udp".
...@@ -12,12 +17,12 @@ section as a SRV record, transport can be "tcp" or "udp". ...@@ -12,12 +17,12 @@ section as a SRV record, transport can be "tcp" or "udp".
._<transport>.qname. 0 IN SRV 0 0 <port> . ._<transport>.qname. 0 IN SRV 0 0 <port> .
~~~ ~~~
If CoreDNS can't find a Corefile on startup this is the *default* plugin that gets loaded. As
such it can be used to check that CoreDNS is responding to queries. Other than that this plugin
is of limited use in production.
The *whoami* plugin will respond to every A or AAAA query, regardless of the query name. The *whoami* plugin will respond to every A or AAAA query, regardless of the query name.
If CoreDNS can't find a Corefile on startup this is the _default_ plugin that gets loaded. As such
it can be used to check that CoreDNS is responding to queries. Other than that this plugin is of
limited use in production.
## Syntax ## Syntax
~~~ txt ~~~ txt
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment