config

type Blocking struct {
	// Named groups of block-list sources (URLs, file paths, or inline content).
	Denylists map[string][]BytesSource `yaml:"denylists"`
	// Named groups of allow-list sources; entries here take precedence over denylists in the same group.
	Allowlists map[string][]BytesSource `yaml:"allowlists"`
	// Named time-based schedules that can gate when list groups are active.
	Schedules map[string]Schedule `yaml:"schedules"`
	// Maps each list group name to the schedule(s) that control when it is active.
	ListSchedules map[string][]string `yaml:"listSchedules"`
	// Maps client identifiers (name, IP, CIDR) to the list groups that apply to them.
	ClientGroupsBlock map[string][]string `yaml:"clientGroupsBlock"`
	// Response for blocked A/AAAA queries: zeroIP (0.0.0.0/::), nxDomain, or custom IPs; other types get NXDOMAIN.
	BlockType string `default:"ZEROIP" yaml:"blockType"`
	// TTL of blocked responses; how long clients cache the block before querying the domain again.
	BlockTTL Duration `default:"6h" yaml:"blockTTL"`
	// Controls how block/allow lists are loaded and periodically refreshed.
	Loading SourceLoading `yaml:"loading"`

	// Deprecated options
	Deprecated struct {
		BlackLists            *map[string][]BytesSource `yaml:"blackLists"`
		WhiteLists            *map[string][]BytesSource `yaml:"whiteLists"`
		DownloadTimeout       *Duration                 `yaml:"downloadTimeout"`
		DownloadAttempts      *uint                     `yaml:"downloadAttempts"`
		DownloadCooldown      *Duration                 `yaml:"downloadCooldown"`
		RefreshPeriod         *Duration                 `yaml:"refreshPeriod"`
		FailStartOnListError  *bool                     `yaml:"failStartOnListError"`
		ProcessingConcurrency *uint                     `yaml:"processingConcurrency"`
		StartStrategy         *InitStrategy             `yaml:"startStrategy"`
		MaxErrorsPerFile      *int                      `yaml:"maxErrorsPerFile"`
	} `yaml:",inline"`
}

type BootstrapDNS bootstrapDNS

type BootstrappedUpstream bootstrappedUpstream

type BytesSource struct {
	Type BytesSourceType
	From string
}

type BytesSourceType uint16

type Caching struct {
	// Minimum TTL for cached entries; if the response TTL is smaller, this value is used instead.
	MinCachingTime Duration `yaml:"minTime"`
	// Maximum TTL for cached entries. If <0, caching is disabled. If 0, the response TTL is used.
	MaxCachingTime Duration `yaml:"maxTime"`
	// TTL for negative responses (NXDOMAIN / empty). Use -1 to disable caching of negative results.
	CacheTimeNegative Duration `default:"30m" yaml:"cacheTimeNegative"`
	// Maximum number of cache entries (soft limit). 0 means unlimited.
	MaxItemsCount int `yaml:"maxItemsCount"`
	// If true, blocky preloads DNS results for frequently queried names before they expire.
	Prefetching bool `yaml:"prefetching"`
	// Time window used to track query frequency for prefetch eligibility.
	PrefetchExpires Duration `default:"2h" yaml:"prefetchExpires"`
	// Minimum number of queries within prefetchExpires required to trigger prefetching.
	PrefetchThreshold int `default:"5" yaml:"prefetchThreshold"`
	// Maximum number of domains tracked for prefetching (soft limit). 0 means unlimited.
	PrefetchMaxItemsCount int `yaml:"prefetchMaxItemsCount"`
	// Regex list of domains that are never cached.
	Exclude []string `yaml:"exclude"`
}

type CertificateFingerprint []byte

type ClientLookup struct {
	// Static map of client name to one or more IP addresses for manual client name assignment.
	ClientnameIPMapping map[string][]net.IP `yaml:"clients"`
	// Upstream DNS server used for rDNS client name lookups (typically your router).
	Upstream Upstream `yaml:"upstream"`
	// Order of preference when a router returns multiple names for a client (1-based index).
	SingleNameOrder []uint `yaml:"singleNameOrder"`
}

