doc update: run Makefile.doc ()

Add the new plugins ones: clouddns and sign. Remove federation from it.

Signed-off-by: Miek Gieben <miek@miek.nl>
This commit is contained in:
Miek Gieben 2019-08-30 15:58:25 +01:00 committed by GitHub
parent c466003a94
commit 25d85338e4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
39 changed files with 436 additions and 156 deletions

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-ANY" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-ANY" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-AUTO" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-AUTO" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-AUTOPATH" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-AUTOPATH" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-BIND" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-BIND" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-CACHE" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-CACHE" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-CANCEL" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-CANCEL" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-CHAOS" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-CHAOS" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
@ -8,7 +8,7 @@
.SH "DESCRIPTION"
.PP
This is useful for retrieving version or author information from the server by querying a TXT record
for a special domainname in the CH class.
for a special domain name in the CH class.
.SH "SYNTAX"
.PP

100
man/coredns-clouddns.7 Normal file
View file

@ -0,0 +1,100 @@
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-CLOUDDNS" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
\fIclouddns\fP - enables serving zone data from GCP Cloud DNS.
.SH "DESCRIPTION"
.PP
The \fIclouddns\fP plugin is useful for serving zones from resource record
sets in GCP Cloud DNS. This plugin supports all Google Cloud DNS
records
\[la]https://cloud.google.com/dns/docs/overview#supported_dns_record_types\[ra]. This plugin can
be used when CoreDNS is deployed on GCP or elsewhere. Note that this plugin accesses the resource
records through the Google Cloud API. For records in a privately hosted zone, it is not necessary to
place CoreDNS and this plugin in the associated VPC network. In fact the private hosted zone could
be created without any associated VPC and this plugin could still access the resource records under
the hosted zone.
.SH "SYNTAX"
.PP
.RS
.nf
clouddns [ZONE:PROJECT\_ID:HOSTED\_ZONE\_NAME...] {
credentials [FILENAME]
fallthrough [ZONES...]
}
.fi
.RE
.IP \(bu 4
\fBZONE\fP the name of the domain to be accessed. When there are multiple zones with overlapping
domains (private vs. public hosted zone), CoreDNS does the lookup in the given order here.
Therefore, for a non-existing resource record, SOA response will be from the rightmost zone.
.IP \(bu 4
\fBPROJECT_ID\fP the project ID of the Google Cloud project.
.IP \(bu 4
\fBHOSTED\fIZONE\fPNAME\fP the name of the hosted zone that contains the resource record sets to be
accessed.
.IP \(bu 4
\fB\fCcredentials\fR is used for reading the credential file.
.IP \(bu 4
\fBFILENAME\fP GCP credentials file path (normally a .json file).
.IP \(bu 4
\fB\fCfallthrough\fR If zone matches and no record can be generated, pass request to the next plugin.
If \fB[ZONES...]\fP is omitted, then fallthrough happens for all zones for which the plugin is
authoritative. If specific zones are listed (for example \fB\fCin-addr.arpa\fR and \fB\fCip6.arpa\fR), then
only queries for those zones will be subject to fallthrough.
.IP \(bu 4
\fBZONES\fP zones it should be authoritative for. If empty, the zones from the configuration block
.SH "EXAMPLES"
.PP
Enable clouddns with implicit GCP credentials and resolve CNAMEs via 10.0.0.1:
.PP
.RS
.nf
\&. {
clouddns example.org.:gcp\-example\-project:example\-zone
forward . 10.0.0.1
}
.fi
.RE
.PP
Enable clouddns with fallthrough:
.PP
.RS
.nf
\&. {
clouddns example.org.:gcp\-example\-project:example\-zone clouddns example.com.:gcp\-example\-project:example\-zone\-2 {
fallthrough example.gov.
}
}
.fi
.RE
.PP
Enable clouddns with multiple hosted zones with the same domain:
.PP
.RS
.nf
\&. {
clouddns example.org.:gcp\-example\-project:example\-zone example.com.:gcp\-example\-project:other\-example\-zone
}
.fi
.RE

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-DEBUG" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-DEBUG" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-DNSSEC" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-DNSSEC" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-DNSTAP" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-DNSTAP" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-ERRATIC" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-ERRATIC" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-ERRORS" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-ERRORS" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,20 +1,25 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-ETCD" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-ETCD" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
\fIetcd\fP - enables reading zone data from an etcd version 3 instance.
\fIetcd\fP - enable SkyDNS service discovery from etcd.
.SH "DESCRIPTION"
.PP
The \fIetcd\fP plugin implements the (older) SkyDNS service discovery service. It is \fInot\fP suitable as
a generic DNS zone data plugin. Only a subset of DNS record types are implemented, and subdomains
and delegations are not handled at all.
.PP
The data in etcd instance has to be encoded as
a message
\[la]https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26\[ra]
like SkyDNS
\[la]https://github.com/skynetservices/skydns\[ra]. It should also work just like SkyDNS.
\[la]https://github.com/skynetservices/skydns\[ra]. It works just like SkyDNS.
.PP
The etcd plugin makes extensive use of the forward plugin to forward and query other servers in the
The etcd plugin makes extensive use of the \fIforward\fP plugin to forward and query other servers in the
network.
.SH "SYNTAX"
@ -28,7 +33,7 @@ etcd [ZONES...]
.RE
.IP \(bu 4
\fBZONES\fP zones etcd should be authoritative for.
\fBZONES\fP zones \fIetcd\fP should be authoritative for.
.PP
@ -86,23 +91,23 @@ is needed.
.SH "SPECIAL BEHAVIOUR"
.PP
CoreDNS etcd plugin leverages directory structure to look for related entries. For example an entry \fB\fC/skydns/test/skydns/mx\fR would have entries like \fB\fC/skydns/test/skydns/mx/a\fR, \fB\fC/skydns/test/skydns/mx/b\fR and so on. Similarly a directory \fB\fC/skydns/test/skydns/mx1\fR will have all \fB\fCmx1\fR entries.
The \fIetcd\fP plugin leverages directory structure to look for related entries. For example
an entry \fB\fC/skydns/test/skydns/mx\fR would have entries like \fB\fC/skydns/test/skydns/mx/a\fR,
\fB\fC/skydns/test/skydns/mx/b\fR and so on. Similarly a directory \fB\fC/skydns/test/skydns/mx1\fR will have all
\fB\fCmx1\fR entries.
.PP
With etcd3, support for hierarchical keys are dropped
\[la]https://coreos.com/etcd/docs/latest/learning/api.html\[ra]. This means there are no directories but only flat keys with prefixes in etcd3. To accommodate lookups, etcdv3 plugin now does a lookup on prefix \fB\fC/skydns/test/skydns/mx/\fR to search for entries like \fB\fC/skydns/test/skydns/mx/a\fR etc, and if there is nothing found on \fB\fC/skydns/test/skydns/mx/\fR, it looks for \fB\fC/skydns/test/skydns/mx\fR to find entries like \fB\fC/skydns/test/skydns/mx1\fR.
With etcd3, support for hierarchical keys are
dropped
\[la]https://coreos.com/etcd/docs/latest/learning/api.html\[ra]. This means there are no directories
but only flat keys with prefixes in etcd3. To accommodate lookups, etcdv3 plugin now does a lookup
on prefix \fB\fC/skydns/test/skydns/mx/\fR to search for entries like \fB\fC/skydns/test/skydns/mx/a\fR etc, and
if there is nothing found on \fB\fC/skydns/test/skydns/mx/\fR, it looks for \fB\fC/skydns/test/skydns/mx\fR to
find entries like \fB\fC/skydns/test/skydns/mx1\fR.
.PP
This causes two lookups from CoreDNS to etcdv3 in certain cases.
.SH "MIGRATION TO "\fB\fCetcdv3\fR" API"
.PP
With CoreDNS release \fB\fC1.2.0\fR, you'll need to migrate existing CoreDNS related data (if any) on your etcd server to etcdv3 API. This is because with \fB\fCetcdv3\fR support, CoreDNS can't see the data stored to an etcd server using \fB\fCetcdv2\fR API.
.PP
Refer this blog by CoreOS team
\[la]https://coreos.com/blog/migrating-applications-etcd-v3.html\[ra] to migrate to etcdv3 API.
.SH "EXAMPLES"
.PP
This is the default SkyDNS setup, with everything specified in full:
@ -159,12 +164,19 @@ etcd skydns.local {
.RE
.PP
Before getting started with these examples, please setup \fB\fCetcdctl\fR (with \fB\fCetcdv3\fR API) as explained here
\[la]https://coreos.com/etcd/docs/latest/dev-guide/interacting_v3.html\[ra]. This will help you to put sample keys in your etcd server.
Before getting started with these examples, please setup \fB\fCetcdctl\fR (with \fB\fCetcdv3\fR API) as explained
here
\[la]https://coreos.com/etcd/docs/latest/dev-guide/interacting_v3.html\[ra]. This will help you to put
sample keys in your etcd server.
.PP
If you prefer, you can use \fB\fCcurl\fR to populate the \fB\fCetcd\fR server, but with \fB\fCcurl\fR the endpoint URL depends on the version of \fB\fCetcd\fR. For instance, \fB\fCetcd v3.2\fR or before uses only [CLIENT-URL]/v3alpha/* while \fB\fCetcd v3.5\fR or later uses [CLIENT-URL]/v3/* . Also, Key and Value must be base64 encoded in the JSON payload. With \fB\fCetcdctl\fR these details are automatically taken care off. You can check this document
\[la]https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/api_grpc_gateway.md#notes\[ra] for details.
If you prefer, you can use \fB\fCcurl\fR to populate the \fB\fCetcd\fR server, but with \fB\fCcurl\fR the
endpoint URL depends on the version of \fB\fCetcd\fR. For instance, \fB\fCetcd v3.2\fR or before uses only
[CLIENT-URL]/v3alpha/* while \fB\fCetcd v3.5\fR or later uses [CLIENT-URL]/v3/* . Also, Key and Value must
be base64 encoded in the JSON payload. With \fB\fCetcdctl\fR these details are automatically taken care
of. You can check this document
\[la]https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/api_grpc_gateway.md#notes\[ra]
for details.
.SS "REVERSE ZONES"
.PP
@ -210,7 +222,9 @@ reverse.skydns.local.
.SS "ZONE NAME AS A RECORD"
.PP
The zone name itself can be used as A record. This behavior can be achieved by writing special entries to the ETCD path of your zone. If your zone is named \fB\fCskydns.local\fR for example, you can create an \fB\fCA\fR record for this zone as follows:
The zone name itself can be used as an \fB\fCA\fR record. This behavior can be achieved by writing special
entries to the ETCD path of your zone. If your zone is named \fB\fCskydns.local\fR for example, you can
create an \fB\fCA\fR record for this zone as follows:
.PP
.RS

View file

@ -1,54 +0,0 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-FEDERATION" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
\fIfederation\fP - enables federated queries to be resolved via the kubernetes plugin.
.SH "DESCRIPTION"
.PP
Enabling this plugin allows
Federated
\[la]https://kubernetes.io/docs/tasks/federation/federation-service-discovery/\[ra] queries to be
resolved via the kubernetes plugin.
.PP
Enabling \fIfederation\fP without also having \fIkubernetes\fP is a noop.
.SH "SYNTAX"
.PP
.RS
.nf
federation [ZONES...] {
NAME DOMAIN
}
.fi
.RE
.IP \(bu 4
Each \fBNAME\fP and \fBDOMAIN\fP defines federation membership. One entry for each. A duplicate
\fBNAME\fP will silently overwrite any previous value.
.SH "EXAMPLES"
.PP
Here we handle all service requests in the \fB\fCprod\fR and \fB\fCstage\fR federations.
.PP
.RS
.nf
\&. {
kubernetes cluster.local
federation cluster.local {
prod prod.feddomain.com
staging staging.feddomain.com
}
forward . 192.168.1.12
}
.fi
.RE

View file

@ -1,4 +1,4 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-FILE" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-FORWARD" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-FORWARD" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-GRPC" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-GRPC" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-HEALTH" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-HEALTH" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
@ -65,7 +65,7 @@ net {
.RE
.PP
Doing this is supported but both endponts ":8080" and ":8081" will export the exact same health.
Doing this is supported but both endpoints ":8080" and ":8081" will export the exact same health.
.SH "METRICS"
.PP

View file

@ -1,4 +1,4 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-HOSTS" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-IMPORT" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-IMPORT" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-K8S_EXTERNAL" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-K8S_EXTERNAL" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
@ -12,11 +12,11 @@ service. This plugin is only useful if the \fIkubernetes\fP plugin is also loade
.PP
The plugin uses an external zone to resolve in-cluster IP addresses. It only handles queries for A,
AAAA and SRV records, all others result in NODATA responses. To make it a proper DNS zone it handles
AAAA and SRV records; all others result in NODATA responses. To make it a proper DNS zone, it handles
SOA and NS queries for the apex of the zone.
.PP
By default the apex of the zone will look like (assuming the zone used is \fB\fCexample.org\fR):
By default the apex of the zone will look like the following (assuming the zone used is \fB\fCexample.org\fR):
.PP
.RS
@ -38,12 +38,12 @@ ns1.dns.example.org. 5 IN AAAA ....
.RE
.PP
Note we use the \fB\fCdns\fR subdomain to place the records the DNS needs (see the \fB\fCapex\fR directive). Also
Note that we use the \fB\fCdns\fR subdomain for the records DNS needs (see the \fB\fCapex\fR directive). Also
note the SOA's serial number is static. The IP addresses of the nameserver records are those of the
CoreDNS service.
.PP
The \fIk8s_external\fP plugin handles the subdomain \fB\fCdns\fR and the apex of the zone by itself, all other
The \fIk8s_external\fP plugin handles the subdomain \fB\fCdns\fR and the apex of the zone itself; all other
queries are resolved to addresses in the cluster.
.SH "SYNTAX"
@ -61,7 +61,7 @@ k8s\_external [ZONE...]
.PP
If you want to change the apex domain or use a different TTL for the return records you can use
If you want to change the apex domain or use a different TTL for the returned records you can use
this extended syntax.
.PP
@ -77,13 +77,13 @@ k8s\_external [ZONE...] {
.RE
.IP \(bu 4
\fBAPEX\fP is the name (DNS label) to use the apex records, defaults to \fB\fCdns\fR.
\fBAPEX\fP is the name (DNS label) to use for the apex records; it defaults to \fB\fCdns\fR.
.IP \(bu 4
\fB\fCttl\fR allows you to set a custom \fBTTL\fP for responses. The default is 5 (seconds).
.PP
Enable names under \fB\fCexample.org\fR to be resolved to in cluster DNS addresses.
Enable names under \fB\fCexample.org\fR to be resolved to in-cluster DNS addresses.
.PP
.RS
@ -98,7 +98,7 @@ Enable names under \fB\fCexample.org\fR to be resolved to in cluster DNS address
.RE
.PP
With the Corefile above, the following Service will get an \fB\fCA\fR record for \fB\fCtest.default.example.org\fR with IP address \fB\fC192.168.200.123\fR.
With the Corefile above, the following Service will get an \fB\fCA\fR record for \fB\fCtest.default.example.org\fR with the IP address \fB\fC192.168.200.123\fR.
.PP
.RS

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-LOADBALANCE" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-LOADBALANCE" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-LOG" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-LOG" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-LOOP" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-LOOP" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-METADATA" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-METADATA" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
@ -10,7 +10,7 @@
By enabling \fImetadata\fP any plugin that implements metadata.Provider
interface
\[la]https://godoc.org/github.com/coredns/coredns/plugin/metadata#Provider\[ra] will be called for
each DNS query, at beginning of the process for that query, in order to add it's own meta data to
each DNS query, at beginning of the process for that query, in order to add its own meta data to
context.
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-METRICS" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-METRICS" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-NSID" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-NSID" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-PPROF" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-PPROF" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-READY" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-READY" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
@ -15,7 +15,7 @@ will not be queried again.
.PP
Each Server Block that enables the \fIready\fP plugin will have the plugins \fIin that server block\fP
report readiness into the /ready endpoint that runs on the same port. This also means that the
\fIsame\fP plugin with different configurations (in potentialy \fIdifferent\fP Server Blocks) will have
\fIsame\fP plugin with different configurations (in potentially \fIdifferent\fP Server Blocks) will have
their readiness reported as the union of their respective readinesses.
.SH "SYNTAX"

View file

@ -1,4 +1,4 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-RELOAD" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
@ -125,7 +125,7 @@ fail loading the new Corefile, abort and keep using the old process
.PP
After the aborted attempt to reload we are left with the old processes running, but the listener is
closed in step 1; so the health endpoint is broken. The same can hopen in the prometheus metrics plugin.
closed in step 1; so the health endpoint is broken. The same can happen in the prometheus metrics plugin.
.PP
In general be careful with assigning new port and expecting reload to work fully.

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-REWRITE" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-REWRITE" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-ROOT" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-ROOT" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-SECONDARY" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-SECONDARY" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

220
man/coredns-sign.7 Normal file
View file

@ -0,0 +1,220 @@
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-SIGN" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP
\fIsign\fP - add DNSSEC records to zone files.
.SH "DESCRIPTION"
.PP
The \fIsign\fP plugin is used to sign (see RFC 6781) zones. In this process DNSSEC resource records are
added. The signatures that sign the resource records sets have an expiration date, this means the
signing process must be repeated before this expiration data is reached. Otherwise the zone's data
will go BAD (RFC 4035, Section 5.5). The \fIsign\fP plugin takes care of this. \fISign\fP works, but has
a couple of limitations, see the "Bugs" section.
.PP
Only NSEC is supported, \fIsign\fP does not support NSEC3.
.PP
\fISign\fP works in conjunction with the \fIfile\fP and \fIauto\fP plugins; this plugin \fBsigns\fP the zones
files, \fIauto\fP and \fIfile\fP \fBserve\fP the zones \fIdata\fP.
.PP
For this plugin to work at least one Common Signing Key, (see coredns-keygen(1)) is needed. This key
(or keys) will be used to sign the entire zone. \fISign\fP does not support the ZSK/KSK split, nor will
it do key or algorithm rollovers - it just signs.
.PP
\fISign\fP will:
.IP \(bu 4
(Re)-sign the zone with the CSK(s) when:
.RS
.IP \(en 4
the last time it was signed is more than a 6 days ago. Each zone will have some jitter
applied to the inception date.
.IP \(en 4
the signature only has 14 days left before expiring.
.RE
Both these dates are only checked on the SOA's signature(s).
.IP \(bu 4
Create signatures that have an inception of -3 hours (minus a jitter between 0 and 18 hours)
and a expiration of +32 days for every given DNSKEY.
.IP \(bu 4
Add or replace \fIall\fP apex CDS/CDNSKEY records with the ones derived from the given keys. For
each key two CDS are created one with SHA1 and another with SHA256.
.IP \(bu 4
Update the SOA's serial number to the \fIUnix epoch\fP of when the signing happens. This will
overwrite \fIany\fP previous serial number.
.PP
Thus there are two ways that dictate when a zone is signed. Normally every 6 days (plus jitter) it
will be resigned. If for some reason we fail this check, the 14 days before expiring kicks in.
.PP
Keys are named (following BIND9): \fB\fCK<name>+<alg>+<id>.key\fR and \fB\fCK<name>+<alg>+<id>.private\fR.
The keys \fBmust not\fP be included in your zone; they will be added by \fIsign\fP. These keys can be
generated with \fB\fCcoredns-keygen\fR or BIND9's \fB\fCdnssec-keygen\fR. You don't have to adhere to this naming
scheme, but then you need to name your keys explicitly, see the \fB\fCkeys file\fR directive.
.PP
A generated zone is written out in a file named \fB\fCdb.<name>.signed\fR in the directory named by the
\fB\fCdirectory\fR directive (which defaults to \fB\fC/var/lib/coredns\fR).
.SH "SYNTAX"
.PP
.RS
.nf
sign DBFILE [ZONES...] {
key file|directory KEY...|DIR...
directory DIR
}
.fi
.RE
.IP \(bu 4
\fBDBFILE\fP the zone database file to read and parse. If the path is relative, the path from the
\fIroot\fP directive will be prepended to it.
.IP \(bu 4
\fBZONES\fP zones it should be sign for. If empty, the zones from the configuration block are
used.
.IP \(bu 4
\fB\fCkey\fR specifies the key(s) (there can be multiple) to sign the zone. If \fB\fCfile\fR is
used the \fBKEY\fP's filenames are used as is. If \fB\fCdirectory\fR is used, \fIsign\fP will look in \fBDIR\fP
for \fB\fCK<name>+<alg>+<id>\fR files. Any metadata in these files (Activate, Publish, etc.) is
\fIignored\fP. These keys must also be Key Signing Keys (KSK).
.IP \(bu 4
\fB\fCdirectory\fR specifies the \fBDIR\fP where CoreDNS should save zones that have been signed.
If not given this defaults to \fB\fC/var/lib/coredns\fR. The zones are saved under the name
\fB\fCdb.<name>.signed\fR. If the path is relative the path from the \fIroot\fP directive will be prepended
to it.
.PP
Keys can be generated with \fB\fCcoredns-keygen\fR, to create one for use in the \fIsign\fP plugin, use:
\fB\fCcoredns-keygen example.org\fR or \fB\fCdnssec-keygen -a ECDSAP256SHA256 -f KSK example.org\fR.
.SH "EXAMPLES"
.PP
Sign the \fB\fCexample.org\fR zone contained in the file \fB\fCdb.example.org\fR and write the result to
\fB\fC./db.example.org.signed\fR to let the \fIfile\fP plugin pick it up and serve it. The keys used
are read from \fB\fC/etc/coredns/keys/Kexample.org.key\fR and \fB\fC/etc/coredns/keys/Kexample.org.private\fR.
.PP
.RS
.nf
example.org {
file db.example.org.signed
sign db.example.org {
key file /etc/coredns/keys/Kexample.org
directory .
}
}
.fi
.RE
.PP
Running this leads to the following log output (note the timers in this example have been set to
shorter intervals).
.PP
.RS
.nf
[WARNING] plugin/file: Failed to open "open /tmp/db.example.org.signed: no such file or directory": trying again in 1m0s
[INFO] plugin/sign: Signing "example.org." because open /tmp/db.example.org.signed: no such file or directory
[INFO] plugin/sign: Successfully signed zone "example.org." in "/tmp/db.example.org.signed" with key tags "59725" and 1564766865 SOA serial, elapsed 9.357933ms, next: 2019\-08\-02T22:27:45.270Z
[INFO] plugin/file: Successfully reloaded zone "example.org." in "/tmp/db.example.org.signed" with serial 1564766865
.fi
.RE
.PP
Or use a single zone file for \fImultiple\fP zones, note that the \fBZONES\fP are repeated for both plugins.
Also note this outputs \fImultiple\fP signed output files. Here we use the default output directory
\fB\fC/var/lib/coredns\fR.
.PP
.RS
.nf
\&. {
file /var/lib/coredns/db.example.org.signed example.org
file /var/lib/coredns/db.example.net.signed example.net
sign db.example.org example.org example.net {
key directory /etc/coredns/keys
}
}
.fi
.RE
.PP
This is the same configuration, but the zones are put in the server block, but note that you still
need to specify what file is served for what zone in the \fIfile\fP plugin:
.PP
.RS
.nf
example.org example.net {
file var/lib/coredns/db.example.org.signed example.org
file var/lib/coredns/db.example.net.signed example.net
sign db.example.org {
key directory /etc/coredns/keys
}
}
.fi
.RE
.PP
Be careful to fully list the origins you want to sign, if you don't:
.PP
.RS
.nf
example.org example.net {
sign plugin/sign/testdata/db.example.org miek.org {
key file /etc/coredns/keys/Kexample.org
}
}
.fi
.RE
.PP
This will lead to \fB\fCdb.example.org\fR be signed \fItwice\fP, as this entire section is parsed twice because
you have specified the origins \fB\fCexample.org\fR and \fB\fCexample.net\fR in the server block.
.PP
Forcibly resigning a zone can be accomplished by removing the signed zone file (CoreDNS will keep on
serving it from memory), and sending SIGUSR1 to the process to make it reload and resign the zone
file.
.SH "ALSO SEE"
.PP
The DNSSEC RFCs: RFC 4033, RFC 4034 and RFC 4035. And the BCP on DNSSEC, RFC 6781. Further more the
manual pages coredns-keygen(1) and dnssec-keygen(8). And the \fIfile\fP plugin's documentation.
.PP
Coredns-keygen can be found at https://github.com/coredns/coredns-utils
\[la]https://github.com/coredns/coredns-utils\[ra] in the coredns-keygen directory.
.SH "BUGS"
.PP
\fB\fCkeys directory\fR is not implemented. Glue records are currently signed, and no DS records are added
for child zones.

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-TEMPLATE" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-TEMPLATE" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-TLS" 7 "July 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-TLS" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-TRACE" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-TRACE" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP

View file

@ -1,5 +1,5 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-WHOAMI" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-WHOAMI" 7 "August 2019" "CoreDNS" "CoreDNS Plugins"
.SH "NAME"
.PP