ctrld

package module
v1.4.4 Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2025 License: MIT Imports: 43 Imported by: 0

README

ctrld

Test Go Reference Go Report Card

ctrld splash image

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 (via network cidr, MAC address or FQDN)
  • 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)
  • Windows Server (386, amd64)
  • MacOS (amd64, arm64)
  • Linux (386, amd64, arm, mips)
  • FreeBSD (386, amd64, arm)
  • Common routers (See below)
Supported Routers

You can run ctrld on any supported router. 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 (or Windows Server) 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.

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 PowerShell:

(Invoke-WebRequest -Uri 'https://api.controld.com/dl/ps1' -UseBasicParsing).Content | Set-Content "$env:TEMPctrld_install.ps1"; Invoke-Expression "& '$env:TEMPctrld_install.ps1'"

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

docker run -d --name=ctrld -p 127.0.0.1:53:53/tcp -p 127.0.0.1:53:53/udp controldns/ctrld:latest

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

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
  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
  service     Manage ctrld service
  clients     Manage clients
  upgrade     Upgrading ctrld to latest version
  log         Manage runtime debug logs

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

This is the most basic way to run ctrld, in foreground mode. Unless you already have a config file, a default one will be generated.

Command

Windows (Admin Shell)

ctrld.exe run

Linux or Macos

sudo ctrld run

You can then 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 that was generated. To enforce a new config, restart the server.

Service Mode

This mode will run the application as a background system service on any Windows, MacOS, Linux, FreeBSD distribution or supported router. This will create a generic ctrld.toml file in the C:\ControlD directory (on Windows) or /etc/controld/ (almost everywhere else), start the system service, and configure the listener on all physical network interface. Service will start on OS boot.

When Control D upstreams are used on a router type device, ctrld will 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.

Command

Windows (Admin Shell)

ctrld.exe start

Linux or Macos

sudo ctrld start

If ctrld is not in your system path (you installed it manually), you will need to run the above commands from the directory where you installed ctrld.

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.

Unmanaged Service Mode

This mode functions similarly to the "Service Mode" above except it will simply start a system service and the config defined listeners, but will not make any changes to any network interfaces. You can then set the ctrld listener(s) IP on the desired network interfaces manually.

Command

Windows (Admin Shell)

ctrld.exe service start

Linux or Macos

sudo ctrld service start

Configuration

ctrld can be configured in variety of different ways, which include: API, local config file or via cli launch args.

API Based Auto Configuration

Application can be started with a specific Control D resolver config, instead of the default one. Simply supply your Resolver ID with a --cd flag, when using the start (service) mode. In this mode, the application will automatically choose a non-conflicting IP and/or port and configure itself as the upstream to whatever process is running on port 53 (like dnsmasq or Windows DNS Server). This mode is used when the 1 liner installer command from the Control D onboarding guide is executed.

The following command will 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 Endpoint.

Windows (Admin Shell)

ctrld.exe start --cd abcd1234

Linux or Macos

sudo ctrld start --cd abcd1234

Once you run the above command, 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
  • All physical network interface will be updated to use the listener started by the service or dnsmasq upstream will be switched to ctrld
  • All DNS queries will be sent to the listener

Manual Configuration

ctrld is entirely config driven and can be configured in many different ways, please see Configuration Docs.

Example
[listener]

  [listener.0]
    ip = '0.0.0.0'
    port = 53

[network]

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

[upstream]

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

The above basic config will:

  • Start listener on 0.0.0.0:53
  • Accept queries from any source address
  • Send all queries to https://freedns.controld.com/p1 using DoH protocol

CLI Args

If you're unable to use a config file, ctrld can be be supplied with basic configuration via launch arguments, in Ephemeral Mode.

Example
ctrld run --listen=127.0.0.1:53 --primary_upstream=https://freedns.controld.com/p2 --secondary_upstream=10.0.10.1:53 --domains=*.company.int,very-secure.local --log /path/to/log.log

The above will start a foreground process and:

  • Listen on 127.0.0.1:53 for DNS queries
  • Forward all queries to https://freedns.controld.com/p2 using DoH protocol, while...
  • Excluding *.company.int and very-secure.local matching queries, that are forwarded to 10.0.10.1:53
  • Write a debug log to /path/to/log.log

