dnsforward

Documentation

Overview

Package dnsforward contains a DNS forwarding server.

Index

• Constants
• func GetIPString(addr net.Addr) string
• func ValidateUpstreams(upstreams []string) error
• type DNSCreateParams
• type FilteringConfig
• type Server
  • func NewServer(p DNSCreateParams) *Server
  • func (s *Server) Close()
  • func (s *Server) Exchange(req *dns.Msg) (*dns.Msg, error)
  • func (s *Server) IsBlockedIP(ip string) (bool, string)
  • func (s *Server) IsRunning() bool
  • func (s *Server) Prepare(config *ServerConfig) error
  • func (s *Server) Reconfigure(config *ServerConfig) error
  • func (s *Server) Resolve(host string) ([]net.IPAddr, error)
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Start() error
  • func (s *Server) Stop() error
  • func (s *Server) WriteDiskConfig(c *FilteringConfig)
• type ServerConfig
• type TLSConfig

Constants

const DefaultTimeout = 10 * time.Second

DefaultTimeout is the default upstream timeout

Functions

func GetIPString

func GetIPString(addr net.Addr) string

GetIPString is a helper function that extracts IP address from net.Addr

func ValidateUpstreams

func ValidateUpstreams(upstreams []string) error

ValidateUpstreams validates each upstream and returns an error if any upstream is invalid or if there are no default upstreams specified

Types

type DNSCreateParams

type DNSCreateParams struct {
	DNSFilter  *dnsfilter.Dnsfilter
	Stats      stats.Stats
	QueryLog   querylog.QueryLog
	DHCPServer dhcpd.ServerInterface
}

DNSCreateParams - parameters for NewServer()

type FilteringConfig

type FilteringConfig struct {

	// Filtering callback function
	FilterHandler func(clientAddr string, settings *dnsfilter.RequestFilteringSettings) `yaml:"-"`

	// GetCustomUpstreamByClient - a callback function that returns upstreams configuration
	// based on the client IP address. Returns nil if there are no custom upstreams for the client
	GetCustomUpstreamByClient func(clientAddr string) *proxy.UpstreamConfig `yaml:"-"`

	ProtectionEnabled  bool   `yaml:"protection_enabled"` // whether or not use any of dnsfilter features
	BlockingMode       string `yaml:"blocking_mode"`      // mode how to answer filtered requests
	BlockingIPv4       string `yaml:"blocking_ipv4"`      // IP address to be returned for a blocked A request
	BlockingIPv6       string `yaml:"blocking_ipv6"`      // IP address to be returned for a blocked AAAA request
	BlockingIPAddrv4   net.IP `yaml:"-"`
	BlockingIPAddrv6   net.IP `yaml:"-"`
	BlockedResponseTTL uint32 `yaml:"blocked_response_ttl"` // if 0, then default is used (3600)

	// IP (or domain name) which is used to respond to DNS requests blocked by parental control or safe-browsing
	ParentalBlockHost     string `yaml:"parental_block_host"`
	SafeBrowsingBlockHost string `yaml:"safebrowsing_block_host"`

	Ratelimit          uint32   `yaml:"ratelimit"`           // max number of requests per second from a given IP (0 to disable)
	RatelimitWhitelist []string `yaml:"ratelimit_whitelist"` // a list of whitelisted client IP addresses
	RefuseAny          bool     `yaml:"refuse_any"`          // if true, refuse ANY requests

	UpstreamDNS         []string `yaml:"upstream_dns"`
	UpstreamDNSFileName string   `yaml:"upstream_dns_file"`
	BootstrapDNS        []string `yaml:"bootstrap_dns"` // a list of bootstrap DNS for DoH and DoT (plain DNS only)
	AllServers          bool     `yaml:"all_servers"`   // if true, parallel queries to all configured upstream servers are enabled
	FastestAddr         bool     `yaml:"fastest_addr"`  // use Fastest Address algorithm

	AllowedClients    []string `yaml:"allowed_clients"`    // IP addresses of whitelist clients
	DisallowedClients []string `yaml:"disallowed_clients"` // IP addresses of clients that should be blocked
	BlockedHosts      []string `yaml:"blocked_hosts"`      // hosts that should be blocked

	CacheSize   uint32 `yaml:"cache_size"`    // DNS cache size (in bytes)
	CacheMinTTL uint32 `yaml:"cache_ttl_min"` // override TTL value (minimum) received from upstream server
	CacheMaxTTL uint32 `yaml:"cache_ttl_max"` // override TTL value (maximum) received from upstream server

	BogusNXDomain          []string `yaml:"bogus_nxdomain"`     // transform responses with these IP addresses to NXDOMAIN
	AAAADisabled           bool     `yaml:"aaaa_disabled"`      // Respond with an empty answer to all AAAA requests
	EnableDNSSEC           bool     `yaml:"enable_dnssec"`      // Set DNSSEC flag in outcoming DNS request
	EnableEDNSClientSubnet bool     `yaml:"edns_client_subnet"` // Enable EDNS Client Subnet option
	MaxGoroutines          uint32   `yaml:"max_goroutines"`     // Max. number of parallel goroutines for processing incoming requests

	// IPSET configuration - add IP addresses of the specified domain names to an ipset list
	// Syntax:
	// "DOMAIN[,DOMAIN].../IPSET_NAME"
	IPSETList []string `yaml:"ipset"`
}

