# 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]. 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))
# 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
# 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
# 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 black and white lists to block queries (for example ads, trackers, adult pages etc.)
blocking:
# definition of blacklist groups. Can be external link (http/https) or local file
# definition of whitelist groups. Attention: if the same group has black and whitelists, whitelists will be used to disable particular blacklist entries. If a group has only whitelist entries -> this means only domains from this list are allowed, all other domains will be blocked
whiteLists:
ads:
- whitelist.txt
- |
# inline definition with YAML literal block scalar style
# hosts format
whitelistdomain.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.
# 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
# optional: use these DNS servers to resolve blacklist urls and upstream DNS servers. It is useful if no system DNS resolver is configured, and/or to encrypt the bootstrap queries.
# optional: DNS listener port(s) and bind ip address(es), default 53 (UDP and TCP). Example: 53, :53, "127.0.0.1:5353,[::1]:5353"
dns:53
# optional: Port(s) and bind ip address(es) for DoT (DNS-over-TLS) listener. Example: 853, 127.0.0.1:853
tls:853
# optional: Port(s) and optional bind ip address(es) to serve HTTPS used for prometheus metrics, pprof, REST API, DoH... If you wish to specify a specific IP, you can do so such as 192.168.0.1:443. 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... If you wish to specify a specific IP, you can do so such as 192.168.0.1:4000. Example: 4000, :4000, 127.0.0.1:4000,[::1]:4000
http:4000
# optional: logging configuration
log:
# optional: Log level (one from 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