plugin

Documentation

Overview

Package plugin provides some types and functions common among plugin.

Index

• Constants
• Variables
• func A(ctx context.Context, b ServiceBackend, zone string, state request.Request, ...) (records []dns.RR, err error)
• func AAAA(ctx context.Context, b ServiceBackend, zone string, state request.Request, ...) (records []dns.RR, err error)
• func BackendError(ctx context.Context, b ServiceBackend, zone string, rcode int, ...) (int, error)
• func CNAME(ctx context.Context, b ServiceBackend, zone string, state request.Request, ...) (records []dns.RR, err error)
• func ClientWrite(rcode int) bool
• func Error(name string, err error) error
• func MX(ctx context.Context, b ServiceBackend, zone string, state request.Request, ...) (records, extra []dns.RR, err error)
• func NS(ctx context.Context, b ServiceBackend, zone string, state request.Request, ...) (records, extra []dns.RR, err error)
• func NextOrFailure(ctx context.Context, name string, next Handler, w dns.ResponseWriter, ...) (int, error)
• func PTR(ctx context.Context, b ServiceBackend, zone string, state request.Request, ...) (records []dns.RR, err error)
• func SOA(ctx context.Context, b ServiceBackend, zone string, state request.Request, ...) ([]dns.RR, error)
• func SRV(ctx context.Context, b ServiceBackend, zone string, state request.Request, ...) (records, extra []dns.RR, err error)
• func SplitHostPort(s string) (host, port string, ipnet *net.IPNet, err error)
• func TXT(ctx context.Context, b ServiceBackend, zone string, state request.Request, ...) (records []dns.RR, err error)
• type Handler
• type HandlerFunc
  • func (f HandlerFunc) Name() string
  • func (f HandlerFunc) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
• type Host
  • func (h Host) Normalize() string
• type Name
  • func (n Name) Matches(child string) bool
  • func (n Name) Normalize() string
• type Options
• type Plugin
• type ServiceBackend
• type Transferer
• type Zones
  • func (z Zones) Matches(qname string) string
  • func (z Zones) Normalize()

Constants

const Namespace = "coredns"

Namespace is the namespace used for the metrics.

Variables

var Directives = []string{
	"metadata",
	"cancel",
	"tls",
	"reload",
	"nsid",
	"root",
	"bind",
	"debug",
	"trace",
	"ready",
	"health",
	"pprof",
	"prometheus",
	"errors",
	"log",
	"dnstap",
	"chaos",
	"loadbalance",
	"cache",
	"rewrite",
	"dnssec",
	"autopath",
	"template",
	"hosts",
	"route53",
	"federation",
	"k8s_external",
	"kubernetes",
	"file",
	"auto",
	"secondary",
	"etcd",
	"rdns",
	"loop",
	"forward",
	"grpc",
	"erratic",
	"whoami",
	"on",
}

Directives are registered in the order they should be executed.

Ordering is VERY important. Every plugin will feel the effects of all other plugin below (after) them during a request, but they must not care what plugin above them are doing.

var ErrOnce = errors.New("this plugin can only be used once per Server Block")

ErrOnce is returned when a plugin doesn't support multiple setups per server.

var TimeBuckets = prometheus.ExponentialBuckets(0.00025, 2, 16) // from 0.25ms to 8 seconds

TimeBuckets is based on Prometheus client_golang prometheus.DefBuckets

Functions

func A

func A(ctx context.Context, b ServiceBackend, zone string, state request.Request, previousRecords []dns.RR, opt Options) (records []dns.RR, err error)

A returns A records from Backend or an error.

func AAAA

func AAAA(ctx context.Context, b ServiceBackend, zone string, state request.Request, previousRecords []dns.RR, opt Options) (records []dns.RR, err error)

AAAA returns AAAA records from Backend or an error.

func BackendError

func BackendError(ctx context.Context, b ServiceBackend, zone string, rcode int, state request.Request, err error, opt Options) (int, error)

BackendError writes an error response to the client.

func CNAME

func CNAME(ctx context.Context, b ServiceBackend, zone string, state request.Request, opt Options) (records []dns.RR, err error)

CNAME returns CNAME records from the backend or an error.

func ClientWrite

func ClientWrite(rcode int) bool

ClientWrite returns true if the response has been written to the client. Each plugin to adhire to this protocol.

func Error

func Error(name string, err error) error

Error returns err with 'plugin/name: ' prefixed to it.

func MX

func MX(ctx context.Context, b ServiceBackend, zone string, state request.Request, opt Options) (records, extra []dns.RR, err error)

MX returns MX records from the Backend. If the Target is not a name but an IP address, a name is created on the fly.

func NS

func NS(ctx context.Context, b ServiceBackend, zone string, state request.Request, opt Options) (records, extra []dns.RR, err error)

NS returns NS records from the backend

func NextOrFailure

func NextOrFailure(ctx context.Context, name string, next Handler, w dns.ResponseWriter, r *dns.Msg) (int, error)

NextOrFailure calls next.ServeDNS when next is not nil, otherwise it will return, a ServerFailure and a nil error.

func PTR

func PTR(ctx context.Context, b ServiceBackend, zone string, state request.Request, opt Options) (records []dns.RR, err error)

