packages/coredns-deployment
1
0
Fork 0
mirror of https://github.com/notherealmarco/coredns-deployment.git synced 2025-03-14 14:16:16 +01:00
Code Issues Projects Releases Packages 1 Wiki Activity Actions

Debian improvements (#45)

Browse source 
* Copy man-pages from source - add corefile.5

* Dont redownload every time
This commit is contained in:
Miek Gieben 2018-01-11 09:42:24 +00:00 committed by GitHub
parent 60666ffcc1
commit 190c36e4f1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
34 changed files with 20 additions and 3414 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
Makefile
View file

@ -1,10 +1,17 @@
# Makefile for building packages for CoreDNS.
# Build the debian packages
# ARCH can be and default to amd64 is not set.
# ARCH := amd64 armhf arm64
ifeq ($(ARCH),)
ARCH:=amd64
endif
.PHONY: debian
debian:
dpkg-buildpackage -us -uc -b --target-arch amd64
dpkg-buildpackage -us -uc -b --target-arch armhf
dpkg-buildpackage -us -uc -b --target-arch arm64
# debs are one up
ls ../*.deb
for a in $(ARCH); do \
dpkg-buildpackage -us -uc -b --target-arch $$aa ;\
done
debian-clean:
rm *.tgz

93
debian/man/coredns-auto.7 vendored
View file

@ -1,93 +0,0 @@
.\" 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

61
debian/man/coredns-autopath.7 vendored
View file

@ -1,61 +0,0 @@
.\" 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\.

37
debian/man/coredns-bind.7 vendored
View file

@ -1,37 +0,0 @@
.\" 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

116
debian/man/coredns-cache.7 vendored
View file

@ -1,116 +0,0 @@
.\" 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

77
debian/man/coredns-chaos.7 vendored
View file

@ -1,77 +0,0 @@
.\" 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

37
debian/man/coredns-debug.7 vendored
View file

@ -1,37 +0,0 @@
.\" 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

125
debian/man/coredns-dnssec.7 vendored
View file

@ -1,125 +0,0 @@
.\" 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

113
debian/man/coredns-dnstap.7 vendored
View file

@ -1,113 +0,0 @@
.\" 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
.
.SH "SEE ALSO"
dnstap\.info \fIhttp://dnstap\.info\fR\.

120
debian/man/coredns-erratic.7 vendored
View file

@ -1,120 +0,0 @@
.\" 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

35
debian/man/coredns-errors.7 vendored
View file

@ -1,35 +0,0 @@
.\" 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

189
debian/man/coredns-etcd.7 vendored
View file

@ -1,189 +0,0 @@
.\" 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 [ZONES\.\.\.]
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\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.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
.
.SH "BUGS"
Only the etcdv2 protocol is supported\.

67
debian/man/coredns-federation.7 vendored
View file

@ -1,67 +0,0 @@
.\" 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 queries to be resolved via the kubernetes plugin\.
.
.SH "DESCRIPTION"
Enabling this plugin allows Federated \fIhttps://kubernetes\.io/docs/tasks/federation/federation\-service\-discovery/\fR queries to be resolved via the kubernetes plugin\.
.
.P
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

91
debian/man/coredns-file.7 vendored
View file

@ -1,91 +0,0 @@
.\" 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

40
debian/man/coredns-health.7 vendored
View file

@ -1,40 +0,0 @@
.\" 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

95
debian/man/coredns-hosts.7 vendored
View file

@ -1,95 +0,0 @@
.\" 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 [ZONES\.\.\.]
}
.
.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\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.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

225
debian/man/coredns-kubernetes.7 vendored
View file

@ -1,225 +0,0 @@
.\" 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 [ZONES\.\.\.]
}
.
.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 \fB[ZONES\.\.\.]\fR If a query for a record in the zones for which the plugin is authoritative 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\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.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

40
debian/man/coredns-loadbalance.7 vendored
View file

@ -1,40 +0,0 @@
.\" 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

200
debian/man/coredns-log.7 vendored
View file

@ -1,200 +0,0 @@
.\" 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

103
debian/man/coredns-metrics.7 vendored
View file

@ -1,103 +0,0 @@
.\" 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
.
.SH "BUGS"
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\.

66
debian/man/coredns-nsid.7 vendored
View file

@ -1,66 +0,0 @@
.\" 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

72
debian/man/coredns-pprof.7 vendored
View file

@ -1,72 +0,0 @@
.\" 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
.
.SH "ALSO SEE"
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\.

276
debian/man/coredns-proxy.7 vendored
View file

@ -1,276 +0,0 @@
.\" 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
.
.SH "BUGS"
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\.

105
debian/man/coredns-reverse.7 vendored
View file

@ -1,105 +0,0 @@
.\" 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 [ZONES\.\.\.]]
[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\. If \fB[ZONES\.\.\.]\fR is omitted, then fallthrough happens for all zones for which the plugin is authoritative\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.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

228
debian/man/coredns-rewrite.7 vendored
View file

@ -1,228 +0,0 @@
.\" 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

37
debian/man/coredns-root.7 vendored
View file

@ -1,37 +0,0 @@
.\" 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

92
debian/man/coredns-secondary.7 vendored
View file

@ -1,92 +0,0 @@
.\" 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
.
.SH "BUGS"
Only AXFR is supported and the retrieved zone is not committed to disk\.

307
debian/man/coredns-template.7 vendored
View file

@ -1,307 +0,0 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREDNS\-TEMPLATE" "7" "January 2018" "CoreDNS" "CoreDNS plugins"
.
.SH "NAME"
\fItemplate\fR \- allows for dynamic responses based on the incoming query\.
.
.SH "DESCRIPTION"
The \fItemplate\fR plugin allows you to dynamically repond to queries by just writing a (Go) template\.
.
.SH "SYNTAX"
.
.nf
template CLASS TYPE [ZONE\.\.\.] {
[match REGEX\.\.\.]
[answer RR]
[additional RR]
[authority RR]
[\.\.\.]
[rcode CODE]
[fallthrough [ZONE\.\.\.]]
}
.
.fi
.
.IP "\(bu" 4
\fBCLASS\fR the query class (usually IN or ANY)\.
.
.IP "\(bu" 4
\fBTYPE\fR the query type (A, PTR, \.\.\. can be ANY to match all types)\.
.
.IP "\(bu" 4
\fBZONE\fR the zone scope(s) for this template\. Defaults to the server zones\.
.
.IP "\(bu" 4
\fBREGEX\fR Go regexp \fIhttps://golang\.org/pkg/regexp/\fR that are matched against the incoming question name\. Specifying no regex matches everything (default: \fB\.*\fR)\. First matching regex wins\.
.
.IP "\(bu" 4
\fBanswer|additional|authority\fR \fBRR\fR A RFC 1035 \fIhttps://tools\.ietf\.org/html/rfc1035#section\-5\fR style resource record fragment build by a Go template \fIhttps://golang\.org/pkg/text/template/\fR that contains the reply\.
.
.IP "\(bu" 4
\fBrcode\fR \fBCODE\fR A response code (\fBNXDOMAIN, SERVFAIL, \.\.\.\fR)\. The default is \fBSUCCESS\fR\.
.
.IP "\(bu" 4
\fBfallthrough\fR Continue with the next plugin if the zone matched but no regex did not match\. If specific zones are listed (for example \fBin\-addr\.arpa\fR and \fBip6\.arpa\fR), then only queries for those zones will be subject to fallthrough\.
.
.IP "" 0
.
.P
At least one \fBanswer\fR or \fBrcode\fR directive is needed (e\.g\. \fBrcode NXDOMAIN\fR)\.
.
.P
\fIAlso see\fR contains an additional reading list\.
.
.SH "TEMPLATES"
Each resource record is a full\-featured Go template \fIhttps://golang\.org/pkg/text/template/\fR with the following predefined data * \fB\.Zone\fR the matched zone string (e\.g\. \fBexample\.\fR)\. * \fB\.Name\fR the query name, as a string (lowercased)\. * \fB\.Class\fR the query class (usually \fBIN\fR)\. * \fB\.Type\fR the RR type requested (e\.g\. \fBPTR\fR)\. * \fB\.Match\fR an array of all matches\. \fBindex \.Match 0\fR refers to the whole match\. * \fB\.Group\fR a map of the named capture groups\. * \fB\.Message\fR the complete incoming DNS message\. * \fB\.Question\fR the matched question section\.
.
.P
The output of the template must be a RFC 1035 \fIhttps://tools\.ietf\.org/html/rfc1035\fR style resource record line (commonly refered to as a "zone file")\.
.
.P
\fBWARNING\fR there is a syntactical problem with Go templates and CoreDNS config files\. Expressions like \fB{{$var}}\fR will be interpreted as a reference to an environment variable by CoreDNS (and Caddy) while \fB{{ $var }}\fR will work\. See \fIBugs\fR and corefile(5)\.
.
.SH "METRICS"
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metrics are exported: \- \fBcoredns_template_matches_total{regex}\fR the total number of matched requests by regex\. \- \fBcoredns_template_template_failures_total{regex,section,template}\fR the number of times the Go templating failed\. Regex, section and template label values can be used to map the error back to the config file\. \- \fBcoredns_template_rr_failures_total{regex,section,template}\fR the number of times the templated resource record was invalid and could not be parsed\. Regex, section and template label values can be used to map the error back to the config file\.
.
.P
Both failure cases indicate a problem with the template configuration\.
.
.SH "EXAMPLES"
.
.SS "RESOLVE EVERYTHING TO NXDOMAIN"
The most simplistic template is
.
.IP "" 4
.
.nf
\&\. {
template ANY ANY {
rcode NXDOMAIN
}
}
.
.fi
.
.IP "" 0
.
.IP "1." 4
This template uses the default zone (\fB\.\fR or all queries)
.
.IP "2." 4
All queries will be answered (no \fBfallthrough\fR)
.
.IP "3." 4
The answer is always NXDOMAIN
.
.IP "" 0
.
.SS "RESOLVE \.INVALID AS NXDOMAIN"
The \fB\.invalid\fR domain is a reserved TLD (see RFC\-2606 Reserved Top Level DNS Names \fIhttps://tools\.ietf\.org/html/rfc2606#section\-2\fR) to indicate invalid domains\.
.
.IP "" 4
.
.nf
\&\. {
proxy \. 8\.8\.8\.8
template ANY ANY invalid {
rcode NXDOMAIN
answer "invalid\. 60 {{ \.Class }} SOA a\.invalid\. b\.invalid\. (1 60 60 60 60)"
}
}
.
.fi
.
.IP "" 0
.
.IP "1." 4
A query to \.invalid will result in NXDOMAIN (rcode)
.
.IP "2." 4
A dummy SOA record is send to hand out a TTL of 60s for caching
.
.IP "3." 4
Querying \fB\.invalid\fR of \fBCH\fR will also cause a NXDOMAIN/SOA response
.
.IP "4." 4
The default regex is \fB\.*\fR
.
.IP "" 0
.
.SS "BLOCK INVALID SEARCH DOMAIN COMPLETIONS"
Imagine you run \fBexample\.com\fR with a datacenter \fBdc1\.example\.com\fR\. The datacenter domain is part of the DNS search domain\. However \fBsomething\.example\.com\.dc1\.example\.com\fR would indicates a fully qualified domain name (\fBsomething\.example\.com\fR) that inadvertely has the default domain or search path (\fBdc1\.example\.com\fR) added\.
.
.IP "" 4
.
.nf
\&\. {
proxy \. 8\.8\.8\.8
template IN ANY example\.com\.dc1\.example\.com {
rcode NXDOMAIN
answer "{{ \.Zone }} 60 IN SOA a\.{{ \.Zone }} b\.{{ \.Zone }} (1 60 60 60 60)"
}
}
.
.fi
.
.IP "" 0
.
.P
A more verbose regex based equivalent would be
.
.IP "" 4
.
.nf
\&\. {
proxy \. 8\.8\.8\.8
template IN ANY example\.com {
match "(example\.com\.dc1\.example\.com)$"
rcode NXDOMAIN
answer "{{ index \.Match 1 }} 60 IN SOA a\.{{ index \.Match 1 }} b\.{{ index \.Match 1 }} (1 60 60 60 60)"
fallthrough
}
}
.
.fi
.
.IP "" 0
.
.P
The regex based version can do more complex matching/templating while zone based templating is easier to read and use\.
.
.SS "RESOLVE A/PTR FOR \.EXAMPLE"
.
.nf
\&\. {
proxy \. 8\.8\.8\.8
# ip\-a\-b\-c\-d\.example\.com A a\.b\.c\.d
template IN A example {
match (^|[\.])ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]example[\.]$
answer "{{ \.Name }} 60 IN A 10\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
fallthrough
}
# d\.c\.b\.a\.in\-addr\.arpa PTR ip\-a\-b\-c\-d\.example
template IN PTR 10\.in\-addr\.arpa\. {
match ^(?P<d>[0\-9]*)[\.](?P<c>[0\-9]*)[\.](?P<b>[0\-9]*)[\.]10[\.]in\-addr[\.]arpa[\.]$
answer "{{ \.Name }} 60 IN PTR ip\-10\-{{ \.Group\.b }}\-{{ \.Group\.c }}\-{{ \.Group\.d }}\.example\.com\."
}
}
.
.fi
.
.P
An IPv4 address consists of 4 bytes, \fBa\.b\.c\.d\fR\. Named groups make it less error prone to reverse the ip in the PTR case\. Try to use named groups to explain what your regex and template are doing\.
.
.P
Note that the A record is actually a wildcard, any subdomain of the ip will resolve to the ip\.
.
.P
Having templates to map certain PTR/A pairs is a common pattern\.
.
.P
Fallthrough is needed for mixed domains where only some responses are templated\.
.
.SS "RESOLVE MULTIPLE IP PATTERNS"
.
.nf
\&\. {
proxy \. 8\.8\.8\.8
template IN A example {
match "^ip\-(?P<a>10)\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]dc[\.]example[\.]$"
match "^(?P<a>[0\-9]*)[\.](?P<b>[0\-9]*)[\.](?P<c>[0\-9]*)[\.](?P<d>[0\-9]*)[\.]ext[\.]example[\.]$"
answer "{{ \.Name }} 60 IN A {{ \.Group\.a}}\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
fallthrough
}
}
.
.fi
.
.P
Named capture groups can be used to template one response for multiple patterns\.
.
.SS "RESOLVE A AND MX RECORDS FOR IP TEMPLATES IN \.EXAMPLE"
.
.nf
\&\. {
proxy \. 8\.8\.8\.8
template IN A example {
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]example[\.]$
answer "{{ \.Name }} 60 IN A 10\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
fallthrough
}
template IN MX example {
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]example[\.]$
answer "{{ \.Name }} 60 IN MX 10 {{ \.Name }}"
additional "{{ \.Name }} 60 IN A 10\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
fallthrough
}
}
.
.fi
.
.SS "ADDING AUTHORITATIVE NAMESERVERS TO THE RESPONSE"
.
.nf
\&\. {
proxy \. 8\.8\.8\.8
template IN A example {
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]example[\.]$
answer "{{ \.Name }} 60 IN A 10\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
authority "example\. 60 IN NS ns0\.example\."
authority "example\. 60 IN NS ns1\.example\."
additional "ns0\.example\. 60 IN A 203\.0\.113\.8"
additional "ns1\.example\. 60 IN A 198\.51\.100\.8"
fallthrough
}
template IN MX example {
match ^ip\-10\-(?P<b>[0\-9]*)\-(?P<c>[0\-9]*)\-(?P<d>[0\-9]*)[\.]example[\.]$
answer "{{ \.Name }} 60 IN MX 10 {{ \.Name }}"
additional "{{ \.Name }} 60 IN A 10\.{{ \.Group\.b }}\.{{ \.Group\.c }}\.{{ \.Group\.d }}"
authority "example\. 60 IN NS ns0\.example\."
authority "example\. 60 IN NS ns1\.example\."
additional "ns0\.example\. 60 IN A 203\.0\.113\.8"
additional "ns1\.example\. 60 IN A 198\.51\.100\.8"
fallthrough
}
}
.
.fi
.
.SH "ALSO SEE"
.
.IP "\(bu" 4
Go regexp \fIhttps://golang\.org/pkg/regexp/\fR for details about the regex implementation
.
.IP "\(bu" 4
RE2 syntax reference \fIhttps://github\.com/google/re2/wiki/Syntax\fR for details about the regex syntax
.
.IP "\(bu" 4
RFC\-1034 \fIhttps://tools\.ietf\.org/html/rfc1034#section\-3\.6\.1\fR and RFC 1035 \fIhttps://tools\.ietf\.org/html/rfc1035#section\-5\fR for the resource record format
.
.IP "\(bu" 4
Go template \fIhttps://golang\.org/pkg/text/template/\fR for the template language reference
.
.IP "" 0
.
.SH "BUGS"
CoreDNS supports caddyfile environment variables \fIhttps://caddyserver\.com/docs/caddyfile#env\fR with notion of \fB{$ENV_VAR}\fR\. This parser feature will break Go template variables \fIhttps://golang\.org/pkg/text/template/#hdr\-Variables\fR notations like\fB{{$variable}}\fR\. The equivalent notation \fB{{ $variable }}\fR will work\. Try to avoid Go template variables in the context of this plugin\.

65
debian/man/coredns-tls.7 vendored
View file

@ -1,65 +0,0 @@
.\" 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\.

134
debian/man/coredns-trace.7 vendored
View file

@ -1,134 +0,0 @@
.\" 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

71
debian/man/coredns-whoami.7 vendored
View file

@ -1,71 +0,0 @@
.\" 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

59
debian/man/coredns.1 vendored
View file

@ -1,59 +0,0 @@
.\" 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(5) corendns\-debug(7) corendns\-dnssec(7) corendns\-health(7) corendns\-log(7) corendns\-file(7) corendns\-nsid(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\-template(7) corendns\-proxy(7) corendns\-autopath(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)\.

31
debian/man/corefile.5 vendored
View file

@ -1,31 +0,0 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "COREFILE" "5" "January 2018" "CoreDNS" "CoreDNS"
.
.SH "NAME"
\fBcorefile\fR
.
.SH "NAME"
\fIcorefile\fR \- configuration file for CoreDNS
.
.SH "DESCRIPTION"
A \fBcorefile\fR
.
.P
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:
.
.SH "AUTHORS"
CoreDNS Authors\.
.
.SH "COPYRIGHT"
Apache License 2\.0
.
.SH "SEE ALSO"
Corefile(5) @@PLUGINS@@\.

8
debian/rules vendored
View file

@ -10,6 +10,7 @@ DEB_HOST_ARCH := $(DEB_TARGET_ARCH)
DISTRIBUTION := $(shell lsb_release -sr)
PACKAGEVERSION := $(VERSION)-0~$(DISTRIBUTION)0
TARBALL := coredns_$(VERSION)_linux_$(DEB_TARGET_ARCH).tgz
VTARBALL := v$(VERSION).tar.gz
# Debian calls it armhf, we call it arm.
ifeq ($(DEB_TARGET_ARCH),armhf)
@ -17,6 +18,7 @@ ifeq ($(DEB_TARGET_ARCH),armhf)
endif
URL := https://github.com/coredns/coredns/releases/download/v$(VERSION)/$(TARBALL)
SRC := https://github.com/coredns/coredns/archive/v$(VERSION).tar.gz
%:
dh_clean
@ -30,9 +32,13 @@ override_dh_auto_clean:
override_dh_auto_test:
override_dh_auto_build:
override_dh_auto_install:
curl -L $(URL) -o $(TARBALL)
if [ ! -e $(TARBALL) ]; then curl -L $(URL) -o $(TARBALL); fi
if [ ! -e $(VTARBALL) ]; then curl -L $(SRC) -o $(VTARBALL); fi
mkdir -p debian/coredns/usr/bin debian/coredns/etc/coredns
mkdir -p debian/man v$(VERSION)
tar -xf $(TARBALL) -C debian/coredns/usr/bin
tar -xf $(VTARBALL) -C v$(VERSION)
cp v$(VERSION)/coredns-$(VERSION)/man/* debian/man/
cp debian/Corefile debian/coredns/etc/coredns/Corefile
override_dh_gencontrol: