+ + + + + + + +

Configuration

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/)
+    - 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: 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: 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: 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: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: 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
+

Basic configuration

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Mandatory	Default value	Description
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)

Example

minTlsServeVersion: 1.1
+connectIPVersion: v4
+

Ports configuration

All logging port are optional.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Default value	Description
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 `192.168.0.1:53`. Example: `53`, `:53`, `127.0.0.1:53,[::1]:53`
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 `192.168.0.1:853`. Example: `83`, `:853`, `127.0.0.1:853,[::1]:853`
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 `192.168.0.1:4000`. Example: `4000`, `:4000`, `127.0.0.1:4000,[::1]:4000`
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 `192.168.0.1:443`. Example: `443`, `:443`, `127.0.0.1:443,[::1]:443`

Example

ports:
+  dns: 53
+  http: 4000
+  https: 443
+

Logging configuration

All logging options are optional.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Default value	Description
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.

Example

log:
+  level: debug
+  format: json
+  timestamp: false
+  privacy: true
+

Upstream configuration

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)

Hint

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:]host:[port][/path][#commonName].

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Mandatory	Default value
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.

Tip

You can use * as wildcard for the sequence of any character or [0-9] as number range

Example

upstream:
+  default:
+    - 5.9.164.112
+    - 1.1.1.1
+    - tcp-tls:fdns1.dismail.de:853
+    - https://dns.digitale-gesellschaft.ch/dns-query
+  laptop*:
+    - 123.123.123.123
+  10.43.8.67/28:
+    - 1.1.1.1
+    - 9.9.9.9
+

Use 123.123.123.123 as single upstream DNS resolver for client laptop-home, +1.1.1.1 and 9.9.9.9 for all clients in the sub-net 10.43.8.67/28 and 4 resolvers (default) for all others clients.

Note

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).

Example

upstream:
+  default:
+    - 46.182.19.48
+    - 80.241.218.68
+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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Mandatory	Default value	Description
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 ips.

Note

