coredns-log

title: coredns-log(7)

text:
# coredns-log(7)

## NAME
log - enables query logging to standard output.

## DESCRIPTION
By just using log you dump all queries (and parts for the reply) on standard output. Options exist to tweak the output a little. Note that for busy servers logging will incur a performance hit.

Enabling or disabling the log plugin only affects the query logging, any other logging from CoreDNS will show up regardless.

## SYNTAX

```
log
```

With no arguments, a query log entry is written to stdout in the common log format for all requests. Or if you want/need slightly more control:

```
log [NAMES...] [FORMAT]
```

- NAMES is the name list to match in order to be logged

- FORMAT is the log format to use (default is Common Log Format), {common} is used as a shortcut for the Common Log Format. You can also use {combined} for a format that adds the query opcode {>opcode} to the Common Log Format.

You can further specify the classes of responses that get logged:

```
log [NAMES...] [FORMAT] {

    class CLASSES...
}
```

•

CLASSES is a space-separated list of classes of responses that should be logged

The classes of responses have the following meaning:

- success: successful response

- denial: either NXDOMAIN or nodata responses (Name exists, type does not). A nodata response sets the return code to NOERROR.

- error: SERVFAIL, NOTIMP, REFUSED, etc. Anything that indicates the remote server is not willing to resolve the request.

- all: the default - nothing is specified. Using of this class means that all messages will be logged whatever we mix together with "all".

If no class is specified, it defaults to all.

## LOG FORMAT
You can specify a custom log format with any placeholder values. Log supports both request and response placeholders.

The following place holders are supported:

- {type}: qtype of the request

- {name}: qname of the request

- {class}: qclass of the request

- {proto}: protocol used (tcp or udp)

- {remote}: client's IP address, for IPv6 addresses these are enclosed in brackets: [::1]

- {local}: server's IP address, for IPv6 addresses these are enclosed in brackets: [::1]

- {size}: request size in bytes

- {port}: client's port

- {duration}: response duration

- {rcode}: response RCODE

- {rsize}: raw (uncompressed), response size (a client may receive a smaller response)

- {>rflags}: response flags, each set flag will be displayed, e.g. "aa, tc". This includes the qr bit as well

- {>bufsize}: the EDNS0 buffer size advertised in the query

- {>do}: is the EDNS0 DO (DNSSEC OK) bit set in the query

- {>id}: query ID

- {>opcode}: query OPCODE

- {common}: the default Common Log Format.

- {combined}: the Common Log Format with the query opcode.

- {/LABEL}: any metadata label is accepted as a place holder if it is enclosed between {/ and }, the place holder will be replaced by the corresponding metadata value or the default value - if label is not defined. See the metadata plugin for more information.

The default Common Log Format is:

```
`{remote}:{port} - {>id} "{type} {class} {name} {proto} {size} {>do} {>bufsize}" {rcode} {>rflags} {rsize} {duration}`
```

Each of these logs will be outputted with log.Infof, so a typical example looks like this:

```
[INFO] [::1]:50759 - 29008 "A IN example.org. udp 41 false 4096" NOERROR qr,rd,ra,ad 68 0.037990251s
~~~~
## Examples
Log all requests to stdout
~~~ corefile
. {

    log

    whoami
}
```

Custom log format, for all zones (.)

```
. {

    log . "{proto} Request: {name} {type} {>id}"
}
```

Only log denials (NXDOMAIN and nodata) for example.org (and below)

```
. {

    log example.org {

        class denial

    }
}
```

Log all queries which were not resolved successfully in the Combined Log Format.

```
. {

    log . {combined} {

        class denial error

    }
}
```

Log all queries on which we did not get errors

```
. {

    log . {

        class denial success

    }
}
```

Also the multiple statements can be OR-ed, for example, we can rewrite the above case as following:

```
. {

    log . {

        class denial

        class success

    }
}
```


coredns-loop

package: coredns

title: coredns-loop(7)

text:
# coredns-loop(7)

## NAME
loop - detects simple forwarding loops and halts the server.

## DESCRIPTION
The loop plugin will send a random probe query to ourselves and will then keep track of how many times we see it. If we see it more than twice, we assume CoreDNS has seen a forwarding loop and we halt the process.

The plugin will try to send the query for up to 30 seconds. This is done to give CoreDNS enough time to start up. Once a query has been successfully sent, loop disables itself to prevent a query of death.

The query sent is <random number>.<random number>.zone with type set to HINFO.

## SYNTAX

```
loop
```

## EXAMPLES
Start a server on the default port and load the loop and forward plugins. The forward plugin forwards to it self.

```
. {

    loop

    forward . 127.0.0.1
}
```

After CoreDNS has started it stops the process while logging:

```
plugin/loop: Loop (127.0.0.1:55953 -> :1053) detected for zone ".", see https://coredns.io/plugins/loop#troubleshooting. Query: "HINFO 4547991504243258144.3688648895315093531."
```

## LIMITATIONS
This plugin only attempts to find simple static forwarding loops at start up time. To detect a loop, the following must be true:

- the loop must be present at start up time.

- the loop must occur for the HINFO query type.

## TROUBLESHOOTING
When CoreDNS logs contain the message Loop ... detected ..., this means that the loop detection plugin has detected an infinite forwarding loop in one of the upstream DNS servers. This is a fatal error because operating with an infinite loop will consume memory and CPU until eventual out of memory death by the host.

A forwarding loop is usually caused by:

- Most commonly, CoreDNS forwarding requests directly to itself. e.g. via a loopback address such as 127.0.0.1, ::1 or 127.0.0.53

- Less commonly, CoreDNS forwarding to an upstream server that in turn, forwards requests back to CoreDNS.

To troubleshoot this problem, look in your Corefile for any forwards to the zone in which the loop was detected. Make sure that they are not forwarding to a local address or to another DNS server that is forwarding requests back to CoreDNS. If forward is using a file (e.g. /etc/resolv.conf), make sure that file does not contain local addresses.

### TROUBLESHOOTING LOOPS IN KUBERNETES CLUSTERS
When a CoreDNS Pod deployed in Kubernetes detects a loop, the CoreDNS Pod will start to "CrashLoopBackOff". This is because Kubernetes will try to restart the Pod every time CoreDNS detects the loop and exits.

A common cause of forwarding loops in Kubernetes clusters is an interaction with a local DNS cache on the host node (e.g. systemd-resolved). For example, in certain configurations systemd-resolved will put the loopback address 127.0.0.53 as a nameserver into /etc/resolv.conf. Kubernetes (via kubelet) by default will pass this /etc/resolv.conf file to all Pods using the default dnsPolicy rendering them unable to make DNS lookups (this includes CoreDNS Pods). CoreDNS uses this /etc/resolv.conf as a list of upstreams to forward requests to. Since it contains a loopback address, CoreDNS ends up forwarding requests to itself.

There are many ways to work around this issue, some are listed here:

- Add the following to your kubelet config yaml: resolvConf: <path-to-your-real-resolv-conf-file> (or via command line flag --resolv-conf deprecated in 1.10). Your "real" resolv.conf is the one that contains the actual IPs of your upstream servers, and no local/loopback address. This flag tells kubelet to pass an alternate resolv.conf to Pods. For systems using systemd-resolved, /run/systemd/resolve/resolv.conf is typically the location of the "real" resolv.conf, although this can be different depending on your distribution.

- Disable the local DNS cache on host nodes, and restore /etc/resolv.conf to the original.

- A quick and dirty fix is to edit your Corefile, replacing forward . /etc/resolv.conf with the IP address of your upstream DNS, for example forward . 8.8.8.8. But this only fixes the issue for CoreDNS, kubelet will continue to forward the invalid resolv.conf to all default dnsPolicy Pods, leaving them unable to resolve DNS.


coredns-metadata

title: coredns-metadata(7)

text:
# coredns-metadata(7)

## NAME
metadata - enables a metadata collector.

## DESCRIPTION
By enabling metadata any plugin that implements metadata.Provider interface ⟨https://godoc.org/github.com/coredns/coredns/plugin/metadata#Provider⟩ will be called for each DNS query, at the beginning of the process for that query, in order to add its own metadata to context.

The metadata collected will be available for all plugins, via the Context parameter provided in the ServeDNS function. The package (code) documentation has examples on how to inspect and retrieve metadata a plugin might be interested in.

The metadata is added by setting a label with a value in the context. These labels should be named plugin/NAME, where NAME is something descriptive. The only hard requirement the metadata plugin enforces is that the labels contain a slash. See the documentation for metadata.SetValueFunc.

The value stored is a string. The empty string signals "no metadata". See the documentation for metadata.ValueFunc on how to retrieve this.

## SYNTAX

```
metadata [ZONES... ]
```

•

ZONES zones metadata should be invoked for.

## PLUGINS
metadata.Provider interface needs to be implemented by each plugin willing to provide metadata information for other plugins. It will be called by metadata and gather the information from all plugins in context.

Note: this method should work quickly, because it is called for every request.

## EXAMPLES
The rewrite plugin uses meta data to rewrite requests.

## SEE ALSO
The Provider interface ⟨https://godoc.org/github.com/coredns/coredns/plugin/metadata#Provider⟩ and the package level ⟨https://godoc.org/github.com/coredns/coredns/plugin/metadata⟩ documentation.


coredns-metrics

title: coredns-metrics(7)

text:
# coredns-metrics(7)

## NAME
prometheus - enables Prometheus ⟨https://prometheus.io/⟩ metrics.

## DESCRIPTION
With prometheus you export metrics from CoreDNS and any plugin that has them. The default location for the metrics is localhost:9153. The metrics path is fixed to /metrics. The following metrics are exported:

- coredns_build_info{version, revision, goversion} - info about CoreDNS itself.

- coredns_panics_total{} - total number of panics.

- coredns_dns_requests_total{server, zone, proto, family, type} - total query count.

- coredns_dns_request_duration_seconds{server, zone, type} - duration to process each query.

- coredns_dns_request_size_bytes{server, zone, proto} - size of the request in bytes.

- coredns_dns_do_requests_total{server, zone} - queries that have the DO bit set

- coredns_dns_response_size_bytes{server, zone, proto} - response size in bytes.

- coredns_dns_responses_total{server, zone, rcode} - response per zone and rcode.

- coredns_plugin_enabled{server, zone, name} - indicates whether a plugin is enabled on per server and zone basis.

Each counter has a label zone which is the zonename used for the request/response.

Extra labels used are:

