diff options
| -rw-r--r-- | man/coredns-metadata.7 | 44 | ||||
| -rw-r--r-- | man/coredns-rewrite.7 | 27 | ||||
| -rw-r--r-- | plugin/metadata/README.md | 21 | ||||
| -rw-r--r-- | plugin/metadata/metadata_test.go | 7 | ||||
| -rw-r--r-- | plugin/metadata/provider.go | 2 |
5 files changed, 86 insertions, 15 deletions
diff --git a/man/coredns-metadata.7 b/man/coredns-metadata.7 new file mode 100644 index 000000000..168df6f7e --- /dev/null +++ b/man/coredns-metadata.7 @@ -0,0 +1,44 @@ +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 +. +.TH "COREDNS\-METADATA" "7" "July 2018" "CoreDNS" "CoreDNS plugins" +. +.SH "NAME" +\fImetadata\fR \- enable a meta data collector\. +. +.SH "DESCRIPTION" +By enabling \fImetadata\fR any plugin that implements metadata\.Provider interface \fIhttps://godoc\.org/github\.com/coredns/coredns/plugin/metadata#Provider\fR 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\. +. +.P +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\. +. +.P +The meta data is added by setting a label with a value in the context\. These labels should be named \fBplugin/NAME\fR, where \fBNAME\fR is something descriptive\. The only hard requirement the \fImetadata\fR plugin enforces is that the labels contains a slash\. See the documentation for \fBmetadata\.SetValueFunc\fR\. +. +.P +The value stored is a string\. The empty string signals "no meta data"\. See the documentation for \fBmetadata\.ValueFunc\fR on how to retrieve this\. +. +.SH "SYNTAX" +. +.nf + +metadata [ZONES\.\.\. ] +. +.fi +. +.IP "\(bu" 4 +\fBZONES\fR zones metadata should be invoked for\. +. +.IP "" 0 +. +.SH "PLUGINS" +\fBmetadata\.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\. +. +.P +Note: this method should work quickly, because it is called for every request\. +. +.SH "EXAMPLES" +The \fIrewrite\fR plugin uses meta data to rewrite requests\. +. +.SH "ALSO SEE" +The Provider interface \fIhttps://godoc\.org/github\.com/coredns/coredns/plugin/metadata#Provider\fR and the package level \fIhttps://godoc\.org/github\.com/coredns/coredns/plugin/metadata\fR documentation\. diff --git a/man/coredns-rewrite.7 b/man/coredns-rewrite.7 index d833f107a..e3cc97187 100644 --- a/man/coredns-rewrite.7 +++ b/man/coredns-rewrite.7 @@ -306,12 +306,16 @@ rewrites the first local option with code 0xffee, setting the data to "abcd"\. E . .IP "" 0 . -.TP -A variable data is specified with a pair of curly brackets \fB{}\fR\. Following are the supported variables -{qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}\. +.IP "\(bu" 4 +A variable data is specified with a pair of curly brackets \fB{}\fR\. Following are the supported variables: {qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}\. +. +.IP "\(bu" 4 +If the metadata plugin is enabled, then labels are supported as variables if they are presented within curly brackets\. the variable data will be filled with the value associated with that label\. If that label is not provided, the variable will be silently substitute by an empty string\. +. +.IP "" 0 . .P -Example: +Examples: . .IP "" 4 . @@ -323,6 +327,21 @@ rewrite edns0 local set 0xffee {client_ip} . .IP "" 0 . +.P +The following example uses metadata and an imaginary "some\-plugin" that would provide "some\-label" as metadata information\. +. +.IP "" 4 +. +.nf + +metadata +some\-plugin +rewrite edns0 local set 0xffee {some\-plugin/some\-label} +. +.fi +. +.IP "" 0 +. .SS "EDNS0_NSID" This has no fields; it will add an NSID option with an empty string for the NSID\. If the option already exists and the action is \fBreplace\fR or \fBset\fR, then the NSID in the option will be set to the empty string\. . diff --git a/plugin/metadata/README.md b/plugin/metadata/README.md index aaf3375b1..55aa4d41b 100644 --- a/plugin/metadata/README.md +++ b/plugin/metadata/README.md @@ -8,15 +8,20 @@ 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 beginning of the process for that query, in order to add it's own Metadata to +each DNS query, at beginning of the process for that query, in order to add it's own meta data 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 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. -TODO: write about naming of the keys (labels). -TODO: write about extracting and using +The meta data 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 contains a slash. See the documentation for +`metadata.SetValueFunc`. + +The value stored is a string. The empty string signals "no meta data". See the documentation for +`metadata.ValueFunc` on how to retrieve this. ## Syntax @@ -28,7 +33,7 @@ metadata [ZONES... ] ## Plugins -metadata.Provider interface needs to be implemented by each plugin willing to provide metadata +`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. @@ -36,7 +41,7 @@ Note: this method should work quickly, because it is called for every request. ## Examples -There are currently no in tree plugins that write or use metadata. +The *rewrite* plugin uses meta data to rewrite requests. ## Also See diff --git a/plugin/metadata/metadata_test.go b/plugin/metadata/metadata_test.go index 08d9b6734..be20f8770 100644 --- a/plugin/metadata/metadata_test.go +++ b/plugin/metadata/metadata_test.go @@ -68,20 +68,23 @@ func TestLabelFormat(t *testing.T) { label string isValid bool }{ + // ok {"plugin/LABEL", true}, {"p/LABEL", true}, {"plugin/L", true}, + // fails {"LABEL", false}, {"plugin.LABEL", false}, {"/NO-PLUGIN-NOT-ACCEPTED", false}, {"ONLY-PLUGIN-NOT-ACCEPTED/", false}, {"PLUGIN/LABEL/SUB-LABEL", false}, {"/", false}, + {"//", false}, } for _, test := range labels { - if IsLabel(test.label) != test.isValid { - t.Errorf("Label %v is expected to have this validaty : %v - and has the opposite", test.label, test.isValid) + if x := IsLabel(test.label); x != test.isValid { + t.Errorf("Label %v expected %v, got: %v", test.label, test.isValid, x) } } } diff --git a/plugin/metadata/provider.go b/plugin/metadata/provider.go index 276a44127..cdb9c878a 100644 --- a/plugin/metadata/provider.go +++ b/plugin/metadata/provider.go @@ -49,7 +49,7 @@ type Provider interface { // Func is the type of function in the metadata, when called they return the value of the label. type Func func() string -// IsLabel check that the provided name looks like a valid label name +// IsLabel checks that the provided name is a valid label name, i.e. two words separated by a slash. func IsLabel(label string) bool { p := strings.Index(label, "/") if p <= 0 || p >= len(label)-1 { |