type ConditionalUpstream struct {
	RewriterConfig `yaml:",inline"`

	// Domain-to-upstream mappings; queries for each domain are forwarded to its configured resolver(s).
	Mapping ConditionalUpstreamMapping `yaml:"mapping"`
}

type ConditionalUpstreamMapping struct {
	Upstreams map[string][]Upstream
}

type Config struct {
	// Upstream DNS servers and strategy configuration.
	Upstreams Upstreams `yaml:"upstreams"`
	// IP version used for outgoing connections (dual, v4, v6).
	ConnectIPVersion IPVersion `yaml:"connectIPVersion"`
	// Custom static DNS mappings and zone definitions.
	CustomDNS CustomDNS `yaml:"customDNS"`
	// Conditional upstream resolvers for specific domains.
	Conditional ConditionalUpstream `yaml:"conditional"`
	// Blocking configuration with allow/denylists and client groups.
	Blocking Blocking `yaml:"blocking"`
	// Client name lookup configuration for resolving client identifiers.
	ClientLookup ClientLookup `yaml:"clientLookup"`
	// DNS response caching settings.
	Caching Caching `yaml:"caching"`
	// Query logging configuration.
	QueryLog QueryLog `yaml:"queryLog"`
	// Prometheus metrics configuration.
	Prometheus Metrics `yaml:"prometheus"`
	// In-memory statistics subsystem (24h window), served at /api/stats.
	Statistics Statistics `yaml:"statistics"`
	// Redis configuration for cache and state synchronization between instances.
	Redis Redis `yaml:"redis"`
	// Logging configuration.
	Log log.Config `yaml:"log"`
	// Listen addresses for DNS, HTTP, HTTPS, and TLS.
	Ports Ports `yaml:"ports"`
	// Minimum TLS version the DoT and DoH servers use to serve encrypted DNS requests.
	MinTLSServeVer TLSVersion `default:"1.2" yaml:"minTlsServeVersion"`
	// Path to the TLS certificate file for DoH and DoT; if empty, a self-signed certificate is generated.
	CertFile string `yaml:"certFile"`
	// Path to the TLS key file for DoH and DoT; if empty, a self-signed certificate is generated.
	KeyFile string `yaml:"keyFile"`
	// Bootstrap DNS servers used to resolve DoH/DoT upstream hostnames.
	BootstrapDNS BootstrapDNS `yaml:"bootstrapDns"`
	// Local hosts file resolution settings.
	HostsFile HostsFile `yaml:"hostsFile"`
	// When enabled, blocky returns NXDOMAIN immediately for non-FQDN queries.
	FQDNOnly FQDNOnly `yaml:"fqdnOnly"`
	// DNS query type filtering configuration.
	Filtering Filtering `yaml:"filtering"`
	// Extended DNS Errors (RFC 8914) configuration.
	EDE EDE `yaml:"ede"`
	// EDNS Client Subnet options.
	ECS ECS `yaml:"ecs"`
	// Special Use Domain Names (SUDN) blocking configuration.
	SUDN SUDN `yaml:"specialUseDomains"`
	// DNS64 synthesis configuration for IPv6-only clients (RFC 6147).
	DNS64 DNS64 `yaml:"dns64"`
	// DNSSEC validation configuration.
	DNSSEC DNSSEC `yaml:"dnssec"`
	// HTTP/3 (DoH3) server configuration.
	HTTP3 HTTP3 `yaml:"http3"`
	// Per-client DNS query rate limiting configuration.
	RateLimit RateLimit `yaml:"rateLimit"`
	// DNS rebinding protection configuration.
	RebindingProtection RebindingProtection `yaml:"rebindingProtection"`

	// Deprecated options
	Deprecated struct {
		Upstream            *UpstreamGroups `yaml:"upstream"`
		UpstreamTimeout     *Duration       `yaml:"upstreamTimeout"`
		DisableIPv6         *bool           `yaml:"disableIPv6"`
		LogLevel            *logrus.Level   `yaml:"logLevel"`
		LogFormat           *log.FormatType `yaml:"logFormat"`
		LogPrivacy          *bool           `yaml:"logPrivacy"`
		LogTimestamp        *bool           `yaml:"logTimestamp"`
		DNSPorts            *ListenConfig   `yaml:"port"`
		HTTPPorts           *ListenConfig   `yaml:"httpPort"`
		HTTPSPorts          *ListenConfig   `yaml:"httpsPort"`
		TLSPorts            *ListenConfig   `yaml:"tlsPort"`
		StartVerifyUpstream *bool           `yaml:"startVerifyUpstream"`
		DoHUserAgent        *string         `yaml:"dohUserAgent"`
	} `yaml:",inline"`
}