- server is identifying the server responsible for the request. This is a string formatted as the server's listening address: <scheme>://[<bind>]:<port>. I.e. for a "normal" DNS server this is dns://:53. If you are using the bind plugin an IP address is included, e.g.: dns://127.0.0.53:53.

- proto which holds the transport of the response ("udp" or "tcp")

- The address family (family) of the transport (1 = IP (IP version 4), 2 = IP6 (IP version 6)).

- type 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.

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).

This plugin can only be used once per Server Block.

## SYNTAX

```
prometheus [ADDRESS]
```

For each zone that you want to see metrics for.

It optionally takes a bind address to which the metrics are exported; the default listens on localhost:9153. The metrics path is fixed to /metrics.

## EXAMPLES
Use an alternative listening address:

```
. {

    prometheus localhost:9253
}
```

Or via an environment variable (this is supported throughout the Corefile): export PORT=9253, and then:

```
. {

    prometheus localhost:{$PORT}
}
```

## BUGS
When reloading, the Prometheus handler is stopped before the new server instance is started. If that new server fails to start, then the initial server instance is still available and DNS queries still served, but Prometheus handler stays down. Prometheus will not reply HTTP request until a successful reload or a complete restart of CoreDNS. Only the plugins that register as Handler are visible in coredns_plugin_enabled{server, zone, name}. As of today the plugins reload and bind will not be reported.


coredns-minimal

title: coredns-minimal(7)

text:
# coredns-minimal(7)

## NAME
minimal - minimizes size of the DNS response message whenever possible.

## DESCRIPTION
The minimal plugin tries to minimize the size of the response. Depending on the response type it removes resource records from the AUTHORITY and ADDITIONAL sections.

Specifically this plugin looks at successful responses (this excludes negative responses, i.e. nodata or name error). If the successful response isn't a delegation only the RRs in the answer section are written to the client.

## SYNTAX

```
minimal
```

## EXAMPLES
Enable minimal responses:

```
example.org {

    whoami

    forward . 8.8.8.8

    minimal
}
```

## SEE ALSO
BIND 9 Configuration Reference ⟨https://bind9.readthedocs.io/en/latest/reference.html#boolean-options⟩


coredns-nsid

title: coredns-nsid(7)

text:
# coredns-nsid(7)

## NAME
nsid - adds an identifier of this server to each reply.

## DESCRIPTION
This plugin implements RFC 5001 ⟨https://tools.ietf.org/html/rfc5001⟩ 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.

This plugin can only be used once per Server Block.

## SYNTAX

```
nsid [DATA]
```

DATA is the string to use in the nsid record.

If DATA is not given, the host's name is used.

## EXAMPLES
Enable nsid:

```
example.org {

    whoami

    nsid Use The Force
}
```

And now a client with NSID support will see an OPT record with the NSID option:

```
% 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
```

## SEE ALSO
RFC 5001 ⟨https://tools.ietf.org/html/rfc5001⟩


coredns-pprof

title: coredns-pprof(7)

text:
# coredns-pprof(7)

## NAME
pprof - publishes runtime profiling data at endpoints under /debug/pprof.

## DESCRIPTION
You can visit /debug/pprof on your site for an index of the available endpoints. By default it will listen on localhost:6053.

This is a debugging tool. Certain requests (such as collecting execution traces) can be slow. If you use pprof on a live server, consider restricting access or enabling it only temporarily.

This plugin can only be used once per Server Block.

## SYNTAX

```
pprof [ADDRESS]
```

Optionally pprof takes an address; the default is localhost:6053.

An extra option can be set with this extended syntax:

```
pprof [ADDRESS] {

   block [RATE]
}
```

•

block option enables block profiling, RATE defaults to 1. RATE must be a positive value. See Diagnostics, chapter profiling ⟨https://golang.org/doc/diagnostics.html⟩ and runtime.SetBlockProfileRate ⟨https://golang.org/pkg/runtime/#SetBlockProfileRate⟩ for what block profiling entails.

## EXAMPLES
Enable a pprof endpoint:

```
. {

    pprof
}
```

And use the pprof tool to get statistics: go tool pprof http://localhost:6053.

Listen on an alternate address:

```
. {

    pprof 10.9.8.7:6060
}
```

Listen on an all addresses on port 6060, and enable block profiling

```
. {

    pprof :6060 {

       block

    }
}
```

## SEE ALSO
See Go's pprof documentation ⟨https://golang.org/pkg/net/http/pprof/⟩ and Profiling Go Programs ⟨https://blog.golang.org/profiling-go-programs⟩.

See runtime.SetBlockProfileRate ⟨https://golang.org/pkg/runtime/#SetBlockProfileRate⟩ for background on block profiling.


coredns-ready

title: coredns-ready(7)

text:
# coredns-ready(7)

## NAME
ready - enables a readiness check HTTP endpoint.

## DESCRIPTION
By enabling ready an HTTP endpoint on port 8181 will return 200 OK, when all plugins that are able to signal readiness have done so. If some are not ready yet the endpoint will return a 503 with the body containing the list of plugins that are not ready. Once a plugin has signaled it is ready it will not be queried again.

Each Server Block that enables the ready plugin will have the plugins in that server block report readiness into the /ready endpoint that runs on the same port. This also means that the same plugin with different configurations (in potentially different Server Blocks) will have their readiness reported as the union of their respective readinesses.

## SYNTAX

```
ready [ADDRESS]
```

ready optionally takes an address; the default is :8181. The path is fixed to /ready. The readiness endpoint returns a 200 response code and the word "OK" when this server is ready. It returns a 503 otherwise and the list of plugins that are not ready.

## PLUGINS
Any plugin wanting to signal readiness will need to implement the ready.Readiness interface by implementing a method Ready() bool that returns true when the plugin is ready and false otherwise.

## EXAMPLES
Let ready report readiness for both the . and example.org servers (assuming the whois plugin also exports readiness):

```
. {

    ready

    erratic
}
example.org {

    ready

    whoami
}
```

Run ready on a different port.

```
. {

    ready localhost:8091
}
```


coredns-reload

title: coredns-reload(7)

text:
# coredns-reload(7)

## NAME
reload - allows automatic reload of a changed Corefile.

## DESCRIPTION
This plugin allows automatic reload of a changed Corefile. To enable automatic reloading of zone file changes, use the auto plugin.

This plugin periodically checks if the Corefile has changed by reading it and calculating its MD5 checksum. If the file has changed, it reloads CoreDNS with the new Corefile. This eliminates the need to send a SIGHUP or SIGUSR1 after changing the Corefile.

The reloads are graceful - you should not see any loss of service when the reload happens. Even if the new Corefile has an error, CoreDNS will continue to run the old config and an error message will be printed to the log. But see the Bugs section for failure modes.

In some environments (for example, Kubernetes), there may be many CoreDNS instances that started very near the same time and all share a common Corefile. To prevent these all from reloading at the same time, some jitter is added to the reload check interval. This is jitter from the perspective of multiple CoreDNS instances; each instance still checks on a regular interval, but all of these instances will have their reloads spread out across the jitter duration. This isn't strictly necessary given that the reloads are graceful, and can be disabled by setting the jitter to 0s.

Jitter is re-calculated whenever the Corefile is reloaded.

This plugin can only be used once per Server Block.

## SYNTAX

```
reload [INTERVAL] [JITTER]
```

The plugin will check for changes every INTERVAL, subject to +/- the JITTER duration.

•

INTERVAL and JITTER are Golang durations ⟨https://golang.org/pkg/time/#ParseDuration⟩. The default INTERVAL is 30s, default JITTER is 15s, the minimal value for INTERVAL is 2s, and for JITTER it is 1s. If JITTER is more than half of INTERVAL, it will be set to half of INTERVAL

## EXAMPLES
Check with the default intervals:

```
. {

    reload

    erratic
}
```

Check every 10 seconds (jitter is automatically set to 10 / 2 = 5 in this case):

```
. {

    reload 10s

    erratic
}
```

## BUGS
The reload happens without data loss (i.e. DNS queries keep flowing), but there is a corner case where the reload fails, and you loose functionality. Consider the following Corefile:

```
. {

    health :8080

    whoami
}
```

CoreDNS starts and serves health from :8080. Now you change :8080 to :443 not knowing a process is already listening on that port. The process reloads and performs the following steps:

1.

close the listener on 8080

2.

reload and parse the config again

3.

fail to start a new listener on 443

4.

fail loading the new Corefile, abort and keep using the old process

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 happen in the prometheus plugin.

In general be careful with assigning new port and expecting reload to work fully.

In CoreDNS v1.6.0 and earlier any import statements are not discovered by this plugin. This means if any of these imported files changes the reload plugin is ignorant of that fact. CoreDNS v1.7.0 and later does parse the Corefile and supports detecting changes in imported files.

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metric is exported:

- coredns_reload_failed_total{} - counts the number of failed reload attempts.

- coredns_reload_version_info{hash, value} - record the hash value during reload.

Currently the type of hash is "md5", the value is the returned hash value.

## SEE ALSO
See coredns-import(7) and corefile(5).


coredns-rewrite

title: coredns-rewrite(7)

text:
# coredns-rewrite(7)

## NAME
rewrite - performs internal message rewriting.

## 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.

## SYNTAX
A simplified/easy-to-digest syntax for rewrite is...

```
rewrite [continue|stop] FIELD [FROM TO|FROM TTL]
```

•

FIELD indicates what part of the request/response is being re-written.

–

type - the type field of the request will be rewritten. FROM/TO must be a DNS record type (A, MX, etc.); e.g., to rewrite ANY queries to HINFO, use rewrite type ANY HINFO.

–

class - the class of the message will be rewritten. FROM/TO must be a DNS class type (IN, CH, or HS); e.g., to rewrite CH queries to IN use rewrite class CH IN.

–

name - the query name in the request is rewritten; by default this is a full match of the name, e.g., rewrite name example.net example.org. Other match types are supported, see the Name Field Rewrites section below.

–

answer name - the query name in the response is rewritten. This option has special restrictions and requirements, in particular it must always combined with a name rewrite. See below in the Response Rewrites section.

–

edns0 - an EDNS0 option can be appended to the request as described below in the EDNS0 Options section.

–

ttl - the TTL value in the response is rewritten.

- FROM is the name (exact, suffix, prefix, substring, or regex) or type to match

- TO is the destination name or type to rewrite to

- TTL is the number of seconds to set the TTL value to

If you specify multiple rules and an incoming query matches multiple rules, the rewrite will behave as follows:

