dnsserver

package
v1.11.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 5, 2024 License: Apache-2.0 Imports: 40 Imported by: 3,595

Documentation

Overview

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

Index

Constants

View Source 
const (
	// DoQCodeNoError is used when the connection or stream needs to be
	// closed, but there is no error to signal.
	DoQCodeNoError quic.ApplicationErrorCode = 0

	// DoQCodeInternalError signals that the DoQ implementation encountered
	// an internal error and is incapable of pursuing the transaction or the
	// connection.
	DoQCodeInternalError quic.ApplicationErrorCode = 1

	// DoQCodeProtocolError signals that the DoQ implementation encountered
	// a protocol error and is forcibly aborting the connection.
	DoQCodeProtocolError quic.ApplicationErrorCode = 2
)
View Source 
const DefaultPort = transport.Port

DefaultPort is the default port.

Variables

View Source 
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.

View Source 
var Directives = []string{
	"root",
	"metadata",
	"geoip",
	"cancel",
	"tls",
	"timeouts",
	"reload",
	"nsid",
	"bufsize",
	"bind",
	"debug",
	"trace",
	"ready",
	"health",
	"pprof",
	"prometheus",
	"errors",
	"log",
	"dnstap",
	"local",
	"dns64",
	"acl",
	"any",
	"chaos",
	"loadbalance",
	"tsig",
	"cache",
	"rewrite",
	"header",
	"dnssec",
	"autopath",
	"minimal",
	"template",
	"transfer",
	"hosts",
	"route53",
	"azure",
	"clouddns",
	"k8s_external",
	"kubernetes",
	"file",
	"auto",
	"secondary",
	"etcd",
	"loop",
	"forward",
	"grpc",
	"erratic",
	"whoami",
	"on",
	"sign",
	"view",
}

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.

View Source 
var EnableChaos = map[string]struct{}{
	"chaos":   {},
	"forward": {},
	"proxy":   {},
}

EnableChaos is a map with plugin names for which we should open CH class queries as we block these by default.

View Source 
var Quiet bool

Quiet mode will not show any informative output on initialization.

Functions

func AddPrefix added in v1.11.0 

func AddPrefix(b []byte) (m []byte)

AddPrefix adds a 2-byte prefix with the DNS message length.

func SplitProtocolHostPort added in v1.0.6 

func SplitProtocolHostPort(address string) (protocol string, ip string, port string, err error)

SplitProtocolHostPort splits a full formed address like "dns://[::1]:53" into parts.

Types

type Config 

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

	// one or several hostnames to bind the server to.
	// defaults to a single empty string that denote the wildcard address
	ListenHosts []string

	// The port to listen on.
	Port string

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

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

	// Stacktrace controls including stacktrace as part of log from recover mechanism, it is disabled by default.
	Stacktrace bool

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

	// If this function is not nil it will be used to inspect and validate
	// HTTP requests. Although this isn't referenced in-tree, external plugins
	// may depend on it.
	HTTPRequestValidateFunc func(*http.Request) bool

	// FilterFuncs is used to further filter access
	// to this handler. E.g. to limit access to a reverse zone
	// on a non-octet boundary, i.e. /17
	FilterFuncs []FilterFunc

	// ViewName is the name of the Viewer PLugin defined in the Config
	ViewName string

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

	// Timeouts for TCP, TLS and HTTPS servers.
	ReadTimeout  time.Duration
	WriteTimeout time.Duration
	IdleTimeout  time.Duration

	// TSIG secrets, [name]key.
	TsigSecret map[string]string

	// Plugin stack.
	Plugin []plugin.Plugin
	// 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) AddPlugin 

func (c *Config) AddPlugin(m plugin.Plugin)

AddPlugin adds a plugin to a site's plugin stack.

func (*Config) Handler 

func (c *Config) Handler(name string) plugin.Handler

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

func (*Config) Handlers added in v1.0.2 

func (c *Config) Handlers() []plugin.Handler

