dns

package
v1.90.8 Latest Latest
Warning

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

 Go to latest Published: Nov 18, 2025 License: BSD-3-Clause Imports: 54 Imported by: 36

Documentation

Overview

Package dns contains code to configure and manage DNS settings.

Index

Constants

This section is empty.

Variables

View Source 
var ErrGetBaseConfigNotSupported = errors.New("getting OS base config is not supported")

ErrGetBaseConfigNotSupported is the error OSConfigurator.GetBaseConfig returns when the OSConfigurator doesn't support reading the underlying configuration out of the OS.

View Source 
var (

	// ErrNoDNSConfig is returned by RecompileDNSConfig when the Manager
	// has no existing DNS configuration.
	ErrNoDNSConfig = errors.New("no DNS configuration")
)
View Source 
var HookWatchFile feature.Hook[func(ctx context.Context, dir, filename string, cb func()) error]

HookWatchFile is a hook for watching file changes, for platforms that support it. The function is called with a directory and filename to watch, and a callback to call when the file changes. It returns an error if the watch could not be set up.

Functions

func CleanUp added in v1.64.0 

func CleanUp(logf logger.Logf, netMon *netmon.Monitor, bus *eventbus.Bus, health *health.Tracker, interfaceName string)

CleanUp restores the system DNS configuration to its original state in case the Tailscale daemon terminated without closing the router. No other state needs to be instantiated before this runs.

health must not be nil

func Clone added in v1.90.0 

func Clone(dst, src any) bool

Clone duplicates src into dst and reports whether it succeeded. To succeed, <src, dst> must be of types <*T, *T> or <*T, **T>, where T is one of Config.

func NewNoopManager 

func NewNoopManager() (noopManager, error)

Types

type Config 

type Config struct {
	// DefaultResolvers are the DNS resolvers to use for DNS names
	// which aren't covered by more specific per-domain routes below.
	// If empty, the OS's default resolvers (the ones that predate
	// Tailscale altering the configuration) are used.
	DefaultResolvers []*dnstype.Resolver
	// Routes maps a DNS suffix to the resolvers that should be used
	// for queries that fall within that suffix.
	// If a query doesn't match any entry in Routes, the
	// DefaultResolvers are used.
	// A Routes entry with no resolvers means the route should be
	// authoritatively answered using the contents of Hosts.
	Routes map[dnsname.FQDN][]*dnstype.Resolver
	// SearchDomains are DNS suffixes to try when expanding
	// single-label queries.
	SearchDomains []dnsname.FQDN
	// Hosts maps DNS FQDNs to their IPs, which can be a mix of IPv4
	// and IPv6.
	// Queries matching entries in Hosts are resolved locally by
	// 100.100.100.100 without leaving the machine.
	// Adding an entry to Hosts merely creates the record. If you want
	// it to resolve, you also need to add appropriate routes to
	// Routes.
	Hosts map[dnsname.FQDN][]netip.Addr
	// OnlyIPv6, if true, uses the IPv6 service IP (for MagicDNS)
	// instead of the IPv4 version (100.100.100.100).
	OnlyIPv6 bool
}

Config is a DNS configuration.

func (*Config) Clone added in v1.90.0 

func (src *Config) Clone() *Config

Clone makes a deep copy of Config. The result aliases no memory with the original.

func (*Config) Equal added in v1.90.0 

func (c *Config) Equal(o *Config) bool

func (*Config) View added in v1.90.0 

func (p *Config) View() ConfigView

View returns a read-only view of Config.

func (*Config) WriteToBufioWriter added in v1.12.0 

func (c *Config) WriteToBufioWriter(w *bufio.Writer)

WriteToBufioWriter write a debug version of c for logs to w, omitting spammy stuff like *.arpa entries and replacing it with a total count.

type ConfigView added in v1.90.0 

type ConfigView struct {
	// contains filtered or unexported fields
}

ConfigView provides a read-only view over Config.

Its methods should only be called if `Valid()` returns true.

func (ConfigView) AsStruct added in v1.90.0 

func (v ConfigView) AsStruct() *Config

AsStruct returns a clone of the underlying value which aliases no memory with the original.

func (ConfigView) DefaultResolvers added in v1.90.0 

