upstreams: init: # Configure startup behavior. # accepted: blocking, failOnError, fast # default: blocking strategy: fast groups: # these external DNS resolvers will be used. Blocky picks 2 random resolvers from the list for each query # format for resolver: [net:]host:[port][/path][#commonname]. net could be empty (default, shortcut for tcp+udp), tcp+udp, tcp, udp, tcp-tls or https (DoH). If port is empty, default port will be used (53 for udp and tcp, 853 for tcp-tls, 443 for https (Doh)) # alternative format: DNS Stamp (sdns://...) - compact format that encodes all parameters including optional certificate hashes for automatic certificate pinning # this configuration is mandatory, please define at least one external DNS resolver default: # example for tcp+udp IPv4 server (https://digitalcourage.de/) - 5.9.164.112 # Cloudflare - 1.1.1.1 # example for DNS-over-TLS server (DoT) - tcp-tls:fdns1.dismail.de:853 # example for DNS-over-HTTPS (DoH) - https://dns.digitale-gesellschaft.ch/dns-query # example for DNS Stamp format (Plain DNS - Google 8.8.8.8) - sdns://AAcAAAAAAAAABzguOC44Ljg # example for DNS Stamp format (DoH - Digitale Gesellschaft) - sdns://AgcAAAAAAAAADTE4NS45NS4yMTguNDKg9_WvKIAeh31986K-KP4UnzJ0p-0p8Tb9UDzjmMuoCw2g9XV9eG8XP2q1MZfsnCKQisBtKuTqoqW29Y678AOXod-gs14FlQz72CWfk3W6EBhwuMPEwOxaUpdX5jFn6d4mqeig7PBiC_ww1ETe9Xetxlw3UFpzui0v2eb_QcPtOtDWWg-gouMnQ2N22OdkBavp_siMtB3i1NA1DU6CkqUxGMS431ugkHjSGlbA4IkdkGIhtpkjMb3RcXLrDzPdoH1cZcbhTDmg1q1wTTQXThIIyVKqq5g16xwGaw3No7Ta1A9FE-jhglqgsl8vNpZ_c5TwmTeIWzM_qjVtcZ_qzzjM6fA1UADz4XSg5kS6aWPjNf52XLmXaxKxDrVClLQkd3ZMyzo6zKOssvygKq4_t78F5MgcQZTcpEUR1PmvMEeG7BrnIYQJz2Kgg1Wg1h2W6_s_oZCW4sAC42A79_2q77InBNqGaAYrvobtS5MgnUgyu0yNdyB7Jd4XWSaC78PKRfV53GZKDtXySPXJM5gcZG5zLmRpZ2l0YWxlLWdlc2VsbHNjaGFmdC5jaAovZG5zLXF1ZXJ5 # optional: use client name (with wildcard support: * - sequence of any characters, [0-9] - range) # or single ip address / client subnet as CIDR notation laptop*: - 123.123.123.123 # optional: Determines what strategy blocky uses to choose the upstream servers. # accepted: parallel_best, strict, random # default: parallel_best strategy: parallel_best # optional: timeout to query the upstream resolver. Default: 2s timeout: 2s # optional: HTTP User Agent when connecting to upstreams. Default: none userAgent: "custom UA" # optional: Determines how blocky will create outgoing connections. This impacts both upstreams, and lists. # accepted: dual, v4, v6 # default: dual connectIPVersion: dual # optional: custom IP address(es) for domain name (with all sub-domains). Multiple addresses must be separated by a comma # example: query "printer.lan" or "my.printer.lan" will return 192.168.178.3 customDNS: customTTL: 1h # optional: if true (default), return empty result for unmapped query types (for example TXT, MX or AAAA if only IPv4 address is defined). # if false, queries with unmapped types will be forwarded to the upstream resolver filterUnmappedTypes: true # optional: replace domain in the query with other domain before resolver lookup in the mapping rewrite: example.com: printer.lan mapping: printer.lan: 192.168.178.3,2001:0db8:85a3:08d3:1319:8a2e:0370:7344 # optional: definition, which DNS resolver(s) should be used for queries to the domain (with all sub-domains). Multiple resolvers must be separated by a comma # Example: Query client.fritz.box will ask DNS server 192.168.178.1. This is necessary for local network, to resolve clients by host name conditional: # optional: if false (default), return empty result if after rewrite, the mapped resolver returned an empty answer. If true, the original query will be sent to the upstream resolver # Example: The query "blog.example.com" will be rewritten to "blog.fritz.box" and also redirected to the resolver at 192.168.178.1. If not found and if `fallbackUpstream` was set to `true`, the original query "blog.example.com" will be sent upstream. # Usage: One usecase when having split DNS for internal and external (internet facing) users, but not all subdomains are listed in the internal domain. fallbackUpstream: false # optional: replace domain in the query with other domain before resolver lookup in the mapping rewrite: example.com: fritz.box mapping: fritz.box: 192.168.178.1 lan.net: 192.168.178.1,192.168.178.2 # optional: use allow/denylists to block queries (for example ads, trackers, adult pages etc.) blocking: # definition of denylist groups. Can be external link (http/https) or local file denylists: ads: - https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt - https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts - http://sysctl.org/cameleon/hosts - https://s3.amazonaws.com/lists.disconnect.me/simple_tracking.txt - | # inline definition with YAML literal block scalar style someadsdomain.com *.example.com special: - https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews/hosts # definition of allowlist groups. # Note: if the same group has both allow/denylists, allowlists take precedence. Meaning if a domain is both blocked and allowed, it will be allowed. # If a group has only allowlist entries, only domains from this list are allowed, and all others be blocked. allowlists: ads: - allowlist.txt - | # inline definition with YAML literal block scalar style # hosts format allowlistdomain.com # this is a regex /^banners?[_.-]/ # definition: which groups should be applied for which client clientGroupsBlock: # default will be used, if no special definition for a client name exists default: - ads - special # use client name (with wildcard support: * - sequence of any characters, [0-9] - range) # or single ip address / client subnet as CIDR notation laptop*: - ads 192.168.178.1/24: - special # which response will be sent, if query is blocked: # zeroIp: 0.0.0.0 will be returned (default) # nxDomain: return NXDOMAIN as return code # comma separated list of destination IP addresses (for example: 192.100.100.15, 2001:0db8:85a3:08d3:1319:8a2e:0370:7344). Should contain ipv4 and ipv6 to cover all query types. Useful with running web server on this address to display the "blocked" page. blockType: zeroIp # optional: TTL for answers to blocked domains # default: 6h blockTTL: 1m # optional: Configure how lists, AKA sources, are loaded loading: # optional: list refresh period in duration format. # Set to a value <= 0 to disable. # default: 4h refreshPeriod: 24h # optional: Applies only to lists that are downloaded (HTTP URLs). downloads: # optional: timeout for list download (each url). Use large values for big lists or slow internet connections # default: 5s timeout: 60s # optional: timeout for list write to disk (each url). Use larger values for big lists or in constrained environments # default: 20s writeTimeout: 60s # optional: timeout for reading the download (each url). Use large values for big lists or in constrained environments # To disable this timeout, set to 0. # default: 20s readTimeout: 60s # optional: timeout for reading request headers for the download (each url). Use large values for slow internet connections # to disable, set to -1. # default: 20s readHeaderTimeout: 60s # optional: Maximum download attempts # default: 3 attempts: 5 # optional: Time between the download attempts # default: 500ms cooldown: 10s # optional: Maximum number of lists to process in parallel. # default: 4 concurrency: 16 # Configure startup behavior. # accepted: blocking, failOnError, fast # default: blocking strategy: failOnError # Number of errors allowed in a list before it is considered invalid. # A value of -1 disables the limit. # default: 5 maxErrorsPerSource: 5 # optional: configuration for caching of DNS responses caching: # duration how long a response must be cached (min value). # If <=0, use response's TTL, if >0 use this value, if TTL is smaller # Default: 0 minTime: 5m # duration how long a response must be cached (max value). # If <0, do not cache responses # If 0, use TTL # If > 0, use this value, if TTL is greater # Default: 0 maxTime: 30m # Max number of cache entries (responses) to be kept in cache (soft limit). Useful on systems with limited amount of RAM. # Default (0): unlimited maxItemsCount: 0 # if true, will preload DNS results for often used queries (default: names queried more than 5 times in a 2-hour time window) # this improves the response time for often used queries, but significantly increases external traffic # default: false prefetching: true # prefetch track time window (in duration format) # default: 120 prefetchExpires: 2h # name queries threshold for prefetch # default: 5 prefetchThreshold: 5 # Max number of domains to be kept in cache for prefetching (soft limit). Useful on systems with limited amount of RAM. # Default (0): unlimited prefetchMaxItemsCount: 0 # Time how long negative results (NXDOMAIN response or empty result) are cached. A value of -1 will disable caching for negative results. # Default: 30m cacheTimeNegative: 30m # optional: configuration of client name resolution clientLookup: # optional: this DNS resolver will be used to perform reverse DNS lookup (typically local router) upstream: 192.168.178.1 # optional: some routers return multiple names for client (host name and user defined name). Define which single name should be used. # Example: take second name if present, if not take first name singleNameOrder: - 2 - 1 # optional: custom mapping of client name to IP addresses. Useful if reverse DNS does not work properly or just to have custom client names. clients: laptop: - 192.168.178.29 # optional: configuration for prometheus metrics endpoint prometheus: # enabled if true enable: true # url path, optional (default '/metrics') path: /metrics # optional: write query information (question, answer, client, duration etc.) to daily csv file queryLog: # optional one of: mysql, postgresql, timescale, csv, csv-client. If empty, log to console type: mysql # directory (should be mounted as volume in docker) for csv, db connection string for mysql/postgresql target: db_user:db_password@tcp(db_host_or_ip:3306)/db_name?charset=utf8mb4&parseTime=True&loc=Local #postgresql target: postgres://user:password@db_host_or_ip:5432/db_name # if > 0, deletes log files which are older than ... days logRetentionDays: 7 # optional: Max attempts to create specific query log writer, default: 3 creationAttempts: 1 # optional: Time between the creation attempts, default: 2s creationCooldown: 2s # optional: Which fields should be logged. You can choose one or more from: clientIP, clientName, responseReason, responseAnswer, question, duration. If not defined, it logs all fields fields: - clientIP - duration # optional: Interval to write data in bulk to the external database, default: 30s flushInterval: 30s # optional: Blocky can synchronize its cache and blocking state between multiple instances through redis. redis: # Server address and port or master name if sentinel is used address: redismaster # Username if necessary username: usrname # Password if necessary password: passwd # Database, default: 0 database: 2 # Connection is required for blocky to start. Default: false required: true # Max connection attempts, default: 3 connectionAttempts: 10 # Time between the connection attempts, default: 1s connectionCooldown: 3s # Sentinal username if necessary sentinelUsername: usrname # Sentinal password if necessary sentinelPassword: passwd # List with address and port of sentinel hosts(sentinel is activated if at least one sentinel address is configured) sentinelAddresses: - redis-sentinel1:26379 - redis-sentinel2:26379 - redis-sentinel3:26379 # optional: Mininal TLS version that the DoH and DoT server will use minTlsServeVersion: 1.3 # if https port > 0: path to cert and key file for SSL encryption. if not set, self-signed certificate will be generated #certFile: server.crt #keyFile: server.key # optional: use these DNS servers to resolve denylist urls and upstream DNS servers. It is useful if no system DNS resolver is configured, and/or to encrypt the bootstrap queries. bootstrapDns: - tcp+udp:1.1.1.1 - https://1.1.1.1/dns-query - upstream: https://dns.digitale-gesellschaft.ch/dns-query ips: - 185.95.218.42 # optional: drop all queries with following query types. Default: empty filtering: queryTypes: - AAAA # optional: return NXDOMAIN for queries that are not FQDNs. fqdnOnly: # default: false enable: true # optional: if path defined, use this file for query resolution (A, AAAA and rDNS). Default: empty hostsFile: # optional: Hosts files to parse sources: - /etc/hosts - https://example.com/hosts - | # inline hosts 127.0.0.1 example.com # optional: TTL, default: 1h hostsTTL: 30m # optional: Whether loopback hosts addresses (127.0.0.0/8 and ::1) should be filtered or not # default: false filterLoopback: true # optional: Configure how sources are loaded loading: # optional: file refresh period in duration format. # Set to a value <= 0 to disable. # default: 4h refreshPeriod: 24h # optional: Applies only to files that are downloaded (HTTP URLs). downloads: # optional: timeout for file download (each url). Use large values for big files or slow internet connections # default: 5s timeout: 60s # optional: Maximum download attempts # default: 3 attempts: 5 # optional: Time between the download attempts # default: 500ms cooldown: 10s # optional: Maximum number of files to process in parallel. # default: 4 concurrency: 16 # Configure startup behavior. # accepted: blocking, failOnError, fast # default: blocking strategy: failOnError # Number of errors allowed in a file before it is considered invalid. # A value of -1 disables the limit. # default: 5 maxErrorsPerSource: 5 # optional: ports configuration ports: # optional: DNS listener port(s) and bind ip address(es) # default: 53 (UDP and TCP) # example: [53, :53, 127.0.0.1:53, [::1]:53] dns: - 53 - localhost:5353 # optional: Port(s) and bind ip address(es) for DoT (DNS-over-TLS) listener. # Supports the same formats as `dns` above. # default: none # example: [853, :853, 127.0.0.1:853, [::1]:853] tls: 853 # optional: Port(s) and optional bind ip address(es) to serve HTTPS used for prometheus metrics, pprof, REST API, DoH... # example: [443, :443, 127.0.0.1:443, [::1]:443] https: 443 # optional: Port(s) and optional bind ip address(es) to serve HTTP used for prometheus metrics, pprof, REST API, DoH... # example: [4000, :4000, 127.0.0.1:4000, [::1]:4000] http: 4000 # optional: URL path for DoH queries. # default: /dns-query dohPath: /dns-query # optional: logging configuration log: # optional: Log level (one from trace, debug, info, warn, error). Default: info level: info # optional: Log format (text or json). Default: text format: text # optional: log timestamps. Default: true timestamp: true # optional: obfuscate log output (replace all alphanumeric characters with *) for user sensitive data like request domains or responses to increase privacy. Default: false privacy: false # optional: add EDE error codes to dns response ede: # enabled if true, Default: false enable: true # optional: configure optional Special Use Domain Names (SUDN) specialUseDomains: # optional: block recomended private TLDs # default: true rfc6762-appendixG: true enable: true # optional: configure extended client subnet (ECS) support ecs: # optional: if the request ecs option with a max sice mask the address will be used as client ip useAsClient: true # optional: if the request contains a ecs option it will be forwarded to the upstream resolver forward: true # optional: DNSSEC validation configuration # DNSSEC (Domain Name System Security Extensions) provides cryptographic authentication # of DNS data to protect against cache poisoning and man-in-the-middle attacks dnssec: # Enable DNSSEC validation. When enabled, Blocky will: # - Set the DNSSEC OK (DO) bit on upstream queries # - Validate cryptographic signatures (RRSIG) in DNS responses # - Verify the chain of trust from root to queried domain # - Validate authenticated denial of existence (NSEC/NSEC3 for NXDOMAIN/NODATA) # - Validate wildcard expansions per RFC 4035 §5.3.4 # - Return SERVFAIL for responses with invalid DNSSEC signatures (Bogus) # - Set the Authenticated Data (AD) flag only after successful validation # # default: false validate: true # Maximum domain label depth for chain of trust validation # Prevents DoS with deeply nested domains (e.g., a.b.c.d.e.f.g.h.i.j.example.com) # default: 10 maxChainDepth: 10 # How long to cache validation results (in hours) # Improves performance by avoiding repeated validation of the same domains # default: 1 cacheExpirationHours: 1 # Maximum upstream DNS queries per validation request # Protects against DoS attacks with queries requiring many upstream lookups # (e.g., deeply nested delegation chains requiring DNSKEY + DS queries per level) # Validation will fail if budget is exhausted # default: 30 maxUpstreamQueries: 30 # Maximum NSEC3 hash iterations allowed during validation # NSEC3 is used for authenticated denial of existence in DNSSEC zones # Higher iteration counts increase CPU cost, making DoS attacks possible # RFC 5155 §10.3 recommends rejecting responses with excessive iterations # default: 150 maxNSEC3Iterations: 150 # Clock skew tolerance in seconds for signature timestamp validation # Allows validation to succeed even if the system clock is off by this amount # RFC 6781 §4.1.2 recommends accounting for clock skew in deployment environments # This is especially important for: # - Virtual machines (clock drift after suspend/resume) # - Containers (clock sync with host) # - IoT/embedded devices (no NTP, battery-backed RTC) # - Systems during NTP synchronization # Default matches industry standard validators (Unbound, BIND) # - 300 (5 minutes): Conservative, handles typical NTP drift # - 3600 (1 hour): Lenient, handles timezone/DST issues (default) # - 7200 (2 hours): Very lenient, for systems with significant clock problems # default: 3600 (1 hour) clockSkewToleranceSec: 3600 # optional: Custom trust anchors (DNSKEY records) for DNSSEC validation # By default, Blocky uses the latest IANA root trust anchors (KSK-2017 and KSK-2024) # Only override this for testing, private zones, or lab environments # Format: DNS record format (DNSKEY or DS records) # WARNING: Specifying custom trust anchors replaces the default root trust anchors # default: [] (use built-in root trust anchors) trustAnchors: # Example: Custom DNSKEY record for a private zone - "example.com. 86400 IN DNSKEY 257 3 8 AwEAAaz/tAm8yTn4Mfeh5eyI96WSVexTBAvkMgJzkKTO..." # Example: DS record format (for parent zone validation) - "subdomain.example.com. 3600 IN DS 12345 8 2 1234567890ABCDEF..." # optional: DNS64 configuration # DNS64 (RFC 6147) allows IPv6-only clients to access IPv4-only services by # synthesizing AAAA (IPv6) records from A (IPv4) records. This is critical for # IPv6-only networks (cellular, IoT, modern datacenters) that need to reach # legacy IPv4-only destinations. dns64: # Enable DNS64 synthesis # WARNING: Do NOT enable if filtering.queryTypes contains AAAA, as all AAAA # queries will be filtered before reaching DNS64 (making DNS64 ineffective) # default: false enable: false # optional: DNS64 prefixes for IPv4-to-IPv6 address synthesis # Multiple prefixes allow for load balancing or redundancy across multiple # NAT64 gateways. DNS64 will synthesize one AAAA record per prefix per A record. # # Format: IPv6 prefix in CIDR notation # Valid prefix lengths (per RFC 6052): /32, /40, /48, /56, /64, /96 # - /96 is most common (well-known prefix 64:ff9b::/96) # - Shorter prefixes (/32, /40, etc.) allow more flexibility in address assignment # # default: [64:ff9b::/96] (RFC 6052 well-known prefix) # # IMPORTANT: Prefixes must not overlap. Overlapping prefixes will be rejected. prefixes: - 64:ff9b::/96 # optional: DNS64 exclusion set # DNS64 will NOT synthesize AAAA records if the response already contains # AAAA records that are NOT in the exclusion set. # # If not specified (recommended), uses default exclusion set: # - IPv4-mapped IPv6 addresses (::ffff:0:0/96) - RFC 6147 requirement # - Loopback address (::1/128) - RFC 6147 recommendation # - Link-local addresses (fe80::/10) - RFC 6147 recommendation # - Configured DNS64 prefixes - prevents synthesis loops # # Custom exclusion set (advanced use only): # WARNING: If you configure a custom exclusion set, you are responsible for # including all necessary ranges. The configured prefixes are NOT automatically # added when using a custom exclusion set. # # default: [::ffff:0:0/96, ::1/128, fe80::/10] + configured prefixes # # Example custom exclusion set: # exclusionSet: # - ::ffff:0:0/96 # IPv4-mapped (REQUIRED by RFC) # - ::1/128 # Loopback (recommended) # - fe80::/10 # Link-local (recommended) # - 64:ff9b::/96 # Your configured prefix (recommended to prevent loops) # - 2001:db8::/32 # Custom exclusion range #