- continue will continue applying the next rule in the rule list.

- stop will consider the current rule the last rule and will not continue. The default behaviour is stop

## EXAMPLES

### NAME FIELD REWRITES
The rewrite plugin offers the ability to match the name in the question section of a DNS request. The match could be exact, a substring match, or based on a prefix, suffix, or regular expression. If the newly used name is not a legal domain name, the plugin returns an error to the client.

The syntax for name rewriting is as follows:

```
rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
```

The match type, e.g., exact, substring, etc., triggers rewrite:

- exact (default): on an exact match of the name in the question section of a request

- substring: on a partial match of the name in the question section of a request

- prefix: when the name begins with the matching string

- suffix: when the name ends with the matching string

- regex: when the name in the question section of a request matches a regular expression

If the match type is omitted, the exact match type is assumed.

The following instruction allows rewriting names in the query that contain the substring service.us-west-1.example.org:

```
rewrite name substring service.us-west-1.example.org service.us-west-1.consul
```

Thus:

- Incoming Request Name: ftp.service.us-west-1.example.org

- Rewritten Request Name: ftp.service.us-west-1.consul

The following instruction uses regular expressions. Names in requests matching the regular expression (.*)-(us-west-1).example.org are replaced with {1}.service.{2}.consul, where {1} and {2} are regular expression match groups.

```
rewrite name regex (.*)-(us-west-1)\.example\.org {1}.service.{2}.consul
```

Thus:

- Incoming Request Name: ftp-us-west-1.example.org

- Rewritten Request Name: ftp.service.us-west-1.consul

The following example rewrites the schmoogle.com suffix to google.com.

```
rewrite name suffix .schmoogle.com. .google.com.
```

### RESPONSE REWRITES
When rewriting incoming DNS requests' names, CoreDNS re-writes the QUESTION SECTION section of the requests. It may be necessary to rewrite the ANSWER SECTION of the requests, because some DNS resolvers treat mismatches between the QUESTION SECTION and ANSWER SECTION as a man-in-the-middle attack (MITM).

For example, a user tries to resolve ftp-us-west-1.coredns.rocks. The CoreDNS configuration file has the following rule:

```
rewrite name regex (.*)-(us-west-1)\.coredns\.rocks {1}.service.{2}.consul
```

CoreDNS rewrote the request from ftp-us-west-1.coredns.rocks to ftp.service.us-west-1.consul and ultimately resolved it to 3 records. The resolved records, in the ANSWER SECTION below, were not from coredns.rocks, but rather from service.us-west-1.consul.

```
$ dig @10.1.1.1 ftp-us-west-1.coredns.rocks
;; QUESTION SECTION:
;ftp-us-west-1.coredns.rocks. IN A
;; ANSWER SECTION:
ftp.service.us-west-1.consul. 0    IN A    10.10.10.10
ftp.service.us-west-1.consul. 0    IN A    10.20.20.20
ftp.service.us-west-1.consul. 0    IN A    10.30.30.30
```

The above is a mismatch between the question asked and the answer provided.

The following configuration snippet allows for rewriting of the ANSWER SECTION, provided that the QUESTION SECTION was rewritten:

```
    rewrite stop {

        name regex (.*)-(us-west-1)\.coredns\.rocks {1}.service.{2}.consul

        answer name (.*)\.service\.(us-west-1)\.consul {1}-{2}.coredns.rocks

    }
```

Now, the ANSWER SECTION matches the QUESTION SECTION:

```
$ dig @10.1.1.1 ftp-us-west-1.coredns.rocks
;; QUESTION SECTION:
;ftp-us-west-1.coredns.rocks. IN A
;; ANSWER SECTION:
ftp-us-west-1.coredns.rocks. 0    IN A    10.10.10.10
ftp-us-west-1.coredns.rocks. 0    IN A    10.20.20.20
ftp-us-west-1.coredns.rocks. 0    IN A    10.30.30.30
```

It is also possible to rewrite other values returned in the DNS response records (e.g. the server names returned in SRV and MX records). This can be enabled by adding the answer value to a name regex rule as specified below. answer value takes a regular expression and a rewrite name as parameters and works in the same way as the answer name rule.

Note that names in the AUTHORITY SECTION and ADDITIONAL SECTION will also be rewritten following the specified rules. The names returned by the following record types: CNAME, DNAME, SOA, SRV, MX, NAPTR, NS will be rewritten if the answer value rule is specified.

The syntax for the rewrite of DNS request and response is as follows:

```
rewrite [continue|stop] {

    name regex STRING STRING

    answer name STRING STRING

    [answer value STRING STRING]
}
```

Note that the above syntax is strict. For response rewrites, only name rules are allowed to match the question section, and only by match type regex. The answer rewrite must be after the name, as in the syntax example.

An alternate syntax for rewriting a DNS request and response is as follows:

```
rewrite [continue|stop] name regex STRING STRING answer name STRING STRING [answer value STRING STRING]
```

When using exact name rewrite rules, the answer gets rewritten automatically, and there is no need to define answer name. The rule below rewrites the name in a request from RED to BLUE, and subsequently rewrites the name in a corresponding response from BLUE to RED. The client in the request would see only RED and no BLUE.

```
rewrite [continue|stop] name exact RED BLUE
```

### TTL FIELD REWRITES
At times, the need to rewrite a TTL value could arise. For example, a DNS server may not cache records with a TTL of zero (0). An administrator may want to increase the TTL to ensure it is cached, e.g., by increasing it to 15 seconds.

In the below example, the TTL in the answers for coredns.rocks domain are being set to 15:

```
    rewrite continue {

        ttl regex (.*)\.coredns\.rocks 15

    }
```

By the same token, an administrator may use this feature to prevent or limit caching by setting the TTL value really low.

The syntax for the TTL rewrite rule is as follows. The meaning of exact|prefix|suffix|substring|regex is the same as with the name rewrite rules.

```
rewrite [continue|stop] ttl [exact|prefix|suffix|substring|regex] STRING SECONDS
```

## EDNS0 OPTIONS
Using the FIELD edns0, you can set, append, or replace specific EDNS0 options in the request.

- replace will modify any "matching" option with the specified option. The criteria for "matching" varies based on EDNS0 type.

- append will add the option only if no matching option exists

- set will modify a matching option or add one if none is found

Currently supported are EDNS0_LOCAL, EDNS0_NSID and EDNS0_SUBNET.

### 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.

•

A string data is treated as hex if it starts with 0x. Example:

```
. {

    rewrite edns0 local set 0xffee 0x61626364

    whoami
}
```

rewrites the first local option with code 0xffee, setting the data to "abcd". This is equivalent to:

```
. {

    rewrite edns0 local set 0xffee abcd
}
```

- A variable data is specified with a pair of curly brackets {}. Following are the supported variables: {qname}, {qtype}, {clientip}, {clientport}, {protocol}, {serverip}, {serverport}.

- If the metadata plugin is enabled, then labels are supported as variables if they are presented within curly brackets. The variable data will be replaced with the value associated with that label. If that label is not provided, the variable will be silently substituted with an empty string.

Examples:

```
rewrite edns0 local set 0xffee {client_ip}
```

The following example uses metadata and an imaginary "some-plugin" that would provide "some-label" as metadata information.

```
metadata
some-plugin
rewrite edns0 local set 0xffee {some-plugin/some-label}
```

### 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 replace or set, then the NSID in the option will be set to the empty string.

### 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.

Example:

```
rewrite edns0 subnet set 24 56
```

- If the query's source IP address is an IPv4 address, the first 24 bits in the IP will be the network subnet.

- If the query's source IP address is an IPv6 address, the first 56 bits in the IP will be the network subnet.

## FULL SYNTAX
The full plugin usage syntax is harder to digest...

```
rewrite [continue|stop] {type|class|edns0|name [exact|prefix|suffix|substring|regex [FROM TO answer name]]} FROM TO
```

The syntax above doesn't cover the multi-line block option for specifying a name request+response rewrite rule described in the Response Rewrite section.


coredns-root

title: coredns-root(7)

text:
# coredns-root(7)

## NAME
root - simply specifies the root of where to find (zone) files.

## DESCRIPTION
The default root is the current working directory of CoreDNS. The root plugin allows you to change this. A relative root path is relative to the current working directory.

This plugin can only be used once per Server Block.

## SYNTAX

```
root PATH
```

PATH is the directory to set as CoreDNS' root.

## EXAMPLES
Serve zone data (when the file plugin is used) from /etc/coredns/zones:

```
. {

    root /etc/coredns/zones
}
```


title: coredns-route53(7)

text:
# coredns-route53(7)

## NAME
route53 - enables serving zone data from AWS route53.

## DESCRIPTION
The route53 plugin is useful for serving zones from resource record sets in AWS route53. This plugin supports all Amazon Route 53 records (https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ResourceRecordTypes.html ⟨https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ResourceRecordTypes.html⟩). The route53 plugin can be used when coredns is deployed on AWS or elsewhere.

## SYNTAX

```
route53 [ZONE:HOSTED_ZONE_ID...] {

    aws_access_key [AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY]

    credentials PROFILE [FILENAME]

    fallthrough [ZONES...]

    refresh DURATION
}
```

- ZONE 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.

- HOSTED_ZONE_ID the ID of the hosted zone that contains the resource record sets to be accessed.

- AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY the AWS access key ID and secret access key to be used when query AWS (optional). If they are not provided, then coredns tries to access AWS credentials the same way as AWS CLI, e.g., environmental variables, AWS credentials file, instance profile credentials, etc.

- credentials is used for reading the credential FILENAME and setting the PROFILE name for a given zone. PROFILE is the AWS account profile name. Defaults to default. FILENAME is the AWS credentials filename, defaults to ~/.aws/credentials.

- fallthrough If zone matches and no record can be generated, pass request to the next plugin. If ZONES is omitted, then fallthrough happens for all zones for which the plugin is authoritative. If specific zones are listed (for example in-addr.arpa and ip6.arpa), then only queries for those zones will be subject to fallthrough.

- refresh can be used to control how long between record retrievals from Route 53. It requires a duration string as a parameter to specify the duration between update cycles. Each update cycle may result in many AWS API calls depending on how many domains use this plugin and how many records are in each. Adjusting the update frequency may help reduce the potential of API rate-limiting imposed by AWS.

- DURATION A duration string. Defaults to 1m. If units are unspecified, seconds are assumed.

## EXAMPLES
Enable route53 with implicit AWS credentials and resolve CNAMEs via 10.0.0.1:

