mirror of https://github.com/0xERR0R/blocky.git
1 line
68 KiB
JSON
1 line
68 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Blocky","text":"<p>Blocky is a DNS proxy and ad-blocker for the local network written in Go with following features:</p>"},{"location":"#features","title":"Features","text":"<ul> <li> <p>Blocking - Blocking of DNS queries with external lists (Ad-block, malware) and whitelisting</p> <ul> <li>Definition of black and white lists per client group (Kids, Smart home devices, etc.)</li> <li>Periodical reload of external black and white lists</li> <li>Regex support</li> <li>Blocking of request domain, response CNAME (deep CNAME inspection) and response IP addresses (against IP lists)</li> </ul> </li> <li> <p>Advanced DNS configuration - not just an ad-blocker</p> <ul> <li>Custom DNS resolution for certain domain names</li> <li>Conditional forwarding to external DNS server</li> <li>Upstream resolvers can be defined per client group</li> </ul> </li> <li> <p>Performance - Improves speed and performance in your network</p> <ul> <li>Customizable caching of DNS answers for queries -> improves DNS resolution speed and reduces amount of external DNS queries</li> <li>Prefetching and caching of often used queries</li> <li>Using multiple external resolver simultaneously</li> <li>Low memory footprint</li> </ul> </li> <li> <p>Various Protocols - Supports modern DNS protocols</p> <ul> <li>DNS over UDP and TCP</li> <li>DNS over HTTPS (aka DoH)</li> <li>DNS over TLS (aka DoT)</li> </ul> </li> <li> <p>Security and Privacy - Secure communication</p> <ul> <li>Supports modern DNS extensions: DNSSEC, eDNS, ...</li> <li>Free configurable blocking lists - no hidden filtering etc.</li> <li>Provides DoH Endpoint</li> <li>Uses random upstream resolvers from the configuration - increases your privacy through the distribution of your DNS traffic over multiple provider</li> <li>Open source development</li> <li>Blocky does NOT collect any user data, telemetry, statistics etc.</li> </ul> </li> <li> <p>Integration - various integration</p> <ul> <li>Prometheus metrics</li> <li>Prepared Grafana dashboards (Prometheus and database)</li> <li>Logging of DNS queries per day / per client in CSV format or MySQL/MariaDB/PostgreSQL database - easy to analyze</li> <li>Various REST API endpoints</li> <li>CLI tool</li> </ul> </li> <li> <p>Simple configuration - single configuration file in YAML format</p> <ul> <li>Simple to maintain</li> <li>Simple to backup</li> </ul> </li> <li> <p>Simple installation/configuration - blocky was designed for simple installation</p> <ul> <li>Stateless (no database, no temporary files)</li> <li>Docker image with Multi-arch support</li> <li>Single binary</li> <li>Supports x86-64 and ARM architectures -> runs fine on Raspberry PI</li> <li>Community supported Helm chart for k8s deployment</li> </ul> </li> </ul>"},{"location":"#contribution","title":"Contribution","text":"<p>Issues, feature suggestions and pull requests are welcome! Blocky lives on GitHub.</p>"},{"location":"additional_information/","title":"Additional information","text":""},{"location":"additional_information/#print-current-configuration","title":"Print current configuration","text":"<p>To print runtime configuration / statistics, you can send <code>SIGUSR1</code> signal to running process.</p> <p>Summary</p> <p>Example output:</p> <pre><code>INFO server: current configuration:\nINFO server: -> resolver: 'ClientNamesResolver'\nINFO server: singleNameOrder = \"[2 1]\"\nINFO server: externalResolver = \"upstream 'tcp+udp:192.168.178.1:53'\"\nINFO server: cache item count = 7\nINFO server: -> resolver: 'QueryLoggingResolver'\nINFO server: logDir= \"/logs\"\nINFO server: perClient = false\nINFO server: logRetentionDays= 7\nINFO server: -> resolver: 'MetricsResolver'\nINFO server: metrics:\nINFO server: Enable = true\nINFO server: Path = /metrics\nINFO server: -> resolver: 'ConditionalUpstreamResolver'\nINFO server: fritz.box = \"parallel upstreams 'upstream 'tcp+udp:192.168.178.1:53''\"\nINFO server: -> resolver: 'CustomDNSResolver'\nINFO server: runtime information:\n...\nINFO server: MEM Alloc = 9 MB\nINFO server: MEM HeapAlloc = 9 MB\nINFO server: MEM Sys = 88 MB\nINFO server: MEM NumGC = 1533\nINFO server: RUN NumCPU = 4\nINFO server: RUN NumGoroutine = 18\n</code></pre> <p>Hint</p> <p>To send a signal to a process you can use <code>kill -s USR1 <PID></code> or <code>docker kill -s SIGUSR1 blocky</code> for docker setup</p>"},{"location":"additional_information/#debug-profiling","title":"Debug / Profiling","text":"<p>If http listener is enabled, pprof endpoint (<code>/debug/pprof</code>) is enabled automatically.</p>"},{"location":"additional_information/#list-sources","title":"List sources","text":"<p>Some links/ideas for lists:</p>"},{"location":"additional_information/#blacklists","title":"Blacklists","text":"<ul> <li>https://github.com/StevenBlack/hosts</li> <li>https://github.com/nickspaargaren/no-google</li> <li>https://energized.pro/</li> <li>https://github.com/Perflyst/PiHoleBlocklist</li> <li>https://github.com/kboghdady/youTube_ads_4_pi-hole</li> <li>https://github.com/chadmayfield/my-pihole-blocklists</li> </ul> <p>Warning</p> <p>Use only blacklists from the sources you trust!</p>"},{"location":"additional_information/#whitelists","title":"Whitelists","text":"<ul> <li>https://github.com/anudeepND/whitelist</li> </ul>"},{"location":"additional_information/#list-of-public-dns-servers","title":"List of public DNS servers","text":"<p>Warning</p> <p>DNS server provider has access to all your DNS queries (all visited domain names). Some DNS providers can use (tracking, analyzing, profiling etc.). It is recommended to use different DNS upstream servers in blocky to distribute your DNS queries over multiple providers.</p> <p>Please read the description before using the DNS server as upstream. Some of them provide already an ad-blocker, some filters other content. If you use external DNS server with included ad-blocker, you can't choose which domains should be blocked, and you can't use whitelisting.</p> <p>This is only a small excerpt of all free available DNS servers and should only be understood as an idee.</p> <p>Info</p> <p>I will NOT rate the DNS providers in the list. This list is sorted alphabetically.</p> <ul> <li>AdGuard</li> <li>CloudFlare</li> <li>Comodo</li> <li>DigitalCourage</li> <li>DigitaleGesellschaft</li> <li>Dismail</li> <li>dnsforge</li> <li>Google</li> <li>OpenDNS</li> <li>Quad9</li> <li>UncensoredDNS</li> </ul>"},{"location":"additional_information/#project-links","title":"Project links","text":""},{"location":"additional_information/#code-repository","title":"Code repository","text":"<p>Main: GitHub</p> <p>Mirror: Codeberg</p>"},{"location":"additional_information/#container-registry","title":"Container Registry","text":"<p>Main: Docker Hub</p> <p>Mirror: GitHub Container Registry</p>"},{"location":"additional_information/#developer-information","title":"Developer Information","text":""},{"location":"additional_information/#docker-images","title":"Docker Images","text":"<p>To enable Docker image creation on a GitHub fork create a secret with the name <code>DEVELOPMENT_DOCKER</code> and the value <code>true</code>. This will trigger a workflow on every push of a branch starting with <code>fb-</code> and create an image with the branch name.</p>"},{"location":"additional_information/#automatic-fork-sync","title":"Automatic fork sync","text":"<p>To enable automatic fork synchronisation create a secret with the name <code>FORK_SYNC_TOKEN</code> with an access token that has write permission to the fork repository. The enabled workflow will sync the main branch every 30 minutes with its upstream.</p>"},{"location":"configuration/","title":"Configuration","text":"<p>This chapter describes all configuration options in <code>config.yaml</code>. You can download a reference file with all configuration properties as JSON.</p> reference configuration file <pre><code># REVIEW: manual changelog entry\n\nupstreams:\ngroups:\n# these external DNS resolvers will be used. Blocky picks 2 random resolvers from the list for each query\n# 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))\n# this configuration is mandatory, please define at least one external DNS resolver\ndefault:\n# example for tcp+udp IPv4 server (https://digitalcourage.de/)\n- 5.9.164.112\n# Cloudflare\n- 1.1.1.1\n# example for DNS-over-TLS server (DoT)\n- tcp-tls:fdns1.dismail.de:853\n# example for DNS-over-HTTPS (DoH)\n- https://dns.digitale-gesellschaft.ch/dns-query\n# optional: use client name (with wildcard support: * - sequence of any characters, [0-9] - range)\n# or single ip address / client subnet as CIDR notation\nlaptop*:\n- 123.123.123.123\n# optional: Determines what strategy blocky uses to choose the upstream servers.\n# accepted: parallel_best, strict\n# default: parallel_best\nstrategy: parallel_best\n# optional: timeout to query the upstream resolver. Default: 2s\ntimeout: 2s\n\n# optional: If true, blocky will fail to start unless at least one upstream server per group is reachable. Default: false\nstartVerifyUpstream: true\n\n# optional: Determines how blocky will create outgoing connections. This impacts both upstreams, and lists.\n# accepted: dual, v4, v6\n# default: dual\nconnectIPVersion: dual\n\n# optional: custom IP address(es) for domain name (with all sub-domains). Multiple addresses must be separated by a comma\n# example: query \"printer.lan\" or \"my.printer.lan\" will return 192.168.178.3\ncustomDNS:\ncustomTTL: 1h\n# optional: if true (default), return empty result for unmapped query types (for example TXT, MX or AAAA if only IPv4 address is defined).\n# if false, queries with unmapped types will be forwarded to the upstream resolver\nfilterUnmappedTypes: true\n# optional: replace domain in the query with other domain before resolver lookup in the mapping\nrewrite:\nexample.com: printer.lan\nmapping:\nprinter.lan: 192.168.178.3,2001:0db8:85a3:08d3:1319:8a2e:0370:7344\n\n# 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\n# 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\nconditional:\n# 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\n# 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.\n# Usage: One usecase when having split DNS for internal and external (internet facing) users, but not all subdomains are listed in the internal domain.\nfallbackUpstream: false\n# optional: replace domain in the query with other domain before resolver lookup in the mapping\nrewrite:\nexample.com: fritz.box\nmapping:\nfritz.box: 192.168.178.1\nlan.net: 192.168.178.1,192.168.178.2\n\n# optional: use black and white lists to block queries (for example ads, trackers, adult pages etc.)\nblocking:\n# definition of blacklist groups. Can be external link (http/https) or local file\nblackLists:\nads:\n- https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt\n- https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts\n- http://sysctl.org/cameleon/hosts\n- https://s3.amazonaws.com/lists.disconnect.me/simple_tracking.txt\n- |\n# inline definition with YAML literal block scalar style\n# hosts format\nsomeadsdomain.com\nspecial:\n- https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews/hosts\n# 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\nwhiteLists:\nads:\n- whitelist.txt\n- |\n# inline definition with YAML literal block scalar style\n# hosts format\nwhitelistdomain.com\n# this is a regex\n/^banners?[_.-]/\n# definition: which groups should be applied for which client\nclientGroupsBlock:\n# default will be used, if no special definition for a client name exists\ndefault:\n- ads\n- special\n# use client name (with wildcard support: * - sequence of any characters, [0-9] - range)\n# or single ip address / client subnet as CIDR notation\nlaptop*:\n- ads\n192.168.178.1/24:\n- special\n# which response will be sent, if query is blocked:\n# zeroIp: 0.0.0.0 will be returned (default)\n# nxDomain: return NXDOMAIN as return code\n# 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.\nblockType: zeroIp\n# optional: TTL for answers to blocked domains\n# default: 6h\nblockTTL: 1m\n# optional: Configure how lists, AKA sources, are loaded\nloading:\n# optional: list refresh period in duration format.\n# Set to a value <= 0 to disable.\n# default: 4h\nrefreshPeriod: 24h\n# optional: Applies only to lists that are downloaded (HTTP URLs).\ndownloads:\n# optional: timeout for list download (each url). Use large values for big lists or slow internet connections\n# default: 5s\ntimeout: 60s\n# optional: Maximum download attempts\n# default: 3\nattempts: 5\n# optional: Time between the download attempts\n# default: 500ms\ncooldown: 10s\n# optional: Maximum number of lists to process in parallel.\n# default: 4\nconcurrency: 16\n# optional: if failOnError, application startup will fail if at least one list can't be downloaded/opened\n# default: blocking\nstrategy: failOnError\n# Number of errors allowed in a list before it is considered invalid.\n# A value of -1 disables the limit.\n# default: 5\nmaxErrorsPerSource: 5\n\n# optional: configuration for caching of DNS responses\ncaching:\n# duration how long a response must be cached (min value).\n# If <=0, use response's TTL, if >0 use this value, if TTL is smaller\n# Default: 0\nminTime: 5m\n# duration how long a response must be cached (max value).\n# If <0, do not cache responses\n# If 0, use TTL\n# If > 0, use this value, if TTL is greater\n# Default: 0\nmaxTime: 30m\n# Max number of cache entries (responses) to be kept in cache (soft limit). Useful on systems with limited amount of RAM.\n# Default (0): unlimited\nmaxItemsCount: 0\n# if true, will preload DNS results for often used queries (default: names queried more than 5 times in a 2-hour time window)\n# this improves the response time for often used queries, but significantly increases external traffic\n# default: false\nprefetching: true\n# prefetch track time window (in duration format)\n# default: 120\nprefetchExpires: 2h\n# name queries threshold for prefetch\n# default: 5\nprefetchThreshold: 5\n# Max number of domains to be kept in cache for prefetching (soft limit). Useful on systems with limited amount of RAM.\n# Default (0): unlimited\nprefetchMaxItemsCount: 0\n# Time how long negative results (NXDOMAIN response or empty result) are cached. A value of -1 will disable caching for negative results.\n# Default: 30m\ncacheTimeNegative: 30m\n\n# optional: configuration of client name resolution\nclientLookup:\n# optional: this DNS resolver will be used to perform reverse DNS lookup (typically local router)\nupstream: 192.168.178.1\n# optional: some routers return multiple names for client (host name and user defined name). Define which single name should be used.\n# Example: take second name if present, if not take first name\nsingleNameOrder:\n- 2\n- 1\n# optional: custom mapping of client name to IP addresses. Useful if reverse DNS does not work properly or just to have custom client names.\nclients:\nlaptop:\n- 192.168.178.29\n\n# optional: configuration for prometheus metrics endpoint\nprometheus:\n# enabled if true\nenable: true\n# url path, optional (default '/metrics')\npath: /metrics\n\n# optional: write query information (question, answer, client, duration etc.) to daily csv file\nqueryLog:\n# optional one of: mysql, postgresql, csv, csv-client. If empty, log to console\ntype: mysql\n# directory (should be mounted as volume in docker) for csv, db connection string for mysql/postgresql\ntarget: db_user:db_password@tcp(db_host_or_ip:3306)/db_name?charset=utf8mb4&parseTime=True&loc=Local\n#postgresql target: postgres://user:password@db_host_or_ip:5432/db_name\n# if > 0, deletes log files which are older than ... days\nlogRetentionDays: 7\n# optional: Max attempts to create specific query log writer, default: 3\ncreationAttempts: 1\n# optional: Time between the creation attempts, default: 2s\ncreationCooldown: 2s\n# 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\nfields:\n- clientIP\n- duration\n\n# optional: Blocky can synchronize its cache and blocking state between multiple instances through redis.\nredis:\n# Server address and port or master name if sentinel is used\naddress: redismaster\n# Username if necessary\nusername: usrname\n# Password if necessary\npassword: passwd\n# Database, default: 0\ndatabase: 2\n# Connection is required for blocky to start. Default: false\nrequired: true\n# Max connection attempts, default: 3\nconnectionAttempts: 10\n# Time between the connection attempts, default: 1s\nconnectionCooldown: 3s\n# Sentinal username if necessary\nsentinelUsername: usrname\n# Sentinal password if necessary\nsentinelPassword: passwd\n# List with address and port of sentinel hosts(sentinel is activated if at least one sentinel address is configured)\nsentinelAddresses:\n- redis-sentinel1:26379\n- redis-sentinel2:26379\n- redis-sentinel3:26379\n\n# optional: Mininal TLS version that the DoH and DoT server will use\nminTlsServeVersion: 1.3\n\n# if https port > 0: path to cert and key file for SSL encryption. if not set, self-signed certificate will be generated\n#certFile: server.crt\n#keyFile: server.key\n\n# 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.\nbootstrapDns:\n- tcp+udp:1.1.1.1\n- https://1.1.1.1/dns-query\n- upstream: https://dns.digitale-gesellschaft.ch/dns-query\nips:\n- 185.95.218.42\n\n# optional: drop all queries with following query types. Default: empty\nfiltering:\nqueryTypes:\n- AAAA\n\n# optional: return NXDOMAIN for queries that are not FQDNs.\nfqdnOnly:\n# default: false\nenable: true\n\n# optional: if path defined, use this file for query resolution (A, AAAA and rDNS). Default: empty\nhostsFile:\n# optional: Hosts files to parse\nsources:\n- /etc/hosts\n- https://example.com/hosts\n- |\n# inline hosts\n127.0.0.1 example.com\n# optional: TTL, default: 1h\nhostsTTL: 30m\n# optional: Whether loopback hosts addresses (127.0.0.0/8 and ::1) should be filtered or not\n# default: false\nfilterLoopback: true\n# optional: Configure how sources are loaded\nloading:\n# optional: file refresh period in duration format.\n# Set to a value <= 0 to disable.\n# default: 4h\nrefreshPeriod: 24h\n# optional: Applies only to files that are downloaded (HTTP URLs).\ndownloads:\n# optional: timeout for file download (each url). Use large values for big files or slow internet connections\n# default: 5s\ntimeout: 60s\n# optional: Maximum download attempts\n# default: 3\nattempts: 5\n# optional: Time between the download attempts\n# default: 500ms\ncooldown: 10s\n# optional: Maximum number of files to process in parallel.\n# default: 4\nconcurrency: 16\n# optional: if failOnError, application startup will fail if at least one file can't be downloaded/opened\n# default: blocking\nstrategy: failOnError\n# Number of errors allowed in a file before it is considered invalid.\n# A value of -1 disables the limit.\n# default: 5\nmaxErrorsPerSource: 5\n\n# optional: ports configuration\nports:\n# 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\"\ndns: 53\n# optional: Port(s) and bind ip address(es) for DoT (DNS-over-TLS) listener. Example: 853, 127.0.0.1:853\ntls: 853\n# 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\nhttps: 443\n# 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\nhttp: 4000\n\n# optional: logging configuration\nlog:\n# optional: Log level (one from debug, info, warn, error). Default: info\nlevel: info\n# optional: Log format (text or json). Default: text\nformat: text\n# optional: log timestamps. Default: true\ntimestamp: true\n# optional: obfuscate log output (replace all alphanumeric characters with *) for user sensitive data like request domains or responses to increase privacy. Default: false\nprivacy: false\n\n# optional: add EDE error codes to dns response\nede:\n# enabled if true, Default: false\nenable: true\n\n# optional: configure optional Special Use Domain Names (SUDN)\nspecialUseDomains:\n# optional: block recomended private TLDs\n# default: true\nrfc6762-appendixG: true\n</code></pre>"},{"location":"configuration/#basic-configuration","title":"Basic configuration","text":"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) <p>Example</p> <pre><code>minTlsServeVersion: 1.1\nconnectIPVersion: v4\n</code></pre>"},{"location":"configuration/#ports-configuration","title":"Ports configuration","text":"<p>All logging port are optional.</p> 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 <code>192.168.0.1:53</code>. Example: <code>53</code>, <code>:53</code>, <code>127.0.0.1:53,[::1]:53</code> 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 <code>192.168.0.1:853</code>. Example: <code>83</code>, <code>:853</code>, <code>127.0.0.1:853,[::1]:853</code> 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 <code>192.168.0.1:4000</code>. Example: <code>4000</code>, <code>:4000</code>, <code>127.0.0.1:4000,[::1]:4000</code> 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 <code>192.168.0.1:443</code>. Example: <code>443</code>, <code>:443</code>, <code>127.0.0.1:443,[::1]:443</code> <p>Example</p> <pre><code>ports:\ndns: 53\nhttp: 4000\nhttps: 443\n</code></pre>"},{"location":"configuration/#logging-configuration","title":"Logging configuration","text":"<p>All logging options are optional.</p> 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. <p>Example</p> <pre><code>log:\nlevel: debug\nformat: json\ntimestamp: false\nprivacy: true\n</code></pre>"},{"location":"configuration/#upstreams-configuration","title":"Upstreams configuration","text":"<p>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):</p> <ul> <li>tcp+udp (UDP and TCP, dependent on query type)</li> <li>https (aka DoH)</li> <li>tcp-tls (aka DoT)</li> </ul> <p>Hint</p> <p>You can (and should!) configure multiple DNS resolvers. Per default blocky uses the <code>parallel_best</code> upstream strategy where blocky picks 2 random resolvers from the list for each query and returns the answer from the fastest one. </p> <p>Each resolver must be defined as a string in following format: <code>[net:]host:[port][/path][#commonName]</code>.</p> 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 <p>The <code>commonName</code> parameter overrides the expected certificate common name value used for verification.</p> <p>Note</p> <p>Blocky needs at least the configuration of the default group with at least one upstream DNS server. This group will be used as a fallback, if no client specific resolver configuration is available.</p> <p>See List of public DNS servers if you need some ideas, which public free DNS server you could use.</p> <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 Client name lookup), client IP address or client subnet (as CIDR).</p> <p>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> <p>Example</p> <pre><code>upstreams:\ngroups:\ndefault:\n- 5.9.164.112\n- 1.1.1.1\n- tcp-tls:fdns1.dismail.de:853\n- https://dns.digitale-gesellschaft.ch/dns-query\nlaptop*:\n- 123.123.123.123\n10.43.8.67/28:\n- 1.1.1.1\n- 9.9.9.9\n</code></pre> <p>The above example results in:</p> <ul> <li><code>123.123.123.123</code> as the only upstream DNS 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, CIDR</p> <p>If a client matches multiple client name or CIDR groups, a warning is logged and the first found group is used.</p>"},{"location":"configuration/#upstream-strategy","title":"Upstream strategy","text":"<p>Blocky supports different upstream strategies (default <code>parallel_best</code>) that determine how and to which upstream DNS 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. If an upstream failed to answer within the last hour, it is less likely to be chosen for the race. This improves your network speed and increases your privacy - your DNS traffic will be distributed over multiple providers (When using 10 upstream servers, each upstream will get on average 20% of the DNS requests)</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> </ul> <p>Example</p> <pre><code>upstreams:\nstrategy: strict\ngroups:\ndefault:\n- 1.2.3.4\n- 9.8.7.6\n</code></pre>"},{"location":"configuration/#upstream-lookup-timeout","title":"Upstream lookup timeout","text":"<p>Blocky will wait 2 seconds (default value) for the response from the external upstream DNS server. You can change this value by setting the <code>timeout</code> configuration parameter (in duration format).</p> <p>Example</p> <pre><code>upstreams:\ntimeout: 5s\ngroups:\ndefault:\n- 46.182.19.48\n- 80.241.218.68\n</code></pre>"},{"location":"configuration/#bootstrap-dns-configuration","title":"Bootstrap DNS configuration","text":"<p>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.</p> 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 <p>When using an upstream specified by IP, and not by hostname, you can write only the upstream and skip <code>ips</code>.</p> <p>Note</p> <p>Works only on Linux/*nix OS due to golang limitations under Windows.</p> <p>Example</p> <pre><code> bootstrapDns:\n- upstream: tcp-tls:dns.example.com\nips:\n- 123.123.123.123\n- upstream: https://234.234.234.234/dns-query\n</code></pre>"},{"location":"configuration/#filtering","title":"Filtering","text":"<p>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).</p> <p>Example</p> <pre><code>filtering:\nqueryTypes:\n- AAAA\n</code></pre> <p>This configuration will drop all 'AAAA' (IPv6) queries.</p>"},{"location":"configuration/#fqdn-only","title":"FQDN only","text":"<p>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.</p> <p>Example</p> <pre><code>fqdnOnly:\nenable: true\n</code></pre>"},{"location":"configuration/#custom-dns","title":"Custom DNS","text":"<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 HTTPS certificate. Multiple IP addresses for one domain must be separated by a comma.</p> 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 <p>Example</p> <pre><code>customDNS:\ncustomTTL: 1h\nfilterUnmappedTypes: true\nrewrite:\nhome: lan\nreplace-me.com: with-this.com\nmapping:\nprinter.lan: 192.168.178.3\notherdevice.lan: 192.168.178.15,2001:0db8:85a3:08d3:1319:8a2e:0370:7344\n</code></pre> <p>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.</p> <p>With the optional parameter <code>rewrite</code> 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.</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 DNS server.</p>"},{"location":"configuration/#conditional-dns-resolution","title":"Conditional DNS resolution","text":"<p>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.</p> <p>The optional parameter <code>rewrite</code> behaves the same as with custom DNS.</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>Usage: One usecase when having split DNS for internal and external (internet facing) users, but not all subdomains are listed in the internal domain</p> <p>Example</p> <pre><code>conditional:\nfallbackUpstream: false\nrewrite:\nexample.com: fritz.box\nreplace-me.com: with-this.com\nmapping:\nfritz.box: 192.168.178.1\nlan.net: 192.170.1.2,192.170.1.3\n# for reverse DNS lookups of local devices\n178.168.192.in-addr.arpa: 192.168.178.1\n# for all unqualified hostnames\n.: 168.168.0.1\n</code></pre> <p>Tip</p> <p>You can use <code>.</code> as wildcard for all non full qualified domains (domains without dot)</p> <p>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.</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 DNS server at 168.168.0.1.</p> <p>One usecase for <code>fallbackUpstream</code> is when having split DNS for internal and external (internet facing) users, but not all subdomains are listed in the internal domain.</p>"},{"location":"configuration/#client-name-lookup","title":"Client name lookup","text":"<p>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.</p>"},{"location":"configuration/#resolving-client-name-from-urlhost","title":"Resolving client name from URL/Host","text":"<p>If DoT or DoH 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>DoT Host: <code>id-bob.example.com</code> -> request's client name is <code>bob</code> DoH URL: <code>https://id-bob.example.com/dns-query</code> -> request's client name is <code>bob</code></p> <p>For DoH you can also pass the client name as url parameter:</p> <p>DoH URL: <code>https://blocky.example.com/dns-query/alice</code> -> request's client name is <code>alice</code></p>"},{"location":"configuration/#resolving-client-name-from-ip-address","title":"Resolving client name from IP address","text":"<p>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.</p>"},{"location":"configuration/#single-name-order","title":"Single name order","text":"<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>"},{"location":"configuration/#custom-client-name-mapping","title":"Custom client name mapping","text":"<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>Example</p> <pre><code>clientLookup:\nupstream: 192.168.178.1\nsingleNameOrder:\n- 2\n- 1\nclients:\nlaptop:\n- 192.168.178.29\n</code></pre> <p>Use <code>192.168.178.1</code> for rDNS 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>"},{"location":"configuration/#blocking-and-whitelisting","title":"Blocking and whitelisting","text":"<p>Blocky can use lists of domains and IPs to block (e.g. advertisement, malware, trackers, adult sites). You can group several list sources together and define the blocking behavior per client. Blocking uses the DNS sinkhole approach. For each DNS query, the domain name from the request, IP address from the response, and any CNAME records will be checked to determine whether to block the query or not.</p> <p>To avoid over-blocking, you can use whitelists.</p>"},{"location":"configuration/#definition-black-and-whitelists","title":"Definition black and whitelists","text":"<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 Sources for details and configuring how those are loaded and reloaded/refreshed.</p> <p>The supported list formats are:</p> <ol> <li>the well-known Hosts format</li> <li>one domain per line (plain domain list)</li> <li>one regex per line</li> </ol> <p>Example</p> <pre><code>blocking:\nblackLists:\nads:\n- https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt\n- https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts\n- |\n# inline definition using YAML literal block scalar style\n# content is in plain domain list format\nsomeadsdomain.com\nanotheradsdomain.com\n- |\n# inline definition with a regex\n/^banners?[_.-]/\nspecial:\n- https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews/hosts\nwhiteLists:\nads:\n- whitelist.txt\n- /path/to/file.txt\n- |\n# inline definition with YAML literal block scalar style\nwhitelistdomain.com\n</code></pre> <p>In this example you can see 2 groups: ads and special with one list. The ads group includes 2 inline lists.</p> <p>Warning</p> <p>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.</p> <p>Warning</p> <p>You must also define client group mapping, otherwise you black and whitelist definition will have no effect.</p>"},{"location":"configuration/#regex-support","title":"Regex support","text":"<p>You can use regex to define patterns to block. A regex entry must start and end with the slash character (<code>/</code>). Some Examples:</p> <ul> <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> </ul>"},{"location":"configuration/#client-groups","title":"Client groups","text":"<p>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.</p> <p>Clients without an explicit group assignment will use the default group.</p> <p>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.</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>Example</p> <pre><code>blocking:\nclientGroupsBlock:\n# default will be used, if no special definition for a client name exists\ndefault:\n- ads\n- special\nlaptop*:\n- ads\n192.168.178.1/24:\n- special\nkid-laptop:\n- ads\n- adult\n</code></pre> <p>All queries from network clients, whose device name starts with <code>laptop</code>, will be filtered against the ads group's lists. All devices from the subnet <code>192.168.178.1/24</code> against the special group and <code>kid-laptop</code> against ads and adult. All other clients: ads and special.</p> <p>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>"},{"location":"configuration/#block-type","title":"Block type","text":"<p>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):</p> 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. <p>Example</p> <pre><code>blocking:\nblockType: nxDomain\n</code></pre>"},{"location":"configuration/#block-ttl","title":"Block TTL","text":"<p>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 <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 after receiving the custom value.</p> <p>Example</p> <pre><code>blocking:\nblockType: 192.100.100.15, 2001:0db8:85a3:08d3:1319:8a2e:0370:7344\nblockTTL: 10s\n</code></pre>"},{"location":"configuration/#lists-loading","title":"Lists Loading","text":"<p>See Sources Loading.</p>"},{"location":"configuration/#caching","title":"Caching","text":"<p>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.</p> <p>With following parameters you can tune the caching behavior:</p> <p>Warning</p> <p>Wrong values can significantly increase external DNS traffic or memory consumption.</p> 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. <p>Example</p> <pre><code>caching:\nminTime: 5m\nmaxTime: 30m\nprefetching: true\n</code></pre>"},{"location":"configuration/#redis","title":"Redis","text":"<p>Blocky can synchronize its cache and blocking state between multiple instances through redis. Synchronization is disabled if no address is configured.</p> 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) <p>Example</p> <pre><code>redis:\naddress: redismaster\nusername: usrname\npassword: passwd\ndatabase: 2\nrequired: true\nconnectionAttempts: 10\nconnectionCooldown: 3s\nsentinelUsername: sentUsrname\nsentinelPassword: sentPasswd\nsentinelAddresses:\n- redis-sentinel1:26379\n- redis-sentinel2:26379\n- redis-sentinel3:26379\n</code></pre>"},{"location":"configuration/#prometheus","title":"Prometheus","text":"<p>Blocky can expose various metrics for prometheus. To use the prometheus feature, the HTTP listener must be enabled ( see Basic Configuration).</p> Parameter Mandatory Default value Description prometheus.enable no false If true, enables prometheus metrics prometheus.path no /metrics URL path to the metrics endpoint <p>Example</p> <pre><code>prometheus:\nenable: true\npath: /metrics\n</code></pre>"},{"location":"configuration/#query-logging","title":"Query logging","text":"<p>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.</p> <p>Warning</p> <p>Query file/database contains sensitive information. Please ensure to inform users, if you log their queries.</p>"},{"location":"configuration/#query-log-types","title":"Query log types","text":"<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 CSV file (one per day)</li> <li><code>csv-client</code> - log into CSV 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>"},{"location":"configuration/#query-log-fields","title":"Query log fields","text":"<p>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:</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 DNS answer</li> <li><code>question</code> - DNS question from the request</li> <li><code>duration</code> - request processing time in milliseconds</li> </ul> <p>Hint</p> <p>If not defined, blocky will log all available information</p> <p>Configuration parameters:</p> 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 <p>Hint</p> <p>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)</p> <p>example for CSV format with limited logging information</p> <p>Example</p> <pre><code>queryLog:\ntype: csv\ntarget: /logs\nlogRetentionDays: 7\nfields:\n- clientIP\n- duration\n</code></pre> <p>example for Database</p> <p>Example</p> <pre><code>queryLog:\ntype: mysql\ntarget: db_user:db_password@tcp(db_host_or_ip:3306)/db_user?charset=utf8mb4&parseTime=True&loc=Local\nlogRetentionDays: 7\n</code></pre>"},{"location":"configuration/#hosts-file","title":"Hosts file","text":"<p>You can enable resolving of entries, located in local hosts file.</p> <p>Configuration parameters:</p> 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) <p>Example</p> <pre><code>hostsFile:\nfilePath: /etc/hosts\nhostsTTL: 1h\nrefreshPeriod: 30m\n</code></pre>"},{"location":"configuration/#deliver-ede-codes-as-edns0-option","title":"Deliver EDE codes as EDNS0 option","text":"<p>DNS responses can be extended with EDE codes according to RFC8914.</p> <p>Configuration parameters:</p> Parameter Type Mandatory Default value Description ede.enable bool no false If true, DNS responses are deliverd with EDE codes <p>Example</p> <pre><code>ede:\nenable: true\n</code></pre>"},{"location":"configuration/#special-use-domain-names","title":"Special Use Domain Names","text":"<p>SUDN (Special Use Domain Names) are always enabled as they are required by various RFCs. Some RFCs have optional recommendations, which are configurable as described below.</p> <p>Configuration parameters:</p> Parameter Type Mandatory Default value Description specialUseDomains.rfc6762-appendixG bool no true Block TLDs listed in RFC 6762 Appendix G <p>Example</p> <pre><code>specialUseDomains:\nrfc6762-appendixG: true\n</code></pre>"},{"location":"configuration/#ssl-certificate-configuration-doh-tls-listener","title":"SSL certificate configuration (DoH / TLS listener)","text":"<p>See Wiki - Configuration of HTTPS for detailed information, how to create and configure SSL certificates.</p> <p>DoH url: <code>https://host:port/dns-query</code></p>"},{"location":"configuration/#sources","title":"Sources","text":"<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>HTTP(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> <p>Note</p> <p>The format/content of the sources depends on the context: lists and hosts files have different, but overlapping, supported formats.</p> <p>Example</p> <pre><code>- https://example.com/a/source # blocky will download and parse the file\n- /a/file/path # blocky will read the local file\n- | # blocky will parse the content of this multi-line string\n# inline configuration\n</code></pre>"},{"location":"configuration/#sources-loading","title":"Sources Loading","text":"<p>This sections covers <code>loading</code> configuration that applies to both the blocking and hosts file resolvers. These settings apply only to the resolver under which they are nested.</p> <p>Example</p> <pre><code>blocking:\nloading:\n# only applies to white/blacklists\n\nhostsFile:\nloading:\n# only applies to hostsFile sources\n</code></pre>"},{"location":"configuration/#refresh-reload","title":"Refresh / Reload","text":"<p>To keep source contents up-to-date, blocky can periodically refresh and reparse them. Default period is ** 4 hours. You can configure this by setting the <code>refreshPeriod</code> parameter to a value in duration format**. A value of zero or less will disable this feature.</p> <p>Example</p> <pre><code>loading:\nrefreshPeriod: 1h\n</code></pre> <p>Refresh every hour.</p>"},{"location":"configuration/#downloads","title":"Downloads","text":"<p>Configures how HTTP(S) sources are downloaded:</p> Parameter Type Mandatory Default value Description timeout duration no 5s Download attempt timeout attempts int no 3 How many download attempts should be performed cooldown duration no 500ms Time between the download attempts <p>Example</p> <pre><code>loading:\ndownloads:\ntimeout: 4m\nattempts: 5\ncooldown: 10s\n</code></pre>"},{"location":"configuration/#strategy","title":"Strategy","text":"<p>This configures how Blocky startup works. The default strategy is blocking.</p> strategy Description blocking all sources are loaded before DNS resolution starts failOnError like blocking but blocky will shut down if any source fails to load fast blocky starts serving DNS immediately and sources are loaded asynchronously. The features requiring the sources should enable soon after <p>Example</p> <pre><code>loading:\nstrategy: failOnError\n</code></pre>"},{"location":"configuration/#max-errors-per-source","title":"Max Errors per Source","text":"<p>Number of errors allowed when parsing a source before it is considered invalid and parsing stops. A value of -1 disables the limit.</p> <p>Example</p> <pre><code>loading:\nmaxErrorsPerSource: 10\n</code></pre>"},{"location":"configuration/#concurrency","title":"Concurrency","text":"<p>Blocky downloads and processes sources concurrently. This allows limiting how many can be processed in the same time. 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. Default value is 4.</p> <p>Example</p> <pre><code>loading:\nconcurrency: 10\n</code></pre> <p>Note</p> <p>As with other settings under <code>loading</code>, the limit applies to the blocking and hosts file resolvers separately. The total number of concurrent sources concurrently processed can reach the sum of both values. For example if blocking has a limit set to 8 and hosts file's is 4, there could be up to 12 concurrent jobs.</p>"},{"location":"installation/","title":"Installation","text":"<p>You can choose one of the following installation options:</p> <ul> <li>Run as standalone binary</li> <li>Run as docker container</li> <li>Kubernetes with helm chart</li> </ul>"},{"location":"installation/#prepare-your-configuration","title":"Prepare your configuration","text":"<p>Blocky supports single or multiple YAML files as configuration. Create new <code>config.yaml</code> with your configuration ( see Configuration for more details and all configuration options).</p> <p>Simple configuration file, which enables only basic features:</p> <pre><code>upstream:\ndefault:\n- 46.182.19.48\n- 80.241.218.68\n- tcp-tls:fdns1.dismail.de:853\n- https://dns.digitale-gesellschaft.ch/dns-query\nblocking:\nblackLists:\nads:\n- https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts\nclientGroupsBlock:\ndefault:\n- ads\nports:\ndns: 53\nhttp: 4000\n</code></pre>"},{"location":"installation/#run-as-standalone-binary","title":"Run as standalone binary","text":"<p>Download the binary file from GitHub for your architecture and run <code>./blocky --config config.yml</code>.</p> <p>Warning</p> <p>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).</p>"},{"location":"installation/#run-with-docker","title":"Run with docker","text":""},{"location":"installation/#alternative-registry","title":"Alternative registry","text":"<p>Blocky docker images are deployed to DockerHub (<code>spx01/blocky</code>) and GitHub Container Registry (<code>ghcr.io/0xerr0r/blocky</code>) .</p>"},{"location":"installation/#parameters","title":"Parameters","text":"<p>You can define the location of the config file in the container with environment variable \"BLOCKY_CONFIG_FILE\". Default value is \"/app/config.yml\".</p>"},{"location":"installation/#docker-from-command-line","title":"Docker from command line","text":"<p>Execute following command from the command line:</p> <pre><code>docker run --name blocky -v /path/to/config.yml:/app/config.yml -p 4000:4000 -p 53:53/udp spx01/blocky\n</code></pre>"},{"location":"installation/#run-with-docker-compose","title":"Run with docker-compose","text":"<p>Create following <code>docker-compose.yml</code> file</p> <pre><code>version: \"2.1\"\nservices:\nblocky:\nimage: spx01/blocky\ncontainer_name: blocky\nrestart: unless-stopped\n# Optional the instance hostname for logging purpose\nhostname: blocky-hostname\nports:\n- \"53:53/tcp\"\n- \"53:53/udp\"\n- \"4000:4000/tcp\"\nenvironment:\n- TZ=Europe/Berlin # Optional to synchronize the log timestamp with host\nvolumes:\n# Optional to synchronize the log timestamp with host\n- /etc/localtime:/etc/localtime:ro\n# config file\n- ./config.yml:/app/config.yml\n</code></pre> <p>and start docker container with</p> <pre><code>docker-compose up -d\n</code></pre>"},{"location":"installation/#advanced-setup","title":"Advanced setup","text":"<p>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.</p> <p>Example</p> <pre><code>version: \"2.1\"\nservices:\nblocky:\nimage: spx01/blocky\ncontainer_name: blocky\nrestart: unless-stopped\nports:\n- \"53:53/tcp\"\n- \"53:53/udp\"\n- \"4000:4000/tcp\" # Prometheus stats (if enabled).\nenvironment:\n- TZ=Europe/Berlin\nvolumes:\n# config file\n- ./config.yml:/app/config.yml\n# write query logs in this volume\n- queryLogs:/logs\n# put your custom white and blacklists in these directories\n- ./blacklists:/app/blacklists/\n- ./whitelists:/app/whitelists/\n\nvolumes:\nqueryLogs:\ndriver: local\ndriver_opts:\ntype: cifs\no: username=USER,password=PASSWORD,rw\ndevice: //NAS_HOSTNAME/blocky </code></pre>"},{"location":"installation/#multiple-configuration-files","title":"Multiple configuration files","text":"<p>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.</p> <p><code>./blocky --config ./config/</code></p> <p>Warning</p> <p>Blocky simply joins the multiple YAML files. If a directive (e.g. <code>upstream</code>) is repeated in multiple files, the configuration will not load and start will fail.</p>"},{"location":"installation/#other-installation-types","title":"Other installation types","text":"<p>Warning</p> <p>These projects are maintained by other people.</p>"},{"location":"installation/#web-ui","title":"Web UI","text":"<p>Blocky Frontend provides a Web UI to control blocky. See linked project for installation instructions.</p>"},{"location":"installation/#run-with-helm-chart-on-kubernetes","title":"Run with helm chart on Kubernetes","text":"<p>See this repo, the documentation and the configuration instructions for details about running blocky via helm in kubernetes.</p>"},{"location":"installation/#run-as-an-app-for-truenas-scale","title":"Run as an App for TrueNAS SCALE","text":"<p>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.</p>"},{"location":"installation/#aur-package-for-arch-linux","title":"AUR package for Arch Linux","text":"<p>See https://aur.archlinux.org/packages/blocky/</p>"},{"location":"installation/#package-for-alpine-linux","title":"Package for Alpine Linux","text":"<p>See https://pkgs.alpinelinux.org/package/edge/testing/x86/blocky</p>"},{"location":"installation/#installation-script-for-centosfedora","title":"Installation script for CentOS/Fedora","text":"<p>See https://github.com/m0zgen/blocky-installer</p>"},{"location":"installation/#package-for-freebsd","title":"Package for FreeBSD","text":"<p>See https://www.freebsd.org/cgi/ports.cgi?query=blocky&stype=all</p>"},{"location":"installation/#homebrew-package-for-macos","title":"Homebrew package for MacOS","text":"<p>See https://formulae.brew.sh/formula/blocky</p>"},{"location":"interfaces/","title":"Interfaces","text":""},{"location":"interfaces/#rest-api","title":"REST API","text":"<p>If http listener is enabled, blocky provides REST API. You can browse the API documentation (Swagger) documentation under https://0xERR0R.github.io/blocky/swagger.html.</p>"},{"location":"interfaces/#cli","title":"CLI","text":"<p>Blocky provides a CLI interface to control. This interface uses internally the REST API.</p> <p>To run the CLI, please ensure, that blocky DNS server is running, then execute <code>blocky help</code> for help or</p> <ul> <li><code>./blocky blocking enable</code> to enable blocking</li> <li><code>./blocky blocking disable</code> to disable blocking</li> <li><code>./blocky blocking disable --duration [duration]</code> to disable blocking for a certain amount of time (30s, 5m, 10m30s, ...)</li> <li><code>./blocky blocking disable --groups ads,othergroup</code> to disable blocking only for special groups</li> <li><code>./blocky blocking status</code> to print current status of blocking</li> <li><code>./blocky query <domain></code> execute DNS query (A) (simple replacement for dig, useful for debug purposes)</li> <li><code>./blocky query <domain> --type <queryType></code> execute DNS query with passed query type (A, AAAA, MX, ...)</li> <li><code>./blocky lists refresh</code> reloads all white and blacklists</li> </ul> <p>Tip</p> <p>To run this inside docker run <code>docker exec blocky ./blocky blocking status</code></p>"},{"location":"network_configuration/","title":"Network configuration","text":"<p>In order, to benefit from all the advantages of blocky like ad-blocking, privacy and speed, it is necessary to use blocky as DNS server for your devices. You can configure DNS server on each device manually or use DHCP in your network router and push the right settings to your device. With this approach, you will configure blocky only once in your router and each device in your network will automatically use blocky as DNS server.</p>"},{"location":"network_configuration/#transparent-configuration-with-dhcp","title":"Transparent configuration with DHCP","text":"<p>Let us assume, blocky is installed on a Raspberry PI with fix IP address <code>192.168.178.2</code>. Each device which connects to the router will obtain an IP address and receive the network configuration. The IP address of the Raspberry PI should be pushed to the device as DNS server.</p> <pre><code>\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 \u2502 \u2502 Raspberry PI \u2502\n\u2502 Router \u2502 \u2502 blocky \u2502 \n\u2502 \u2502 \u2502 192.168.178.2 \u2502 \n\u2514\u2500\u25b2\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u25b2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \n \u25021 \u2502 \u2502 3 \n \u2502 \u2502 \u2502 \n \u2502 \u2502 \u2502 \n \u2502 \u2502 \u2502 \n \u2502 \u2502 \u2502\n \u2502 \u2502 \u2502\n \u2502 \u2502 \u2502\n \u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 \u2502 2 \u2502 \u2502\n \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25ba Network device \u2502\n \u2502 \u2502 Android \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</code></pre> <p>1 - Network device asks the DHCP server (on Router) for the network configuration</p> <p>2 - Router assigns a free IP address to the device and says \"Use 192.168.178.2\" as DNS server</p> <p>3 - Clients makes DNS queries and is happy to use blocky </p> <p>Warning</p> <p>It is necessary to assign the server which runs blocky (e.g. Raspberry PI) a fix IP address.</p>"},{"location":"network_configuration/#example-configuration-with-fritzbox","title":"Example configuration with FritzBox","text":"<p>To configure the DNS server in the FritzBox, please open in the FritzBox web interface:</p> <ul> <li>in navigation menu on the left side: Home Network -> Network</li> <li>Network Settings tab on the top</li> <li>\"IPv4 Configuration\" Button at the bottom op the page</li> <li>Enter the IP address of blocky under \"Local DNS server\", see screenshot</li> </ul> <p></p>"},{"location":"prometheus_grafana/","title":"Integration in Grafana","text":""},{"location":"prometheus_grafana/#prometheus","title":"Prometheus","text":""},{"location":"prometheus_grafana/#prometheus-export","title":"Prometheus export","text":"<p>Blocky can optionally export metrics for Prometheus.</p> <p>Following metrics will be exported:</p> 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"},{"location":"prometheus_grafana/#grafana-dashboard","title":"Grafana dashboard","text":"<p>Example Grafana dashboard definition as JSON or at grafana.com .</p> <p>This dashboard shows all relevant statistics and allows enabling and disabling the blocking status.</p>"},{"location":"prometheus_grafana/#grafana-configuration","title":"Grafana configuration","text":"<p>Please install <code>grafana-piechart-panel</code> and set disable_sanitize_html in config or as env to use control buttons to enable/disable the blocking status.</p>"},{"location":"prometheus_grafana/#grafana-and-prometheus-example-project","title":"Grafana and Prometheus example project","text":"<p>This repo contains example docker-compose.yml with blocky, prometheus (with configured scraper for blocky) and grafana with prometheus datasource.</p>"},{"location":"prometheus_grafana/#mysql-mariadb","title":"MySQL / MariaDB","text":"<p>If database query logging is activated (see Query logging), you can use following Grafana Dashboard as JSON or at grafana.com</p> <p>.</p> <p>Please define the MySQL source in Grafana, which points to the database with blocky's log entries.</p>"},{"location":"prometheus_grafana/#postgres","title":"Postgres","text":"<p>The JSON for a Grafana dashboard equivalent to the MySQL/MariaDB version is located here</p>"}]} |