<spanclass="w"></span><spanclass="c1"># these external DNS resolvers will be used. Blocky picks 2 random resolvers from the list for each query</span>
<spanclass="w"></span><spanclass="c1"># 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))</span>
<spanclass="w"></span><spanclass="c1"># this configuration is mandatory, please define at least one external DNS resolver</span>
<spanclass="w"></span><spanclass="c1"># optional: if true (default), return empty result for unmapped query types (for example TXT, MX or AAAA if only IPv4 address is defined).</span>
<spanclass="w"></span><spanclass="c1"># if false, queries with unmapped types will be forwarded to the upstream resolver</span>
<spanclass="c1"># 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</span>
<spanclass="c1"># 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</span>
<spanclass="w"></span><spanclass="c1"># 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</span>
<spanclass="w"></span><spanclass="c1"># 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.</span>
<spanclass="w"></span><spanclass="c1"># Usage: One usecase when having split DNS for internal and external (internet facing) users, but not all subdomains are listed in the internal domain.</span>
<spanclass="w"></span><spanclass="c1"># 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</span>
<spanclass="w"></span><spanclass="c1"># which response will be sent, if query is blocked:</span>
<spanclass="w"></span><spanclass="c1"># zeroIp: 0.0.0.0 will be returned (default)</span>
<spanclass="w"></span><spanclass="c1"># nxDomain: return NXDOMAIN as return code</span>
<spanclass="w"></span><spanclass="c1"># 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.</span>
<spanclass="w"></span><spanclass="c1"># optional: timeout for list download (each url). Use large values for big lists or slow internet connections</span>
<spanclass="w"></span><spanclass="c1"># Max number of cache entries (responses) to be kept in cache (soft limit). Useful on systems with limited amount of RAM.</span>
<spanclass="w"></span><spanclass="c1"># if true, will preload DNS results for often used queries (default: names queried more than 5 times in a 2-hour time window)</span>
<spanclass="w"></span><spanclass="c1"># this improves the response time for often used queries, but significantly increases external traffic</span>
<spanclass="w"></span><spanclass="c1"># Max number of domains to be kept in cache for prefetching (soft limit). Useful on systems with limited amount of RAM.</span>
<spanclass="w"></span><spanclass="c1"># Time how long negative results (NXDOMAIN response or empty result) are cached. A value of -1 will disable caching for negative results.</span>
<spanclass="w"></span><spanclass="c1"># optional: some routers return multiple names for client (host name and user defined name). Define which single name should be used.</span>
<spanclass="w"></span><spanclass="c1"># Example: take second name if present, if not take first name</span>
<spanclass="w"></span><spanclass="c1"># optional: custom mapping of client name to IP addresses. Useful if reverse DNS does not work properly or just to have custom client names.</span>
<spanclass="w"></span><spanclass="c1"># 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</span>
<spanclass="w"></span><spanclass="c1"># List with address and port of sentinel hosts(sentinel is activated if at least one sentinel address is configured)</span>
<spanclass="c1"># 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.</span>
<spanclass="w"></span><spanclass="c1"># optional: timeout for file download (each url). Use large values for big files or slow internet connections</span>
<spanclass="w"></span><spanclass="c1"># 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"</span>
<spanclass="w"></span><spanclass="c1"># 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</span>
<spanclass="w"></span><spanclass="c1"># 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</span>
<spanclass="w"></span><spanclass="c1"># optional: obfuscate log output (replace all alphanumeric characters with *) for user sensitive data like request domains or responses to increase privacy. Default: false</span>
<td>Path to cert and key file for <abbrtitle="Secure Sockets Layer">SSL</abbr> encryption (<abbrtitle="DNS-over-HTTPS">DoH</abbr> and <abbrtitle="DNS-over-TLS">DoT</abbr>); if empty, self-signed certificate is generated</td>
</tr>
<tr>
<td>keyFile</td>
<td>path</td>
<td>no</td>
<td></td>
<td>Path to cert and key file for <abbrtitle="Secure Sockets Layer">SSL</abbr> encryption (<abbrtitle="DNS-over-HTTPS">DoH</abbr> and <abbrtitle="DNS-over-TLS">DoT</abbr>); if empty, self-signed certificate is generated</td>
</tr>
<tr>
<td>minTlsServeVersion</td>
<td>string</td>
<td>no</td>
<td>1.2</td>
<td>Minimum TLS version that the <abbrtitle="DNS-over-TLS">DoT</abbr> and <abbrtitle="DNS-over-HTTPS">DoH</abbr> server use to serve those encrypted <abbrtitle="Domain Name System">DNS</abbr> requests</td>
</tr>
<tr>
<td>connectIPVersion</td>
<td>enum (dual, v4, v6)</td>
<td>no</td>
<td>dual</td>
<td>IP version to use for outgoing connections (dual, v4, v6)</td>
<td>Port(s) and optional bind ip address(es) to serve <abbrtitle="Domain Name System">DNS</abbr> endpoint (<abbrtitle="Transmission Control Protocol">TCP</abbr> and <abbrtitle="User Datagram Protocol">UDP</abbr>). If you wish to specify a specific IP, you can do so such as <code>192.168.0.1:53</code>. Example: <code>53</code>, <code>:53</code>, <code>127.0.0.1:53,[::1]:53</code></td>
</tr>
<tr>
<td>ports.tls</td>
<td>[IP]:port[,[IP]:port]*</td>
<td></td>
<td>Port(s) and optional bind ip address(es) to serve <abbrtitle="DNS-over-TLS">DoT</abbr><abbrtitle="Domain Name System">DNS</abbr> endpoint (<abbrtitle="Domain Name System">DNS</abbr>-over-TLS). If you wish to specify a specific IP, you can do so such as <code>192.168.0.1:853</code>. Example: <code>83</code>, <code>:853</code>, <code>127.0.0.1:853,[::1]:853</code></td>
</tr>
<tr>
<td>ports.http</td>
<td>[IP]:port[,[IP]:port]*</td>
<td></td>
<td>Port(s) and optional bind ip address(es) to serve <abbrtitle="Hypertext Transfer Protocol">HTTP</abbr> used for prometheus metrics, pprof, <abbrtitle="Representational State Transfer">REST</abbr><abbrtitle="Application Programming Interface">API</abbr>, <abbrtitle="DNS-over-HTTPS">DoH</abbr>... If you wish to specify a specific IP, you can do so such as <code>192.168.0.1:4000</code>. Example: <code>4000</code>, <code>:4000</code>, <code>127.0.0.1:4000,[::1]:4000</code></td>
</tr>
<tr>
<td>ports.https</td>
<td>[IP]:port[,[IP]:port]*</td>
<td></td>
<td>Port(s) and optional bind ip address(es) to serve <abbrtitle="Hypertext Transfer Protocol Secure">HTTPS</abbr> used for prometheus metrics, pprof, <abbrtitle="Representational State Transfer">REST</abbr><abbrtitle="Application Programming Interface">API</abbr>, <abbrtitle="DNS-over-HTTPS">DoH</abbr>... If you wish to specify a specific IP, you can do so such as <code>192.168.0.1:443</code>. Example: <code>443</code>, <code>:443</code>, <code>127.0.0.1:443,[::1]:443</code></td>
<td>Obfuscate log output (replace all alphanumeric characters with *) for user sensitive data like request domains or responses to increase privacy.</td>
<p>A couple of features use an "init/loading strategy" which configures behavior at Blocky startup.<br/>
This applies to all of them. The default strategy is blocking.</p>
<table>
<thead>
<tr>
<th>strategy</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>blocking</td>
<td>Initialization happens before <abbrtitle="Domain Name System">DNS</abbr> resolution starts. Any errors are logged, but Blocky continues running if possible.</td>
</tr>
<tr>
<td>failOnError</td>
<td>Like blocking but Blocky will exit with an error if initialization fails.</td>
</tr>
<tr>
<td>fast</td>
<td>Blocky starts serving <abbrtitle="Domain Name System">DNS</abbr> immediately and initialization happens in the background. The feature requiring initialization will enable later on (if it succeeds).</td>
<td>Upstream <abbrtitle="Domain Name System">DNS</abbr> servers to use, in groups.</td>
</tr>
<tr>
<td>usptreams.init.strategy</td>
<td>enum (blocking, failOnError, fast)</td>
<td>no</td>
<td>blocking</td>
<td>See <ahref="#init-strategy">Init Strategy</a> and below.</td>
</tr>
<tr>
<td>usptreams.strategy</td>
<td>enum (parallel_best, random, strict)</td>
<td>no</td>
<td>parallel_best</td>
<td>Upstream server usage strategy.</td>
</tr>
<tr>
<td>usptreams.timeout</td>
<td>duration</td>
<td>no</td>
<td>2s</td>
<td>Upstream connection timeout.</td>
</tr>
<tr>
<td>usptreams.userAgent</td>
<td>string</td>
<td>no</td>
<td></td>
<td><abbrtitle="Hypertext Transfer Protocol">HTTP</abbr> User Agent when connecting to upstreams.</td>
</tr>
</tbody>
</table>
<p>For <code>init.strategy</code>, the "init" is testing the given resolvers for each group. The potentially fatal error, depending on the strategy, is if a group has no functional resolvers.</p>
<p>To resolve a <abbrtitle="Domain Name System">DNS</abbr> query, blocky needs external public or private <abbrtitle="Domain Name System">DNS</abbr> resolvers. Blocky supports <abbrtitle="Domain Name System">DNS</abbr> resolvers with
following network protocols (net part of the resolver URL):</p>
<ul>
<li>tcp+udp (<abbrtitle="User Datagram Protocol">UDP</abbr> and <abbrtitle="Transmission Control Protocol">TCP</abbr>, dependent on query type)</li>
<p>The <code>commonName</code> parameter overrides the expected certificate common name value used for verification.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>Blocky needs at least the configuration of the <strong>default</strong> group with at least one upstream <abbrtitle="Domain Name System">DNS</abbr> server. This group will be used as a fallback, if no client
<p>See <ahref="../additional_information/#list-of-public-dns-servers">List of public <abbrtitle="Domain Name System">DNS</abbr> servers</a> if you need some ideas, which public free <abbrtitle="Domain Name System">DNS</abbr> server you could use.</p>
</div>
<p>You can specify multiple upstream groups (additional to the <code>default</code> group) to use different upstream servers for different clients, based on client name (see <ahref="#client-name-lookup">Client name lookup</a>), client IP address or client subnet (as <abbrtitle="Classless Inter-Domain Routing">CIDR</abbr>).</p>
<li><code>123.123.123.123</code> as the only upstream <abbrtitle="Domain Name System">DNS</abbr> resolver for clients with a name starting with "laptop"</li>
<li><code>1.1.1.1</code> and <code>9.9.9.9</code> for all clients in the subnet <code>10.43.8.67/28</code></li>
<li>4 resolvers (default) for all others clients.</li>
</ul>
<p>The logic determining what group a client belongs to follows a strict order: IP, client name, <abbrtitle="Classless Inter-Domain Routing">CIDR</abbr></p>
<p>If a client matches multiple client name or <abbrtitle="Classless Inter-Domain Routing">CIDR</abbr> groups, a warning is logged and the first found group is used.</p>
<p>Blocky will wait 2 seconds (default value) for the response from the external upstream <abbrtitle="Domain Name System">DNS</abbr> server. You can change this
value by setting the <code>timeout</code> configuration parameter (in <strong><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></strong>).</p>
<p>Blocky supports different upstream strategies (default <code>parallel_best</code>) that determine how and to which upstream <abbrtitle="Domain Name System">DNS</abbr> servers requests are forwarded.</p>
<p>Currently available strategies:</p>
<ul>
<li><code>parallel_best</code>: blocky picks 2 random (weighted) resolvers from the upstream group for each query and returns the answer from the fastest one.<br/>
If an upstream failed to answer within the last hour, it is less likely to be chosen for the race.<br/>
This improves your network speed and increases your privacy - your <abbrtitle="Domain Name System">DNS</abbr> traffic will be distributed over multiple providers.<br/>
(When using 10 upstream servers, each upstream will get on average 20% of the <abbrtitle="Domain Name System">DNS</abbr> requests)</li>
<li><code>random</code>: blocky picks one random (weighted) resolver from the upstream group for each query and if successful, returns its response.<br/>
If the selected resolver fails to respond, a second one is picked to which the query is sent.<br/>
The weighting is identical to the <code>parallel_best</code> strategy.<br/>
Although the <code>random</code> strategy might be slower than the <code>parallel_best</code> strategy, it offers more privacy since each request is sent to a single upstream.</li>
<li><code>strict</code>: blocky forwards the request in a strict order. If the first upstream does not respond, the second is asked, and so on.</li>
<h2id="bootstrap-dns-configuration">Bootstrap <abbrtitle="Domain Name System">DNS</abbr> configuration</h2>
<p>These <abbrtitle="Domain Name System">DNS</abbr> servers are used to resolve upstream <abbrtitle="DNS-over-HTTPS">DoH</abbr> and <abbrtitle="DNS-over-TLS">DoT</abbr> servers that are specified as host names, and list domains.
It is useful if no system <abbrtitle="Domain Name System">DNS</abbr> resolver is configured, and/or to encrypt the bootstrap queries.</p>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Mandatory</th>
<th>Default value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>upstream</td>
<td>Upstream (see above)</td>
<td>no</td>
<td></td>
<td></td>
</tr>
<tr>
<td>ips</td>
<td>List of IPs</td>
<td>yes, if upstream is <abbrtitle="DNS-over-TLS">DoT</abbr>/<abbrtitle="DNS-over-HTTPS">DoH</abbr></td>
<td></td>
<td>Only valid if upstream is <abbrtitle="DNS-over-HTTPS">DoH</abbr> or <abbrtitle="DNS-over-TLS">DoT</abbr></td>
</tr>
</tbody>
</table>
<p>When using an upstream specified by IP, and not by hostname, you can write only the upstream and skip <code>ips</code>.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>Works only on Linux/*nix OS due to golang limitations under Windows.</p>
<p>Under certain circumstances, it may be useful to filter some types of <abbrtitle="Domain Name System">DNS</abbr> queries. You can define one or more <abbrtitle="Domain Name System">DNS</abbr> query
types, all queries with these types will be dropped (empty answer will be returned).</p>
<p>This configuration will drop all 'AAAA' (IPv6) queries.</p>
<h2id="fqdn-only">FQDN only</h2>
<p>In domain environments, it may be useful to only response to FQDN requests. If this option is enabled blocky respond immediately
with <abbrtitle="Non-Existence Domain">NXDOMAIN</abbr> 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.</p>
<h2id="custom-dns">Custom <abbrtitle="Domain Name System">DNS</abbr></h2>
<p>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 <abbrtitle="Hypertext Transfer Protocol Secure">HTTPS</abbr> certificate. Multiple IP addresses for one
<p>With the optional parameter <code>rewrite</code> you can replace domain part of the query with the defined part <strong>before</strong> the
resolver lookup is performed.
The query "printer.home" will be rewritten to "printer.lan" and return 192.168.178.3.</p>
<p>With parameter <code>filterUnmappedTypes = true</code> (default), blocky will filter all queries with unmapped types, for example:
AAAA for "printer.lan" or TXT for "otherdevice.lan".
With <code>filterUnmappedTypes = false</code> a query AAAA "printer.lan" will be forwarded to the upstream <abbrtitle="Domain Name System">DNS</abbr> server.</p>
<h2id="conditional-dns-resolution">Conditional <abbrtitle="Domain Name System">DNS</abbr> resolution</h2>
<p>You can define, which <abbrtitle="Domain Name System">DNS</abbr> 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 <abbrtitle="Domain Name System">DNS</abbr> queries for the local network should be redirected to the router.</p>
<p>The optional parameter <code>rewrite</code> behaves the same as with custom <abbrtitle="Domain Name System">DNS</abbr>.</p>
<p>The optional parameter <code>fallbackUpstream</code>, 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.</p>
<p><strong>Usage:</strong> One usecase when having split <abbrtitle="Domain Name System">DNS</abbr> for internal and external (internet facing) users, but not all subdomains are listed in the internal domain</p>
<p>You can use <code>.</code> as wildcard for all non full qualified domains (domains without dot)</p>
</div>
<p>In this example, a <abbrtitle="Domain Name System">DNS</abbr> query "client.fritz.box" will be redirected to the router's <abbrtitle="Domain Name System">DNS</abbr> 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.</p>
<p>If not found and if <code>fallbackUpstream</code> was set to <code>true</code>, the original query "blog.example.com" will be sent upstream.</p>
<p>All unqualified host names (e.g. "test") will be redirected to the <abbrtitle="Domain Name System">DNS</abbr> server at 168.168.0.1.</p>
<p>One usecase for <code>fallbackUpstream</code> is when having split <abbrtitle="Domain Name System">DNS</abbr> for internal and external (internet facing) users, but not all subdomains are listed in the internal domain.</p>
<h2id="client-name-lookup">Client name lookup</h2>
<p>Blocky can try to resolve a user-friendly client name from the IP address or server URL (<abbrtitle="DNS-over-TLS">DoT</abbr> and <abbrtitle="DNS-over-HTTPS">DoH</abbr>). This is useful
for defining of blocking groups, since IP address can change dynamically.</p>
<h3id="resolving-client-name-from-urlhost">Resolving client name from URL/Host</h3>
<p>If <abbrtitle="DNS-over-TLS">DoT</abbr> or <abbrtitle="DNS-over-HTTPS">DoH</abbr> is enabled, you can use a subdomain prefixed with <code>id-</code> to provide a client name (wildcard ssl certificate
recommended).</p>
<p>Example: domain <code>example.com</code></p>
<p><abbrtitle="DNS-over-TLS">DoT</abbr> Host: <code>id-bob.example.com</code> -> request's client name is <code>bob</code>
<abbrtitle="DNS-over-HTTPS">DoH</abbr> URL: <code>https://id-bob.example.com/dns-query</code> -> request's client name is <code>bob</code></p>
<p>For <abbrtitle="DNS-over-HTTPS">DoH</abbr> you can also pass the client name as url parameter:</p>
<p><abbrtitle="DNS-over-HTTPS">DoH</abbr> URL: <code>https://blocky.example.com/dns-query/alice</code> -> request's client name is <code>alice</code></p>
<h3id="resolving-client-name-from-ip-address">Resolving client name from IP address</h3>
<p>Blocky uses <abbrtitle="Reverse DNS">rDNS</abbr> to retrieve client's name. To use this feature, you can configure a <abbrtitle="Domain Name System">DNS</abbr> server for client lookup (
typically your router). You can also define client names manually per IP address.</p>
<h4id="single-name-order">Single name order</h4>
<p>Some routers return multiple names for the client (host name and user defined name). With
parameter <code>clientLookup.singleNameOrder</code> you can specify, which of retrieved names should be used.</p>
<h4id="custom-client-name-mapping">Custom client name mapping</h4>
<p>You can also map a particular client name to one (or more) IP (ipv4/ipv6) addresses. Parameter <code>clientLookup.clients</code>
contains a map of client name and multiple IP addresses.</p>
<p>Use <code>192.168.178.1</code> for <abbrtitle="Reverse DNS">rDNS</abbr> lookup. Take second name if present, if not take first name. IP address <code>192.168.178.29</code> is mapped to <code>laptop</code> as client name.</p>
</div>
<h2id="blocking-and-whitelisting">Blocking and whitelisting</h2>
Blocking uses the <ahref="https://en.wikipedia.org/wiki/DNS_sinkhole"><abbrtitle="Domain Name System">DNS</abbr> sinkhole</a> approach. For each <abbrtitle="Domain Name System">DNS</abbr> query, the domain name from
the request, IP address from the response, and any <abbrtitle="Canonical Name">CNAME</abbr> records will be checked to determine whether to block the query or not.</p>
<p>To avoid over-blocking, you can use whitelists.</p>
<p>Lists are defined in groups. This allows using different sets of lists for different clients.</p>
<p>Each list in a group is a "source" and can be downloaded, read from a file, or inlined in the config. See <ahref="#sources">Sources</a> for details and configuring how those are loaded and reloaded/refreshed.</p>
<p>In this example you can see 2 groups: <strong>ads</strong> and <strong>special</strong> with one list. The <strong>ads</strong> group includes 2 inline lists.</p>
<p>You can use <abbrtitle="Regular expression">regex</abbr> to define patterns to block. A <abbrtitle="Regular expression">regex</abbr> entry must start and end with the slash character (<code>/</code>). Some
<li><code>/baddomain/</code> will block <code>www.baddomain.com</code>, <code>baddomain.com</code>, but also <code>mybaddomain-sometext.com</code></li>
<li><code>/^baddomain/</code> will block <code>baddomain.com</code>, but not <code>www.baddomain.com</code></li>
<li><code>/^apple\.(de|com)$/</code> will only block <code>apple.de</code> and <code>apple.com</code></li>
<p>You can use the client name (see <ahref="#client-name-lookup">Client name lookup</a>), client's IP address, client's full-qualified domain name
or a client subnet as <abbrtitle="Classless Inter-Domain Routing">CIDR</abbr> notation.</p>
<p>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.</p>
<p>All queries from network clients, whose device name starts with <code>laptop</code>, will be filtered against the <strong>ads</strong> group's lists. All devices from the subnet <code>192.168.178.1/24</code> against the <strong>special</strong> group and <code>kid-laptop</code> against <strong>ads</strong> and <strong>adult</strong>. All other clients: <strong>ads</strong> and <strong>special</strong>.</p>
</div>
<divclass="admonition tip">
<pclass="admonition-title">Tip</p>
<p>You can use <code>*</code> as wildcard for the sequence of any character or <code>[0-9]</code> as number range</p>
</div>
<h3id="block-type">Block type</h3>
<p>You can configure, which response should be sent to the client, if a requested query is blocked (only for A and AAAA
queries, <abbrtitle="Non-Existence Domain">NXDOMAIN</abbr> for other types):</p>
<table>
<thead>
<tr>
<th>blockType</th>
<th>Example</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>zeroIP</td>
<td>zeroIP</td>
<td>This is the default block type. Server returns 0.0.0.0 (or :: for IPv6) as result for A and AAAA queries</td>
</tr>
<tr>
<td>nxDomain</td>
<td>nxDomain</td>
<td>return <abbrtitle="Non-Existence Domain">NXDOMAIN</abbr> as return code</td>
<td>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.</td>
<p><abbrtitle="Time-To-Live">TTL</abbr> for answers to blocked domains can be set to customize the time (in <strong><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></strong>) clients ask for those
domains again. Default Block <abbrtitle="Time-To-Live">TTL</abbr> is <strong>6hours</strong>. This setting only makes sense when <code>blockType</code> is set to <code>nxDomain</code> or
<code>zeroIP</code>, and will affect how much time it could take for a client to be able to see the real IP address for a domain
<p>Each <abbrtitle="Domain Name System">DNS</abbr> response has a <abbrtitle="Time-To-Live">TTL</abbr> (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 <abbrtitle="Domain Name System">DNS</abbr> traffic and increases the network speed, since
blocky can serve the result immediately from the cache.</p>
<p>With following parameters you can tune the caching behavior:</p>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>Wrong values can significantly increase external <abbrtitle="Domain Name System">DNS</abbr> traffic or memory consumption.</p>
</div>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Mandatory</th>
<th>Default value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>caching.minTime</td>
<td><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
<td>How long a response must be cached (min value). If <=0, use response's <abbrtitle="Time-To-Live">TTL</abbr>, if >0 use this value, if <abbrtitle="Time-To-Live">TTL</abbr> is smaller</td>
</tr>
<tr>
<td>caching.maxTime</td>
<td><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
<td>How long a response must be cached (max value). If <0, do not cache responses. If 0, use <abbrtitle="Time-To-Live">TTL</abbr>. If > 0, use this value, if <abbrtitle="Time-To-Live">TTL</abbr> is greater</td>
</tr>
<tr>
<td>caching.maxItemsCount</td>
<td>int</td>
<td>no</td>
<td>0 (unlimited)</td>
<td>Max number of cache entries (responses) to be kept in cache (soft limit). Default (0): unlimited. Useful on systems with limited amount of RAM.</td>
</tr>
<tr>
<td>caching.prefetching</td>
<td>bool</td>
<td>no</td>
<td>false</td>
<td>if true, blocky will preload <abbrtitle="Domain Name System">DNS</abbr> 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 (<abbrtitle="Time-To-Live">TTL</abbr>). 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.</td>
</tr>
<tr>
<td>caching.prefetchExpires</td>
<td><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
<td>no</td>
<td>2h</td>
<td>Prefetch track time window</td>
</tr>
<tr>
<td>caching.prefetchThreshold</td>
<td>int</td>
<td>no</td>
<td>5</td>
<td>Name queries threshold for prefetch</td>
</tr>
<tr>
<td>caching.prefetchMaxItemsCount</td>
<td>int</td>
<td>no</td>
<td>0 (unlimited)</td>
<td>Max number of domains to be kept in cache for prefetching (soft limit). Default (0): unlimited. Useful on systems with limited amount of RAM.</td>
</tr>
<tr>
<td>caching.cacheTimeNegative</td>
<td><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
<td>no</td>
<td>30m</td>
<td>Time how long negative results (<abbrtitle="Non-Existence Domain">NXDOMAIN</abbr> response or empty result) are cached. A value of -1 will disable caching for negative results.</td>
<p>Blocky can synchronize its cache and blocking state between multiple instances through redis.
Synchronization is disabled if no address is configured.</p>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Mandatory</th>
<th>Default value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>redis.address</td>
<td>string</td>
<td>no</td>
<td></td>
<td>Server address and port or master name if sentinel is used</td>
</tr>
<tr>
<td>redis.username</td>
<td>string</td>
<td>no</td>
<td></td>
<td>Username if necessary</td>
</tr>
<tr>
<td>redis.password</td>
<td>string</td>
<td>no</td>
<td></td>
<td>Password if necessary</td>
</tr>
<tr>
<td>redis.database</td>
<td>int</td>
<td>no</td>
<td>0</td>
<td>Database</td>
</tr>
<tr>
<td>redis.required</td>
<td>bool</td>
<td>no</td>
<td>false</td>
<td>Connection is required for blocky to start</td>
</tr>
<tr>
<td>redis.connectionAttempts</td>
<td>int</td>
<td>no</td>
<td>3</td>
<td>Max connection attempts</td>
</tr>
<tr>
<td>redis.connectionCooldown</td>
<td><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
<td>no</td>
<td>1s</td>
<td>Time between the connection attempts</td>
</tr>
<tr>
<td>redis.sentinelUsername</td>
<td>string</td>
<td>no</td>
<td></td>
<td>Sentinel username if necessary</td>
</tr>
<tr>
<td>redis.sentinelPassword</td>
<td>string</td>
<td>no</td>
<td></td>
<td>Sentinel password if necessary</td>
</tr>
<tr>
<td>redis.sentinelAddresses</td>
<td>string[]</td>
<td>no</td>
<td></td>
<td>Sentinel host list (Sentinel is activated if addresses are defined)</td>
<p>Blocky can expose various metrics for prometheus. To use the prometheus feature, the <abbrtitle="Hypertext Transfer Protocol">HTTP</abbr> listener must be enabled (
see <ahref="#basic-configuration">Basic Configuration</a>).</p>
<p>You can enable the logging of <abbrtitle="Domain Name System">DNS</abbr> queries (question, answer, client, duration etc.) to a daily <abbrtitle="Comma-separated values">CSV</abbr> file (can be opened
in Excel or OpenOffice Calc) or MySQL/MariaDB database.</p>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p>Query file/database contains sensitive information. Please ensure to inform users, if you log their queries.</p>
</div>
<h3id="query-log-types">Query log types</h3>
<p>You can select one of following query log types:</p>
<ul>
<li><code>mysql</code> - log each query in the external MySQL/MariaDB database</li>
<li><code>postgresql</code> - log each query in the external PostgreSQL database</li>
<li><code>csv</code> - log into <abbrtitle="Comma-separated values">CSV</abbr> file (one per day)</li>
<li><code>csv-client</code> - log into <abbrtitle="Comma-separated values">CSV</abbr> file (one per day and per client)</li>
<li><code>console</code> - log into console output</li>
<li><code>none</code> - do not log any queries</li>
</ul>
<h3id="query-log-fields">Query log fields</h3>
<p>You can choose which information from processed <abbrtitle="Domain Name System">DNS</abbr> request and response should be logged in the target system. You can define one or more of following fields:</p>
<ul>
<li><code>clientIP</code> - origin IP address from the request</li>
<li><code>clientName</code> - resolved client name(s) from the origins request</li>
<li><code>responseReason</code> - reason for the response (e.g. from which upstream resolver), response type and code</li>
<li><code>responseAnswer</code> - returned <abbrtitle="Domain Name System">DNS</abbr> answer</li>
<li><code>question</code> - <abbrtitle="Domain Name System">DNS</abbr> question from the request</li>
<li><code>duration</code> - request processing time in milliseconds</li>
</ul>
<divclass="admonition hint">
<pclass="admonition-title">Hint</p>
<p>If not defined, blocky will log all available information</p>
</div>
<p>Configuration parameters:</p>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Mandatory</th>
<th>Default value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>queryLog.type</td>
<td>enum (mysql, postgresql, csv, csv-client, console, none (see above))</td>
<td>no</td>
<td></td>
<td>Type of logging target. Console if empty</td>
</tr>
<tr>
<td>queryLog.target</td>
<td>string</td>
<td>no</td>
<td></td>
<td>directory for writing the logs (for csv) or database url (for mysql or postgresql)</td>
</tr>
<tr>
<td>queryLog.logRetentionDays</td>
<td>int</td>
<td>no</td>
<td>0</td>
<td>if > 0, deletes log files/database entries which are older than ... days</td>
</tr>
<tr>
<td>queryLog.creationAttempts</td>
<td>int</td>
<td>no</td>
<td>3</td>
<td>Max attempts to create specific query log writer</td>
<td><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
<td><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
<td>no</td>
<td>30s</td>
<td>Interval to write data in bulk to the external database</td>
<td><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
<td>no</td>
<td>1h</td>
<td>Time between hosts file refresh</td>
</tr>
<tr>
<td>hostsFile.filterLoopback</td>
<td>bool</td>
<td>no</td>
<td>false</td>
<td>Filter loopback addresses (127.0.0.0/8 and ::1)</td>
<h2id="deliver-ede-codes-as-edns0-option">Deliver EDE codes as EDNS0 option</h2>
<p><abbrtitle="Domain Name System">DNS</abbr> responses can be extended with EDE codes according to <ahref="https://datatracker.ietf.org/doc/rfc8914/">RFC8914</a>.</p>
<p>Configuration parameters:</p>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Mandatory</th>
<th>Default value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ede.enable</td>
<td>bool</td>
<td>no</td>
<td>false</td>
<td>If true, <abbrtitle="Domain Name System">DNS</abbr> responses are deliverd with EDE codes</td>
<p>See <ahref="https://github.com/0xERR0R/blocky/wiki/Configuration-of-HTTPS-for-DoH-and-Rest-API">Wiki - Configuration of <abbrtitle="Hypertext Transfer Protocol Secure">HTTPS</abbr></a>
for detailed information, how to create and configure <abbrtitle="Secure Sockets Layer">SSL</abbr> certificates.</p>
<p>Sources are a concept shared by the blocking and hosts file resolvers. They represent where to load the files for each resolver.</p>
<p>The supported source types are:</p>
<ul>
<li><abbrtitle="Hypertext Transfer Protocol">HTTP</abbr>(S) URL (any source starting with <code>http</code>)</li>
<li>inline configuration (any source containing a newline)</li>
<li>local file path (any source not matching the above rules)</li>
</ul>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>The format/content of the sources depends on the context: lists and hosts files have different, but overlapping, supported formats.</p>
</div>
<divclass="admonition example">
<pclass="admonition-title">Example</p>
<divclass="highlight"><pre><span></span><code><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">https://example.com/a/source</span><spanclass="w"></span><spanclass="c1"># blocky will download and parse the file</span>
<spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">/a/file/path</span><spanclass="w"></span><spanclass="c1"># blocky will read the local file</span>
<spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="p p-Indicator">|</span><spanclass="w"></span><spanclass="c1"># blocky will parse the content of this multi-line string</span>
<spanclass="w"></span><spanclass="c1"># only applies to hostsFile sources</span>
</code></pre></div>
</div>
<h4id="refresh-reload">Refresh / Reload</h4>
<p>To keep source contents up-to-date, blocky can periodically refresh and reparse them. Default period is **
4 hours<strong>. You can configure this by setting the <code>refreshPeriod</code> parameter to a value in </strong><abbrtitle="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr>**.<br/>
A value of zero or less will disable this feature.</p>
<p>Blocky downloads and processes sources concurrently. This allows limiting how many can be processed in the same time.<br/>
Larger values can reduce the overall list refresh time at the cost of using more RAM. Please consider reducing this value on systems with limited memory.<br/>
<scriptid="__config"type="application/json">{"base":"..","features":[],"search":"../assets/javascripts/workers/search.f886a092.min.js","translations":{"clipboard.copied":"Copied to clipboard","clipboard.copy":"Copy to clipboard","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.placeholder":"Type to start searching","search.result.term.missing":"Missing","select.version":"Select version"},"version":{"provider":"mike"}}</script>