165 lines
5.3 KiB
Groff
165 lines
5.3 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-CACHE" 7 "March 2021" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIcache\fP - enables a frontend cache.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
With \fIcache\fP enabled, all records except zone transfers and metadata records will be cached for up to
|
|
3600s. Caching is mostly useful in a scenario when fetching data from the backend (upstream,
|
|
database, etc.) is expensive.
|
|
|
|
.PP
|
|
\fICache\fP will change the query to enable DNSSEC (DNSSEC OK; DO) if it passes through the plugin. If
|
|
the client didn't request any DNSSEC (records), these are filtered out when replying.
|
|
|
|
.PP
|
|
This plugin can only be used once per Server Block.
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
cache [TTL] [ZONES...]
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBTTL\fP max TTL in seconds. If not specified, the maximum TTL will be used, which is 3600 for
|
|
NOERROR responses and 1800 for denial of existence ones.
|
|
Setting a TTL of 300: \fB\fCcache 300\fR would cache records up to 300 seconds.
|
|
.IP \(bu 4
|
|
\fBZONES\fP zones it should cache for. If empty, the zones from the configuration block are used.
|
|
|
|
|
|
.PP
|
|
Each element in the cache is cached according to its TTL (with \fBTTL\fP as the max).
|
|
A cache is divided into 256 shards, each holding up to 39 items by default - for a total size
|
|
of 256 * 39 = 9984 items.
|
|
|
|
.PP
|
|
If you want more control:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
cache [TTL] [ZONES...] {
|
|
success CAPACITY [TTL] [MINTTL]
|
|
denial CAPACITY [TTL] [MINTTL]
|
|
prefetch AMOUNT [[DURATION] [PERCENTAGE%]]
|
|
serve\_stale [DURATION]
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBTTL\fP and \fBZONES\fP as above.
|
|
.IP \(bu 4
|
|
\fB\fCsuccess\fR, override the settings for caching successful responses. \fBCAPACITY\fP indicates the maximum
|
|
number of packets we cache before we start evicting (\fIrandomly\fP). \fBTTL\fP overrides the cache maximum TTL.
|
|
\fBMINTTL\fP overrides the cache minimum TTL (default 5), which can be useful to limit queries to the backend.
|
|
.IP \(bu 4
|
|
\fB\fCdenial\fR, override the settings for caching denial of existence responses. \fBCAPACITY\fP indicates the maximum
|
|
number of packets we cache before we start evicting (LRU). \fBTTL\fP overrides the cache maximum TTL.
|
|
\fBMINTTL\fP overrides the cache minimum TTL (default 5), which can be useful to limit queries to the backend.
|
|
There is a third category (\fB\fCerror\fR) but those responses are never cached.
|
|
.IP \(bu 4
|
|
\fB\fCprefetch\fR will prefetch popular items when they are about to be expunged from the cache.
|
|
Popular means \fBAMOUNT\fP queries have been seen with no gaps of \fBDURATION\fP or more between them.
|
|
\fBDURATION\fP defaults to 1m. Prefetching will happen when the TTL drops below \fBPERCENTAGE\fP,
|
|
which defaults to \fB\fC10%\fR, or latest 1 second before TTL expiration. Values should be in the range \fB\fC[10%, 90%]\fR.
|
|
Note the percent sign is mandatory. \fBPERCENTAGE\fP is treated as an \fB\fCint\fR.
|
|
.IP \(bu 4
|
|
\fB\fCserve_stale\fR, when serve_stale is set, cache always will serve an expired entry to a client if there is one
|
|
available. When this happens, cache will attempt to refresh the cache entry after sending the expired cache
|
|
entry to the client. The responses have a TTL of 0. \fBDURATION\fP is how far back to consider
|
|
stale responses as fresh. The default duration is 1h.
|
|
|
|
|
|
.SH "CAPACITY AND EVICTION"
|
|
.PP
|
|
If \fBCAPACITY\fP \fIis not\fP specified, the default cache size is 9984 per cache. The minimum allowed cache size is 1024.
|
|
If \fBCAPACITY\fP \fIis\fP specified, the actual cache size used will be rounded down to the nearest number divisible by 256 (so all shards are equal in size).
|
|
|
|
.PP
|
|
Eviction is done per shard. In effect, when a shard reaches capacity, items are evicted from that shard.
|
|
Since shards don't fill up perfectly evenly, evictions will occur before the entire cache reaches full capacity.
|
|
Each shard capacity is equal to the total cache size / number of shards (256). Eviction is random, not TTL based.
|
|
Entries with 0 TTL will remain in the cache until randomly evicted when the shard reaches capacity.
|
|
|
|
.SH "METRICS"
|
|
.PP
|
|
If monitoring is enabled (via the \fIprometheus\fP plugin) then the following metrics are exported:
|
|
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_cache_entries{server, type}\fR - Total elements in the cache by cache type.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_cache_hits_total{server, type}\fR - Counter of cache hits by cache type.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_cache_misses_total{server}\fR - Counter of cache misses.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_cache_prefetch_total{server}\fR - Counter of times the cache has prefetched a cached item.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_cache_drops_total{server}\fR - Counter of responses excluded from the cache due to request/response question name mismatch.
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_cache_served_stale_total{server}\fR - Counter of requests served from stale cache entries.
|
|
|
|
|
|
.PP
|
|
Cache types are either "denial" or "success". \fB\fCServer\fR is the server handling the request, see the
|
|
prometheus plugin for documentation.
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Enable caching for all zones, but cap everything to a TTL of 10 seconds:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
cache 10
|
|
whoami
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Proxy to Google Public DNS and only cache responses for example.org (or below).
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
forward . 8.8.8.8:53
|
|
cache example.org
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Enable caching for \fB\fCexample.org\fR, keep a positive cache size of 5000 and a negative cache size of 2500:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
example.org {
|
|
cache {
|
|
success 5000
|
|
denial 2500
|
|
}
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|