```
example.org {

    route53 example.org.:Z1Z2Z3Z4DZ5Z6Z7
}
. {

    forward . 10.0.0.1
}
```

Enable route53 with explicit AWS credentials:

```
example.org {

    route53 example.org.:Z1Z2Z3Z4DZ5Z6Z7 {

      aws_access_key AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

    }
}
```

Enable route53 with fallthrough:

```
. {

    route53 example.org.:Z1Z2Z3Z4DZ5Z6Z7 example.gov.:Z654321543245 {

      fallthrough example.gov.

    }
}
```

Enable route53 with multiple hosted zones with the same domain:

```
example.org {

    route53 example.org.:Z1Z2Z3Z4DZ5Z6Z7 example.org.:Z93A52145678156
}
```

Enable route53 and refresh records every 3 minutes

```
example.org {

    route53 example.org.:Z1Z2Z3Z4DZ5Z6Z7 {

      refresh 3m

    }
}
```


coredns-secondary

title: coredns-secondary(7)

text:
# coredns-secondary(7)

## NAME
secondary - enables serving a zone retrieved from a primary server.

## DESCRIPTION
With secondary you can transfer (via AXFR) a zone from another server. The retrieved zone is not committed to disk (a violation of the RFC). This means restarting CoreDNS will cause it to retrieve all secondary zones.

## SYNTAX

```
secondary [ZONES...]
```

•

ZONES zones it should be authoritative for. If empty, the zones from the configuration block are used. Note that without a remote address to get the zone from, the above is not that useful.

A working syntax would be:

```
secondary [zones...] {

    transfer from ADDRESS [ADDRESS...]
}
```

•

transfer from specifies from which ADDRESS to fetch the zone. It can be specified multiple times; if one does not work, another will be tried. Transfering this zone outwards again can be done by enabling the transfer plugin.

When a zone is due to be refreshed (refresh timer fires) a random jitter of 5 seconds is applied, before fetching. In the case of retry this will be 2 seconds. If there are any errors during the transfer in, the transfer fails; this will be logged.

## EXAMPLES
Transfer example.org from 10.0.1.1, and if that fails try 10.1.2.1.

```
example.org {

    secondary {

        transfer from 10.0.1.1 10.1.2.1

    }
}
```

Or re-export the retrieved zone to other secondaries.

```
example.net {

    secondary {

        transfer from 10.1.2.1

    }

    transfer {

        to *

    }
}
```

## BUGS
Only AXFR is supported and the retrieved zone is not committed to disk.

## SEE ALSO
See the transfer plugin to enable zone transfers to other servers.


coredns-sign

title: coredns-sign(7)

text:
# coredns-sign(7)

## NAME
sign - adds DNSSEC records to zone files.

## DESCRIPTION
The sign 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 sign plugin takes care of this.

Only NSEC is supported, sign does not support NSEC3.

Sign works in conjunction with the file and auto plugins; this plugin signs the zones files, auto and file serve the zones data.

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. Sign does not support the ZSK/KSK split, nor will it do key or algorithm rollovers - it just signs.

Sign will:

•

(Re)-sign the zone with the CSK(s) when:

–

the last time it was signed is more than a 6 days ago. Each zone will have some jitter applied to the inception date.

–

the signature only has 14 days left before expiring.

Both these dates are only checked on the SOA's signature(s).

- Create RRSIGs that have an inception of -3 hours (minus a jitter between 0 and 18 hours) and a expiration of +32 (plus a jitter between 0 and 5 days) days for every given DNSKEY.

- Add NSEC records for all names in the zone. The TTL for these is the negative cache TTL from the SOA record.

- Add or replace all 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.

- Update the SOA's serial number to the Unix epoch of when the signing happens. This will overwrite any previous serial number.

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.

Keys are named (following BIND9): K<name>+<alg>+<id>.key and K<name>+<alg>+<id>.private. The keys must not be included in your zone; they will be added by sign. These keys can be generated with coredns-keygen or BIND9's dnssec-keygen. You don't have to adhere to this naming scheme, but then you need to name your keys explicitly, see the keys file directive.

A generated zone is written out in a file named db.<name>.signed in the directory named by the directory directive (which defaults to /var/lib/coredns).

## SYNTAX

```
sign DBFILE [ZONES...] {

    key file|directory KEY...|DIR...

    directory DIR
}
```

- DBFILE the zone database file to read and parse. If the path is relative, the path from the root plugin will be prepended to it.

- ZONES zones it should be sign for. If empty, the zones from the configuration block are used.

- key specifies the key(s) (there can be multiple) to sign the zone. If file is used the KEY's filenames are used as is. If directory is used, sign will look in DIR for K<name>+<alg>+<id> files. Any metadata in these files (Activate, Publish, etc.) is ignored. These keys must also be Key Signing Keys (KSK).

- directory specifies the DIR where CoreDNS should save zones that have been signed. If not given this defaults to /var/lib/coredns. The zones are saved under the name db.<name>.signed. If the path is relative the path from the root plugin will be prepended to it.

Keys can be generated with coredns-keygen, to create one for use in the sign plugin, use: coredns-keygen example.org or dnssec-keygen -a ECDSAP256SHA256 -f KSK example.org.

## EXAMPLES
Sign the example.org zone contained in the file db.example.org and write the result to ./db.example.org.signed to let the file plugin pick it up and serve it. The keys used are read from /etc/coredns/keys/Kexample.org.key and /etc/coredns/keys/Kexample.org.private.

```
example.org {

    file db.example.org.signed

    sign db.example.org {

        key file /etc/coredns/keys/Kexample.org

        directory .

    }
}
```

Running this leads to the following log output (note the timers in this example have been set to shorter intervals).

```
[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
```

Or use a single zone file for multiple zones, note that the ZONES are repeated for both plugins. Also note this outputs multiple signed output files. Here we use the default output directory /var/lib/coredns.

```
. {

    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

    }
}
```

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 file plugin:

```
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

    }
}
```

Be careful to fully list the origins you want to sign, if you don't:

```
example.org example.net {

    sign plugin/sign/testdata/db.example.org miek.org {

        key file /etc/coredns/keys/Kexample.org

    }
}
```

This will lead to db.example.org be signed twice, as this entire section is parsed twice because you have specified the origins example.org and example.net in the server block.

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.

## SEE ALSO
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 file plugin's documentation.

Coredns-keygen can be found at https://github.com/coredns/coredns-utils ⟨https://github.com/coredns/coredns-utils⟩ in the coredns-keygen directory.

Other useful DNSSEC tools can be found in ldns ⟨https://nlnetlabs.nl/projects/ldns/about/⟩, e.g. ldns-key2ds to create DS records from DNSKEYs.

## BUGS
keys directory is not implemented.


coredns-template

title: coredns-template(7)

text:
# coredns-template(7)

## NAME
template - allows for dynamic responses based on the incoming query.

## DESCRIPTION
The template plugin allows you to dynamically respond to queries by just writing a (Go) template.

## SYNTAX

```
template CLASS TYPE [ZONE...] {

    match REGEX...

    answer RR

    additional RR

    authority RR

    rcode CODE

    fallthrough [ZONE...]
}
```

- CLASS the query class (usually IN or ANY).

- TYPE the query type (A, PTR, ... can be ANY to match all types).

- ZONE the zone scope(s) for this template. Defaults to the server zones.

- REGEX Go regexp ⟨https://golang.org/pkg/regexp/⟩ that are matched against the incoming question name. Specifying no regex matches everything (default: .*). First matching regex wins.

- answer|additional|authority RR A RFC 1035 ⟨https://tools.ietf.org/html/rfc1035#section-5⟩ style resource record fragment built by a Go template ⟨https://golang.org/pkg/text/template/⟩ that contains the reply.

- rcode CODE A response code (NXDOMAIN, SERVFAIL, ...). The default is SUCCESS.

- fallthrough Continue with the next plugin if the zone matched but no regex matched. If specific zones are listed (for example in-addr.arpa and ip6.arpa), then only queries for those zones will be subject to fallthrough.

At least one answer or rcode directive is needed (e.g. rcode NXDOMAIN).

Also see ⟨#also-see⟩ contains an additional reading list.

## TEMPLATES
Each resource record is a full-featured Go template ⟨https://golang.org/pkg/text/template/⟩ with the following predefined data

- .Zone the matched zone string (e.g. example.).

- .Name the query name, as a string (lowercased).

- .Class the query class (usually IN).

- .Type the RR type requested (e.g. PTR).

- .Match an array of all matches. index .Match 0 refers to the whole match.

- .Group a map of the named capture groups.

- .Message the complete incoming DNS message.

- .Question the matched question section.

- .Remote client’s IP address

- .Meta a function that takes a metadata name and returns the value, if the metadata plugin is enabled. For example, .Meta "kubernetes/client-namespace"

The output of the template must be a RFC 1035 ⟨https://tools.ietf.org/html/rfc1035⟩ style resource record (commonly referred to as a "zone file").

WARNING there is a syntactical problem with Go templates and CoreDNS config files. Expressions

like {{$var}} will be interpreted as a reference to an environment variable by CoreDNS (and

Caddy) while {{ $var }} will work. See Bugs ⟨#bugs⟩ and corefile(5).

## METRICS
If monitoring is enabled (via the prometheus plugin) then the following metrics are exported:

- coredns_template_matches_total{server, regex} the total number of matched requests by regex.

- coredns_template_template_failures_total{server, regex,section,template} 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.

- coredns_template_rr_failures_total{server, regex,section,template} 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.

Both failure cases indicate a problem with the template configuration. The server label indicates the server incrementing the metric, see the metrics plugin for details.

## EXAMPLES

### RESOLVE EVERYTHING TO NXDOMAIN
The most simplistic template is

```
. {

    template ANY ANY {

      rcode NXDOMAIN

    }
}
```

1.

This template uses the default zone (. or all queries)

2.

All queries will be answered (no fallthrough)

3.

The answer is always NXDOMAIN