Handlers returns a slice of plugins that have been registered. This can be used to inspect and interact with registered plugins but cannot be used to remove or add plugins. Note that this is order dependent and the order is defined in directives.go, i.e. if your plugin comes before the plugin you are checking; it will not be there (yet).

type DoHWriter added in v1.1.3 

type DoHWriter struct {

	// Msg is a response to be written to the client.
	Msg *dns.Msg
	// contains filtered or unexported fields
}

DoHWriter is a dns.ResponseWriter that adds more specific LocalAddr and RemoteAddr methods.

func (*DoHWriter) Close added in v1.11.0 

func (d *DoHWriter) Close() error

Close no-op implementation.

func (*DoHWriter) Hijack added in v1.11.0 

func (d *DoHWriter) Hijack()

Hijack no-op implementation.

func (*DoHWriter) LocalAddr added in v1.1.3 

func (d *DoHWriter) LocalAddr() net.Addr

LocalAddr returns the local address.

func (*DoHWriter) RemoteAddr added in v1.1.3 

func (d *DoHWriter) RemoteAddr() net.Addr

RemoteAddr returns the remote address.

func (*DoHWriter) Request added in v1.8.2 

func (d *DoHWriter) Request() *http.Request

Request returns the HTTP request.

func (*DoHWriter) TsigStatus added in v1.11.0 

func (d *DoHWriter) TsigStatus() error

TsigStatus no-op implementation.

func (*DoHWriter) TsigTimersOnly added in v1.11.0 

func (d *DoHWriter) TsigTimersOnly(_ bool)

TsigTimersOnly no-op implementation.

func (*DoHWriter) Write added in v1.11.0 

func (d *DoHWriter) Write(b []byte) (int, error)

Write stores the message to be written to the client.

func (*DoHWriter) WriteMsg added in v1.11.0 

func (d *DoHWriter) WriteMsg(m *dns.Msg) error

WriteMsg stores the message to be written to the client.

type DoQWriter added in v1.11.0 

type DoQWriter struct {
	Msg *dns.Msg
	// contains filtered or unexported fields
}

func (*DoQWriter) Close added in v1.11.0 

func (w *DoQWriter) Close() error

Close sends the STREAM FIN signal. The server MUST send the response(s) on the same stream and MUST indicate, after the last response, through the STREAM FIN mechanism that no further data will be sent on that stream. See https://www.rfc-editor.org/rfc/rfc9250#section-4.2-7

func (*DoQWriter) Hijack added in v1.11.0 

func (w *DoQWriter) Hijack()

func (*DoQWriter) LocalAddr added in v1.11.0 

func (w *DoQWriter) LocalAddr() net.Addr

func (*DoQWriter) RemoteAddr added in v1.11.0 

func (w *DoQWriter) RemoteAddr() net.Addr

func (*DoQWriter) TsigStatus added in v1.11.0 

func (w *DoQWriter) TsigStatus() error

These methods implement the dns.ResponseWriter interface from Go DNS.

func (*DoQWriter) TsigTimersOnly added in v1.11.0 

func (w *DoQWriter) TsigTimersOnly(b bool)

func (*DoQWriter) Write added in v1.11.0 

func (w *DoQWriter) Write(b []byte) (int, error)

func (*DoQWriter) WriteMsg added in v1.11.0 

func (w *DoQWriter) WriteMsg(m *dns.Msg) error

type FilterFunc added in v1.10.0 

type FilterFunc func(context.Context, *request.Request) bool

FilterFunc is a function that filters requests from the Config

type HTTPRequestKey added in v1.9.4 

type HTTPRequestKey struct{}

HTTPRequestKey is the context key for the current processed HTTP request (if current processed request was done over DOH)

type Key added in v1.0.6 

type Key struct{}

Key is the context key for the current server added to the context.

type LoopKey added in v1.8.1 

type LoopKey struct{}

LoopKey is the context key to detect server wide loops.

type MetadataCollector added in v1.10.0 

type MetadataCollector interface {
	Collect(context.Context, request.Request) context.Context
}