type Configurable interface {
	// IsEnabled returns true when the receiver is configured.
	IsEnabled() bool

	// LogConfig logs the receiver's configuration.
	//
	// The behavior of this method is undefined when `IsEnabled` returns false.
	LogConfig(logger *logrus.Entry)
}

type CustomDNS struct {
	RewriterConfig `yaml:",inline"`

	// TTL for DNS records defined in the mapping section (does not apply to zone file records).
	CustomTTL Duration `default:"1h" yaml:"customTTL"`
	// Simple domain-to-IP mappings; multiple IPs per domain separated by commas.
	Mapping CustomDNSMapping `yaml:"mapping"`
	// DNS zone file content for more complex record definitions (A, AAAA, CNAME, TXT, SRV).
	Zone ZoneFileDNS `default:"" yaml:"zone"`
	// If true, queries for types not defined for a domain return empty; if false, they are forwarded upstream.
	FilterUnmappedTypes bool `default:"true" yaml:"filterUnmappedTypes"`
}

type CustomDNSEntries []dns.RR

type CustomDNSMapping map[string]CustomDNSEntries

type DNS64 struct {
	// Enable DNS64 synthesis of AAAA records from A records for IPv6-only clients (RFC 6147).
	Enable bool `default:"false" yaml:"enable"`
	// IPv6 prefixes used for synthesis; valid lengths are /32, /40, /48, /56, /64, /96 (default: 64:ff9b::/96).
	Prefixes []netip.Prefix `yaml:"prefixes"`
	// IPv6 prefixes excluded from triggering synthesis. Overrides the default exclusion set; advanced use only.
	ExclusionSet []netip.Prefix `yaml:"exclusionSet"`
}

type DNSSEC struct {
	// Enable DNSSEC validation of DNS responses.
	Validate bool `default:"false" yaml:"validate"`
	// Custom trust anchors (DNSKEY or DS records); empty uses built-in IANA root trust anchors.
	TrustAnchors []string `yaml:"trustAnchors"`
	// Maximum domain label depth for chain of trust validation (DoS protection).
	MaxChainDepth uint `default:"10" yaml:"maxChainDepth"`
	// How long to cache DNSSEC validation results, in hours.
	CacheExpirationHours uint `default:"1"   yaml:"cacheExpirationHours"`
	MaxNSEC3Iterations   uint `default:"150" yaml:"maxNSEC3Iterations"` // RFC 5155 §10.3
	// DoS protection: max upstream queries per validation
	MaxUpstreamQueries uint `default:"30" yaml:"maxUpstreamQueries"`
	// Clock skew tolerance in seconds for signature validation (default: 3600 = 1 hour)
	// Allows validation to succeed even if system clock is off by this amount.
	// Matches Unbound/BIND defaults for real-world deployments (VMs, containers, embedded systems).
	// Per RFC 6781 §4.1.2: Validators should account for clock skew in deployment environments.
	ClockSkewToleranceSec uint `default:"3600" yaml:"clockSkewToleranceSec"`
}

type Downloader struct {
	// Timeout per download attempt (default: 5s).
	Timeout Duration `default:"5s" yaml:"timeout"`
	// Timeout for reading the download response body (default: 20s).
	ReadTimeout Duration `default:"20s" yaml:"readTimeout"`
	// Timeout for reading the download response headers (default: 20s).
	ReadHeaderTimeout Duration `default:"20s" yaml:"readHeaderTimeout"`
	// Timeout for writing the downloaded file (default: 20s).
	WriteTimeout Duration `default:"20s" yaml:"writeTimeout"`
	// Number of download attempts before giving up (default: 3).
	Attempts uint `default:"3" yaml:"attempts"`
	// Pause between consecutive download attempts (default: 500ms).
	Cooldown Duration `default:"500ms" yaml:"cooldown"`
	// Directory for the on-disk download cache. When empty (default), downloads are
	// fully stateless: nothing is written to disk and every source is downloaded in
	// full on every refresh. When set, blocky uses HTTP conditional requests and
	// serves unchanged/unavailable sources from this directory.
	CachePath string `yaml:"cachePath"`
}