Works only on Linux/*nix OS due to golang limitations under Windows.

Example

    bootstrapDns:
+      - upstream: tcp-tls:dns.example.com
+        ips:
+        - 123.123.123.123
+      - upstream: https://234.234.234.234/dns-query
+

Filtering

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).

Example

filtering:
+  queryTypes:
+    - AAAA
+

This configuration will drop all 'AAAA' (IPv6) queries.

FQDN only

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.

Example

fqdnOnly: true
+

Custom DNS

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Mandatory	Default value
customTTL	duration (no unit is minutes)	no	1h
rewrite	string: string (domain: domain)	no
mapping	string: string (hostname: address list)	no
filterUnmappedTypes	boolean	no	true

Example

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.

With parameter filterUnmappedTypes = true (default), blocky will filter all queries with unmapped types, for example: +AAAA for "printer.lan" or TXT for "otherdevice.lan". +With 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

Example

conditional:
+  fallbackUpstream: false
+  rewrite:
+    example.com: fritz.box
+    replace-me.com: with-this.com
+  mapping:
+    fritz.box: 192.168.178.1
+    lan.net: 192.170.1.2,192.170.1.3
+    # for reverse DNS lookups of local devices
+    178.168.192.in-addr.arpa: 192.168.178.1
+    # for all unqualified hostnames
+    .: 168.168.0.1
+

Tip

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 192.170.1.2 and 192.170.1.3. +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 168.168.0.1.

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 +recommended).

Example: domain example.com

DoT Host: id-bob.example.com -> request's client name is bob +DoH URL: https://id-bob.example.com/dns-query -> request's client name is bob

For DoH you can also pass the client name as url parameter:

DoH URL: https://blocky.example.com/dns-query/alice -> request's client name is alice

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 +parameter 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 clientLookup.clients +contains a map of client name and multiple IP addresses.

Example

clientLookup:
+  upstream: 192.168.178.1
+  singleNameOrder:
+    - 2
+    - 1
+  clients:
+    laptop:
+      - 192.168.178.29
+

Use 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.

Example

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.

Warning

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

Note

Please define also client group mapping, otherwise you black and whitelist definition will have no effect

Regex support

You can use regex to define patterns to block. A regex entry must start and end with the slash character (/). Some +Examples:

/baddomain/ will block www.baddomain.com, baddomain.com, but also mybaddomain-sometext.com
/^baddomain/ will block baddomain.com, but not www.baddomain.com
/^apple\.(de|com)$/ will only block apple.de and apple.com

Client groups

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.

Example

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.

Tip

You can use * as wildcard for the sequence of any character or [0-9] as number range

Block type

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):

+ + + + + + + + + + + + + + + + + + + + + + + + + +

blockType	Example	Description
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	192.100.100.15, 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.

Example

blocking:
+  blockType: nxDomain
+

Block TTL

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 nxDomain or +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.

Example

blocking:
+  blockType: 192.100.100.15, 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.

Example

blocking:
+  refreshPeriod: 60m
+

Refresh every hour.

Download

You can configure the list download attempts according to your internet connection:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Mandatory	Default value	Description
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

Example

blocking:
+  downloadTimeout: 4m
+  downloadAttempts: 5
+  downloadCooldown: 10s
+

Start strategy

You can configure the blocking behavior during application start of blocky.
+If no starategy is selected blocking will be used.

+ + + + + + + + + + + + + + + + + + + + + +

startStrategy	Description
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

Example

blocking:
+  startStrategy: failOnError
+

Concurrency

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.

Example

blocking:
+  processingConcurrency: 10
+

Caching

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:

Warning

Wrong values can significantly increase external DNS traffic or memory consumption.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Mandatory	Default value	Description
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.

Example

caching:
+  minTime: 5m
+  maxTime: 30m
+  prefetching: true
+

Redis

Blocky can synchronize its cache and blocking state between multiple instances through redis. +Synchronization is disabled if no address is configured.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Mandatory	Default value	Description
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.database	int	no	0	Database
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)

Example

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
+

Prometheus

Blocky can expose various metrics for prometheus. To use the prometheus feature, the HTTP listener must be enabled ( +see Basic Configuration).

+ + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Mandatory	Default value	Description
prometheus.enable	no	false	If true, enables prometheus metrics
prometheus.path	no	/metrics	URL path to the metrics endpoint

Example

prometheus:
+  enable: true
+  path: /metrics
+

Query logging

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.

Warning

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

Hint

If not defined, blocky will log all available information

Configuration parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Mandatory	Default value	Description
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

Hint

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

Example

queryLog:
+  type: csv
+  target: /logs
+  logRetentionDays: 7
+  fields:
+  - clientIP
+  - duration
+

example for Database

Example

queryLog:
+  type: mysql
+  target: db_user:db_password@tcp(db_host_or_ip:3306)/db_user?charset=utf8mb4&parseTime=True&loc=Local
+  logRetentionDays: 7
+

Hosts file

You can enable resolving of entries, located in local hosts file.

Configuration parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Type	Mandatory	Default value	Description
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)

Example

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.

Configuration parameters:

+ + + + + + + + + + + + + + + + + + + +

Parameter	Type	Mandatory	Default value	Description
ede.enable	bool	no	false	If true, DNS responses are deliverd with EDE codes

Example

ede:
+  enable: true
+

SSL certificate configuration (DoH / TLS listener)

See Wiki - Configuration of HTTPS +for detailed information, how to create and configure SSL certificates.

DoH url: https://host:port/dns-query

+ + + + + + +

+ + + + + + + +

Installation

You can choose one of the following installation options:

Run as standalone binary
Run as docker container
Kubernetes with helm chart

Prepare your configuration

Blocky supports single or multiple YAML files as configuration. Create new config.yaml with your configuration ( +see Configuration for more details and all configuration options).

Simple configuration file, which enables only basic features:

upstream:
+  default:
+    - 46.182.19.48
+    - 80.241.218.68
+    - tcp-tls:fdns1.dismail.de:853
+    - https://dns.digitale-gesellschaft.ch/dns-query
+blocking:
+  blackLists:
+    ads:
+      - https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
+  clientGroupsBlock:
+    default:
+      - ads
+port: 53
+httpPort: 4000
+

Run as standalone binary

Download the binary file from GitHub for your architecture and +run ./blocky --config config.yml.

Warning

Please be aware, if you want to use port 53 or 953 on Linux you should add CAP_NET_BIND_SERVICE capability +to the binary or run with root privileges (running as root is not recommended).

Run with docker

Alternative registry

Blocky docker images are deployed to DockerHub (spx01/blocky) and GitHub Container Registry (ghcr.io/0xerr0r/blocky) +.

Parameters

You can define the location of the config file in the container with environment variable "BLOCKY_CONFIG_FILE". +Default value is "/app/config.yml".

Docker from command line

Execute following command from the command line:

docker run --name blocky -v /path/to/config.yml:/app/config.yml -p 4000:4000 -p 53:53/udp spx01/blocky
+

Run with docker-compose

Create following docker-compose.yml file

version: "2.1"
+services:
+  blocky:
+    image: spx01/blocky
+    container_name: blocky
+    restart: unless-stopped
+    # Optional the instance hostname for logging purpose
+    hostname: blocky-hostname
+    ports:
+      - "53:53/tcp"
+      - "53:53/udp"
+      - "4000:4000/tcp"
+    environment:
+      - TZ=Europe/Berlin # Optional to synchronize the log timestamp with host
+    volumes:
+      # Optional to synchronize the log timestamp with host
+      - /etc/localtime:/etc/localtime:ro
+      # config file
+      - ./config.yml:/app/config.yml
+

and start docker container with

docker-compose up -d
+

Advanced setup

Following example shows, how to run blocky in a docker container and store query logs on a SAMBA share. Local black and +whitelists directories are mounted as volume. You can create own black or whitelists in these directories and define the +path like '/app/whitelists/whitelist.txt' in the config file.

Example

version: "2.1"
+services:
+  blocky:
+    image: spx01/blocky
+    container_name: blocky
+    restart: unless-stopped
+    ports:
+      - "53:53/tcp"
+      - "53:53/udp"
+      - "4000:4000/tcp" # Prometheus stats (if enabled).
+    environment:
+      - TZ=Europe/Berlin
+    volumes:
+      # config file
+      - ./config.yml:/app/config.yml
+      # write query logs in this volume
+      - queryLogs:/logs
+      # put your custom white and blacklists in these directories
+      - ./blacklists:/app/blacklists/
+      - ./whitelists:/app/whitelists/
+
+volumes:
+  queryLogs:
+    driver: local
+    driver_opts:
+      type: cifs
+      o: username=USER,password=PASSWORD,rw
+      device: //NAS_HOSTNAME/blocky  
+

Multiple configuration files

For complex setups, splitting the configuration between multiple YAML files might be desired. In this case, folder containing YAML files is passed on startup, Blocky will join all the files.

./blocky --config ./config/

Warning

Blocky simply joins the multiple YAML files. If a directive (e.g. upstream) is repeated in multiple files, the configuration will not load and start will fail.

Other installation types

Warning

These projects are maintained by other people.

Web UI

Blocky Frontend provides a Web UI to control blocky. See linked project for installation instructions.

Run with helm chart on Kubernetes

See this repo, +the documentation +and the configuration instructions for details about running blocky via helm in kubernetes.

Run as an App for TrueNAS SCALE

You can find the App in the TrueCharts App Catalog +or read the documentation +and configuration instructions for details about running blocky as a native TrueNAS SCALE App.

+ + + + + + +

name	Description
blocky_blacklist_cache / blocky_whitelist_cache	Number of entries in blacklist/whitelist cache, partitioned by group
blocky_error_total	Counter for internal errors
blocky_query_total	Number of total queries, partitioned by client and DNS request type (A, AAAA, PTR, etc)
blocky_request_duration_ms_bucket	Request duration histogram, partitioned by response type (Blocked, cached, etc)
blocky_response_total	Number of responses, partitioned by response type (Blocked, cached, etc), DNS response code, and reason
blocky_blocking_enabled	1 if blocking is enabled, 0 otherwise
blocky_cache_entry_count	Number of entries in cache
blocky_cache_hit_count / blocky_cache_miss_count	Cache hit/miss counters
blocky_prefetch_count	Amount of prefetched DNS responses
blocky_prefetch_domain_name_cache_count	Amount of domain names being prefetched
blocky_failed_download_count	Number of failed list downloads

Operation	Description
GET /blocking/disable	Disable blocking +
GET /blocking/enable	Enable blocking +
GET /blocking/status	Blocking status +


+ duration +	duration of blocking (Example: 300s, 5m, 1h, 5m30s) +	query	+ string (duration) + + +	+
+ groups +	groups to disable (comma separated). If empty, disable all groups +	query	+ string (string) + + +	+

404 - Not found

Additional information

Print current configuration

Debug / Profiling

List sources

Blacklists

Whitelists

List of public DNS servers

Configuration

Basic configuration

Ports configuration

Logging configuration

Upstream configuration

Upstream lookup timeout

Bootstrap DNS configuration

Filtering

FQDN only

Custom DNS

Conditional DNS resolution

Client name lookup

Resolving client name from URL/Host

Resolving client name from IP address

Single name order

Custom client name mapping

Blocking and whitelisting

Definition black and whitelists

Regex support

Client groups

Block type

Block TTL

List refresh period

Download

Start strategy

Concurrency

Caching

Redis

Prometheus

Query logging

Query log types

Query log fields

Hosts file

Deliver EDE codes as EDNS0 option

SSL certificate configuration (DoH / TLS listener)

Abbreviations

Blocky

Features

Contribution

Installation

Prepare your configuration

Run as standalone binary

Run with docker

Alternative registry

Parameters

Docker from command line

Run with docker-compose

Advanced setup

Multiple configuration files

Other installation types

Web UI

Run with helm chart on Kubernetes

Run as an App for TrueNAS SCALE

AUR package for Arch Linux

Package for Alpine Linux

Installation script for CentOS/Fedora

Package for FreeBSD

Interfaces

REST API

CLI

Network configuration

Transparent configuration with DHCP

Example configuration with FritzBox

Integration in Grafana

Prometheus

Prometheus export

Grafana dashboard

Grafana configuration

Grafana and Prometheus example project

MySQL / MariaDB

Postgres

blocky API