ctrld

README

ctrld

A highly configurable DNS forwarding proxy with support for:

• Multiple listeners for incoming queries
• Multiple upstreams with fallbacks
• Multiple network policy driven DNS query steering
• Policy driven domain based "split horizon" DNS with wildcard support
• Integrations with common router vendors and firmware
• LAN client discovery via DHCP, mDNS, ARP, NDP, hosts file parsing
• Prometheus metrics exporter

TLDR

Proxy legacy DNS traffic to secure DNS upstreams in highly configurable ways.

All DNS protocols are supported, including:

• UDP 53
• DNS-over-HTTPS
• DNS-over-TLS
• DNS-over-HTTP/3 (DOH3)
• DNS-over-QUIC

Use Cases

1. Use secure DNS protocols on networks and devices that don't natively support them (legacy routers, legacy OSes, TVs, smart toasters).
2. Create source IP based DNS routing policies with variable secure DNS upstreams. Subnet 1 (admin) uses upstream resolver A, while Subnet 2 (employee) uses upstream resolver B.
3. Create destination IP based DNS routing policies with variable secure DNS upstreams. Listener 1 uses upstream resolver C, while Listener 2 uses upstream resolver D.
4. Create domain level "split horizon" DNS routing policies to send internal domains (*.company.int) to a local DNS server, while everything else goes to another upstream.
5. Deploy on a router and create LAN client specific DNS routing policies from a web GUI (When using ControlD.com).

OS Support

• Windows (386, amd64, arm)
• Mac (amd64, arm64)
• Linux (386, amd64, arm, mips)
• FreeBSD
• Common routers (See Router Mode below)

Install

