dnsforward

package
v0.108.0-b.34 Latest Latest
Warning

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

 Go to latest Published: Apr 18, 2023 License: GPL-3.0 Imports: 44 Imported by: 0

Documentation

Overview

Package dnsforward contains a DNS forwarding server.

Index

Constants

View Source 
const (
	// ErrRDNSNoData is returned by [RDNSExchanger.Exchange] when the answer
	// section of response is either NODATA or has no PTR records.
	ErrRDNSNoData errors.Error = "no ptr data in response"

	// ErrRDNSFailed is returned by [RDNSExchanger.Exchange] if the received
	// response is not a NOERROR or NXDOMAIN.
	ErrRDNSFailed errors.Error = "failed to resolve ptr"
)
View Source 
const DefaultTimeout = 10 * time.Second

DefaultTimeout is the default upstream timeout

Variables

This section is empty.

Functions

func IsCommentOrEmpty added in v0.107.0 

func IsCommentOrEmpty(s string) (ok bool)

IsCommentOrEmpty returns true if s starts with a "#" character or is empty. This function is useful for filtering out non-upstream lines from upstream configs.

func UpstreamHTTPVersions added in v0.107.15 

func UpstreamHTTPVersions(http3 bool) (v []upstream.HTTPVersion)

UpstreamHTTPVersions returns the HTTP versions for upstream configuration depending on configuration.

func ValidateClientID added in v0.105.0 

func ValidateClientID(id string) (err error)

ValidateClientID returns an error if id is not a valid ClientID.

func ValidateUpstreams 

func ValidateUpstreams(upstreams []string) (err error)

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

TODO(e.burkov): Move into aghnet or even into dnsproxy.

func ValidateUpstreamsPrivate added in v0.107.7 

func ValidateUpstreamsPrivate(upstreams []string, privateNets netutil.SubnetSet) (err error)

ValidateUpstreamsPrivate validates each upstream and returns an error if any upstream is invalid or if there are no default upstreams specified. It also checks each domain of domain-specific upstreams for being ARPA pointing to a locally-served network. privateNets must not be nil.

Types

type BlockingMode added in v0.107.0 

type BlockingMode string

BlockingMode is an enum of all allowed blocking modes. 

const (
	// BlockingModeCustomIP means respond with a custom IP address.
	BlockingModeCustomIP BlockingMode = "custom_ip"

	// BlockingModeDefault is the same as BlockingModeNullIP for
	// Adblock-style rules, but responds with the IP address specified in
	// the rule when blocked by an `/etc/hosts`-style rule.
	BlockingModeDefault BlockingMode = "default"

	// BlockingModeNullIP means respond with a zero IP address: "0.0.0.0"
	// for A requests and "::" for AAAA ones.
	BlockingModeNullIP BlockingMode = "null_ip"

	// BlockingModeNXDOMAIN means respond with the NXDOMAIN code.
	BlockingModeNXDOMAIN BlockingMode = "nxdomain"

	// BlockingModeREFUSED means respond with the REFUSED code.
	BlockingModeREFUSED BlockingMode = "refused"
)

Allowed blocking modes.

type DNSCreateParams 

type DNSCreateParams struct {
	DNSFilter   *filtering.DNSFilter
	Stats       stats.Interface
	QueryLog    querylog.QueryLog
	DHCPServer  dhcpd.Interface
	PrivateNets netutil.SubnetSet
	Anonymizer  *aghnet.IPMut
	LocalDomain string
}

DNSCreateParams are parameters to create a new server.

type DNSCryptConfig added in v0.105.0 

type DNSCryptConfig struct {
	ResolverCert   *dnscrypt.Cert
	ProviderName   string
	UDPListenAddrs []*net.UDPAddr
	TCPListenAddrs []*net.TCPAddr
	Enabled        bool
}

DNSCryptConfig is the DNSCrypt server configuration struct.

type EDNSClientSubnet added in v0.107.26 

