From 3b4235a7c62dc05a04eb5097c50c8a83b937ae8e Mon Sep 17 00:00:00 2001 From: Miek Gieben Date: Sat, 27 Jan 2018 20:35:52 +0000 Subject: [PATCH] plugin.md updates (#1451) * plugin.md updates Talk about return code, logging and other bits. Also checked the code for fmt.Printf logging, there is none. Fixes #1449 #1450 * review * more typos --- plugin.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/plugin.md b/plugin.md index 28168f241..f5f950884 100644 --- a/plugin.md +++ b/plugin.md @@ -2,11 +2,44 @@ ## Writing Plugins +The main method that gets called is `ServeDNS`. It has three parameters: + +* a `context.Context`; +* `dns.ResponseWriter` that is, basically, the client's connection; +* `*dns.Msg` the request from the client. + +`ServeDNS` returns two values, a response code and an error. If the error is not nil CoreDNS +will return a generic SERVFAIL to the client. The response code tells CoreDNS if a reply has been +written by the plugin chain or not. In the latter case CoreDNS will take care of that. + +CoreDNS treats: + +* SERVFAIL (dns.RcodeServerFailure) +* REFUSED (dns.RcodeRefused) +* FORMERR (dns.RcodeFormatError) +* NOTIMP (dns.RcodeNotImplemented) + +as special and will then assume *nothing* has been written to the client. In all other cases it +assumes something has been written to the client (by the plugin). + +The [*example*](https://github.com/coredns/example) plugin shows a bare-bones implementation that +can be used as a starting point for your plugin. + +## Hooking It Up + See a couple of blog posts on how to write and add plugin to CoreDNS: * * , slightly older, but useful. +## Logging + +If your plugin needs to output a log line you should use the `log` package. CoreDNS does not +implement log levels. The standard way of outputing is: `log.Printf("[LEVEL] ...")`, and LEVEL +can be: `INFO`, `WARNING` or `ERROR`. +In general, logging should be left to the higher layers by returning an error. However, if there is +a reason to consume the error but notify the user, then logging in the plugin can be acceptable. + ## Metrics When exporting metrics the *Namespace* should be `plugin.Namespace` (="coredns"), and the