2020-07-05 22:29:05 +02:00
upstream :
# 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))
2021-04-22 22:37:59 +02:00
# this configuration is mandatory, please define at least one external DNS resolver
default :
2022-02-01 21:54:17 +01:00
# 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)
2020-07-05 22:29:05 +02:00
- tcp-tls:fdns1.dismail.de:853
2022-02-01 21:54:17 +01:00
# example for DNS-over-HTTPS (DoH)
2020-07-05 22:29:05 +02:00
- https://dns.digitale-gesellschaft.ch/dns-query
2021-04-22 22:37:59 +02:00
# 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
2020-07-05 22:29:05 +02:00
2021-09-19 22:25:04 +02:00
# optional: timeout to query the upstream resolver. Default: 2s
upstreamTimeout : 2s
2022-09-19 21:44:12 +02:00
# optional: If true, blocky will fail to start unless at least one upstream server per group is reachable. Default: false
2022-08-21 17:21:08 +02:00
startVerifyUpstream : true
2022-09-19 21:44:12 +02:00
# optional: Determines how blocky will create outgoing connections. This impacts both upstreams, and lists.
# accepted: dual, v4, v6
# default: dual
connectIPVersion : dual
2021-03-07 22:50:47 +01:00
# optional: custom IP address(es) for domain name (with all sub-domains). Multiple addresses must be separated by a comma
2020-07-05 22:29:05 +02:00
# example: query "printer.lan" or "my.printer.lan" will return 192.168.178.3
customDNS :
2021-12-16 21:38:01 +01:00
customTTL : 1h
2022-03-22 22:15:31 +01:00
# 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
2022-03-17 22:30:21 +01:00
# optional: replace domain in the query with other domain before resolver lookup in the mapping
rewrite :
example.com : printer.lan
2020-07-05 22:29:05 +02:00
mapping :
2021-03-07 22:50:47 +01:00
printer.lan : 192.168 .178 .3 , 2001 : 0db8:85a3:08d3:1319:8a2e:0370:7344
2020-07-05 22:29:05 +02:00
2021-03-07 22:50:47 +01:00
# 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
2020-07-05 22:29:05 +02:00
# 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 :
2022-07-11 08:06:42 +02:00
# 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
2021-09-19 22:25:04 +02:00
# optional: replace domain in the query with other domain before resolver lookup in the mapping
2021-03-10 22:59:04 +01:00
rewrite :
example.com : fritz.box
2020-07-05 22:29:05 +02:00
mapping :
2022-03-28 21:48:49 +02:00
fritz.box : 192.168 .178 .1
lan.net : 192.168 .178 .1 , 192.168 .178 .2
2020-07-05 22:29:05 +02:00
# 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
blackLists :
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
2021-08-28 22:20:59 +02:00
- |
# inline definition with YAML literal block scalar style
# hosts format
someadsdomain.com
2020-07-05 22:29:05 +02:00
special :
- https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews/hosts
# 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
2021-08-28 22:20:59 +02:00
- |
# inline definition with YAML literal block scalar style
# hosts format
whitelistdomain.com
2021-09-18 22:37:02 +02:00
# this is a regex
/^banners?[_.-]/
2020-07-05 22:29:05 +02:00
# 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
2020-08-24 22:15:31 +02:00
# use client name (with wildcard support: * - sequence of any characters, [0-9] - range)
# or single ip address / client subnet as CIDR notation
laptop* :
2020-07-05 22:29:05 +02:00
- ads
2020-08-24 21:47:28 +02:00
192.168.178.1/24 :
- special
2020-07-05 22:29:05 +02:00
# which response will be sent, if query is blocked:
# zeroIp: 0.0.0.0 will be returned (default)
# nxDomain: return NXDOMAIN as return code
2021-09-19 22:25:04 +02:00
# 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.
2020-07-05 22:29:05 +02:00
blockType : zeroIp
2021-09-12 21:17:32 +02:00
# optional: TTL for answers to blocked domains
# default: 6h
blockTTL : 1m
# optional: automatically list refresh period (in duration format). Default: 4h.
2020-07-05 22:29:05 +02:00
# Negative value -> deactivate automatically refresh.
# 0 value -> use default
2021-09-12 21:17:32 +02:00
refreshPeriod : 4h
2021-09-14 22:48:57 +02:00
# optional: timeout for list download (each url). Default: 60s. Use large values for big lists or slow internet connections
downloadTimeout : 4m
2021-11-14 21:47:24 +01:00
# optional: Download attempt timeout. Default: 60s
downloadAttempts : 5
# optional: Time between the download attempts. Default: 1s
downloadCooldown : 10s
2022-09-03 22:12:07 +02:00
# optional: if failOnError, application startup will fail if at least one list can't be downloaded / opened. Default: blocking
startStrategy : failOnError
2020-07-05 22:29:05 +02:00
# optional: configuration for caching of DNS responses
caching :
2021-09-12 21:17:32 +02:00
# duration how long a response must be cached (min value).
2020-07-05 22:29:05 +02:00
# If <=0, use response's TTL, if >0 use this value, if TTL is smaller
# Default: 0
2021-09-12 21:17:32 +02:00
minTime : 5m
# duration how long a response must be cached (max value).
2020-07-05 22:29:05 +02:00
# If <0, do not cache responses
# If 0, use TTL
# If > 0, use this value, if TTL is greater
# Default: 0
2022-05-19 11:15:48 +02:00
maxTime : 30m
2021-05-17 21:56:39 +02:00
# 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
2021-09-19 22:25:04 +02:00
# if true, will preload DNS results for often used queries (default: names queried more than 5 times in a 2-hour time window)
2021-01-16 22:24:05 +01:00
# this improves the response time for often used queries, but significantly increases external traffic
# default: false
prefetching : true
2021-09-12 21:17:32 +02:00
# prefetch track time window (in duration format)
2021-05-03 22:29:26 +02:00
# default: 120
2021-09-12 21:17:32 +02:00
prefetchExpires : 2h
2021-05-03 22:29:26 +02:00
# name queries threshold for prefetch
# default: 5
prefetchThreshold : 5
2021-05-17 21:56:39 +02:00
# 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
2022-11-08 11:27:59 +01:00
# 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
2020-07-05 22:29:05 +02:00
# optional: configuration of client name resolution
clientLookup :
# optional: this DNS resolver will be used to perform reverse DNS lookup (typically local router)
2022-03-28 21:48:49 +02:00
upstream : 192.168 .178 .1
2020-07-05 22:29:05 +02:00
# 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
2021-09-19 22:25:04 +02:00
# optional: write query information (question, answer, client, duration etc.) to daily csv file
2020-07-05 22:29:05 +02:00
queryLog :
2022-01-07 21:42:06 +01:00
# optional one of: mysql, postgresql, csv, csv-client. If empty, log to console
2021-08-30 18:11:06 +02:00
type : mysql
2022-01-07 21:42:06 +01:00
# 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
2020-07-05 22:29:05 +02:00
# if > 0, deletes log files which are older than ... days
logRetentionDays : 7
2021-12-21 22:03:02 +01:00
# optional: Max attempts to create specific query log writer, default: 3
creationAttempts : 1
# optional: Time between the creation attempts, default: 2s
creationCooldown : 2s
2020-07-05 22:29:05 +02:00
2022-01-19 22:03:41 +01:00
# optional: Blocky can synchronize its cache and blocking state between multiple instances through redis.
redis :
# Server address and port
address : redis:6379
# 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
2021-12-20 22:13:07 +01:00
# 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"
2020-07-05 22:29:05 +02:00
port : 53
2021-12-20 22:13:07 +01:00
# optional: Port(s) and bind ip address(es) for DoT (DNS-over-TLS) listener. Example: 853, 127.0.0.1:853
2022-03-17 09:08:52 +01:00
#tlsPort: 853
2021-12-20 22:13:07 +01:00
# optional: HTTPS listener port(s) and bind ip address(es), default empty = no http listener. If > 0, will be used for prometheus metrics, pprof, REST API, DoH... Example: 443, :443, 127.0.0.1:443
2020-07-05 22:29:05 +02:00
httpPort : 4000
#httpsPort: 443
2022-06-04 08:23:40 +02:00
# optional: Mininal TLS version that the DoH and DoT server will use
minTlsServeVersion : 1.3
2022-05-27 22:20:44 +02:00
# if https port > 0: path to cert and key file for SSL encryption. if not set, self-signed certificate will be generated
2021-10-02 22:54:56 +02:00
#certFile: server.crt
#keyFile: server.key
2021-08-22 22:45:11 +02:00
# optional: use this DNS server to resolve blacklist urls and upstream DNS servers. Useful if no DNS resolver is configured and blocky needs to resolve a host name. Format net:IP:port, net must be udp or tcp
2022-04-02 21:54:20 +02:00
bootstrapDns : tcp+udp:1.1.1.1
2022-04-01 08:58:09 +02:00
filtering :
# optional: drop all queries with following query types. Default: empty
queryTypes :
- AAAA
2022-01-04 15:40:09 +01:00
# optional: if path defined, use this file for query resolution (A, AAAA and rDNS). Default: empty
hostsFile :
# optional: Path to hosts file (e.g. /etc/hosts on Linux)
filePath : /etc/hosts
# optional: TTL, default: 1h
hostsTTL : 60m
# optional: Time between hosts file refresh, default: 1h
refreshPeriod : 30m
2022-08-23 08:54:03 +02:00
# optional: Whether loopback hosts addresses (127.0.0.0/8 and ::1) should be filtered or not, default: false
filterLoopback : true
2020-07-05 22:29:05 +02:00
# optional: Log level (one from debug, info, warn, error). Default: info
logLevel : info
# optional: Log format (text or json). Default: text
2021-04-17 22:19:58 +02:00
logFormat : text
# optional: log timestamps. Default: true
2021-06-28 07:51:46 +02:00
logTimestamp : true
2021-08-22 22:45:11 +02:00
# optional: obfuscate log output (replace all alphanumeric characters with *) for user sensitive data like request domains or responses to increase privacy. Default: false
logPrivacy : false
2022-08-06 22:30:26 +02:00
# optional: add EDE error codes to dns response
ede :
# enabled if true, Default: false
enable : true