type EDNSClientSubnet struct {
	// CustomIP for EDNS Client Subnet.
	CustomIP netip.Addr `yaml:"custom_ip"`

	// Enabled defines if EDNS Client Subnet is enabled.
	Enabled bool `yaml:"enabled"`

	// UseCustom defines if CustomIP should be used.
	UseCustom bool `yaml:"use_custom"`
}

EDNSClientSubnet is the settings list for EDNS Client Subnet.

type FilteringConfig 

type FilteringConfig struct {

	// FilterHandler is an optional additional filtering callback.
	FilterHandler func(clientAddr net.IP, clientID string, settings *filtering.Settings) `yaml:"-"`

	// GetCustomUpstreamByClient is a callback that returns upstreams
	// configuration based on the client IP address or ClientID.  It returns
	// nil if there are no custom upstreams for the client.
	GetCustomUpstreamByClient func(id string) (conf *proxy.UpstreamConfig, err error) `yaml:"-"`

	// ProtectionEnabled defines whether or not use any of filtering features.
	ProtectionEnabled bool `yaml:"protection_enabled"`

	// BlockingMode defines the way how blocked responses are constructed.
	BlockingMode BlockingMode `yaml:"blocking_mode"`

	// BlockingIPv4 is the IP address to be returned for a blocked A request.
	BlockingIPv4 net.IP `yaml:"blocking_ipv4"`

	// BlockingIPv6 is the IP address to be returned for a blocked AAAA
	// request.
	BlockingIPv6 net.IP `yaml:"blocking_ipv6"`

	// BlockedResponseTTL is the time-to-live value for blocked responses.  If
	// 0, then default value is used (3600).
	BlockedResponseTTL uint32 `yaml:"blocked_response_ttl"`

	// ProtectionDisabledUntil is the timestamp until when the protection is
	// disabled.
	ProtectionDisabledUntil *time.Time `yaml:"protection_disabled_until"`

	// ParentalBlockHost is the IP (or domain name) which is used to respond to
	// DNS requests blocked by parental control.
	ParentalBlockHost string `yaml:"parental_block_host"`

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

	// Ratelimit is the maximum number of requests per second from a given IP
	// (0 to disable).
	Ratelimit uint32 `yaml:"ratelimit"`

	// RatelimitWhitelist is the list of whitelisted client IP addresses.
	RatelimitWhitelist []string `yaml:"ratelimit_whitelist"`

	// RefuseAny, if true, refuse ANY requests.
	RefuseAny bool `yaml:"refuse_any"`

	// UpstreamDNS is the list of upstream DNS servers.
	UpstreamDNS []string `yaml:"upstream_dns"`

	// UpstreamDNSFileName, if set, points to the file which contains upstream
	// DNS servers.
	UpstreamDNSFileName string `yaml:"upstream_dns_file"`

	// BootstrapDNS is the list of bootstrap DNS servers for DoH and DoT
	// resolvers (plain DNS only).
	BootstrapDNS []string `yaml:"bootstrap_dns"`

	// AllServers, if true, parallel queries to all configured upstream servers
	// are enabled.
	AllServers bool `yaml:"all_servers"`

	// FastestAddr, if true, use Fastest Address algorithm.
	FastestAddr bool `yaml:"fastest_addr"`

	// FastestTimeout replaces the default timeout for dialing IP addresses
	// when FastestAddr is true.
	FastestTimeout timeutil.Duration `yaml:"fastest_timeout"`

	// AllowedClients is the slice of IP addresses, CIDR networks, and
	// ClientIDs of allowed clients.  If not empty, only these clients are
	// allowed, and [FilteringConfig.DisallowedClients] are ignored.
	AllowedClients []string `yaml:"allowed_clients"`

	// DisallowedClients is the slice of IP addresses, CIDR networks, and
	// ClientIDs of disallowed clients.
	DisallowedClients []string `yaml:"disallowed_clients"`

	// BlockedHosts is the list of hosts that should be blocked.
	BlockedHosts []string `yaml:"blocked_hosts"`

	// TrustedProxies is the list of IP addresses and CIDR networks to detect
	// proxy servers addresses the DoH requests from which should be handled.
	// The value of nil or an empty slice for this field makes Proxy not trust
	// any address.
	TrustedProxies []string `yaml:"trusted_proxies"`

	// CacheSize is the DNS cache size (in bytes).
	CacheSize uint32 `yaml:"cache_size"`

	// CacheMinTTL is the override TTL value (minimum) received from upstream
	// server.
	CacheMinTTL uint32 `yaml:"cache_ttl_min"`

	// CacheMaxTTL is the override TTL value (maximum) received from upstream
	// server.
	CacheMaxTTL uint32 `yaml:"cache_ttl_max"`

	// CacheOptimistic defines if optimistic cache mechanism should be used.
	CacheOptimistic bool `yaml:"cache_optimistic"`

	// BogusNXDomain is the list of IP addresses, responses with them will be
	// transformed to NXDOMAIN.
	BogusNXDomain []string `yaml:"bogus_nxdomain"`

	// AAAADisabled, if true, respond with an empty answer to all AAAA
	// requests.
	AAAADisabled bool `yaml:"aaaa_disabled"`

	// EnableDNSSEC, if true, set AD flag in outcoming DNS request.
	EnableDNSSEC bool `yaml:"enable_dnssec"`

	// EDNSClientSubnet is the settings list for EDNS Client Subnet.
	EDNSClientSubnet *EDNSClientSubnet `yaml:"edns_client_subnet"`

	// MaxGoroutines is the max number of parallel goroutines for processing
	// incoming requests.
	MaxGoroutines uint32 `yaml:"max_goroutines"`

	// HandleDDR, if true, handle DDR requests
	HandleDDR bool `yaml:"handle_ddr"`

	// IpsetList is the ipset configuration that allows AdGuard Home to add IP
	// addresses of the specified domain names to an ipset list.  Syntax:
	//
	//	DOMAIN[,DOMAIN].../IPSET_NAME
	//
	// This field is ignored if [IpsetListFileName] is set.
	IpsetList []string `yaml:"ipset"`

	// IpsetListFileName, if set, points to the file with ipset configuration.
	// The format is the same as in [IpsetList].
	IpsetListFileName string `yaml:"ipset_file"`

	// BootstrapPreferIPv6, if true, instructs the bootstrapper to prefer IPv6
	// addresses to IPv4 ones for DoH, DoQ, and DoT.
	BootstrapPreferIPv6 bool `yaml:"bootstrap_prefer_ipv6"`
}

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