type Duration time.Duration

type ECS struct {
	// Use the ECS client subnet as the client IP when a full-prefix ECS option is present.
	UseAsClient bool `default:"false" yaml:"useAsClient"`
	// Forward the ECS option from the client request to upstream resolvers.
	Forward bool `default:"false" yaml:"forward"`
	// Subnet mask for IPv4 EDNS Client Subnet; adds ECS option when greater than zero (max 32).
	IPv4Mask ECSv4Mask `default:"0" yaml:"ipv4Mask"`
	// Subnet mask for IPv6 EDNS Client Subnet; adds ECS option when greater than zero (max 128).
	IPv6Mask ECSv6Mask `default:"0" yaml:"ipv6Mask"`
}

type ECSv4Mask uint8

type ECSv6Mask uint8

type EDE = toEnable

type FQDNOnly = toEnable

type Filtering struct {
	// DNS query types to drop; matching queries receive an empty answer (e.g. AAAA to block IPv6 lookups).
	QueryTypes QTypeSet `yaml:"queryTypes"`
}

type HTTP3 struct {
	// Enable the HTTP/3 listener on the same addresses as ports.https (requires ports.https to be set).
	Enable bool `default:"false" yaml:"enable"`
}

type HostsFile struct {
	// Host files to load (e.g. /etc/hosts); supports local paths, URLs, and inline content.
	Sources []BytesSource `yaml:"sources"`
	// TTL for DNS records resolved from host files.
	HostsTTL Duration `default:"1h" yaml:"hostsTTL"`
	// If true, loopback addresses (127.0.0.0/8 and ::1) from host files are ignored.
	FilterLoopback bool `yaml:"filterLoopback"`
	// Controls how host files are loaded and periodically refreshed.
	Loading SourceLoading `yaml:"loading"`

	// Deprecated options
	Deprecated struct {
		RefreshPeriod *Duration    `yaml:"refreshPeriod"`
		Filepath      *BytesSource `yaml:"filePath"`
	} `yaml:",inline"`
}

type IPVersion uint8

type Init struct {
	// Startup strategy controlling how initialization failures are handled.
	Strategy InitStrategy `default:"blocking" yaml:"strategy"`
}

type InitStrategy uint16

type ListenConfig []string

type Metrics struct {
	// If true, enables the Prometheus metrics endpoint.
	Enable bool `default:"false" yaml:"enable"`
	// URL path under which the Prometheus metrics are served.
	Path string `default:"/metrics" yaml:"path"`
}

type NetProtocol uint16

type Ports struct {
	// Listen address(es) for DNS over TCP and UDP (default: 53).
	DNS ListenConfig `default:"53" yaml:"dns"`
	// Listen address(es) for HTTP (metrics, REST API, DoH).
	HTTP ListenConfig `yaml:"http"`
	// Listen address(es) for HTTPS (metrics, REST API, DoH).
	HTTPS ListenConfig `yaml:"https"`
	// Listen address(es) for DNS-over-TLS (DoT).
	TLS ListenConfig `yaml:"tls"`
	// URL path for DoH queries.
	DOHPath string `default:"/dns-query" yaml:"dohPath"`
	// Allow binding the DNS and DoT listeners to addresses that are not yet assigned to a network
	// interface, via the Linux IP_FREEBIND socket option (e.g. for Tailscale/WireGuard/VRRP addresses
	// brought up after startup). Has no effect on wildcard binds and is ignored, with a warning, on
	// non-Linux platforms.
	FreeBind bool `default:"false" yaml:"freeBind"`
	// PROXY protocol listener families. List the TCP listeners that sit behind a trusted proxy and
	// must require a PROXY protocol header before the connection is handled, e.g. [https, tls].
	ProxyProtocol ProxyProtocolListeners `yaml:"proxyProtocol"`
}

