diff options
Diffstat (limited to 'plugin.md')
| -rw-r--r-- | plugin.md | 33 |
1 files changed, 33 insertions, 0 deletions
@@ -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: * <https://blog.coredns.io/2017/03/01/how-to-add-plugins-to-coredns/> * <https://blog.coredns.io/2016/12/19/writing-plugin-for-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 |