dnsserver

Documentation

Overview

Package dnsserver implements all the interfaces from Caddy, so that CoreDNS can be a servertype plugin.

Index

• Constants
• Variables
• func DefaultErrorFunc(w dns.ResponseWriter, r *dns.Msg, rc int)
• func GetMiddleware(c *caddy.Controller, name string) middleware.Handler
• func RegisterDevDirective(name, before string)
• func Transport(s string) string
• type Config
  • func GetConfig(c *caddy.Controller) *Config
  • func (c *Config) AddMiddleware(m middleware.Middleware)
• type Server
  • func NewServer(addr string, group []*Config) (*Server, error)
  • func (s *Server) Address() string
  • func (s *Server) Listen() (net.Listener, error)
  • func (s *Server) ListenPacket() (net.PacketConn, error)
  • func (s *Server) OnStartupComplete()
  • func (s *Server) Serve(l net.Listener) error
  • func (s *Server) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg)
  • func (s *Server) ServePacket(p net.PacketConn) error
  • func (s *Server) Stop() (err error)
  • func (s *Server) Tracer() ot.Tracer
• type ServerTLS
  • func NewServerTLS(addr string, group []*Config) (*ServerTLS, error)
  • func (s *ServerTLS) Listen() (net.Listener, error)
  • func (s *ServerTLS) ListenPacket() (net.PacketConn, error)
  • func (s *ServerTLS) OnStartupComplete()
  • func (s *ServerTLS) Serve(l net.Listener) error
  • func (s *ServerTLS) ServePacket(p net.PacketConn) error
• type ServergRPC
  • func NewServergRPC(addr string, group []*Config) (*ServergRPC, error)
  • func (s *ServergRPC) Listen() (net.Listener, error)
  • func (s *ServergRPC) ListenPacket() (net.PacketConn, error)
  • func (s *ServergRPC) OnStartupComplete()
  • func (s *ServergRPC) Query(ctx context.Context, in *pb.DnsPacket) (*pb.DnsPacket, error)
  • func (s *ServergRPC) Serve(l net.Listener) error
  • func (s *ServergRPC) ServePacket(p net.PacketConn) error
  • func (s *ServergRPC) Shutdown() error
  • func (s *ServergRPC) Stop() (err error)

Constants

const (
	TransportDNS  = "dns"
	TransportTLS  = "tls"
	TransportGRPC = "grpc"
)

Supported transports.

const (
	// DefaultPort is the default port.
	DefaultPort = "53"
	// TLSPort is the default port for DNS-over-TLS.
	TLSPort = "853"
	// GRPCPort is the default port for DNS-over-gRPC.
	GRPCPort = "443"
)

Variables

var (
	// Port is the port we listen on by default.
	Port = DefaultPort

	// GracefulTimeout is the maximum duration of a graceful shutdown.
	GracefulTimeout time.Duration
)

These "soft defaults" are configurable by command line flags, etc.

var (
	// Quiet mode will not show any informative output on initialization.
	Quiet bool
)

Functions

func DefaultErrorFunc

func DefaultErrorFunc(w dns.ResponseWriter, r *dns.Msg, rc int)

DefaultErrorFunc responds to an DNS request with an error.

func GetMiddleware

func GetMiddleware(c *caddy.Controller, name string) middleware.Handler

GetMiddleware returns the middleware handler that has been added to the config under name. This is useful to inspect if a certain middleware is active in this server. Note that this is order dependent and the order is defined in directives.go, i.e. if your middleware comes before the middleware you are checking; it will not be there (yet).

func RegisterDevDirective

func RegisterDevDirective(name, before string)

RegisterDevDirective splices name into the list of directives immediately before another directive. This function is ONLY for plugin development purposes! NEVER use it for a plugin that you are not currently building. If before is empty, the directive will be appended to the end of the list.

It is imperative that directives execute in the proper order, and hard-coding the list of directives guarantees a correct, absolute order every time. This function is convenient when developing a plugin, but it does not guarantee absolute ordering. Multiple plugins registering directives with this function will lead to non- deterministic builds and buggy software.

Directive names must be lower-cased and unique. Any errors here are fatal, and even successful calls print a message to stdout as a reminder to use it only in development.

func Transport

func Transport(s string) string

Transport returns the protocol of the string s

Types

type Config

type Config struct {
	// The zone of the site.
	Zone string

	// The hostname to bind listener to, defaults to the wildcard address
	ListenHost string

	// The port to listen on.
	Port string

	// Root points to a base directory we we find user defined "things".
	// First consumer is the file middleware to looks for zone files in this place.
	Root string

	// Debug controls the panic/recover mechanism that is enabled by default.
	Debug bool

	// The transport we implement, normally just "dns" over TCP/UDP, but could be
	// DNS-over-TLS or DNS-over-gRPC.
	Transport string

	// TLSConfig when listening for encrypted connections (gRPC, DNS-over-TLS).
	TLSConfig *tls.Config

	// Middleware stack.
	Middleware []middleware.Middleware
	// contains filtered or unexported fields
}

Config configuration for a single server.

func GetConfig

func GetConfig(c *caddy.Controller) *Config