type ProxyProtocolListeners []ProxyProtocolType

type ProxyProtocolType string

type QType dns.Type

type QTypeSet map[QType]struct{}

type QUICConfig struct {
	// Maximum idle duration before the QUIC connection is closed.
	MaxIdleTimeout Duration `default:"30s" yaml:"maxIdleTimeout"`
	// Interval at which keep-alive packets are sent to maintain the QUIC connection.
	KeepAlivePeriod Duration `default:"15s" yaml:"keepAlivePeriod"`
}

type QueryLog struct {
	// Directory for CSV log files, file path for sqlite, or database URL for mysql/postgresql/timescale.
	Target Secret `yaml:"target"`
	// Log target type: mysql, postgresql, timescale, sqlite, csv, csv-client, console, or none.
	Type QueryLogType `yaml:"type"`
	// Delete log entries older than this many days. 0 disables retention cleanup.
	LogRetentionDays uint64 `yaml:"logRetentionDays"`
	// Maximum number of attempts to create the query log writer on startup.
	CreationAttempts int `default:"3" yaml:"creationAttempts"`
	// Delay between query log writer creation attempts.
	CreationCooldown Duration `default:"2s" yaml:"creationCooldown"`
	// Which fields to include in log entries; defaults to all available fields.
	Fields []QueryLogField `yaml:"fields"`
	// Interval at which buffered log entries are flushed in bulk to the database
	// (used by the mysql, postgresql, timescale and sqlite targets).
	FlushInterval Duration `default:"30s" yaml:"flushInterval"`
	// Rules to suppress certain queries from being logged.
	Ignore QueryLogIgnore `yaml:"ignore"`
}

type QueryLogField string

type QueryLogIgnore struct {
	// If true, queries resolved as Special Use Domain Names (SUDN) are not logged.
	SUDN bool `default:"false" yaml:"sudn"`
	// Domains whose queries are not logged. Each entry is matched against the
	// query name as an exact domain, a *.wildcard, or a /regex/.
	Domains []string `yaml:"domains"`
}

type QueryLogType int16

type RateLimit struct {
	// Enable per-client DNS rate limiting.
	Enable bool `default:"false" yaml:"enable"`
	// Sustained query rate limit in queries per second per client.
	Rate uint `default:"0" yaml:"rate"`
	// Token bucket capacity; queries above this burst are dropped. Defaults to rate × 2.
	Burst uint `default:"0" yaml:"burst"`
	// Prefix length used to aggregate IPv4 client addresses into a single bucket.
	IPv4Prefix uint8 `default:"32" yaml:"ipv4Prefix"`
	// Prefix length used to aggregate IPv6 client addresses into a single bucket.
	IPv6Prefix uint8 `default:"64" yaml:"ipv6Prefix"`
	// CIDRs or IPs that are never rate-limited.
	Allowlist []string `yaml:"allowlist"`
	// contains filtered or unexported fields
}

type RebindingProtection struct {
	// Enable DNS rebinding protection for answers from the general upstream resolvers.
	Enable bool `yaml:"enable"`
	// Domains (including their subdomains) that may resolve to non-public IPs (split-horizon DNS).
	AllowedDomains []string `yaml:"allowedDomains"`
	// contains filtered or unexported fields
}

type Redis struct {
	// Server address and port (e.g. `localhost:6379`), a unix socket path (e.g. `/var/run/redis/redis.sock`),
	// or the sentinel master name when sentinel is used. An address starting with `/` is treated as a unix socket.
	Address string `yaml:"address"`
	// Redis username (if authentication is required).
	Username string `default:"" yaml:"username"`
	// Redis password (if authentication is required).
	Password Secret `default:"" yaml:"password"`
	// Redis database index to use.
	Database int `default:"0" yaml:"database"`
	// If true, blocky will not start when the Redis connection cannot be established.
	Required bool `default:"false" yaml:"required"`
	// Maximum number of connection attempts before giving up.
	ConnectionAttempts int `default:"3" yaml:"connectionAttempts"`
	// Delay between consecutive connection attempts.
	ConnectionCooldown Duration `default:"1s" yaml:"connectionCooldown"`
	// Sentinel username (if sentinel authentication is required).
	SentinelUsername string `default:"" yaml:"sentinelUsername"`
	// Sentinel password (if sentinel authentication is required).
	SentinelPassword Secret `default:"" yaml:"sentinelPassword"`
	// List of Redis Sentinel host:port addresses; enables sentinel mode when non-empty.
	SentinelAddresses []string `yaml:"sentinelAddresses"`
}