type RDNSExchanger added in v0.106.0 

type RDNSExchanger interface {
	// Exchange tries to resolve the ip in a suitable way, i.e. either as local
	// or as external.
	Exchange(ip net.IP) (host string, err error)

	// ResolvesPrivatePTR returns true if the RDNSExchanger is able to
	// resolve PTR requests for locally-served addresses.
	ResolvesPrivatePTR() (ok bool)
}

RDNSExchanger is a resolver for clients' addresses.

type Server 

type Server struct {
	// 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) (s *Server, err error)

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 gracefully closes the server. It is safe for concurrent use.

TODO(e.burkov): A better approach would be making Stop method waiting for all its workers finished. But it would require the upstream.Upstream to have the Close method to prevent from hanging while waiting for unresponsive server to respond.

func (*Server) Exchange 

func (s *Server) Exchange(ip net.IP) (host string, err error)

Exchange implements the RDNSExchanger interface for *Server.

func (*Server) IsBlockedClient added in v0.107.0 

func (s *Server) IsBlockedClient(ip netip.Addr, clientID string) (blocked bool, rule string)

IsBlockedClient returns true if the client is blocked by the current access settings.

func (*Server) IsRunning 

func (s *Server) IsRunning() bool

IsRunning returns true if the DNS server is running.

func (*Server) Prepare 

func (s *Server) Prepare(conf *ServerConfig) (err error)

Prepare initializes parameters of s using data from conf. conf must not be nil.

func (*Server) RDNSSettings added in v0.106.0 

func (s *Server) RDNSSettings() (localPTRResolvers []string, resolveClients, resolvePTR bool)

RDNSSettings returns the copy of actual RDNS configuration.

func (*Server) Reconfigure 

func (s *Server) Reconfigure(conf *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) ResolvesPrivatePTR added in v0.107.0 

func (s *Server) ResolvesPrivatePTR() (ok bool)

ResolvesPrivatePTR implements the RDNSExchanger interface for *Server.

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) UpdatedProtectionStatus added in v0.107.28 