PTR returns the PTR records from the backend, only services that have a domain name as host are included.

func SOA

func SOA(ctx context.Context, b ServiceBackend, zone string, state request.Request, opt Options) ([]dns.RR, error)

SOA returns a SOA record from the backend.

func SRV

func SRV(ctx context.Context, b ServiceBackend, zone string, state request.Request, opt Options) (records, extra []dns.RR, err error)

SRV returns SRV records from the Backend. If the Target is not a name but an IP address, a name is created on the fly.

func SplitHostPort

func SplitHostPort(s string) (host, port string, ipnet *net.IPNet, err error)

SplitHostPort splits s up in a host and port portion, taking reverse address notation into account. String the string s should *not* be prefixed with any protocols, i.e. dns://. The returned ipnet is the *net.IPNet that is used when the zone is a reverse and a netmask is given.

func TXT

func TXT(ctx context.Context, b ServiceBackend, zone string, state request.Request, opt Options) (records []dns.RR, err error)

TXT returns TXT records from Backend or an error.

Types

type Handler

type Handler interface {
	ServeDNS(context.Context, dns.ResponseWriter, *dns.Msg) (int, error)
	Name() string
}

Handler is like dns.Handler except ServeDNS may return an rcode and/or error.

If ServeDNS writes to the response body, it should return a status code. If the status code is not one of the following:

* SERVFAIL (dns.RcodeServerFailure)

* REFUSED (dns.RecodeRefused)

* FORMERR (dns.RcodeFormatError)

* NOTIMP (dns.RcodeNotImplemented)

CoreDNS assumes *no* reply has yet been written. All other response codes signal other handlers above it that the response message is already written, and that they should not write to it also.

If ServeDNS encounters an error, it should return the error value so it can be logged by designated error-handling plugin.

If writing a response after calling another ServeDNS method, the returned rcode SHOULD be used when writing the response.

If handling errors after calling another ServeDNS method, the returned error value SHOULD be logged or handled accordingly.

Otherwise, return values should be propagated down the plugin chain by returning them unchanged.

type HandlerFunc

type HandlerFunc func(context.Context, dns.ResponseWriter, *dns.Msg) (int, error)

HandlerFunc is a convenience type like dns.HandlerFunc, except ServeDNS returns an rcode and an error. See Handler documentation for more information.

func (HandlerFunc) Name

func (f HandlerFunc) Name() string

Name implements the Handler interface.

func (HandlerFunc) ServeDNS

func (f HandlerFunc) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

ServeDNS implements the Handler interface.

type Host

type Host string

Host represents a host from the Corefile, may contain port.

func (Host) Normalize

func (h Host) Normalize() string

Normalize will return the host portion of host, stripping of any port or transport. The host will also be fully qualified and lowercased.

type Name

type Name string

Name represents a domain name.

func (Name) Matches

func (n Name) Matches(child string) bool

Matches checks to see if other is a subdomain (or the same domain) of n. This method assures that names can be easily and consistently matched.

func (Name) Normalize

func (n Name) Normalize() string

Normalize lowercases and makes n fully qualified.

type Options

type Options struct{}

Options are extra options that can be specified for a lookup.

type Plugin

type Plugin func(Handler) Handler

Plugin is a middle layer which represents the traditional idea of plugin: it chains one Handler to the next by being passed the next Handler in the chain.

type ServiceBackend

type ServiceBackend interface {
	// Services communicates with the backend to retrieve the service definitions. Exact indicates
	// on exact match should be returned.
	Services(ctx context.Context, state request.Request, exact bool, opt Options) ([]msg.Service, error)

	// Reverse communicates with the backend to retrieve service definition based on a IP address
	// instead of a name. I.e. a reverse DNS lookup.
	Reverse(ctx context.Context, state request.Request, exact bool, opt Options) ([]msg.Service, error)

	// Lookup is used to find records else where.
	Lookup(ctx context.Context, state request.Request, name string, typ uint16) (*dns.Msg, error)

	// Returns _all_ services that matches a certain name.
	// Note: it does not implement a specific service.
	Records(ctx context.Context, state request.Request, exact bool) ([]msg.Service, error)

	// IsNameError return true if err indicated a record not found condition
	IsNameError(err error) bool

	Transferer
}

ServiceBackend defines a (dynamic) backend that returns a slice of service definitions.

type Transferer

type Transferer interface {
	// Serial returns a SOA serial number to construct a SOA record.
	Serial(state request.Request) uint32

	// MinTTL returns the minimum TTL to be used in the SOA record.
	MinTTL(state request.Request) uint32

	// Transfer handles a zone transfer it writes to the client just
	// like any other handler.
	Transfer(ctx context.Context, state request.Request) (int, error)
}

Transferer defines an interface for backends that provide AXFR of all records.

type Zones

type Zones []string

Zones respresents a lists of zone names.

func (Zones) Matches

func (z Zones) Matches(qname string) string

Matches checks if qname is a subdomain of any of the zones in z. The match will return the most specific zones that matches. The empty string signals a not found condition.

func (Zones) Normalize

func (z Zones) Normalize()

Normalize fully qualifies all zones in z. The zones in Z must be domain names, without a port or protocol prefix.