GetConfig gets the Config that corresponds to c. If none exist nil is returned.

func (*Config) AddMiddleware

func (c *Config) AddMiddleware(m middleware.Middleware)

AddMiddleware adds a middleware to a site's middleware stack.

type Server

type Server struct {
	Addr string // Address we listen on
	// contains filtered or unexported fields
}

Server represents an instance of a server, which serves DNS requests at a particular address (host and port). A server is capable of serving numerous zones on the same address and the listener may be stopped for graceful termination (POSIX only).

func NewServer

func NewServer(addr string, group []*Config) (*Server, error)

NewServer returns a new CoreDNS server and compiles all middleware in to it.

func (*Server) Address

func (s *Server) Address() string

Address together with Stop() implement caddy.GracefulServer.

func (*Server) Listen

func (s *Server) Listen() (net.Listener, error)

Listen implements caddy.TCPServer interface.

func (*Server) ListenPacket

func (s *Server) ListenPacket() (net.PacketConn, error)

ListenPacket implements caddy.UDPServer interface.

func (*Server) OnStartupComplete

func (s *Server) OnStartupComplete()

OnStartupComplete lists the sites served by this server and any relevant information, assuming Quiet is false.

func (*Server) Serve

func (s *Server) Serve(l net.Listener) error

Serve starts the server with an existing listener. It blocks until the server stops. This implements caddy.TCPServer interface.

func (*Server) ServeDNS

func (s *Server) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg)

ServeDNS is the entry point for every request to the address that s is bound to. It acts as a multiplexer for the requests zonename as defined in the request so that the correct zone (configuration and middleware stack) will handle the request.

func (*Server) ServePacket

func (s *Server) ServePacket(p net.PacketConn) error

ServePacket starts the server with an existing packetconn. It blocks until the server stops. This implements caddy.UDPServer interface.

func (*Server) Stop

func (s *Server) Stop() (err error)

Stop stops the server. It blocks until the server is totally stopped. On POSIX systems, it will wait for connections to close (up to a max timeout of a few seconds); on Windows it will close the listener immediately. This implements Caddy.Stopper interface.

func (*Server) Tracer

func (s *Server) Tracer() ot.Tracer

Tracer ... TODO: Add comment

type ServerTLS

type ServerTLS struct {
	*Server
}

ServerTLS represents an instance of a TLS-over-DNS-server.

func NewServerTLS

func NewServerTLS(addr string, group []*Config) (*ServerTLS, error)

NewServerTLS returns a new CoreDNS TLS server and compiles all middleware in to it.

func (*ServerTLS) Listen

func (s *ServerTLS) Listen() (net.Listener, error)

Listen implements caddy.TCPServer interface.

func (*ServerTLS) ListenPacket

func (s *ServerTLS) ListenPacket() (net.PacketConn, error)

ListenPacket implements caddy.UDPServer interface.

func (*ServerTLS) OnStartupComplete

func (s *ServerTLS) OnStartupComplete()

OnStartupComplete lists the sites served by this server and any relevant information, assuming Quiet is false.

func (*ServerTLS) Serve

func (s *ServerTLS) Serve(l net.Listener) error

Serve implements caddy.TCPServer interface.

func (*ServerTLS) ServePacket

func (s *ServerTLS) ServePacket(p net.PacketConn) error

ServePacket implements caddy.UDPServer interface.

type ServergRPC

type ServergRPC struct {
	*Server
	// contains filtered or unexported fields
}

ServergRPC represents an instance of a DNS-over-gRPC server.

func NewServergRPC

func NewServergRPC(addr string, group []*Config) (*ServergRPC, error)

NewServergRPC returns a new CoreDNS GRPC server and compiles all middleware in to it.

func (*ServergRPC) Listen

func (s *ServergRPC) Listen() (net.Listener, error)

Listen implements caddy.TCPServer interface.

func (*ServergRPC) ListenPacket

func (s *ServergRPC) ListenPacket() (net.PacketConn, error)

ListenPacket implements caddy.UDPServer interface.

func (*ServergRPC) OnStartupComplete

func (s *ServergRPC) OnStartupComplete()

OnStartupComplete lists the sites served by this server and any relevant information, assuming Quiet is false.

func (*ServergRPC) Query

func (s *ServergRPC) Query(ctx context.Context, in *pb.DnsPacket) (*pb.DnsPacket, error)

Query is the main entry-point into the gRPC server. From here we call ServeDNS like any normal server. We use a custom responseWriter to pick up the bytes we need to write back to the client as a protobuf.

func (*ServergRPC) Serve

func (s *ServergRPC) Serve(l net.Listener) error

Serve implements caddy.TCPServer interface.

func (*ServergRPC) ServePacket

func (s *ServergRPC) ServePacket(p net.PacketConn) error

ServePacket implements caddy.UDPServer interface.

func (*ServergRPC) Shutdown

func (s *ServergRPC) Shutdown() error

Shutdown stops the server (non gracefully).

func (*ServergRPC) Stop

func (s *ServergRPC) Stop() (err error)

Stop stops the server. It blocks until the server is totally stopped.