Contributing

See Contribution Guideline

Documentation

Index

Constants

View Source 
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"
	// FreeDNSBoostrapIPv6 is the IPv6 address of freedns.controld.com.
	FreeDNSBoostrapIPv6 = "2606:1a40::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"
	// PremiumDNSBoostrapIPv6 is the IPv6 address of dns.controld.com.
	PremiumDNSBoostrapIPv6 = "2606:1a40::22"
)

IpStackBoth ...

View Source 
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 private resolver only.
	ResolverTypePrivate = "private"
	// ResolverTypeLocal is like ResolverTypeOS, but use for local resolver only.
	ResolverTypeLocal = "local"
	// ResolverTypeSDNS specifies resolver with information encoded using DNS Stamps.
	// See: https://dnscrypt.info/stamps-specifications/
	ResolverTypeSDNS = "sdns"
)

Variables

View Source 
var DecodeArchNameMap = map[string]string{}

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

View Source 
var DecodeOsNameMap = map[string]string{}

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

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

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

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

View Source 
var ProxyLogger atomic.Pointer[zerolog.Logger]

ProxyLogger emits the log record for proxy operations.

Functions

func DisableIPv6 added in v1.4.2 

func DisableIPv6()

DisableIPv6 marks IPv6 as unavailable if enabled.

func GetDefaultLocalIPv4 added in v1.4.0 

func GetDefaultLocalIPv4() net.IP

GetDefaultLocalIPv4 returns the stored local IPv4 or nil if none.

func GetDefaultLocalIPv6 added in v1.4.0 

func GetDefaultLocalIPv6() net.IP

GetDefaultLocalIPv6 returns the stored local IPv6 or nil if none.

func HasIPv6 added in v1.4.2 

func HasIPv6() bool

HasIPv6 reports whether the current network stack has IPv6 available.

func InitConfig 

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

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

func InitializeOsResolver added in v1.3.7 

func InitializeOsResolver(guardAgainstNoNameservers bool) []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 IsDesktopPlatform added in v1.4.4 

func IsDesktopPlatform() bool

IsDesktopPlatform indicates if ctrld is running on a desktop platform, currently defined as macOS or Windows workstation.

func LanQueryCtx added in v1.4.0 

func LanQueryCtx(ctx context.Context) context.Context

LanQueryCtx returns a context.Context with LanQueryCtxKey set.

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 added in v1.2.0 

func LookupIP(domain string) []string

LookupIP looks up domain using current system nameservers settings. It returns a slice of that host's IPv4 and IPv6 addresses.

func ResolverTypeFromEndpoint added in v1.1.4 

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 - If endpoint starts with "h3://" -> ResolverTypeDOH3 - If endpoint starts with "sdns://" -> ResolverTypeSDNS - For anything else -> ResolverTypeDOT

func Rfc1918Addresses added in v1.3.2 

func Rfc1918Addresses() []string

Rfc1918Addresses returns the list of local interfaces private IP addresses

func SavedStaticDnsSettingsFilePath added in v1.4.1 

func SavedStaticDnsSettingsFilePath(iface *net.Interface) string

SavedStaticDnsSettingsFilePath returns the file path where the static DNS settings for the provided interface are saved.

func SavedStaticNameservers added in v1.4.1 

func SavedStaticNameservers(iface *net.Interface) ([]string, string)

SavedStaticNameservers returns the stored static nameservers for the given interface.

func SelfDiscover added in v1.4.2 

func SelfDiscover() bool

SelfDiscover reports whether ctrld should only do self discover.

func SetCacheReply added in v1.4.4 

func SetCacheReply(answer, msg *dns.Msg, code int)

SetCacheReply extracts and stores the necessary data from the message for a cached answer.

func SetConfigName added in v1.1.0 

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

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

func SetConfigNameWithPath added in v1.2.0 

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

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

func SetDefaultLocalIPv4 added in v1.4.0 

func SetDefaultLocalIPv4(ip net.IP)

SetDefaultLocalIPv4 updates the stored local IPv4.

func SetDefaultLocalIPv6 added in v1.4.0 

func SetDefaultLocalIPv6(ip net.IP)

SetDefaultLocalIPv6 updates the stored local IPv6.