func (v ConfigView) DefaultResolvers() views.SliceView[*dnstype.Resolver, dnstype.ResolverView]

DefaultResolvers are the DNS resolvers to use for DNS names which aren't covered by more specific per-domain routes below. If empty, the OS's default resolvers (the ones that predate Tailscale altering the configuration) are used.

func (ConfigView) Equal added in v1.90.0 

func (v ConfigView) Equal(v2 ConfigView) bool

func (ConfigView) Hosts added in v1.90.0 

func (v ConfigView) Hosts() views.MapSlice[dnsname.FQDN, netip.Addr]

Hosts maps DNS FQDNs to their IPs, which can be a mix of IPv4 and IPv6. Queries matching entries in Hosts are resolved locally by 100.100.100.100 without leaving the machine. Adding an entry to Hosts merely creates the record. If you want it to resolve, you also need to add appropriate routes to Routes.

func (ConfigView) MarshalJSON added in v1.90.0 

func (v ConfigView) MarshalJSON() ([]byte, error)

MarshalJSON implements jsonv1.Marshaler.

func (ConfigView) MarshalJSONTo added in v1.90.0 

func (v ConfigView) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo implements jsonv2.MarshalerTo.

func (ConfigView) OnlyIPv6 added in v1.90.0 

func (v ConfigView) OnlyIPv6() bool

OnlyIPv6, if true, uses the IPv6 service IP (for MagicDNS) instead of the IPv4 version (100.100.100.100).

func (ConfigView) Routes added in v1.90.0 

func (v ConfigView) Routes() views.MapFn[dnsname.FQDN, []*dnstype.Resolver, views.SliceView[*dnstype.Resolver, dnstype.ResolverView]]

Routes maps a DNS suffix to the resolvers that should be used for queries that fall within that suffix. If a query doesn't match any entry in Routes, the DefaultResolvers are used. A Routes entry with no resolvers means the route should be authoritatively answered using the contents of Hosts.

func (ConfigView) SearchDomains added in v1.90.0 

func (v ConfigView) SearchDomains() views.Slice[dnsname.FQDN]

SearchDomains are DNS suffixes to try when expanding single-label queries.

func (*ConfigView) UnmarshalJSON added in v1.90.0 

func (v *ConfigView) UnmarshalJSON(b []byte) error

UnmarshalJSON implements jsonv1.Unmarshaler.

func (*ConfigView) UnmarshalJSONFrom added in v1.90.0 

func (v *ConfigView) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom implements jsonv2.UnmarshalerFrom.

func (ConfigView) Valid added in v1.90.0 

func (v ConfigView) Valid() bool

Valid reports whether v's underlying value is non-nil.

type HostEntry added in v1.30.0 

type HostEntry struct {
	Addr  netip.Addr
	Hosts []string
}

HostEntry represents a single line in the OS's hosts file.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager manages system DNS settings.

func NewManager 

func NewManager(logf logger.Logf, oscfg OSConfigurator, health *health.Tracker, dialer *tsdial.Dialer, linkSel resolver.ForwardLinkSelector, knobs *controlknobs.Knobs, goos string) *Manager

NewManagers created a new manager from the given config.

knobs may be nil.

func (*Manager) Down 

func (m *Manager) Down() error

func (*Manager) FlushCaches added in v1.16.0 

func (m *Manager) FlushCaches() error

func (*Manager) GetBaseConfig added in v1.74.0 

func (m *Manager) GetBaseConfig() (OSConfig, error)

GetBaseConfig returns the current base OS DNS configuration as provided by the OSConfigurator.

func (*Manager) HandleTCPConn added in v1.26.0 

func (m *Manager) HandleTCPConn(conn net.Conn, srcAddr netip.AddrPort)

HandleTCPConn implements magicDNS over TCP, taking a connection and servicing DNS requests sent down it.

func (*Manager) Query added in v1.26.0 

func (m *Manager) Query(ctx context.Context, bs []byte, family string, from netip.AddrPort) ([]byte, error)

Query executes a DNS query received from the given address. The query is provided in bs as a wire-encoded DNS query without any transport header. This method is called for requests arriving over UDP and TCP.

The "family" parameter should indicate what type of DNS query this is: either "tcp" or "udp".