MetadataCollector is a plugin that can retrieve metadata functions from all metadata providing plugins

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 plugins in to it. By default CH class queries are blocked unless queries from enableChaos are loaded.

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 is bound to. It acts as a multiplexer for the requests zonename as defined in the request so that the correct zone (configuration and plugin 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 returns the tracer in the server if defined.

func (*Server) WrapListener added in v1.4.0 

func (s *Server) WrapListener(ln net.Listener) net.Listener

WrapListener Listen implements caddy.GracefulServer interface.

type ServerHTTPS added in v1.1.3 

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

ServerHTTPS represents an instance of a DNS-over-HTTPS server.

func NewServerHTTPS added in v1.1.3 

func NewServerHTTPS(addr string, group []*Config) (*ServerHTTPS, error)

NewServerHTTPS returns a new CoreDNS HTTPS server and compiles all plugins in to it.

func (*ServerHTTPS) Listen added in v1.1.3 

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

Listen implements caddy.TCPServer interface.

func (*ServerHTTPS) ListenPacket added in v1.1.3 

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

ListenPacket implements caddy.UDPServer interface.

func (*ServerHTTPS) OnStartupComplete added in v1.1.3 

func (s *ServerHTTPS) OnStartupComplete()

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

func (*ServerHTTPS) Serve added in v1.1.3 

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

Serve implements caddy.TCPServer interface.

func (*ServerHTTPS) ServeHTTP added in v1.1.3 

func (s *ServerHTTPS) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP is the handler that gets the HTTP request and converts to the dns format, calls the plugin chain, converts it back and write it to the client.

func (*ServerHTTPS) ServePacket added in v1.1.3 

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

ServePacket implements caddy.UDPServer interface.

func (*ServerHTTPS) Shutdown added in v1.1.3 

func (s *ServerHTTPS) Shutdown() error

Shutdown stops the server (non gracefully).

func (*ServerHTTPS) Stop added in v1.1.3 

func (s *ServerHTTPS) Stop() error

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

type ServerQUIC added in v1.11.0 

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

ServerQUIC represents an instance of a DNS-over-QUIC server.

func NewServerQUIC added in v1.11.0 

func NewServerQUIC(addr string, group []*Config) (*ServerQUIC, error)

NewServerQUIC returns a new CoreDNS QUIC server and compiles all plugin in to it.

func (*ServerQUIC) Listen added in v1.11.0 

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

Listen implements caddy.TCPServer interface.

func (*ServerQUIC) ListenPacket added in v1.11.0 

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

ListenPacket implements caddy.UDPServer interface.

func (*ServerQUIC) OnStartupComplete added in v1.11.0 

func (s *ServerQUIC) OnStartupComplete()

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

func (*ServerQUIC) Serve added in v1.11.0 

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

Serve implements caddy.TCPServer interface.

func (*ServerQUIC) ServePacket added in v1.11.0 

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

ServePacket implements caddy.UDPServer interface.

func (*ServerQUIC) ServeQUIC added in v1.11.0 

func (s *ServerQUIC) ServeQUIC() error

ServeQUIC listens for incoming QUIC packets.

func (*ServerQUIC) Stop added in v1.11.0 

func (s *ServerQUIC) Stop() error

Stop stops the server non-gracefully. It blocks until the server is totally stopped.

type ServerTLS 

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

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 plugin 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
	*pb.UnimplementedDnsServiceServer
	// 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 plugin 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.

type ViewKey added in v1.10.0 

type ViewKey struct{}

ViewKey is the context key for the current view, if defined

type Viewer added in v1.10.0 

type Viewer interface {
	// Filter returns true if the server should use the server block in which the implementing plugin resides, and the
	// name of the view for metrics logging.
	Filter(ctx context.Context, req *request.Request) bool

	// ViewName returns the name of the view
	ViewName() string
}

Viewer - If Viewer is implemented by a plugin in a server block, its Filter() is added to the server block's filter functions when starting the server. When a running server serves a DNS request, it will route the request to the first Config (server block) that passes all its filter functions.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.