### RESOLVE .INVALID AS NXDOMAIN
The .invalid domain is a reserved TLD (see RFC 2606 Reserved Top Level DNS Names ⟨https://tools.ietf.org/html/rfc2606#section-2⟩) to indicate invalid domains.

```
. {

    forward . 8.8.8.8

    template ANY ANY invalid {

      rcode NXDOMAIN

      authority "invalid. 60 {{ .Class }} SOA ns.invalid. hostmaster.invalid. (1 60 60 60 60)"

    }
}
```

1.

A query to .invalid will result in NXDOMAIN (rcode)

2.

A dummy SOA record is sent to hand out a TTL of 60s for caching purposes

3.

Querying .invalid in the CH class will also cause a NXDOMAIN/SOA response

4.

The default regex is .*

### BLOCK INVALID SEARCH DOMAIN COMPLETIONS
Imagine you run example.com with a datacenter dc1.example.com. The datacenter domain is part of the DNS search domain. However something.example.com.dc1.example.com would indicate a fully qualified domain name (something.example.com) that inadvertently has the default domain or search path (dc1.example.com) added.

```
. {

    forward . 8.8.8.8

    template IN ANY example.com.dc1.example.com {

      rcode NXDOMAIN

      authority "{{ .Zone }} 60 IN SOA ns.example.com hostmaster.example.com (1 60 60 60 60)"

    }
}
```

A more verbose regex based equivalent would be

```
. {

    forward . 8.8.8.8

    template IN ANY example.com {

      match "example\.com\.(dc1\.example\.com\.)$"

      rcode NXDOMAIN

      authority "{{ index .Match 1 }} 60 IN SOA ns.{{ index .Match 1 }} hostmaster.{{ index .Match 1 }} (1 60 60 60 60)"

      fallthrough

    }
}
```

The regex-based version can do more complex matching/templating while zone-based templating is easier to read and use.

### RESOLVE A/PTR FOR .EXAMPLE

```
. {

    forward . 8.8.8.8

    # ip-a-b-c-d.example A a.b.c.d

    template IN A example {

      match (^|[.])ip-(?P<a>[0-9]*)-(?P<b>[0-9]*)-(?P<c>[0-9]*)-(?P<d>[0-9]*)[.]example[.]$

      answer "{{ .Name }} 60 IN A {{ .Group.a }}.{{ .Group.b }}.{{ .Group.c }}.{{ .Group.d }}"

      fallthrough

    }

    # d.c.b.a.in-addr.arpa PTR ip-a-b-c-d.example

    template IN PTR in-addr.arpa {

      match ^(?P<d>[0-9]*)[.](?P<c>[0-9]*)[.](?P<b>[0-9]*)[.](?P<a>[0-9]*)[.]in-addr[.]arpa[.]$

      answer "{{ .Name }} 60 IN PTR ip-{{ .Group.a }}-{{ .Group.b }}-{{ .Group.c }}-{{ .Group.d }}.example."

    }
}
```

An IPv4 address consists of 4 bytes, a.b.c.d. Named groups make it less error-prone to reverse the IP address in the PTR case. Try to use named groups to explain what your regex and template are doing.

Note that the A record is actually a wildcard: any subdomain of the IP address will resolve to the IP address.

Having templates to map certain PTR/A pairs is a common pattern.

Fallthrough is needed for mixed domains where only some responses are templated.

### RESOLVE MULTIPLE IP PATTERNS

```
. {

    forward . 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

    }
}
```

Named capture groups can be used to template one response for multiple patterns.

### RESOLVE A AND MX RECORDS FOR IP TEMPLATES IN .EXAMPLE

```
. {

    forward . 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

    }
}
```

### ADDING AUTHORITATIVE NAMESERVERS TO THE RESPONSE

```
. {

    forward . 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

    }
}
```

## ALSO SEE

- Go regexp ⟨https://golang.org/pkg/regexp/⟩ for details about the regex implementation

- RE2 syntax reference ⟨https://github.com/google/re2/wiki/Syntax⟩ for details about the regex syntax

- RFC 1034 ⟨https://tools.ietf.org/html/rfc1034#section-3.6.1⟩ and RFC 1035 ⟨https://tools.ietf.org/html/rfc1035#section-5⟩ for the resource record format

- Go template ⟨https://golang.org/pkg/text/template/⟩ for the template language reference

## BUGS
CoreDNS supports caddyfile environment variables ⟨https://caddyserver.com/docs/caddyfile#env⟩ with notion of {$ENV_VAR}. This parser feature will break Go template variables ⟨https://golang.org/pkg/text/template/#hdr-Variables⟩ notations like{{$variable}}. The equivalent notation {{ $variable }} will work. Try to avoid Go template variables in the context of this plugin.


coredns-tls

title: coredns-tls(7)

text:
# coredns-tls(7)

## NAME
tls - allows you to configure the server certificates for the TLS and gRPC servers.

## DESCRIPTION
CoreDNS supports queries that are encrypted using TLS (DNS over Transport Layer Security, RFC 7858) or are using gRPC (https://grpc.io/ ⟨https://grpc.io/⟩, not an IETF standard). Normally DNS traffic isn't encrypted at all (DNSSEC only signs resource records).

The tls "plugin" allows you to configure the cryptographic keys that are needed for both DNS-over-TLS and DNS-over-gRPC. If the tls plugin is omitted, then no encryption takes place.

The gRPC protobuffer is defined in pb/dns.proto. It defines the proto as a simple wrapper for the wire data of a DNS message.

## SYNTAX

```
tls CERT KEY [CA]
```

Parameter CA is optional. If not set, system CAs can be used to verify the client certificate

```
tls CERT KEY [CA] {

    client_auth nocert|request|require|verify_if_given|require_and_verify
}
```

If client_auth option is specified, it controls the client authentication policy. The option value corresponds to the ClientAuthType values of the Go tls package ⟨https://golang.org/pkg/crypto/tls/#ClientAuthType⟩: NoClientCert, RequestClientCert, RequireAnyClientCert, VerifyClientCertIfGiven, and RequireAndVerifyClientCert, respectively. The default is "nocert". Note that it makes no sense to specify parameter CA unless this option is set to verify_if_given or require_and_verify.

## EXAMPLES
Start a DNS-over-TLS server that picks up incoming DNS-over-TLS queries on port 5553 and uses the nameservers defined in /etc/resolv.conf to resolve the query. This proxy path uses plain old DNS.

```
tls://.:5553 {

    tls cert.pem key.pem ca.pem

    forward . /etc/resolv.conf
}
```

Start a DNS-over-gRPC server that is similar to the previous example, but using DNS-over-gRPC for incoming queries.

```
grpc://. {

    tls cert.pem key.pem ca.pem

    forward . /etc/resolv.conf
}
```

Only Knot DNS' kdig supports DNS-over-TLS queries, no command line client supports gRPC making debugging these transports harder than it should be.

## SEE ALSO
RFC 7858 and https://grpc.io ⟨https://grpc.io⟩.


coredns-trace

title: coredns-trace(7)

text:
# coredns-trace(7)

## NAME
trace - enables OpenTracing-based tracing of DNS requests as they go through the plugin chain.

## DESCRIPTION
With trace you enable OpenTracing of how a request flows through CoreDNS. Enable the debug plugin to get logs from the trace plugin.

## SYNTAX
The simplest form is just:

```
trace [ENDPOINT-TYPE] [ENDPOINT]
```

- ENDPOINT-TYPE is the type of tracing destination. Currently only zipkin and datadog are supported. Defaults to zipkin.

- ENDPOINT is the tracing destination, and defaults to localhost:9411. For Zipkin, if ENDPOINT does not begin with http, then it will be transformed to http://ENDPOINT/api/v1/spans.

With this form, all queries will be traced.

Additional features can be enabled with this syntax:

```
trace [ENDPOINT-TYPE] [ENDPOINT] {

    every AMOUNT

    service NAME

    client_server

    datadog_analytics_rate RATE
}
```

- every AMOUNT 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.

- service NAME allows you to specify the service name reported to the tracing server. Default is coredns.

- client_server will enable the ClientServerSameSpan OpenTracing feature.

- datadog_analytics_rate RATE will enable trace analytics ⟨https://docs.datadoghq.com/tracing/app_analytics⟩ on the traces sent from 0 to 1, 1 being every trace sent will be analyzed. This is a datadog only feature (ENDPOINT-TYPE needs to be datadog)

## ZIPKIN
You can run Zipkin on a Docker host like this:

```
docker run -d -p 9411:9411 openzipkin/zipkin
```

Note the zipkin provider does not support the v1 API since coredns 1.7.1.

## EXAMPLES
Use an alternative Zipkin address:

```
trace tracinghost:9253
```

or

```
. {

    trace zipkin tracinghost:9253
}
```

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:

```
trace http://tracinghost:9411/zipkin/api/v1/spans
```

Using DataDog:

```
trace datadog localhost:8126
```

Trace one query every 10000 queries, rename the service, and enable same span:

```
trace tracinghost:9411 {

    every 10000

    service dnsproxy

    client_server
}
```

## SEE ALSO
See the debug plugin for more information about debug logging.


coredns-transfer

title: coredns-transfer(7)

text:
# coredns-transfer(7)

## NAME
transfer - perform (outgoing) zone transfers for other plugins.

## DESCRIPTION
This plugin answers zone transfers for authoritative plugins that implement transfer.Transferer.

transfer answers full zone transfer (AXFR) requests and incremental zone transfer (IXFR) requests with AXFR fallback if the zone has changed.

When a plugin wants to notify it's secondaries it will call back into the transfer plugin.

The following plugins implement zone transfers using this plugin: file, auto, secondary, and kubernetes. See transfer.go for implementation details if you are a plugin author that wants to use this plugin.

## SYNTAX

```
transfer [ZONE...] {

  to ADDRESS...
}
```

- ZONE The zones transfer will answer zone transfer requests for. If left blank, the zones are inherited from the enclosing server block. To answer zone transfers for a given zone, there must be another plugin in the same server block that serves the same zone, and implements transfer.Transferer.

- to ADDRESS... The hosts transfer will transfer to. Use * to permit transfers to all addresses. ADDRESS must be denoted in CIDR notation (e.g., 127.0.0.1/32) or just as plain addresses. to may be specified multiple times.

## EXAMPLES
See the specific plugins using this plugin for examples on it's usage.


coredns-tsig

title: coredns-tsig(7)

text:
# coredns-tsig(7)

## NAME
tsig - validate TSIG requests and sign responses.

## DESCRIPTION
With tsig, you can define a set of TSIG secret keys for validating incoming TSIG requests and signing responses. It can also require TSIG for certain query types, refusing requests that do not comply.

## SYNTAX

```
tsig [ZONE...] {

  secret NAME KEY

  secrets FILE

  require [QTYPE...]
}
```

- ZONE - the zones tsig will TSIG. By default, the zones from the server block are used.

- secret NAME KEY - specifies a TSIG secret for NAME with KEY. Use this option more than once to define multiple secrets. Secrets are global to the server instance, not just for the enclosing ZONE.

- secrets FILE - same as secret, but load the secrets from a file. The file may define any number

of unique keys, each in the following named.conf format:

```
 key "example." {

     secret "X28hl0BOfAL5G0jsmJWSacrwn7YRm2f6U5brnzwWEus=";

 };
```

Each key may also specify an algorithm e.g. algorithm hmac-sha256;, but this is currently ignored by the plugin.

–

require QTYPE... - the query types that must be TSIG'd. Requests of the specified types will be REFUSED if they are not signed.require all will require requests of all types to be signed. require none will not require requests any types to be signed. Default behavior is to not require.

## EXAMPLES
Require TSIG signed transactions for transfer requests to example.zone.

```
example.zone {

  tsig {

    secret example.zone.key. NoTCJU+DMqFWywaPyxSijrDEA/eC3nK0xi3AMEZuPVk=

    require AXFR IXFR

  }

  transfer {

    to *

  }
}
```

Require TSIG signed transactions for all requests to auth.zone.

```
auth.zone {

  tsig {

    secret auth.zone.key. NoTCJU+DMqFWywaPyxSijrDEA/eC3nK0xi3AMEZuPVk=

    require all

  }

  forward . 10.1.0.2
}
```

## BUGS

### ZONE TRANSFER NOTIFIES
With the transfer plugin, zone transfer notifications from CoreDNS are not TSIG signed.

### SPECIAL CONSIDERATIONS FOR FORWARDING SERVERS (RFC 8945 5.5)
https://datatracker.ietf.org/doc/html/rfc8945#section-5.5 ⟨https://datatracker.ietf.org/doc/html/rfc8945#section-5.5⟩

CoreDNS does not implement this section as follows ...

•

RFC requirement: > If the name on the TSIG is not of a secret that the server shares with the originator, the server MUST forward the message unchanged including the TSIG.

CoreDNS behavior: If ths zone of the request matches the tsig plugin zones, then the TSIG record is always stripped. But even when the tsig plugin is not involved, the forward plugin may alter the message with compression, which would cause validation failure at the destination.

•

RFC requirement: > If the TSIG passes all checks, the forwarding server MUST, if possible, include a TSIG of its own to the destination or the next forwarder.

CoreDNS behavior: If ths zone of the request matches the tsig plugin zones, forward plugin will proxy the request upstream without TSIG.

•

RFC requirement: > If no transaction security is available to the destination and the message is a query, and if the corresponding response has the AD flag (see RFC4035) set, the forwarder MUST clear the AD flag before adding the TSIG to the response and returning the result to the system from which it received the query.

CoreDNS behavior: The AD flag is not cleared.


coredns-view

title: coredns-view(7)

text:
# coredns-view(7)

## NAME
view - defines conditions that must be met for a DNS request to be routed to the server block.

## DESCRIPTION
view defines an expression that must evaluate to true for a DNS request to be routed to the server block. This enables advanced server block routing functions such as split dns.

## SYNTAX

```
view NAME {

  expr EXPRESSION
}
```

- view NAME - The name of the view used by metrics and exported as metadata for requests that match the view's expression

- expr EXPRESSION - CoreDNS will only route incoming queries to the enclosing server block if the EXPRESSION evaluates to true. See the Expressions section for available variables and functions. If multiple instances of view are defined, all EXPRESSION must evaluate to true for CoreDNS will only route incoming queries to the enclosing server block.

For expression syntax and examples, see the Expressions and Examples sections.

## EXAMPLES
Implement CIDR based split DNS routing. This will return a different answer for test. depending on client's IP address. It returns ... * test. 3600 IN A 1.1.1.1, for queries with a source address in 127.0.0.0/24 * test. 3600 IN A 2.2.2.2, for queries with a source address in 192.168.0.0/16 * test. 3600 IN A 3.3.3.3, for all others

```
. {

  view example1 {

    expr incidr(client_ip(), '127.0.0.0/24')

  }

  hosts {

    1.1.1.1 test

  }
}
. {

  view example2 {

    expr incidr(client_ip(), '192.168.0.0/16')

  }

  hosts {

    2.2.2.2 test

  }
}
. {

  hosts {

    3.3.3.3 test

  }
}
```

Send all A and AAAA requests to 10.0.0.6, and all other requests to 10.0.0.1.

```
. {

  view example {

    expr type() in ['A', 'AAAA']

  }

  forward . 10.0.0.6
}
. {

  forward . 10.0.0.1
}
```

Send all requests for abc.*.example.com (where * can be any number of labels), to 10.0.0.2, and all other requests to 10.0.0.1. Note that the regex pattern is enclosed in single quotes, and backslashes are escaped with backslashes.

```
. {

  view example {

    expr name() matches '^abc\\..*\\.example\\.com\\.$'

  }

  forward . 10.0.0.2
}
. {

  forward . 10.0.0.1
}
```

## EXPRESSIONS
To evaluate expressions, view uses the antonmedv/expr package (https://github.com/antonmedv/expr ⟨https://github.com/antonmedv/expr⟩). For example, an expression could look like: (type() == 'A' && name() == 'example.com') || client_ip() == '1.2.3.4'.

All expressions should be written to evaluate to a boolean value.

See https://github.com/antonmedv/expr/blob/master/docs/Language-Definition.md ⟨https://github.com/antonmedv/expr/blob/master/docs/Language-Definition.md⟩ as a detailed reference for valid syntax.

### AVAILABLE EXPRESSION FUNCTIONS
In the context of the view plugin, expressions can reference DNS query information by using utility functions defined below.

### DNS QUERY FUNCTIONS

- bufsize() int: the EDNS0 buffer size advertised in the query

- class() string: class of the request (IN, CH, ...)

- client_ip() string: client's IP address, for IPv6 addresses these are enclosed in brackets: [::1]

- do() bool: the EDNS0 DO (DNSSEC OK) bit set in the query

- id() int: query ID

- name() string: name of the request (the domain name requested)

- opcode() int: query OPCODE

- port() string: client's port

- proto() string: protocol used (tcp or udp)

- server_ip() string: server's IP address; for IPv6 addresses these are enclosed in brackets: [::1]

- server_port() string : client's port

- size() int: request size in bytes

- type() string: type of the request (A, AAAA, TXT, ...)

### UTILITY FUNCTIONS

- incidr(ip string, cidr string) bool: returns true if ip is within cidr

- metadata(label string) - returns the value for the metadata matching label

## METADATA
The view plugin will publish the following metadata, if the metadata plugin is also enabled:

•

view/name: the name of the view handling the current request


coredns-whoami

title: coredns-whoami(7)

text:
# coredns-whoami(7)

## NAME
whoami - returns your resolver's local IP address, port and transport.

## DESCRIPTION
The whoami plugin is not really that useful, but can be used for having a simple (fast) endpoint to test clients against. When whoami returns a response it will have your client's IP address in the additional section as either an A or AAAA record.

The reply always has an empty answer section. The port and transport are included in the additional section as a SRV record, transport can be "tcp" or "udp".

```
._<transport>.qname. 0 IN SRV 0 0 <port> .
```

The whoami plugin will respond to every A or AAAA query, regardless of the query name.

If CoreDNS can't find a Corefile on startup this is the default plugin that gets loaded. As such it can be used to check that CoreDNS is responding to queries. Other than that this plugin is of limited use in production.

## SYNTAX

```
whoami
```

## EXAMPLES
Start a server on the default port and load the whoami plugin.

```
example.org {

    whoami
}
```

When queried for "example.org A", CoreDNS will respond with:

```
;; 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
```

## SEE ALSO
Read the blog post ⟨https://coredns.io/2017/03/01/how-to-add-plugins-to-coredns/⟩ on how this plugin is built, or explore the source code ⟨https://github.com/coredns/coredns/blob/master/plugin/whoami/⟩.


package: corosync

title: cmap_keys(7)

text:
# cmap_keys(7)

## NAME
cmap_keys - Overview of keys stored in the Configuration Map

## OVERVIEW
There are 3 main types of keys stored in CMAP:

* Mapping of values stored in the config file.

* Runtime statistics.

* Other user created values.

In this man page, wild-cards have the usual meaning.

## ICMAP KEYS
These keys are in the icmap (default) map

internal_configuration.*

Internal configuration data. All keys in this prefix are read only. It's only useful for getting a list of loaded services.

logging.*

Values read from the configuration file. It's possible to change them at runtime. If subsystem specific configuration is needed, the key must be in the form logging.logger_subsys.SERVICE.key, where SERVICE is upper case name of the service and key is same as in the configuration file. All values are of string type.

nodelist.*

Values are read from the configuration file only (dynamic updates are not allowed). Each node element in the configuration file gets assigned its position starting from zero. So the first node from the config file has nodelist.node.0. prefix. To be a valid entry, each node must have ring0_addr key. To change the nodeid key, use a u32 data type. Local node position is stored in local_node_pos key (RO), so it's easy to find out nodeid/ring addresses of the local node directly from cmap.

runtime.blackbox.*

Trigger keys for storing fplay data. It's recommended that you use the corosync-blackbox command to change keys in this prefix.

runtime.force_gather

Set to 'yes' to force the processor to move into the GATHER state. This operation is dangerous and is not recommended.

runtime.config.*

Contains the values actually in use by the totem membership protocol. Values here are either taken from the Corosync configuration file, defaults or computed from entries in the config file. For information on individual keys please refer to the man page corosync.conf(5).

runtime.services.*

Prefix with statistics for service engines. Each service has its own service_id key in the prefix with the name runtime.services.SERVICE., where SERVICE is the lower case name of the service. Inside the service prefix is the number of messages received and sent by the corosync engine in the format runtime.services.SERVICE.EXEC_CALL.rx and runtime.services.SERVICE.EXEC_CALL.tx, where EXEC_CALL is the internal id of the service call (so for example 3 in cpg service is receive of multicast message from other nodes).

runtime.totem.members.*

Prefix containing members of the totem single ring protocol. Each member keys has format runtime.totem.members.NODEID.KEY, where key is one of: config_version Config version of the member node.

resources.process.PID.*

Prefix created by applications using SAM with CMAP integration. It contains the following keys: recovery Recovery policy of the process. Can be one of quit or restart.

poll_period Value passed in sam_initialize as a time_interval.

last_updated Last time SAM received a heartbeat from the client.

state State of the client. Can be one of failed, stopped, running and waiting for quorum.

uidgid.*

Information about users/groups which are allowed to make IPC connections to corosync. Entries loaded from configuration file are stored with uidgid.config.* prefix and are pruned on configuration file reload. Dynamic entries has uidgid.* prefix and a configuration file reload doesn't affect them.

quorum.cancel_wait_for_all

Tells votequorum to cancel waiting for all nodes at cluster startup. Can be used to unblock quorum if notes are known to be down. For pcs use only.

cfg.shutdown_timeout

Sets the timeout within which daemons that are registered for cfg callbacks must respond to a corosync_cfg_try_shutdown() request. the default is 5000 mS

config.reload_in_progress

This value will be set to 1 (or created) when a corosync.conf reload is started, and set to 0 when the reload is completed. This allows interested subsystems to do atomic reconfiguration rather than changing each key. Note that individual add/change/delete notifications will still be sent during a reload.

config.totemconfig_reload_in_progress

This key is similar to config.totemconfig_reload_in_progress but changed after the totem config trigger is processed. It is useful (mainly) for situations when nodelist.local_node_pos must be correctly reinstated before anything else.

## STATS KEYS
These keys are in the stats map. All keys in this map are read-only. Modification tracking of individual keys is supported in the stats map, but not prefixes. Add/Delete operations are supported on prefixes though so you can track for new ipc connections or knet interfaces.

stats.srp.*

Prefix containing statistics about totem. Typical key prefixes: commit_entered Number of times the processor entered COMMIT state.

commit_token_lost Number of times the processor lost token in COMMIT state.

consensus_timeouts How many times the processor timed out forming a consensus about membership.

continuous_gather How many times the processor was not able to reach consensus.

firewall_enabled_or_nic_failure Set to 1 when processor was not able to reach consensus for long time. The usual reason is a badly configured firewall or connection failure.

gather_entered Number of times the processor entered GATHER state.

gather_token_lost Number of times the processor lost token in GATHER state.

mcast_retx Number of retransmitted messages.

mcast_rx Number of received multicast messages.

mcast_tx Number of transmitted multicast messages.

memb_commit_token_rx Number of received commit tokens.

memb_commit_token_tx Number of transmitted commit tokens.

memb_join_rx Number of received join messages.

memb_join_tx Number of transmitted join messages.

memb_merge_detect_rx Number of received member merge messages.

memb_merge_detect_tx Number of transmitted member merge messages.

orf_token_rx Number of received orf tokens.

orf_token_tx Number of transmitted orf tokens.

recovery_entered Number of times the processor entered recovery.

recovery_token_lost Number of times the token was lost in recovery state.

rx_msg_dropped Number of received messages which were dropped because they were not expected (as example multicast message in commit state).

token_hold_cancel_rx Number of received token hold cancel messages.

token_hold_cancel_tx Number of transmitted token hold cancel messages.

mtt_rx_token Mean transit time of token in milliseconds. In other words, time between two consecutive token receives.

avg_token_workload Average time in milliseconds of holding time of token on the current processor.

avg_backlog_calc Average number of not yet sent messages on the current processor.

stats.knet.nodeX.linkY.*

Statistics about the network traffic to and from each node and link when using tke kronosnet transport connected Whether the link is connected or not

up_count Number of times this link has changed state to UP

down_count Number of times this link has changed state to DOWN

latency_ave / latency_max / latency_max Calculated latencies of this link. Note that if there has been no traffic on the link then latency_min will show a very large number.

latency_samples The number of samples used to calculate the latency figures, so you have some idea of their precision.

rx_data_packets / tx_data_packets The number of packets sent/received on this link

rx_data_bytes / tx_data_bytes The number of bytes sent/received on this link

rx_pmtu_packets / tx_pmtu_packets The number of packets sent/received by the PMTUd subsystem

rx_pmtu_bytes / tx_pmtu_bytes The number of bytes sent/received by the PMTUd subsystem

rx_ping_packets / tx_ping_packets The number of packets sent/received as pings

rx_ping_bytes / tx_ping_bytes The number of bytes sent/received as pings

rx_pong_packets / tx_pong_packets The number of packets sent/received as pongs

rx_pong_bytes / tx_pong_bytes The number of bytes sent/received as pongs

rx_total_packets / tx_total_packets The total number of packets sent/received. The aggregate of all of the above packet stats

rx_total_bytes / tx_total_bytes The total number of bytes sent/received. The aggregate of all of the above bytes stats

tx_data_retries / tx_pmtu_retries / tx_ping_retries / tx_pong_retries / tx_total_retries Number of times a transmit operation had to be retried due to the socket returning EAGAIN

stats.ipcs.*

There is information about total number of active connections from client programs at the time the request was made. active number of closed connections during whole runtime of corosync closed Total number of connections that have been made since corosync was started

stats.ipcs.ID.*

Each IPC connection has a unique ID. This is in the form [[serviceX:][PID:]internal_id. Typical keys in this prefix are:

proc_name process name of connected process (unavailable on some platforms)

dispatched number of dispatched messages.

invalid_request number of requests made by IPC which are invalid (calling non-existing call, ...).

name contains short name of the IPC connection (unavailable on some platforms).

overload is number of requests which were not processed because of overload.

queue_size contains the number of messages in the queue waiting for send.

recv_retries is the total number of interrupted receives.

requests contains the number of requests made by IPC.

responses is the number of responses sent to the IPC client.

send_retries contains the total number of interrupted sends.

service_id contains the ID of service which the IPC is connected to.

stats.schedmiss.<n>.*

If corosync is not scheduled after the required period of time it will log this event and also write an entry to the stats cmap under this key. There can be up to 10 entries (0..9) in here, when an 11th event happens the earliest will be removed. These events will always be in reverse order, so stats.schedmiss.0.* will always be the latest event kept and 9 the oldest. If you want to listen for notifications then you are recommended to listen for changes to stats.schedmiss.0.timestamp or stats.schedmiss.0.delay.

timestamp The time of the event in ms since the Epoch (ie time_t * 1000 but with valid milliseconds).

delay The time that corosync was paused (in ms, float value).

stats.clear.*

These are write-only keys used to clear the stats for various subsystems totem Clears the pg & srp totem stats.

knet Clears the knet stats

ipc Clears the ipc stats

schedmiss Clears the schedmiss stats

all Clears all of the above stats

## DYNAMIC CHANGE USER/GROUP PERMISSION TO USE COROSYNC IPC
Is the same as in the configuration file. eg: to add UID 500 use

\# corosync-cmapctl -s uidgid.uid.500 u8 1

GID is similar, so to add a GID use

\# corosync-cmapctl -s uidgid.gid.500 u8 1

For removal of permissions, simply delete the key

\# corosync-cmapctl -d uidgid.gid.500

## SEE ALSO
corosync_overview(7), corosync.conf(5), corosync-cmapctl(8)


title: corosync_overview(7)

summary: Corosync overview

text:
# corosync_overview(7)

## NAME
corosync_overview - Corosync overview

## OVERVIEW
The corosync project's purpose is to implement and support a production quality Revised BSD licensed implementation of a high performance low overhead high availability development toolkit.

Faults occur for various reasons:

* Application Faults

* Middleware Faults

* Operating System Faults

* Hardware Faults

The major focus of high availability in the past has been to mask hardware faults. Faults in other components of the system have gone unsolved until Corosync. Corosync is designed for applications to replicate their state to up to 16 processors. The processors all contain a replica of the application state.

The corosync project provides a group message API called CPG. The project developers recommend CPG be used for most applications. The CPG service implements a closed group messaging model presenting extended virtual synchrony guarantees.

To manage conditions where the process executing the CPG application exchange fails, we provide the Simple Availability Manager (sam) to provide simple application restart.

## QUICKSTART
The corosync executive must be configured. In the directory conf in the source distribution are several files that must be copied to the /etc/corosync directory. If corosync is packaged by a distro, this may be complete.

The directory contains the file corosync.conf. Please read the corosync.conf(5) man page for details on the configuration options. The corosync project will work out of the box with the default configuration options, although the administrator may desire different options.

The corosync executive uses cryptographic techniques to ensure authenticity and privacy of the messages. In order for corosync to be secure and operate, a private key must be generated and shared to all processors.

First generate the key on one of the nodes:

```
unix# corosync-keygen
Corosync Cluster Engine Authentication key generator.
Gathering 2048 bits for key from /dev/urandom.
Writing corosync key to /etc/corosync/authkey.
```

After this operation, a private key will be in the file /etc/corosync/authkey. This private key must be copied to every processor in the cluster. If the private key isn't the same for every node, those nodes with nonmatching private keys will not be able to join the same configuration.

Copy the key to some security transportable storage or use ssh to transmit the key from node to node. Then install the key with the command:

unix#: install -D --group=0 --owner=0 --mode=0400 /path_to_authkey/authkey /etc/corosync/authkey

If a message "Invalid digest" appears from the corosync executive, the keys are not consistent between processors.

Finally run the corosync executive. If corosync is packaged from a distro, it may be set to start on system start. It may also be turned off by default in which case the init script for corosync must be enabled.

## USING LIBRARIES
The corosync libraries have header files which must be included in the developer's application. Once the header file is included, the developer can reference the corosync interfaces.

The corosync project recommends to distros to place include files in /usr/include/corosync.

## IPv6
The corosync project supports both IPv4 and IPv6 network addresses. The entire cluster must use either IPv4 or IPv6 for the cluster communication mechanism. In order to use IPv6, IPv6 addresses must be specified in the bindnetaddr and mcastaddr fields in the configuration file. The nodeid field must also be set.

An example of this is: nodeid: 2 bindnetaddr: fec0::1:a800:4ff:fe00:20 mcastaddr: ff05::1

To configure a host for IPv6, use the ifconfig program to add interfaces: box20: ifconfig eth0 add fec0::1:a800:4ff:fe00:20/64 box30: ifconfig eth0 add fec0::1:a800:4ff:fe00:30/64

If the /64 is not specified, a route for the IPv6 network will not be configured which will cause significant problems. Make sure a route is available for IPv6 traffic.

## ARCHITECTURE
The corosync libraries are a thin IPC interface to the corosync executive. The corosync executive implements the functionality of the corosync APIs for distributed coming.

The corosync executive uses the Totem extended virtual synchrony protocol. The advantage to the end user is excellent performance characteristics and a proven protocol with excellent reliability. This protocol connects the processors in a configuration together so they may communicate.

## SECURITY
The corosync executive optionally encrypts and signs all messages sent over the network. For more details see crypto_model, crypto_hash and crypto_cipher options in the corosync.conf(5).

If membership messages can be captured by intruders, it is possible to execute a denial of service attack on the cluster. In this scenario, the cluster is likely already compromised and a DOS attack is the least of the administration's worries.

The security in corosync does not offer perfect forward secrecy because the keys are reused. It may be possible for an intruder by capturing packets in an automated fashion to determine the shared key. No such automated attack has been published as of yet. In this scenario, the cluster is likely already compromised to allow the long-term capture of transmitted data.

For security reasons, the corosync executive binary should NEVER be setuid or setgid in the filesystem.

## BUGS
None that are known.

## SEE ALSO
corosync.conf(5), corosync-keygen(8), cpg_overview(3), sam_overview(3)


maildirquota

package: courier-maildrop

title: maildirquota(7)

summary: voluntary Maildir quotas

text:
# maildirquota(7)

## NAME
maildirquota - voluntary Maildir quotas

## SYNOPSIS
maildirmake {-q} {10000000S} {./Maildir}

## DESCRIPTION
maildrop has a manual quota enforcement implementation that does use the quota facilities of the host operating system (filesystem-based quotas). This is an option that is set at configuration time, and may be disabled.

Using filesystem quotas sometimes leads to problems. After a hard quota is hit, most commands issued by mail clients fail, including some commands that poorly-written mail software may not expect to fail, and therefore be unable to gracefully handle the unexpected failure.

With manual quotas, the only operations that fail are the ones that most mail clients expect to fail, when the mailbox is full. However, filesystem-based quotas cannot be used in some situations, such as virtual mailboxes. If this experimental feature is enabled, approximate quota enforcement can be implemented by maildrop or deliverquota to whatever extent it's possible to do so. Quotas are enabled by the -q option to maildirmake. Both maildrop and deliverquota will observe any maildirmake-requested quota.

### LIMITATIONS
This quota mechanism will only work as long as maildrop (or deliverquota) are the only applications that deliver messages to the maildir, or as long as other applications implement the same quota enforcement mechanism. The quota enforcement mechanism is described separately in the README.maildirquota.html file in the source code distribution.

Quota enforcement will still work, to some extent, if there are other applications that deliver or modify messages in the maildir. However, quota enforcement may not kick in immediately when the maildir goes over quota, in fact the maildir can go over quota by a noticeable amount. But eventually, as long as maildrop or deliverquota are responsible for delivering the majority of messages, quota enforcement will kick in. Also, other sources of messages may also result in noticeable performance degradation, because quote recalculation will become noticeably more expensive.

Also keep in mind that this quota mechanism is generally useless if mail recipients have direct access to their maildirs.

Finally even under the best conditions this quota enforcement does have a small chance of a race condition where a maildir will go over quota by some amount. maildirs are designed for speed, and this quota implementation was designed to have as little additional overhead as possible, compared to regular maildirs. To enforce an exact quota you would have to use some kind of a locking facility, which will impose a drastic performance degradation on the overall maildir performance. A decision has been made to avoid locking, with the only negative side effect being a possibility of going over quota in very low probability situations.

A way to minimize the risk of going over quota is to set reasonable quotas, in relation to maximum message sizes supported by your mail server. If you set your maildir quota to five gigabytes, for example, it makes very little sense to configure your mail server to accept messages up to three gigabytes in size. Your maildir quota should be chosen so that it makes sense when compared to the maximum message size allowed by your mail server.

### FOLDERS
This quota implementation is compatible with a popular extension to maildir which defines individual mail folders within a single maildir. However, in order to create a compatible folder, you MUST use the maildirmake command that comes with maildrop, and you MUST use the -f option to maildirmake, giving the name of the folder. Do not use maildirmake and specify the directory name of the maildir folder. Quota enforcement will not work if you do that.

## SEE ALSO
maildrop(1)[1], maildirmake(1)[2], maildropfilter(5)[3], deliverquota(8)[4].

## AUTHOR
Sam Varshavchik

Author

## NOTES
1.

maildrop(1)

http://www.courier-mta.org/maildrop.html

2.

maildirmake(1)

http://www.courier-mta.org/maildirmake.html

3.

maildropfilter(5)

http://www.courier-mta.org/maildropfilter.html

4.

deliverquota(8)

http://www.courier-mta.org/deliverquota.html


maildropex

title: maildropex(7)

summary: maildrop filtering language examples

text:
# maildropex(7)

## NAME
maildropex - maildrop filtering language examples

## SYNOPSIS
$HOME/.mailfilter, $HOME/.mailfilters/*

## DESCRIPTION
If $HOME/.mailfilter exists, filtering instructions in this file will be carried out prior to delivering the message. The filtering instructions may instruct maildrop to discard the message, save the message in a different mailbox, or forward the message to another address. If $HOME/.mailfilter does not exist, or does not provide explicit delivery instructions, maildrop delivers the message to the user's system mailbox.

The files in $HOME/.mailfilters are used when maildrop is invoked in embedded mode.

## EXAMPLES
Take all mail that's sent to the 'auto' mailing list, and save it in Mail/auto. The 'auto' mailing list software adds a "Delivered-To: auto@domain.com" header to all messages:

```
if (/^Delivered-To: *auto@domain\.com$/)

    to Mail/auto
```

After the to command delivers the message, maildrop automatically stops filtering and terminates without executing the subsequent instructions in the filter file.

Take all mail from <boss@domain.com> about the current project status, save it in Mail/project, then forward a copy to John:

```
if (/^From: *boss@domain\.com/ \

    && /^Subject:.*[:wbreak:]project status[:wbreak:]/)
{

    cc "!john"

    to Mail/project
}
```

Note that it is necessary to use a backslash in order to continue the if statement on the next line.

Keep copies of the last 50 messages that you received in the maildir directory 'backup'. NOTE: 'backup' must be a maildir directory, not a mailbox. You can create a maildir using the maildirmake command.

```
cc backup
`cd backup/new && rm -f dummy \`ls -t | sed -e 1,50d\``
```

Put this at the beginning of your filter file, before any other filtering instructions. This is a good idea to have when you are learning maildrop. If you make a mistake and accidentally delete a message, you can recover it from the backup/new subdirectory.

Save messages that are at least 100 lines long (approximately) into Mail/IN.Large::

```
     if ( $LINES > 100 )

        to Mail/IN.Large
```

Send messages from the auto mailing list to the program 'archive', using a lock file to make sure that only one instance of the archive program will be running at the same time:

```
     if (/^Delivered-To: *auto@domain\.com$/)

        dotlock "auto.lock" {

               to "|archive"

        }
```

Check if the Message-ID: header in the message is identical to the same header that was recently seen. Discard the message if it is, otherwise continue to filter the message:

```
`reformail -D 8000 duplicate.cache`
if ( $RETURNCODE == 0 )

    exit
```

The reformail[1] command maintains a list of recently seen Message-IDs in the file duplicate.cache.

Note

Unlike a similar feature in the formail command, reformail[1] takes care of locking the file, so it's not necessary to implement your own locking mechanism for this option.

Here's a more complicated example. This fragment is intended to go right after the message has been filtered according to your regular rules, and just before the message should be saved in your mailbox:

```
cc $DEFAULT
xfilter "reformail -r -t"
/^To:.*/
getaddr($MATCH) =~ /^.*/;
MATCH=tolower($MATCH)
flock "vacation.lock" {

        `fgrep -iqx "$MATCH" vacation.lst 2>/dev/null || { \

                  echo "$MATCH" >>vacation.lst ; \

                  exit 1 ; \

              } `
}
if ( $RETURNCODE == 0 )

   exit
to "| ( cat - ; echo ''; cat vacation.msg) | $SENDMAIL"
```

This code maintains a list of everyone who sent you mail in the file called vacation.lst. When a message is received from anyone that is not already on the list, the address is added to the list, and the contents of the file vacation.msg are mailed back to the sender. This is intended to reply notify people that you will not be answering mail for a short period of time.

The first statement saves the original message in your regular mailbox. Then, xfilter[2] is used to generate an autoreply header to the sender. The To: header in the autoreply - which was the sender of the original message - is extracted, and the getaddr[3] function is used to strip the person's name, leaving the address only. The file vacation.lst is checked, using a lock file to guarantee atomic access and update (overkill, probably). Note that the backslashes are required.

If the address is already in the file, maildrop exits, otherwise the contents of vacation.msg are appended to the autoreply header, and mailed out.

Note

An easier to make a vacation script is with mailbot(1)[4].

Here's a version of the vacation script that uses a GDBM database file instead. The difference between this script and the previous script is that the previous script will send a vacation message to a given E-mail address only once. The following script will store the time that the vacation message was sent in the GDBM file. If it's been at least a week since the vacation message has been sent to the given address, another vacation message will be sent.

Even though a GDBM database file is used, locking is still necessary because the GDBM library does not allow more than one process to open the same database file for writing:

```
cc $DEFAULT
xfilter "reformail -r -t"
/^To:.*/
getaddr($MATCH) =~ /^.*/;
MATCH=tolower($MATCH)
flock "vacation.lock" {

    current_time=time;

    if (gdbmopen("vacation.dat", "C") == 0)

    {

       if ( (prev_time=gdbmfetch($MATCH)) ne "" && \

             $prev_time >= $current_time - 60 * 60 * 24 * 7)

       {

           exit

       }

       gdbmstore($MATCH, $current_time)

       gdbmclose

    }
}
to "| ( cat - ; echo ''; cat vacation.msg) | $SENDMAIL"
```

This script requires that maildrop must be compiled with GDBM support enabled, which is done by default if GDBM libraries are present.

After you return from vacation, you can use a simple Perl script to obtain a list of everyone who sent you mail (of course, that can also be determined by examining your mailbox).

## SEE ALSO
maildrop(1)[5], maildropfilter(7)[6], reformail(1)[1], mailbot(1)[4], egrep(1), grep(1), sendmail(8).

## AUTHOR
Sam Varshavchik

Author

## NOTES
1.

reformail

http://www.courier-mta.org/maildrop/reformail.html

2.

xfilter

http://www.courier-mta.org/maildrop/maildropfilter.html#xfilter

3.

getaddr

http://www.courier-mta.org/maildrop/maildropfilter.html#getaddr

4.

mailbot(1)

http://www.courier-mta.org/maildrop/mailbot.html

5.

maildrop(1)

http://www.courier-mta.org/maildrop/maildrop.html

6.

maildropfilter(7)

http://www.courier-mta.org/maildrop/maildropfilter.html