func (*Manager) RecompileDNSConfig added in v1.82.0 

func (m *Manager) RecompileDNSConfig() error

RecompileDNSConfig recompiles the last attempted DNS configuration, which has the side effect of re-querying the OS's interface nameservers. This should be used on platforms where the interface nameservers can change. Darwin, for example, where the nameservers aren't always available when we process a major interface change event, or platforms where the nameservers may change while tunnel is up.

This should be called if it is determined that [OSConfigurator.GetBaseConfig] may give a better or different result than when Manager.Set was last called. The logic for making that determination is up to the caller.

It returns ErrNoDNSConfig if Manager.Set has never been called.

func (*Manager) Resolver added in v1.20.0 

func (m *Manager) Resolver() *resolver.Resolver

Resolver returns the Manager's DNS Resolver.

func (*Manager) Set 

func (m *Manager) Set(cfg Config) error

type OSConfig 

type OSConfig struct {
	// Hosts is a map of DNS FQDNs to their IPs, which should be added to the
	// OS's hosts file. Currently, (2022-08-12) it is only populated for Windows
	// in SplitDNS mode and with Smart Name Resolution turned on.
	Hosts []*HostEntry
	// Nameservers are the IP addresses of the nameservers to use.
	Nameservers []netip.Addr
	// SearchDomains are the domain suffixes to use when expanding
	// single-label name queries. SearchDomains is additive to
	// whatever non-Tailscale search domains the OS has.
	SearchDomains []dnsname.FQDN
	// MatchDomains are the DNS suffixes for which Nameservers should
	// be used. If empty, Nameservers is installed as the "primary" resolver.
	// A non-empty MatchDomains requests a "split DNS" configuration
	// from the OS, which will only work with OSConfigurators that
	// report SupportsSplitDNS()=true.
	MatchDomains []dnsname.FQDN
}

OSConfig is an OS DNS configuration.

func (OSConfig) Equal 

func (a OSConfig) Equal(b OSConfig) bool

func (OSConfig) Format added in v1.32.0 

func (a OSConfig) Format(f fmt.State, verb rune)

Format implements the fmt.Formatter interface to ensure that Hosts is printed correctly (i.e. not as a bunch of pointers).

Fixes https://github.com/tailscale/tailscale/issues/5669

func (OSConfig) IsZero 

func (o OSConfig) IsZero() bool

func (*OSConfig) WriteToBufioWriter added in v1.50.0 

func (o *OSConfig) WriteToBufioWriter(w *bufio.Writer)

type OSConfigurator 

type OSConfigurator interface {
	// SetDNS updates the OS's DNS configuration to match cfg.
	// If cfg is the zero value, all Tailscale-related DNS
	// configuration is removed.
	// SetDNS must not be called after Close.
	// SetDNS takes ownership of cfg.
	SetDNS(cfg OSConfig) error
	// SupportsSplitDNS reports whether the configurator is capable of
	// installing a resolver only for specific DNS suffixes. If false,
	// the configurator can only set a global resolver.
	SupportsSplitDNS() bool

	// Implementations that don't support getting the base config must
	// return ErrGetBaseConfigNotSupported.
	GetBaseConfig() (OSConfig, error)
	// Close removes Tailscale-related DNS configuration from the OS.
	Close() error
}

An OSConfigurator applies DNS settings to the operating system.

func NewOSConfigurator 

func NewOSConfigurator(logf logger.Logf, health *health.Tracker, _ policyclient.Client, _ *controlknobs.Knobs, interfaceName string) (ret OSConfigurator, err error)

NewOSConfigurator created a new OS configurator.

The health tracker may be nil; the knobs may be nil and are ignored on this platform.

Source Files

View all Source files

Directories

Path Synopsis
Package publicdns contains mapping and helpers for working with public DNS providers.
 Package publicdns contains mapping and helpers for working with public DNS providers.
Package resolvconffile parses & serializes /etc/resolv.conf-style files.
 Package resolvconffile parses & serializes /etc/resolv.conf-style files.
Package resolver implements a stub DNS resolver that can also serve records out of an internal local zone.
 Package resolver implements a stub DNS resolver that can also serve records out of an internal local zone.

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.