There are several ways to download and install `ctrld.

Quick Install

The simplest way to download and install ctrld is to use the following installer command on any UNIX-like platform:

sh -c 'sh -c "$(curl -sL https://api.controld.com/dl)"'

Windows user and prefer Powershell (who doesn't)? No problem, execute this command instead in administrative cmd:

powershell -Command "(Invoke-WebRequest -Uri 'https://api.controld.com/dl' -UseBasicParsing).Content | Set-Content 'ctrld_install.bat'" && ctrld_install.bat

Or you can pull and run a Docker container from Docker Hub

$ docker pull controldns/ctrld

Download Manually

Alternatively, if you know what you're doing you can download pre-compiled binaries from the Releases section for the appropriate platform.

Build

Lastly, you can build ctrld from source which requires go1.21+:

$ go build ./cmd/ctrld

or

$ go install github.com/Control-D-Inc/ctrld/cmd/ctrld@latest

or

$ docker build -t controldns/ctrld . -f docker/Dockerfile
$ docker run -d --name=ctrld -p 53:53/tcp -p 53:53/udp controldns/ctrld --cd=RESOLVER_ID_GOES_HERE -vv

Usage

The cli is self documenting, so free free to run --help on any sub-command to get specific usages.

Arguments

        __         .__       .___
  _____/  |________|  |    __| _/
_/ ___\   __\_  __ \  |   / __ |
\  \___|  |  |  | \/  |__/ /_/ |
 \___  >__|  |__|  |____/\____ |
     \/ dns forwarding proxy  \/

Usage:
  ctrld [command]

Available Commands:
  run         Run the DNS proxy server
  service     Manage ctrld service
  start       Quick start service and configure DNS on interface
  stop        Quick stop service and remove DNS from interface
  restart     Restart the ctrld service
  reload      Reload the ctrld service
  status      Show status of the ctrld service
  uninstall   Stop and uninstall the ctrld service
  clients     Manage clients
  upgrade     Upgrading ctrld to latest version

Flags:
  -h, --help            help for ctrld
  -s, --silent          do not write any log output
  -v, --verbose count   verbose log output, "-v" basic logging, "-vv" debug level logging
      --version         version for ctrld

Use "ctrld [command] --help" for more information about a command.

Basic Run Mode

To start the server with default configuration, simply run: ./ctrld run. This will create a generic ctrld.toml file in the working directory and start the application in foreground.

1. Start the server

$ sudo ./ctrld run

1. Run a test query using a DNS client, for example, dig:

$ dig verify.controld.com @127.0.0.1 +short
api.controld.com.
147.185.34.1

If verify.controld.com resolves, you're successfully using the default Control D upstream. From here, you can start editing the config file and go nuts with it. To enforce a new config, restart the server.

Service Mode

To run the application in service mode on any Windows, MacOS, Linux distibution or supported router, simply run: ./ctrld start as system/root user. This will create a generic ctrld.toml file in the user home directory (on Windows) or /etc/controld/ (almost everywhere else), start the system service, and configure the listener on the default network interface. Service will start on OS boot.

When Control D upstreams are used, ctrld willl relay your network topology to Control D (LAN IPs, MAC addresses, and hostnames), and you will be able to see your LAN devices in the web panel, view analytics and apply unique profiles to them.

In order to stop the service, and restore your DNS to original state, simply run ./ctrld stop. If you wish to stop and uninstall the service permanently, run ./ctrld uninstall.

Supported Routers

You can run ctrld on any supported router, which will function similarly to the Service Mode mentioned above. The list of supported routers and firmware includes:

• Asus Merlin
• DD-WRT
• Firewalla
• FreshTomato
• GL.iNet
• OpenWRT
• pfSense / OPNsense
• Synology
• Ubiquiti (UniFi, EdgeOS)

ctrld will attempt to interface with dnsmasq whenever possible and set itself as the upstream, while running on port 5354. On FreeBSD based OSes, ctrld will terminate dnsmasq and unbound in order to be able to listen on port 53 directly.

Control D Auto Configuration

Application can be started with a specific resolver config, instead of the default one. Simply supply your Resolver ID with a --cd flag, when using the run (foreground) or start (service) modes.

The following command will start the application in foreground mode, using the free "p2" resolver, which blocks Ads & Trackers.

./ctrld run --cd p2

Alternatively, you can use your own personal Control D Device resolver, and start the application in service mode. Your resolver ID is displayed on the "Show Resolvers" screen for the relevant Control D Device.

./ctrld start --cd abcd1234

Once you run the above commands (in service mode only), the following things will happen:

• You resolver configuration will be fetched from the API, and config file templated with the resolver data
• Application will start as a service, and keep running (even after reboot) until you run the stop or uninstall sub-commands
• Your default network interface will be updated to use the listener started by the service
• All OS DNS queries will be sent to the listener

Configuration

See Configuration Docs.

Example

• Start listener.0 on 127.0.0.1:53
• Accept queries from any source address
• Send all queries to upstream.0 via DoH protocol

Default Config

[listener]

  [listener.0]
    ip = ""
    port = 0
    restricted = false

[network]

  [network.0]
    cidrs = ["0.0.0.0/0"]
    name = "Network 0"

[service]
  log_level = "info"
  log_path = ""

[upstream]

  [upstream.0]
    bootstrap_ip = "76.76.2.11"
    endpoint = "https://freedns.controld.com/p1"
    name = "Control D - Anti-Malware"
    timeout = 5000
    type = "doh"

  [upstream.1]
    bootstrap_ip = "76.76.2.11"
    endpoint = "p2.freedns.controld.com"
    name = "Control D - No Ads"
    timeout = 3000
    type = "doq"

ctrld will pick a working config for listener.0 then writing the default config to disk for the first run.

Advanced Configuration

The above is the most basic example, which will work out of the box. If you're looking to do advanced configurations using policies, see Configuration Docs for complete documentation of the config file.

You can also supply configuration via launch argeuments, in Ephemeral Mode.

Contributing

See Contribution Guideline

Roadmap

The following functionality is on the roadmap and will be available in future releases.

• DNS intercept mode
• Direct listener mode
• Support for more routers (let us know which ones)

Documentation

Index

• Constants
• Variables
• func InitConfig(v *viper.Viper, name string)
• func InitializeOsResolver() []string
• func Log(ctx context.Context, e *zerolog.Event, format string, v ...any)
• func LookupIP(domain string) []string
• func ResolverTypeFromEndpoint(endpoint string) string
• func Rfc1918Addresses() []string
• func SetConfigName(v *viper.Viper, name string)
• func SetConfigNameWithPath(v *viper.Viper, name, configPath string)
• func ValidateConfig(validate *validator.Validate, cfg *Config) error
• type ClientInfo
• type ClientInfoCtxKey
• type Config
  • func (c *Config) FirstListener() *ListenerConfig
  • func (c *Config) FirstUpstream() *UpstreamConfig
  • func (c *Config) HasUpstreamSendClientInfo() bool
• type LeaseFileFormat
• type ListenerConfig
  • func (lc *ListenerConfig) Init()
  • func (lc *ListenerConfig) IsDirectDnsListener() bool
• type ListenerPolicyConfig
• type NetworkConfig
• type ReqIdCtxKey
• type Resolver
  • func NewBootstrapResolver(servers ...string) Resolver
  • func NewPrivateResolver() Resolver
  • func NewResolver(uc *UpstreamConfig) (Resolver, error)
  • func NewResolverWithNameserver(nameservers []string) Resolver
• type Rule
• type ServiceConfig
• type UpstreamConfig
  • func (uc *UpstreamConfig) BootstrapIPs() []string
  • func (uc *UpstreamConfig) ErrorPing() error
  • func (uc *UpstreamConfig) Init()
  • func (uc *UpstreamConfig) IsControlD() bool
  • func (uc *UpstreamConfig) IsDiscoverable() bool
  • func (uc *UpstreamConfig) Ping()
  • func (uc *UpstreamConfig) ReBootstrap()
  • func (uc *UpstreamConfig) SetCertPool(cp *x509.CertPool)
  • func (uc *UpstreamConfig) SetupBootstrapIP()
  • func (uc *UpstreamConfig) SetupTransport()
  • func (uc *UpstreamConfig) UID() string
  • func (uc *UpstreamConfig) UpstreamSendClientInfo() bool
  • func (uc *UpstreamConfig) VerifyDomain() string

Constants

const (
	// IpStackBoth indicates that ctrld will use either ipv4 or ipv6 for connecting to upstream,
	// depending on which stack is available when receiving the DNS query.
	IpStackBoth = "both"
	// IpStackV4 indicates that ctrld will use only ipv4 for connecting to upstream.
	IpStackV4 = "v4"
	// IpStackV6 indicates that ctrld will use only ipv6 for connecting to upstream.
	IpStackV6 = "v6"
	// IpStackSplit indicates that ctrld will use either ipv4 or ipv6 for connecting to upstream,
	// depending on the record type of the DNS query.
	IpStackSplit = "split"

	// FreeDnsDomain is the domain name of free ControlD service.
	FreeDnsDomain = "freedns.controld.com"
	// FreeDNSBoostrapIP is the IP address of freedns.controld.com.
	FreeDNSBoostrapIP = "76.76.2.11"
	// PremiumDnsDomain is the domain name of premium ControlD service.
	PremiumDnsDomain = "dns.controld.com"
	// PremiumDNSBoostrapIP is the IP address of dns.controld.com.
	PremiumDNSBoostrapIP = "76.76.2.22"
)

IpStackBoth ...

const (
	// ResolverTypeDOH specifies DoH resolver.
	ResolverTypeDOH = "doh"
	// ResolverTypeDOH3 specifies DoH3 resolver.
	ResolverTypeDOH3 = "doh3"
	// ResolverTypeDOT specifies DoT resolver.
	ResolverTypeDOT = "dot"
	// ResolverTypeDOQ specifies DoQ resolver.
	ResolverTypeDOQ = "doq"
	// ResolverTypeOS specifies OS resolver.
	ResolverTypeOS = "os"
	// ResolverTypeLegacy specifies legacy resolver.
	ResolverTypeLegacy = "legacy"
	// ResolverTypePrivate is like ResolverTypeOS, but use for local resolver only.
	ResolverTypePrivate = "private"
)

Variables

var DecodeArchNameMap = map[string]string{}

DecodeArchNameMap provides mapping from encoded OS arch to real value, used for decoding x-cd-os value.

var DecodeOsNameMap = map[string]string{}

DecodeOsNameMap provides mapping from encoded OS name to real value, used for decoding x-cd-os value.

var EncodeArchNameMap = map[string]string{
	"amd64":  "1",
	"arm64":  "2",
	"arm":    "3",
	"386":    "4",
	"mips":   "5",
	"mipsle": "6",
	"mips64": "7",
}

EncodeArchNameMap provides mapping from OS arch to a shorter string, used for encoding x-cd-os value.

var EncodeOsNameMap = map[string]string{
	"windows": "1",
	"darwin":  "2",
	"linux":   "3",
	"freebsd": "4",
}

EncodeOsNameMap provides mapping from OS name to a shorter string, used for encoding x-cd-os value.

var ProxyLog = zerolog.New(io.Discard)

ProxyLog emits the log record for proxy operations. The caller should set it only once. DEPRECATED: use ProxyLogger instead.

var ProxyLogger atomic.Pointer[zerolog.Logger]

ProxyLogger emits the log record for proxy operations.

Functions

func InitConfig

func InitConfig(v *viper.Viper, name string)

InitConfig initializes default config values for given *viper.Viper instance.

func InitializeOsResolver

func InitializeOsResolver() []string

InitializeOsResolver initializes OS resolver using the current system DNS settings. It returns the nameservers that is going to be used by the OS resolver.

It's the caller's responsibility to ensure the system DNS is in a clean state before calling this function.

func Log

func Log(ctx context.Context, e *zerolog.Event, format string, v ...any)

Log emits the logs for a particular zerolog event. The request id associated with the context will be included if presents.

func LookupIP

func LookupIP(domain string) []string

LookupIP looks up host using OS resolver. It returns a slice of that host's IPv4 and IPv6 addresses.

func ResolverTypeFromEndpoint

func ResolverTypeFromEndpoint(endpoint string) string

ResolverTypeFromEndpoint tries guessing the resolver type with a given endpoint using following rules:

- If endpoint is an IP address -> ResolverTypeLegacy - If endpoint starts with "https://" -> ResolverTypeDOH - If endpoint starts with "quic://" -> ResolverTypeDOQ - For anything else -> ResolverTypeDOT

func Rfc1918Addresses

func Rfc1918Addresses() []string

Rfc1918Addresses returns the list of local interfaces private IP addresses

func SetConfigName

func SetConfigName(v *viper.Viper, name string)

SetConfigName set the config name that ctrld will look for. DEPRECATED: use SetConfigNameWithPath instead.

func SetConfigNameWithPath

func SetConfigNameWithPath(v *viper.Viper, name, configPath string)

SetConfigNameWithPath set the config path and name that ctrld will look for.

func ValidateConfig

func ValidateConfig(validate *validator.Validate, cfg *Config) error

ValidateConfig validates the given config.

Types

type ClientInfo

type ClientInfo struct {
	Mac          string
	IP           string
	Hostname     string
	Self         bool
	ClientIDPref string
}

ClientInfo represents ctrld's clients information.

type ClientInfoCtxKey

type ClientInfoCtxKey struct{}

ClientInfoCtxKey is the context key to store client info.

type Config

type Config struct {
	Service  ServiceConfig              `mapstructure:"service" toml:"service,omitempty"`
	Listener map[string]*ListenerConfig `mapstructure:"listener" toml:"listener" validate:"min=1,dive"`
	Network  map[string]*NetworkConfig  `mapstructure:"network" toml:"network" validate:"min=1,dive"`
	Upstream map[string]*UpstreamConfig `mapstructure:"upstream" toml:"upstream" validate:"min=1,dive"`
}

Config represents ctrld supported configuration.

func (*Config) FirstListener

func (c *Config) FirstListener() *ListenerConfig

FirstListener returns the first listener config of current config. Listeners are sorted numerically.

It panics if Config has no listeners configured.

func (*Config) FirstUpstream

func (c *Config) FirstUpstream() *UpstreamConfig

FirstUpstream returns the first upstream of current config. Upstreams are sorted numerically.

It panics if Config has no upstreams configured.

func (*Config) HasUpstreamSendClientInfo

func (c *Config) HasUpstreamSendClientInfo() bool

HasUpstreamSendClientInfo reports whether the config has any upstream is configured to send client info to Control D DNS server.

type LeaseFileFormat

type LeaseFileFormat string

LeaseFileFormat specifies the format of DHCP lease file.

const (
	Dnsmasq  LeaseFileFormat = "dnsmasq"
	IscDhcpd LeaseFileFormat = "isc-dhcpd"
	KeaDHCP4 LeaseFileFormat = "kea-dhcp4"
)

type ListenerConfig

type ListenerConfig struct {
	IP              string                `mapstructure:"ip" toml:"ip,omitempty" validate:"iporempty"`
	Port            int                   `mapstructure:"port" toml:"port,omitempty" validate:"gte=0"`
	Restricted      bool                  `mapstructure:"restricted" toml:"restricted,omitempty"`
	AllowWanClients bool                  `mapstructure:"allow_wan_clients" toml:"allow_wan_clients,omitempty"`
	Policy          *ListenerPolicyConfig `mapstructure:"policy" toml:"policy,omitempty"`
}

ListenerConfig specifies the networks configuration that ctrld will run on.

func (*ListenerConfig) Init

func (lc *ListenerConfig) Init()

Init initialized necessary values for an ListenerConfig.

func (*ListenerConfig) IsDirectDnsListener

func (lc *ListenerConfig) IsDirectDnsListener() bool

IsDirectDnsListener reports whether ctrld can be a direct listener on port 53. It returns true only if ctrld can listen on port 53 for all interfaces. That means there's no other software listening on port 53.

If someone listening on port 53, or ctrld could only listen on port 53 for a specific interface, ctrld could only be configured as a DNS forwarder.

type ListenerPolicyConfig

type ListenerPolicyConfig struct {
	Name                 string   `mapstructure:"name" toml:"name,omitempty"`
	Networks             []Rule   `mapstructure:"networks" toml:"networks,omitempty,inline,multiline" validate:"dive,len=1"`
	Rules                []Rule   `mapstructure:"rules" toml:"rules,omitempty,inline,multiline" validate:"dive,len=1"`
	Macs                 []Rule   `mapstructure:"macs" toml:"macs,omitempty,inline,multiline" validate:"dive,len=1"`
	FailoverRcodes       []string `mapstructure:"failover_rcodes" toml:"failover_rcodes,omitempty" validate:"dive,dnsrcode"`
	FailoverRcodeNumbers []int    `mapstructure:"-" toml:"-"`
}

ListenerPolicyConfig specifies the policy rules for ctrld to filter incoming requests.

type NetworkConfig

type NetworkConfig struct {
	Name   string       `mapstructure:"name" toml:"name,omitempty"`
	Cidrs  []string     `mapstructure:"cidrs" toml:"cidrs,omitempty" validate:"dive,cidr"`
	IPNets []*net.IPNet `mapstructure:"-" toml:"-"`
}

NetworkConfig specifies configuration for networks where ctrld will handle requests.

type ReqIdCtxKey

type ReqIdCtxKey struct{}

ReqIdCtxKey is the context.Context key for a request id.

type Resolver

type Resolver interface {
	Resolve(ctx context.Context, msg *dns.Msg) (*dns.Msg, error)
}

Resolver is the interface that wraps the basic DNS operations.

Resolve resolves the DNS query, return the result and the corresponding error.

func NewBootstrapResolver

func NewBootstrapResolver(servers ...string) Resolver

NewBootstrapResolver returns an OS resolver, which use following nameservers:

• Gateway IP address (depends on OS).
• Input servers.

func NewPrivateResolver

func NewPrivateResolver() Resolver

NewPrivateResolver returns an OS resolver, which includes only private DNS servers, excluding:

- Nameservers from /etc/resolv.conf file. - Nameservers which is local RFC1918 addresses.

This is useful for doing PTR lookup in LAN network.

func NewResolver

func NewResolver(uc *UpstreamConfig) (Resolver, error)

NewResolver creates a Resolver based on the given upstream config.

func NewResolverWithNameserver

func NewResolverWithNameserver(nameservers []string) Resolver

NewResolverWithNameserver returns an OS resolver which uses the given nameservers for resolving DNS queries. If nameservers is empty, a dummy resolver will be returned.

Each nameserver must be form "host:port". It's the caller responsibility to ensure all nameservers are well formatted by using net.JoinHostPort function.

type Rule

type Rule map[string][]string

Rule is a map from source to list of upstreams. ctrld uses rule to perform requests matching and forward the request to corresponding upstreams if it's matched.

type ServiceConfig

type ServiceConfig struct {
	LogLevel                string         `mapstructure:"log_level" toml:"log_level,omitempty"`
	LogPath                 string         `mapstructure:"log_path" toml:"log_path,omitempty"`
	CacheEnable             bool           `mapstructure:"cache_enable" toml:"cache_enable,omitempty"`
	CacheSize               int            `mapstructure:"cache_size" toml:"cache_size,omitempty"`
	CacheTTLOverride        int            `mapstructure:"cache_ttl_override" toml:"cache_ttl_override,omitempty"`
	CacheServeStale         bool           `mapstructure:"cache_serve_stale" toml:"cache_serve_stale,omitempty"`
	CacheFlushDomains       []string       `mapstructure:"cache_flush_domains" toml:"cache_flush_domains" validate:"max=256"`
	MaxConcurrentRequests   *int           `mapstructure:"max_concurrent_requests" toml:"max_concurrent_requests,omitempty" validate:"omitempty,gte=0"`
	DHCPLeaseFile           string         `mapstructure:"dhcp_lease_file_path" toml:"dhcp_lease_file_path" validate:"omitempty,file"`
	DHCPLeaseFileFormat     string         `` /* 144-byte string literal not displayed */
	DiscoverMDNS            *bool          `mapstructure:"discover_mdns" toml:"discover_mdns,omitempty"`
	DiscoverARP             *bool          `mapstructure:"discover_arp" toml:"discover_arp,omitempty"`
	DiscoverDHCP            *bool          `mapstructure:"discover_dhcp" toml:"discover_dhcp,omitempty"`
	DiscoverPtr             *bool          `mapstructure:"discover_ptr" toml:"discover_ptr,omitempty"`
	DiscoverHosts           *bool          `mapstructure:"discover_hosts" toml:"discover_hosts,omitempty"`
	DiscoverRefreshInterval int            `mapstructure:"discover_refresh_interval" toml:"discover_refresh_interval,omitempty"`
	ClientIDPref            string         `mapstructure:"client_id_preference" toml:"client_id_preference,omitempty" validate:"omitempty,oneof=host mac"`
	MetricsQueryStats       bool           `mapstructure:"metrics_query_stats" toml:"metrics_query_stats,omitempty"`
	MetricsListener         string         `mapstructure:"metrics_listener" toml:"metrics_listener,omitempty"`
	DnsWatchdogEnabled      *bool          `mapstructure:"dns_watchdog_enabled" toml:"dns_watchdog_enabled,omitempty"`
	DnsWatchdogInvterval    *time.Duration `mapstructure:"dns_watchdog_interval" toml:"dns_watchdog_interval,omitempty"`
	RefetchTime             *int           `mapstructure:"refetch_time" toml:"refetch_time,omitempty"`
	Daemon                  bool           `mapstructure:"-" toml:"-"`
	AllocateIP              bool           `mapstructure:"-" toml:"-"`
}

ServiceConfig specifies the general ctrld config.

type UpstreamConfig

type UpstreamConfig struct {
	Name        string `mapstructure:"name" toml:"name,omitempty"`
	Type        string `mapstructure:"type" toml:"type,omitempty" validate:"oneof=doh doh3 dot doq os legacy"`
	Endpoint    string `mapstructure:"endpoint" toml:"endpoint,omitempty"`
	BootstrapIP string `mapstructure:"bootstrap_ip" toml:"bootstrap_ip,omitempty"`
	Domain      string `mapstructure:"-" toml:"-"`
	IPStack     string `mapstructure:"ip_stack" toml:"ip_stack,omitempty" validate:"ipstack"`
	Timeout     int    `mapstructure:"timeout" toml:"timeout,omitempty" validate:"gte=0"`
	// The caller should not access this field directly.
	// Use UpstreamSendClientInfo instead.
	SendClientInfo *bool `mapstructure:"send_client_info" toml:"send_client_info,omitempty"`
	// The caller should not access this field directly.
	// Use IsDiscoverable instead.
	Discoverable *bool `mapstructure:"discoverable" toml:"discoverable"`
	// contains filtered or unexported fields
}

UpstreamConfig specifies configuration for upstreams that ctrld will forward requests to.

func (*UpstreamConfig) BootstrapIPs

func (uc *UpstreamConfig) BootstrapIPs() []string

BootstrapIPs returns the bootstrap IPs list of upstreams.

func (*UpstreamConfig) ErrorPing

func (uc *UpstreamConfig) ErrorPing() error

ErrorPing is like Ping, but return an error if any.

func (*UpstreamConfig) Init

func (uc *UpstreamConfig) Init()

Init initialized necessary values for an UpstreamConfig.

func (*UpstreamConfig) IsControlD

func (uc *UpstreamConfig) IsControlD() bool

IsControlD reports whether this is a ControlD upstream.

func (*UpstreamConfig) IsDiscoverable

func (uc *UpstreamConfig) IsDiscoverable() bool

IsDiscoverable reports whether the upstream can be used for PTR discovery. The caller must ensure uc.Init() was called before calling this.

func (*UpstreamConfig) Ping

func (uc *UpstreamConfig) Ping()

Ping warms up the connection to DoH/DoH3 upstream.

func (*UpstreamConfig) ReBootstrap

func (uc *UpstreamConfig) ReBootstrap()

ReBootstrap re-setup the bootstrap IP and the transport.

func (*UpstreamConfig) SetCertPool

func (uc *UpstreamConfig) SetCertPool(cp *x509.CertPool)

SetCertPool sets the system cert pool used for TLS connections.

func (*UpstreamConfig) SetupBootstrapIP

func (uc *UpstreamConfig) SetupBootstrapIP()

SetupBootstrapIP manually find all available IPs of the upstream. The first usable IP will be used as bootstrap IP of the upstream.

func (*UpstreamConfig) SetupTransport

func (uc *UpstreamConfig) SetupTransport()

SetupTransport initializes the network transport used to connect to upstream server. For now, only DoH upstream is supported.

func (*UpstreamConfig) UID

func (uc *UpstreamConfig) UID() string

UID returns the unique identifier of the upstream.

func (*UpstreamConfig) UpstreamSendClientInfo

func (uc *UpstreamConfig) UpstreamSendClientInfo() bool

UpstreamSendClientInfo reports whether the upstream is configured to send client info to Control D DNS server.

Client info includes:

• MAC
• Lan IP
• Hostname

func (*UpstreamConfig) VerifyDomain

func (uc *UpstreamConfig) VerifyDomain() string

VerifyDomain returns the domain name that could be resolved by the upstream endpoint. It returns empty for non-ControlD upstream endpoint.