func ValidateConfig 

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

ValidateConfig validates the given config.

Types

type ClientInfo added in v1.2.0 

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

ClientInfo represents ctrld's clients information.

type ClientInfoCtxKey added in v1.2.0 

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 added in v1.3.0 

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 added in v1.3.0 

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 added in v1.2.0 

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 LanQueryCtxKey added in v1.4.0 

type LanQueryCtxKey struct{}

LanQueryCtxKey is the context.Context key to indicate that the request is for LAN network.

type LeaseFileFormat added in v1.3.0 

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 added in v1.3.0 

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 added in v1.2.1 

func NewBootstrapResolver(servers ...string) Resolver

NewBootstrapResolver returns an OS resolver, which use following nameservers:

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

func NewPrivateResolver added in v1.3.0 

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 added in v1.3.2 

func NewResolverWithNameserver(nameservers []string) Resolver

NewResolverWithNameserver returns a 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         `` /* 154-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"`
	ForceRefetchWaitTime    *int           `mapstructure:"force_refetch_wait_time" toml:"force_refetch_wait_time,omitempty"`
	LeakOnUpstreamFailure   *bool          `mapstructure:"leak_on_upstream_failure" toml:"leak_on_upstream_failure,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 sdns ''"`
	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 added in v1.2.0 

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

BootstrapIPs returns the bootstrap IPs list of upstreams.

func (*UpstreamConfig) Context added in v1.4.2 

func (uc *UpstreamConfig) Context(ctx context.Context) (context.Context, context.CancelFunc)

Context returns a new context with timeout set from upstream config.

func (*UpstreamConfig) ErrorPing added in v1.3.6 

func (uc *UpstreamConfig) ErrorPing() error

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

func (*UpstreamConfig) FallbackToDirectIP added in v1.4.2 

func (uc *UpstreamConfig) FallbackToDirectIP() bool

FallbackToDirectIP changes ControlD upstream endpoint to use direct IP instead of domain.

func (*UpstreamConfig) Init 

func (uc *UpstreamConfig) Init()

Init initialized necessary values for an UpstreamConfig.

func (*UpstreamConfig) IsControlD added in v1.3.8 

func (uc *UpstreamConfig) IsControlD() bool

IsControlD reports whether this is a ControlD upstream.

func (*UpstreamConfig) IsDiscoverable added in v1.3.2 

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 added in v1.3.0 

func (uc *UpstreamConfig) Ping()

Ping warms up the connection to DoH/DoH3 upstream.

func (*UpstreamConfig) ReBootstrap added in v1.1.1 

func (uc *UpstreamConfig) ReBootstrap()

ReBootstrap re-setup the bootstrap IP and the transport.

func (*UpstreamConfig) SetCertPool added in v1.2.0 

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

SetCertPool sets the system cert pool used for TLS connections.

func (*UpstreamConfig) SetupBootstrapIP added in v1.1.1 

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. The upstream domain will be looked up using following orders:

- Current system DNS settings. - Direct IPs table for ControlD upstreams. - ControlD Bootstrap DNS 76.76.2.22

The setup process will block until there's usable IPs found.

func (*UpstreamConfig) SetupTransport added in v1.1.0 

func (uc *UpstreamConfig) SetupTransport()

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

func (*UpstreamConfig) String added in v1.4.0 

func (uc *UpstreamConfig) String() string

String returns a string representation of the UpstreamConfig for logging.

func (*UpstreamConfig) UID added in v1.3.1 

func (uc *UpstreamConfig) UID() string

UID returns the unique identifier of the upstream.

func (*UpstreamConfig) UpstreamSendClientInfo added in v1.2.0 

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 added in v1.2.1 

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
cli
ctrld
ctrld_library
internal
certs
clientinfo
controld
dns
dns/resolvconffile
Package resolvconffile parses & serializes /etc/resolv.conf-style files.
 Package resolvconffile parses & serializes /etc/resolv.conf-style files.
dnscache
dnsrcode
net
resolvconffile
router
router/ddwrt
router/dnsmasq
router/edgeos
router/firewalla
router/merlin
router/netgear_orbi_voxel
router/ntp
router/nvram
router/openwrt
router/synology
router/tomato
router/ubios

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.