b780f49ccf
each readme starts with the plugin's name as a header, this needs to be chopped off to provide a good manual page. Signed-off-by: Miek Gieben <miek@miek.nl>
64 lines
1.9 KiB
Groff
64 lines
1.9 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.nl
|
|
.TH "COREDNS-METADATA" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH NAME
|
|
.PP
|
|
\fImetadata\fP - enable a meta data collector.
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
By enabling \fImetadata\fP any plugin that implements metadata.Provider
|
|
interface
|
|
\[la]https://godoc.org/github.com/coredns/coredns/plugin/metadata#Provider\[ra] will be called for
|
|
each DNS query, at beginning of the process for that query, in order to add it's own meta data to
|
|
context.
|
|
|
|
.PP
|
|
The meta data 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.
|
|
|
|
.PP
|
|
The meta data is added by setting a label with a value in the context. These labels should be named
|
|
\fB\fCplugin/NAME\fR, where \fBNAME\fP is something descriptive. The only hard requirement the \fImetadata\fP
|
|
plugin enforces is that the labels contains a slash. See the documentation for
|
|
\fB\fCmetadata.SetValueFunc\fR.
|
|
|
|
.PP
|
|
The value stored is a string. The empty string signals "no meta data". See the documentation for
|
|
\fB\fCmetadata.ValueFunc\fR on how to retrieve this.
|
|
|
|
.SH SYNTAX
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
metadata [ZONES... ]
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBZONES\fP zones metadata should be invoked for.
|
|
|
|
|
|
.SH PLUGINS
|
|
.PP
|
|
\fB\fCmetadata.Provider\fR 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.
|
|
|
|
.PP
|
|
Note: this method should work quickly, because it is called for every request.
|
|
|
|
.SH EXAMPLES
|
|
.PP
|
|
The \fIrewrite\fP plugin uses meta data to rewrite requests.
|
|
|
|
.SH ALSO SEE
|
|
.PP
|
|
The Provider interface
|
|
\[la]https://godoc.org/github.com/coredns/coredns/plugin/metadata#Provider\[ra] and
|
|
the package level
|
|
\[la]https://godoc.org/github.com/coredns/coredns/plugin/metadata\[ra] documentation.
|
|
|