This chapter describes all configuration options in
config.yaml. You can download a reference file with all
configuration properties as JSON.
reference configuration file
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)) # this configuration is mandatory, please define at least one external DNS resolver default: # example for tcp+udp IPv4 server (https://digitalcourage.de/) - 220.127.116.11 # Cloudflare - 18.104.22.168 # 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*: - 22.214.171.124 # optional: timeout to query the upstream resolver. Default: 2s upstreamTimeout: 2s # optional: If true, blocky will fail to start unless at least one upstream server per group is reachable. Default: false startVerifyUpstream: true # 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 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 - | # inline definition with YAML literal block scalar style # hosts format someadsdomain.com 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 - | # 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: 126.96.36.199, 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: automatically list refresh period (in duration format). Default: 4h. # Negative value -> deactivate automatically refresh. # 0 value -> use default refreshPeriod: 4h # optional: timeout for list download (each url). Default: 60s. Use large values for big lists or slow internet connections downloadTimeout: 4m # optional: Download attempt timeout. Default: 60s downloadAttempts: 5 # optional: Time between the download attempts. Default: 1s downloadCooldown: 10s # optional: if failOnError, application startup will fail if at least one list can't be downloaded / opened. Default: blocking startStrategy: failOnError # 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, 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: 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 blacklist 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:188.8.131.52 - https://184.108.40.206/dns-query - upstream: https://dns.digitale-gesellschaft.ch/dns-query ips: - 220.127.116.11 # optional: drop all queries with following query types. Default: empty filtering: queryTypes: - AAAA # 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 # optional: Whether loopback hosts addresses (127.0.0.0/8 and ::1) should be filtered or not, default: false filterLoopback: true # 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: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 privacy: false # optional: add EDE error codes to dns response ede: # enabled if true, Default: false enable: true
|certFile||path||no||Path to cert and key file for SSL encryption (DoH and DoT); if empty, self-signed certificate is generated|
|keyFile||path||no||Path to cert and key file for SSL encryption (DoH and DoT); if empty, self-signed certificate is generated|
|dohUserAgent||string||no||HTTP User Agent for DoH upstreams|
|minTlsServeVersion||string||no||1.2||Minimum TLS version that the DoT and DoH server use to serve those encrypted DNS requests|
|startVerifyUpstream||bool||no||false||If true, blocky will fail to start unless at least one upstream server per group is reachable.|
|connectIPVersion||enum (dual, v4, v6)||no||dual||IP version to use for outgoing connections (dual, v4, v6)|
minTlsServeVersion: 1.1 connectIPVersion: v4
All logging port are optional.
|ports.dns||[IP]:port[,[IP]:port]*||53||Port(s) and optional bind ip address(es) to serve DNS endpoint (TCP and UDP). If you wish to specify a specific IP, you can do so such as
|ports.tls||[IP]:port[,[IP]:port]*||Port(s) and optional bind ip address(es) to serve DoT DNS endpoint (DNS-over-TLS). If you wish to specify a specific IP, you can do so such as
|ports.http||[IP]:port[,[IP]:port]*||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
|ports.https||[IP]:port[,[IP]:port]*||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
ports: dns: 53 http: 4000 https: 443
All logging options are optional.
|log.level||enum (debug, info, warn, error)||info||Log level|
|log.format||enum (text, json)||text||Log format (text or json).|
|log.timestamp||bool||true||Log time stamps (true or false).|
|log.privacy||bool||false||Obfuscate log output (replace all alphanumeric characters with *) for user sensitive data like request domains or responses to increase privacy.|
log: level: debug format: json timestamp: false privacy: true
To resolve a DNS query, blocky needs external public or private DNS resolvers. Blocky supports DNS resolvers with following network protocols (net part of the resolver URL):
- tcp+udp (UDP and TCP, dependent on query type)
- https (aka DoH)
- tcp-tls (aka DoT)
You can (and should!) configure multiple DNS resolvers. Blocky picks 2 random resolvers from the list for each query and returns the answer from the fastest one. This improves your network speed and increases your privacy - your DNS traffic will be distributed over multiple providers.
Each resolver must be defined as a string in following format:
|net||enum (tcp+udp, tcp-tls or https)||no||tcp+udp|
|host||IP or hostname||yes|
|port||int (1 - 65535)||no||53 for udp/tcp, 853 for tcp-tls and 443 for https|
|commonName||string||no||the host value|
The commonName parameter overrides the expected certificate common name value used for verification.
Blocky needs at least the configuration of the default group. This group will be used as a fallback, if no client specific resolver configuration is available.
You can use the client name (see Client name lookup), client's IP address or a client subnet as CIDR notation.
You can use
* as wildcard for the sequence of any character or
[0-9] as number range
upstream: default: - 18.104.22.168 - 22.214.171.124 - tcp-tls:fdns1.dismail.de:853 - https://dns.digitale-gesellschaft.ch/dns-query laptop*: - 126.96.36.199 10.43.8.67/28: - 188.8.131.52 - 184.108.40.206
220.127.116.11 as single upstream DNS resolver for client laptop-home,
18.104.22.168 for all clients in the sub-net
10.43.8.67/28 and 4 resolvers (default) for all others clients.
Blocky needs at least one upstream DNS server
See List of public DNS servers if you need some ideas, which public free DNS server you could use.
Upstream lookup timeout
Blocky will wait 2 seconds (default value) for the response from the external upstream DNS server. You can change this
value by setting the
upstreamTimeout configuration parameter (in duration format).
upstream: default: - 22.214.171.124 - 126.96.36.199 upstreamTimeout: 5s
Bootstrap DNS configuration
These DNS servers are used to resolve upstream DoH and DoT servers that are specified as host names, and list domains. It is useful if no system DNS resolver is configured, and/or to encrypt the bootstrap queries.
|upstream||Upstream (see above)||no|
|ips||List of IPs||yes, if upstream is DoT/DoH||Only valid if upstream is DoH or DoT|
When using an upstream specified by IP, and not by hostname, you can write only the upstream and skip
Works only on Linux/*nix OS due to golang limitations under Windows.
bootstrapDns: - upstream: tcp-tls:dns.example.com ips: - 188.8.131.52 - upstream: https://184.108.40.206/dns-query
Under certain circumstances, it may be useful to filter some types of DNS queries. You can define one or more DNS query types, all queries with these types will be dropped (empty answer will be returned).
filtering: queryTypes: - AAAA
This configuration will drop all 'AAAA' (IPv6) queries.
In domain environments, it may be useful to only response to FQDN requests. If this option is enabled blocky respond immediately with NXDOMAIN if the request is not a valid FQDN. The request is therefore not further processed by other options like custom or conditional. Please be aware that by enabling it your hostname resolution will break unless every hostname is part of a domain.
You can define your own domain name to IP mappings. For example, you can use a user-friendly name for a network printer or define a domain name for your local device on order to use the HTTPS certificate. Multiple IP addresses for one domain must be separated by a comma.
|customTTL||duration (no unit is minutes)||no||1h|
|rewrite||string: string (domain: domain)||no|
|mapping||string: string (hostname: address list)||no|
customDNS: customTTL: 1h filterUnmappedTypes: true rewrite: home: lan replace-me.com: with-this.com mapping: printer.lan: 192.168.178.3 otherdevice.lan: 192.168.178.15,2001:0db8:85a3:08d3:1319:8a2e:0370:7344
This configuration will also resolve any subdomain of the defined domain. For example a query "printer.lan" or " my.printer.lan" will return 192.168.178.3 as IP address.
With the optional parameter
rewrite you can replace domain part of the query with the defined part before the
resolver lookup is performed.
The query "printer.home" will be rewritten to "printer.lan" and return 192.168.178.3.
filterUnmappedTypes = true (default), blocky will filter all queries with unmapped types, for example:
AAAA for "printer.lan" or TXT for "otherdevice.lan".
filterUnmappedTypes = false a query AAAA "printer.lan" will be forwarded to the upstream DNS server.
Conditional DNS resolution
You can define, which DNS resolver(s) should be used for queries for the particular domain (with all subdomains). This is for example useful, if you want to reach devices in your local network by the name. Since only your router know which hostname belongs to which IP address, all DNS queries for the local network should be redirected to the router.
The optional parameter
rewrite behaves the same as with custom DNS.
The optional parameter
fallbackUpstream, 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.
Usage: One usecase when having split DNS for internal and external (internet facing) users, but not all subdomains are listed in the internal domain
conditional: fallbackUpstream: false rewrite: example.com: fritz.box replace-me.com: with-this.com mapping: fritz.box: 192.168.178.1 lan.net: 220.127.116.11,18.104.22.168 # for reverse DNS lookups of local devices 178.168.192.in-addr.arpa: 192.168.178.1 # for all unqualified hostnames .: 22.214.171.124
You can use
. as wildcard for all non full qualified domains (domains without dot)
In this example, a DNS query "client.fritz.box" will be redirected to the router's DNS server at 192.168.178.1 and client.lan.net to 126.96.36.199 and 188.8.131.52. The query "client.example.com" will be rewritten to "client.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.
All unqualified host names (e.g. "test") will be redirected to the DNS server at 184.108.40.206.
One usecase for
fallbackUpstream is when having split DNS for internal and external (internet facing) users, but not all subdomains are listed in the internal domain.
Client name lookup
Blocky can try to resolve a user-friendly client name from the IP address or server URL (DoT and DoH). This is useful for defining of blocking groups, since IP address can change dynamically.
Resolving client name from URL/Host
If DoT or DoH is enabled, you can use a subdomain prefixed with
id- to provide a client name (wildcard ssl certificate
id-bob.example.com -> request's client name is
https://id-bob.example.com/dns-query -> request's client name is
For DoH you can also pass the client name as url parameter:
https://blocky.example.com/dns-query/alice -> request's client name is
Resolving client name from IP address
Blocky uses rDNS to retrieve client's name. To use this feature, you can configure a DNS server for client lookup ( typically your router). You can also define client names manually per IP address.
Single name order
Some routers return multiple names for the client (host name and user defined name). With
clientLookup.singleNameOrder you can specify, which of retrieved names should be used.
Custom client name mapping
You can also map a particular client name to one (or more) IP (ipv4/ipv6) addresses. Parameter
contains a map of client name and multiple IP addresses.
clientLookup: upstream: 192.168.178.1 singleNameOrder: - 2 - 1 clients: laptop: - 192.168.178.29
192.168.178.1 for rDNS lookup. Take second name if present, if not take first name. IP address
192.168.178.29 is mapped to
laptop as client name.
Blocking and whitelisting
Blocky can download and use external lists with domains or IP addresses to block DNS query (e.g. advertisement, malware, trackers, adult sites). You can group several list sources together and define the blocking behavior per client. External blacklists must be either in the well-known Hosts format or just a plain domain list (one domain per line). Blocky also supports regex as more powerful tool to define patterns to block.
Blocky uses DNS sinkhole approach to block a DNS query. Domain name from the request, IP address from the response, and the CNAME record will be checked against configured blacklists.
To avoid over-blocking, you can define or use already existing whitelists.
Definition black and whitelists
Each black or whitelist can be either a path to the local file, a URL to download or inline list definition of a domains in hosts format (YAML literal block scalar style). All Urls must be grouped to a group name.
blocking: blackLists: ads: - https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt - https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts - | # inline definition with YAML literal block scalar style someadsdomain.com anotheradsdomain.com # this is a regex /^banners?[_.-]/ special: - https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews/hosts whiteLists: ads: - whitelist.txt - | # inline definition with YAML literal block scalar style whitelistdomain.com
In this example you can see 2 groups: ads with 2 lists and special with one list. One local whitelist was defined for the ads group.
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
Please define also client group mapping, otherwise you black and whitelist definition will have no effect
You can use regex to define patterns to block. A regex entry must start and end with the slash character (/). Some Examples:
baddomain.com, but also
baddomain.com, but not
/^apple\.(de|com)$/will only block
In this configuration section, you can define, which blocking group(s) should be used for which client in your network. Example: All clients should use the ads group, which blocks advertisement and kids devices should use the adult group, which blocky adult sites.
Clients without a group assignment will use automatically the default group.
You can use the client name (see Client name lookup), client's IP address, client's full-qualified domain name or a client subnet as CIDR notation.
If full-qualified domain name is used (for example "myclient.ddns.org"), blocky will try to resolve the IP address (A and AAAA records) of this domain. If client's IP address matches with the result, the defined group will be used.
blocking: clientGroupsBlock: # default will be used, if no special definition for a client name exists default: - ads - special laptop*: - ads 192.168.178.1/24: - special kid-laptop: - ads - adult
All queries from network clients, whose device name starts with
laptop, will be filtered against the ads group's lists. All devices from the subnet
192.168.178.1/24 against the special group and
kid-laptop against ads and adult. All other clients: ads and special.
You can use
* as wildcard for the sequence of any character or
[0-9] as number range
You can configure, which response should be sent to the client, if a requested query is blocked (only for A and AAAA queries, NXDOMAIN for other types):
|zeroIP||zeroIP||This is the default block type. Server returns 0.0.0.0 (or :: for IPv6) as result for A and AAAA queries|
|nxDomain||nxDomain||return NXDOMAIN as return code|
|custom IPs||220.127.116.11, 2001:0db8:85a3:08d3:1319:8a2e:0370:7344||comma separated list of destination IP addresses. Should contain ipv4 and ipv6 to cover all query types. Useful with running web server on this address to display the "blocked" page.|
blocking: blockType: nxDomain
TTL for answers to blocked domains can be set to customize the time (in duration format) clients ask for those
domains again. Default Block TTL is 6hours. This setting only makes sense when
blockType is set to
zeroIP, and will affect how much time it could take for a client to be able to see the real IP address for a domain
after receiving the custom value.
blocking: blockType: 18.104.22.168, 2001:0db8:85a3:08d3:1319:8a2e:0370:7344 blockTTL: 10s
List refresh period
To keep the list cache up-to-date, blocky will periodically download and reload all external lists. Default period is
4 hours. You can configure this by setting the
blocking.refreshPeriod parameter to a value in duration format.
Negative value will deactivate automatically refresh.
blocking: refreshPeriod: 60m
Refresh every hour.
You can configure the list download attempts according to your internet connection:
|downloadTimeout||duration format||no||60s||Download attempt timeout|
|downloadAttempts||int||no||3||How many download attempts should be performed|
|downloadCooldown||duration format||no||1s||Time between the download attempts|
blocking: downloadTimeout: 4m downloadAttempts: 5 downloadCooldown: 10s
You can configure the blocking behavior during application start of blocky.
If no starategy is selected blocking will be used.
|blocking||all blocking lists will be loaded before DNS resolution starts|
|failOnError||like blocking but blocky will shut down if any download fails|
|fast||DNS resolution starts immediately without blocking which will be enabled after list load is completed|
blocking: startStrategy: failOnError
Blocky downloads and processes links in a single group concurrently. With parameter
processingConcurrency you can adjust
how many links can be processed in the same time. Higher value can reduce the overall list refresh time, but more parallel
download and processing jobs need more RAM. Please consider to reduce this value on systems with limited memory. Default value is 4.
blocking: processingConcurrency: 10
Each DNS response has a TTL (Time-to-live) value. This value defines, how long is the record valid in seconds. The values are maintained by domain owners, server administrators etc. Blocky caches the answers from all resolved queries in own cache in order to avoid repeated requests. This reduces the DNS traffic and increases the network speed, since blocky can serve the result immediately from the cache.
With following parameters you can tune the caching behavior:
Wrong values can significantly increase external DNS traffic or memory consumption.
|caching.minTime||duration format||no||0 (use TTL)||How long a response must be cached (min value). If <=0, use response's TTL, if >0 use this value, if TTL is smaller|
|caching.maxTime||duration format||no||0 (use TTL)||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|
|caching.maxItemsCount||int||no||0 (unlimited)||Max number of cache entries (responses) to be kept in cache (soft limit). Default (0): unlimited. Useful on systems with limited amount of RAM.|
|caching.prefetching||bool||no||false||if true, blocky will preload DNS results for often used queries (default: names queried more than 5 times in a 2 hour time window). Results in cache will be loaded again on their expire (TTL). This improves the response time for often used queries, but significantly increases external traffic. It is recommended to increase "minTime" to reduce the number of prefetch queries to external resolvers.|
|caching.prefetchExpires||duration format||no||2h||Prefetch track time window|
|caching.prefetchThreshold||int||no||5||Name queries threshold for prefetch|
|caching.prefetchMaxItemsCount||int||no||0 (unlimited)||Max number of domains to be kept in cache for prefetching (soft limit). Default (0): unlimited. Useful on systems with limited amount of RAM.|
|caching.cacheTimeNegative||duration format||no||30m||Time how long negative results (NXDOMAIN response or empty result) are cached. A value of -1 will disable caching for negative results.|
caching: minTime: 5m maxTime: 30m prefetching: true
Blocky can synchronize its cache and blocking state between multiple instances through redis. Synchronization is disabled if no address is configured.
|redis.address||string||no||Server address and port or master name if sentinel is used|
|redis.username||string||no||Username if necessary|
|redis.password||string||no||Password if necessary|
|redis.required||bool||no||false||Connection is required for blocky to start|
|redis.connectionAttempts||int||no||3||Max connection attempts|
|redis.connectionCooldown||duration format||no||1s||Time between the connection attempts|
|redis.sentinelUsername||string||no||Sentinel username if necessary|
|redis.sentinelPassword||string||no||Sentinel password if necessary|
|redis.sentinelAddresses||string||no||Sentinel host list (Sentinel is activated if addresses are defined)|
redis: address: redismaster username: usrname password: passwd database: 2 required: true connectionAttempts: 10 connectionCooldown: 3s sentinelUsername: sentUsrname sentinelPassword: sentPasswd sentinelAddresses: - redis-sentinel1:26379 - redis-sentinel2:26379 - redis-sentinel3:26379
Blocky can expose various metrics for prometheus. To use the prometheus feature, the HTTP listener must be enabled ( see Basic Configuration).
|prometheus.enable||no||false||If true, enables prometheus metrics|
|prometheus.path||no||/metrics||URL path to the metrics endpoint|
prometheus: enable: true path: /metrics
You can enable the logging of DNS queries (question, answer, client, duration etc.) to a daily CSV file (can be opened in Excel or OpenOffice Calc) or MySQL/MariaDB database.
Query file/database contains sensitive information. Please ensure to inform users, if you log their queries.
Query log types
You can select one of following query log types:
mysql- log each query in the external MySQL/MariaDB database
postgresql- log each query in the external PostgreSQL database
csv- log into CSV file (one per day)
csv-client- log into CSV file (one per day and per client)
console- log into console output
none- do not log any queries
Query log fields
You can choose which information from processed DNS request and response should be logged in the target system. You can define one or more of following fields:
clientIP- origin IP address from the request
clientName- resolved client name(s) from the origins request
responseReason- reason for the response (e.g. from which upstream resolver), response type and code
responseAnswer- returned DNS answer
question- DNS question from the request
duration- request processing time in milliseconds
If not defined, blocky will log all available information
|queryLog.type||enum (mysql, postgresql, csv, csv-client, console, none (see above))||no||Type of logging target. Console if empty|
|queryLog.target||string||no||directory for writing the logs (for csv) or database url (for mysql or postgresql)|
|queryLog.logRetentionDays||int||no||0||if > 0, deletes log files/database entries which are older than ... days|
|queryLog.creationAttempts||int||no||3||Max attempts to create specific query log writer|
|queryLog.CreationCooldown||duration format||no||2||Time between the creation attempts|
|queryLog.fields||list enum (clientIP, clientName, responseReason, responseAnswer, question, duration)||no||all||which information should be logged|
Please ensure, that the log directory is writable or database exists. If you use docker, please ensure, that the directory is properly mounted (e.g. volume)
example for CSV format with limited logging information
queryLog: type: csv target: /logs logRetentionDays: 7 fields: - clientIP - duration
example for Database
queryLog: type: mysql target: db_user:db_password@tcp(db_host_or_ip:3306)/db_user?charset=utf8mb4&parseTime=True&loc=Local logRetentionDays: 7
You can enable resolving of entries, located in local hosts file.
|hostsFile.filePath||string||no||Path to hosts file (e.g. /etc/hosts on Linux)|
|hostsFile.hostsTTL||duration (no units is minutes)||no||1h||TTL|
|hostsFile.refreshPeriod||duration format||no||1h||Time between hosts file refresh|
|hostsFile.filterLoopback||bool||no||false||Filter loopback addresses (127.0.0.0/8 and ::1)|
hostsFile: filePath: /etc/hosts hostsTTL: 60m refreshPeriod: 30m
Deliver EDE codes as EDNS0 option
DNS responses can be extended with EDE codes according to RFC8914.
|ede.enable||bool||no||false||If true, DNS responses are deliverd with EDE codes|
ede: enable: true
SSL certificate configuration (DoH / TLS listener)
See Wiki - Configuration of HTTPS for detailed information, how to create and configure SSL certificates.