func (s *Server) UpdatedProtectionStatus() (enabled bool, disabledUntil *time.Time)

UpdatedProtectionStatus updates protection state, if the protection was disabled temporarily. Returns the updated state of protection.

func (*Server) WriteDiskConfig 

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

WriteDiskConfig - write configuration

type ServerConfig 

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

	FilteringConfig
	TLSConfig
	DNSCryptConfig
	TLSAllowUnencryptedDoH bool

	// UpstreamTimeout is the timeout for querying upstream servers.
	UpstreamTimeout time.Duration

	TLSv12Roots *x509.CertPool // list of root CAs for TLSv1.2

	// TLSCiphers are the IDs of TLS cipher suites to use.
	TLSCiphers []uint16

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

	// Register an HTTP handler
	HTTPRegister aghhttp.RegisterFunc

	// LocalPTRResolvers is a slice of addresses to be used as upstreams for
	// resolving PTR queries for local addresses.
	LocalPTRResolvers []string

	// DNS64Prefixes is a slice of NAT64 prefixes to be used for DNS64.
	DNS64Prefixes []netip.Prefix

	// ResolveClients signals if the RDNS should resolve clients' addresses.
	ResolveClients bool

	// UsePrivateRDNS defines if the PTR requests for unknown addresses from
	// locally-served networks should be resolved via private PTR resolvers.
	UsePrivateRDNS bool

	// UseDNS64 defines if DNS64 is enabled for incoming requests.
	UseDNS64 bool

	// ServeHTTP3 defines if HTTP/3 is be allowed for incoming requests.
	ServeHTTP3 bool

	// UseHTTP3Upstreams defines if HTTP/3 is be allowed for DNS-over-HTTPS
	// upstreams.
	UseHTTP3Upstreams bool
}

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

type TLSConfig 

type TLSConfig struct {
	TLSListenAddrs   []*net.TCPAddr `yaml:"-" json:"-"`
	QUICListenAddrs  []*net.UDPAddr `yaml:"-" json:"-"`
	HTTPSListenAddrs []*net.TCPAddr `yaml:"-" json:"-"`

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

	CertificatePath string `yaml:"certificate_path" json:"certificate_path"`
	PrivateKeyPath  string `yaml:"private_key_path" json:"private_key_path"`

	CertificateChainData []byte `yaml:"-" json:"-"`
	PrivateKeyData       []byte `yaml:"-" json:"-"`

	// ServerName is the hostname of the server.  Currently, it is only being
	// used for ClientID checking and Discovery of Designated Resolvers (DDR).
	ServerName string `yaml:"-" json:"-"`

	// OverrideTLSCiphers, when set, contains the names of the cipher suites to
	// use.  If the slice is empty, the default safe suites are used.
	OverrideTLSCiphers []string `yaml:"override_tls_ciphers,omitempty" json:"-"`

	// StrictSNICheck controls if the connections with SNI mismatching the
	// certificate's ones should be rejected.
	StrictSNICheck bool `yaml:"strict_sni_check" json:"-"`
	// contains filtered or unexported fields
}

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

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.