type RewriterConfig struct {
	// Domain rewrite rules applied before resolution; keys are rewritten to their values.
	Rewrite map[string]string `yaml:"rewrite"`
	// If true, the original query is sent upstream when the mapped resolver returns an empty answer.
	FallbackUpstream bool `default:"false" yaml:"fallbackUpstream"`
}

type SUDN struct {
	// These are "recommended for private use" but not mandatory.
	// If a user wishes to use one, it will most likely be via conditional
	// upstream or custom DNS, which come before SUDN in the resolver chain.
	// Thus defaulting to `true` and returning NXDOMAIN here should not conflict.
	RFC6762AppendixG bool `default:"true" yaml:"rfc6762-appendixG"`
	// Set to false to completely disable Special Use Domain Name blocking (not recommended for remote upstreams).
	Enable bool `default:"true" yaml:"enable"`
}

type Schedule struct {
	// Start time in HH:MM format; omit together with end for an all-day schedule.
	Start string `yaml:"start"`
	// End time in HH:MM format; if before start, the window is overnight (e.g. 22:00 to 06:00).
	End string `yaml:"end"`
	// Days of the week this schedule is active (mon, tue, wed, thu, fri, sat, sun).
	Weekdays []Weekday `yaml:"weekdays"`
	// contains filtered or unexported fields
}

type Secret string

type SourceLoading struct {
	Init `yaml:",inline"`

	// Maximum number of sources downloaded and processed concurrently (default: 4).
	Concurrency uint `default:"4" yaml:"concurrency"`
	// Maximum parse errors per source before the source is considered invalid; -1 disables the limit.
	MaxErrorsPerSource int `default:"5" yaml:"maxErrorsPerSource"`
	// How often sources are reloaded; a value of 0 or less disables periodic refresh (default: 4h).
	RefreshPeriod Duration `default:"4h" yaml:"refreshPeriod"`
	// HTTP(S) download settings for remote sources.
	Downloads Downloader `yaml:"downloads"`
}

type Statistics struct {
	// If true, enables in-memory statistics collection and the /api/stats endpoint.
	Enable bool `default:"false" yaml:"enable"`
}

type TLSVersion int // values MUST match `tls.VersionTLS*`

type Upstream struct {
	Net        NetProtocol
	Host       string
	Port       uint16
	Path       string
	CommonName string // Common Name to use for certificate verification; optional. "" uses .Host

	// DNS stamp metadata (optional) - only populated when parsing DNS stamps
	CertificateFingerprints []CertificateFingerprint // SHA256 fingerprints for TLS certificate pinning
	IPs                     []net.IP                 // IPs from the DNS stamp (addr + bootstrap IPs) for bootstrapping
}

type UpstreamGroup struct {
	Upstreams

	Name string // group name
}

type UpstreamGroups map[string][]Upstream

type UpstreamStrategy uint8

type Upstreams struct {
	// Initialization strategy controlling when upstream resolvers are tested on startup.
	Init Init `yaml:"init"`
	// Timeout for upstream DNS connections; a value <= 0 is reset to the default.
	Timeout Duration `default:"2s" yaml:"timeout"`
	// Named groups of upstream DNS resolvers; the "default" group is required.
	Groups UpstreamGroups `yaml:"groups"`
	// Strategy for selecting which upstream(s) to use per query (parallel_best, random, strict).
	Strategy UpstreamStrategy `default:"parallel_best" yaml:"strategy"`
	// HTTP User-Agent header sent when connecting to DoH upstream servers.
	UserAgent string `yaml:"userAgent"`
	// QUIC-specific connection settings used when DoQ upstreams are configured.
	QUIC QUICConfig `yaml:"quic"`
}

type Weekday time.Weekday

type ZoneFileDNS struct {
	RRs CustomDNSMapping
	// contains filtered or unexported fields
}