mirror of https://github.com/0xERR0R/blocky.git
2372 lines
117 KiB
HTML
2372 lines
117 KiB
HTML
|
|
<!doctype html>
|
|
<html lang="en" class="no-js">
|
|
<head>
|
|
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
|
|
<meta name="description" content="blocky Documentation">
|
|
|
|
|
|
|
|
|
|
<link rel="prev" href="..">
|
|
|
|
|
|
<link rel="next" href="../installation/">
|
|
|
|
<link rel="icon" href="../assets/images/favicon.png">
|
|
<meta name="generator" content="mkdocs-1.4.2, mkdocs-material-9.1.1">
|
|
|
|
|
|
|
|
<title>Configuration - blocky</title>
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../assets/stylesheets/main.402914a4.min.css">
|
|
|
|
|
|
<link rel="stylesheet" href="../assets/stylesheets/palette.a0c5b2b5.min.css">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
|
|
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
|
|
|
|
|
|
|
|
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="teal" data-md-color-accent="teal">
|
|
|
|
|
|
|
|
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
|
|
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
|
|
<label class="md-overlay" for="__drawer"></label>
|
|
<div data-md-component="skip">
|
|
|
|
|
|
<a href="#configuration" class="md-skip">
|
|
Skip to content
|
|
</a>
|
|
|
|
</div>
|
|
<div data-md-component="announce">
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<header class="md-header md-header--shadow" data-md-component="header">
|
|
<nav class="md-header__inner md-grid" aria-label="Header">
|
|
<a href=".." title="blocky" class="md-header__button md-logo" aria-label="blocky" data-md-component="logo">
|
|
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z"/></svg>
|
|
|
|
</a>
|
|
<label class="md-header__button md-icon" for="__drawer">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg>
|
|
</label>
|
|
<div class="md-header__title" data-md-component="header-title">
|
|
<div class="md-header__ellipsis">
|
|
<div class="md-header__topic">
|
|
<span class="md-ellipsis">
|
|
blocky
|
|
</span>
|
|
</div>
|
|
<div class="md-header__topic" data-md-component="header-topic">
|
|
<span class="md-ellipsis">
|
|
|
|
Configuration
|
|
|
|
</span>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
<label class="md-header__button md-icon" for="__search">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
|
|
</label>
|
|
<div class="md-search" data-md-component="search" role="dialog">
|
|
<label class="md-search__overlay" for="__search"></label>
|
|
<div class="md-search__inner" role="search">
|
|
<form class="md-search__form" name="search">
|
|
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
|
|
<label class="md-search__icon md-icon" for="__search">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
|
|
</label>
|
|
<nav class="md-search__options" aria-label="Search">
|
|
|
|
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg>
|
|
</button>
|
|
</nav>
|
|
|
|
</form>
|
|
<div class="md-search__output">
|
|
<div class="md-search__scrollwrap" data-md-scrollfix>
|
|
<div class="md-search-result" data-md-component="search-result">
|
|
<div class="md-search-result__meta">
|
|
Initializing search
|
|
</div>
|
|
<ol class="md-search-result__list" role="presentation"></ol>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div class="md-header__source">
|
|
<a href="https://github.com/0xERR0R/blocky" title="Go to repository" class="md-source" data-md-component="source">
|
|
<div class="md-source__icon md-icon">
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.3.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2023 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg>
|
|
</div>
|
|
<div class="md-source__repository">
|
|
GitHub
|
|
</div>
|
|
</a>
|
|
</div>
|
|
|
|
</nav>
|
|
|
|
</header>
|
|
|
|
<div class="md-container" data-md-component="container">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<main class="md-main" data-md-component="main">
|
|
<div class="md-main__inner md-grid">
|
|
|
|
|
|
|
|
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
|
|
<div class="md-sidebar__scrollwrap">
|
|
<div class="md-sidebar__inner">
|
|
|
|
|
|
|
|
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
|
|
<label class="md-nav__title" for="__drawer">
|
|
<a href=".." title="blocky" class="md-nav__button md-logo" aria-label="blocky" data-md-component="logo">
|
|
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z"/></svg>
|
|
|
|
</a>
|
|
blocky
|
|
</label>
|
|
|
|
<div class="md-nav__source">
|
|
<a href="https://github.com/0xERR0R/blocky" title="Go to repository" class="md-source" data-md-component="source">
|
|
<div class="md-source__icon md-icon">
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.3.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2023 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg>
|
|
</div>
|
|
<div class="md-source__repository">
|
|
GitHub
|
|
</div>
|
|
</a>
|
|
</div>
|
|
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href=".." class="md-nav__link">
|
|
Welcome
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--active">
|
|
|
|
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
|
|
|
|
|
|
|
|
|
|
|
|
<label class="md-nav__link md-nav__link--active" for="__toc">
|
|
Configuration
|
|
<span class="md-nav__icon md-icon"></span>
|
|
</label>
|
|
|
|
<a href="./" class="md-nav__link md-nav__link--active">
|
|
Configuration
|
|
</a>
|
|
|
|
|
|
|
|
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<label class="md-nav__title" for="__toc">
|
|
<span class="md-nav__icon md-icon"></span>
|
|
Table of contents
|
|
</label>
|
|
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#basic-configuration" class="md-nav__link">
|
|
Basic configuration
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#ports-configuration" class="md-nav__link">
|
|
Ports configuration
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#logging-configuration" class="md-nav__link">
|
|
Logging configuration
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#upstream-configuration" class="md-nav__link">
|
|
Upstream configuration
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Upstream configuration">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#upstream-lookup-timeout" class="md-nav__link">
|
|
Upstream lookup timeout
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#bootstrap-dns-configuration" class="md-nav__link">
|
|
Bootstrap DNS configuration
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#filtering" class="md-nav__link">
|
|
Filtering
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#fqdn-only" class="md-nav__link">
|
|
FQDN only
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-dns" class="md-nav__link">
|
|
Custom DNS
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#conditional-dns-resolution" class="md-nav__link">
|
|
Conditional DNS resolution
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#client-name-lookup" class="md-nav__link">
|
|
Client name lookup
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Client name lookup">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#resolving-client-name-from-urlhost" class="md-nav__link">
|
|
Resolving client name from URL/Host
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#resolving-client-name-from-ip-address" class="md-nav__link">
|
|
Resolving client name from IP address
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Resolving client name from IP address">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#single-name-order" class="md-nav__link">
|
|
Single name order
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-client-name-mapping" class="md-nav__link">
|
|
Custom client name mapping
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#blocking-and-whitelisting" class="md-nav__link">
|
|
Blocking and whitelisting
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Blocking and whitelisting">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#definition-black-and-whitelists" class="md-nav__link">
|
|
Definition black and whitelists
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Definition black and whitelists">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#regex-support" class="md-nav__link">
|
|
Regex support
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#client-groups" class="md-nav__link">
|
|
Client groups
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#block-type" class="md-nav__link">
|
|
Block type
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#block-ttl" class="md-nav__link">
|
|
Block TTL
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#list-refresh-period" class="md-nav__link">
|
|
List refresh period
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#download" class="md-nav__link">
|
|
Download
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#start-strategy" class="md-nav__link">
|
|
Start strategy
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#concurrency" class="md-nav__link">
|
|
Concurrency
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#caching" class="md-nav__link">
|
|
Caching
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#redis" class="md-nav__link">
|
|
Redis
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#prometheus" class="md-nav__link">
|
|
Prometheus
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#query-logging" class="md-nav__link">
|
|
Query logging
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Query logging">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#query-log-types" class="md-nav__link">
|
|
Query log types
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#query-log-fields" class="md-nav__link">
|
|
Query log fields
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#hosts-file" class="md-nav__link">
|
|
Hosts file
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#deliver-ede-codes-as-edns0-option" class="md-nav__link">
|
|
Deliver EDE codes as EDNS0 option
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#ssl-certificate-configuration-doh-tls-listener" class="md-nav__link">
|
|
SSL certificate configuration (DoH / TLS listener)
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../installation/" class="md-nav__link">
|
|
Installation
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../prometheus_grafana/" class="md-nav__link">
|
|
Prometheus / Grafana
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../interfaces/" class="md-nav__link">
|
|
Interfaces
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../network_configuration/" class="md-nav__link">
|
|
Network configuration
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../additional_information/" class="md-nav__link">
|
|
Additional information
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
</ul>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
|
|
<div class="md-sidebar__scrollwrap">
|
|
<div class="md-sidebar__inner">
|
|
|
|
|
|
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<label class="md-nav__title" for="__toc">
|
|
<span class="md-nav__icon md-icon"></span>
|
|
Table of contents
|
|
</label>
|
|
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#basic-configuration" class="md-nav__link">
|
|
Basic configuration
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#ports-configuration" class="md-nav__link">
|
|
Ports configuration
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#logging-configuration" class="md-nav__link">
|
|
Logging configuration
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#upstream-configuration" class="md-nav__link">
|
|
Upstream configuration
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Upstream configuration">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#upstream-lookup-timeout" class="md-nav__link">
|
|
Upstream lookup timeout
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#bootstrap-dns-configuration" class="md-nav__link">
|
|
Bootstrap DNS configuration
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#filtering" class="md-nav__link">
|
|
Filtering
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#fqdn-only" class="md-nav__link">
|
|
FQDN only
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-dns" class="md-nav__link">
|
|
Custom DNS
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#conditional-dns-resolution" class="md-nav__link">
|
|
Conditional DNS resolution
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#client-name-lookup" class="md-nav__link">
|
|
Client name lookup
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Client name lookup">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#resolving-client-name-from-urlhost" class="md-nav__link">
|
|
Resolving client name from URL/Host
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#resolving-client-name-from-ip-address" class="md-nav__link">
|
|
Resolving client name from IP address
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Resolving client name from IP address">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#single-name-order" class="md-nav__link">
|
|
Single name order
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-client-name-mapping" class="md-nav__link">
|
|
Custom client name mapping
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#blocking-and-whitelisting" class="md-nav__link">
|
|
Blocking and whitelisting
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Blocking and whitelisting">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#definition-black-and-whitelists" class="md-nav__link">
|
|
Definition black and whitelists
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Definition black and whitelists">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#regex-support" class="md-nav__link">
|
|
Regex support
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#client-groups" class="md-nav__link">
|
|
Client groups
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#block-type" class="md-nav__link">
|
|
Block type
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#block-ttl" class="md-nav__link">
|
|
Block TTL
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#list-refresh-period" class="md-nav__link">
|
|
List refresh period
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#download" class="md-nav__link">
|
|
Download
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#start-strategy" class="md-nav__link">
|
|
Start strategy
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#concurrency" class="md-nav__link">
|
|
Concurrency
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#caching" class="md-nav__link">
|
|
Caching
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#redis" class="md-nav__link">
|
|
Redis
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#prometheus" class="md-nav__link">
|
|
Prometheus
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#query-logging" class="md-nav__link">
|
|
Query logging
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Query logging">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#query-log-types" class="md-nav__link">
|
|
Query log types
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#query-log-fields" class="md-nav__link">
|
|
Query log fields
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#hosts-file" class="md-nav__link">
|
|
Hosts file
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#deliver-ede-codes-as-edns0-option" class="md-nav__link">
|
|
Deliver EDE codes as EDNS0 option
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#ssl-certificate-configuration-doh-tls-listener" class="md-nav__link">
|
|
SSL certificate configuration (DoH / TLS listener)
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="md-content" data-md-component="content">
|
|
<article class="md-content__inner md-typeset">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h1 id="configuration">Configuration</h1>
|
|
<p>This chapter describes all configuration options in <code>config.yaml</code>. You can download a reference file with all
|
|
configuration properties as <a href="../config.yml">JSON</a>.</p>
|
|
<details class="example">
|
|
<summary>reference configuration file</summary>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">upstream</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># these external DNS resolvers will be used. Blocky picks 2 random resolvers from the list for each query</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="c1"># this configuration is mandatory, please define at least one external DNS resolver</span>
|
|
<span class="w"> </span><span class="nt">default</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># example for tcp+udp IPv4 server (https://digitalcourage.de/)</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5.9.164.112</span>
|
|
<span class="w"> </span><span class="c1"># Cloudflare</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1.1.1.1</span>
|
|
<span class="w"> </span><span class="c1"># example for DNS-over-TLS server (DoT)</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tcp-tls:fdns1.dismail.de:853</span>
|
|
<span class="w"> </span><span class="c1"># example for DNS-over-HTTPS (DoH)</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://dns.digitale-gesellschaft.ch/dns-query</span>
|
|
<span class="w"> </span><span class="c1"># optional: use client name (with wildcard support: * - sequence of any characters, [0-9] - range)</span>
|
|
<span class="w"> </span><span class="c1"># or single ip address / client subnet as CIDR notation</span>
|
|
<span class="w"> </span><span class="nt">laptop*</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">123.123.123.123</span>
|
|
|
|
<span class="c1"># optional: timeout to query the upstream resolver. Default: 2s</span>
|
|
<span class="nt">upstreamTimeout</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2s</span>
|
|
|
|
<span class="c1"># optional: If true, blocky will fail to start unless at least one upstream server per group is reachable. Default: false</span>
|
|
<span class="nt">startVerifyUpstream</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
|
|
<span class="c1"># optional: Determines how blocky will create outgoing connections. This impacts both upstreams, and lists.</span>
|
|
<span class="c1"># accepted: dual, v4, v6</span>
|
|
<span class="c1"># default: dual</span>
|
|
<span class="nt">connectIPVersion</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dual</span>
|
|
|
|
<span class="c1"># optional: custom IP address(es) for domain name (with all sub-domains). Multiple addresses must be separated by a comma</span>
|
|
<span class="c1"># example: query "printer.lan" or "my.printer.lan" will return 192.168.178.3</span>
|
|
<span class="nt">customDNS</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">customTTL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1h</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="c1"># if false, queries with unmapped types will be forwarded to the upstream resolver</span>
|
|
<span class="w"> </span><span class="nt">filterUnmappedTypes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
<span class="w"> </span><span class="c1"># optional: replace domain in the query with other domain before resolver lookup in the mapping</span>
|
|
<span class="w"> </span><span class="nt">rewrite</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">example.com</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">printer.lan</span>
|
|
<span class="w"> </span><span class="nt">mapping</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">printer.lan</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.3,2001:0db8:85a3:08d3:1319:8a2e:0370:7344</span>
|
|
|
|
<span class="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>
|
|
<span class="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>
|
|
<span class="nt">conditional</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="nt">fallbackUpstream</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
<span class="w"> </span><span class="c1"># optional: replace domain in the query with other domain before resolver lookup in the mapping</span>
|
|
<span class="w"> </span><span class="nt">rewrite</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">example.com</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">fritz.box</span>
|
|
<span class="w"> </span><span class="nt">mapping</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">fritz.box</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.1</span>
|
|
<span class="w"> </span><span class="nt">lan.net</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.1,192.168.178.2</span>
|
|
|
|
<span class="c1"># optional: use black and white lists to block queries (for example ads, trackers, adult pages etc.)</span>
|
|
<span class="nt">blocking</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># definition of blacklist groups. Can be external link (http/https) or local file</span>
|
|
<span class="w"> </span><span class="nt">blackLists</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">ads</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">http://sysctl.org/cameleon/hosts</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://s3.amazonaws.com/lists.disconnect.me/simple_tracking.txt</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">|</span>
|
|
<span class="w"> </span><span class="no"># inline definition with YAML literal block scalar style</span>
|
|
<span class="w"> </span><span class="no"># hosts format</span>
|
|
<span class="w"> </span><span class="no">someadsdomain.com</span>
|
|
<span class="w"> </span><span class="nt">special</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews/hosts</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="nt">whiteLists</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">ads</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">whitelist.txt</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">|</span>
|
|
<span class="w"> </span><span class="no"># inline definition with YAML literal block scalar style</span>
|
|
<span class="w"> </span><span class="no"># hosts format</span>
|
|
<span class="w"> </span><span class="no">whitelistdomain.com</span>
|
|
<span class="w"> </span><span class="no"># this is a regex</span>
|
|
<span class="w"> </span><span class="no">/^banners?[_.-]/</span>
|
|
<span class="w"> </span><span class="c1"># definition: which groups should be applied for which client</span>
|
|
<span class="w"> </span><span class="nt">clientGroupsBlock</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># default will be used, if no special definition for a client name exists</span>
|
|
<span class="w"> </span><span class="nt">default</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ads</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">special</span>
|
|
<span class="w"> </span><span class="c1"># use client name (with wildcard support: * - sequence of any characters, [0-9] - range)</span>
|
|
<span class="w"> </span><span class="c1"># or single ip address / client subnet as CIDR notation</span>
|
|
<span class="w"> </span><span class="nt">laptop*</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ads</span>
|
|
<span class="w"> </span><span class="nt">192.168.178.1/24</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">special</span>
|
|
<span class="w"> </span><span class="c1"># which response will be sent, if query is blocked:</span>
|
|
<span class="w"> </span><span class="c1"># zeroIp: 0.0.0.0 will be returned (default)</span>
|
|
<span class="w"> </span><span class="c1"># nxDomain: return NXDOMAIN as return code</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="nt">blockType</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">zeroIp</span>
|
|
<span class="w"> </span><span class="c1"># optional: TTL for answers to blocked domains</span>
|
|
<span class="w"> </span><span class="c1"># default: 6h</span>
|
|
<span class="w"> </span><span class="nt">blockTTL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1m</span>
|
|
<span class="w"> </span><span class="c1"># optional: automatically list refresh period (in duration format). Default: 4h.</span>
|
|
<span class="w"> </span><span class="c1"># Negative value -> deactivate automatically refresh.</span>
|
|
<span class="w"> </span><span class="c1"># 0 value -> use default</span>
|
|
<span class="w"> </span><span class="nt">refreshPeriod</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">4h</span>
|
|
<span class="w"> </span><span class="c1"># optional: timeout for list download (each url). Default: 60s. Use large values for big lists or slow internet connections</span>
|
|
<span class="w"> </span><span class="nt">downloadTimeout</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">4m</span>
|
|
<span class="w"> </span><span class="c1"># optional: Download attempt timeout. Default: 60s</span>
|
|
<span class="w"> </span><span class="nt">downloadAttempts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span>
|
|
<span class="w"> </span><span class="c1"># optional: Time between the download attempts. Default: 1s</span>
|
|
<span class="w"> </span><span class="nt">downloadCooldown</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10s</span>
|
|
<span class="w"> </span><span class="c1"># optional: if failOnError, application startup will fail if at least one list can't be downloaded / opened. Default: blocking</span>
|
|
<span class="w"> </span><span class="nt">startStrategy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">failOnError</span>
|
|
|
|
<span class="c1"># optional: configuration for caching of DNS responses</span>
|
|
<span class="nt">caching</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># duration how long a response must be cached (min value).</span>
|
|
<span class="w"> </span><span class="c1"># If <=0, use response's TTL, if >0 use this value, if TTL is smaller</span>
|
|
<span class="w"> </span><span class="c1"># Default: 0</span>
|
|
<span class="w"> </span><span class="nt">minTime</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5m</span>
|
|
<span class="w"> </span><span class="c1"># duration how long a response must be cached (max value).</span>
|
|
<span class="w"> </span><span class="c1"># If <0, do not cache responses</span>
|
|
<span class="w"> </span><span class="c1"># If 0, use TTL</span>
|
|
<span class="w"> </span><span class="c1"># If > 0, use this value, if TTL is greater</span>
|
|
<span class="w"> </span><span class="c1"># Default: 0</span>
|
|
<span class="w"> </span><span class="nt">maxTime</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">30m</span>
|
|
<span class="w"> </span><span class="c1"># Max number of cache entries (responses) to be kept in cache (soft limit). Useful on systems with limited amount of RAM.</span>
|
|
<span class="w"> </span><span class="c1"># Default (0): unlimited</span>
|
|
<span class="w"> </span><span class="nt">maxItemsCount</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">0</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="c1"># this improves the response time for often used queries, but significantly increases external traffic</span>
|
|
<span class="w"> </span><span class="c1"># default: false</span>
|
|
<span class="w"> </span><span class="nt">prefetching</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
<span class="w"> </span><span class="c1"># prefetch track time window (in duration format)</span>
|
|
<span class="w"> </span><span class="c1"># default: 120</span>
|
|
<span class="w"> </span><span class="nt">prefetchExpires</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2h</span>
|
|
<span class="w"> </span><span class="c1"># name queries threshold for prefetch</span>
|
|
<span class="w"> </span><span class="c1"># default: 5</span>
|
|
<span class="w"> </span><span class="nt">prefetchThreshold</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span>
|
|
<span class="w"> </span><span class="c1"># Max number of domains to be kept in cache for prefetching (soft limit). Useful on systems with limited amount of RAM.</span>
|
|
<span class="w"> </span><span class="c1"># Default (0): unlimited</span>
|
|
<span class="w"> </span><span class="nt">prefetchMaxItemsCount</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">0</span>
|
|
<span class="w"> </span><span class="c1"># Time how long negative results (NXDOMAIN response or empty result) are cached. A value of -1 will disable caching for negative results.</span>
|
|
<span class="w"> </span><span class="c1"># Default: 30m</span>
|
|
<span class="w"> </span><span class="nt">cacheTimeNegative</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">30m</span>
|
|
|
|
<span class="c1"># optional: configuration of client name resolution</span>
|
|
<span class="nt">clientLookup</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># optional: this DNS resolver will be used to perform reverse DNS lookup (typically local router)</span>
|
|
<span class="w"> </span><span class="nt">upstream</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.1</span>
|
|
<span class="w"> </span><span class="c1"># optional: some routers return multiple names for client (host name and user defined name). Define which single name should be used.</span>
|
|
<span class="w"> </span><span class="c1"># Example: take second name if present, if not take first name</span>
|
|
<span class="w"> </span><span class="nt">singleNameOrder</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="nt">clients</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">laptop</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.29</span>
|
|
<span class="c1"># optional: configuration for prometheus metrics endpoint</span>
|
|
<span class="nt">prometheus</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># enabled if true</span>
|
|
<span class="w"> </span><span class="nt">enable</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
<span class="w"> </span><span class="c1"># url path, optional (default '/metrics')</span>
|
|
<span class="w"> </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/metrics</span>
|
|
|
|
<span class="c1"># optional: write query information (question, answer, client, duration etc.) to daily csv file</span>
|
|
<span class="nt">queryLog</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># optional one of: mysql, postgresql, csv, csv-client. If empty, log to console</span>
|
|
<span class="w"> </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mysql</span>
|
|
<span class="w"> </span><span class="c1"># directory (should be mounted as volume in docker) for csv, db connection string for mysql/postgresql</span>
|
|
<span class="w"> </span><span class="nt">target</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">db_user:db_password@tcp(db_host_or_ip:3306)/db_name?charset=utf8mb4&parseTime=True&loc=Local</span>
|
|
<span class="w"> </span><span class="c1">#postgresql target: postgres://user:password@db_host_or_ip:5432/db_name</span>
|
|
<span class="w"> </span><span class="c1"># if > 0, deletes log files which are older than ... days</span>
|
|
<span class="w"> </span><span class="nt">logRetentionDays</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">7</span>
|
|
<span class="w"> </span><span class="c1"># optional: Max attempts to create specific query log writer, default: 3</span>
|
|
<span class="w"> </span><span class="nt">creationAttempts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1</span>
|
|
<span class="w"> </span><span class="c1"># optional: Time between the creation attempts, default: 2s</span>
|
|
<span class="w"> </span><span class="nt">creationCooldown</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2s</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="nt">fields</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">clientIP</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">duration</span>
|
|
|
|
<span class="c1"># optional: Blocky can synchronize its cache and blocking state between multiple instances through redis.</span>
|
|
<span class="nt">redis</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># Server address and port or master name if sentinel is used</span>
|
|
<span class="w"> </span><span class="nt">address</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redismaster</span>
|
|
<span class="w"> </span><span class="c1"># Username if necessary</span>
|
|
<span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">usrname</span>
|
|
<span class="w"> </span><span class="c1"># Password if necessary</span>
|
|
<span class="w"> </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">passwd</span>
|
|
<span class="w"> </span><span class="c1"># Database, default: 0</span>
|
|
<span class="w"> </span><span class="nt">database</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
|
|
<span class="w"> </span><span class="c1"># Connection is required for blocky to start. Default: false</span>
|
|
<span class="w"> </span><span class="nt">required</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
<span class="w"> </span><span class="c1"># Max connection attempts, default: 3</span>
|
|
<span class="w"> </span><span class="nt">connectionAttempts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
|
|
<span class="w"> </span><span class="c1"># Time between the connection attempts, default: 1s</span>
|
|
<span class="w"> </span><span class="nt">connectionCooldown</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3s</span>
|
|
<span class="w"> </span><span class="c1"># Sentinal username if necessary</span>
|
|
<span class="w"> </span><span class="nt">sentinelUsername</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">usrname</span>
|
|
<span class="w"> </span><span class="c1"># Sentinal password if necessary</span>
|
|
<span class="w"> </span><span class="nt">sentinelPassword</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">passwd</span>
|
|
<span class="w"> </span><span class="c1"># List with address and port of sentinel hosts(sentinel is activated if at least one sentinel address is configured)</span>
|
|
<span class="w"> </span><span class="nt">sentinelAddresses</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redis-sentinel1:26379</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redis-sentinel2:26379</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redis-sentinel3:26379</span>
|
|
|
|
<span class="c1"># optional: Mininal TLS version that the DoH and DoT server will use</span>
|
|
<span class="nt">minTlsServeVersion</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1.3</span>
|
|
<span class="c1"># if https port > 0: path to cert and key file for SSL encryption. if not set, self-signed certificate will be generated</span>
|
|
<span class="c1">#certFile: server.crt</span>
|
|
<span class="c1">#keyFile: server.key</span>
|
|
<span class="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>
|
|
<span class="nt">bootstrapDns</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tcp+udp:1.1.1.1</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://1.1.1.1/dns-query</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">upstream</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://dns.digitale-gesellschaft.ch/dns-query</span>
|
|
<span class="w"> </span><span class="nt">ips</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">185.95.218.42</span>
|
|
|
|
<span class="c1"># optional: drop all queries with following query types. Default: empty</span>
|
|
<span class="nt">filtering</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">queryTypes</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">AAAA</span>
|
|
|
|
<span class="c1"># optional: if path defined, use this file for query resolution (A, AAAA and rDNS). Default: empty</span>
|
|
<span class="nt">hostsFile</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># optional: Path to hosts file (e.g. /etc/hosts on Linux)</span>
|
|
<span class="w"> </span><span class="nt">filePath</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/etc/hosts</span>
|
|
<span class="w"> </span><span class="c1"># optional: TTL, default: 1h</span>
|
|
<span class="w"> </span><span class="nt">hostsTTL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">60m</span>
|
|
<span class="w"> </span><span class="c1"># optional: Time between hosts file refresh, default: 1h</span>
|
|
<span class="w"> </span><span class="nt">refreshPeriod</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">30m</span>
|
|
<span class="w"> </span><span class="c1"># optional: Whether loopback hosts addresses (127.0.0.0/8 and ::1) should be filtered or not, default: false</span>
|
|
<span class="w"> </span><span class="nt">filterLoopback</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
|
|
<span class="c1"># optional: ports configuration</span>
|
|
<span class="nt">ports</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="nt">dns</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">53</span>
|
|
<span class="w"> </span><span class="c1"># optional: Port(s) and bind ip address(es) for DoT (DNS-over-TLS) listener. Example: 853, 127.0.0.1:853</span>
|
|
<span class="w"> </span><span class="nt">tls</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">853</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="nt">https</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">443</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="nt">http</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">4000</span>
|
|
|
|
<span class="c1"># optional: logging configuration</span>
|
|
<span class="nt">log</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># optional: Log level (one from debug, info, warn, error). Default: info</span>
|
|
<span class="w"> </span><span class="nt">level</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">info</span>
|
|
<span class="w"> </span><span class="c1"># optional: Log format (text or json). Default: text</span>
|
|
<span class="w"> </span><span class="nt">format</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">text</span>
|
|
<span class="w"> </span><span class="c1"># optional: log timestamps. Default: true</span>
|
|
<span class="w"> </span><span class="nt">timestamp</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
<span class="w"> </span><span class="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>
|
|
<span class="w"> </span><span class="nt">privacy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
|
|
<span class="c1"># optional: add EDE error codes to dns response</span>
|
|
<span class="nt">ede</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># enabled if true, Default: false</span>
|
|
<span class="w"> </span><span class="nt">enable</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</code></pre></div>
|
|
</details>
|
|
<h2 id="basic-configuration">Basic configuration</h2>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Type</th>
|
|
<th>Mandatory</th>
|
|
<th>Default value</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>certFile</td>
|
|
<td>path</td>
|
|
<td>no</td>
|
|
<td></td>
|
|
<td>Path to cert and key file for <abbr title="Secure Sockets Layer">SSL</abbr> encryption (<abbr title="DNS-over-HTTPS">DoH</abbr> and <abbr title="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 <abbr title="Secure Sockets Layer">SSL</abbr> encryption (<abbr title="DNS-over-HTTPS">DoH</abbr> and <abbr title="DNS-over-TLS">DoT</abbr>); if empty, self-signed certificate is generated</td>
|
|
</tr>
|
|
<tr>
|
|
<td>dohUserAgent</td>
|
|
<td>string</td>
|
|
<td>no</td>
|
|
<td></td>
|
|
<td><abbr title="Hypertext Transfer Protocol">HTTP</abbr> User Agent for <abbr title="DNS-over-HTTPS">DoH</abbr> upstreams</td>
|
|
</tr>
|
|
<tr>
|
|
<td>minTlsServeVersion</td>
|
|
<td>string</td>
|
|
<td>no</td>
|
|
<td>1.2</td>
|
|
<td>Minimum TLS version that the <abbr title="DNS-over-TLS">DoT</abbr> and <abbr title="DNS-over-HTTPS">DoH</abbr> server use to serve those encrypted <abbr title="Domain Name System">DNS</abbr> requests</td>
|
|
</tr>
|
|
<tr>
|
|
<td>startVerifyUpstream</td>
|
|
<td>bool</td>
|
|
<td>no</td>
|
|
<td>false</td>
|
|
<td>If true, blocky will fail to start unless at least one upstream server per group is reachable.</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>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">minTlsServeVersion</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1.1</span>
|
|
<span class="nt">connectIPVersion</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">v4</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="ports-configuration">Ports configuration</h2>
|
|
<p>All logging port are optional.</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Type</th>
|
|
<th>Default value</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>ports.dns</td>
|
|
<td>[IP]:port[,[IP]:port]*</td>
|
|
<td>53</td>
|
|
<td>Port(s) and optional bind ip address(es) to serve <abbr title="Domain Name System">DNS</abbr> endpoint (<abbr title="Transmission Control Protocol">TCP</abbr> and <abbr title="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 <abbr title="DNS-over-TLS">DoT</abbr> <abbr title="Domain Name System">DNS</abbr> endpoint (<abbr title="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 <abbr title="Hypertext Transfer Protocol">HTTP</abbr> used for prometheus metrics, pprof, <abbr title="Representational State Transfer">REST</abbr> <abbr title="Application Programming Interface">API</abbr>, <abbr title="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 <abbr title="Hypertext Transfer Protocol Secure">HTTPS</abbr> used for prometheus metrics, pprof, <abbr title="Representational State Transfer">REST</abbr> <abbr title="Application Programming Interface">API</abbr>, <abbr title="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>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">ports</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">dns</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">53</span>
|
|
<span class="w"> </span><span class="nt">http</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">4000</span>
|
|
<span class="w"> </span><span class="nt">https</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">443</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="logging-configuration">Logging configuration</h2>
|
|
<p>All logging options are optional.</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Type</th>
|
|
<th>Default value</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>log.level</td>
|
|
<td>enum (debug, info, warn, error)</td>
|
|
<td>info</td>
|
|
<td>Log level</td>
|
|
</tr>
|
|
<tr>
|
|
<td>log.format</td>
|
|
<td>enum (text, json)</td>
|
|
<td>text</td>
|
|
<td>Log format (text or json).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>log.timestamp</td>
|
|
<td>bool</td>
|
|
<td>true</td>
|
|
<td>Log time stamps (true or false).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>log.privacy</td>
|
|
<td>bool</td>
|
|
<td>false</td>
|
|
<td>Obfuscate log output (replace all alphanumeric characters with *) for user sensitive data like request domains or responses to increase privacy.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">log</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">level</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">debug</span>
|
|
<span class="w"> </span><span class="nt">format</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">json</span>
|
|
<span class="w"> </span><span class="nt">timestamp</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
<span class="w"> </span><span class="nt">privacy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="upstream-configuration">Upstream configuration</h2>
|
|
<p>To resolve a <abbr title="Domain Name System">DNS</abbr> query, blocky needs external public or private <abbr title="Domain Name System">DNS</abbr> resolvers. Blocky supports <abbr title="Domain Name System">DNS</abbr> resolvers with
|
|
following network protocols (net part of the resolver URL):</p>
|
|
<ul>
|
|
<li>tcp+udp (<abbr title="User Datagram Protocol">UDP</abbr> and <abbr title="Transmission Control Protocol">TCP</abbr>, dependent on query type)</li>
|
|
<li>https (aka <abbr title="DNS-over-HTTPS">DoH</abbr>)</li>
|
|
<li>tcp-tls (aka <abbr title="DNS-over-TLS">DoT</abbr>)</li>
|
|
</ul>
|
|
<div class="admonition hint">
|
|
<p class="admonition-title">Hint</p>
|
|
<p>You can (and should!) configure multiple <abbr title="Domain Name System">DNS</abbr> resolvers. Blocky picks 2 random resolvers from the list for each query and
|
|
returns the answer from the fastest one. This improves your network speed and increases your privacy - your <abbr title="Domain Name System">DNS</abbr> traffic
|
|
will be distributed over multiple providers.</p>
|
|
</div>
|
|
<p>Each resolver must be defined as a string in following format: <code>[net:]host:[port][/path][#commonName]</code>.</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Type</th>
|
|
<th>Mandatory</th>
|
|
<th>Default value</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>net</td>
|
|
<td>enum (tcp+udp, tcp-tls or https)</td>
|
|
<td>no</td>
|
|
<td>tcp+udp</td>
|
|
</tr>
|
|
<tr>
|
|
<td>host</td>
|
|
<td>IP or hostname</td>
|
|
<td>yes</td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td>port</td>
|
|
<td>int (1 - 65535)</td>
|
|
<td>no</td>
|
|
<td>53 for udp/tcp, 853 for tcp-tls and 443 for https</td>
|
|
</tr>
|
|
<tr>
|
|
<td>commonName</td>
|
|
<td>string</td>
|
|
<td>no</td>
|
|
<td>the host value</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The commonName parameter overrides the expected certificate common name value used for verification.</p>
|
|
<p>Blocky needs at least the configuration of the <strong>default</strong> group. This group will be used as a fallback, if no client
|
|
specific resolver configuration is available.</p>
|
|
<p>You can use the client name (see <a href="#client-name-lookup">Client name lookup</a>), client's IP address or a client subnet as
|
|
<abbr title="Classless Inter-Domain Routing">CIDR</abbr> notation.</p>
|
|
<div class="admonition tip">
|
|
<p class="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>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">upstream</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">default</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5.9.164.112</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1.1.1.1</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tcp-tls:fdns1.dismail.de:853</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://dns.digitale-gesellschaft.ch/dns-query</span>
|
|
<span class="w"> </span><span class="nt">laptop*</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">123.123.123.123</span>
|
|
<span class="w"> </span><span class="nt">10.43.8.67/28</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1.1.1.1</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">9.9.9.9</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<p>Use <code>123.123.123.123</code> as single upstream <abbr title="Domain Name System">DNS</abbr> resolver for client laptop-home,
|
|
<code>1.1.1.1</code> and <code>9.9.9.9</code> for all clients in the sub-net <code>10.43.8.67/28</code> and 4 resolvers (default) for all others clients.</p>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p><strong> Blocky needs at least one upstream <abbr title="Domain Name System">DNS</abbr> server </strong></p>
|
|
</div>
|
|
<p>See <a href="../additional_information/#list-of-public-dns-servers">List of public <abbr title="Domain Name System">DNS</abbr> servers</a> if you need some ideas, which
|
|
public free <abbr title="Domain Name System">DNS</abbr> server you could use.</p>
|
|
<h3 id="upstream-lookup-timeout">Upstream lookup timeout</h3>
|
|
<p>Blocky will wait 2 seconds (default value) for the response from the external upstream <abbr title="Domain Name System">DNS</abbr> server. You can change this
|
|
value by setting the <code>upstreamTimeout</code> configuration parameter (in <strong><abbr title="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></strong>).</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">upstream</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">default</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">46.182.19.48</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">80.241.218.68</span>
|
|
<span class="nt">upstreamTimeout</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5s</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="bootstrap-dns-configuration">Bootstrap <abbr title="Domain Name System">DNS</abbr> configuration</h2>
|
|
<p>These <abbr title="Domain Name System">DNS</abbr> servers are used to resolve upstream <abbr title="DNS-over-HTTPS">DoH</abbr> and <abbr title="DNS-over-TLS">DoT</abbr> servers that are specified as host names, and list domains.
|
|
It is useful if no system <abbr title="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 <abbr title="DNS-over-TLS">DoT</abbr>/<abbr title="DNS-over-HTTPS">DoH</abbr></td>
|
|
<td></td>
|
|
<td>Only valid if upstream is <abbr title="DNS-over-HTTPS">DoH</abbr> or <abbr title="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>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p>Works only on Linux/*nix OS due to golang limitations under Windows.</p>
|
|
</div>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="w"> </span><span class="nt">bootstrapDns</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">upstream</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tcp-tls:dns.example.com</span>
|
|
<span class="w"> </span><span class="nt">ips</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">123.123.123.123</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">upstream</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://234.234.234.234/dns-query</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="filtering">Filtering</h2>
|
|
<p>Under certain circumstances, it may be useful to filter some types of <abbr title="Domain Name System">DNS</abbr> queries. You can define one or more <abbr title="Domain Name System">DNS</abbr> query
|
|
types, all queries with these types will be dropped (empty answer will be returned).</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">filtering</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">queryTypes</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">AAAA</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<p>This configuration will drop all 'AAAA' (IPv6) queries.</p>
|
|
<h2 id="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 <abbr title="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>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">fqdnOnly</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="custom-dns">Custom <abbr title="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 <abbr title="Hypertext Transfer Protocol Secure">HTTPS</abbr> certificate. Multiple IP addresses for one
|
|
domain must be separated by a comma.</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Type</th>
|
|
<th>Mandatory</th>
|
|
<th>Default value</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>customTTL</td>
|
|
<td>duration (no unit is minutes)</td>
|
|
<td>no</td>
|
|
<td>1h</td>
|
|
</tr>
|
|
<tr>
|
|
<td>rewrite</td>
|
|
<td>string: string (domain: domain)</td>
|
|
<td>no</td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td>mapping</td>
|
|
<td>string: string (hostname: address list)</td>
|
|
<td>no</td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td>filterUnmappedTypes</td>
|
|
<td>boolean</td>
|
|
<td>no</td>
|
|
<td>true</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">customDNS</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">customTTL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1h</span>
|
|
<span class="w"> </span><span class="nt">filterUnmappedTypes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
<span class="w"> </span><span class="nt">rewrite</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">home</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lan</span>
|
|
<span class="w"> </span><span class="nt">replace-me.com</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">with-this.com</span>
|
|
<span class="w"> </span><span class="nt">mapping</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">printer.lan</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.3</span>
|
|
<span class="w"> </span><span class="nt">otherdevice.lan</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.15,2001:0db8:85a3:08d3:1319:8a2e:0370:7344</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<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 <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 <abbr title="Domain Name System">DNS</abbr> server.</p>
|
|
<h2 id="conditional-dns-resolution">Conditional <abbr title="Domain Name System">DNS</abbr> resolution</h2>
|
|
<p>You can define, which <abbr title="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 <abbr title="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 <abbr title="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 <abbr title="Domain Name System">DNS</abbr> for internal and external (internet facing) users, but not all subdomains are listed in the internal domain</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">conditional</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">fallbackUpstream</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
<span class="w"> </span><span class="nt">rewrite</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">example.com</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">fritz.box</span>
|
|
<span class="w"> </span><span class="nt">replace-me.com</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">with-this.com</span>
|
|
<span class="w"> </span><span class="nt">mapping</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">fritz.box</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.1</span>
|
|
<span class="w"> </span><span class="nt">lan.net</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.170.1.2,192.170.1.3</span>
|
|
<span class="w"> </span><span class="c1"># for reverse DNS lookups of local devices</span>
|
|
<span class="w"> </span><span class="nt">178.168.192.in-addr.arpa</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.1</span>
|
|
<span class="w"> </span><span class="c1"># for all unqualified hostnames</span>
|
|
<span class="w"> </span><span class="nt">.</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">168.168.0.1</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<div class="admonition tip">
|
|
<p class="admonition-title">Tip</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 <abbr title="Domain Name System">DNS</abbr> query "client.fritz.box" will be redirected to the router's <abbr title="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 <abbr title="Domain Name System">DNS</abbr> server at 168.168.0.1.</p>
|
|
<p>One usecase for <code>fallbackUpstream</code> is when having split <abbr title="Domain Name System">DNS</abbr> for internal and external (internet facing) users, but not all subdomains are listed in the internal domain.</p>
|
|
<h2 id="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 (<abbr title="DNS-over-TLS">DoT</abbr> and <abbr title="DNS-over-HTTPS">DoH</abbr>). This is useful
|
|
for defining of blocking groups, since IP address can change dynamically.</p>
|
|
<h3 id="resolving-client-name-from-urlhost">Resolving client name from URL/Host</h3>
|
|
<p>If <abbr title="DNS-over-TLS">DoT</abbr> or <abbr title="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><abbr title="DNS-over-TLS">DoT</abbr> Host: <code>id-bob.example.com</code> -> request's client name is <code>bob</code>
|
|
<abbr title="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 <abbr title="DNS-over-HTTPS">DoH</abbr> you can also pass the client name as url parameter:</p>
|
|
<p><abbr title="DNS-over-HTTPS">DoH</abbr> URL: <code>https://blocky.example.com/dns-query/alice</code> -> request's client name is <code>alice</code></p>
|
|
<h3 id="resolving-client-name-from-ip-address">Resolving client name from IP address</h3>
|
|
<p>Blocky uses <abbr title="Reverse DNS">rDNS</abbr> to retrieve client's name. To use this feature, you can configure a <abbr title="Domain Name System">DNS</abbr> server for client lookup (
|
|
typically your router). You can also define client names manually per IP address.</p>
|
|
<h4 id="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>
|
|
<h4 id="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>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">clientLookup</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">upstream</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.1</span>
|
|
<span class="w"> </span><span class="nt">singleNameOrder</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1</span>
|
|
<span class="w"> </span><span class="nt">clients</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">laptop</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.168.178.29</span>
|
|
</code></pre></div>
|
|
<p>Use <code>192.168.178.1</code> for <abbr title="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>
|
|
<h2 id="blocking-and-whitelisting">Blocking and whitelisting</h2>
|
|
<p>Blocky can download and use external lists with domains or IP addresses to block <abbr title="Domain Name System">DNS</abbr> query (e.g. advertisement, malware,
|
|
trackers, adult sites). You can group several list sources together and define the blocking behavior per client.
|
|
External blacklists must be either in the well-known <a href="https://en.wikipedia.org/wiki/Hosts_(file)">Hosts format</a> or just
|
|
a plain domain list (one domain per line). Blocky also supports <abbr title="Regular expression">regex</abbr> as more powerful tool to define patterns to block.</p>
|
|
<p>Blocky uses <a href="https://en.wikipedia.org/wiki/DNS_sinkhole"><abbr title="Domain Name System">DNS</abbr> sinkhole</a> approach to block a <abbr title="Domain Name System">DNS</abbr> query. Domain name from
|
|
the request, IP address from the response, and the <abbr title="Canonical Name">CNAME</abbr> record will be checked against configured blacklists.</p>
|
|
<p>To avoid over-blocking, you can define or use already existing whitelists.</p>
|
|
<h3 id="definition-black-and-whitelists">Definition black and whitelists</h3>
|
|
<p>Each black or whitelist can be either a path to the local file, a URL to download or inline list definition of a domains
|
|
in hosts format (<abbr title="YAML Ain't Markup Language">YAML</abbr> literal block scalar style). All Urls must be grouped to a group name.</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">blocking</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">blackLists</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">ads</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">|</span>
|
|
<span class="w"> </span><span class="no"># inline definition with YAML literal block scalar style</span>
|
|
<span class="w"> </span><span class="no">someadsdomain.com</span>
|
|
<span class="w"> </span><span class="no">anotheradsdomain.com</span>
|
|
<span class="w"> </span><span class="no"># this is a regex</span>
|
|
<span class="w"> </span><span class="no">/^banners?[_.-]/</span>
|
|
<span class="w"> </span><span class="nt">special</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews/hosts</span>
|
|
<span class="w"> </span><span class="nt">whiteLists</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">ads</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">whitelist.txt</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">|</span>
|
|
<span class="w"> </span><span class="no"># inline definition with YAML literal block scalar style</span>
|
|
<span class="w"> </span><span class="no">whitelistdomain.com</span>
|
|
</code></pre></div>
|
|
<p>In this example you can see 2 groups: <strong>ads</strong> with 2 lists and <strong>special</strong> with one list. One local whitelist was defined for the <strong>ads</strong> group.</p>
|
|
</div>
|
|
<div class="admonition warning">
|
|
<p class="admonition-title">Warning</p>
|
|
<p>If the same group has black and whitelists, whitelists will be used to disable particular blacklist entries.
|
|
If a group has <strong>only</strong> whitelist entries -> this means only domains from this list are allowed, all other domains will
|
|
be blocked</p>
|
|
</div>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p>Please define also client group mapping, otherwise you black and whitelist definition will have no effect</p>
|
|
</div>
|
|
<h4 id="regex-support">Regex support</h4>
|
|
<p>You can use <abbr title="Regular expression">regex</abbr> to define patterns to block. A <abbr title="Regular expression">regex</abbr> entry must start and end with the slash character (/). 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>
|
|
<h3 id="client-groups">Client groups</h3>
|
|
<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 <strong>ads</strong> group, which blocks advertisement and kids devices should use the <strong>adult</strong>
|
|
group, which blocky adult sites.</p>
|
|
<p>Clients without a group assignment will use automatically the <strong>default</strong> group.</p>
|
|
<p>You can use the client name (see <a href="#client-name-lookup">Client name lookup</a>), client's IP address, client's full-qualified domain name
|
|
or a client subnet as <abbr title="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>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">blocking</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">clientGroupsBlock</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="c1"># default will be used, if no special definition for a client name exists</span>
|
|
<span class="w"> </span><span class="nt">default</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ads</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">special</span>
|
|
<span class="w"> </span><span class="nt">laptop*</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ads</span>
|
|
<span class="w"> </span><span class="nt">192.168.178.1/24</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">special</span>
|
|
<span class="w"> </span><span class="nt">kid-laptop</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ads</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">adult</span>
|
|
</code></pre></div>
|
|
<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>
|
|
<div class="admonition tip">
|
|
<p class="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>
|
|
<h3 id="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, <abbr title="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 <abbr title="Non-Existence Domain">NXDOMAIN</abbr> as return code</td>
|
|
</tr>
|
|
<tr>
|
|
<td>custom IPs</td>
|
|
<td>192.100.100.15, 2001:0db8:85a3:08d3:1319:8a2e:0370:7344</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>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">blocking</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">blockType</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">nxDomain</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h3 id="block-ttl">Block <abbr title="Time-To-Live">TTL</abbr></h3>
|
|
<p><abbr title="Time-To-Live">TTL</abbr> for answers to blocked domains can be set to customize the time (in <strong><abbr title="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 <abbr title="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
|
|
after receiving the custom value.</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">blocking</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">blockType</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">192.100.100.15, 2001:0db8:85a3:08d3:1319:8a2e:0370:7344</span>
|
|
<span class="w"> </span><span class="nt">blockTTL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10s</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h3 id="list-refresh-period">List refresh period</h3>
|
|
<p>To keep the list cache up-to-date, blocky will periodically download and reload all external lists. Default period is <strong>
|
|
4 hours</strong>. You can configure this by setting the <code>blocking.refreshPeriod</code> parameter to a value in <strong><abbr title="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></strong>.
|
|
Negative value will deactivate automatically refresh.</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">blocking</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">refreshPeriod</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">60m</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<p>Refresh every hour.</p>
|
|
<h3 id="download">Download</h3>
|
|
<p>You can configure the list download attempts according to your internet connection:</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>downloadTimeout</td>
|
|
<td><abbr title="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
|
|
<td>no</td>
|
|
<td>60s</td>
|
|
<td>Download attempt timeout</td>
|
|
</tr>
|
|
<tr>
|
|
<td>downloadAttempts</td>
|
|
<td>int</td>
|
|
<td>no</td>
|
|
<td>3</td>
|
|
<td>How many download attempts should be performed</td>
|
|
</tr>
|
|
<tr>
|
|
<td>downloadCooldown</td>
|
|
<td><abbr title="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 download attempts</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">blocking</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">downloadTimeout</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">4m</span>
|
|
<span class="w"> </span><span class="nt">downloadAttempts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span>
|
|
<span class="w"> </span><span class="nt">downloadCooldown</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10s</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h3 id="start-strategy">Start strategy</h3>
|
|
<p>You can configure the blocking behavior during application start of blocky.<br />
|
|
If no starategy is selected blocking will be used.</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>startStrategy</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>blocking</td>
|
|
<td>all blocking lists will be loaded before <abbr title="Domain Name System">DNS</abbr> resolution starts</td>
|
|
</tr>
|
|
<tr>
|
|
<td>failOnError</td>
|
|
<td>like blocking but blocky will shut down if any download fails</td>
|
|
</tr>
|
|
<tr>
|
|
<td>fast</td>
|
|
<td><abbr title="Domain Name System">DNS</abbr> resolution starts immediately without blocking which will be enabled after list load is completed</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">blocking</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">startStrategy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">failOnError</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h3 id="concurrency">Concurrency</h3>
|
|
<p>Blocky downloads and processes links in a single group concurrently. With parameter <code>processingConcurrency</code> you can adjust
|
|
how many links can be processed in the same time. Higher value can reduce the overall list refresh time, but more parallel
|
|
download and processing jobs need more RAM. Please consider to reduce this value on systems with limited memory. Default value is 4.</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">blocking</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">processingConcurrency</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="caching">Caching</h2>
|
|
<p>Each <abbr title="Domain Name System">DNS</abbr> response has a <abbr title="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 <abbr title="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>
|
|
<div class="admonition warning">
|
|
<p class="admonition-title">Warning</p>
|
|
<p>Wrong values can significantly increase external <abbr title="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><abbr title="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
|
|
<td>no</td>
|
|
<td>0 (use <abbr title="Time-To-Live">TTL</abbr>)</td>
|
|
<td>How long a response must be cached (min value). If <=0, use response's <abbr title="Time-To-Live">TTL</abbr>, if >0 use this value, if <abbr title="Time-To-Live">TTL</abbr> is smaller</td>
|
|
</tr>
|
|
<tr>
|
|
<td>caching.maxTime</td>
|
|
<td><abbr title="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
|
|
<td>no</td>
|
|
<td>0 (use <abbr title="Time-To-Live">TTL</abbr>)</td>
|
|
<td>How long a response must be cached (max value). If <0, do not cache responses. If 0, use <abbr title="Time-To-Live">TTL</abbr>. If > 0, use this value, if <abbr title="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 <abbr title="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 (<abbr title="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><abbr title="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><abbr title="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 (<abbr title="Non-Existence Domain">NXDOMAIN</abbr> response or empty result) are cached. A value of -1 will disable caching for negative results.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">caching</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">minTime</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5m</span>
|
|
<span class="w"> </span><span class="nt">maxTime</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">30m</span>
|
|
<span class="w"> </span><span class="nt">prefetching</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="redis">Redis</h2>
|
|
<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><abbr title="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>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">redis</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">address</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redismaster</span>
|
|
<span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">usrname</span>
|
|
<span class="w"> </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">passwd</span>
|
|
<span class="w"> </span><span class="nt">database</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
|
|
<span class="w"> </span><span class="nt">required</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
<span class="w"> </span><span class="nt">connectionAttempts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
|
|
<span class="w"> </span><span class="nt">connectionCooldown</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3s</span>
|
|
<span class="w"> </span><span class="nt">sentinelUsername</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sentUsrname</span>
|
|
<span class="w"> </span><span class="nt">sentinelPassword</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">sentPasswd</span>
|
|
<span class="w"> </span><span class="nt">sentinelAddresses</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redis-sentinel1:26379</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redis-sentinel2:26379</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redis-sentinel3:26379</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="prometheus">Prometheus</h2>
|
|
<p>Blocky can expose various metrics for prometheus. To use the prometheus feature, the <abbr title="Hypertext Transfer Protocol">HTTP</abbr> listener must be enabled (
|
|
see <a href="#basic-configuration">Basic Configuration</a>).</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Mandatory</th>
|
|
<th>Default value</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>prometheus.enable</td>
|
|
<td>no</td>
|
|
<td>false</td>
|
|
<td>If true, enables prometheus metrics</td>
|
|
</tr>
|
|
<tr>
|
|
<td>prometheus.path</td>
|
|
<td>no</td>
|
|
<td>/metrics</td>
|
|
<td>URL path to the metrics endpoint</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">prometheus</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">enable</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
<span class="w"> </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/metrics</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="query-logging">Query logging</h2>
|
|
<p>You can enable the logging of <abbr title="Domain Name System">DNS</abbr> queries (question, answer, client, duration etc.) to a daily <abbr title="Comma-separated values">CSV</abbr> file (can be opened
|
|
in Excel or OpenOffice Calc) or MySQL/MariaDB database.</p>
|
|
<div class="admonition warning">
|
|
<p class="admonition-title">Warning</p>
|
|
<p>Query file/database contains sensitive information. Please ensure to inform users, if you log their queries.</p>
|
|
</div>
|
|
<h3 id="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 <abbr title="Comma-separated values">CSV</abbr> file (one per day)</li>
|
|
<li><code>csv-client</code> - log into <abbr title="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>
|
|
<h3 id="query-log-fields">Query log fields</h3>
|
|
<p>You can choose which information from processed <abbr title="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 <abbr title="Domain Name System">DNS</abbr> answer</li>
|
|
<li><code>question</code> - <abbr title="Domain Name System">DNS</abbr> question from the request</li>
|
|
<li><code>duration</code> - request processing time in milliseconds</li>
|
|
</ul>
|
|
<div class="admonition hint">
|
|
<p class="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>
|
|
</tr>
|
|
<tr>
|
|
<td>queryLog.CreationCooldown</td>
|
|
<td><abbr title="Example: "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".">duration format</abbr></td>
|
|
<td>no</td>
|
|
<td>2</td>
|
|
<td>Time between the creation attempts</td>
|
|
</tr>
|
|
<tr>
|
|
<td>queryLog.fields</td>
|
|
<td>list enum (clientIP, clientName, responseReason, responseAnswer, question, duration)</td>
|
|
<td>no</td>
|
|
<td>all</td>
|
|
<td>which information should be logged</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition hint">
|
|
<p class="admonition-title">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>
|
|
</div>
|
|
<p>example for <abbr title="Comma-separated values">CSV</abbr> format with limited logging information</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">queryLog</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">csv</span>
|
|
<span class="w"> </span><span class="nt">target</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/logs</span>
|
|
<span class="w"> </span><span class="nt">logRetentionDays</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">7</span>
|
|
<span class="w"> </span><span class="nt">fields</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">clientIP</span>
|
|
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">duration</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<p>example for Database</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">queryLog</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mysql</span>
|
|
<span class="w"> </span><span class="nt">target</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">db_user:db_password@tcp(db_host_or_ip:3306)/db_user?charset=utf8mb4&parseTime=True&loc=Local</span>
|
|
<span class="w"> </span><span class="nt">logRetentionDays</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">7</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="hosts-file">Hosts file</h2>
|
|
<p>You can enable resolving of entries, located in local hosts file.</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>hostsFile.filePath</td>
|
|
<td>string</td>
|
|
<td>no</td>
|
|
<td></td>
|
|
<td>Path to hosts file (e.g. /etc/hosts on Linux)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>hostsFile.hostsTTL</td>
|
|
<td>duration (no units is minutes)</td>
|
|
<td>no</td>
|
|
<td>1h</td>
|
|
<td><abbr title="Time-To-Live">TTL</abbr></td>
|
|
</tr>
|
|
<tr>
|
|
<td>hostsFile.refreshPeriod</td>
|
|
<td><abbr title="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>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">hostsFile</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">filePath</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/etc/hosts</span>
|
|
<span class="w"> </span><span class="nt">hostsTTL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">60m</span>
|
|
<span class="w"> </span><span class="nt">refreshPeriod</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">30m</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="deliver-ede-codes-as-edns0-option">Deliver EDE codes as EDNS0 option</h2>
|
|
<p><abbr title="Domain Name System">DNS</abbr> responses can be extended with EDE codes according to <a href="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, <abbr title="Domain Name System">DNS</abbr> responses are deliverd with EDE codes</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<div class="highlight"><pre><span></span><code><span class="nt">ede</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="nt">enable</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</code></pre></div>
|
|
</div>
|
|
<h2 id="ssl-certificate-configuration-doh-tls-listener"><abbr title="Secure Sockets Layer">SSL</abbr> certificate configuration (<abbr title="DNS-over-HTTPS">DoH</abbr> / TLS listener)</h2>
|
|
<p>See <a href="https://github.com/0xERR0R/blocky/wiki/Configuration-of-HTTPS-for-DoH-and-Rest-API">Wiki - Configuration of <abbr title="Hypertext Transfer Protocol Secure">HTTPS</abbr></a>
|
|
for detailed information, how to create and configure <abbr title="Secure Sockets Layer">SSL</abbr> certificates.</p>
|
|
<p><abbr title="DNS-over-HTTPS">DoH</abbr> url: <code>https://host:port/dns-query</code></p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</article>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
</main>
|
|
|
|
<footer class="md-footer">
|
|
|
|
<div class="md-footer-meta md-typeset">
|
|
<div class="md-footer-meta__inner md-grid">
|
|
<div class="md-copyright">
|
|
|
|
|
|
Made with
|
|
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
|
|
Material for MkDocs
|
|
</a>
|
|
|
|
</div>
|
|
|
|
<div class="md-social">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://github.com/0xERR0R/blocky" target="_blank" rel="noopener" title="github.com" class="md-social__link">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.3.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2023 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>
|
|
</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://hub.docker.com/r/spx01/blocky" target="_blank" rel="noopener" title="hub.docker.com" class="md-social__link">
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><!--! Font Awesome Free 6.3.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2023 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1v59.4zm0-204.3h-66.1v60.7h66.1V32zm78.2 144.8H362v59.4h66.1v-59.4zm-156.3-72.1h-66.1v60.1h66.1v-60.1zm78.1 0h-66.1v60.1h66.1v-60.1zm276.8 100c-14.4-9.7-47.6-13.2-73.1-8.4-3.3-24-16.7-44.9-41.1-63.7l-14-9.3-9.3 14c-18.4 27.8-23.4 73.6-3.7 103.8-8.7 4.7-25.8 11.1-48.4 10.7H2.4c-8.7 50.8 5.8 116.8 44 162.1 37.1 43.9 92.7 66.2 165.4 66.2 157.4 0 273.9-72.5 328.4-204.2 21.4.4 67.6.1 91.3-45.2 1.5-2.5 6.6-13.2 8.5-17.1l-13.3-8.9zm-511.1-27.9h-66v59.4h66.1v-59.4zm78.1 0h-66.1v59.4h66.1v-59.4zm78.1 0h-66.1v59.4h66.1v-59.4zm-78.1-72.1h-66.1v60.1h66.1v-60.1z"/></svg>
|
|
</a>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
</footer>
|
|
|
|
</div>
|
|
<div class="md-dialog" data-md-component="dialog">
|
|
<div class="md-dialog__inner md-typeset"></div>
|
|
</div>
|
|
|
|
<script id="__config" type="application/json">{"base": "..", "features": [], "search": "../assets/javascripts/workers/search.208ed371.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"}}</script>
|
|
|
|
|
|
<script src="../assets/javascripts/bundle.b78d2936.min.js"></script>
|
|
|
|
|
|
</body>
|
|
</html> |