FilteringConfig represents the DNS filtering configuration of AdGuard Home The zero FilteringConfig is empty and ready for use.

type Server

type Server struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Server is the main way to start a DNS server.

Example:

s := dnsforward.Server{}
err := s.Start(nil) // will start a DNS server listening on default port 53, in a goroutine
err := s.Reconfigure(ServerConfig{UDPListenAddr: &net.UDPAddr{Port: 53535}}) // will reconfigure running DNS server to listen on UDP port 53535
err := s.Stop() // will stop listening on port 53535 and cancel all goroutines
err := s.Start(nil) // will start listening again, on port 53535, in a goroutine

The zero Server is empty and ready for use.

func NewServer

func NewServer(p DNSCreateParams) *Server

NewServer creates a new instance of the dnsforward.Server Note: this function must be called only once

func (*Server) Close

func (s *Server) Close()

Close - close object

func (*Server) Exchange

func (s *Server) Exchange(req *dns.Msg) (*dns.Msg, error)

Exchange - send DNS request to an upstream server and receive response No request/response filtering is performed. Query log and Stats are not updated. This method may be called before Start().

func (*Server) IsBlockedIP

func (s *Server) IsBlockedIP(ip string) (bool, string)

IsBlockedIP - return TRUE if this client should be blocked

func (*Server) IsRunning

func (s *Server) IsRunning() bool

IsRunning returns true if the DNS server is running

func (*Server) Prepare

func (s *Server) Prepare(config *ServerConfig) error

Prepare the object

func (*Server) Reconfigure

func (s *Server) Reconfigure(config *ServerConfig) error

Reconfigure applies the new configuration to the DNS server

func (*Server) Resolve

func (s *Server) Resolve(host string) ([]net.IPAddr, error)

Resolve - get IP addresses by host name from an upstream server. No request/response filtering is performed. Query log and Stats are not updated. This method may be called before Start().

func (*Server) ServeHTTP

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

ServeHTTP is a HTTP handler method we use to provide DNS-over-HTTPS

func (*Server) Start

func (s *Server) Start() error

Start starts the DNS server

func (*Server) Stop

func (s *Server) Stop() error

Stop stops the DNS server

func (*Server) WriteDiskConfig

func (s *Server) WriteDiskConfig(c *FilteringConfig)

WriteDiskConfig - write configuration

type ServerConfig

type ServerConfig struct {
	UDPListenAddr  *net.UDPAddr          // UDP listen address
	TCPListenAddr  *net.TCPAddr          // TCP listen address
	UpstreamConfig *proxy.UpstreamConfig // Upstream DNS servers config
	OnDNSRequest   func(d *proxy.DNSContext)

	FilteringConfig
	TLSConfig
	TLSAllowUnencryptedDOH bool

	TLSv12Roots *x509.CertPool // list of root CAs for TLSv1.2
	TLSCiphers  []uint16       // list of TLS ciphers to use

	// Called when the configuration is changed by HTTP request
	ConfigModified func()

	// Register an HTTP handler
	HTTPRegister func(string, string, func(http.ResponseWriter, *http.Request))
}

ServerConfig represents server configuration. The zero ServerConfig is empty and ready for use.

type TLSConfig

type TLSConfig struct {
	TLSListenAddr  *net.TCPAddr `yaml:"-" json:"-"`
	QUICListenAddr *net.UDPAddr `yaml:"-" json:"-"`
	StrictSNICheck bool         `yaml:"strict_sni_check" json:"-"` // Reject connection if the client uses server name (in SNI) that doesn't match the certificate

	CertificateChain string `yaml:"certificate_chain" json:"certificate_chain"` // PEM-encoded certificates chain
	PrivateKey       string `yaml:"private_key" json:"private_key"`             // PEM-encoded private key

	CertificatePath string `yaml:"certificate_path" json:"certificate_path"` // certificate file name
	PrivateKeyPath  string `yaml:"private_key_path" json:"private_key_path"` // private key file name

	CertificateChainData []byte `yaml:"-" json:"-"`
	PrivateKeyData       []byte `yaml:"-" json:"-"`
	// contains filtered or unexported fields
}

TLSConfig is the TLS configuration for HTTPS, DNS-over-HTTPS, and DNS-over-TLS